claude-nomad 0.30.0 → 0.32.0

package/src/commands.push.recovery.redact.ts

@@ -0,0 +1,113 @@
+/**
+ * The Redact action for the push-time recovery menu. `applyRedact` resolves a
+ * finding's local transcript, refuses live sessions, re-scans the local file
+ * WITHOUT `--redact` to recover real secret values, rewrites it in place, and
+ * copies the cleaned file back to the staged tree.
+ *
+ * Split from `commands.push.recovery.actions.ts` to keep both modules under the
+ * ~220-line cap. Depends only on lower-level helpers (no import of the actions
+ * module), so the dependency direction stays acyclic: actions -> redact.
+ */
+
+import { cpSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
+
+import type { PathMap } from './config.ts';
+import { CLAUDE_HOME, HOST, REPO_HOME } from './config.ts';
+import { applyRedactions, isRecentlyModified, resolveLiveTranscript } from './commands.redact.ts';
+import type { Finding } from './push-gitleaks.scan.ts';
+import { scanFile } from './push-gitleaks.scan.ts';
+import { backupBeforeWrite } from './utils.fs.ts';
+import { encodePath } from './utils.json.ts';
+import { log } from './utils.ts';
+import { sessionIdFromFinding } from './commands.push.recovery.seams.ts';
+
+/**
+ * Apply the Redact action for one finding. Resolves the local transcript,
+ * checks the live-session guard, re-scans the local file (without `--redact`)
+ * to obtain real secret values, backs up, rewrites in place (same inode), and
+ * surgically copies the file back to the staged tree. Returns true on success,
+ * false when the session is active, unresolvable, or the local re-scan fails.
+ *
+ * The push-verdict findings (`f`, `allFindings`) drive which sessions to act on
+ * and provide session-id extraction, but their `Match` fields come from a
+ * `--redact` scan and are masked. The local re-scan (via `scan`) runs WITHOUT
+ * `--redact` so `applyRedactions` receives the real secret values.
+ *
+ * @param f Trigger finding (used for session-id extraction).
+ * @param allFindings Full finding set for this run (used for session-id
+ *   matching; values are masked and not used for redaction).
+ * @param ts Backup timestamp for `backupBeforeWrite`.
+ * @param map Parsed path-map for staged-tree path resolution.
+ * @param nowMs Injectable clock for the live-session mtime check.
+ * @param scan Injectable scan function for local re-scan (default: `scanFile`).
+ * @returns True when the redaction was applied; false when refused or failed.
+ */
+export function applyRedact(
+  f: Finding,
+  allFindings: Finding[],
+  ts: string,
+  map: PathMap,
+  nowMs: () => number,
+  scan: (p: string) => Finding[] | null = scanFile,
+): boolean {
+  /** Emit a refusal message and return false. */
+  const refuse = (msg: string): false => {
+    log(msg);
+    return false;
+  };
+
+  const sid = sessionIdFromFinding(f);
+  if (sid === null) {
+    return refuse(
+      `could not locate the local transcript for this finding; choose Skip or Drop session.`,
+    );
+  }
+  const localPath = resolveLiveTranscript(sid);
+  if (localPath === null) {
+    return refuse(
+      `could not locate the local transcript for session ${sid}; choose Skip or Drop session.`,
+    );
+  }
+  if (isRecentlyModified(statSync(localPath).mtimeMs, nowMs())) {
+    return refuse(
+      `session ${sid} looks active (modified within the last 5 minutes); refusing to redact, no changes made.\n` +
+        `  End the session and choose Redact again, or choose Drop session (holds this session back` +
+        ` from the push, local copy kept) or Skip.`,
+    );
+  }
+
+  // Re-scan without --redact to get real secret values for value-based redaction.
+  // Push-verdict findings have masked Match fields and cannot be used directly.
+  const realFindings = scan(localPath);
+  if (realFindings === null) {
+    return refuse(`re-scan of the transcript failed; choose Skip or Drop session.`);
+  }
+  if (realFindings.length === 0) {
+    return refuse(
+      `nothing to redact in the local transcript for session ${sid}; choose Skip or Drop session.`,
+    );
+  }
+
+  backupBeforeWrite(localPath, ts);
+  writeFileSync(localPath, applyRedactions(readFileSync(localPath, 'utf8'), realFindings), 'utf8');
+
+  let copied = false;
+  for (const [logical, hostMap] of Object.entries(map.projects)) {
+    const abs = hostMap[HOST];
+    if (abs === undefined) continue;
+    if (localPath.startsWith(join(CLAUDE_HOME, 'projects', encodePath(abs)) + sep)) {
+      cpSync(localPath, join(REPO_HOME, 'shared', 'projects', logical, `${sid}.jsonl`), {
+        force: true,
+      });
+      copied = true;
+      break;
+    }
+  }
+  if (!copied) {
+    return refuse(
+      `could not map the local transcript for session ${sid} to a staged copy; choose Drop session or Skip.`,
+    );
+  }
+  return true;
+}

package/src/commands.push.recovery.seams.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure, side-effect-free seams for the push-time recovery menu: key
+ * derivation, session-id extraction, and prompt-answer parsing. Extracted from
+ * `commands.push.recovery.actions.ts` so both modules stay under the 220-line
+ * advisory cap.
+ */
+
+import type { Finding } from './push-gitleaks.scan.ts';
+import { SESSION_PATH } from './push-gitleaks.ts';
+
+/** Action a user can assign to one finding in the recovery menu. */
+export type FindingAction = 'redact' | 'allow' | 'drop' | 'skip';
+
+/** Prompt function: asks one question and returns the answer. */
+export type PromptFn = (prompt: string) => Promise<string>;
+
+/**
+ * Build a stable key for a finding used as the actions-map key. Includes the
+ * rule id so two findings at the same file/line/column but different rules
+ * produce distinct keys and do not collide in the actions map.
+ *
+ * @param f The gitleaks finding.
+ * @returns A colon-delimited key combining file, start line, start column, and rule id.
+ */
+export function findingKey(f: Finding): string {
+  return `${f.File}:${f.StartLine}:${f.StartColumn}:${f.RuleID}`;
+}
+
+/** Valid session id charset: alphanumeric, hyphen, underscore (same as cmdDropSession/cmdRedact). */
+const VALID_SID = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Extract the session id from a finding's File path. Handles both the flat
+ * `shared/projects/<logical>/<sid>.jsonl` form (SESSION_PATH) and the deeper
+ * subagent form `shared/projects/<logical>/<sid>/...`. The extracted id is
+ * validated against `/^[A-Za-z0-9_-]+$/` before being returned; path-traversal
+ * segments (e.g. `..`) are rejected and cause a null return.
+ *
+ * @param f The gitleaks finding.
+ * @returns The session id, or null when the path matches neither pattern or the
+ *   extracted id contains characters outside `[A-Za-z0-9_-]`.
+ */
+export function sessionIdFromFinding(f: Finding): string | null {
+  // Try the flat `<sid>.jsonl` form first, then the deeper subagent form. Both
+  // patterns capture the session id at group 1; a matched capture group is
+  // always a string, so no nullish guard on `m[1]` is needed.
+  const m = SESSION_PATH.exec(f.File) ?? /^shared\/projects\/[^/]+\/([^/]+)\//.exec(f.File);
+  if (m === null) return null;
+  const sid = m[1];
+  return VALID_SID.test(sid) ? sid : null;
+}
+
+/**
+ * Parse a raw prompt answer into a `FindingAction`. Returns `'skip'` for
+ * empty, blank, or unrecognized input (D-02 default).
+ *
+ * @param raw The untrimmed string returned by the prompt.
+ * @returns The corresponding action, defaulting to `'skip'`.
+ */
+export function parseAction(raw: string): FindingAction {
+  const t = raw.trim().toLowerCase();
+  if (t === 'r' || t === 'redact') return 'redact';
+  if (t === 'a' || t === 'allow') return 'allow';
+  if (t === 'd' || t === 'drop') return 'drop';
+  return 'skip';
+}

package/src/commands.push.recovery.ts

@@ -0,0 +1,198 @@
+/**
+ * Push-time interactive recovery menu for gitleaks findings. When `nomad push`
+ * detects secrets in the staged tree and the process is running on a real TTY,
+ * `resolveLeakFindings` presents a per-finding Redact / Allow / Drop / Skip
+ * menu (default Skip), applies each resolved action, then re-stages and
+ * re-scans. The push proceeds only when zero findings remain unresolved.
+ *
+ * Non-TTY contexts (CI, piped input) keep the existing `buildSessionAwareFatal`
+ * abort unchanged: the function throws a `NomadFatal` carrying the existing
+ * recovery body verbatim (D-01: zero CI behavior change).
+ *
+ * `--redact-all` bypasses the prompt and redacts every real finding in batch
+ * without requiring a TTY.
+ *
+ * Action helpers and per-finding dispatch live in
+ * `commands.push.recovery.actions.ts` to keep both modules under the 220-line
+ * advisory cap.
+ */
+
+import { createInterface } from 'node:readline/promises';
+
+import type { PathMap } from './config.ts';
+import { REPO_HOME } from './config.ts';
+import {
+  type FindingAction,
+  type PromptFn,
+  collectActions,
+  dispatchActions,
+  findingKey,
+  redactAllFindings,
+} from './commands.push.recovery.actions.ts';
+import type { Finding } from './push-gitleaks.scan.ts';
+import { scanFile } from './push-gitleaks.scan.ts';
+import { buildSessionAwareFatal, partitionFindings } from './push-gitleaks.ts';
+import type { LeakVerdict } from './push-leak-verdict.ts';
+import { NomadFatal, gitOrFatal } from './utils.ts';
+
+export type { FindingAction };
+
+/**
+ * Dependency injection object for `resolveLeakFindings`. Provides seams for
+ * the prompt loop, the re-scan, the clock, and the TTY check so tests can
+ * drive the interactive flow without a real terminal.
+ */
+export type RecoveryDeps = {
+  /** Override TTY detection (default: `isTTY()`). */
+  isTTYCheck?: () => boolean;
+  /** Override `scanPushVerdict` for the post-action re-scan. */
+  scanVerdict?: () => LeakVerdict;
+  /** Injectable clock for live-session detection (default: `Date.now`). */
+  nowMs?: () => number;
+  /** When true, redact all findings without prompting; no TTY required. */
+  redactAll?: boolean;
+  /** Injectable prompt factory for tests (default: real readline). */
+  makePrompt?: () => PromptFn;
+  /** Injectable single-file scan for redaction (default: `scanFile`). */
+  scan?: (p: string) => Finding[] | null;
+  /** Injectable legend printer for tests (default: `printRecoveryLegend`). */
+  printLegend?: () => void;
+};
+
+/**
+ * True when both stdin and stdout are interactive TTYs. Accepts injectable
+ * stream objects so tests can drive the branch without a real TTY.
+ *
+ * @param stdin Readable with optional `isTTY` flag (default: `process.stdin`).
+ * @param stdout Writable with optional `isTTY` flag (default: `process.stdout`).
+ * @returns True iff both streams report `isTTY === true`.
+ */
+export function isTTY(
+  stdin: { isTTY?: boolean } = process.stdin,
+  stdout: { isTTY?: boolean } = process.stdout,
+): boolean {
+  return stdin.isTTY === true && stdout.isTTY === true;
+}
+
+/**
+ * True when any value in the actions map is `'skip'`, meaning at least one
+ * finding was left unresolved. Pure, no I/O.
+ *
+ * @param actions Per-finding action map keyed by `findingKey`.
+ * @returns True when at least one action is `'skip'`.
+ */
+export function hasUnresolved(actions: Map<string, FindingAction>): boolean {
+  for (const action of actions.values()) {
+    if (action === 'skip') return true;
+  }
+  return false;
+}
+
+/**
+ * Print a one-time action legend to stdout before the interactive menu loop.
+ * Called exactly once on the TTY path; never called on non-TTY or --redact-all.
+ *
+ * @param print Output sink (default: `console.log`). Injectable for tests.
+ */
+export function printRecoveryLegend(print: (line: string) => void = console.log): void {
+  print('');
+  print('Recovery actions:');
+  print('  Redact       - scrub the secret from the local transcript, push the cleaned copy');
+  print('  Allow        - mark as false positive (adds a .gitleaksignore fingerprint), push as-is');
+  print('  Drop session - exclude this session from this push (local transcript kept, running');
+  print('                 session is not stopped)');
+  print('  Skip         - leave unresolved (the push aborts)');
+  print('');
+}
+
+/** Build the real-TTY readline-based prompt function (one interface per call). */
+function makeRealPrompt(): PromptFn {
+  return async (prompt: string) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true,
+    });
+    try {
+      return await rl.question(prompt);
+    } finally {
+      rl.close();
+    }
+  };
+}
+
+/**
+ * Resolve the gitleaks findings from `verdict` interactively (TTY path) or
+ * via `--redact-all` (non-interactive batch path). On a non-TTY context with
+ * no `--redact-all` flag, throws `NomadFatal` carrying the existing recovery
+ * body verbatim (D-01: zero CI behavior change).
+ *
+ * TTY flow (D-02, D-03): prompts once per finding with R/A/D/S (default Skip
+ * on empty input), collects all actions, dispatches them, then re-stages via
+ * `git add -A` and re-scans. If the re-scan still has findings the menu loops
+ * on the new set. If any finding remains Skipped after triage, throws the
+ * session-aware FATAL so the push aborts with the same non-zero exit.
+ *
+ * @param verdict The current leak verdict from `scanPushVerdict`.
+ * @param ts Backup timestamp created at the start of this push run.
+ * @param map Parsed `path-map.json` for session path resolution.
+ * @param deps Optional dependency overrides for testing.
+ * @returns The final clean `LeakVerdict` after all findings are resolved.
+ */
+export async function resolveLeakFindings(
+  verdict: LeakVerdict,
+  ts: string,
+  map: PathMap,
+  deps: RecoveryDeps = {},
+): Promise<LeakVerdict> {
+  const {
+    isTTYCheck = isTTY,
+    nowMs = Date.now,
+    redactAll = false,
+    makePrompt: makePromptFn = makeRealPrompt,
+    scan = scanFile,
+    printLegend = printRecoveryLegend,
+  } = deps;
+
+  const scanVerdict = deps.scanVerdict ?? (await import('./push-leak-verdict.ts')).scanPushVerdict;
+
+  let current = verdict;
+
+  if (redactAll) {
+    redactAllFindings(current.findings, ts, map, nowMs, scan);
+    gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
+    const next = scanVerdict();
+    if (next.leak) {
+      const { bySession, other } = partitionFindings(next.findings);
+      throw new NomadFatal(buildSessionAwareFatal(bySession, other));
+    }
+    return next;
+  }
+
+  if (!isTTYCheck()) {
+    // Every leak:true verdict has a non-null recovery body. The fallback covers
+    // the defensive unreachable case (scan-crash with leak=true).
+    /* c8 ignore next */
+    throw new NomadFatal(current.recovery ?? 'gitleaks detected secrets');
+  }
+
+  const prompt = makePromptFn();
+  printLegend();
+
+  while (current.leak && current.findings.length > 0) {
+    const actions = await collectActions(current.findings, prompt);
+
+    if (hasUnresolved(actions)) {
+      // collectActions populates an entry for every finding, so `get` never
+      // returns undefined here; an explicit `=== 'skip'` needs no default.
+      const unresolved = current.findings.filter((f) => actions.get(findingKey(f)) === 'skip');
+      const { bySession, other } = partitionFindings(unresolved);
+      throw new NomadFatal(buildSessionAwareFatal(bySession, other));
+    }
+
+    dispatchActions(current.findings, actions, ts, map, nowMs, scan);
+    gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
+    current = scanVerdict();
+  }
+  return current;
+}

package/src/commands.push.ts

@@ -3,6 +3,7 @@ import { join, relative } from 'node:path';
 
 import { HOME, HOST, type PathMap, REPO_HOME } from './config.ts';
 import { enforceAllowList } from './commands.push.allowlist.ts';
+import { resolveLeakFindings } from './commands.push.recovery.ts';
 import { type PushState, renderNoScanTree, renderPushTree } from './commands.push.sections.ts';
 import { remapExtrasPush } from './extras-sync.ts';
 import { scanPushVerdict } from './push-leak-verdict.ts';
@@ -35,27 +36,27 @@ function guardGitlinks(): void {
 }
 
 /**
- * The staged-tree leak gate + commit/push for the REAL push path. Runs
- * `scanPushVerdict` AFTER `git add -A` (sees what would push) but BEFORE commit
- * (a detection unwinds cleanly with no commit to revert). On a leak it renders
- * the tree (with the ✗ Leak scan row + Summary) so the tree precedes the
- * recovery block, then throws the recovery body as a `NomadFatal` (the catch
- * prints it and sets a non-zero exit). On a clean scan it commits, pushes, and
- * renders the tree with the `✓ no leaks` row.
+ * Staged-tree leak gate + commit/push. Stages with `git add -A`, scans, and
+ * on a leak renders the ✗ tree row then delegates to `resolveLeakFindings`
+ * (TTY interactive menu or non-TTY FATAL throw, D-01 preserved). On a clean
+ * scan commits, pushes, and renders the `✓ no leaks` row.
  *
- * @param st - The collected push state for the final tree render.
+ * @param st - Push state for the tree render.
+ * @param ts - Backup timestamp passed to the recovery flow.
+ * @param map - Parsed path-map for session path resolution.
+ * @param redactAll - When true, redact all findings non-interactively.
  */
-function commitAndPush(st: PushState): void {
-  // gitOrFatal uses execFileSync (no shell) so NOMAD_HOST cannot escape quoting.
+async function commitAndPush(
+  st: PushState,
+  ts: string,
+  map: PathMap,
+  redactAll: boolean,
+): Promise<void> {
   gitOrFatal(['add', '-A'], 'git add', REPO_HOME);
-  const verdict = scanPushVerdict();
+  let verdict = scanPushVerdict();
   if (verdict.leak) {
     renderPushTree(st, verdict);
-    // Every `leak: true` branch of scanPushVerdict sets a non-null recovery
-    // body, so the `?? fallback` is defensively unreachable (excluded from
-    // coverage rather than contorting a test to fake an impossible state).
-    /* c8 ignore next */
-    throw new NomadFatal(verdict.recovery ?? 'gitleaks detected secrets');
+    verdict = await resolveLeakFindings(verdict, ts, map, { redactAll });
   }
   gitOrFatal(['commit', '-m', `chore: sync from ${HOST}`], 'git commit', REPO_HOME);
   gitOrFatal(['push'], 'git push', REPO_HOME);
@@ -144,8 +145,9 @@ function runDryRunPreview(st: PushState, map: PathMap | null): void {
  * pre-existing violation surfaces; an empty status has nothing to classify.
  * Mirrors `cmdPull`'s `dryRun` contract.
  */
-export function cmdPush(opts: { dryRun?: boolean } = {}): void {
+export async function cmdPush(opts: { dryRun?: boolean; redactAll?: boolean } = {}): Promise<void> {
   const dryRun = opts.dryRun === true;
+  const redactAll = opts.redactAll === true;
   if (!existsSync(REPO_HOME)) die(`repo not cloned at ${REPO_HOME}`);
   const handle = acquireLock('push');
   if (handle === null) process.exit(0);
@@ -202,7 +204,7 @@ export function cmdPush(opts: { dryRun?: boolean } = {}): void {
     // dryRun skips git add / commit / push: run the read-only leak preview,
     // which prints any recovery below the rendered tree.
     if (dryRun) return runDryRunPreview(st, map);
-    commitAndPush(st);
+    await commitAndPush(st, ts, map, redactAll);
   } catch (err) {
     if (err instanceof NomadFatal) {
       fail(err.message);

package/src/commands.redact.core.ts

@@ -0,0 +1,94 @@
+import { appendFileSync } from 'node:fs';
+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;
+  Match: string;
+  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.
+ *
+ * @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);
+  let result = content;
+  for (const f of sorted) {
+    if (f.Match === '') continue;
+    result = result.split(f.Match).join(`[REDACTED:${f.RuleID}]`);
+  }
+  return result;
+}
+
+/**
+ * Format a gitleaks fingerprint for appending to `.gitleaksignore`. Strips any
+ * embedded `\r` or `\n` characters (a newline in a fingerprint must not inject
+ * extra ignore lines) and appends exactly one trailing newline. Pure.
+ *
+ * @param fingerprint Raw fingerprint string from `Finding.Fingerprint`.
+ * @returns Sanitized fingerprint with a single trailing newline.
+ */
+export function formatFingerprint(fingerprint: string): string {
+  return fingerprint.replace(/[\r\n]/g, '') + '\n';
+}
+
+/**
+ * True if the file mtime is within `thresholdMs` of `nowMs` (heuristic for a
+ * live session that Claude Code may still be writing). Pure, injectable for
+ * tests.
+ *
+ * @param mtimeMs File modification time in milliseconds.
+ * @param nowMs Current epoch time in milliseconds.
+ * @param thresholdMs Threshold window in milliseconds (default 5 minutes).
+ * @returns True when the file was modified within the threshold.
+ */
+export function isRecentlyModified(
+  mtimeMs: number,
+  nowMs: number,
+  thresholdMs = 5 * 60 * 1000,
+): boolean {
+  return nowMs - mtimeMs < thresholdMs;
+}
+
+/**
+ * Append one sanitized fingerprint line to `REPO_HOME/.gitleaksignore`. The
+ * fingerprint is passed through `formatFingerprint` to strip embedded newlines
+ * before the append.
+ *
+ * @param fingerprint Raw fingerprint from `Finding.Fingerprint`.
+ */
+export function appendGitleaksIgnore(fingerprint: string): void {
+  appendFileSync(join(REPO_HOME, '.gitleaksignore'), formatFingerprint(fingerprint), 'utf8');
+}