bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/shared/scripts/skf-skill-inventory.py

@@ -0,0 +1,210 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Skill Inventory — Scan skills directory and produce structured inventory.
+
+Scans the skills output folder, reads manifests and metadata, resolves active
+versions via symlinks, and outputs a JSON inventory. Reused by 9+ skills.
+
+CLI: python3 skf-skill-inventory.py <skills-output-folder>
+     python3 skf-skill-inventory.py <skills-output-folder> --skill <name>
+     python3 skf-skill-inventory.py <skills-output-folder> --manifest-only
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def read_json_file(path):
+    """Read a JSON file, returning (data, None) or (None, error)."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f), None
+    except FileNotFoundError:
+        return None, f"Not found: {path}"
+    except json.JSONDecodeError as e:
+        return None, f"JSON parse error in {path}: {e}"
+
+
+def resolve_active_version(skill_group_dir):
+    """Resolve the active version for a skill group directory.
+
+    Returns (version_string, resolved_path) or (None, None).
+    """
+    active_link = skill_group_dir / "active"
+    if active_link.is_symlink() or active_link.is_dir():
+        target = active_link.resolve()
+        if target.is_dir():
+            return target.name, target
+    return None, None
+
+
+def scan_skill_group(skill_group_dir, skill_name):
+    """Scan a single skill group directory and return its inventory entry."""
+    entry = {
+        "name": skill_name,
+        "path": str(skill_group_dir),
+        "versions": [],
+        "active_version": None,
+        "active_path": None,
+        "metadata": None,
+        "has_skill_md": False,
+        "has_provenance_map": False,
+        "has_context_snippet": False,
+        "errors": [],
+    }
+
+    # Check for version directories (contain a skill-name subdirectory)
+    for child in sorted(skill_group_dir.iterdir()):
+        if child.is_dir() and child.name != "active" and not child.name.startswith("."):
+            # Check if this is a version dir (contains skill-name subdir or SKILL.md)
+            skill_subdir = child / skill_name
+            if skill_subdir.is_dir():
+                entry["versions"].append(child.name)
+            elif (child / "SKILL.md").exists():
+                # Flat version dir without skill-name nesting
+                entry["versions"].append(child.name)
+
+    # Resolve active version
+    active_ver, active_path = resolve_active_version(skill_group_dir)
+    if active_ver:
+        entry["active_version"] = active_ver
+        # The active path points to the version dir; skill files are in version/skill-name/
+        skill_pkg = active_path / skill_name
+        if skill_pkg.is_dir():
+            entry["active_path"] = str(skill_pkg)
+        elif (active_path / "SKILL.md").exists():
+            entry["active_path"] = str(active_path)
+        else:
+            entry["active_path"] = str(active_path)
+
+    # If no versions found, check for flat layout (SKILL.md at group root)
+    if not entry["versions"]:
+        if (skill_group_dir / "SKILL.md").exists():
+            entry["versions"].append("flat")
+            entry["active_version"] = "flat"
+            entry["active_path"] = str(skill_group_dir)
+
+    # Load metadata from active path
+    active_dir = Path(entry["active_path"]) if entry["active_path"] else None
+    if active_dir and active_dir.is_dir():
+        entry["has_skill_md"] = (active_dir / "SKILL.md").exists()
+        entry["has_provenance_map"] = (active_dir / "provenance-map.json").exists()
+        entry["has_context_snippet"] = (active_dir / "context-snippet.md").exists()
+
+        metadata_path = active_dir / "metadata.json"
+        meta, meta_err = read_json_file(metadata_path)
+        if meta:
+            entry["metadata"] = {
+                "version": meta.get("version"),
+                "language": meta.get("language"),
+                "source_authority": meta.get("source_authority"),
+                "source_repo": meta.get("source_repo"),
+                "generated_by": meta.get("generated_by"),
+                "confidence_tier": meta.get("confidence_tier"),
+                "exports_total": meta.get("stats", {}).get("exports_total"),
+            }
+        elif meta_err and "Not found" not in meta_err:
+            entry["errors"].append(meta_err)
+
+    return entry
+
+
+def scan_inventory(skills_folder, skill_filter=None, manifest_only=False):
+    """Scan the skills output folder and produce an inventory."""
+    skills_dir = Path(skills_folder)
+
+    if not skills_dir.is_dir():
+        return {
+            "status": "error",
+            "error": f"Skills directory not found: {skills_dir}",
+            "code": "DIR_NOT_FOUND",
+        }
+
+    result = {
+        "status": "ok",
+        "skills_folder": str(skills_dir),
+        "manifest": None,
+        "manifest_error": None,
+        "skills": [],
+        "summary": {
+            "total_skills": 0,
+            "total_versions": 0,
+            "with_metadata": 0,
+            "with_provenance": 0,
+        },
+    }
+
+    # Load export manifest
+    manifest_path = skills_dir / ".export-manifest.json"
+    manifest, manifest_err = read_json_file(manifest_path)
+    if manifest:
+        result["manifest"] = manifest
+    else:
+        result["manifest_error"] = manifest_err
+
+    if manifest_only:
+        return result
+
+    # Determine which skills to scan
+    skill_names = set()
+
+    # From manifest exports
+    if manifest and "exports" in manifest:
+        skill_names.update(manifest["exports"].keys())
+
+    # From directory listing
+    for child in skills_dir.iterdir():
+        if child.is_dir() and not child.name.startswith("."):
+            skill_names.add(child.name)
+
+    # Apply filter
+    if skill_filter:
+        if skill_filter in skill_names:
+            skill_names = {skill_filter}
+        else:
+            return {
+                "status": "error",
+                "error": f"Skill '{skill_filter}' not found in {skills_dir}",
+                "code": "SKILL_NOT_FOUND",
+                "available": sorted(skill_names),
+            }
+
+    # Scan each skill group
+    for name in sorted(skill_names):
+        skill_group_dir = skills_dir / name
+        if skill_group_dir.is_dir():
+            entry = scan_skill_group(skill_group_dir, name)
+            result["skills"].append(entry)
+
+    # Compute summary
+    result["summary"]["total_skills"] = len(result["skills"])
+    result["summary"]["total_versions"] = sum(len(s["versions"]) for s in result["skills"])
+    result["summary"]["with_metadata"] = sum(1 for s in result["skills"] if s["metadata"])
+    result["summary"]["with_provenance"] = sum(1 for s in result["skills"] if s["has_provenance_map"])
+
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python3 skf-skill-inventory.py <skills-output-folder> [--skill <name>] [--manifest-only]", file=sys.stderr)
+        sys.exit(1)
+
+    folder = sys.argv[1]
+    skill = None
+    manifest_only = "--manifest-only" in sys.argv
+
+    if "--skill" in sys.argv:
+        idx = sys.argv.index("--skill")
+        if idx + 1 < len(sys.argv):
+            skill = sys.argv[idx + 1]
+
+    result = scan_inventory(folder, skill_filter=skill, manifest_only=manifest_only)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["status"] == "ok" else 1)

package/src/shared/scripts/skf-structural-diff.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""Structural Diff — Deterministic comparison of skill export inventories.
+
+Compares a baseline export inventory against a current export inventory and
+produces a structured JSON diff showing added, removed, and changed entries.
+Used by audit-skill and update-skill to replace LLM-based inventory comparison.
+
+CLI:
+  python3 skf-structural-diff.py baseline.json current.json
+  python3 skf-structural-diff.py baseline.json current.json -o diff-result.json
+
+Input:
+  Two JSON files. Each file must be either:
+    - An object with an "exports" array  (provenance-map / extraction-snapshot format)
+    - A plain array of export entries
+
+  Each export entry must have at minimum:
+    - name: string   (primary key for matching)
+    - type: string   (function/class/type/const/interface/etc.)
+
+  Optional fields used for change detection:
+    - signature: string
+    - file: string
+    - line: number
+    - confidence: string
+
+Output:
+  JSON object:
+    summary:          { added, removed, changed, moved, unchanged }
+    added:            list of entries present in current but not baseline
+    removed:          list of entries present in baseline but not current
+    changed:          list of { name, field, baseline_value, current_value }
+    moved:            list of { name, previous_file, current_file }
+    unchanged_count:  number of entries that matched exactly
+
+Exit codes:
+  0  — inventories are identical (no diff)
+  1  — differences found (or error)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+# Fields compared for change detection (in order).
+# "name" is the primary key and is not diffed as a field.
+# "file" is excluded — file moves are tracked separately in the "moved" list.
+DIFF_FIELDS = ["type", "signature", "line", "confidence"]
+
+
+def load_inventory(path: Path) -> tuple[list[dict], str | None]:
+    """Load an export inventory from a JSON file.
+
+    Accepts either:
+      - {"exports": [...]}  (provenance-map / extraction-snapshot)
+      - [...]               (plain array)
+
+    Returns (exports, error_message).
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return [], f"Cannot read file '{path}': {exc}"
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        return [], f"Invalid JSON in '{path}': {exc}"
+
+    if isinstance(data, list):
+        return data, None
+    if isinstance(data, dict):
+        if "exports" in data and isinstance(data["exports"], list):
+            return data["exports"], None
+        # If it's a plain object without "exports", treat values as entries
+        # (some inventory formats are name-keyed objects)
+        if all(isinstance(v, dict) for v in data.values()):
+            return list(data.values()), None
+        return [], f"Unrecognised inventory format in '{path}': expected array or object with 'exports' key"
+
+    return [], f"Unrecognised inventory format in '{path}': top-level value must be array or object"
+
+
+def index_by_name(entries: list[dict]) -> dict[str, dict]:
+    """Build a name-keyed dict from an export list, skipping nameless entries."""
+    result: dict[str, dict] = {}
+    for entry in entries:
+        name = entry.get("name", "").strip()
+        if name:
+            result[name] = entry
+    return result
+
+
+def entry_matches(base: dict, curr: dict) -> bool:
+    """Return True if two entries are identical across all DIFF_FIELDS."""
+    for field in DIFF_FIELDS:
+        if base.get(field) != curr.get(field):
+            return False
+    return True
+
+
+def diff_inventories(
+    baseline_entries: list[dict],
+    current_entries: list[dict],
+) -> dict:
+    """Compute the structural diff between two export inventories.
+
+    Returns a dict with keys: summary, added, removed, changed, unchanged_count.
+    """
+    baseline = index_by_name(baseline_entries)
+    current = index_by_name(current_entries)
+
+    baseline_names = set(baseline.keys())
+    current_names = set(current.keys())
+
+    added_names = current_names - baseline_names
+    removed_names = baseline_names - current_names
+    common_names = baseline_names & current_names
+
+    added = [current[n] for n in sorted(added_names)]
+    removed = [baseline[n] for n in sorted(removed_names)]
+
+    changed: list[dict] = []
+    moved: list[dict] = []
+    unchanged_count = 0
+
+    for name in sorted(common_names):
+        base_entry = baseline[name]
+        curr_entry = current[name]
+
+        # Detect file moves separately
+        base_file = base_entry.get("file")
+        curr_file = curr_entry.get("file")
+        if base_file and curr_file and base_file != curr_file:
+            moved.append({
+                "name": name,
+                "previous_file": base_file,
+                "current_file": curr_file,
+            })
+
+        entry_changed = False
+        for field in DIFF_FIELDS:
+            base_val = base_entry.get(field)
+            curr_val = curr_entry.get(field)
+            if base_val != curr_val:
+                changed.append({
+                    "name": name,
+                    "field": field,
+                    "baseline_value": base_val,
+                    "current_value": curr_val,
+                })
+                entry_changed = True
+
+        if not entry_changed:
+            unchanged_count += 1
+
+    # Count distinct names that have at least one field change
+    changed_names = len({c["name"] for c in changed})
+
+    return {
+        "summary": {
+            "added": len(added),
+            "removed": len(removed),
+            "changed": changed_names,
+            "moved": len(moved),
+            "unchanged": unchanged_count,
+        },
+        "added": added,
+        "removed": removed,
+        "changed": changed,
+        "moved": moved,
+        "unchanged_count": unchanged_count,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-structural-diff.py",
+        description=(
+            "Compare two JSON export inventories and produce a structured diff.\n"
+            "\n"
+            "Each inventory file must be either a JSON array of export entries\n"
+            "or a JSON object with an 'exports' key containing such an array.\n"
+            "Every entry must have at minimum 'name' and 'type' fields.\n"
+            "\n"
+            "Exit code 0 means no differences were found.\n"
+            "Exit code 1 means differences were found (or an error occurred)."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  python3 skf-structural-diff.py provenance-map.json current-snapshot.json\n"
+            "  python3 skf-structural-diff.py baseline.json current.json -o diff.json\n"
+        ),
+    )
+    parser.add_argument(
+        "baseline",
+        metavar="baseline.json",
+        help="path to the baseline export inventory (e.g. provenance-map.json)",
+    )
+    parser.add_argument(
+        "current",
+        metavar="current.json",
+        help="path to the current export inventory (e.g. extraction-snapshot.json)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="write JSON output to FILE instead of stdout",
+    )
+
+    args = parser.parse_args()
+
+    baseline_path = Path(args.baseline)
+    current_path = Path(args.current)
+
+    baseline_entries, err = load_inventory(baseline_path)
+    if err:
+        print(json.dumps({"status": "error", "error": err}, indent=2))
+        return 1
+
+    current_entries, err = load_inventory(current_path)
+    if err:
+        print(json.dumps({"status": "error", "error": err}, indent=2))
+        return 1
+
+    result = diff_inventories(baseline_entries, current_entries)
+    output_text = json.dumps(result, indent=2)
+
+    if args.output:
+        out_path = Path(args.output)
+        try:
+            out_path.write_text(output_text + "\n", encoding="utf-8")
+        except OSError as exc:
+            print(
+                json.dumps({"status": "error", "error": f"Cannot write output: {exc}"}, indent=2)
+            )
+            return 1
+    else:
+        print(output_text)
+
+    summary = result["summary"]
+    has_diff = summary["added"] or summary["removed"] or summary["changed"] or summary["moved"]
+    return 1 if has_diff else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())