Address automated review findings on PR #2482:
- source.mjs: validate URL-derived subdir with safePathInsideRoot so a
../ subdir can't copy out of the shared clone cache; run cleanup() if
the terminal copyDir throws so the temp working dir never leaks.
- install.mjs: reject unknown --channel values (e.g. a 'stabl' typo)
instead of silently treating them as the 'next' default.
- remove.mjs / update.mjs: containment-check manifest/CLI-derived paths
before destructive fs.rm / atomic swap, reusing safePathInsideRoot.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Close the remaining capability gaps where the skill's custom-module install was
narrower than the canonical installer (tools/installer/modules/custom-module-manager.js
+ channel-resolver.js). The new-spec install path was already shared code and the
legacy resolver a faithful port, so this targets only the independently-implemented
source/channel/cache plumbing.
- source.mjs parseSource: accept `owner/repo@ref`, and browser-style deep-path
git URLs (tree/blob, GitLab `-/tree`, Gitea `src/branch`, `?path=`), extracting
the embedded ref + repo subdirectory — so a module in a monorepo subfolder
installs directly. URL-based parsing handles Azure DevOps `_git`, nested
groups, and dotted repo names.
- lib/cache.mjs: shared clone cache at ~/.bmad/cache/custom-modules/<host>/<owner>/<repo>/
with .bmad-source.json/.bmad-channel.json metadata, matching the installer
(reuse on matching ref, fetch/refresh otherwise, keep stale copy on fetch
failure). materializeSource copies the module root out of the cache into a
throwaway temp tree so the cache is never mutated.
- lib/channel-resolver.mjs: node:-only port of resolveChannel (stable/next/pinned);
`stable` resolves the latest non-prerelease GitHub tag, falling back to next.
semver-lite gains prerelease/compare/rcompare so it stays registry-free.
- install.mjs/update.mjs: resolve channel+ref before clone; update re-resolves the
channel the module was installed with.
Tests + CI:
- test/test-bmad-module-source.mjs: unit coverage for parseSource, semver-lite, and
channel-resolver, at parity with the installer's test-parse-source-urls.js /
test-installer-channels.js.
- Wire the skill's unit test (test:skill-source) and its end-to-end integration
test (test:skill) into npm test, npm run quality, and the quality.yaml CI job —
the integration test was previously committed but only ever run by hand.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The standalone bmad-module skill only understood the new plugin.json#bmad
spec, so installing a legacy repo (marketplace.json + module.yaml, e.g.
bmad-code-org/bmad-module-game-dev-studio) failed with exit 20. Legacy
support existed only in the full installer's PluginResolver, which the
skill can't import (it ships self-contained under .claude/skills/).
Port that resolver into lib/legacy-resolver.mjs (strategies 1-5): when a
repo has no plugin.json#bmad but has a marketplace.json, resolve it into a
synthetic manifest of the same shape readAndValidateManifest produces, then
run it through the existing buildCopyPlan -> rewrite -> stage -> swap
pipeline unchanged. buildCopyPlan already copies marketplace.json verbatim,
flattens arbitrary skill paths to skills/<basename>, and flattens
moduleDefinition/moduleHelpCsv, so almost no downstream change is needed.
- plugin-json.mjs: extract validateManifestObject(m, {allowReserved}) and
add hasBmadPluginJson(dir). Legacy installs pass allowReserved:true so
first-party codes (gds, bmm, ...) install; new-spec authors still get
exit 21.
- install.mjs: detect new-spec -> legacy -> neither in §3; write
synthesized module.yaml/module-help.csv into the temp clone for the
strategy-5 fallback.
- cli.mjs: add --module <code> to disambiguate a multi-module marketplace
(otherwise exit 20 lists the available codes).
- help-catalog.mjs: export MODULE_HELP_CSV_HEADER for the synthesizer.
- tests: legacy fixtures (strategy-1, reserved code, synthesize fallback)
+ integration assertions. SKILL.md/README updated.
Verified: full install of the real game-dev-studio repo resolves gds and
lands 250 files under _bmad/gds/. Integration suite 97/0, installer
component tests 374/0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Remove EXIT.FILE_OVERLAP (40): never thrown anywhere; its docs
described code 70 (path traversal). Dropped from exit.mjs and the
cli.mjs --help listing.
- Document --channel on the update verb (already wired through the
scripts for both install and update).
- Trim the SKILL.md exit-code table to the codes that change what the
agent tells the user (5, 10, 80, 90); defer the full list to the
script's --help, removing the triplicated/drifting table.
- Lightly tighten the intro and script-path prose loaded on every
skill activation; no behavioral change.
Integration suite 73 pass / 0 fail; validate:refs clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This work was developed in a separate bmad-marketplace repo and is now
landing directly in BMAD-METHOD, so the migration framing is obsolete:
- remove links to docs/spec.md (only existed in the temp repo) and the
bmad-marketplace / 'upstream patch' / 'sibling checkout' references in
README, the integration test, and the acme-md-lint fixture
- drop dead 'spec §N' pointers in install.mjs, install-plan.mjs, and
plugin-json.mjs (including a user-facing reserved-code error message)
- reword the manifest-generator 'patch' note as in-repo behavior
- correct the documented install path from _bmad/ to the IDE skills
directories the installer now distributes skills to (.claude/skills/, etc.)
No behavior change. Integration suite: 73 pass / 0 fail.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The bmad-module skill copied a module's files and distributed skills to IDEs,
but skipped four post-copy steps the full `bmad install --custom-source` path
performs, leaving modules incompletely installed:
- Merge each module's module-help.csv into _bmad/_config/bmad-help.csv (the
catalog bmad-help reads) — new lib/help-catalog.mjs
- Generate [modules.<code>] / [agents.<code>] blocks in config.toml /
config.user.toml from module.yaml (defaults + --set overrides), via a
targeted merge that preserves [core] and sibling modules — new lib/config-gen.mjs
- Create the working directories a module declares under `directories:`
(with move-on-path-change and wds_folders) — new lib/module-dirs.mjs
- Run `npm install --omit=dev` in place when a module ships package.json
(opt out via bmad.install.skipNpm) — new lib/npm-deps.mjs
All four run as a shared finishModuleInstall step wired into install, update,
and remove; every step is non-fatal so a module already committed to _bmad/
isn't lost to a post-copy hiccup. Adds a repeatable --set <code>.<key>=<value>
flag mirroring the installer.
Also fixes two latent issues in the manifest-driven copy that the new steps
depend on:
- moduleDefinition / moduleHelpCsv are now flattened to the module root even
when they live inside a declared skill dir (the setup-skill assets pattern);
previously claimedSrc dedup skipped them and the rewritten plugin.json
pointed at a non-existent ./module.yaml.
- package.json / package-lock.json are now copied so npm deps can install.
Tests: extends the integration suite with config/agent-roster, --set,
directory-creation, help-catalog, removal-cleanup, and npm assertions
(73/73 pass); adds a minimal-npm fixture and rewrites the comprehensive
fixture's module-help.csv to the canonical schema.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The bmad-module skill staged community modules under _bmad/<code>/ but never
pushed their skills out to the coding assistants the user selected at
`bmad install` time, so a freshly installed module was invisible to Claude
Code / Cursor / Copilot / etc. until a full reinstall; remove left skills
orphaned in the IDE dirs.
install/update/remove now distribute (or prune) skills to every IDE listed in
_bmad/_config/manifest.yaml and clean the redundant skill dirs from _bmad/,
matching how official modules end up.
Single engine, three callers — no fork:
- New tools/installer/core/ide-sync.js (syncIdes) wraps the real
IdeManager.setupBatch + platform-codes engine. The full installer
(_setupIdes/_cleanupSkillDirs), the new `bmad ide-sync` command, and the
skill all route through it, so new IDEs and engine changes propagate
everywhere automatically.
Local, dependency-free delivery — no npx/network at runtime:
- build-ide-sync.mjs esbuild-bundles the engine into vendor/ide-sync.mjs
(+ platform-codes.yaml), aliasing ../prompts and ../project-root to small
shims so @clack and the installer graph are dropped. The bundle ships inside
the skill tree (like yaml.mjs); the skill execs it locally. It's
generated-from-source and gated by vendor:check, refreshed on every install.
update/remove pass --prune with the module's canonicalIds so skills dropped
between versions (or on uninstall) are removed from IDE dirs + command
pointers. Graceful degradation: if the bundle is unreachable, the verb still
succeeds and points the user at `bmad ide-sync`.
Tests: new test/test-ide-sync.js drift-guard (engine == bundle, incl. prune),
integration.test.sh IDE-distribution section (offline), bundle self-check in
the build. All gates green (vendor:check, lint, format, test:install 349/349).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The copy planner treated every skills/agents/commands entry as a
directory and ran it through addDirRecursive, which lists files *under*
the path. For a subagent declared as a file (e.g.
`"agents": ["./agents/foo.md"]` — a standard Claude-Code shape) that
listed nothing, so the agent was silently dropped from the install even
though rewriteManifestPaths already remapped it to `./agents/foo.md`.
Stat each entry and branch: directories recurse as before, files are
queued directly (honoring the ignore matcher). Verified by the
comprehensive fixture's changelog-archivist.md agent.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the flat copy-list staging with a manifest-driven copy plan:
- buildCopyPlan maps declared skills/agents/commands and string-typed
Claude-Code surfaces into canonical install slots, copies conventional
top-level metadata, and drops anything not covered (no more leaking of
tools/, website/, .github/, etc.).
- rewriteManifestPaths emits a plugin.json whose paths point at the
canonical post-install locations, keeping the on-disk manifest
self-consistent inside _bmad/<code>/.
- stageCopyPlan stages the plan plus synthesized files (rewritten
plugin.json) into the tmp dir for the atomic swap.
install.mjs and update.mjs switch to the new plan/skillDestDirs flow and
drop the now-unused copy-list helpers.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The skill is copied into _bmad/core/skills/bmad-module/ by the installer,
which strips node_modules, ships no package.json under the skill, and never
runs npm install there. Bare `import 'yaml'`/`import 'semver'` therefore
crashed at module load (ERR_MODULE_NOT_FOUND, exit 1) before any structured
exit code could fire. Every other installed script is zero-third-party-dep.
- Vendor the real yaml@2.8.4 as a deterministic esbuild single-file bundle
(scripts/lib/vendor/yaml.mjs), imported by relative path. Guarantees
byte-identical manifest.yaml round-trips with BMAD core's writer, which uses
the same library + options (tools/installer/core/manifest.js).
- Drop semver for a node:-only semver-lite.mjs (valid/validRange),
parity-tested against the real semver across 469 cases (400 fuzzed).
- Fix a third bare yaml import that the original report missed (frontmatter.mjs).
- Make bmad-module.mjs a zero-import launcher that maps any load failure to a
new documented EXIT.TOOLING (5) with reinstall guidance instead of leaking a
raw ESM stack trace; the verb dispatcher moves to cli.mjs.
- Enforce vendor freshness so a yaml/esbuild bump can't ship a stale bundle:
build-vendor.mjs --check is wired into npm test (pre-commit), npm run quality,
and the quality.yaml CI validate job. Adds vendor:build / vendor:check scripts.
- Ignore the generated vendor/ dir in eslint + prettier; document the rationale
in SKILL.md, README.md, and vendor/README.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
pbean
Brian Madison