@indigoai-us/hq-cli 5.47.0 → 5.47.1

package/dist/commands/onboard-join.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `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 declare function tokenlessJoinGuidance(): string;
+/**
+ * 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 declare function planOnboardJoin(opts: JoinOptionsInput): JoinPlan;
+//# sourceMappingURL=onboard-join.d.ts.map

package/dist/commands/onboard-join.js

@@ -0,0 +1,76 @@
+/**
+ * `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`).
+ */
+/**
+ * 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.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="38623485-912f-52db-bf3d-f1c911246026")}catch(e){}}();
+export function tokenlessJoinGuidance() {
+    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) {
+    const inviteToken = (opts.inviteToken ?? "").trim();
+    if (!inviteToken) {
+        return { kind: "tokenless", guidance: tokenlessJoinGuidance() };
+    }
+    const email = (opts.email ?? "").trim();
+    const personName = (opts.personName ?? "").trim();
+    const missing = [];
+    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 };
+}
+//# sourceMappingURL=onboard-join.js.map
+//# debugId=38623485-912f-52db-bf3d-f1c911246026

package/dist/commands/onboard.js

@@ -19,12 +19,13 @@
  * browser-OAuth flow opens automatically.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="99e9ce57-1051-59ce-8897-edcc83e83a16")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="05a49c9b-23bc-5b96-b5e1-cc2e573b11c3")}catch(e){}}();
 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";
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -49,8 +50,8 @@ export function registerOnboardCommand(program) {
             console.log(`  Person:   ${options.personName} <${options.email}>`);
             console.log(`  HQ root:  ${options.hqRoot}\n`);
             console.log(chalk.gray("  This creates a NEW company you own. Joining a teammate's existing\n" +
-                "  company? Stop and run `hq onboard join --invite-token <token>` —\n" +
-                "  creating a same-named company leaves you alone in a separate one.\n"));
+                "  company? Stop — accept your invite, then run `hq sync` to pull it.\n" +
+                "  Creating a same-named company leaves you alone in a separate one.\n"));
             const accessToken = await ensureCognitoToken();
             const result = await runOnboardCli({
                 mode: "create-company",
@@ -74,21 +75,39 @@ export function registerOnboardCommand(program) {
     onboard
         .command("join")
         .description("Accept an invite and join an existing company")
-        .requiredOption("--invite-token <token>", "Magic link token from your invite email")
-        .requiredOption("--email <email>", "Your email (must match Cognito sign-in)")
-        .requiredOption("--person-name <name>", "Your display name")
+        // 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) => {
         try {
             console.log(chalk.bold(`\nHQ Onboard — Join Company`));
-            console.log(`  Person:   ${options.personName} <${options.email}>`);
+            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: options.personName,
-                personEmail: options.email,
-                inviteToken: options.inviteToken,
+                personName: plan.personName,
+                personEmail: plan.email,
+                inviteToken: plan.inviteToken,
                 vaultConfig: buildVaultConfig(accessToken),
                 hqRoot: options.hqRoot,
             });
@@ -179,4 +198,4 @@ export function registerOnboardCommand(program) {
     });
 }
 //# sourceMappingURL=onboard.js.map
-//# debugId=99e9ce57-1051-59ce-8897-edcc83e83a16
+//# debugId=05a49c9b-23bc-5b96-b5e1-cc2e573b11c3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.47.0",
+  "version": "5.47.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

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

@@ -0,0 +1,96 @@
+/**
+ * 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

@@ -0,0 +1,101 @@
+/**
+ * `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.ts

@@ -31,6 +31,7 @@ import {
 } from "../utils/cognito-session.js";
 import { createDefaultVaultClient } from "./cloud-provision.js";
 import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
+import { planOnboardJoin } from "./onboard-join.js";
 
 // ---------------------------------------------------------------------------
 // Command registration
@@ -72,8 +73,8 @@ export function registerOnboardCommand(program: Command): void {
         console.log(
           chalk.gray(
             "  This creates a NEW company you own. Joining a teammate's existing\n" +
-              "  company? Stop and run `hq onboard join --invite-token <token>` —\n" +
-              "  creating a same-named company leaves you alone in a separate one.\n",
+              "  company? Stop — accept your invite, then run `hq sync` to pull it.\n" +
+              "  Creating a same-named company leaves you alone in a separate one.\n",
           ),
         );
 
@@ -104,31 +105,53 @@ export function registerOnboardCommand(program: Command): void {
   onboard
     .command("join")
     .description("Accept an invite and join an existing company")
-    .requiredOption("--invite-token <token>", "Magic link token from your invite email")
-    .requiredOption("--email <email>", "Your email (must match Cognito sign-in)")
-    .requiredOption("--person-name <name>", "Your display name")
+    // 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;
+      inviteToken?: string;
+      email?: string;
+      personName?: string;
       hqRoot: string;
     }) => {
       try {
         console.log(chalk.bold(`\nHQ Onboard — Join Company`));
-        console.log(`  Person:   ${options.personName} <${options.email}>`);
+
+        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: options.personName,
-          personEmail: options.email,
-          inviteToken: options.inviteToken,
+          personName: plan.personName,
+          personEmail: plan.email,
+          inviteToken: plan.inviteToken,
           vaultConfig: buildVaultConfig(accessToken),
           hqRoot: options.hqRoot,
         });