@indigoai-us/hq-cloud 6.5.0 → 6.7.0

package/src/scope-shrink.ts

@@ -209,10 +209,56 @@ function classifyOrphan(
   return { path: relPath, entry, clean: true };
 }
 
+/**
+ * Where a scope-shrink error is going to be rendered, so the structured error
+ * can carry advice that is ACTUALLY FOLLOWABLE from that entry point.
+ *
+ *   - `"cli"`    — a human at a terminal running `hq sync pull|now`. They can
+ *                  re-run with `--force-scope-shrink` or run the guided
+ *                  `hq sync narrow --apply` ritual.
+ *   - `"runner"` — the menubar's `hq-sync-runner`. It accepts NO such flag
+ *                  (DEV-1768 fix #2: the old "pass --force-scope-shrink" advice
+ *                  was impossible to follow from here), so the only followable
+ *                  action is to open a terminal and run `hq sync narrow --apply`.
+ *                  In practice the runner pulls with `scopeShrinkPolicy:
+ *                  "auto-recover"` and never throws this — but the context keeps
+ *                  the message honest if it ever surfaces.
+ *   - `"engine"` — unknown/library caller; generic advice.
+ */
+export type ScopeShrinkAdviceContext = "cli" | "runner" | "engine";
+
+/** Followable next-step advice for a blocked scope shrink, per entry point. */
+function scopeShrinkAdvice(ctx: ScopeShrinkAdviceContext): string {
+  switch (ctx) {
+    case "cli":
+      return (
+        "Re-run with `--force-scope-shrink` to disown them now (dirty files " +
+        "are KEPT on disk, only un-tracked from sync), or run " +
+        "`hq sync narrow --apply` to migrate with a confirmation prompt."
+      );
+    case "runner":
+      return (
+        "The menubar sync cannot take this flag — open a terminal and run " +
+        "`hq sync narrow --apply` to migrate this membership (you confirm the " +
+        "file list), or `hq sync now --force-scope-shrink` once to proceed " +
+        "(dirty files are KEPT on disk, only un-tracked)."
+      );
+    default:
+      return (
+        "Run `hq sync narrow --apply` to migrate with confirmation, or pass " +
+        "`forceScopeShrink` (dirty files are kept on disk, only un-tracked)."
+      );
+  }
+}
+
 /**
  * Structured error thrown when the engine refuses to proceed because a scope
  * shrink would orphan dirty files. The CLI catches this and renders the
  * operator-facing message; the engine never prints directly.
+ *
+ * `adviceContext` makes the message FOLLOWABLE from each entry point — the old
+ * fixed "pass --force-scope-shrink" line was impossible to act on from the
+ * menubar runner, which rejects that flag (DEV-1768 fix #2).
  */
 export class ScopeShrinkBlockedError extends Error {
   readonly code = "SCOPE_SHRINK_BLOCKED";
@@ -222,11 +268,12 @@ export class ScopeShrinkBlockedError extends Error {
     public readonly toMode: PullRecord["syncMode"],
     public readonly dirty: OrphanClassification[],
     public readonly clean: OrphanClassification[],
+    public readonly adviceContext: ScopeShrinkAdviceContext = "engine",
   ) {
     super(
       `Sync scope shrank for ${companyUid} (${fromMode} → ${toMode}); ` +
-        `${dirty.length} dirty file(s) outside the new scope would be ` +
-        `pruned from the journal. Resolve or pass --force-scope-shrink.`,
+        `${dirty.length} locally-modified file(s) outside the new scope ` +
+        `would be un-tracked from sync. ${scopeShrinkAdvice(adviceContext)}`,
     );
     this.name = "ScopeShrinkBlockedError";
   }
@@ -249,17 +296,31 @@ export class ScopeShrinkLargePruneError extends Error {
     public readonly toMode: PullRecord["syncMode"],
     public readonly cleanCount: number,
     public readonly cap: number,
+    public readonly adviceContext: ScopeShrinkAdviceContext = "engine",
   ) {
     super(
-      `Refusing to auto-prune ${cleanCount} local file(s) for ${companyUid} ` +
+      `Refusing to auto-move ${cleanCount} local file(s) for ${companyUid} ` +
         `(${toMode} scope) in one sync — exceeds the safety cap of ${cap}. ` +
-        `Run \`hq sync narrow --apply\` to migrate with confirmation, raise ` +
-        `HQ_SYNC_MAX_AUTO_PRUNE, or pass --force-scope-shrink.`,
+        `Raise HQ_SYNC_MAX_AUTO_PRUNE, or ${scopeShrinkAdvice(adviceContext)}`,
     );
     this.name = "ScopeShrinkLargePruneError";
   }
 }
 
+/**
+ * Disposition for CLEAN orphans (files provably unchanged since the last sync)
+ * that fall outside the new scope:
+ *
+ *   - `"delete"`     — `unlink` the local file. The legacy behavior; reserved
+ *                      for the explicit `hq sync narrow --apply` ritual, which
+ *                      already confirms the file list with the operator.
+ *   - `"quarantine"` — MOVE the file into `quarantineRoot` instead of deleting
+ *                      it, so it stays recoverable. The conservative default
+ *                      for the automatic pull path: a background sync must
+ *                      never silently PURGE local files (DEV-1768 fix #3).
+ */
+export type CleanOrphanDisposition = "delete" | "quarantine";
+
 export interface ApplyScopeShrinkInput {
   journal: SyncJournal;
   plan: ScopeShrinkPlan;
@@ -273,49 +334,132 @@ export interface ApplyScopeShrinkInput {
    */
   forceScopeShrink: boolean;
   reason?: "scope_shrink" | "narrow_apply" | "manual";
+  /**
+   * How to dispose of CLEAN orphans. Defaults to `"delete"` so existing
+   * callers (and the confirmed `narrow --apply` ritual) keep their behavior;
+   * the automatic pull path passes `"quarantine"`.
+   */
+  cleanDisposition?: CleanOrphanDisposition;
+  /**
+   * Absolute directory clean orphans are relocated into when
+   * `cleanDisposition === "quarantine"`. Each orphan moves to
+   * `<quarantineRoot>/<orphan.path>` (parent dirs created). REQUIRED when
+   * quarantining; if absent, the function falls back to `"delete"` so it can
+   * never get stuck unable to make progress.
+   */
+  quarantineRoot?: string;
 }
 
 export interface ApplyScopeShrinkResult {
+  /** Clean orphans `unlink`ed from disk (only when disposition is `delete`). */
   cleanRemoved: number;
+  /** Clean orphans MOVED to quarantine (only when disposition is `quarantine`). */
+  cleanQuarantined: number;
+  /** Dirty orphans tombstoned in the journal (file LEFT on disk). */
   dirtyTombstoned: number;
+  /** Named paths deleted — for explicit, non-silent operator reporting. */
+  removedPaths: string[];
+  /** Named paths moved to quarantine — for explicit reporting. */
+  quarantinedPaths: string[];
+  /** Named dirty paths un-tracked but KEPT on disk — for explicit reporting. */
+  dirtyKeptPaths: string[];
+  /** Absolute quarantine directory used (when anything was quarantined). */
+  quarantineRoot?: string;
+}
+
+/**
+ * Move a clean orphan from the working tree into the quarantine tree,
+ * preserving its relative path. Same-device `rename` first (cheap, atomic);
+ * cross-device falls back to copy+unlink. A missing source is a no-op (the
+ * user already removed it — harmless). Returns true iff the file was relocated
+ * (or was already absent), false only on an unexpected error the caller should
+ * surface.
+ */
+function quarantineOrphan(
+  srcAbs: string,
+  destAbs: string,
+): void {
+  fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+  try {
+    fs.renameSync(srcAbs, destAbs);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return; // source already gone — nothing to move
+    if (code === "EXDEV") {
+      // Cross-device move: copy then unlink. cpSync handles files + symlinks.
+      fs.cpSync(srcAbs, destAbs, { recursive: true, verbatimSymlinks: true });
+      fs.rmSync(srcAbs, { recursive: true, force: true });
+      return;
+    }
+    throw err;
+  }
 }
 
 /**
- * Apply a scope-shrink plan: delete clean orphans on disk + tombstone their
- * journal entries. With `forceScopeShrink: true`, dirty orphans are
- * preserved on disk but their journal entries are also tombstoned.
+ * Apply a scope-shrink plan: dispose of clean orphans (delete OR quarantine)
+ * + tombstone their journal entries. With `forceScopeShrink: true`, dirty
+ * orphans are PRESERVED on disk and only their journal entries are tombstoned
+ * (so they stop being re-flagged on every pull — the idempotent recovery seam).
  *
- * Returns counts for the audit log row (`scope_shrink_blocked` /
- * `scope_shrink_forced`).
+ * Returns counts AND named paths so the caller can report exactly what moved /
+ * was un-tracked — never a silent purge (DEV-1768 fix #3).
  */
 export function applyScopeShrink(
   input: ApplyScopeShrinkInput,
 ): ApplyScopeShrinkResult {
   const { journal, plan, hqRoot, forceScopeShrink } = input;
   const reason = input.reason ?? "scope_shrink";
+  // Quarantine only when explicitly asked AND a destination is provided;
+  // otherwise fall back to delete so we always make progress.
+  const quarantining =
+    input.cleanDisposition === "quarantine" && !!input.quarantineRoot;
   let cleanRemoved = 0;
+  let cleanQuarantined = 0;
   let dirtyTombstoned = 0;
+  const removedPaths: string[] = [];
+  const quarantinedPaths: string[] = [];
+  const dirtyKeptPaths: string[] = [];
 
   for (const orphan of plan.clean) {
     const absPath = path.join(hqRoot, orphan.path);
-    try {
-      fs.unlinkSync(absPath);
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code !== "ENOENT") throw err; // missing-on-disk is fine; anything else escalates
+    if (quarantining) {
+      const destAbs = path.join(input.quarantineRoot!, orphan.path);
+      quarantineOrphan(absPath, destAbs);
+      tombstoneEntry(journal, orphan.path, reason);
+      cleanQuarantined++;
+      quarantinedPaths.push(orphan.path);
+    } else {
+      try {
+        fs.unlinkSync(absPath);
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code !== "ENOENT") throw err; // missing-on-disk is fine; anything else escalates
+      }
+      tombstoneEntry(journal, orphan.path, reason);
+      cleanRemoved++;
+      removedPaths.push(orphan.path);
     }
-    tombstoneEntry(journal, orphan.path, reason);
-    cleanRemoved++;
   }
 
   if (forceScopeShrink) {
     for (const orphan of plan.dirty) {
-      // Do NOT delete the file — that's the entire point of the `--force`
-      // contract: keep dirty content on disk, prune only the journal entry.
+      // Do NOT delete the file — keep dirty content on disk, prune only the
+      // journal entry so it stops being re-flagged as an orphan on each pull.
       tombstoneEntry(journal, orphan.path, reason);
       dirtyTombstoned++;
+      dirtyKeptPaths.push(orphan.path);
     }
   }
 
-  return { cleanRemoved, dirtyTombstoned };
+  return {
+    cleanRemoved,
+    cleanQuarantined,
+    dirtyTombstoned,
+    removedPaths,
+    quarantinedPaths,
+    dirtyKeptPaths,
+    ...(quarantining && quarantinedPaths.length > 0
+      ? { quarantineRoot: input.quarantineRoot }
+      : {}),
+  };
 }

package/src/sync/pull-scope.ts

@@ -0,0 +1,161 @@
+/**
+ * Effective per-company PULL scope resolution (US-005), shared between
+ * `hq-sync-runner` (the menubar's background sync) and `hq sync pull|now`
+ * (the hq-cli foreground sync).
+ *
+ * BACKGROUND — why this lives in one place. The runner historically owned
+ * this resolver while hq-cli's pull paths resolved the membership's sync-mode
+ * only to drive the narrow-hint banner and then called `sync()` WITHOUT a
+ * `syncMode`/`prefixSet`. That meant every hq-cli pull silently ran
+ * `syncMode: "all"` and stamped an `all`-mode `PullRecord` (prefixSet `[""]`)
+ * — even for a membership whose real mode is `shared`/`custom`. For an owner
+ * (whose STS is wide by role-bypass) that journals the WHOLE company. The next
+ * menubar runner sync then resolves the REAL narrowed scope, scope-shrinks
+ * against the seeded `[""]`, and — if any out-of-scope file was edited locally
+ * — throws `ScopeShrinkBlockedError(all → shared)` and exits 2 on every
+ * subsequent run: a permanent wedge (DEV-1768 / feedback_f7663e92).
+ *
+ * The two surfaces drifting apart is exactly what caused the wedge, so the
+ * resolver is defined ONCE here and consumed by both. Any future change to how
+ * scope is derived now lands for the runner and the CLI in lockstep.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { coalescePrefixes, grantPathToPrefix } from "../prefix-coalesce.js";
+import type {
+  ExplicitGrant,
+  MembershipSyncConfig,
+  SyncMode,
+} from "../vault-client.js";
+
+/**
+ * Minimal structural surface `resolvePullScope` needs. Both the runner's
+ * `VaultClientSurface` and hq-cli's concrete `VaultClient` satisfy it, so
+ * either can be passed without an adapter.
+ */
+export interface PullScopeClient {
+  listMyMemberships(): Promise<
+    Array<{ companyUid: string; membershipKey: string }>
+  >;
+  getMembershipSyncConfig?: (
+    membershipId: string,
+  ) => Promise<MembershipSyncConfig>;
+  listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
+}
+
+/**
+ * Effective download scope for one company leg (US-005). Resolved per company
+ * just before its pull, then handed to `sync()` as `{ syncMode, prefixSet }`.
+ */
+export interface PullScope {
+  syncMode: SyncMode;
+  /** Coalesced company-relative prefixes; omitted/undefined for `all`. */
+  prefixSet?: string[];
+}
+
+/**
+ * Resolve the effective download scope for a company target.
+ *
+ *   - `all`    → no prefix set; full-bucket pull (legacy behavior).
+ *   - `shared` → coalesced caller explicit grants (company-relative paths,
+ *                same namespace as `RemoteFile.key`).
+ *   - `custom` → coalesced `customPaths` from the sync-config row.
+ *
+ * DEGRADE-TO-`all` CONTRACT: any failure (missing client method, membership
+ * not found, network error, grant fetch error) returns `{ syncMode: "all" }`.
+ * A transient failure must NEVER silently narrow scope — that would prune the
+ * local tree. A genuinely-empty grant list (the method exists and returns `[]`)
+ * is a real "nothing shared with me" and IS allowed to narrow.
+ */
+export async function resolvePullScope(
+  client: PullScopeClient,
+  companyUid: string,
+  // Company slug — required to normalize grant paths (which may be anchored
+  // at `companies/<slug>/` or `<slug>/`) into the company-relative namespace.
+  slug: string,
+  // Local HQ root — used to read the per-machine pin set (`.hq/pins.json`).
+  // When omitted, pins are simply not unioned (no behavior change).
+  hqRoot?: string,
+): Promise<PullScope> {
+  if (!client.getMembershipSyncConfig) return { syncMode: "all" };
+  try {
+    const memberships = await client.listMyMemberships();
+    const m = memberships.find((x) => x.companyUid === companyUid);
+    if (!m) return { syncMode: "all" };
+    const cfg = await client.getMembershipSyncConfig(m.membershipKey);
+    if (cfg.syncMode === "all") return { syncMode: "all" };
+
+    // Pins are company-relative prefixes a user explicitly materialized via
+    // `hq files get`. They're unioned into the scope so a scoped pull keeps
+    // them instead of pruning them as out-of-scope orphans. Pins only WIDEN
+    // scope, never narrow — and `all` mode (handled above) ignores them since
+    // it pulls everything anyway.
+    const pinPrefixes = hqRoot ? readPinnedPrefixes(hqRoot, slug) : [];
+
+    if (cfg.syncMode === "custom") {
+      const customPrefixes = (cfg.customPaths ?? []).map((p) =>
+        grantPathToPrefix(p, slug),
+      );
+      // A bare-everything entry ("" — e.g. a `*` path) collapses under
+      // `coalescePrefixes` (which drops empties) to "nothing", which would
+      // prune the whole tree. An everything-scope is semantically `all`.
+      if (customPrefixes.some((p) => p === "")) return { syncMode: "all" };
+      return {
+        syncMode: "custom",
+        prefixSet: coalescePrefixes([...customPrefixes, ...pinPrefixes]),
+      };
+    }
+    // shared: scope to the caller's explicit grants. Real grant paths are
+    // inconsistent — full (`companies/<slug>/x/*`), slug-anchored
+    // (`<slug>/x/*`), company-relative (`x/*`), bare globs (`*`), and exact
+    // files all coexist in production — so each is normalized via
+    // `grantPathToPrefix` into a company-relative, startsWith-friendly prefix
+    // (the namespace the engine's `RemoteFile.key`s live in) before coalescing.
+    //
+    // SAFETY: if the client can't fetch grants, we must NOT fall through to an
+    // empty `shared` scope — that would tell the engine "nothing is in scope"
+    // and scope-shrink would prune every clean local file. Degrade to `all`
+    // instead. A genuinely-empty grant list (the method exists and returns
+    // []) is a real "nothing shared with me" and is allowed to narrow.
+    if (!client.listMyExplicitGrants) return { syncMode: "all" };
+    const grants = await client.listMyExplicitGrants(companyUid);
+    const sharedPrefixes = grants.map((g) => grantPathToPrefix(g.path, slug));
+    // A wildcard grant (`*`) normalizes to "" = everything. Since
+    // `coalescePrefixes` drops empties (collapsing "everything" to "nothing"),
+    // treat any such grant as full-access `all` rather than risk pruning.
+    if (sharedPrefixes.some((p) => p === "")) return { syncMode: "all" };
+    return {
+      syncMode: "shared",
+      prefixSet: coalescePrefixes([...sharedPrefixes, ...pinPrefixes]),
+    };
+  } catch {
+    // Degrade to `all` — never prune on a resolution failure.
+    return { syncMode: "all" };
+  }
+}
+
+/**
+ * Read the per-machine pin set (`<hqRoot>/.hq/pins.json`) and return the
+ * company-relative pinned prefixes for `slug`. These are prefixes the user
+ * materialized on demand via `hq files get` that must survive a scoped pull.
+ *
+ * Tolerant by construction: a missing, unreadable, or malformed file yields
+ * `[]` (no pins) — pins only ever widen scope, so "no pins" is the safe
+ * default. Empty-string entries are dropped (an everything-pin is meaningless
+ * here; `all` mode already covers that case).
+ */
+export function readPinnedPrefixes(hqRoot: string, slug: string): string[] {
+  try {
+    const raw = fs.readFileSync(path.join(hqRoot, ".hq", "pins.json"), "utf-8");
+    const parsed = JSON.parse(raw) as { pins?: Record<string, unknown> };
+    const list = parsed?.pins?.[slug];
+    if (Array.isArray(list)) {
+      return list.filter(
+        (p): p is string => typeof p === "string" && p.length > 0,
+      );
+    }
+  } catch {
+    /* missing / unreadable / malformed → no pins */
+  }
+  return [];
+}