@kudusov.takhir/ba-toolkit 1.4.0 → 2.0.0

package/CHANGELOG.md

@@ -11,6 +11,89 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [2.0.0] — 2026-04-09
+
+### ⚠️ BREAKING — install layout dropped the `ba-toolkit/` wrapper
+
+**Every previous version of this package was broken.** The CLI installed skills under a `ba-toolkit/` wrapper folder (e.g. `.claude/skills/ba-toolkit/brief/SKILL.md`), but Claude Code, Codex CLI, Gemini CLI, Cursor and Windsurf all expect skills as **direct children** of their skills/rules root (`.claude/skills/<skill-name>/SKILL.md`). The wrapper made every shipped skill invisible to the agent — `/brief`, `/srs`, etc. silently did nothing because the agent didn't know they existed. The README, examples and all documentation referenced `/brief`, but the install path made it impossible for that command to ever resolve. Confirmed against the [official Claude Code skills documentation](https://code.claude.com/docs/en/skills.md): *"Each skill is a directory with `SKILL.md` as the entrypoint"* under `.claude/skills/<skill-name>/`, with no nested-namespace support.
+
+v2.0 fixes this for real:
+
+- **All 5 agent install paths drop the `ba-toolkit/` wrapper.** New paths:
+  - Claude Code: `.claude/skills/` (project) and `~/.claude/skills/` (global)
+  - OpenAI Codex CLI: `~/.codex/skills/` (global only)
+  - Gemini CLI: `.gemini/skills/` and `~/.gemini/skills/`
+  - Cursor: `.cursor/rules/` (project only, flat .mdc files)
+  - Windsurf: `.windsurf/rules/` (project only, flat .mdc files)
+- **Cursor and Windsurf layouts are now flat.** Previously each skill was nested under `.cursor/rules/ba-toolkit/<skill>/<skill>.mdc` (3 levels). Now each becomes a single `.mdc` file at the rules root: `.cursor/rules/<skill>.mdc`. Cursor's rule loader expects flat `.mdc` files, never recurses.
+- **SKILL.md `name:` field renamed.** The 21 SKILL.md files used `name: ba-brief`, `name: ba-srs`, etc. But Claude Code derives the slash command from the `name` field — so the actual command was `/ba-brief`, not `/brief` as the README promised. All 21 files now use bare names (`name: brief`, `name: srs`, ...), and the slash commands `/brief`, `/srs`, `/ac`, … finally match the documentation.
+- **Manifest replaces sentinel.** `runInstall` now writes `.ba-toolkit-manifest.json` listing every item it owns at the destination root. `cmdUninstall` and `cmdUpgrade` read the manifest and remove **only** those items — the destination directory is now shared with the user's other skills, so we can never `rm -rf` the whole root. Without a manifest, uninstall and upgrade refuse to do anything destructive. Manifest format:
+  ```json
+  {
+    "version": "2.0.0",
+    "installedAt": "2026-04-09T...",
+    "format": "skill",
+    "items": ["brief", "srs", "ac", ..., "references"]
+  }
+  ```
+- **Legacy v1.x detection.** `runInstall`, `cmdUpgrade`, `cmdUninstall`, and `cmdStatus` now detect the old `ba-toolkit/` wrapper folder if it's still on disk and print a yellow warning with the exact `rm -rf` command to clean it up. The legacy folder is never auto-deleted — it might contain user state.
+
+### Migration from v1.x
+
+If you have a v1.x install on disk, the legacy `ba-toolkit/` wrapper will be sitting in the same parent directory as the new layout — it doesn't conflict with v2.0 file-wise, but it never worked, so you should remove it:
+
+```bash
+# Manual cleanup (one-time, per agent that had a v1.x install):
+rm -rf .claude/skills/ba-toolkit          # claude-code project-level
+rm -rf ~/.claude/skills/ba-toolkit         # claude-code global
+rm -rf ~/.codex/skills/ba-toolkit          # codex
+rm -rf .gemini/skills/ba-toolkit           # gemini project-level
+rm -rf ~/.gemini/skills/ba-toolkit         # gemini global
+rm -rf .cursor/rules/ba-toolkit            # cursor
+rm -rf .windsurf/rules/ba-toolkit          # windsurf
+
+# Then reinstall with v2.0:
+ba-toolkit install --for claude-code
+```
+
+`ba-toolkit status` lists any legacy wrappers it finds on the system as a warning row, so you can audit before cleaning up.
+
+### Internal
+
+- **`copySkills(srcRoot, destRoot, { format })` replaces the previous `copyDir` + `skillToMdc`** combo. The new copy logic understands the per-format layout (folder-per-skill for `skill` format, flat `.mdc` files for `mdc` format) and reads the SKILL.md frontmatter to derive the canonical skill name from the `name:` field. References go to `<destRoot>/references/` regardless of format — non-`.mdc` files there are ignored by Cursor's rule loader.
+- **Manifest helpers** (`readManifest`, `writeManifest`, `removeManifestItems`) replace the previous `readSentinel` / `writeSentinel`. The sentinel was a 2-field marker; the manifest is also the source of truth for what to remove on uninstall.
+- **`detectLegacyInstall(agent)`** helper, used by every command that touches the install layout.
+- **Test count 91 → 95.** Sentinel tests replaced with manifest tests; new tests for `detectLegacyInstall` (positive and negative cases) and `skillToMdcContent` (frontmatter + body extraction). All 95 tests pass.
+
+---
+
+## [1.5.0] — 2026-04-08
+
+### Added
+
+- **Typo detection on unknown CLI flags**, with a Levenshtein-based "Did you mean ...?" hint. Previously the parser silently accepted any `--flag` and stored it in `args.flags`, where most code paths then ignored it — users would hit `ba-toolkit init --drry-run`, get no error, and watch the script start an interactive session wondering why their flag did nothing. Now `validateFlags` runs immediately after parsing and rejects anything not in `KNOWN_FLAGS`:
+  ```
+  $ ba-toolkit init --drry-run
+  error: Unknown option: --drry-run
+    Did you mean --dry-run?
+  Run ba-toolkit --help for the full list of options.
+  ```
+  The Levenshtein threshold is calibrated (`max(1, floor(input.length / 3))`) so common typos like `--domian`, `--gloabl`, `--no-installl`, `--foo`/`--for` get matched, but unrelated inputs like `--foobar` (distance 3 from "global") get no suggestion at all — better to say nothing than suggest something wildly off.
+
+### Changed
+
+- **Help output is ~20 lines shorter.** Four nearly-duplicate options sections (`INIT OPTIONS`, `INSTALL OPTIONS`, `UNINSTALL OPTIONS`, `UPGRADE OPTIONS`) collapsed into a single `OPTIONS` section. Each flag is listed exactly once with a per-command scope annotation (`init only — ...`, `install/uninstall/upgrade — ...`). Three sections after v1.4.0 added `uninstall`/`upgrade` repeated the same four flags with only wording differences; the dedup removes the noise without losing any information.
+- **Domain and agent menu column widths are now computed dynamically** from the longest entry instead of being hardcoded to magic constants (`padEnd(13)` and `padEnd(20)`). If a future commit adds a domain or agent with a longer display name, the em-dash column on the right stays aligned automatically. No visible change for the current set.
+
+### Internal
+
+- **`AGENTS.md` template extracted** to `skills/references/templates/agents-template.md`. Previously it lived as a 44-line embedded string in `bin/ba-toolkit.js`, which was the only artifact template not in `skills/references/templates/`. Now follows the same `[NAME]` / `[SLUG]` / `[DOMAIN]` / `[DATE]` placeholder convention as `brief-template.md`, `srs-template.md`, etc. `renderAgentsMd` shrinks from a 60-line string template to a 12-line file read + four `String.replace` calls. Adding a field to the auto-generated AGENTS.md is now a Markdown edit, not a JS edit.
+- **`stringFlag(args, key)` helper extracted** to centralise the `flag && flag !== true` (and inverse `!flag || flag === true`) pattern that was repeated across `cmdInit` (4 sites), `cmdInstall`, `cmdUninstall`, `cmdUpgrade` (3 sites). Returns the string value or `null` for absent / boolean / empty-string flags. The seven call sites collapse to single-line `stringFlag(args, 'name')` reads.
+- **`parseSkillFrontmatter(content)` mini-parser** replaces the three regexes that `skillToMdc` used to extract `name` and `description` from SKILL.md frontmatter. The previous folded-scalar regex (`description:\s*>\s*\r?\n([\s\S]*?)(?:\r?\n\w|$)`) used a fragile `\r?\n\w` lookahead that would have over-captured on multi-paragraph descriptions and silently misparsed the `|` literal block scalar form (no shipped SKILL.md uses it yet, but the trap was there). The new walker handles inline / folded / literal forms uniformly, recognises chomping indicators (`>+`/`>-`/`|+`/`|-`), and correctly collapses multi-paragraph blocks with blank lines. Backward-compat verified by running `ba-toolkit install --for cursor` and confirming all 21 generated `.mdc` files have the same descriptions as before.
+- **Unit-test infrastructure (78 → 91 tests).** Pure helper functions (`sanitiseSlug`, `parseArgs`, `resolveDomain`, `resolveAgent`, `stringFlag`, `parseSkillFrontmatter`, `readSentinel`, `renderAgentsMd`, `levenshtein`, `closestMatch`) are now exported from `bin/ba-toolkit.js` (guarded by `require.main === module` so the CLI still runs directly), and covered by `test/cli.test.js` using Node's built-in `node:test` runner — zero added dependencies. The test file does not ship to npm consumers (`test/` is not in `package.json`'s `files` whitelist). Includes one integration test that loads every shipped `SKILL.md` and asserts the parser produces a non-empty single-line description for each — catches regressions where a future skill is added with a frontmatter form the parser doesn't understand.
+
+---
+
 ## [1.4.0] — 2026-04-08
 
 ### Added
@@ -267,7 +350,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.5.0...v2.0.0
+[1.5.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.4.0...v1.5.0
 [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

package/README.md

@@ -55,36 +55,45 @@ Supported agents: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. Cursor
 
 Use these if you can't use npm or want to track a specific git commit.
 
+**Important — v2.0 layout:** the skills go directly under the agent's skills root, not nested under a `ba-toolkit/` wrapper folder. Versions before v2.0 used a wrapper, which made every skill invisible to the agent. If you're upgrading from v1.x, remove the legacy wrapper folder first.
+
 ### Claude Code CLI
 
 ```bash
 git clone https://github.com/TakhirKudusov/ba-toolkit.git
-cp -r ba-toolkit/skills/ /path/to/project/.claude/skills/ba-toolkit/
 
-# Or install globally:
-cp -r ba-toolkit/skills/ ~/.claude/skills/ba-toolkit/
+# Project-level: copy the contents of skills/ into .claude/skills/
+mkdir -p /path/to/project/.claude/skills
+cp -R ba-toolkit/skills/. /path/to/project/.claude/skills/
+
+# Or globally:
+mkdir -p ~/.claude/skills
+cp -R ba-toolkit/skills/. ~/.claude/skills/
 ```
 
-Keep the full tree: skill folders (`brief/`, `srs/`, …) must stay together with `references/` in the same parent directory.
+Each skill folder (`brief/`, `srs/`, …) lands as a direct child of `.claude/skills/`, and the `references/` folder sits next to them. If you have other skills installed in the same directory, they're left alone.
 
 ### OpenAI Codex CLI
 
 Skills load from `$CODEX_HOME/skills` (default `~/.codex/skills`):
 
 ```bash
-cp -r ba-toolkit/skills/ ~/.codex/skills/ba-toolkit/
+mkdir -p ~/.codex/skills
+cp -R ba-toolkit/skills/. ~/.codex/skills/
 ```
 
-If you use a custom Codex home, set `CODEX_HOME` and copy under `$CODEX_HOME/skills/ba-toolkit/`.
+If you use a custom Codex home, set `CODEX_HOME` and copy under `$CODEX_HOME/skills/`.
 
 ### Google Gemini CLI
 
 ```bash
 # User-wide (all projects)
-cp -r ba-toolkit/skills/ ~/.gemini/skills/ba-toolkit/
+mkdir -p ~/.gemini/skills
+cp -R ba-toolkit/skills/. ~/.gemini/skills/
 
 # Or project-only
-cp -r ba-toolkit/skills/ /path/to/project/.gemini/skills/ba-toolkit/
+mkdir -p /path/to/project/.gemini/skills
+cp -R ba-toolkit/skills/. /path/to/project/.gemini/skills/
 ```
 
 Reload the CLI after copying.
@@ -193,9 +202,9 @@ BA Toolkit uses the open Agent Skills specification (`SKILL.md` format) publishe
 
 | Platform | Support | Installation |
 |----------|:-------:|-------------|
-| **Claude Code** | Native | `cp -r skills/ .claude/skills/ba-toolkit/` |
-| **OpenAI Codex CLI** | Native | `cp -r skills/ ~/.codex/skills/ba-toolkit/` |
-| **Gemini CLI** | Native | Copy `skills/` to `~/.gemini/skills/ba-toolkit/` (user) or `.gemini/skills/ba-toolkit/` (workspace) |
+| **Claude Code** | Native | `cp -R skills/. .claude/skills/` |
+| **OpenAI Codex CLI** | Native | `cp -R skills/. ~/.codex/skills/` |
+| **Gemini CLI** | Native | Copy `skills/.` contents to `~/.gemini/skills/` (user) or `.gemini/skills/` (workspace) |
 | **Cursor** | Convert | `SKILL.md` → `.mdc` rules in `.cursor/rules/` |
 | **Windsurf** | Convert | `SKILL.md` → rules in `.windsurf/rules/` |
 | **Aider** | Convert | `SKILL.md` → conventions file |