@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/sync-narrow.ts

@@ -1,555 +0,0 @@
-/**
- * `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,
-  grantPathToPrefix,
-  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);
-  // 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({
-    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);
-      }
-    });
-}
-