claude-nomad 0.26.1 → 0.27.0

package/src/commands.push.sections.ts

@@ -0,0 +1,171 @@
+/**
+ * Pure section-builder helpers shared by `cmdPush` and `cmdPull` for the
+ * doctor-style grouped tree. The builders are verb-agnostic: they take the
+ * already-selected detail array (the wet `pushed`/`pulled` list or the dry-run
+ * `wouldPush`/`wouldPull` list) plus the relevant skip count, so the same code
+ * renders both push and pull rows. Row shapes mirror `nomad doctor`: one
+ * `${green(okGlyph)} <item>` row per synced item, then a single collapsed
+ * `${dim(infoGlyph)} <N> <noun>` count row instead of one row per skip.
+ *
+ * Sections returned here may be empty; `renderTree` (in `./output-tree.ts`)
+ * skips empty sections, so a Sessions/Extras group with zero items and a zero
+ * skip count never prints a header.
+ */
+
+import { dim, green, infoGlyph, okGlyph } from './color.ts';
+import type { remapExtrasPush } from './extras-sync.ts';
+import { type DoctorSection, addItem, renderTree, section } from './output-tree.ts';
+import type { LeakVerdict } from './push-leak-verdict.ts';
+import type { remapPush } from './remap.ts';
+import { summaryRow } from './summary.ts';
+
+/**
+ * Build the single collapsed count row, or `null` when `n` is zero. Used for
+ * the "not in path-map" session skips and the "extras skipped" extras skips so
+ * the noisy per-project skip lines fold into one row that points at
+ * `nomad doctor` for the authoritative list.
+ *
+ * @param n - The skip count (no row is produced when `0`).
+ * @param noun - The collapsed-row phrasing after the count (e.g.
+ *   `'not in path-map (run nomad doctor to list)'` or `'extras skipped'`).
+ * @returns The rendered ℹ︎ count row, or `null` when `n` is `0`.
+ */
+export function collapsedSkipRow(n: number, noun: string): string | null {
+  if (n <= 0) return null;
+  return `${dim(infoGlyph)} ${n} ${noun}`;
+}
+
+/**
+ * Build the Settings section for `cmdPull`: a single
+ * `${green(okGlyph)} settings.json (base + <label>)` row. `label` is the
+ * override-source tag returned by `regenerateSettings` (`'<HOST>.json'` when a
+ * host override exists, else `'no host overrides'`), surfacing what was written
+ * without `regenerateSettings` logging the line inline. Push has no Settings
+ * section, so this helper is pull-only.
+ *
+ * @param label - The override-source tag from `regenerateSettings`.
+ * @returns A `Settings` `DoctorSection` holding the one settings row.
+ */
+export function buildSettingsSection(label: string): DoctorSection {
+  const s = section('Settings');
+  addItem(s, `${green(okGlyph)} settings.json (base + ${label})`);
+  return s;
+}
+
+/**
+ * Build the Sessions section: one ✓ row per synced logical name plus, when
+ * `unmapped > 0`, a single collapsed `${unmapped} not in path-map` count row.
+ * Verb-agnostic: pass `remapResult.pushed` (or `wouldPush`, or the pull-side
+ * `pulled`/`wouldPull`) as `items`.
+ *
+ * @param items - The logical names synced this run.
+ * @param unmapped - Count of path-map entries skipped for this host.
+ * @returns A `Sessions` `DoctorSection` (possibly empty).
+ */
+export function buildSessionsSection(items: string[], unmapped: number): DoctorSection {
+  const s = section('Sessions');
+  for (const logical of items) addItem(s, `${green(okGlyph)} ${logical}`);
+  const skip = collapsedSkipRow(unmapped, 'not in path-map (run nomad doctor to list)');
+  if (skip !== null) addItem(s, skip);
+  return s;
+}
+
+/**
+ * Build the Extras section: one ✓ row per synced `<logical>/<dirname>` entry
+ * plus, when `extrasSkipped > 0`, a single collapsed `${extrasSkipped} extras
+ * skipped` count row. Verb-agnostic: pass the wet or dry detail array as
+ * `items`.
+ *
+ * @param items - The `<logical>/<dirname>` entries synced this run.
+ * @param extrasSkipped - Count of dirnames the whitelist declined to sync.
+ * @returns An `Extras` `DoctorSection` (possibly empty).
+ */
+export function buildExtrasSection(items: string[], extrasSkipped: number): DoctorSection {
+  const s = section('Extras');
+  for (const entry of items) addItem(s, `${green(okGlyph)} ${entry}`);
+  const skip = collapsedSkipRow(extrasSkipped, 'extras skipped');
+  if (skip !== null) addItem(s, skip);
+  return s;
+}
+
+/**
+ * Collected per-run push state threaded through `cmdPush` so the grouped tree
+ * can be assembled once at the end. `remap`/`extras` carry the detail arrays +
+ * counts; `dryRun` selects the wet (`pushed`) vs would-* (`wouldPush`) arrays.
+ */
+export type PushState = {
+  dryRun: boolean;
+  remap: ReturnType<typeof remapPush>;
+  extras: ReturnType<typeof remapExtrasPush>;
+};
+
+/**
+ * Assemble the Sessions/Extras sections shared by the real and dry-run push
+ * paths, selecting the wet `pushed` detail arrays or the `wouldPush` arrays
+ * under `dryRun`. The Leak scan and Summary sections are appended by the caller
+ * in path-specific order.
+ *
+ * @param st - The collected push state.
+ * @returns The ordered `[Sessions, Extras]` sections (either may be empty).
+ */
+function syncedSections(st: PushState): DoctorSection[] {
+  const sessions = st.dryRun ? st.remap.wouldPush : st.remap.pushed;
+  const extras = st.dryRun ? st.extras.wouldPush : st.extras.pushed;
+  return [
+    buildSessionsSection(sessions, st.remap.unmapped),
+    buildExtrasSection(extras, st.extras.skipped),
+  ];
+}
+
+/**
+ * Build the single-row Summary section from the combined unmapped count
+ * (sessions + extras), the collision count, and the extras-skipped count.
+ * Phrasing is delegated to `summaryRow` so it matches `emitSummary` exactly.
+ *
+ * @param st - The collected push state.
+ * @returns A `Summary` `DoctorSection` holding the one summary row.
+ */
+function summarySection(st: PushState): DoctorSection {
+  const s = section('Summary');
+  const unmapped = st.remap.unmapped + st.extras.unmapped;
+  addItem(s, summaryRow('push', unmapped, st.remap.collisions, st.extras.skipped));
+  return s;
+}
+
+/**
+ * Render the grouped push tree with a Leak scan section (carrying `verdict`'s
+ * row) between Extras and Summary. The caller throws the recovery body as a
+ * `NomadFatal` AFTER this returns (real-push leak) or prints it via `fail`
+ * (dry-run) so the recovery block follows the tree.
+ *
+ * @param st - The collected push state.
+ * @param verdict - The leak verdict for the Leak scan section.
+ */
+export function renderPushTree(st: PushState, verdict: LeakVerdict): void {
+  const leakScan = section('Leak scan');
+  addItem(leakScan, verdict.verdictRow);
+  renderTree([...syncedSections(st), leakScan, summarySection(st)]);
+}
+
+/**
+ * Render the no-Leak-scan push tree: the Sessions/Extras rows (if any) plus the
+ * Summary row. `renderTree` skips empty sections, so an empty push prints only
+ * the Summary. Two callers: the real-push nothing-to-commit early return
+ * (`noMapHint` omitted) and the dry-run no-`path-map.json` case
+ * (`noMapHint: true`), which prepends a `Path map` section carrying a single
+ * `${dim(infoGlyph)} no path-map.json (nothing to preview)` row so a dry-run
+ * user sees WHY no Leak scan section rendered (no map means nothing to stage).
+ *
+ * @param st - The collected push state.
+ * @param opts.noMapHint - When `true`, prepend the no-path-map hint section.
+ * @returns Nothing; renders to stdout.
+ */
+export function renderNoScanTree(st: PushState, opts: { noMapHint?: boolean } = {}): void {
+  const sections: DoctorSection[] = [];
+  if (opts.noMapHint === true) {
+    const pathMap = section('Path map');
+    addItem(pathMap, `${dim(infoGlyph)} no path-map.json (nothing to preview)`);
+    sections.push(pathMap);
+  }
+  renderTree([...sections, ...syncedSections(st), summarySection(st)]);
+}

package/src/commands.push.ts

@@ -1,18 +1,93 @@
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 
-import { HOME, HOST, REPO_HOME } from './config.ts';
+import { HOME, HOST, type PathMap, REPO_HOME } from './config.ts';
 import { enforceAllowList } from './commands.push.allowlist.ts';
+import { type PushState, renderNoScanTree, renderPushTree } from './commands.push.sections.ts';
 import { remapExtrasPush } from './extras-sync.ts';
+import { scanPushVerdict } from './push-leak-verdict.ts';
 import { findGitlinks, probeGitleaks, rebaseBeforePush } from './push-checks.ts';
-import { runGitleaksScan } from './push-gitleaks.ts';
+import { previewPushLeaks } from './push-preview.ts';
 import { remapPush } from './remap.ts';
-import { emitSummary } from './summary.ts';
 import { die, fail, gitOrFatal, gitStatusPorcelainZ, log, NomadFatal } from './utils.ts';
 import { freshBackupTs } from './utils.fs.ts';
 import { readPathMap } from './utils.json.ts';
 import { acquireLock, releaseLock } from './utils.lockfile.ts';
 
+/**
+ * Walk `shared/` for nested `.git` entries copied in from a host's encoded
+ * session dir. A gitlink would otherwise push as a submodule via the
+ * `shared/projects/<logical>/` prefix. Emits a per-hit FATAL line on stderr and
+ * throws a summarizing `NomadFatal` (caught by `cmdPush` so the lock releases).
+ * Runs AFTER `remapPush` so it inspects the post-copy tree.
+ */
+function guardGitlinks(): void {
+  const gitlinks = findGitlinks(join(REPO_HOME, 'shared'));
+  if (gitlinks.length === 0) return;
+  for (const p of gitlinks) {
+    const rel = relative(REPO_HOME, p);
+    fail(`gitlink: ${rel} would push as submodule (run: rm -rf ${rel} or remove the nested repo)`);
+  }
+  const noun = gitlinks.length === 1 ? 'entry' : 'entries';
+  throw new NomadFatal(
+    `gitlink trap: ${gitlinks.length} nested .git ${noun} in shared/; remove before retry`,
+  );
+}
+
+/**
+ * The staged-tree leak gate + commit/push for the REAL push path. Runs
+ * `scanPushVerdict` AFTER `git add -A` (sees what would push) but BEFORE commit
+ * (a detection unwinds cleanly with no commit to revert). On a leak it renders
+ * the tree (with the ✗ Leak scan row + Summary) so the tree precedes the
+ * recovery block, then throws the recovery body as a `NomadFatal` (the catch
+ * prints it and sets a non-zero exit). On a clean scan it commits, pushes, and
+ * renders the tree with the `✓ no leaks` row.
+ *
+ * @param st - The collected push state for the final tree render.
+ */
+function commitAndPush(st: PushState): void {
+  // gitOrFatal uses execFileSync (no shell) so NOMAD_HOST cannot escape quoting.
+  gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
+  const verdict = scanPushVerdict();
+  if (verdict.leak) {
+    renderPushTree(st, verdict);
+    // Every `leak: true` branch of scanPushVerdict sets a non-null recovery
+    // body, so the `?? fallback` is defensively unreachable (excluded from
+    // coverage rather than contorting a test to fake an impossible state).
+    /* c8 ignore next */
+    throw new NomadFatal(verdict.recovery ?? 'gitleaks detected secrets');
+  }
+  gitOrFatal(['commit', '-m', `chore: sync from ${HOST}`], 'git commit', REPO_HOME);
+  gitOrFatal(['push'], 'git push', REPO_HOME);
+  renderPushTree(st, verdict);
+}
+
+/**
+ * Render the dry-run leak-scan tree. With `map === null` (a dry-run with no
+ * `path-map.json`) there is nothing to stage, so it renders the no-scan tree
+ * with the `noMapHint` row and returns. Otherwise it runs `previewPushLeaks`
+ * (which stages its OWN temp
+ * tree from the map, independent of `REPO_HOME` status, and sets
+ * `process.exitCode = 1` on findings), renders the push tree with the verdict
+ * row in the Leak scan section, and prints the recovery body BELOW the tree via
+ * `fail` (stderr) when one is present.
+ *
+ * Extracted from `cmdPush` so the command body and this helper each stay under
+ * the sonarjs cognitive-complexity threshold.
+ *
+ * @param st - The collected push state for the tree render.
+ * @param map - The parsed path-map, or `null` when a dry-run has no map.
+ */
+function runDryRunPreview(st: PushState, map: PathMap | null): void {
+  if (map === null) {
+    renderNoScanTree(st, { noMapHint: true });
+    return;
+  }
+  const verdict = previewPushLeaks(map);
+  renderPushTree(st, verdict);
+  if (verdict.recovery !== null) fail(verdict.recovery);
+}
+
 /**
  * `nomad push` command. Acquires the lock, runs the four pre-push safety
  * checks in the order from CONTEXT.md, stages, and pushes:
@@ -26,20 +101,48 @@ import { acquireLock, releaseLock } from './utils.lockfile.ts';
  *   5. `findGitlinks` walk of `shared/` (refuse to push nested .git entries)
  *   6. allow-list enforcement on the resulting `git status` (runtime
  *      `shared/extras/<logical>/` prefix per declared logical added)
- *   7. `git add -A` -> `runGitleaksScan` on staged tree -> `git commit` -> `git push`
+ *   7. `git add -A` -> `scanPushVerdict` on staged tree -> `git commit` -> `git push`
+ *
+ * Output is a doctor-style grouped tree: a `push on host=...` header, then
+ * `Sessions` / `Extras` / `Leak scan` / `Summary` sections rendered with
+ * `├`/`└` connectors. Pushed sessions and extras list as `✓` rows; the
+ * per-project "not in path-map" skips collapse to one `ℹ︎` count row. The Leak
+ * scan section shows `✓ no leaks` on a clean scan; on a leak it shows a `✗`
+ * one-line verdict row and the full `buildSessionAwareFatal` recovery block
+ * still prints BELOW the rendered tree.
+ *
+ * The WET-path Summary row (including the warn `⚠︎` case) renders to STDOUT as
+ * part of the grouped tree via `renderTree`, not to stderr via `warn` as in the
+ * pre-tree behavior. The dry-run preview likewise renders via `renderTree`
+ * (push has no dry-run `emitSummary` path; `cmdPull`'s dry-run does, see its
+ * JSDoc for the intentional wet-stdout/dry-pull-stderr stream split).
  *
  * The gitleaks scan runs AFTER staging so it sees what would actually be
  * pushed, but BEFORE commit so a detection unwinds cleanly without leaving a
  * commit to amend or revert. Any `NomadFatal` is caught here so `finally`
- * releases the lock.
+ * releases the lock; a real-push leak re-raises the recovery body as a
+ * `NomadFatal` AFTER the tree renders so the recovery block follows the tree.
  *
  * `opts.dryRun` (default `false`): when `true`, the network round-trip
  * (`rebaseBeforePush`) still runs so users see what a real push would see,
- * but `remapPush` runs with `dryRun: true` (no session copies into shared/),
- * and the `git add` / `runGitleaksScan` / `git commit` / `git push` quartet
- * is skipped. The allow-list check still classifies the existing `git
- * status` so a pre-existing violation surfaces before the user thinks
- * everything is fine. Mirrors `cmdPull`'s `dryRun` contract.
+ * and `remapPush` / `remapExtrasPush` run with `dryRun: true` (no copies
+ * into `shared/`). The `git add` / `git commit` / `git push` steps are
+ * skipped. Instead, `previewPushLeaks` runs a READ-ONLY gitleaks leak
+ * preview against a temp copy of the would-be-staged sessions AND extras
+ * (no `REPO_HOME/shared` mutation), returning a structured verdict whose
+ * `verdictRow` lands in the Leak scan section and whose `recovery` (if any)
+ * prints below the tree; `process.exitCode = 1` is set on findings.
+ *
+ * The dry-run preview runs REGARDLESS of `REPO_HOME` `git status`: in dry-run
+ * nothing is copied into `shared/`, so an empty status is the normal case for
+ * the headline target (a clean repo with new mapped sessions). `previewPushLeaks`
+ * stages its own temp tree from the path-map, so the empty-status
+ * `'nothing to commit'` early return is REAL-PUSH-ONLY. A dry-run with NO
+ * path-map renders the no-scan tree and returns without dying (a real push with
+ * a non-empty status and no map still dies on the allow-list check). The
+ * allow-list still classifies a non-empty `git status` (dry or wet) so a
+ * pre-existing violation surfaces; an empty status has nothing to classify.
+ * Mirrors `cmdPull`'s `dryRun` contract.
  */
 export function cmdPush(opts: { dryRun?: boolean } = {}): void {
   const dryRun = opts.dryRun === true;
@@ -47,7 +150,7 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
   const handle = acquireLock('push');
   if (handle === null) process.exit(0);
   try {
-    log(dryRun ? `pushing on host=${HOST} (dry-run)` : `pushing on host=${HOST}`);
+    console.log(dryRun ? `push on host=${HOST} (dry-run)` : `push on host=${HOST}`);
     // Probe at top of flow: fail fast if gitleaks is missing, before any mutation.
     probeGitleaks();
     // Rebase BEFORE any local mutation: surfaces remote conflicts against the
@@ -59,29 +162,14 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     const ts = freshBackupTs(backupBase);
     // remapPush runs BEFORE the empty-status check: it produces the diffs status
     // observes, so swapping the order would short-circuit before anything is staged.
-    const remapResult = remapPush(ts, { dryRun });
+    const remap = remapPush(ts, { dryRun });
     // remapExtrasPush lands between remapPush and findGitlinks so the
     // produced `shared/extras/<logical>/<dirname>/` paths are visible to
     // both the gitlink walk and the downstream allow-list classification.
     // dryRun is forwarded so a preview push reports the same skipped count.
-    const extrasResult = remapExtrasPush(ts, { dryRun });
-    // Gitlink walk of shared/ AFTER remapPush so it inspects the post-copy tree.
-    // A nested .git copied in from a host's encoded session dir would slip past a
-    // pre-remap scan and reach the remote via the shared/projects/<logical>/ prefix.
-    // Per-hit FATAL on stderr plus a summarizing throw, mirroring enforceAllowList.
-    const sharedDir = join(REPO_HOME, 'shared');
-    const gitlinks = findGitlinks(sharedDir);
-    if (gitlinks.length > 0) {
-      for (const p of gitlinks) {
-        const rel = relative(REPO_HOME, p);
-        fail(
-          `gitlink: ${rel} would push as submodule (run: rm -rf ${rel} or remove the nested repo)`,
-        );
-      }
-      throw new NomadFatal(
-        `gitlink trap: ${gitlinks.length} nested .git ${gitlinks.length === 1 ? 'entry' : 'entries'} in shared/; remove before retry`,
-      );
-    }
+    const extras = remapExtrasPush(ts, { dryRun });
+    const st: PushState = { dryRun, remap, extras };
+    guardGitlinks();
     // Routed through the shell-free, untrimmed helper because `sh` would .trim()
     // the leading status-space and shift parsePorcelainZ's offsets.
     // `untrackedAll` (issue #111): the allow-list runs on this snapshot BEFORE
@@ -91,53 +179,30 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     // match, so the first extras push is rejected. Expanding to per-file paths
     // lets the existing allow-list accept them while keeping the gate order.
     const status = gitStatusPorcelainZ(REPO_HOME, { untrackedAll: true });
-    if (!status) {
+    // REAL-PUSH-ONLY early return: a dry-run copies nothing into shared/, so an
+    // empty status is the normal headline case (clean repo, new mapped
+    // sessions) and must still reach the dry-run preview below.
+    if (!dryRun && !status) {
       log('nothing to commit');
-      // Combine session-unmapped and extras-unmapped into one user-visible
-      // count; both mean "couldn't sync this for the host". extras-skipped
-      // (non-whitelisted dirname) stays separate because it signals config
-      // misuse, not a host-config gap.
-      emitSummary(
-        'push',
-        remapResult.unmapped + extrasResult.unmapped,
-        remapResult.collisions,
-        extrasResult.skipped,
-      );
+      renderNoScanTree(st);
       return;
     }
     const mapPath = join(REPO_HOME, 'path-map.json');
-    if (!existsSync(mapPath)) die('path-map.json missing, cannot enforce push allow-list');
+    // A dry-run with no map cannot enforce nor scan: render the no-scan tree and
+    // return without dying. A real push with a non-empty status still dies.
+    if (!existsSync(mapPath)) {
+      if (dryRun) return runDryRunPreview(st, null);
+      die('path-map.json missing, cannot enforce push allow-list');
+    }
     // readPathMap routes parse failures through NomadFatal so finally releases the lock.
     const map = readPathMap(mapPath);
-    enforceAllowList(status, map);
-    if (dryRun) {
-      // Skip the staging quartet so no commit lands and nothing is pushed.
-      // The user has already seen probeGitleaks pass, the rebase result, the
-      // remap preview, the gitlink scan, and the allow-list classification.
-      log('push: dry-run; skipping git add, gitleaks scan, commit, and push');
-      emitSummary(
-        'push',
-        remapResult.unmapped + extrasResult.unmapped,
-        remapResult.collisions,
-        extrasResult.skipped,
-      );
-      return;
-    }
-    // gitOrFatal uses execFileSync (no shell) so NOMAD_HOST cannot escape quoting.
-    gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
-    // Gitleaks scan AFTER staging (sees what would push), BEFORE commit (no cleanup
-    // needed on detection). The empty-status early return above guarantees the
-    // index is non-empty here.
-    runGitleaksScan();
-    gitOrFatal(['commit', '-m', `chore: sync from ${HOST}`], 'git commit', REPO_HOME);
-    gitOrFatal(['push'], 'git push', REPO_HOME);
-    log('push complete');
-    emitSummary(
-      'push',
-      remapResult.unmapped + extrasResult.unmapped,
-      remapResult.collisions,
-      extrasResult.skipped,
-    );
+    // Classify only a non-empty status; an empty status (dry-run on a clean
+    // repo) has nothing to gate.
+    if (status) enforceAllowList(status, map);
+    // dryRun skips git add / commit / push: run the read-only leak preview,
+    // which prints any recovery below the rendered tree.
+    if (dryRun) return runDryRunPreview(st, map);
+    commitAndPush(st);
   } catch (err) {
     if (err instanceof NomadFatal) {
       fail(err.message);

package/src/extras-sync.core.ts

@@ -0,0 +1,96 @@
+import { cpSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { HOST, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { assertSafeLocalRoot, assertSafeLogical } from './extras-sync.guards.ts';
+import { log } from './utils.ts';
+import { readPathMap } from './utils.json.ts';
+
+/** Parsed `path-map.json` plus its validated `extras` block. */
+export type ValidatedExtras = { map: PathMap; extrasMap: Record<string, string[]> };
+
+/** Skip counts: `unmapped` per-project (no host path / `'TBD'`), `skipped` per-dirname (not whitelisted). */
+export 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).
+ */
+export 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 v - validated path-map plus its extras block.
+ * @param counts - mutated in place as targets are skipped or yielded. Skips are
+ *   counted silently (no per-skip log line); the caller's detail arrays and the
+ *   collapsed count row carry that information to the tree renderer.
+ */
+export function* eachExtrasTarget(
+  v: ValidatedExtras,
+  counts: ExtrasCounts,
+): 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++;
+      continue;
+    }
+    for (const dirname of dirnames) {
+      if (!whitelist.includes(dirname)) {
+        counts.skipped++;
+        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 });
+}

package/src/extras-sync.remap.ts

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { REPO_HOME } from './config.ts';
+import {
+  copyExtras,
+  eachExtrasTarget,
+  loadValidatedExtras,
+  type ExtrasCounts,
+  type ValidatedExtras,
+} from './extras-sync.core.ts';
+import { backupExtrasWrite, backupRepoWrite } from './utils.fs.ts';
+
+/** Detail lists returned by an extras op: items copied (wet) and would-copy (dry). */
+type ExtrasDetail = ExtrasCounts & { done: string[]; would: string[] };
+
+/** One yielded extras target: a (logical, host localRoot, dirname) triple. */
+type ExtrasTarget = { logical: string; localRoot: string; dirname: string };
+
+/**
+ * Shared copy loop for `remapExtrasPush` / `remapExtrasPull`. Walks every
+ * surviving extras target (counts mutated via `eachExtrasTarget`; skips are
+ * counted silently, no per-skip log line), resolves src/dst through the
+ * side-specific `paths(...)`, and either records the would-copy item under
+ * `dryRun` or backs up + copies and records the done item. Returns
+ * `{ unmapped, skipped, done, would }`; the public wrappers rename
+ * `done`/`would` to push/pull-specific field names. No per-item log lines: the
+ * detail arrays carry that information to the tree renderer.
+ *
+ * @param v - validated path-map plus its extras block.
+ * @param dryRun - when `true`, collect `would` without mutating.
+ * @param paths - resolves `{ src, dst }` for one target (side-specific).
+ * @param backup - snapshots the dst before clobber (side-specific).
+ * @returns the counts plus the done/would detail lists.
+ */
+function runExtrasOp(
+  v: ValidatedExtras,
+  dryRun: boolean,
+  paths: (t: ExtrasTarget) => { src: string; dst: string },
+  backup: (dst: string, localRoot: string) => void,
+): ExtrasDetail {
+  const counts: ExtrasCounts = { unmapped: 0, skipped: 0 };
+  const done: string[] = [];
+  const would: string[] = [];
+  for (const t of eachExtrasTarget(v, counts)) {
+    const { src, dst } = paths(t);
+    if (!existsSync(src)) continue;
+    const item = `${t.logical}/${t.dirname}`;
+    if (dryRun) {
+      would.push(item);
+      continue;
+    }
+    backup(dst, t.localRoot);
+    copyExtras(src, dst);
+    done.push(item);
+  }
+  return { ...counts, done, would };
+}
+
+/**
+ * Push: copy whitelisted extras directories under each project's localRoot
+ * into the repo at `shared/extras/<logical>/<dirname>/`. Returns
+ * `{ unmapped, skipped, pushed, wouldPush }` with intentionally asymmetric
+ * count granularity (see `eachExtrasTarget`): `unmapped` per-project, `skipped`
+ * per-dirname; both feed the summary row. `pushed` / `wouldPush` hold
+ * `<logical>/<dirname>` strings copied (wet) or that would copy under
+ * `opts.dryRun` so cmdPush can render a grouped tree. Skips are counted
+ * silently and per-item log lines are dropped; counts are unchanged. Legacy
+ * `path-map.json` without an `extras` key returns empty arrays and zero counts
+ * cleanly.
+ *
+ * @param ts - backup timestamp namespace.
+ * @param opts.dryRun - when `true`, collect `wouldPush` without mutating.
+ */
+export function remapExtrasPush(
+  ts: string,
+  opts: { dryRun?: boolean } = {},
+): ExtrasCounts & { pushed: string[]; wouldPush: string[] } {
+  const dryRun = opts.dryRun === true;
+  const v = loadValidatedExtras({ missingMsg: 'no path-map.json; skipping extras push' });
+  if (v === null) return { unmapped: 0, skipped: 0, pushed: [], wouldPush: [] };
+
+  const repoExtras = join(REPO_HOME, 'shared', 'extras');
+  if (!dryRun) mkdirSync(repoExtras, { recursive: true });
+
+  const { unmapped, skipped, done, would } = runExtrasOp(
+    v,
+    dryRun,
+    ({ localRoot, logical, dirname }) => ({
+      src: join(localRoot, dirname),
+      dst: join(repoExtras, logical, dirname),
+    }),
+    (dst) => backupRepoWrite(dst, ts, REPO_HOME),
+  );
+  return { unmapped, skipped, pushed: done, wouldPush: would };
+}
+
+/**
+ * Pull: copy whitelisted extras from `shared/extras/<logical>/<dirname>/`
+ * back into each project's localRoot on this host. Returns
+ * `{ unmapped, skipped, pulled, wouldPull }` with the same asymmetric count
+ * granularity as `remapExtrasPush`; `pulled` / `wouldPull` hold
+ * `<logical>/<dirname>` strings for the grouped tree. Skips are counted
+ * silently and per-item log lines are dropped; counts are unchanged. 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.
+ *
+ * @param ts - backup timestamp namespace.
+ * @param opts.dryRun - when `true`, collect `wouldPull` without mutating.
+ */
+export function remapExtrasPull(
+  ts: string,
+  opts: { dryRun?: boolean } = {},
+): ExtrasCounts & { pulled: string[]; wouldPull: string[] } {
+  const dryRun = opts.dryRun === true;
+  const v = loadValidatedExtras({
+    requireRepoExtras: true,
+    missingMsg: 'no path-map or repo extras dir; skipping extras remap',
+  });
+  if (v === null) return { unmapped: 0, skipped: 0, pulled: [], wouldPull: [] };
+
+  const repoExtras = join(REPO_HOME, 'shared', 'extras');
+  const { unmapped, skipped, done, would } = runExtrasOp(
+    v,
+    dryRun,
+    ({ localRoot, logical, dirname }) => ({
+      src: join(repoExtras, logical, dirname),
+      dst: join(localRoot, dirname),
+    }),
+    // Snapshot the host-side dst BEFORE copyExtras clobbers it. Anchor on
+    // localRoot so the backup tree mirrors the project layout.
+    (dst, localRoot) => backupExtrasWrite(dst, ts, localRoot),
+  );
+  return { unmapped, skipped, pulled: done, wouldPull: would };
+}