@indigoai-us/hq-cli 5.61.0 → 5.62.0

package/src/commands/outposts.ts

@@ -0,0 +1,338 @@
+/**
+ * `hq outposts` — manage your personal HQ Outposts (EC2 boxes) from the
+ * terminal instead of the web console. Targets the hq-pro `/outpost/*`
+ * control plane on `DEFAULT_VAULT_API_URL` via the shared `vaultApiFetch`
+ * helper — the same routes the console's outpost panel calls.
+ *
+ * Outposts are PERSONAL / caller-scoped: hq-pro keys every `/outpost/*` route
+ * on the caller's Cognito sub, so there is no `--company`. `--id <outpostId>`
+ * selects a specific box (passed as the `outpostId` query param); when omitted
+ * hq-pro targets the caller's primary slot.
+ *
+ * Subcommands:
+ *   hq outposts list                — every Outpost you own (row summaries)
+ *   hq outposts status [--id]       — live detail for one box
+ *   hq outposts codex-enable [--id] — enable / retry Codex on the box
+ *   hq outposts login [--id]        — request a fresh login URL
+ *   hq outposts destroy [--id] --yes — tear the box down (destructive; flag-guarded)
+ *
+ * NOTE: hq-pro exposes no rename or settings-mutation route for Outposts (the
+ * web console can't rename them either), so this CLI wraps only the lifecycle
+ * and status routes that exist. Renaming an Outpost is not a backend capability.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+
+/** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
+export class OutpostHttpError extends Error {
+  status: number;
+  step?: string;
+  constructor(status: number, message: string, step?: string) {
+    super(message);
+    this.name = "OutpostHttpError";
+    this.status = status;
+    this.step = step;
+  }
+}
+
+/** Row summary from `GET /outpost/list`. */
+export interface OutpostSummary {
+  outpostId: string;
+  state: string;
+  instanceName: string;
+  region: string;
+  agentRuntime: string;
+  platform: string;
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Authenticated JSON round-trip against the outpost control plane. Throws
+ * `OutpostHttpError` on any non-2xx (never swallows — hq-never-swallow-errors),
+ * decoding hq-pro's `{ error | message, step }` envelope for the reason. The
+ * `step` is preserved so callers can recognise the `destroy` route's
+ * `teardown-incomplete` 409 (which means "retry", not "failed").
+ */
+export async function outpostRequest<T>(opts: {
+  token: string;
+  path: string;
+  method?: string;
+  query?: Record<string, string>;
+}): Promise<T> {
+  const res = await vaultApiFetch(opts);
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as {
+      error?: unknown;
+      message?: string;
+      step?: string;
+    };
+    const message =
+      typeof body.message === "string"
+        ? body.message
+        : typeof body.error === "string"
+          ? body.error
+          : res.statusText;
+    throw new OutpostHttpError(res.status, message, body.step);
+  }
+  return (await res.json()) as T;
+}
+
+export async function listOutposts(token: string): Promise<OutpostSummary[]> {
+  const data = await outpostRequest<{ outposts: OutpostSummary[] }>({
+    token,
+    path: "/outpost/list",
+  });
+  return data.outposts ?? [];
+}
+
+export async function getOutpostStatus(
+  token: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/status",
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+export async function enableCodex(
+  token: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/codex/enable",
+    method: "POST",
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+export async function regenerateLoginUrl(
+  token: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/regenerate-login-url",
+    method: "POST",
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+export async function destroyOutpost(
+  token: string,
+  outpostId?: string,
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/destroy",
+    method: "POST",
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+function fail(err: unknown): never {
+  if (err instanceof OutpostHttpError) {
+    console.error(chalk.red(err.message));
+  } else {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+  process.exit(1);
+}
+
+/** Print a top-level object as `key: value`, JSON-ifying nested values. */
+function printKeyValues(obj: Record<string, unknown>): void {
+  for (const [k, v] of Object.entries(obj)) {
+    const rendered = v && typeof v === "object" ? JSON.stringify(v) : String(v);
+    console.log(`${chalk.bold(k)}: ${rendered}`);
+  }
+}
+
+export function registerOutpostsCommand(program: Command): void {
+  const outposts = program
+    .command("outposts")
+    .description("Manage your personal HQ Outposts (EC2 boxes)");
+
+  outposts
+    .command("list")
+    .description("List every Outpost you own")
+    .option("--json", "Emit raw JSON")
+    .action(async function (this: Command, opts: { json?: boolean }) {
+      try {
+        const token = await ensureCognitoToken();
+        const rows = await listOutposts(token);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
+          return;
+        }
+        if (rows.length === 0) {
+          console.log(chalk.gray("You don't own any Outposts yet."));
+          return;
+        }
+        const idW = Math.max(2, ...rows.map((r) => (r.outpostId ?? "").length));
+        const stateW = Math.max(5, ...rows.map((r) => (r.state ?? "").length));
+        const nameW = Math.max(
+          4,
+          ...rows.map((r) => (r.instanceName ?? "").length),
+        );
+        const regionW = Math.max(6, ...rows.map((r) => (r.region ?? "").length));
+        const rtW = Math.max(
+          7,
+          ...rows.map((r) => (r.agentRuntime ?? "").length),
+        );
+        console.log(
+          chalk.bold(
+            [
+              "ID".padEnd(idW),
+              "STATE".padEnd(stateW),
+              "INSTANCE".padEnd(nameW),
+              "REGION".padEnd(regionW),
+              "RUNTIME".padEnd(rtW),
+              "PLATFORM",
+            ].join("  "),
+          ),
+        );
+        for (const r of rows) {
+          console.log(
+            [
+              (r.outpostId ?? "").padEnd(idW),
+              (r.state ?? "").padEnd(stateW),
+              (r.instanceName ?? "").padEnd(nameW),
+              (r.region ?? "").padEnd(regionW),
+              (r.agentRuntime ?? "").padEnd(rtW),
+              r.platform ?? "",
+            ].join("  "),
+          );
+        }
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("status")
+    .description("Show live detail for one Outpost")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        const status = await getOutpostStatus(token, opts.id);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+          return;
+        }
+        printKeyValues(status);
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("codex-enable")
+    .description("Enable (or retry) Codex on an Outpost")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        const result = await enableCodex(token, opts.id);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+          return;
+        }
+        console.log(chalk.green("Codex enablement requested for the Outpost."));
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("login")
+    .description("Request a fresh login URL for an Outpost")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      opts: { id?: string; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        const result = await regenerateLoginUrl(token, opts.id);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+          return;
+        }
+        console.log(
+          chalk.green(
+            "Login-URL regeneration requested. The box mints a fresh URL shortly — " +
+              "check `hq outposts status` to pick it up.",
+          ),
+        );
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  outposts
+    .command("destroy")
+    .description("Tear down (permanently destroy) an Outpost")
+    .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option("--yes", "Confirm the irreversible teardown (required)")
+    .action(async function (
+      this: Command,
+      opts: { id?: string; yes?: boolean },
+    ) {
+      const target = opts.id ?? "your primary Outpost";
+      if (!opts.yes) {
+        console.error(
+          chalk.yellow(
+            `This will permanently destroy ${target} and delete its cloud resources. ` +
+              `This cannot be undone.\n` +
+              `Re-run with --yes to confirm: hq outposts destroy${opts.id ? ` --id ${opts.id}` : ""} --yes`,
+          ),
+        );
+        process.exit(1);
+      }
+      try {
+        const token = await ensureCognitoToken();
+        await destroyOutpost(token, opts.id);
+        console.log(chalk.green(`Destroyed ${target}.`));
+      } catch (err) {
+        // A 409 teardown-incomplete is not a failure — the gateway's 30s cap
+        // fired while the Lambda keeps working. The row is preserved and the
+        // operation is idempotent, so tell the caller to retry.
+        if (
+          err instanceof OutpostHttpError &&
+          (err.status === 409 || err.step === "teardown-incomplete")
+        ) {
+          console.log(
+            chalk.yellow(
+              `Teardown still in progress for ${target} — this is expected for large boxes. ` +
+                `Re-run the same destroy command to finish (it's idempotent).`,
+            ),
+          );
+          return;
+        }
+        fail(err);
+      }
+    });
+}

package/src/commands/secrets.parse-destination.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Pre-landing hardening (secrets-proxy-per-secret-destination): `--destination`
+ * must reject an embedded `user:pass@host` userinfo segment EXPLICITLY rather
+ * than letting `new URL()` silently drop it and normalize to the bare host.
+ * Mirrors hq-pro's authoritative `validateDestinations` server-side check — the
+ * server re-validates and remains authoritative, but the CLI must not present a
+ * userinfo URL as an accepted destination.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { parseDestinationUrl } from "./secrets.js";
+
+describe("parseDestinationUrl — userinfo hardening", () => {
+  beforeEach(() => {
+    // parseDestinationUrl logs the rejection reason to stderr; silence it so the
+    // test output stays clean while still exercising the real code path.
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it.each([
+    "https://user:pass@api.openai.com",
+    "https://user@api.openai.com",
+    "https://:pass@api.openai.com",
+  ])("rejects a destination with embedded userinfo (%s)", (raw) => {
+    expect(parseDestinationUrl(raw).ok).toBe(false);
+  });
+
+  it("still accepts a bare scheme+host HTTPS destination (guards against over-rejection)", () => {
+    const result = parseDestinationUrl("https://api.openai.com");
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.url).toBe("https://api.openai.com");
+      expect(result.hostname).toBe("api.openai.com");
+    }
+  });
+});

package/src/commands/secrets.test.ts

@@ -162,6 +162,30 @@ describe("secrets sandbox", () => {
     expect(stdoutSpy).toHaveBeenCalledWith("done\n");
   });
 
+  it("accumulates repeated --only flags instead of silently keeping only the last", async () => {
+    const program = buildProgram();
+    await program.parseAsync([
+      "node",
+      "hq",
+      "secrets",
+      "sandbox",
+      "--company",
+      "acme",
+      "--only",
+      "API_KEY,OTHER_KEY",
+      "--only",
+      "THIRD_KEY",
+      "--",
+      "env",
+    ]);
+
+    expect(startJobSpy).toHaveBeenCalledWith("test-token", {
+      companyUid: "prs_alice",
+      secretNames: ["API_KEY", "OTHER_KEY", "THIRD_KEY"],
+      command: "env",
+    });
+  });
+
   it("requires --only", async () => {
     const program = buildProgram();
 

package/src/commands/secrets.ts

@@ -338,7 +338,7 @@ function parseAuthStyle(authStyle: string): SecretInjectionRecipe | null {
 // (src/vault-service/handlers/secrets.ts) so a malformed URL is caught
 // locally with an actionable message rather than a round trip — the server
 // re-validates and remains authoritative.
-function parseDestinationUrl(
+export function parseDestinationUrl(
   raw: string,
 ): { ok: true; url: string; hostname: string } | { ok: false } {
   let parsed: URL;
@@ -362,6 +362,17 @@ function parseDestinationUrl(
     );
     return { ok: false };
   }
+  // Reject an embedded `user:pass@host` credential segment explicitly rather
+  // than letting `new URL()` silently drop it (mirrors hq-pro's authoritative
+  // `validateDestinations`; the server re-validates and remains authoritative).
+  if (parsed.username !== "" || parsed.password !== "") {
+    console.error(
+      chalk.red(
+        `Invalid --destination '${raw}': must not contain embedded userinfo (user:pass@) credentials`,
+      ),
+    );
+    return { ok: false };
+  }
   if (
     (parsed.pathname !== "" && parsed.pathname !== "/") ||
     parsed.search !== "" ||
@@ -427,8 +438,17 @@ async function buildSecretUsage(
   };
 }
 
-function parseSecretNameList(input: string): string[] {
-  const keys = input.split(",").map((k) => k.trim()).filter(Boolean);
+// Commander collector for `--only`: accumulates across REPEATED flags instead
+// of the last one silently winning, and each value may still be
+// comma-separated. So `--only A,B`, `--only A --only B`, and
+// `--only A,B --only C` all resolve to the full list.
+export function collectSecretNames(value: string, previous?: string[]): string[] {
+  const parsed = value.split(",").map((k) => k.trim()).filter(Boolean);
+  return (previous ?? []).concat(parsed);
+}
+
+function parseSecretNameList(input: string[] | undefined): string[] {
+  const keys = input ?? [];
   if (keys.length === 0) {
     console.error(chalk.red("Error: --only requires at least one secret name."));
     process.exit(1);
@@ -1447,11 +1467,11 @@ export function registerSecretsCommand(program: Command): void {
       "--personal",
       "Operate on the caller's personal vault (no sharing)",
     )
-    .option("--only <keys>", "Comma-separated list of secret names to inject (required)")
+    .option("--only <keys>", "Secret names to inject (comma-separated; may be repeated) (required)", collectSecretNames)
     .allowUnknownOption(true)
-    .action(async (opts: { company?: string; personal?: boolean; only?: string }, cmd: Command) => {
+    .action(async (opts: { company?: string; personal?: boolean; only?: string[] }, cmd: Command) => {
       try {
-        if (!opts.only || opts.only.trim().length === 0) {
+        if (!opts.only || opts.only.length === 0) {
           console.error(chalk.red("Error: --only is required and must name at least one secret."));
           process.exit(1);
         }
@@ -1501,10 +1521,10 @@ export function registerSecretsCommand(program: Command): void {
   secrets
     .command("exec")
     .description("Run a command with secrets injected as env vars")
-    .requiredOption("--only <keys>", "Comma-separated list of secret names to inject (required)")
+    .requiredOption("--only <keys>", "Secret names to inject (comma-separated; may be repeated) (required)", collectSecretNames)
     .option("--script <path>", "Attach local script identity for script-locked secrets")
     .allowUnknownOption(true)
-    .action(async (_opts: { only: string; script?: string }, cmd: Command) => {
+    .action(async (_opts: { only: string[]; script?: string }, cmd: Command) => {
       try {
         const rawArgs = cmd.args;
         const dashIndex = process.argv.indexOf("--");
@@ -1575,9 +1595,9 @@ export function registerSecretsCommand(program: Command): void {
   secrets
     .command("env")
     .description("Print 'export KEY=VALUE' lines suitable for: source <(hq secrets env --only K1,K2)")
-    .requiredOption("--only <keys>", "Comma-separated list of secret names to print (required)")
+    .requiredOption("--only <keys>", "Secret names to print (comma-separated; may be repeated) (required)", collectSecretNames)
     .option("--script <path>", "Attach local script identity for script-locked secrets")
-    .action(async (opts: { only: string; script?: string }) => {
+    .action(async (opts: { only: string[]; script?: string }) => {
       try {
         const redact = process.stdout.isTTY;
         if (redact) {