claude-nomad 0.17.0

package/src/commands.drop-session.ts

@@ -0,0 +1,173 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { REPO_HOME } from './config.ts';
+import { acquireLock, die, fail, log, NomadFatal, releaseLock } from './utils.ts';
+
+/**
+ * Surgical removal of a contaminated session from the staged tree of
+ * `~/claude-nomad/`. Walks `shared/projects/<logical>/<id>.jsonl` at the
+ * top level only, classifies each match via `git ls-files --error-unmatch`,
+ * and unstages with the appropriate primitive:
+ *
+ *   - tracked-in-HEAD  -> `git restore --staged --worktree -- <rel>`
+ *   - newly-staged     -> `git rm --cached -f -- <rel>`
+ *
+ * Idempotent: files that are not in the index at all are skipped silently
+ * rather than treated as errors. Exits 0 on any drop, including an
+ * idempotent re-run that finds the matches already absent. Exits 1 with
+ * `✗ no staged session matches <id>` (red `✗` fail glyph) only when no
+ * `shared/projects/<logical>/<id>.jsonl` exists at all in the shared tree.
+ *
+ * Defense-in-depth: the id is validated against the same allowlist regex
+ * used in `src/resume.ts` before any path composition. argv-array form
+ * for every git invocation.
+ *
+ * NEVER touches `~/.claude/projects/<encoded>/<id>.jsonl`. The local file
+ * is preserved so it can race-safely coexist with active Claude Code
+ * writers; rotate-and-scrub of the local copy is the user's
+ * responsibility.
+ *
+ * @param id Session id (filename minus `.jsonl`). Must match `[A-Za-z0-9_-]+`
+ *           with length 1..128.
+ * @throws NomadFatal when a lower-level helper translates a git or
+ *         filesystem failure into a fatal. Caught by the try/catch wrapper
+ *         which routes it to stderr and sets `process.exitCode = 1`.
+ */
+export function cmdDropSession(id: string): void {
+  if (id.length === 0 || id.length > 128 || !/^[A-Za-z0-9_-]+$/.test(id)) {
+    fail(`invalid session id: ${id}`);
+    process.exit(1);
+  }
+  if (!existsSync(REPO_HOME)) die(`repo not cloned at ${REPO_HOME}`);
+
+  const handle = acquireLock('drop-session');
+  if (handle === null) process.exit(0);
+  try {
+    const repoProjects = join(REPO_HOME, 'shared', 'projects');
+    if (!existsSync(repoProjects)) {
+      throw new NomadFatal(`no staged session matches ${id}`);
+    }
+    // Top-level walk only: for each `shared/projects/<logical>/` child,
+    // check whether `<id>.jsonl` exists. No descent into
+    // subagents/memory/tool-results subdirectories.
+    const matches: string[] = [];
+    for (const logical of readdirSync(repoProjects)) {
+      const candidate = join(repoProjects, logical, `${id}.jsonl`);
+      if (existsSync(candidate)) {
+        matches.push(candidate);
+      }
+    }
+    if (matches.length === 0) {
+      throw new NomadFatal(`no staged session matches ${id}`);
+    }
+    for (const m of matches) {
+      const rel = relative(REPO_HOME, m);
+      // Pitfall 7: skip files that are not in the index at all (the
+      // load-bearing guard for the idempotent second-run case, where the
+      // first drop already removed the entry from the index but left the
+      // working tree file in place).
+      if (!isInIndex(rel)) {
+        log(`dropped ${rel} (already absent from index)`);
+        continue;
+      }
+      try {
+        if (isTrackedInHead(rel)) {
+          execFileSync('git', ['restore', '--staged', '--worktree', '--', rel], {
+            cwd: REPO_HOME,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        } else {
+          execFileSync('git', ['rm', '--cached', '-f', '--', rel], {
+            cwd: REPO_HOME,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        }
+      } catch (err) {
+        // Convert raw execFileSync failures (non-zero git exit, EACCES on
+        // .git/index, EPERM, etc.) into NomadFatal so the outer catch can
+        // emit a clean `✗ ...` line instead of letting the ExecException
+        // bubble past nomad.ts's NomadFatal-only dispatcher.
+        // The `?? err.message` fallback only fires when git fails without
+        // producing stderr (spawn-level error before the process emits
+        // anything), which `cmdPush`'s gitleaks probe already rules out
+        // for the typical install path. Excluded from coverage.
+        const e = err as NodeJS.ErrnoException & { stderr?: Buffer };
+        /* c8 ignore next */
+        const detail = e.stderr?.toString().trim() ?? e.message;
+        throw new NomadFatal(`git failed to unstage ${rel}: ${detail}`);
+      }
+      log(`dropped ${rel}`);
+    }
+  } catch (err) {
+    // Defensive escape hatch: only fires if a non-NomadFatal error escapes
+    // the try block. All execFileSync mutation failures are wrapped in
+    // NomadFatal above, file-system helpers swallow their own errors, and
+    // readdirSync only throws under a race we do not handle. Excluded from
+    // coverage rather than contorting tests to fake an impossible state.
+    /* c8 ignore next 3 */
+    if (!(err instanceof NomadFatal)) {
+      throw err;
+    }
+    // All NomadFatal paths surfaced here are exit-1 conditions (no staged
+    // session matches the id, git mutation failed, etc.); the red `✗`
+    // glyph carries the severity uniformly.
+    fail(err.message);
+    process.exitCode = 1;
+  } finally {
+    releaseLock(handle);
+  }
+}
+
+/**
+ * Is `rel` (repo-relative path) present in the HEAD tree? Wraps
+ * `git cat-file -e HEAD:<rel>`: exit 0 means tracked in HEAD,
+ * non-zero means either no HEAD exists yet (empty repo) or the path is
+ * only in the index (newly-staged-not-in-HEAD). `git ls-files
+ * --error-unmatch` is NOT a HEAD-presence check; it matches anything in
+ * the index too, which would misclassify newly-staged paths.
+ *
+ * The catch deliberately collapses three cases to `false`: (a) HEAD has
+ * no commit yet (fresh `git init`), (b) HEAD is unresolvable / corrupt
+ * (e.g., `.git/refs/heads/main` was deleted manually), and (c) the
+ * specific path simply does not exist in a valid HEAD. Git produces the
+ * same exit 128 and the same stderr (`fatal: invalid object name 'HEAD'`)
+ * for (a) and (b), so a probe-based distinction would require additional
+ * git-plumbing reads (`rev-parse --verify HEAD`, `.git/refs/heads/`
+ * inspection) that are brittle and break the empty-repo path every
+ * existing test runs through. The downstream `git rm --cached -f` is
+ * idempotent and produces the user-intended unstage outcome regardless
+ * of which case fired, so the collapsed return is intentional. Repo
+ * health belongs to `nomad doctor`, not drop-session.
+ */
+function isTrackedInHead(rel: string): boolean {
+  try {
+    execFileSync('git', ['cat-file', '-e', `HEAD:${rel}`], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Is `rel` present in the index at all? Wraps `git ls-files -- <rel>` and
+ * checks for non-empty stdout. Required for the Pitfall 7 idempotency
+ * guard: a second invocation on the same id finds the file on disk (per
+ * `existsSync`) but absent from the index, and must NOT call `git rm
+ * --cached` on it (which would fail with exit 128).
+ */
+function isInIndex(rel: string): boolean {
+  try {
+    const out = execFileSync('git', ['ls-files', '--', rel], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return out.toString().trim() !== '';
+  } catch {
+    return false;
+  }
+}

package/src/commands.pull.ts

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { HOME, HOST, REPO_HOME } from './config.ts';
+import { applySharedLinks, regenerateSettings } from './links.ts';
+import { computePreview } from './preview.ts';
+import { remapPull } from './remap.ts';
+import { emitSummary } from './summary.ts';
+// prettier-ignore
+import { acquireLock, die, fail, freshBackupTs, gitOrFatal, log, NomadFatal, releaseLock } from './utils.ts';
+
+/**
+ * `nomad pull` command. Acquires the push/pull lock, takes a backup
+ * timestamp, runs `git pull --rebase --autostash` in `REPO_HOME`, then
+ * applies the three side-effecting sync steps in order:
+ *   1. `applySharedLinks` (symlink shared/* into ~/.claude/)
+ *   2. `regenerateSettings` (deep-merge base + host-override into settings.json)
+ *   3. `remapPull` (copy repo-side session transcripts into host-encoded dirs)
+ *
+ * `opts.dryRun` (default `false`): when `true`, the lock IS still acquired
+ * and `git pull --rebase` still runs (so concurrent invocations cannot race
+ * and so the user sees the same network round-trip behavior they would on a
+ * real pull). Then `computePreview` runs in place of the three mutating
+ * steps. The per-run backup directory under
+ * `~/.cache/claude-nomad/backup/<ts>/` is intentionally NOT created (no
+ * backups are written under dryRun and an empty dir would pollute the cache).
+ *
+ * Any `NomadFatal` thrown along the way is caught here so the `finally` block
+ * releases the lock before exit (a raw `process.exit()` would skip `finally`
+ * and leak the lock, see `NomadFatal` JSDoc). Non-fatal errors rethrow.
+ */
+export function cmdPull(opts: { dryRun?: boolean } = {}): void {
+  const dryRun = opts.dryRun === true;
+  if (!existsSync(REPO_HOME)) die(`repo not cloned at ${REPO_HOME}`);
+  // Fire the init-hint FATAL BEFORE acquireLock so an
+  // unscaffolded repo never creates a lock file. Keyed off the same signal
+  // regenerateSettings uses (shared/settings.base.json), so the two entry
+  // points share one phrasing instead of diverging on edits.
+  if (!existsSync(join(REPO_HOME, 'shared', 'settings.base.json'))) {
+    die("repo not initialized; run 'nomad init' to scaffold");
+  }
+  const handle = acquireLock('pull');
+  if (handle === null) process.exit(0);
+  try {
+    // Collision-resistant ts: nowTimestamp() is second-resolution, so two
+    // pulls in the same wall-clock second would share `ts` and the second's
+    // backupBeforeWrite calls (cpSync force:false) would silently no-op.
+    const backupBase = join(HOME, '.cache', 'claude-nomad', 'backup');
+    const ts = freshBackupTs(backupBase);
+    if (!dryRun) {
+      // Fail-fast: create backup root BEFORE any mutation. If mkdir fails
+      // (out of disk, permission denied), die() throws (NomadFatal) and the
+      // outer catch logs + sets exitCode, then finally releases the lock.
+      // Skipped under dryRun: no backups are written, and an empty
+      // backup-root dir would pollute the cache.
+      const backupRoot = join(backupBase, ts);
+      try {
+        mkdirSync(backupRoot, { recursive: true });
+      } catch (err) {
+        die(`could not create backup dir: ${(err as Error).message}`);
+      }
+    }
+    log(`pulling on host=${HOST} (backup=${ts}${dryRun ? '; dry-run' : ''})`);
+    gitOrFatal(['pull', '--rebase', '--autostash'], 'git pull --rebase', REPO_HOME);
+    if (dryRun) {
+      const previewResult = computePreview(ts);
+      log('dry-run complete; no mutation');
+      emitSummary('pull', previewResult.unmapped);
+    } else {
+      applySharedLinks(ts);
+      regenerateSettings(ts);
+      const remapResult = remapPull(ts);
+      log('pull complete');
+      emitSummary('pull', remapResult.unmapped);
+    }
+  } catch (err) {
+    // Catch fatal errors here so the finally block runs and releases the
+    // lock. Throwing through process.exit() would skip finally.
+    if (err instanceof NomadFatal) {
+      fail(err.message);
+      process.exitCode = 1;
+    } else {
+      throw err;
+    }
+  } finally {
+    releaseLock(handle);
+  }
+}

package/src/commands.push.ts

@@ -0,0 +1,215 @@
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+// prettier-ignore
+import { HOME, HOST, NEVER_SYNC, PUSH_ALLOWED_STATIC, REPO_HOME, type PathMap } from './config.ts';
+import { findGitlinks, probeGitleaks, rebaseBeforePush } from './push-checks.ts';
+import { runGitleaksScan } from './push-gitleaks.ts';
+import { remapPush } from './remap.ts';
+import { emitSummary } from './summary.ts';
+// prettier-ignore
+import { acquireLock, die, fail, freshBackupTs, gitOrFatal, gitStatusPorcelainZ, log, NomadFatal, readJson, releaseLock } from './utils.ts';
+
+/**
+ * Match `path` against an entry in the push allow-list. Exact match for
+ * non-`/`-terminated entries; prefix match for `/`-terminated entries; and
+ * a special case for `hosts/`: only `hosts/<name>.json` (single-level,
+ * `.json` extension) is allowed, so arbitrary credentials like
+ * `hosts/dell-wsl.key` are rejected even though they share the prefix.
+ */
+function isAllowed(path: string, allowed: readonly string[]): boolean {
+  for (const entry of allowed) {
+    if (path === entry) return true;
+    if (entry === 'hosts/') {
+      if (/^hosts\/[^/]+\.json$/.test(path)) return true;
+      continue;
+    }
+    if (entry.endsWith('/') && path.startsWith(entry)) return true;
+  }
+  return false;
+}
+
+/** True when any path segment matches a `NEVER_SYNC` entry (hard-block list). */
+function isNeverSync(path: string): boolean {
+  for (const segment of path.split('/')) {
+    if (NEVER_SYNC.has(segment)) return true;
+  }
+  return false;
+}
+
+/**
+ * Parse `git status --porcelain=v1 -z` (NUL-delimited) output into a flat
+ * list of paths. Handles rename (`R`) and copy (`C`) records, which span
+ * two NUL fields (`XY new\0old\0`): both halves are returned so the
+ * allow-list can reject either side. `-z` avoids the quoting that LF
+ * porcelain applies to paths containing spaces or specials, which would
+ * otherwise cause parser misclassification.
+ */
+export function parsePorcelainZ(statusPorcelain: string): string[] {
+  const records = statusPorcelain.split('\0');
+  const paths: string[] = [];
+  for (let i = 0; i < records.length; i++) {
+    const rec = records[i];
+    if (rec === undefined || rec === '') continue;
+    // Each record starts with "XY " (2 status chars + 1 space). The path is
+    // everything after byte 3. For R/C the NEXT record holds the old path.
+    if (rec.length < 4) continue;
+    const xy = rec.slice(0, 2);
+    const newPath = rec.slice(3);
+    paths.push(newPath);
+    // Check BOTH XY positions: X is the index status, Y is the working-tree
+    // status. Either can carry R (rename) or C (copy), and the old-path record
+    // follows the new-path record in -z porcelain regardless of which column
+    // detected the rename. Missing the Y-column case (e.g. ` R`) would skip
+    // the consume and let the next iteration misread the old path as a new
+    // record, smuggling unallowed sources past the allow-list.
+    if (/[RC]/.test(xy)) {
+      const oldPath = records[i + 1];
+      if (oldPath !== undefined && oldPath !== '') paths.push(oldPath);
+      i++; // consume the paired old-path record
+    }
+  }
+  return paths;
+}
+
+/**
+ * Reject any staged path that is not on the push allow-list or that matches a
+ * `NEVER_SYNC` entry. Builds the runtime allow-list by combining
+ * `PUSH_ALLOWED_STATIC` with one `shared/projects/<logical>/` prefix per entry
+ * in `path-map.json`. Logs every violation as a FATAL line so the user sees
+ * the full set (not just the first), then throws `NomadFatal` to unwind the
+ * caller's try/finally and release the push lock.
+ */
+export function enforceAllowList(statusPorcelain: string, map: PathMap): void {
+  const allowed = [
+    ...PUSH_ALLOWED_STATIC,
+    ...Object.keys(map.projects).map((l) => `shared/projects/${l}/`),
+  ];
+  const neverSyncHits: string[] = [];
+  const violations: string[] = [];
+  for (const path of parsePorcelainZ(statusPorcelain)) {
+    if (isNeverSync(path)) {
+      neverSyncHits.push(path);
+    } else if (!isAllowed(path, allowed)) {
+      violations.push(path);
+    }
+  }
+  if (neverSyncHits.length === 0 && violations.length === 0) return;
+  for (const p of neverSyncHits) {
+    fail(`${p} is in NEVER_SYNC and must never be pushed`);
+  }
+  for (const p of violations) {
+    fail(`to sync ${p}, add to PUSH_ALLOWED in src/config.ts`);
+  }
+  throw new NomadFatal('push allow-list violations');
+}
+
+/**
+ * `nomad push` command. Acquires the lock, runs the four pre-push safety
+ * checks in the order from CONTEXT.md, stages, and pushes:
+ *   1. `probeGitleaks` (fail fast if the secret scanner isn't on PATH)
+ *   2. `rebaseBeforePush` (surface remote conflicts against committed state,
+ *      not against in-flight `remapPush` copies)
+ *   3. `remapPush` (copy host-encoded session dirs into shared logical names)
+ *   4. `findGitlinks` walk of `shared/` (refuse to push nested .git entries;
+ *      runs AFTER `remapPush` so it catches .git dirs copied in from the host)
+ *   5. allow-list enforcement on the resulting `git status` (refuse any path
+ *      not on `PUSH_ALLOWED_STATIC` or matching `NEVER_SYNC`)
+ *   6. `git add -A` -> `runGitleaksScan` on staged tree -> `git commit` -> `git push`
+ *
+ * The gitleaks scan runs AFTER staging so it sees what would actually be
+ * pushed, but BEFORE commit so a detection unwinds cleanly without leaving a
+ * commit to amend or revert. Any `NomadFatal` is caught here so `finally`
+ * releases the lock.
+ *
+ * `opts.dryRun` (default `false`): when `true`, the network round-trip
+ * (`rebaseBeforePush`) still runs so users see what a real push would see,
+ * but `remapPush` runs with `dryRun: true` (no session copies into shared/),
+ * and the `git add` / `runGitleaksScan` / `git commit` / `git push` quartet
+ * is skipped. The allow-list check still classifies the existing `git
+ * status` so a pre-existing violation surfaces before the user thinks
+ * everything is fine. Mirrors `cmdPull`'s `dryRun` contract.
+ */
+export function cmdPush(opts: { dryRun?: boolean } = {}): void {
+  const dryRun = opts.dryRun === true;
+  if (!existsSync(REPO_HOME)) die(`repo not cloned at ${REPO_HOME}`);
+  const handle = acquireLock('push');
+  if (handle === null) process.exit(0);
+  try {
+    log(dryRun ? `pushing on host=${HOST} (dry-run)` : `pushing on host=${HOST}`);
+    // Probe at top of flow: fail fast if gitleaks is missing, before any mutation.
+    probeGitleaks();
+    // Rebase BEFORE any local mutation: surfaces remote conflicts against the
+    // user's committed state, not against in-flight remapPush copies. Runs
+    // under dryRun too so the network round-trip mirrors a real push.
+    rebaseBeforePush();
+    // Collision-resistant ts for remapPush's pre-copy snapshot of repo-side state.
+    const backupBase = join(HOME, '.cache', 'claude-nomad', 'backup');
+    const ts = freshBackupTs(backupBase);
+    // remapPush runs BEFORE the empty-status check: it produces the diffs status
+    // observes, so swapping the order would short-circuit before anything is staged.
+    const remapResult = remapPush(ts, { dryRun });
+    // Gitlink walk of shared/ AFTER remapPush so it inspects the post-copy tree.
+    // A nested .git copied in from a host's encoded session dir would slip past a
+    // pre-remap scan and reach the remote via the shared/projects/<logical>/ prefix.
+    // Per-hit FATAL on stderr plus a summarizing throw, mirroring enforceAllowList.
+    const sharedDir = join(REPO_HOME, 'shared');
+    const gitlinks = findGitlinks(sharedDir);
+    if (gitlinks.length > 0) {
+      for (const p of gitlinks) {
+        const rel = relative(REPO_HOME, p);
+        fail(
+          `gitlink: ${rel} would push as submodule (run: rm -rf ${rel} or remove the nested repo)`,
+        );
+      }
+      throw new NomadFatal(
+        `gitlink trap: ${gitlinks.length} nested .git ${gitlinks.length === 1 ? 'entry' : 'entries'} in shared/; remove before retry`,
+      );
+    }
+    // Routed through the shell-free, untrimmed helper because `sh` would .trim()
+    // the leading status-space and shift parsePorcelainZ's offsets.
+    const status = gitStatusPorcelainZ(REPO_HOME);
+    if (!status) {
+      log('nothing to commit');
+      emitSummary('push', remapResult.unmapped, remapResult.collisions);
+      return;
+    }
+    const mapPath = join(REPO_HOME, 'path-map.json');
+    if (!existsSync(mapPath)) die('path-map.json missing, cannot enforce push allow-list');
+    // Route a malformed path-map.json through NomadFatal so finally releases the lock.
+    let map: PathMap;
+    try {
+      map = readJson<PathMap>(mapPath);
+    } catch (err) {
+      throw new NomadFatal(`could not parse path-map.json: ${(err as Error).message}`);
+    }
+    enforceAllowList(status, map);
+    if (dryRun) {
+      // Skip the staging quartet so no commit lands and nothing is pushed.
+      // The user has already seen probeGitleaks pass, the rebase result, the
+      // remap preview, the gitlink scan, and the allow-list classification.
+      log('push: dry-run; skipping git add, gitleaks scan, commit, and push');
+      emitSummary('push', remapResult.unmapped, remapResult.collisions);
+      return;
+    }
+    // gitOrFatal uses execFileSync (no shell) so NOMAD_HOST cannot escape quoting.
+    gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
+    // Gitleaks scan AFTER staging (sees what would push), BEFORE commit (no cleanup
+    // needed on detection). The empty-status early return above guarantees the
+    // index is non-empty here.
+    runGitleaksScan();
+    gitOrFatal(['commit', '-m', `chore: sync from ${HOST}`], 'git commit', REPO_HOME);
+    gitOrFatal(['push'], 'git push', REPO_HOME);
+    log('push complete');
+    emitSummary('push', remapResult.unmapped, remapResult.collisions);
+  } catch (err) {
+    if (err instanceof NomadFatal) {
+      fail(err.message);
+      process.exitCode = 1;
+    } else {
+      throw err;
+    }
+  } finally {
+    releaseLock(handle);
+  }
+}