@indigoai-us/hq-cli 5.62.1 → 5.63.0

package/src/commands/billing.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Unit tests for `hq billing` (billing.ts).
+ *
+ * Mirrors company.test.ts: mock ensureCognitoToken + getCompanyUid, spy on
+ * global fetch, drive through a Commander program, assert the request shape and
+ * rendered output.
+ */
+
+import { Command } from "commander";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+vi.mock("../utils/cognito-session.js", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("../utils/cognito-session.js")>();
+  return {
+    ...original,
+    ensureCognitoToken: vi.fn(async () => "test-token"),
+  };
+});
+
+vi.mock("../utils/vault-api.js", async (importOriginal) => {
+  const original = await importOriginal<typeof import("../utils/vault-api.js")>();
+  return {
+    ...original,
+    getCompanyUid: vi.fn(async () => "cmp_acme"),
+  };
+});
+
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
+import { registerBillingCommand } from "./billing.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchSpy: MockInstance<typeof fetch>;
+let logSpy: MockInstance<typeof console.log>;
+let stdoutSpy: MockInstance<typeof process.stdout.write>;
+const mockEnsureCognitoToken = vi.mocked(ensureCognitoToken);
+const mockGetCompanyUid = vi.mocked(getCompanyUid);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+  mockEnsureCognitoToken.mockResolvedValue("test-token");
+  mockGetCompanyUid.mockResolvedValue("cmp_acme");
+  vi.spyOn(process, "exit").mockImplementation((code?: number) => {
+    throw new Error(`process.exit(${code})`);
+  });
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.name("hq").exitOverride();
+  registerBillingCommand(program);
+  return program;
+}
+
+async function run(args: string[]): Promise<void> {
+  await buildProgram().parseAsync(["node", "hq", ...args]);
+}
+
+describe("hq billing status", () => {
+  it("GETs /v1/billing/summary and renders card-on-file", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        subscriptionStatus: "active",
+        defaultPaymentMethod: { present: true, brand: "visa", last4: "4242" },
+      }),
+    );
+
+    await run(["billing", "--company", "acme", "status"]);
+
+    const url = String(fetchSpy.mock.calls[0][0]);
+    expect(url).toContain("/v1/billing/summary");
+    expect(url).toContain("companyUid=cmp_acme");
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toMatch(/active/);
+    expect(printed).toMatch(/visa/);
+    expect(printed).toMatch(/4242/);
+  });
+
+  it("flags no card on file", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        subscriptionStatus: null,
+        defaultPaymentMethod: { present: false, brand: null, last4: null },
+      }),
+    );
+    await run(["billing", "--company", "acme", "status"]);
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toMatch(/no card on file/i);
+  });
+});
+
+describe("hq billing checkout", () => {
+  it("POSTs /v1/billing/checkout/org with companyUid and prints the url", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { url: "https://checkout.stripe.com/abc" }),
+    );
+
+    await run(["billing", "--company", "acme", "checkout"]);
+
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/v1/billing/checkout/org");
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(init?.body as string)).toEqual({ companyUid: "cmp_acme" });
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://checkout.stripe.com/abc");
+  });
+
+  it("POSTs /v1/billing/checkout/person with --personal", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { url: "https://checkout.stripe.com/xyz" }),
+    );
+    await run(["billing", "checkout", "--personal"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/v1/billing/checkout/person");
+    expect(init?.method).toBe("POST");
+    // Person checkout resolves the payer from the JWT — no companyUid resolution.
+    expect(mockGetCompanyUid).not.toHaveBeenCalled();
+  });
+
+  it("emits raw JSON with --json", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { url: "https://checkout.stripe.com/j" }),
+    );
+    await run(["billing", "--company", "acme", "checkout", "--json"]);
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://checkout.stripe.com/j");
+  });
+
+  it("exits 1 when the checkout response has no url", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    await expect(
+      run(["billing", "--company", "acme", "checkout"]),
+    ).rejects.toThrow("process.exit(1)");
+  });
+});

package/src/commands/billing.ts

@@ -0,0 +1,146 @@
+/**
+ * `hq billing` — inspect billing state and mint a card-capture link from the
+ * terminal. Backs the paid-provisioning gate (agents & Outposts): a user can
+ * check whether a card is on file, and proactively hand out the same Stripe
+ * hosted card-capture link that a `402 billing_required` would surface.
+ *
+ * Targets the hq-pro billing control plane on `DEFAULT_VAULT_API_URL` via the
+ * shared `vaultApiFetch` helper — the same routes the console billing surfaces
+ * call.
+ *
+ * Subcommands:
+ *   hq billing status   [--company <slug>]              — subscription + card on file
+ *   hq billing checkout [--company <slug>] [--personal] — mint a card-capture link
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { mintPaymentLink, type BillingSetupAction } from "../utils/billing-gate.js";
+
+/** Shape of `GET /v1/billing/summary` we render. */
+interface BillingSummary {
+  subscriptionStatus: string | null;
+  defaultPaymentMethod: {
+    present: boolean;
+    brand: string | null;
+    last4: string | null;
+  };
+  [key: string]: unknown;
+}
+
+function fail(err: unknown): never {
+  console.error(
+    chalk.red("Error:"),
+    err instanceof Error ? err.message : String(err),
+  );
+  process.exit(1);
+}
+
+async function getBillingSummary(
+  token: string,
+  companyUid: string,
+): Promise<BillingSummary> {
+  const res = await vaultApiFetch({
+    token,
+    path: "/v1/billing/summary",
+    query: { companyUid },
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as {
+      error?: string;
+      message?: string;
+    };
+    throw new Error(body.error ?? body.message ?? res.statusText);
+  }
+  return (await res.json()) as BillingSummary;
+}
+
+export function registerBillingCommand(program: Command): void {
+  const billing = program
+    .command("billing")
+    .description("Inspect billing and mint a card-capture link")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  const companyOf = (sub: Command): string | undefined =>
+    (sub.opts().company as string | undefined) ??
+    (billing.opts().company as string | undefined);
+
+  billing
+    .command("status")
+    .description("Show subscription status and whether a card is on file")
+    .option("--company <slug>", "Company slug (resolves to companyUid)")
+    .option("--json", "Emit raw JSON")
+    .action(async function (this: Command, opts: { json?: boolean }) {
+      try {
+        const token = await ensureCognitoToken();
+        const companyUid = await getCompanyUid(token, companyOf(this));
+        const summary = await getBillingSummary(token, companyUid);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+          return;
+        }
+        const sub = summary.subscriptionStatus ?? "none";
+        console.log(`${chalk.bold("Subscription")}: ${sub}`);
+        const pm = summary.defaultPaymentMethod;
+        if (pm?.present) {
+          const detail =
+            pm.brand && pm.last4 ? `${pm.brand} ••••${pm.last4}` : "on file";
+          console.log(`${chalk.bold("Card")}: ${detail}`);
+        } else {
+          console.log(
+            `${chalk.bold("Card")}: ${chalk.yellow("no card on file")} — ` +
+              `run \`hq billing checkout\` to add one before provisioning paid resources.`,
+          );
+        }
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  billing
+    .command("checkout")
+    .description("Mint a Stripe card-capture link (shareable) to add a card")
+    .option("--company <slug>", "Company slug (resolves to companyUid)")
+    .option(
+      "--personal",
+      "Mint the link for your personal payer (Outposts) instead of a company",
+    )
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      opts: { personal?: boolean; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        let setup: BillingSetupAction;
+        if (opts.personal) {
+          setup = {
+            payerType: "person",
+            path: "/v1/billing/checkout/person",
+            method: "POST",
+          };
+        } else {
+          const companyUid = await getCompanyUid(token, companyOf(this));
+          setup = {
+            payerType: "company",
+            path: "/v1/billing/checkout/org",
+            method: "POST",
+            body: { companyUid },
+          };
+        }
+        const url = await mintPaymentLink(token, setup);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify({ url }, null, 2) + "\n");
+          return;
+        }
+        console.log(
+          "Add a card here (safe to share with whoever owns billing):\n  " +
+            chalk.cyan(url),
+        );
+      } catch (err) {
+        fail(err);
+      }
+    });
+}

package/src/commands/cloud.pull-all.test.ts

@@ -180,6 +180,59 @@ describe("pullAll", () => {
     expect(companyCall?.prefixSet).toEqual(["knowledge/", "policies/"]);
   });
 
+  // ── 1c. Sessions-exclusion: excludePrefixes is threaded into sync() ───────
+  //
+  // Guards the "session transcripts never sync DOWN" invariant on the CLI path:
+  // a company OWNER's STS scope is wide enough to read `sessions/` keys, so if
+  // the 4-site scope→sync-options mapping dropped `excludePrefixes` the CLI
+  // would bulk-download everyone's full-content session transcripts to local
+  // disk. This asserts the resolver's excludePrefixes reaches the SyncCallOptions
+  // handed to sync(); it FAILS if any mapping site drops the field.
+  it("threads the resolved excludePrefixes into sync() (sessions never pull DOWN)", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_a" }],
+      entitiesBySlug: { cmp_a: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+    // hq-cloud derives excludePrefixes on the resolved scope.
+    const resolveScope = vi.fn(async (_uid: string, _slug: string) => ({
+      syncMode: "shared" as const,
+      prefixSet: ["knowledge/", "policies/"],
+      excludePrefixes: ["sessions/"],
+    }));
+
+    await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn, resolveScope },
+    );
+
+    const companyCall = sync.calls.find((c) => c.company === "cmp_a");
+    expect(companyCall?.excludePrefixes).toEqual(["sessions/"]);
+    // Sibling scope fields still flow — excludePrefixes rides alongside them.
+    expect(companyCall?.syncMode).toBe("shared");
+    expect(companyCall?.prefixSet).toEqual(["knowledge/", "policies/"]);
+  });
+
+  it("omits excludePrefixes when the resolved scope carries none", async () => {
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_a" }],
+      entitiesBySlug: { cmp_a: { slug: "acme" } },
+    });
+    const sync = makeSyncSpy();
+    const resolveScope = vi.fn(async () => ({
+      syncMode: "shared" as const,
+      prefixSet: ["knowledge/"],
+    }));
+
+    await pullAll(
+      { hqRoot: "/tmp/hq" },
+      { vaultClient, sync: sync.fn, resolveScope },
+    );
+
+    const companyCall = sync.calls.find((c) => c.company === "cmp_a");
+    expect(companyCall?.excludePrefixes).toBeUndefined();
+  });
+
   it("passes no prefixSet for an all-mode membership (full pull preserved)", async () => {
     const vaultClient = makeVaultClient({
       memberships: [{ companyUid: "cmp_a" }],

package/src/commands/cloud.ts

@@ -153,6 +153,17 @@ export interface SyncCallOptions {
    */
   syncMode?: SyncMode;
   prefixSet?: string[];
+  /**
+   * Company-relative prefixes the pull must NOT materialize even when the
+   * caller's STS scope is wide enough to read them (sessions-exclusion /
+   * company-work-corpus). Derived by `resolvePullScope` in the hq-cloud release
+   * carrying the sessions/ pull-exclusion, forwarded to `sync()` here so the CLI
+   * honors the same "session transcripts never sync DOWN" invariant the
+   * background sync engine enforces. A company OWNER can read `sessions/` keys,
+   * so without this the CLI would bulk-download everyone's full-content session
+   * transcripts to local disk. Undefined/empty ⇒ nothing excluded (legacy).
+   */
+  excludePrefixes?: string[];
   /** Honor a `--force-scope-shrink` on a foreground pull (dirty files kept). */
   forceScopeShrink?: boolean;
 }
@@ -320,6 +331,29 @@ function pickCanonicalPerson<
   })[0];
 }
 
+/**
+ * Read the sessions-exclusion prefix set off a resolved {@link PullScope}.
+ *
+ * `resolvePullScope` in hq-cloud derives the sessions/ pull-exclusion and
+ * derives `excludePrefixes` (e.g. `["sessions/"]`) so a company OWNER — whose STS
+ * scope is wide enough to read `sessions/` keys — does not bulk-download
+ * everyone's full-content session transcripts to local disk, upholding the
+ * "session transcripts never sync DOWN" invariant hq-cloud enforces for the
+ * background engine. Keep the small runtime shape check even though PullScope
+ * now declares the field: it protects the CLI when an older external resolver
+ * implementation is injected by tests or downstream callers.
+ */
+function readScopeExcludePrefixes(
+  scope: PullScope | undefined,
+): string[] | undefined {
+  const raw: unknown = scope?.excludePrefixes;
+  if (!Array.isArray(raw)) return undefined;
+  const prefixes = raw.filter(
+    (p): p is string => typeof p === "string" && p.length > 0,
+  );
+  return prefixes.length > 0 ? prefixes : undefined;
+}
+
 export async function pullAll(
   options: PullAllOptions,
   deps: PullAllDeps,
@@ -398,6 +432,12 @@ export async function pullAll(
         if (scope.prefixSet !== undefined) {
           entry.syncOptions.prefixSet = scope.prefixSet;
         }
+        // Sessions-exclusion: thread the resolver's excludePrefixes into the
+        // pull so a wide-STS OWNER never bulk-downloads session transcripts.
+        const excludePrefixes = readScopeExcludePrefixes(scope);
+        if (excludePrefixes) {
+          entry.syncOptions.excludePrefixes = excludePrefixes;
+        }
       } catch {
         resolvedMode = undefined;
       }
@@ -1205,6 +1245,7 @@ export function registerCloudCommands(program: Command): void {
             process.exit(1);
           }
 
+          const excludePrefixes = readScopeExcludePrefixes(pullScope);
           const result = await sync({
             company: options.company,
             onConflict: options.onConflict,
@@ -1216,6 +1257,9 @@ export function registerCloudCommands(program: Command): void {
             ...(pullScope?.prefixSet !== undefined
               ? { prefixSet: pullScope.prefixSet }
               : {}),
+            // Sessions-exclusion: never materialize excluded prefixes even for
+            // a wide-STS owner.
+            ...(excludePrefixes ? { excludePrefixes } : {}),
             ...(options.forceScopeShrink ? { forceScopeShrink: true } : {}),
           });
 
@@ -1519,6 +1563,11 @@ async function runPullAll(
               : {}),
             ...(opts.syncMode !== undefined ? { syncMode: opts.syncMode } : {}),
             ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
+            // Sessions-exclusion: forward the per-company excludePrefixes that
+            // pullAll stamped onto SyncCallOptions into the real hq-cloud sync().
+            ...(opts.excludePrefixes?.length
+              ? { excludePrefixes: opts.excludePrefixes }
+              : {}),
             ...(opts.forceScopeShrink ? { forceScopeShrink: true } : {}),
           }),
       },
@@ -1877,6 +1926,7 @@ async function runNowSingle(
     }
 
     console.log(chalk.dim("  → pull leg"));
+    const excludePrefixes = readScopeExcludePrefixes(pullScope);
     const pullResult = await sync({
       company: targetCompany,
       vaultConfig,
@@ -1890,6 +1940,9 @@ async function runNowSingle(
       ...(pullScope?.prefixSet !== undefined
         ? { prefixSet: pullScope.prefixSet }
         : {}),
+      // Sessions-exclusion: honor the resolver's excludePrefixes on the
+      // `hq sync now` pull leg too.
+      ...(excludePrefixes ? { excludePrefixes } : {}),
       ...(forceScopeShrink ? { forceScopeShrink: true } : {}),
     });
     console.log(

package/src/commands/members.test.ts

@@ -95,6 +95,24 @@ describe("detectTarget", () => {
     });
   });
 
+  it("recognizes fleet agent uids", () => {
+    expect(detectTarget("agt_01HXYZABCDEFGHJKMNPQRSTVWX")).toEqual({
+      type: "agent",
+      value: "agt_01HXYZABCDEFGHJKMNPQRSTVWX",
+      isAgent: true,
+    });
+  });
+
+  it("recognizes fleet agent machine emails", () => {
+    expect(
+      detectTarget("agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai"),
+    ).toEqual({
+      type: "email",
+      value: "agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai",
+      isAgent: true,
+    });
+  });
+
   it("returns null for invalid targets", () => {
     expect(detectTarget("not-a-target")).toBeNull();
     expect(detectTarget("cmp_company")).toBeNull();
@@ -234,6 +252,48 @@ describe("inviteMember", () => {
     expect(fetchSpy).not.toHaveBeenCalled();
   });
 
+  it("invites a fleet agent by uid as member via /membership/invite", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(201, {
+        membership: {
+          membershipKey: "agt_01HXYZ#cmp_acme",
+          role: "member",
+          status: "active",
+        },
+        agentUid: "agt_01HXYZABCDEFGHJKMNPQRSTVWX",
+        hostCompanyUid: "cmp_host",
+        activationBilled: false,
+      }),
+    );
+
+    const result = await inviteMember({
+      target: "agt_01HXYZABCDEFGHJKMNPQRSTVWX",
+      role: "member",
+      companyUid: "cmp_acme",
+      callerUid: "prs_admin",
+      token: "test-token",
+    });
+
+    expect(result.membership.status).toBe("active");
+    expect(result.membership.role).toBe("member");
+    const body = JSON.parse((fetchSpy.mock.calls[0][1]?.body as string) ?? "{}");
+    expect(body.personUid).toBe("agt_01HXYZABCDEFGHJKMNPQRSTVWX");
+    expect(body.role).toBe("member");
+  });
+
+  it("rejects owner/guest roles for agent invites", async () => {
+    await expect(
+      inviteMember({
+        target: "agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai",
+        role: "owner",
+        companyUid: "cmp_acme",
+        callerUid: "prs_admin",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/member or admin/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
   it("rejects an unknown role", async () => {
     await expect(
       inviteMember({
@@ -1134,6 +1194,24 @@ describe("registerMembersCommand promote", () => {
 // ---------------------------------------------------------------------------
 
 describe("resolveRevokeTargetToMembershipKey", () => {
+  it("wraps fleet agent uids as agt_…#companyUid", () => {
+    expect(
+      resolveRevokeTargetToMembershipKey(
+        "agt_01HXYZABCDEFGHJKMNPQRSTVWX",
+        "cmp_abc",
+      ),
+    ).toBe("agt_01HXYZABCDEFGHJKMNPQRSTVWX#cmp_abc");
+  });
+
+  it("maps agent machine emails to agt_…#companyUid (active guest memberships)", () => {
+    expect(
+      resolveRevokeTargetToMembershipKey(
+        "agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai",
+        "cmp_abc",
+      ),
+    ).toBe("agt_01HXYZABCDEFGHJKMNPQRSTVWX#cmp_abc");
+  });
+
   // Regression: `hq members revoke alice@example.com` used to send the raw
   // email straight to /membership/revoke, which the server rejects with 404
   // "Invite not found" because it keys on `email:<email>#<companyUid>`. Live