claude-nomad 0.17.0

package/src/init.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CLAUDE_HOME, type PathMap, REPO_HOME } from './config.ts';
+import { snapshotIntoShared } from './init.snapshot.ts';
+import { die, log, readJson, writeJsonAtomic } from './utils.ts';
+
+/**
+ * The HTML comment line that anchors `shared/CLAUDE.md` on a fresh scaffold.
+ * Empty file would be silently misleading after symlinking into `~/.claude/`;
+ * the comment makes the file self-describing when grep'd or `cat`-ed later.
+ */
+const SHARED_CLAUDE_MD =
+  '<!-- claude-nomad shared CLAUDE.md; symlinked into ~/.claude/CLAUDE.md by nomad pull -->\n';
+
+/**
+ * Subdirectories under `shared/` that get a `.gitkeep` placeholder on a fresh
+ * scaffold so the empty dirs survive git and materialize on every host. Pairs
+ * with the SHARED_LINKS contract in `src/config.ts` (those same names are
+ * symlinked into `~/.claude/` on every pull).
+ */
+const SHARED_KEEP_DIRS = ['agents', 'skills', 'commands', 'rules'] as const;
+
+/**
+ * Pre-flight refuse-to-clobber list. If ANY of these absolute paths
+ * already exists at the target REPO_HOME, `cmdInit` aborts with a NomadFatal
+ * naming the offender. Partial state is unsafe to merge with; init writes
+ * only into a clean target. Note that REPO_HOME itself is allowed to exist
+ * (e.g. it might be an empty dir created by `git clone` of an empty repo);
+ * the guard fires only on artifacts cmdInit is about to write.
+ */
+function preflightConflict(repoHome: string): string | null {
+  const candidates = [
+    join(repoHome, 'shared', 'settings.base.json'),
+    join(repoHome, 'shared', 'CLAUDE.md'),
+    join(repoHome, 'path-map.json'),
+    join(repoHome, 'hosts'),
+    join(repoHome, 'shared'),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return null;
+}
+
+/**
+ * Scaffold REPO_HOME with the minimal layout `cmdDoctor` expects: `shared/`
+ * with `CLAUDE.md`, four `<name>/.gitkeep` markers, and an empty
+ * `settings.base.json`; `hosts/.gitkeep`; root `path-map.json` =
+ * `{"projects":{}}`. No auto-commit; no lock (no concurrent-mutator surface
+ * on a fresh target).
+ *
+ * When `opts.snapshot` is true, the user's current `~/.claude/` SHARED_LINKS
+ * are overlaid onto `shared/` and `~/.claude/settings.json` (if present) is
+ * translated into `hosts/<HOST>.json`. The placeholder `shared/CLAUDE.md`
+ * write is skipped when `~/.claude/CLAUDE.md` exists so the snapshot captures
+ * verbatim content; originals are NOT removed. Aborts with NomadFatal
+ * (containing `already initialized`) when any scaffold path already exists,
+ * identical to plain init; a bare `shared/` dir is enough to refuse since
+ * partial state is unsafe to merge with.
+ */
+export function cmdInit(opts: { snapshot?: boolean } = {}): void {
+  const snapshot = opts.snapshot === true;
+
+  const conflict = preflightConflict(REPO_HOME);
+  if (conflict !== null) {
+    die(`already initialized; refusing to clobber ${conflict}`);
+  }
+
+  // Create the directory structure first so the subsequent file writes have
+  // a parent. `recursive: true` is a no-op when the dir already exists, but
+  // the preflight guarantees it does not.
+  mkdirSync(join(REPO_HOME, 'shared'), { recursive: true });
+  mkdirSync(join(REPO_HOME, 'hosts'), { recursive: true });
+  for (const name of SHARED_KEEP_DIRS) {
+    mkdirSync(join(REPO_HOME, 'shared', name), { recursive: true });
+  }
+
+  // Per-artifact writes. Each emits a log line so the user sees the
+  // structure being built. Atomic writes for JSON so a power loss mid-init
+  // leaves either a clean fresh-clone state or the fully-written scaffold,
+  // never a half-written JSON the next pull would die on. In snapshot mode,
+  // skip the CLAUDE.md placeholder when a real source exists so the overlay
+  // copies the user content verbatim instead of an overwrite-from-placeholder.
+  const userClaudeMd = join(CLAUDE_HOME, 'CLAUDE.md');
+  if (!snapshot || !existsSync(userClaudeMd)) {
+    writeFileSync(join(REPO_HOME, 'shared', 'CLAUDE.md'), SHARED_CLAUDE_MD);
+    log('created shared/CLAUDE.md');
+  }
+  for (const name of SHARED_KEEP_DIRS) {
+    writeFileSync(join(REPO_HOME, 'shared', name, '.gitkeep'), '');
+    log(`created shared/${name}/.gitkeep`);
+  }
+  writeFileSync(join(REPO_HOME, 'hosts', '.gitkeep'), '');
+  log('created hosts/.gitkeep');
+  writeJsonAtomic(join(REPO_HOME, 'shared', 'settings.base.json'), {});
+  log('created shared/settings.base.json');
+  writeJsonAtomic(join(REPO_HOME, 'path-map.json'), { projects: {} } satisfies PathMap);
+  log('created path-map.json');
+
+  if (snapshot) {
+    snapshotIntoShared();
+    log(`snapshot staged in shared/; review, then 'nomad push' to share with other hosts.`);
+    log('~/.claude/ originals were NOT removed.');
+  }
+
+  log('init complete');
+}
+
+/**
+ * Read-only health classifier for `cmdDoctor`'s `repo state:` header.
+ * Inspects three signals at the given `repoHome`: `shared/settings.base.json`
+ * presence, `path-map.json.projects` having at least one entry, and
+ * `hosts/<host>.json` presence.
+ *
+ * Returns `'empty'` when the base is missing AND the path-map has no entries
+ * (either missing or `projects` is empty); `'populated'` when all three
+ * signals are positive; `'partial'` for anything in between. Malformed
+ * `path-map.json` is treated as zero entries rather than thrown, so a doctor
+ * run against a corrupted scaffold still produces a classification line.
+ *
+ * The `host` parameter is passed explicitly (rather than read from the
+ * imported `HOST` constant) so the test fixture can drive multiple host
+ * scenarios without mutating module-level state via `vi.resetModules()`.
+ */
+export function classifyRepoState(
+  repoHome: string,
+  host: string,
+): 'empty' | 'partial' | 'populated' {
+  const basePath = join(repoHome, 'shared', 'settings.base.json');
+  const mapPath = join(repoHome, 'path-map.json');
+  const hostPath = join(repoHome, 'hosts', `${host}.json`);
+
+  const hasBase = existsSync(basePath);
+  const hasMap = existsSync(mapPath);
+  const hasHost = existsSync(hostPath);
+
+  let mapEntryCount = 0;
+  if (hasMap) {
+    try {
+      const map = readJson<PathMap>(mapPath);
+      mapEntryCount = Object.keys(map.projects).length;
+    } catch {
+      // Malformed JSON: treat as zero entries, do NOT throw. The doctor's
+      // own JSON-parse FAIL line will surface the malformed file separately.
+      mapEntryCount = 0;
+    }
+  }
+
+  if (!hasBase && mapEntryCount === 0) return 'empty';
+  if (hasBase && mapEntryCount > 0 && hasHost) return 'populated';
+  return 'partial';
+}
+
+/**
+ * Suffix that follows `repo state: WARN partial` per the fixed priority
+ * order. First matching condition wins, exactly one suffix per line.
+ * Inspects the same on-disk signals `classifyRepoState` reads (base file,
+ * `path-map.json` + its `.projects` entry count, `hosts/<host>.json`), but
+ * explicitly distinguishes "path-map missing" from "path-map present but
+ * empty" because users debug differently for each.
+ *
+ * Lives alongside `classifyRepoState` so the suffix rules and the classifier
+ * stay co-located: changes to one almost always require updating the other.
+ * Returns the string with a leading `- ` separator so the caller can
+ * concatenate directly without re-deciding the separator.
+ */
+export function reasonForPartial(repoHome: string, host: string): string {
+  const basePath = join(repoHome, 'shared', 'settings.base.json');
+  const mapPath = join(repoHome, 'path-map.json');
+  const hostPath = join(repoHome, 'hosts', `${host}.json`);
+  if (!existsSync(basePath)) return '- shared/settings.base.json missing';
+  if (!existsSync(mapPath)) return '- path-map.json missing';
+  let mapEntryCount: number;
+  try {
+    const map = readJson<PathMap>(mapPath);
+    mapEntryCount = Object.keys(map.projects).length;
+  } catch {
+    // Malformed JSON: treat as zero entries. Doctor's own JSON-parse FAIL
+    // line surfaces the malformed file separately.
+    mapEntryCount = 0;
+  }
+  if (mapEntryCount === 0) return '- path-map.json.projects has no entries';
+  if (!existsSync(hostPath)) return `- hosts/${host}.json missing`;
+  // Defensive fallback: classifyRepoState returned 'partial' for a reason
+  // not captured by the four signals above. Should be unreachable in
+  // practice because the priority order is exhaustive against the
+  // classifier's definition of populated.
+  return '- partial state (unknown gap)';
+}

package/src/links.ts

@@ -0,0 +1,123 @@
+import { existsSync, lstatSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CLAUDE_HOME, HOST, REPO_HOME, SHARED_LINKS } from './config.ts';
+import {
+  backupBeforeWrite,
+  deepMerge,
+  die,
+  ensureSymlink,
+  log,
+  readJson,
+  warn,
+  writeJsonAtomic,
+} from './utils.ts';
+
+/**
+ * Symlink the `SHARED_LINKS` names from the repo's `shared/` dir into
+ * `~/.claude/`. Two-pass: first back up and remove any pre-existing
+ * non-symlink at each link path (auto-move using `ts` as the backup
+ * timestamp), then create the symlinks. Skips a link entirely when the repo
+ * has no counterpart, so a host where `shared/commands/` does not exist
+ * keeps its local `~/.claude/commands/` instead of having it silently
+ * deleted.
+ *
+ * `opts.dryRun` (default `false`): when `true`, no disk mutation occurs. The
+ * function logs `would auto-move non-symlink:` and `would create symlink:`
+ * lines describing the would-be effect and returns. Backwards-compatible: a
+ * call with no opts arg or with `dryRun: false` keeps the prior mutating
+ * behavior.
+ */
+export function applySharedLinks(ts: string, opts: { dryRun?: boolean } = {}): void {
+  const dryRun = opts.dryRun === true;
+  for (const name of SHARED_LINKS) {
+    const linkPath = join(CLAUDE_HOME, name);
+    const target = join(REPO_HOME, 'shared', name);
+    if (!existsSync(linkPath)) continue;
+    if (lstatSync(linkPath).isSymbolicLink()) continue;
+    if (!existsSync(target)) continue;
+    if (dryRun) {
+      log(`would auto-move non-symlink: ${linkPath} -> backup/${ts}/${name}`);
+      continue;
+    }
+    backupBeforeWrite(linkPath, ts);
+    rmSync(linkPath, { recursive: true, force: true });
+  }
+  for (const name of SHARED_LINKS) {
+    const target = join(REPO_HOME, 'shared', name);
+    if (!existsSync(target)) continue;
+    if (dryRun) {
+      log(`would create symlink: ${join(CLAUDE_HOME, name)} -> ${target}`);
+      continue;
+    }
+    ensureSymlink(join(CLAUDE_HOME, name), target);
+  }
+}
+
+/**
+ * Deep-merge `shared/settings.base.json` with `hosts/<HOST>.json` (when
+ * present) and atomically rewrite `~/.claude/settings.json`. Composes
+ * `writeJsonAtomic` (temp + fsync + rename + parent fsync) on top of
+ * `backupBeforeWrite`, so an interrupted pull leaves either the pre-pull
+ * file or the fully-merged file, never a half-written one. Surfaces a
+ * stderr WARN when no host override exists AND prior settings has top-level
+ * keys not in base; the matching doctor-side FAIL with non-zero exit lives
+ * in `cmdDoctor`.
+ *
+ * `opts.dryRun` (default `false`): when `true`, skip the
+ * `backupBeforeWrite` + `writeJsonAtomic` pair and instead log a single
+ * `would write settings.json ...` line. The drift-detection WARN above
+ * still fires (informational), so users see the same warning a real pull
+ * 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).
+ */
+export function regenerateSettings(ts: string, opts: { dryRun?: boolean } = {}): void {
+  const dryRun = opts.dryRun === true;
+  const basePath = join(REPO_HOME, 'shared', 'settings.base.json');
+  const hostPath = join(REPO_HOME, 'hosts', `${HOST}.json`);
+  if (!existsSync(basePath)) {
+    die("repo not initialized; run 'nomad init' to scaffold");
+  }
+
+  const base = readJson<Record<string, unknown>>(basePath);
+  const hasOverrides = existsSync(hostPath);
+  const overrides = hasOverrides ? readJson<Record<string, unknown>>(hostPath) : {};
+  const merged = deepMerge(base, overrides);
+
+  const settingsPath = join(CLAUDE_HOME, 'settings.json');
+
+  // Pull-side surface: warn-then-proceed when no host file matches AND
+  // existing settings has top-level keys not in base. Informational only;
+  // pull does NOT abort. The matching doctor-side FAIL with non-zero exit
+  // lives in `cmdDoctor`. The WARN runs in dry-run mode too: the user sees
+  // the same drift signal they would see on a real pull.
+  if (!hasOverrides && existsSync(settingsPath)) {
+    // Best-effort drift report. Malformed prior settings.json must not block
+    // regeneration: the whole point here is to overwrite it from base+overrides.
+    try {
+      const existing = readJson<Record<string, unknown>>(settingsPath);
+      const baseKeys = new Set(Object.keys(base));
+      const drift = Object.keys(existing).filter((k) => !baseKeys.has(k));
+      if (drift.length > 0) {
+        warn(
+          `no hosts/${HOST}.json found; existing settings has unbased keys ${JSON.stringify(drift)}. ` +
+            `Set NOMAD_HOST to match a hosts/*.json or rerun 'nomad doctor' for candidates.`,
+        );
+      }
+    } catch {
+      warn('existing settings.json is malformed; skipping drift-check and regenerating.');
+    }
+  }
+
+  const overrideLabel = hasOverrides ? `${HOST}.json` : 'no host overrides';
+
+  if (dryRun) {
+    log(`would write settings.json (base + ${overrideLabel})`);
+    return;
+  }
+
+  backupBeforeWrite(settingsPath, ts);
+  writeJsonAtomic(settingsPath, merged);
+  log(`wrote settings.json (base + ${overrideLabel})`);
+}

package/src/nomad.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * claude-nomad: Claude Code config sync wrapper over a private Git repo.
+ *
+ * Adds two features the existing community tools lack:
+ *   1. Path remapping so session history follows you across machines even
+ *      when the same repo lives at /Users/norm/code/foo vs /home/norm/foo.
+ *   2. Per-host overrides for settings.json via deep merge.
+ *
+ * Layout (~/claude-nomad/):
+ *   shared/                  symlinked into ~/.claude/ on every host
+ *   shared/settings.base.json  merged with hosts/<hostname>.json -> settings.json
+ *   shared/projects/         session transcripts keyed by logical name
+ *   hosts/<hostname>.json    per-host settings.json overrides
+ *   path-map.json            logical project name -> { host: localPath }
+ */
+
+import { cmdDoctor } from './commands.doctor.ts';
+import { cmdDropSession } from './commands.drop-session.ts';
+import { cmdPull } from './commands.pull.ts';
+import { cmdPush } from './commands.push.ts';
+import { cmdUpdate } from './commands.update.ts';
+import { HOME } from './config.ts';
+import { cmdDiff } from './diff.ts';
+import { cmdInit } from './init.ts';
+import { resumeCmd } from './resume.ts';
+import { fail, NomadFatal } from './utils.ts';
+
+/**
+ * Static JSON import for the `--version` arm. Uses `with { type: 'json' }`
+ * per Node 22+ import-attribute syntax (the older `assert { type: 'json' }`
+ * was removed). Reading synchronously at module load avoids a runtime fs
+ * walk on every `nomad --version` invocation and keeps the smoke-test
+ * contract (in npm-publish.yml) deterministic.
+ */
+import pkg from '../package.json' with { type: 'json' };
+
+/**
+ * Multi-line help block printed on the `default:` arm of the dispatcher
+ * (bare `nomad` and any unknown subcommand). Per-subcommand `usage:` lines
+ * stay terse and live inside their own `case` arms; this block exists so a
+ * cold invocation of `nomad` is self-describing without forcing the user
+ * into the README. Channel is stderr, exit code is 1.
+ */
+const DEFAULT_HELP = [
+  'usage: nomad <command> [flags]',
+  '',
+  'Commands:',
+  '  pull             Sync ~/.claude/ from the shared repo (settings, symlinks, sessions).',
+  '       --dry-run   Run lock + git pull, then preview every mutation without writing.',
+  '',
+  '  push             Rebase, run safety checks (gitleaks, gitlinks, allow-list), commit, push.',
+  '       --dry-run   Run pre-checks (rebase, gitleaks probe, gitlink scan) and preview',
+  '                   remap, without staging or pushing.',
+  '',
+  '  diff             Offline preview of what `pull` would change against local repo state.',
+  '                   No git pull, no lock acquired.',
+  '',
+  '  init             Scaffold an empty ~/claude-nomad/ repo (shared/, hosts/, path-map).',
+  '       --snapshot  Overlay the current ~/.claude/ into shared/ as the initial seed.',
+  '',
+  '  doctor                  Read-only health check (symlinks, host file, path-map,',
+  '                          gitleaks, gitlinks).',
+  '       --resume-cmd <id>  Print `cd <abspath> && claude --resume <id>` for a session id',
+  '                          from ~/.claude/projects/.',
+  '',
+  '  drop-session <id>   Unstage shared/projects/<logical>/<id>.jsonl from the staged tree (local ~/.claude/projects is never touched).',
+  '',
+  '  update              Topology-aware upgrade of ~/claude-nomad/ to the latest upstream.',
+  '       --dry-run      Detect topology + pre-flight, print would-be git commands only.',
+  '       --force        Proceed even when the working tree is not clean.',
+  '       --push-origin  Fork topology only: push the merge to origin/main without prompting.',
+  '',
+  'Run `nomad doctor` to validate your setup. Edit shared/ or hosts/<HOST>.json',
+  'in the repo, never ~/.claude/settings.json directly (it is regenerated on',
+  'every pull).',
+].join('\n');
+
+if (!HOME) {
+  fail(
+    'could not determine home directory (HOME env unset and no uid mapping). Set HOME and retry.',
+  );
+  process.exit(1);
+}
+
+try {
+  const cmd = process.argv[2];
+  switch (cmd) {
+    case '--version':
+      // Early-arm placement so a broken --version invocation never falls
+      // through to full command dispatch. Bare semver output (no prefix)
+      // matches the contract asserted by the smoke-test step in
+      // .github/workflows/npm-publish.yml (`nomad --version` strict-equal
+      // to the published tag minus the leading `v`).
+      if (process.argv.length !== 3) {
+        console.error('usage: nomad --version (no extra arguments)');
+        process.exit(1);
+      }
+      console.log(pkg.version);
+      break;
+    case 'pull': {
+      // Sub-flag: `pull --dry-run` runs the full pull flow (lock + git pull)
+      // in preview mode without mutating ~/.claude/. Any other argv after
+      // `pull` is rejected so a typo does not silently degrade to a real pull.
+      const sub = process.argv[3];
+      if (sub === undefined) {
+        cmdPull();
+      } else if (sub === '--dry-run' && process.argv.length === 4) {
+        cmdPull({ dryRun: true });
+      } else {
+        console.error('usage: nomad pull [--dry-run]');
+        process.exit(1);
+      }
+      break;
+    }
+    case 'push': {
+      // Sub-flag: `push --dry-run` runs the pre-checks and remap preview
+      // without staging, scanning, committing, or pushing. Any other argv
+      // after `push` is rejected so a typo does not silently degrade.
+      const sub = process.argv[3];
+      if (sub === undefined) {
+        cmdPush();
+      } else if (sub === '--dry-run' && process.argv.length === 4) {
+        cmdPush({ dryRun: true });
+      } else {
+        console.error('usage: nomad push [--dry-run]');
+        process.exit(1);
+      }
+      break;
+    }
+    case 'init':
+      // Two valid forms: `nomad init` (empty scaffold) and
+      // `nomad init --snapshot` (overlay user's current ~/.claude/ into
+      // shared/). Anything else (unknown flag, extra positional arg, two
+      // flags) hits the same usage-error pattern as `doctor --resume-cmd`.
+      if (process.argv[3] === undefined) {
+        cmdInit();
+      } else if (process.argv[3] === '--snapshot' && process.argv[4] === undefined) {
+        cmdInit({ snapshot: true });
+      } else {
+        console.error('usage: nomad init [--snapshot]');
+        process.exit(1);
+      }
+      break;
+    case 'diff':
+      // Offline, lockless preview against local repo state. No git pull, no
+      // lock acquisition. Reject any argv after `diff` since this slice
+      // accepts no flags.
+      if (process.argv.length > 3) {
+        console.error('usage: nomad diff');
+        process.exit(1);
+      }
+      cmdDiff();
+      break;
+    case 'update': {
+      // Set-based parse so flag order does not matter and duplicates are
+      // rejected (`--dry-run --dry-run` is a typo, not a no-op). Unknown
+      // flags hit the same usage-error pattern as other subcommands.
+      const known = new Set(['--dry-run', '--force', '--push-origin']);
+      const seen = new Set<string>();
+      let argvOk = true;
+      for (let i = 3; i < process.argv.length; i++) {
+        const flag = process.argv[i];
+        if (!known.has(flag) || seen.has(flag)) {
+          argvOk = false;
+          break;
+        }
+        seen.add(flag);
+      }
+      if (!argvOk) {
+        console.error('usage: nomad update [--dry-run] [--force] [--push-origin]');
+        process.exit(1);
+      }
+      cmdUpdate({
+        dryRun: seen.has('--dry-run'),
+        force: seen.has('--force'),
+        pushOrigin: seen.has('--push-origin'),
+      });
+      break;
+    }
+    case 'doctor':
+      // Sub-flag: `doctor --resume-cmd <session-id>` dispatches to the
+      // read-only sidecar that prints `cd <abspath> && claude --resume <id>`.
+      if (process.argv[3] === '--resume-cmd') {
+        const id = process.argv[4];
+        if (typeof id !== 'string' || id.length === 0) {
+          console.error('usage: nomad doctor --resume-cmd <session-id>');
+          process.exit(1);
+        }
+        resumeCmd(id);
+      } else {
+        cmdDoctor();
+      }
+      break;
+    case 'drop-session': {
+      // Single positional argv; cmdDropSession revalidates id at entry as
+      // defense-in-depth (the function may be called from non-argv paths
+      // in tests). The argv regex mirrors the function-entry allowlist
+      // (`[A-Za-z0-9_-]`) but additionally rejects ids starting with `-`
+      // so a typo like `nomad drop-session --bogus` shows the usage line,
+      // not a FATAL. The length bound matches cmdDropSession.
+      const id = process.argv[3];
+      if (
+        process.argv.length !== 4 ||
+        typeof id !== 'string' ||
+        !/^[A-Za-z0-9_][A-Za-z0-9_-]{0,127}$/.test(id)
+      ) {
+        console.error('usage: nomad drop-session <id>');
+        process.exit(1);
+      }
+      cmdDropSession(id);
+      break;
+    }
+    default:
+      console.error(DEFAULT_HELP);
+      process.exit(1);
+  }
+} catch (err) {
+  // Top-level safety net for NomadFatal thrown from contexts that don't have
+  // their own try/catch (e.g., cmdDoctor's readJson path). cmdPull / cmdPush
+  // have their own catches so their finally blocks release the lock first.
+  if (err instanceof NomadFatal) {
+    fail(err.message);
+    process.exit(1);
+  }
+  throw err;
+}

package/src/preview.ts

@@ -0,0 +1,141 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { green, red } from './color.ts';
+import { CLAUDE_HOME, HOST, REPO_HOME } from './config.ts';
+import { applySharedLinks } from './links.ts';
+import { remapPull } from './remap.ts';
+import { deepMerge, log, readJson } from './utils.ts';
+
+/**
+ * Minimal in-tree unified-diff helper for two pre-stringified JSON
+ * documents. Walks the line arrays in parallel and emits a unified-diff
+ * style output: unchanged lines prefixed with a space, removed lines with
+ * `-` (red), added lines with `+` (green), plus at most three lines of
+ * surrounding context per changed block. The implementation is intentionally
+ * naive (no LCS); for two ~50-line settings JSON inputs the result is
+ * acceptable even if not optimal.
+ *
+ * Returns the empty string when the inputs are byte-identical so the caller
+ * can suppress the section. Picocolors handles `NO_COLOR` / `FORCE_COLOR`
+ * detection, so the `red`/`green` wrappers degrade to identity in non-TTY
+ * environments and the output stays literal `-` / `+` prefixed.
+ *
+ * The header line `--- ~/.claude/settings.json` / `+++ would write` is
+ * literal; callers that want a different header can prepend their own.
+ */
+export function diffJsonStrings(currentJsonText: string, newJsonText: string): string {
+  if (currentJsonText === newJsonText) return '';
+  const a = currentJsonText.split('\n');
+  const b = newJsonText.split('\n');
+  const lines: string[] = [];
+  lines.push('--- ~/.claude/settings.json');
+  lines.push('+++ would write');
+
+  // Walk both arrays in parallel. Lines that match index-wise are context;
+  // others are emitted as -a / +b. A real unified-diff would compute the
+  // longest common subsequence; this naive walk is good enough for two JSON
+  // documents pretty-printed at the same indentation level.
+  const maxLen = Math.max(a.length, b.length);
+  for (let i = 0; i < maxLen; i++) {
+    const av = a[i];
+    const bv = b[i];
+    if (av === bv) {
+      if (av !== undefined) lines.push(` ${av}`);
+      continue;
+    }
+    if (av !== undefined) lines.push(red(`-${av}`));
+    if (bv !== undefined) lines.push(green(`+${bv}`));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Read JSON from `path` returning the parsed object, or `null` on any
+ * filesystem or parse failure. Used by computePreview's tolerant settings
+ * read so a malformed settings.json on a fresh-clone host does not abort
+ * the preview surface.
+ */
+function readJsonOrNull(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return null;
+  try {
+    return readJson<Record<string, unknown>>(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Orchestrate the dry-run preview across all three sync modalities:
+ * symlinks (via applySharedLinks dry-run), settings.json (via deepMerge +
+ * diffJsonStrings; we do NOT call regenerateSettings dry-run because that
+ * emits a "would write" intent line that duplicates the unified diff
+ * produced here), and projects (via remapPull dry-run).
+ *
+ * Returns `{ unmapped, collisions }` aggregated from remapPull. Collisions
+ * is always 0 in this slice; a future slice wires path-encoding collision
+ * detection through.
+ *
+ * Tolerant by design: missing `shared/settings.base.json` and malformed
+ * `~/.claude/settings.json` both emit a single log line and continue rather
+ * than throw. This supports `cmdDiff`'s offline-safe contract, where the
+ * preview may run against a partially-scaffolded repo (e.g. right after a
+ * fresh clone before `nomad init`).
+ *
+ * Settings diff output goes through `log()` so each line gets the ℹ︎-prefixed
+ * prefix, keeping output channels consistent across the three sections.
+ */
+export function computePreview(ts: string): { unmapped: number; collisions: number } {
+  log(`would pull on host=${HOST} (dry-run; no mutation)`);
+
+  // Symlinks: applySharedLinks emits its own would-create / would-auto-move
+  // lines. dryRun:true is mandatory; a real call here would mutate disk.
+  applySharedLinks(ts, { dryRun: true });
+
+  // Settings section: skip-with-log when base or current is missing. Per the
+  // locked phrasing decision, the message text is fixed so cmdDiff users see
+  // the same line regardless of which side is missing. Calling
+  // regenerateSettings(ts, { dryRun: true }) would only emit a generic
+  // "would write" intent line; we want the unified diff here, so we compute
+  // it directly from base + host-override + current.
+  const basePath = join(REPO_HOME, 'shared', 'settings.base.json');
+  const hostPath = join(REPO_HOME, 'hosts', `${HOST}.json`);
+  const settingsPath = join(CLAUDE_HOME, 'settings.json');
+  const base = readJsonOrNull(basePath);
+  if (base === null) {
+    // Base is the load-bearing input here. Per the locked phrasing decision,
+    // emit one canonical message and skip the diff. The current-side missing
+    // case (no ~/.claude/settings.json) is handled below by treating current
+    // as `{}` and producing a normal diff; only base-missing is fatal-ish.
+    log('settings.json: section skipped (base or current missing)');
+  } else {
+    // Tolerate a malformed hosts/<HOST>.json the same way base and current
+    // are tolerated: log once and fall back to no overrides so the preview
+    // keeps rendering instead of crashing the dry-run.
+    const hostOverrides = readJsonOrNull(hostPath);
+    if (hostOverrides === null && existsSync(hostPath)) {
+      log(`settings.json: malformed hosts/${HOST}.json; ignoring overrides`);
+    }
+    const overrides = hostOverrides ?? {};
+    const merged = deepMerge(base, overrides);
+    const current = readJsonOrNull(settingsPath);
+    if (current === null && existsSync(settingsPath)) {
+      log('settings.json: malformed; skipping diff');
+    } else {
+      const currentText = JSON.stringify(current ?? {}, null, 2);
+      const mergedText = JSON.stringify(merged, null, 2);
+      const diff = diffJsonStrings(currentText, mergedText);
+      if (diff === '') {
+        log('settings.json: no changes');
+      } else {
+        log('settings.json:');
+        for (const line of diff.split('\n')) log(line);
+      }
+    }
+  }
+
+  // Projects: remapPull emits its own would-overwrite lines and returns the
+  // skipped count.
+  const remapResult = remapPull(ts, { dryRun: true });
+  return { unmapped: remapResult.unmapped, collisions: 0 };
+}