claude-nomad 0.26.2 → 0.27.0

package/src/extras-sync.ts

@@ -1,102 +1,27 @@
-import { cpSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { HOME, HOST, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { HOME, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
 import { listDivergingFiles } from './extras-sync.diff.ts';
-import { assertSafeLocalRoot, assertSafeLogical } from './extras-sync.guards.ts';
-import { log, warn } from './utils.ts';
-import { backupExtrasWrite, backupRepoWrite } from './utils.fs.ts';
-import { encodePath, readPathMap } from './utils.json.ts';
-
-/** Parsed `path-map.json` plus its validated `extras` block. */
-type ValidatedExtras = { map: PathMap; extrasMap: Record<string, string[]> };
-
-/** Skip counts: `unmapped` per-project (no host path / `'TBD'`), `skipped` per-dirname (not whitelisted). */
-type ExtrasCounts = { unmapped: number; skipped: number };
-
-/**
- * Load and validate `path-map.json` for an extras op, owning the guard order
- * so the "FATAL before any filesystem mutation" contract holds for every
- * caller. Returns the parsed map plus its `extras` block, or `null` on a clean
- * early-exit (missing `path-map.json`, a missing repo extras dir when
- * `requireRepoExtras`, or an empty/absent `extras` key). THE VALIDATION PASS
- * runs here, up-front over the whole map (`assertSafeLogical` per logical,
- * `assertSafeLocalRoot` per mapped non-`'TBD'` path) so a clean entry ahead of
- * a poisoned one cannot let a `mkdirSync`/`cpSync` land before the FATAL fires.
- *
- * @param opts.requireRepoExtras - Also require `shared/extras/` (pull side).
- * @param opts.missingMsg - `log()` line on the missing-prereq exit (omitted for
- *   the divergence check, which skips silently).
- */
-function loadValidatedExtras(opts: {
-  requireRepoExtras?: boolean;
-  missingMsg?: string;
-}): ValidatedExtras | null {
-  const mapPath = join(REPO_HOME, 'path-map.json');
-  const repoExtras = join(REPO_HOME, 'shared', 'extras');
-  if (!existsSync(mapPath) || (opts.requireRepoExtras === true && !existsSync(repoExtras))) {
-    if (opts.missingMsg !== undefined) log(opts.missingMsg);
-    return null;
-  }
-
-  const map = readPathMap(mapPath);
-  const extrasMap = map.extras ?? {};
-  if (Object.keys(extrasMap).length === 0) return null;
-
-  for (const logical of Object.keys(extrasMap)) {
-    assertSafeLogical(logical);
-    const localRoot = map.projects[logical]?.[HOST];
-    if (localRoot && localRoot !== 'TBD') assertSafeLocalRoot(localRoot, logical);
-  }
-  return { map, extrasMap };
-}
-
-/**
- * Yield every surviving `{ logical, localRoot, dirname }` extras target after
- * the per-project and per-dirname skip filters, mutating `counts` as it goes
- * (`unmapped++` for a project with no host path / `'TBD'`, then skip it;
- * `skipped++` for a dirname outside `SUPPORTED_EXTRAS`). Shared by push, pull,
- * and the divergence check so all three walk identical skip/count semantics;
- * the caller builds src/dst from the yielded triple.
- *
- * @param quiet - Suppress the per-skip `log()` lines (the read-only divergence
- *   check skips silently; push/pull narrate). Counts increment either way.
- */
-function* eachExtrasTarget(
-  v: ValidatedExtras,
-  counts: ExtrasCounts,
-  quiet = false,
-): Generator<{ logical: string; localRoot: string; dirname: string }> {
-  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
-  for (const [logical, dirnames] of Object.entries(v.extrasMap)) {
-    const localRoot = v.map.projects[logical]?.[HOST];
-    if (!localRoot || localRoot === 'TBD') {
-      counts.unmapped++;
-      if (!quiet) log(`skip ${logical}: no path for ${HOST}`);
-      continue;
-    }
-    for (const dirname of dirnames) {
-      if (!whitelist.includes(dirname)) {
-        counts.skipped++;
-        if (!quiet) log(`skip ${dirname} for ${logical}: not in SUPPORTED_EXTRAS`);
-        continue;
-      }
-      yield { logical, localRoot, dirname };
-    }
-  }
-}
-
-/**
- * Recursive mirror copy: `rmSync` then `cpSync` so dst-only entries are
- * removed (true mirror, not just overwrite). Passes `verbatimSymlinks: true`
- * to keep relative symlink targets unrewritten across hosts (Pitfall 1;
- * nodejs/node issue 41693). Exported so the test file can call it directly;
- * `remapExtrasPush` and `remapExtrasPull` are the primary public API.
- */
-export function copyExtras(src: string, dst: string): void {
-  rmSync(dst, { recursive: true, force: true });
-  cpSync(src, dst, { recursive: true, force: true, verbatimSymlinks: true });
-}
+import {
+  copyExtras,
+  eachExtrasTarget,
+  loadValidatedExtras,
+  type ExtrasCounts,
+  type ValidatedExtras,
+} from './extras-sync.core.ts';
+import { assertSafeLogical } from './extras-sync.guards.ts';
+import { warn } from './utils.ts';
+import { encodePath } from './utils.json.ts';
+
+// Re-export the shared primitives so existing import sites that pull them from
+// `./extras-sync.ts` (tests call `copyExtras` directly) keep working unchanged.
+export { copyExtras, eachExtrasTarget, loadValidatedExtras };
+export type { ExtrasCounts, ValidatedExtras };
+
+// The two public remap ops live in the sibling module to hold the soft
+// line-cap; re-exported here so `./extras-sync.ts` stays the public surface.
+export { remapExtrasPull, remapExtrasPush } from './extras-sync.remap.ts';
 
 /**
  * Repo-relative `shared/extras/<logical>/<dirname>` paths for every (logical,
@@ -125,77 +50,6 @@ export function whitelistedExtrasPaths(map: PathMap): string[] {
   return [...paths].sort((a, b) => a.localeCompare(b));
 }
 
-/**
- * Push: copy whitelisted extras directories under each project's localRoot
- * into the repo at `shared/extras/<logical>/<dirname>/`. Returns
- * `{ unmapped, skipped }` with intentionally asymmetric granularity (see
- * `eachExtrasTarget`): `unmapped` per-project, `skipped` per-dirname; both feed
- * `emitSummary`. `opts.dryRun` logs `would push extras:` lines without writing,
- * with identical count semantics. Legacy `path-map.json` without an `extras`
- * key returns `{ unmapped: 0, skipped: 0 }` cleanly.
- */
-export function remapExtrasPush(ts: string, opts: { dryRun?: boolean } = {}): ExtrasCounts {
-  const dryRun = opts.dryRun === true;
-  const counts: ExtrasCounts = { unmapped: 0, skipped: 0 };
-  const v = loadValidatedExtras({ missingMsg: 'no path-map.json; skipping extras push' });
-  if (v === null) return counts;
-
-  const repoExtras = join(REPO_HOME, 'shared', 'extras');
-  if (!dryRun) mkdirSync(repoExtras, { recursive: true });
-
-  for (const { logical, localRoot, dirname } of eachExtrasTarget(v, counts)) {
-    const src = join(localRoot, dirname);
-    if (!existsSync(src)) continue;
-    const dst = join(repoExtras, logical, dirname);
-    if (dryRun) {
-      log(`would push extras: ${src} -> ${dst}`);
-      continue;
-    }
-    backupRepoWrite(dst, ts, REPO_HOME);
-    copyExtras(src, dst);
-    log(`pushed extras ${logical}/${dirname} -> shared/extras/${logical}/${dirname}`);
-  }
-  return counts;
-}
-
-/**
- * Pull: copy whitelisted extras from `shared/extras/<logical>/<dirname>/`
- * back into each project's localRoot on this host. Returns `{ unmapped,
- * skipped }` with the same asymmetric granularity as `remapExtrasPush`.
- * `opts.dryRun` logs `would overwrite extras:` lines without writing. Uses
- * `backupExtrasWrite` (not `backupBeforeWrite`) because `<localRoot>/<dirname>`
- * lives outside `CLAUDE_HOME` and the standard helper's relative-path guard
- * would no-op and lose prior content. Legacy `path-map.json` without an
- * `extras` key, or a missing `shared/extras/`, both produce a clean no-op.
- */
-export function remapExtrasPull(ts: string, opts: { dryRun?: boolean } = {}): ExtrasCounts {
-  const dryRun = opts.dryRun === true;
-  const counts: ExtrasCounts = { unmapped: 0, skipped: 0 };
-  const v = loadValidatedExtras({
-    requireRepoExtras: true,
-    missingMsg: 'no path-map or repo extras dir; skipping extras remap',
-  });
-  if (v === null) return counts;
-
-  const repoExtras = join(REPO_HOME, 'shared', 'extras');
-
-  for (const { logical, localRoot, dirname } of eachExtrasTarget(v, counts)) {
-    const src = join(repoExtras, logical, dirname);
-    if (!existsSync(src)) continue;
-    const dst = join(localRoot, dirname);
-    if (dryRun) {
-      log(`would overwrite extras: ${dst} (from ${src})`);
-      continue;
-    }
-    // Snapshot the host-side dst BEFORE copyExtras clobbers it. Anchor
-    // on localRoot so the backup tree mirrors the project layout.
-    backupExtrasWrite(dst, ts, localRoot);
-    copyExtras(src, dst);
-    log(`pulled extras ${logical}/${dirname} -> ${dst}`);
-  }
-  return counts;
-}
-
 /**
  * Read-only pre-pull check: compare local `<localRoot>/<dirname>/` against
  * the just-pulled `shared/extras/<logical>/<dirname>/` and emit a WARN per
@@ -214,7 +68,7 @@ export function divergenceCheckExtras(ts: string): void {
 
   const counts: ExtrasCounts = { unmapped: 0, skipped: 0 };
   const backupRoot = join(HOME, '.cache', 'claude-nomad', 'backup', ts, 'extras');
-  for (const { logical, localRoot, dirname } of eachExtrasTarget(v, counts, true)) {
+  for (const { logical, localRoot, dirname } of eachExtrasTarget(v, counts)) {
     const local = join(localRoot, dirname);
     const repo = join(REPO_HOME, 'shared', 'extras', logical, dirname);
     if (!existsSync(local) || !existsSync(repo)) continue;

package/src/links.ts

@@ -64,8 +64,19 @@ export function applySharedLinks(ts: string, opts: { dryRun?: boolean } = {}): v
  * would produce. The unified textual diff of the would-be-written content
  * is produced by `computePreview` in `src/preview.ts`, not here, to keep
  * this function's contract simple (mutation or log-only).
+ *
+ * Returns `{ label }` where `label` is the override-source tag
+ * (`'<HOST>.json'` when a host override exists, else `'no host overrides'`).
+ * The WET path no longer logs `wrote settings.json (base + <label>)` inline;
+ * `cmdPull` consumes the returned label to render the Settings row of its
+ * grouped tree. The dry-run `would write settings.json ...` log and the
+ * drift WARN are unchanged (the WET success log is the only thing that moved).
+ *
+ * @param ts - backup timestamp namespace for `backupBeforeWrite`.
+ * @param opts.dryRun - when `true`, log the would-write line and skip mutation.
+ * @returns `{ label }` describing the override source for the Settings row.
  */
-export function regenerateSettings(ts: string, opts: { dryRun?: boolean } = {}): void {
+export function regenerateSettings(ts: string, opts: { dryRun?: boolean } = {}): { label: string } {
   const dryRun = opts.dryRun === true;
   const basePath = join(REPO_HOME, 'shared', 'settings.base.json');
   const hostPath = join(REPO_HOME, 'hosts', `${HOST}.json`);
@@ -107,10 +118,10 @@ export function regenerateSettings(ts: string, opts: { dryRun?: boolean } = {}):
 
   if (dryRun) {
     log(`would write settings.json (base + ${overrideLabel})`);
-    return;
+    return { label: overrideLabel };
   }
 
   backupBeforeWrite(settingsPath, ts);
   writeJsonAtomic(settingsPath, merged);
-  log(`wrote settings.json (base + ${overrideLabel})`);
+  return { label: overrideLabel };
 }

package/src/output-tree.ts

@@ -0,0 +1,91 @@
+import { failGlyph, red } from './color.ts';
+
+/**
+ * Bare `failGlyph` codepoint (`✗`, U+2717) without any WSL padding the
+ * `failGlyph` constant may carry. Header rendering composes its own
+ * spacing (`${red(failGlyph)} ${header}`), so the section-header path
+ * must use the unpadded codepoint to avoid a double space on WSL.
+ */
+const FAIL_GLYPH_BARE = '✗';
+
+/**
+ * Tree-style output builder shared by `cmdDoctor`, `cmdPush`, and `cmdPull`.
+ * Callers build an ordered list of `DoctorSection`s, push pre-rendered
+ * plain-text items into the relevant section, then call `renderTree`
+ * (aliased `renderDoctor` for doctor's call site) to emit a Claude Code
+ * `/doctor`-style tree (`Header` / `  ├ item` / `  └ last`) on stdout.
+ *
+ * Color and status glyphs (okGlyph/warnGlyph/failGlyph/infoGlyph) already
+ * live inside the item text; this module never re-colors or re-tokenizes.
+ * Sections with zero items are skipped at render time (no empty headers).
+ *
+ * Output goes directly through `console.log` rather than `utils.log` so the
+ * dim `ℹ︎` info glyph used by `pull` / `push` / `init` does NOT appear in
+ * doctor output (doctor has its own glyphs per row). Test assertions continue
+ * to spy on `console.log`.
+ */
+export type DoctorSection = {
+  header: string;
+  items: string[];
+};
+
+/** Construct an empty section with the given header. */
+export function section(header: string): DoctorSection {
+  return { header, items: [] };
+}
+
+/** Append one rendered line to a section. */
+export function addItem(s: DoctorSection, text: string): void {
+  s.items.push(text);
+}
+
+/**
+ * True when any item in the section contains the FAIL glyph.
+ * Color-wrapped failGlyph (`[31m✗[39m`) still contains the
+ * glyph as a substring, so this works for both color-on and color-off output.
+ */
+function sectionFailed(s: DoctorSection): boolean {
+  return s.items.some((line) => line.includes(failGlyph));
+}
+
+/**
+ * Render one section: a (possibly fail-glyph-prefixed) header followed by its
+ * items as a tree. Empty-string items print as true blank lines; the `└` elbow
+ * attaches to the last non-empty item so a trailing blank cannot strand it.
+ */
+function renderSection(s: DoctorSection): void {
+  const header = sectionFailed(s) ? `${red(FAIL_GLYPH_BARE)} ${s.header}` : s.header;
+  console.log(header);
+  const lastContent = s.items.reduce((acc, item, j) => (item !== '' ? j : acc), -1);
+  for (let j = 0; j < s.items.length; j++) {
+    if (s.items[j] === '') console.log('');
+    else console.log(`${j === lastContent ? '  └ ' : '  ├ '}${s.items[j]}`);
+  }
+}
+
+/**
+ * Emit the full grouped tree. Skips empty sections, prefixes failed-section
+ * headers with a red `✗ ` glyph (U+2717, same as the per-item FAIL glyph so
+ * `grep -F '✗'` catches both row and header failures), and writes one blank
+ * line between rendered sections (no leading or trailing blank).
+ *
+ * An empty-string item renders as a true blank line (no tree connector), which
+ * lets a reporter set off a footer block (e.g. the `--check-shared` description
+ * legend) with vertical whitespace. The `└` connector attaches to the last
+ * non-empty item rather than the last array slot so a trailing blank does not
+ * strand the elbow on an empty line.
+ */
+export function renderTree(sections: DoctorSection[]): void {
+  const visible = sections.filter((s) => s.items.length > 0);
+  for (let i = 0; i < visible.length; i++) {
+    if (i > 0) console.log('');
+    renderSection(visible[i]);
+  }
+}
+
+/**
+ * Back-compat alias for `renderTree`. Doctor's call site imports
+ * `renderDoctor`; push/pull import `renderTree`. Both point at the same
+ * implementation so doctor output stays byte-identical.
+ */
+export const renderDoctor = renderTree;

package/src/push-leak-verdict.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared leak-scan verdict vocabulary for `cmdPush`. Both the dry-run preview
+ * (`previewPushLeaks` in `./push-preview.ts`) and the real-push scan
+ * (`scanPushVerdict` here) produce the same structured `LeakVerdict` so the
+ * one-line Leak scan row rendered inside the grouped tree cannot drift between
+ * the two paths. The multi-line `recovery` block (the `buildSessionAwareFatal`
+ * body) is printed by `cmdPush` BELOW the rendered tree on a leak.
+ *
+ * On a real push the scan still aborts the run: `cmdPush` renders the tree with
+ * the ✗ verdict row, then throws a `NomadFatal` carrying `recovery` so the
+ * existing catch prints the recovery block and sets a non-zero exit. The
+ * dry-run path never throws; it only sets `process.exitCode = 1`.
+ */
+
+import { failGlyph, green, okGlyph, red } from './color.ts';
+import { REPO_HOME } from './config.ts';
+import { gitleaksInstallHint } from './push-checks.ts';
+import {
+  type Finding,
+  buildSessionAwareFatal,
+  partitionFindings,
+  scanStagedTree,
+} from './push-gitleaks.ts';
+
+/**
+ * Structured leak-scan verdict.
+ *
+ * - `leak`: `true` only when findings were present (a scan crash is surfaced
+ *   via a ✗ `verdictRow` but is NOT a leak, so the dry-run path does not throw).
+ * - `verdictRow`: the rendered one-line Leak scan row (glyph embedded).
+ * - `recovery`: the `buildSessionAwareFatal` body on a leak, else `null`.
+ */
+export type LeakVerdict = {
+  leak: boolean;
+  verdictRow: string;
+  recovery: string | null;
+};
+
+/** Rendered clean Leak scan row (no findings). */
+export const noLeaksRow = (): string => `${green(okGlyph)} no leaks`;
+
+/** Rendered ✗ Leak scan row (caller supplies the message text). */
+export const failRow = (text: string): string => `${red(failGlyph)} ${text}`;
+
+/**
+ * Build the one-line ✗ Leak scan verdict row for a non-empty findings set,
+ * naming the affected session count. Falls back to the raw finding count when
+ * no finding matches the session-path pattern. Pure.
+ *
+ * @param findings - The non-empty findings array.
+ * @returns The rendered ✗ verdict row.
+ */
+export function leakVerdictRow(findings: Finding[]): string {
+  const { bySession } = partitionFindings(findings);
+  const n = bySession.size > 0 ? bySession.size : findings.length;
+  return failRow(`gitleaks detected secrets in ${n} session transcript(s)`);
+}
+
+/**
+ * Build the leak verdict for a non-empty findings set: the ✗ verdict row plus
+ * the `buildSessionAwareFatal` recovery body. Pure (no `process.exitCode`
+ * side effect; callers own that). Shared by the dry-run and real-push paths so
+ * the verdict row and recovery body cannot diverge.
+ *
+ * @param findings - The non-empty findings array.
+ * @returns A `leak=true` verdict carrying the ✗ row and recovery body.
+ */
+function leakFound(findings: Finding[]): LeakVerdict {
+  const { bySession, other } = partitionFindings(findings);
+  return {
+    leak: true,
+    verdictRow: leakVerdictRow(findings),
+    recovery: buildSessionAwareFatal(bySession, other),
+  };
+}
+
+/**
+ * Map a `scanStagedTree` result to a structured `LeakVerdict`, applying the
+ * shared side effect (`process.exitCode = 1` on findings or a scan crash). A
+ * `null` report (scan crash) yields a ✗ scan-failed row with `recovery=null`
+ * and is NOT classified as a `leak` (so the dry-run path neither throws nor
+ * offers a phantom drop-session hint). An empty array yields the clean
+ * `✓ no leaks` row. Non-empty findings yield the ✗ verdict row plus the
+ * `buildSessionAwareFatal` recovery body.
+ *
+ * @param findings - Output of `scanStagedTree`, or `null` on scan crash.
+ * @returns The structured verdict for the Leak scan section.
+ */
+export function verdictFromFindings(findings: Finding[] | null): LeakVerdict {
+  if (findings === null) {
+    process.exitCode = 1;
+    return {
+      leak: false,
+      verdictRow: failRow('scan failed, no parseable report'),
+      recovery: null,
+    };
+  }
+  if (findings.length === 0) return { leak: false, verdictRow: noLeaksRow(), recovery: null };
+  process.exitCode = 1;
+  return leakFound(findings);
+}
+
+/**
+ * Verdict for a scan that threw before producing a report (e.g. gitleaks/git
+ * absent on the dry-run path). Sets `process.exitCode = 1` and yields a ✗ row
+ * with `recovery=null`. Does not mark `leak` so the caller never throws.
+ *
+ * @param text - The ✗ row message text.
+ * @returns The structured scan-error verdict.
+ */
+export function verdictScanError(text: string): LeakVerdict {
+  process.exitCode = 1;
+  return { leak: false, verdictRow: failRow(text), recovery: null };
+}
+
+/**
+ * Run the real-push staged gitleaks scan (the same `scanStagedTree(REPO_HOME,
+ * true)` the push gate uses) and RETURN a structured `LeakVerdict` instead of
+ * throwing. This lets `cmdPush` render the grouped tree with the ✗ Leak scan
+ * row BEFORE re-raising the FATAL so the recovery block prints below the tree.
+ *
+ * On findings: `leak=true`, `verdictRow` is the ✗ row, `recovery` is the
+ * `buildSessionAwareFatal` body. On a clean scan: `✓ no leaks`. On a null
+ * report (scanner crash, malformed JSON): a ✗ scan-failed verdict with
+ * `recovery` set to the same scan-failed FATAL string `runGitleaksScan` would
+ * have thrown, so `cmdPush` still aborts. ENOENT (gitleaks/git absent) maps to
+ * the platform-aware install-hint FATAL as `recovery` with a ✗ row.
+ *
+ * @returns The structured verdict for the real-push Leak scan section.
+ */
+export function scanPushVerdict(): LeakVerdict {
+  let findings: Finding[] | null;
+  try {
+    findings = scanStagedTree(REPO_HOME, true);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return {
+        leak: true,
+        verdictRow: failRow('gitleaks not found'),
+        recovery: gitleaksInstallHint(),
+      };
+    }
+    throw err;
+  }
+  if (findings === null) {
+    return {
+      leak: true,
+      verdictRow: failRow('scan failed, no parseable report'),
+      recovery: 'gitleaks scan failed: no parseable JSON report. Review the gitleaks output above.',
+    };
+  }
+  if (findings.length === 0) return { leak: false, verdictRow: noLeaksRow(), recovery: null };
+  return leakFound(findings);
+}

package/src/push-preview.ts

@@ -0,0 +1,160 @@
+/**
+ * Push dry-run gitleaks leak preview.
+ *
+ * Stages a read-only copy of the session transcripts and extras that a real
+ * `nomad push` would send for this host, then runs `scanStagedTree` against
+ * that temp tree. The verdict is RETURNED as a structured
+ * `{ leak, verdictRow, recovery }` (rather than logged) so `cmdPush` can place
+ * `verdictRow` in the grouped tree's Leak scan section and print `recovery`
+ * (the `buildSessionAwareFatal` body) below the tree. On findings it still sets
+ * `process.exitCode = 1`.
+ *
+ * This module is the push-dry-run-only path. The `nomad doctor --check-shared`
+ * preflight (session-only scan, no extras) is unchanged and lives in
+ * `./commands.doctor.check-shared.ts`. Extras-in-doctor is a deferred
+ * follow-up (out of scope here).
+ */
+
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { dim, infoGlyph } from './color.ts';
+import { CLAUDE_HOME, HOST, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { assertSafeLogical } from './extras-sync.guards.ts';
+import { copyExtras } from './extras-sync.ts';
+import { copyDirJsonlOnly } from './remap.ts';
+import { type LeakVerdict, verdictFromFindings, verdictScanError } from './push-leak-verdict.ts';
+import { scanStagedTree } from './push-gitleaks.ts';
+import { nowTimestamp } from './utils.fs.ts';
+import { encodePath } from './utils.json.ts';
+
+/** Rendered neutral Leak scan row when there was nothing to scan. */
+const NOTHING_TO_SCAN_ROW = `${dim(infoGlyph)} nothing to scan, no leaks`;
+
+/**
+ * Stage local session transcripts for HOST into `<tmpRoot>/shared/projects/<logical>/`
+ * using the same depth-0 `*.jsonl` filter as a real push. Builds the
+ * encoded-dir-to-logical reverse map from `map.projects` (skipping TBD or
+ * missing entries), then copies each matching `~/.claude/projects/<dir>/`.
+ *
+ * @param tmpRoot - Root of the throwaway staging tree.
+ * @param map - Parsed `path-map.json`.
+ * @returns Number of session directories staged.
+ */
+function stageSessions(tmpRoot: string, map: PathMap): number {
+  if (typeof map.projects !== 'object' || map.projects === null) return 0;
+
+  const reverse = new Map<string, string>();
+  for (const [logical, hosts] of Object.entries(map.projects)) {
+    assertSafeLogical(logical);
+    const p = hosts[HOST];
+    if (!p || p === 'TBD') continue;
+    reverse.set(encodePath(p), logical);
+  }
+
+  const localProjects = join(CLAUDE_HOME, 'projects');
+  if (!existsSync(localProjects)) return 0;
+
+  let staged = 0;
+  for (const dir of readdirSync(localProjects)) {
+    const logical = reverse.get(dir);
+    if (!logical) continue;
+    copyDirJsonlOnly(join(localProjects, dir), join(tmpRoot, 'shared', 'projects', logical));
+    staged++;
+  }
+  return staged;
+}
+
+/**
+ * Stage whitelisted extras for HOST into
+ * `<tmpRoot>/shared/extras/<logical>/<dirname>/`. Mirrors the skip semantics of
+ * `remapExtrasPush`: skips logicals with no host path or `'TBD'`, skips
+ * dirnames not in `SUPPORTED_EXTRAS`, and skips when the source path does not
+ * exist locally.
+ *
+ * Guards a non-object or missing `map.projects` defensively (mirroring
+ * `stageSessions`): a malformed map with an `extras` block but no usable
+ * `projects` stages nothing rather than throwing on the `map.projects[logical]`
+ * read.
+ *
+ * @param tmpRoot - Root of the throwaway staging tree.
+ * @param map - Parsed `path-map.json`.
+ * @returns Number of extras entries staged.
+ */
+function stageExtras(tmpRoot: string, map: PathMap): number {
+  if (typeof map.projects !== 'object' || map.projects === null) return 0;
+  const extrasMap = map.extras ?? {};
+  const whitelist: readonly string[] = SUPPORTED_EXTRAS;
+  let staged = 0;
+  for (const [logical, dirnames] of Object.entries(extrasMap)) {
+    assertSafeLogical(logical);
+    const localRoot = map.projects[logical]?.[HOST];
+    if (!localRoot || localRoot === 'TBD') continue;
+    for (const dirname of dirnames) {
+      if (!whitelist.includes(dirname)) continue;
+      const src = join(localRoot, dirname);
+      if (!existsSync(src)) continue;
+      const dst = join(tmpRoot, 'shared', 'extras', logical, dirname);
+      copyExtras(src, dst);
+      staged++;
+    }
+  }
+  return staged;
+}
+
+/**
+ * Run a read-only gitleaks leak preview of what `nomad push` would stage for
+ * this host: both mapped session transcripts
+ * (`shared/projects/<logical>/*.jsonl`) and opted-in extras
+ * (`shared/extras/<logical>/<dirname>`).
+ *
+ * Stages the content into a throwaway tree under
+ * `~/.cache/claude-nomad/push-preview-tree-<stamp>` and runs `scanStagedTree`
+ * with `forwardStreams=false` (read-only: no gitleaks stderr/stdout leak to the
+ * terminal). The temp tree is always removed in a `finally`, regardless of
+ * whether the scan found leaks, crashed, or returned clean. `REPO_HOME/shared`
+ * is never written.
+ *
+ * Returns a structured `LeakVerdict` rather than logging the verdict line so
+ * `cmdPush` can render `verdictRow` in the Leak scan section and print
+ * `recovery` below the tree. Side effects preserved: `process.exitCode = 1` on
+ * findings AND on a scan crash. A scan that throws maps to a ✗ scan-error row
+ * with `exitCode = 1`: ENOENT (gitleaks/git absent) keeps the "not on PATH"
+ * wording, any other error (e.g. EACCES) surfaces its real message so the
+ * cause is not mislabeled. Nothing-to-scan maps to a neutral ℹ︎ row.
+ *
+ * Fails closed before any copy: an unsafe `logical` key (path separator or
+ * `..`) raised by `assertSafeLogical` in the staging step propagates out as a
+ * `NomadFatal` to `cmdPush`, and the `finally` still removes the temp tree.
+ *
+ * @param map - Parsed `path-map.json` (already in scope from `cmdPush`).
+ * @returns The structured verdict for the Leak scan section.
+ */
+export function previewPushLeaks(map: PathMap): LeakVerdict {
+  const cacheDir = join(homedir(), '.cache', 'claude-nomad');
+  mkdirSync(cacheDir, { recursive: true });
+  const stamp = `${nowTimestamp()}-${process.pid}-${randomBytes(4).toString('hex')}`;
+  const tmpRoot = join(cacheDir, `push-preview-tree-${stamp}`);
+
+  try {
+    const sessionCount = stageSessions(tmpRoot, map);
+    const extrasCount = stageExtras(tmpRoot, map);
+    if (sessionCount + extrasCount === 0) {
+      return { leak: false, verdictRow: NOTHING_TO_SCAN_ROW, recovery: null };
+    }
+    let findings: ReturnType<typeof scanStagedTree>;
+    try {
+      findings = scanStagedTree(tmpRoot);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return verdictScanError('scan error (git or gitleaks not on PATH)');
+      }
+      return verdictScanError(`scan error: ${(err as Error).message}`);
+    }
+    return verdictFromFindings(findings);
+  } finally {
+    rmSync(tmpRoot, { recursive: true, force: true });
+  }
+}