bmad-method-quarkus 1.0.0

package/src/scripts/render_skill.py

@@ -0,0 +1,401 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Render a skill's Markdown sources into an immutable project snapshot."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+# Installed scripts are consumer files, not a location for interpreter caches.
+sys.dont_write_bytecode = True
+
+from config_utils import ConfigError, load_central_config, load_customization, load_toml
+
+
+class RenderError(ValueError):
+    """Raised when rendering cannot safely publish a snapshot."""
+
+
+_CONFIG_TOKEN = re.compile(r"\{\{config\.([A-Za-z0-9_.-]+)\}\}")
+_SHORT_CONFIG_TOKEN = re.compile(r"\{\{\.([A-Za-z0-9_]+)\}\}")
+_CUSTOM_TOKEN = re.compile(r"\{workflow\.([A-Za-z0-9_.-]+)\}")
+_SNAPSHOT_TOKEN = re.compile(r"\[\[bmad-snapshot:([A-Za-z0-9_./-]+\.md)\]\]")
+
+
+def _hash_bytes(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def _canonical_json(value: Any) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode("utf-8")
+
+
+def _lookup(data: dict[str, Any], dotted_path: str, label: str) -> Any:
+    current: Any = data
+    for part in dotted_path.split("."):
+        if not isinstance(current, dict) or part not in current:
+            raise RenderError(f"missing {label} `{dotted_path}`")
+        current = current[part]
+    return current
+
+
+def _require_string(value: Any, label: str, *, allow_empty: bool = False) -> str:
+    if not isinstance(value, str):
+        raise RenderError(f"{label} must be a string, got {type(value).__name__}")
+    if not allow_empty and not value.strip():
+        raise RenderError(f"{label} must not be empty")
+    return value
+
+
+def _require_string_list(value: Any, label: str) -> list[str]:
+    if not isinstance(value, list):
+        raise RenderError(f"{label} must be a list, got {type(value).__name__}")
+    result = []
+    for index, item in enumerate(value):
+        result.append(_require_string(item, f"{label}[{index}]"))
+    return result
+
+
+def _require_review_layers(value: Any, label: str) -> list[dict[str, str]]:
+    if not isinstance(value, list):
+        raise RenderError(f"{label} must be a list of tables")
+    result: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for index, item in enumerate(value):
+        item_label = f"{label}[{index}]"
+        if not isinstance(item, dict):
+            raise RenderError(f"{item_label} must be a table")
+        identifier = _require_string(item.get("id"), f"{item_label}.id")
+        if identifier in seen:
+            raise RenderError(f"duplicate review layer id `{identifier}`")
+        seen.add(identifier)
+        layer = {
+            "id": identifier,
+            "name": _require_string(item.get("name", identifier), f"{item_label}.name"),
+            "instruction": _require_string(
+                item.get("instruction"), f"{item_label}.instruction", allow_empty=True
+            ),
+        }
+        if "when" in item:
+            layer["when"] = _require_string(item["when"], f"{item_label}.when")
+        result.append(layer)
+    return result
+
+
+def _load_sources(skill_dir: Path) -> dict[str, str]:
+    sources: dict[str, str] = {}
+    for candidate in sorted(skill_dir.rglob("*.md")):
+        if candidate.name == "SKILL.md":
+            continue
+        name = candidate.relative_to(skill_dir).as_posix()
+        path = candidate.resolve(strict=True)
+        if not path.is_relative_to(skill_dir):
+            raise RenderError(f"render source escapes skill directory: {name}")
+        if not path.is_file():
+            raise RenderError(f"render source is missing or not a file: {path}")
+        try:
+            sources[name] = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError) as error:
+            raise RenderError(f"failed to read render source {path}: {error}") from error
+    if "workflow.md" not in sources:
+        raise RenderError(f"render entry is missing: {skill_dir / 'workflow.md'}")
+    return sources
+
+
+def _resolve_config_value(value: Any, label: str, project_root: Path) -> str:
+    text = _require_string(value, label)
+    if "{project-root}" not in text:
+        return text
+    resolved = text.replace("{project-root}", str(project_root))
+    if not Path(resolved).is_absolute():
+        raise RenderError(f"{label} must resolve to an absolute path: {resolved}")
+    return resolved
+
+
+def _find_config_values(data: Any, key: str, prefix: str = "") -> list[tuple[str, Any]]:
+    matches: list[tuple[str, Any]] = []
+    if not isinstance(data, dict):
+        return matches
+    for name, value in data.items():
+        path = f"{prefix}.{name}" if prefix else name
+        if name == key and not isinstance(value, (dict, list)):
+            matches.append((path, value))
+        matches.extend(_find_config_values(value, key, path))
+    return matches
+
+
+def _resolve_short_config(
+    central: dict[str, Any], key: str, project_root: Path
+) -> tuple[str, str]:
+    matches = _find_config_values(central, key)
+    if not matches:
+        raise RenderError(f"missing config value `{key}`")
+    if len(matches) > 1:
+        paths = ", ".join(path for path, _ in matches)
+        raise RenderError(f"ambiguous config value `{key}` found at: {paths}")
+    path, value = matches[0]
+    return path, _resolve_config_value(value, f"config.{path}", project_root)
+
+
+def _format_markdown_list(items: list[str]) -> str:
+    if not items:
+        return "_None._"
+    rendered = []
+    for item in items:
+        lines = item.splitlines() or [""]
+        rendered.append("- " + lines[0])
+        rendered.extend("  " + line for line in lines[1:])
+    return "\n".join(rendered)
+
+
+def _format_review_layers(layers: list[dict[str, str]]) -> str:
+    active = [layer for layer in layers if layer["instruction"].strip()]
+    if not active:
+        return "No active review layers. HALT with blocking condition `no active review layers`."
+    sections = []
+    for layer in active:
+        section = [f"#### {layer['name']} (`{layer['id']}`)"]
+        if layer.get("when"):
+            section.extend(["", f"Run only when: {layer['when']}"])
+        section.extend(["", layer["instruction"].strip()])
+        sections.append("\n".join(section))
+    return "\n\n".join(sections)
+
+
+def _resolve_customization_value(value: Any, default: Any, label: str) -> tuple[Any, str]:
+    if isinstance(default, str):
+        allow_empty = not default.strip() or label == "customization.workflow.open_spec"
+        resolved = _require_string(value, label, allow_empty=allow_empty)
+        return resolved, resolved
+    if isinstance(default, list):
+        if default and all(isinstance(item, dict) for item in default):
+            resolved = _require_review_layers(value, label)
+            return resolved, _format_review_layers(resolved)
+        resolved = _require_string_list(value, label)
+        return resolved, _format_markdown_list(resolved)
+    raise RenderError(f"{label} has unsupported default type {type(default).__name__}")
+
+
+def _resolve_replacements(
+    sources: dict[str, str],
+    central: dict[str, Any],
+    customization: dict[str, Any],
+    defaults: dict[str, Any] | None,
+    project_root: Path,
+) -> tuple[dict[str, str], dict[str, Any]]:
+    replacements: dict[str, str] = {}
+    input_values: dict[str, Any] = {}
+    for content in sources.values():
+        for match in _SHORT_CONFIG_TOKEN.finditer(content):
+            token, key = match.group(0), match.group(1)
+            path, resolved = _resolve_short_config(central, key, project_root)
+            source = f"config.{path}"
+            replacements[token] = resolved
+            input_values[source] = resolved
+        for match in _CONFIG_TOKEN.finditer(content):
+            token, path = match.group(0), match.group(1)
+            source = f"config.{path}"
+            resolved = _resolve_config_value(
+                _lookup(central, path, "config value"), source, project_root
+            )
+            replacements[token] = resolved
+            input_values[source] = resolved
+        for match in _CUSTOM_TOKEN.finditer(content):
+            if defaults is None:
+                raise RenderError("customization tokens require customize.toml")
+            token, relative_path = match.group(0), match.group(1)
+            path = f"workflow.{relative_path}"
+            source = f"customization.{path}"
+            resolved, rendered = _resolve_customization_value(
+                _lookup(customization, path, "customization value"),
+                _lookup(defaults, path, "customization default"),
+                source,
+            )
+            replacements[token] = rendered
+            input_values[source] = resolved
+    return replacements, input_values
+
+
+def _render_sources(
+    sources: dict[str, str], replacements: dict[str, str], destination: Path
+) -> dict[str, str]:
+    """Resolve only tokens authored in installed sources in one opaque pass."""
+    # Workflow customization may reference installed skill files; bind those
+    # references to the immutable generation before inserting the prose.
+    replacements = {
+        token: value.replace("{skill-root}", str(destination))
+        if token.startswith("{workflow.")
+        else value
+        for token, value in replacements.items()
+    }
+    source_names = set(sources)
+    patterns = [
+        *(re.escape(token) for token in sorted(replacements, key=len, reverse=True)),
+        _SNAPSHOT_TOKEN.pattern,
+    ]
+    token_pattern = re.compile("|".join(patterns))
+
+    def replace(match: re.Match[str]) -> str:
+        token = match.group(0)
+        if token in replacements:
+            return replacements[token]
+        snapshot = _SNAPSHOT_TOKEN.fullmatch(token)
+        if snapshot is None:
+            raise RenderError(f"unsupported render token: {token}")
+        target = snapshot.group(1)
+        if target not in source_names:
+            raise RenderError(f"snapshot reference targets undeclared source: {target}")
+        return str(destination / target)
+
+    rendered: dict[str, str] = {}
+    for name, content in sources.items():
+        # Inserted paths and customization prose are never scanned as source tokens.
+        rendered[name] = token_pattern.sub(replace, content)
+    return rendered
+
+
+def _verify_existing(destination: Path, manifest: dict[str, Any]) -> None:
+    manifest_path = destination / "manifest.json"
+    try:
+        existing = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise RenderError(f"corrupt existing generation {destination}: {error}") from error
+    if existing != manifest:
+        raise RenderError(f"generation collision or corruption at {destination}")
+    expected_files = set(manifest["outputs"]) | {"manifest.json"}
+    actual_files = {
+        path.relative_to(destination).as_posix()
+        for path in destination.rglob("*")
+        if path.is_file()
+    }
+    if actual_files != expected_files:
+        raise RenderError(f"generation contains unexpected or missing files: {destination}")
+    for name, expected_hash in manifest["outputs"].items():
+        try:
+            actual_hash = _hash_bytes((destination / name).read_bytes())
+        except OSError as error:
+            raise RenderError(f"failed to verify {destination / name}: {error}") from error
+        if actual_hash != expected_hash:
+            raise RenderError(f"generation output hash mismatch: {destination / name}")
+
+
+def _publish(destination: Path, outputs: dict[str, bytes], manifest: dict[str, Any]) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if destination.exists():
+        _verify_existing(destination, manifest)
+        return
+    staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=destination.parent))
+    try:
+        for name, content in outputs.items():
+            path = staging / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(content)
+        (staging / "manifest.json").write_bytes(
+            json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True).encode("utf-8")
+            + b"\n"
+        )
+        try:
+            os.rename(staging, destination)
+        except OSError:
+            if destination.exists():
+                _verify_existing(destination, manifest)
+            else:
+                raise
+    finally:
+        if staging.exists():
+            shutil.rmtree(staging, ignore_errors=True)
+
+
+def render(project_root: Path, skill_dir: Path) -> Path:
+    project_root = project_root.resolve(strict=True)
+    skill_dir = skill_dir.resolve(strict=True)
+    if not (project_root / "_bmad").is_dir():
+        raise RenderError(f"project root does not contain _bmad/: {project_root}")
+
+    sources = _load_sources(skill_dir)
+    central = load_central_config(project_root)
+    has_customization = any(
+        _CUSTOM_TOKEN.search(content) for content in sources.values()
+    )
+    defaults = (
+        load_toml(skill_dir / "customize.toml", required=True)
+        if has_customization
+        else None
+    )
+    customization = (
+        load_customization(project_root, skill_dir) if has_customization else {}
+    )
+    replacements, input_values = _resolve_replacements(
+        sources, central, customization, defaults, project_root
+    )
+    source_hashes = {
+        name: _hash_bytes(content.encode("utf-8")) for name, content in sources.items()
+    }
+    root_hash = _hash_bytes(str(project_root).encode("utf-8"))[:12]
+    slug = re.sub(r"[^a-z0-9]+", "-", project_root.name.lower()).strip("-") or "project"
+    slug = slug[:80].rstrip("-") or "project"
+    renderer_hash = _hash_bytes(Path(__file__).read_bytes())
+    identity = {
+        "project_root": str(project_root),
+        "renderer_sha256": renderer_hash,
+        "resolved_values": input_values,
+        "source_sha256": source_hashes,
+    }
+    generation_hash = _hash_bytes(_canonical_json(identity))[:20]
+    destination = (
+        project_root
+        / "_bmad"
+        / "render"
+        / skill_dir.name
+        / f"{slug}-{root_hash}"
+        / generation_hash
+    )
+    rendered = _render_sources(sources, replacements, destination)
+    outputs = {name: content.encode("utf-8") for name, content in rendered.items()}
+    output_hashes = {name: _hash_bytes(content) for name, content in outputs.items()}
+    manifest = {
+        "schema_version": 1,
+        "skill": skill_dir.name,
+        "project_root": str(project_root),
+        "project_slug": slug,
+        "root_hash": root_hash,
+        "generation_hash": generation_hash,
+        "inputs": identity,
+        "outputs": output_hashes,
+    }
+    _publish(destination, outputs, manifest)
+    return destination / "workflow.md"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project-root", required=True)
+    parser.add_argument("--skill", required=True)
+    args = parser.parse_args()
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8")
+    try:
+        entry = render(Path(args.project_root), Path(args.skill))
+    except (ConfigError, RenderError, OSError, UnicodeError, ValueError) as error:
+        sys.stdout.write(f"HALT: {error}\n")
+        return 1
+    sys.stdout.write(f"read and follow {entry}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/scripts/resolve_config.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve BMad's four central TOML layers to JSON."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Installed scripts are consumer files, not a location for interpreter caches.
+sys.dont_write_bytecode = True
+
+try:
+    from config_utils import ConfigError, load_central_config
+except ModuleNotFoundError as error:
+    if error.name != "tomllib":
+        raise
+    sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib` not found).\n")
+    raise SystemExit(3) from None
+
+
+_MISSING = object()
+
+
+def extract_key(data, dotted_key: str):
+    current = data
+    for part in dotted_key.split("."):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return _MISSING
+    return current
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad central config using four-layer TOML merge."
+    )
+    parser.add_argument(
+        "--project-root",
+        "-p",
+        required=True,
+        help="Absolute project root containing _bmad/",
+    )
+    parser.add_argument(
+        "--key",
+        "-k",
+        action="append",
+        default=[],
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    try:
+        merged = load_central_config(Path(args.project_root).resolve())
+    except ConfigError as error:
+        sys.stderr.write(f"error: {error}\n")
+        return 1
+
+    output = merged
+    if args.key:
+        output = {}
+        for key in args.key:
+            value = extract_key(merged, key)
+            if value is not _MISSING:
+                output[key] = value
+    sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/scripts/resolve_customization.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve a skill's default, team, and user TOML customization layers."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Installed scripts are consumer files, not a location for interpreter caches.
+sys.dont_write_bytecode = True
+
+try:
+    from config_utils import ConfigError, load_customization
+except ModuleNotFoundError as error:
+    if error.name != "tomllib":
+        raise
+    sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib` not found).\n")
+    raise SystemExit(3) from None
+
+
+_MISSING = object()
+
+
+def find_project_root(start: Path) -> Path | None:
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").exists() or (current / ".git").exists():
+            return current
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def extract_key(data, dotted_key: str):
+    current = data
+    for part in dotted_key.split("."):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return _MISSING
+    return current
+
+
+def write_json_stdout(output) -> None:
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8")
+    sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Resolve skill customization using three-layer TOML merge."
+    )
+    parser.add_argument(
+        "--skill", "-s", required=True, help="Absolute path to the skill directory"
+    )
+    parser.add_argument(
+        "--project-root",
+        "-p",
+        help="Explicit project root containing _bmad/ (recommended)",
+    )
+    parser.add_argument(
+        "--key",
+        "-k",
+        action="append",
+        default=[],
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    skill_dir = Path(args.skill).resolve()
+    project_root = (
+        Path(args.project_root).resolve()
+        if args.project_root
+        else find_project_root(skill_dir) or find_project_root(Path.cwd())
+    )
+    try:
+        merged = load_customization(project_root, skill_dir)
+    except ConfigError as error:
+        sys.stderr.write(f"error: {error}\n")
+        return 1
+
+    output = merged
+    if args.key:
+        output = {}
+        for key in args.key:
+            value = extract_key(merged, key)
+            if value is not _MISSING:
+                output[key] = value
+    write_json_stdout(output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/scripts/tests/test_config_utils.py

@@ -0,0 +1,85 @@
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from config_utils import (  # noqa: E402
+    ConfigError,
+    load_central_config,
+    load_customization,
+    load_toml,
+    structural_merge,
+)
+
+
+class ConfigUtilsTests(unittest.TestCase):
+    def test_structural_merge_recurses_appends_and_replaces_keyed_tables(self):
+        base = {
+            "nested": {"keep": True, "replace": "old"},
+            "plain": ["base"],
+            "items": [{"id": "one", "value": "old"}],
+        }
+        override = {
+            "nested": {"replace": "new"},
+            "plain": ["override"],
+            "items": [
+                {"id": "one", "value": "new"},
+                {"id": "two", "value": "added"},
+            ],
+        }
+
+        merged = structural_merge(base, override)
+
+        self.assertEqual(merged["nested"], {"keep": True, "replace": "new"})
+        self.assertEqual(merged["plain"], ["base", "override"])
+        self.assertEqual(
+            merged["items"],
+            [
+                {"id": "one", "value": "new"},
+                {"id": "two", "value": "added"},
+            ],
+        )
+
+    def test_non_string_keyed_identifier_is_rejected(self):
+        with self.assertRaisesRegex(ConfigError, "identifier `id` must be a string"):
+            structural_merge([{"id": "valid"}], [{"id": 42}])
+
+    def test_present_malformed_optional_layer_is_rejected(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            path = Path(temp_dir) / "optional.toml"
+            path.write_text("[broken\n", encoding="utf-8")
+
+            with self.assertRaisesRegex(ConfigError, "failed to parse"):
+                load_toml(path)
+
+    def test_missing_optional_layer_is_empty(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            path = Path(temp_dir) / "optional.toml"
+
+            self.assertEqual(load_toml(path), {})
+
+    def test_filesystem_layer_precedence(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            bmad = root / "_bmad"
+            custom = bmad / "custom"
+            skill = bmad / "bmm" / "sample-skill"
+            custom.mkdir(parents=True)
+            skill.mkdir(parents=True)
+            (bmad / "config.toml").write_text('[value]\norder = "base-team"\n', encoding="utf-8")
+            (bmad / "config.user.toml").write_text('[value]\norder = "base-user"\n', encoding="utf-8")
+            (custom / "config.toml").write_text('[value]\norder = "custom-team"\n', encoding="utf-8")
+            (custom / "config.user.toml").write_text('[value]\norder = "custom-user"\n', encoding="utf-8")
+            (skill / "customize.toml").write_text('[value]\norder = "default"\n', encoding="utf-8")
+            (custom / "sample-skill.toml").write_text('[value]\norder = "team"\n', encoding="utf-8")
+            (custom / "sample-skill.user.toml").write_text('[value]\norder = "user"\n', encoding="utf-8")
+
+            self.assertEqual(load_central_config(root)["value"]["order"], "custom-user")
+            self.assertEqual(load_customization(root, skill)["value"]["order"], "user")
+
+
+if __name__ == "__main__":
+    unittest.main()