feat(compute): insta compute exec — run a one-shot command in a compute service

Merged
JW
3mo ago
+225-1

What

New command: insta compute exec [service] -- <command> [args...] — runs a one-shot command inside a compute service's machine via the new platform route POST /projects/:id/services/:serviceId/exec.

Options: --branch <b> (default: current), --timeout <sec> (1–180, default 30), --json.

Semantics (each backed by a test)

  • Remote stdout→stdout, stderr→stderr verbatim (process.stdout.write, no added newlines).
  • The CLI's exit code is the remote command's exit code — scripts/agents can branch on it. Codes outside 0–255 (e.g. the platform's -1 unknown-exit sentinel) map to exit 1 with a stderr note (avoids Node's DEP0164).
  • 202 approval-pending exits 1 (not 0 — a pending approval must not read as success in && chains); --json prints the raw 202 envelope.
  • Output is capped by the platform at 1 MiB per stream; a truncation notice goes to stderr.
  • One-shot only — no interactive shell, no stdin. Wakes a scaled-to-zero machine first (a few seconds; billed as uptime).
  • Argv split: exec needs a literal -- boundary (optional [service] + variadic command is otherwise ambiguous in commander); isolated in a pure, unit-tested splitExecArgs.

Tests

npm run typecheck clean; npm test 330/330 (19 exec tests: split/validation/timeout bounds + applyExecResult exit/clamp/202/json paths); npm run build clean. Manual smoke of 200/202/400/truncation against a fake server (transcript in the PR branch's review notes).

Ordering

Requires the platform route (InsForge/insta-platform PR feat/compute-exec — link in comments once open). Do not cut a CLI release with this until the platform change is deployed, or the command 404s against prod.

🤖 Generated with Claude Code

Summary by cubic

Adds insta compute exec to run a one-shot command inside a compute service and exit with the remote command’s code. Pending approvals now exit 1 (was 0) and out-of-range remote exit codes clamp to 1 to avoid Node’s 255 fallback.

  • Non-interactive execution: insta compute exec [service] -- <command> [args…]. Requires a literal --; no shell, stdin, or PTY. Wakes scaled-to-zero machines; latency and billing as normal uptime.
  • Output and exit codes: stdout/stderr are written verbatim (no added newlines). Each stream is capped at 1 MiB; truncation prints a stderr note. CLI exit code equals the remote exit code; 202 approval-pending exits 1; codes outside 0–255 clamp to 1 with a stderr note.
  • Options: --branch <b> (default: current), --timeout <sec> (1–180; omitted uses platform default 30), --json (prints the raw response, including 202 envelopes).
  • Implementation touchpoints: pre-parse argv via splitExecArgs before commander; new applyExecResult handles 200/202 and exit code mapping; request body omits timeoutSec when not provided. Unit tests cover argv splitting, timeout bounds, request body, and result handling.

Rollout

  • Requires platform route POST /projects/:id/services/:serviceId/exec. Do not ship a CLI release until the platform change is live.
  • Automation: ensure scripts pass the literal -- before the command and expect exit 1 on approval-pending.