@indigoai-us/hq-cli 5.68.1 → 5.69.0

package/src/commands/outposts-self-deploy.test.ts

@@ -0,0 +1,243 @@
+import { Command } from "commander";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+import {
+  registerOutpostsCommand,
+  type SelfDeployDependencies,
+} from "./outposts.js";
+
+type SpawnCall = {
+  command: string;
+  args: string[];
+  options: Parameters<SelfDeployDependencies["spawnSync"]>[2];
+};
+
+const AL2023 = 'ID="amzn"\nVERSION_ID="2023"\n';
+const SECRET = "refresh-token-that-must-never-be-printed";
+
+function successfulSpawn(stdout = "") {
+  return {
+    status: 0,
+    stdout,
+    stderr: "",
+    error: undefined,
+  } as ReturnType<SelfDeployDependencies["spawnSync"]>;
+}
+
+function selfDeployDependencies(input: {
+  osRelease?: string;
+  uname?: string;
+  systemd?: boolean;
+  sudo?: boolean;
+  session?: { refreshToken?: string; idToken?: string } | undefined;
+  stdinTty?: boolean;
+  uid?: number;
+} = {}): { deps: Partial<SelfDeployDependencies>; calls: SpawnCall[] } {
+  const calls: SpawnCall[] = [];
+  const deps: Partial<SelfDeployDependencies> = {
+    readTextFile: () => input.osRelease ?? AL2023,
+    loadCachedTokens: () => input.session ?? { refreshToken: SECRET },
+    getUid: () => input.uid ?? 1000,
+    isStdinTty: () => input.stdinTty ?? true,
+    confirm: async () => true,
+    defaultHqRoot: () => "/home/ec2-user/hq",
+    invokingUser: () => "ec2-user",
+    spawnSync: ((command, args, options) => {
+      calls.push({ command, args, options });
+      if (command === "uname") return successfulSpawn(input.uname ?? "x86_64\n");
+      if (command === "systemctl" && args[0] === "--version") {
+        return input.systemd === false
+          ? { ...successfulSpawn(), status: 1 }
+          : successfulSpawn("systemd 252\n");
+      }
+      if (command === "sudo" && args[0] === "-n") {
+        return input.sudo === false ? { ...successfulSpawn(), status: 1 } : successfulSpawn();
+      }
+      return successfulSpawn();
+    }) as SelfDeployDependencies["spawnSync"],
+  };
+  return { deps, calls };
+}
+
+function buildProgram(deps: Partial<SelfDeployDependencies>): Command {
+  const program = new Command();
+  program.name("hq").exitOverride();
+  registerOutpostsCommand(program, deps);
+  return program;
+}
+
+async function run(
+  deps: Partial<SelfDeployDependencies>,
+  args: string[],
+): Promise<void> {
+  await buildProgram(deps).parseAsync(["node", "hq", ...args]);
+}
+
+let exitSpy: MockInstance<typeof process.exit>;
+let logSpy: MockInstance<typeof console.log>;
+let errorSpy: MockInstance<typeof console.error>;
+let fetchSpy: MockInstance<typeof fetch>;
+
+beforeEach(() => {
+  exitSpy = vi.spyOn(process, "exit").mockImplementation((code?: number) => {
+    throw new Error(`process.exit(${code})`);
+  }) as unknown as MockInstance<typeof process.exit>;
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function printed(): string {
+  return [
+    ...logSpy.mock.calls.map((call) => call.map(String).join(" ")),
+    ...errorSpy.mock.calls.map((call) => call.map(String).join(" ")),
+  ].join("\n");
+}
+
+function installedCommands(calls: SpawnCall[]): SpawnCall[] {
+  return calls.filter(
+    (call) =>
+      call.command === "hq" ||
+      (call.command === "sudo" &&
+        ["tee", "chmod", "systemctl"].includes(call.args[0] ?? "")),
+  );
+}
+
+describe("hq outposts self-deploy", () => {
+  it("is hidden from outposts help but remains invokable", async () => {
+    const { deps, calls } = selfDeployDependencies();
+    const program = buildProgram(deps);
+    const outposts = program.commands.find((command) => command.name() === "outposts");
+
+    expect(outposts?.helpInformation()).not.toContain("self-deploy");
+
+    await run(deps, ["outposts", "self-deploy", "--yes"]);
+    expect(calls).toContainEqual(
+      expect.objectContaining({
+        command: "hq",
+        args: ["rescue", "--hq-root", "/home/ec2-user/hq", "--yes"],
+      }),
+    );
+  });
+
+  it("rejects non-Amazon Linux 2023 before installing anything", async () => {
+    const { deps, calls } = selfDeployDependencies({
+      osRelease: 'ID="ubuntu"\nVERSION_ID="24.04"\n',
+    });
+
+    await expect(run(deps, ["outposts", "self-deploy", "--yes"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+    expect(printed()).toContain("Amazon Linux 2023 x86_64");
+    expect(installedCommands(calls)).toEqual([]);
+  });
+
+  it("rejects a host without systemd before installing anything", async () => {
+    const { deps, calls } = selfDeployDependencies({ systemd: false });
+
+    await expect(run(deps, ["outposts", "self-deploy", "--yes"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+    expect(printed()).toContain("systemd is required");
+    expect(installedCommands(calls)).toEqual([]);
+  });
+
+  it("requires an existing hq login before installing anything", async () => {
+    const { deps, calls } = selfDeployDependencies({ session: undefined });
+    deps.loadCachedTokens = () => undefined;
+
+    await expect(run(deps, ["outposts", "self-deploy", "--yes"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+    expect(printed()).toContain("hq login");
+    expect(installedCommands(calls)).toEqual([]);
+  });
+
+  it("aborts without a TTY or --yes before running install commands", async () => {
+    const idToken = `header.${Buffer.from(JSON.stringify({ email: "person@example.com" })).toString("base64url")}.signature`;
+    const { deps, calls } = selfDeployDependencies({
+      stdinTty: false,
+      session: { refreshToken: SECRET, idToken },
+    });
+
+    await expect(run(deps, ["outposts", "self-deploy"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+    expect(printed()).toContain("HQ identity: person@example.com");
+    expect(printed()).toContain("SELF-HOSTED HQ outpost");
+    expect(printed()).toMatch(/pass --yes/i);
+    expect(installedCommands(calls)).toEqual([]);
+  });
+
+  it("installs the all-company watch sync service locally with --yes", async () => {
+    const { deps, calls } = selfDeployDependencies();
+
+    await run(deps, ["outposts", "self-deploy", "--yes"]);
+
+    expect(calls).toContainEqual(
+      expect.objectContaining({
+        command: "hq",
+        args: ["rescue", "--hq-root", "/home/ec2-user/hq", "--yes"],
+      }),
+    );
+    const serviceWrite = calls.find(
+      (call) =>
+        call.command === "sudo" &&
+        call.args[0] === "tee" &&
+        call.args[1] === "/etc/systemd/system/outpost-sync.service",
+    );
+    const serviceContents = String(
+      (serviceWrite?.options as { input?: unknown } | undefined)?.input,
+    );
+    expect(serviceContents).toContain("User=ec2-user");
+    expect(serviceContents).toContain("WorkingDirectory=\"/home/ec2-user/hq\"");
+    expect(serviceContents).toContain("ExecStart=/usr/local/bin/outpost-sync.sh");
+    expect(serviceContents).toContain("Restart=always");
+
+    const scriptWrite = calls.find(
+      (call) =>
+        call.command === "sudo" &&
+        call.args[0] === "tee" &&
+        call.args[1] === "/usr/local/bin/outpost-sync.sh",
+    );
+    const scriptContents = String(
+      (scriptWrite?.options as { input?: unknown } | undefined)?.input,
+    );
+    expect(scriptContents).toContain("hq auth refresh");
+    expect(scriptContents).toContain("hq-sync-runner");
+    expect(scriptContents).toContain("--companies");
+    expect(scriptContents).toContain("--watch");
+    expect(scriptContents).toContain("--event-push");
+    expect(scriptContents).toContain("--poll-remote-ms 60000");
+    expect(calls).toContainEqual(
+      expect.objectContaining({
+        command: "sudo",
+        args: ["systemctl", "enable", "--now", "outpost-sync.service"],
+      }),
+    );
+  });
+
+  it("never exposes session secrets or makes hq-pro requests", async () => {
+    const { deps, calls } = selfDeployDependencies({
+      session: { refreshToken: SECRET },
+    });
+
+    await run(deps, ["outposts", "self-deploy", "--yes"]);
+
+    expect(JSON.stringify(calls)).not.toContain(SECRET);
+    expect(printed()).not.toContain(SECRET);
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});

package/src/commands/outposts.ts

@@ -27,6 +27,7 @@ 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 * as readline from "node:readline";
 import { randomBytes } from "node:crypto";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -360,11 +361,355 @@ function printKeyValues(obj: Record<string, unknown>): void {
   }
 }
 
-export function registerOutpostsCommand(program: Command): void {
+// ---------------------------------------------------------------------------
+// Hidden local self-deploy command
+// ---------------------------------------------------------------------------
+
+/** The small local-environment surface used by `outposts self-deploy`. */
+export interface SelfDeployDependencies {
+  spawnSync: (
+    command: string,
+    args: string[],
+    options?: Parameters<typeof spawnSync>[2],
+  ) => ReturnType<typeof spawnSync>;
+  readTextFile: (file: string) => string;
+  loadCachedTokens: () =>
+    | { refreshToken?: string; idToken?: string }
+    | undefined;
+  getUid: () => number | undefined;
+  isStdinTty: () => boolean;
+  confirm: () => Promise<boolean>;
+  defaultHqRoot: () => string;
+  invokingUser: () => string;
+}
+
+const defaultSelfDeployDependencies: SelfDeployDependencies = {
+  spawnSync: (command, args, options) => spawnSync(command, args, options),
+  readTextFile: (file) => fs.readFileSync(file, "utf8"),
+  loadCachedTokens: () => loadCachedTokens() ?? undefined,
+  getUid: () => process.getuid?.(),
+  isStdinTty: () => process.stdin.isTTY === true,
+  confirm: async () => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    return new Promise((resolve) => {
+      rl.question("", (answer) => {
+        rl.close();
+        resolve(/^y(es)?$/i.test(answer.trim()));
+      });
+    });
+  },
+  defaultHqRoot: () => process.env.HQ_ROOT ?? path.join(os.homedir(), "hq"),
+  invokingUser: () =>
+    process.env.SUDO_USER ?? process.env.USER ?? os.userInfo().username,
+};
+
+function selfDeployError(message: string): Error {
+  return new Error(`Self-deploy preflight failed: ${message}`);
+}
+
+function commandSucceeded(
+  deps: SelfDeployDependencies,
+  command: string,
+  args: string[],
+): boolean {
+  try {
+    const result = deps.spawnSync(command, args, { encoding: "utf8" });
+    return !!result && !result.error && result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function commandOutput(
+  deps: SelfDeployDependencies,
+  command: string,
+  args: string[],
+): string | undefined {
+  try {
+    const result = deps.spawnSync(command, args, { encoding: "utf8" });
+    if (!result || result.error || result.status !== 0) return undefined;
+    return String(result.stdout ?? "").trim();
+  } catch {
+    return undefined;
+  }
+}
+
+function parseOsRelease(source: string): Map<string, string> {
+  const values = new Map<string, string>();
+  for (const line of source.split("\n")) {
+    const match = /^([A-Z_]+)=(.*)$/.exec(line);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    values.set(key, rawValue.replace(/^['"]|['"]$/g, ""));
+  }
+  return values;
+}
+
+function hqIdentityFromSession(session: {
+  refreshToken?: string;
+  idToken?: string;
+}): string {
+  if (!session.idToken) return "your cached HQ session";
+  try {
+    const payload = session.idToken.split(".")[1];
+    if (!payload) return "your cached HQ session";
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as Record<
+      string,
+      unknown
+    >;
+    for (const key of [
+      "email",
+      "preferred_username",
+      "cognito:username",
+      "username",
+      "sub",
+    ]) {
+      const value = claims[key];
+      if (typeof value === "string" && value) return value;
+    }
+  } catch {
+    // A cache that has a refresh token remains valid for this local setup. The
+    // identity banner is informational, so never expose a token parse failure.
+  }
+  return "your cached HQ session";
+}
+
+function bashSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function systemdQuoted(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function renderSelfDeploySyncScript(hqRoot: string): string {
+  return `#!/usr/bin/env bash
+set -u
+# Persistent all-membership sync for a locally self-hosted HQ outpost. The
+# watch runner event-pushes local changes and polls remote changes every minute.
+HQ_ROOT=${bashSingleQuote(hqRoot)}
+cd "$HQ_ROOT"
+while true; do
+  hq auth refresh || echo "[outpost-sync] auth refresh failed, continuing"
+  npx -y --package=@indigoai-us/hq-cloud@latest hq-sync-runner \\
+    --companies \\
+    --direction both \\
+    --on-conflict keep \\
+    --hq-root "$HQ_ROOT" \\
+    --watch \\
+    --event-push \\
+    --poll-remote-ms 60000
+  echo "[outpost-sync] watch runner exited; restarting in 10 seconds"
+  sleep 10
+done
+`;
+}
+
+function renderSelfDeployService(hqRoot: string, user: string): string {
+  return `[Unit]
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=${user}
+WorkingDirectory=${systemdQuoted(hqRoot)}
+ExecStart=/usr/local/bin/outpost-sync.sh
+Restart=always
+RestartSec=10s
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+function runChecked(
+  deps: SelfDeployDependencies,
+  command: string,
+  args: string[],
+  description: string,
+  options?: Parameters<typeof spawnSync>[2],
+): void {
+  let result: ReturnType<typeof spawnSync>;
+  try {
+    result = deps.spawnSync(command, args, options);
+  } catch {
+    throw new Error(`${description} could not be started.`);
+  }
+  if (!result || result.error || result.status !== 0) {
+    // Do not include child process output here: even though this command never
+    // passes credentials to children, it keeps the error path secret-safe.
+    throw new Error(`${description} failed. Resolve the error and try again.`);
+  }
+}
+
+function runPrivileged(
+  deps: SelfDeployDependencies,
+  command: string,
+  args: string[],
+  description: string,
+  options?: Parameters<typeof spawnSync>[2],
+): void {
+  if (deps.getUid() === 0) {
+    runChecked(deps, command, args, description, options);
+    return;
+  }
+  runChecked(deps, "sudo", [command, ...args], description, options);
+}
+
+function selfDeployPreflight(
+  deps: SelfDeployDependencies,
+): { refreshToken?: string; idToken?: string } {
+  let osRelease: string;
+  try {
+    osRelease = deps.readTextFile("/etc/os-release");
+  } catch {
+    throw selfDeployError(
+      "could not read /etc/os-release. This command only supports Amazon Linux 2023 x86_64.",
+    );
+  }
+  const release = parseOsRelease(osRelease);
+  if (
+    release.get("ID") !== "amzn" ||
+    !release.get("VERSION_ID")?.startsWith("2023")
+  ) {
+    throw selfDeployError(
+      "this command only supports Amazon Linux 2023 x86_64. Use an Amazon Linux 2023 EC2 instance.",
+    );
+  }
+
+  const architecture = commandOutput(deps, "uname", ["-m"]);
+  if (architecture !== "x86_64") {
+    throw selfDeployError(
+      "this command only supports x86_64 EC2 instances. Use an Amazon Linux 2023 x86_64 instance.",
+    );
+  }
+
+  if (!commandSucceeded(deps, "systemctl", ["--version"])) {
+    throw selfDeployError(
+      "systemd is required but `systemctl --version` failed. Run this on an Amazon Linux 2023 EC2 host with systemd.",
+    );
+  }
+
+  if (deps.getUid() !== 0 && !commandSucceeded(deps, "sudo", ["-n", "true"])) {
+    throw selfDeployError(
+      "root or passwordless sudo is required. Configure passwordless sudo or run this command as root.",
+    );
+  }
+
+  const session = deps.loadCachedTokens();
+  if (!session?.refreshToken) {
+    throw selfDeployError("no HQ login session was found. Run `hq login`, then re-run this command.");
+  }
+  return session;
+}
+
+async function selfDeployOutpost(
+  opts: { yes?: boolean; hqRoot?: string },
+  deps: SelfDeployDependencies,
+): Promise<void> {
+  const session = selfDeployPreflight(deps);
+  const hqRoot = opts.hqRoot ?? deps.defaultHqRoot();
+  const user = deps.invokingUser();
+
+  if (!opts.yes) {
+    console.log(`HQ identity: ${hqIdentityFromSession(session)}`);
+    console.log(
+      chalk.yellow(
+        "This machine will run as a SELF-HOSTED HQ outpost under YOUR identity, continuously syncing ALL your company vaults. " +
+          "It is NOT registered with or managed by hq-pro (no console entry, no remote management, no metering). " +
+          "Anyone with root on this box can act as you. Continue? [y/N]",
+      ),
+    );
+    if (!deps.isStdinTty()) {
+      throw new Error("Confirmation requires a TTY. Pass --yes to continue non-interactively.");
+    }
+    if (!(await deps.confirm())) {
+      throw new Error("Self-deploy cancelled.");
+    }
+  }
+
+  runChecked(
+    deps,
+    "hq",
+    ["rescue", "--hq-root", hqRoot, "--yes"],
+    "HQ kernel rescue",
+    { stdio: "inherit" },
+  );
+
+  runPrivileged(
+    deps,
+    "tee",
+    ["/usr/local/bin/outpost-sync.sh"],
+    "Writing /usr/local/bin/outpost-sync.sh",
+    {
+      encoding: "utf8",
+      input: renderSelfDeploySyncScript(hqRoot),
+      stdio: ["pipe", "ignore", "pipe"],
+    },
+  );
+  runPrivileged(
+    deps,
+    "chmod",
+    ["+x", "/usr/local/bin/outpost-sync.sh"],
+    "Making /usr/local/bin/outpost-sync.sh executable",
+  );
+  runPrivileged(
+    deps,
+    "tee",
+    ["/etc/systemd/system/outpost-sync.service"],
+    "Writing /etc/systemd/system/outpost-sync.service",
+    {
+      encoding: "utf8",
+      input: renderSelfDeployService(hqRoot, user),
+      stdio: ["pipe", "ignore", "pipe"],
+    },
+  );
+  runPrivileged(
+    deps,
+    "systemctl",
+    ["daemon-reload"],
+    "Reloading systemd",
+  );
+  runPrivileged(
+    deps,
+    "systemctl",
+    ["enable", "--now", "outpost-sync.service"],
+    "Enabling outpost-sync.service",
+  );
+
+  console.log(chalk.green("This box is now a self-hosted HQ outpost and will sync all your company vaults continuously."));
+  console.log(chalk.dim("Check it with: systemctl status outpost-sync.service"));
+  console.log(chalk.dim("It is unregistered and unmanaged by hq-pro (no console entry or remote management)."));
+}
+
+export function registerOutpostsCommand(
+  program: Command,
+  selfDeployOverrides: Partial<SelfDeployDependencies> = {},
+): void {
+  const selfDeployDependencies: SelfDeployDependencies = {
+    ...defaultSelfDeployDependencies,
+    ...selfDeployOverrides,
+  };
   const outposts = program
     .command("outposts")
     .description("Manage your personal HQ Outposts (EC2 boxes)");
 
+  outposts
+    .command("self-deploy", { hidden: true })
+    .description("Configure this EC2 host as a locally self-hosted HQ outpost")
+    .option("--yes", "Skip the self-hosting confirmation")
+    .option("--hq-root <path>", "HQ root to sync", selfDeployDependencies.defaultHqRoot())
+    .action(async (opts: { yes?: boolean; hqRoot?: string }) => {
+      try {
+        await selfDeployOutpost(opts, selfDeployDependencies);
+      } catch (err) {
+        fail(err);
+      }
+    });
+
   outposts
     .command("provision")
     .alias("create")

package/src/main.ts

@@ -71,6 +71,7 @@ import {
   shouldSkipGate,
 } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
+import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
 
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
 // the pipe early. This covers the ASYNC path — an 'error' event emitted on the
@@ -264,6 +265,10 @@ registerOutpostsCommand(program);
 // provisioning gate for agents & Outposts.
 registerBillingCommand(program);
 
+program.hook("preAction", async () => {
+  await emitCliSessionStarted();
+});
+
 export async function runCli(): Promise<void> {
   try {
     Sentry.addBreadcrumb({