@indigoai-us/hq-cli 5.68.2 → 5.70.0

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({

package/src/utils/cli-telemetry.test.ts

@@ -0,0 +1,153 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Each case does vi.resetModules() + a dynamic import() to reset the module-scoped
+// once-per-process memoization; the cold transform/import is slow, so raise the
+// per-test timeout well above the default 5s.
+vi.setConfig({ testTimeout: 30_000 });
+
+const mocks = vi.hoisted(() => ({
+  browserLogin: vi.fn(),
+  isExpiring: vi.fn(),
+  isMachineIdentity: vi.fn(),
+  loadCachedTokens: vi.fn(),
+  refreshTokens: vi.fn(),
+  vaultApiFetch: vi.fn(),
+}));
+
+vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@indigoai-us/hq-cloud")>();
+  return { ...actual, ...mocks };
+});
+
+vi.mock("./vault-api.js", () => ({
+  vaultApiFetch: mocks.vaultApiFetch,
+}));
+
+vi.mock("../cli-version.js", () => ({
+  CLI_NAME: "@indigoai-us/hq-cli",
+  CLI_VERSION: "5.68.1",
+}));
+
+const HUMAN_TOKENS = {
+  accessToken: "human-access-token",
+  idToken: "human-id-token",
+  refreshToken: "human-refresh-token",
+  expiresAt: Date.now() + 3_600_000,
+  tokenType: "Bearer" as const,
+};
+
+const MACHINE_TOKENS = {
+  ...HUMAN_TOKENS,
+  accessToken: "machine-access-token",
+  idToken: "machine-id-token",
+};
+
+async function loadEmitter() {
+  vi.resetModules();
+  return import("./cli-telemetry.js");
+}
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  mocks.isMachineIdentity.mockReturnValue(false);
+  mocks.isExpiring.mockReturnValue(false);
+  mocks.vaultApiFetch.mockResolvedValue(new Response(null, { status: 202 }));
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("emitCliSessionStarted", () => {
+  it("posts the privacy-safe event with a valid cached human token", async () => {
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    await emitCliSessionStarted();
+
+    expect(mocks.vaultApiFetch).toHaveBeenCalledTimes(1);
+    const request = mocks.vaultApiFetch.mock.calls[0]?.[0];
+    expect(request).toMatchObject({
+      token: HUMAN_TOKENS.accessToken,
+      path: "/v1/telemetry/events",
+      method: "POST",
+      signal: expect.any(AbortSignal),
+    });
+    expect(request.body.events).toHaveLength(1);
+    expect(request.body.events[0]).toEqual({
+      eventName: "cli_session_started",
+      app: "hq-cli",
+      source: "cli",
+      occurredAt: expect.any(String),
+      schemaVersion: 1,
+      properties: { version: "5.68.1" },
+    });
+  });
+
+  it("uses the cached ID token for a machine identity", async () => {
+    mocks.isMachineIdentity.mockReturnValue(true);
+    mocks.loadCachedTokens.mockReturnValue(MACHINE_TOKENS);
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    await emitCliSessionStarted();
+
+    expect(mocks.vaultApiFetch).toHaveBeenCalledWith(
+      expect.objectContaining({ token: MACHINE_TOKENS.idToken }),
+    );
+  });
+
+  it.each([
+    ["is absent", null, false],
+    ["is expiring", HUMAN_TOKENS, true],
+  ])(
+    "does not emit or refresh/login when the cached token %s",
+    async (_description, cachedTokens, expiring) => {
+      mocks.loadCachedTokens.mockReturnValue(cachedTokens);
+      mocks.isExpiring.mockReturnValue(expiring);
+      const { emitCliSessionStarted } = await loadEmitter();
+
+      await emitCliSessionStarted();
+
+      expect(mocks.vaultApiFetch).not.toHaveBeenCalled();
+      expect(mocks.refreshTokens).not.toHaveBeenCalled();
+      expect(mocks.browserLogin).not.toHaveBeenCalled();
+    },
+  );
+
+  it("swallows a non-2xx telemetry response", async () => {
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.vaultApiFetch.mockResolvedValue(new Response(null, { status: 503 }));
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    await expect(emitCliSessionStarted()).resolves.toBeUndefined();
+  });
+
+  it("aborts a slow telemetry request without failing the command", async () => {
+    vi.useFakeTimers();
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    mocks.vaultApiFetch.mockImplementation(
+      ({ signal }: { signal: AbortSignal }) =>
+        new Promise((_resolve, reject) => {
+          signal.addEventListener("abort", () => reject(new Error("aborted")), {
+            once: true,
+          });
+        }),
+    );
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    const emission = emitCliSessionStarted();
+    await vi.advanceTimersByTimeAsync(1_200);
+
+    await expect(emission).resolves.toBeUndefined();
+    expect(mocks.vaultApiFetch.mock.calls[0]?.[0].signal.aborted).toBe(true);
+  });
+
+  it("posts at most once when the root hook is invoked repeatedly", async () => {
+    mocks.loadCachedTokens.mockReturnValue(HUMAN_TOKENS);
+    const { emitCliSessionStarted } = await loadEmitter();
+
+    await Promise.all([emitCliSessionStarted(), emitCliSessionStarted()]);
+
+    expect(mocks.vaultApiFetch).toHaveBeenCalledTimes(1);
+  });
+});

package/src/utils/cli-telemetry.ts

@@ -0,0 +1,61 @@
+import { CLI_VERSION } from "../cli-version.js";
+import {
+  isExpiring,
+  isMachineIdentity,
+  loadCachedTokens,
+} from "./cognito-session.js";
+import { vaultApiFetch } from "./vault-api.js";
+
+const TELEMETRY_TIMEOUT_MS = 1_200;
+
+let cliSessionStartedPromise: Promise<void> | undefined;
+
+/**
+ * Emit the authenticated CLI session signal using an already-cached token.
+ * This deliberately never refreshes a session or opens a browser.
+ */
+export function emitCliSessionStarted(): Promise<void> {
+  cliSessionStartedPromise ??= emitCachedCliSessionStarted();
+  return cliSessionStartedPromise;
+}
+
+async function emitCachedCliSessionStarted(): Promise<void> {
+  try {
+    const cached = loadCachedTokens();
+    if (!cached || isExpiring(cached, 120)) return;
+
+    const token = isMachineIdentity() ? cached.idToken : cached.accessToken;
+    if (!token) return;
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+
+    try {
+      const response = await vaultApiFetch({
+        token,
+        path: "/v1/telemetry/events",
+        method: "POST",
+        body: {
+          events: [
+            {
+              eventName: "cli_session_started",
+              app: "hq-cli",
+              source: "cli",
+              occurredAt: new Date().toISOString(),
+              schemaVersion: 1,
+              properties: { version: CLI_VERSION },
+            },
+          ],
+        },
+        signal: controller.signal,
+      });
+      if (!response.ok) return;
+    } catch {
+      // Telemetry is best effort and must never affect a CLI command.
+    } finally {
+      clearTimeout(timeout);
+    }
+  } catch {
+    // Cached-token reads are also best effort (for example, a malformed cache).
+  }
+}

package/src/utils/cognito-session.ts

@@ -38,6 +38,10 @@ import {
 } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 
+// Re-export the cached-session primitives for callers that must deliberately
+// avoid the refresh/login behavior in the higher-level helpers below.
+export { isExpiring, isMachineIdentity, loadCachedTokens };
+
 export const DEFAULT_COGNITO: CognitoAuthConfig = {
   region: process.env.AWS_REGION ?? "us-east-1",
   userPoolDomain: process.env.HQ_COGNITO_DOMAIN ?? "vault-indigo-hq-prod",

package/src/utils/vault-api.test.ts

@@ -229,3 +229,21 @@ describe('vaultApiFetch breadcrumb URL sanitization', () => {
     expect(errorCrumb.data?.url).toContain('?<redacted>');
   });
 });
+
+describe('vaultApiFetch abort signals', () => {
+  it('passes an optional abort signal to fetch', async () => {
+    fetchMock.mockResolvedValueOnce(mockResponse(200, {}));
+    const controller = new AbortController();
+
+    await vaultApiFetch({
+      token: 'tok',
+      path: '/v1/telemetry/events',
+      signal: controller.signal,
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({ signal: controller.signal }),
+    );
+  });
+});

package/src/utils/vault-api.ts

@@ -7,6 +7,7 @@ export interface VaultApiOptions {
   method?: string;
   body?: Record<string, unknown>;
   query?: Record<string, string>;
+  signal?: AbortSignal;
 }
 
 export async function vaultApiFetch(opts: VaultApiOptions): Promise<Response> {
@@ -31,6 +32,7 @@ export async function vaultApiFetch(opts: VaultApiOptions): Promise<Response> {
       'Content-Type': 'application/json',
     },
     body: opts.body ? JSON.stringify(opts.body) : undefined,
+    signal: opts.signal,
   });
   if (!response.ok) {
     Sentry.addBreadcrumb({