baldart 4.40.0 → 4.41.0

package/src/commands/configure.js

@@ -6,6 +6,8 @@ const toolAdapters = require('../utils/tool-adapters');
 const LspInstaller = require('../utils/lsp-installer');
 const lspAdapters = require('../utils/lsp-adapters');
 const GraphifyInstaller = require('../utils/graphify-installer');
+const ToolchainInstaller = require('../utils/toolchain-installer');
+const toolchainAdapters = require('../utils/toolchain-adapters');
 
 const CONFIG_FILE = 'baldart.config.yml';
 // The subtree pull copies the entire BALDART repo (which itself has a
@@ -459,6 +461,12 @@ function detect(cwd = process.cwd()) {
       // Drives the default for the configure prompt; the install/build side
       // effects only run in the interactive branch (see below).
       has_code_graph: new GraphifyInstaller(cwd).detect(),
+      // Curated toolchain recommended (default Y) when this is a JS/TS project
+      // AND no incumbent linter/formatter is present — we never surprise a repo
+      // that already has ESLint/Prettier (that path PROPOSES migration instead).
+      // Drives the prompt default; install side effects only run interactively.
+      has_toolchain: toolchainAdapters.detectAll(cwd).length > 0
+        && toolchainAdapters.detectIncumbents(cwd).length === 0,
     },
     tools: {
       enabled: toolAdapters.defaultEnabled(cwd)
@@ -627,6 +635,7 @@ async function interactivePrompts(merged, detected) {
     ['has_wiki_overlay', 'Project has LLM-wiki overlay (docs/wiki/)?'],
     ['has_lsp_layer', 'Enable LSP symbol-search layer? (recommended for large codebases)'],
     ['has_code_graph', 'Enable Graphify code-knowledge-graph layer? (structural queries + wiki feed; recommended for large codebases)'],
+    ['has_toolchain', 'Enable curated dev toolchain? (Biome format+lint+import; agents run it in the quality gates — recommended for JS/TS)'],
     ['has_e2e_review', 'Enable BLOCKING end-to-end review (Phase 2.6 of /new invokes /e2e-review — functional + visual fidelity gate)?'],
   ]) {
     const [key, question] = flag;
@@ -910,6 +919,78 @@ async function interactivePrompts(merged, detected) {
     }
   }
 
+  // ---- Curated dev toolchain (since v4.40.0) ----------------------------
+  // Opinionated-but-askable: on a JS/TS project with no incumbent, configure
+  // PRESELECTS Biome and installs it (the user opts out). If ESLint/Prettier
+  // are present, it NEVER auto-installs — it PROPOSES a (manual) migration.
+  // Install side effects run only here (interactive); CI / `--yes` writes the
+  // flag and `baldart doctor` backfills. Non-destructive throughout: configs
+  // are written only when absent; incumbents are never touched.
+  merged.toolchain = merged.toolchain || {
+    installed_tools: [],
+    commands: { lint: '', format: '', typecheck: '', test: '', test_related: '', build: '', audit: '' },
+    auto_verify: true,
+  };
+  if (merged.features.has_toolchain === true) {
+    UI.section('Curated dev toolchain (Biome — format + lint + import organizer)');
+    const ti = new ToolchainInstaller(process.cwd());
+    if (!ti.hasPackageJson()) {
+      UI.info('No package.json found — the JS/TS toolchain is not applicable here. Skipping (the flag stays on; re-run configure after adding package.json, or run /toolchain-bootstrap).');
+    } else {
+      const recommended = ti.recommend();   // clean installs (no incumbent conflict)
+      const migs = ti.migrations();          // curated tools blocked by an incumbent
+      const toInstall = [];
+
+      // Clean path — preselect (default Y).
+      if (recommended.length) {
+        const want = await UI.confirm(`Install the curated toolchain (${recommended.join(', ')}) as devDependencies now?`, true);
+        if (want) toInstall.push(...recommended);
+        else UI.info('Skipping install. Run `/toolchain-bootstrap` later — `baldart doctor` will flag the missing tools.');
+      }
+
+      // Migration path — never automatic; propose per blocked tool (default N).
+      for (const m of migs) {
+        UI.warning(`Detected ${m.replaces.join(' + ')} — ${m.tool} would replace ${m.replaces.length > 1 ? 'them' : 'it'} with a single, faster tool.`);
+        const hint = m.tool === 'biome'
+          ? ' (preview the change first: `npx biome migrate eslint --write` / `npx biome migrate prettier --write`)'
+          : (m.replaces.includes('husky') ? ' (your .husky/ hooks are NOT touched — hand the hooks over to lefthook yourself)' : '');
+        UI.info(`Your existing ${m.replaces.join('/')} config is NOT touched.${hint}`);
+        const migrate = await UI.confirm(`Migrate to ${m.tool} now?`, false);
+        if (migrate) toInstall.push(m.tool);
+        else UI.info(`Keeping ${m.replaces.join('/')}. Toolchain commands fall back to the project default for this gate.`);
+      }
+
+      if (toInstall.length) {
+        const res = ti.install({ tools: toInstall });
+        for (const t of res.installed) UI.success(`Installed ${t}.`);
+        for (const f of res.failed) UI.warning(`Install failed for ${f.tool}: ${f.error}`);
+        for (const s of res.skipped) UI.info(`Skipped ${s.tool}: ${s.reason}`);
+      }
+
+      // Resolve the active tool set (every in-scope tool usable now) → configs + commands.
+      const active = ti.activeTools();
+      if (active.length) {
+        const cfgRes = ti.initConfigs({ tools: active });
+        for (const c of cfgRes) {
+          if (c.status === 'written') UI.success(`Wrote default ${c.tool} config.`);
+          else if (c.status === 'skipped' && c.reason === 'exists') UI.info(`Kept existing ${c.tool} config (not overwritten).`);
+        }
+        merged.toolchain.installed_tools = active;
+        const cmds = ti.commandsFor(active);
+        for (const k of Object.keys(cmds)) {
+          if (cmds[k]) merged.toolchain.commands[k] = cmds[k];
+        }
+        const cert = ti.certify({ tools: active });
+        if (cert.ok) UI.success(`Toolchain CERTIFIED: ${active.join(', ')} resolve via npx; gate commands written to toolchain.commands.*`);
+        else UI.warning(`Toolchain NOT fully certified — ${cert.perTool.filter((t) => !t.devDep).map((t) => t.tool).join(', ')} did not resolve. Run \`baldart doctor\` or \`/toolchain-bootstrap\`.`);
+      }
+    }
+  } else {
+    // Feature disabled — keep installed_tools honest (we never uninstall, but we
+    // do not advertise tools the consumer opted out of).
+    merged.toolchain.installed_tools = [];
+  }
+
   UI.section('Stack (autodetected from package.json — confirm or override)');
   const charting = merged.stack.charting;
   const chartingCanonical = await promptForKey(

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 ToolchainInstaller = require('../utils/toolchain-installer');
 const ToolCurrency = require('../utils/tool-currency');
 const CodexOrphans = require('../utils/codex-orphans');
 const UpdateNotifier = require('../utils/update-notifier');
@@ -391,6 +392,39 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on graph probe */ }
 
+    // ---- Curated dev toolchain (since v4.41.0) -------------------------
+    // configure's install side effects run only interactively (a devDep install
+    // is never run silently in CI). So doctor is the backfill: it installs the
+    // missing tools and restores any default config that went missing — all
+    // gated on features.has_toolchain, all non-destructive.
+    state.toolchainEnabled = false;
+    state.toolchainMissingTools = [];
+    state.toolchainMissingConfigs = [];
+    try {
+      // Flag-gated (like the graph layer): enabling the feature means "I want
+      // this layer", so doctor backfills the install even when CI / `--yes`
+      // wrote the flag with an empty installed_tools (it never installs in CI).
+      if (config && !config.__malformed && config.features && config.features.has_toolchain === true) {
+        state.toolchainEnabled = true;
+        const ti = new ToolchainInstaller(cwd);
+        if (ti.hasPackageJson()) {
+          const declared = (config.toolchain && Array.isArray(config.toolchain.installed_tools))
+            ? config.toolchain.installed_tools : [];
+          if (declared.length) {
+            // Declared set: re-verify it resolves + its config is present.
+            const cert = ti.certify({ tools: declared });
+            state.toolchainMissingTools = cert.perTool.filter((t) => !t.devDep).map((t) => t.tool);
+            if (config.toolchain && config.toolchain.auto_verify !== false) {
+              state.toolchainMissingConfigs = cert.perTool.filter((t) => !t.config).map((t) => t.tool);
+            }
+          } else {
+            // Nothing recorded yet (CI backfill case) — offer the clean recommendation.
+            state.toolchainMissingTools = ti.recommend();
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on toolchain 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
@@ -818,6 +852,39 @@ function planActions(state) {
     });
   }
 
+  // ---- Curated dev toolchain backfill (since v4.41.0) ------------------
+  if (state.toolchainEnabled && state.toolchainMissingTools.length) {
+    actions.push({
+      key: 'toolchain-install',
+      label: `Install curated toolchain tools: ${state.toolchainMissingTools.join(', ')}`,
+      why: `features.has_toolchain is true but ${state.toolchainMissingTools.join(', ')} ${state.toolchainMissingTools.length > 1 ? 'do' : 'does'} not resolve via npx (not yet installed, or a CI/--yes configure wrote the flag without installing). The quality gates fall back to the project defaults until installed as devDependencies.`,
+      autoOk: false, // installs devDependencies; let the user confirm
+      run: async () => {
+        const ti = new ToolchainInstaller(state.cwd);
+        const res = ti.install({ tools: state.toolchainMissingTools });
+        for (const t of res.installed) UI.success(`Installed ${t}.`);
+        for (const f of res.failed) UI.warning(`Install failed for ${f.tool}: ${f.error}`);
+        for (const s of res.skipped) UI.info(`Skipped ${s.tool}: ${s.reason}`);
+      },
+    });
+  }
+  if (state.toolchainEnabled && state.toolchainMissingConfigs.length) {
+    actions.push({
+      key: 'toolchain-init-config',
+      label: `Restore missing toolchain config: ${state.toolchainMissingConfigs.join(', ')}`,
+      why: `toolchain.auto_verify is on and the default config for ${state.toolchainMissingConfigs.join(', ')} is missing. Restore it (written only when absent — never overwrites your own).`,
+      autoOk: true, // only writes an absent default config
+      run: async () => {
+        const ti = new ToolchainInstaller(state.cwd);
+        const cfgRes = ti.initConfigs({ tools: state.toolchainMissingConfigs });
+        for (const c of cfgRes) {
+          if (c.status === 'written') UI.success(`Wrote default ${c.tool} config.`);
+          else UI.info(`${c.tool}: ${c.reason || c.status}`);
+        }
+      },
+    });
+  }
+
   // 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`

package/src/commands/update.js

@@ -1297,12 +1297,24 @@ async function update(options = {}, unknownArgs = []) {
             // diff the block's own scalar keys so a new sub-key surfaces too.
             const missingGraph = Object.keys(tpl.graph || {})
               .filter((k) => !(k in (cur2.graph || {})));
+            // `toolchain:` (since v4.41.0) — same nested-block contract as
+            // `graph:`. Diff its own scalar keys + the nested `commands.*` map so
+            // a new gate command (added in a future release) surfaces too.
+            const missingToolchain = Object.keys(tpl.toolchain || {})
+              .filter((k) => k !== 'commands')
+              .filter((k) => !(k in (cur2.toolchain || {})))
+              .map((k) => `toolchain.${k}`);
+            const missingToolchainCmds = Object.keys((tpl.toolchain && tpl.toolchain.commands) || {})
+              .filter((k) => !(k in ((cur2.toolchain && cur2.toolchain.commands) || {})))
+              .map((k) => `toolchain.commands.${k}`);
             const allMissing = [
               ...missingPaths,
               ...missingFeatures,
               ...missingGit.map((k) => `git.${k}`),
               ...missingStack.map((k) => `stack.${k}`),
               ...missingGraph.map((k) => `graph.${k}`),
+              ...missingToolchain,
+              ...missingToolchainCmds,
             ];
             if (allMissing.length) {
               UI.newline();

package/src/utils/tool-currency.js

@@ -1,7 +1,10 @@
 const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
 const { cmpVersions } = require('./semver-lite');
 const GraphifyInstaller = require('./graphify-installer');
 const { REGISTRY } = require('./lsp-adapters');
+const { REGISTRY: TOOLCHAIN_REGISTRY } = require('./toolchain-adapters');
 
 /**
  * External-tool currency layer (since v4.38.0).
@@ -123,6 +126,52 @@ function _lspRecords(cwd, config, lspInstalled, timeoutMs) {
   return records;
 }
 
+/** Installed version of an npm package from the consumer's node_modules, or null. */
+function _npmInstalledVersion(cwd, pkg) {
+  try {
+    const pj = path.join(cwd, 'node_modules', ...pkg.split('/'), 'package.json');
+    if (!fs.existsSync(pj)) return null;
+    return JSON.parse(fs.readFileSync(pj, 'utf8')).version || null;
+  } catch { return null; }
+}
+
+/**
+ * Build curated-toolchain currency records (Biome, Vitest, tsc, Lefthook). These
+ * are project devDependencies: the installed version is read from node_modules
+ * (not a global binary), and the upgrade touches package.json — so the record is
+ * `autoUpgradable: false` (the user runs the pinned `@latest` install on their
+ * terms). Gated on features.has_toolchain + toolchain.installed_tools.
+ */
+function _toolchainRecords(cwd, config, timeoutMs) {
+  if (!(config && config.features && config.features.has_toolchain === true)) return [];
+  const names = (config.toolchain && Array.isArray(config.toolchain.installed_tools))
+    ? config.toolchain.installed_tools : [];
+  const records = [];
+  for (const name of names) {
+    const Cls = TOOLCHAIN_REGISTRY[name];
+    if (!Cls) continue;
+    let adapter;
+    try { adapter = new Cls(cwd); } catch { continue; }
+    const pkg = adapter.npmPackage || adapter.binary;
+    const installed = _npmInstalledVersion(cwd, pkg);
+    if (!installed) continue; // unresolved devDep is the toolchain-install action's job
+    const latest = _npmLatest(pkg, timeoutMs);
+    const outdated = !!(latest && cmpVersions(installed, latest) < 0);
+    records.push({
+      tool: `toolchain:${name}`,
+      label: `${adapter.label} (${pkg})`,
+      installed,
+      latest,
+      status: outdated ? 'outdated' : (latest ? 'current' : 'unknown'),
+      // devDep upgrades mutate package.json — surfaced as a command, not auto-run.
+      upgradeCommand: `npm install --save-dev${name === 'biome' ? ' --save-exact' : ''} ${pkg}@latest`,
+      autoUpgradable: false,
+      source: `npm:${pkg}`,
+    });
+  }
+  return records;
+}
+
 /**
  * Probe every external tool BALDART manages for version currency.
  * Returns an array of records (possibly empty). Async (network). Never throws.
@@ -137,6 +186,9 @@ async function probeAll({ cwd = process.cwd(), config = null, lspInstalled = [],
   try {
     records.push(..._lspRecords(cwd, config, lspInstalled, timeoutMs));
   } catch { /* best-effort */ }
+  try {
+    records.push(..._toolchainRecords(cwd, config, timeoutMs));
+  } catch { /* best-effort */ }
   return records;
 }
 

package/src/utils/toolchain-adapters/biome.js

@@ -0,0 +1,92 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Biome toolchain adapter — format + lint + import organizer in one binary.
+ *
+ * Install mode: `npm-dev` (project devDependency, pinned `-E`). UNLIKE the LSP
+ * servers (which go global because Claude Code spawns them by name from `$PATH`),
+ * Biome is a project tool invoked via `npx --no-install biome …` — it must land in
+ * `node_modules/.bin`, not on the global `$PATH`. There is no global install case
+ * for the JS toolchain.
+ *
+ * Detection signal (in-scope): the project is JS/TS — a `package.json` exists, or a
+ * `tsconfig.json`/`jsconfig.json`, or loose `.ts`/`.js` sources. Biome installs as a
+ * devDep, so a `package.json` is required for the actual install (the installer
+ * guards on that separately).
+ *
+ * `replaces` lists the incumbent tools Biome supersedes — drives the migration
+ * proposal in `configure` (never an automatic replacement).
+ */
+class BiomeAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'biome'; }
+  get label() { return 'Biome (format + lint + import organizer)'; }
+  get binary() { return 'biome'; }
+  get installMode() { return 'npm-dev'; }
+  get npmPackage() { return '@biomejs/biome'; }
+
+  /** devDep install, pinned exact (`-E`) so the toolchain is reproducible. */
+  installCommand() { return 'npm install --save-dev --save-exact @biomejs/biome'; }
+
+  /** Functional probe: resolves the devDep the SAME way agents invoke it (npx). */
+  verifyCommand() { return 'npx --no-install biome --version'; }
+
+  /** Config file Biome reads; `initConfig` writes it only when absent. */
+  get configFile() { return 'biome.json'; }
+
+  /**
+   * The literal commands agents run (read from toolchain.commands.* in the
+   * consumer's baldart.config.yml). Keys map onto the config block; Biome owns
+   * `lint` + `format` (it is the linter, formatter, AND import organizer).
+   */
+  commands() {
+    return {
+      lint: 'npx biome check .',
+      format: 'npx biome format --write .',
+    };
+  }
+
+  /**
+   * Write a default biome.json ONLY when none exists (never overwrite — the
+   * non-destructive invariant). Returns `{ status: 'written'|'skipped', reason?, path }`.
+   * Never throws.
+   */
+  initConfig(cwd = this.cwd) {
+    const target = path.join(cwd, this.configFile);
+    if (fs.existsSync(target)) {
+      return { status: 'skipped', reason: 'exists', path: target };
+    }
+    const defaultConfig = {
+      $schema: 'https://biomejs.dev/schemas/2.0.0/schema.json',
+      vcs: { enabled: true, clientKind: 'git', useIgnoreFile: true },
+      files: { ignoreUnknown: true },
+      formatter: { enabled: true, indentStyle: 'space', indentWidth: 2 },
+      linter: { enabled: true, rules: { recommended: true } },
+      assist: { actions: { source: { organizeImports: 'on' } } },
+    };
+    try {
+      fs.writeFileSync(target, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf8');
+      return { status: 'written', path: target };
+    } catch (err) {
+      return { status: 'skipped', reason: (err.message || '').split('\n')[0], path: target };
+    }
+  }
+
+  /** Incumbent tools Biome supersedes — drives the migration proposal. */
+  static get replaces() { return ['eslint', 'prettier']; }
+
+  /** Autodetect whether the JS/TS toolchain is in scope for the project. */
+  static detect(cwd = process.cwd()) {
+    const markers = ['package.json', 'tsconfig.json', 'jsconfig.json'];
+    for (const m of markers) {
+      if (fs.existsSync(path.join(cwd, m))) return true;
+    }
+    try {
+      return fs.readdirSync(cwd).some((e) => /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(e));
+    } catch { return false; }
+  }
+}
+
+module.exports = BiomeAdapter;

package/src/utils/toolchain-adapters/eslint.js

@@ -0,0 +1,39 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * ESLint INCUMBENT detector — detection only, no install.
+ *
+ * BALDART never installs or removes ESLint; this adapter exists so `configure`
+ * can detect an existing ESLint setup and offer a (manual, never automatic)
+ * migration to Biome — never clobbering the user's config. `replacedBy` names
+ * the curated tool that would supersede it.
+ */
+class EslintDetector {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'eslint'; }
+  get label() { return 'ESLint'; }
+  get replacedBy() { return 'biome'; }
+
+  static detect(cwd = process.cwd()) {
+    const markers = [
+      '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json',
+      '.eslintrc.yml', '.eslintrc.yaml', 'eslint.config.js', 'eslint.config.mjs',
+      'eslint.config.cjs', 'eslint.config.ts',
+    ];
+    for (const m of markers) {
+      if (fs.existsSync(path.join(cwd, m))) return true;
+    }
+    try {
+      const pkgPath = path.join(cwd, 'package.json');
+      if (!fs.existsSync(pkgPath)) return false;
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.eslintConfig) return true;
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      return Boolean(allDeps.eslint);
+    } catch { return false; }
+  }
+}
+
+module.exports = EslintDetector;

package/src/utils/toolchain-adapters/husky.js

@@ -0,0 +1,30 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * husky INCUMBENT detector — detection only, no install. When present, the
+ * Lefthook migration stays MANUAL: BALDART never overwrites `.husky/` or runs
+ * `lefthook install` over an existing husky setup (the hook-handoff is the
+ * user's call). Drives the migration proposal in `configure`.
+ */
+class HuskyDetector {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'husky'; }
+  get label() { return 'husky'; }
+  get replacedBy() { return 'lefthook'; }
+
+  static detect(cwd = process.cwd()) {
+    if (fs.existsSync(path.join(cwd, '.husky'))) return true;
+    try {
+      const pkgPath = path.join(cwd, 'package.json');
+      if (!fs.existsSync(pkgPath)) return false;
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.husky) return true;
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      return Boolean(allDeps.husky);
+    } catch { return false; }
+  }
+}
+
+module.exports = HuskyDetector;

package/src/utils/toolchain-adapters/index.js

@@ -0,0 +1,83 @@
+const BiomeAdapter = require('./biome');
+const VitestAdapter = require('./vitest');
+const TscAdapter = require('./tsc');
+const LefthookAdapter = require('./lefthook');
+const EslintDetector = require('./eslint');
+const PrettierDetector = require('./prettier');
+const JestDetector = require('./jest');
+const HuskyDetector = require('./husky');
+
+/**
+ * Toolchain adapter registry.
+ *
+ * Two registries, two questions:
+ *   - REGISTRY    — curated tools BALDART can INSTALL (Biome, …; later Vitest,
+ *                   tsc, Lefthook, and cross-language Ruff/gofmt). Each exports a
+ *                   class shaped like BiomeAdapter (name, label, binary, installMode,
+ *                   npmPackage, installCommand, verifyCommand, configFile, commands(),
+ *                   initConfig(cwd), static replaces, static detect(cwd)).
+ *   - INCUMBENTS  — tools BALDART only DETECTS (ESLint, Prettier, …; later Jest,
+ *                   husky). Detection-only — never installed or removed. Drives the
+ *                   non-destructive migration proposal in `configure`.
+ *
+ * Adding a new curated tool:
+ *   1. Create `src/utils/toolchain-adapters/<name>.js` (BiomeAdapter shape).
+ *   2. Add it to REGISTRY below.
+ * Adding a new incumbent detector: same, into INCUMBENTS.
+ *
+ * Adapters describe HOW to install/verify a tool; they do NOT run the gates
+ * themselves. Agents read the resolved commands from `toolchain.commands.*` in
+ * baldart.config.yml at runtime (see framework/agents/toolchain-protocol.md).
+ */
+const REGISTRY = {
+  biome: BiomeAdapter,
+  vitest: VitestAdapter,
+  tsc: TscAdapter,
+  lefthook: LefthookAdapter,
+};
+
+const INCUMBENTS = {
+  eslint: EslintDetector,
+  prettier: PrettierDetector,
+  jest: JestDetector,
+  husky: HuskyDetector,
+};
+
+function listAdapters() { return Object.keys(REGISTRY); }
+
+function getAdapter(name, cwd) {
+  const Cls = REGISTRY[name];
+  if (!Cls) throw new Error(`Unknown toolchain adapter: ${name}. Available: ${listAdapters().join(', ')}`);
+  return new Cls(cwd);
+}
+
+/**
+ * Probe the cwd for every curated tool and return the names of adapters whose
+ * static detect() fires (i.e. the tool is in scope for this project — a JS/TS
+ * project for Biome). Pure: no install side effects.
+ */
+function detectAll(cwd = process.cwd()) {
+  return Object.entries(REGISTRY)
+    .filter(([, Cls]) => {
+      try { return Cls.detect(cwd); } catch { return false; }
+    })
+    .map(([name]) => name);
+}
+
+/**
+ * Probe the cwd for incumbent tools already in use. Returns
+ * `[{ name, label, replacedBy }]` so `configure` can propose a migration.
+ * Pure: no side effects, never throws.
+ */
+function detectIncumbents(cwd = process.cwd()) {
+  return Object.entries(INCUMBENTS)
+    .filter(([, Cls]) => {
+      try { return Cls.detect(cwd); } catch { return false; }
+    })
+    .map(([name, Cls]) => {
+      const inst = new Cls(cwd);
+      return { name, label: inst.label, replacedBy: inst.replacedBy };
+    });
+}
+
+module.exports = { REGISTRY, INCUMBENTS, listAdapters, getAdapter, detectAll, detectIncumbents };

package/src/utils/toolchain-adapters/jest.js

@@ -0,0 +1,34 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Jest INCUMBENT detector — detection only, no install. Lets `configure`
+ * propose a (manual) migration to Vitest without ever touching the Jest setup.
+ */
+class JestDetector {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'jest'; }
+  get label() { return 'Jest'; }
+  get replacedBy() { return 'vitest'; }
+
+  static detect(cwd = process.cwd()) {
+    const markers = [
+      'jest.config.js', 'jest.config.cjs', 'jest.config.mjs',
+      'jest.config.ts', 'jest.config.json',
+    ];
+    for (const m of markers) {
+      if (fs.existsSync(path.join(cwd, m))) return true;
+    }
+    try {
+      const pkgPath = path.join(cwd, 'package.json');
+      if (!fs.existsSync(pkgPath)) return false;
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.jest) return true;
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      return Boolean(allDeps.jest);
+    } catch { return false; }
+  }
+}
+
+module.exports = JestDetector;

package/src/utils/toolchain-adapters/lefthook.js

@@ -0,0 +1,84 @@
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Lefthook toolchain adapter — the curated pre-commit hook runner.
+ *
+ * `npm-dev` install. Owns the `pre-commit` hook (Graphify owns `post-commit`, so
+ * no collision). `replaces` = ['husky'] so a husky project routes to the manual
+ * migration proposal — BALDART NEVER overwrites `.husky/`.
+ *
+ * `initConfig` writes a minimal `lefthook.yml` only when absent (non-destructive).
+ * `postInstall` registers the git hooks via `npx lefthook install` — run by the
+ * installer AFTER the devDep + config land, and only on the clean-install path
+ * (never when husky is the incumbent).
+ *
+ * Contributes no `commands()` gate — it is plumbing, not a quality gate the
+ * agents invoke directly.
+ */
+class LefthookAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'lefthook'; }
+  get label() { return 'Lefthook (pre-commit hooks)'; }
+  get binary() { return 'lefthook'; }
+  get installMode() { return 'npm-dev'; }
+  get npmPackage() { return 'lefthook'; }
+
+  installCommand() { return 'npm install --save-dev lefthook'; }
+  verifyCommand() { return 'npx --no-install lefthook version'; }
+
+  get configFile() { return 'lefthook.yml'; }
+
+  /** Plumbing, not a gate — contributes no toolchain.commands.* entry. */
+  commands() { return {}; }
+
+  /**
+   * Write a minimal lefthook.yml (pre-commit → Biome on staged files) only when
+   * absent. Never overwrites. Returns `{ status, reason?, path }`. Never throws.
+   */
+  initConfig(cwd = this.cwd) {
+    const target = path.join(cwd, this.configFile);
+    if (fs.existsSync(target)) return { status: 'skipped', reason: 'exists', path: target };
+    const yml = [
+      '# Managed by BALDART toolchain layer — customize freely.',
+      '# Runs Biome over staged files before each commit. Edit/remove as needed.',
+      'pre-commit:',
+      '  parallel: true',
+      '  commands:',
+      '    biome:',
+      '      glob: "*.{js,ts,jsx,tsx,json,jsonc,css}"',
+      '      run: npx biome check --no-errors-on-unmatched {staged_files}',
+      '',
+    ].join('\n');
+    try {
+      fs.writeFileSync(target, yml, 'utf8');
+      return { status: 'written', path: target };
+    } catch (err) {
+      return { status: 'skipped', reason: (err.message || '').split('\n')[0], path: target };
+    }
+  }
+
+  /**
+   * Register the git hooks. Run by the installer after install+config, only on
+   * the clean-install path. Returns `{ ok, error? }`. Never throws.
+   */
+  postInstall(cwd = this.cwd) {
+    try {
+      execSync('npx --no-install lefthook install', { cwd, stdio: 'pipe', timeout: 60000 });
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: (err.message || '').split('\n')[0] };
+    }
+  }
+
+  static get replaces() { return ['husky']; }
+
+  /** In scope for any JS/TS project with git (a project benefits from hooks). */
+  static detect(cwd = process.cwd()) {
+    return fs.existsSync(path.join(cwd, 'package.json'));
+  }
+}
+
+module.exports = LefthookAdapter;