@kudusov.takhir/ba-toolkit 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -11,6 +11,27 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.4.0] — 2026-04-08
+
+### Added
+
+- **`ba-toolkit uninstall --for <agent>`** — remove BA Toolkit skills from an agent's directory. Symmetric to `install`: same `--for`, `--global`, `--project`, `--dry-run` flag set, same project-vs-global default. Counts files in the destination, asks `Remove {dest}? (y/N)` (defaults to N), and prints `Removed N files` after the rm completes. The pre-removal safety guard refuses to proceed unless `path.basename(destDir) === 'ba-toolkit'` — this is the only place in the CLI that calls `fs.rmSync({recursive: true})`, so it gets the strictest validation against future bugs that could turn it into `rm -rf $HOME`.
+- **`ba-toolkit upgrade --for <agent>`** (aliased as `update`) — refresh skills after a toolkit version bump. Reads the new version sentinel (see below), compares to `PKG.version`, and either prints `Already up to date` or wipes the destination wholesale and re-runs install with `force: true` (skipping the overwrite prompt). The wipe-and-reinstall approach guarantees that files removed from the toolkit between versions don't linger as ghost files in the destination — fixes the same class of bug that motivated `cmdUninstall`'s safety check. Pre-1.4 installs with no sentinel are treated as out-of-date and get a clean reinstall on first upgrade.
+- **`ba-toolkit status`** — pure read-only inspection: scans every (agent × scope) combination — 5 agents × project/global where supported, 8 real locations in total — and reports which versions of BA Toolkit are installed where. Output is grouped per installation, multi-line for readability, with colored version labels (`green: current` / `yellow: outdated` / `gray: pre-1.4 install with no sentinel`) and a summary footer pointing at `upgrade` for stale installs. Drives the natural follow-up to the version sentinel: now there's something to read it back with.
+- **Version sentinel `.ba-toolkit-version`** — `runInstall` now writes a hidden JSON marker file (`{"version": "1.4.0", "installedAt": "..."}`) into the install destination after a successful copy. The file has no `.md`/`.mdc` extension, so all five supported agents' skill loaders ignore it. Lets `upgrade` and `status` tell which package version is currently installed without diffing every file.
+- **`runInstall({..., force: true})` option** — skips the existing-destination overwrite prompt. Used by `cmdUpgrade` because it has already wiped the destination (or is in dry-run) and the prompt would just be noise. Not exposed as a CLI flag — `force` is an internal API surface only.
+
+### Fixed
+
+- **Five Tier 1 CLI fixes were already shipped in 1.3.2**, but they're worth restating in context here because 1.4.0 builds directly on the same `bin/ba-toolkit.js` improvements: `cmdInit` now honours `runInstall`'s return value (no false success message after a declined overwrite), `parseArgs` accepts `--key=value` form, the readline lifecycle and SIGINT handling are unified through a single shared interface with `INPUT_CLOSED` rejection, the slug-derivation path prints a clear error when the input has no ASCII letters, and `AGENTS.md` now lists all 21 skills (the previous template was missing the 8 cross-cutting utilities added in v1.1 and v1.2). See the 1.3.2 entry below for the per-fix detail.
+
+### Internal
+
+- **`resolveAgentDestination(...)` helper** — extracted scope-resolution logic from `runInstall`'s inline checks. `cmdUninstall` and `cmdUpgrade` reuse it. `runInstall` itself could be refactored to call the helper too in a follow-up — kept inline for now to keep this release's diff focused on the user-facing features.
+- **Documentation:** `CLAUDE.md` added at the repo root, with project conventions, the release flow (including the `.claude/settings.local.json` stash dance), the npm publish CI gotchas (curl tarball bypass for the broken bundled npm, `_authToken` strip for OIDC), and the do-not-touch list. Future Claude Code sessions get the institutional context without reading the full git log.
+
+---
+
 ## [1.3.2] — 2026-04-08
 
 ### Fixed
@@ -246,7 +267,8 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.2...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.2...v1.4.0
 [1.3.2]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.2.5...v1.3.0

package/bin/ba-toolkit.js

@@ -497,10 +497,39 @@ async function cmdInit(args) {
   log('');
 }
 
-// Core install logic. Shared between `cmdInstall` (standalone) and `cmdInit`
-// (full setup). Returns true on success, false if the user declined to
-// overwrite an existing destination.
-async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = true }) {
+// Marker file written into the install destination after a successful copy.
+// Lets `upgrade` and `status` (future command) tell which package version
+// is currently installed without diffing every file. Hidden file with no
+// `.md` / `.mdc` extension so the agent's skill loader ignores it.
+const SENTINEL_FILENAME = '.ba-toolkit-version';
+
+function readSentinel(destDir) {
+  const p = path.join(destDir, SENTINEL_FILENAME);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeSentinel(destDir) {
+  const payload = {
+    version: PKG.version,
+    installedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(
+    path.join(destDir, SENTINEL_FILENAME),
+    JSON.stringify(payload, null, 2) + '\n',
+  );
+}
+
+// Core install logic. Shared between `cmdInstall` (standalone), `cmdInit`
+// (full setup), and `cmdUpgrade`. Returns true on success, false if the
+// user declined to overwrite an existing destination. Pass `force: true`
+// to skip the overwrite prompt — `cmdUpgrade` uses this because it has
+// already wiped the destination and explicitly knows the overwrite is ok.
+async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = true, force = false }) {
   const agent = AGENTS[agentId];
   if (!agent) {
     logError(`Unknown agent: ${agentId}`);
@@ -538,7 +567,7 @@ async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = t
   log(`    format:       ${agent.format === 'mdc' ? '.mdc (converted from SKILL.md)' : 'SKILL.md (native)'}`);
   if (dryRun) log('    ' + yellow('mode:         dry-run (no files will be written)'));
 
-  if (fs.existsSync(destDir) && !dryRun) {
+  if (fs.existsSync(destDir) && !dryRun && !force) {
     const answer = await prompt(`    ${destDir} already exists. Overwrite? (y/N): `);
     if (answer.toLowerCase() !== 'y') {
       log('    cancelled.');
@@ -555,6 +584,10 @@ async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = t
     process.exit(1);
   }
 
+  if (!dryRun) {
+    writeSentinel(destDir);
+  }
+
   log('    ' + green(`${dryRun ? 'would copy' : 'copied'} ${copied.length} files.`));
   if (!dryRun && agent.format === 'mdc') {
     log('    ' + gray('SKILL.md files converted to .mdc rule format.'));
@@ -584,6 +617,271 @@ async function cmdInstall(args) {
   log('');
 }
 
+// Resolve agent + scope (project vs global) into the target directory
+// path. Shared validation for cmdUninstall — `runInstall` does its own
+// version of this inline; both could be unified later.
+function resolveAgentDestination({ agentId, isGlobal, isProject }) {
+  const agent = AGENTS[agentId];
+  if (!agent) {
+    logError(`Unknown agent: ${agentId}`);
+    log('Supported: ' + Object.keys(AGENTS).join(', '));
+    process.exit(1);
+  }
+  let effectiveGlobal = !!isGlobal;
+  if (!isGlobal && !isProject) {
+    effectiveGlobal = !agent.projectPath;
+  }
+  if (effectiveGlobal && !agent.globalPath) {
+    logError(`${agent.name} does not support --global install.`);
+    process.exit(1);
+  }
+  if (!effectiveGlobal && !agent.projectPath) {
+    logError(`${agent.name} does not support project-level install. Use --global.`);
+    process.exit(1);
+  }
+  const destDir = effectiveGlobal ? agent.globalPath : path.resolve(process.cwd(), agent.projectPath);
+  return { agent, destDir, effectiveGlobal };
+}
+
+function cmdStatus() {
+  log('');
+  log('  ' + cyan('BA Toolkit — Installation Status'));
+  log('  ' + cyan('================================'));
+  log('');
+  log(`  package version:  ${PKG.version}`);
+  log(`  scanning from:    ${process.cwd()}`);
+  log('');
+
+  // Walk every (agent × scope) combination and collect the ones whose
+  // destination directory actually exists. Project-scope paths resolve
+  // against the current working directory; global paths are absolute.
+  const rows = [];
+  for (const [agentId, agent] of Object.entries(AGENTS)) {
+    if (agent.projectPath) {
+      const projectDir = path.resolve(process.cwd(), agent.projectPath);
+      if (fs.existsSync(projectDir)) {
+        const sentinel = readSentinel(projectDir);
+        rows.push({
+          agentName: agent.name,
+          agentId,
+          scope: 'project',
+          path: projectDir,
+          version: sentinel ? sentinel.version : null,
+          installedAt: sentinel ? sentinel.installedAt : null,
+        });
+      }
+    }
+    if (agent.globalPath) {
+      if (fs.existsSync(agent.globalPath)) {
+        const sentinel = readSentinel(agent.globalPath);
+        rows.push({
+          agentName: agent.name,
+          agentId,
+          scope: 'global',
+          path: agent.globalPath,
+          version: sentinel ? sentinel.version : null,
+          installedAt: sentinel ? sentinel.installedAt : null,
+        });
+      }
+    }
+  }
+
+  if (rows.length === 0) {
+    log('  ' + gray('No BA Toolkit installations found in any known location.'));
+    log('  ' + gray("Run 'ba-toolkit install --for <agent>' to install one."));
+    log('');
+    return;
+  }
+
+  log(`  Found ${bold(rows.length)} installation${rows.length === 1 ? '' : 's'}:`);
+  log('');
+
+  for (const row of rows) {
+    let versionLabel;
+    if (!row.version) {
+      versionLabel = gray('(unknown — pre-1.4 install with no sentinel)');
+    } else if (row.version === PKG.version) {
+      versionLabel = green(row.version + ' (current)');
+    } else {
+      versionLabel = yellow(row.version + ' (outdated)');
+    }
+    log(`  ${bold(row.agentName)} ${gray('(' + row.agentId + ', ' + row.scope + ')')}`);
+    log(`    path:      ${row.path}`);
+    log(`    version:   ${versionLabel}`);
+    if (row.installedAt) {
+      log(`    installed: ${gray(row.installedAt)}`);
+    }
+    log('');
+  }
+
+  const stale = rows.filter((r) => !r.version || r.version !== PKG.version);
+  if (stale.length > 0) {
+    log('  ' + yellow(`${stale.length} installation${stale.length === 1 ? '' : 's'} not at version ${PKG.version}.`));
+    log('  ' + gray("Run 'ba-toolkit upgrade --for <agent>' to refresh."));
+    log('');
+  } else {
+    log('  ' + green('All installations are up to date.'));
+    log('');
+  }
+}
+
+async function cmdUpgrade(args) {
+  const agentId = args.flags.for;
+  if (!agentId || agentId === true) {
+    logError('--for <agent> is required.');
+    log('Supported agents: ' + Object.keys(AGENTS).join(', '));
+    process.exit(1);
+  }
+  const { agent, destDir, effectiveGlobal } = resolveAgentDestination({
+    agentId,
+    isGlobal: !!args.flags.global,
+    isProject: !!args.flags.project,
+  });
+  const dryRun = !!args.flags['dry-run'];
+
+  log('');
+  log('  ' + cyan(`BA Toolkit — Upgrade for ${agent.name}`));
+  log('  ' + cyan('================================'));
+  log('');
+  log(`  destination:  ${destDir}`);
+  log(`  scope:        ${effectiveGlobal ? 'global (user-wide)' : 'project-level'}`);
+
+  if (!fs.existsSync(destDir)) {
+    log('');
+    log('  ' + gray(`No installation found at ${destDir}.`));
+    log('  ' + gray(`Run \`ba-toolkit install --for ${agentId}\` first.`));
+    log('');
+    return;
+  }
+
+  const sentinel = readSentinel(destDir);
+  const currentVersion = PKG.version;
+  const installedVersion = sentinel ? sentinel.version : null;
+
+  if (installedVersion === currentVersion) {
+    log(`  installed:    ${installedVersion} (current)`);
+    log(`  package:      ${currentVersion}`);
+    log('');
+    log('  ' + green('Already up to date.'));
+    log('  ' + gray(`To force a clean reinstall, run \`ba-toolkit install --for ${agentId}\`.`));
+    log('');
+    return;
+  }
+
+  log(`  installed:    ${installedVersion || gray('(unknown — pre-1.4 install with no sentinel)')}`);
+  log(`  package:      ${currentVersion}`);
+  if (dryRun) log('  ' + yellow('mode:         dry-run (no files will be written)'));
+  log('');
+
+  // Safety: same guard as cmdUninstall — never rmSync anything that
+  // doesn't look like a ba-toolkit folder.
+  if (path.basename(destDir) !== 'ba-toolkit') {
+    logError(`Refusing to upgrade suspicious destination (not a ba-toolkit folder): ${destDir}`);
+    process.exit(1);
+  }
+
+  // Count files in the existing install for the dry-run preview.
+  if (dryRun) {
+    let existingCount = 0;
+    (function walk(d) {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const p = path.join(d, entry.name);
+        if (entry.isDirectory()) walk(p);
+        else existingCount++;
+      }
+    })(destDir);
+    log('  ' + yellow(`would remove ${existingCount} existing files`));
+  } else {
+    log('  ' + green('Removing previous install...'));
+    fs.rmSync(destDir, { recursive: true, force: true });
+  }
+
+  const ok = await runInstall({
+    agentId,
+    isGlobal: effectiveGlobal,
+    isProject: !effectiveGlobal,
+    dryRun,
+    showHeader: false,
+    force: true,
+  });
+  log('');
+  if (ok && !dryRun) {
+    log('  ' + cyan(`Upgraded to ${currentVersion}.`));
+    log('  ' + yellow(agent.restartHint));
+  }
+  log('');
+}
+
+async function cmdUninstall(args) {
+  const agentId = args.flags.for;
+  if (!agentId || agentId === true) {
+    logError('--for <agent> is required.');
+    log('Supported agents: ' + Object.keys(AGENTS).join(', '));
+    process.exit(1);
+  }
+  const { agent, destDir, effectiveGlobal } = resolveAgentDestination({
+    agentId,
+    isGlobal: !!args.flags.global,
+    isProject: !!args.flags.project,
+  });
+  const dryRun = !!args.flags['dry-run'];
+
+  log('');
+  log('  ' + cyan(`BA Toolkit — Uninstall from ${agent.name}`));
+  log('  ' + cyan('================================'));
+  log('');
+  log(`  destination:  ${destDir}`);
+  log(`  scope:        ${effectiveGlobal ? 'global (user-wide)' : 'project-level'}`);
+  if (dryRun) log('  ' + yellow('mode:         dry-run (no files will be removed)'));
+  log('');
+
+  // Safety: this is the only place in the CLI that calls fs.rmSync with
+  // recursive: true. Refuse to proceed unless the destination is clearly
+  // a ba-toolkit folder (the install paths in AGENTS all end in
+  // `ba-toolkit/`). Without this check, a corrupted AGENTS entry or a
+  // future bug could turn this into `rm -rf $HOME`.
+  if (path.basename(destDir) !== 'ba-toolkit') {
+    logError(`Refusing to remove suspicious destination (not a ba-toolkit folder): ${destDir}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(destDir)) {
+    log('  ' + gray(`Nothing to uninstall — ${destDir} does not exist.`));
+    log('');
+    return;
+  }
+
+  // Count files for the preview message and final confirmation.
+  let fileCount = 0;
+  (function walk(d) {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else fileCount++;
+    }
+  })(destDir);
+
+  log(`  Found ${bold(fileCount)} files in the destination.`);
+
+  if (dryRun) {
+    log('  ' + yellow(`would remove ${fileCount} files from ${destDir}.`));
+    log('');
+    return;
+  }
+
+  log('');
+  const answer = await prompt(`  Remove ${destDir}? (y/N): `);
+  if (answer.toLowerCase() !== 'y') {
+    log('  Cancelled.');
+    log('');
+    return;
+  }
+  fs.rmSync(destDir, { recursive: true, force: true });
+  log('  ' + green(`Removed ${fileCount} files from ${destDir}.`));
+  log('  ' + yellow(agent.restartHint));
+  log('');
+}
+
 function cmdHelp() {
   log(`${bold('ba-toolkit')} v${PKG.version} — AI-powered Business Analyst pipeline
 
@@ -597,6 +895,18 @@ ${bold('COMMANDS')}
                                  skills into the chosen agent's directory.
   install --for <agent>          Install (or re-install) skills into an
                                  agent's directory without creating a project.
+  uninstall --for <agent>        Remove BA Toolkit skills from an agent's
+                                 directory. Asks for confirmation before
+                                 deleting; supports --dry-run.
+  upgrade --for <agent>          Refresh skills after a toolkit version bump.
+                                 Compares the installed version sentinel
+                                 against the package version, wipes the old
+                                 install on mismatch, and re-runs install.
+                                 Aliased as 'update'.
+  status                         Scan all known install locations for every
+                                 supported agent (project + global) and
+                                 report which versions are installed where.
+                                 Read-only; no flags.
 
 ${bold('INIT OPTIONS')}
   --name <name>                  Skip the project name prompt
@@ -617,6 +927,20 @@ ${bold('INSTALL OPTIONS')}
   --project                      Project-level install (default when supported)
   --dry-run                      Preview without writing files
 
+${bold('UNINSTALL OPTIONS')}
+  --for <agent>                  One of: ${Object.keys(AGENTS).join(', ')}
+  --global                       Remove the user-wide install
+  --project                      Remove the project-level install
+                                 (default when the agent supports it)
+  --dry-run                      Preview without removing files
+
+${bold('UPGRADE OPTIONS')}
+  --for <agent>                  One of: ${Object.keys(AGENTS).join(', ')}
+  --global                       Upgrade the user-wide install
+  --project                      Upgrade the project-level install
+                                 (default when the agent supports it)
+  --dry-run                      Preview without writing or removing files
+
 ${bold('GENERAL OPTIONS')}
   --version, -v                  Print version and exit
   --help, -h                     Print this help and exit
@@ -635,6 +959,18 @@ ${bold('EXAMPLES')}
   ba-toolkit install --for claude-code
   ba-toolkit install --for cursor --dry-run
 
+  # Remove skills from an agent (asks for confirmation).
+  ba-toolkit uninstall --for claude-code
+  ba-toolkit uninstall --for claude-code --global
+  ba-toolkit uninstall --for cursor --dry-run
+
+  # After 'npm update -g @kudusov.takhir/ba-toolkit', refresh the skills.
+  ba-toolkit upgrade --for claude-code
+  ba-toolkit upgrade --for cursor --dry-run
+
+  # See where (and which version) BA Toolkit is installed.
+  ba-toolkit status
+
 ${bold('LEARN MORE')}
   https://github.com/TakhirKudusov/ba-toolkit
 `);
@@ -663,6 +999,16 @@ async function main() {
     case 'install':
       await cmdInstall(args);
       break;
+    case 'uninstall':
+      await cmdUninstall(args);
+      break;
+    case 'upgrade':
+    case 'update':
+      await cmdUpgrade(args);
+      break;
+    case 'status':
+      cmdStatus();
+      break;
     case 'help':
       cmdHelp();
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "AI-powered Business Analyst pipeline — 21 skills from project brief to development handoff. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
   "keywords": [
     "business-analyst",