claude-nomad 0.25.0 → 0.25.2

package/src/commands.update.resolve.ts

@@ -0,0 +1,138 @@
+import { execFileSync } from 'node:child_process';
+import { closeSync, openSync, readSync } from 'node:fs';
+
+import type { CmdUpdateOpts } from './commands.update.ts';
+import { REPO_HOME } from './config.ts';
+import { gitOrFatal, log } from './utils.ts';
+
+/**
+ * Default y/N prompt used when `opts.prompt` is not injected.
+ *
+ * Reads from `/dev/tty` byte-by-byte until newline so the call returns after
+ * the user presses Enter (cooked-mode TTY line buffering). The naive
+ * `readFileSync(0)` approach reads until EOF, which hangs interactive use
+ * until Ctrl-D. Opening `/dev/tty` directly also means the prompt still
+ * works when stdin is piped or redirected.
+ *
+ * @param question - Prompt text written to stdout before reading input.
+ * @returns The user's trimmed answer; `''` on any failure (no controlling TTY, read error), which `runFork` treats as "no" and skips the push.
+ */
+export function defaultPrompt(question: string): string {
+  process.stdout.write(question);
+  let fd: number;
+  try {
+    fd = openSync('/dev/tty', 'r');
+  } catch {
+    return '';
+  }
+  try {
+    const buf = Buffer.alloc(1);
+    let answer = '';
+    while (true) {
+      const n = readSync(fd, buf, 0, 1, null);
+      if (n === 0) break;
+      const ch = buf.toString('utf8', 0, 1);
+      if (ch === '\n' || ch === '\r') break;
+      answer += ch;
+    }
+    return answer.trim();
+  } catch {
+    return '';
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Files release-please touches as a set on every release commit. Multi-file
+ * merge conflicts in `nomad update` that consist entirely of paths from this
+ * set are diagnostic for a release landing upstream while the mirror has its
+ * own local commits on these artifacts. Taking upstream is the canonical
+ * resolution (these are all generated artifacts the user has no business
+ * editing on a mirror), but multi-file is more aggressive than the lone
+ * lockfile case so we prompt before mutating.
+ */
+const RELEASE_PLEASE_ARTIFACTS: ReadonlySet<string> = new Set([
+  'package.json',
+  'package-lock.json',
+  'CHANGELOG.md',
+  '.release-please-manifest.json',
+]);
+
+/**
+ * Resolve a merge conflict by taking upstream's version of every listed path,
+ * regenerating the lockfile via `npm install`, and committing the merge.
+ * Shared body for the lone-lockfile auto-resolve and the release-please
+ * multi-file prompted auto-resolve.
+ *
+ * @param paths - Unmerged paths to resolve via `git checkout --theirs`.
+ */
+export function resolveByTakingTheirs(paths: readonly string[]): void {
+  for (const p of paths) {
+    gitOrFatal(['checkout', '--theirs', '--', p], `git checkout --theirs ${p}`, REPO_HOME);
+  }
+  gitOrFatal(['add', ...paths], `git add ${paths.join(' ')}`, REPO_HOME);
+  execFileSync('npm', ['install'], { cwd: REPO_HOME, stdio: 'inherit' });
+  gitOrFatal(['add', 'package-lock.json'], 'git add package-lock.json', REPO_HOME);
+  gitOrFatal(['commit', '--no-edit'], 'git commit --no-edit', REPO_HOME);
+  log(`auto-resolved merge conflict (took upstream for ${paths.join(', ')}, reinstalled)`);
+}
+
+/**
+ * Auto-resolve a merge conflict in the two scenarios both caused by
+ * release-please landing upstream while the mirror has local commits:
+ *
+ * 1. **Sole `package-lock.json`** (silent): the lone-lockfile case from PR
+ *    #96. Any host that has run `npm install` against the mirror will hit
+ *    this on the next `nomad update`; take upstream + reinstall is the
+ *    semantically-correct fix and surprise-free for a generated artifact.
+ *
+ * 2. **All paths in `RELEASE_PLEASE_ARTIFACTS` and more than one path**
+ *    (prompted): a release commit conflicting on `package.json`,
+ *    `CHANGELOG.md`, `.release-please-manifest.json` together with the
+ *    lockfile. Same semantic resolution, but more files are touched so we
+ *    require explicit y/N consent before mutating.
+ *
+ * Returns `false` for any other conflict shape (including probe failure);
+ * the caller re-throws the original merge `NomadFatal` unchanged.
+ *
+ * @param opts - Update options; only `prompt` is consulted (used for the multi-file release-please consent prompt).
+ * @returns `true` when the conflict was auto-resolved and the merge committed; `false` when the conflict shape does not match either auto-resolve case (caller should re-throw the original failure).
+ */
+export function tryAutoResolveMergeConflict(opts: CmdUpdateOpts): boolean {
+  let unmerged: string[];
+  try {
+    unmerged = execFileSync('git', ['diff', '--name-only', '--diff-filter=U'], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+      .toString()
+      .split('\n')
+      .filter((line) => line !== '');
+  } catch {
+    // Probe failure must not mask the original merge NomadFatal. Returning
+    // false lets the caller re-throw the merge error unchanged.
+    return false;
+  }
+
+  if (unmerged.length === 1 && unmerged[0] === 'package-lock.json') {
+    resolveByTakingTheirs(['package-lock.json']);
+    return true;
+  }
+
+  if (unmerged.length > 1 && unmerged.every((p) => RELEASE_PLEASE_ARTIFACTS.has(p))) {
+    const promptFn = opts.prompt ?? defaultPrompt;
+    log(`merge conflict in release-please artifacts: ${unmerged.join(', ')}`);
+    const answer = promptFn(
+      'Auto-resolve by taking upstream + `npm install` + commit? [y/N] ',
+    ).toLowerCase();
+    if (answer !== 'y' && answer !== 'yes') {
+      log('skipping auto-resolve (resolve manually then re-run `nomad update`)');
+      return false;
+    }
+    resolveByTakingTheirs(unmerged);
+    return true;
+  }
+
+  return false;
+}

package/src/commands.update.test-helpers.git.ts

@@ -0,0 +1,107 @@
+/**
+ * Produce git `remote -v` formatted output from a map of remote names to URLs.
+ *
+ * Each entry produces two lines: one with `(fetch)` and one with `(push)`.
+ * `parseRemotes` only consumes `(fetch)`, but emitting production-shaped
+ * output keeps the test honest against the real git CLI format.
+ *
+ * @param remotes - Mapping of remote name to its URL
+ * @returns A `git remote -v`-style string where each remote has `(fetch)` and `(push)` lines; includes a trailing newline when there is at least one line
+ */
+export function formatRemoteV(remotes: Record<string, string>): string {
+  const lines: string[] = [];
+  for (const [name, url] of Object.entries(remotes)) {
+    lines.push(`${name}\t${url} (fetch)`, `${name}\t${url} (push)`);
+  }
+  return lines.join('\n') + (lines.length > 0 ? '\n' : '');
+}
+
+/** Shape passed to `mockGit` so each test declares only the bits it cares
+ * about; defaults cover the "vanilla healthy" path. */
+export type GitBehavior = {
+  remotes?: Record<string, string>;
+  branch?: string;
+  status?: string;
+  diffNames?: string;
+  pullThrows?: Error;
+  fetchThrows?: Error;
+  mergeThrows?: Error;
+  /** When set, `git rev-parse --abbrev-ref HEAD` throws this error. Used to
+   * exercise `currentBranch`'s NomadFatal-wrapping catch arm. */
+  branchThrows?: Error;
+  /** When set, `git rev-parse HEAD` throws this error. Used to exercise
+   * `headSha`'s NomadFatal-wrapping catch arm. */
+  headShaThrows?: Error;
+  /** Successive `git rev-parse HEAD` return values, consumed in order (one
+   * per call) and sticky on the last entry once exhausted. Lets a test model
+   * HEAD advancing across a merge (distinct pre/post SHAs) or staying put (a
+   * single entry, or unset for the constant default). Mutated in place. */
+  headShas?: string[];
+  /** When set, `git remote -v` throws this error. Used to exercise
+   * `loadTopology`'s NomadFatal-wrapping catch arm. */
+  remoteThrows?: Error;
+  /** Output for `git diff --name-only --diff-filter=U`: newline-separated
+   * unmerged paths after a failed merge. Empty/unset = no unmerged paths. */
+  unmergedPaths?: string;
+  /** When set, `git diff --name-only --diff-filter=U` throws this error.
+   * Used to verify the auto-resolve probe degrades gracefully and the
+   * original merge failure surfaces instead of a probe exception. */
+  diffThrows?: Error;
+};
+
+/** Per-command handler: returns the canned output (or throws the configured
+ * error). Each handler is keyed by `git ${args[0]}` or `npm ${args[0]}` for
+ * dispatch via a table, which keeps `mockGit`'s `execFileSync` body flat. */
+type Handler = (behavior: GitBehavior, args: readonly string[]) => Buffer;
+
+/** Dispatch table consumed by `mockGit`: maps `${bin} ${args[0]}` to the
+ * handler that returns the canned git/npm output (or throws). Extracted from
+ * the helper module so `mockGit` stays under the line cap. */
+export const HANDLERS: Record<string, Handler> = {
+  'git remote': (b, args) => {
+    if (args[1] !== '-v') throw new Error(`unhandled: git remote ${args.join(' ')}`);
+    if (b.remoteThrows !== undefined) throw b.remoteThrows;
+    return Buffer.from(formatRemoteV(b.remotes ?? {}));
+  },
+  'git rev-parse': (b, args) => {
+    if (args[1] === '--abbrev-ref') {
+      if (b.branchThrows !== undefined) throw b.branchThrows;
+      return Buffer.from((b.branch ?? 'main') + '\n');
+    }
+    if (args[1] === 'HEAD') {
+      if (b.headShaThrows !== undefined) throw b.headShaThrows;
+      const seq = b.headShas;
+      if (seq !== undefined && seq.length > 0) {
+        const next = seq.length > 1 ? seq.shift()! : seq[0];
+        return Buffer.from(next + '\n');
+      }
+      return Buffer.from('0123456789abcdef0123456789abcdef01234567\n');
+    }
+    throw new Error(`unhandled: git rev-parse ${args.join(' ')}`);
+  },
+  'git status': (b) => Buffer.from(b.status ?? ''),
+  'git pull': (b) => {
+    if (b.pullThrows !== undefined) throw b.pullThrows;
+    return Buffer.from('');
+  },
+  'git fetch': (b) => {
+    if (b.fetchThrows !== undefined) throw b.fetchThrows;
+    return Buffer.from('');
+  },
+  'git merge': (b) => {
+    if (b.mergeThrows !== undefined) throw b.mergeThrows;
+    return Buffer.from('');
+  },
+  'git push': () => Buffer.from(''),
+  'git diff': (b, args) => {
+    if (args.includes('--diff-filter=U')) {
+      if (b.diffThrows !== undefined) throw b.diffThrows;
+      return Buffer.from(b.unmergedPaths ?? '');
+    }
+    return Buffer.from(b.diffNames ?? '');
+  },
+  'git checkout': () => Buffer.from(''),
+  'git add': () => Buffer.from(''),
+  'git commit': () => Buffer.from(''),
+  'npm install': () => Buffer.from(''),
+};

package/src/commands.update.ts

@@ -1,11 +1,12 @@
-import { execFileSync } from 'node:child_process';
-import { closeSync, existsSync, openSync, readSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 
 import { cmdDoctor } from './commands.doctor.ts';
+import { currentBranch, headSha, reinstallIfNeeded } from './commands.update.git.ts';
+import { defaultPrompt, tryAutoResolveMergeConflict } from './commands.update.resolve.ts';
 import { REPO_HOME } from './config.ts';
 import { commitRegeneratedLockfile, precommitForkExtras } from './update.fork-extras.ts';
 import { loadTopology } from './update.topology.ts';
-import { die, gitOrFatal, gitStatusPorcelainZ, log, NomadFatal, warn } from './utils.ts';
+import { die, gitOrFatal, gitStatusPorcelainZ, log, warn } from './utils.ts';
 
 /**
  * Caller-supplied options for `cmdUpdate`. All flags optional; defaults are
@@ -27,130 +28,6 @@ export type CmdUpdateOpts = {
   prompt?: (question: string) => string;
 };
 
-/**
- * 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.
- */
-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');
-  }
-}
-
-/**
- * Default y/N prompt used when `opts.prompt` is not injected.
- *
- * Reads from `/dev/tty` byte-by-byte until newline so the call returns after
- * the user presses Enter (cooked-mode TTY line buffering). The naive
- * `readFileSync(0)` approach reads until EOF, which hangs interactive use
- * until Ctrl-D. Opening `/dev/tty` directly also means the prompt still
- * works when stdin is piped or redirected.
- *
- * @param question - Prompt text written to stdout before reading input.
- * @returns The user's trimmed answer; `''` on any failure (no controlling TTY, read error), which `runFork` treats as "no" and skips the push.
- */
-function defaultPrompt(question: string): string {
-  process.stdout.write(question);
-  let fd: number;
-  try {
-    fd = openSync('/dev/tty', 'r');
-  } catch {
-    return '';
-  }
-  try {
-    const buf = Buffer.alloc(1);
-    let answer = '';
-    while (true) {
-      const n = readSync(fd, buf, 0, 1, null);
-      if (n === 0) break;
-      const ch = buf.toString('utf8', 0, 1);
-      if (ch === '\n' || ch === '\r') break;
-      answer += ch;
-    }
-    return answer.trim();
-  } catch {
-    return '';
-  } finally {
-    closeSync(fd);
-  }
-}
-
-/**
- * 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).
- */
-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
- */
-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
- */
-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' });
-}
-
 /**
  * Perform a vanilla update by fast-forward pulling `origin/main`.
  *
@@ -172,100 +49,6 @@ function runVanilla(opts: CmdUpdateOpts): boolean {
   return false;
 }
 
-/**
- * Files release-please touches as a set on every release commit. Multi-file
- * merge conflicts in `nomad update` that consist entirely of paths from this
- * set are diagnostic for a release landing upstream while the mirror has its
- * own local commits on these artifacts. Taking upstream is the canonical
- * resolution (these are all generated artifacts the user has no business
- * editing on a mirror), but multi-file is more aggressive than the lone
- * lockfile case so we prompt before mutating.
- */
-const RELEASE_PLEASE_ARTIFACTS: ReadonlySet<string> = new Set([
-  'package.json',
-  'package-lock.json',
-  'CHANGELOG.md',
-  '.release-please-manifest.json',
-]);
-
-/**
- * Resolve a merge conflict by taking upstream's version of every listed path,
- * regenerating the lockfile via `npm install`, and committing the merge.
- * Shared body for the lone-lockfile auto-resolve and the release-please
- * multi-file prompted auto-resolve.
- *
- * @param paths - Unmerged paths to resolve via `git checkout --theirs`.
- */
-function resolveByTakingTheirs(paths: readonly string[]): void {
-  for (const p of paths) {
-    gitOrFatal(['checkout', '--theirs', '--', p], `git checkout --theirs ${p}`, REPO_HOME);
-  }
-  gitOrFatal(['add', ...paths], `git add ${paths.join(' ')}`, REPO_HOME);
-  execFileSync('npm', ['install'], { cwd: REPO_HOME, stdio: 'inherit' });
-  gitOrFatal(['add', 'package-lock.json'], 'git add package-lock.json', REPO_HOME);
-  gitOrFatal(['commit', '--no-edit'], 'git commit --no-edit', REPO_HOME);
-  log(`auto-resolved merge conflict (took upstream for ${paths.join(', ')}, reinstalled)`);
-}
-
-/**
- * Auto-resolve a merge conflict in the two scenarios both caused by
- * release-please landing upstream while the mirror has local commits:
- *
- * 1. **Sole `package-lock.json`** (silent): the lone-lockfile case from PR
- *    #96. Any host that has run `npm install` against the mirror will hit
- *    this on the next `nomad update`; take upstream + reinstall is the
- *    semantically-correct fix and surprise-free for a generated artifact.
- *
- * 2. **All paths in `RELEASE_PLEASE_ARTIFACTS` and more than one path**
- *    (prompted): a release commit conflicting on `package.json`,
- *    `CHANGELOG.md`, `.release-please-manifest.json` together with the
- *    lockfile. Same semantic resolution, but more files are touched so we
- *    require explicit y/N consent before mutating.
- *
- * Returns `false` for any other conflict shape (including probe failure);
- * the caller re-throws the original merge `NomadFatal` unchanged.
- *
- * @param opts - Update options; only `prompt` is consulted (used for the multi-file release-please consent prompt).
- * @returns `true` when the conflict was auto-resolved and the merge committed; `false` when the conflict shape does not match either auto-resolve case (caller should re-throw the original failure).
- */
-function tryAutoResolveMergeConflict(opts: CmdUpdateOpts): boolean {
-  let unmerged: string[];
-  try {
-    unmerged = execFileSync('git', ['diff', '--name-only', '--diff-filter=U'], {
-      cwd: REPO_HOME,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-      .toString()
-      .split('\n')
-      .filter((line) => line !== '');
-  } catch {
-    // Probe failure must not mask the original merge NomadFatal. Returning
-    // false lets the caller re-throw the merge error unchanged.
-    return false;
-  }
-
-  if (unmerged.length === 1 && unmerged[0] === 'package-lock.json') {
-    resolveByTakingTheirs(['package-lock.json']);
-    return true;
-  }
-
-  if (unmerged.length > 1 && unmerged.every((p) => RELEASE_PLEASE_ARTIFACTS.has(p))) {
-    const promptFn = opts.prompt ?? defaultPrompt;
-    log(`merge conflict in release-please artifacts: ${unmerged.join(', ')}`);
-    const answer = promptFn(
-      'Auto-resolve by taking upstream + `npm install` + commit? [y/N] ',
-    ).toLowerCase();
-    if (answer !== 'y' && answer !== 'yes') {
-      log('skipping auto-resolve (resolve manually then re-run `nomad update`)');
-      return false;
-    }
-    resolveByTakingTheirs(unmerged);
-    return true;
-  }
-
-  return false;
-}
-
 /**
  * Perform a fork-style update by fetching from `upstream`, merging `upstream/main` into `main`, and optionally pushing the merge to `origin`.
  *

package/src/diff.ts

@@ -4,7 +4,8 @@ import { join } from 'node:path';
 import { HOME, REPO_HOME } from './config.ts';
 import { computePreview } from './preview.ts';
 import { emitSummary } from './summary.ts';
-import { die, fail, freshBackupTs, NomadFatal } from './utils.ts';
+import { die, fail, NomadFatal } from './utils.ts';
+import { freshBackupTs } from './utils.fs.ts';
 
 /**
  * `nomad diff` command. Offline-safe, read-only preview surface that runs

package/src/extras-sync.diff.ts

@@ -0,0 +1,40 @@
+import { execFileSync } from 'node:child_process';
+
+import { warn } from './utils.ts';
+
+/**
+ * List files that differ between two paths via `git diff --no-index
+ * --name-only`. Exit 0 = identical, exit 1 = differences exist (read names
+ * from `e.stdout`, not an error). Missing-git (ENOENT) and other git failures
+ * each surface a WARN instead of collapsing to a silent empty list, so the
+ * operator can tell "no diff" (silent) apart from a skipped check (the
+ * loud-doctor contract). Argv-array `execFileSync` (no shell) so paths cannot
+ * inject.
+ *
+ * @param a - First path to compare (the local side, named in WARN messages).
+ * @param b - Second path to compare (the repo side).
+ * @returns Relative file paths that differ, or `[]` when identical or skipped.
+ */
+export function listDivergingFiles(a: string, b: string): string[] {
+  try {
+    const stdout = execFileSync('git', ['diff', '--no-index', '--name-only', a, b], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString();
+    return stdout.split('\n').filter((line) => line.length > 0);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { status?: number; stdout?: Buffer };
+    if (e.status === 1 && e.stdout !== undefined) {
+      return e.stdout
+        .toString()
+        .split('\n')
+        .filter((line) => line.length > 0);
+    }
+    if (e.code === 'ENOENT') {
+      warn(`git not on PATH; divergence check skipped for ${a}`);
+      return [];
+    }
+    /* c8 ignore next -- e.message is set on any thrown Error; String(err) is a defensive fallback */
+    warn(`divergence check failed for ${a}: ${e.message ?? String(err)}`);
+    return [];
+  }
+}

package/src/extras-sync.guards.ts

@@ -0,0 +1,52 @@
+import { isAbsolute, normalize } from 'node:path';
+
+import { NomadFatal } from './utils.ts';
+
+/**
+ * `logical` keys in `path-map.json` are project identifiers (e.g. `ha-acwd`,
+ * `foo`), never path fragments. A crafted key like `../escape` or `foo/bar`
+ * would escape `shared/extras/` via `join()` (which normalizes `..`) and land
+ * content somewhere unexpected on the filesystem. The push allow-list catches
+ * such commits at the `git add` boundary, but the filesystem mutation has
+ * already happened by then. This check fails fast before any write. The
+ * pattern matches what every reasonable project name looks like and rejects
+ * everything else; tighten only if a real project needs broader characters.
+ */
+const SAFE_LOGICAL = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Throw `NomadFatal` unless `logical` is a path-separator-free project
+ * identifier (see `SAFE_LOGICAL`). Path-traversal defense-in-depth; called
+ * before any filesystem mutation by every extras op.
+ */
+export function assertSafeLogical(logical: string): void {
+  if (!SAFE_LOGICAL.test(logical) || logical === '.' || logical === '..') {
+    throw new NomadFatal(
+      `invalid logical name in path-map.json extras: ${JSON.stringify(logical)} (must match [A-Za-z0-9._-]+; no path separators or '..')`,
+    );
+  }
+}
+
+/**
+ * Reject `localRoot` values that contain unnormalized segments (`..`,
+ * redundant `/.`, trailing slashes that don't survive `normalize`). A
+ * poisoned `path-map.json` with `host: '/tmp/x/../escape'` would silently
+ * land writes at `/tmp/escape/.planning/` because `path.join` normalizes
+ * `..` before `cpSync` sees the destination. The user thinks they declared
+ * one path and got another. Requiring `localRoot === normalize(localRoot)`
+ * (and an absolute path on top) catches the obvious traversal trick and
+ * forces poisoned-map writes to surface as a FATAL before any filesystem
+ * mutation. Same defense-in-depth shape as `assertSafeLogical`.
+ */
+export function assertSafeLocalRoot(localRoot: string, logical: string): void {
+  if (!isAbsolute(localRoot)) {
+    throw new NomadFatal(
+      `invalid localRoot for ${logical} in path-map.json: ${JSON.stringify(localRoot)} (must be absolute)`,
+    );
+  }
+  if (localRoot !== normalize(localRoot)) {
+    throw new NomadFatal(
+      `invalid localRoot for ${logical} in path-map.json: ${JSON.stringify(localRoot)} (must be already-normalized; no '..' or redundant segments)`,
+    );
+  }
+}