ma-agents 2.19.2 → 2.20.1

package/docs/validation/bundled-installation-validation.md

@@ -0,0 +1,52 @@
+# Bundled BMAD Installation Validation
+
+**Package version:** ma-agents 2.19.2
+**bmad-method version:** 6.0.4
+**Validation date:** 2026-03-16
+**Tester environment:** Node.js v22.14.0, OS: Windows 10 Enterprise LTSC 2021 (10.0.19044), npm v11.7.0
+
+## Validation Steps
+
+| Step | Description | Result | Notes |
+|------|-------------|--------|-------|
+| V1 | npm pack → tarball contains lib/bmad-cache/ | PASS | 753 files; bmb, cis, gds, tea dirs confirmed via `npm pack --dry-run` |
+| V2 | npm install from tarball — bmad-method present in node_modules | PASS | `bmad-method@6.0.4` at top-level node_modules |
+| V3 | npx ma-agents install — cache pre-population messages appear | PASS | `~ Cached module exists, skipping: <mod>` × 4 (already in global cache from tarball install) |
+| V4 | Post-install: ~/.bmad/cache/external-modules/ has 4 modules | PASS | bmb, cis, gds, tea confirmed |
+| V5 | Post-install: _bmad/ has core + bmm + bmb + cis + tea + gds | PASS | All 6 dirs present; config.yaml generated with v6.0.4 timestamp |
+| V6 | Idempotency: second install skips existing cache | PASS | All 4 modules show `~ Cached module exists, skipping` on second run; no summary line (by design) |
+| V7 | --force: replaces cache modules | PASS | All 4 modules show `+ Replaced cached module: <mod>`; cache-pre-population summary printed |
+| V8 | npx ma-agents status shows correct output | PARTIAL | Shows "No skills installed (project scope)" — status command tracks IDE skills only; BMAD module installation status is not surfaced. See Issues section. |
+| V9 | No git clone or npm fetch during offline simulation | PASS | GIT_TERMINAL_PROMPT=0 set on all execSync calls; no GitHub URLs in output; cache served from lib/bmad-cache/ entirely |
+| V10 | BMAD workflows present and syntactically valid | PASS | 12 workflow YAML files found and readable; 9 agent personas in _bmad/bmm/agents/ |
+
+## Issues Found
+
+### Issue 1 (FIXED — H1): Missing `--directory` flag in bmad.js execSync calls
+
+**Root cause:** `installBmad()`, `updateBmad()`, and `applyCustomizations()` in `lib/bmad.js` all constructed bmad-method commands with `--yes` but without `--directory <projectRoot>`. The bmad-method v6.0.4 `ui.js` only skips the directory prompt when `options.directory` is explicitly provided; without it, the interactive `getConfirmedDirectory()` prompt is triggered. When running via `execSync` (non-TTY), this prompt silently completes with exit code 0 but **no `_bmad/` installation occurs**.
+
+**Fix applied:** All 3 `getBmadCommand()` call sites in `lib/bmad.js` updated to include `--directory "${projectRoot}"`:
+- Line 26: `installBmad` — `install --yes --directory "${projectRoot}"`
+- Line 51: `updateBmad` — `install --action update --yes --directory "${projectRoot}"`
+- Line 128: `applyCustomizations` — `install --yes --directory "${projectRoot}"`
+
+**Verification:** After fix, `installBmad()` correctly creates `_bmad/` at `D:\tmp\bmad-validation-test2\_bmad` on first run. All ACs re-validated with fix in place.
+
+### Issue 2 (OBSERVATION — not a code bug): `npx ma-agents status` does not show BMAD module status
+
+**Observation:** AC#3 states status should show "BMAD installation status, version numbers". The current `showStatus()` function only reads the `.agent/manifest.json` (skills manifest) and reports IDE skill installations. BMAD modules installed via bmad-method are not tracked in this manifest.
+
+**Impact:** Low — BMAD modules can be verified via `ls _bmad/` and `cat _bmad/bmm/config.yaml`. The status command gap is a UX issue, not a functional one.
+
+**Recommendation:** Future story to add BMAD module detection to `showStatus()` — read `_bmad/bmm/config.yaml` if present and display module list + version.
+
+## Conclusion
+
+The bundled installation mechanism (Epic 5, Stories 5.1–5.3) is **functionally correct** for deterministic offline installation. NFR21 (deterministic installation) is satisfied: same tarball produces same `_bmad/` output on repeated runs.
+
+One critical bug was found and fixed during validation (Issue 1): the missing `--directory` flag caused silent no-op installs in automated/non-TTY contexts. The fix is minimal and targeted (3 lines in `lib/bmad.js`).
+
+AC#3 partial gap (status command) is a UX observation only and does not block the story — all other ACs pass.
+
+**Overall: PASS with fix applied**

package/lib/bmad-cache/bmb/.markdownlint-cli2.yaml

@@ -0,0 +1,35 @@
+# markdownlint-cli2 configuration
+# https://github.com/DavidAnson/markdownlint-cli2
+
+ignores:
+  - node_modules/**
+  - test/fixtures/**
+  - CODE_OF_CONDUCT.md
+  - _bmad/**
+  - _bmad*/**
+  - .*/**
+  - z*/**
+
+# Rule configuration
+config:
+  # Disable all rules by default
+  default: false
+
+  # Heading levels should increment by one (h1 -> h2 -> h3, not h1 -> h3)
+  MD001: true
+
+  # Duplicate sibling headings (same heading text at same level under same parent)
+  MD024:
+    siblings_only: true
+
+  # Trailing commas in headings (likely typos)
+  MD026:
+    punctuation: ","
+
+  # Bare URLs - may not render as links in all parsers
+  # Should use <url> or [text](url) format
+  MD034: true
+
+  # Spaces inside emphasis markers - breaks rendering
+  # e.g., "* text *" won't render as emphasis
+  MD037: true

package/lib/bmad-cache/bmb/.nvmrc

@@ -0,0 +1 @@
+22

package/lib/bmad-cache/bmb/.prettierignore

@@ -0,0 +1,9 @@
+# Test fixtures with intentionally broken/malformed files
+test/fixtures/**
+
+# Contributor Covenant (external standard)
+CODE_OF_CONDUCT.md
+
+# BMAD runtime folders (user-specific, not in repo)
+_bmad/
+_bmad*/

package/lib/bmad-cache/bmb/CNAME

@@ -0,0 +1 @@
+bmad-builder-docs.bmad-method.org

package/lib/bmad-cache/bmb/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2025 BMad Code, LLC
+
+This project incorporates contributions from the open source community.
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor attribution.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TRADEMARK NOTICE:
+BMad™, BMad Method™, and BMad Core™ are trademarks of BMad Code, LLC, covering all
+casings and variations (including BMAD, bmad, BMadMethod, BMAD-METHOD, etc.). The use of
+these trademarks in this software does not grant any rights to use the trademarks
+for any other purpose. See [TRADEMARK.md](TRADEMARK.md) for detailed guidelines.

package/lib/bmad-cache/bmb/README.md

@@ -0,0 +1,63 @@
+# BMad Builder
+
+[![Version](https://img.shields.io/npm/v/bmad-builder?color=blue&label=version)](https://www.npmjs.com/package/bmad-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
+
+**Build More, Architect Dreams... With the BMad Builder!**
+
+BMad Builder is so much more than a skill builder. BMad Method modules support:
+
+- **Agents** that transform your AI tool into exactly who you need to talk to — with memory that persists across sessions
+- **Workflows** that go far beyond simple tasks into truly guided, facilitated processes that can produce near-infinite steps and turns as needed
+- **Modules** that are entire ecosystems, not just skill packs — like the BMad Method module for agile AI-driven development. You can create simpler or vastly more complex modules for any entertainment or work purpose.
+
+## The Dream
+
+Imagine AI that truly knows you — a fitness coach that remembers every PR, a writing partner that knows your characters better than you do, a research assistant that learns your preferences.
+
+BMad Builder lets you create:
+
+- **Personal AI Companions** — Agents with memory that evolve with you over time
+- **Domain Experts** — Specialists for any field: legal, medical, creative, technical
+- **Workflow Automations** — Structured processes that guide you through complex tasks
+- **Custom Modules** — Bundle agents and workflows into shareable packages that can empower any type of business or domain
+
+## What Makes It Different
+
+| Feature | Why It Matters |
+|---------|----------------|
+| **Persistent Memory** | Agents remember across sessions — they learn and grow |
+| **Composable** | Your creations work alongside the entire BMad ecosystem |
+| **Skill-Compliant** | Built on open standards that work with any AI tool |
+| **Shareable** | Package your modules for the BMad Marketplace (coming soon) |
+
+## What You Can Build
+
+| Domain | Example |
+|--------|---------|
+| **Personal** | Journal companion, habit coach, learning tutor |
+| **Professional** | Code reviewer, documentation specialist, workflow automator |
+| **Creative** | Story architect, character developer, campaign designer |
+| **Any Domain** | If you can describe it, you can build it |
+
+## Learn More
+
+**[Documentation and Quick Start](https://bmad-builder-docs.bmad-method.org)**
+
+Complete guides for building agents, workflows, and modules.
+
+## Community
+
+- **[Discord](https://discord.gg/gk8jAdXWmj)** — Get help and share what you've built
+- **[BMad Method](https://docs.bmad-method.org)** — Core framework documentation
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+**BMad Builder** — Part of the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) ecosystem.
+
+[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/bmad-builder)](https://github.com/bmad-code-org/bmad-builder/graphs/contributors)
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor information.

package/lib/bmad-cache/bmb/eslint.config.mjs

@@ -0,0 +1,141 @@
+import js from '@eslint/js';
+import eslintConfigPrettier from 'eslint-config-prettier/flat';
+import nodePlugin from 'eslint-plugin-n';
+import unicorn from 'eslint-plugin-unicorn';
+import yml from 'eslint-plugin-yml';
+
+export default [
+  // Global ignores for files/folders that should not be linted
+  {
+    ignores: [
+      'dist/**',
+      'coverage/**',
+      '**/*.min.js',
+      'test/template-test-generator/**',
+      'test/template-test-generator/**/*.js',
+      'test/template-test-generator/**/*.md',
+      'test/fixtures/**',
+      'test/fixtures/**/*.yaml',
+      '_bmad/**',
+      '_bmad*/**',
+      // Build output
+      'build/**',
+      // Website uses ESM/Astro - separate linting ecosystem
+      'website/**',
+      // Gitignored patterns
+      'z*/**', // z-samples, z1, z2, etc.
+      '.claude/**',
+      '.codex/**',
+      '.github/chatmodes/**',
+      '.agent/**',
+      '.agentvibes/**',
+      '.kiro/**',
+      '.roo/**',
+      'test-project-install/**',
+      'sample-project/**',
+      'tools/template-test-generator/test-scenarios/**',
+      'src/modules/*/sub-modules/**',
+      '.bundler-temp/**',
+    ],
+  },
+
+  // Base JavaScript recommended rules
+  js.configs.recommended,
+
+  // Node.js rules
+  ...nodePlugin.configs['flat/mixed-esm-and-cjs'],
+
+  // Unicorn rules (modern best practices)
+  unicorn.configs.recommended,
+
+  // YAML linting
+  ...yml.configs['flat/recommended'],
+
+  // Place Prettier last to disable conflicting stylistic rules
+  eslintConfigPrettier,
+
+  // Project-specific tweaks
+  {
+    rules: {
+      // Allow console for CLI tools in this repo
+      'no-console': 'off',
+      // Enforce .yaml file extension for consistency
+      'yml/file-extension': [
+        'error',
+        {
+          extension: 'yaml',
+          caseSensitive: true,
+        },
+      ],
+      // Prefer double quotes in YAML wherever quoting is used, but allow the other to avoid escapes
+      'yml/quotes': [
+        'error',
+        {
+          prefer: 'double',
+          avoidEscape: true,
+        },
+      ],
+      // Relax some Unicorn rules that are too opinionated for this codebase
+      'unicorn/prevent-abbreviations': 'off',
+      'unicorn/no-null': 'off',
+    },
+  },
+
+  // CLI scripts under tools/** and test/**
+  {
+    files: ['tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js'],
+    rules: {
+      // Allow CommonJS patterns for Node CLI scripts
+      'unicorn/prefer-module': 'off',
+      'unicorn/import-style': 'off',
+      'unicorn/no-process-exit': 'off',
+      'n/no-process-exit': 'off',
+      'unicorn/no-await-expression-member': 'off',
+      'unicorn/prefer-top-level-await': 'off',
+      // Avoid failing CI on incidental unused vars in internal scripts
+      'no-unused-vars': 'off',
+      // Reduce style-only churn in internal tools
+      'unicorn/prefer-ternary': 'off',
+      'unicorn/filename-case': 'off',
+      'unicorn/no-array-reduce': 'off',
+      'unicorn/no-array-callback-reference': 'off',
+      'unicorn/consistent-function-scoping': 'off',
+      'n/no-extraneous-require': 'off',
+      'n/no-extraneous-import': 'off',
+      'n/no-unpublished-require': 'off',
+      'n/no-unpublished-import': 'off',
+      // Some scripts intentionally use globals provided at runtime
+      'no-undef': 'off',
+      // Additional relaxed rules for legacy/internal scripts
+      'no-useless-catch': 'off',
+      'unicorn/prefer-number-properties': 'off',
+      'no-unreachable': 'off',
+      'unicorn/text-encoding-identifier-case': 'off',
+    },
+  },
+
+  // ESLint config file should not be checked for publish-related Node rules
+  {
+    files: ['eslint.config.mjs'],
+    rules: {
+      'n/no-unpublished-import': 'off',
+    },
+  },
+
+  // GitHub workflow files in this repo may use empty mapping values
+  {
+    files: ['.github/workflows/**/*.yaml'],
+    rules: {
+      'yml/no-empty-mapping-value': 'off',
+    },
+  },
+
+  // Other GitHub YAML files may intentionally use empty values and reserved filenames
+  {
+    files: ['.github/**/*.yaml'],
+    rules: {
+      'yml/no-empty-mapping-value': 'off',
+      'unicorn/filename-case': 'off',
+    },
+  },
+];