@indigoai-us/hq-cli 5.77.13 → 5.78.0

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

@@ -1,362 +0,0 @@
-/**
- * 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 {
-  /**
-   * COMPANY-RELATIVE path (e.g. `meetings/a.md`) — the canonical namespace
-   * shared by the per-company journal keys, the vault S3 keys, and the
-   * server's explicit-grant paths. NOT hq-root-relative.
-   */
-  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
-   * COMPANY-RELATIVE (e.g. `meetings/`) — the namespace the grants endpoint
-   * returns and the namespace `relPath` is now computed in.
-   */
-  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();
-  }
-
-  // Walk with `walkRoot` as the rel-root so each file's `relPath` is
-  // COMPANY-RELATIVE (e.g. `meetings/a.md`) — the same namespace as the
-  // server's explicit-grant paths, the per-company journal keys, and the
-  // hq-cloud sync engine's `RemoteFile.key`. Computing it relative to `hqRoot`
-  // (the old behavior) produced `companies/<slug>/meetings/a.md`, which
-  // matched neither the company-relative grants nor the journal keys — so
-  // every file fell out of `prospectivePrefixSet` AND missed its journal
-  // entry, making narrow flag the entire tree as dirty orphans. See the
-  // namespace contract in hq-cloud `scope-shrink.ts` / `prefix-coalesce.ts`.
-  walkLocal(walkRoot, walkRoot, (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).
- */
-/**
- * Normalize OS-native path separators to POSIX "/" for vault keys.
- *
- * `path.relative()` yields "\\"-separated paths on Windows, but vault S3 keys
- * are always "/"-separated — the server splits keys on "/" to rebuild the tree
- * and the journal + grants endpoint use that same namespace. Emit POSIX keys
- * regardless of client OS so a Windows narrow-plan lines up with the
- * forward-slash keys everywhere else. Mirrors the same normalization on
- * @indigoai-us/hq-cloud's upload path. Converting "\\" explicitly (rather than
- * only path.sep) keeps the result correct — and the regression test meaningful
- * — on a POSIX CI too.
- */
-export function toPosixKey(p: string): string {
-  return p.split("\\").join("/");
-}
-
-function walkLocal(
-  dir: string,
-  // Rel-root for `relPath` — the company walk root (`<hqRoot>/companies/<slug>`),
-  // so emitted `relPath`s are company-relative. Fixed across recursion.
-  relRoot: 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 = toPosixKey(path.relative(relRoot, 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, relRoot, 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]}`;
-}

package/src/lib/narrow-hint-banner.test.ts

@@ -1,235 +0,0 @@
-/**
- * Unit tests for `narrow-hint-banner` (US-011).
- *
- * Coverage:
- *   1. Emits a hint when sync mode is 'all' and not suppressed.
- *   2. Skips emission for shared/custom memberships.
- *   3. Dedupes per {companyUid, level} for the process lifetime.
- *   4. Suppression via HQ_SYNC_NARROW_HINT=off (env).
- *   5. Suppression via <hqRoot>/.hq/config.json `syncNarrowHint: 'off'`.
- *   6. Warning + strict level messages.
- *   7. `isStrictRefusal` only fires for strict + 'all'.
- *   8. `resolveBannerLevel` parses env values and defaults to 'hint'.
- */
-
-import { beforeEach, describe, expect, it } from "vitest";
-
-import {
-  _resetShownForTests,
-  emitNarrowHint,
-  isStrictRefusal,
-  resolveBannerLevel,
-  shouldShowBanner,
-} from "./narrow-hint-banner.js";
-
-function makeSink(): { lines: string[]; write: (s: string) => void } {
-  const lines: string[] = [];
-  return {
-    lines,
-    write: (s: string) => {
-      lines.push(s);
-    },
-  };
-}
-
-beforeEach(() => {
-  _resetShownForTests();
-});
-
-describe("emitNarrowHint", () => {
-  it("emits a hint message when sync mode is 'all' and not suppressed", () => {
-    const sink = makeSink();
-    emitNarrowHint(
-      { companyUid: "cmp_acme", syncMode: "all", level: "hint" },
-      { write: sink.write, showOverride: true },
-    );
-    expect(sink.lines).toHaveLength(1);
-    expect(sink.lines[0]).toMatch(/switch to shared-mode sync/i);
-    expect(sink.lines[0]).toMatch(/hq sync narrow --dry-run/);
-  });
-
-  it("skips emission when sync mode is 'shared'", () => {
-    const sink = makeSink();
-    emitNarrowHint(
-      { companyUid: "cmp_acme", syncMode: "shared", level: "hint" },
-      { write: sink.write, showOverride: true },
-    );
-    expect(sink.lines).toHaveLength(0);
-  });
-
-  it("skips emission when sync mode is 'custom'", () => {
-    const sink = makeSink();
-    emitNarrowHint(
-      { companyUid: "cmp_acme", syncMode: "custom", level: "hint" },
-      { write: sink.write, showOverride: true },
-    );
-    expect(sink.lines).toHaveLength(0);
-  });
-
-  it("dedupes per {companyUid, level} across calls", () => {
-    const sink = makeSink();
-    const input = {
-      companyUid: "cmp_acme",
-      syncMode: "all",
-      level: "hint",
-    } as const;
-    emitNarrowHint(input, { write: sink.write, showOverride: true });
-    emitNarrowHint(input, { write: sink.write, showOverride: true });
-    emitNarrowHint(input, { write: sink.write, showOverride: true });
-    expect(sink.lines).toHaveLength(1);
-  });
-
-  it("emits separately for different companies", () => {
-    const sink = makeSink();
-    emitNarrowHint(
-      { companyUid: "cmp_acme", syncMode: "all", level: "hint" },
-      { write: sink.write, showOverride: true },
-    );
-    emitNarrowHint(
-      { companyUid: "cmp_globex", syncMode: "all", level: "hint" },
-      { write: sink.write, showOverride: true },
-    );
-    expect(sink.lines).toHaveLength(2);
-  });
-
-  it("emits separately for the same company at a different level", () => {
-    const sink = makeSink();
-    emitNarrowHint(
-      { companyUid: "cmp_acme", syncMode: "all", level: "hint" },
-      { write: sink.write, showOverride: true },
-    );
-    emitNarrowHint(
-      { companyUid: "cmp_acme", syncMode: "all", level: "warning" },
-      { write: sink.write, showOverride: true },
-    );
-    expect(sink.lines).toHaveLength(2);
-  });
-
-  it("suppresses emission when showOverride=false (suppression path)", () => {
-    const sink = makeSink();
-    emitNarrowHint(
-      { companyUid: "cmp_acme", syncMode: "all", level: "hint" },
-      { write: sink.write, showOverride: false },
-    );
-    expect(sink.lines).toHaveLength(0);
-  });
-
-  it("emits the warning-level message", () => {
-    const sink = makeSink();
-    emitNarrowHint(
-      { companyUid: "cmp_acme", syncMode: "all", level: "warning" },
-      { write: sink.write, showOverride: true },
-    );
-    expect(sink.lines).toHaveLength(1);
-    expect(sink.lines[0]).toMatch(/shared-mode sync is the new default/i);
-  });
-
-  it("emits the strict-level message (does NOT throw or exit)", () => {
-    const sink = makeSink();
-    expect(() =>
-      emitNarrowHint(
-        { companyUid: "cmp_acme", syncMode: "all", level: "strict" },
-        { write: sink.write, showOverride: true },
-      ),
-    ).not.toThrow();
-    expect(sink.lines).toHaveLength(1);
-    expect(sink.lines[0]).toMatch(/--mode-all/);
-  });
-});
-
-describe("shouldShowBanner", () => {
-  it("returns true with no overrides", () => {
-    expect(shouldShowBanner({ envValue: undefined })).toBe(true);
-  });
-
-  it("returns false when env value is 'off' (case-insensitive)", () => {
-    expect(shouldShowBanner({ envValue: "off" })).toBe(false);
-    expect(shouldShowBanner({ envValue: "OFF" })).toBe(false);
-  });
-
-  it("returns true for env values other than 'off'", () => {
-    expect(shouldShowBanner({ envValue: "on" })).toBe(true);
-    expect(shouldShowBanner({ envValue: "" })).toBe(true);
-  });
-
-  it("returns false when .hq/config.json sets syncNarrowHint='off'", () => {
-    const exists = (_p: string) => true;
-    const read = (_p: string) => JSON.stringify({ syncNarrowHint: "off" });
-    expect(
-      shouldShowBanner({
-        envValue: undefined,
-        hqRoot: "/tmp/hq",
-        existsFile: exists,
-        readFile: read,
-      }),
-    ).toBe(false);
-  });
-
-  it("returns true when .hq/config.json has no syncNarrowHint key", () => {
-    const exists = (_p: string) => true;
-    const read = (_p: string) =>
-      JSON.stringify({ activeCompany: "acme" });
-    expect(
-      shouldShowBanner({
-        envValue: undefined,
-        hqRoot: "/tmp/hq",
-        existsFile: exists,
-        readFile: read,
-      }),
-    ).toBe(true);
-  });
-
-  it("tolerates malformed config.json (returns true)", () => {
-    const exists = (_p: string) => true;
-    const read = (_p: string) => "{not json";
-    expect(
-      shouldShowBanner({
-        envValue: undefined,
-        hqRoot: "/tmp/hq",
-        existsFile: exists,
-        readFile: read,
-      }),
-    ).toBe(true);
-  });
-
-  it("returns true when config file does not exist", () => {
-    expect(
-      shouldShowBanner({
-        envValue: undefined,
-        hqRoot: "/tmp/hq",
-        existsFile: () => false,
-        readFile: () => {
-          throw new Error("should not be called");
-        },
-      }),
-    ).toBe(true);
-  });
-});
-
-describe("isStrictRefusal", () => {
-  it("returns true only for level=strict + syncMode=all", () => {
-    expect(isStrictRefusal("all", "strict")).toBe(true);
-    expect(isStrictRefusal("shared", "strict")).toBe(false);
-    expect(isStrictRefusal("custom", "strict")).toBe(false);
-    expect(isStrictRefusal("all", "warning")).toBe(false);
-    expect(isStrictRefusal("all", "hint")).toBe(false);
-  });
-});
-
-describe("resolveBannerLevel", () => {
-  it("defaults to 'hint' when env is undefined", () => {
-    expect(resolveBannerLevel(undefined)).toBe("hint");
-  });
-
-  it("parses recognized values (case-insensitive)", () => {
-    expect(resolveBannerLevel("hint")).toBe("hint");
-    expect(resolveBannerLevel("warning")).toBe("warning");
-    expect(resolveBannerLevel("strict")).toBe("strict");
-    expect(resolveBannerLevel("WARNING")).toBe("warning");
-  });
-
-  it("falls back to 'hint' for unknown values", () => {
-    expect(resolveBannerLevel("loud")).toBe("hint");
-    expect(resolveBannerLevel("")).toBe("hint");
-  });
-});