baldart 4.40.0 → 4.42.0

package/src/utils/toolchain-installer.js

@@ -0,0 +1,233 @@
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const UI = require('./ui');
+const adapters = require('./toolchain-adapters');
+
+/**
+ * High-level installer/wrapper for the curated dev toolchain (Biome today;
+ * Vitest, tsc, Lefthook next), used by `baldart configure`, the
+ * `/toolchain-bootstrap` skill, and `doctor`.
+ *
+ * Design (since v4.41.0):
+ *   - Curated, OPINIONATED defaults: the framework recommends the tools it
+ *     considers best for a JS/TS project. "Opinionated but askable" — configure
+ *     preselects, the user opts out.
+ *   - NON-DESTRUCTIVE: `initConfigs` writes a config file only when absent;
+ *     incumbent tools (ESLint/Prettier/…) are detected, never installed or
+ *     removed. Flipping `features.has_toolchain` true→false does NOT uninstall.
+ *   - NEVER silent in CI: the command layer only invokes `install` in the
+ *     interactive `configure` path; `--non-interactive`/`--yes` writes the flag
+ *     and `doctor` backfills.
+ *   - All mutating ops return plain `{ ok|status, … }` objects and never throw,
+ *     so the command layers stay thin and can render results / hints.
+ *
+ * Per-tool adapters under src/utils/toolchain-adapters/ describe HOW to install
+ * and verify each tool; this class composes them. The CONSUME side (agents
+ * running the gates) reads the resolved literal commands from
+ * `toolchain.commands.*` in baldart.config.yml — see
+ * framework/agents/toolchain-protocol.md.
+ */
+class ToolchainInstaller {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  // ── Detection ───────────────────────────────────────────────────────────
+
+  /** True iff this project has a package.json (required to install JS devDeps). */
+  hasPackageJson() {
+    return fs.existsSync(path.join(this.cwd, 'package.json'));
+  }
+
+  /** Curated tools in scope for this project (e.g. ['biome'] on a JS/TS repo). */
+  inScope() { return adapters.detectAll(this.cwd); }
+
+  /** Incumbent tools already present: `[{ name, label, replacedBy }]`. */
+  detectIncumbents() { return adapters.detectIncumbents(this.cwd); }
+
+  /**
+   * Curated tools to install on the CLEAN path: in scope, not yet usable, and
+   * NOT blocked by an incumbent they would replace (a Jest/husky/ESLint project
+   * routes the corresponding tool to `migrations()` instead — never auto-installed
+   * over an existing setup). Never throws.
+   */
+  recommend() {
+    const present = new Set(this.detectIncumbents().map((i) => i.name));
+    return this.inScope().filter((name) => {
+      if (this._toolUsable(name)) return false;
+      return !this._replacesOf(name).some((inc) => present.has(inc));
+    });
+  }
+
+  /**
+   * Curated tools in scope but BLOCKED by an incumbent they would replace.
+   * Returns `[{ tool, replaces:[incumbent names present] }]` — the migration
+   * proposal surface (manual, never automatic). Never throws.
+   */
+  migrations() {
+    const present = new Set(this.detectIncumbents().map((i) => i.name));
+    return this.inScope()
+      .filter((name) => !this._toolUsable(name))
+      .map((name) => ({ tool: name, replaces: this._replacesOf(name).filter((inc) => present.has(inc)) }))
+      .filter((m) => m.replaces.length);
+  }
+
+  /** True iff at least one curated tool is already usable in this project. */
+  detect() {
+    return this.inScope().some((name) => this._toolUsable(name));
+  }
+
+  /**
+   * In-scope curated tools that RESOLVE right now (devDep present). This is the
+   * set whose configs + gate commands are written into baldart.config.yml — a
+   * declined migration (incumbent kept) leaves its tool out, so the command
+   * stays empty and the consume side falls back. Never throws.
+   */
+  activeTools() {
+    return this.inScope().filter((name) => this._toolUsable(name));
+  }
+
+  // ── Install (devDeps) ─────────────────────────────────────────────────────
+
+  /**
+   * Install the given curated tools as project devDependencies. Returns
+   * `{ ok, installed:[], failed:[{tool,error}], skipped:[{tool,reason}] }`.
+   * Never throws. NOT run in CI / `--non-interactive` by the command layer.
+   */
+  install({ tools = this.recommend(), spinner = true } = {}) {
+    if (!this.hasPackageJson()) {
+      return { ok: false, installed: [], failed: [], skipped: tools.map((t) => ({ tool: t, reason: 'no package.json' })) };
+    }
+    const installed = [];
+    const failed = [];
+    const skipped = [];
+    for (const name of tools) {
+      let adapter;
+      try { adapter = adapters.getAdapter(name, this.cwd); }
+      catch (err) { skipped.push({ tool: name, reason: (err.message || '').split('\n')[0] }); continue; }
+      if (this._toolUsable(name)) { skipped.push({ tool: name, reason: 'already present' }); continue; }
+      const sp = spinner ? UI.spinner(`Installing ${adapter.label}…`).start() : null;
+      try {
+        // Write the tool's default config (if absent) BEFORE `npm install`, so a
+        // package whose own postinstall scaffolds from its config (Lefthook's
+        // npm postinstall runs `lefthook install` and would otherwise drop a
+        // commented-out example, then register no hooks) sees OURS — a biome
+        // pre-commit — and registers it. Non-destructive (skips if present).
+        if (typeof adapter.initConfig === 'function') {
+          try { adapter.initConfig(this.cwd); } catch (_) { /* non-fatal */ }
+        }
+        execSync(adapter.installCommand(), { cwd: this.cwd, stdio: 'pipe', timeout: 300000 });
+        if (this._toolUsable(name)) {
+          // Optional post-install side effect (e.g. re-assert Lefthook's git hooks
+          // in case the package's own postinstall ran before our config existed).
+          // Only runs on this clean-install path — never over an incumbent setup.
+          let postWarn = null;
+          if (typeof adapter.postInstall === 'function') {
+            const pi = adapter.postInstall(this.cwd);
+            if (pi && !pi.ok) postWarn = pi.error;
+          }
+          if (sp) sp.succeed(`Installed ${adapter.label}`);
+          if (postWarn) UI.warning(`${adapter.label} installed but post-install step failed: ${postWarn}`);
+          installed.push(name);
+        } else {
+          if (sp) sp.fail(`${adapter.label} install did not resolve`);
+          failed.push({ tool: name, error: 'verify failed after install' });
+        }
+      } catch (err) {
+        if (sp) sp.fail(`${adapter.label} install failed`);
+        failed.push({ tool: name, error: (err.message || '').split('\n')[0] });
+      }
+    }
+    return { ok: failed.length === 0, installed, failed, skipped };
+  }
+
+  /**
+   * Write each tool's default config when absent (non-destructive). Returns
+   * `[{ tool, status:'written'|'skipped'|'noop', reason?, path? }]`. Never throws.
+   */
+  initConfigs({ tools = this.inScope() } = {}) {
+    const out = [];
+    for (const name of tools) {
+      let adapter;
+      try { adapter = adapters.getAdapter(name, this.cwd); }
+      catch { out.push({ tool: name, status: 'noop', reason: 'unknown adapter' }); continue; }
+      if (typeof adapter.initConfig !== 'function') { out.push({ tool: name, status: 'noop' }); continue; }
+      try { out.push({ tool: name, ...adapter.initConfig(this.cwd) }); }
+      catch (err) { out.push({ tool: name, status: 'noop', reason: (err.message || '').split('\n')[0] }); }
+    }
+    return out;
+  }
+
+  /**
+   * Merge the literal commands contributed by the given tools into a flat
+   * `{ lint, format, typecheck, test, test_related, build, audit }` map (empty
+   * string for unprovided keys). Written verbatim into `toolchain.commands.*`.
+   */
+  commandsFor(tools = this.inScope()) {
+    const merged = {
+      lint: '', format: '', typecheck: '', test: '', test_related: '', build: '', audit: '',
+    };
+    for (const name of tools) {
+      let adapter;
+      try { adapter = adapters.getAdapter(name, this.cwd); } catch { continue; }
+      if (typeof adapter.commands !== 'function') continue;
+      const c = adapter.commands() || {};
+      for (const k of Object.keys(c)) {
+        if (k in merged && c[k]) merged[k] = c[k];
+      }
+    }
+    return merged;
+  }
+
+  // ── Version currency (stub in Phase 1; real impl lands with tool-currency) ──
+
+  /** Placeholder — devDep currency arrives with `_toolchainRecords` (Phase 3). */
+  async checkUpgrade() { return { tool: 'toolchain', installed: null, latest: null, outdated: false, source: 'npm' }; }
+
+  /** Placeholder — devDep upgrades touch package.json; user runs them. */
+  upgrade() { return { ok: false, error: 'devDep upgrades are user-driven (npm install -D -E <pkg>@latest)' }; }
+
+  // ── Certification ─────────────────────────────────────────────────────────
+
+  /**
+   * One-shot certification of the selected tools, used by `configure`, the
+   * bootstrap skill, and `doctor`. Per tool, attests: the devDep RESOLVES
+   * (`npx --no-install <bin> --version`) and its config file EXISTS. Returns a
+   * plain object; never throws. `ok` = every selected tool resolves (a missing
+   * config is reported but does not fail `ok` — it is restorable).
+   */
+  certify({ tools = this.inScope() } = {}) {
+    const perTool = tools.map((name) => {
+      let adapter;
+      try { adapter = adapters.getAdapter(name, this.cwd); }
+      catch { return { tool: name, devDep: false, config: false }; }
+      const devDep = this._toolUsable(name);
+      const config = adapter.configFile
+        ? fs.existsSync(path.join(this.cwd, adapter.configFile))
+        : true;
+      return { tool: name, devDep, config };
+    });
+    const ok = perTool.length > 0 && perTool.every((t) => t.devDep);
+    return { ok, perTool };
+  }
+
+  // ── internals ─────────────────────────────────────────────────────────────
+
+  /** Static `replaces` (incumbents superseded) declared by a curated adapter. */
+  _replacesOf(name) {
+    const Cls = adapters.REGISTRY[name];
+    return (Cls && Array.isArray(Cls.replaces)) ? Cls.replaces : [];
+  }
+
+  /** True iff the tool's binary resolves via its verifyCommand in this cwd. */
+  _toolUsable(name) {
+    let adapter;
+    try { adapter = adapters.getAdapter(name, this.cwd); } catch { return false; }
+    if (typeof adapter.verifyCommand !== 'function') return false;
+    try {
+      execSync(adapter.verifyCommand(), { cwd: this.cwd, stdio: 'ignore', timeout: 15000 });
+      return true;
+    } catch { return false; }
+  }
+}
+
+module.exports = ToolchainInstaller;