@indigoai-us/hq-cli 5.25.1 → 5.28.0

package/src/commands/dm.ts

@@ -0,0 +1,222 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { readFileSync } from "node:fs";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+
+const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
+const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+
+export interface DmRecipient {
+  toEmail?: string;
+  toPersonUid?: string;
+}
+
+/**
+ * Classify a recipient arg as an email or a personUid. Mirrors the
+ * email/prs_ heuristic used by `hq members`. Returns null for neither.
+ */
+export function detectRecipient(recipient: string): DmRecipient | null {
+  const r = recipient.trim();
+  if (EMAIL_PATTERN.test(r)) return { toEmail: r.toLowerCase() };
+  if (PERSON_UID_PATTERN.test(r)) return { toPersonUid: r };
+  return null;
+}
+
+/**
+ * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
+ * Returns null on anything that doesn't match. Pure → unit-testable.
+ */
+export function parseDuration(input: string): number | null {
+  const m = /^(\d+)\s*(s|m|h|d)$/.exec(input.trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  const mult: Record<string, number> = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+  };
+  return n * mult[m[2]];
+}
+
+export interface DmSendBody {
+  toEmail?: string;
+  toPersonUid?: string;
+  body: string;
+  prompt?: string;
+  details?: string;
+  deliverAt?: string;
+}
+
+/**
+ * Build the POST /v1/notify/dm request body from CLI inputs. Pure (no I/O,
+ * no clock) so the option-resolution logic is unit-testable; the caller
+ * supplies `now` for the `--in` relative-delay computation.
+ *
+ * Throws Error with a user-facing message on invalid input.
+ */
+export function buildDmBody(args: {
+  recipient: string;
+  message: string;
+  prompt?: string;
+  details?: string;
+  at?: string;
+  inDelay?: string;
+  now: number;
+}): DmSendBody {
+  const rcpt = detectRecipient(args.recipient);
+  if (!rcpt) {
+    throw new Error(
+      `Invalid recipient '${args.recipient}': must be an email address or a personUid (prs_…).`,
+    );
+  }
+  const body = (args.message ?? "").trim();
+  if (!body) {
+    throw new Error("A message body is required: hq dm <recipient> <message>");
+  }
+
+  if (args.at && args.inDelay) {
+    throw new Error("Use only one of --at or --in, not both.");
+  }
+  let deliverAt: string | undefined;
+  if (args.at) {
+    const when = new Date(args.at);
+    if (isNaN(when.getTime())) {
+      throw new Error(`Invalid --at '${args.at}': must be an ISO8601 date.`);
+    }
+    deliverAt = when.toISOString();
+  } else if (args.inDelay) {
+    const ms = parseDuration(args.inDelay);
+    if (ms === null) {
+      throw new Error(
+        `Invalid --in '${args.inDelay}': use a relative delay like 30s, 10m, 2h, 1d.`,
+      );
+    }
+    deliverAt = new Date(args.now + ms).toISOString();
+  }
+
+  const prompt = args.prompt?.trim();
+  const details = args.details?.trim();
+
+  return {
+    ...rcpt,
+    body,
+    ...(prompt ? { prompt } : {}),
+    ...(details ? { details } : {}),
+    ...(deliverAt ? { deliverAt } : {}),
+  };
+}
+
+function friendlyDmError(status: number, code: string | undefined, fallback: string): string {
+  if (status === 401) return "Not authenticated — run `hq login` and try again.";
+  if (status === 404 || code === "RECIPIENT_NOT_FOUND") {
+    return "Recipient not found or not reachable — you can only DM someone you share an active company with.";
+  }
+  if (status >= 500) return `Server error: ${fallback}`;
+  return fallback;
+}
+
+export function registerDmCommand(program: Command): void {
+  program
+    .command("dm <recipient> [message]")
+    .description(
+      "Send a direct message to a teammate (email or personUid). They receive it as an HQ Sync notification.",
+    )
+    .option(
+      "--prompt <text>",
+      "Agent-context prompt the recipient can one-click copy into their agent",
+    )
+    .option("--prompt-file <path>", "Read the agent prompt from a file")
+    .option(
+      "--details <text>",
+      "Longer detail shown in the recipient's DM detail window",
+    )
+    .option("--details-file <path>", "Read the details from a file")
+    .option(
+      "--at <iso>",
+      "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time)",
+    )
+    .option(
+      "--in <duration>",
+      "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d",
+    )
+    .action(
+      async (
+        recipient: string,
+        message: string | undefined,
+        opts: {
+          prompt?: string;
+          promptFile?: string;
+          details?: string;
+          detailsFile?: string;
+          at?: string;
+          in?: string;
+        },
+      ) => {
+        try {
+          // Resolve prompt/details from inline text or a file.
+          let prompt = opts.prompt;
+          if (opts.promptFile) prompt = readFileSync(opts.promptFile, "utf8");
+          let details = opts.details;
+          if (opts.detailsFile) details = readFileSync(opts.detailsFile, "utf8");
+
+          const reqBody = buildDmBody({
+            recipient,
+            message: message ?? "",
+            prompt,
+            details,
+            at: opts.at,
+            inDelay: opts.in,
+            now: Date.now(),
+          });
+
+          const token = await ensureCognitoToken();
+          const res = await vaultApiFetch({
+            token,
+            path: "/v1/notify/dm",
+            method: "POST",
+            body: reqBody as unknown as Record<string, unknown>,
+          });
+
+          if (!res.ok) {
+            const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+            console.error(
+              chalk.red(
+                friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+              ),
+            );
+            process.exit(1);
+          }
+
+          const data = (await res.json()) as {
+            eventId?: string;
+            createdAt?: string;
+            scheduled?: boolean;
+            deliverAt?: string;
+          };
+
+          if (data.scheduled) {
+            console.log(
+              chalk.green(
+                `Scheduled DM to ${recipient} for ${data.deliverAt} (eventId ${data.eventId}).`,
+              ),
+            );
+            console.log(
+              chalk.dim("It delivers within ~60s of that time, even if you're offline."),
+            );
+          } else {
+            console.log(
+              chalk.green(`DM sent to ${recipient} (eventId ${data.eventId}).`),
+            );
+          }
+        } catch (err) {
+          console.error(
+            chalk.red("Error:"),
+            err instanceof Error ? err.message : String(err),
+          );
+          process.exit(1);
+        }
+      },
+    );
+}

package/src/commands/files-browse.test.ts

@@ -27,8 +27,11 @@ import {
   parseCompanySlugFromPath,
   runBrowse,
   runCat,
+  runSharedWithMe,
+  formatSharedWithMeTable,
   type FilesBrowseS3Client,
   type FilesBrowseVaultClient,
+  type FilesSharedWithMeVaultClient,
   type S3ClientFactory,
 } from "./files-browse.js";
 import type { ExplicitGrant, VendResult } from "@indigoai-us/hq-cloud";
@@ -685,3 +688,89 @@ describe("runCat", () => {
     ).rejects.toThrow(/personalMode requires personalUid/);
   });
 });
+
+// ── runSharedWithMe ──────────────────────────────────────────────────────────
+
+function sharedWithMeClient(opts: {
+  memberships?: Array<{ companyUid: string }>;
+  grantsByCompany?: Record<string, ExplicitGrant[]>;
+  slugByUid?: Record<string, string>;
+}): FilesSharedWithMeVaultClient {
+  return {
+    listMyMemberships: async () => opts.memberships ?? [],
+    listMyExplicitGrants: async (companyUid: string) =>
+      opts.grantsByCompany?.[companyUid] ?? [],
+    entity: {
+      get: async (uid: string) => ({
+        uid,
+        slug: opts.slugByUid?.[uid] ?? uid,
+      }),
+    },
+  };
+}
+
+describe("runSharedWithMe", () => {
+  it("lists explicit grants for a single company (companyUid supplied)", async () => {
+    const rows = await runSharedWithMe({
+      vaultClient: sharedWithMeClient({
+        grantsByCompany: {
+          cmp_indigo: [fakeGrant("knowledge/"), fakeGrant("reports/q3.pdf")],
+        },
+      }),
+      companyUid: "cmp_indigo",
+      companySlug: "indigo",
+    });
+    expect(rows).toEqual([
+      { companySlug: "indigo", path: "knowledge/", permission: "read", source: "person" },
+      { companySlug: "indigo", path: "reports/q3.pdf", permission: "read", source: "person" },
+    ]);
+  });
+
+  it("rolls up across every membership when no company is supplied", async () => {
+    const rows = await runSharedWithMe({
+      vaultClient: sharedWithMeClient({
+        memberships: [{ companyUid: "cmp_b" }, { companyUid: "cmp_a" }],
+        slugByUid: { cmp_a: "acme", cmp_b: "beta" },
+        grantsByCompany: {
+          cmp_a: [fakeGrant("docs/")],
+          cmp_b: [fakeGrant("shared/")],
+        },
+      }),
+    });
+    // Sorted by company slug, then path.
+    expect(rows.map((r) => [r.companySlug, r.path])).toEqual([
+      ["acme", "docs/"],
+      ["beta", "shared/"],
+    ]);
+  });
+
+  it("skips a company whose grant fetch throws (best-effort roll-up)", async () => {
+    const client: FilesSharedWithMeVaultClient = {
+      listMyMemberships: async () => [{ companyUid: "cmp_ok" }, { companyUid: "cmp_bad" }],
+      listMyExplicitGrants: async (uid: string) => {
+        if (uid === "cmp_bad") throw new Error("boom");
+        return [fakeGrant("ok/")];
+      },
+      entity: { get: async (uid: string) => ({ uid, slug: uid }) },
+    };
+    const rows = await runSharedWithMe({ vaultClient: client });
+    expect(rows).toEqual([
+      { companySlug: "cmp_ok", path: "ok/", permission: "read", source: "person" },
+    ]);
+  });
+
+  it("formats an empty result with the role-bypass caveat", () => {
+    const out = formatSharedWithMeTable([]);
+    expect(out).toContain("Nothing is explicitly shared with you");
+    expect(out).toContain("role-bypass");
+  });
+
+  it("formats rows as a table with company + path + permission + source", () => {
+    const out = formatSharedWithMeTable([
+      { companySlug: "indigo", path: "knowledge/", permission: "read", source: "person" },
+    ]);
+    expect(out).toContain("COMPANY");
+    expect(out).toContain("indigo");
+    expect(out).toContain("knowledge/");
+  });
+});

package/src/commands/files-browse.ts

@@ -484,6 +484,125 @@ export async function runCat(input: RunCatInput): Promise<RunCatResult> {
   return { bytesWritten, destination: { kind: "stdout" }, vend };
 }
 
+// ── shared-with-me ────────────────────────────────────────────────────────
+
+/**
+ * Subset of `VaultClient` the `shared-with-me` orchestrator uses. No vend / S3
+ * — this is a pure read of the caller's explicit-grant graph, so it never
+ * touches the credential/browse vend surface.
+ */
+export interface FilesSharedWithMeVaultClient {
+  listMyMemberships(): Promise<Array<{ companyUid: string }>>;
+  listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]>;
+  entity: {
+    get(uid: string): Promise<{ uid: string; slug: string; name?: string }>;
+  };
+}
+
+export interface SharedWithMeRow {
+  companySlug: string;
+  /** Company-relative grant path (e.g. `knowledge/`, `reports/q3.pdf`). */
+  path: string;
+  permission: ExplicitGrant["permission"];
+  source: ExplicitGrant["source"];
+}
+
+export interface RunSharedWithMeInput {
+  vaultClient: FilesSharedWithMeVaultClient;
+  /**
+   * Scope to a single company by UID. When omitted, rolls up across every
+   * company the caller has a membership in (the cross-company "what's shared
+   * with me everywhere" view).
+   */
+  companyUid?: string;
+  /** Display slug for the single-company case (avoids an extra entity.get). */
+  companySlug?: string;
+}
+
+/**
+ * `hq files shared-with-me` orchestrator. Lists the caller's EXPLICIT
+ * file-ACL grants — the canonical "what's been shared with me" surface.
+ * Role-bypass access (owner/admin) is intentionally excluded server-side by
+ * `listMyExplicitGrants`, so this shows real grants, not role-implied reach.
+ *
+ * Pure data — no console output, no S3, no vend. The caller renders + exits.
+ */
+export async function runSharedWithMe(
+  input: RunSharedWithMeInput,
+): Promise<SharedWithMeRow[]> {
+  const { vaultClient } = input;
+
+  // Resolve the (companyUid, slug) pairs to query. Single-company when a UID
+  // was supplied; otherwise fan out across every membership.
+  let targets: Array<{ uid: string; slug: string }>;
+  if (input.companyUid) {
+    targets = [{ uid: input.companyUid, slug: input.companySlug ?? input.companyUid }];
+  } else {
+    const memberships = await vaultClient.listMyMemberships();
+    targets = await Promise.all(
+      memberships.map(async (m) => {
+        try {
+          const ent = await vaultClient.entity.get(m.companyUid);
+          return { uid: m.companyUid, slug: ent.slug || m.companyUid };
+        } catch {
+          // Entity not visible — fall back to the UID as the display label
+          // rather than dropping the company's grants entirely.
+          return { uid: m.companyUid, slug: m.companyUid };
+        }
+      }),
+    );
+  }
+
+  const rows: SharedWithMeRow[] = [];
+  for (const t of targets) {
+    let grants: ExplicitGrant[];
+    try {
+      grants = await vaultClient.listMyExplicitGrants(t.uid);
+    } catch {
+      // A single company's grant fetch failing shouldn't sink the whole
+      // roll-up — skip it and continue (best-effort discovery view).
+      continue;
+    }
+    for (const g of grants) {
+      rows.push({
+        companySlug: t.slug,
+        path: g.path,
+        permission: g.permission,
+        source: g.source,
+      });
+    }
+  }
+
+  // Stable sort: company, then path — deterministic output for humans + tests.
+  rows.sort((a, b) =>
+    a.companySlug === b.companySlug
+      ? a.path.localeCompare(b.path)
+      : a.companySlug.localeCompare(b.companySlug),
+  );
+  return rows;
+}
+
+/**
+ * Render `shared-with-me` rows as a padded table. Mirrors `formatBrowseTable`.
+ */
+export function formatSharedWithMeTable(rows: SharedWithMeRow[]): string {
+  if (rows.length === 0) {
+    return "Nothing is explicitly shared with you. (Owner/admin role-bypass access is not listed here — only explicit grants.)";
+  }
+  const cols = ["COMPANY", "PATH", "PERMISSION", "SOURCE"];
+  const data = rows.map((r) => [r.companySlug, r.path, r.permission, r.source]);
+  const widths = cols.map((c, i) =>
+    Math.max(c.length, ...data.map((row) => row[i].length)),
+  );
+  const renderRow = (row: string[]): string =>
+    row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+  return [
+    chalk.bold(renderRow(cols)),
+    chalk.dim(renderRow(widths.map((w) => "─".repeat(w)))),
+    ...data.map(renderRow),
+  ].join("\n");
+}
+
 // ── CLI registration ────────────────────────────────────────────────────────
 
 const defaultS3Factory: S3ClientFactory = ({ region, credentials }) =>
@@ -736,4 +855,42 @@ export function registerFilesBrowseCommands(filesCmd: Command): void {
         process.exit(1);
       }
     });
+
+  filesCmd
+    .command("shared-with-me")
+    .description(
+      "List the files/prefixes explicitly shared with you. Omit --company to roll up across every company you're a member of. Pure read — no download, no credentials vended. Owner/admin role-bypass access is NOT listed (only explicit grants).",
+    )
+    .option(
+      "--company <slug>",
+      "Scope to a single company (defaults to a cross-company roll-up).",
+    )
+    .action(async (options: { company?: string }) => {
+      try {
+        const accessToken = await ensureCognitoToken();
+        const vaultConfig = buildVaultConfig(accessToken);
+        const client = new VaultClient(vaultConfig);
+
+        let companyUid: string | undefined;
+        if (options.company) {
+          // Confirm membership + resolve UID, same early-failure pattern as
+          // browse/cat. Roll-up mode skips this and fans out internally.
+          companyUid = await getCompanyUid(accessToken, options.company);
+        }
+
+        const rows = await runSharedWithMe({
+          vaultClient: client,
+          companyUid,
+          companySlug: options.company,
+        });
+
+        console.log(formatSharedWithMeTable(rows));
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
 }

package/src/commands/sync-narrow.test.ts

@@ -291,18 +291,24 @@ describe("resolveNarrowTarget", () => {
 
 describe("computeNarrowPlan", () => {
   it("coalesces grants and returns a partitioned plan", async () => {
+    // Files live on disk at their hq-root-relative path…
     writeFile("companies/acme/meetings/notes.md", "stays");
     writeFile("companies/acme/scratch/old.md", "clean orphan");
 
+    // …but the journal keys + grant paths are COMPANY-RELATIVE — the
+    // namespace the real server + engine use. (The old fixtures used
+    // full `companies/acme/...` grant paths, which never matched the
+    // company-relative keys buildNarrowPlan emits — masking the namespace
+    // bug this test now guards against.)
     const journal = journalFromFiles([
-      { rel: "companies/acme/meetings/notes.md", contents: "stays" },
-      { rel: "companies/acme/scratch/old.md", contents: "clean orphan" },
+      { rel: "meetings/notes.md", contents: "stays" },
+      { rel: "scratch/old.md", contents: "clean orphan" },
     ]);
 
     const { client } = makeStubClient({
       grants: [
-        fakeGrant("companies/acme/meetings/"),
-        fakeGrant("companies/acme/meetings/2026/"), // collapsed by coalesce
+        fakeGrant("meetings/"),
+        fakeGrant("meetings/2026/"), // collapsed by coalesce
       ],
     });
 
@@ -316,13 +322,67 @@ describe("computeNarrowPlan", () => {
       journalIO: journalIO.io,
     });
 
-    expect(result.prospectivePrefixSet).toEqual([
-      "companies/acme/meetings/",
+    expect(result.prospectivePrefixSet).toEqual(["meetings/"]);
+    expect(result.plan.totalStayingCount).toBe(1);
+    expect(result.plan.totalCleanCount).toBe(1);
+    expect(result.plan.totalDirtyCount).toBe(0);
+  });
+
+  it("normalizes real-world anchored + glob grant paths (grantPathToPrefix)", async () => {
+    writeFile("companies/acme/design-pack/logo.svg", "svg");
+    writeFile("companies/acme/scratch/old.md", "clean orphan");
+
+    const journal = journalFromFiles([
+      { rel: "design-pack/logo.svg", contents: "svg" },
+      { rel: "scratch/old.md", contents: "clean orphan" },
     ]);
+
+    // The exact messy shapes the live vault returns: full-anchored + glob,
+    // and slug-anchored + glob — neither startsWith-matches the
+    // company-relative local keys until grantPathToPrefix de-anchors them.
+    const { client } = makeStubClient({
+      grants: [
+        fakeGrant("companies/acme/design-pack/*"),
+        fakeGrant("acme/design-pack/2026/*"), // subsumed after normalize+coalesce
+      ],
+    });
+
+    const result = await computeNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      companyUid: "cmp_acme",
+      vaultClient: client,
+      journalIO: makeStubJournalIO(journal).io,
+    });
+
+    expect(result.prospectivePrefixSet).toEqual(["design-pack/"]);
+    // design-pack/logo.svg stays (covered); scratch/old.md is a clean orphan.
     expect(result.plan.totalStayingCount).toBe(1);
     expect(result.plan.totalCleanCount).toBe(1);
     expect(result.plan.totalDirtyCount).toBe(0);
   });
+
+  it("a wildcard '*' grant keeps everything (no orphans)", async () => {
+    writeFile("companies/acme/a.md", "a");
+    writeFile("companies/acme/sub/b.md", "b");
+
+    const { client } = makeStubClient({ grants: [fakeGrant("*")] });
+
+    const result = await computeNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      companyUid: "cmp_acme",
+      vaultClient: client,
+      journalIO: makeStubJournalIO(journalFromFiles([])).io,
+    });
+
+    // "*" → "" → guarded to [""] (covers everything) so narrowing keeps the
+    // whole tree rather than collapsing to "nothing" and proposing deletes.
+    expect(result.prospectivePrefixSet).toEqual([""]);
+    expect(result.plan.totalCleanCount).toBe(0);
+    expect(result.plan.totalDirtyCount).toBe(0);
+    expect(result.plan.totalStayingCount).toBe(2);
+  });
 });
 
 // ── applyNarrow ─────────────────────────────────────────────────────────────

package/src/commands/sync-narrow.ts

@@ -45,6 +45,7 @@ import * as fs from "node:fs";
 import {
   VaultClient,
   coalescePrefixes,
+  grantPathToPrefix,
   readJournal,
   writeJournal,
   tombstoneEntry,
@@ -218,7 +219,20 @@ export async function computeNarrowPlan(
   const io = input.journalIO ?? realJournalIO;
 
   const grants = await vaultClient.listMyExplicitGrants(companyUid);
-  const prospectivePrefixSet = coalescePrefixes(grants.map((g) => g.path));
+  // Normalize each grant into a company-relative, startsWith-friendly prefix
+  // (grantPathToPrefix, hq-cloud ≥5.42.0): real grants are anchored
+  // (`companies/<slug>/x/*`, `<slug>/x/*`) and glob-style (`x/*`, bare `*`),
+  // none of which startsWith-match the company-relative local-tree keys
+  // buildNarrowPlan emits. A wildcard grant normalizes to "" (everything);
+  // coalescePrefixes drops empties, so guard it explicitly to `[""]` (which
+  // isCoveredByAny treats as covering everything → nothing orphaned) rather
+  // than letting it collapse to "nothing" and propose deleting the tree.
+  const normalizedPrefixes = grants.map((g) =>
+    grantPathToPrefix(g.path, companySlug),
+  );
+  const prospectivePrefixSet = normalizedPrefixes.some((p) => p === "")
+    ? [""]
+    : coalescePrefixes(normalizedPrefixes);
   const journal = io.read(companySlug);
 
   const plan = buildNarrowPlan({

package/src/index.ts

@@ -31,6 +31,7 @@ import { registerGroupsCommand } from "./commands/groups.js";
 import { registerFilesCommand } from "./commands/files.js";
 import { registerFilesBrowseCommands } from "./commands/files-browse.js";
 import { registerMembersCommand } from "./commands/members.js";
+import { registerDmCommand } from "./commands/dm.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
 import { registerSourcesCommand } from "./commands/sources.js";
@@ -138,6 +139,7 @@ registerFilesBrowseCommands(filesCmd);
 
 // Membership management (subcommand group — hq members invite|list|revoke)
 registerMembersCommand(program);
+registerDmCommand(program);
 
 // Onboarding (top-level — Cognito + vault-service provisioning)
 registerOnboardCommand(program);