@indigoai-us/hq-cli 5.77.14 → 5.79.0

package/src/commands/onboard-identity-guard.test.ts

@@ -1,99 +0,0 @@
-/**
- * Regression tests for the onboarding identity-link guard
- * (DEV-1695 / DEV-1701 / DEV-1721).
- *
- * Covers the resume-with-mismatched-sub path: a checkpoint that completed
- * `create-person` against a `personUid` the current caller does NOT own must
- * be detected as a recoverable mismatch instead of being allowed to loop
- * forever at bootstrap-membership. Also covers the no-false-positive cases
- * (no checkpoint, no adopted person, create-person not complete, person owned).
- *
- * Pure function — no network, no VaultClient. The resume command supplies the
- * owned-person UID set from the JWT-scoped `/entity/by-type/person` call.
- */
-
-import { describe, expect, it } from "vitest";
-import type { OnboardingCheckpoint } from "@indigoai-us/hq-onboarding";
-
-import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
-
-const OLD_PERSON = "prs_01KRGW9JQ4D2ZHD080B931ZT0J";
-const NEW_PERSON = "prs_01NEWOWNEDBYCURRENTSIGNIN00";
-
-function checkpoint(
-  overrides: Partial<OnboardingCheckpoint> = {},
-): OnboardingCheckpoint {
-  return {
-    mode: "create-company",
-    startedAt: "2026-05-13T14:36:45.668Z",
-    updatedAt: "2026-06-03T14:04:32.261Z",
-    personUid: OLD_PERSON,
-    companyUid: "cmp_01KT6WSNM6HGSH3JZGS8X1KXGS",
-    companySlug: "maximus",
-    completedSteps: ["create-person", "create-company", "provision-bucket"],
-    failedStep: "bootstrap-membership",
-    ...overrides,
-  };
-}
-
-describe("detectOnboardingIdentityMismatch", () => {
-  it("flags the mismatch when the checkpoint's person is owned by a different sign-in", () => {
-    // The Jacob Wuertz case: checkpoint adopted prs_OLD (owned by the original
-    // Cognito sub), but the current caller only owns prs_NEW.
-    const result = detectOnboardingIdentityMismatch({
-      checkpoint: checkpoint(),
-      ownedPersonUids: [NEW_PERSON],
-    });
-
-    expect(result.kind).toBe("mismatch");
-    if (result.kind !== "mismatch") throw new Error("expected mismatch");
-    expect(result.personUid).toBe(OLD_PERSON);
-    expect(result.message).toContain(OLD_PERSON);
-    // Actionable + references the recovery paths that actually work.
-    expect(result.message).toMatch(/DEV-1695/);
-    expect(result.message).toMatch(/original/i);
-    expect(result.message).toMatch(/relink/i);
-  });
-
-  it("also flags the mismatch when the caller owns NO person entities at all", () => {
-    const result = detectOnboardingIdentityMismatch({
-      checkpoint: checkpoint(),
-      ownedPersonUids: [],
-    });
-    expect(result.kind).toBe("mismatch");
-  });
-
-  it("passes when the adopted person IS owned by the current caller", () => {
-    const result = detectOnboardingIdentityMismatch({
-      checkpoint: checkpoint({ personUid: NEW_PERSON }),
-      ownedPersonUids: [NEW_PERSON, "prs_01ANOTHERONE0000000000000000"],
-    });
-    expect(result).toEqual({ kind: "ok" });
-  });
-
-  it("passes when there is no checkpoint", () => {
-    const result = detectOnboardingIdentityMismatch({
-      checkpoint: null,
-      ownedPersonUids: [NEW_PERSON],
-    });
-    expect(result).toEqual({ kind: "ok" });
-  });
-
-  it("passes when the checkpoint has not adopted a person yet (no personUid)", () => {
-    const result = detectOnboardingIdentityMismatch({
-      checkpoint: checkpoint({ personUid: undefined, completedSteps: [] }),
-      ownedPersonUids: [],
-    });
-    expect(result).toEqual({ kind: "ok" });
-  });
-
-  it("passes when create-person is not yet complete, even with a personUid present", () => {
-    // A personUid that predates the create-person step completing is not yet
-    // the committed identity — don't false-positive on it.
-    const result = detectOnboardingIdentityMismatch({
-      checkpoint: checkpoint({ completedSteps: ["create-company"] }),
-      ownedPersonUids: [NEW_PERSON],
-    });
-    expect(result).toEqual({ kind: "ok" });
-  });
-});

package/src/commands/onboard-identity-guard.ts

@@ -1,103 +0,0 @@
-/**
- * Onboarding identity-link guard (DEV-1695 / DEV-1701 / DEV-1721).
- *
- * Failure mode this guards against:
- *
- *   The onboarding orchestrator's `create-person` step resolves the caller's
- *   person entity by an email-derived slug GLOBALLY (not scoped to the caller's
- *   Cognito identity). When a user signs back in under a DIFFERENT Cognito
- *   `sub` — e.g. a new Google account, an email change, or a linked-IdP sub
- *   swap — the slug lookup still finds the person row created under the ORIGINAL
- *   sub and records it in the checkpoint's `personUid`. `create-person` is then
- *   marked complete and is never re-validated against the live identity.
- *
- *   On every `hq onboard resume`, `create-person` is skipped as "already
- *   complete" while the stale `personUid` is carried forward. The server
- *   correctly refuses to bootstrap a company membership for a person the caller
- *   does not own (it resolves the caller's person by the live Cognito sub), so
- *   resume re-fails at `bootstrap-membership` every single time — an infinite
- *   loop with a misleading downstream error.
- *
- * This module is the detection half of the fix: given the local checkpoint and
- * the set of person entities ACTUALLY owned by the current caller (the server
- * scopes `/entity/by-type/person` by the live Cognito sub), it reports whether
- * the checkpoint adopted a person the caller no longer owns. The resume command
- * uses it to surface a recoverable, actionable error instead of looping.
- */
-
-import type { OnboardingCheckpoint } from "@indigoai-us/hq-onboarding";
-
-export type OnboardingIdentityCheck =
-  | { kind: "ok" }
-  | { kind: "mismatch"; personUid: string; message: string };
-
-/**
- * Build the human-facing recovery message for a detected mismatch.
- *
- * Only the two recovery paths that ACTUALLY work are offered. Deleting the
- * checkpoint and re-running `create-company` does NOT help: the email-derived
- * slug would re-adopt the same other-owned person row, so it is deliberately
- * not suggested.
- */
-function buildMismatchMessage(personUid: string): string {
-  return [
-    `Onboarding can't continue — an identity-link mismatch is blocking resume.`,
-    ``,
-    `Your saved onboarding checkpoint is linked to person record ${personUid},`,
-    `but that record is owned by a different sign-in than the one you're using`,
-    `now. This usually means onboarding was started under one identity (one`,
-    `Google account / email) and later resumed under a different one.`,
-    ``,
-    `Because the person record belongs to the original sign-in, resume can't`,
-    `bootstrap your company membership and would otherwise retry forever.`,
-    ``,
-    `To recover, do ONE of the following:`,
-    `  1. Sign out and sign back in with your ORIGINAL onboarding identity,`,
-    `     then re-run 'hq onboard resume'.`,
-    `  2. Ask an HQ admin to relink person ${personUid} to your current`,
-    `     sign-in (reference Linear DEV-1695), then re-run 'hq onboard resume'.`,
-    ``,
-    `Nothing was changed — your data is safe.`,
-  ].join("\n");
-}
-
-/**
- * Detect the person-entity-vs-Cognito-sub mismatch that wedges
- * `hq onboard resume` into an infinite loop.
- *
- * Returns `{ kind: "ok" }` whenever the flow should proceed normally:
- *   - there is no checkpoint, or
- *   - the checkpoint never recorded an adopted person (`personUid` unset, or
- *     `create-person` not yet completed), or
- *   - the adopted person is among those owned by the current caller.
- *
- * Returns `{ kind: "mismatch", ... }` only when the checkpoint completed
- * `create-person` with a `personUid` that the current caller does NOT own —
- * the exact state that loops forever at `bootstrap-membership`.
- */
-export function detectOnboardingIdentityMismatch(input: {
-  checkpoint: OnboardingCheckpoint | null;
-  ownedPersonUids: readonly string[];
-}): OnboardingIdentityCheck {
-  const { checkpoint, ownedPersonUids } = input;
-
-  if (!checkpoint) return { kind: "ok" };
-
-  const adopted = checkpoint.personUid;
-  if (!adopted) return { kind: "ok" };
-
-  // Mirror the orchestrator's `isStepComplete`: a personUid that predates the
-  // create-person step completing has not been committed as the adopted
-  // identity yet, so don't treat it as a mismatch.
-  if (!checkpoint.completedSteps?.includes("create-person")) {
-    return { kind: "ok" };
-  }
-
-  if (ownedPersonUids.includes(adopted)) return { kind: "ok" };
-
-  return {
-    kind: "mismatch",
-    personUid: adopted,
-    message: buildMismatchMessage(adopted),
-  };
-}

package/src/commands/onboard-join.test.ts

@@ -1,96 +0,0 @@
-/**
- * Regression tests for the `hq onboard join` tokenless routing
- * (invite-accept-local-attach).
- *
- * The bug: `hq onboard join` declared `--invite-token` as a commander
- * requiredOption, so a modern (tokenless, email-keyed) invitee could not reach
- * the action — they got "required option '--invite-token' not specified",
- * which reads as "my HQ doesn't know I'm a member". The fix routes the
- * no-token case to the real path (`hq sync`) and keeps the legacy token path
- * intact. `planOnboardJoin` is a pure function — no network, no VaultClient.
- */
-
-import { describe, expect, it } from "vitest";
-
-import { planOnboardJoin, tokenlessJoinGuidance } from "./onboard-join.js";
-
-describe("planOnboardJoin", () => {
-  it("routes a no-token invocation to the tokenless (sync) path", () => {
-    const plan = planOnboardJoin({});
-    expect(plan.kind).toBe("tokenless");
-    if (plan.kind === "tokenless") {
-      expect(plan.guidance).toBe(tokenlessJoinGuidance());
-    }
-  });
-
-  it("treats an empty / whitespace-only token as tokenless", () => {
-    expect(planOnboardJoin({ inviteToken: "" }).kind).toBe("tokenless");
-    expect(planOnboardJoin({ inviteToken: "   " }).kind).toBe("tokenless");
-  });
-
-  it("ignores email / person-name on the tokenless path (sync uses cached identity)", () => {
-    // A user who copy-pastes old instructions may still pass these — they must
-    // not flip the decision or be required.
-    const plan = planOnboardJoin({
-      email: "richard@sender.agency",
-      personName: "Richard",
-    });
-    expect(plan.kind).toBe("tokenless");
-  });
-
-  it("keeps the legacy path when a token + email + person-name are all present", () => {
-    const plan = planOnboardJoin({
-      inviteToken: "tok_abc123",
-      email: "richard@sender.agency",
-      personName: "Richard",
-    });
-    expect(plan.kind).toBe("legacy");
-    if (plan.kind === "legacy") {
-      expect(plan.inviteToken).toBe("tok_abc123");
-      expect(plan.email).toBe("richard@sender.agency");
-      expect(plan.personName).toBe("Richard");
-    }
-  });
-
-  it("trims the token before deciding", () => {
-    const plan = planOnboardJoin({
-      inviteToken: "  tok_abc123  ",
-      email: "r@x.co",
-      personName: "R",
-    });
-    expect(plan.kind).toBe("legacy");
-    if (plan.kind === "legacy") {
-      expect(plan.inviteToken).toBe("tok_abc123");
-    }
-  });
-
-  it("errors actionably when a token is given but email/person-name are missing", () => {
-    const plan = planOnboardJoin({ inviteToken: "tok_abc123" });
-    expect(plan.kind).toBe("error");
-    if (plan.kind === "error") {
-      expect(plan.message).toContain("--email");
-      expect(plan.message).toContain("--person-name");
-      // Steers the likely-confused user back to the tokenless path.
-      expect(plan.message).toContain("hq sync");
-    }
-  });
-
-  it("names only the missing legacy field", () => {
-    const plan = planOnboardJoin({ inviteToken: "tok_abc123", email: "r@x.co" });
-    expect(plan.kind).toBe("error");
-    if (plan.kind === "error") {
-      expect(plan.message).toContain("--person-name");
-      expect(plan.message).not.toContain("--email and");
-    }
-  });
-});
-
-describe("tokenlessJoinGuidance", () => {
-  it("points at both the CLI sync and the menubar Sync button, and disclaims the token", () => {
-    const g = tokenlessJoinGuidance();
-    expect(g).toContain("hq sync");
-    expect(g).toMatch(/menubar|Sync/);
-    expect(g).toContain("--invite-token");
-    expect(g.toLowerCase()).toContain("don't use a token");
-  });
-});

package/src/commands/onboard-join.ts

@@ -1,101 +0,0 @@
-/**
- * `hq onboard join` planning helper.
- *
- * Modern HQ invites are email-keyed and TOKENLESS (hq-pro schemaVersion 2+):
- * the membership row is claimed when the invitee signs into HQ with the
- * invited email, and `hq sync` then discovers every company they belong to
- * and pulls it locally. There is no token to redeem.
- *
- * The legacy path (schemaVersion ≤ 1) handed out a random `inviteToken` the
- * invitee redeemed via `hq://accept/{token}`. `hq onboard join` historically
- * declared `--invite-token` as a commander `requiredOption`, so a modern
- * invitee — who has no token — could not even reach the action handler. They
- * got `error: required option '--invite-token <token>' not specified`, which
- * reads as "my HQ doesn't know I'm a member / I'm missing a token" when in
- * fact the invite is fine and they simply need to sync.
- *
- * This module decides which path a given invocation is on and produces the
- * tokenless guidance, as a pure function so it can be unit-tested without
- * commander, the network, or a VaultClient (same shape as
- * `onboard-identity-guard.ts`).
- */
-
-export interface JoinTokenless {
-  kind: "tokenless";
-  /** Human-facing guidance pointing at the real (sync) path. */
-  guidance: string;
-}
-
-export interface JoinLegacy {
-  kind: "legacy";
-  inviteToken: string;
-  email: string;
-  personName: string;
-}
-
-export interface JoinError {
-  kind: "error";
-  message: string;
-}
-
-export type JoinPlan = JoinTokenless | JoinLegacy | JoinError;
-
-export interface JoinOptionsInput {
-  inviteToken?: string;
-  email?: string;
-  personName?: string;
-}
-
-/**
- * Guidance shown when `hq onboard join` is run without a token. Covers both
- * the CLI (`hq sync`) and the HQ Sync menubar app (the Sync button), since
- * most invitees are on the app rather than the CLI.
- */
-export function tokenlessJoinGuidance(): string {
-  return [
-    "Modern HQ invites don't use a token — there's nothing to redeem.",
-    "",
-    "If you've accepted your invite (the email link or HQ Console), your",
-    "membership already exists. To pull it onto this machine, just sync:",
-    "",
-    "    hq sync",
-    "",
-    "That signs you in, finds every company you've been added to, and pulls",
-    "it locally. In the HQ Sync menubar app, click Sync — same result.",
-    "",
-    "(--invite-token is only for legacy token invites and is no longer issued.)",
-  ].join("\n");
-}
-
-/**
- * Decide how an `hq onboard join` invocation should proceed.
- *
- * - No token  → tokenless: the invitee belongs on the `hq sync` path. Email
- *   and person-name are irrelevant here (sync uses the cached Cognito
- *   identity), so they are ignored rather than required.
- * - Token     → legacy: the historical redeem path. `--email` and
- *   `--person-name` are still required to bootstrap the person entity; a
- *   missing one yields an actionable error instead of a commander stack trace.
- */
-export function planOnboardJoin(opts: JoinOptionsInput): JoinPlan {
-  const inviteToken = (opts.inviteToken ?? "").trim();
-  if (!inviteToken) {
-    return { kind: "tokenless", guidance: tokenlessJoinGuidance() };
-  }
-
-  const email = (opts.email ?? "").trim();
-  const personName = (opts.personName ?? "").trim();
-  const missing: string[] = [];
-  if (!email) missing.push("--email");
-  if (!personName) missing.push("--person-name");
-  if (missing.length > 0) {
-    return {
-      kind: "error",
-      message:
-        `Legacy token join (--invite-token) also requires ${missing.join(" and ")}. ` +
-        "Most invites are tokenless — omit --invite-token and run `hq sync` instead.",
-    };
-  }
-
-  return { kind: "legacy", inviteToken, email, personName };
-}

package/src/commands/onboard-warning.test.ts

@@ -1,26 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { buildCreateCompanyWarning } from "./onboard-warning.js";
-
-describe("buildCreateCompanyWarning", () => {
-  it("documents the warning shown on the create-company path", () => {
-    const warning = buildCreateCompanyWarning();
-    expect(warning).toContain("NEW company");
-    expect(warning).toMatch(/does NOT join an existing one/i);
-  });
-
-  it("advises existing-company users to ask an admin or owner for an invite", () => {
-    const warning = buildCreateCompanyWarning();
-    expect(warning).toMatch(/ask your admin or owner.*invite/i);
-  });
-
-  it("tells invitees to run hq sync after accepting", () => {
-    const warning = buildCreateCompanyWarning();
-    expect(warning).toContain("accept it and run `hq sync`");
-  });
-
-  it("warns that duplicate creation leaves the user alone in a separate company", () => {
-    const warning = buildCreateCompanyWarning();
-    expect(warning).toMatch(/separate one you'd be alone in/i);
-  });
-});

package/src/commands/onboard-warning.ts

@@ -1,12 +0,0 @@
-/**
- * Builds the static create-time warning surfaced by both `create-company` and
- * `dry-run`, because users may accidentally create duplicate companies instead
- * of joining the existing company they were invited to.
- */
-export function buildCreateCompanyWarning(): string {
-  return (
-    "  This creates a NEW company that you own — it does NOT join an existing one.\n" +
-    "  If your company already uses HQ, do NOT create it again: ask your admin or owner to send you an invite, then accept it and run `hq sync` to pull the existing company.\n" +
-    "  Creating a same-named company makes a separate one you'd be alone in.\n"
-  );
-}