@indigoai-us/hq-cli 5.17.0 → 5.18.0

package/src/commands/sync-narrow.ts

@@ -0,0 +1,541 @@
+/**
+ * `hq sync narrow` (US-007) — explicit migration ritual to flip a company's
+ * membership from `syncMode: all` to `syncMode: shared`, with a dry-run
+ * preview and a dirty-file safety gate.
+ *
+ * Two call shapes:
+ *
+ *   hq sync narrow --dry-run [--company <slug>]
+ *       Resolves the membership for <slug> (or the active company), fetches
+ *       the caller's explicit grants, coalesces them, walks the local
+ *       `companies/<slug>/` tree, and prints a table:
+ *
+ *           files staying:  N
+ *           clean orphans:  N (size)
+ *           dirty orphans:  N (size)
+ *
+ *       Writes nothing — no journal, no local file, no server call beyond
+ *       the read-only GET on grants + sync-config.
+ *
+ *   hq sync narrow --apply [--yes] [--force] [--company <slug>]
+ *       Same computation, then:
+ *         - if `dirty > 0` and `--force` NOT set → abort with conflict report
+ *           and a recovery message.
+ *         - else delete clean orphans on disk, tombstone their journal
+ *           entries, optionally delete dirty orphans too (with `--force`),
+ *           then PUT sync-config to `shared`. The server's PUT writes the
+ *           authoritative `MEMBERSHIP_SYNC_CONFIG_CHANGED` audit row; the
+ *           CLI prints a local audit line as well.
+ *
+ * Refuses on already-`shared` or `custom` memberships (acceptance 5) —
+ * narrowing makes sense only as `all → shared`.
+ *
+ * Cross-package note: depends on hq-cloud helpers shipped in US-005
+ * (`coalescePrefixes`, `readJournal`/`writeJournal`, `tombstoneEntry`) and
+ * the VaultClient sync-config endpoints from US-003. While that hq-cloud
+ * release is unpublished, hq-cli pins `@indigoai-us/hq-cloud` to
+ * `file:../hq-cloud` via `pnpm.overrides`.
+ */
+
+import { Command } from "commander";
+import chalk from "chalk";
+import * as readline from "node:readline";
+import * as fs from "node:fs";
+
+import {
+  VaultClient,
+  coalescePrefixes,
+  readJournal,
+  writeJournal,
+  tombstoneEntry,
+  type ExplicitGrant,
+  type Membership,
+  type MembershipSyncConfig,
+  type SyncMode,
+  type SyncJournal,
+} from "@indigoai-us/hq-cloud";
+
+import {
+  DEFAULT_HQ_ROOT,
+  ensureCognitoToken,
+  buildVaultConfig,
+} from "../utils/cognito-session.js";
+import { readActiveCompanySlug } from "./sync-mode.js";
+import {
+  buildNarrowPlan,
+  formatBytes,
+  formatNarrowPlanSummary,
+  type NarrowPlan,
+  type NarrowDirtyFile,
+} from "../lib/local-tree-diff.js";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** Subset of VaultClient surface this command exercises (test seam). */
+export interface SyncNarrowVaultClient {
+  listMyMemberships(): Promise<Membership[]>;
+  getMembershipSyncConfig(membershipId: string): Promise<MembershipSyncConfig>;
+  setMembershipSyncConfig(
+    membershipId: string,
+    partial: { syncMode: SyncMode; customPaths?: string[] },
+  ): Promise<MembershipSyncConfig>;
+  listMyExplicitGrants(companyUid: string): Promise<ExplicitGrant[]>;
+  entity: {
+    get(uid: string): Promise<{ uid: string; slug: string; name?: string }>;
+  };
+}
+
+/** Journal I/O seam — defaults to the real `readJournal`/`writeJournal`. */
+export interface JournalIO {
+  read(slug: string): SyncJournal;
+  write(slug: string, journal: SyncJournal): void;
+}
+
+const realJournalIO: JournalIO = {
+  read: readJournal,
+  write: writeJournal,
+};
+
+/** Filesystem seam — defaults to real `fs` (only `unlinkSync` is exercised). */
+export interface FsIO {
+  unlinkSync(p: string): void;
+}
+
+const realFsIO: FsIO = {
+  unlinkSync: fs.unlinkSync,
+};
+
+/** Confirmation prompt seam — defaults to a `readline` y/N gate. */
+export type ConfirmFn = (message: string) => Promise<boolean>;
+
+const realConfirm: ConfirmFn = async (message) => {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(`${message} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+};
+
+export interface ResolveTargetInput {
+  companySlug: string;
+  vaultClient: SyncNarrowVaultClient;
+}
+
+export interface ResolveTargetResult {
+  membership: Membership;
+  companyUid: string;
+  companySlug: string;
+  syncConfig: MembershipSyncConfig;
+}
+
+/**
+ * Resolve the caller's membership for `companySlug` and read its current
+ * sync-config. Throws if the slug doesn't match any membership or if the
+ * current mode isn't eligible for narrowing (`all` → `shared` only).
+ */
+export async function resolveNarrowTarget(
+  input: ResolveTargetInput,
+): Promise<ResolveTargetResult> {
+  const { companySlug, vaultClient } = input;
+  const memberships = await vaultClient.listMyMemberships();
+  const enriched = await Promise.all(
+    memberships.map(async (m) => {
+      try {
+        const ent = await vaultClient.entity.get(m.companyUid);
+        return { membership: m, slug: ent.slug, name: ent.name };
+      } catch {
+        return { membership: m, slug: undefined, name: undefined };
+      }
+    }),
+  );
+
+  const match = enriched.find((row) => row.slug === companySlug);
+  if (!match) {
+    const known = enriched
+      .map((r) => r.slug)
+      .filter((s): s is string => !!s)
+      .join(", ");
+    throw new Error(
+      `No membership found for company '${companySlug}'. Memberships visible to you: ${
+        known || "(none)"
+      }.`,
+    );
+  }
+
+  const membership = match.membership;
+  const syncConfig = await vaultClient.getMembershipSyncConfig(
+    membership.membershipKey,
+  );
+
+  if (syncConfig.syncMode !== "all") {
+    throw new Error(
+      `Refusing to narrow: membership for '${companySlug}' is currently ` +
+        `syncMode='${syncConfig.syncMode}'. The narrow ritual only runs on ` +
+        `syncMode='all' memberships (shared → shared is a no-op; ` +
+        `custom requires \`hq sync mode shared\` directly).`,
+    );
+  }
+
+  return {
+    membership,
+    companyUid: membership.companyUid,
+    companySlug,
+    syncConfig,
+  };
+}
+
+export interface ComputePlanInput {
+  hqRoot: string;
+  companySlug: string;
+  companyUid: string;
+  vaultClient: SyncNarrowVaultClient;
+  journalIO?: JournalIO;
+}
+
+export interface ComputePlanResult {
+  plan: NarrowPlan;
+  prospectivePrefixSet: string[];
+  grants: ExplicitGrant[];
+  journal: SyncJournal;
+}
+
+/**
+ * Compute the narrow plan for one company: fetch explicit grants, coalesce,
+ * read the per-company journal, walk the local tree, classify.
+ *
+ * Reads only — never mutates the journal or hits a destructive endpoint.
+ * `apply()` consumes this and performs the destructive steps.
+ */
+export async function computeNarrowPlan(
+  input: ComputePlanInput,
+): Promise<ComputePlanResult> {
+  const { hqRoot, companySlug, companyUid, vaultClient } = input;
+  const io = input.journalIO ?? realJournalIO;
+
+  const grants = await vaultClient.listMyExplicitGrants(companyUid);
+  const prospectivePrefixSet = coalescePrefixes(grants.map((g) => g.path));
+  const journal = io.read(companySlug);
+
+  const plan = buildNarrowPlan({
+    hqRoot,
+    companySlug,
+    prospectivePrefixSet,
+    journal,
+  });
+
+  return { plan, prospectivePrefixSet, grants, journal };
+}
+
+export interface ApplyNarrowInput {
+  companySlug: string;
+  membershipId: string;
+  plan: NarrowPlan;
+  journal: SyncJournal;
+  vaultClient: SyncNarrowVaultClient;
+  /** If true, delete dirty orphans too (still tombstoned). */
+  force: boolean;
+  journalIO?: JournalIO;
+  fsIO?: FsIO;
+}
+
+export interface ApplyNarrowResult {
+  cleanDeleted: number;
+  cleanBytes: number;
+  dirtyDeleted: number;
+  dirtyBytes: number;
+  tombstoned: number;
+  newConfig: MembershipSyncConfig;
+}
+
+/**
+ * Apply the destructive side of a narrow:
+ *   1. Delete clean orphans (best-effort — ENOENT is ignored).
+ *   2. Tombstone their journal entries.
+ *   3. If `force`, also delete + tombstone dirty orphans.
+ *   4. Persist the journal.
+ *   5. PUT sync-config → `shared` (server writes the audit row).
+ *
+ * Order is fail-safe: if a delete throws partway, the journal write below
+ * won't run, but the in-progress deletions are already on disk — that's the
+ * "don't roll back I/O" contract from the spec. The CLI surfaces a
+ * recovery message when this throws.
+ *
+ * Pure-ish: no prompting (the CLI wrapper handles that), no console
+ * output. Just disk + network.
+ */
+export async function applyNarrow(
+  input: ApplyNarrowInput,
+): Promise<ApplyNarrowResult> {
+  const { plan, journal, force, companySlug, membershipId, vaultClient } = input;
+  const journalIO = input.journalIO ?? realJournalIO;
+  const fsIO = input.fsIO ?? realFsIO;
+
+  let cleanDeleted = 0;
+  let dirtyDeleted = 0;
+  let tombstoned = 0;
+  const cleanBytes = plan.clean.reduce((sum, f) => sum + f.bytes, 0);
+  const dirtyBytes = force
+    ? plan.dirty.reduce((sum, f) => sum + f.bytes, 0)
+    : 0;
+
+  // 1. Delete clean orphans + tombstone.
+  for (const file of plan.clean) {
+    try {
+      fsIO.unlinkSync(file.absPath);
+      cleanDeleted++;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT") throw err;
+    }
+    tombstoneEntry(journal, file.relPath, "narrow_apply");
+    tombstoned++;
+  }
+
+  // 2. With --force, delete dirty orphans too.
+  if (force) {
+    for (const file of plan.dirty) {
+      try {
+        fsIO.unlinkSync(file.absPath);
+        dirtyDeleted++;
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code !== "ENOENT") throw err;
+      }
+      // tombstone only if a journal entry exists — `not-in-journal` files
+      // never had one to tombstone.
+      if (journal.files[file.relPath]) {
+        tombstoneEntry(journal, file.relPath, "narrow_apply");
+        tombstoned++;
+      }
+    }
+  }
+
+  // 3. Persist journal.
+  journalIO.write(companySlug, journal);
+
+  // 4. PUT sync-config → shared. Server writes the authoritative
+  //    MEMBERSHIP_SYNC_CONFIG_CHANGED audit row.
+  const newConfig = await vaultClient.setMembershipSyncConfig(membershipId, {
+    syncMode: "shared",
+  });
+
+  return {
+    cleanDeleted,
+    cleanBytes,
+    dirtyDeleted,
+    dirtyBytes,
+    tombstoned,
+    newConfig,
+  };
+}
+
+// ── Dirty-file conflict report (operator-facing) ───────────────────────────
+
+/**
+ * Format the dirty-file conflict report shown on `--apply` when dirty files
+ * are present and `--force` is NOT set. The CLI prints this and exits
+ * non-zero so the operator can resolve before retrying.
+ */
+export function formatDirtyConflictReport(
+  dirty: NarrowDirtyFile[],
+  companySlug: string,
+): string {
+  const lines: string[] = [];
+  lines.push(
+    `Aborting narrow for '${companySlug}': ${dirty.length} locally-modified file(s) ` +
+      `would be removed by this narrow.`,
+  );
+  lines.push("");
+  lines.push("Dirty files:");
+  const cap = 25;
+  for (const f of dirty.slice(0, cap)) {
+    lines.push(`  ${f.relPath}  (${formatBytes(f.bytes)}, ${f.reason})`);
+  }
+  if (dirty.length > cap) {
+    lines.push(`  ... ${dirty.length - cap} more`);
+  }
+  lines.push("");
+  lines.push("Resolve before retrying:");
+  lines.push("  - commit or push the modifications via the normal sync flow;");
+  lines.push("  - move them outside the company folder; or");
+  lines.push("  - delete them locally if they really should be gone.");
+  lines.push("");
+  lines.push(
+    "Alternatively, re-run with --force to remove the dirty files anyway " +
+      "(destructive — there is no undo).",
+  );
+  return lines.join("\n");
+}
+
+// ── CLI registration ────────────────────────────────────────────────────────
+
+interface SyncNarrowCliOptions {
+  dryRun?: boolean;
+  apply?: boolean;
+  yes?: boolean;
+  force?: boolean;
+  company?: string;
+  hqRoot: string;
+}
+
+/**
+ * Wire `hq sync narrow` onto the existing `sync` Commander group. Called
+ * from `src/index.ts` after `registerSyncModeCommand`.
+ */
+export function registerSyncNarrowCommand(syncCmd: Command): void {
+  syncCmd
+    .command("narrow")
+    .description(
+      "Migrate a company's membership from syncMode='all' to 'shared' — " +
+        "dry-run previews diff, --apply performs the prune + flip",
+    )
+    .option(
+      "--dry-run",
+      "Compute + print the narrow plan; write nothing (default if neither --dry-run nor --apply is passed)",
+    )
+    .option("--apply", "Execute the narrow — delete clean orphans, flip sync-mode to 'shared'")
+    .option("--yes", "Skip the interactive confirmation prompt on --apply")
+    .option(
+      "--force",
+      "On --apply, also remove locally-modified (dirty) files (destructive — no undo)",
+    )
+    .option(
+      "--company <slug>",
+      "Company slug (defaults to the active company in <hq-root>/.hq/config.json)",
+    )
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(async (options: SyncNarrowCliOptions) => {
+      try {
+        if (options.dryRun && options.apply) {
+          throw new Error("--dry-run and --apply are mutually exclusive.");
+        }
+        // Default to dry-run when nothing is specified — safer.
+        const apply = !!options.apply;
+        const dryRun = !apply;
+
+        const companySlug =
+          options.company ?? readActiveCompanySlug(options.hqRoot);
+        if (!companySlug) {
+          throw new Error(
+            "No company specified. Pass --company <slug> or set activeCompany in <hq-root>/.hq/config.json.",
+          );
+        }
+
+        const accessToken = await ensureCognitoToken();
+        const vaultConfig = buildVaultConfig(accessToken);
+        const client = new VaultClient(vaultConfig);
+
+        const target = await resolveNarrowTarget({
+          companySlug,
+          vaultClient: client,
+        });
+
+        const { plan, prospectivePrefixSet, grants } = await computeNarrowPlan({
+          hqRoot: options.hqRoot,
+          companySlug: target.companySlug,
+          companyUid: target.companyUid,
+          vaultClient: client,
+        });
+
+        // Always print the summary.
+        console.log(
+          chalk.bold(
+            `${dryRun ? "Dry-run" : "Apply"}: narrow '${target.companySlug}' (${grants.length} explicit grant${
+              grants.length === 1 ? "" : "s"
+            }, ${prospectivePrefixSet.length} coalesced prefix${
+              prospectivePrefixSet.length === 1 ? "" : "es"
+            })`,
+          ),
+        );
+        console.log(formatNarrowPlanSummary(plan));
+
+        if (dryRun) {
+          if (plan.totalDirtyCount > 0) {
+            console.log("");
+            console.log(
+              chalk.yellow(
+                `Heads-up: ${plan.totalDirtyCount} dirty file(s) would block --apply unless --force is passed.`,
+              ),
+            );
+          }
+          return;
+        }
+
+        // --apply path
+        if (plan.totalDirtyCount > 0 && !options.force) {
+          console.error(chalk.red(formatDirtyConflictReport(plan.dirty, target.companySlug)));
+          process.exit(2);
+          return;
+        }
+
+        if (!options.yes) {
+          const force = !!options.force;
+          const dirtyTail = force
+            ? ` AND remove ${plan.totalDirtyCount} dirty file(s) (--force)`
+            : "";
+          const confirmed = await realConfirm(
+            `About to remove ${plan.totalCleanCount} clean file(s)${dirtyTail} and flip '${target.companySlug}' to syncMode='shared'. Proceed?`,
+          );
+          if (!confirmed) {
+            console.log("Cancelled. No changes applied.");
+            return;
+          }
+        }
+
+        // Re-read the journal at apply time to avoid races with concurrent syncs.
+        const journal = readJournal(target.companySlug);
+        const result = await applyNarrow({
+          companySlug: target.companySlug,
+          membershipId: target.membership.membershipKey,
+          plan,
+          journal,
+          vaultClient: client,
+          force: !!options.force,
+        });
+
+        console.log(
+          chalk.green("✓"),
+          `Narrow applied for ${chalk.bold(target.companySlug)}:`,
+        );
+        console.log(
+          chalk.dim(
+            `  removed: ${result.cleanDeleted} clean (${formatBytes(result.cleanBytes)})${
+              result.dirtyDeleted > 0
+                ? ` + ${result.dirtyDeleted} dirty (${formatBytes(result.dirtyBytes)})`
+                : ""
+            }`,
+          ),
+        );
+        console.log(
+          chalk.dim(`  tombstoned: ${result.tombstoned} journal entr${result.tombstoned === 1 ? "y" : "ies"}`),
+        );
+        console.log(
+          chalk.dim(
+            `  syncMode: all → ${result.newConfig.syncMode}` +
+              (result.newConfig.updatedAt ? ` (updatedAt: ${result.newConfig.updatedAt})` : ""),
+          ),
+        );
+        console.log(
+          chalk.dim(
+            `  audit: server-side MEMBERSHIP_SYNC_CONFIG_CHANGED row written by PUT /v1/memberships/${target.membership.membershipKey}/sync-config`,
+          ),
+        );
+      } catch (err) {
+        console.error(
+          chalk.red("✗ sync narrow failed:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}
+

package/src/index.ts

@@ -11,6 +11,8 @@ import { registerSyncCommand } from "./commands/sync.js";
 import { registerListCommand } from "./commands/list.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerCloudCommands } from "./commands/cloud.js";
+import { registerSyncModeCommand } from "./commands/sync-mode.js";
+import { registerSyncNarrowCommand } from "./commands/sync-narrow.js";
 import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
 import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
 import { registerLoginCommand } from "./commands/login.js";
@@ -27,6 +29,7 @@ import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 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 { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
@@ -91,6 +94,8 @@ const syncCmd = program
   .description("Cloud sync commands — sync HQ to S3 for mobile access");
 
 registerCloudCommands(syncCmd);
+registerSyncModeCommand(syncCmd);
+registerSyncNarrowCommand(syncCmd);
 
 // Cloud provisioning subcommand group (entity + bucket + initial sync)
 // Distinct from `hq sync` which assumes provisioning has already happened.
@@ -122,7 +127,10 @@ registerRunCommand(program);
 registerGroupsCommand(program);
 
 // Files ACL management (subcommand group — hq files share|unshare|acl)
-registerFilesCommand(program);
+// `registerFilesCommand` returns the `files` group so we can attach the
+// browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
+const filesCmd = registerFilesCommand(program);
+registerFilesBrowseCommands(filesCmd);
 
 // Membership management (subcommand group — hq members invite|list|revoke)
 registerMembersCommand(program);

package/src/lib/hq-cloud-dep.smoke.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Dependency-bump smoke for @indigoai-us/hq-cloud.
+ *
+ * After moving from `file:../hq-cloud` to the published `^5.23.0`, this
+ * test pins the contract: the SDK methods + types that hq-cli's
+ * sync-mode / sync-narrow / files-browse / narrow-hint-banner commands
+ * depend on must keep resolving from the npm-published package.
+ *
+ * If a future major bump on hq-cloud removes or renames any of these, the
+ * matching hq-cli command would only fail at runtime (or at the call site's
+ * own test). Locking it here catches the regression at install time in CI.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as cloud from "@indigoai-us/hq-cloud";
+
+describe("@indigoai-us/hq-cloud — pinned methods used by hq-cli", () => {
+  it("US-004 + US-008 prep — VaultClient carries the sync-browse methods", () => {
+    const proto = cloud.VaultClient.prototype as unknown as Record<
+      string,
+      unknown
+    >;
+    expect(typeof proto.listMyExplicitGrants).toBe("function");
+    expect(typeof proto.getMembershipSyncConfig).toBe("function");
+    expect(typeof proto.setMembershipSyncConfig).toBe("function");
+    expect(typeof proto.vend).toBe("function");
+  });
+
+  it("US-004 type aliases used by sync-mode + sync-narrow + files-browse compile-link", () => {
+    const _grant: cloud.ExplicitGrant = {
+      companyUid: "cmp_x",
+      path: "companies/x/",
+      permission: "read",
+      source: "person",
+    };
+    const _config: cloud.MembershipSyncConfig = {
+      membershipId: "mbr_x",
+      syncMode: "shared",
+      isDefault: false,
+      updatedAt: "2026-05-20T00:00:00Z",
+      updatedBy: "prs_x",
+    };
+    const _input: cloud.SetMembershipSyncConfigInput = { syncMode: "all" };
+    expect(_grant.source).toBe("person");
+    expect(_config.syncMode).toBe("shared");
+    expect(_input.syncMode).toBe("all");
+  });
+
+  it("US-008 prep — VendPurpose + VendInput keep purpose='browse' typecheckable", () => {
+    const _vendInput: cloud.VendInput = {
+      paths: ["companies/x/"],
+      operations: "read-only",
+      purpose: "browse",
+    };
+    expect(_vendInput.purpose).toBe("browse");
+  });
+
+  it("dep is the published @indigoai-us/hq-cloud, not a local file: link", async () => {
+    // The package.json of the loaded module must be the npm-published one
+    // (not file:../hq-cloud which was the dev wiring during US-006 onwards).
+    // We resolve the package.json path via Node's require resolver and read
+    // its `_resolved` (pnpm) or `version` field — both confirm origin.
+    const pkgPath = require.resolve(
+      "@indigoai-us/hq-cloud/package.json",
+    );
+    const pkg = await import(pkgPath, { with: { type: "json" } });
+    expect(pkg.default.name).toBe("@indigoai-us/hq-cloud");
+    // Must be ≥ 5.23.0 — the first published version carrying the sync-
+    // browse SDK + raw vend with purpose. A lower version means the bump
+    // never made it into the lockfile / pnpm-store.
+    const [maj, min] = pkg.default.version.split(".").map(Number);
+    expect(maj).toBeGreaterThanOrEqual(5);
+    if (maj === 5) expect(min).toBeGreaterThanOrEqual(23);
+  });
+});