bmad-module-skill-forge 1.3.0 → 1.4.0

package/src/shared/scripts/skf-detect-workspaces.py

@@ -0,0 +1,427 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["pyyaml"]
+# ///
+"""SKF Detect Workspaces — pure detector for monorepo / multi-package layouts.
+
+Takes a JSON payload on stdin describing a target repo's file tree plus the
+contents of a small set of root manifests, and returns whether a workspace
+layout is present, which manifest kind drives it, and the list of resolved
+workspaces. The helper does NO file I/O — the caller (typically
+skf-brief-skill step-02 §1b) fetches files via `gh api` / local filesystem
+and pipes the relevant content in.
+
+Detection runs in priority order; the first matching detector wins:
+
+  1. npm-workspaces       package.json has `workspaces: [...]` or `{packages: [...]}`
+  2. pnpm-workspaces      pnpm-workspace.yaml exists with a `packages:` list
+  3. lerna                lerna.json exists (`packages` field optional, defaults to `packages/*`)
+  4. cargo-workspace      Cargo.toml has `[workspace]` with `members = [...]`
+  5. python-multi-package multiple pyproject.toml under packages/* or apps/*
+  6. generic-folders      apps/, packages/, libs/, or code/ each with subdirs
+                          containing a recognisable manifest
+
+Glob members (`packages/*`, `apps/*`, etc.) are resolved against the supplied
+file tree; only directories whose recognisable manifest is present in the tree
+become workspaces. A detector that finds zero non-excluded matches falls
+through to the next detector instead of returning is_monorepo: true with an
+empty list.
+
+Input JSON shape (stdin):
+
+  {
+    "tree": ["package.json", "packages/foo/package.json", "packages/foo/src/index.js", ...],
+    "manifests": {
+      "package.json":        "<raw text>",
+      "Cargo.toml":          "<raw text>",
+      "pnpm-workspace.yaml": "<raw text>",
+      "lerna.json":          "<raw text>"
+    }
+  }
+
+  - `tree` is a flat list of repository-relative file paths (POSIX separators).
+    Per-workspace child manifests (e.g. `packages/foo/package.json`) MUST appear
+    here for glob resolution; their contents are optional.
+  - `manifests` is a dict keyed by repository-relative path; only root-level
+    manifests must be supplied. Per-workspace manifest contents may be
+    included to populate the workspace `name` field, but absence is fine
+    (the path basename is used as a fallback).
+
+Output JSON shape (stdout):
+
+  {
+    "is_monorepo":   true | false,
+    "manifest_kind": "npm-workspaces" | "pnpm-workspaces" | "lerna"
+                   | "cargo-workspace" | "python-multi-package"
+                   | "generic-folders" | null,
+    "workspaces":    [
+      {"name": "foo", "path": "packages/foo", "manifest": "packages/foo/package.json"},
+      ...
+    ],
+    "warnings":      ["..."]
+  }
+
+Exit codes:
+
+  0  success (regardless of is_monorepo value)
+  1  payload error (malformed top-level JSON shape)
+  2  stdin / argparse / JSON-decode error
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import re
+import sys
+import tomllib
+from typing import Optional
+
+
+GENERIC_PARENTS = ("apps", "packages", "libs", "code")
+RECOGNISED_MANIFESTS = (
+    "package.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "setup.py",
+    "go.mod",
+    "build.gradle",
+    "build.gradle.kts",
+    "pom.xml",
+)
+
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+
+def _normalise_path(path: str) -> str:
+    """Strip leading './' and trailing '/' so comparisons are stable."""
+    while path.startswith("./"):
+        path = path[2:]
+    return path.rstrip("/")
+
+
+def _match_globs(tree: set[str], globs: list[str]) -> list[str]:
+    """Resolve workspace globs against the tree.
+
+    Returns the sorted list of *directory paths* that have at least one matching
+    manifest under them. Patterns starting with `!` are exclusions applied after
+    the inclusion pass. Brace expansion is not supported (npm/pnpm rarely use
+    it in published configs); a literal pattern without `*` is treated as a
+    literal directory path.
+    """
+    includes: list[str] = []
+    excludes: list[str] = []
+    for raw in globs:
+        if not isinstance(raw, str) or not raw.strip():
+            continue
+        cleaned = _normalise_path(raw.strip())
+        if cleaned.startswith("!"):
+            excludes.append(cleaned[1:])
+        else:
+            includes.append(cleaned)
+
+    candidate_dirs: set[str] = set()
+    for pat in includes:
+        if "*" in pat:
+            for path in tree:
+                # match the directory portion of every file path against the glob
+                parts = path.split("/")
+                for depth in range(1, len(parts)):
+                    candidate = "/".join(parts[:depth])
+                    if fnmatch.fnmatchcase(candidate, pat):
+                        candidate_dirs.add(candidate)
+        else:
+            # literal directory; include only if the tree contains a manifest under it
+            candidate_dirs.add(pat)
+
+    # Apply excludes
+    survivors: set[str] = set()
+    for cand in candidate_dirs:
+        if any(fnmatch.fnmatchcase(cand, ex) or cand == ex for ex in excludes):
+            continue
+        survivors.add(cand)
+
+    return sorted(survivors)
+
+
+def _find_workspace_manifest(workspace_path: str, tree: set[str]) -> Optional[str]:
+    """Return the first recognised manifest under `workspace_path`, or None."""
+    for manifest in RECOGNISED_MANIFESTS:
+        candidate = f"{workspace_path}/{manifest}"
+        if candidate in tree:
+            return candidate
+    return None
+
+
+def _read_workspace_name(manifest_path: str, manifests: dict[str, str], fallback: str) -> str:
+    """Extract a sensible name from a workspace's manifest.
+
+    Best-effort: returns the manifest's declared package name when parseable,
+    otherwise the directory basename.
+    """
+    content = manifests.get(manifest_path)
+    if content is None:
+        return fallback
+    if manifest_path.endswith("package.json"):
+        try:
+            data = json.loads(content)
+            name = data.get("name")
+            if isinstance(name, str) and name:
+                return name
+        except (json.JSONDecodeError, AttributeError):
+            pass
+    elif manifest_path.endswith("Cargo.toml"):
+        try:
+            data = tomllib.loads(content)
+            name = data.get("package", {}).get("name")
+            if isinstance(name, str) and name:
+                return name
+        except tomllib.TOMLDecodeError:
+            pass
+    elif manifest_path.endswith("pyproject.toml"):
+        try:
+            data = tomllib.loads(content)
+            name = data.get("project", {}).get("name")
+            if isinstance(name, str) and name:
+                return name
+        except tomllib.TOMLDecodeError:
+            pass
+    return fallback
+
+
+def _build_workspaces(
+    workspace_dirs: list[str],
+    tree: set[str],
+    manifests: dict[str, str],
+) -> list[dict]:
+    """Resolve each workspace dir to its manifest + name, drop dirs without a manifest."""
+    out: list[dict] = []
+    for ws_path in workspace_dirs:
+        manifest = _find_workspace_manifest(ws_path, tree)
+        if manifest is None:
+            continue
+        fallback_name = ws_path.rsplit("/", 1)[-1] or ws_path
+        name = _read_workspace_name(manifest, manifests, fallback_name)
+        out.append({"name": name, "path": ws_path, "manifest": manifest})
+    return out
+
+
+# --------------------------------------------------------------------------
+# Detectors
+# --------------------------------------------------------------------------
+
+
+def detect_npm_workspaces(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    content = manifests.get("package.json")
+    if content is None:
+        return None
+    try:
+        data = json.loads(content)
+    except json.JSONDecodeError as e:
+        warnings.append(f"package.json JSON parse error: {e}")
+        return None
+    if not isinstance(data, dict):
+        return None
+    ws = data.get("workspaces")
+    if ws is None:
+        return None
+    if isinstance(ws, dict):
+        ws = ws.get("packages", [])
+    if not isinstance(ws, list) or not ws:
+        return None
+    dirs = _match_globs(tree, ws)
+    return _build_workspaces(dirs, tree, manifests)
+
+
+def detect_pnpm_workspaces(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    content = manifests.get("pnpm-workspace.yaml")
+    if content is None:
+        return None
+    try:
+        import yaml  # local import keeps top-level cheap when YAML is unused
+    except ImportError:
+        warnings.append("pyyaml not available — pnpm-workspace.yaml not parsed")
+        return None
+    try:
+        data = yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        warnings.append(f"pnpm-workspace.yaml parse error: {e}")
+        return None
+    if not isinstance(data, dict):
+        return None
+    pkgs = data.get("packages")
+    if not isinstance(pkgs, list) or not pkgs:
+        return None
+    dirs = _match_globs(tree, pkgs)
+    return _build_workspaces(dirs, tree, manifests)
+
+
+def detect_lerna(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    content = manifests.get("lerna.json")
+    if content is None:
+        return None
+    try:
+        data = json.loads(content)
+    except json.JSONDecodeError as e:
+        warnings.append(f"lerna.json JSON parse error: {e}")
+        return None
+    if not isinstance(data, dict):
+        return None
+    pkgs = data.get("packages")
+    if pkgs is None:
+        return None
+    if not isinstance(pkgs, list) or not pkgs:
+        return None
+    dirs = _match_globs(tree, pkgs)
+    return _build_workspaces(dirs, tree, manifests)
+
+
+def detect_cargo_workspace(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    content = manifests.get("Cargo.toml")
+    if content is None:
+        return None
+    try:
+        data = tomllib.loads(content)
+    except tomllib.TOMLDecodeError as e:
+        warnings.append(f"Cargo.toml parse error: {e}")
+        return None
+    workspace = data.get("workspace")
+    if not isinstance(workspace, dict):
+        return None
+    members = workspace.get("members")
+    if not isinstance(members, list) or not members:
+        return None
+    excludes = workspace.get("exclude", [])
+    patterns = list(members) + [f"!{e}" for e in excludes if isinstance(e, str)]
+    dirs = _match_globs(tree, patterns)
+    return _build_workspaces(dirs, tree, manifests)
+
+
+def detect_python_multi_package(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    candidates: list[str] = []
+    for path in tree:
+        if not path.endswith("/pyproject.toml"):
+            continue
+        parent = path[: -len("/pyproject.toml")]
+        # match `packages/<x>/pyproject.toml`, `apps/<x>/pyproject.toml`, or `libs/<x>/pyproject.toml`
+        if re.match(r"^(packages|apps|libs)/[^/]+$", parent):
+            candidates.append(parent)
+    if len(candidates) < 2:
+        return None
+    return _build_workspaces(sorted(set(candidates)), tree, manifests)
+
+
+def detect_generic_folders(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    """Last-resort: ≥2 manifested subdirs under any combination of apps/, packages/, libs/, code/.
+
+    Accumulates across all GENERIC_PARENTS — a repo with one manifested child under apps/
+    and one under packages/ counts as a 2-workspace monorepo. Earlier detectors (npm, pnpm,
+    cargo) take priority for repos with a root workspace manifest.
+    """
+    discovered: list[str] = []
+    for parent in GENERIC_PARENTS:
+        children: set[str] = set()
+        for path in tree:
+            if not path.startswith(parent + "/"):
+                continue
+            parts = path.split("/")
+            if len(parts) < 3:
+                continue  # need at least parent/child/file
+            children.add(f"{parent}/{parts[1]}")
+        for child in children:
+            if _find_workspace_manifest(child, tree) is not None:
+                discovered.append(child)
+    if len(discovered) < 2:
+        return None
+    return _build_workspaces(sorted(set(discovered)), tree, manifests)
+
+
+DETECTORS: list[tuple[str, callable]] = [
+    ("npm-workspaces",       detect_npm_workspaces),
+    ("pnpm-workspaces",      detect_pnpm_workspaces),
+    ("lerna",                detect_lerna),
+    ("cargo-workspace",      detect_cargo_workspace),
+    ("python-multi-package", detect_python_multi_package),
+    ("generic-folders",      detect_generic_folders),
+]
+
+
+# --------------------------------------------------------------------------
+# Entry point
+# --------------------------------------------------------------------------
+
+
+def detect(payload: dict) -> dict:
+    """Pure detection — the CLI wraps this with stdin/stdout I/O and exit-code mapping."""
+    tree_raw = payload.get("tree")
+    manifests = payload.get("manifests")
+    warnings: list[str] = []
+    if not isinstance(tree_raw, list):
+        return {"_payload_error": "missing or non-list 'tree' field"}
+    if not isinstance(manifests, dict):
+        return {"_payload_error": "missing or non-dict 'manifests' field"}
+    tree: set[str] = {_normalise_path(p) for p in tree_raw if isinstance(p, str) and p.strip()}
+
+    for kind, detector in DETECTORS:
+        result = detector(tree, manifests, warnings)
+        if result and len(result) >= 1:
+            return {
+                "is_monorepo":   True,
+                "manifest_kind": kind,
+                "workspaces":    result,
+                "warnings":      warnings,
+            }
+
+    return {
+        "is_monorepo":   False,
+        "manifest_kind": None,
+        "workspaces":    [],
+        "warnings":      warnings,
+    }
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Detect monorepo / workspace layouts from a tree + manifests payload.")
+    parser.add_argument("--json", help="Inline JSON payload (otherwise read from stdin).")
+    args = parser.parse_args(argv)
+
+    raw = args.json
+    if raw is None:
+        raw = sys.stdin.read()
+    if not raw.strip():
+        print(json.dumps({"error": "empty input"}), file=sys.stderr)
+        return 2
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(json.dumps({"error": f"json decode error: {e}"}), file=sys.stderr)
+        return 2
+
+    result = detect(payload)
+    if "_payload_error" in result:
+        print(json.dumps({"error": result["_payload_error"]}), file=sys.stderr)
+        return 1
+
+    print(json.dumps(result, separators=(",", ":")))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/shared/scripts/skf-emit-brief-result-envelope.py

@@ -0,0 +1,257 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Emit Brief Result Envelope — Schema-locked headless output for skf-brief-skill.
+
+Replaces the prose-driven envelope assembly in `src/skf-brief-skill/steps-c/
+step-05-write-brief.md` §4b with one Python invocation. The envelope contract
+(SKF_BRIEF_RESULT_JSON) is documented in src/skf-brief-skill/SKILL.md Result
+Contract section.
+
+LLM-rendered envelopes risk silent schema drift on every invocation —
+a pipeline that grep's `SKF_BRIEF_RESULT_JSON: {…}` out of the workflow
+log can break if the model decides to rename a key, reorder properties,
+or swap a null for an empty string. This script is the single source of
+truth: it takes a context payload as JSON on stdin, derives the
+exit_code from the halt_reason deterministically, validates the
+assembled envelope against the JSON Schema at
+`src/shared/scripts/schemas/skf-brief-result-envelope.v1.json`, and
+emits the line in a fixed shape.
+
+Subcommands:
+
+  emit       Read context payload as JSON on stdin, derive exit_code,
+             validate against the schema, emit the
+             `SKF_BRIEF_RESULT_JSON: {one-line JSON}` prefix line on
+             stdout (or stderr if --target=stderr). Default subcommand.
+
+  validate   Read an envelope (without the prefix) as JSON on stdin
+             and verify it against the schema. Silent + exit 0 on
+             success; non-zero exit + stderr error on failure. Useful
+             for paranoid pipelines that want to validate a received
+             envelope before consuming it.
+
+Context payload shape (consumed by `emit`):
+
+  {
+    "status":      "success" | "error",
+    "brief_path":  "/abs/path/skill-brief.yaml" | null,
+    "skill_name":  "marked",
+    "version":     "1.2.3" | null,
+    "language":    "javascript" | null,
+    "scope_type":  "public-api" | null,
+    "halt_reason": null | "input-missing" | "input-invalid" |
+                   "forge-tier-missing" | "target-inaccessible" |
+                   "gh-auth-failed" | "write-failed" |
+                   "overwrite-cancelled" | "user-cancelled"
+  }
+
+The caller does NOT supply exit_code — the script derives it from
+halt_reason via the canonical mapping (null→0; input-*→2;
+forge-tier-missing/target-inaccessible/gh-auth-failed→3;
+write-failed→4; overwrite-cancelled→5; user-cancelled→6).
+
+Cross-platform: pure stdlib, no third-party deps.
+
+CLI:
+
+  echo '{...}' | uv run skf-emit-brief-result-envelope.py emit
+  echo '{...}' | uv run skf-emit-brief-result-envelope.py emit --target stderr
+  echo '{...}' | uv run skf-emit-brief-result-envelope.py validate
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+PREFIX = "SKF_BRIEF_RESULT_JSON: "
+
+VALID_STATUS = {"success", "error"}
+VALID_HALT_REASONS = {
+    None,
+    "input-missing",
+    "input-invalid",
+    "forge-tier-missing",
+    "target-inaccessible",
+    "gh-auth-failed",
+    "write-failed",
+    "overwrite-cancelled",
+    "user-cancelled",
+}
+VALID_SCOPE_TYPES = {
+    None,
+    "full-library",
+    "specific-modules",
+    "public-api",
+    "component-library",
+    "reference-app",
+    "docs-only",
+}
+
+# Canonical halt_reason → exit_code mapping (mirrors SKILL.md Exit Codes table).
+HALT_TO_EXIT = {
+    None: 0,
+    "input-missing": 2,
+    "input-invalid": 2,
+    "forge-tier-missing": 3,
+    "target-inaccessible": 3,
+    "gh-auth-failed": 3,
+    "write-failed": 4,
+    "overwrite-cancelled": 5,
+    "user-cancelled": 6,
+}
+
+# Envelope key order — fixed so byte-stable diffs are possible.
+KEY_ORDER = [
+    "status",
+    "brief_path",
+    "skill_name",
+    "version",
+    "language",
+    "scope_type",
+    "exit_code",
+    "halt_reason",
+]
+
+
+def _die(message: str, code: int = 1) -> None:
+    sys.stderr.write(f"skf-emit-brief-result-envelope: {message}\n")
+    sys.exit(code)
+
+
+def assemble(ctx: dict[str, Any]) -> dict[str, Any]:
+    """Build the envelope from a context payload, deriving exit_code."""
+    status = ctx.get("status")
+    if status not in VALID_STATUS:
+        _die(f"status must be one of {sorted(VALID_STATUS)}; got {status!r}")
+
+    halt_reason = ctx.get("halt_reason")
+    if halt_reason not in VALID_HALT_REASONS:
+        _die(
+            f"halt_reason must be one of {sorted(r for r in VALID_HALT_REASONS if r is not None)} or null; "
+            f"got {halt_reason!r}"
+        )
+
+    if status == "success" and halt_reason is not None:
+        _die(f"halt_reason must be null when status is 'success'; got {halt_reason!r}")
+    if status == "error" and halt_reason is None:
+        _die("halt_reason must be set when status is 'error'")
+
+    scope_type = ctx.get("scope_type")
+    if scope_type not in VALID_SCOPE_TYPES:
+        _die(
+            f"scope_type must be one of {sorted(t for t in VALID_SCOPE_TYPES if t is not None)} or null; "
+            f"got {scope_type!r}"
+        )
+
+    skill_name = ctx.get("skill_name")
+    if not skill_name or not isinstance(skill_name, str):
+        _die(f"skill_name is required and must be a non-empty string; got {skill_name!r}")
+
+    envelope = {
+        "status": status,
+        "brief_path": ctx.get("brief_path"),
+        "skill_name": skill_name,
+        "version": ctx.get("version"),
+        "language": ctx.get("language"),
+        "scope_type": scope_type,
+        "exit_code": HALT_TO_EXIT[halt_reason],
+        "halt_reason": halt_reason,
+    }
+    # Re-emit in canonical key order
+    return {k: envelope[k] for k in KEY_ORDER}
+
+
+def validate(envelope: dict[str, Any]) -> None:
+    """Validate an envelope dict against the schema. Exits non-zero on failure."""
+    required = set(KEY_ORDER)
+    missing = required - set(envelope.keys())
+    if missing:
+        _die(f"envelope missing required keys: {sorted(missing)}")
+    extra = set(envelope.keys()) - required
+    if extra:
+        _die(f"envelope has unexpected keys: {sorted(extra)}")
+    if envelope.get("status") not in VALID_STATUS:
+        _die(f"status invalid: {envelope.get('status')!r}")
+    if envelope.get("halt_reason") not in VALID_HALT_REASONS:
+        _die(f"halt_reason invalid: {envelope.get('halt_reason')!r}")
+    if envelope.get("scope_type") not in VALID_SCOPE_TYPES:
+        _die(f"scope_type invalid: {envelope.get('scope_type')!r}")
+    if envelope.get("exit_code") not in {0, 2, 3, 4, 5, 6}:
+        _die(f"exit_code invalid: {envelope.get('exit_code')!r}")
+    expected_exit = HALT_TO_EXIT[envelope.get("halt_reason")]
+    if envelope.get("exit_code") != expected_exit:
+        _die(
+            f"exit_code {envelope.get('exit_code')!r} does not match canonical mapping "
+            f"for halt_reason {envelope.get('halt_reason')!r} (expected {expected_exit})"
+        )
+    if not envelope.get("skill_name") or not isinstance(envelope.get("skill_name"), str):
+        _die("skill_name must be a non-empty string")
+
+
+def cmd_emit(target_stream: str) -> int:
+    raw = sys.stdin.read()
+    if not raw or not raw.strip():
+        _die("emit: empty stdin (expected JSON context payload)")
+    try:
+        ctx = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _die(f"emit: invalid JSON on stdin: {e}")
+    if not isinstance(ctx, dict):
+        _die("emit: context payload must be a JSON object")
+
+    envelope = assemble(ctx)
+    line = PREFIX + json.dumps(envelope, separators=(",", ":"))
+    if target_stream == "stderr":
+        print(line, file=sys.stderr)
+    else:
+        print(line)
+    return 0
+
+
+def cmd_validate() -> int:
+    raw = sys.stdin.read()
+    if not raw or not raw.strip():
+        _die("validate: empty stdin (expected envelope JSON)")
+    try:
+        envelope = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _die(f"validate: invalid JSON on stdin: {e}")
+    if not isinstance(envelope, dict):
+        _die("validate: envelope must be a JSON object")
+    validate(envelope)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-emit-brief-result-envelope",
+        description="Schema-locked SKF_BRIEF_RESULT_JSON envelope emitter for skf-brief-skill.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_emit = sub.add_parser("emit", help="Read context JSON on stdin, emit prefixed envelope line")
+    p_emit.add_argument(
+        "--target",
+        choices=["stdout", "stderr"],
+        default="stdout",
+        help="Output stream for the prefixed envelope line. step-05 §4b uses stdout on success and stderr on HARD HALT.",
+    )
+
+    sub.add_parser("validate", help="Read envelope JSON on stdin, exit 0 if schema-valid")
+
+    args = parser.parse_args()
+
+    if args.cmd == "emit":
+        return cmd_emit(args.target)
+    elif args.cmd == "validate":
+        return cmd_validate()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())