@indigoai-us/hq-cloud 6.15.4 → 6.15.5

package/dist/outposts/command.test.js

@@ -0,0 +1,933 @@
+/**
+ * Unit tests for the `outposts` command tree.
+ *
+ * Drives real Commander parses and spies on global `fetch`, asserting the
+ * `/outpost/*` request shape (method + path + query + body) plus the guards that
+ * matter: the destroy confirmation, the paid-provision gate, the teardown-incomplete
+ * retry, the per-person cap, the two 402 billing remediations, and the Lightsail
+ * SSH fallback.
+ *
+ * Ported from hq-cli when this surface moved into hq-cloud. The host seams the CLI
+ * used to own — token resolution and the cached session read — arrive through
+ * `OutpostsCommandDeps` here, so these tests inject them directly instead of
+ * module-mocking the CLI's internals.
+ *
+ * Outposts are caller-scoped, so there is no company resolution to mock.
+ */
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi, } from "vitest";
+// The SSH fallback shells out to `ssh` via spawnSync — stub it so tests don't
+// touch a real box or need the ssh binary.
+vi.mock("node:child_process", async (importOriginal) => {
+    const original = await importOriginal();
+    return { ...original, spawnSync: vi.fn() };
+});
+import { execFileSync, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { OutpostsClient } from "./client.js";
+import { registerOutpostsCommand } from "./command.js";
+import { joinCommandParts, withRemoteHqDir } from "./remote-command.js";
+import { createOutpostTransport } from "./transport.js";
+const mockSpawnSync = vi.mocked(spawnSync);
+const TEST_API_URL = "https://hqapi.test.invalid";
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+let fetchSpy;
+let exitSpy;
+let logSpy;
+beforeEach(() => {
+    vi.clearAllMocks();
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+    exitSpy = vi
+        .spyOn(process, "exit")
+        .mockImplementation((code) => {
+        throw new Error(`process.exit(${code})`);
+    });
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+    vi.spyOn(console, "error").mockImplementation(() => { });
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+function testTransport() {
+    return createOutpostTransport({ baseUrl: TEST_API_URL });
+}
+function testDeps(overrides = {}) {
+    return {
+        transport: testTransport(),
+        getToken: async () => "test-token",
+        // Provision sends the cached refresh token to the box; stub the session read
+        // so tests never need a real login on disk.
+        loadCachedTokens: () => ({ refreshToken: "rt_test" }),
+        resolveCallerPersonUid: async () => "prs_test",
+        defaultApiBaseUrl: TEST_API_URL,
+        ...overrides,
+    };
+}
+function buildProgram(overrides = {}) {
+    const program = new Command();
+    program.name("hq").exitOverride();
+    registerOutpostsCommand(program, testDeps(overrides));
+    return program;
+}
+async function run(args, overrides = {}) {
+    await buildProgram(overrides).parseAsync(["node", "hq", ...args]);
+}
+describe("outposts list", () => {
+    it("GETs /outpost/list", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            outposts: [
+                {
+                    outpostId: "primary",
+                    state: "running",
+                    instanceName: "outpost-abc",
+                    region: "us-east-1",
+                    agentRuntime: "claude",
+                    platform: "ec2",
+                    createdAt: "2026-01-01T00:00:00Z",
+                },
+            ],
+        }));
+        await run(["outposts", "list"]);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("/outpost/list");
+        expect(init?.method ?? "GET").toBe("GET");
+    });
+    it("sends the resolved bearer token", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { outposts: [] }));
+        await run(["outposts", "list"]);
+        const headers = fetchSpy.mock.calls[0][1]?.headers;
+        expect(headers.Authorization).toBe("Bearer test-token");
+    });
+    it("re-resolves the token per command so a refreshed session is picked up", async () => {
+        // The CLI passes `ensureCognitoToken`, which returns a NEW token once the old
+        // one nears expiry. Pinning the token at construction would send a stale one.
+        let calls = 0;
+        // A fresh Response per call — a Response body can only be read once, so a
+        // single reused object would fail the second command's `.json()`.
+        fetchSpy.mockImplementation(async () => jsonResponse(200, { outposts: [] }));
+        const deps = { getToken: async () => `token-${++calls}` };
+        await run(["outposts", "list"], deps);
+        await run(["outposts", "list"], deps);
+        const sent = fetchSpy.mock.calls.map(([, init]) => (init?.headers).Authorization);
+        expect(sent).toEqual(["Bearer token-1", "Bearer token-2"]);
+    });
+    it("emits raw JSON with --json", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { outposts: [] }));
+        await run(["outposts", "list", "--json"]);
+        const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("\n");
+        expect(printed).toContain("[]");
+    });
+});
+describe("outposts status", () => {
+    it("GETs /outpost/status with the --id query param", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { state: "running" }));
+        await run(["outposts", "status", "--id", "2"]);
+        const url = String(fetchSpy.mock.calls[0][0]);
+        expect(url).toContain("/outpost/status");
+        expect(url).toContain("outpostId=2");
+    });
+    it("omits outpostId when --id is not given", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { state: "running" }));
+        await run(["outposts", "status"]);
+        expect(String(fetchSpy.mock.calls[0][0])).not.toContain("outpostId=");
+    });
+});
+describe("outposts codex-enable / login", () => {
+    it("POSTs /outpost/codex/enable", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+        await run(["outposts", "codex-enable"]);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("/outpost/codex/enable");
+        expect(init?.method).toBe("POST");
+    });
+    it("POSTs /outpost/regenerate-login-url", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+        await run(["outposts", "login"]);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("/outpost/regenerate-login-url");
+        expect(init?.method).toBe("POST");
+    });
+    it("login-code POSTs /outpost/login-code with the code in the body", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true, userId: "u1" }));
+        await run(["outposts", "login-code", "ABC-123"]);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("/outpost/login-code");
+        expect(init?.method).toBe("POST");
+        expect(JSON.parse(String(init?.body))).toEqual({ code: "ABC-123" });
+    });
+    it("login-code targets a specific box via --id (outpostId query)", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true, userId: "u1" }));
+        await run(["outposts", "login-code", "CODE", "--id", "3"]);
+        const [url] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("outpostId=3");
+    });
+    it("login-code trims whitespace and refuses an empty code without calling the API", async () => {
+        await expect(run(["outposts", "login-code", "   "])).rejects.toThrow("process.exit(1)");
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("login-code surfaces an awaiting-login not-found error", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(404, {
+            error: true,
+            step: "not-found",
+            message: "no outpost",
+        }));
+        await expect(run(["outposts", "login-code", "CODE"])).rejects.toThrow("process.exit(1)");
+    });
+});
+describe("outposts destroy", () => {
+    it("refuses without --yes and does not call the API", async () => {
+        await expect(run(["outposts", "destroy"])).rejects.toThrow("process.exit(1)");
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("POSTs /outpost/destroy with --yes", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true, userId: "u1" }));
+        await run(["outposts", "destroy", "--yes"]);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("/outpost/destroy");
+        expect(init?.method).toBe("POST");
+    });
+    it("treats a 409 teardown-incomplete as retryable (no exit)", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(409, { error: true, step: "teardown-incomplete" }));
+        await run(["outposts", "destroy", "--id", "2", "--yes"]);
+        const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+        expect(printed).toMatch(/still in progress/i);
+        expect(exitSpy).not.toHaveBeenCalled();
+    });
+    it("exits 1 on a genuine failure", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(500, { error: "boom", step: "teardown" }));
+        await expect(run(["outposts", "destroy", "--yes"])).rejects.toThrow("process.exit(1)");
+    });
+});
+describe("outposts provision (billing gate)", () => {
+    it("refuses without --yes, prints the cost, and makes NO API call", async () => {
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        await expect(run(["outposts", "provision"])).rejects.toThrow("process.exit(1)");
+        expect(fetchSpy).not.toHaveBeenCalled();
+        const printed = errSpy.mock.calls
+            .map((c) => c.map(String).join(" "))
+            .join("\n");
+        expect(printed).toMatch(/\$80\.00\/month/);
+    });
+    it("POSTs /outpost/provision with the refresh token when --yes", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+        await run(["outposts", "provision", "--runtime", "codex", "--yes"]);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("/outpost/provision");
+        expect(init?.method).toBe("POST");
+        const sent = JSON.parse(init?.body);
+        expect(sent.refreshToken).toBe("rt_test");
+        expect(sent.agentRuntime).toBe("codex");
+    });
+    it("exits without provisioning when there is no cached session", async () => {
+        await expect(run(["outposts", "provision", "--yes"], {
+            loadCachedTokens: () => undefined,
+        })).rejects.toThrow("process.exit(1)");
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("rejects an unknown --runtime before the charge gate and makes NO API call", async () => {
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        await expect(run(["outposts", "provision", "--runtime", "codx", "--yes"])).rejects.toThrow("process.exit(1)");
+        expect(fetchSpy).not.toHaveBeenCalled();
+        const printed = errSpy.mock.calls
+            .map((c) => c.map(String).join(" "))
+            .join("\n");
+        // A typo'd runtime must not silently resolve to claude — codex is the whole
+        // point of the flag, so a near-miss has to name itself.
+        expect(printed).toContain("codx");
+        expect(printed).toMatch(/claude/);
+        expect(printed).toMatch(/codex/);
+    });
+    it("accepts an explicit --runtime claude", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+        await run(["outposts", "provision", "--runtime", "claude", "--yes"]);
+        const sent = JSON.parse(fetchSpy.mock.calls[0][1]?.body);
+        expect(sent.agentRuntime).toBe("claude");
+    });
+    it("explains the per-person cap on a 409 rather than printing a bare 'Conflict'", async () => {
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        // hq-pro's cap body carries `capped`/`limit`/`outposts` and NO
+        // `message`/`error` field, so the generic decoder falls through to
+        // res.statusText — the operator sees only "Conflict".
+        fetchSpy.mockResolvedValueOnce(jsonResponse(409, {
+            capped: true,
+            userId: "user_test_123",
+            limit: 1,
+            outposts: [
+                {
+                    outpostId: "primary",
+                    state: "ready",
+                    instanceName: "outpost-user_test_123",
+                    region: "us-east-1",
+                    agentRuntime: "claude",
+                    platform: "ec2",
+                    createdAt: "2026-07-01T00:00:00.000Z",
+                },
+            ],
+        }));
+        await expect(run(["outposts", "provision", "--yes"])).rejects.toThrow("process.exit(1)");
+        const printed = errSpy.mock.calls
+            .map((c) => c.map(String).join(" "))
+            .join("\n");
+        expect(printed).not.toMatch(/^Conflict$/m);
+        expect(printed).toMatch(/limit/i);
+        // Name the box they already own, and reassure on the charge they were just
+        // warned about — the cap is checked BEFORE activation billing.
+        expect(printed).toContain("primary");
+        expect(printed).toMatch(/not been charged/i);
+    });
+    it("mints a card-capture link on 402 billing_required and exits 1", async () => {
+        fetchSpy
+            .mockResolvedValueOnce(jsonResponse(402, {
+            error: "payment required",
+            billing: {
+                status: "billing_required",
+                setup: {
+                    payerType: "person",
+                    path: "/v1/billing/checkout/person",
+                    method: "POST",
+                },
+            },
+        }))
+            .mockResolvedValueOnce(jsonResponse(200, { url: "https://checkout.stripe.com/outpost" }));
+        await expect(run(["outposts", "provision", "--yes"])).rejects.toThrow("process.exit(1)");
+        expect(String(fetchSpy.mock.calls[1][0])).toContain("/v1/billing/checkout/person");
+        const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+        expect(printed).toContain("https://checkout.stripe.com/outpost");
+    });
+    it("surfaces the DECLINE reason on 402 payment_failed — never the 'No card on file' copy", async () => {
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        // hq-pro's payment_failed envelope: a card EXISTS and was declined. The
+        // server's `message` carries the friendly decline copy; telling this user
+        // "No card on file" sends them down the wrong remediation path entirely.
+        fetchSpy
+            .mockResolvedValueOnce(jsonResponse(402, {
+            error: "payment required",
+            message: "Your card was declined. Try a different card or contact your bank.",
+            billing: {
+                status: "payment_failed",
+                setup: {
+                    payerType: "person",
+                    path: "/v1/billing/checkout/person",
+                    method: "POST",
+                },
+            },
+        }))
+            .mockResolvedValueOnce(jsonResponse(200, { url: "https://checkout.stripe.com/update-card" }));
+        await expect(run(["outposts", "provision", "--yes"])).rejects.toThrow("process.exit(1)");
+        const printed = [...errSpy.mock.calls, ...logSpy.mock.calls]
+            .map((c) => c.map(String).join(" "))
+            .join("\n");
+        expect(printed).toContain("declined");
+        expect(printed).not.toContain("No card on file");
+        // The card-capture link still surfaces — as the way to UPDATE the card.
+        expect(printed).toContain("https://checkout.stripe.com/update-card");
+    });
+});
+describe("outposts exec", () => {
+    afterEach(() => {
+        process.exitCode = undefined;
+    });
+    it("wraps the command to run from the box's HQ folder, then runs it", () => {
+        const wrapped = withRemoteHqDir("pwd");
+        // SSM may invoke the command as root with HOME unset. Seed a real home so
+        // tools such as gh do not write machine state into the HQ checkout.
+        expect(wrapped).toContain('export HOME="${HOME:-/root}"');
+        // cd into $HOME/hq (SSH/login user) …
+        expect(wrapped).toContain('cd "$HOME/hq"');
+        // … falling back to ec2-user's home for the SSM/root path (no $HOME) …
+        expect(wrapped).toContain("cd ~ec2-user/hq");
+        // … never failing merely because the box has no HQ folder …
+        expect(wrapped).toContain("|| true");
+        // … and the caller's command still runs after the cd.
+        expect(wrapped.endsWith("; pwd")).toBe(true);
+    });
+    it("POSTs /outpost/exec with the joined command and streams stdout", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            outpostId: "primary",
+            instanceId: "i-abc",
+            commandId: "cmd-1",
+            status: "Success",
+            exitCode: 0,
+            stdout: "hello world\n",
+            stderr: "",
+            truncated: false,
+        }));
+        await run(["outposts", "exec", "echo", "hello", "world"]);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("/outpost/exec");
+        expect(init?.method).toBe("POST");
+        // The command is wrapped so it runs from the box's HQ folder.
+        expect(JSON.parse(init?.body)).toEqual({
+            command: withRemoteHqDir("'echo' 'hello' 'world'"),
+        });
+        const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+        expect(printed).toContain("hello world\n");
+        expect(process.exitCode).toBe(0);
+    });
+    it("propagates a non-zero remote exit code", async () => {
+        vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            outpostId: "primary",
+            instanceId: "i-abc",
+            commandId: "cmd-2",
+            status: "Failed",
+            exitCode: 2,
+            stdout: "",
+            stderr: "nope\n",
+            truncated: false,
+        }));
+        await run(["outposts", "exec", "exit", "2"]);
+        expect(process.exitCode).toBe(2);
+    });
+    it("exits nonzero when SSM reports a Failed status with no numeric exit code", async () => {
+        // A remote failure that SSM can't attach a code to (Failed/Cancelled with
+        // exitCode null) must NOT read as success, or `hq outposts exec` in a script
+        // silently swallows the failure.
+        vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            outpostId: "primary",
+            instanceId: "i-abc",
+            commandId: "cmd-x",
+            status: "Failed",
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            truncated: false,
+        }));
+        await run(["outposts", "exec", "boom"]);
+        expect(process.exitCode).toBe(1);
+    });
+    it("still exits 0 on a Success status that carries no numeric code", async () => {
+        vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            outpostId: "primary",
+            instanceId: "i-abc",
+            commandId: "cmd-y",
+            status: "Success",
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            truncated: false,
+        }));
+        await run(["outposts", "exec", "true"]);
+        expect(process.exitCode).toBe(0);
+    });
+    it("passes --id through as the outpostId query param", async () => {
+        vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            outpostId: "2",
+            instanceId: "i-2",
+            commandId: "c",
+            status: "Success",
+            exitCode: 0,
+            stdout: "",
+            stderr: "",
+            truncated: false,
+        }));
+        await run(["outposts", "exec", "--id", "2", "uptime"]);
+        expect(String(fetchSpy.mock.calls[0][0])).toContain("outpostId=2");
+    });
+    it("exits 1 and surfaces the server message on a non-2xx (e.g. not-ready)", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(409, {
+            error: true,
+            step: "not-ready",
+            message: 'outpost is "provisioning", not ready — it must be running to exec',
+        }));
+        await expect(run(["outposts", "exec", "echo", "hi"])).rejects.toThrow("process.exit(1)");
+    });
+    it("emits raw JSON with --json", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            outpostId: "primary",
+            instanceId: "i-abc",
+            commandId: "cmd-3",
+            status: "Success",
+            exitCode: 0,
+            stdout: "x\n",
+            stderr: "",
+            truncated: false,
+        }));
+        await run(["outposts", "exec", "--json", "echo", "x"]);
+        const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+        expect(printed).toContain('"commandId": "cmd-3"');
+    });
+});
+describe("outposts exec — Lightsail SSH fallback", () => {
+    afterEach(() => {
+        process.exitCode = undefined;
+    });
+    function platformUnsupported() {
+        return jsonResponse(409, {
+            error: true,
+            step: "platform-unsupported",
+            message: "remote exec requires the EC2 platform",
+        });
+    }
+    function sshAccess() {
+        return jsonResponse(200, {
+            ok: true,
+            outpostId: "primary",
+            platform: "lightsail",
+            host: "52.2.2.2",
+            port: 22,
+            username: "ec2-user",
+            privateKey: "-----BEGIN KEY-----\nx\n-----END KEY-----\n",
+        });
+    }
+    it("falls back to SSH when the box is Lightsail, streams stdout, propagates exit", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        fetchSpy
+            .mockResolvedValueOnce(platformUnsupported()) // /outpost/exec (SSM) → 409
+            .mockResolvedValueOnce(sshAccess()); // /outpost/ssh-access → 200
+        mockSpawnSync.mockReturnValue({
+            status: 0,
+            stdout: "lightsail-out\n",
+            stderr: "",
+            signal: null,
+            output: [],
+            pid: 1,
+        });
+        // Flags meant for the remote command go after `--` (same as the SSM path).
+        await run(["outposts", "exec", "--", "uname", "-a"]);
+        // Second HTTP call is the ssh-access mint.
+        expect(String(fetchSpy.mock.calls[1][0])).toContain("/outpost/ssh-access");
+        // ssh was invoked with the box coordinates and the command as the last arg.
+        const args = mockSpawnSync.mock.calls[0][1];
+        expect(mockSpawnSync.mock.calls[0][0]).toBe("ssh");
+        expect(args).toContain("ec2-user@52.2.2.2");
+        expect(args[args.length - 1]).toBe(withRemoteHqDir("'uname' '-a'"));
+        expect(args).toContain("BatchMode=yes");
+        const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+        expect(printed).toContain("lightsail-out\n");
+        expect(process.exitCode).toBe(0);
+    });
+    it("propagates a non-zero SSH exit code", async () => {
+        vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        fetchSpy
+            .mockResolvedValueOnce(platformUnsupported())
+            .mockResolvedValueOnce(sshAccess());
+        mockSpawnSync.mockReturnValue({
+            status: 7,
+            stdout: "",
+            stderr: "boom\n",
+            signal: null,
+            output: [],
+            pid: 1,
+        });
+        await run(["outposts", "exec", "false"]);
+        expect(process.exitCode).toBe(7);
+    });
+    it("exits 1 with a clear message when the ssh client is missing", async () => {
+        fetchSpy
+            .mockResolvedValueOnce(platformUnsupported())
+            .mockResolvedValueOnce(sshAccess());
+        const enoent = Object.assign(new Error("spawnSync ssh ENOENT"), {
+            code: "ENOENT",
+        });
+        mockSpawnSync.mockReturnValue({
+            error: enoent,
+            status: null,
+            stdout: "",
+            stderr: "",
+            signal: null,
+            output: [],
+            pid: 0,
+        });
+        await expect(run(["outposts", "exec", "echo", "hi"])).rejects.toThrow("process.exit(1)");
+    });
+    it("does NOT fall back for a non-platform error (e.g. not-ready)", async () => {
+        fetchSpy.mockResolvedValueOnce(jsonResponse(409, {
+            error: true,
+            step: "not-ready",
+            message: "not ready",
+        }));
+        await expect(run(["outposts", "exec", "echo", "hi"])).rejects.toThrow("process.exit(1)");
+        // Only the SSM call happened; no ssh-access mint, no ssh.
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+        expect(mockSpawnSync).not.toHaveBeenCalled();
+    });
+    it("refuses --async on Lightsail instead of silently holding an SSH session", async () => {
+        // --async exists to escape the ~20s sync cap. Falling back to a live SSH hold
+        // would reintroduce exactly the timeout it was meant to avoid.
+        fetchSpy.mockResolvedValueOnce(platformUnsupported());
+        await expect(run(["outposts", "exec", "--async", "sleep", "60"])).rejects.toThrow("process.exit(1)");
+        expect(mockSpawnSync).not.toHaveBeenCalled();
+    });
+});
+describe("outposts exec --async / --detach", () => {
+    afterEach(() => {
+        process.exitCode = undefined;
+    });
+    it("--detach submits with HQ-dir wrapper and prints commandId without waiting", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u",
+            outpostId: "3",
+            instanceId: "i-3",
+            commandId: "cmd-detach",
+            outputPrefix: "outpost-exec/u/3/n/out",
+            executionTimeoutSeconds: 172800,
+        }));
+        await run([
+            "outposts",
+            "exec",
+            "--detach",
+            "--id",
+            "3",
+            "--json",
+            "sleep",
+            "999",
+        ]);
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchSpy.mock.calls[0];
+        expect(String(url)).toContain("/outpost/exec");
+        expect(String(url)).toContain("outpostId=3");
+        expect(JSON.parse(init?.body)).toEqual({
+            mode: "submit",
+            command: withRemoteHqDir("'sleep' '999'"),
+        });
+        const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+        expect(printed).toContain('"commandId":"cmd-detach"');
+        // No second poll.
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+    it("--async submits then polls until done and streams stdout", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        fetchSpy
+            .mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u",
+            outpostId: "primary",
+            instanceId: "i",
+            commandId: "cmd-async",
+            outputPrefix: "p",
+            executionTimeoutSeconds: 7200,
+        }))
+            .mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u",
+            outpostId: "primary",
+            status: "Success",
+            done: true,
+            exitCode: 0,
+            stdout: "finished\n",
+            stderr: "",
+        }));
+        await run([
+            "outposts",
+            "exec",
+            "--async",
+            "--timeout-seconds",
+            "7200",
+            "echo",
+            "finished",
+        ]);
+        // submit + one result poll (terminal on first poll)
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+        expect(JSON.parse(fetchSpy.mock.calls[0][1]?.body)).toEqual({
+            mode: "submit",
+            command: withRemoteHqDir("'echo' 'finished'"),
+            timeoutSeconds: 7200,
+        });
+        expect(JSON.parse(fetchSpy.mock.calls[1][1]?.body)).toEqual({
+            mode: "result",
+            commandId: "cmd-async",
+        });
+        const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+        expect(printed).toContain("finished\n");
+        expect(process.exitCode).toBe(0);
+    });
+    it("refuses --async and --detach together", async () => {
+        await expect(run(["outposts", "exec", "--async", "--detach", "true"])).rejects.toThrow("process.exit(1)");
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("rejects a --timeout-seconds beyond the AWS-RunShellScript 48h ceiling", async () => {
+        await expect(run(["outposts", "exec", "--timeout-seconds", "172801", "true"])).rejects.toThrow("process.exit(1)");
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("exec-submit forwards --timeout-seconds", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            commandId: "cmd-sub",
+            executionTimeoutSeconds: 3600,
+            userId: "u",
+            outpostId: "primary",
+            instanceId: "i",
+            outputPrefix: "p",
+        }));
+        await run([
+            "outposts",
+            "exec-submit",
+            "--timeout-seconds",
+            "3600",
+            "--json",
+            "sleep",
+            "10",
+        ]);
+        expect(JSON.parse(fetchSpy.mock.calls[0][1]?.body)).toEqual({
+            mode: "submit",
+            command: "'sleep' '10'",
+            timeoutSeconds: 3600,
+        });
+        const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+        expect(printed).toContain("cmd-sub");
+    });
+});
+describe("outposts asynchronous exec", () => {
+    it("sends the stage, submit, and result mode request bodies", async () => {
+        fetchSpy
+            .mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u1",
+            outpostId: "2",
+            key: "input-key",
+            putUrl: "https://upload.invalid/put",
+            getUrl: "https://download.invalid/get",
+            expiresInSeconds: 300,
+        }))
+            .mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u1",
+            outpostId: "2",
+            instanceId: "i-2",
+            commandId: "cmd-1",
+            outputPrefix: "output-prefix",
+        }))
+            .mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u1",
+            outpostId: "2",
+            status: "InProgress",
+            done: false,
+        }));
+        const client = new OutpostsClient({
+            transport: testTransport(),
+            token: "test-token",
+        });
+        await client.stageExecInput("2");
+        await client.submitExec("cd /tmp && run-worker", "2");
+        await client.fetchExecResult("cmd-1", "2");
+        expect(fetchSpy.mock.calls.map(([url]) => String(url))).toEqual([
+            expect.stringContaining("/outpost/exec?outpostId=2"),
+            expect.stringContaining("/outpost/exec?outpostId=2"),
+            expect.stringContaining("/outpost/exec?outpostId=2"),
+        ]);
+        expect(fetchSpy.mock.calls.map(([, init]) => JSON.parse(init?.body))).toEqual([
+            { mode: "stage" },
+            { mode: "submit", command: "cd /tmp && run-worker" },
+            { mode: "result", commandId: "cmd-1" },
+        ]);
+    });
+    it("exec-stage PUTs the exact file bytes and prints only key + getUrl JSON", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        const file = path.join(process.cwd(), "package.json");
+        const expectedBytes = fs.readFileSync(file);
+        fetchSpy
+            .mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u1",
+            outpostId: "2",
+            key: "input-key",
+            putUrl: "https://upload.invalid/put",
+            getUrl: "https://download.invalid/get",
+            expiresInSeconds: 300,
+        }))
+            .mockResolvedValueOnce(new Response(null, { status: 200 }));
+        await run([
+            "outposts",
+            "exec-stage",
+            "--id",
+            "2",
+            "--file",
+            file,
+            "--json",
+        ]);
+        expect(fetchSpy).toHaveBeenCalledTimes(2);
+        const [uploadUrl, uploadInit] = fetchSpy.mock.calls[1];
+        expect(String(uploadUrl)).toBe("https://upload.invalid/put");
+        expect(uploadInit?.method).toBe("PUT");
+        expect(uploadInit?.headers).toEqual({
+            "Content-Length": String(expectedBytes.byteLength),
+        });
+        expect(Buffer.from(uploadInit?.body)).toEqual(expectedBytes);
+        const printed = stdoutSpy.mock.calls
+            .map((call) => String(call[0]))
+            .join("");
+        expect(JSON.parse(printed)).toEqual({
+            key: "input-key",
+            getUrl: "https://download.invalid/get",
+        });
+    });
+    it("exec-stage exits non-zero when the presigned upload fails", async () => {
+        fetchSpy
+            .mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u1",
+            outpostId: "primary",
+            key: "input-key",
+            putUrl: "https://upload.invalid/put",
+            getUrl: "https://download.invalid/get",
+            expiresInSeconds: 300,
+        }))
+            .mockResolvedValueOnce(new Response(null, { status: 503 }));
+        await expect(run([
+            "outposts",
+            "exec-stage",
+            "--file",
+            path.join(process.cwd(), "package.json"),
+            "--json",
+        ])).rejects.toThrow("process.exit(1)");
+    });
+    it("exec-submit shell-quotes multiple argv parts without adding the HQ-directory wrapper", async () => {
+        const stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+        const script = 'printf "%s\\n" "$0" "$1" "$2"';
+        fetchSpy.mockResolvedValueOnce(jsonResponse(200, {
+            ok: true,
+            userId: "u1",
+            outpostId: "primary",
+            instanceId: "i-1",
+            commandId: "cmd-submit",
+            outputPrefix: "output-prefix",
+        }));
+        await run([
+            "outposts",
+            "exec-submit",
+            "--json",
+            "--",
+            "bash",
+            "-c",
+            script,
+            "marker",
+            "a b",
+            "quote's",
+        ]);
+        const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body);
+        expect(body).toEqual({
+            mode: "submit",
+            command: joinCommandParts([
+                "bash",
+                "-c",
+                script,
+                "marker",
+                "a b",
+                "quote's",
+            ]),
+        });
+        expect(body.command).not.toContain("cd ~ec2-user/hq");
+        expect(JSON.parse(String(stdoutSpy.mock.calls[0][0]))).toEqual({
+            commandId: "cmd-submit",
+        });
+    });
+    // Spawns a real `bash` (execFileSync) to prove the round-trip end-to-end. Under
+    // the saturated full-suite parallel pool that spawn can exceed vitest's default
+    // per-test budget purely on scheduling contention; the extra budget covers that,
+    // not slow logic (isolated, this runs in milliseconds).
+    it("preserves one command part verbatim and round-trips quoted bash argv", () => {
+        const single = "  printf 'already formed'  ";
+        expect(joinCommandParts([single])).toBe(single);
+        const script = 'printf "%s\\n" "$0" "$1" "$2"';
+        const command = joinCommandParts([
+            "bash",
+            "-c",
+            script,
+            "marker",
+            "a b",
+            "quote's",
+        ]);
+        expect(execFileSync("bash", ["-c", command], { encoding: "utf8" })).toBe("marker\na b\nquote's\n");
+    }, 30_000);
+    it("exec-result --wait retries a 429, polls until done, and prints the result contract", async () => {
+        vi.useFakeTimers();
+        try {
+            const stdoutSpy = vi
+                .spyOn(process.stdout, "write")
+                .mockImplementation(() => true);
+            fetchSpy
+                .mockResolvedValueOnce(jsonResponse(429, {
+                error: true,
+                step: "rate",
+                message: "slow down",
+            }))
+                .mockResolvedValueOnce(jsonResponse(200, {
+                ok: true,
+                userId: "u1",
+                outpostId: "2",
+                status: "InProgress",
+                done: false,
+            }))
+                .mockResolvedValueOnce(jsonResponse(200, {
+                ok: true,
+                userId: "u1",
+                outpostId: "2",
+                status: "Success",
+                done: true,
+                exitCode: 0,
+                stdout: "finished\n",
+                stderr: "",
+                truncated: false,
+            }));
+            const pending = run([
+                "outposts",
+                "exec-result",
+                "--id",
+                "2",
+                "--command-id",
+                "cmd-1",
+                "--wait",
+                "--json",
+            ]);
+            await vi.advanceTimersByTimeAsync(500);
+            await vi.advanceTimersByTimeAsync(1_000);
+            await pending;
+            expect(fetchSpy).toHaveBeenCalledTimes(3);
+            expect(JSON.parse(String(stdoutSpy.mock.calls[0][0]))).toEqual({
+                done: true,
+                status: "Success",
+                exitCode: 0,
+                stdout: "finished\n",
+                stderr: "",
+            });
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});
+//# sourceMappingURL=command.test.js.map