ma-agents 3.5.0 → 3.5.2

package/lib/bmad-cache/bmb/samples/bmad-agent-sentinel/scripts/tests/test-init-sanctum.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Tests for init-sanctum.py"""
+
+import sys
+import tempfile
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from importlib.machinery import SourceFileLoader
+
+# Load the module with hyphenated filename
+loader = SourceFileLoader("init_sanctum", str(Path(__file__).parent.parent / "init-sanctum.py"))
+init_sanctum = loader.load_module()
+
+
+def test_parse_yaml_config_basic():
+    """Test basic YAML parsing with simple key-value pairs."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        f.write("user_name: TestUser\ncommunication_language: English\n")
+        f.flush()
+        config = init_sanctum.parse_yaml_config(Path(f.name))
+        assert config["user_name"] == "TestUser"
+        assert config["communication_language"] == "English"
+    Path(f.name).unlink()
+
+
+def test_parse_yaml_config_missing_file():
+    """Test that missing config file returns empty dict."""
+    config = init_sanctum.parse_yaml_config(Path("/nonexistent/config.yaml"))
+    assert config == {}
+
+
+def test_parse_yaml_config_quoted_values():
+    """Test YAML parsing strips quotes from values."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        f.write("name: 'quoted'\nother: \"double-quoted\"\n")
+        f.flush()
+        config = init_sanctum.parse_yaml_config(Path(f.name))
+        assert config["name"] == "quoted"
+        assert config["other"] == "double-quoted"
+    Path(f.name).unlink()
+
+
+def test_parse_frontmatter():
+    """Test frontmatter extraction from markdown files."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
+        f.write("---\nname: test-cap\ndescription: A test\ncode: TC\n---\n\n# Content\n")
+        f.flush()
+        meta = init_sanctum.parse_frontmatter(Path(f.name))
+        assert meta["name"] == "test-cap"
+        assert meta["code"] == "TC"
+    Path(f.name).unlink()
+
+
+def test_parse_frontmatter_no_frontmatter():
+    """Test frontmatter extraction when no frontmatter exists."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
+        f.write("# Just content\nNo frontmatter here.\n")
+        f.flush()
+        meta = init_sanctum.parse_frontmatter(Path(f.name))
+        assert meta == {}
+    Path(f.name).unlink()
+
+
+def test_substitute_vars():
+    """Test variable substitution in content strings."""
+    content = "Hello {user_name}, born on {birth_date}."
+    variables = {"user_name": "TestUser", "birth_date": "2026-04-05"}
+    result = init_sanctum.substitute_vars(content, variables)
+    assert result == "Hello TestUser, born on 2026-04-05."
+
+
+def test_substitute_vars_no_match():
+    """Test that unmatched placeholders are left as-is."""
+    content = "Hello {unknown_var}."
+    result = init_sanctum.substitute_vars(content, {"user_name": "Test"})
+    assert result == "Hello {unknown_var}."
+
+
+def test_generate_capabilities_md_evolvable():
+    """Test capabilities markdown generation with evolvable enabled."""
+    caps = [{"name": "test", "description": "A test", "code": "TS", "source": "./references/test.md"}]
+    result = init_sanctum.generate_capabilities_md(caps, evolvable=True)
+    assert "## Learned" in result
+    assert "How to Add a Capability" in result
+    assert "[TS]" in result
+
+
+def test_generate_capabilities_md_not_evolvable():
+    """Test capabilities markdown generation without evolvable."""
+    caps = [{"name": "test", "description": "A test", "code": "TS", "source": "./references/test.md"}]
+    result = init_sanctum.generate_capabilities_md(caps, evolvable=False)
+    assert "## Learned" not in result
+    assert "[TS]" in result
+
+
+def test_sanctum_creation():
+    """Test full sanctum creation in a temp directory."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        project_root = Path(tmpdir)
+        skill_path = project_root / "skill"
+
+        # Create minimal skill structure
+        bmad_dir = project_root / "_bmad"
+        bmad_dir.mkdir()
+        (bmad_dir / "config.yaml").write_text("document_output_language: English\n")
+        (bmad_dir / "config.user.yaml").write_text("user_name: Tester\ncommunication_language: English\n")
+
+        # Create skill dirs
+        refs_dir = skill_path / "references"
+        refs_dir.mkdir(parents=True)
+        assets_dir = skill_path / "assets"
+        assets_dir.mkdir(parents=True)
+        scripts_dir = skill_path / "scripts"
+        scripts_dir.mkdir(parents=True)
+
+        # Create a capability reference
+        (refs_dir / "test-cap.md").write_text(
+            "---\nname: test-cap\ndescription: Test capability\ncode: TC\n---\n\n# Test\n"
+        )
+
+        # Create minimal templates
+        for tmpl in init_sanctum.TEMPLATE_FILES:
+            (assets_dir / tmpl).write_text(f"# Template {tmpl}\nUser: {{user_name}}\nBorn: {{birth_date}}\n")
+
+        # Run the sanctum creation logic
+        sanctum_path = bmad_dir / "memory" / init_sanctum.SANCTUM_DIR
+
+        # Simulate main() logic
+        sanctum_path.mkdir(parents=True, exist_ok=True)
+        (sanctum_path / "capabilities").mkdir(exist_ok=True)
+        (sanctum_path / "sessions").mkdir(exist_ok=True)
+
+        # Verify structure
+        assert sanctum_path.exists()
+        assert (sanctum_path / "capabilities").exists()
+        assert (sanctum_path / "sessions").exists()
+
+
+def run_tests():
+    """Run all tests and report results."""
+    tests = [
+        test_parse_yaml_config_basic,
+        test_parse_yaml_config_missing_file,
+        test_parse_yaml_config_quoted_values,
+        test_parse_frontmatter,
+        test_parse_frontmatter_no_frontmatter,
+        test_substitute_vars,
+        test_substitute_vars_no_match,
+        test_generate_capabilities_md_evolvable,
+        test_generate_capabilities_md_not_evolvable,
+        test_sanctum_creation,
+    ]
+
+    passed = 0
+    failed = 0
+    for test in tests:
+        try:
+            test()
+            passed += 1
+            print(f"  PASS: {test.__name__}")
+        except Exception as e:
+            failed += 1
+            print(f"  FAIL: {test.__name__} — {e}")
+
+    print(f"\n{passed} passed, {failed} failed")
+    return failed == 0
+
+
+if __name__ == "__main__":
+    success = run_tests()
+    sys.exit(0 if success else 1)

package/lib/bmad-cache/bmb/samples/sample-module-setup/assets/module-help.csv

@@ -0,0 +1,16 @@
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+BMad Samples,sample-module-setup,Setup Samples Module,SS,"Install or update BMad Samples module config and help entries.",configure,"{-H: headless mode}|{inline values: skip prompts with provided values}",anytime,,,false,{project-root}/_bmad,config.yaml and config.user.yaml
+BMad Samples,bmad-agent-code-coach,Code Coaching,TC,"Personal coding coaching and mentoring — code review, pair programming, and learning paths.",activate,,anytime,,,false,,coaching session
+BMad Samples,bmad-agent-creative-muse,Creative Muse,TM,"Creative brainstorming, problem-solving, and storytelling companion.",activate,,anytime,,,false,,creative session
+BMad Samples,bmad-agent-diagram-reviewer,Diagram Review,DR,"Review architecture diagrams for gaps, ambiguities, and missing connections.",diagram-review,,anytime,,,false,,review findings
+BMad Samples,bmad-agent-dream-weaver,Dream Capture,DL,"Capture and log a dream through guided conversation.",dream-log,,anytime,,,false,,journal entry
+BMad Samples,bmad-agent-dream-weaver,Dream Interpretation,DI,"Analyze a dream for symbolism, meaning, and personal connections.",dream-interpret,,anytime,sam:dream-log,,false,,interpretation
+BMad Samples,bmad-agent-dream-weaver,Recall Training,RT,"Dream recall exercises and progress tracking.",recall-training,,anytime,,,false,,coaching updates
+BMad Samples,bmad-agent-dream-weaver,Lucid Coaching,LC,"Progressive lucid dreaming training and milestone tracking.",lucid-coach,,anytime,sam:recall-training,,false,,coaching updates
+BMad Samples,bmad-agent-dream-weaver,Dream Seeding,DS,"Pre-sleep dream incubation — plant themes and intentions.",dream-seed,,anytime,,,false,,seed log entry
+BMad Samples,bmad-agent-dream-weaver,Pattern Discovery,PD,"Surface recurring themes, symbols, and emotional patterns across dreams.",pattern-discovery,,anytime,sam:dream-log,,false,,pattern analysis
+BMad Samples,bmad-agent-dream-weaver,Dream Query,DQ,"Search dream history by symbol, emotion, date, or keyword.",dream-query,,anytime,sam:dream-log,,false,,search results
+BMad Samples,bmad-agent-dream-weaver,Save Memory,SM,"Save current session context to memory.",save-memory,,anytime,,,false,,memory checkpoint
+BMad Samples,bmad-agent-sentinel,Sentinel Coaching,TS,"Strategic coaching — risk radar, decision stress-testing, and execution accountability.",activate,,anytime,,,false,,coaching session
+BMad Samples,bmad-excalidraw,Create Diagram,XD,"Create Excalidraw diagrams through guided or autonomous workflows.",diagram-generation,"{-H: headless mode}|{--yolo: quick generation}",anytime,,,false,sample_output_folder,excalidraw file
+BMad Samples,bmad-excalidraw,Validate Diagram,XV,"Validate an Excalidraw file's structure and report issues.",validate,,anytime,sam:diagram-generation,,false,,validation report

package/lib/bmad-cache/bmb/samples/sample-module-setup/assets/module.yaml

@@ -0,0 +1,13 @@
+code: sam
+name: "BMad Samples"
+description: "Demo module showcasing sample BMad agents, workflows, and skills"
+module_version: 1.0.0
+default_selected: false
+module_greeting: >
+  The BMad Samples module is ready! Explore the sample agents and skills to see what's possible with BMad.
+  For questions, suggestions and support - check us on Discord at https://discord.gg/gk8jAdXWmj
+
+sample_output_folder:
+  prompt: "Where should sample output (diagrams, reports) be saved?"
+  default: "{project-root}/_bmad-output"
+  result: "{project-root}/{value}"

package/lib/bmad-cache/bmb/samples/sample-module-setup/scripts/merge-config.py

@@ -0,0 +1,408 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""Merge module configuration into shared _bmad/config.yaml and config.user.yaml.
+
+Reads a module.yaml definition and a JSON answers file, then writes or updates
+the shared config.yaml (core values at root + module section) and config.user.yaml
+(user_name, communication_language, plus any module variable with user_setting: true).
+Uses an anti-zombie pattern for the module section in config.yaml.
+
+Legacy migration: when --legacy-dir is provided, reads old per-module config files
+from {legacy-dir}/{module-code}/config.yaml and {legacy-dir}/core/config.yaml.
+Matching values serve as fallback defaults (answers override them). After a
+successful merge, the legacy config.yaml files are deleted. Only the current
+module and core directories are touched — other module directories are left alone.
+
+Exit codes: 0=success, 1=validation error, 2=runtime error
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("Error: pyyaml is required (PEP 723 dependency)", file=sys.stderr)
+    sys.exit(2)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Merge module config into shared _bmad/config.yaml with anti-zombie pattern."
+    )
+    parser.add_argument(
+        "--config-path",
+        required=True,
+        help="Path to the target _bmad/config.yaml file",
+    )
+    parser.add_argument(
+        "--module-yaml",
+        required=True,
+        help="Path to the module.yaml definition file",
+    )
+    parser.add_argument(
+        "--answers",
+        required=True,
+        help="Path to JSON file with collected answers",
+    )
+    parser.add_argument(
+        "--user-config-path",
+        required=True,
+        help="Path to the target _bmad/config.user.yaml file",
+    )
+    parser.add_argument(
+        "--legacy-dir",
+        help="Path to _bmad/ directory to check for legacy per-module config files. "
+        "Matching values are used as fallback defaults, then legacy files are deleted.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print detailed progress to stderr",
+    )
+    return parser.parse_args()
+
+
+def load_yaml_file(path: str) -> dict:
+    """Load a YAML file, returning empty dict if file doesn't exist."""
+    file_path = Path(path)
+    if not file_path.exists():
+        return {}
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = yaml.safe_load(f)
+    return content if content else {}
+
+
+def load_json_file(path: str) -> dict:
+    """Load a JSON file."""
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+# Keys that live at config root (shared across all modules)
+_CORE_KEYS = frozenset(
+    {"user_name", "communication_language", "document_output_language", "output_folder"}
+)
+
+
+def load_legacy_values(
+    legacy_dir: str, module_code: str, module_yaml: dict, verbose: bool = False
+) -> tuple[dict, dict, list]:
+    """Read legacy per-module config files and return core/module value dicts.
+
+    Reads {legacy_dir}/core/config.yaml and {legacy_dir}/{module_code}/config.yaml.
+    Only returns values whose keys match the current schema (core keys or module.yaml
+    variable definitions). Other modules' directories are not touched.
+
+    Returns:
+        (legacy_core, legacy_module, files_found) where files_found lists paths read.
+    """
+    legacy_core: dict = {}
+    legacy_module: dict = {}
+    files_found: list = []
+
+    # Read core legacy config
+    core_path = Path(legacy_dir) / "core" / "config.yaml"
+    if core_path.exists():
+        core_data = load_yaml_file(str(core_path))
+        files_found.append(str(core_path))
+        for k, v in core_data.items():
+            if k in _CORE_KEYS:
+                legacy_core[k] = v
+        if verbose:
+            print(f"Legacy core config: {list(legacy_core.keys())}", file=sys.stderr)
+
+    # Read module legacy config
+    mod_path = Path(legacy_dir) / module_code / "config.yaml"
+    if mod_path.exists():
+        mod_data = load_yaml_file(str(mod_path))
+        files_found.append(str(mod_path))
+        for k, v in mod_data.items():
+            if k in _CORE_KEYS:
+                # Core keys duplicated in module config — only use if not already set
+                if k not in legacy_core:
+                    legacy_core[k] = v
+            elif k in module_yaml and isinstance(module_yaml[k], dict):
+                # Module-specific key that matches a current variable definition
+                legacy_module[k] = v
+        if verbose:
+            print(
+                f"Legacy module config: {list(legacy_module.keys())}", file=sys.stderr
+            )
+
+    return legacy_core, legacy_module, files_found
+
+
+def apply_legacy_defaults(answers: dict, legacy_core: dict, legacy_module: dict) -> dict:
+    """Apply legacy values as fallback defaults under the answers.
+
+    Legacy values fill in any key not already present in answers.
+    Explicit answers always win.
+    """
+    merged = dict(answers)
+
+    if legacy_core:
+        core = merged.get("core", {})
+        filled_core = dict(legacy_core)  # legacy as base
+        filled_core.update(core)  # answers override
+        merged["core"] = filled_core
+
+    if legacy_module:
+        mod = merged.get("module", {})
+        filled_mod = dict(legacy_module)  # legacy as base
+        filled_mod.update(mod)  # answers override
+        merged["module"] = filled_mod
+
+    return merged
+
+
+def cleanup_legacy_configs(
+    legacy_dir: str, module_code: str, verbose: bool = False
+) -> list:
+    """Delete legacy config.yaml files for this module and core only.
+
+    Returns list of deleted file paths.
+    """
+    deleted = []
+    for subdir in (module_code, "core"):
+        legacy_path = Path(legacy_dir) / subdir / "config.yaml"
+        if legacy_path.exists():
+            if verbose:
+                print(f"Deleting legacy config: {legacy_path}", file=sys.stderr)
+            legacy_path.unlink()
+            deleted.append(str(legacy_path))
+    return deleted
+
+
+def extract_module_metadata(module_yaml: dict) -> dict:
+    """Extract non-variable metadata fields from module.yaml."""
+    meta = {}
+    for k in ("name", "description"):
+        if k in module_yaml:
+            meta[k] = module_yaml[k]
+    meta["version"] = module_yaml.get("module_version")  # null if absent
+    if "default_selected" in module_yaml:
+        meta["default_selected"] = module_yaml["default_selected"]
+    return meta
+
+
+def apply_result_templates(
+    module_yaml: dict, module_answers: dict, verbose: bool = False
+) -> dict:
+    """Apply result templates from module.yaml to transform raw answer values.
+
+    For each answer, if the corresponding variable definition in module.yaml has
+    a 'result' field, replaces {value} in that template with the answer. Skips
+    the template if the answer already contains '{project-root}' to prevent
+    double-prefixing.
+    """
+    transformed = {}
+    for key, value in module_answers.items():
+        var_def = module_yaml.get(key)
+        if (
+            isinstance(var_def, dict)
+            and "result" in var_def
+            and "{project-root}" not in str(value)
+        ):
+            template = var_def["result"]
+            transformed[key] = template.replace("{value}", str(value))
+            if verbose:
+                print(
+                    f"Applied result template for '{key}': {value} → {transformed[key]}",
+                    file=sys.stderr,
+                )
+        else:
+            transformed[key] = value
+    return transformed
+
+
+def merge_config(
+    existing_config: dict,
+    module_yaml: dict,
+    answers: dict,
+    verbose: bool = False,
+) -> dict:
+    """Merge answers into config, applying anti-zombie pattern.
+
+    Args:
+        existing_config: Current config.yaml contents (may be empty)
+        module_yaml: The module definition
+        answers: JSON with 'core' and/or 'module' keys
+        verbose: Print progress to stderr
+
+    Returns:
+        Updated config dict ready to write
+    """
+    config = dict(existing_config)
+    module_code = module_yaml.get("code")
+
+    if not module_code:
+        print("Error: module.yaml must have a 'code' field", file=sys.stderr)
+        sys.exit(1)
+
+    # Migrate legacy core: section to root
+    if "core" in config and isinstance(config["core"], dict):
+        if verbose:
+            print("Migrating legacy 'core' section to root", file=sys.stderr)
+        config.update(config.pop("core"))
+
+    # Strip user-only keys from config — they belong exclusively in config.user.yaml
+    for key in _CORE_USER_KEYS:
+        if key in config:
+            if verbose:
+                print(f"Removing user-only key '{key}' from config (belongs in config.user.yaml)", file=sys.stderr)
+            del config[key]
+
+    # Write core values at root (global properties, not nested under "core")
+    # Exclude user-only keys — those belong exclusively in config.user.yaml
+    core_answers = answers.get("core")
+    if core_answers:
+        shared_core = {k: v for k, v in core_answers.items() if k not in _CORE_USER_KEYS}
+        if shared_core:
+            if verbose:
+                print(f"Writing core config at root: {list(shared_core.keys())}", file=sys.stderr)
+            config.update(shared_core)
+
+    # Anti-zombie: remove existing module section
+    if module_code in config:
+        if verbose:
+            print(
+                f"Removing existing '{module_code}' section (anti-zombie)",
+                file=sys.stderr,
+            )
+        del config[module_code]
+
+    # Build module section: metadata + variable values
+    module_section = extract_module_metadata(module_yaml)
+    module_answers = apply_result_templates(
+        module_yaml, answers.get("module", {}), verbose
+    )
+    module_section.update(module_answers)
+
+    if verbose:
+        print(
+            f"Writing '{module_code}' section with keys: {list(module_section.keys())}",
+            file=sys.stderr,
+        )
+
+    config[module_code] = module_section
+
+    return config
+
+
+# Core keys that are always written to config.user.yaml
+_CORE_USER_KEYS = ("user_name", "communication_language")
+
+
+def extract_user_settings(module_yaml: dict, answers: dict) -> dict:
+    """Collect settings that belong in config.user.yaml.
+
+    Includes user_name and communication_language from core answers, plus any
+    module variable whose definition contains user_setting: true.
+    """
+    user_settings = {}
+
+    core_answers = answers.get("core", {})
+    for key in _CORE_USER_KEYS:
+        if key in core_answers:
+            user_settings[key] = core_answers[key]
+
+    module_answers = answers.get("module", {})
+    for var_name, var_def in module_yaml.items():
+        if isinstance(var_def, dict) and var_def.get("user_setting") is True:
+            if var_name in module_answers:
+                user_settings[var_name] = module_answers[var_name]
+
+    return user_settings
+
+
+def write_config(config: dict, config_path: str, verbose: bool = False) -> None:
+    """Write config dict to YAML file, creating parent dirs as needed."""
+    path = Path(config_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if verbose:
+        print(f"Writing config to {path}", file=sys.stderr)
+
+    with open(path, "w", encoding="utf-8") as f:
+        yaml.dump(
+            config,
+            f,
+            default_flow_style=False,
+            allow_unicode=True,
+            sort_keys=False,
+        )
+
+
+def main():
+    args = parse_args()
+
+    # Load inputs
+    module_yaml = load_yaml_file(args.module_yaml)
+    if not module_yaml:
+        print(f"Error: Could not load module.yaml from {args.module_yaml}", file=sys.stderr)
+        sys.exit(1)
+
+    answers = load_json_file(args.answers)
+    existing_config = load_yaml_file(args.config_path)
+
+    if args.verbose:
+        exists = Path(args.config_path).exists()
+        print(f"Config file exists: {exists}", file=sys.stderr)
+        if exists:
+            print(f"Existing sections: {list(existing_config.keys())}", file=sys.stderr)
+
+    # Legacy migration: read old per-module configs as fallback defaults
+    legacy_files_found = []
+    if args.legacy_dir:
+        module_code = module_yaml.get("code", "")
+        legacy_core, legacy_module, legacy_files_found = load_legacy_values(
+            args.legacy_dir, module_code, module_yaml, args.verbose
+        )
+        if legacy_core or legacy_module:
+            answers = apply_legacy_defaults(answers, legacy_core, legacy_module)
+            if args.verbose:
+                print("Applied legacy values as fallback defaults", file=sys.stderr)
+
+    # Merge and write config.yaml
+    updated_config = merge_config(existing_config, module_yaml, answers, args.verbose)
+    write_config(updated_config, args.config_path, args.verbose)
+
+    # Merge and write config.user.yaml
+    user_settings = extract_user_settings(module_yaml, answers)
+    existing_user_config = load_yaml_file(args.user_config_path)
+    updated_user_config = dict(existing_user_config)
+    updated_user_config.update(user_settings)
+    if user_settings:
+        write_config(updated_user_config, args.user_config_path, args.verbose)
+
+    # Legacy cleanup: delete old per-module config files
+    legacy_deleted = []
+    if args.legacy_dir:
+        legacy_deleted = cleanup_legacy_configs(
+            args.legacy_dir, module_yaml["code"], args.verbose
+        )
+
+    # Output result summary as JSON
+    module_code = module_yaml["code"]
+    result = {
+        "status": "success",
+        "config_path": str(Path(args.config_path).resolve()),
+        "user_config_path": str(Path(args.user_config_path).resolve()),
+        "module_code": module_code,
+        "core_updated": bool(answers.get("core")),
+        "module_keys": list(updated_config.get(module_code, {}).keys()),
+        "user_keys": list(user_settings.keys()),
+        "legacy_configs_found": legacy_files_found,
+        "legacy_configs_deleted": legacy_deleted,
+    }
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()