bmad-module-skill-forge 0.10.0 → 1.0.0-rc.3

package/src/shared/scripts/skf-manifest-ops.py

@@ -0,0 +1,236 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Manifest Ops — CRUD operations on the export manifest.
+
+Reads, adds, updates, removes entries in .export-manifest.json.
+Used by export-skill, drop-skill, and rename-skill.
+
+CLI: python3 skf-manifest-ops.py <skills-folder> <command> [args]
+
+Commands:
+  read                          — Read entire manifest
+  get <skill-name>              — Get a single skill entry
+  set <skill-name> <version>    — Add/update skill with active version
+  remove <skill-name>           — Remove skill from manifest
+  deprecate <skill-name> [ver]  — Mark skill or version as deprecated
+  rename <old-name> <new-name>  — Rename a skill entry
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def read_manifest(manifest_path):
+    """Read manifest file, returning (data, None) or (None, error).
+
+    Handles both v1 (flat list) and v2 (dict) manifest formats.
+    V1 manifests are migrated in-place to v2 on next write.
+    Legacy `platforms` field at the version level is renamed to `ides`.
+    """
+    try:
+        with open(manifest_path, encoding="utf-8") as f:
+            data = json.load(f)
+        if data.get("schema_version") != "2":
+            data = _migrate_v1_to_v2(data)
+        data = _normalize_platforms_to_ides(data)
+        return data, None
+    except FileNotFoundError:
+        return {"schema_version": "2", "exports": {}, "updated_at": None}, None
+    except json.JSONDecodeError as e:
+        return None, f"Manifest JSON parse error: {e}"
+
+
+def _migrate_v1_to_v2(data):
+    """Migrate a v1 manifest to v2 format in memory."""
+    data["schema_version"] = "2"
+    for skill_name, entry in data.get("exports", {}).items():
+        versions = entry.get("versions", [])
+        if isinstance(versions, list):
+            active = entry.get("active_version", "")
+            deprecated = entry.get("deprecated", False)
+            new_versions = {}
+            for v in versions:
+                status = "active" if v == active and not deprecated else "archived"
+                new_versions[v] = {
+                    "ides": [],
+                    "last_exported": data.get("updated_at", ""),
+                    "status": "deprecated" if deprecated and v == active else status,
+                }
+            entry["versions"] = new_versions
+        entry.pop("deprecated", None)
+        entry.pop("deprecated_versions", None)
+    return data
+
+
+def _normalize_platforms_to_ides(data):
+    """Rename legacy `platforms` key → `ides` on each version entry.
+
+    Pre-rename v2 manifests used `platforms` for the list of IDE identifiers
+    the version was exported to. The field was ambiguous (IDE name vs context
+    file vs skill root), so it was renamed to `ides` to match
+    `config.yaml.ides`. Existing manifests are upgraded on next read.
+    """
+    for entry in data.get("exports", {}).values():
+        versions = entry.get("versions", {})
+        if not isinstance(versions, dict):
+            continue
+        for v_data in versions.values():
+            if not isinstance(v_data, dict):
+                continue
+            if "platforms" in v_data:
+                legacy = v_data.pop("platforms")
+                if "ides" not in v_data:
+                    v_data["ides"] = legacy
+    return data
+
+
+def write_manifest(manifest_path, data):
+    """Write manifest file atomically via write-to-temp-then-rename."""
+    data["updated_at"] = datetime.now(timezone.utc).isoformat()
+    manifest_path = Path(manifest_path)
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=manifest_path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+            f.write("\n")
+        os.replace(tmp_path, manifest_path)
+    except Exception:
+        os.unlink(tmp_path)
+        raise
+
+
+def cmd_read(manifest_path):
+    data, err = read_manifest(manifest_path)
+    if err:
+        return {"status": "error", "error": err}
+    return {"status": "ok", "manifest": data}
+
+
+def cmd_get(manifest_path, skill_name):
+    data, err = read_manifest(manifest_path)
+    if err:
+        return {"status": "error", "error": err}
+    exports = data.get("exports", {})
+    if skill_name not in exports:
+        return {"status": "not_found", "skill": skill_name, "available": sorted(exports.keys())}
+    return {"status": "ok", "skill": skill_name, "entry": exports[skill_name]}
+
+
+def cmd_set(manifest_path, skill_name, version):
+    data, err = read_manifest(manifest_path)
+    if err:
+        return {"status": "error", "error": err}
+    exports = data.setdefault("exports", {})
+    existing = exports.get(skill_name, {})
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+    # Preserve existing versions dict, archive the previously-active version
+    versions = existing.get("versions", {})
+    if isinstance(versions, list):
+        versions = {}  # Safety: handle any residual v1 data
+    old_active = existing.get("active_version")
+    if old_active and old_active in versions and old_active != version:
+        versions[old_active]["status"] = "archived"
+
+    # Add or update the new active version
+    existing_version = versions.get(version, {})
+    versions[version] = {
+        "ides": existing_version.get("ides", existing_version.get("platforms", [])),
+        "last_exported": today,
+        "status": "active",
+    }
+
+    exports[skill_name] = {
+        "active_version": version,
+        "versions": versions,
+    }
+    write_manifest(manifest_path, data)
+    return {"status": "ok", "action": "set", "skill": skill_name, "version": version}
+
+
+def cmd_remove(manifest_path, skill_name):
+    data, err = read_manifest(manifest_path)
+    if err:
+        return {"status": "error", "error": err}
+    exports = data.get("exports", {})
+    if skill_name not in exports:
+        return {"status": "not_found", "skill": skill_name}
+    removed = exports.pop(skill_name)
+    write_manifest(manifest_path, data)
+    return {"status": "ok", "action": "removed", "skill": skill_name, "removed_entry": removed}
+
+
+def cmd_deprecate(manifest_path, skill_name, version=None):
+    data, err = read_manifest(manifest_path)
+    if err:
+        return {"status": "error", "error": err}
+    exports = data.get("exports", {})
+    if skill_name not in exports:
+        return {"status": "not_found", "skill": skill_name}
+    versions = exports[skill_name].get("versions", {})
+    if version:
+        if version not in versions:
+            return {"status": "error", "error": f"Version '{version}' not found for '{skill_name}'"}
+        versions[version]["status"] = "deprecated"
+    else:
+        # Deprecate all versions
+        for v in versions.values():
+            v["status"] = "deprecated"
+    write_manifest(manifest_path, data)
+    return {"status": "ok", "action": "deprecated", "skill": skill_name, "version": version}
+
+
+def cmd_rename(manifest_path, old_name, new_name):
+    data, err = read_manifest(manifest_path)
+    if err:
+        return {"status": "error", "error": err}
+    exports = data.get("exports", {})
+    if old_name not in exports:
+        return {"status": "not_found", "skill": old_name}
+    if new_name in exports:
+        return {"status": "error", "error": f"Target name '{new_name}' already exists in manifest"}
+    exports[new_name] = exports.pop(old_name)
+    write_manifest(manifest_path, data)
+    return {"status": "ok", "action": "renamed", "from": old_name, "to": new_name}
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: python3 skf-manifest-ops.py <skills-folder> <command> [args]", file=sys.stderr)
+        print("Commands: read, get <name>, set <name> <version>, remove <name>, deprecate <name> [version], rename <old> <new>", file=sys.stderr)
+        sys.exit(1)
+
+    skills_folder = Path(sys.argv[1])
+    command = sys.argv[2]
+    manifest_path = skills_folder / ".export-manifest.json"
+
+    if command == "read":
+        result = cmd_read(manifest_path)
+    elif command == "get" and len(sys.argv) >= 4:
+        result = cmd_get(manifest_path, sys.argv[3])
+    elif command == "set" and len(sys.argv) >= 5:
+        result = cmd_set(manifest_path, sys.argv[3], sys.argv[4])
+    elif command == "remove" and len(sys.argv) >= 4:
+        result = cmd_remove(manifest_path, sys.argv[3])
+    elif command == "deprecate" and len(sys.argv) >= 4:
+        ver = sys.argv[4] if len(sys.argv) >= 5 else None
+        result = cmd_deprecate(manifest_path, sys.argv[3], ver)
+    elif command == "rename" and len(sys.argv) >= 5:
+        result = cmd_rename(manifest_path, sys.argv[3], sys.argv[4])
+    else:
+        result = {"status": "error", "error": f"Unknown command or missing args: {command}"}
+
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["status"] == "ok" else 1)
+
+
+if __name__ == "__main__":
+    main()

package/src/shared/scripts/skf-preflight.py

@@ -0,0 +1,164 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pyyaml"]
+# ///
+"""SKF Preflight — Config and sidecar loader for all SKF skills.
+
+Loads config.yaml, validates sidecar_path, loads preferences.yaml and
+forge-tier.yaml, and outputs a unified JSON blob for step consumption.
+
+CLI: python3 skf-preflight.py <project-root>
+     python3 skf-preflight.py <project-root> --config-path <alt-config>
+
+Output: JSON to stdout with all resolved config variables and sidecar state.
+Exit 0 on success, exit 1 on hard-halt conditions (missing config, bad sidecar).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print(
+        json.dumps({"error": "PyYAML not installed. Run: pip install pyyaml", "code": "MISSING_DEPENDENCY"}),
+    )
+    sys.exit(1)
+
+
+def load_yaml_file(path):
+    """Load a YAML file, returning (data, None) or (None, error_string)."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        return data or {}, None
+    except FileNotFoundError:
+        return None, f"File not found: {path}"
+    except yaml.YAMLError as e:
+        return None, f"YAML parse error in {path}: {e}"
+
+
+def run_preflight(project_root, config_path=None):
+    """Run preflight checks and return a result dict."""
+    project_root = Path(project_root).resolve()
+
+    # 1. Load config.yaml
+    if config_path:
+        cfg_path = Path(config_path)
+    else:
+        cfg_path = project_root / "_bmad" / "skf" / "config.yaml"
+
+    config, err = load_yaml_file(cfg_path)
+    if err:
+        return {
+            "status": "hard-halt",
+            "error": f"Cannot initialize. SKF config not found at {cfg_path}. Run the skf-setup skill to initialize your forge environment.",
+            "code": "CONFIG_MISSING",
+        }
+
+    # 2. Resolve config variables
+    resolved = {
+        "project_root": str(project_root),
+        "config_path": str(cfg_path),
+        "project_name": config.get("project_name", ""),
+        "output_folder": config.get("output_folder", ""),
+        "user_name": config.get("user_name", ""),
+        "communication_language": config.get("communication_language", "English"),
+        "document_output_language": config.get("document_output_language", "English"),
+        "sidecar_path": config.get("sidecar_path", ""),
+        "skills_output_folder": config.get("skills_output_folder", ""),
+        "forge_data_folder": config.get("forge_data_folder", ""),
+    }
+
+    # 3. Validate sidecar_path
+    sidecar_path = resolved["sidecar_path"]
+    if not sidecar_path or sidecar_path == "{sidecar_path}":
+        return {
+            "status": "hard-halt",
+            "error": (
+                "Cannot initialize. sidecar_path is not defined in your installed config.yaml. "
+                f"Add sidecar_path: {project_root}/_bmad/_memory/forger-sidecar to your project "
+                "config.yaml and retry. This is a known installer issue with prompt: false config variables."
+            ),
+            "code": "SIDECAR_UNDEFINED",
+            "config": resolved,
+        }
+
+    sidecar_dir = Path(sidecar_path)
+    if not sidecar_dir.is_absolute():
+        sidecar_dir = project_root / sidecar_path
+
+    if not sidecar_dir.is_dir():
+        return {
+            "status": "hard-halt",
+            "error": f"Sidecar directory not found: {sidecar_dir}. Run skf-setup to initialize.",
+            "code": "SIDECAR_MISSING",
+            "config": resolved,
+        }
+
+    resolved["sidecar_path_resolved"] = str(sidecar_dir)
+
+    # 4. Load sidecar files
+    sidecar = {}
+
+    prefs_path = sidecar_dir / "preferences.yaml"
+    prefs, prefs_err = load_yaml_file(prefs_path)
+    if prefs_err:
+        sidecar["preferences"] = None
+        sidecar["preferences_error"] = prefs_err
+    else:
+        sidecar["preferences"] = prefs
+
+    tier_path = sidecar_dir / "forge-tier.yaml"
+    tier, tier_err = load_yaml_file(tier_path)
+    if tier_err:
+        sidecar["forge_tier"] = None
+        sidecar["forge_tier_error"] = tier_err
+    else:
+        sidecar["forge_tier"] = tier
+
+    # 5. Derive convenience fields
+    tier_value = None
+    if tier:
+        tier_value = tier.get("tier")
+
+    compact_greeting = False
+    if prefs:
+        compact_greeting = prefs.get("compact_greeting", False) is True
+
+    tier_override = None
+    if prefs:
+        tier_override = prefs.get("tier_override")
+
+    return {
+        "status": "ok",
+        "config": resolved,
+        "sidecar": sidecar,
+        "derived": {
+            "tier": tier_override or tier_value,
+            "tier_source": "override" if tier_override else ("detected" if tier_value else None),
+            "compact_greeting": compact_greeting,
+            "is_first_run": tier_value is None,
+        },
+    }
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python3 skf-preflight.py <project-root> [--config-path <path>]", file=sys.stderr)
+        sys.exit(1)
+
+    proj_root = sys.argv[1]
+    cfg_path = None
+
+    if "--config-path" in sys.argv:
+        idx = sys.argv.index("--config-path")
+        if idx + 1 < len(sys.argv):
+            cfg_path = sys.argv[idx + 1]
+
+    result = run_preflight(proj_root, cfg_path)
+    print(json.dumps(result, indent=2))
+    sys.exit(1 if result["status"] == "hard-halt" else 0)

package/src/shared/scripts/skf-rebuild-managed-sections.py

@@ -0,0 +1,201 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Rebuild Managed Sections — Context file marker surgery.
+
+Reads a context file (CLAUDE.md/AGENTS.md/.cursorrules), finds the
+<!-- SKF:BEGIN --> / <!-- SKF:END --> markers, and replaces the managed
+section with new content. Preserves all content outside the markers.
+
+CLI: python3 skf-rebuild-managed-sections.py <context-file> <action> [args]
+
+Actions:
+  read          — Extract current managed section content
+  replace       — Replace managed section with content from stdin or --content
+  clear         — Remove managed section entirely (markers + content)
+  insert        — Insert managed section if not present (at end of file)
+  check         — Check if managed section exists, report status
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+BEGIN_MARKER_PREFIX = "<!-- SKF:BEGIN"
+END_MARKER = "<!-- SKF:END -->"
+MARKER_PATTERN = re.compile(
+    r"(<!-- SKF:BEGIN[^>]*-->)(.*?)(<!-- SKF:END -->)",
+    re.DOTALL,
+)
+
+
+def read_context_file(file_path):
+    """Read a context file. Returns (content, None) or (None, error)."""
+    try:
+        return Path(file_path).read_text(encoding="utf-8"), None
+    except FileNotFoundError:
+        return None, f"File not found: {file_path}"
+
+
+def find_managed_section(content):
+    """Find the managed section in content. Returns match or None."""
+    return MARKER_PATTERN.search(content)
+
+
+def cmd_check(file_path):
+    """Check if managed section exists."""
+    content, err = read_context_file(file_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    has_begin = BEGIN_MARKER_PREFIX in content
+    has_end = END_MARKER in content
+    match = find_managed_section(content)
+
+    if match:
+        section_content = match.group(2)
+        return {
+            "status": "ok",
+            "has_managed_section": True,
+            "markers_valid": True,
+            "section_length": len(section_content.strip()),
+            "section_line_count": len(section_content.strip().split("\n")) if section_content.strip() else 0,
+        }
+    elif has_begin and not has_end:
+        return {
+            "status": "ok",
+            "has_managed_section": False,
+            "markers_valid": False,
+            "error_detail": "Found <!-- SKF:BEGIN but no matching <!-- SKF:END -->",
+        }
+    elif not has_begin and has_end:
+        return {
+            "status": "ok",
+            "has_managed_section": False,
+            "markers_valid": False,
+            "error_detail": "Found <!-- SKF:END --> but no matching <!-- SKF:BEGIN",
+        }
+    else:
+        return {"status": "ok", "has_managed_section": False, "markers_valid": True}
+
+
+def cmd_read(file_path):
+    """Extract the managed section content."""
+    content, err = read_context_file(file_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    match = find_managed_section(content)
+    if not match:
+        return {"status": "ok", "has_managed_section": False, "content": None}
+
+    return {"status": "ok", "has_managed_section": True, "content": match.group(2)}
+
+
+def cmd_replace(file_path, new_content):
+    """Replace managed section content between markers."""
+    content, err = read_context_file(file_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    match = find_managed_section(content)
+    if not match:
+        return {"status": "error", "error": "No managed section found. Use 'insert' to create one."}
+
+    # Replace content between markers with fresh timestamp
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    new_section = f"<!-- SKF:BEGIN updated:{today} -->\n{new_content}\n{END_MARKER}"
+    updated = content[: match.start()] + new_section + content[match.end() :]
+
+    Path(file_path).write_text(updated, encoding="utf-8")
+    return {"status": "ok", "action": "replaced", "bytes_written": len(updated)}
+
+
+def cmd_clear(file_path):
+    """Remove managed section entirely (markers + content)."""
+    content, err = read_context_file(file_path)
+    if err:
+        return {"status": "error", "error": err}
+
+    match = find_managed_section(content)
+    if not match:
+        return {"status": "ok", "action": "no_change", "reason": "No managed section found"}
+
+    # Remove the entire marker block, plus any surrounding blank lines
+    before = content[: match.start()].rstrip("\n")
+    after = content[match.end() :].lstrip("\n")
+    updated = before + ("\n\n" if before and after else "") + after
+
+    Path(file_path).write_text(updated, encoding="utf-8")
+    return {"status": "ok", "action": "cleared", "bytes_written": len(updated)}
+
+
+def cmd_insert(file_path, new_content):
+    """Insert managed section at end of file if not present."""
+    content, err = read_context_file(file_path)
+    if err:
+        # File doesn't exist — create it
+        if "not found" in err.lower():
+            content = ""
+        else:
+            return {"status": "error", "error": err}
+
+    match = find_managed_section(content)
+    if match:
+        return {"status": "error", "error": "Managed section already exists. Use 'replace' instead."}
+
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    section = f"\n<!-- SKF:BEGIN updated:{today} -->\n{new_content}\n{END_MARKER}\n"
+    updated = content.rstrip("\n") + "\n" + section if content.strip() else section.lstrip("\n")
+
+    Path(file_path).write_text(updated, encoding="utf-8")
+    return {"status": "ok", "action": "inserted", "bytes_written": len(updated)}
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: python3 skf-rebuild-managed-sections.py <context-file> <action> [--content <text>]", file=sys.stderr)
+        print("Actions: read, replace, clear, insert, check", file=sys.stderr)
+        sys.exit(1)
+
+    file_path = sys.argv[1]
+    action = sys.argv[2]
+
+    content_arg = None
+    if "--content" in sys.argv:
+        idx = sys.argv.index("--content")
+        if idx + 1 < len(sys.argv):
+            content_arg = sys.argv[idx + 1]
+    elif action in ("replace", "insert") and not sys.stdin.isatty():
+        content_arg = sys.stdin.read()
+
+    if action == "check":
+        result = cmd_check(file_path)
+    elif action == "read":
+        result = cmd_read(file_path)
+    elif action == "replace":
+        if content_arg is None:
+            result = {"status": "error", "error": "replace requires --content or stdin"}
+        else:
+            result = cmd_replace(file_path, content_arg)
+    elif action == "clear":
+        result = cmd_clear(file_path)
+    elif action == "insert":
+        if content_arg is None:
+            result = {"status": "error", "error": "insert requires --content or stdin"}
+        else:
+            result = cmd_insert(file_path, content_arg)
+    else:
+        result = {"status": "error", "error": f"Unknown action: {action}"}
+
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["status"] == "ok" else 1)
+
+
+if __name__ == "__main__":
+    main()