claude-nomad 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.21.0](https://github.com/funkadelic/claude-nomad/compare/v0.20.0...v0.21.0) (2026-05-22)
+
+
+### Added
+
+* **config:** add settings.local.json to NEVER_SYNC ([#100](https://github.com/funkadelic/claude-nomad/issues/100)) ([26c7dc1](https://github.com/funkadelic/claude-nomad/commit/26c7dc1ef15206056349d117395cd22a4ee5bd84))
+
+
+### Changed
+
+* **utils:** drop unused writeJson helper ([#101](https://github.com/funkadelic/claude-nomad/issues/101)) ([168a9d7](https://github.com/funkadelic/claude-nomad/commit/168a9d7a582e3cd8ff97e26ac32c9ee4adad1a0d))
+
+## [0.20.0](https://github.com/funkadelic/claude-nomad/compare/v0.19.0...v0.20.0) (2026-05-22)
+
+
+### Added
+
+* **update:** prompted auto-resolve for release-please artifact conflicts ([#98](https://github.com/funkadelic/claude-nomad/issues/98)) ([958cbf1](https://github.com/funkadelic/claude-nomad/commit/958cbf19839f1bda8ad0e25db0bb8495a88c2ee9))
+
 ## [0.19.0](https://github.com/funkadelic/claude-nomad/compare/v0.18.0...v0.19.0) (2026-05-22)
 
 

package/README.md

@@ -113,7 +113,7 @@ By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config
 │   ├── commands/
 │   ├── rules/
 │   ├── my-statusline.cjs     # any script you want symlinked into ~/.claude/
-│   ├── .gitignore            # defense-in-depth: blocks .claude.json, *.token, *.key, .env
+│   ├── .gitignore            # defense-in-depth: blocks .claude.json, settings.local.json, *.token, *.key, .env
 │   └── projects/             # session transcripts under logical names
 ├── hosts/
 │   ├── <your-mac>.json       # patches merged over settings.base.json
@@ -125,13 +125,13 @@ By default the CLI operates on `~/claude-nomad/` (see `REPO_HOME` in `src/config
 
 ## What gets synced vs. not
 
-| Category            | Items                                                                                                                                                                                         | Behavior                                                                                                                                                                                   |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Synced**          | `CLAUDE.md`, `agents/`, `skills/`, `commands/`, `rules/`, `my-statusline.cjs`                                                                                                                 | Symlinked into `~/.claude/` from `shared/` (see `SHARED_LINKS` in `src/config.ts`).                                                                                                        |
-| **Generated**       | `settings.json`                                                                                                                                                                               | Deep-merge of `settings.base.json` with `hosts/<hostname>.json`. Rewritten on every pull.                                                                                                  |
-| **Remapped**        | `projects/` session transcripts                                                                                                                                                               | Copied with path translation per `path-map.json`.                                                                                                                                          |
-| **Never synced**    | `~/.claude.json` (OAuth, MCP state), `history.jsonl`, `stats-cache.json`, `todos/`, `shell-snapshots/`, `debug/`, `file-history/`, `plans/`, `session-env/`, `statsig/`, `telemetry/`, `ide/` | Per-host ephemeral state.                                                                                                                                                                  |
-| **Auto-rehydrated** | `~/.claude/plugins/cache/<plugin>/...`                                                                                                                                                        | Plugin payloads not synced. Claude Code re-downloads them on first use from the `enabledPlugins` list in the regenerated `settings.json`; no manual `claude plugins install ...` per host. |
+| Category            | Items                                                                                                                                                                                                                                     | Behavior                                                                                                                                                                                   |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Synced**          | `CLAUDE.md`, `agents/`, `skills/`, `commands/`, `rules/`, `my-statusline.cjs`                                                                                                                                                             | Symlinked into `~/.claude/` from `shared/` (see `SHARED_LINKS` in `src/config.ts`).                                                                                                        |
+| **Generated**       | `settings.json`                                                                                                                                                                                                                           | Deep-merge of `settings.base.json` with `hosts/<hostname>.json`. Rewritten on every pull.                                                                                                  |
+| **Remapped**        | `projects/` session transcripts                                                                                                                                                                                                           | Copied with path translation per `path-map.json`.                                                                                                                                          |
+| **Never synced**    | `~/.claude.json` (OAuth, MCP state), `history.jsonl`, `settings.local.json` (per-host overrides), `stats-cache.json`, `todos/`, `shell-snapshots/`, `debug/`, `file-history/`, `plans/`, `session-env/`, `statsig/`, `telemetry/`, `ide/` | Per-host ephemeral state.                                                                                                                                                                  |
+| **Auto-rehydrated** | `~/.claude/plugins/cache/<plugin>/...`                                                                                                                                                                                                    | Plugin payloads not synced. Claude Code re-downloads them on first use from the `enabledPlugins` list in the regenerated `settings.json`; no manual `claude plugins install ...` per host. |
 
 > [!NOTE]
 > Plugins that depend on host-specific state (external binaries, API keys in env, MCP server URLs) still need that side set up on each host. Put them in `hosts/<host>.json` or the plugin's own per-host config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "description": "Sync Claude Code config (~/.claude/) across machines via a private Git repo, with path remapping and per-host settings overrides.",
   "keywords": [

package/shared/.gitignore

@@ -3,6 +3,7 @@
 .env
 .env.*
 .claude.json
+settings.local.json
 *.pem
 id_rsa
 id_ed25519

package/src/commands.update.ts

@@ -160,26 +160,74 @@ function reinstallIfNeeded(beforeSha: string): void {
  * today.
  *
  * @param opts - Update options; only `dryRun` is observed for this topology.
+ * @returns `true` when this path already ran `npm install` and committed the merged lockfile (so the caller should skip `reinstallIfNeeded`). Vanilla `--ff-only` pulls never conflict, so this is always `false`.
  */
-function runVanilla(opts: CmdUpdateOpts): void {
+function runVanilla(opts: CmdUpdateOpts): boolean {
   if (opts.dryRun === true) {
     log('DRY-RUN: would run `git pull --ff-only origin main`');
-    return;
+    return false;
   }
   gitOrFatal(['pull', '--ff-only', 'origin', 'main'], 'git pull', REPO_HOME);
+  return false;
 }
 
 /**
- * Auto-resolve a merge conflict when `package-lock.json` is the only unmerged
- * path. Release-please bumps the lockfile on every release, so any host that
- * has run `npm install` against its mirror will hit this conflict on the next
- * `nomad update`. The semantically-correct resolution is "take upstream's
- * lockfile, then regenerate locally", so do that automatically when no other
- * files are unmerged. Multi-file conflicts still fail loud for human review.
+ * 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.
  *
- * @returns `true` when the conflict was auto-resolved and the merge committed; `false` when other files are also unmerged (caller should re-throw the original failure).
+ * @param paths - Unmerged paths to resolve via `git checkout --theirs`.
  */
-function tryAutoResolveLockfileConflict(): boolean {
+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'], {
@@ -194,19 +242,27 @@ function tryAutoResolveLockfileConflict(): boolean {
     // false lets the caller re-throw the merge error unchanged.
     return false;
   }
-  if (unmerged.length !== 1 || unmerged[0] !== 'package-lock.json') return false;
 
-  gitOrFatal(
-    ['checkout', '--theirs', '--', 'package-lock.json'],
-    'git checkout --theirs package-lock.json',
-    REPO_HOME,
-  );
-  gitOrFatal(['add', 'package-lock.json'], 'git add package-lock.json', 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 package-lock.json conflict (took upstream, reinstalled, committed merge)');
-  return true;
+  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;
 }
 
 /**
@@ -226,7 +282,7 @@ function tryAutoResolveLockfileConflict(): boolean {
  *   - `pushOrigin`: when true, push to `origin/main` without prompting
  *   - `prompt`: optional prompt function used for interactive confirmation
  */
-function runFork(opts: CmdUpdateOpts): void {
+function runFork(opts: CmdUpdateOpts): boolean {
   const promptFn = opts.prompt ?? defaultPrompt;
   if (opts.dryRun === true) {
     log('DRY-RUN: would run `git fetch upstream`');
@@ -236,17 +292,19 @@ function runFork(opts: CmdUpdateOpts): void {
     } else {
       log('DRY-RUN: would prompt before pushing to origin/main');
     }
-    return;
+    return false;
   }
   gitOrFatal(['fetch', 'upstream'], 'git fetch upstream', REPO_HOME);
+  let autoResolved = false;
   try {
     gitOrFatal(['merge', 'upstream/main'], 'git merge upstream/main', REPO_HOME);
   } catch (err) {
-    if (!tryAutoResolveLockfileConflict()) throw err;
+    if (!tryAutoResolveMergeConflict(opts)) throw err;
+    autoResolved = true;
   }
   if (opts.pushOrigin === true) {
     gitOrFatal(['push', 'origin', 'main'], 'git push origin main', REPO_HOME);
-    return;
+    return autoResolved;
   }
   const answer = promptFn(
     'Push merge to origin/main? (y publishes to your private mirror so other hosts see it; N keeps it local) [y/N] ',
@@ -256,6 +314,7 @@ function runFork(opts: CmdUpdateOpts): void {
   } else {
     log('skipping push to origin (run `git push origin main` later)');
   }
+  return autoResolved;
 }
 
 /**
@@ -317,9 +376,8 @@ export function cmdUpdate(opts: CmdUpdateOpts = {}): void {
   }
 
   const beforeSha = headSha();
-  if (topology === 'vanilla') runVanilla(opts);
-  else runFork(opts);
+  const installAlreadyRan = topology === 'vanilla' ? runVanilla(opts) : runFork(opts);
 
-  reinstallIfNeeded(beforeSha);
+  if (!installAlreadyRan) reinstallIfNeeded(beforeSha);
   cmdDoctor();
 }

package/src/config.ts

@@ -65,6 +65,7 @@ export const SHARED_LINKS = [
 export const NEVER_SYNC = new Set([
   '.claude.json',
   'history.jsonl',
+  'settings.local.json',
   'stats-cache.json',
   'todos',
   'shell-snapshots',

package/src/utils.ts

@@ -117,11 +117,6 @@ export function readJson<T>(path: string): T {
   return data as T;
 }
 
-/** Write `data` as pretty-printed JSON (2-space indent, trailing newline). Non-atomic. */
-export function writeJson(path: string, data: unknown): void {
-  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
-}
-
 /**
  * Atomic write: temp + fsync + rename + parent-dir fsync. Survives
  * interrupted pulls. Preserves the destination file's existing mode when it