baldart 4.37.0 → 4.38.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.38.0] - 2026-06-15
+
+**`baldart doctor` now checks whether the external tools BALDART installs are out of date upstream, and offers a one-command upgrade.** BALDART installs external tools into consumer machines but **pins none of them** — `pipx install graphifyy`, `npm install -g typescript-language-server`, … all grab "latest" at install time, and neither pipx nor npm ever auto-upgrades. So a consumer who installed months ago is frozen on whatever version they got, and never receives upstream security/correctness fixes; the `add`/`update`/`configure` flows can't help because they only run at install time. Concrete trigger: Graphify shipped `0.8.37` (SSRF guard thread-safety + prompt-injection mitigation + a macOS NFC/NFD re-extraction loop fix), `0.8.38` (`calls` edge-direction + JS/TS default import/export + tsconfig `paths` correctness) and `0.8.39` (a `graphify affected` `KeyError` crash fix — a command BALDART agents actually invoke) — all invisible to a frozen install. This release adds the continuous currency check that was missing: the tool-dependency analogue of the `baldart` CLI's own `UpdateNotifier`. **MINOR** (new doctor diagnostic + self-heal action; backwards-compatible — network-gated and skipped under `--offline`, zero output when every tool is current, no install/layout change, no `baldart.config.yml` key ⇒ schema-propagation rule N/A).
+
+### Added
+
+- **`src/utils/tool-currency.js`** — external-tool currency prober. `probeAll()` returns one record per managed tool BALDART can query against its upstream registry, comparing the installed version to the latest published one. Probes today: **Graphify** (`graphifyy` on PyPI, gated on `features.has_code_graph` + binary present) and **LSP language servers** (gated on `features.has_lsp_layer`; `npm-global` adapters queried via the npm registry, `system` adapters — gopls, rust-analyzer — reported `unknown` with their canonical `@latest` reinstall command rather than a probe we can't cheaply run). Invariants mirror the rest of doctor's probes: **best-effort** (a failed probe is omitted, never throws, never blocks), **honest** (`status: 'outdated'` only with BOTH versions known and installed < latest — `unknown`/`current` are never surfaced as a nag), **offline-aware** (the caller skips it entirely under `--offline`).
+- **`src/utils/http.js`** — dependency-free `getJson(url, {timeoutMs})` over `https` core (no reliance on the Node 18 `fetch` flag), resolving `null` on any failure. Used by the currency layer to read registry metadata.
+- **`src/utils/semver-lite.js`** — tolerant dependency-free version comparison (`cmpVersions`) for heterogeneous registry strings (`0.8.39`, `v1.2`, `4.3.3`, `1.2.3-rc1`); returns `0` (no nag) on unparseable input. Shared by `graphify-installer` and `tool-currency`.
+- **`src/utils/graphify-installer.js`** — `checkUpgrade()` (installed CLI vs latest `graphifyy` on PyPI; best-effort, async, never nags on uncertainty) and `upgrade()` (`pipx upgrade graphifyy`, falling back to `pip --user --upgrade`; never throws).
+- **`src/commands/doctor.js`** — new probe (`state.toolCurrency`, network-gated on `!--offline`) and one non-blocking upgrade action per tool **confirmed** behind upstream (`tool-upgrade:<tool>`, `autoOk: false` — upgrading a system-level tool warrants explicit intent). Auto-upgradable tools (pipx/npm) run the upgrade in place; non-auto ones (system toolchains) print the canonical `@latest` command. `unknown`/`current` tools produce no action — no nag without proof.
+
 ## [4.37.0] - 2026-06-15
 
 **`baldart doctor` now detects and reaps orphaned MCP-server processes left behind by BALDART's Codex calls.** A real machine hit ~100% CPU from ~45 orphaned `@playwright/mcp` processes (plus stray `obsidian-mcp-server` instances), all children of OpenAI Codex CLI sessions that had since died. Root cause traced through the Codex companion plugin: every BALDART Codex finder call (`/new`, `new2`, `/codexreview`, the cron review engine) drives `codex app-server` via `codex-companion.mjs`, which attaches to a **shared, `detached + unref'd` broker** (`broker-lifecycle.mjs`). That broker spawns every MCP server declared in the user's `~/.codex/config.toml` (Playwright, Figma, …) as its own children; when the broker dies the OS reparents those MCP servers to init (ppid 1) and they keep running — an `@playwright/mcp` can peg a core for days. The leak compounds across sessions. We cannot suppress the MCP spawn per-call (the companion attaches to a broker it does not control, and exposes no shutdown verb), so the fix is a **safe reaper** owned by the doctor. **MINOR** (new doctor diagnostic + self-heal action; backwards-compatible — zero output on a clean machine, no install/layout change, not a `baldart.config.yml` key ⇒ schema-propagation rule N/A).

package/README.md

@@ -508,6 +508,14 @@ MCP servers from `~/.codex/config.toml` (Playwright, …) and leaks them to init
 orphaned MCP servers (and their browser children) directly via syscall; the live
 `codex app-server` broker is never touched.
 
+Since v4.38.0 it also checks **external-tool version currency** — BALDART pins
+none of the tools it installs (`graphifyy` via pipx, language servers via npm),
+and pipx/npm never auto-upgrade, so an old install silently misses upstream
+security/correctness fixes. The doctor probes the managed tools against their
+registries (PyPI / npm) and surfaces a non-blocking one-command upgrade for any
+confirmed behind upstream (e.g. `Upgrade Graphify 0.8.36 → 0.8.39`). Network-gated
+— skipped under `--offline`, silent when everything is current.
+
 ```bash
 npx baldart            # diagnostic + interactive prompts
 npx baldart --auto     # CI-friendly: skip y/n; error out on ambiguity

package/VERSION

@@ -1 +1 @@
-4.37.0
+4.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.37.0",
+  "version": "4.38.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/doctor.js

@@ -33,6 +33,7 @@ const Hooks = require('../utils/hooks');
 const GitHooks = require('../utils/githooks');
 const LspInstaller = require('../utils/lsp-installer');
 const GraphifyInstaller = require('../utils/graphify-installer');
+const ToolCurrency = require('../utils/tool-currency');
 const CodexOrphans = require('../utils/codex-orphans');
 const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
@@ -390,6 +391,24 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on graph probe */ }
 
+    // ---- External-tool version currency (since v4.38.0) ----------------
+    // BALDART pins none of the external tools it installs (graphifyy via pipx,
+    // language servers via npm/system) — pipx/npm never auto-upgrade, so a
+    // consumer installed months ago is frozen and never receives upstream
+    // security/correctness fixes. Probe the managed tools against their
+    // registries and let the planner surface a non-blocking upgrade. Network;
+    // skipped entirely under --offline. Best-effort — never blocks doctor.
+    state.toolCurrency = [];
+    if (!opts.offline) {
+      try {
+        state.toolCurrency = await ToolCurrency.probeAll({
+          cwd,
+          config: (config && !config.__malformed) ? config : null,
+          lspInstalled: state.lspInstalled,
+        });
+      } catch (_) { /* never block doctor on currency probe */ }
+    }
+
     // ---- Orphaned MCP servers from Codex calls (since v4.37.0) ---------
     // BALDART's Codex finder calls (/new, new2, /codexreview, cron engine)
     // drive `codex app-server` via the companion plugin. That broker spawns the
@@ -799,6 +818,31 @@ function planActions(state) {
     });
   }
 
+  // External-tool version currency (since v4.38.0). One non-blocking upgrade
+  // action per managed tool confirmed behind upstream — the tool-dependency
+  // analogue of the `baldart` CLI's own UpdateNotifier. `unknown`/`current`
+  // records are NOT surfaced (no nag without proof). Auto-upgradable records
+  // (pipx/npm) get a runnable action; non-auto ones (system toolchains) print
+  // the canonical `@latest` command without auto-running it.
+  for (const rec of ToolCurrency.outdated(state.toolCurrency)) {
+    actions.push({
+      key: `tool-upgrade:${rec.tool}`,
+      label: `Upgrade ${rec.label} ${rec.installed} → ${rec.latest}`,
+      why: `${rec.label} is installed at ${rec.installed} but ${rec.latest} is published (${rec.source}). BALDART pins no external-tool versions and ${rec.autoUpgradable ? 'pipx/npm' : 'the system package manager'} never auto-upgrades, so this install is missing every upstream fix since ${rec.installed}. Upgrade with: \`${rec.upgradeCommand}\`.`,
+      autoOk: false, // upgrading a system-level tool warrants explicit intent
+      run: async () => {
+        if (rec.autoUpgradable && typeof rec.upgrade === 'function') {
+          const r = rec.upgrade();
+          if (r && r.ok) UI.success(`${rec.label} upgraded${r.method ? ` via ${r.method}` : ''}.`);
+          else UI.warning(`Upgrade failed: ${(r && r.error) || 'unknown error'}. Run \`${rec.upgradeCommand}\` manually.`);
+        } else {
+          UI.info(`Run to upgrade ${rec.label}:`);
+          console.log(`    ${rec.upgradeCommand}`);
+        }
+      },
+    });
+  }
+
   // Orphaned MCP servers from Codex calls (since v4.37.0). BALDART's Codex
   // finder calls leave behind MCP-server processes (Playwright, obsidian-mcp, …)
   // reparented to init when their `codex app-server` broker dies. They keep

package/src/utils/graphify-installer.js

@@ -2,6 +2,8 @@ const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const UI = require('./ui');
+const { getJson } = require('./http');
+const { cmpVersions } = require('./semver-lite');
 
 /**
  * High-level installer/wrapper for the Graphify code-knowledge-graph layer,
@@ -47,6 +49,51 @@ class GraphifyInstaller {
     }
   }
 
+  // ── Version currency (since v4.38.0) ──────────────────────────────────────
+
+  /**
+   * Compare the installed `graphify` CLI against the latest `graphifyy` on
+   * PyPI. BEST-EFFORT: returns `{ installed, latest, outdated, source }` where
+   * any field may be `null` when it cannot be determined (offline, CLI absent,
+   * PyPI unreachable). `outdated` is only `true` with BOTH versions known and
+   * installed < latest — never nags on uncertainty. Async (network); never
+   * throws. The upgrade command is `pipx upgrade graphifyy` (see `upgrade()`).
+   */
+  async checkUpgrade({ timeoutMs = 4000 } = {}) {
+    const installed = this.verify().version || null;
+    let latest = null;
+    try {
+      const data = await getJson('https://pypi.org/pypi/graphifyy/json', { timeoutMs });
+      latest = (data && data.info && data.info.version) || null;
+    } catch { latest = null; }
+    const outdated = !!(installed && latest && cmpVersions(installed, latest) < 0);
+    return { tool: 'graphify', installed, latest, outdated, source: 'pypi:graphifyy' };
+  }
+
+  /**
+   * Upgrade the Graphify CLI in place via the same package manager that can
+   * install it (pipx preferred, then pip --user). Returns `{ ok, method?,
+   * error? }`. Never throws. Safe to run unattended (no sudo); the command
+   * layer still asks for explicit intent before invoking it.
+   */
+  upgrade({ spinner = true } = {}) {
+    const attempts = [];
+    if (this._hasCmd('pipx')) attempts.push({ method: 'pipx', cmd: 'pipx upgrade graphifyy' });
+    if (this._hasCmd('pip3')) attempts.push({ method: 'pip3 --user', cmd: 'pip3 install --user --upgrade graphifyy' });
+    if (this._hasCmd('pip')) attempts.push({ method: 'pip --user', cmd: 'pip install --user --upgrade graphifyy' });
+    if (!attempts.length) return { ok: false, error: 'no pipx/pip found on PATH' };
+    const sp = spinner ? UI.spinner('Upgrading Graphify (graphifyy)…').start() : null;
+    for (const a of attempts) {
+      try {
+        execSync(a.cmd, { stdio: 'pipe', timeout: 300000 });
+        if (sp) sp.succeed(`Upgraded Graphify via ${a.method}`);
+        return { ok: true, method: a.method };
+      } catch (_) { /* try next */ }
+    }
+    if (sp) sp.fail('Graphify upgrade failed');
+    return { ok: false, error: `upgrade failed (tried: ${attempts.map(a => a.method).join(', ')}). Run \`pipx upgrade graphifyy\` manually.` };
+  }
+
   /** Absolute path to the graph artifact for a graphed root. */
   graphPath(root = this.cwd, outputDir = 'graphify-out') {
     return path.join(root, outputDir, 'graph.json');

package/src/utils/http.js

@@ -0,0 +1,35 @@
+const https = require('https');
+
+/**
+ * Minimal dependency-free JSON GET with a hard timeout.
+ *
+ * Used by the external-tool currency layer (`tool-currency.js`,
+ * `graphify-installer.checkUpgrade`) to ask a package registry "what is the
+ * latest published version?". It is deliberately tiny and BEST-EFFORT:
+ *   - resolves `null` on ANY failure (DNS, TLS, non-200, bad JSON, timeout),
+ *   - never throws, never rejects — currency checks must never break a flow.
+ *
+ * `https` core only (no `node-fetch`, no relying on global `fetch` which is
+ * still flagged on the Node 18 floor). HTTP is not supported on purpose:
+ * registry metadata is always HTTPS.
+ */
+function getJson(url, { timeoutMs = 4000, headers = {} } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (val) => { if (!settled) { settled = true; resolve(val); } };
+    let req;
+    try {
+      req = https.get(url, { headers: { 'User-Agent': 'baldart-doctor', Accept: 'application/json', ...headers } }, (res) => {
+        if (res.statusCode !== 200) { res.resume(); return done(null); }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (c) => { body += c; if (body.length > 5_000_000) { req.destroy(); done(null); } });
+        res.on('end', () => { try { done(JSON.parse(body)); } catch { done(null); } });
+      });
+    } catch { return done(null); }
+    req.on('error', () => done(null));
+    req.setTimeout(timeoutMs, () => { req.destroy(); done(null); });
+  });
+}
+
+module.exports = { getJson };

package/src/utils/semver-lite.js

@@ -0,0 +1,38 @@
+/**
+ * Tolerant, dependency-free version comparison for the external-tool currency
+ * layer. NOT a full semver implementation — registry version strings from
+ * heterogeneous tools (PyPI `0.8.39`, a language server's `4.3.3`, a `v1.2`
+ * prefix, an `1.2.3-rc1` suffix) only need a stable "is A behind B?" ordering.
+ *
+ * Rules:
+ *   - leading `v`/`graphify ` style noise is stripped, numeric dotted core is
+ *     compared field by field (missing fields treated as 0, so `1.2` < `1.2.1`),
+ *   - any non-numeric suffix (`-rc1`, `+build`) is ignored for ordering — a
+ *     pre-release is treated as equal to its release core, which is acceptable
+ *     for a "should I upgrade?" hint (we never auto-act on a tie),
+ *   - unparseable input yields `null` from `parse`, and `cmpVersions` returns
+ *     `0` (treat as equal → no nag) when either side is unparseable.
+ */
+function parse(v) {
+  if (v == null) return null;
+  const m = String(v).match(/(\d+(?:\.\d+)*)/);
+  if (!m) return null;
+  return m[1].split('.').map((n) => parseInt(n, 10));
+}
+
+/** -1 if a<b, 1 if a>b, 0 if equal/unknown. Never throws. */
+function cmpVersions(a, b) {
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return 0;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+module.exports = { parse, cmpVersions };

package/src/utils/tool-currency.js

@@ -0,0 +1,148 @@
+const { execSync } = require('child_process');
+const { cmpVersions } = require('./semver-lite');
+const GraphifyInstaller = require('./graphify-installer');
+const { REGISTRY } = require('./lsp-adapters');
+
+/**
+ * External-tool currency layer (since v4.38.0).
+ *
+ * BALDART installs external tools into consumer machines but pins NONE of them
+ * (`pipx install graphifyy`, `npm install -g typescript-language-server`, …
+ * all grab "latest" at install time). pipx/npm never auto-upgrade, so a
+ * consumer that installed months ago is frozen — security/correctness fixes
+ * never reach them. The `add`/`update`/`configure` flows can't help: they run
+ * at install time, not continuously.
+ *
+ * This module is the missing continuous check. `baldart doctor` probes the
+ * tools it manages against their upstream registries and surfaces a
+ * non-blocking "X is N versions behind — upgrade with: …" action. It is the
+ * tool-dependency analogue of `UpdateNotifier` (which already does this for the
+ * `baldart` npm package itself).
+ *
+ * Invariants (mirroring the rest of doctor's probes):
+ *   - BEST-EFFORT: every probe resolves to a record or is omitted; a failed
+ *     probe never throws and never blocks doctor.
+ *   - HONEST: `status` is `'outdated'` only when BOTH installed and latest are
+ *     known and installed < latest. When latest can't be fetched (offline,
+ *     registry down, system package manager we can't query) the record is
+ *     `'unknown'` — we never claim up-to-date we can't prove, and never nag.
+ *   - OFFLINE-AWARE: the caller skips `probeAll` entirely under `--offline`.
+ *
+ * Record shape:
+ *   { tool, label, installed, latest, status: 'outdated'|'current'|'unknown',
+ *     upgradeCommand, autoUpgradable, source, upgrade? }
+ * `upgrade` (when present) is a thunk doctor can run to perform the upgrade.
+ */
+
+/** Run a command and pull the first dotted-numeric version token from stdout. */
+function _probeBinaryVersion(cmd, timeoutMs = 8000) {
+  try {
+    const out = execSync(cmd, { stdio: ['ignore', 'pipe', 'pipe'], timeout: timeoutMs }).toString();
+    const m = out.match(/(\d+\.\d+(?:\.\d+)?)/);
+    return m ? m[1] : null;
+  } catch { return null; }
+}
+
+/** `npm view <pkg> version` → latest published version, or null. Network. */
+function _npmLatest(pkg, timeoutMs = 8000) {
+  try {
+    return execSync(`npm view ${pkg} version`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: timeoutMs })
+      .toString().trim() || null;
+  } catch { return null; }
+}
+
+/** Build the Graphify currency record (only when the layer is on + present). */
+async function _graphifyRecord(cwd, config, timeoutMs) {
+  if (!(config && config.features && config.features.has_code_graph === true)) return null;
+  const gi = new GraphifyInstaller(cwd);
+  if (!gi.detect()) return null; // a missing binary is the install action's job, not currency
+  const r = await gi.checkUpgrade({ timeoutMs });
+  return {
+    tool: 'graphify',
+    label: 'Graphify (graphifyy)',
+    installed: r.installed,
+    latest: r.latest,
+    status: r.outdated ? 'outdated' : (r.installed && r.latest ? 'current' : 'unknown'),
+    upgradeCommand: 'pipx upgrade graphifyy',
+    autoUpgradable: true,
+    source: 'pypi:graphifyy',
+    upgrade: () => gi.upgrade({ spinner: false }),
+  };
+}
+
+/**
+ * Build LSP language-server currency records. Only `npm-global` adapters can
+ * be queried generically (npm registry + `<binary> --version`). `system`-mode
+ * servers (gopls, rust-analyzer) live under per-language toolchains we don't
+ * version-probe — we emit an `'unknown'` record carrying the canonical
+ * `@latest` reinstall command so the user can refresh on their terms.
+ */
+function _lspRecords(cwd, config, lspInstalled, timeoutMs) {
+  if (!(config && config.features && config.features.has_lsp_layer === true)) return [];
+  const names = Array.isArray(lspInstalled) ? lspInstalled : [];
+  const records = [];
+  for (const name of names) {
+    const Cls = REGISTRY[name];
+    if (!Cls) continue;
+    let adapter;
+    try { adapter = new Cls(cwd); } catch { continue; }
+    const installed = _probeBinaryVersion(adapter.verifyCommand(), timeoutMs);
+    if (!installed) continue; // broken/absent server is the LSP-repair action's job
+    if (adapter.installMode === 'npm-global') {
+      // First whitespace-separated token of npmPackage is the versioned one.
+      const pkg = String(adapter.npmPackage || adapter.binary).split(/\s+/)[0];
+      const latest = _npmLatest(pkg, timeoutMs);
+      const outdated = !!(latest && cmpVersions(installed, latest) < 0);
+      records.push({
+        tool: `lsp:${name}`,
+        label: `${adapter.label} LSP (${pkg})`,
+        installed,
+        latest,
+        status: outdated ? 'outdated' : (latest ? 'current' : 'unknown'),
+        upgradeCommand: adapter.installCommand(), // already pins @latest
+        autoUpgradable: true,
+        source: `npm:${pkg}`,
+        upgrade: () => {
+          try { execSync(adapter.installCommand(), { stdio: 'pipe', cwd, timeout: 300000 }); return { ok: true, method: 'npm -g' }; }
+          catch (e) { return { ok: false, error: (e.message || '').split('\n')[0] }; }
+        },
+      });
+    } else {
+      records.push({
+        tool: `lsp:${name}`,
+        label: `${adapter.label} LSP (${adapter.binary})`,
+        installed,
+        latest: null,
+        status: 'unknown', // system toolchain — can't cheaply ask "latest"
+        upgradeCommand: adapter.installCommand(), // e.g. `... @latest`
+        autoUpgradable: false,
+        source: 'system',
+      });
+    }
+  }
+  return records;
+}
+
+/**
+ * Probe every external tool BALDART manages for version currency.
+ * Returns an array of records (possibly empty). Async (network). Never throws.
+ * The caller is responsible for skipping this under `--offline`.
+ */
+async function probeAll({ cwd = process.cwd(), config = null, lspInstalled = [], timeoutMs = 6000 } = {}) {
+  const records = [];
+  try {
+    const g = await _graphifyRecord(cwd, config, timeoutMs);
+    if (g) records.push(g);
+  } catch { /* best-effort */ }
+  try {
+    records.push(..._lspRecords(cwd, config, lspInstalled, timeoutMs));
+  } catch { /* best-effort */ }
+  return records;
+}
+
+/** Convenience: only the records that are confirmed behind upstream. */
+function outdated(records) {
+  return (records || []).filter((r) => r.status === 'outdated');
+}
+
+module.exports = { probeAll, outdated, _probeBinaryVersion, _npmLatest };