baldart 3.8.2 → 3.10.0

package/src/commands/configure.js

@@ -3,6 +3,8 @@ const path = require('path');
 const yaml = require('js-yaml');
 const UI = require('../utils/ui');
 const toolAdapters = require('../utils/tool-adapters');
+const LspInstaller = require('../utils/lsp-installer');
+const lspAdapters = require('../utils/lsp-adapters');
 
 const CONFIG_FILE = 'baldart.config.yml';
 // The subtree pull copies the entire BALDART repo (which itself has a
@@ -26,6 +28,48 @@ const IGNORED_DIRS = new Set([
   '.expo', '.parcel-cache', 'tmp', '.idea', '.vscode', '.DS_Store'
 ]);
 
+/**
+ * Probe origin/develop branch protection to recommend a merge strategy.
+ * Returns: { value, protected, reason }
+ *   - 'pr'         when develop is protected (PR is the only viable path)
+ *   - 'local-push' when develop is NOT protected (FF push is faster, no gh needed)
+ *   - 'pr' as a safe default if we can't tell (gh missing, network down, no remote)
+ *
+ * Non-fatal: any failure returns `{ value: 'pr', protected: null }` so configure
+ * keeps moving. The user can override in the interactive prompt.
+ */
+function detectMergeStrategy(cwd = process.cwd()) {
+  try {
+    const { execSync } = require('child_process');
+    const opts = { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, encoding: 'utf8' };
+    // Need both git + gh. If either is absent or unauthenticated, default 'pr'.
+    try { execSync('gh --version', opts); } catch (_) {
+      return { value: 'pr', protected: null, reason: 'gh CLI not installed — defaulting to pr.' };
+    }
+    let nameWithOwner = '';
+    try {
+      nameWithOwner = execSync('gh repo view --json nameWithOwner -q .nameWithOwner', opts).trim();
+    } catch (_) {
+      return { value: 'pr', protected: null, reason: 'no GitHub remote detected — defaulting to pr.' };
+    }
+    // Probe branch protection. 404 means "not protected" → local-push viable.
+    try {
+      execSync(`gh api repos/${nameWithOwner}/branches/develop/protection`, opts);
+      return { value: 'pr', protected: true, reason: 'develop is protected on origin — PR strategy required.' };
+    } catch (_) {
+      // Could be 404 (not protected) OR branch doesn't exist. Check existence:
+      try {
+        execSync(`gh api repos/${nameWithOwner}/branches/develop -q .name`, opts);
+        return { value: 'local-push', protected: false, reason: 'develop exists on origin and is not protected — local-push viable.' };
+      } catch (_) {
+        return { value: 'pr', protected: null, reason: 'develop branch not found on origin — defaulting to pr.' };
+      }
+    }
+  } catch (_) {
+    return { value: 'pr', protected: null, reason: 'probe failed — defaulting to pr.' };
+  }
+}
+
 function detect(cwd = process.cwd()) {
   const exists = (p) => fs.existsSync(path.join(cwd, p));
   const findFirst = (...candidates) => candidates.find(exists) || '';
@@ -238,6 +282,8 @@ function detect(cwd = process.cwd()) {
     : (exists('cypress.config.ts') || exists('cypress.config.js') || hasDep('cypress')) ? 'cypress'
     : '';
 
+  const mergeStrategyProbe = detectMergeStrategy(cwd);
+
   const detected = {
     paths: {
       design_system: designSystemPath,
@@ -298,10 +344,23 @@ function detect(cwd = process.cwd()) {
       has_adrs: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0,
       has_prd_workflow: exists('docs/prd'),
       has_wiki_overlay: exists('docs/wiki'),
+      // LSP recommended when any supported language server adapter would
+      // detect this project. Drives the default for the configure prompt.
+      has_lsp_layer: lspAdapters.detectAll(cwd).length > 0,
     },
     tools: {
       enabled: toolAdapters.defaultEnabled(cwd)
     },
+    git: {
+      // Set to a plain string — the structured probe details (`protected`,
+      // `reason`) are kept on a sibling key so mergePreserving stays type-safe.
+      merge_strategy: mergeStrategyProbe.value,
+    },
+    _probes: {
+      // Internal scratchpad — never serialized to YAML. Used by
+      // interactivePrompts to surface the autodetection reasoning.
+      merge_strategy: mergeStrategyProbe,
+    },
   };
 
   // Reference walkFirst once so the dead-code linter is happy and the helper
@@ -424,6 +483,25 @@ async function interactivePrompts(merged, detected) {
   }
   merged.tools.enabled = currentEnabled;
 
+  // ---- Git merge strategy (since v3.9.0) --------------------------------
+  UI.section('Git merge strategy (how `/mw` lands feature branches onto develop)');
+  merged.git = merged.git || {};
+  const probe = (detected._probes && detected._probes.merge_strategy)
+    || { value: 'pr', protected: null };
+  if (probe.reason) UI.info(probe.reason);
+  const currentMerge = merged.git.merge_strategy || probe.value || 'pr';
+  const chosenMerge = await UI.select(
+    `Choose merge strategy (current: ${currentMerge})`,
+    [
+      { name: 'pr — open a GitHub PR, merge via `gh pr merge` (required if develop is protected)', value: 'pr' },
+      { name: 'local-push — direct FF push to origin/develop (no PR, no `gh` dependency)', value: 'local-push' },
+    ]
+  );
+  merged.git.merge_strategy = chosenMerge;
+  if (chosenMerge === 'local-push' && probe.protected === true) {
+    UI.warning('You picked `local-push` but develop appears protected on origin — pushes will be rejected. Switch back to `pr` if it fails.');
+  }
+
   UI.section('Features (explicit yes/no — option A: always ask)');
   for (const flag of [
     ['has_design_system', 'Project has a documented design system?'],
@@ -433,6 +511,7 @@ async function interactivePrompts(merged, detected) {
     ['has_adrs', 'Project uses ADR workflow?'],
     ['has_prd_workflow', 'Project uses PRD workflow (docs/prd/)?'],
     ['has_wiki_overlay', 'Project has LLM-wiki overlay (docs/wiki/)?'],
+    ['has_lsp_layer', 'Enable LSP symbol-search layer? (recommended for large codebases)'],
   ]) {
     const [key, question] = flag;
     const currentVal = merged.features[key];
@@ -471,6 +550,48 @@ async function interactivePrompts(merged, detected) {
     merged.paths[key] = await promptForKey(`${label}`, proposed);
   }
 
+  // ---- LSP layer (since v3.10.0) ----------------------------------------
+  // Only runs when the user opted in above. Idempotent: re-running configure
+  // on an already-installed project re-detects, asks which servers to keep,
+  // and updates lsp.installed_servers accordingly.
+  merged.lsp = merged.lsp || { installed_servers: [], auto_verify: true };
+  if (merged.features.has_lsp_layer === true) {
+    UI.section('LSP layer (install language servers for symbol search)');
+    const installer = new LspInstaller(process.cwd());
+    const detectedLangs = installer.detectLanguages();
+    if (detectedLangs.length === 0) {
+      UI.warning('No supported languages detected (tsconfig.json, pyproject.toml, go.mod, Cargo.toml, Gemfile).');
+      UI.info('Skipping LSP install. You can run `/lsp-bootstrap` or `npx baldart configure` later.');
+    } else {
+      const recs = installer.recommend(detectedLangs);
+      const already = new Set(merged.lsp.installed_servers || []);
+      const toInstall = [];
+      for (const r of recs) {
+        const note = already.has(r.name) ? ' (already recorded)' : '';
+        UI.info(`${r.label} → ${r.binary} (${r.installMode})${note}`);
+        const want = await UI.confirm(`Install ${r.label}?`, true);
+        if (want) toInstall.push(r.name);
+      }
+      if (toInstall.length) {
+        const { installed, skipped, manual } = await installer.installServers(toInstall, { interactive: false });
+        for (const m of manual) {
+          UI.warning(`System-level install required for ${m.label}:`);
+          UI.code(m.command, `Recorded as pending — run \`baldart doctor\` after installing to verify.`);
+        }
+        const verify = installer.verifyServers(installed.map(i => i.name));
+        const verified = verify.filter(v => v.ok).map(v => v.name);
+        const newSet = new Set([...(merged.lsp.installed_servers || []), ...verified, ...manual.map(m => m.name)]);
+        merged.lsp.installed_servers = Array.from(newSet);
+        if (skipped.length) {
+          UI.warning(`Skipped: ${skipped.map(s => `${s.name} (${s.reason})`).join(', ')}`);
+        }
+      }
+    }
+  } else {
+    // Feature disabled — wipe the state so `installed_servers` doesn't lie.
+    merged.lsp.installed_servers = [];
+  }
+
   UI.section('Stack (autodetected from package.json — confirm or override)');
   const charting = merged.stack.charting;
   const chartingCanonical = await promptForKey(
@@ -535,7 +656,9 @@ function serialize(config) {
 # NOTE: features.* flags MUST be explicit (true | false). Any flag absent
 # from this file will prompt the user on first skill invocation.
 `;
-  return header + yaml.dump(stripNullFeatures(config), { lineWidth: 100, noRefs: true });
+  const clean = stripNullFeatures(config);
+  if (clean && clean._probes) delete clean._probes;
+  return header + yaml.dump(clean, { lineWidth: 100, noRefs: true });
 }
 
 async function configure(opts = {}) {

package/src/commands/doctor.js

@@ -30,6 +30,7 @@ const GitUtils = require('../utils/git');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
+const LspInstaller = require('../utils/lsp-installer');
 
 const FRAMEWORK_DIR = '.framework';
 const REPO_DEFAULT = 'antbald/BALDART';
@@ -196,6 +197,25 @@ async function detectState(cwd, opts = {}) {
 
     state.editGateRegistered = false;
     try { state.editGateRegistered = Hooks.isRegistered(cwd); } catch (_) {}
+
+    // ---- LSP layer (since v3.10.0) -------------------------------------
+    state.lspEnabled = false;
+    state.lspInstalled = [];
+    state.lspBroken = [];
+    try {
+      // Reuse the `config` already parsed above instead of re-reading the file.
+      if (config && !config.__malformed && config.features && config.features.has_lsp_layer === true) {
+        state.lspEnabled = true;
+        const installed = (config.lsp && config.lsp.installed_servers) || [];
+        state.lspInstalled = installed;
+        const autoVerify = !(config.lsp && config.lsp.auto_verify === false);
+        if (autoVerify && installed.length) {
+          const installer = new LspInstaller(cwd);
+          const results = installer.verifyServers(installed);
+          state.lspBroken = results.filter(r => !r.ok).map(r => r.name);
+        }
+      }
+    } catch (_) { /* never block doctor on LSP probe */ }
   }
 
   return state;
@@ -306,6 +326,27 @@ function planActions(state) {
     });
   }
 
+  if (state.lspEnabled && state.lspBroken && state.lspBroken.length > 0) {
+    actions.push({
+      key: 'lsp-fix',
+      label: `Reinstall ${state.lspBroken.length} broken LSP server(s)`,
+      why: `LSP layer is enabled but these language servers are not reachable: ${state.lspBroken.join(', ')}. Symbol search will silently fall back to Grep until they are reinstalled.`,
+      autoOk: false, // touches dev-deps and is the kind of action a user may
+      // have made deliberate (switching from npm pyright to system pyright);
+      // keep the outer prompt + the per-server confirm both alive.
+      run: async () => {
+        const installer = new LspInstaller(state.cwd);
+        const { installed, manual, skipped } = await installer.installServers(state.lspBroken);
+        if (installed.length) UI.success(`Reinstalled: ${installed.map(i => i.name).join(', ')}`);
+        for (const m of manual) {
+          UI.warning(`System-level reinstall required for ${m.label}:`);
+          console.log(`    ${m.command}`);
+        }
+        if (skipped.length) UI.warning(`Skipped: ${skipped.map(s => `${s.name} (${s.reason})`).join(', ')}`);
+      },
+    });
+  }
+
   const remoteAhead = state.remote.fetched && state.remote.behind > 0;
   const hasLocalWork = state.workingTreeDirty > 0 || state.commitsAhead > 0;
 
@@ -437,6 +478,20 @@ function renderDiagnostic(state) {
     state.editGateRegistered ? 'ok' : 'warn'
   ));
 
+  if (state.lspEnabled) {
+    const total = state.lspInstalled.length;
+    const broken = state.lspBroken.length;
+    const value = total === 0
+      ? 'enabled but no servers installed'
+      : broken === 0
+        ? `${total} server(s) verified (${state.lspInstalled.join(', ')})`
+        : `${broken}/${total} broken (${state.lspBroken.join(', ')})`;
+    const severity = total === 0 || broken > 0 ? 'warn' : 'ok';
+    console.log(statusLine('LSP layer', value, severity));
+  } else {
+    console.log(statusLine('LSP layer', 'disabled', 'ok'));
+  }
+
   console.log();
 }
 

package/src/commands/update.js

@@ -413,12 +413,21 @@ async function update(options = {}) {
               .filter((k) => !(k in (cur2.features || {})));
             const missingPaths = Object.keys(tpl.paths || {})
               .filter((k) => !(k in (cur2.paths || {})));
-            if (missingFeatures.length || missingPaths.length) {
+            const missingGit = Object.keys(tpl.git || {})
+              .filter((k) => !(k in (cur2.git || {})));
+            const allMissing = [...missingPaths, ...missingFeatures, ...missingGit.map((k) => `git.${k}`)];
+            if (allMissing.length) {
               UI.newline();
-              UI.warning(
-                `New config keys in this version: ${[...missingPaths, ...missingFeatures].join(', ')}. ` +
-                'Re-run `npx baldart configure` to populate them (existing values are preserved).'
-              );
+              UI.warning(`New config keys in this version: ${allMissing.join(', ')}.`);
+              // Auto-offer configure so the user actually answers, instead of
+              // silently falling back to template defaults on first use.
+              const runConfigure = await UI.confirm('Run `baldart configure` now to populate them? (existing values are preserved)', true);
+              if (runConfigure) {
+                const configureCmd = require('./configure');
+                await configureCmd();
+              } else {
+                UI.info('Skipped. Skills will prompt for the missing keys on first use.');
+              }
             }
           } catch (_) {
             // Non-fatal — schema drift detection is best-effort.

package/src/utils/lsp-adapters/go.js

@@ -0,0 +1,29 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Go LSP adapter — gopls.
+ *
+ * gopls is a Go binary; we can't install it into node_modules. installMode
+ * is 'system' which means the configure flow prints the canonical install
+ * command and the user runs it themselves. The verify step still checks
+ * that the binary is in PATH.
+ */
+class GoAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'go'; }
+  get label() { return 'Go (gopls)'; }
+  get binary() { return 'gopls'; }
+  get installMode() { return 'system'; }
+
+  installCommand() { return 'go install golang.org/x/tools/gopls@latest'; }
+  verifyCommand() { return 'gopls version'; }
+  claudePluginId() { return null; }
+
+  static detect(cwd = process.cwd()) {
+    return fs.existsSync(path.join(cwd, 'go.mod'));
+  }
+}
+
+module.exports = GoAdapter;

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

@@ -0,0 +1,49 @@
+const TypeScriptAdapter = require('./typescript');
+const PythonAdapter     = require('./python');
+const GoAdapter         = require('./go');
+const RustAdapter       = require('./rust');
+const RubyAdapter       = require('./ruby');
+
+/**
+ * LSP adapter registry.
+ *
+ * Adding a new language (Java, C/C++, PHP, Elixir, …):
+ *   1. Create `src/utils/lsp-adapters/<lang>.js` exporting a class with the
+ *      same shape as TypeScriptAdapter (name, label, binary, installMode,
+ *      installCommand, verifyCommand, claudePluginId, static detect).
+ *   2. Add it to the REGISTRY below.
+ *   3. (Optional) Wire a Claude Code plugin id if one exists.
+ *
+ * Adapters describe *how* to install/verify a language server; they do NOT
+ * speak LSP themselves. The actual symbol search at runtime happens through
+ * whatever Claude Code plugin or MCP server the user has loaded.
+ */
+const REGISTRY = {
+  typescript: TypeScriptAdapter,
+  python:     PythonAdapter,
+  go:         GoAdapter,
+  rust:       RustAdapter,
+  ruby:       RubyAdapter
+};
+
+function listAdapters() { return Object.keys(REGISTRY); }
+
+function getAdapter(name, cwd) {
+  const Cls = REGISTRY[name];
+  if (!Cls) throw new Error(`Unknown LSP adapter: ${name}. Available: ${listAdapters().join(', ')}`);
+  return new Cls(cwd);
+}
+
+/**
+ * Probe the cwd for every known language and return the names of adapters
+ * whose static detect() fires. 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);
+}
+
+module.exports = { REGISTRY, listAdapters, getAdapter, detectAll };

package/src/utils/lsp-adapters/python.js

@@ -0,0 +1,42 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Python LSP adapter — Pyright.
+ *
+ * Pyright ships as both an npm package and a pip package. We default to the
+ * npm devDep route so installs stay project-local and version-pinned without
+ * touching the user's Python env. Users who already drive Python via pip/uv
+ * can override by removing pyright from devDeps and installing system-wide.
+ *
+ * Detection signal: pyproject.toml, setup.py, setup.cfg, requirements.txt,
+ * Pipfile, or a top-level .py source tree.
+ */
+class PythonAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'python'; }
+  get label() { return 'Python (Pyright)'; }
+  get binary() { return 'pyright'; }
+  get installMode() { return 'npm-dev'; }
+  get npmPackage() { return 'pyright'; }
+
+  installCommand() { return 'npm install --save-dev pyright'; }
+  verifyCommand() { return 'npx --no-install pyright --version'; }
+  claudePluginId() { return null; }
+
+  static detect(cwd = process.cwd()) {
+    const markers = ['pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile'];
+    for (const m of markers) {
+      if (fs.existsSync(path.join(cwd, m))) return true;
+    }
+    // Fallback: a `src/` or top-level *.py file is a strong enough signal.
+    try {
+      const entries = fs.readdirSync(cwd);
+      if (entries.some(e => e.endsWith('.py'))) return true;
+    } catch { /* ignore */ }
+    return false;
+  }
+}
+
+module.exports = PythonAdapter;

package/src/utils/lsp-adapters/ruby.js

@@ -0,0 +1,30 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Ruby LSP adapter — ruby-lsp (Shopify).
+ *
+ * Installed as a gem; system-mode. Users on Bundler-managed projects may
+ * prefer to add `gem 'ruby-lsp', group: :development` to their Gemfile and
+ * `bundle install` instead — we print the simple gem install command for
+ * portability.
+ */
+class RubyAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'ruby'; }
+  get label() { return 'Ruby (ruby-lsp)'; }
+  get binary() { return 'ruby-lsp'; }
+  get installMode() { return 'system'; }
+
+  installCommand() { return 'gem install ruby-lsp'; }
+  verifyCommand() { return 'ruby-lsp --version'; }
+  claudePluginId() { return null; }
+
+  static detect(cwd = process.cwd()) {
+    const markers = ['Gemfile', '.ruby-version', 'config.ru'];
+    return markers.some(m => fs.existsSync(path.join(cwd, m)));
+  }
+}
+
+module.exports = RubyAdapter;

package/src/utils/lsp-adapters/rust.js

@@ -0,0 +1,26 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Rust LSP adapter — rust-analyzer.
+ *
+ * Installed through rustup as a toolchain component. System-mode only.
+ */
+class RustAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'rust'; }
+  get label() { return 'Rust (rust-analyzer)'; }
+  get binary() { return 'rust-analyzer'; }
+  get installMode() { return 'system'; }
+
+  installCommand() { return 'rustup component add rust-analyzer'; }
+  verifyCommand() { return 'rust-analyzer --version'; }
+  claudePluginId() { return null; }
+
+  static detect(cwd = process.cwd()) {
+    return fs.existsSync(path.join(cwd, 'Cargo.toml'));
+  }
+}
+
+module.exports = RustAdapter;

package/src/utils/lsp-adapters/typescript.js

@@ -0,0 +1,54 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * TypeScript / JavaScript LSP adapter.
+ *
+ * Language server: `typescript-language-server` (Node, npm).
+ * Install mode: project-local devDep — keeps the binary inside the consumer
+ * repo's node_modules and avoids polluting the user's global env.
+ *
+ * Detection signal: presence of `tsconfig.json`, `jsconfig.json`, or a
+ * `package.json` referencing typescript in deps/devDeps.
+ */
+class TypeScriptAdapter {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  get name() { return 'typescript'; }
+  get label() { return 'TypeScript / JavaScript'; }
+  get binary() { return 'typescript-language-server'; }
+
+  /** 'npm-dev' = npm devDependency, 'system' = printed install instructions. */
+  get installMode() { return 'npm-dev'; }
+
+  /** npm package to install when mode='npm-dev'. */
+  get npmPackage() { return 'typescript-language-server typescript'; }
+
+  /** Shell command the user (or installer) should run. */
+  installCommand() {
+    return 'npm install --save-dev typescript-language-server typescript';
+  }
+
+  /** Verify the binary is reachable (no execution side effects). */
+  verifyCommand() { return 'npx --no-install typescript-language-server --version'; }
+
+  /** Claude Code code-intelligence plugin id, if any. Null = use generic LSP. */
+  claudePluginId() { return null; }
+
+  /** Autodetect whether this language is in scope for the project. */
+  static detect(cwd = process.cwd()) {
+    const markers = ['tsconfig.json', 'jsconfig.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'));
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      return Boolean(allDeps.typescript);
+    } catch { return false; }
+  }
+}
+
+module.exports = TypeScriptAdapter;

package/src/utils/lsp-installer.js

@@ -0,0 +1,118 @@
+const { execSync } = require('child_process');
+const { detectAll, getAdapter, listAdapters } = require('./lsp-adapters');
+const UI = require('./ui');
+
+/**
+ * High-level LSP installer used by `baldart configure` and the `lsp-bootstrap`
+ * skill / doctor step. Owns the install + verify side effects so the command
+ * layers stay thin.
+ *
+ * Contract:
+ *   - Pure detection (no install) when only `detectLanguages` is called.
+ *   - All mutating ops respect `--non-interactive` via the `interactive` flag.
+ *   - Returns plain objects (no throws) so the caller can render results.
+ */
+class LspInstaller {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  /** Languages whose marker files exist under cwd. */
+  detectLanguages() { return detectAll(this.cwd); }
+
+  /** Adapters that BALDART knows about (regardless of detection). */
+  knownAdapters() { return listAdapters(); }
+
+  /**
+   * Build a recommendation list from detected languages. Each entry carries
+   * the install command and the install mode so the UI can decide whether
+   * to run it automatically (npm-dev) or just print it (system).
+   */
+  recommend(langs = this.detectLanguages()) {
+    return langs.map(name => {
+      const a = getAdapter(name, this.cwd);
+      return {
+        name: a.name,
+        label: a.label,
+        binary: a.binary,
+        installMode: a.installMode,
+        installCommand: a.installCommand(),
+        verifyCommand: a.verifyCommand(),
+        claudePluginId: a.claudePluginId()
+      };
+    });
+  }
+
+  /**
+   * Install one or more language servers. Returns `{ installed, skipped, manual }`.
+   *  - npm-dev adapters: executed in-process (npm install --save-dev …).
+   *  - system adapters: never executed automatically; surfaced under `manual`
+   *    so the caller can print the command for the user to run.
+   *
+   * `opts.interactive`: when true, asks confirmation per server (default true).
+   * `opts.dryRun`:      when true, no commands are executed.
+   */
+  async installServers(serverNames, opts = {}) {
+    const { interactive = true, dryRun = false } = opts;
+    const installed = [];
+    const skipped = [];
+    const manual = [];
+
+    for (const name of serverNames) {
+      let a;
+      try { a = getAdapter(name, this.cwd); }
+      catch (err) { skipped.push({ name, reason: err.message }); continue; }
+
+      if (a.installMode === 'system') {
+        manual.push({
+          name: a.name,
+          label: a.label,
+          command: a.installCommand()
+        });
+        continue;
+      }
+
+      if (interactive) {
+        const ok = await UI.confirm(`Install ${a.label} via \`${a.installCommand()}\`?`, true);
+        if (!ok) { skipped.push({ name, reason: 'user declined' }); continue; }
+      }
+
+      if (dryRun) { installed.push({ name, dryRun: true }); continue; }
+
+      const spinner = UI.spinner(`Installing ${a.label}…`).start();
+      try {
+        execSync(a.installCommand(), { cwd: this.cwd, stdio: 'pipe' });
+        spinner.succeed(`Installed ${a.label}`);
+        installed.push({ name });
+      } catch (err) {
+        spinner.fail(`Failed to install ${a.label}`);
+        skipped.push({ name, reason: err.message.split('\n')[0] });
+      }
+    }
+
+    return { installed, skipped, manual };
+  }
+
+  /**
+   * Verify each named server's binary is reachable. Returns
+   * `[{ name, ok, output | error }]`. Never throws.
+   */
+  verifyServers(serverNames) {
+    return serverNames.map(name => {
+      let a;
+      try { a = getAdapter(name, this.cwd); }
+      catch (err) { return { name, ok: false, error: err.message }; }
+
+      try {
+        const out = execSync(a.verifyCommand(), {
+          cwd: this.cwd,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: 8000
+        }).toString().trim();
+        return { name, ok: true, output: out };
+      } catch (err) {
+        return { name, ok: false, error: (err.message || '').split('\n')[0] };
+      }
+    });
+  }
+}
+
+module.exports = LspInstaller;