baldart 3.12.0 → 3.14.0

package/src/commands/update.js

@@ -130,6 +130,29 @@ async function update(options = {}) {
     const currentVersion = await git.getFrameworkVersion();
     UI.success(`Current version: ${currentVersion}`);
 
+    // `.framework/` MUST be trackable — heal a stale `.gitignore` before
+    // any `git subtree pull` / `git add` runs. Idempotent. (since v3.14.0)
+    try {
+      const heal = await git.ensureFrameworkNotIgnored();
+      if (heal.wasFixed) {
+        UI.warning(`.framework/ was ignored by ${heal.source || 'a gitignore'} — auto-healed.`);
+        if (heal.removedLines > 0) {
+          UI.info(`  Removed ${heal.removedLines} stale .framework line(s) from .gitignore.`);
+        }
+        if (heal.appendedNegation) {
+          UI.info('  Appended `!.framework` negation block to .gitignore (idempotent).');
+        }
+        if (heal.stillIgnored) {
+          UI.error('.framework/ is STILL ignored after auto-heal — likely a parent-dir .gitignore outside this repo.');
+          UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
+          UI.info('Resolve by removing that rule, then re-run `baldart update`.');
+          process.exit(1);
+        }
+      }
+    } catch (err) {
+      UI.warning(`Could not check .gitignore for .framework: ${err.message}`);
+    }
+
     // Step 2: Check for updates
     UI.header('STEP 2/5: Check for Updates');
 
@@ -246,7 +269,21 @@ async function update(options = {}) {
 
       newVersion = await git.getFrameworkVersion();
       UI.success(`New version: ${newVersion}`);
-      try { State.recordUpdate({ from: currentVersion, to: newVersion }); } catch (_) { /* non-fatal */ }
+      // Update the ledger and VERIFY the write landed. Prior to v3.13.0 this
+      // call used a silent catch — write failures (permissions, EBUSY) were
+      // hidden, and the user only noticed the drift weeks later via doctor.
+      // Now: visible warning + always-actionable next step.
+      try {
+        const after = State.recordUpdate({ from: currentVersion, to: newVersion });
+        if (after.installed_version !== newVersion) {
+          UI.warning(`Ledger write returned installed_version=${after.installed_version}, expected ${newVersion}.`);
+          UI.info('Run `baldart doctor` to reconcile the ledger.');
+        }
+      } catch (err) {
+        UI.warning(`Could not write .baldart/state.json: ${err.message}`);
+        UI.info(`Framework on disk is at v${newVersion} but the ledger still records v${currentVersion}.`);
+        UI.info('Run `baldart doctor` to reconcile, or check filesystem permissions on .baldart/state.json.');
+      }
 
       // Re-apply the pre-update stash (if any). Conflicts mean we leave the
       // stash intact and tell the user how to resolve — never silently drop.

package/src/commands/version.js

@@ -1,6 +1,7 @@
 const GitUtils = require('../utils/git');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
+const UpdateNotifier = require('../utils/update-notifier');
 
 const REPO_DEFAULT = 'antbald/BALDART';
 const FRAMEWORK_DIR = '.framework';
@@ -48,6 +49,7 @@ async function version(opts = {}) {
     const frameworkVersion = await git.getFrameworkVersion();
     const state = State.load();
     const cliVersion = require('../../package.json').version;
+    const cliUpdate = UpdateNotifier.hint({ currentVersion: cliVersion });
 
     // Optionally fetch upstream to compute drift (default: yes).
     const offline = opts.offline === true;
@@ -75,7 +77,9 @@ async function version(opts = {}) {
       `Last update: ${fmtDate(state.last_update_date)}`,
       `Last push:   v${state.last_pushed_version || '—'}    ${state.last_push_date ? `(${fmtDate(state.last_push_date)})` : ''}`.trim(),
       '',
-      `CLI:         v${cliVersion}`,
+      cliUpdate
+        ? `CLI:         v${cliVersion} → v${cliUpdate.latest} available (npm i -g baldart@latest)`
+        : `CLI:         v${cliVersion}`,
       `Repository:  https://github.com/${state.framework_repo || REPO_DEFAULT}`,
     ].filter((l) => l !== ''));
     UI.newline();

package/src/utils/git.js

@@ -176,6 +176,99 @@ class GitUtils {
       return '';
     }
   }
+
+  // ────────────────────────────────────────────────────────────────────
+  // `.framework/` is a git subtree — it MUST be tracked. If anything in
+  // the gitignore chain (project .gitignore, .git/info/exclude, global
+  // excludes) matches `.framework`, every subsequent `git add` on files
+  // under that directory fails with "paths are ignored by one of your
+  // .gitignore files". Detect + self-heal idempotently so install /
+  // update / push flows never trip over this. (since v3.14.0)
+  // ────────────────────────────────────────────────────────────────────
+  async checkFrameworkIgnored() {
+    try {
+      const out = await this.git.raw([
+        'check-ignore',
+        '-v',
+        '--no-index',
+        '--',
+        FRAMEWORK_DIR
+      ]);
+      const line = (out || '').trim();
+      if (!line) return { ignored: false };
+      // Format: "<source>:<line>:<pattern>\t<path>"
+      const m = /^(.+?):(\d+):([^\t]+)\t/.exec(line);
+      return {
+        ignored: true,
+        source: m ? m[1] : 'unknown',
+        line: m ? Number(m[2]) : null,
+        pattern: m ? m[3] : null,
+        raw: line
+      };
+    } catch (_) {
+      // `git check-ignore` exits 1 when the path is not ignored — simple-git
+      // throws on non-zero. Treat as "not ignored".
+      return { ignored: false };
+    }
+  }
+
+  async ensureFrameworkNotIgnored() {
+    const status = await this.checkFrameworkIgnored();
+    if (!status.ignored) return { wasFixed: false };
+
+    const gitignorePath = path.join(this.cwd, '.gitignore');
+    const marker = '# BALDART: .framework/ is a git subtree — never ignore (auto-managed)';
+    const negationBlock = `\n${marker}\n!.framework\n!.framework/**\n`;
+
+    let original = '';
+    if (fs.existsSync(gitignorePath)) {
+      original = fs.readFileSync(gitignorePath, 'utf8');
+    }
+
+    // 1. Strip standalone .framework rules from the project .gitignore so we
+    //    don't leave stale "do ignore" lines that future maintainers might
+    //    notice and try to "fix" by removing our negation.
+    const lines = original.split('\n');
+    const stripped = lines.filter((line) => {
+      const t = line.trim();
+      return !(
+        t === '.framework' ||
+        t === '.framework/' ||
+        t === '/.framework' ||
+        t === '/.framework/' ||
+        t === '.framework/*' ||
+        t === '/.framework/*'
+      );
+    });
+    const removedLines = lines.length - stripped.length;
+
+    // 2. Append the negation block (only once — idempotent across re-runs).
+    let next = stripped.join('\n');
+    if (!next.includes(marker)) {
+      if (next.length && !next.endsWith('\n')) next += '\n';
+      next += negationBlock;
+    }
+
+    if (next !== original) {
+      fs.writeFileSync(gitignorePath, next, 'utf8');
+    }
+
+    // 3. Verify the heal actually took effect. If the rule lives somewhere we
+    //    cannot rewrite from here (a parent-dir .gitignore outside the repo,
+    //    a non-standard core.excludesFile that overrides the project file),
+    //    surface the leftover state to the caller instead of pretending.
+    const recheck = await this.checkFrameworkIgnored();
+
+    return {
+      wasFixed: true,
+      stillIgnored: recheck.ignored,
+      removedLines,
+      appendedNegation: !original.includes(marker),
+      source: status.source,
+      pattern: status.pattern,
+      recheck
+    };
+  }
 }
 
 module.exports = GitUtils;

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

@@ -19,7 +19,7 @@ class GoAdapter {
 
   installCommand() { return 'go install golang.org/x/tools/gopls@latest'; }
   verifyCommand() { return 'gopls version'; }
-  claudePluginId() { return null; }
+  claudePluginId() { return 'gopls-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {
     return fs.existsSync(path.join(cwd, 'go.mod'));

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

@@ -23,7 +23,7 @@ class PythonAdapter {
 
   installCommand() { return 'npm install --save-dev pyright'; }
   verifyCommand() { return 'npx --no-install pyright --version'; }
-  claudePluginId() { return null; }
+  claudePluginId() { return 'pyright-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {
     const markers = ['pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile'];

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

@@ -19,7 +19,7 @@ class RubyAdapter {
 
   installCommand() { return 'gem install ruby-lsp'; }
   verifyCommand() { return 'ruby-lsp --version'; }
-  claudePluginId() { return null; }
+  claudePluginId() { return 'ruby-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {
     const markers = ['Gemfile', '.ruby-version', 'config.ru'];

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

@@ -16,7 +16,7 @@ class RustAdapter {
 
   installCommand() { return 'rustup component add rust-analyzer'; }
   verifyCommand() { return 'rust-analyzer --version'; }
-  claudePluginId() { return null; }
+  claudePluginId() { return 'rust-analyzer-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {
     return fs.existsSync(path.join(cwd, 'Cargo.toml'));

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

@@ -32,8 +32,14 @@ class TypeScriptAdapter {
   /** 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; }
+  /**
+   * Claude Code code-intelligence plugin id, if any. Null = no companion plugin.
+   * When non-null, `LspInstaller.installClaudePlugins()` installs this plugin
+   * from the `claude-plugins-official` marketplace (anthropics/claude-plugins-official)
+   * so the LSP layer is wired into Claude Code natively instead of leaving the
+   * user to enable it manually after `baldart configure`.
+   */
+  claudePluginId() { return 'typescript-lsp@claude-plugins-official'; }
 
   /** Autodetect whether this language is in scope for the project. */
   static detect(cwd = process.cwd()) {

package/src/utils/lsp-installer.js

@@ -1,7 +1,42 @@
 const { execSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { detectAll, getAdapter, listAdapters } = require('./lsp-adapters');
 const UI = require('./ui');
 
+/**
+ * The `claude` CLI is built on Ink (React for TUIs) and writes stdout in a
+ * way that truncates at ~8 KB when piped directly to a node child process —
+ * regardless of `maxBuffer` setting. Workaround: shell-redirect to a temp
+ * file and read the file back. Used only for read-only `--json` queries.
+ *
+ * Returns the file contents as a string, or throws (caller catches).
+ */
+function captureClaudeJson(args, { timeout = 10000 } = {}) {
+  const tmp = path.join(os.tmpdir(), `baldart-claude-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+  try {
+    execSync(`claude ${args} > ${JSON.stringify(tmp)} 2>/dev/null`, {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      timeout,
+      shell: '/bin/bash',
+    });
+    return fs.readFileSync(tmp, 'utf8');
+  } finally {
+    try { fs.unlinkSync(tmp); } catch (_) { /* best-effort cleanup */ }
+  }
+}
+
+/**
+ * Anthropic's official marketplace for native Claude Code LSP plugins
+ * (typescript-lsp, pyright-lsp, gopls-lsp, rust-analyzer-lsp, ruby-lsp, …).
+ * Every adapter's `claudePluginId()` returns an id namespaced under this
+ * marketplace, so the installer hard-codes it here. If a future adapter needs
+ * a different marketplace, lift this into a per-adapter field.
+ */
+const OFFICIAL_MARKETPLACE_NAME = 'claude-plugins-official';
+const OFFICIAL_MARKETPLACE_SOURCE = 'anthropics/claude-plugins-official';
+
 /**
  * High-level LSP installer used by `baldart configure` and the `lsp-bootstrap`
  * skill / doctor step. Owns the install + verify side effects so the command
@@ -11,6 +46,10 @@ const UI = require('./ui');
  *   - 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.
+ *   - Claude plugin install ops gate on the `claude` CLI being on PATH AND on
+ *     `claude` being present in `tools.enabled`; when either fails the methods
+ *     report `{ skipped: [...], reason }` so the caller can render a hint
+ *     instead of erroring.
  */
 class LspInstaller {
   constructor(cwd = process.cwd()) { this.cwd = cwd; }
@@ -91,6 +130,210 @@ class LspInstaller {
     return { installed, skipped, manual };
   }
 
+  // ──────────────────────────────────────────────────────────────────────
+  // Native Claude Code companion plugins (since v3.14.0)
+  //
+  // For each language whose adapter declares a `claudePluginId()`, this layer
+  // ensures the matching plugin from the `claude-plugins-official` marketplace
+  // is installed. Without it, enabling `features.has_lsp_layer: true` only
+  // installs the language-server binary — Claude Code itself never sees it,
+  // and agents fall back to Grep silently. Wiring the two together is the
+  // whole point of opting into LSP, so the installer treats this as part of
+  // the install, not an optional extra.
+  // ──────────────────────────────────────────────────────────────────────
+
+  /** True iff the `claude` CLI is on PATH and answers `--version`. */
+  isClaudeCliAvailable() {
+    try {
+      execSync('claude --version', { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+      return true;
+    } catch { return false; }
+  }
+
+  /**
+   * Idempotently register the official marketplace. Reads the existing list
+   * first so we never spam `claude plugin marketplace add` on every configure
+   * run. Returns `{ ok, alreadyPresent, error? }`. Never throws.
+   */
+  ensureClaudeMarketplace() {
+    if (!this.isClaudeCliAvailable()) {
+      return { ok: false, error: 'claude CLI not on PATH' };
+    }
+    try {
+      const out = captureClaudeJson('plugin marketplace list --json', { timeout: 8000 });
+      const parsed = JSON.parse(out);
+      // Tolerate both shapes: object map keyed by name, or array of { name, … }.
+      const names = Array.isArray(parsed)
+        ? parsed.map(m => m && m.name).filter(Boolean)
+        : Object.keys(parsed || {});
+      if (names.includes(OFFICIAL_MARKETPLACE_NAME)) {
+        return { ok: true, alreadyPresent: true };
+      }
+    } catch (_) {
+      // Fall through to the add — if the add itself fails, we report that.
+    }
+    try {
+      execSync(`claude plugin marketplace add ${OFFICIAL_MARKETPLACE_SOURCE} --scope user`, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 60000 // first add clones the marketplace repo; allow time
+      });
+      return { ok: true, alreadyPresent: false };
+    } catch (err) {
+      return { ok: false, error: (err.message || '').split('\n')[0] };
+    }
+  }
+
+  /**
+   * Return the set of plugin ids (e.g. `typescript-lsp@claude-plugins-official`)
+   * currently installed at ANY scope. Used to skip already-installed plugins.
+   * Returns `Set<string>`; empty set on any failure (degrade open — we'd rather
+   * issue a redundant install than block on a parser hiccup).
+   */
+  listInstalledClaudePlugins() {
+    const ids = new Set();
+    try {
+      const out = captureClaudeJson('plugin list --json', { timeout: 8000 });
+      const parsed = JSON.parse(out);
+      const entries = Array.isArray(parsed) ? parsed : Object.values(parsed || {});
+      for (const entry of entries) {
+        // Be tolerant of shape drift: pull the id from `name`, `id`, or
+        // the object's own key.
+        const id = (entry && (entry.id || entry.name)) || null;
+        if (id) ids.add(id);
+      }
+      // Also handle the `{ "<id>@<marketplace>": [...] }` map shape that the
+      // on-disk `installed_plugins.json` uses, in case `list --json` mirrors it.
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        for (const key of Object.keys(parsed)) {
+          if (key.includes('@')) ids.add(key);
+        }
+      }
+    } catch (_) { /* swallow — empty set means "install, don't skip" */ }
+    return ids;
+  }
+
+  /**
+   * Install the native Claude Code companion plugins for the given language
+   * server names. Idempotent: skips plugins already installed, skips adapters
+   * whose `claudePluginId()` is null.
+   *
+   * Gating:
+   *   - `opts.toolsEnabled` (array, default `['claude']`): when `claude` is
+   *     not in the array, the whole method is a silent no-op (Codex-only users
+   *     don't want Claude marketplace mutation).
+   *   - When the `claude` CLI is missing, returns `{ skipped, reason }` so the
+   *     caller can render a manual-install hint.
+   *
+   * Returns `{ installed: [...], skipped: [...], manual: [...], marketplace }`.
+   * Never throws.
+   */
+  async installClaudePlugins(serverNames, opts = {}) {
+    const {
+      toolsEnabled = ['claude'],
+      scope = 'user', // LSP plugins are machine-wide useful — avoid N project copies
+      interactive = false
+    } = opts;
+
+    if (!Array.isArray(toolsEnabled) || !toolsEnabled.includes('claude')) {
+      return { skipped: [], installed: [], manual: [], reason: 'claude not in tools.enabled' };
+    }
+    if (!this.isClaudeCliAvailable()) {
+      return {
+        skipped: serverNames.map(n => ({ name: n, reason: 'claude CLI not on PATH' })),
+        installed: [], manual: [],
+        reason: 'claude CLI not on PATH'
+      };
+    }
+
+    // Resolve <serverName> → <claudePluginId>, dropping adapters without one.
+    const targets = [];
+    for (const name of serverNames) {
+      try {
+        const a = getAdapter(name, this.cwd);
+        const pid = a.claudePluginId();
+        if (pid) targets.push({ name, label: a.label, pluginId: pid });
+      } catch { /* unknown adapter — ignore */ }
+    }
+    if (!targets.length) {
+      return { installed: [], skipped: [], manual: [], reason: 'no adapters declare a Claude plugin id' };
+    }
+
+    // Idempotency 1: marketplace add (no-op if already registered).
+    const mkt = this.ensureClaudeMarketplace();
+    if (!mkt.ok) {
+      return {
+        installed: [],
+        skipped: targets.map(t => ({ name: t.name, reason: `marketplace not registered (${mkt.error || 'unknown'})` })),
+        manual: targets.map(t => ({
+          name: t.name,
+          label: t.label,
+          command: `claude plugin marketplace add ${OFFICIAL_MARKETPLACE_SOURCE} && claude plugin install ${t.pluginId} --scope ${scope}`
+        })),
+        marketplace: mkt
+      };
+    }
+
+    // Idempotency 2: skip plugins already installed at any scope.
+    const already = this.listInstalledClaudePlugins();
+
+    const installed = [];
+    const skipped = [];
+    const manual = [];
+
+    for (const t of targets) {
+      if (already.has(t.pluginId)) {
+        skipped.push({ name: t.name, reason: 'plugin already installed' });
+        continue;
+      }
+
+      if (interactive) {
+        const ok = await UI.confirm(
+          `Install native Claude Code plugin \`${t.pluginId}\` (--scope ${scope})?`,
+          true
+        );
+        if (!ok) { skipped.push({ name: t.name, reason: 'user declined' }); continue; }
+      }
+
+      const spinner = UI.spinner(`Installing ${t.pluginId}…`).start();
+      try {
+        execSync(`claude plugin install ${t.pluginId} --scope ${scope}`, {
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: 60000
+        });
+        spinner.succeed(`Installed ${t.pluginId}`);
+        installed.push({ name: t.name, pluginId: t.pluginId });
+      } catch (err) {
+        spinner.fail(`Failed to install ${t.pluginId}`);
+        manual.push({
+          name: t.name,
+          label: t.label,
+          command: `claude plugin install ${t.pluginId} --scope ${scope}`
+        });
+        skipped.push({ name: t.name, reason: (err.message || '').split('\n')[0] });
+      }
+    }
+
+    return { installed, skipped, manual, marketplace: mkt };
+  }
+
+  /**
+   * For each declared server, report whether the matching Claude plugin is
+   * installed. Returns `[{ name, pluginId, installed }]`. Adapters without a
+   * `claudePluginId()` are reported as `{ pluginId: null, installed: null }`
+   * so callers can filter them out.
+   */
+  verifyClaudePlugins(serverNames) {
+    const already = this.listInstalledClaudePlugins();
+    return serverNames.map(name => {
+      let a;
+      try { a = getAdapter(name, this.cwd); }
+      catch { return { name, pluginId: null, installed: null }; }
+      const pid = a.claudePluginId();
+      if (!pid) return { name, pluginId: null, installed: null };
+      return { name, pluginId: pid, installed: already.has(pid) };
+    });
+  }
+
   /**
    * Verify each named server's binary is reachable. Returns
    * `[{ name, ok, output | error }]`. Never throws.

package/src/utils/state.js

@@ -106,6 +106,32 @@ function recordUpdate({ from, to }, cwd = process.cwd()) {
   return state;
 }
 
+/**
+ * Reconcile the ledger's installed_version with the actual framework version
+ * on disk (read from .framework/VERSION). Used by `baldart doctor` when it
+ * detects a mismatch between the payload and the ledger — typically caused by
+ * an interrupted update flow, a manual commit that excluded state.json, or a
+ * filesystem write failure that the silent catch in update.js used to hide.
+ *
+ * Idempotent: calling with the already-current version is a no-op (no history
+ * entry produced). History entry uses event "ledger-reconcile" so the source
+ * of the bump is auditable separately from real updates.
+ */
+function reconcileInstalledVersion({ to, reason }, cwd = process.cwd()) {
+  const state = load(cwd);
+  const from = state.installed_version;
+  if (from === to) return { state, changed: false };
+  state.installed_version = to;
+  state.history = appendHistory(state, {
+    event: 'ledger-reconcile',
+    from,
+    to,
+    note: reason || 'reconcile ledger with .framework/VERSION'
+  });
+  save(state, cwd);
+  return { state, changed: true, from, to };
+}
+
 function recordPush({ from, to, description }, cwd = process.cwd()) {
   const state = load(cwd);
   state.last_pushed_version = to;
@@ -137,6 +163,7 @@ module.exports = {
   recordInstall,
   recordUpdate,
   recordPush,
+  reconcileInstalledVersion,
   readFrameworkVersion,
   STATE_FILE,
   STATE_VERSION,