@indigoai-us/hq-cli 5.63.0 → 5.64.0

package/dist/commands/outposts.d.ts

@@ -73,5 +73,26 @@ export declare function getOutpostStatus(token: string, outpostId?: string): Pro
 export declare function enableCodex(token: string, outpostId?: string): Promise<Record<string, unknown>>;
 export declare function regenerateLoginUrl(token: string, outpostId?: string): Promise<Record<string, unknown>>;
 export declare function destroyOutpost(token: string, outpostId?: string): Promise<Record<string, unknown>>;
+/** Result of `POST /outpost/exec` — a terminal SSM invocation on the box. */
+export interface OutpostExecResult {
+    ok: true;
+    outpostId: string;
+    instanceId: string;
+    commandId: string;
+    /** SSM invocation status (Success | Failed | Cancelled). */
+    status: string;
+    /** Remote process exit code, or null when SSM reported none. */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** True when SSM clipped stdout/stderr at its inline output limit. */
+    truncated: boolean;
+}
+/**
+ * Run a one-shot shell command on the caller's Outpost via `POST /outpost/exec`
+ * (server-brokered SSM — no SSH). Throws `OutpostHttpError` on a non-2xx, whose
+ * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
+ */
+export declare function execOutpost(token: string, command: string, outpostId?: string): Promise<OutpostExecResult>;
 export declare function registerOutpostsCommand(program: Command): void;
 //# sourceMappingURL=outposts.d.ts.map

package/dist/commands/outposts.js

@@ -21,7 +21,7 @@
  * and status routes that exist. Renaming an Outpost is not a backend capability.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d99c091a-e57f-55a6-a666-fdc339c83aab")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="067e20d6-0132-565a-8a22-9c27520669d2")}catch(e){}}();
 import chalk from "chalk";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -119,6 +119,20 @@ export async function destroyOutpost(token, outpostId) {
         query: outpostId ? { outpostId } : undefined,
     });
 }
+/**
+ * Run a one-shot shell command on the caller's Outpost via `POST /outpost/exec`
+ * (server-brokered SSM — no SSH). Throws `OutpostHttpError` on a non-2xx, whose
+ * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
+ */
+export async function execOutpost(token, command, outpostId) {
+    return outpostRequest({
+        token,
+        path: "/outpost/exec",
+        method: "POST",
+        body: { command },
+        query: outpostId ? { outpostId } : undefined,
+    });
+}
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -267,6 +281,45 @@ export function registerOutpostsCommand(program) {
             fail(err);
         }
     });
+    outposts
+        .command("exec <command...>")
+        .description("Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command)")
+        .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+        .option("--json", "Emit raw JSON")
+        .action(async function (commandParts, opts) {
+        try {
+            const command = commandParts.join(" ").trim();
+            if (!command) {
+                console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
+                process.exit(1);
+            }
+            const token = await ensureCognitoToken();
+            const result = await execOutpost(token, command, opts.id);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                // Stream the remote streams to ours so the command feels local, then
+                // exit with the remote exit code.
+                if (result.stdout)
+                    process.stdout.write(result.stdout);
+                if (result.stderr)
+                    process.stderr.write(result.stderr);
+                if (result.truncated) {
+                    console.error(chalk.yellow("(output truncated by SSM's inline limit — redirect to a file on the box for full output)"));
+                }
+                if (result.status !== "Success" && result.exitCode === null) {
+                    console.error(chalk.yellow(`(command ended with SSM status: ${result.status})`));
+                }
+            }
+            // Propagate the remote exit code so `hq outposts exec -- false` exits 1.
+            process.exitCode =
+                typeof result.exitCode === "number" ? result.exitCode : 0;
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     outposts
         .command("codex-enable")
         .description("Enable (or retry) Codex on an Outpost")
@@ -339,4 +392,4 @@ export function registerOutpostsCommand(program) {
     });
 }
 //# sourceMappingURL=outposts.js.map
-//# debugId=d99c091a-e57f-55a6-a666-fdc339c83aab
+//# debugId=067e20d6-0132-565a-8a22-9c27520669d2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.63.0",
+  "version": "5.64.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/outposts.test.ts

@@ -245,3 +245,112 @@ describe("hq outposts provision (billing gate)", () => {
     expect(printed).toContain("https://checkout.stripe.com/outpost");
   });
 });
+
+describe("hq outposts exec", () => {
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
+  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");
+    expect(JSON.parse(init?.body as string)).toEqual({ command: "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("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"');
+  });
+});

package/src/commands/outposts.ts

@@ -187,6 +187,41 @@ export async function destroyOutpost(
   });
 }
 
+/** Result of `POST /outpost/exec` — a terminal SSM invocation on the box. */
+export interface OutpostExecResult {
+  ok: true;
+  outpostId: string;
+  instanceId: string;
+  commandId: string;
+  /** SSM invocation status (Success | Failed | Cancelled). */
+  status: string;
+  /** Remote process exit code, or null when SSM reported none. */
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  /** True when SSM clipped stdout/stderr at its inline output limit. */
+  truncated: boolean;
+}
+
+/**
+ * Run a one-shot shell command on the caller's Outpost via `POST /outpost/exec`
+ * (server-brokered SSM — no SSH). Throws `OutpostHttpError` on a non-2xx, whose
+ * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
+ */
+export async function execOutpost(
+  token: string,
+  command: string,
+  outpostId?: string,
+): Promise<OutpostExecResult> {
+  return outpostRequest({
+    token,
+    path: "/outpost/exec",
+    method: "POST",
+    body: { command },
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -369,6 +404,51 @@ export function registerOutpostsCommand(program: Command): void {
       }
     });
 
+  outposts
+    .command("exec <command...>")
+    .description(
+      "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command)",
+    )
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      commandParts: string[],
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const command = commandParts.join(" ").trim();
+        if (!command) {
+          console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
+          process.exit(1);
+        }
+        const token = await ensureCognitoToken();
+        const result = await execOutpost(token, command, opts.id);
+
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        } else {
+          // Stream the remote streams to ours so the command feels local, then
+          // exit with the remote exit code.
+          if (result.stdout) process.stdout.write(result.stdout);
+          if (result.stderr) process.stderr.write(result.stderr);
+          if (result.truncated) {
+            console.error(
+              chalk.yellow("(output truncated by SSM's inline limit — redirect to a file on the box for full output)"),
+            );
+          }
+          if (result.status !== "Success" && result.exitCode === null) {
+            console.error(chalk.yellow(`(command ended with SSM status: ${result.status})`));
+          }
+        }
+        // Propagate the remote exit code so `hq outposts exec -- false` exits 1.
+        process.exitCode =
+          typeof result.exitCode === "number" ? result.exitCode : 0;
+      } catch (err) {
+        fail(err);
+      }
+    });
+
   outposts
     .command("codex-enable")
     .description("Enable (or retry) Codex on an Outpost")