baldart 4.40.0 → 4.42.0

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;

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

@@ -0,0 +1,39 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Prettier INCUMBENT detector — detection only, no install.
+ *
+ * Same contract as the ESLint detector: BALDART never installs or removes
+ * Prettier; this lets `configure` detect an existing formatter and offer a
+ * manual migration to Biome (which subsumes formatting), never overwriting
+ * the user's config.
+ */
+class PrettierDetector {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'prettier'; }
+  get label() { return 'Prettier'; }
+  get replacedBy() { return 'biome'; }
+
+  static detect(cwd = process.cwd()) {
+    const markers = [
+      '.prettierrc', '.prettierrc.js', '.prettierrc.cjs', '.prettierrc.json',
+      '.prettierrc.yml', '.prettierrc.yaml', '.prettierrc.toml',
+      'prettier.config.js', 'prettier.config.cjs', 'prettier.config.mjs',
+    ];
+    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.prettier) return true;
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      return Boolean(allDeps.prettier);
+    } catch { return false; }
+  }
+}
+
+module.exports = PrettierDetector;

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

@@ -0,0 +1,50 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * TypeScript type-checker (tsc) toolchain adapter.
+ *
+ * `npm-dev` install of the `typescript` package (often already present). The
+ * gate is `npx tsc --noEmit`. `initConfig` is a NO-OP — BALDART NEVER creates or
+ * touches `tsconfig.json` (it is deeply project-specific and the #1 data-loss
+ * risk). In scope ONLY for TypeScript projects (a tsconfig or a typescript dep);
+ * a plain-JS project is not offered tsc. No incumbent (`replaces` empty).
+ */
+class TscAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'tsc'; }
+  get label() { return 'TypeScript type-checker (tsc)'; }
+  get binary() { return 'tsc'; }
+  get installMode() { return 'npm-dev'; }
+  get npmPackage() { return 'typescript'; }
+
+  installCommand() { return 'npm install --save-dev typescript'; }
+  verifyCommand() { return 'npx --no-install tsc --version'; }
+
+  /** Never managed by BALDART — tsconfig.json is project-owned. */
+  get configFile() { return null; }
+
+  commands() {
+    return { typecheck: 'npx tsc --noEmit' };
+  }
+
+  initConfig() { return { status: 'noop' }; }
+
+  static get replaces() { return []; }
+
+  /** In scope ONLY for TypeScript projects. */
+  static detect(cwd = process.cwd()) {
+    if (fs.existsSync(path.join(cwd, 'tsconfig.json'))) return true;
+    if (fs.existsSync(path.join(cwd, 'jsconfig.json'))) return true;
+    try {
+      const pkgPath = path.join(cwd, 'package.json');
+      if (!fs.existsSync(pkgPath)) return false;
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      return Boolean(allDeps.typescript);
+    } catch { return false; }
+  }
+}
+
+module.exports = TscAdapter;

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

@@ -0,0 +1,46 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Vitest toolchain adapter — the curated test runner.
+ *
+ * `npm-dev` install. No config is scaffolded: Vitest runs with sensible defaults
+ * and many projects configure it inside an existing `vite.config.*`, so writing a
+ * standalone `vitest.config.ts` would risk a conflict — `initConfig` is a no-op
+ * (non-destructive). `replaces` = ['jest'] so a Jest project routes to the
+ * migration proposal instead of an automatic install alongside Jest.
+ */
+class VitestAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'vitest'; }
+  get label() { return 'Vitest (test runner)'; }
+  get binary() { return 'vitest'; }
+  get installMode() { return 'npm-dev'; }
+  get npmPackage() { return 'vitest'; }
+
+  installCommand() { return 'npm install --save-dev vitest'; }
+  verifyCommand() { return 'npx --no-install vitest --version'; }
+
+  /** No standalone config — Vitest defaults + optional vite.config integration. */
+  get configFile() { return null; }
+
+  commands() {
+    return {
+      test: 'npx vitest run',
+      test_related: 'npx vitest related --run',
+    };
+  }
+
+  /** Non-destructive: never scaffolds a config (avoids clobbering vite.config). */
+  initConfig() { return { status: 'noop' }; }
+
+  static get replaces() { return ['jest']; }
+
+  /** In scope for any JS/TS project (a project needs a test runner). */
+  static detect(cwd = process.cwd()) {
+    return fs.existsSync(path.join(cwd, 'package.json'));
+  }
+}
+
+module.exports = VitestAdapter;