@indigoai-us/hq-cli 5.50.2 → 5.52.0

package/src/commands/people.test.ts

@@ -19,7 +19,11 @@ import {
   resolveNameToEmail,
   type PersonRecord,
 } from "../utils/people.js";
-import { registerPeopleCommand, resolveCompanySlug } from "./people.js";
+import {
+  registerPeopleCommand,
+  resolveCompanySlug,
+  type RefreshPeopleRoster,
+} from "./people.js";
 
 // ---------------------------------------------------------------------------
 // Filesystem fixture helpers
@@ -335,15 +339,20 @@ describe("companyPeopleDir", () => {
 // Wired CLI surface (list / search / resolve)
 // ---------------------------------------------------------------------------
 
-function buildProgram(): Command {
+function buildProgram(deps?: { refreshRoster?: RefreshPeopleRoster }): Command {
   const program = new Command();
   program.exitOverride(); // throw instead of process.exit on commander errors
-  registerPeopleCommand(program);
+  registerPeopleCommand(program, deps);
   return program;
 }
 
-async function run(args: string[]): Promise<void> {
-  await buildProgram().parseAsync(["node", "hq", ...args]);
+async function run(
+  args: string[],
+  deps: { refreshRoster?: RefreshPeopleRoster } = {
+    refreshRoster: async () => {},
+  },
+): Promise<void> {
+  await buildProgram(deps).parseAsync(["node", "hq", ...args]);
 }
 
 describe("hq people (wired)", () => {
@@ -396,6 +405,104 @@ describe("hq people (wired)", () => {
     expect(out[0].email).toBe("jane@acme.com");
   });
 
+  it("search local hit does not refresh the roster", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+    await run(
+      [
+        "people",
+        "search",
+        "jane",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+      ],
+      { refreshRoster },
+    );
+    expect(refreshRoster).not.toHaveBeenCalled();
+  });
+
+  it("search local miss refreshes once and retries from the refreshed roster", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+      makePerson("acme", "ada-lovelace", {
+        name: "Ada Lovelace",
+        email: "ada@acme.com",
+        type: "internal",
+      });
+    });
+
+    await run(
+      [
+        "people",
+        "search",
+        "ada",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+      ],
+      { refreshRoster },
+    );
+
+    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(refreshRoster).toHaveBeenCalledWith(tmpRoot, "acme");
+    const out = JSON.parse(logSpy.mock.calls[0][0] as string);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatchObject({
+      name: "Ada Lovelace",
+      email: "ada@acme.com",
+    });
+  });
+
+  it("search local miss with refresh failure reports the original empty JSON and logs a note", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+      throw new Error("offline");
+    });
+
+    await run(
+      [
+        "people",
+        "search",
+        "ada",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+      ],
+      { refreshRoster },
+    );
+
+    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual([]);
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Could not refresh people roster"),
+    );
+  });
+
+  it("search --local-only skips refresh on a miss", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+    await run(
+      [
+        "people",
+        "search",
+        "ada",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+        "--json",
+        "--local-only",
+      ],
+      { refreshRoster },
+    );
+
+    expect(refreshRoster).not.toHaveBeenCalled();
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual([]);
+  });
+
   it("resolve prints the bare email on stdout", async () => {
     await run([
       "people",
@@ -409,6 +516,106 @@ describe("hq people (wired)", () => {
     expect(logSpy).toHaveBeenCalledWith("jane@acme.com");
   });
 
+  it("resolve local hit does not refresh the roster", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+    await run(
+      [
+        "people",
+        "resolve",
+        "Jane Smith",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+      ],
+      { refreshRoster },
+    );
+    expect(refreshRoster).not.toHaveBeenCalled();
+  });
+
+  it("resolve local miss refreshes once and retries from the refreshed roster", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+      makePerson("acme", "ada-lovelace", {
+        name: "Ada Lovelace",
+        email: "ada@acme.com",
+        type: "internal",
+      });
+    });
+
+    await run(
+      [
+        "people",
+        "resolve",
+        "Ada Lovelace",
+        "--company",
+        "acme",
+        "--hq-root",
+        tmpRoot,
+      ],
+      { refreshRoster },
+    );
+
+    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(refreshRoster).toHaveBeenCalledWith(tmpRoot, "acme");
+    expect(logSpy).toHaveBeenCalledWith("ada@acme.com");
+  });
+
+  it("resolve local miss with refresh failure reports unchanged not_found JSON and logs a note", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>(async () => {
+      throw new Error("not signed in");
+    });
+
+    await expect(
+      run(
+        [
+          "people",
+          "resolve",
+          "Ada Lovelace",
+          "--company",
+          "acme",
+          "--hq-root",
+          tmpRoot,
+          "--json",
+        ],
+        { refreshRoster },
+      ),
+    ).rejects.toThrow("__exit__");
+
+    expect(refreshRoster).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual({
+      status: "not_found",
+    });
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Could not refresh people roster"),
+    );
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it("resolve --local-only skips refresh on a miss", async () => {
+    const refreshRoster = vi.fn<RefreshPeopleRoster>();
+    await expect(
+      run(
+        [
+          "people",
+          "resolve",
+          "Ada Lovelace",
+          "--company",
+          "acme",
+          "--hq-root",
+          tmpRoot,
+          "--json",
+          "--local-only",
+        ],
+        { refreshRoster },
+      ),
+    ).rejects.toThrow("__exit__");
+
+    expect(refreshRoster).not.toHaveBeenCalled();
+    expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toEqual({
+      status: "not_found",
+    });
+  });
+
   it("resolve exits non-zero when not found", async () => {
     await expect(
       run([

package/src/commands/people.ts

@@ -14,9 +14,17 @@
 import * as fs from "fs";
 import { Command, Option } from "commander";
 import chalk from "chalk";
+import { VaultClient } from "@indigoai-us/hq-cloud";
 import * as yaml from "js-yaml";
 import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath, type ManifestDoc } from "./cloud-provision.js";
+import {
+  DEFAULT_COGNITO,
+  buildVaultConfig,
+  ensureCognitoToken,
+} from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
+import { createCompanyPresignClient, runGet } from "./files-browse.js";
 import {
   assertSafeCompanySlug,
   listCompanyPeople,
@@ -31,6 +39,39 @@ interface PeopleScopeOpts {
   hqRoot?: string;
 }
 
+export type RefreshPeopleRoster = (
+  hqRoot: string,
+  companySlug: string,
+) => Promise<void>;
+
+interface PeopleCommandDeps {
+  refreshRoster?: RefreshPeopleRoster;
+}
+
+interface PeopleLookupOpts {
+  localOnly?: boolean;
+  json?: boolean;
+}
+
+export async function refreshPeopleRosterFromCloud(
+  hqRoot: string,
+  companySlug: string,
+): Promise<void> {
+  const accessToken = await ensureCognitoToken();
+  const client = new VaultClient(buildVaultConfig(accessToken));
+  await getCompanyUid(accessToken, companySlug);
+
+  await runGet({
+    path: `companies/${companySlug}/people/`,
+    hqRoot,
+    companySlug,
+    vaultClient: client,
+    companyClient: ({ companyUid }) =>
+      createCompanyPresignClient({ token: accessToken, companyUid }),
+    region: DEFAULT_COGNITO.region,
+  });
+}
+
 /** Companies that still exist (anything not explicitly `status: archived`). */
 function activeCompanySlugs(manifest: ManifestDoc): string[] {
   const companies = manifest.companies ?? {};
@@ -118,7 +159,82 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-export function registerPeopleCommand(program: Command): void {
+function logRefreshFailure(companySlug: string, err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(
+    chalk.dim(
+      `  Could not refresh people roster for '${companySlug}': ${message}`,
+    ),
+  );
+}
+
+async function tryRefreshRoster(
+  refreshRoster: RefreshPeopleRoster,
+  hqRoot: string,
+  slug: string,
+): Promise<boolean> {
+  try {
+    await refreshRoster(hqRoot, slug);
+    return true;
+  } catch (err) {
+    logRefreshFailure(slug, err);
+    return false;
+  }
+}
+
+export async function resolvePersonWithRosterFallback(
+  input: {
+    hqRoot: string;
+    slug: string;
+    name: string;
+    opts?: PeopleLookupOpts;
+    refreshRoster?: RefreshPeopleRoster;
+  },
+): Promise<ReturnType<typeof resolveNameToEmail>> {
+  const local = resolveNameToEmail(
+    listCompanyPeople(input.hqRoot, input.slug),
+    input.name,
+  );
+  if (local.status !== "not_found" || input.opts?.localOnly) return local;
+
+  const refreshed = await tryRefreshRoster(
+    input.refreshRoster ?? refreshPeopleRosterFromCloud,
+    input.hqRoot,
+    input.slug,
+  );
+  if (!refreshed) return local;
+  return resolveNameToEmail(
+    listCompanyPeople(input.hqRoot, input.slug),
+    input.name,
+  );
+}
+
+export async function searchPeopleWithRosterFallback(input: {
+  hqRoot: string;
+  slug: string;
+  keyword: string;
+  opts?: PeopleLookupOpts;
+  refreshRoster?: RefreshPeopleRoster;
+}): Promise<PersonRecord[]> {
+  const local = searchPeople(
+    listCompanyPeople(input.hqRoot, input.slug),
+    input.keyword,
+  );
+  if (local.length > 0 || input.opts?.localOnly) return local;
+
+  const refreshed = await tryRefreshRoster(
+    input.refreshRoster ?? refreshPeopleRosterFromCloud,
+    input.hqRoot,
+    input.slug,
+  );
+  if (!refreshed) return local;
+  return searchPeople(listCompanyPeople(input.hqRoot, input.slug), input.keyword);
+}
+
+export function registerPeopleCommand(
+  program: Command,
+  deps: PeopleCommandDeps = {},
+): void {
   const people = program
     .command("people")
     .description(
@@ -170,12 +286,22 @@ export function registerPeopleCommand(program: Command): void {
     .command("search <keyword>")
     .description("Keyword search over people names and emails")
     .option("--json", "Output JSON instead of a table")
-    .action((keyword: string, opts: { json?: boolean }) => {
+    .option(
+      "--local-only",
+      "Skip cloud fallback; search only the local people roster",
+    )
+    .action(async (keyword: string, opts: PeopleLookupOpts) => {
       try {
         const scope = people.opts() as PeopleScopeOpts;
         const hqRoot = resolveHqRoot(scope);
         const slug = resolveCompanySlug(hqRoot, scope.company);
-        const matches = searchPeople(listCompanyPeople(hqRoot, slug), keyword);
+        const matches = await searchPeopleWithRosterFallback({
+          hqRoot,
+          slug,
+          keyword,
+          opts,
+          refreshRoster: deps.refreshRoster,
+        });
 
         if (opts.json) {
           console.log(JSON.stringify(matches, null, 2));
@@ -195,12 +321,22 @@ export function registerPeopleCommand(program: Command): void {
     .command("resolve <name>")
     .description("Resolve a person name to their email address")
     .option("--json", "Output JSON instead of plain text")
-    .action((name: string, opts: { json?: boolean }) => {
+    .option(
+      "--local-only",
+      "Skip cloud fallback; resolve only from the local people roster",
+    )
+    .action(async (name: string, opts: PeopleLookupOpts) => {
       try {
         const scope = people.opts() as PeopleScopeOpts;
         const hqRoot = resolveHqRoot(scope);
         const slug = resolveCompanySlug(hqRoot, scope.company);
-        const result = resolveNameToEmail(listCompanyPeople(hqRoot, slug), name);
+        const result = await resolvePersonWithRosterFallback({
+          hqRoot,
+          slug,
+          name,
+          opts,
+          refreshRoster: deps.refreshRoster,
+        });
 
         if (opts.json) {
           console.log(JSON.stringify(result, null, 2));

package/src/commands/secrets-scope.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  describeSecretsScope,
+  formatSecretSaved,
+  formatSecretsListEmpty,
+  formatSecretsListHeader,
+} from "./secrets-scope.js";
+
+describe("describeSecretsScope", () => {
+  it("describes the personal vault", () => {
+    expect(
+      describeSecretsScope({ personal: true, companyUid: "prs_alice" }),
+    ).toBe("your personal vault");
+  });
+
+  it("describes a company by slug when present", () => {
+    expect(
+      describeSecretsScope({
+        personal: false,
+        companySlug: "acme",
+        companyUid: "cmp_01ABC",
+      }),
+    ).toBe("company acme");
+  });
+
+  it("describes a company by uid when no slug is present", () => {
+    expect(
+      describeSecretsScope({ personal: false, companyUid: "cmp_01ABC" }),
+    ).toBe("company cmp_01ABC");
+  });
+});
+
+describe("formatSecretSaved", () => {
+  it("formats the set echo", () => {
+    expect(formatSecretSaved("MY_KEY", "your personal vault")).toBe(
+      "Secret 'MY_KEY' saved to your personal vault.",
+    );
+  });
+});
+
+describe("formatSecretsListHeader", () => {
+  it("formats the list header", () => {
+    expect(formatSecretsListHeader("company acme")).toBe(
+      "Secrets for company acme:",
+    );
+  });
+});
+
+describe("formatSecretsListEmpty", () => {
+  it("formats the empty list message", () => {
+    expect(formatSecretsListEmpty("your personal vault")).toBe(
+      "No secrets found for your personal vault.",
+    );
+  });
+});

package/src/commands/secrets-scope.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure helpers describing WHICH secrets scope a command acted on, so `set` and
+ * `list` can echo it. Users were setting a secret in one scope (personal vs a
+ * company, or company A vs B) and listing another, then seeing "no secrets" with
+ * no indication the scopes differed (feedback_70e059da).
+ */
+export interface SecretsScopeRef {
+  /** True when --personal was used (caller's personal vault). */
+  personal: boolean;
+  /** The slug the user passed via --company, if any. */
+  companySlug?: string;
+  /** Resolved entity uid: prs_* for personal, cmp_* for a company. */
+  companyUid: string;
+}
+
+/** Human label for a secrets scope: "your personal vault" or "company <slug-or-uid>". */
+export function describeSecretsScope(ref: SecretsScopeRef): string {
+  if (ref.personal) return "your personal vault";
+  return `company ${ref.companySlug ?? ref.companyUid}`;
+}
+
+export function formatSecretSaved(name: string, scope: string): string {
+  return `Secret '${name}' saved to ${scope}.`;
+}
+
+export function formatSecretsListHeader(scope: string): string {
+  return `Secrets for ${scope}:`;
+}
+
+export function formatSecretsListEmpty(scope: string): string {
+  return `No secrets found for ${scope}.`;
+}

package/src/commands/secrets.ts

@@ -13,6 +13,12 @@ import {
 } from "../utils/secrets-cache.js";
 import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN } from "./_patterns.js";
+import {
+  describeSecretsScope,
+  formatSecretSaved,
+  formatSecretsListEmpty,
+  formatSecretsListHeader,
+} from "./secrets-scope.js";
 import {
   vaultApiFetch,
   getCompanyUid,
@@ -506,10 +512,13 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companyUid = await getEntityUid(
-          token,
-          scopeOpts(secrets.opts()),
-        );
+        const scope = scopeOpts(secrets.opts());
+        const companyUid = await getEntityUid(token, scope);
+        const scopeLabel = describeSecretsScope({
+          personal: scope.personal,
+          companySlug: scope.companySlug,
+          companyUid,
+        });
 
         const res = await vaultApiFetch({
           token,
@@ -527,7 +536,7 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         removeCacheEntry(companyUid, name);
-        console.log(chalk.green(`Secret '${name}' saved.`));
+        console.log(chalk.green(formatSecretSaved(name, scopeLabel)));
       } catch (err) {
         console.error(
           chalk.red("Error:"),
@@ -703,10 +712,13 @@ export function registerSecretsCommand(program: Command): void {
         }
 
         const token = await ensureCognitoToken();
-        const companyUid = await getEntityUid(
-          token,
-          scopeOpts(secrets.opts()),
-        );
+        const scope = scopeOpts(secrets.opts());
+        const companyUid = await getEntityUid(token, scope);
+        const scopeLabel = describeSecretsScope({
+          personal: scope.personal,
+          companySlug: scope.companySlug,
+          companyUid,
+        });
 
         const query: Record<string, string> = {};
         if (normalizedPrefix) {
@@ -739,7 +751,7 @@ export function registerSecretsCommand(program: Command): void {
         };
 
         if (data.secrets.length === 0) {
-          console.log(chalk.dim("No secrets found."));
+          console.log(chalk.dim(formatSecretsListEmpty(scopeLabel)));
           return;
         }
 
@@ -756,6 +768,7 @@ export function registerSecretsCommand(program: Command): void {
         if (hasPermission) {
           const accessWidth = Math.max(6, ...data.secrets.map((s) => (s.permission ?? "-").length));
           const header = `${"NAME".padEnd(nameWidth)}  ${"ACCESS".padEnd(accessWidth)}  ${"TIER".padEnd(tierWidth)}  ${"SCRIPT LOCK".padEnd(scriptLockWidth)}  LAST MODIFIED`;
+          console.log(chalk.dim(formatSecretsListHeader(scopeLabel)));
           console.log(chalk.bold(header));
           for (const s of data.secrets) {
             const access = s.permission ?? "-";
@@ -766,6 +779,7 @@ export function registerSecretsCommand(program: Command): void {
           }
         } else {
           const header = `${"NAME".padEnd(nameWidth)}  ${"TIER".padEnd(tierWidth)}  ${"SCRIPT LOCK".padEnd(scriptLockWidth)}  LAST MODIFIED`;
+          console.log(chalk.dim(formatSecretsListHeader(scopeLabel)));
           console.log(chalk.bold(header));
           for (const s of data.secrets) {
             const tier = normalizeSecretTier(s.tier);

package/src/index.ts

@@ -4,6 +4,9 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
+// MUST be first: guard the Node version before any dependency that needs a
+// Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
+import "./node-preflight.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -47,6 +50,8 @@ import { registerRescueCommand } from "./commands/rescue.js";
 import { registerMcpCommand } from "./commands/mcp-status.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { isEpipe } from "./utils/epipe.js";
+import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import {
   maybeWarnNewVersion,
   refreshVersionCache,
@@ -57,9 +62,13 @@ import {
 } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 
-// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes the pipe early.
+// 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
+// stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
+// console.log inside a command) is handled in the top-level catch below; both
+// share `isEpipe` (HQ-6B).
 const onPipeError = (err: NodeJS.ErrnoException): void => {
-  if (err.code === "EPIPE") {
+  if (isEpipe(err)) {
     process.exit(0);
   }
   throw err;
@@ -222,18 +231,37 @@ registerMcpCommand(program);
     }
     await program.parseAsync();
   } catch (err) {
-    // A full disk / exhausted quota / read-only filesystem is the user's
-    // machine, not an HQ code defect. Surface a clear, actionable message and
-    // skip Sentry capture so one full disk doesn't flood the tracker with
-    // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
-    // to Sentry and still exit 1.
-    const envMsg = environmentalFsErrorMessage(err);
-    if (envMsg) {
-      process.stderr.write(`hq: ${envMsg}\n`);
+    // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
+    // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
+    // Unix behavior with no user-facing degradation — exit cleanly (0) and
+    // skip Sentry capture instead of shipping a fatal (HQ-6B). A synchronous
+    // `write EPIPE` thrown out of console.log lands here rather than on the
+    // stream 'error' listener above.
+    if (isEpipe(err)) {
+      process.exitCode = 0;
+    } else if (isInterceptedProcessExit(err)) {
+      // A security/audit FUZZ harness replaced `process.exit` with a throw so it
+      // can keep exercising the binary. Commander calling `process.exit` for
+      // normal CLI control flow (e.g. an unknown command → exit 1) then surfaces
+      // here as that synthetic marker. It is a test-harness artifact, NOT an
+      // hq-cli defect — a real user's `process.exit` just exits, so nothing is
+      // thrown or captured. Skip Sentry capture (no signal, no user-facing
+      // degradation) and preserve the intended non-zero exit (HQ-CLI-3).
+      process.exitCode = 1;
     } else {
-      Sentry.captureException(err);
+      // A full disk / exhausted quota / read-only filesystem is the user's
+      // machine, not an HQ code defect. Surface a clear, actionable message and
+      // skip Sentry capture so one full disk doesn't flood the tracker with
+      // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+      // to Sentry and still exit 1.
+      const envMsg = environmentalFsErrorMessage(err);
+      if (envMsg) {
+        process.stderr.write(`hq: ${envMsg}\n`);
+      } else {
+        Sentry.captureException(err);
+      }
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
   } finally {
     // Release health: finalize the per-run session before the flush.
     Sentry.endSession();