claude-nomad 0.25.0 → 0.25.2

package/src/commands.drop-session.ts

@@ -3,23 +3,17 @@ import { existsSync, readdirSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 
 import { REPO_HOME } from './config.ts';
-import { acquireLock, die, fail, log, NomadFatal, releaseLock } from './utils.ts';
+import { expandStagedDir, isInIndex, isTrackedInHead } from './commands.drop-session.git.ts';
+import { die, fail, log, NomadFatal } from './utils.ts';
+import { acquireLock, releaseLock } from './utils.lockfile.ts';
 
 /**
  * Surgical removal of a contaminated session from the staged tree of
- * `~/claude-nomad/`. For each `shared/projects/<logical>/` child this
- * matches both the flat `<id>.jsonl` AND the sibling subagent directory
- * `<id>/` (whose nested transcripts are keyed by the same session id),
- * classifies each staged entry via `git ls-files --error-unmatch`, and
- * unstages with the appropriate primitive:
- *
- *   - tracked-in-HEAD  -> `git restore --staged --worktree -- <rel>`
- *   - newly-staged     -> `git rm --cached -f -- <rel>`
- *
- * The directory tree is expanded into its staged entries via
- * `git ls-files -z -- <dir-rel>` so every nested file flows through the
- * same per-entry classification loop as the flat jsonl; this closes the
- * leak where a "dropped" session still shipped its subagent transcripts.
+ * `~/claude-nomad/`. Thin orchestrator: validates the id, acquires the
+ * lock, collects every staged path matching the flat `<id>.jsonl` and the
+ * sibling subagent directory `<id>/` (via `collectMatches`), then unstages
+ * each (via `unstageOne`). This closes the leak where a "dropped" session
+ * still shipped its subagent transcripts.
  *
  * Idempotent: entries not in the index are skipped silently. Exits 0 on
  * any drop (including an idempotent re-run); exits 1 with `✗ no staged
@@ -27,8 +21,8 @@ import { acquireLock, die, fail, log, NomadFatal, releaseLock } from './utils.ts
  * `<id>/` directory with staged entries exists anywhere in the tree.
  *
  * Defense-in-depth: the id is validated against the same allowlist regex
- * used in `src/resume.ts` before any path composition. argv-array form
- * for every git invocation.
+ * used in `src/resume.ts` before any path composition or lock acquisition.
+ * argv-array form for every git invocation.
  *
  * NEVER touches `~/.claude/projects/<encoded>/<id>.jsonl` or the local
  * `<id>/` tree; the local copies are preserved so they race-safely
@@ -54,68 +48,11 @@ export function cmdDropSession(id: string): void {
     if (!existsSync(repoProjects)) {
       throw new NomadFatal(`no staged session matches ${id}`);
     }
-    // For each `shared/projects/<logical>/` child, match the flat
-    // `<id>.jsonl` plus the sibling subagent directory `<id>/`. The
-    // directory is expanded into its staged entries so every nested file
-    // flows through the same per-entry unstage loop as the flat jsonl.
-    const matches: string[] = [];
-    for (const logical of readdirSync(repoProjects)) {
-      const candidate = join(repoProjects, logical, `${id}.jsonl`);
-      if (existsSync(candidate)) {
-        matches.push(relative(REPO_HOME, candidate));
-      }
-      const dir = join(repoProjects, logical, id);
-      if (existsSync(dir) && statSync(dir).isDirectory()) {
-        const dirRel = relative(REPO_HOME, dir);
-        const staged = expandStagedDir(dirRel);
-        // A dir present on disk but absent from the index is an already-dropped
-        // rerun: push the dir path itself so the per-entry isInIndex() guard
-        // logs it as "already absent" rather than letting an empty match set
-        // escalate to the no-match fatal (idempotency for dir-only sessions).
-        if (staged.length > 0) matches.push(...staged);
-        else matches.push(dirRel);
-      }
-    }
+    const matches = collectMatches(repoProjects, id);
     if (matches.length === 0) {
       throw new NomadFatal(`no staged session matches ${id}`);
     }
-    for (const rel of matches) {
-      // Pitfall 7: skip files that are not in the index at all (the
-      // load-bearing guard for the idempotent second-run case, where the
-      // first drop already removed the entry from the index but left the
-      // working tree file in place).
-      if (!isInIndex(rel)) {
-        log(`dropped ${rel} (already absent from index)`);
-        continue;
-      }
-      try {
-        if (isTrackedInHead(rel)) {
-          execFileSync('git', ['restore', '--staged', '--worktree', '--', rel], {
-            cwd: REPO_HOME,
-            stdio: ['ignore', 'pipe', 'pipe'],
-          });
-        } else {
-          execFileSync('git', ['rm', '--cached', '-f', '--', rel], {
-            cwd: REPO_HOME,
-            stdio: ['ignore', 'pipe', 'pipe'],
-          });
-        }
-      } catch (err) {
-        // Convert raw execFileSync failures (non-zero git exit, EACCES on
-        // .git/index, EPERM, etc.) into NomadFatal so the outer catch can
-        // emit a clean `✗ ...` line instead of letting the ExecException
-        // bubble past nomad.ts's NomadFatal-only dispatcher.
-        // The `?? err.message` fallback only fires when git fails without
-        // producing stderr (spawn-level error before the process emits
-        // anything), which `cmdPush`'s gitleaks probe already rules out
-        // for the typical install path. Excluded from coverage.
-        const e = err as NodeJS.ErrnoException & { stderr?: Buffer };
-        /* c8 ignore next */
-        const detail = e.stderr?.toString().trim() ?? e.message;
-        throw new NomadFatal(`git failed to unstage ${rel}: ${detail}`);
-      }
-      log(`dropped ${rel}`);
-    }
+    for (const rel of matches) unstageOne(rel);
   } catch (err) {
     // Defensive escape hatch: only fires if a non-NomadFatal error escapes
     // the try block. All execFileSync mutation failures are wrapped in
@@ -137,78 +74,82 @@ export function cmdDropSession(id: string): void {
 }
 
 /**
- * Expand a repo-relative directory into its staged entries via
- * `git ls-files -z -- <dirRel>` (argv-array form, NUL-split for path
- * safety). Returns repo-relative POSIX paths for every staged file under
- * the directory, or an empty array when none are staged or `git` fails
- * (missing/corrupt index); the caller then falls through to the existing
- * per-entry idempotency guard rather than escalating to a FATAL.
+ * Collect repo-relative staged paths matching the session `id`. For each
+ * `shared/projects/<logical>/` child, match the flat `<id>.jsonl` plus the
+ * sibling subagent directory `<id>/`. The directory is expanded into its
+ * staged entries via `expandStagedDir` so every nested file flows through
+ * the same per-entry unstage loop as the flat jsonl.
  *
- * @param dirRel Repo-relative directory path (`shared/projects/<logical>/<id>`).
+ * @param repoProjects Absolute path to `<REPO_HOME>/shared/projects`.
+ * @param id Already-validated session id (see `cmdDropSession`'s entry guard).
+ * @returns Repo-relative paths to unstage (possibly empty).
  */
-function expandStagedDir(dirRel: string): string[] {
-  try {
-    const out = execFileSync('git', ['ls-files', '-z', '--', dirRel], {
-      cwd: REPO_HOME,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    return out
-      .toString()
-      .split('\0')
-      .filter((p) => p !== '');
-  } catch {
-    return [];
+function collectMatches(repoProjects: string, id: string): string[] {
+  const matches: string[] = [];
+  for (const logical of readdirSync(repoProjects)) {
+    const candidate = join(repoProjects, logical, `${id}.jsonl`);
+    if (existsSync(candidate)) {
+      matches.push(relative(REPO_HOME, candidate));
+    }
+    const dir = join(repoProjects, logical, id);
+    if (existsSync(dir) && statSync(dir).isDirectory()) {
+      const dirRel = relative(REPO_HOME, dir);
+      const staged = expandStagedDir(dirRel);
+      // A dir present on disk but absent from the index is an already-dropped
+      // rerun: push the dir path itself so the per-entry isInIndex() guard
+      // logs it as "already absent" rather than letting an empty match set
+      // escalate to the no-match fatal (idempotency for dir-only sessions).
+      if (staged.length > 0) matches.push(...staged);
+      else matches.push(dirRel);
+    }
   }
+  return matches;
 }
 
 /**
- * Is `rel` (repo-relative path) present in the HEAD tree? Wraps
- * `git cat-file -e HEAD:<rel>`: exit 0 means tracked in HEAD,
- * non-zero means either no HEAD exists yet (empty repo) or the path is
- * only in the index (newly-staged-not-in-HEAD). `git ls-files
- * --error-unmatch` is NOT a HEAD-presence check; it matches anything in
- * the index too, which would misclassify newly-staged paths.
+ * Unstage one repo-relative path via the tracked-vs-newly-staged primitive.
+ * Skips paths absent from the index (Pitfall 7 idempotency guard), then
+ * classifies via `isTrackedInHead` and unstages with `git restore
+ * --staged --worktree` (tracked-in-HEAD) or `git rm --cached -f`
+ * (newly-staged). Git calls keep `execFileSync` argv-array form (PUSH-04).
  *
- * The catch deliberately collapses three cases to `false`: (a) HEAD has
- * no commit yet (fresh `git init`), (b) HEAD is unresolvable / corrupt
- * (e.g., `.git/refs/heads/main` was deleted manually), and (c) the
- * specific path simply does not exist in a valid HEAD. Git produces the
- * same exit 128 and the same stderr (`fatal: invalid object name 'HEAD'`)
- * for (a) and (b), so a probe-based distinction would require additional
- * git-plumbing reads (`rev-parse --verify HEAD`, `.git/refs/heads/`
- * inspection) that are brittle and break the empty-repo path every
- * existing test runs through. The downstream `git rm --cached -f` is
- * idempotent and produces the user-intended unstage outcome regardless
- * of which case fired, so the collapsed return is intentional. Repo
- * health belongs to `nomad doctor`, not drop-session.
+ * @param rel Repo-relative path to unstage.
+ * @throws NomadFatal when the underlying git invocation fails.
  */
-function isTrackedInHead(rel: string): boolean {
-  try {
-    execFileSync('git', ['cat-file', '-e', `HEAD:${rel}`], {
-      cwd: REPO_HOME,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    return true;
-  } catch {
-    return false;
+function unstageOne(rel: string): void {
+  // Pitfall 7: skip files that are not in the index at all (the
+  // load-bearing guard for the idempotent second-run case, where the
+  // first drop already removed the entry from the index but left the
+  // working tree file in place).
+  if (!isInIndex(rel)) {
+    log(`dropped ${rel} (already absent from index)`);
+    return;
   }
-}
-
-/**
- * Is `rel` present in the index at all? Wraps `git ls-files -- <rel>` and
- * checks for non-empty stdout. Required for the Pitfall 7 idempotency
- * guard: a second invocation on the same id finds the file on disk (per
- * `existsSync`) but absent from the index, and must NOT call `git rm
- * --cached` on it (which would fail with exit 128).
- */
-function isInIndex(rel: string): boolean {
   try {
-    const out = execFileSync('git', ['ls-files', '--', rel], {
-      cwd: REPO_HOME,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    return out.toString().trim() !== '';
-  } catch {
-    return false;
+    if (isTrackedInHead(rel)) {
+      execFileSync('git', ['restore', '--staged', '--worktree', '--', rel], {
+        cwd: REPO_HOME,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } else {
+      execFileSync('git', ['rm', '--cached', '-f', '--', rel], {
+        cwd: REPO_HOME,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    }
+  } catch (err) {
+    // Convert raw execFileSync failures (non-zero git exit, EACCES on
+    // .git/index, EPERM, etc.) into NomadFatal so the outer catch can
+    // emit a clean `✗ ...` line instead of letting the ExecException
+    // bubble past nomad.ts's NomadFatal-only dispatcher.
+    // The `?? err.message` fallback only fires when git fails without
+    // producing stderr (spawn-level error before the process emits
+    // anything), which `cmdPush`'s gitleaks probe already rules out
+    // for the typical install path. Excluded from coverage.
+    const e = err as NodeJS.ErrnoException & { stderr?: Buffer };
+    /* c8 ignore next */
+    const detail = e.stderr?.toString().trim() ?? e.message;
+    throw new NomadFatal(`git failed to unstage ${rel}: ${detail}`);
   }
+  log(`dropped ${rel}`);
 }

package/src/commands.pull.ts

@@ -7,8 +7,9 @@ import { applySharedLinks, regenerateSettings } from './links.ts';
 import { computePreview } from './preview.ts';
 import { remapPull } from './remap.ts';
 import { emitSummary } from './summary.ts';
-// prettier-ignore
-import { acquireLock, die, fail, freshBackupTs, gitOrFatal, log, NomadFatal, releaseLock } from './utils.ts';
+import { die, fail, gitOrFatal, log, NomadFatal } from './utils.ts';
+import { freshBackupTs } from './utils.fs.ts';
+import { acquireLock, releaseLock } from './utils.lockfile.ts';
 
 /**
  * `nomad pull` command. Acquires the push/pull lock, takes a backup

package/src/commands.push.allowlist.ts

@@ -0,0 +1,119 @@
+import { NEVER_SYNC, PUSH_ALLOWED_STATIC, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { fail, NomadFatal } from './utils.ts';
+
+/**
+ * Match `path` against an entry in the push allow-list. Exact match for
+ * non-`/`-terminated entries; prefix match for `/`-terminated entries; and
+ * a special case for `hosts/`: only `hosts/<name>.json` (single-level,
+ * `.json` extension) is allowed, so arbitrary credentials like
+ * `hosts/dell-wsl.key` are rejected even though they share the prefix.
+ */
+function isAllowed(path: string, allowed: readonly string[]): boolean {
+  for (const entry of allowed) {
+    if (path === entry) return true;
+    if (entry === 'hosts/') {
+      if (/^hosts\/[^/]+\.json$/.test(path)) return true;
+      continue;
+    }
+    if (entry.endsWith('/') && path.startsWith(entry)) return true;
+  }
+  return false;
+}
+
+/**
+ * True when any path segment matches a `NEVER_SYNC` entry (hard-block list).
+ * Scope exception (Pitfall 6): paths beginning with `shared/extras/` are
+ * exempt. The segment list was authored against `~/.claude/` semantics for
+ * ephemeral Claude Code state (`todos/`, `shell-snapshots/`, etc.); inside
+ * the extras tree, `.planning/todos/` is a meaningful GSD-managed path. The
+ * narrowed scope preserves the original hard-block for all other surface.
+ */
+function isNeverSync(path: string): boolean {
+  if (path.startsWith('shared/extras/')) return false;
+  for (const segment of path.split('/')) {
+    if (NEVER_SYNC.has(segment)) return true;
+  }
+  return false;
+}
+
+/**
+ * Parse `git status --porcelain=v1 -z` (NUL-delimited) output into a flat
+ * list of paths. Handles rename (`R`) and copy (`C`) records, which span
+ * two NUL fields (`XY new\0old\0`): both halves are returned so the
+ * allow-list can reject either side. `-z` avoids the quoting that LF
+ * porcelain applies to paths containing spaces or specials, which would
+ * otherwise cause parser misclassification.
+ */
+export function parsePorcelainZ(statusPorcelain: string): string[] {
+  const records = statusPorcelain.split('\0');
+  const paths: string[] = [];
+  for (let i = 0; i < records.length; i++) {
+    const rec = records[i];
+    if (rec === undefined || rec === '') continue;
+    // Each record starts with "XY " (2 status chars + 1 space). The path is
+    // everything after byte 3. For R/C the NEXT record holds the old path.
+    if (rec.length < 4) continue;
+    const xy = rec.slice(0, 2);
+    const newPath = rec.slice(3);
+    paths.push(newPath);
+    // Check BOTH XY positions: X is the index status, Y is the working-tree
+    // status. Either can carry R (rename) or C (copy), and the old-path record
+    // follows the new-path record in -z porcelain regardless of which column
+    // detected the rename. Missing the Y-column case (e.g. ` R`) would skip
+    // the consume and let the next iteration misread the old path as a new
+    // record, smuggling unallowed sources past the allow-list.
+    if (/[RC]/.test(xy)) {
+      const oldPath = records[i + 1];
+      if (oldPath !== undefined && oldPath !== '') paths.push(oldPath);
+      i++; // consume the paired old-path record
+    }
+  }
+  return paths;
+}
+
+/**
+ * Reject any staged path that is not on the push allow-list or that matches a
+ * `NEVER_SYNC` entry. Builds the runtime allow-list by combining
+ * `PUSH_ALLOWED_STATIC` with one `shared/projects/<logical>/` prefix per entry
+ * in `path-map.json` AND, per (logical, whitelisted name) pair in
+ * `map.extras ?? {}`, an exact `shared/extras/<logical>/<name>` entry plus a
+ * `shared/extras/<logical>/<name>/` prefix entry (Pitfall 4 closed:
+ * data-driven, no hand-rolled bypass). The exact entry permits the declared
+ * name when it is a single root file (e.g. `CLAUDE.md`); the prefix entry
+ * permits the declared name's subtree when it is a directory. Neither widens
+ * to a logical-only prefix, so an arbitrary sibling file under the same
+ * logical stays rejected. The name filter (`SUPPORTED_EXTRAS`) is the same one
+ * `remapExtrasPush` honors, so manually staged content under a non-whitelisted
+ * name surfaces as a FATAL instead of riding through. Logs every violation as
+ * a FATAL line so the user sees the full set (not just the first), then throws
+ * `NomadFatal` to unwind the caller's try/finally and release the push lock.
+ */
+export function enforceAllowList(statusPorcelain: string, map: PathMap): void {
+  const extrasWhitelist: readonly string[] = SUPPORTED_EXTRAS;
+  const allowed = [
+    ...PUSH_ALLOWED_STATIC,
+    ...Object.keys(map.projects).map((l) => `shared/projects/${l}/`),
+    ...Object.entries(map.extras ?? {}).flatMap(([l, names]) =>
+      names
+        .filter((n) => extrasWhitelist.includes(n))
+        .flatMap((n) => [`shared/extras/${l}/${n}`, `shared/extras/${l}/${n}/`]),
+    ),
+  ];
+  const neverSyncHits: string[] = [];
+  const violations: string[] = [];
+  for (const path of parsePorcelainZ(statusPorcelain)) {
+    if (isNeverSync(path)) {
+      neverSyncHits.push(path);
+    } else if (!isAllowed(path, allowed)) {
+      violations.push(path);
+    }
+  }
+  if (neverSyncHits.length === 0 && violations.length === 0) return;
+  for (const p of neverSyncHits) {
+    fail(`${p} is in NEVER_SYNC and must never be pushed`);
+  }
+  for (const p of violations) {
+    fail(`to sync ${p}, add to PUSH_ALLOWED in src/config.ts`);
+  }
+  throw new NomadFatal('push allow-list violations');
+}

package/src/commands.push.ts

@@ -1,132 +1,17 @@
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 
-// prettier-ignore
-import { HOME, HOST, NEVER_SYNC, PUSH_ALLOWED_STATIC, REPO_HOME, SUPPORTED_EXTRAS, type PathMap } from './config.ts';
+import { HOME, HOST, REPO_HOME } from './config.ts';
+import { enforceAllowList } from './commands.push.allowlist.ts';
 import { remapExtrasPush } from './extras-sync.ts';
 import { findGitlinks, probeGitleaks, rebaseBeforePush } from './push-checks.ts';
 import { runGitleaksScan } from './push-gitleaks.ts';
 import { remapPush } from './remap.ts';
 import { emitSummary } from './summary.ts';
-// prettier-ignore
-import { acquireLock, die, fail, freshBackupTs, gitOrFatal, gitStatusPorcelainZ, log, NomadFatal, readPathMap, releaseLock } from './utils.ts';
-
-/**
- * Match `path` against an entry in the push allow-list. Exact match for
- * non-`/`-terminated entries; prefix match for `/`-terminated entries; and
- * a special case for `hosts/`: only `hosts/<name>.json` (single-level,
- * `.json` extension) is allowed, so arbitrary credentials like
- * `hosts/dell-wsl.key` are rejected even though they share the prefix.
- */
-function isAllowed(path: string, allowed: readonly string[]): boolean {
-  for (const entry of allowed) {
-    if (path === entry) return true;
-    if (entry === 'hosts/') {
-      if (/^hosts\/[^/]+\.json$/.test(path)) return true;
-      continue;
-    }
-    if (entry.endsWith('/') && path.startsWith(entry)) return true;
-  }
-  return false;
-}
-
-/**
- * True when any path segment matches a `NEVER_SYNC` entry (hard-block list).
- * Scope exception (Pitfall 6): paths beginning with `shared/extras/` are
- * exempt. The segment list was authored against `~/.claude/` semantics for
- * ephemeral Claude Code state (`todos/`, `shell-snapshots/`, etc.); inside
- * the extras tree, `.planning/todos/` is a meaningful GSD-managed path. The
- * narrowed scope preserves the original hard-block for all other surface.
- */
-function isNeverSync(path: string): boolean {
-  if (path.startsWith('shared/extras/')) return false;
-  for (const segment of path.split('/')) {
-    if (NEVER_SYNC.has(segment)) return true;
-  }
-  return false;
-}
-
-/**
- * Parse `git status --porcelain=v1 -z` (NUL-delimited) output into a flat
- * list of paths. Handles rename (`R`) and copy (`C`) records, which span
- * two NUL fields (`XY new\0old\0`): both halves are returned so the
- * allow-list can reject either side. `-z` avoids the quoting that LF
- * porcelain applies to paths containing spaces or specials, which would
- * otherwise cause parser misclassification.
- */
-export function parsePorcelainZ(statusPorcelain: string): string[] {
-  const records = statusPorcelain.split('\0');
-  const paths: string[] = [];
-  for (let i = 0; i < records.length; i++) {
-    const rec = records[i];
-    if (rec === undefined || rec === '') continue;
-    // Each record starts with "XY " (2 status chars + 1 space). The path is
-    // everything after byte 3. For R/C the NEXT record holds the old path.
-    if (rec.length < 4) continue;
-    const xy = rec.slice(0, 2);
-    const newPath = rec.slice(3);
-    paths.push(newPath);
-    // Check BOTH XY positions: X is the index status, Y is the working-tree
-    // status. Either can carry R (rename) or C (copy), and the old-path record
-    // follows the new-path record in -z porcelain regardless of which column
-    // detected the rename. Missing the Y-column case (e.g. ` R`) would skip
-    // the consume and let the next iteration misread the old path as a new
-    // record, smuggling unallowed sources past the allow-list.
-    if (/[RC]/.test(xy)) {
-      const oldPath = records[i + 1];
-      if (oldPath !== undefined && oldPath !== '') paths.push(oldPath);
-      i++; // consume the paired old-path record
-    }
-  }
-  return paths;
-}
-
-/**
- * Reject any staged path that is not on the push allow-list or that matches a
- * `NEVER_SYNC` entry. Builds the runtime allow-list by combining
- * `PUSH_ALLOWED_STATIC` with one `shared/projects/<logical>/` prefix per entry
- * in `path-map.json` AND, per (logical, whitelisted name) pair in
- * `map.extras ?? {}`, an exact `shared/extras/<logical>/<name>` entry plus a
- * `shared/extras/<logical>/<name>/` prefix entry (Pitfall 4 closed:
- * data-driven, no hand-rolled bypass). The exact entry permits the declared
- * name when it is a single root file (e.g. `CLAUDE.md`); the prefix entry
- * permits the declared name's subtree when it is a directory. Neither widens
- * to a logical-only prefix, so an arbitrary sibling file under the same
- * logical stays rejected. The name filter (`SUPPORTED_EXTRAS`) is the same one
- * `remapExtrasPush` honors, so manually staged content under a non-whitelisted
- * name surfaces as a FATAL instead of riding through. Logs every violation as
- * a FATAL line so the user sees the full set (not just the first), then throws
- * `NomadFatal` to unwind the caller's try/finally and release the push lock.
- */
-export function enforceAllowList(statusPorcelain: string, map: PathMap): void {
-  const extrasWhitelist: readonly string[] = SUPPORTED_EXTRAS;
-  const allowed = [
-    ...PUSH_ALLOWED_STATIC,
-    ...Object.keys(map.projects).map((l) => `shared/projects/${l}/`),
-    ...Object.entries(map.extras ?? {}).flatMap(([l, names]) =>
-      names
-        .filter((n) => extrasWhitelist.includes(n))
-        .flatMap((n) => [`shared/extras/${l}/${n}`, `shared/extras/${l}/${n}/`]),
-    ),
-  ];
-  const neverSyncHits: string[] = [];
-  const violations: string[] = [];
-  for (const path of parsePorcelainZ(statusPorcelain)) {
-    if (isNeverSync(path)) {
-      neverSyncHits.push(path);
-    } else if (!isAllowed(path, allowed)) {
-      violations.push(path);
-    }
-  }
-  if (neverSyncHits.length === 0 && violations.length === 0) return;
-  for (const p of neverSyncHits) {
-    fail(`${p} is in NEVER_SYNC and must never be pushed`);
-  }
-  for (const p of violations) {
-    fail(`to sync ${p}, add to PUSH_ALLOWED in src/config.ts`);
-  }
-  throw new NomadFatal('push allow-list violations');
-}
+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';
 
 /**
  * `nomad push` command. Acquires the lock, runs the four pre-push safety

package/src/commands.update.git.ts

@@ -0,0 +1,90 @@
+import { execFileSync } from 'node:child_process';
+
+import { REPO_HOME } from './config.ts';
+import { log, NomadFatal } from './utils.ts';
+
+/**
+ * Get the current Git branch name for the repository at REPO_HOME.
+ *
+ * Wraps the failure path so a corrupt or missing `.git` directory surfaces as
+ * ``✗ ...`` via the top-level dispatcher's `NomadFatal` catch
+ * rather than a raw `ExecException` stack trace.
+ *
+ * @returns The current branch name (trimmed).
+ * @throws NomadFatal when the git command fails; if the command produced stderr, that stderr is written to process.stderr before the exception is thrown.
+ */
+export function currentBranch(): string {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+      .toString()
+      .trim();
+  } catch (err) {
+    const e = err as Error & { stderr?: Buffer };
+    if (e.stderr) process.stderr.write(e.stderr);
+    throw new NomadFatal('git rev-parse --abbrev-ref HEAD failed');
+  }
+}
+
+/**
+ * Read and return the current `HEAD` commit SHA from the repository.
+ *
+ * Used to pin the pre-update commit so the post-update lockfile diff is
+ * exact regardless of whether the pull was a fast-forward, a no-op, or a
+ * merge. `HEAD@{1}` is unreliable here: a no-op `git pull --ff-only` does
+ * not always write a reflog entry, and a freshly cloned repo has no
+ * `HEAD@{1}` at all.
+ *
+ * @returns The `HEAD` commit SHA as a trimmed string.
+ * @throws NomadFatal if `git rev-parse HEAD` fails (stderr is written to stderr when present).
+ */
+export function headSha(): string {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+      .toString()
+      .trim();
+  } catch (err) {
+    const e = err as Error & { stderr?: Buffer };
+    if (e.stderr) process.stderr.write(e.stderr);
+    throw new NomadFatal('git rev-parse HEAD failed');
+  }
+}
+
+/**
+ * List files changed between the given commit and the current HEAD.
+ *
+ * @param beforeSha - Commit SHA to compare against HEAD
+ * @returns An array of file paths changed between `beforeSha` and `HEAD`; an empty array if there are no changes
+ */
+export function changedFilesSince(beforeSha: string): string[] {
+  const out = execFileSync('git', ['diff', '--name-only', `${beforeSha}..HEAD`], {
+    cwd: REPO_HOME,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).toString();
+  return out.split('\n').filter((line) => line !== '');
+}
+
+/**
+ * Run `npm install` in the repository only if `package-lock.json` changed since a given commit.
+ *
+ * If `package-lock.json` did not change between `beforeSha` and `HEAD`, logs
+ * a skip message; otherwise runs `npm install` with working directory set to
+ * `REPO_HOME`. Routing through `execFileSync` (no shell) keeps the call
+ * mockable in tests and prevents any chance of argv injection.
+ *
+ * @param beforeSha - Commit SHA to compare against `HEAD` when determining whether the lockfile changed
+ */
+export function reinstallIfNeeded(beforeSha: string): void {
+  const changed = changedFilesSince(beforeSha);
+  if (!changed.includes('package-lock.json')) {
+    log('skipping npm install (lockfile unchanged)');
+    return;
+  }
+  log('package-lock.json changed, running npm install');
+  execFileSync('npm', ['install'], { cwd: REPO_HOME, stdio: 'inherit' });
+}