@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/onboard.ts

@@ -1,267 +0,0 @@
-/**
- * `hq onboard` — bootstrap an HQ vault: sign in to Cognito + provision
- * the company entity, S3 bucket, KMS key, owner membership, and STS-vended
- * credentials in one flow.
- *
- * This is the "the entire flow" entry point that VLT-9 was building toward:
- * a real user can install hq-cli and run `hq onboard create-company` once
- * to land in a fully provisioned vault, then use `hq sync push|pull` to
- * round-trip files against S3.
- *
- * Subcommands:
- *   hq onboard create-company  — provision a brand new company
- *   hq onboard join            — accept an invite from another user
- *   hq onboard resume          — resume a partially-completed flow from checkpoint
- *   hq onboard dry-run         — show what create-company would do, without doing it
- *
- * Auth: we cache the Cognito access + refresh tokens at ~/.hq/cognito-tokens.json.
- * If the cached token is missing or expired beyond the refresh window, the
- * browser-OAuth flow opens automatically.
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-
-import { runOnboardCli, readCheckpoint } from "@indigoai-us/hq-onboarding";
-import {
-  DEFAULT_HQ_ROOT,
-  DEFAULT_VAULT_API_URL,
-  ensureCognitoToken,
-  buildVaultConfig,
-} from "../utils/cognito-session.js";
-import { createDefaultVaultClient } from "./cloud-provision.js";
-import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
-import { planOnboardJoin } from "./onboard-join.js";
-import { buildCreateCompanyWarning } from "./onboard-warning.js";
-
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-
-export function registerOnboardCommand(program: Command): void {
-  const onboard = program
-    .command("onboard")
-    .description("Provision an HQ vault: sign in, create company, S3 bucket, STS, sync");
-
-  onboard
-    .command("create-company")
-    .description(
-      "Sign in and provision a brand NEW HQ vault for a company. To join a " +
-        "teammate's EXISTING company instead, use `hq onboard join` — creating " +
-        "a same-named company makes a separate one you'd be alone in.",
-    )
-    .requiredOption("--slug <slug>", "Company slug (used as bucket name suffix)")
-    .requiredOption("--name <name>", "Company display name")
-    .requiredOption("--email <email>", "Your email (must match Cognito sign-in)")
-    .requiredOption("--person-name <name>", "Your display name")
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .action(async (options: {
-      slug: string;
-      name: string;
-      email: string;
-      personName: string;
-      hqRoot: string;
-    }) => {
-      try {
-        console.log(chalk.bold(`\nHQ Onboard — Create Company`));
-        console.log(`  Company:  ${options.name} (${options.slug})`);
-        console.log(`  Person:   ${options.personName} <${options.email}>`);
-        console.log(`  HQ root:  ${options.hqRoot}\n`);
-        console.log(chalk.gray(buildCreateCompanyWarning()));
-
-        const accessToken = await ensureCognitoToken();
-        const result = await runOnboardCli({
-          mode: "create-company",
-          personName: options.personName,
-          personEmail: options.email,
-          companyName: options.name,
-          companySlug: options.slug,
-          vaultConfig: buildVaultConfig(accessToken),
-          hqRoot: options.hqRoot,
-        });
-
-        if (!result.success) {
-          console.error(chalk.red(`\n✗ Onboarding failed: ${result.error}`));
-          process.exit(1);
-        }
-      } catch (err) {
-        console.error(
-          chalk.red("\n✗ Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  onboard
-    .command("join")
-    .description("Accept an invite and join an existing company")
-    // Modern invites are tokenless (email-keyed); the token, email, and
-    // person-name are required ONLY on the legacy redeem path. Declaring them
-    // as plain options (not requiredOption) lets a tokenless invitee reach the
-    // action and be routed to `hq sync` instead of hitting a commander
-    // "required option not specified" wall that reads as "I have no token".
-    .option("--invite-token <token>", "Legacy magic-link token (modern invites don't need one)")
-    .option("--email <email>", "Your email (legacy token join only; must match Cognito sign-in)")
-    .option("--person-name <name>", "Your display name (legacy token join only)")
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .action(async (options: {
-      inviteToken?: string;
-      email?: string;
-      personName?: string;
-      hqRoot: string;
-    }) => {
-      try {
-        console.log(chalk.bold(`\nHQ Onboard — Join Company`));
-
-        const plan = planOnboardJoin({
-          inviteToken: options.inviteToken,
-          email: options.email,
-          personName: options.personName,
-        });
-
-        if (plan.kind === "tokenless") {
-          console.log(`\n${plan.guidance}\n`);
-          return;
-        }
-
-        if (plan.kind === "error") {
-          console.error(chalk.red(`\n✗ ${plan.message}`));
-          process.exit(1);
-        }
-
-        console.log(`  Person:   ${plan.personName} <${plan.email}>`);
-        console.log(`  HQ root:  ${options.hqRoot}\n`);
-
-        const accessToken = await ensureCognitoToken();
-        const result = await runOnboardCli({
-          mode: "join-company",
-          personName: plan.personName,
-          personEmail: plan.email,
-          inviteToken: plan.inviteToken,
-          vaultConfig: buildVaultConfig(accessToken),
-          hqRoot: options.hqRoot,
-        });
-
-        if (!result.success) {
-          console.error(chalk.red(`\n✗ Join failed: ${result.error}`));
-          process.exit(1);
-        }
-      } catch (err) {
-        console.error(
-          chalk.red("\n✗ Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  onboard
-    .command("resume")
-    .description("Resume a partially-completed onboarding flow from local checkpoint")
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .action(async (options: { hqRoot: string }) => {
-      try {
-        const accessToken = await ensureCognitoToken();
-
-        // Identity-link pre-flight (DEV-1695 / DEV-1701 / DEV-1721): if the
-        // saved checkpoint adopted a person entity owned by a DIFFERENT Cognito
-        // sign-in than the current one, resume would skip the completed
-        // create-person step with that stale personUid and re-fail at
-        // bootstrap-membership forever. Detect it up front and surface a
-        // recoverable, actionable error instead of looping.
-        const checkpoint = await readCheckpoint(options.hqRoot);
-        if (checkpoint?.personUid) {
-          let ownedPersonUids: string[] | null = null;
-          try {
-            const client = createDefaultVaultClient(
-              DEFAULT_VAULT_API_URL,
-              accessToken,
-            );
-            const owned = await client.listMyPersonEntities();
-            ownedPersonUids = owned.map((p) => p.uid);
-          } catch (err) {
-            // Best-effort guard: if the pre-flight lookup itself fails (network,
-            // auth), don't block resume — but don't swallow it silently either.
-            console.warn(
-              chalk.yellow(
-                `  (skipping identity pre-flight check: ${
-                  err instanceof Error ? err.message : String(err)
-                })`,
-              ),
-            );
-          }
-          if (ownedPersonUids) {
-            const check = detectOnboardingIdentityMismatch({
-              checkpoint,
-              ownedPersonUids,
-            });
-            if (check.kind === "mismatch") {
-              console.error(chalk.red(`\n✗ Resume blocked:\n\n${check.message}`));
-              process.exit(1);
-            }
-          }
-        }
-
-        const result = await runOnboardCli({
-          mode: "resume",
-          vaultConfig: buildVaultConfig(accessToken),
-          hqRoot: options.hqRoot,
-        });
-        if (!result.success) {
-          console.error(chalk.red(`\n✗ Resume failed: ${result.error}`));
-          process.exit(1);
-        }
-      } catch (err) {
-        console.error(
-          chalk.red("\n✗ Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  onboard
-    .command("dry-run")
-    .description("Show what create-company would do, without provisioning anything")
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .action(async (options: { hqRoot: string }) => {
-      try {
-        console.log(chalk.gray(buildCreateCompanyWarning()));
-
-        // No auth needed for dry-run — runOnboardCli handles this branch
-        // without touching the vault-service.
-        const result = await runOnboardCli({
-          mode: "dry-run",
-          vaultConfig: buildVaultConfig("dry-run-no-token"),
-          hqRoot: options.hqRoot,
-        });
-        if (!result.success) {
-          console.error(chalk.red(`\n✗ Dry-run failed: ${result.error}`));
-          process.exit(1);
-        }
-      } catch (err) {
-        console.error(
-          chalk.red("\n✗ Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-}

package/src/commands/outposts-heartbeat.test.ts

@@ -1,299 +0,0 @@
-/**
- * Unit tests for `hq outposts heartbeat` (outposts-heartbeat.ts).
- *
- * The loop runs ON the box under systemd, so the properties that matter are
- * operational, not cosmetic:
- *   - it ticks on a cadence and NEVER dies on a transient failure;
- *   - it resolves identity ONCE per process, not once per tick (the whole point
- *     of moving the cadence in-process — the old bash loop re-authenticated and
- *     re-resolved a package every 5s);
- *   - nothing leaves the box that fails the no-secrets contract.
- *
- * Everything the loop touches (clock, sleep, publish, identity, fs) is injected
- * so these run without a network, a real box, or real time.
- */
-
-import { describe, expect, it, vi } from "vitest";
-import {
-  resolveIntervalSeconds,
-  runHeartbeatLoop,
-  type HeartbeatLoopDeps,
-} from "./outposts-heartbeat.js";
-import type {
-  FileSystemPort,
-  SessionsHeartbeatPayload,
-} from "../outpost/session-heartbeat.js";
-
-const PERSON_UID = "prs_01TESTPERSON";
-
-/** An fs port with no sessions on disk — enumeration yields an empty payload. */
-const emptyFs: FileSystemPort = {
-  readDir: async () => [],
-  stat: async () => ({ mtimeMs: 0, birthtimeMs: 0, size: 0 }),
-  readTextFile: async () => "",
-  readBounded: async () => "",
-};
-
-function makeDeps(over: Partial<HeartbeatLoopDeps> = {}): {
-  deps: HeartbeatLoopDeps;
-  published: { topic: string; payload: SessionsHeartbeatPayload }[];
-  sleeps: number[];
-  logs: string[];
-  personUidCalls: () => number;
-} {
-  const published: { topic: string; payload: SessionsHeartbeatPayload }[] = [];
-  const sleeps: number[] = [];
-  const logs: string[] = [];
-  const getPersonUid = vi.fn(async () => PERSON_UID);
-
-  const deps: HeartbeatLoopDeps = {
-    fs: emptyFs,
-    publish: async (topic, payload) => {
-      published.push({ topic, payload });
-    },
-    getPersonUid,
-    sleep: async (ms: number) => {
-      sleeps.push(ms);
-    },
-    now: () => new Date("2026-07-29T00:00:00.000Z"),
-    log: (line: string) => logs.push(line),
-    ...over,
-  };
-
-  return {
-    deps,
-    published,
-    sleeps,
-    logs,
-    personUidCalls: () => getPersonUid.mock.calls.length,
-  };
-}
-
-describe("resolveIntervalSeconds", () => {
-  it("prefers the explicit flag over the environment", () => {
-    expect(
-      resolveIntervalSeconds("30", {
-        OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS: "9",
-      }),
-    ).toBe(30);
-  });
-
-  it("falls back to the environment when no flag is given", () => {
-    expect(
-      resolveIntervalSeconds(undefined, {
-        OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS: "9",
-      }),
-    ).toBe(9);
-  });
-
-  it("defaults to 5s when neither is set", () => {
-    expect(resolveIntervalSeconds(undefined, {})).toBe(5);
-  });
-
-  it("floors at 1s so a bad value cannot hammer the fabric", () => {
-    expect(resolveIntervalSeconds("0", {})).toBe(1);
-    expect(resolveIntervalSeconds("-4", {})).toBe(1);
-    expect(resolveIntervalSeconds("not-a-number", {})).toBe(5);
-  });
-});
-
-describe("runHeartbeatLoop", () => {
-  it("--once emits exactly one heartbeat and returns", async () => {
-    const { deps, published, sleeps } = makeDeps();
-
-    const ticks = await runHeartbeatLoop({ once: true }, deps);
-
-    expect(ticks).toBe(1);
-    expect(published).toHaveLength(1);
-    expect(published[0].topic).toBe(`hq/${PERSON_UID}/sessions`);
-    expect(published[0].payload.type).toBe("sessions");
-    expect(published[0].payload.origin).toBe("outpost");
-    // One-shot must not sleep — systemd/an operator owns the cadence there.
-    expect(sleeps).toEqual([]);
-  });
-
-  it("ticks repeatedly on the configured cadence, sleeping between ticks", async () => {
-    const { deps, published, sleeps } = makeDeps();
-
-    const ticks = await runHeartbeatLoop(
-      { intervalSeconds: 5, maxTicks: 3 },
-      deps,
-    );
-
-    expect(ticks).toBe(3);
-    expect(published).toHaveLength(3);
-    // N ticks ⇒ N-1 gaps. The loop must not sleep before exiting.
-    expect(sleeps).toEqual([5000, 5000]);
-  });
-
-  it("resolves identity ONCE per process, not once per tick", async () => {
-    // Regression guard for the original design: the bash loop re-ran
-    // `hq auth refresh` AND re-resolved an npm package on every single tick.
-    const { deps, personUidCalls } = makeDeps();
-
-    await runHeartbeatLoop({ intervalSeconds: 1, maxTicks: 10 }, deps);
-
-    expect(personUidCalls()).toBe(1);
-  });
-
-  it("survives a publish failure and keeps beating", async () => {
-    let attempt = 0;
-    const { deps, published, logs } = makeDeps({
-      publish: async (topic, payload) => {
-        attempt += 1;
-        if (attempt === 2) throw new Error("iot unavailable");
-        published.push({ topic, payload });
-      },
-    });
-
-    const ticks = await runHeartbeatLoop({ maxTicks: 3 }, deps);
-
-    expect(ticks).toBe(3);
-    // Ticks 1 and 3 landed; tick 2 failed without killing the loop.
-    expect(published).toHaveLength(2);
-    expect(logs.join("\n")).toContain("iot unavailable");
-  });
-
-  it("survives a collection failure and keeps beating", async () => {
-    let calls = 0;
-    const { deps, published, logs } = makeDeps({
-      fs: {
-        ...emptyFs,
-        readDir: async () => {
-          calls += 1;
-          if (calls === 1) throw new Error("EIO: disk unhappy");
-          return [];
-        },
-      },
-    });
-
-    const ticks = await runHeartbeatLoop({ maxTicks: 2 }, deps);
-
-    expect(ticks).toBe(2);
-    expect(published).toHaveLength(1);
-    expect(logs.join("\n")).toContain("disk unhappy");
-  });
-
-  it("keeps beating when identity cannot be resolved yet", async () => {
-    // A box that boots before its session is warm must retry, not exit — a
-    // crash here is what systemd Restart= masks into a silent flap.
-    let calls = 0;
-    const { deps, published } = makeDeps({
-      getPersonUid: async () => {
-        calls += 1;
-        if (calls === 1) throw new Error("no cached HQ session");
-        return PERSON_UID;
-      },
-    });
-
-    const ticks = await runHeartbeatLoop({ maxTicks: 2 }, deps);
-
-    expect(ticks).toBe(2);
-    expect(published).toHaveLength(1);
-  });
-
-  it("never publishes a payload that fails the no-secrets guard", async () => {
-    const { deps, published, logs } = makeDeps({
-      fs: {
-        ...emptyFs,
-        readDir: async (path: string) => {
-          // Only the Claude tree has anything in it; Codex enumeration must
-          // come back empty so the leak under test is unambiguously the
-          // sniffed Claude `model` field.
-          if (path.endsWith("/.claude/projects")) {
-            return [{ name: "-home-ec2-user-hq", isDirectory: true, isFile: false }];
-          }
-          if (path.endsWith("/.claude/projects/-home-ec2-user-hq")) {
-            return [
-              {
-                name: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.jsonl",
-                isDirectory: false,
-                isFile: true,
-              },
-            ];
-          }
-          return [];
-        },
-        stat: async () => ({
-          mtimeMs: Date.parse("2026-07-29T00:00:00.000Z"),
-          birthtimeMs: Date.parse("2026-07-29T00:00:00.000Z"),
-          size: 128,
-        }),
-        // An adversarial transcript that tries to smuggle a key out via the
-        // sniffed model field.
-        readBounded: async () =>
-          JSON.stringify({ model: "sk-ant-api03-LEAKED-KEY-VALUE" }),
-      },
-    });
-
-    const ticks = await runHeartbeatLoop({ once: true }, deps);
-
-    expect(ticks).toBe(1);
-    expect(published).toEqual([]);
-    expect(logs.join("\n").toLowerCase()).toContain("refusing to publish");
-  });
-
-  it("records a liveness marker after a successful publish", async () => {
-    // The marker is what the box audit reads. Without it the audit can only see
-    // "systemd says active", which is exactly the signal that stayed green for
-    // nine days while every tick failed.
-    const marks: number[] = [];
-    const { deps } = makeDeps({
-      onPublished: async () => {
-        marks.push(1);
-      },
-    });
-
-    await runHeartbeatLoop({ maxTicks: 3 }, deps);
-
-    expect(marks).toHaveLength(3);
-  });
-
-  it("does NOT record a liveness marker when the publish failed", async () => {
-    // A marker written regardless of outcome would recreate the original bug in
-    // a new place: a freshness check that is always fresh.
-    const marks: number[] = [];
-    const { deps } = makeDeps({
-      publish: async () => {
-        throw new Error("iot unavailable");
-      },
-      onPublished: async () => {
-        marks.push(1);
-      },
-    });
-
-    await runHeartbeatLoop({ maxTicks: 3 }, deps);
-
-    expect(marks).toEqual([]);
-  });
-
-  it("keeps beating when the liveness marker cannot be written", async () => {
-    const { deps, published } = makeDeps({
-      onPublished: async () => {
-        throw new Error("EACCES: read-only filesystem");
-      },
-    });
-
-    const ticks = await runHeartbeatLoop({ maxTicks: 2 }, deps);
-
-    expect(ticks).toBe(2);
-    expect(published).toHaveLength(2);
-  });
-
-  it("stops promptly when aborted", async () => {
-    const controller = new AbortController();
-    const { deps, published } = makeDeps({
-      sleep: async () => {
-        controller.abort();
-      },
-    });
-
-    const ticks = await runHeartbeatLoop(
-      { intervalSeconds: 5, signal: controller.signal },
-      deps,
-    );
-
-    expect(ticks).toBe(1);
-    expect(published).toHaveLength(1);
-  });
-});