claude-nomad 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [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.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/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/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>`;