baldart 3.17.0 → 3.17.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.17.1] - 2026-05-23
+
+CLI quality-of-life patch shaken loose by a hands-on consumer update simulation (mayo, 3.13.0 → 3.16.0). Four real bugs surfaced when actually driving `baldart update` end-to-end from a scripted context. Two were show-stoppers for any non-interactive use (CI, AI-driven, headless update agent), one was cosmetic but ugly, one was a stale stub that lied to the user. All four are fixed; nothing in this release changes framework payload behaviour for end-users running BALDART interactively in a TTY.
+
+### Fixed
+
+- **`baldart update` gains `--yes`/`-y` and `--auto-stash` flags** in [bin/baldart.js](bin/baldart.js) and [src/commands/update.js](src/commands/update.js). Until now, every `UI.confirm` and the `UI.select` arrow-key stash prompt blocked indefinitely on a non-TTY stdin (inquirer's pattern detection mis-handles re-rendered prompts when fed via pipe or `expect`). Both flags route through a single internal `confirm()` wrapper that short-circuits to the prompt's default when `--yes` is set; `--auto-stash` is the narrower variant for users who want manual control over confirms but auto-stash on dirty trees. `--yes` implies `--auto-stash` and additionally passes `--non-interactive` down to the `baldart configure` sub-invocation triggered by the schema-drift detector, plus switches symlink reconcile from `mode: 'prompt'` to `mode: 'force'` (the conflict-resolution prompts inside `SymlinkUtils` would otherwise reintroduce blocking I/O even with `--yes`).
+- **`baldart status` actually checks the framework against the upstream tip** in [src/commands/status.js](src/commands/status.js). Previously the "Update Status" section was a hard-coded `UI.success('Up to date')` stub regardless of the installed version — a 4-versions-stale consumer was told everything was fine. The fix calls `git.fetch('antbald/BALDART')` + `git.getRemoteVersion(...)` (already exported by `src/utils/git.js`), compares semver with a tiny inline `cmpSemver` helper, and renders one of four outcomes: update available (`X → Y`), local ahead of remote (unreleased commit, common during BALDART self-development), up to date, or "Cannot check (offline?)" on fetch failure. The SUMMARY box now carries the update line too, so it's visible without scrolling past the per-section output.
+- **`baldart --version` and `baldart --help` exit cleanly** in [bin/baldart.js](bin/baldart.js). Commander 9 throws a `CommanderError` with `exitCode: 0` from these flags as its internal flow-control mechanism; the previous `bin/baldart.js` had no try/catch around `program.parse(process.argv)`, so the throw escaped to Node and printed a 12-line `CommanderError: 3.17.0` stack trace right after the version itself. Now wrapped in try/catch that recognises the three known sentinel codes (`commander.version`, `commander.help`, `commander.helpDisplayed`) and exits 0 silently; real errors keep the previous behaviour (log message + non-zero exit).
+- **CLI version is read from the `VERSION` file, not `package.json`** in [bin/baldart.js](bin/baldart.js). `package.json.version` is only synced at publish time via `npm run sync-version` (see `scripts/sync-version`), so in dev / local-source / pre-publish contexts it lagged the actual `VERSION` file — `node bin/baldart.js --version` was printing `3.14.1` while VERSION was `3.17.0`. A new `resolveVersion()` reads `VERSION` at module load with `package.json.version` as fallback. Published `baldart@<x.y.z>` on npm is unaffected (the workflow still runs `sync-version` first, so both files agree in published artefacts).
+
+### Notes
+
+- **No framework payload changes** — all four fixes are inside `bin/` and `src/`. Skills, agents, templates, hooks, routines, docs are untouched. The next `baldart update` for consumers picks up the new flags and the working status check without any change to the framework files they install.
+- **Not a v3.18.0 because no new capability shipped** — this is purely "what should already have worked". The new flags are additive (zero-config end-users in a TTY see no change) and the status fix is replacing a stub with the real check it was always supposed to be.
+- **Bug #4 from the mayo simulation (schema-drift detector skipped with `--no-commit`) was a false positive** — the drift detector at lines 462–503 runs before `postUpdateAutoCommit` (line 506), so `--no-commit` doesn't reach it. Verified by reading the call sequence, no code change needed.
+- **Verification** (manual, no test suite): (1) `node bin/baldart.js --version` prints `3.17.1` and exits 0 silently; (2) `node bin/baldart.js update --help` shows the three options (`--no-commit`, `--yes/-y`, `--auto-stash`); (3) in a stale consumer repo, `baldart status` reports "Update available" with the version diff; (4) `baldart update --yes` on a dirty consumer auto-stashes, pulls, reconciles symlinks in force mode, runs `configure --non-interactive`, and exits 0 with no blocking prompts.
+
 ## [3.17.0] - 2026-05-23
 
 The `/prd` skill gains a third option in the design phase. Until v3.16.0, when a user reached Step 3 without having provided mockups (`mockups.status: none`), the only path forward was internal generation via the `ui-design` skill (3 HTML options → iteration → save). With Claude Design now offering a design-system-sync'd visual generator, users who prefer iterating in that surface had to abandon the PRD flow halfway, work externally, and then re-enter as if they'd had mockups from the start. This release adds **Step 3.0 — Mockup Source Decision**: when `mockups.status: none` AND UI impact ≠ N/A, the skill explicitly asks "internal generation or handoff to Claude Design?". The handoff branch generates a context-rich prompt (discovery + brand voice + design-system tokens + screens in scope + stack target) ready to paste, then STOPs. On user re-entry with local paths, it re-uses the existing Step 1.6 Mockup Intake verbatim — copy → analyze → populate state — and Step 3 falls naturally into Hybrid mode. Zero code paths downstream of the bivio are new; the entire feature is a decision point + a prompt generator on top of pre-existing infrastructure.

package/VERSION

@@ -1 +1 @@
-3.17.0
+3.17.1

package/bin/baldart.js

@@ -2,9 +2,27 @@
 
 const { Command } = require('commander');
 const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
 const packageJson = require('../package.json');
 const updateNotifier = require('../src/utils/update-notifier');
 
+// Source of truth for the running version is the VERSION file at the repo
+// root. package.json.version is only synced at publish time (see scripts/
+// sync-version), so in dev / local-source / pre-publish contexts it lags.
+// Reading VERSION here keeps `baldart --version` honest in every scenario.
+function resolveVersion() {
+  try {
+    const versionFile = path.join(__dirname, '..', 'VERSION');
+    const fromFile = fs.readFileSync(versionFile, 'utf8').trim();
+    if (fromFile) return fromFile;
+  } catch (_) { /* fall through */ }
+  // Fall back to package.json (already required above). Avoids the TDZ trap
+  // of self-referencing `CLI_VERSION` before its initialiser runs.
+  return packageJson.version;
+}
+const CLI_VERSION = resolveVersion();
+
 // CLI self-update notifier (v3.13.0+). Best-effort; non-blocking; suppressed
 // in CI / non-TTY / via BALDART_NO_UPDATE_CHECK=1 / when --offline is passed.
 // Prints a one-shot hint at the top of the run if a newer npm version was
@@ -14,7 +32,7 @@ const updateNotifier = require('../src/utils/update-notifier');
 const rawArgsForNotifier = process.argv.slice(2);
 const offlineForNotifier = rawArgsForNotifier.includes('--offline');
 updateNotifier.announceAndRefresh({
-  currentVersion: packageJson.version,
+  currentVersion: CLI_VERSION,
   offline: offlineForNotifier,
 });
 
@@ -23,7 +41,7 @@ const program = new Command();
 program
   .name('baldart')
   .description('Claude Agent Framework - AI agent coordination for software projects')
-  .version(packageJson.version);
+  .version(CLI_VERSION);
 
 program
   .command('add [repo]')
@@ -38,6 +56,8 @@ program
   .command('update')
   .description('Update the framework to the latest version')
   .option('--no-commit', 'Skip the post-update auto-commit prompt')
+  .option('-y, --yes', 'Auto-confirm all prompts (CI / scripting). Implies --auto-stash.')
+  .option('--auto-stash', 'When the working tree is dirty, stash automatically instead of prompting.')
   .action(async (options) => {
     const updateCommand = require('../src/commands/update');
     await updateCommand(options);
@@ -153,5 +173,16 @@ if (isDoctorShortcut) {
     process.exit(1);
   });
 } else {
-  program.parse(process.argv);
+  try {
+    program.parse(process.argv);
+  } catch (err) {
+    // Commander throws CommanderError(exitCode: 0) for --version / --help.
+    // That's a normal exit, not a crash — swallow the throw and exit cleanly.
+    if (err && err.code === 'commander.version') process.exit(0);
+    if (err && err.code === 'commander.help') process.exit(0);
+    if (err && err.code === 'commander.helpDisplayed') process.exit(0);
+    // Real error: log and exit non-zero like before.
+    console.error(err && err.message ? err.message : err);
+    process.exit(err && Number.isInteger(err.exitCode) ? err.exitCode : 1);
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.17.0",
+  "version": "3.17.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/status.js

@@ -4,6 +4,19 @@ const UI = require('../utils/ui');
 const fs = require('fs');
 const path = require('path');
 
+// Lightweight semver compare. Returns positive if a > b, negative if a < b,
+// zero if equal. Treats malformed input as 0 — degrade open rather than throw.
+function cmpSemver(a, b) {
+  if (!a || !b) return 0;
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
 async function status() {
   const git = new GitUtils();
   const symlinks = new SymlinkUtils();
@@ -94,24 +107,43 @@ async function status() {
       }
     }
 
-    // Check for pending updates
+    // Check for pending updates (since v3.17.1 — was a no-op stub before).
     UI.newline();
     UI.section('Update Status');
 
+    let updateAvailable = false;
+    let remoteVersion = null;
     try {
       await git.fetch('antbald/BALDART');
-      UI.info('Checking for updates...');
-      // Simplified - would need more sophisticated version comparison
-      UI.success('Up to date (check with: baldart update)');
+      remoteVersion = await git.getRemoteVersion('antbald/BALDART', 'main');
+      if (!remoteVersion || remoteVersion === 'unknown') {
+        UI.warning('Could not read remote VERSION — check `baldart update` manually.');
+      } else if (cmpSemver(remoteVersion, version) > 0) {
+        updateAvailable = true;
+        UI.warning(`Update available: ${version} → ${remoteVersion}. Run: baldart update`);
+      } else if (cmpSemver(remoteVersion, version) < 0) {
+        UI.info(`Local v${version} is ahead of remote v${remoteVersion} (likely an unreleased commit).`);
+      } else {
+        UI.success(`Up to date (v${version})`);
+      }
     } catch (error) {
       UI.warning('Cannot check for updates (offline?)');
     }
 
     // Summary
     UI.newline();
+    let updateLine;
+    if (updateAvailable && remoteVersion) {
+      updateLine = `Update: ${version} → ${remoteVersion} available`;
+    } else if (remoteVersion && remoteVersion !== 'unknown') {
+      updateLine = `Update: up to date`;
+    } else {
+      updateLine = `Update: unknown (could not reach remote)`;
+    }
     UI.box('SUMMARY', [
       `Version: ${version}`,
       `Installation: ${symlinkValid ? 'Valid' : 'Issues detected'}`,
+      updateLine,
       '',
       'Commands available:',
       '  • baldart update  - Update framework',

package/src/commands/update.js

@@ -81,7 +81,10 @@ async function postUpdateAutoCommit(git, newVersion, options) {
   if (userOwned.length > 0) {
     UI.warning(`${userOwned.length} other dirty path(s) will be left untouched (not BALDART-managed).`);
   }
-  const ok = await UI.confirm(`Commit them as \`chore(baldart): post-update reconcile to v${newVersion}\`?`, true);
+  const autoYes = options && options.yes === true;
+  const ok = autoYes
+    ? true
+    : await UI.confirm(`Commit them as \`chore(baldart): post-update reconcile to v${newVersion}\`?`, true);
   if (!ok) {
     UI.info('Auto-commit declined. Your worktree keeps the changes for manual review.');
     return;
@@ -110,6 +113,13 @@ async function update(options = {}) {
   const symlinks = new SymlinkUtils();
   const repo = 'antbald/BALDART'; // Default repo
 
+  // Non-interactive flags (since v3.17.1). `--yes` implies `--auto-stash`.
+  // When `yes` is set, every UI.confirm/UI.select downstream short-circuits
+  // to its default — the same value an unattended user would have produced.
+  const autoYes = options.yes === true;
+  const autoStash = autoYes || options.autoStash === true;
+  const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
+
   try {
     // Step 1: Verify installation
     UI.header('STEP 1/5: Verify Installation');
@@ -194,14 +204,14 @@ async function update(options = {}) {
     const diff = await git.diffWithRemote();
     if (diff) {
       UI.info('Changes detected. Review recommended.');
-      const showDiff = await UI.confirm('Show detailed diff?', false);
+      const showDiff = await confirm('Show detailed diff?', false);
 
       if (showDiff) {
         console.log(diff);
       }
     }
 
-    const proceedUpdate = await UI.confirm('Proceed with update?', true);
+    const proceedUpdate = await confirm('Proceed with update?', true);
     if (!proceedUpdate) {
       UI.info('Update cancelled');
       process.exit(0);
@@ -225,10 +235,16 @@ async function update(options = {}) {
       UI.list(unique.slice(0, 8), 'yellow');
       if (unique.length > 8) UI.info(`…and ${unique.length - 8} more.`);
 
-      const action = await UI.select('How would you like to proceed?', [
-        { name: 'Auto-stash now and re-apply after the update (recommended)', value: 'stash' },
-        { name: 'Abort — I want to commit or stash manually first', value: 'abort' }
-      ]);
+      let action;
+      if (autoStash) {
+        UI.info('Auto-stashing dirty paths (--yes / --auto-stash).');
+        action = 'stash';
+      } else {
+        action = await UI.select('How would you like to proceed?', [
+          { name: 'Auto-stash now and re-apply after the update (recommended)', value: 'stash' },
+          { name: 'Abort — I want to commit or stash manually first', value: 'abort' }
+        ]);
+      }
       if (action === 'abort') {
         UI.info('Aborted. Commit or `git stash -u`, then re-run `npx baldart update`.');
         process.exit(0);
@@ -361,9 +377,12 @@ async function update(options = {}) {
         'Convert legacy .claude/skills/ bulk symlink (v2.0.x) into the new per-item layout.',
         `Merge framework skills into per-tool skill dirs (${enabledTools.join(', ')}) without touching your personal skills.`
       ]);
-      const recreate = await UI.confirm('Reconcile symlinks now?', true);
+      const recreate = await confirm('Reconcile symlinks now?', true);
       if (recreate) {
-        await symlinks.createAllSymlinks({ mode: 'prompt', tools: enabledTools });
+        // In auto-yes mode pass 'force' instead of 'prompt' so per-conflict
+        // prompts inside SymlinkUtils don't reintroduce blocking I/O.
+        const mode = autoYes ? 'force' : 'prompt';
+        await symlinks.createAllSymlinks({ mode, tools: enabledTools });
       }
     } else {
       // Re-run the per-item merges for every enabled tool so newly-shipped
@@ -403,10 +422,10 @@ async function update(options = {}) {
       if (!fs.existsSync(configPath)) {
         UI.newline();
         UI.warning('No baldart.config.yml in this project — skills installed by this framework version require it.');
-        const runConfigure = await UI.confirm('Run `baldart configure` now?', true);
+        const runConfigure = await confirm('Run `baldart configure` now?', true);
         if (runConfigure) {
           const configureCmd = require('./configure');
-          await configureCmd();
+          await configureCmd(autoYes ? { nonInteractive: true } : undefined);
         }
       } else {
         // Schema migration: backfill `tools.enabled` for configs created
@@ -425,7 +444,7 @@ async function update(options = {}) {
           UI.warning('Pre-v3.7.0 config detected — `tools.enabled` is missing.');
           UI.info(`From v3.7.0, BALDART can install framework skills for multiple AI tools (Claude Code, OpenAI Codex CLI, …) from the same source.`);
           UI.info(`Autodetected on this machine: ${suggested.join(', ')}`);
-          const ok = await UI.confirm(`Backfill \`tools.enabled: [${suggested.join(', ')}]\` into baldart.config.yml?`, true);
+          const ok = await confirm(`Backfill \`tools.enabled: [${suggested.join(', ')}]\` into baldart.config.yml?`, true);
           if (ok) {
             cur.tools = cur.tools || {};
             cur.tools.enabled = suggested;
@@ -470,10 +489,10 @@ async function update(options = {}) {
               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);
+              const runConfigure = await confirm('Run `baldart configure` now to populate them? (existing values are preserved)', true);
               if (runConfigure) {
                 const configureCmd = require('./configure');
-                await configureCmd();
+                await configureCmd(autoYes ? { nonInteractive: true } : undefined);
               } else {
                 UI.info('Skipped. Skills will prompt for the missing keys on first use.');
               }