claude-nomad 0.17.0

package/src/push-checks.ts

@@ -0,0 +1,170 @@
+/**
+ * Reusable helpers for push-boundary safety: gitlink walker, gitleaks
+ * presence probe, and rebase-before-push.
+ *
+ * The staged gitleaks scan lives in `./push-gitleaks.ts` so the
+ * session-aware FATAL builder has its own module under the 200-line cap.
+ * `gitleaksInstallHint` stays here because both `probeGitleaks`
+ * (top-of-flow) and `runGitleaksScan` (mid-flow) need the platform-aware
+ * install scaffold on ENOENT.
+ *
+ * All execFileSync-backed helpers use argv-array form with
+ * `stdio: ['ignore', 'pipe', 'pipe']` (no shell). Same shape as
+ * `gitStatusPorcelainZ` in src/utils.ts so the audit surface is uniform.
+ *
+ * Used by `cmdPush` for refuse-on-hit safety and by `cmdDoctor` for
+ * read-only diagnostics (doctor only consumes `findGitlinks` and
+ * `probeGitleaks`).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, type Dirent } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+import { REPO_HOME } from './config.ts';
+import { NomadFatal } from './utils.ts';
+
+/**
+ * Platform-aware "gitleaks not on PATH" hint, mirroring the scaffold
+ * `install.sh` prints during onboarding:
+ *   - macOS: `brew install gitleaks`.
+ *   - Linux: numbered steps (download arch-matched tarball, extract to
+ *            `~/.local/bin`, optional PATH note when the dir isn't on PATH).
+ *   - Other: just the release-page link.
+ * Evaluated at call time so the PATH-on-rc check reflects the runtime
+ * env, not the value at module load.
+ */
+export function gitleaksInstallHint(): string {
+  const head = 'gitleaks not on PATH (required for nomad push). Install:';
+  const plat = platform();
+  if (plat === 'darwin') {
+    return `${head}\n  brew install gitleaks`;
+  }
+  if (plat === 'linux') {
+    const archMap: Record<string, string> = { x64: 'x64', arm64: 'arm64', arm: 'armv7' };
+    const arch = archMap[process.arch];
+    const lines = [
+      head,
+      arch
+        ? `  1. Download the linux_${arch} tarball: https://github.com/gitleaks/gitleaks/releases`
+        : `  1. Download the linux artifact for arch=${process.arch}: https://github.com/gitleaks/gitleaks/releases`,
+      '  2. Install (replace TARBALL with the path to your download):',
+      '       mkdir -p ~/.local/bin',
+      '       tar -xzf TARBALL -C ~/.local/bin gitleaks',
+      '       chmod +x ~/.local/bin/gitleaks',
+      '       ~/.local/bin/gitleaks version   # verify',
+    ];
+    const localBin = `${homedir()}/.local/bin`;
+    const paths = (process.env.PATH ?? '').split(':');
+    if (!paths.includes(localBin)) {
+      lines.push(
+        '  3. ~/.local/bin is not on PATH; add to your shell rc:',
+        '       export PATH="$HOME/.local/bin:$PATH"',
+      );
+    }
+    return lines.join('\n');
+  }
+  return `${head}\n  See https://github.com/gitleaks/gitleaks/releases`;
+}
+
+/**
+ * Recursively find every entry whose basename is `.git` under `dir`. Returns
+ * absolute paths. Used by `cmdPush` (refuse-on-hit) and `cmdDoctor`
+ * (read-only diagnostic). Callers feed `REPO_HOME/shared/` only; the tool's
+ * own repo .git at `~/claude-nomad/.git/` is outside the walk root.
+ *
+ * Does NOT follow symlinks. `Dirent.isDirectory()` returns `false` for
+ * `S_IFLNK` entries even when the link target is a directory, so the
+ * recursion naturally short-circuits at any symlink. This is the
+ * load-bearing fix for a known hazard: `readdirSync` in recursive mode
+ * follows self-referential symlink cycles up to libuv's internal cap
+ * (empirically verified on Node 22.16: 82 entries at depth 83 before the
+ * cap fired). The hand-rolled walker below is cycle-safe by construction.
+ *
+ * Tolerates permission errors silently (returns whatever was collected before
+ * the error). Reports both file gitlinks (submodule pointer) and directory
+ * gitlinks (real nested repo); both push as gitlinks and both break clone.
+ */
+export function findGitlinks(dir: string): string[] {
+  const hits: string[] = [];
+  function walk(current: string): void {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = join(current, e.name);
+      if (e.name === '.git') {
+        hits.push(p);
+        continue;
+      }
+      if (e.isDirectory()) walk(p);
+    }
+  }
+  walk(dir);
+  return hits;
+}
+
+/**
+ * Probe for the gitleaks binary on PATH. Returns the trimmed `gitleaks
+ * version` stdout on success. Throws NomadFatal with the install hint on
+ * ENOENT; throws NomadFatal with the error message on any other failure.
+ * Used by `cmdPush` (top-of-flow probe) and `cmdDoctor` (read-only).
+ *
+ * Conditionally passes `--config <REPO_HOME>/.gitleaks.toml` when that file
+ * exists at call time. `gitleaks version` ignores the flag empirically on
+ * 8.30.1, so the wiring here is conservative: symmetric with
+ * `runGitleaksScan` and surfaces a malformed toml early if a future gitleaks
+ * version starts parsing the config on the `version` subcommand. When the
+ * toml is missing (e.g., fresh clone predating the allowlist) the flag is
+ * omitted entirely; behavior reverts silently to the default gitleaks ruleset.
+ */
+export function probeGitleaks(): string {
+  const tomlPath = join(REPO_HOME, '.gitleaks.toml');
+  const args: string[] = ['version'];
+  if (existsSync(tomlPath)) args.push('--config', tomlPath);
+  try {
+    return execFileSync('gitleaks', args, { stdio: ['ignore', 'pipe', 'pipe'] })
+      .toString()
+      .trim();
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'ENOENT') throw new NomadFatal(gitleaksInstallHint());
+    throw new NomadFatal(`gitleaks --version failed: ${e.message}`);
+  }
+}
+
+/**
+ * Run `git pull --rebase --autostash` in REPO_HOME before push.
+ * The `--autostash` absorbs dirty trees (in-progress path-map.json edits,
+ * host overrides) so users do not need to commit-or-stash first.
+ *
+ * On failure, forwards git's stderr so the user sees the actual reason
+ * (conflict, no-upstream, unreachable remote, auth failure, etc.), then
+ * throws NomadFatal.
+ *
+ * FATAL wording references `git rebase --continue` / `--abort` (not the
+ * stash list): when `--autostash` is in flight, the stashed work lives in
+ * `.git/rebase-merge/autostash` mid-conflict and is reapplied by
+ * `--continue` / `--abort` automatically. Pointing the user at the stash
+ * list would mislead them; the recovery commands are the actual fix.
+ *
+ * `cmdPull` may adopt the same helper in a future refactor.
+ */
+export function rebaseBeforePush(): void {
+  try {
+    execFileSync('git', ['pull', '--rebase', '--autostash'], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { stderr?: Buffer };
+    if (e.stderr) process.stderr.write(e.stderr);
+    throw new NomadFatal(
+      'rebase failed; if a conflict was reported, resolve it in ~/claude-nomad/ and run "git rebase --continue" (or "git rebase --abort" to give up). Re-run nomad push after resolution.',
+    );
+  }
+}

package/src/push-gitleaks.ts

@@ -0,0 +1,217 @@
+/**
+ * Owns the staged gitleaks scan invoked at the end of `cmdPush`.
+ *
+ * Lives in its own module (split from `push-checks.ts`) so the
+ * session-aware FATAL builder (gitleaks JSON parser + per-session message
+ * composer) has a clean home while keeping every file under the 200-line
+ * cap. `findGitlinks`, `probeGitleaks`, `gitleaksInstallHint`, and
+ * `rebaseBeforePush` stay in `push-checks.ts`.
+ *
+ * `gitleaksInstallHint` is imported from `./push-checks.ts` because the
+ * ENOENT branch surfaces the same platform-aware install scaffold whether
+ * the missing binary is detected by `probeGitleaks` (top-of-flow) or by
+ * this scan (defense-in-depth mid-flow).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { REPO_HOME } from './config.ts';
+import { gitleaksInstallHint } from './push-checks.ts';
+import { NomadFatal, nowTimestamp } from './utils.ts';
+
+/**
+ * Subset of gitleaks 8.x JSON report fields the parser consumes. The
+ * report is an array of objects (one per finding) emitted to the
+ * `--report-path` file; on clean scans the array is empty.
+ */
+export type Finding = {
+  RuleID: string;
+  File: string;
+  StartLine: number;
+  Match: string;
+  Fingerprint: string;
+};
+
+/**
+ * Captures the session id from a repo-relative POSIX path of the form
+ * `shared/projects/<logical>/<sid>.jsonl`. gitleaks emits forward-slash
+ * paths regardless of host OS, so the literal works cross-platform.
+ * Anchored at both ends + depth-4 segments by construction so deeper
+ * paths (e.g., `shared/projects/<logical>/subagents/<id>.jsonl`) fall
+ * through to the non-session `other` bucket.
+ */
+const SESSION_PATH = /^shared\/projects\/[^/]+\/([^/]+)\.jsonl$/;
+
+/**
+ * Legacy fallback FATAL emitted when no finding's File matches the session
+ * path pattern. Locked verbatim so existing tests covering the non-session
+ * path do not regress.
+ */
+const LEGACY_FATAL =
+  'gitleaks detected secrets; review staged changes with git diff --cached and unstage offending files before retry';
+
+/**
+ * Group findings by extracted session id, counting per RuleID, with
+ * non-session paths routed to the `other` bucket. Pure: no side effects,
+ * no environment reads.
+ */
+export function partitionFindings(findings: Finding[]): {
+  bySession: Map<string, Map<string, number>>;
+  other: Finding[];
+} {
+  const bySession = new Map<string, Map<string, number>>();
+  const other: Finding[] = [];
+  for (const f of findings) {
+    const m = SESSION_PATH.exec(f.File);
+    if (m === null) {
+      other.push(f);
+      continue;
+    }
+    const sid = m[1];
+    // Defensive type narrowing: the regex guarantees group 1 is captured
+    // when m !== null, so this branch is unreachable at runtime. Excluded
+    // from coverage rather than contorting tests to fake an impossible state.
+    /* c8 ignore next */
+    if (sid === undefined) continue;
+    let counts = bySession.get(sid);
+    if (counts === undefined) {
+      counts = new Map<string, number>();
+      bySession.set(sid, counts);
+    }
+    counts.set(f.RuleID, (counts.get(f.RuleID) ?? 0) + 1);
+  }
+  return { bySession, other };
+}
+
+/**
+ * Build the FATAL message body. Returns the legacy fallback string when
+ * `bySession` is empty (no session matches); otherwise composes the
+ * multi-section message: `gitleaks detected secrets in N session
+ * transcript(s).` header, one block per affected session with a
+ * `Recover with: nomad drop-session <id>` line, an optional `Also found:`
+ * block for non-session paths, and a trailing `After recovery, re-run
+ * nomad push.` line. Pure.
+ */
+export function buildSessionAwareFatal(
+  bySession: Map<string, Map<string, number>>,
+  other: Finding[],
+): string {
+  if (bySession.size === 0) return LEGACY_FATAL;
+  const lines: string[] = [];
+  lines.push(`gitleaks detected secrets in ${bySession.size} session transcript(s).`);
+  for (const [sid, counts] of bySession) {
+    const summary = [...counts.entries()].map(([rule, n]) => `${rule} (${n})`).join(', ');
+    lines.push('');
+    lines.push(`Session ${sid}:`);
+    lines.push(`  ${summary}`);
+    lines.push(`  Recover with: nomad drop-session ${sid}`);
+  }
+  if (other.length > 0) {
+    lines.push('');
+    lines.push('Also found:');
+    for (const f of other) {
+      lines.push(`  ${f.File}  ${f.RuleID}`);
+    }
+    lines.push('  Review with: git diff --cached, then unstage manually.');
+  }
+  lines.push('');
+  lines.push('After recovery, re-run nomad push.');
+  return lines.join('\n');
+}
+
+/**
+ * Read and parse the gitleaks JSON report at `reportPath`. Returns the
+ * findings array on success, or `null` when the file is missing or the
+ * JSON is malformed. Defense-in-depth: an unreadable/invalid report on
+ * the failure path must NOT cascade into a parse-error stack trace; the
+ * caller falls back to the legacy FATAL string in that case.
+ */
+function readGitleaksReport(reportPath: string): Finding[] | null {
+  try {
+    const raw = readFileSync(reportPath, 'utf8');
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return null;
+    return parsed as Finding[];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run gitleaks against the staged index, writing the JSON report to a
+ * collision-resistant path under `~/.cache/claude-nomad/`. On non-zero
+ * exit, forwards gitleaks' redacted stderr/stdout so the user sees which
+ * file is dirty, reads the JSON report, classifies findings into session
+ * vs non-session paths, and throws a session-aware NomadFatal whose
+ * message names every affected session id with a `nomad drop-session`
+ * recovery hint. Non-session-only findings fall back to the legacy FATAL
+ * string. The temp report file is removed via `finally` on both success
+ * and failure paths.
+ *
+ * Conditionally passes `--config <REPO_HOME>/.gitleaks.toml` when that file
+ * exists at call time. The allowlist suppresses
+ * structurally-distinguishable tool-output noise (Sonar issue keys,
+ * gitleaks fingerprints, npm audit JSON id-field hashes, coverage line-keys)
+ * without weakening real-secret detection. Missing toml = silent fallback
+ * to the default gitleaks ruleset (e.g., fresh clones pre-allowlist).
+ *
+ * ENOENT branch is defense-in-depth: the presence probe at the top of
+ * `cmdPush` should have caught a missing binary, but if `cmdPush` ever
+ * bypasses the probe (or the user uninstalls gitleaks mid-flow) the same
+ * install-hint FATAL fires here.
+ */
+export function runGitleaksScan(): void {
+  const cacheDir = join(homedir(), '.cache', 'claude-nomad');
+  mkdirSync(cacheDir, { recursive: true });
+  // Disambiguate with pid so the lockfile invariant (one concurrent push
+  // per host) is enough to keep the report path unique. The prior
+  // freshBackupTs() call checked for a sibling directory named exactly
+  // <ts>, which never collides with the file `gitleaks-<ts>.json` being
+  // written.
+  const reportPath = join(cacheDir, `gitleaks-${nowTimestamp()}-${process.pid}.json`);
+  const tomlPath = join(REPO_HOME, '.gitleaks.toml');
+  const args: string[] = [
+    'protect',
+    '--staged',
+    '--redact',
+    '-v',
+    '--report-format=json',
+    `--report-path=${reportPath}`,
+  ];
+  if (existsSync(tomlPath)) args.push('--config', tomlPath);
+  try {
+    execFileSync('gitleaks', args, {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & {
+      status?: number;
+      stderr?: Buffer;
+      stdout?: Buffer;
+    };
+    if (e.code === 'ENOENT') throw new NomadFatal(gitleaksInstallHint());
+    if (e.stderr) process.stderr.write(e.stderr);
+    if (e.stdout) process.stdout.write(e.stdout);
+    const findings = readGitleaksReport(reportPath);
+    if (findings === null) {
+      // gitleaks exited non-zero but no parseable JSON report exists at the
+      // expected path. Could be a scanner crash, a malformed report, a
+      // missing/locked file, or a non-finding runtime failure (gitleaks v8.x
+      // returns exit 1 for both "leaks found" and runtime errors). Tell the
+      // operator the scan itself failed so they do not chase a phantom
+      // `nomad drop-session` rabbit hole. The stderr/stdout already
+      // forwarded above carries the underlying gitleaks output.
+      throw new NomadFatal(
+        `gitleaks scan failed: no parseable JSON report at ${reportPath} (${e.message}). Review the gitleaks output above.`,
+      );
+    }
+    const { bySession, other } = partitionFindings(findings);
+    throw new NomadFatal(buildSessionAwareFatal(bySession, other));
+  } finally {
+    rmSync(reportPath, { force: true });
+  }
+}

package/src/remap.ts

@@ -0,0 +1,158 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+import { CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
+import { backupBeforeWrite, backupRepoWrite, encodePath, log, readJson } from './utils.ts';
+
+/**
+ * Recursive mirror copy: removes `dst` first, then copies `src` into it.
+ * `cpSync(force:true)` overwrites matching files but does not delete
+ * dst-only entries; the upfront `rmSync` makes the operation a true mirror
+ * so `dst` reflects `src` exactly rather than accumulating stale files.
+ */
+function copyDir(src: string, dst: string): void {
+  rmSync(dst, { recursive: true, force: true });
+  cpSync(src, dst, { recursive: true, force: true });
+}
+
+/**
+ * Push-side mirror copy: identical to copyDir except a depth-0 extension
+ * filter restricts to *.jsonl files only. Subdirectory contents (subagents,
+ * memory, tool-results, etc.) copy recursively with no further filtering.
+ * Stray .bak / .tmp / .swp / editor backups at the source root are skipped
+ * and produce one `ℹ︎ skip <rel>: extension not in allowlist` log
+ * line each. The filter must allow the source root explicitly (Pitfall 1:
+ * cpSync invokes the filter on src === src first, and a false return
+ * there would abort the whole copy). Used by remapPush only; remapPull
+ * keeps the unfiltered copyDir because the repo side is already curated
+ * by the push gate.
+ */
+function copyDirJsonlOnly(src: string, dst: string): void {
+  rmSync(dst, { recursive: true, force: true });
+  cpSync(src, dst, {
+    recursive: true,
+    force: true,
+    filter: (srcPath) => {
+      const rel = relative(src, srcPath);
+      if (rel === '') return true;
+      if (rel.split(sep).length > 1) return true;
+      if (statSync(srcPath).isDirectory()) return true;
+      if (srcPath.endsWith('.jsonl')) return true;
+      log(`skip ${rel}: extension not in allowlist`);
+      return false;
+    },
+  });
+}
+
+/**
+ * Pull: copy from repo's logical project names into local path-encoded dirs.
+ *
+ * Returns `{ unmapped: N }` where `N` counts path-map entries skipped for
+ * this host (either `'TBD'` placeholder or no entry for `HOST`). The count
+ * is consumed by `computePreview` and the future summary line.
+ *
+ * `opts.dryRun` (default `false`): when `true`, log `would overwrite:` lines
+ * instead of calling `backupBeforeWrite` + `copyDir`. The unmapped count is
+ * computed identically in both modes.
+ */
+export function remapPull(ts: string, opts: { dryRun?: boolean } = {}): { unmapped: number } {
+  const dryRun = opts.dryRun === true;
+  let unmapped = 0;
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  const repoProjects = join(REPO_HOME, 'shared', 'projects');
+  if (!existsSync(mapPath) || !existsSync(repoProjects)) {
+    log('no path-map or repo projects dir; skipping session remap');
+    return { unmapped: 0 };
+  }
+
+  const map = readJson<PathMap>(mapPath);
+  const localProjects = join(CLAUDE_HOME, 'projects');
+  if (!dryRun) mkdirSync(localProjects, { recursive: true });
+
+  for (const [logical, hosts] of Object.entries(map.projects)) {
+    const localPath = hosts[HOST];
+    if (localPath === 'TBD') {
+      unmapped++;
+      log(`skip ${logical}: placeholder path for ${HOST}`);
+      continue;
+    }
+    if (!localPath) {
+      unmapped++;
+      log(`skip ${logical}: no path for ${HOST}`);
+      continue;
+    }
+    const src = join(repoProjects, logical);
+    if (!existsSync(src)) continue;
+    const dst = join(localProjects, encodePath(localPath));
+    if (dryRun) {
+      log(`would overwrite: ${dst} (from ${src})`);
+      continue;
+    }
+    // Snapshot prior encoded-path-dir state BEFORE copyDir overwrites it.
+    backupBeforeWrite(dst, ts);
+    copyDir(src, dst);
+    log(`pulled ${logical} -> ${encodePath(localPath)}`);
+  }
+  return { unmapped };
+}
+
+/**
+ * Push: copy local path-encoded dirs back to repo under logical names.
+ *
+ * Returns `{ unmapped: N, collisions: M }` where `unmapped` is the count of
+ * `~/.claude/projects/<dir>/` entries that have no path-map reverse-lookup
+ * for this host. `collisions` is reserved for a future slice's path-encoding
+ * collision detection and is always `0` here.
+ *
+ * `opts.dryRun` (default `false`): when `true`, log `would push:` lines
+ * instead of calling `backupRepoWrite` + `copyDir`. Counts are computed
+ * identically in both modes.
+ */
+export function remapPush(
+  ts: string,
+  opts: { dryRun?: boolean } = {},
+): { unmapped: number; collisions: number } {
+  const dryRun = opts.dryRun === true;
+  let unmapped = 0;
+  const collisions = 0;
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  if (!existsSync(mapPath)) {
+    log('no path-map.json; skipping session export');
+    return { unmapped: 0, collisions: 0 };
+  }
+
+  const map = readJson<PathMap>(mapPath);
+  const localProjects = join(CLAUDE_HOME, 'projects');
+  const repoProjects = join(REPO_HOME, 'shared', 'projects');
+  if (!dryRun) mkdirSync(repoProjects, { recursive: true });
+
+  const reverse = new Map<string, string>();
+  for (const [logical, hosts] of Object.entries(map.projects)) {
+    const p = hosts[HOST];
+    if (!p || p === 'TBD') continue;
+    reverse.set(encodePath(p), logical);
+  }
+
+  if (!existsSync(localProjects)) return { unmapped, collisions };
+  for (const dir of readdirSync(localProjects)) {
+    const logical = reverse.get(dir);
+    if (!logical) {
+      unmapped++;
+      log(`skip ${dir}: not in path-map for ${HOST}`);
+      continue;
+    }
+    const repoDst = join(repoProjects, logical);
+    if (dryRun) {
+      log(`would push: ${dir} -> ${logical}`);
+      continue;
+    }
+    // Snapshot repo-side destination before copyDir clobbers it. Git
+    // history exists only AFTER the commit step, so a corrupt or
+    // path-encoding-collided local dir would otherwise have no rollback
+    // path. Symmetric with remapPull's backupBeforeWrite on the local dst.
+    backupRepoWrite(repoDst, ts, REPO_HOME);
+    copyDirJsonlOnly(join(localProjects, dir), repoDst);
+    log(`pushed ${dir} -> ${logical}`);
+  }
+  return { unmapped, collisions };
+}