@indigoai-us/hq-cli 5.65.0 → 5.66.0

package/dist/commands/outposts.d.ts

@@ -94,5 +94,34 @@ export interface OutpostExecResult {
  * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
  */
 export declare function execOutpost(token: string, command: string, outpostId?: string): Promise<OutpostExecResult>;
+/** SSH connection details vended by `POST /outpost/ssh-access`. */
+export interface OutpostSshAccess {
+    outpostId: string;
+    platform: "ec2" | "lightsail";
+    host: string;
+    port: number;
+    username: string;
+    /** PEM private key for the box. SENSITIVE — never printed or logged. */
+    privateKey: string;
+}
+/**
+ * Fetch SSH connection info + key for the caller's Outpost and open the caller's
+ * IP on the box's SSH port. Used to reach a Lightsail box (no SSM). Throws
+ * `OutpostHttpError` on a non-2xx.
+ */
+export declare function getOutpostSshAccess(token: string, outpostId?: string): Promise<OutpostSshAccess>;
+/**
+ * Run `command` on the box over SSH using vended access details. Writes the
+ * private key to a locked-down temp file, runs a non-interactive `ssh`, and
+ * returns stdout/stderr/exitCode. The key file + a throwaway known_hosts file
+ * are always cleaned up; the key is never printed. `exitCode` is `null` only
+ * when `ssh` itself couldn't run (e.g. binary missing) — surfaced via `error`.
+ */
+export declare function execViaSsh(access: OutpostSshAccess, command: string): {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    error?: string;
+};
 export declare function registerOutpostsCommand(program: Command): void;
 //# sourceMappingURL=outposts.d.ts.map

package/dist/commands/outposts.js

@@ -21,8 +21,13 @@
  * 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]="067e20d6-0132-565a-8a22-9c27520669d2")}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]="951a0bc6-7dc3-5b10-b8f6-728df1074817")}catch(e){}}();
 import chalk from "chalk";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
@@ -133,6 +138,72 @@ export async function execOutpost(token, command, outpostId) {
         query: outpostId ? { outpostId } : undefined,
     });
 }
+/**
+ * Fetch SSH connection info + key for the caller's Outpost and open the caller's
+ * IP on the box's SSH port. Used to reach a Lightsail box (no SSM). Throws
+ * `OutpostHttpError` on a non-2xx.
+ */
+export async function getOutpostSshAccess(token, outpostId) {
+    return outpostRequest({
+        token,
+        path: "/outpost/ssh-access",
+        method: "POST",
+        body: {},
+        query: outpostId ? { outpostId } : undefined,
+    });
+}
+/**
+ * Run `command` on the box over SSH using vended access details. Writes the
+ * private key to a locked-down temp file, runs a non-interactive `ssh`, and
+ * returns stdout/stderr/exitCode. The key file + a throwaway known_hosts file
+ * are always cleaned up; the key is never printed. `exitCode` is `null` only
+ * when `ssh` itself couldn't run (e.g. binary missing) — surfaced via `error`.
+ */
+export function execViaSsh(access, command) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-outpost-ssh-"));
+    const keyPath = path.join(dir, `id_${randomBytes(6).toString("hex")}`);
+    const knownHosts = path.join(dir, "known_hosts");
+    try {
+        fs.writeFileSync(keyPath, ensureTrailingNewline(access.privateKey), {
+            mode: 0o600,
+        });
+        const result = spawnSync("ssh", [
+            "-i",
+            keyPath,
+            "-p",
+            String(access.port),
+            "-o",
+            "BatchMode=yes",
+            "-o",
+            "StrictHostKeyChecking=accept-new",
+            "-o",
+            `UserKnownHostsFile=${knownHosts}`,
+            "-o",
+            "ConnectTimeout=15",
+            "-o",
+            "LogLevel=ERROR",
+            `${access.username}@${access.host}`,
+            command,
+        ], { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+        if (result.error) {
+            const hint = result.error.code === "ENOENT"
+                ? "the `ssh` client is not installed or not on PATH"
+                : result.error.message;
+            return { stdout: "", stderr: "", exitCode: null, error: hint };
+        }
+        return {
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            exitCode: result.status,
+        };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith("\n") ? s : s + "\n";
+}
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -294,27 +365,60 @@ export function registerOutpostsCommand(program) {
                 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)"));
+            try {
+                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.
+                    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})`));
+                    }
                 }
-                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) {
+                // Lightsail boxes have no SSM agent — transparently fall back to SSH.
+                if (err instanceof OutpostHttpError &&
+                    err.step === "platform-unsupported") {
+                    const access = await getOutpostSshAccess(token, opts.id);
+                    const ssh = execViaSsh(access, command);
+                    if (ssh.error) {
+                        console.error(chalk.red(`Could not run the command over SSH: ${ssh.error}`));
+                        process.exit(1);
+                    }
+                    if (opts.json) {
+                        process.stdout.write(JSON.stringify({
+                            via: "ssh",
+                            platform: access.platform,
+                            host: access.host,
+                            exitCode: ssh.exitCode,
+                            stdout: ssh.stdout,
+                            stderr: ssh.stderr,
+                        }, null, 2) + "\n");
+                    }
+                    else {
+                        if (ssh.stdout)
+                            process.stdout.write(ssh.stdout);
+                        if (ssh.stderr)
+                            process.stderr.write(ssh.stderr);
+                    }
+                    process.exitCode =
+                        typeof ssh.exitCode === "number" ? ssh.exitCode : 1;
+                    return;
                 }
+                throw err;
             }
-            // 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);
@@ -392,4 +496,4 @@ export function registerOutpostsCommand(program) {
     });
 }
 //# sourceMappingURL=outposts.js.map
-//# debugId=067e20d6-0132-565a-8a22-9c27520669d2
+//# debugId=951a0bc6-7dc3-5b10-b8f6-728df1074817

package/package.json

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

package/src/commands/outposts.test.ts

@@ -42,9 +42,20 @@ vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
   };
 });
 
+// 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<typeof import("node:child_process")>();
+  return { ...original, spawnSync: vi.fn() };
+});
+
+import { spawnSync } from "node:child_process";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { registerOutpostsCommand } from "./outposts.js";
 
+const mockSpawnSync = vi.mocked(spawnSync);
+
 function jsonResponse(status: number, body: unknown): Response {
   return new Response(JSON.stringify(body), {
     status,
@@ -354,3 +365,112 @@ describe("hq outposts exec", () => {
     expect(printed).toContain('"commandId": "cmd-3"');
   });
 });
+
+describe("hq outposts exec — Lightsail SSH fallback", () => {
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
+  function platformUnsupported(): Response {
+    return jsonResponse(409, {
+      error: true,
+      step: "platform-unsupported",
+      message: "remote exec requires the EC2 platform",
+    });
+  }
+
+  function sshAccess(): Response {
+    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,
+    } as unknown as ReturnType<typeof spawnSync>);
+
+    // 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] as string[];
+    expect(mockSpawnSync.mock.calls[0][0]).toBe("ssh");
+    expect(args).toContain("ec2-user@52.2.2.2");
+    expect(args[args.length - 1]).toBe("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,
+    } as unknown as ReturnType<typeof spawnSync>);
+    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,
+    } as unknown as ReturnType<typeof spawnSync>);
+    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();
+  });
+});

package/src/commands/outposts.ts

@@ -23,6 +23,11 @@
 
 import { Command } from "commander";
 import chalk from "chalk";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
@@ -222,6 +227,96 @@ export async function execOutpost(
   });
 }
 
+/** SSH connection details vended by `POST /outpost/ssh-access`. */
+export interface OutpostSshAccess {
+  outpostId: string;
+  platform: "ec2" | "lightsail";
+  host: string;
+  port: number;
+  username: string;
+  /** PEM private key for the box. SENSITIVE — never printed or logged. */
+  privateKey: string;
+}
+
+/**
+ * Fetch SSH connection info + key for the caller's Outpost and open the caller's
+ * IP on the box's SSH port. Used to reach a Lightsail box (no SSM). Throws
+ * `OutpostHttpError` on a non-2xx.
+ */
+export async function getOutpostSshAccess(
+  token: string,
+  outpostId?: string,
+): Promise<OutpostSshAccess> {
+  return outpostRequest({
+    token,
+    path: "/outpost/ssh-access",
+    method: "POST",
+    body: {},
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+/**
+ * Run `command` on the box over SSH using vended access details. Writes the
+ * private key to a locked-down temp file, runs a non-interactive `ssh`, and
+ * returns stdout/stderr/exitCode. The key file + a throwaway known_hosts file
+ * are always cleaned up; the key is never printed. `exitCode` is `null` only
+ * when `ssh` itself couldn't run (e.g. binary missing) — surfaced via `error`.
+ */
+export function execViaSsh(
+  access: OutpostSshAccess,
+  command: string,
+): { stdout: string; stderr: string; exitCode: number | null; error?: string } {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-outpost-ssh-"));
+  const keyPath = path.join(dir, `id_${randomBytes(6).toString("hex")}`);
+  const knownHosts = path.join(dir, "known_hosts");
+  try {
+    fs.writeFileSync(keyPath, ensureTrailingNewline(access.privateKey), {
+      mode: 0o600,
+    });
+    const result = spawnSync(
+      "ssh",
+      [
+        "-i",
+        keyPath,
+        "-p",
+        String(access.port),
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        "StrictHostKeyChecking=accept-new",
+        "-o",
+        `UserKnownHostsFile=${knownHosts}`,
+        "-o",
+        "ConnectTimeout=15",
+        "-o",
+        "LogLevel=ERROR",
+        `${access.username}@${access.host}`,
+        command,
+      ],
+      { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
+    );
+    if (result.error) {
+      const hint =
+        (result.error as NodeJS.ErrnoException).code === "ENOENT"
+          ? "the `ssh` client is not installed or not on PATH"
+          : result.error.message;
+      return { stdout: "", stderr: "", exitCode: null, error: hint };
+    }
+    return {
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      exitCode: result.status,
+    };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function ensureTrailingNewline(s: string): string {
+  return s.endsWith("\n") ? s : s + "\n";
+}
+
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -423,27 +518,64 @@ export function registerOutpostsCommand(program: Command): void {
           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)"),
-            );
+        try {
+          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.
+            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})`));
+            }
           }
-          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) {
+          // Lightsail boxes have no SSM agent — transparently fall back to SSH.
+          if (
+            err instanceof OutpostHttpError &&
+            err.step === "platform-unsupported"
+          ) {
+            const access = await getOutpostSshAccess(token, opts.id);
+            const ssh = execViaSsh(access, command);
+            if (ssh.error) {
+              console.error(chalk.red(`Could not run the command over SSH: ${ssh.error}`));
+              process.exit(1);
+            }
+            if (opts.json) {
+              process.stdout.write(
+                JSON.stringify(
+                  {
+                    via: "ssh",
+                    platform: access.platform,
+                    host: access.host,
+                    exitCode: ssh.exitCode,
+                    stdout: ssh.stdout,
+                    stderr: ssh.stderr,
+                  },
+                  null,
+                  2,
+                ) + "\n",
+              );
+            } else {
+              if (ssh.stdout) process.stdout.write(ssh.stdout);
+              if (ssh.stderr) process.stderr.write(ssh.stderr);
+            }
+            process.exitCode =
+              typeof ssh.exitCode === "number" ? ssh.exitCode : 1;
+            return;
           }
+          throw err;
         }
-        // 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);
       }