@indigoai-us/hq-cli 5.17.0 → 5.18.0

package/src/lib/local-tree-diff.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Unit tests for `buildNarrowPlan` (local-tree-diff.ts).
+ *
+ * Uses a tmpdir fixture (same pattern as cloud-demote.test.ts) — vitest +
+ * real fs — so the symmetric-diff + dirty-classification logic is exercised
+ * end-to-end against an actual journal + filesystem.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+
+import {
+  buildNarrowPlan,
+  formatBytes,
+  formatNarrowPlanSummary,
+} from "./local-tree-diff.js";
+import type { SyncJournal } from "@indigoai-us/hq-cloud";
+
+// ── Fixture helpers ─────────────────────────────────────────────────────────
+
+let tmpRoot: string;
+
+function writeFile(rel: string, contents: string): { abs: string; rel: string } {
+  const abs = path.join(tmpRoot, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, contents);
+  return { abs, rel };
+}
+
+function sha256(s: string): string {
+  return crypto.createHash("sha256").update(s).digest("hex");
+}
+
+/** Build a journal that "knows about" the given files at their current hash + mtime. */
+function journalFromFiles(
+  files: Array<{ rel: string; contents: string; syncedAt?: string }>,
+): SyncJournal {
+  const j: SyncJournal = {
+    version: "2",
+    lastSync: new Date().toISOString(),
+    files: {},
+    pulls: [],
+  };
+  for (const f of files) {
+    j.files[f.rel] = {
+      hash: sha256(f.contents),
+      size: Buffer.byteLength(f.contents),
+      // Stamp syncedAt slightly in the future so on-disk mtime <= syncedAt
+      // (the clean path needs `mtime <= syncedAt + 1s` and mkdtemp file
+      // mtimes are essentially "now").
+      syncedAt: f.syncedAt ?? new Date(Date.now() + 5000).toISOString(),
+      direction: "down",
+    };
+  }
+  return j;
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-narrow-plan-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+// ── Happy-path partitioning ─────────────────────────────────────────────────
+
+describe("buildNarrowPlan — partition by prefix coverage", () => {
+  it("separates files into staying / clean / dirty buckets", () => {
+    // Staying — covered by prospective prefix.
+    const staying = writeFile(
+      "companies/acme/meetings/2026/notes.md",
+      "stays here",
+    );
+    // Clean orphan — outside prospective, matches journal.
+    const cleanOrphan = writeFile(
+      "companies/acme/scratch/old.md",
+      "clean content",
+    );
+    // Dirty orphan — outside prospective, hash mismatch.
+    const dirtyOrphan = writeFile(
+      "companies/acme/scratch/dirty.md",
+      "current local content",
+    );
+
+    const journal = journalFromFiles([
+      { rel: staying.rel, contents: "stays here" },
+      { rel: cleanOrphan.rel, contents: "clean content" },
+      // Journal saw an earlier version → hash mismatch with the on-disk
+      // "current local content" → dirty.
+      { rel: dirtyOrphan.rel, contents: "JOURNAL VERSION DIFFERENT" },
+    ]);
+
+    const plan = buildNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      prospectivePrefixSet: ["companies/acme/meetings/"],
+      journal,
+    });
+
+    expect(plan.staying.map((f) => f.relPath)).toEqual([staying.rel]);
+    expect(plan.clean.map((f) => f.relPath)).toEqual([cleanOrphan.rel]);
+    expect(plan.dirty.map((f) => f.relPath)).toEqual([dirtyOrphan.rel]);
+    expect(plan.dirty[0].reason).toBe("hash-mismatch");
+
+    expect(plan.totalStayingCount).toBe(1);
+    expect(plan.totalCleanCount).toBe(1);
+    expect(plan.totalDirtyCount).toBe(1);
+    expect(plan.totalCleanBytes).toBe(Buffer.byteLength("clean content"));
+  });
+
+  it("classifies files with no journal entry as dirty (not-in-journal)", () => {
+    const orphan = writeFile("companies/acme/scratch/local-draft.md", "never synced");
+    const plan = buildNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      prospectivePrefixSet: ["companies/acme/meetings/"],
+      journal: journalFromFiles([]),
+    });
+    expect(plan.dirty.map((f) => f.relPath)).toEqual([orphan.rel]);
+    expect(plan.dirty[0].reason).toBe("not-in-journal");
+  });
+
+  it("treats tombstoned journal entries as not-in-journal (dirty)", () => {
+    const orphan = writeFile("companies/acme/scratch/tombstoned.md", "still here");
+    const journal = journalFromFiles([
+      { rel: orphan.rel, contents: "still here" },
+    ]);
+    // Mark the entry tombstoned post-hoc.
+    journal.files[orphan.rel]!.removedAt = new Date().toISOString();
+    journal.files[orphan.rel]!.removedReason = "scope_shrink";
+
+    const plan = buildNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      prospectivePrefixSet: ["companies/acme/meetings/"],
+      journal,
+    });
+    expect(plan.dirty.map((f) => f.relPath)).toEqual([orphan.rel]);
+    expect(plan.dirty[0].reason).toBe("not-in-journal");
+  });
+
+  it("flags modified-after-sync via mtime past syncedAt", () => {
+    const orphan = writeFile("companies/acme/scratch/touched.md", "v1");
+    const journal = journalFromFiles([
+      { rel: orphan.rel, contents: "v1", syncedAt: new Date(0).toISOString() },
+    ]);
+    const plan = buildNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      prospectivePrefixSet: ["companies/acme/meetings/"],
+      journal,
+    });
+    expect(plan.dirty.map((f) => f.relPath)).toEqual([orphan.rel]);
+    expect(plan.dirty[0].reason).toBe("modified-after-sync");
+  });
+
+  it("handles nested prefixes (broader covers narrower) by trusting the caller-coalesced set", () => {
+    const a = writeFile("companies/acme/meetings/a.md", "a");
+    const b = writeFile("companies/acme/meetings/2026/b.md", "b");
+    const c = writeFile("companies/acme/scratch/c.md", "c");
+
+    const plan = buildNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      prospectivePrefixSet: ["companies/acme/meetings/"],
+      journal: journalFromFiles([
+        { rel: a.rel, contents: "a" },
+        { rel: b.rel, contents: "b" },
+        { rel: c.rel, contents: "c" },
+      ]),
+    });
+
+    const stayingPaths = plan.staying.map((f) => f.relPath).sort();
+    expect(stayingPaths).toEqual([a.rel, b.rel].sort());
+    expect(plan.clean.map((f) => f.relPath)).toEqual([c.rel]);
+  });
+
+  it("returns an empty plan when the company folder is missing", () => {
+    const plan = buildNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "ghost",
+      prospectivePrefixSet: ["companies/ghost/"],
+      journal: journalFromFiles([]),
+    });
+    expect(plan.totalStayingCount).toBe(0);
+    expect(plan.totalCleanCount).toBe(0);
+    expect(plan.totalDirtyCount).toBe(0);
+  });
+
+  it("everything is clean when the prefix set is empty (entire tree is orphan)", () => {
+    const a = writeFile("companies/acme/a.md", "aa");
+    const b = writeFile("companies/acme/sub/b.md", "bb");
+    const plan = buildNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      prospectivePrefixSet: [],
+      journal: journalFromFiles([
+        { rel: a.rel, contents: "aa" },
+        { rel: b.rel, contents: "bb" },
+      ]),
+    });
+    expect(plan.totalStayingCount).toBe(0);
+    expect(plan.totalCleanCount).toBe(2);
+    expect(plan.totalDirtyCount).toBe(0);
+  });
+
+  it("everything stays when the prospective prefix covers the whole company folder", () => {
+    const a = writeFile("companies/acme/a.md", "aa");
+    const b = writeFile("companies/acme/sub/b.md", "bb");
+    const plan = buildNarrowPlan({
+      hqRoot: tmpRoot,
+      companySlug: "acme",
+      prospectivePrefixSet: ["companies/acme/"],
+      journal: journalFromFiles([]),
+    });
+    expect(plan.totalStayingCount).toBe(2);
+    expect(plan.totalCleanCount).toBe(0);
+    expect(plan.totalDirtyCount).toBe(0);
+    // both are staying, regardless of journal state
+    expect(
+      plan.staying.map((f) => f.relPath).sort(),
+    ).toEqual([a.rel, b.rel].sort());
+  });
+});
+
+// ── Formatters ──────────────────────────────────────────────────────────────
+
+describe("formatBytes", () => {
+  it("formats bytes in a fixed unit ladder", () => {
+    expect(formatBytes(0)).toBe("0 B");
+    expect(formatBytes(512)).toBe("512 B");
+    expect(formatBytes(2048)).toBe("2.00 KB");
+    expect(formatBytes(5 * 1024 * 1024)).toBe("5.00 MB");
+  });
+
+  it("clamps negative + non-finite to 0 B", () => {
+    expect(formatBytes(-1)).toBe("0 B");
+    expect(formatBytes(Number.NaN)).toBe("0 B");
+  });
+});
+
+describe("formatNarrowPlanSummary", () => {
+  it("renders staying / clean / dirty counts with byte totals", () => {
+    const out = formatNarrowPlanSummary({
+      staying: [],
+      clean: [],
+      dirty: [],
+      totalStayingCount: 5,
+      totalCleanCount: 3,
+      totalCleanBytes: 2048,
+      totalDirtyCount: 1,
+      totalDirtyBytes: 1024,
+    });
+    expect(out).toContain("files staying:  5");
+    expect(out).toContain("clean orphans:  3 (2.00 KB)");
+    expect(out).toContain("dirty orphans:  1 (1.00 KB)");
+  });
+});

package/src/lib/local-tree-diff.ts

@@ -0,0 +1,330 @@
+/**
+ * Pure helper for `hq sync narrow` (US-007).
+ *
+ * Walks a local directory tree under `<hqRoot>/companies/{slug}/`, classifies
+ * each file against a prospective `shared`-mode prefix set, and groups the
+ * results into three buckets:
+ *
+ *   - **staying**  — file is covered by the prospective prefix set; survives.
+ *   - **clean**    — file is NOT covered (orphan) AND is provably unchanged
+ *                    since the last journal sync (safe to delete).
+ *   - **dirty**    — file is NOT covered (orphan) AND has been locally
+ *                    modified since the last sync (sacred — abort without
+ *                    `--force`).
+ *
+ * The clean-vs-dirty rule mirrors hq-cloud's implicit-shrink path
+ * (`scope-shrink.ts::classifyOrphan`) verbatim so the two narrowing paths —
+ * implicit (next pull after sync-mode flip) and explicit (`hq sync narrow
+ * --apply`) — agree on what "dirty" means. See US-000 Task 3 in
+ * `companies/indigo/projects/hq-sync-browse-vs-sync/references.md`.
+ *
+ * Pure: no network. Reads the journal off `SyncJournal` (caller passes it
+ * in), stats + hashes files on disk — no journal mutations and no remote
+ * calls happen here. The CLI orchestrator (`sync-narrow.ts`) is responsible
+ * for the destructive side effects (delete, tombstone, PUT sync-config).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+  hashFile,
+  isCoveredByAny,
+  type JournalEntry,
+  type SyncJournal,
+} from "@indigoai-us/hq-cloud";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export type DirtyReason =
+  | "modified-after-sync"
+  | "hash-mismatch"
+  | "not-in-journal"
+  | "stat-error";
+
+export interface NarrowFile {
+  /** Path relative to `hqRoot` (matches journal key + S3 key naming). */
+  relPath: string;
+  /** Absolute path on disk (convenience for the CLI delete loop). */
+  absPath: string;
+  /** Size in bytes from the local stat. 0 for symlinks (lstat size is the link, not target). */
+  bytes: number;
+}
+
+export interface NarrowDirtyFile extends NarrowFile {
+  reason: DirtyReason;
+}
+
+export interface NarrowPlan {
+  /** Files covered by `prospectivePrefixSet` — survive the narrow. */
+  staying: NarrowFile[];
+  /** Orphan files that are journal-clean — safe to delete on `--apply`. */
+  clean: NarrowFile[];
+  /** Orphan files that are locally dirty — block `--apply` unless `--force`. */
+  dirty: NarrowDirtyFile[];
+
+  // Convenience aggregates for the CLI summary table.
+  totalStayingCount: number;
+  totalCleanCount: number;
+  totalCleanBytes: number;
+  totalDirtyCount: number;
+  totalDirtyBytes: number;
+}
+
+export interface BuildNarrowPlanInput {
+  /** Absolute HQ root path (the dir containing `companies/`). */
+  hqRoot: string;
+  /** Company slug — used to derive the walk root `<hqRoot>/companies/<slug>/`. */
+  companySlug: string;
+  /**
+   * Coalesced prospective `shared`-mode prefix set (the result of running
+   * the caller's explicit grants through `coalescePrefixes`). Prefixes are
+   * hq-root-relative (e.g. `companies/indigo/meetings/`).
+   */
+  prospectivePrefixSet: readonly string[];
+  /**
+   * Active per-company journal. Hash + mtime comparisons key off
+   * `journal.files[relPath]`.
+   */
+  journal: SyncJournal;
+}
+
+// ── Pure entry point ────────────────────────────────────────────────────────
+
+/**
+ * Build a NarrowPlan by walking `<hqRoot>/companies/<slug>/` and classifying
+ * each regular file against `prospectivePrefixSet` + `journal`.
+ *
+ * Walk semantics:
+ *   - Recursive `fs.readdirSync(... withFileTypes)`.
+ *   - Symlinks are RECORDED but never followed (`lstat`, not `stat`), matching
+ *     the `share()`/sync engine's contract.
+ *   - Hidden files + `.DS_Store` + `node_modules` are walked as-is — the
+ *     caller is expected to point this at HQ content, where `.hqignore`
+ *     filtering happens upstream of the journal. The journal already
+ *     reflects what's been pushed/pulled, so `not-in-journal` is the
+ *     classifier signal for "we didn't put this here".
+ *   - If the walk root is missing entirely, returns an empty plan (rather
+ *     than throwing) — a freshly-flipped membership may not have synced any
+ *     files yet.
+ */
+export function buildNarrowPlan(input: BuildNarrowPlanInput): NarrowPlan {
+  const { hqRoot, companySlug, prospectivePrefixSet, journal } = input;
+  const walkRoot = path.join(hqRoot, "companies", companySlug);
+
+  const staying: NarrowFile[] = [];
+  const clean: NarrowFile[] = [];
+  const dirty: NarrowDirtyFile[] = [];
+
+  if (!fs.existsSync(walkRoot)) {
+    return emptyPlan();
+  }
+
+  walkLocal(walkRoot, hqRoot, (file) => {
+    if (isCoveredByAny(file.relPath, prospectivePrefixSet)) {
+      staying.push(file);
+      return;
+    }
+    const verdict = classifyAgainstJournal(file, journal);
+    if (verdict.clean) {
+      clean.push(file);
+    } else {
+      dirty.push({ ...file, reason: verdict.reason });
+    }
+  });
+
+  return {
+    staying,
+    clean,
+    dirty,
+    totalStayingCount: staying.length,
+    totalCleanCount: clean.length,
+    totalCleanBytes: clean.reduce((sum, f) => sum + f.bytes, 0),
+    totalDirtyCount: dirty.length,
+    totalDirtyBytes: dirty.reduce((sum, f) => sum + f.bytes, 0),
+  };
+}
+
+// ── Internal: walk + classify ───────────────────────────────────────────────
+
+function emptyPlan(): NarrowPlan {
+  return {
+    staying: [],
+    clean: [],
+    dirty: [],
+    totalStayingCount: 0,
+    totalCleanCount: 0,
+    totalCleanBytes: 0,
+    totalDirtyCount: 0,
+    totalDirtyBytes: 0,
+  };
+}
+
+/**
+ * Recursive readdir walk yielding regular files (and dangling-target
+ * symlinks — those are recorded as files for narrow-plan purposes; the
+ * delete path uses `fs.unlinkSync` which handles symlinks correctly).
+ *
+ * Uses `lstat` rather than `stat` so a symlink's size doesn't follow the
+ * target chain (matches the share-engine convention).
+ */
+function walkLocal(
+  dir: string,
+  hqRoot: string,
+  emit: (file: NarrowFile) => void,
+): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    // Permission-denied or ENOENT mid-walk — skip silently; the CLI
+    // surfaces the higher-level "company folder missing" message earlier.
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "EACCES") return;
+    throw err;
+  }
+
+  for (const entry of entries) {
+    const absPath = path.join(dir, entry.name);
+    const relPath = path.relative(hqRoot, absPath);
+
+    if (entry.isSymbolicLink()) {
+      // Record the link as a file-like entry. Don't descend — narrow is
+      // about pruning files that the LOCAL tree has materialized here; a
+      // symlink to a knowledge repo is one such "file" from the
+      // walk's POV.
+      let bytes = 0;
+      try {
+        bytes = fs.lstatSync(absPath).size;
+      } catch {
+        // pass — dangling link still gets emitted with size 0
+      }
+      emit({ relPath, absPath, bytes });
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      walkLocal(absPath, hqRoot, emit);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      let bytes = 0;
+      try {
+        bytes = fs.lstatSync(absPath).size;
+      } catch {
+        // pass
+      }
+      emit({ relPath, absPath, bytes });
+    }
+  }
+}
+
+interface JournalVerdict {
+  clean: boolean;
+  reason: DirtyReason;
+}
+
+/**
+ * Mirror of `scope-shrink.ts::classifyOrphan`:
+ *
+ *   clean = (entry exists AND hash(local) === entry.hash AND mtime <= syncedAt + 1s)
+ *           OR (local file missing)
+ *
+ * Differences from the implicit path:
+ *   - If there is NO journal entry at all, classify as **dirty**
+ *     (`not-in-journal`). The implicit path never sees those files (it
+ *     iterates the journal); here we walk the local tree so an
+ *     un-journaled file is a real risk — it could be an unsynced local
+ *     draft.
+ *   - We don't honor `direction: "up"` differently. For an explicit
+ *     narrow migration the user is asking "wipe everything outside the
+ *     shared scope" — push-only authorship deserves the same dirty-file
+ *     protection as pulled content (otherwise `--apply` could nuke local
+ *     drafts).
+ */
+function classifyAgainstJournal(
+  file: NarrowFile,
+  journal: SyncJournal,
+): JournalVerdict {
+  const entry: JournalEntry | undefined = journal.files[file.relPath];
+  if (!entry) {
+    return { clean: false, reason: "not-in-journal" };
+  }
+  // Tombstoned entries — the file shouldn't be here at all; treat as
+  // not-in-journal for safety so `--apply` doesn't silently delete it.
+  if (entry.removedAt) {
+    return { clean: false, reason: "not-in-journal" };
+  }
+
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(file.absPath);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      // Already gone — clean (the apply path will skip ENOENT on unlink).
+      return { clean: true, reason: "stat-error" };
+    }
+    return { clean: false, reason: "stat-error" };
+  }
+
+  // mtime guard with 1s grace for filesystem clock jitter, matching
+  // hq-cloud `scope-shrink.ts`.
+  const syncedAtMs = Date.parse(entry.syncedAt);
+  if (!Number.isNaN(syncedAtMs) && stat.mtimeMs > syncedAtMs + 1000) {
+    return { clean: false, reason: "modified-after-sync" };
+  }
+
+  // Hash check — final word. Symlinks: hashFile reads contents which is
+  // wrong for symlinks (it would follow the target), so on a symlink we
+  // skip the hash check and trust mtime alone. This matches the
+  // engine's behavior in the symlink-orphan case.
+  if (stat.isSymbolicLink()) {
+    return { clean: true, reason: "stat-error" };
+  }
+
+  let actualHash: string;
+  try {
+    actualHash = hashFile(file.absPath);
+  } catch {
+    return { clean: false, reason: "stat-error" };
+  }
+  if (actualHash !== entry.hash) {
+    return { clean: false, reason: "hash-mismatch" };
+  }
+  return { clean: true, reason: "stat-error" };
+}
+
+// ── Formatting helper (separable for tests) ────────────────────────────────
+
+/**
+ * Render the dry-run summary as plain text (no chalk — keep it pure). The
+ * CLI wrapper can colorize lines afterwards if desired.
+ */
+export function formatNarrowPlanSummary(plan: NarrowPlan): string {
+  const lines: string[] = [];
+  lines.push("Narrow plan summary:");
+  lines.push(`  files staying:  ${plan.totalStayingCount}`);
+  lines.push(
+    `  clean orphans:  ${plan.totalCleanCount} (${formatBytes(plan.totalCleanBytes)})`,
+  );
+  lines.push(
+    `  dirty orphans:  ${plan.totalDirtyCount} (${formatBytes(plan.totalDirtyBytes)})`,
+  );
+  return lines.join("\n");
+}
+
+/** Human-readable byte counts with a fixed unit ladder. */
+export function formatBytes(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return "0 B";
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let v = n / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(2)} ${units[i]}`;
+}