claude-nomad 0.17.0

package/src/commands.doctor.checks.ts

@@ -0,0 +1,343 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import {
+  blue,
+  cyan,
+  dim,
+  failGlyph,
+  green,
+  infoGlyph,
+  okGlyph,
+  red,
+  warnGlyph,
+  yellow,
+} from './color.ts';
+// prettier-ignore
+import { CLAUDE_HOME, HOST, KNOWN_SETTINGS_KEYS, NEVER_SYNC, REPO_HOME, SHARED_LINKS, type PathMap } from './config.ts';
+import { addItem, type DoctorSection } from './commands.doctor.format.ts';
+import { classifyRepoState, reasonForPartial } from './init.ts';
+import { findGitlinks } from './push-checks.ts';
+import { encodePath, gitStatusPorcelainZ, readJson } from './utils.ts';
+
+/**
+ * Per-check helpers used by `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).
+ */
+
+/**
+ * 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.
+ */
+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 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. */
+export function reportSharedLinks(section: DoctorSection): void {
+  for (const name of SHARED_LINKS) {
+    const p = join(CLAUDE_HOME, name);
+    if (!existsSync(p)) {
+      addItem(section, `${yellow(warnGlyph)} ${name}: missing`);
+      continue;
+    }
+    if (lstatSync(p).isSymbolicLink()) {
+      addItem(section, `${green(okGlyph)} ${name}: symlink`);
+    } else {
+      addItem(section, `${red(failGlyph)} ${name}: NOT a symlink (blocks sync)`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+/** 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)`,
+    );
+  }
+}
+
+/** Emits the mapped-projects header for the current host and one line per mapped project. */
+function reportMappedProjects(section: DoctorSection, map: PathMap): void {
+  const mapped = Object.entries(map.projects).filter(([, hosts]) => hosts[HOST]);
+  addItem(
+    section,
+    `${dim(infoGlyph)} mapped projects for ${cyan(HOST)}: ${dim(String(mapped.length))}`,
+  );
+  for (const [name, hosts] of mapped) {
+    addItem(section, `${dim(infoGlyph)} ${name} -> ${blue(hosts[HOST])}`);
+  }
+}
+
+/** Scans every host of every project for encodePath collisions; emits failGlyph per collision (sets exitCode=1), okGlyph when clean. */
+function reportPathCollisions(section: DoctorSection, map: PathMap): void {
+  const seen = new Map<string, string>();
+  let collisionCount = 0;
+  for (const hosts of Object.values(map.projects)) {
+    for (const abspath of Object.values(hosts)) {
+      if (!abspath || abspath === 'TBD') continue;
+      const encoded = encodePath(abspath);
+      const prior = seen.get(encoded);
+      if (prior !== undefined && prior !== abspath) {
+        addItem(
+          section,
+          `${red(failGlyph)} path-encoding collision: ${prior} and ${abspath} both encode to ${encoded}`,
+        );
+        collisionCount++;
+      } else {
+        seen.set(encoded, abspath);
+      }
+    }
+  }
+  if (collisionCount > 0) process.exitCode = 1;
+  else addItem(section, `${green(okGlyph)} path-encoding: no collisions`);
+}
+
+/** Pushes mapped projects for the current host and FAILs on path-encoding collisions across hosts; FAILs when path-map.json is missing. */
+export function reportPathMap(section: DoctorSection): void {
+  const mapPath = join(REPO_HOME, 'path-map.json');
+  if (!existsSync(mapPath)) {
+    addItem(section, `${red(failGlyph)} path-map.json missing at ${blue(mapPath)}`);
+    process.exitCode = 1;
+    return;
+  }
+  const map = readJsonSafe<PathMap>(mapPath, mapPath, section);
+  if (map === null) return;
+  // Guard non-object `projects` and per-project non-object `hosts` so the
+  // helpers' `hosts[HOST]` / `Object.values(hosts)` cannot throw mid-output
+  // and break the tolerant-doctor contract.
+  const projects: unknown = (map as { projects?: unknown }).projects;
+  if (projects === null || typeof projects !== 'object' || Array.isArray(projects)) {
+    addItem(
+      section,
+      `${red(failGlyph)} path-map.json invalid schema: "projects" must be an object`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  for (const [name, hosts] of Object.entries(projects as Record<string, unknown>)) {
+    if (hosts === null || typeof hosts !== 'object' || Array.isArray(hosts)) {
+      addItem(
+        section,
+        `${red(failGlyph)} path-map.json invalid schema: project "${name}" hosts must be an object`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    for (const [hostName, mappedPath] of Object.entries(hosts as Record<string, unknown>)) {
+      if (typeof mappedPath !== 'string') {
+        addItem(
+          section,
+          `${red(failGlyph)} path-map.json invalid schema: project "${name}" host "${hostName}" path must be a string`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+  reportMappedProjects(section, map);
+  reportPathCollisions(section, map);
+}
+
+/** Pushes the comma-joined NEVER_SYNC set for informational visibility. */
+export function reportNeverSync(section: DoctorSection): void {
+  addItem(section, `${dim(infoGlyph)} never-sync items: ${[...NEVER_SYNC].join(', ')}`);
+}
+
+/** Probes for gitleaks on PATH; emits okGlyph with version, or failGlyph with ENOENT vs other-error distinction (sets exitCode=1). */
+export function reportGitleaksProbe(section: DoctorSection): void {
+  try {
+    const v = execFileSync('gitleaks', ['version'], { stdio: ['ignore', 'pipe', 'pipe'] })
+      .toString()
+      .trim();
+    addItem(section, `${green(okGlyph)} gitleaks: ${dim(v)}`);
+  } 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;
+  }
+}
+
+/** 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.format.ts

@@ -0,0 +1,68 @@
+import { failGlyph, red } from './color.ts';
+
+/**
+ * Bare `failGlyph` codepoint (`✗`, U+2717) without any WSL padding the
+ * `failGlyph` constant may carry. Header rendering composes its own
+ * spacing (`${red(failGlyph)} ${header}`), so the section-header path
+ * must use the unpadded codepoint to avoid a double space on WSL.
+ */
+const FAIL_GLYPH_BARE = '✗';
+
+/**
+ * Tree-style output builder for `cmdDoctor`. Doctor builds an ordered list of
+ * `DoctorSection`s, each reporter pushes plain-text items into the relevant
+ * section, then the orchestrator calls `renderDoctor` to emit a Claude Code
+ * `/doctor`-style tree (`Header` / `  ├ item` / `  └ last`) on stdout.
+ *
+ * Color and status glyphs (okGlyph/warnGlyph/failGlyph/infoGlyph) already
+ * live inside the item text; this module never re-colors or re-tokenizes.
+ * Sections with zero items are skipped at render time (no empty headers).
+ *
+ * Output goes directly through `console.log` rather than `utils.log` so the
+ * dim `ℹ︎` info glyph used by `pull` / `push` / `init` does NOT appear in
+ * doctor output (doctor has its own glyphs per row). Test assertions continue
+ * to spy on `console.log`.
+ */
+export type DoctorSection = {
+  header: string;
+  items: string[];
+};
+
+/** Construct an empty section with the given header. */
+export function section(header: string): DoctorSection {
+  return { header, items: [] };
+}
+
+/** Append one rendered line to a section. */
+export function addItem(s: DoctorSection, text: string): void {
+  s.items.push(text);
+}
+
+/**
+ * True when any item in the section contains the FAIL glyph.
+ * Color-wrapped failGlyph (`✗`) still contains the
+ * glyph as a substring, so this works for both color-on and color-off output.
+ */
+function sectionFailed(s: DoctorSection): boolean {
+  return s.items.some((line) => line.includes(failGlyph));
+}
+
+/**
+ * Emit the full doctor report. Skips empty sections, prefixes failed-section
+ * headers with a red `✗ ` glyph (U+2717, same as the per-item FAIL glyph so
+ * `grep -F '✗'` catches both row and header failures), and writes one blank
+ * line between rendered sections (no leading or trailing blank).
+ */
+export function renderDoctor(sections: DoctorSection[]): void {
+  const visible = sections.filter((s) => s.items.length > 0);
+  for (let i = 0; i < visible.length; i++) {
+    if (i > 0) console.log('');
+    const s = visible[i];
+    const header = sectionFailed(s) ? `${red(FAIL_GLYPH_BARE)} ${s.header}` : s.header;
+    console.log(header);
+    for (let j = 0; j < s.items.length; j++) {
+      const isLast = j === s.items.length - 1;
+      console.log(`${isLast ? '  └ ' : '  ├ '}${s.items[j]}`);
+    }
+  }
+}

package/src/commands.doctor.ts

@@ -0,0 +1,56 @@
+import {
+  loadAndReportSettings,
+  loadBaseSettings,
+  reportGitleaksProbe,
+  reportGitlinks,
+  reportHostAndPaths,
+  reportHostOverrides,
+  reportNeverSync,
+  reportPathMap,
+  reportRebaseClean,
+  reportRemote,
+  reportRepoState,
+  reportSharedLinks,
+} from './commands.doctor.checks.ts';
+import { renderDoctor, section } from './commands.doctor.format.ts';
+import { reportVersionCheck } from './commands.doctor.version.ts';
+
+/**
+ * Read-only health check for the nomad install on the current host. Each
+ * reporter pushes items into a named section; `renderDoctor` emits the final
+ * Claude Code `/doctor`-style tree on stdout via `console.log` (no `ℹ︎`
+ * prefix). FAILs in any section bubble up via `process.exitCode = 1` set
+ * inside the individual reporters, so a piped
+ * `nomad doctor 2>/dev/null` still exposes failures to scripts. Differs from
+ * `cmdPull` / `cmdPush` / `resumeCmd`, where FATAL is on stderr.
+ */
+export function cmdDoctor(): void {
+  const host = section('Host');
+  reportHostAndPaths(host);
+  reportRepoState(host);
+
+  const links = section('Shared links');
+  reportSharedLinks(links);
+
+  const settings = section('Settings');
+  const base = loadBaseSettings(settings);
+  const parsedSettings = loadAndReportSettings(settings);
+  reportHostOverrides(settings, base, parsedSettings);
+
+  const pathMap = section('Path map');
+  reportPathMap(pathMap);
+
+  const neverSync = section('Never-sync');
+  reportNeverSync(neverSync);
+
+  const repository = section('Repository');
+  reportGitleaksProbe(repository);
+  reportGitlinks(repository);
+  reportRemote(repository);
+  reportRebaseClean(repository);
+
+  const version = section('Version');
+  reportVersionCheck(version);
+
+  renderDoctor([version, host, links, settings, pathMap, neverSync, repository]);
+}

package/src/commands.doctor.version.ts

@@ -0,0 +1,190 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { dim, green, infoGlyph, okGlyph, warnGlyph, yellow } from './color.ts';
+import { addItem, type DoctorSection } from './commands.doctor.format.ts';
+import { HOME, UPSTREAM_REPO_SLUG } from './config.ts';
+
+/**
+ * Soft, offline-tolerant release-version check appended to `cmdDoctor`. Reads
+ * the local `package.json.version`, compares it to the latest release tag on
+ * the upstream GitHub repo (cached 1h, 3s curl timeout), and emits one of:
+ *   - `✓ version: <local> (latest)` when local == latest
+ *   - `⚠︎ version: <local> -> <latest>` when local < latest
+ *   - `ℹ︎ version: <local> (ahead of latest release <latest>)` when local > latest
+ * Every failure path (offline, curl missing, non-2xx, malformed JSON, missing
+ * `tag_name`, missing/unreadable package.json) is a SILENT skip; this module
+ * never sets `process.exitCode` and never writes to stderr.
+ */
+
+/** Absolute path to the cached latest-tag entry. Sits under HOME so tests that
+ * override `process.env.HOME` get a sandboxed cache for free. */
+const CACHE_PATH = join(HOME, '.cache', 'claude-nomad', 'version-check.json');
+
+/** Cache TTL in milliseconds. Matches GitHub's 1-hour anonymous rate-limit
+ * reset window: long enough to collapse `nomad doctor` debugging bursts into a
+ * single fetch, short enough that new releases surface within the same day. */
+const CACHE_TTL_MS = 60 * 60 * 1000;
+
+/** Strict-semver regex used to gate both the local version and the latest tag
+ * fed into `compareSemver`. Pre-release suffixes like `-dev` are rejected at
+ * the regex; downstream callers strip them off before comparing. */
+const STRICT_SEMVER = /^\d+\.\d+\.\d+$/;
+
+/** Capturing variant of `STRICT_SEMVER` used to peel a strict-semver prefix
+ * off a pre-release version string (e.g. `0.12.0` out of `0.12.0-dev`). The
+ * trailing `(?:[-+]|$)` anchor rejects malformed inputs like `1.2.3foo` or
+ * `1.2.3.4` that would otherwise be silently truncated to `1.2.3` and yield
+ * a false PASS against an identical `latest`. */
+const STRICT_SEMVER_PREFIX = /^(\d+\.\d+\.\d+)(?:[-+]|$)/;
+
+/** Shape of the on-disk cache entry. Both fields are validated structurally
+ * in `loadCache` before use (typeof + finiteness + regex). */
+type CacheEntry = { checked_at: number; latest: string };
+
+/**
+ * Strict triple-segment semver comparison: returns -1 when `a < b`, 0 when
+ * equal, 1 when `a > b`. BOTH inputs must match `/^\d+\.\d+\.\d+$/`; any
+ * non-strict input causes a 0 return, which the caller treats as "skip the
+ * diagnostic" (silent-skip on undecidable comparisons is intentional, mirrors
+ * the rest of the version-check codepath that errs on the side of saying
+ * nothing). Pure, no side effects.
+ */
+export function compareSemver(a: string, b: string): -1 | 0 | 1 {
+  if (!STRICT_SEMVER.test(a) || !STRICT_SEMVER.test(b)) return 0;
+  const [aMajor, aMinor, aPatch] = a.split('.').map((x) => Number.parseInt(x, 10));
+  const [bMajor, bMinor, bPatch] = b.split('.').map((x) => Number.parseInt(x, 10));
+  if (aMajor !== bMajor) return aMajor < bMajor ? -1 : 1;
+  if (aMinor !== bMinor) return aMinor < bMinor ? -1 : 1;
+  if (aPatch !== bPatch) return aPatch < bPatch ? -1 : 1;
+  return 0;
+}
+
+/**
+ * Locate and parse the local `package.json` (one directory above this source
+ * module). Returns the `version` string when present and non-empty, otherwise
+ * `null`. Any throw (missing file, parse error, etc.) becomes a `null` return
+ * so the caller silently skips the diagnostic.
+ */
+function readLocalVersion(): string | null {
+  try {
+    const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+    const parsed = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: unknown };
+    if (typeof parsed.version === 'string' && parsed.version.length > 0) {
+      return parsed.version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load the cached latest-tag entry. Returns the parsed entry when the file
+ * exists, parses cleanly, and matches the expected shape (`checked_at` finite
+ * number, `latest` strict-semver string); any failure surfaces as `null` so
+ * the caller falls through to `fetchLatestTag`. Treating malformed cache as a
+ * miss is the safer default than crashing or surfacing the error.
+ */
+function loadCache(): CacheEntry | null {
+  try {
+    if (!existsSync(CACHE_PATH)) return null;
+    const parsed = JSON.parse(readFileSync(CACHE_PATH, 'utf8')) as Partial<CacheEntry>;
+    if (typeof parsed.checked_at !== 'number' || !Number.isFinite(parsed.checked_at)) {
+      return null;
+    }
+    if (typeof parsed.latest !== 'string' || !STRICT_SEMVER.test(parsed.latest)) {
+      return null;
+    }
+    return { checked_at: parsed.checked_at, latest: parsed.latest };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the latest tag plus a `Date.now()` stamp to the cache file. Errors
+ * (read-only filesystem, missing parent dir despite `mkdirSync`, etc.) are
+ * swallowed so a cache-write failure never breaks `nomad doctor` output.
+ */
+function saveCache(latest: string): void {
+  try {
+    mkdirSync(dirname(CACHE_PATH), { recursive: true });
+    writeFileSync(CACHE_PATH, JSON.stringify({ checked_at: Date.now(), latest }));
+  } catch {
+    // Silent on cache-write failure (locked design): the user-facing
+    // diagnostic still emits; the cost is one extra network round-trip on
+    // the next invocation.
+  }
+}
+
+/**
+ * Fetch the latest release tag from the upstream GitHub releases API. Uses
+ * `execFileSync('curl', ...)` rather than `node:https` because curl honors
+ * system proxies, respects the `-m` timeout reliably, and is already a
+ * required dependency on every supported host (push uses gitleaks; pull uses
+ * git). 3-second timeout, fail-fast on non-2xx (`-f`), silent (`-s`), follow
+ * redirects (`-L`). Returns `null` on ANY failure path including a missing
+ * `tag_name` field or a tag that fails strict-semver validation after the
+ * leading `v` strip. Release tags ship as `v<semver>` per
+ * `release-please-config.json`'s `include-v-in-tag: true`.
+ */
+function fetchLatestTag(): string | null {
+  try {
+    const url = `https://api.github.com/repos/${UPSTREAM_REPO_SLUG}/releases/latest`;
+    const raw = execFileSync(
+      'curl',
+      ['-fsSL', '-m', '3', '-H', 'Accept: application/vnd.github+json', url],
+      { stdio: ['ignore', 'pipe', 'pipe'] },
+    ).toString();
+    const parsed = JSON.parse(raw) as { tag_name?: unknown };
+    if (typeof parsed.tag_name !== 'string') return null;
+    const tag = parsed.tag_name.startsWith('v') ? parsed.tag_name.slice(1) : parsed.tag_name;
+    if (!STRICT_SEMVER.test(tag)) return null;
+    return tag;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Emit a single, non-fatal version diagnostic for `nomad doctor` by comparing the local package.json version to the latest upstream release.
+ *
+ * Logs one of:
+ * - `✓ version: <local> (latest)` when the versions match
+ * - `⚠︎ version: <local> -> <latest> (run \`nomad update\`)` when the local version is behind
+ * - `ℹ︎ version: <local> (ahead of latest release <latest>)` when the local version is ahead
+ *
+ * Any failure to read the local version, retrieve or parse the latest release, or use the cache results in no output and does not change `process.exitCode`.
+ */
+export function reportVersionCheck(section: DoctorSection): void {
+  const local = readLocalVersion();
+  if (local === null) return;
+  // Strip pre-release suffix for the COMPARISON. The display value keeps the
+  // full string so e.g. `0.12.0-dev (ahead of latest release 0.11.2)` is
+  // readable.
+  const localPure = STRICT_SEMVER_PREFIX.exec(local)?.[1] ?? null;
+  if (localPure === null) return;
+
+  let latest: string | null = null;
+  const cached = loadCache();
+  if (cached !== null && Date.now() - cached.checked_at < CACHE_TTL_MS) {
+    latest = cached.latest;
+  }
+  if (latest === null) {
+    latest = fetchLatestTag();
+    if (latest === null) return;
+    saveCache(latest);
+  }
+
+  const cmp = compareSemver(localPure, latest);
+  if (cmp === 0) {
+    addItem(section, `${green(okGlyph)} version: ${local} (latest)`);
+  } else if (cmp === -1) {
+    addItem(section, `${yellow(warnGlyph)} version: ${local} -> ${latest} (run \`nomad update\`)`);
+  } else {
+    addItem(section, `${dim(infoGlyph)} version: ${local} (ahead of latest release ${latest})`);
+  }
+}