@kudusov.takhir/ba-toolkit 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -11,6 +11,18 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.3.2] — 2026-04-08
+
+### Fixed
+
+- **`bin/ba-toolkit.js` `cmdInit` ignored `runInstall` return value.** When the user declined the "Overwrite? (y/N)" prompt for an existing skill destination, `runInstall` returned `false`, but `cmdInit` ignored it and printed the success path ("Project is ready. Next steps: Restart Claude Code to load the new skills") even though no skills were installed. The next-steps block now branches on the install result and tells the user how to retry: `ba-toolkit install --for {agentId}`.
+- **`parseArgs` did not accept `--key=value` form.** The hand-rolled parser only understood `--key value` (space-separated). Users typing the GNU long-option style accepted by git/npm/gh (`--name=MyApp`, `--domain=saas`) silently lost the value — the flag was stored as `name=MyApp` set to `true` and the script then prompted for the project name interactively. Both forms now work and can be mixed in a single invocation. Splits on the first `=` only, so values containing further `=` characters are preserved (e.g. `--name="Foo=Bar"`).
+- **No SIGINT handler / readline lifecycle issues.** Each `prompt()` call previously created a fresh `readline.Interface` and closed it after the answer. Hitting Ctrl+C mid-prompt killed Node abruptly and left some terminals in raw mode. Piped stdin that closed mid-flow caused the next prompt's promise to hang forever and the process to exit silently with no error message. Fixed by switching to a single shared `readline.Interface` per CLI invocation, adding a `process.on('SIGINT')` handler that prints a clean `Cancelled.` message and exits with code 130, and rejecting in-flight prompt promises with `err.code = 'INPUT_CLOSED'` when the input stream closes prematurely. The outer `main().catch(...)` filters this code to print a friendly two-line message instead of a Node stack trace.
+- **Silent failure when slug could not be derived from a non-ASCII name.** `sanitiseSlug` strips everything outside `[a-z0-9-]`, so `--name "Проект Космос"` or `--name "🚀"` produced an empty derived slug. In the non-interactive path the script then exited with a generic `Invalid or empty slug` error with no clue about why. Now in the non-interactive path it prints `Cannot derive a slug from "{name}" — it contains no ASCII letters or digits` plus a one-line workaround (`Pass an explicit slug with --slug, e.g. --slug my-project`). In the interactive path it prints a gray hint above the manual slug prompt explaining we couldn't auto-derive.
+- **`AGENTS.md` template was missing 8 of the 21 skills.** `renderAgentsMd` emitted a "Pipeline Status" table with 13 rows — the 12 numbered stages + the `7a` sub-step. The 8 cross-cutting utilities added in v1.1 and v1.2 (`/trace`, `/clarify`, `/analyze`, `/estimate`, `/glossary`, `/export`, `/risk`, `/sprint`) were missing entirely. Since `AGENTS.md` is the project context every AI agent reads on entry to a new session, those 8 skills were effectively invisible — agents didn't know they existed without re-reading README. Added a second "Cross-cutting Tools" section below the pipeline table listing all 8, with descriptions copied from the canonical README pipeline table. A `MAINTENANCE` comment above the function reminds future-me to update both tables when adding a new skill.
+
+---
+
 ## [1.3.1] — 2026-04-08
 
 ### Fixed
@@ -234,7 +246,8 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.2...HEAD
+[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
 [1.2.5]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.2.4...v1.2.5

package/bin/ba-toolkit.js

@@ -94,6 +94,15 @@ function parseArgs(argv) {
       break;
     }
     if (a.startsWith('--')) {
+      // Support --key=value form (in addition to --key value). The `=` must
+      // come after at least one character of key, so `--=value` and `--`
+      // alone fall through. Splits on the FIRST `=` only — values may
+      // contain further `=` characters.
+      const eqIdx = a.indexOf('=');
+      if (eqIdx > 2) {
+        args.flags[a.slice(2, eqIdx)] = a.slice(eqIdx + 1);
+        continue;
+      }
       const key = a.slice(2);
       const next = argv[i + 1];
       if (next !== undefined && !next.startsWith('-')) {
@@ -114,16 +123,42 @@ function parseArgs(argv) {
 
 // --- Prompt helper -----------------------------------------------------
 
+// Shared across all prompts in a single CLI invocation. Creating a new
+// readline.Interface for every question (the previous approach) made Ctrl+C
+// handling unreliable, leaked listeners on stdin, and broke when stdin was
+// piped (EOF on the second create). One interface per process, closed by
+// closeReadline() once main() finishes (or by the SIGINT handler).
+let sharedRl = null;
+
 function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
+  if (!sharedRl) {
+    sharedRl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  }
+  return new Promise((resolve, reject) => {
+    let answered = false;
+    const onClose = () => {
+      if (!answered) {
+        const err = new Error('input stream closed before answer');
+        err.code = 'INPUT_CLOSED';
+        reject(err);
+      }
+    };
+    sharedRl.once('close', onClose);
+    sharedRl.question(question, (answer) => {
+      answered = true;
+      sharedRl.removeListener('close', onClose);
       resolve(answer.trim());
     });
   });
 }
 
+function closeReadline() {
+  if (sharedRl) {
+    sharedRl.close();
+    sharedRl = null;
+  }
+}
+
 // --- Utilities ---------------------------------------------------------
 
 function sanitiseSlug(input) {
@@ -222,6 +257,12 @@ function skillToMdc(srcPath, destPath) {
   return { destPath: newDestPath, content: mdcFrontmatter + body };
 }
 
+// MAINTENANCE: when adding a new skill, update BOTH tables below.
+// - Sequential pipeline stages (numbered 0-11 + 7a sub-step) go in
+//   "Pipeline Status" — they have a per-project status that progresses.
+// - Cross-cutting utilities (no fixed stage) go in "Cross-cutting Tools".
+// The README.md pipeline table is the canonical source of truth for the
+// 21-skill list and ordering; keep this template in sync with it.
 function renderAgentsMd({ name, slug, domain }) {
   return `# BA Toolkit — Project Context
 
@@ -253,6 +294,21 @@ function renderAgentsMd({ name, slug, domain }) {
 | 10 | /scenarios | ⬜ Not started | — |
 | 11 | /handoff | ⬜ Not started | — |
 
+## Cross-cutting Tools
+
+Utilities available throughout the pipeline. No fixed stage — invoke whenever they help. See README.md for the prerequisites of each.
+
+| Tool | Purpose |
+|------|---------|
+| /trace | Traceability Matrix + coverage gaps |
+| /clarify [focus] | Targeted ambiguity resolution for any artifact |
+| /analyze | Cross-artifact quality report with severity-rated findings |
+| /estimate | Effort estimation — Fibonacci SP, T-shirt sizes, or person-days |
+| /glossary | Unified project glossary with terminology drift detection |
+| /export [format] | Export User Stories to Jira / GitHub Issues / Linear / CSV |
+| /risk | Risk register — probability × impact matrix, mitigation per risk |
+| /sprint | Sprint plan — stories grouped by velocity and capacity with sprint goals |
+
 ## Key Constraints
 
 - Domain: ${domain}
@@ -293,12 +349,22 @@ async function cmdInit(args) {
   if (!slug) {
     const derived = sanitiseSlug(name);
     if (nameFromFlag) {
-      // Non-interactive path: silently accept the derived slug.
+      // Non-interactive path. Either accept the derived slug, or fail
+      // loudly with a hint when the name has no ASCII letters/digits to
+      // derive from (e.g. `--name "Проект"` or `--name "🚀"`). Without
+      // this branch the user got an opaque "Invalid or empty slug" with
+      // no clue why.
+      if (!derived) {
+        logError(`Cannot derive a slug from "${name}" — it contains no ASCII letters or digits.`);
+        log('Pass an explicit slug with --slug, e.g. --slug my-project');
+        process.exit(1);
+      }
       slug = derived;
     } else if (derived) {
       const custom = await prompt(`  Project slug [${cyan(derived)}]: `);
       slug = custom || derived;
     } else {
+      log('  ' + gray(`(could not derive a slug from "${name}" — please type one manually)`));
       slug = await prompt('  Project slug (lowercase, hyphens only): ');
     }
   }
@@ -389,9 +455,13 @@ async function cmdInit(args) {
   }
 
   // --- 6. Install skills for the selected agent ---
+  // installed: null = no install attempted (--no-install or no agentId),
+  //            true = install succeeded,
+  //            false = install was cancelled (e.g. user declined overwrite).
+  let installed = null;
   if (!skipInstall && agentId) {
     log('');
-    await runInstall({
+    installed = await runInstall({
       agentId,
       isGlobal: !!args.flags.global,
       isProject: !!args.flags.project,
@@ -405,10 +475,16 @@ async function cmdInit(args) {
   log('  ' + cyan(`Project '${name}' (${slug}) is ready.`));
   log('');
   log('  ' + yellow('Next steps:'));
-  if (!skipInstall && agentId) {
+  if (installed === true) {
     log('    1. ' + AGENTS[agentId].restartHint);
     log('    2. Optional: run /principles to define project-wide conventions');
     log('    3. Run /brief to start the BA pipeline');
+  } else if (installed === false) {
+    log('    1. Skill install was cancelled. To install later, run:');
+    log('         ' + gray(`ba-toolkit install --for ${agentId}`));
+    log('    2. Open your AI assistant (Claude, Cursor, etc.)');
+    log('    3. Optional: run /principles to define project-wide conventions');
+    log('    4. Run /brief to start the BA pipeline');
   } else {
     log('    1. Install skills for your agent:');
     log('         ' + gray('ba-toolkit install --for claude-code'));
@@ -597,7 +673,26 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  logError(err && (err.stack || err.message) || String(err));
-  process.exit(1);
+// Clean exit on Ctrl+C: print on a fresh line so we don't append to a
+// half-typed prompt, close the readline interface so the terminal is
+// returned to a sane state, then exit with the conventional 130 code.
+process.on('SIGINT', () => {
+  console.log('\n  ' + yellow('Cancelled.'));
+  closeReadline();
+  process.exit(130);
 });
+
+main()
+  .then(() => {
+    closeReadline();
+  })
+  .catch((err) => {
+    closeReadline();
+    if (err && err.code === 'INPUT_CLOSED') {
+      logError('Input stream closed before all prompts could be answered.');
+      log('Pass remaining values as flags (e.g. --name, --domain, --for) or run interactively.');
+      process.exit(1);
+    }
+    logError(err && (err.stack || err.message) || String(err));
+    process.exit(1);
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "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",