ma-agents 3.5.0 → 3.5.2

package/lib/bmad-cache/bmb/skills/bmad-module-builder/assets/standalone-module-template/merge-help-csv.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""Merge module help entries into shared _bmad/module-help.csv.
+
+Reads a source CSV with module help entries and merges them into a target CSV.
+Uses an anti-zombie pattern: all existing rows matching the source module code
+are removed before appending fresh rows.
+
+Legacy cleanup: when --legacy-dir and --module-code are provided, deletes old
+per-module module-help.csv files from {legacy-dir}/{module-code}/ and
+{legacy-dir}/core/. Only the current module and core are touched.
+
+Exit codes: 0=success, 1=validation error, 2=runtime error
+"""
+
+import argparse
+import csv
+import json
+import sys
+from io import StringIO
+from pathlib import Path
+
+# CSV header for module-help.csv
+HEADER = [
+    "module",
+    "skill",
+    "display-name",
+    "menu-code",
+    "description",
+    "action",
+    "args",
+    "phase",
+    "after",
+    "before",
+    "required",
+    "output-location",
+    "outputs",
+]
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Merge module help entries into shared _bmad/module-help.csv with anti-zombie pattern."
+    )
+    parser.add_argument(
+        "--target",
+        required=True,
+        help="Path to the target _bmad/module-help.csv file",
+    )
+    parser.add_argument(
+        "--source",
+        required=True,
+        help="Path to the source module-help.csv with entries to merge",
+    )
+    parser.add_argument(
+        "--legacy-dir",
+        help="Path to _bmad/ directory to check for legacy per-module CSV files.",
+    )
+    parser.add_argument(
+        "--module-code",
+        help="Module code (required with --legacy-dir for scoping cleanup).",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print detailed progress to stderr",
+    )
+    return parser.parse_args()
+
+
+def read_csv_rows(path: str) -> tuple[list[str], list[list[str]]]:
+    """Read CSV file returning (header, data_rows).
+
+    Returns empty header and rows if file doesn't exist.
+    """
+    file_path = Path(path)
+    if not file_path.exists():
+        return [], []
+
+    with open(file_path, "r", encoding="utf-8", newline="") as f:
+        content = f.read()
+
+    reader = csv.reader(StringIO(content))
+    rows = list(reader)
+
+    if not rows:
+        return [], []
+
+    return rows[0], rows[1:]
+
+
+def extract_module_codes(rows: list[list[str]]) -> set[str]:
+    """Extract unique module codes from data rows."""
+    codes = set()
+    for row in rows:
+        if row and row[0].strip():
+            codes.add(row[0].strip())
+    return codes
+
+
+def filter_rows(rows: list[list[str]], module_code: str) -> list[list[str]]:
+    """Remove all rows matching the given module code."""
+    return [row for row in rows if not row or row[0].strip() != module_code]
+
+
+def write_csv(path: str, header: list[str], rows: list[list[str]], verbose: bool = False) -> None:
+    """Write header + rows to CSV file, creating parent dirs as needed."""
+    file_path = Path(path)
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if verbose:
+        print(f"Writing {len(rows)} data rows to {path}", file=sys.stderr)
+
+    with open(file_path, "w", encoding="utf-8", newline="") as f:
+        writer = csv.writer(f)
+        writer.writerow(header)
+        for row in rows:
+            writer.writerow(row)
+
+
+def cleanup_legacy_csvs(
+    legacy_dir: str, module_code: str, verbose: bool = False
+) -> list:
+    """Delete legacy per-module module-help.csv 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 / "module-help.csv"
+        if legacy_path.exists():
+            if verbose:
+                print(f"Deleting legacy CSV: {legacy_path}", file=sys.stderr)
+            legacy_path.unlink()
+            deleted.append(str(legacy_path))
+    return deleted
+
+
+def main():
+    args = parse_args()
+
+    # Read source entries
+    source_header, source_rows = read_csv_rows(args.source)
+    if not source_rows:
+        print(f"Error: No data rows found in source {args.source}", file=sys.stderr)
+        sys.exit(1)
+
+    # Determine module codes being merged
+    source_codes = extract_module_codes(source_rows)
+    if not source_codes:
+        print("Error: Could not determine module code from source rows", file=sys.stderr)
+        sys.exit(1)
+
+    if args.verbose:
+        print(f"Source module codes: {source_codes}", file=sys.stderr)
+        print(f"Source rows: {len(source_rows)}", file=sys.stderr)
+
+    # Read existing target (may not exist)
+    target_header, target_rows = read_csv_rows(args.target)
+    target_existed = Path(args.target).exists()
+
+    if args.verbose:
+        print(f"Target exists: {target_existed}", file=sys.stderr)
+        if target_existed:
+            print(f"Existing target rows: {len(target_rows)}", file=sys.stderr)
+
+    # Use source header if target doesn't exist or has no header
+    header = target_header if target_header else (source_header if source_header else HEADER)
+
+    # Anti-zombie: remove all rows for each source module code
+    filtered_rows = target_rows
+    removed_count = 0
+    for code in source_codes:
+        before_count = len(filtered_rows)
+        filtered_rows = filter_rows(filtered_rows, code)
+        removed_count += before_count - len(filtered_rows)
+
+    if args.verbose and removed_count > 0:
+        print(f"Removed {removed_count} existing rows (anti-zombie)", file=sys.stderr)
+
+    # Append source rows
+    merged_rows = filtered_rows + source_rows
+
+    # Write result
+    write_csv(args.target, header, merged_rows, args.verbose)
+
+    # Legacy cleanup: delete old per-module CSV files
+    legacy_deleted = []
+    if args.legacy_dir:
+        if not args.module_code:
+            print(
+                "Error: --module-code is required when --legacy-dir is provided",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        legacy_deleted = cleanup_legacy_csvs(
+            args.legacy_dir, args.module_code, args.verbose
+        )
+
+    # Output result summary as JSON
+    result = {
+        "status": "success",
+        "target_path": str(Path(args.target).resolve()),
+        "target_existed": target_existed,
+        "module_codes": sorted(source_codes),
+        "rows_removed": removed_count,
+        "rows_added": len(source_rows),
+        "total_rows": len(merged_rows),
+        "legacy_csvs_deleted": legacy_deleted,
+    }
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/lib/bmad-cache/bmb/skills/bmad-module-builder/scripts/scaffold-setup-skill.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Scaffold a BMad module setup skill from template.
+
+Copies the setup-skill-template into the target directory as {code}-setup/,
+then writes the generated module.yaml and module-help.csv into the assets folder
+and updates the SKILL.md frontmatter with the module's identity.
+"""
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Scaffold a BMad module setup skill from template"
+    )
+    parser.add_argument(
+        "--target-dir",
+        required=True,
+        help="Directory to create the setup skill in (the user's skills folder)",
+    )
+    parser.add_argument(
+        "--module-code",
+        required=True,
+        help="Module code (2-4 letter abbreviation, e.g. 'cis')",
+    )
+    parser.add_argument(
+        "--module-name",
+        required=True,
+        help="Module display name (e.g. 'Creative Intelligence Suite')",
+    )
+    parser.add_argument(
+        "--module-yaml",
+        required=True,
+        help="Path to the generated module.yaml content file",
+    )
+    parser.add_argument(
+        "--module-csv",
+        required=True,
+        help="Path to the generated module-help.csv content file",
+    )
+    parser.add_argument(
+        "--verbose", action="store_true", help="Print progress to stderr"
+    )
+    args = parser.parse_args()
+
+    template_dir = Path(__file__).resolve().parent.parent / "assets" / "setup-skill-template"
+    setup_skill_name = f"{args.module_code}-setup"
+    target = Path(args.target_dir) / setup_skill_name
+
+    if not template_dir.is_dir():
+        print(
+            json.dumps({"status": "error", "message": f"Template not found: {template_dir}"}),
+            file=sys.stdout,
+        )
+        return 2
+
+    for source_path in [args.module_yaml, args.module_csv]:
+        if not Path(source_path).is_file():
+            print(
+                json.dumps({"status": "error", "message": f"Source file not found: {source_path}"}),
+                file=sys.stdout,
+            )
+            return 2
+
+    target_dir = Path(args.target_dir)
+    if not target_dir.is_dir():
+        print(
+            json.dumps({"status": "error", "message": f"Target directory not found: {target_dir}"}),
+            file=sys.stdout,
+        )
+        return 2
+
+    # Remove existing setup skill if present (anti-zombie)
+    if target.exists():
+        if args.verbose:
+            print(f"Removing existing {setup_skill_name}/", file=sys.stderr)
+        shutil.rmtree(target)
+
+    # Copy template
+    if args.verbose:
+        print(f"Copying template to {target}", file=sys.stderr)
+    shutil.copytree(template_dir, target)
+
+    # Update SKILL.md frontmatter placeholders
+    skill_md = target / "SKILL.md"
+    content = skill_md.read_text(encoding="utf-8")
+    content = content.replace("{setup-skill-name}", setup_skill_name)
+    content = content.replace("{module-name}", args.module_name)
+    content = content.replace("{module-code}", args.module_code)
+    skill_md.write_text(content, encoding="utf-8")
+
+    # Write generated module.yaml
+    yaml_content = Path(args.module_yaml).read_text(encoding="utf-8")
+    (target / "assets" / "module.yaml").write_text(yaml_content, encoding="utf-8")
+
+    # Write generated module-help.csv
+    csv_content = Path(args.module_csv).read_text(encoding="utf-8")
+    (target / "assets" / "module-help.csv").write_text(csv_content, encoding="utf-8")
+
+    # Collect file list
+    files_created = sorted(
+        str(p.relative_to(target)) for p in target.rglob("*") if p.is_file()
+    )
+
+    result = {
+        "status": "success",
+        "setup_skill": setup_skill_name,
+        "location": str(target),
+        "files_created": files_created,
+        "files_count": len(files_created),
+    }
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/bmad-cache/bmb/skills/bmad-module-builder/scripts/scaffold-standalone-module.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Scaffold standalone module infrastructure into an existing skill.
+
+Copies template files (module-setup.md, merge scripts) into the skill directory
+and generates a .claude-plugin/marketplace.json for distribution. The LLM writes
+module.yaml and module-help.csv directly to the skill's assets/ folder before
+running this script.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Scaffold standalone module infrastructure into an existing skill"
+    )
+    parser.add_argument(
+        "--skill-dir",
+        required=True,
+        help="Path to the existing skill directory (must contain SKILL.md)",
+    )
+    parser.add_argument(
+        "--module-code",
+        required=True,
+        help="Module code (2-4 letter abbreviation, e.g. 'exc')",
+    )
+    parser.add_argument(
+        "--module-name",
+        required=True,
+        help="Module display name (e.g. 'Excalidraw Tools')",
+    )
+    parser.add_argument(
+        "--marketplace-dir",
+        default=None,
+        help="Directory to create .claude-plugin/ in (defaults to skill-dir parent)",
+    )
+    parser.add_argument(
+        "--verbose", action="store_true", help="Print progress to stderr"
+    )
+    args = parser.parse_args()
+
+    template_dir = (
+        Path(__file__).resolve().parent.parent
+        / "assets"
+        / "standalone-module-template"
+    )
+    skill_dir = Path(args.skill_dir).resolve()
+    marketplace_dir = (
+        Path(args.marketplace_dir).resolve() if args.marketplace_dir else skill_dir.parent
+    )
+
+    # --- Validation ---
+
+    if not template_dir.is_dir():
+        print(
+            json.dumps({"status": "error", "message": f"Template not found: {template_dir}"}),
+            file=sys.stdout,
+        )
+        return 2
+
+    if not skill_dir.is_dir():
+        print(
+            json.dumps({"status": "error", "message": f"Skill directory not found: {skill_dir}"}),
+            file=sys.stdout,
+        )
+        return 2
+
+    if not (skill_dir / "SKILL.md").is_file():
+        print(
+            json.dumps({"status": "error", "message": f"No SKILL.md found in {skill_dir}"}),
+            file=sys.stdout,
+        )
+        return 2
+
+    if not (skill_dir / "assets" / "module.yaml").is_file():
+        print(
+            json.dumps({
+                "status": "error",
+                "message": f"assets/module.yaml not found in {skill_dir} — the LLM must write it before running this script",
+            }),
+            file=sys.stdout,
+        )
+        return 2
+
+    # --- Copy template files ---
+
+    files_created: list[str] = []
+    files_skipped: list[str] = []
+    warnings: list[str] = []
+
+    # 1. Copy module-setup.md to assets/ (alongside module.yaml and module-help.csv)
+    assets_dir = skill_dir / "assets"
+    assets_dir.mkdir(exist_ok=True)
+    src_setup = template_dir / "module-setup.md"
+    dst_setup = assets_dir / "module-setup.md"
+    if args.verbose:
+        print(f"Copying module-setup.md to {dst_setup}", file=sys.stderr)
+    dst_setup.write_bytes(src_setup.read_bytes())
+    files_created.append("assets/module-setup.md")
+
+    # 2. Copy merge scripts to scripts/
+    scripts_dir = skill_dir / "scripts"
+    scripts_dir.mkdir(exist_ok=True)
+
+    for script_name in ("merge-config.py", "merge-help-csv.py"):
+        src = template_dir / script_name
+        dst = scripts_dir / script_name
+        if dst.exists():
+            msg = f"scripts/{script_name} already exists — skipped to avoid overwriting"
+            files_skipped.append(f"scripts/{script_name}")
+            warnings.append(msg)
+            if args.verbose:
+                print(f"SKIP: {msg}", file=sys.stderr)
+        else:
+            if args.verbose:
+                print(f"Copying {script_name} to {dst}", file=sys.stderr)
+            dst.write_bytes(src.read_bytes())
+            dst.chmod(0o755)
+            files_created.append(f"scripts/{script_name}")
+
+    # 3. Generate marketplace.json
+    plugin_dir = marketplace_dir / ".claude-plugin"
+    plugin_dir.mkdir(parents=True, exist_ok=True)
+    marketplace_json = plugin_dir / "marketplace.json"
+
+    # Read module.yaml for description and version
+    module_yaml_path = skill_dir / "assets" / "module.yaml"
+    module_description = ""
+    module_version = "1.0.0"
+    try:
+        yaml_text = module_yaml_path.read_text(encoding="utf-8")
+        for line in yaml_text.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("description:"):
+                module_description = stripped.split(":", 1)[1].strip().strip('"').strip("'")
+            elif stripped.startswith("module_version:"):
+                module_version = stripped.split(":", 1)[1].strip().strip('"').strip("'")
+    except Exception:
+        pass
+
+    skill_dir_name = skill_dir.name
+    marketplace_data = {
+        "name": args.module_code,
+        "owner": {"name": ""},
+        "license": "",
+        "homepage": "",
+        "repository": "",
+        "keywords": ["bmad"],
+        "plugins": [
+            {
+                "name": args.module_code,
+                "source": "./",
+                "description": module_description,
+                "version": module_version,
+                "author": {"name": ""},
+                "skills": [f"./{skill_dir_name}"],
+            }
+        ],
+    }
+
+    if args.verbose:
+        print(f"Writing marketplace.json to {marketplace_json}", file=sys.stderr)
+    marketplace_json.write_text(
+        json.dumps(marketplace_data, indent=2) + "\n", encoding="utf-8"
+    )
+    files_created.append(".claude-plugin/marketplace.json")
+
+    # --- Result ---
+
+    result = {
+        "status": "success",
+        "skill_dir": str(skill_dir),
+        "module_code": args.module_code,
+        "files_created": files_created,
+        "files_skipped": files_skipped,
+        "warnings": warnings,
+        "marketplace_json": str(marketplace_json),
+    }
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())