@indigoai-us/hq-cli 5.55.0 → 5.57.0

package/package.json

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

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

@@ -82,6 +82,7 @@ function makeShareSpy(
         bytesUploaded: 0,
         filesSkipped: 0,
         filesDeleted: 0,
+        filesExcludedByScope: 0,
         conflictPaths: [],
         aborted: false,
         ...override,
@@ -307,6 +308,7 @@ describe("pushAll", () => {
       filesUploaded: 0,
       bytesUploaded: 0,
       filesDeleted: 0,
+      filesExcludedByScope: 0,
       errors: [],
       perCompany: [],
     });
@@ -379,6 +381,33 @@ describe("pushAll", () => {
     expect(result.filesDeleted).toBe(4);
   });
 
+  it("aggregates filesExcludedByScope across every successful target", async () => {
+    const hqRoot = makeHqRoot(["companies", "docs"]);
+    const vaultClient = makeVaultClient({
+      memberships: [{ companyUid: "cmp_acme" }],
+      persons: [
+        {
+          uid: "psn_alice",
+          type: "person",
+          slug: "alice",
+          createdAt: "2026-01-01T00:00:00Z",
+        },
+      ],
+      entitiesBySlug: { cmp_acme: { slug: "acme" } },
+    });
+    const share = makeShareSpy({
+      cmp_acme: { filesExcludedByScope: 2 },
+      psn_alice: { filesExcludedByScope: 3 },
+    });
+
+    const result = await pushAll(
+      { hqRoot },
+      { vaultClient, share: share.fn },
+    );
+
+    expect(result.filesExcludedByScope).toBe(5);
+  });
+
   // ── skipPersonal — fanout omits the canonical-person leg ──────────────────
   //
   // Symmetric with the `pullAll` skipPersonal coverage in

package/src/commands/cloud.scope-excluded-warning.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+
+import { scopeExcludedWarning } from "./cloud.js";
+
+describe("scopeExcludedWarning", () => {
+  it("returns null for zero and negative counts", () => {
+    expect(scopeExcludedWarning(0)).toBeNull();
+    expect(scopeExcludedWarning(-1)).toBeNull();
+  });
+
+  it("returns a loud warning for positive counts", () => {
+    const warning = scopeExcludedWarning(3);
+
+    expect(warning).toBeTruthy();
+    expect(warning).toContain("3");
+    // The warning must loudly state the files did NOT reach the vault and
+    // explain why (outside the caller's write access) — without leaning on
+    // the jargon word "scope" in user-facing copy.
+    expect(warning).toContain("NOT uploaded");
+    expect(warning?.toLowerCase()).toContain("write access");
+  });
+});

package/src/commands/cloud.ts

@@ -50,6 +50,22 @@ import {
   type BannerLevel,
 } from "../lib/narrow-hint-banner.js";
 
+/**
+ * Build a loud, human-readable warning when a push dropped files because
+ * they fell outside the caller's granted write scope. Returns null when
+ * nothing was scope-excluded. Keeping this pure makes the "never silently
+ * succeed when files were dropped" guarantee unit-testable.
+ */
+export function scopeExcludedWarning(count: number): string | null {
+  if (count <= 0) return null;
+  return (
+    `⚠ ${count} file(s) were NOT uploaded — they fall outside the ` +
+    `prefixes you have write access to (company-wide or direct grants). ` +
+    `They were skipped, not synced. Re-run with --json to list them, or ` +
+    `ask an admin to grant you write on those paths.`
+  );
+}
+
 /**
  * Resolve the `propagateDeletePolicy` for share() calls.
  *
@@ -234,6 +250,7 @@ export interface ShareCallResult {
   bytesUploaded: number;
   filesSkipped: number;
   filesDeleted: number;
+  filesExcludedByScope: number;
   conflictPaths: string[];
   aborted: boolean;
 }
@@ -267,6 +284,7 @@ export interface PushAllResult {
   filesUploaded: number;
   bytesUploaded: number;
   filesDeleted: number;
+  filesExcludedByScope: number;
   errors: Array<{ company: string; message: string }>;
   perCompany: PushAllRow[];
 }
@@ -513,6 +531,7 @@ export async function pushAll(
     filesUploaded: 0,
     bytesUploaded: 0,
     filesDeleted: 0,
+    filesExcludedByScope: 0,
     errors: [],
     perCompany: [],
   };
@@ -524,6 +543,7 @@ export async function pushAll(
       result.filesUploaded += r.filesUploaded;
       result.bytesUploaded += r.bytesUploaded;
       result.filesDeleted += r.filesDeleted;
+      result.filesExcludedByScope += r.filesExcludedByScope;
       result.perCompany.push({ slug: entry.slug, result: r });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -1016,11 +1036,21 @@ export function registerCloudCommands(program: Command): void {
             process.exit(1);
           }
 
-          log(
-            chalk.green(
-              `\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`,
-            ),
-          );
+          if (result.filesExcludedByScope > 0) {
+            log(
+              chalk.yellow(
+                `\n⚠ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ` +
+                  `${result.filesSkipped} skipped, ${result.filesExcludedByScope} scope-excluded)`,
+              ),
+            );
+            log(chalk.yellow(scopeExcludedWarning(result.filesExcludedByScope)!));
+          } else {
+            log(
+              chalk.green(
+                `\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`,
+              ),
+            );
+          }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           if (jsonMode) {
@@ -1657,11 +1687,15 @@ async function runPushAll(
       console.log(chalk.red(`  ✗ ${row.slug}: ${row.error}`));
     } else if (row.result) {
       const r = row.result;
-      const status = r.aborted ? chalk.yellow("⚠") : chalk.green("✓");
+      const status =
+        r.aborted || r.filesExcludedByScope > 0
+          ? chalk.yellow("⚠")
+          : chalk.green("✓");
       console.log(
         `  ${status} ${row.slug}: ${r.filesUploaded} file(s), ` +
           `${formatBytes(r.bytesUploaded)}, ${r.filesSkipped} skipped, ` +
-          `${r.filesDeleted} deleted, ${r.conflictPaths.length} conflict(s)` +
+          `${r.filesDeleted} deleted, ${r.filesExcludedByScope} scope-excluded, ` +
+          `${r.conflictPaths.length} conflict(s)` +
           (r.aborted ? " — aborted" : ""),
       );
     }
@@ -1671,8 +1705,16 @@ async function runPushAll(
   const summary =
     `\nPushed ${result.filesUploaded} file(s) ` +
     `(${formatBytes(result.bytesUploaded)}) across ${result.attempted} ` +
-    `target(s); ${result.filesDeleted} deleted; ${errored} error(s)`;
-  console.log(errored > 0 ? chalk.yellow(summary) : chalk.green(summary));
+    `target(s); ${result.filesDeleted} deleted; ${errored} error(s); ` +
+    `${result.filesExcludedByScope} scope-excluded`;
+  console.log(
+    errored > 0 || result.filesExcludedByScope > 0
+      ? chalk.yellow(summary)
+      : chalk.green(summary),
+  );
+  if (result.filesExcludedByScope > 0) {
+    console.log(chalk.yellow(scopeExcludedWarning(result.filesExcludedByScope)!));
+  }
   if (errored > 0) process.exit(1);
 }
 
@@ -1747,12 +1789,19 @@ async function runNowSingle(
       ...(journalSlug !== undefined ? { journalSlug } : {}),
       ...(author ? { author } : {}),
     });
+    const pushStatus =
+      pushResult.aborted || pushResult.filesExcludedByScope > 0
+        ? chalk.yellow("⚠")
+        : chalk.green("✓");
     console.log(
-      `    ${pushResult.aborted ? chalk.yellow("⚠") : chalk.green("✓")} ` +
+      `    ${pushStatus} ` +
         `${pushResult.filesUploaded} uploaded, ${pushResult.filesSkipped} skipped, ` +
-        `${pushResult.filesDeleted} deleted` +
+        `${pushResult.filesDeleted} deleted, ${pushResult.filesExcludedByScope} scope-excluded` +
         (pushResult.aborted ? " — aborted" : ""),
     );
+    if (pushResult.filesExcludedByScope > 0) {
+      console.log(chalk.yellow(scopeExcludedWarning(pushResult.filesExcludedByScope)!));
+    }
     if (pushResult.aborted) {
       console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
       process.exit(1);

package/src/commands/groups.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Unit tests for `hq groups` principal detection (groups.ts).
+ *
+ * Regression coverage for feedback_edb1796a-24be-4b9f-bc60-a06f39d1c9f2:
+ * `hq groups add` rejected agent identities (agt_<ULID>), forcing per-agent
+ * secret shares instead of group-carried ACLs. Agent uids ride the same
+ * personUid wire slot as people (server contract — the group-members handler
+ * accepts granteeType "person" with an agt_* granteeId, and every ACL
+ * evaluation keys off caller.personUid, which for agent JWTs IS the agt_ uid).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { detectPrincipalType } from "./groups.js";
+
+describe("detectPrincipalType", () => {
+  it("detects an email principal and normalizes it", () => {
+    expect(detectPrincipalType("Jane@Example.COM")).toEqual({
+      granteeType: "email",
+      granteeId: "jane@example.com",
+    });
+  });
+
+  it("detects a personUid principal", () => {
+    expect(detectPrincipalType("prs_01ABCDEF")).toEqual({
+      granteeType: "person",
+      granteeId: "prs_01ABCDEF",
+    });
+  });
+
+  it("detects an agentUid principal and sends it in the person slot (regression)", () => {
+    expect(detectPrincipalType("agt_01KWFVWZYX8H1DN57ZPNZNKM6C")).toEqual({
+      granteeType: "person",
+      granteeId: "agt_01KWFVWZYX8H1DN57ZPNZNKM6C",
+    });
+  });
+
+  it("rejects malformed principals", () => {
+    expect(detectPrincipalType("agt_")).toBeNull();
+    expect(detectPrincipalType("prs_")).toBeNull();
+    expect(detectPrincipalType("grp_finance")).toBeNull();
+    expect(detectPrincipalType("not a principal")).toBeNull();
+  });
+});

package/src/commands/groups.ts

@@ -6,8 +6,12 @@ import { GROUP_ID_PATTERN } from "./_patterns.js";
 
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
 
-function detectPrincipalType(
+const INVALID_PRINCIPAL_HINT =
+  "must be an email address, a personUid (prs_…), or an agentUid (agt_…)";
+
+export function detectPrincipalType(
   principal: string,
 ): { granteeType: "email" | "person"; granteeId: string } | null {
   if (EMAIL_PATTERN.test(principal)) {
@@ -15,7 +19,10 @@ function detectPrincipalType(
     // cache keys agree with the server-side canonicalization.
     return { granteeType: "email", granteeId: principal.trim().toLowerCase() };
   }
-  if (PERSON_UID_PATTERN.test(principal)) {
+  // Agent uids ride the same personUid wire slot as people — that is the
+  // server contract (group members, DM recipients, and memberships all carry
+  // agt_* in the personUid field; see hq-pro handlers).
+  if (PERSON_UID_PATTERN.test(principal) || AGENT_UID_PATTERN.test(principal)) {
     return { granteeType: "person", granteeId: principal };
   }
   return null;
@@ -130,7 +137,7 @@ export function registerGroupsCommand(program: Command): void {
 
   groups
     .command("add <groupId> <principal>")
-    .description("Add a person to a group (principal: email or personUid)")
+    .description("Add a person or agent to a group (principal: email, personUid, or agentUid)")
     .action(async (groupId: string, principal: string) => {
       try {
         if (!GROUP_ID_PATTERN.test(groupId)) {
@@ -140,7 +147,7 @@ export function registerGroupsCommand(program: Command): void {
 
         const detected = detectPrincipalType(principal);
         if (!detected) {
-          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a personUid matching prs_<alphanumeric>`));
+          console.error(chalk.red(`Invalid principal '${principal}': ${INVALID_PRINCIPAL_HINT}`));
           process.exit(1);
         }
 
@@ -181,7 +188,7 @@ export function registerGroupsCommand(program: Command): void {
 
   groups
     .command("remove <groupId> <principal>")
-    .description("Remove a person from a group (principal: email or personUid)")
+    .description("Remove a person or agent from a group (principal: email, personUid, or agentUid)")
     .action(async (groupId: string, principal: string) => {
       try {
         if (!GROUP_ID_PATTERN.test(groupId)) {
@@ -191,7 +198,7 @@ export function registerGroupsCommand(program: Command): void {
 
         const detected = detectPrincipalType(principal);
         if (!detected) {
-          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a personUid matching prs_<alphanumeric>`));
+          console.error(chalk.red(`Invalid principal '${principal}': ${INVALID_PRINCIPAL_HINT}`));
           process.exit(1);
         }
 

package/src/commands/meetings.test.ts

@@ -65,6 +65,85 @@ function jsonRes(body: unknown, status = 200): Response {
   });
 }
 
+describe("meetings get — short id resolution", () => {
+  it("resolves an 8-char short id to the full id before calling the by-id endpoint", async () => {
+    const fullId = "589bfd78-aaaa-bbbb-cccc-1234567890ab";
+    vi.mocked(vaultApiFetch)
+      .mockResolvedValueOnce(
+        jsonRes({
+          meetings: [
+            {
+              meetingId: fullId,
+              title: "T",
+              status: "ready",
+              startTime: "2026-01-01T00:00:00Z",
+              endTime: "2026-01-01T00:00:00Z",
+              duration: 0,
+              participantCount: 0,
+              hasTranscript: false,
+              hasNotes: false,
+            },
+          ],
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonRes({
+          meetingId: fullId,
+          title: "T",
+          startTime: "2026-01-01T00:00:00Z",
+          endTime: "2026-01-01T00:00:00Z",
+          duration: 0,
+          participants: [],
+          calendarEventId: null,
+          botProvider: "recall",
+          sourceApp: "calendar",
+          companyId: "cmp_acme",
+          status: "ready",
+          recallBotId: null,
+          isShared: false,
+          createdAt: "2026-01-01T00:00:00Z",
+          updatedAt: "2026-01-01T00:00:00Z",
+          documentUrl: "",
+          hasTranscript: false,
+          hasNotes: false,
+        }),
+      );
+
+    const program = buildProgram();
+    await program.parseAsync(["node", "hq", "meetings", "get", "589bfd78"]);
+
+    expect(vaultApiFetch).toHaveBeenNthCalledWith(1, {
+      token: "test-token",
+      path: "/v1/meetings",
+      query: { limit: "500" },
+    });
+    expect(vaultApiFetch).toHaveBeenNthCalledWith(2, {
+      token: "test-token",
+      path: `/v1/meetings/${fullId}`,
+      query: {},
+    });
+  });
+
+  it("errors and never sends the truncated id when the short id matches no meeting", async () => {
+    vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit");
+    }) as never);
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(jsonRes({ meetings: [] }));
+
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["node", "hq", "meetings", "get", "589bfd78"]),
+    ).rejects.toThrow("process.exit");
+
+    expect(errSpy).toHaveBeenCalledWith(
+      expect.stringContaining("No meeting matches ID \"589bfd78\""),
+    );
+    expect(vaultApiFetch).not.toHaveBeenCalledWith(
+      expect.objectContaining({ path: "/v1/meetings/589bfd78" }),
+    );
+  });
+});
+
 describe("meetings set-company", () => {
   it("POSTs the resolved company id and applies to the recurring series by default", async () => {
     vi.mocked(vaultApiFetch).mockResolvedValueOnce(
@@ -225,3 +304,49 @@ describe("meetings set-company", () => {
     expect(output).not.toContain("Future occurrences of this recurring series will inherit this attribution.");
   });
 });
+
+describe("meetings list — null-safe rendering", () => {
+  it("does not crash when a meeting has an undefined or null title", async () => {
+    // The API can return meetings with a missing/null title even though the
+    // type says string. This list previously crashed with
+    // "Cannot read properties of undefined (reading 'length')" after printing
+    // the header. Assert the command completes and renders a placeholder.
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonRes({
+        meetings: [
+          {
+            meetingId: "589bfd78-aaaa-bbbb-cccc-1234567890ab",
+            // title intentionally omitted (undefined)
+            status: "ready",
+            startTime: "2026-01-01T00:00:00Z",
+            endTime: "2026-01-01T00:30:00Z",
+            duration: 1800,
+            participantCount: 3,
+            hasTranscript: true,
+            hasNotes: false,
+          },
+          {
+            meetingId: "689bfd78-aaaa-bbbb-cccc-1234567890ab",
+            title: null,
+            status: "ready",
+            startTime: "2026-01-02T00:00:00Z",
+            endTime: "2026-01-02T00:30:00Z",
+            duration: 1800,
+            participantCount: 1,
+            hasTranscript: false,
+            hasNotes: true,
+          },
+        ],
+      }),
+    );
+
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["node", "hq", "meetings", "list", "--company", "indigo"]),
+    ).resolves.toBeDefined();
+
+    const printed = logSpy.mock.calls.map(([line]) => String(line)).join("\n");
+    expect(printed).toContain("Meetings (2)");
+    expect(printed).toContain("(untitled)");
+  });
+});

package/src/commands/meetings.ts

@@ -105,8 +105,16 @@ async function resolveShortId(
   query: Record<string, string>,
 ): Promise<string> {
   if (prefix.includes("-") && prefix.length > 8) return prefix;
-  const res = await vaultApiFetch({ token, path: "/v1/meetings", query });
-  if (!res.ok) return prefix;
+  const res = await vaultApiFetch({
+    token,
+    path: "/v1/meetings",
+    query: { ...query, limit: "500" },
+  });
+  if (!res.ok) {
+    throw new Error(
+      `Could not resolve meeting ID "${prefix}" — failed to list meetings (${res.status}). Pass the full meeting id.`,
+    );
+  }
   const data = (await res.json()) as { meetings: MeetingListItem[] };
   const matches = data.meetings.filter((m) => m.meetingId.startsWith(prefix));
   if (matches.length === 1) return matches[0].meetingId;
@@ -114,7 +122,12 @@ async function resolveShortId(
     console.error(chalk.red(`Ambiguous ID prefix "${prefix}" — matches ${matches.length} meetings. Use a longer prefix.`));
     process.exit(1);
   }
-  return prefix;
+  console.error(
+    chalk.red(
+      `No meeting matches ID "${prefix}". It may be older than the meetings shown by \`hq meetings list\`, still processing, or attributed to a different company. Pass the full meeting id, add --company <slug>, or widen the list with \`hq meetings list --limit <n>\`.`,
+    ),
+  );
+  process.exit(1);
 }
 
 async function handleApiError(res: Response): Promise<never> {
@@ -137,8 +150,13 @@ function printMeetingTable(meetings: MeetingListItem[]): void {
     return;
   }
 
+  // Titles can come back null/undefined from the API even though the type says
+  // string; fall back to a placeholder so width calc + rendering never crash on
+  // `undefined.length`.
+  const displayTitle = (m: MeetingListItem): string => m.title ?? "(untitled)";
+
   const ID_W = 8;
-  const TITLE_W = Math.min(40, Math.max(10, ...meetings.map((m) => m.title.length)));
+  const TITLE_W = Math.min(40, Math.max(10, ...meetings.map((m) => displayTitle(m).length)));
   const DATE_W = 16;
   const DUR_W = 8;
   const STATUS_W = 12;
@@ -161,7 +179,8 @@ function printMeetingTable(meetings: MeetingListItem[]): void {
 
   for (const m of meetings) {
     const id = m.meetingId.slice(0, 8);
-    const title = m.title.length > TITLE_W ? m.title.slice(0, TITLE_W - 1) + "…" : m.title;
+    const fullTitle = displayTitle(m);
+    const title = fullTitle.length > TITLE_W ? fullTitle.slice(0, TITLE_W - 1) + "…" : fullTitle;
     const date = new Date(m.startTime).toLocaleDateString("en-US", {
       month: "short",
       day: "numeric",