ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/tools/installer
History
Brian Madison 1ab4d5f93c refactor(installer): simplify --set to a post-install TOML patch 
The original implementation tried to integrate `--set` with the prompt /
result-template / schema-strict-partition system: pre-seeding answers,
filtering questions, evaluating function defaults, tracking override
keys for partition exemption, mirroring carry-forward in two collection
helpers, threading state through Config + ui.js + collection helpers +
manifest writer. ~900 lines spawned across 4 review rounds, with bugs
the bots kept finding because every change touched a different layer.

The simpler model: `--set` is a post-install patch. The installer runs
its normal flow untouched, then `applySetOverrides` upserts each value
into `_bmad/config.toml` (team scope) or `_bmad/config.user.toml` (user
scope) AND into `_bmad/<module>/config.yaml` so declared keys carry
forward via the existingValue path on the next install.

What gets ripped out
- All `setOverrides` plumbing through OfficialModules (constructor
  field, applyOverridesAfterSeeding, _trackUnknownKeysAsOverrides,
  declaredResultKeys, override classification + pre-write +
  question-filter + two-pass function-defaults + carry-forward in
  collectModuleConfig, _trackUnknownKeysAsOverrides calls in
  collectModuleConfigQuick, headless-branch additions in
  Installer.build). official-modules.js reset to its pre-#1663 baseline
  (commit 48a7ec8b).
- `setOverrideKeys` field on Config, threading from ui.js, partition
  exemption parameter on `manifest-generator.writeCentralConfig`.
- The "ignored under quick-update" warning in install.js — `--set` is
  now a uniform post-install patch, so it works the same way for
  quick-update as for a regular install.

What stays
- `tools/installer/set-overrides.js` parser with the prototype-pollution
  guard, prefixed by the new `applySetOverrides` / `upsertTomlKey` /
  `tomlString` / `tomlHasKey` helpers.
- `tools/installer/list-options.js` — small standalone discovery
  helper, untouched.
- The `--set` and `--list-options` CLI flag registration in
  `commands/install.js`.
- ui.js `collectModuleConfigs` retains the early-feedback warning for
  overrides targeting modules not in the install set (and now also
  filters them out of `setOverrides` before threading).

Routing rules (post-install patch)
- If `_bmad/config.user.toml` already has `[section] key`, update it
  there (so user-scope keys like `core.user_name` and
  `bmm.user_skill_level` keep their proper file).
- Otherwise update `_bmad/config.toml` (team scope, default).
- A module without `_bmad/<module>/config.yaml` (i.e. not installed)
  is skipped silently — no orphan `[modules.notamodule]` sections.

Tradeoffs documented in `docs/how-to/install-bmad.md`
- Values are written verbatim — no `result:` template rendering. Pass
  `--set bmm.project_knowledge='{project-root}/research'` if you want
  the rendered form.
- Carry-forward is automatic for declared schema keys (per-module yaml
  → existingValue → prompt default → accepted under --yes). For keys
  outside any module's schema, the value lands in `config.toml` for
  the current install but won't be re-emitted on the next install.
  Re-pass `--set` if you need it sticky.
- No "key not in schema" validation — whatever you assert is written.

Tests: Suite 44 rewritten. 355 passing (was 351). Coverage now focused
on what matters: parser + pollution guard, tomlString escaping,
upsertTomlKey across insert/replace/missing-section/empty-file/
preserved-newline cases, applySetOverrides happy path + uninstalled-
module skip + missing-user-toml-creation + empty-input no-op,
discoverOfficialModuleYamls / formatOptionsList sanity.

E2E smoke verified across all 6 scenarios:
1. fresh install with mixed declared + undeclared --set → correct files
2. quick-update no --set → declared keys persist via per-module yaml
3. quick-update WITH --set → applies (used to be warned + dropped)
4. --set for unselected module → warned, no orphan section
5. prototype pollution → exit 1
6. --list-options bmm exit 0, --list-options nope exit 1

Net: -158 lines vs HEAD. The complex integration was load-bearing for
edge cases nobody actually needed; the simple post-install patch
covers the real use case (script a config value from CI) without the
schema gymnastics.
 		2026-04-28 19:48:30 -05:00
..
commands refactor(installer): simplify --set to a post-install TOML patch 2026-04-28 19:48:30 -05:00
core refactor(installer): simplify --set to a post-install TOML patch 2026-04-28 19:48:30 -05:00
ide fix(installer): require --tools for fresh --yes installs; remove --tools none (#2346) 2026-04-27 23:01:23 -05:00
modules refactor(installer): simplify --set to a post-install TOML patch 2026-04-28 19:48:30 -05:00
README.md refactor(installer): restructure installer with clean separation of concerns (#2129) 2026-03-27 06:50:07 -06:00
bmad-cli.js fix(publish): advance @next dist-tag after stable release (#2320) 2026-04-26 10:30:41 -05:00
cli-utils.js chore(installer): remove 1,683 lines of dead code (#2247) 2026-04-10 20:24:50 -07:00
file-ops.js fix(installer): replace fs-extra with native node:fs to prevent file loss 2026-04-13 00:44:28 -05:00
fs-native.js fix(installer): add missing sync and async methods to fs-native wrapper 2026-04-13 09:59:41 -05:00
install-messages.yaml feat(installer): overhaul branding, versioning, and skill cleanup (#2223) 2026-04-07 02:31:36 -05:00
list-options.js fix(installer): address fourth-round PR #2353 review comments 2026-04-28 18:59:17 -05:00
message-loader.js fix(installer): replace fs-extra with native node:fs to prevent file loss 2026-04-13 00:44:28 -05:00
project-root.js fix(installer): route community installs through PluginResolver when marketplace.json ships (#2331) 2026-04-26 22:50:47 -05:00
prompts.js chore(installer): remove 1,683 lines of dead code (#2247) 2026-04-10 20:24:50 -07:00
set-overrides.js refactor(installer): simplify --set to a post-install TOML patch 2026-04-28 19:48:30 -05:00
ui.js refactor(installer): simplify --set to a post-install TOML patch 2026-04-28 19:48:30 -05:00
yaml-format.js refactor(installer): restructure installer with clean separation of concerns (#2129) 2026-03-27 06:50:07 -06:00

README.md

BMad CLI Tool

Installing external repo BMad official modules

For external official modules to be discoverable during install, ensure an entry for the external repo is added to external-official-modules.yaml.

For community modules - this will be handled in a different way. This file is only for registration of modules under the bmad-code-org.

Post-Install Notes

Modules can display setup guidance to users after configuration is collected during npx bmad-method install. Notes are defined in the module's own module.yaml — no changes to the installer are needed.

Simple Format

Always displayed after the module is configured:

post-install-notes: |
  Thank you for choosing the XYZ Cool Module
  For Support about this Module call 555-1212

Conditional Format

Display different messages based on a config question's answer:

post-install-notes:
  config_key_name:
    value1: |
      Instructions for value1...      
    value2: |
      Instructions for value2...

Values without an entry (e.g., none) display nothing. Multiple config keys can each have their own conditional notes.

Example: TEA Module

The TEA module uses the conditional format keyed on tea_browser_automation:

post-install-notes:
  tea_browser_automation:
    cli: |
      Playwright CLI Setup:
        npm install -g @playwright/cli@latest
        playwright-cli install --skills      
    mcp: |
      Playwright MCP Setup (two servers):
        1. playwright    — npx @playwright/mcp@latest
        2. playwright-test — npx playwright run-test-mcp-server      
    auto: |
      Playwright CLI Setup:
        ...
      Playwright MCP Setup (two servers):
        ...

When a user selects auto, they see both CLI and MCP instructions. When they select none, nothing is shown.