claude-nomad 0.31.0 → 0.32.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.32.1](https://github.com/funkadelic/claude-nomad/compare/v0.32.0...v0.32.1) (2026-05-30)
+
+
+### Fixed
+
+* **redact:** make applyRedactions overlap-safe ([#186](https://github.com/funkadelic/claude-nomad/issues/186)) ([8da07d1](https://github.com/funkadelic/claude-nomad/commit/8da07d1ef58b7f6596ca479a3c57863fc75f35bb))
+
+## [0.32.0](https://github.com/funkadelic/claude-nomad/compare/v0.31.0...v0.32.0) (2026-05-30)
+
+
+### Added
+
+* **adopt:** add nomad adopt for pre-existing local dirs ([#185](https://github.com/funkadelic/claude-nomad/issues/185)) ([251d5b7](https://github.com/funkadelic/claude-nomad/commit/251d5b71569315cbcf6ae073e29faecb4dbe5aa2))
+
+
+### Documentation
+
+* **readme:** note synced skills carry shims, not the tool engine ([#183](https://github.com/funkadelic/claude-nomad/issues/183)) ([695ba02](https://github.com/funkadelic/claude-nomad/commit/695ba029a92f397a1469ca1cf5f782e0b5bcecac))
+
 ## [0.31.0](https://github.com/funkadelic/claude-nomad/compare/v0.30.0...v0.31.0) (2026-05-29)
 
 

package/README.md

@@ -194,6 +194,17 @@ Pointers and specifics:
 > URLs) still need that side set up on each host. Put them in `hosts/<host>.json` or the plugin's
 > own per-host config.
 
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> Syncing a tool's `skills/` or `commands/` files copies the command shims, not the engine behind
+> them. If a tool keeps a binary or runtime outside `~/.claude/` (installed with `npm i -g`, a setup
+> script, and so on), nomad does not carry that part, so the synced commands appear on a new host but
+> fail until the tool itself is installed there. Install such tools once per host. For example, if you
+> sync the GSD (`get-shit-done`) skills, run `npm i -g get-shit-done-cc` on each host, pinned to the
+> version that matches your committed skills. Claude Code marketplace plugins (such as superpowers)
+> are the exception: they are listed in `enabledPlugins`, synced via `settings.base.json`, and
+> re-downloaded by Claude Code automatically, so they need no manual install.
+
 For the rationale behind these choices, see
 [What does NOT sync (deliberate trade-offs)](#what-does-not-sync-deliberate-trade-offs).
 
@@ -614,6 +625,8 @@ point under your npm prefix's `bin/`), then delete the alias line from your shel
 | `nomad push --dry-run`           | Run pre-push safety checks (gitleaks probe, rebase, remap preview, gitlink scan, allow-list) and a read-only gitleaks leak preview over a throwaway temp copy of the sessions and extras this host would stage; skip stage, commit, and push. Exits 1 if a leak is found in the preview. Nothing is written to the sync repo.                                                                                                                                                |
 | `nomad push --redact-all`        | Redact all findings non-interactively (backup written first) without a TTY. Does not auto-Allow findings. After redaction re-stages and re-scans; aborts with the session-aware FATAL if any finding survives. Use this in scripts or when you are confident every finding is a real secret that should be scrubbed. See [Recovery flow: push-time interactive menu](#recovery-flow-push-time-interactive-menu).                                                             |
 | `nomad drop-session <id>`        | Surgically unstage every `shared/projects/*/<id>.jsonl` and the sibling `shared/projects/*/<id>/` subagent directory from the staged tree of `~/claude-nomad/`. Idempotent; the local `~/.claude/projects/<encoded>/<id>.jsonl` and `<id>/` tree are preserved. See [Recovery flows](#recovery-flows).                                                                                                                                                                       |
+| `nomad adopt <name>`             | Back up, then move a pre-existing `~/.claude/<name>` directory into `shared/<name>`, recreate the symlink so this host keeps working, and stage the result for push. `<name>` must already be listed in `SHARED_LINKS` or in the `sharedDirs` field of `path-map.json`; adopt is a mover, not a config editor, so it never writes `path-map.json` itself.                                                                                                                    |
+| `nomad adopt <name> --dry-run`   | Preview the planned backup, move, and `git add` without touching the filesystem or the git index.                                                                                                                                                                                                                                                                                                                                                                            |
 | `nomad redact <session-id>`      | Rewrite the secret span in the local source transcript for a session, backed up to `~/.cache/claude-nomad/backup/`. Refuses to touch a session that was modified recently (potential active session). Safe to re-run. See [`nomad redact <session-id>`](#nomad-redact-session-id).                                                                                                                                                                                           |
 | `nomad redact --rule <id>`       | Limit redaction to findings of one gitleaks rule id only.                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `nomad redact --dry-run`         | Show what `nomad redact` would change without writing anything.                                                                                                                                                                                                                                                                                                                                                                                                              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "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/src/commands.adopt.ts

@@ -0,0 +1,183 @@
+import { cpSync, existsSync, lstatSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CLAUDE_HOME, HOME, REPO_HOME, SHARED_LINKS, type PathMap } from './config.ts';
+import { isValidSharedDir } from './config.sharedDirs.guard.ts';
+import { fail, gitOrFatal, log, NomadFatal } from './utils.ts';
+import { backupBeforeWrite, ensureSymlink, freshBackupTs } from './utils.fs.ts';
+import { readPathMap } from './utils.json.ts';
+
+/**
+ * Follow-up hint printed after a successful adopt. Exported so Plan 02's
+ * doctor hint can reuse the exact literal without duplicating the string.
+ */
+export const ADOPT_PUSH_HINT = 'run `nomad push` to share with other hosts';
+
+/**
+ * lstat-based existence check that, unlike `existsSync`, does NOT follow
+ * symlinks: a dangling symlink at `p` returns true. Used for the clobber
+ * guard so an existing (even broken) `shared/<name>` link is refused rather
+ * than fed to `cpSync`, which would otherwise throw an opaque non-NomadFatal
+ * error on a dangling-symlink destination.
+ *
+ * @param p Absolute path to probe.
+ * @returns True when any entry (file, dir, or symlink) exists at `p`.
+ */
+function lexists(p: string): boolean {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read `path-map.json` if present; fall back to an empty map when absent.
+ * Adopt reads sharedDirs for membership only; it never writes path-map.json.
+ *
+ * @param repoHome Absolute path to the nomad repo root.
+ * @returns The parsed PathMap, or `{ projects: {} }` when path-map.json is absent.
+ */
+function readMapIfPresent(repoHome: string): PathMap {
+  const mapPath = join(repoHome, 'path-map.json');
+  return existsSync(mapPath) ? readPathMap(mapPath) : { projects: {} };
+}
+
+/**
+ * Return true when `name` is an already-configured shared target: either a
+ * static `SHARED_LINKS` member or a `sharedDirs` entry declared in
+ * `path-map.json`. This is a read-only membership check; adopt never writes
+ * `path-map.json` (D-03).
+ *
+ * @param name Candidate name.
+ * @param map Parsed path-map (sharedDirs membership source).
+ * @returns True when name is a configured shared target.
+ */
+function isConfiguredTarget(name: string, map: PathMap): boolean {
+  return (
+    (SHARED_LINKS as readonly string[]).includes(name) || (map.sharedDirs?.includes(name) ?? false)
+  );
+}
+
+/**
+ * Return true when `name` is safe to adopt. Static `SHARED_LINKS` members
+ * are pre-approved and bypass `isValidSharedDir` (which rejects RESERVED_SHARED,
+ * overlapping with SHARED_LINKS). Candidate `sharedDirs` names must pass
+ * `isValidSharedDir` to prevent path injection (D-00a).
+ *
+ * @param name Candidate name from the CLI argument.
+ * @returns True when the name is safe for adopt processing.
+ */
+function isValidAdoptName(name: string): boolean {
+  if ((SHARED_LINKS as readonly string[]).includes(name)) return true;
+  return isValidSharedDir(name);
+}
+
+/**
+ * Perform the actual backup -> copy -> remove -> relink -> stage sequence
+ * once all preconditions have passed. Extracts the mutation block so the
+ * top-level function stays under the cognitive-complexity threshold.
+ *
+ * @param name The validated, configured, real-directory name to adopt.
+ * @param linkPath Absolute path of the source directory (`CLAUDE_HOME/<name>`).
+ * @param sharedTarget Absolute path of the destination (`REPO_HOME/shared/<name>`).
+ */
+function performAdoptMove(name: string, linkPath: string, sharedTarget: string): void {
+  const backupBase = join(HOME, '.cache', 'claude-nomad', 'backup');
+  const ts = freshBackupTs(backupBase);
+
+  // D-00c: backup before any mutation
+  backupBeforeWrite(linkPath, ts);
+
+  // D-00e, V-07: copy fully into shared/ BEFORE removing the source so a
+  // mid-move crash cannot lose user content
+  cpSync(linkPath, sharedTarget, { recursive: true, force: true, preserveTimestamps: true });
+  rmSync(linkPath, { recursive: true, force: true });
+
+  // D-01: recreate the symlink immediately on this host
+  ensureSymlink(linkPath, sharedTarget);
+
+  // D-02: targeted stage of shared/<name> only; never git add -A
+  const rel = join('shared', name);
+  gitOrFatal(['add', '--', rel], `git add shared/${name}`, REPO_HOME);
+
+  log(`adopted ${name}; ${ADOPT_PUSH_HINT}`);
+}
+
+/**
+ * Bring a pre-existing `~/.claude/<name>` directory into the nomad shared set.
+ *
+ * Validates `name`, enforces the precondition matrix, then performs:
+ * backup -> copy-into-shared -> remove-source -> recreate-symlink ->
+ * targeted `git add` -> print follow-up hint. Stops there: no auto-commit,
+ * no push pipeline (D-02).
+ *
+ * Accepts only already-configured names: a static SHARED_LINKS member or a
+ * `sharedDirs` entry already declared in `path-map.json`. adopt is a mover,
+ * not a config editor; it never writes `path-map.json` (D-03).
+ *
+ * `--dry-run` reports the planned actions and performs zero filesystem or
+ * git changes (D-00d, V-08).
+ *
+ * @param name The `~/.claude/<name>` directory to adopt.
+ * @param opts.dryRun When true, log planned actions and return without mutation.
+ */
+export function cmdAdopt(name: string, opts: { dryRun?: boolean } = {}): void {
+  const dryRun = opts.dryRun === true;
+
+  // D-00a: validate name format (rejects path separators, NEVER_SYNC, and arbitrary
+  // names that are not in SHARED_LINKS; SHARED_LINKS statics bypass isValidSharedDir
+  // because RESERVED_SHARED overlaps with SHARED_LINKS by design)
+  if (!isValidAdoptName(name)) {
+    fail(`invalid name: ${JSON.stringify(name)}`);
+    process.exit(1);
+  }
+
+  // D-03: confirm name is an already-configured shared target
+  const map = readMapIfPresent(REPO_HOME);
+  if (!isConfiguredTarget(name, map)) {
+    fail(
+      `${name}: not a configured shared target. ` +
+        `Add it to sharedDirs in path-map.json first, then re-run adopt.`,
+    );
+    process.exit(1);
+  }
+
+  const linkPath = join(CLAUDE_HOME, name);
+  const sharedTarget = join(REPO_HOME, 'shared', name);
+
+  // D-00b precondition checks -- in order: absent, already symlink, would clobber
+  if (!existsSync(linkPath)) {
+    log(`${name}: nothing to adopt (not present in ~/.claude/)`);
+    return;
+  }
+  if (lstatSync(linkPath).isSymbolicLink()) {
+    log(`${name}: already adopted (already a symlink)`);
+    return;
+  }
+  if (lexists(sharedTarget)) {
+    fail(`${name}: shared/${name} already exists; would clobber. Remove it first.`);
+    process.exit(1);
+  }
+
+  // D-00d: dry-run preview -- branch before any mutation
+  if (dryRun) {
+    const backupBase = join(HOME, '.cache', 'claude-nomad', 'backup');
+    const ts = freshBackupTs(backupBase);
+    log(`would backup: ${linkPath} -> backup/${ts}/${name}`);
+    log(`would move: ${linkPath} -> shared/${name}`);
+    log(`would stage: shared/${name}`);
+    return;
+  }
+
+  /* c8 ignore start -- catch is defensive: performAdoptMove only throws on a git/fs fault */
+  try {
+    performAdoptMove(name, linkPath, sharedTarget);
+  } catch (err) {
+    if (!(err instanceof NomadFatal)) throw err;
+    fail(err.message);
+    process.exitCode = 1;
+  }
+  /* c8 ignore stop */
+}

package/src/commands.doctor.checks.repo.ts

@@ -119,7 +119,10 @@ function classifySharedLink(name: string, p: string): { line: string; fail: bool
     return { line: `${red(failGlyph)} ${name}: could not stat (${String(code)})`, fail: true };
   }
   if (!stat.isSymbolicLink()) {
-    return { line: `${red(failGlyph)} ${name}: NOT a symlink (blocks sync)`, fail: true };
+    return {
+      line: `${red(failGlyph)} ${name}: NOT a symlink (blocks sync); run \`nomad adopt ${name}\` to fix`,
+      fail: true,
+    };
   }
   return classifySymlinkTarget(name, p);
 }

package/src/commands.redact.core.ts

@@ -3,25 +3,6 @@ import { join } from 'node:path';
 
 import { REPO_HOME } from './config.ts';
 
-/**
- * Replace every occurrence of a literal secret value in a raw line. Uses
- * split/join to avoid regex escaping and to replace all occurrences. Pure,
- * no I/O.
- *
- * The replacement token `[REDACTED:<ruleId>]` contains no JSON-special
- * characters, so the result remains valid JSON when the value sits inside a
- * JSON string token.
- *
- * @param line Raw JSONL line text.
- * @param match Literal secret value to replace (empty string is a no-op).
- * @param ruleId Gitleaks rule identifier included in the replacement token.
- * @returns Line with all occurrences of `match` replaced by `[REDACTED:<ruleId>]`.
- */
-export function redactValue(line: string, match: string, ruleId: string): string {
-  if (match === '') return line;
-  return line.split(match).join(`[REDACTED:${ruleId}]`);
-}
-
 /** Minimal finding shape consumed by `applyRedactions`. */
 export type RedactFinding = {
   StartLine: number;
@@ -29,25 +10,95 @@ export type RedactFinding = {
   RuleID: string;
 };
 
+/** A half-open byte interval `[start, end)` derived from a `Match` value. */
+type MatchInterval = {
+  start: number;
+  end: number;
+  ruleId: string;
+};
+
 /**
- * Apply all findings for one file in memory. Replaces each finding's `Match`
- * value globally across the whole content string (split/join, no column
- * arithmetic). To avoid a shorter secret being a substring of a longer one
- * causing a partial match, findings are sorted by `Match.length` descending so
- * the longer secret is replaced first. Findings with an empty `Match` are
- * silently skipped (a defensive guard: an empty match would otherwise inject
- * the token between every character). Pure, no I/O.
+ * Locate every occurrence of each finding's `Match` value in `content` using
+ * `indexOf`. Findings with an empty `Match` are skipped. Multiple
+ * non-overlapping occurrences of the same value are each recorded as a
+ * separate interval. Offsets are value-derived, not column-derived, so they
+ * are always correct regardless of gitleaks column alignment.
+ *
+ * @param content Full file content as a single string.
+ * @param findings Array of finding descriptors.
+ * @returns Array of `{start, end, ruleId}` intervals (unmerged, unsorted).
+ */
+export function collectMatchIntervals(
+  content: string,
+  findings: readonly RedactFinding[],
+): MatchInterval[] {
+  const intervals: MatchInterval[] = [];
+  for (const f of findings) {
+    const match = f.Match;
+    if (match === '') continue;
+    let from = 0;
+    let pos = content.indexOf(match, from);
+    while (pos !== -1) {
+      intervals.push({ start: pos, end: pos + match.length, ruleId: f.RuleID });
+      from = pos + match.length;
+      pos = content.indexOf(match, from);
+    }
+  }
+  return intervals;
+}
+
+/**
+ * Sort and merge a list of (possibly overlapping or adjacent) intervals into a
+ * minimal list of non-overlapping spans. Sort order is start ascending, then
+ * end descending so that a longer interval at the same start position wins its
+ * `ruleId`. Overlapping or adjacent intervals are folded into one span that
+ * extends to the maximum end seen, keeping the first span's `ruleId`.
+ *
+ * @param intervals Unmerged intervals from `collectMatchIntervals`.
+ * @returns Sorted, merged, non-overlapping intervals.
+ */
+export function mergeIntervals(intervals: MatchInterval[]): MatchInterval[] {
+  if (intervals.length === 0) return [];
+  const sorted = [...intervals].sort((a, b) => a.start - b.start || b.end - a.end);
+  let last = { ...sorted[0] };
+  const merged: MatchInterval[] = [last];
+  for (let i = 1; i < sorted.length; i++) {
+    const cur = sorted[i];
+    if (cur.start <= last.end) {
+      if (cur.end > last.end) last.end = cur.end;
+    } else {
+      last = { ...cur };
+      merged.push(last);
+    }
+  }
+  return merged;
+}
+
+/**
+ * Apply all findings for one file in memory. Collects every occurrence of each
+ * finding's `Match` value via `indexOf`, merges overlapping and adjacent spans
+ * into non-overlapping intervals, then replaces each interval right-to-left so
+ * earlier offsets remain valid. Findings with an empty `Match` are silently
+ * skipped. Returns `content` unchanged when there are no findings or no
+ * occurrences are found.
+ *
+ * The replacement token `[REDACTED:<ruleId>]` is byte-identical to the previous
+ * format. Right-to-left replacement guarantees that overlapping matches (e.g.
+ * two findings whose `Match` values share a middle span) are replaced by a
+ * single token covering the full union, leaving no fragment. Pure, no I/O.
  *
  * @param content Full file content as a single string.
  * @param findings Array of finding descriptors.
  * @returns Redacted file content.
  */
 export function applyRedactions(content: string, findings: readonly RedactFinding[]): string {
-  const sorted = [...findings].sort((a, b) => b.Match.length - a.Match.length);
+  const raw = collectMatchIntervals(content, findings);
+  if (raw.length === 0) return content;
+  const merged = mergeIntervals(raw);
   let result = content;
-  for (const f of sorted) {
-    if (f.Match === '') continue;
-    result = result.split(f.Match).join(`[REDACTED:${f.RuleID}]`);
+  for (let i = merged.length - 1; i >= 0; i--) {
+    const { start, end, ruleId } = merged[i];
+    result = result.slice(0, start) + `[REDACTED:${ruleId}]` + result.slice(end);
   }
   return result;
 }

package/src/commands.redact.ts

@@ -15,7 +15,6 @@ export {
   appendGitleaksIgnore,
   formatFingerprint,
   isRecentlyModified,
-  redactValue,
 } from './commands.redact.core.ts';
 
 /**

package/src/nomad.help.ts

@@ -61,6 +61,13 @@ export const DEFAULT_HELP = [
     'Unstage shared/projects/<logical>/<id>.jsonl from the staged tree (local ~/.claude/projects is never touched).',
   ),
   '',
+  row(
+    '  adopt <name>',
+    'Move a pre-existing ~/.claude/<name> dir into shared/<name>, recreate the',
+  ),
+  cont('symlink, and stage for push. <name> must be in SHARED_LINKS or sharedDirs.'),
+  row('       --dry-run', 'Preview backup, move, and git-add without writing.'),
+  '',
   row(
     '  redact <session-id>',
     'Rewrite the secret span in the local source transcript for a session,',

package/src/nomad.ts

@@ -15,6 +15,7 @@
  *   path-map.json            logical project name -> { host: localPath }
  */
 
+import { cmdAdopt } from './commands.adopt.ts';
 import { cmdDoctor } from './commands.doctor.ts';
 import { cmdDropSession } from './commands.drop-session.ts';
 import { cmdRedact } from './commands.redact.ts';
@@ -125,6 +126,24 @@ try {
       });
       break;
     }
+    case 'adopt': {
+      // Required positional <name>; optional --dry-run. Any other shape
+      // (missing name, leading-dash name, two positionals, unknown flag)
+      // is a usage error. Single <name> per invocation (D-04).
+      const name = process.argv[3];
+      const sub = process.argv[4];
+      if (
+        typeof name !== 'string' ||
+        name.length === 0 ||
+        name.startsWith('-') ||
+        (sub !== undefined && (sub !== '--dry-run' || process.argv.length !== 5))
+      ) {
+        console.error('usage: nomad adopt <name> [--dry-run]');
+        process.exit(1);
+      }
+      cmdAdopt(name, { dryRun: sub === '--dry-run' });
+      break;
+    }
     case 'doctor':
       // Sub-flags: `doctor --resume-cmd <session-id>` dispatches to the
       // read-only sidecar that prints `cd <abspath> && claude --resume <id>`;