claude-nomad 0.25.0 → 0.25.2

package/src/commands.doctor.checks.repo.ts

@@ -0,0 +1,133 @@
+import { existsSync, lstatSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  blue,
+  cyan,
+  dim,
+  failGlyph,
+  green,
+  infoGlyph,
+  okGlyph,
+  red,
+  warnGlyph,
+  yellow,
+} from './color.ts';
+import { CLAUDE_HOME, HOST, REPO_HOME, SHARED_LINKS } from './config.ts';
+import { addItem, type DoctorSection } from './commands.doctor.format.ts';
+import { classifyRepoState, reasonForPartial } from './init.classify.ts';
+
+/**
+ * Host- and repo-state reporters for `cmdDoctor`. Each helper appends one or
+ * more items to its target `DoctorSection` (via `addItem`) and signals failure
+ * by setting `process.exitCode = 1`. Items go to stdout at render time through
+ * `renderDoctor` in `commands.doctor.format`; nothing here writes to stderr
+ * (read-only doctor contract: FAIL lines stay on stdout so a piped
+ * `nomad doctor 2>/dev/null` does not lose them).
+ */
+
+/**
+ * True when the `NOMAD_REPO` env override is set to a non-empty value.
+ * Mirrors the `||` empty-string-fallthrough semantics of `REPO_HOME` itself
+ * (see `src/config.ts`): an unset env, or `export NOMAD_REPO=`, both return
+ * false because the default fallback fires. Reads `process.env.NOMAD_REPO`
+ * directly so a set-but-empty value is distinguishable from "set to the
+ * default path"; reading via the imported `REPO_HOME` constant cannot make
+ * that distinction. Exposed for `reportRepoState`; not for general use.
+ */
+export function isOverrideActive(): boolean {
+  return Boolean(process.env.NOMAD_REPO);
+}
+
+/**
+ * Pushes the host identity (info) and the two key path lines (repo and
+ * claude-home) with gutter glyphs. Path presence is reported via warnGlyph
+ * (not failGlyph) so an absent CLAUDE_HOME does not flip sectionFailed to
+ * decorate the Host header with `✘`. The authoritative empty-repo FAIL is
+ * owned by reportRepoState; these two lines remain informational and do
+ * NOT mutate process.exitCode.
+ */
+export function reportHostAndPaths(section: DoctorSection): void {
+  addItem(section, `${dim(infoGlyph)} host: ${cyan(HOST)}`);
+  addItem(
+    section,
+    `${existsSync(REPO_HOME) ? green(okGlyph) : yellow(warnGlyph)} repo: ${blue(REPO_HOME)}`,
+  );
+  addItem(
+    section,
+    `${existsSync(CLAUDE_HOME) ? green(okGlyph) : yellow(warnGlyph)} claude home: ${blue(CLAUDE_HOME)}`,
+  );
+}
+
+/** Emits the repo-state status line derived from classifyRepoState (okGlyph/warnGlyph/failGlyph). When `NOMAD_REPO` is active, all three branches receive a ` (NOMAD_REPO)` suffix so the env override is visible whatever the repo state. FAIL signals via process.exitCode. */
+export function reportRepoState(section: DoctorSection): void {
+  const state = classifyRepoState(REPO_HOME, HOST);
+  // Computed once so populated/partial/empty branches share the same
+  // annotation. Leading space before `(` keeps the line readable on every
+  // branch; empty string produces zero visual change when the override is
+  // not in play, matching SPEC §5 (acceptance: unset env -> no annotation).
+  const overrideLabel = isOverrideActive() ? ' (NOMAD_REPO)' : '';
+  if (state === 'populated') {
+    addItem(section, `${green(okGlyph)} repo state: populated${overrideLabel}`);
+  } else if (state === 'partial') {
+    addItem(
+      section,
+      `${yellow(warnGlyph)} repo state: partial ${reasonForPartial(REPO_HOME, HOST)}${overrideLabel}`,
+    );
+  } else {
+    addItem(
+      section,
+      `${red(failGlyph)} repo state: empty - run 'nomad init' to scaffold${overrideLabel}`,
+    );
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * Emits a per-entry status line for each name in SHARED_LINKS
+ * (okGlyph/warnGlyph/failGlyph). A non-symlink blocks sync and FAILs via
+ * process.exitCode. TOCTOU-safe: lstatSync is wrapped in try/catch so a path
+ * that vanishes or becomes unreadable between the probe and the stat yields a
+ * row instead of an unhandled throw that aborts the whole doctor run. A symlink
+ * whose target cannot be resolved is a WARN (broken-symlink for a missing
+ * target, target-unreadable otherwise), never a healthy OK, so a dangling or
+ * unreadable link is not masked.
+ */
+export function reportSharedLinks(section: DoctorSection): void {
+  for (const name of SHARED_LINKS) {
+    const p = join(CLAUDE_HOME, name);
+    let stat;
+    try {
+      stat = lstatSync(p);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') {
+        addItem(section, `${yellow(warnGlyph)} ${name}: missing`);
+      } else {
+        addItem(section, `${red(failGlyph)} ${name}: could not stat (${String(code)})`);
+        process.exitCode = 1;
+      }
+      continue;
+    }
+    if (stat.isSymbolicLink()) {
+      try {
+        // statSync follows the link; a throw means the target does not resolve.
+        statSync(p);
+        addItem(section, `${green(okGlyph)} ${name}: symlink`);
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === 'ENOENT') {
+          addItem(section, `${yellow(warnGlyph)} ${name}: broken symlink (target missing)`);
+        } else {
+          addItem(
+            section,
+            `${yellow(warnGlyph)} ${name}: symlink target unreadable (${String(code)})`,
+          );
+        }
+      }
+    } else {
+      addItem(section, `${red(failGlyph)} ${name}: NOT a symlink (blocks sync)`);
+      process.exitCode = 1;
+    }
+  }
+}

package/src/commands.doctor.checks.repository.ts

@@ -0,0 +1,105 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import {
+  blue,
+  cyan,
+  dim,
+  failGlyph,
+  green,
+  infoGlyph,
+  okGlyph,
+  red,
+  warnGlyph,
+  yellow,
+} from './color.ts';
+import { REPO_HOME } from './config.ts';
+import { addItem, type DoctorSection } from './commands.doctor.format.ts';
+import { findGitlinks } from './push-checks.ts';
+import { gitStatusPorcelainZ } from './utils.ts';
+
+/**
+ * Repository-state reporters for `cmdDoctor`: the gitleaks presence probe, the
+ * nested-gitlink scan of `shared/`, the remote-origin line, and the
+ * rebase-clean-tree WARN. Each helper appends items to its target
+ * `DoctorSection` and signals failure by setting `process.exitCode = 1`.
+ * Read-only: FAIL lines stay on stdout.
+ */
+
+/**
+ * Probes for gitleaks on PATH; emits okGlyph with version, or failGlyph with
+ * ENOENT vs other-error distinction (sets exitCode=1). Returns `true` when a
+ * usable binary was found so the caller can skip a redundant second `version`
+ * probe (e.g. the `--check-shared` Shared scan section).
+ */
+export function reportGitleaksProbe(section: DoctorSection): boolean {
+  try {
+    const v = execFileSync('gitleaks', ['version'], { stdio: ['ignore', 'pipe', 'pipe'] })
+      .toString()
+      .trim();
+    addItem(section, `${green(okGlyph)} gitleaks: ${dim(v)}`);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      addItem(section, `${red(failGlyph)} gitleaks: not on PATH (required for nomad push)`);
+    } else {
+      addItem(section, `${red(failGlyph)} gitleaks: probe failed: ${(err as Error).message}`);
+    }
+    process.exitCode = 1;
+    return false;
+  }
+}
+
+/** Walks shared/ for nested .git gitlinks; emits failGlyph per gitlink found (sets exitCode=1), okGlyph when none. */
+export function reportGitlinks(section: DoctorSection): void {
+  const sharedDir = join(REPO_HOME, 'shared');
+  if (existsSync(sharedDir)) {
+    const gitlinks = findGitlinks(sharedDir);
+    for (const p of gitlinks) {
+      const rel = relative(REPO_HOME, p);
+      addItem(
+        section,
+        `${red(failGlyph)} gitlink: ${blue(rel)} would push as submodule (run: rm -rf ${rel} or remove the nested repo)`,
+      );
+    }
+    if (gitlinks.length > 0) {
+      process.exitCode = 1;
+    } else {
+      addItem(section, `${green(okGlyph)} gitlink scan: no nested .git in shared/`);
+    }
+  }
+}
+
+/** Pushes the `git remote get-url origin` line or a `not configured` informational line. */
+export function reportRemote(section: DoctorSection): void {
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+      .toString()
+      .trim();
+    addItem(section, `${dim(infoGlyph)} remote origin: ${cyan(url)}`);
+  } catch {
+    addItem(section, `${dim(infoGlyph)} remote origin: not configured`);
+  }
+}
+
+/** WARNs when ~/claude-nomad/ has uncommitted changes (autostash territory for push). */
+export function reportRebaseClean(section: DoctorSection): void {
+  try {
+    const status = gitStatusPorcelainZ(REPO_HOME);
+    if (status.length > 0) {
+      addItem(
+        section,
+        `${yellow(warnGlyph)} ${blue('~/claude-nomad/')} has uncommitted changes (nomad push will --autostash these)`,
+      );
+    }
+  } catch {
+    // gitStatusPorcelainZ failure on a missing or non-repo REPO_HOME is
+    // already surfaced by reportHostAndPaths (warnGlyph on the `repo:` line
+    // when the directory is absent) and reportRepoState ('empty' FAIL when
+    // the scaffold is absent). Swallowing here avoids double-reporting.
+  }
+}

package/src/commands.doctor.checks.settings.ts

@@ -0,0 +1,88 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  blue,
+  dim,
+  failGlyph,
+  green,
+  infoGlyph,
+  okGlyph,
+  red,
+  warnGlyph,
+  yellow,
+} from './color.ts';
+import { HOST, KNOWN_SETTINGS_KEYS, REPO_HOME, CLAUDE_HOME } from './config.ts';
+import { addItem, readJsonSafe, type DoctorSection } from './commands.doctor.format.ts';
+
+/**
+ * Settings reporters for `cmdDoctor`: the shared base, the local
+ * `settings.json` schema check, and the host-override diagnostic. Each helper
+ * appends items to its target `DoctorSection` and signals failure by setting
+ * `process.exitCode = 1`. Read-only: FAIL lines stay on stdout (a piped
+ * `nomad doctor 2>/dev/null` keeps them).
+ */
+
+/** Loads shared/settings.base.json; on missing or malformed, records a FAIL item in the supplied section. Returns the parsed object or null. */
+export function loadBaseSettings(section: DoctorSection): Record<string, unknown> | null {
+  const basePath = join(REPO_HOME, 'shared', 'settings.base.json');
+  if (!existsSync(basePath)) {
+    addItem(section, `${red(failGlyph)} shared/settings.base.json missing at ${blue(basePath)}`);
+    process.exitCode = 1;
+    return null;
+  }
+  return readJsonSafe<Record<string, unknown>>(basePath, basePath, section);
+}
+
+/** Loads ~/.claude/settings.json when present and emits the schema status (okGlyph for known-keys-only, warnGlyph when unknown keys are present); returns the parsed object or null. */
+export function loadAndReportSettings(section: DoctorSection): Record<string, unknown> | null {
+  const settingsPath = join(CLAUDE_HOME, 'settings.json');
+  if (!existsSync(settingsPath)) return null;
+  const settings = readJsonSafe<Record<string, unknown>>(settingsPath, settingsPath, section);
+  if (settings === null) return null;
+  const unknownKeys = Object.keys(settings).filter((k) => !KNOWN_SETTINGS_KEYS.has(k));
+  if (unknownKeys.length > 0) {
+    addItem(
+      section,
+      `${yellow(warnGlyph)} settings.json has unknown keys (schema drift?): ${unknownKeys.join(', ')}`,
+    );
+  } else {
+    addItem(section, `${green(okGlyph)} settings.json schema: known keys only`);
+  }
+  return settings;
+}
+
+/** Emits the host-override status: okGlyph when no host file is needed (base-only matches settings), failGlyph on drift without a host file (with candidate list), or okGlyph path when the host file parses. */
+export function reportHostOverrides(
+  section: DoctorSection,
+  base: Record<string, unknown> | null,
+  settings: Record<string, unknown> | null,
+): void {
+  const hostFile = join(REPO_HOME, 'hosts', `${HOST}.json`);
+  let drift: string[] = [];
+  if (base !== null && settings !== null) {
+    const baseKeys = new Set(Object.keys(base));
+    drift = Object.keys(settings).filter((k) => !baseKeys.has(k));
+  }
+  if (existsSync(hostFile)) {
+    if (readJsonSafe<Record<string, unknown>>(hostFile, hostFile, section) !== null) {
+      addItem(section, `${green(okGlyph)} host overrides: ${blue(hostFile)}`);
+    }
+  } else if (drift.length > 0) {
+    addItem(
+      section,
+      `${red(failGlyph)} no hosts/${HOST}.json AND settings.json has unbased keys ${JSON.stringify(drift)}`,
+    );
+    const hostsDir = join(REPO_HOME, 'hosts');
+    if (existsSync(hostsDir)) {
+      const cands = readdirSync(hostsDir).filter((f) => f.endsWith('.json'));
+      if (cands.length > 0) addItem(section, `${dim(infoGlyph)} candidates: ${cands.join(', ')}`);
+    }
+    process.exitCode = 1;
+  } else {
+    addItem(
+      section,
+      `${green(okGlyph)} host overrides: none (base-only is fine, no settings drift)`,
+    );
+  }
+}

package/src/commands.doctor.format.ts

@@ -1,4 +1,5 @@
 import { failGlyph, red } from './color.ts';
+import { readJson } from './utils.json.ts';
 
 /**
  * Bare `failGlyph` codepoint (`✗`, U+2717) without any WSL padding the
@@ -38,6 +39,23 @@ export function addItem(s: DoctorSection, text: string): void {
   s.items.push(text);
 }
 
+/**
+ * Tolerant JSON reader for `cmdDoctor`. Doctor reads three JSON files
+ * (`settings.json`, `settings.base.json`, `path-map.json`); a malformed
+ * input must not throw mid-output (user would lose every line below it).
+ * Returns `null` on parse failure, records a FAIL item in the supplied
+ * section, and sets `process.exitCode = 1` so scripts can gate on the result.
+ */
+export function readJsonSafe<T>(path: string, label: string, section: DoctorSection): T | null {
+  try {
+    return readJson<T>(path);
+  } catch (err) {
+    addItem(section, `${red(failGlyph)} ${label} malformed JSON: ${(err as Error).message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
 /**
  * True when any item in the section contains the FAIL glyph.
  * Color-wrapped failGlyph (`✗`) still contains the

package/src/commands.doctor.ts

@@ -1,17 +1,20 @@
+import {
+  reportHostAndPaths,
+  reportRepoState,
+  reportSharedLinks,
+} from './commands.doctor.checks.repo.ts';
 import {
   loadAndReportSettings,
   loadBaseSettings,
+  reportHostOverrides,
+} from './commands.doctor.checks.settings.ts';
+import { reportNeverSync, reportPathMap } from './commands.doctor.checks.pathmap.ts';
+import {
   reportGitleaksProbe,
   reportGitlinks,
-  reportHostAndPaths,
-  reportHostOverrides,
-  reportNeverSync,
-  reportPathMap,
   reportRebaseClean,
   reportRemote,
-  reportRepoState,
-  reportSharedLinks,
-} from './commands.doctor.checks.ts';
+} from './commands.doctor.checks.repository.ts';
 import { reportCheckShared } from './commands.doctor.check-shared.ts';
 import { reportNodeEngineCheck } from './commands.doctor.engine.ts';
 import { renderDoctor, section } from './commands.doctor.format.ts';

package/src/commands.drop-session.git.ts

@@ -0,0 +1,81 @@
+import { execFileSync } from 'node:child_process';
+
+import { REPO_HOME } from './config.ts';
+
+/**
+ * Expand a repo-relative directory into its staged entries via
+ * `git ls-files -z -- <dirRel>` (argv-array form, NUL-split for path
+ * safety). Returns repo-relative POSIX paths for every staged file under
+ * the directory, or an empty array when none are staged or `git` fails
+ * (missing/corrupt index); the caller then falls through to the existing
+ * per-entry idempotency guard rather than escalating to a FATAL.
+ *
+ * @param dirRel Repo-relative directory path (`shared/projects/<logical>/<id>`).
+ */
+export function expandStagedDir(dirRel: string): string[] {
+  try {
+    const out = execFileSync('git', ['ls-files', '-z', '--', dirRel], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return out
+      .toString()
+      .split('\0')
+      .filter((p) => p !== '');
+  } catch {
+    /* c8 ignore next -- defensive: a git ls-files failure falls back to an empty list */
+    return [];
+  }
+}
+
+/**
+ * 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.
+ */
+export 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).
+ */
+export 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;
+  }
+}