claude-nomad 0.26.0 → 0.26.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.26.2](https://github.com/funkadelic/claude-nomad/compare/v0.26.1...v0.26.2) (2026-05-28)
+
+
+### Fixed
+
+* **gitleaks:** condense push output and group doctor check-shared layout ([#161](https://github.com/funkadelic/claude-nomad/issues/161)) ([d9e5758](https://github.com/funkadelic/claude-nomad/commit/d9e57589f616e70b8e2d6249c957af55a25a578b))
+
+## [0.26.1](https://github.com/funkadelic/claude-nomad/compare/v0.26.0...v0.26.1) (2026-05-27)
+
+
+### Fixed
+
+* **preview:** replace diffJsonStrings parallel walk with jsdiff LCS line diff ([#159](https://github.com/funkadelic/claude-nomad/issues/159)) ([d9c0dca](https://github.com/funkadelic/claude-nomad/commit/d9c0dcae7b417d069e826ce3b825e9f23115ba2d))
+* **remap:** fail closed on path-map collisions in remapPush before any write ([#156](https://github.com/funkadelic/claude-nomad/issues/156)) ([db33157](https://github.com/funkadelic/claude-nomad/commit/db33157faa02b5439278ae4e92a02bd671faee72))
+
+
+### Changed
+
+* **codeql:** skip analysis on release-please PR branches ([#160](https://github.com/funkadelic/claude-nomad/issues/160)) ([2bfed46](https://github.com/funkadelic/claude-nomad/commit/2bfed463ccd76f6331e5ab775bbd5d19df2898e9))
+* **tests:** skip PR-time test matrix on release-please PR branches ([#158](https://github.com/funkadelic/claude-nomad/issues/158)) ([222e27b](https://github.com/funkadelic/claude-nomad/commit/222e27b2643382136505f72e148c17c7ecb7a08f))
+
 ## [0.26.0](https://github.com/funkadelic/claude-nomad/compare/v0.25.5...v0.26.0) (2026-05-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nomad",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "type": "module",
   "description": "Sync Claude Code config (~/.claude/) across machines via a private Git repo, with path remapping and per-host settings overrides.",
   "keywords": [
@@ -80,6 +80,7 @@
     "vitest": "^4.1.6"
   },
   "dependencies": {
+    "diff": "^9.0.0",
     "picocolors": "^1.1.1",
     "tsx": "^4.22.2"
   }

package/src/commands.doctor.check-shared.scan.ts

@@ -7,14 +7,14 @@
  * Owns the post-stage block: run the shared `scanStagedTree` (the same git
  * init + add + `gitleaks protect --staged` mechanism push uses), classify the
  * findings via `partitionFindings`, and emit the doctor glyph rows (clean,
- * per-session leak with rotate-and-scrub guidance, and the nested "other"
- * bucket). All external work flows through `scanStagedTree`; this module spawns
+ * per-session leak rows, then a Remediation block, then a Finding types legend).
+ * All external work flows through `scanStagedTree`; this module spawns
  * nothing itself.
  */
 
 import { join } from 'node:path';
 
-import { green, red, dim, okGlyph, failGlyph } from './color.ts';
+import { green, red, dim, bold, okGlyph, failGlyph } from './color.ts';
 import { addItem, type DoctorSection } from './commands.doctor.format.ts';
 import { CLAUDE_HOME } from './config.ts';
 import { type Finding, partitionFindings, scanStagedTree } from './push-gitleaks.ts';
@@ -32,31 +32,18 @@ function scrubPath(logical: string, sid: string, logicalToEncoded: Map<string, s
 }
 
 /**
- * Emit one fail row per affected session plus rotate-and-scrub + allowlist
- * guidance, and set `process.exitCode = 1`. `logicalBySession` carries the
- * `<logical>` captured from the same match that keyed `bySession`, so the
- * scrub-path hint reuses the authoritative parse. The hint guard omits a row
- * rather than print a wrong path if the invariant ever breaks; the leak row is
- * always emitted.
+ * Emit one fail row per affected session (the `✗ ... in session` rows only)
+ * and set `process.exitCode = 1`. Rotate-and-scrub guidance and the
+ * false-positive hint are NOT emitted here; they belong to `reportRemediation`
+ * which is called after all finding rows.
  */
 function reportSessionFindings(
   section: DoctorSection,
   bySession: Map<string, Map<string, number>>,
-  logicalBySession: Map<string, string>,
-  logicalToEncoded: Map<string, string>,
 ): void {
   for (const [sid, counts] of bySession) {
     const summary = [...counts.entries()].map(([rule, n]) => `${rule} (${n})`).join(', ');
     addItem(section, `${red(failGlyph)} ${red(summary)} in session ${sid}`);
-    const logical = logicalBySession.get(sid);
-    /* c8 ignore next -- false branch is defensive; every bySession sid is keyed in logicalBySession */
-    if (logical !== undefined) {
-      addItem(
-        section,
-        `  ${dim(`rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`)}`,
-      );
-    }
-    addItem(section, `  ${dim('false positive? add a pattern to .gitleaks.toml')}`);
   }
   process.exitCode = 1;
 }
@@ -75,6 +62,36 @@ function reportOtherFindings(section: DoctorSection, other: Finding[]): void {
   process.exitCode = 1;
 }
 
+/**
+ * Emit the remediation block after all finding rows. Findings-first ordering
+ * means guidance is grouped at the end, not interleaved between session rows.
+ * Emits a leading blank, a bold `Remediation` header, one rotate-and-scrub
+ * line per session (using `logicalBySession` to build the scrub path), and
+ * exactly ONE false-positive hint after the loop (deduped, not once per session).
+ * The hint guard omits a rotate row rather than print a wrong path if the
+ * invariant ever breaks; the false-positive line is always appended.
+ */
+function reportRemediation(
+  section: DoctorSection,
+  bySession: Map<string, Map<string, number>>,
+  logicalBySession: Map<string, string>,
+  logicalToEncoded: Map<string, string>,
+): void {
+  addItem(section, '');
+  addItem(section, bold('Remediation'));
+  for (const [sid] of bySession) {
+    const logical = logicalBySession.get(sid);
+    /* c8 ignore next -- false branch is defensive; every bySession sid is keyed in logicalBySession */
+    if (logical !== undefined) {
+      addItem(
+        section,
+        `  ${dim(`- rotate the credential, then scrub ${scrubPath(logical, sid, logicalToEncoded)}`)}`,
+      );
+    }
+  }
+  addItem(section, `  ${dim('- false positive? add a pattern to .gitleaks.toml')}`);
+}
+
 /**
  * Captures both the `<logical>` segment and the `<sid>` from a repo-relative
  * `shared/projects/<logical>/<sid>.jsonl` path. The session-id group matches
@@ -112,14 +129,14 @@ function buildLogicalBySession(findings: Finding[]): Map<string, string> {
 }
 
 /**
- * Emit a deduplicated description legend in the footer: one `[rule-id]:
- * description` row per distinct RuleID across all findings, set off by a blank
- * line before and after. Sourced from the `Description` gitleaks bakes into
- * each finding, so it needs no network; rules whose description is absent
- * (older gitleaks, custom rules) are skipped, and the whole block (including
- * the surrounding blanks) is omitted when no descriptions are available. The
- * legend lives in the footer so a rule hit across many files or sessions
- * (e.g. `sonar-api-token`) is explained once, not per occurrence.
+ * Emit a deduplicated description legend in the footer: one `- [rule-id]:
+ * description` row per distinct RuleID across all findings, headed by a bold
+ * `Finding types` header with a leading blank but no trailing blank (renderSection
+ * attaches the `└` elbow to the last non-empty item). Rules whose description
+ * is absent (older gitleaks, custom rules) are skipped, and the whole block
+ * (including the surrounding blank and header) is omitted when no descriptions
+ * are available. The legend lives in the footer so a rule hit across many files
+ * or sessions (e.g. `sonar-api-token`) is explained once, not per occurrence.
  */
 function emitDescriptionLegend(section: DoctorSection, findings: Finding[]): void {
   const descByRule = new Map<string, string>();
@@ -128,16 +145,19 @@ function emitDescriptionLegend(section: DoctorSection, findings: Finding[]): voi
   }
   if (descByRule.size === 0) return;
   addItem(section, '');
+  addItem(section, bold('Finding types'));
   for (const [rule, desc] of descByRule) {
-    addItem(section, `  ${red(`[${rule}]`)}: ${dim(desc)}`);
+    addItem(section, `  ${red(`- [${rule}]`)}: ${dim(desc)}`);
   }
-  addItem(section, '');
 }
 
 /**
  * Scan the staged temp tree through the shared `scanStagedTree` and emit the
- * result rows. Isolates the deepest nesting from `reportCheckShared`: the scan
- * try/catch (failure -> fail row + exit 1, carrying `err.message` only, never
+ * result rows in findings-first order: other-bucket leak rows, then per-session
+ * leak rows, then a `Remediation` block (gated on bySession.size > 0), then a
+ * `Finding types` legend (gated on at least one finding carrying a Description).
+ * Isolates the deepest nesting from `reportCheckShared`: the scan try/catch
+ * (failure -> fail row + exit 1, carrying `err.message` only, never
  * stderr/stdout), the unparseable `findings === null` branch, `partitionFindings`,
  * and the clean / `other` / `bySession` rows. BOTH buckets gate the clean row: a
  * finding in `other` (nested transcripts matching neither the flat `SESSION_PATH`
@@ -175,8 +195,9 @@ export function scanAndReport(
     return;
   }
   if (other.length > 0) reportOtherFindings(section, other);
+  if (bySession.size > 0) reportSessionFindings(section, bySession);
   if (bySession.size > 0) {
-    reportSessionFindings(section, bySession, buildLogicalBySession(findings), logicalToEncoded);
+    reportRemediation(section, bySession, buildLogicalBySession(findings), logicalToEncoded);
   }
   emitDescriptionLegend(section, findings);
 }

package/src/diff-lines.ts

@@ -0,0 +1,43 @@
+import { diffLines } from 'diff';
+
+import { green, red } from './color.ts';
+
+/**
+ * Map a jsdiff `diffLines` result for two pre-stringified JSON strings into
+ * an array of unified-diff body lines (the two-line header is the caller's
+ * responsibility).
+ *
+ * Each jsdiff part has a `value` that may span multiple lines and may carry a
+ * trailing `\n`. The value is split on `\n` and any trailing empty element
+ * (produced by the trailing newline) is dropped so that it does not become a
+ * spurious blank output line.
+ *
+ * Line prefix mapping per part type:
+ *   - context (neither added nor removed): a single leading space then the line
+ *   - removed (`part.removed === true`): `red('-' + line)`
+ *   - added (`part.added === true`): `green('+' + line)`
+ *
+ * Coloring routes through `color.ts` `red`/`green` helpers, so `NO_COLOR` /
+ * non-TTY environments degrade to literal `-` / `+` prefixed lines with no
+ * ANSI escape sequences. Picocolors owns the detection logic.
+ */
+export function diffLinesToUnified(oldStr: string, newStr: string): string[] {
+  const parts = diffLines(oldStr, newStr);
+  const lines: string[] = [];
+  for (const part of parts) {
+    const partLines = part.value.split('\n');
+    // A part value ending in '\n' yields a trailing '' after split; drop it.
+    if (partLines[partLines.length - 1] === '') {
+      partLines.pop();
+    }
+    const prefix = part.removed
+      ? (line: string) => red(`-${line}`)
+      : part.added
+        ? (line: string) => green(`+${line}`)
+        : (line: string) => ` ${line}`;
+    for (const line of partLines) {
+      lines.push(prefix(line));
+    }
+  }
+  return lines;
+}

package/src/preview.ts

@@ -1,53 +1,34 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { green, red } from './color.ts';
 import { CLAUDE_HOME, HOST, REPO_HOME } from './config.ts';
+import { diffLinesToUnified } from './diff-lines.ts';
 import { applySharedLinks } from './links.ts';
 import { remapPull } from './remap.ts';
 import { log } from './utils.ts';
 import { deepMerge, readJson } from './utils.json.ts';
 
 /**
- * Minimal in-tree unified-diff helper for two pre-stringified JSON
- * documents. Walks the line arrays in parallel and emits a unified-diff
- * style output: unchanged lines prefixed with a space, removed lines with
- * `-` (red), added lines with `+` (green), plus at most three lines of
- * surrounding context per changed block. The implementation is intentionally
- * naive (no LCS); for two ~50-line settings JSON inputs the result is
- * acceptable even if not optimal.
+ * LCS line diff for two pre-stringified JSON documents via jsdiff. Returns a
+ * unified-diff style string: the two literal header lines
+ * `--- ~/.claude/settings.json` and `+++ would write`, followed by body lines
+ * where unchanged lines are prefixed with a space, removed lines with `-`
+ * (red), and added lines with `+` (green). Coloring routes through `color.ts`
+ * so `NO_COLOR` / non-TTY environments degrade to literal prefixes with no
+ * ANSI escape sequences.
  *
- * Returns the empty string when the inputs are byte-identical so the caller
- * can suppress the section. Picocolors handles `NO_COLOR` / `FORCE_COLOR`
- * detection, so the `red`/`green` wrappers degrade to identity in non-TTY
- * environments and the output stays literal `-` / `+` prefixed.
- *
- * The header line `--- ~/.claude/settings.json` / `+++ would write` is
- * literal; callers that want a different header can prepend their own.
+ * Returns the empty string when inputs are byte-identical so the caller can
+ * suppress the section. jsdiff `diffLines` aligns on the longest common
+ * subsequence, so a mid-document insertion does not cascade false `-`/`+`
+ * pairs for the unchanged tail.
  */
 export function diffJsonStrings(currentJsonText: string, newJsonText: string): string {
   if (currentJsonText === newJsonText) return '';
-  const a = currentJsonText.split('\n');
-  const b = newJsonText.split('\n');
-  const lines: string[] = [];
-  lines.push('--- ~/.claude/settings.json');
-  lines.push('+++ would write');
-
-  // Walk both arrays in parallel. Lines that match index-wise are context;
-  // others are emitted as -a / +b. A real unified-diff would compute the
-  // longest common subsequence; this naive walk is good enough for two JSON
-  // documents pretty-printed at the same indentation level.
-  const maxLen = Math.max(a.length, b.length);
-  for (let i = 0; i < maxLen; i++) {
-    const av = a[i];
-    const bv = b[i];
-    if (av === bv) {
-      if (av !== undefined) lines.push(` ${av}`);
-      continue;
-    }
-    if (av !== undefined) lines.push(red(`-${av}`));
-    if (bv !== undefined) lines.push(green(`+${bv}`));
-  }
+  const lines: string[] = [
+    '--- ~/.claude/settings.json',
+    '+++ would write',
+    ...diffLinesToUnified(currentJsonText, newJsonText),
+  ];
   return lines.join('\n');
 }
 

package/src/push-gitleaks.scan.ts

@@ -83,10 +83,12 @@ export function readGitleaksReport(reportPath: string): Finding[] | null {
  *
  * `forwardStreams` (default `false`): when `true`, the gitleaks redacted
  * stderr/stdout captured on a non-zero exit is written to the process streams
- * so the operator sees which file is dirty. `runGitleaksScan` passes `true`
- * (byte-identical push behavior); the read-only `--check-shared` preflight
- * leaves it `false` so it never writes to stderr (its scan-failed row carries
- * the error message only, never the streams).
+ * ONLY on the scan-crash path (when the report is unparseable or missing, i.e.
+ * `readGitleaksReport` returns `null`). On the leaks-found path the report
+ * parses to a findings array, the structured caller FATAL fully describes the
+ * findings, and the raw streams are suppressed to avoid printing them twice.
+ * `runGitleaksScan` passes `true`; the read-only `--check-shared` preflight
+ * leaves it `false` so it never writes to streams on any path.
  */
 export function scanStagedTree(repoDir: string, forwardStreams = false): Finding[] | null {
   const cacheDir = join(homedir(), '.cache', 'claude-nomad');
@@ -111,11 +113,12 @@ export function scanStagedTree(repoDir: string, forwardStreams = false): Finding
   } catch (err) {
     const e = err as NodeJS.ErrnoException & { stderr?: Buffer; stdout?: Buffer };
     if (e.code === 'ENOENT') throw err;
-    if (forwardStreams) {
+    const report = readGitleaksReport(reportPath);
+    if (forwardStreams && report === null) {
       if (e.stderr) process.stderr.write(e.stderr);
       if (e.stdout) process.stdout.write(e.stdout);
     }
-    return readGitleaksReport(reportPath);
+    return report;
   } finally {
     rmSync(reportPath, { force: true });
   }

package/src/push-gitleaks.ts

@@ -92,6 +92,20 @@ export function partitionFindings(findings: Finding[]): {
  * session, since those nested paths route to the `other` bucket and are
  * not listed per-session. Pure.
  */
+/**
+ * Render one `Also found:` row for a non-session ("other"-bucket) finding as
+ * `  <File>:<StartLine>  <RuleID>`, where the line number is the manual-scrub
+ * locator for the nested transcript. `StartLine` is typed `number` but comes
+ * from an unvalidated `parsed as Finding[]` cast over gitleaks subprocess
+ * output, so a missing or non-positive value (gitleaks line numbers are
+ * 1-indexed) drops the `:<line>` suffix rather than emit a confusing
+ * `:undefined` / `:0`.
+ */
+export function formatOtherFinding(f: Finding): string {
+  const loc = Number.isInteger(f.StartLine) && f.StartLine > 0 ? `:${f.StartLine}` : '';
+  return `  ${f.File}${loc}  ${f.RuleID}`;
+}
+
 export function buildSessionAwareFatal(
   bySession: Map<string, Map<string, number>>,
   other: Finding[],
@@ -110,7 +124,7 @@ export function buildSessionAwareFatal(
     lines.push(
       '',
       'Also found:',
-      ...other.map((f) => `  ${f.File}  ${f.RuleID}`),
+      ...other.map(formatOtherFinding),
       '  Review with: git diff --cached, then unstage manually.',
     );
   }
@@ -133,8 +147,10 @@ export function buildSessionAwareFatal(
  * missing/locked file, or a non-finding runtime failure, since gitleaks v8.x
  * returns exit 1 for both "leaks found" and runtime errors) it throws a
  * distinct scan-failed FATAL so the operator does not chase a phantom
- * `nomad drop-session` recovery; the forwarded stderr/stdout above carries the
- * underlying gitleaks output.
+ * `nomad drop-session` recovery. On the leaks-found path the raw gitleaks
+ * streams are suppressed (the session-aware FATAL fully describes the findings).
+ * On the scan-failed/null-report path the raw stderr/stdout is forwarded so
+ * "Review the gitleaks output above." has something to point at.
  *
  * ENOENT (gitleaks or git absent) propagates from the helper and is mapped to
  * the platform-aware install-hint FATAL. Defense-in-depth: the presence probe

package/src/remap.ts

@@ -2,7 +2,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'no
 import { join, relative, sep } from 'node:path';
 
 import { CLAUDE_HOME, HOST, REPO_HOME, type PathMap } from './config.ts';
-import { log } from './utils.ts';
+import { die, log } from './utils.ts';
 import { backupBeforeWrite, backupRepoWrite } from './utils.fs.ts';
 import { encodePath, readJson } from './utils.json.ts';
 
@@ -98,17 +98,67 @@ export function remapPull(ts: string, opts: { dryRun?: boolean } = {}): { unmapp
   return { unmapped };
 }
 
+/**
+ * Build the encoded-key to logical-name reverse map for the current host,
+ * failing closed on any `path-map.json` shape that would silently lose session
+ * data on push. Both failure modes `die()` (throw `NomadFatal`) before the
+ * caller writes anything:
+ *
+ * - Encoded-path collision: two distinct host paths that `encodePath` maps to
+ *   the same key (every `/` becomes `-`), which would clobber each other under
+ *   one repo directory.
+ * - Duplicate path: two logical names mapping to the same host path, where only
+ *   one logical could be pushed and the other's `shared/projects/` copy would
+ *   be orphaned.
+ *
+ * @param map - the parsed `path-map.json`
+ * @returns reverse lookup from encoded local dir name to logical project name
+ */
+function buildReverseMap(map: PathMap): Map<string, string> {
+  const reverse = new Map<string, string>();
+  const encodedPaths = new Map<string, string>();
+  for (const [logical, hosts] of Object.entries(map.projects)) {
+    const p = hosts[HOST];
+    if (!p || p === 'TBD') continue;
+    const encoded = encodePath(p);
+    const prior = encodedPaths.get(encoded);
+    if (prior !== undefined) {
+      if (prior !== p) {
+        die(
+          `encoded-path collision in path-map.json: "${prior}" and "${p}" both encode to` +
+            ` "${encoded}" (encodePath replaces every / with -).` +
+            ` Edit path-map.json so the two paths do not encode identically.` +
+            ` Run nomad doctor for the full list of collisions.`,
+        );
+      }
+      die(
+        `duplicate path in path-map.json: logical names "${reverse.get(encoded)}" and "${logical}"` +
+          ` both map to "${p}" for ${HOST}, so only one could be pushed and the other's` +
+          ` shared/projects/ copy would be orphaned.` +
+          ` Edit path-map.json so each host path maps to a single logical name.`,
+      );
+    }
+    encodedPaths.set(encoded, p);
+    reverse.set(encoded, logical);
+  }
+  return reverse;
+}
+
 /**
  * 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.
+ * for this host. `collisions` is always `0` on the success path: any
+ * `path-map.json` shape that would silently lose data (an encoded-path
+ * collision between two distinct host paths, or two logical names mapping to
+ * the same host path) makes `buildReverseMap` `die()` (throw `NomadFatal`) to
+ * refuse the push before any `shared/projects/` content is written. Detection
+ * runs during the reverse-map build, so it fires under `dryRun` too.
  *
  * `opts.dryRun` (default `false`): when `true`, log `would push:` lines
- * instead of calling `backupRepoWrite` + `copyDir`. Counts are computed
- * identically in both modes.
+ * instead of calling `backupRepoWrite` + `copyDir`. Collision detection
+ * runs identically in both modes.
  */
 export function remapPush(
   ts: string,
@@ -116,7 +166,6 @@ export function remapPush(
 ): { 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');
@@ -126,16 +175,14 @@ export function remapPush(
   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);
-  }
+  const reverse = buildReverseMap(map);
+  if (!existsSync(localProjects)) return { unmapped, collisions: 0 };
+  // Create the repo destination only after collision detection passes and we
+  // know there is something to push, so a failing or no-op push is fully
+  // side-effect-free (no empty shared/projects/ left behind).
+  if (!dryRun) mkdirSync(repoProjects, { recursive: true });
 
-  if (!existsSync(localProjects)) return { unmapped, collisions };
   for (const dir of readdirSync(localProjects)) {
     const logical = reverse.get(dir);
     if (!logical) {
@@ -156,5 +203,5 @@ export function remapPush(
     copyDirJsonlOnly(join(localProjects, dir), repoDst);
     log(`pushed ${dir} -> ${logical}`);
   }
-  return { unmapped, collisions };
+  return { unmapped, collisions: 0 };
 }