bmad-module-skill-forge 1.1.0 → 1.3.0

package/src/shared/scripts/skf-render-quick-metadata.py

@@ -0,0 +1,192 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Render Quick Metadata — render metadata.json per the canonical
+skill-template.md schema with quick-skill-specific population rules.
+
+Pure renderer — no I/O beyond stdin/stdout. Reads a JSON payload of
+extracted state on stdin and emits the corresponding metadata.json
+on stdout. Replaces the hand-assembly the LLM previously did in
+skf-quick-skill step-04 §4.
+
+Constants vs. input-derived split mirrors step-04's documentation:
+
+  Constants (always literal):
+    skill_type            "single"
+    spec_version          "1.3"
+    source_authority      "community"
+    confidence_tier       "Quick"
+    generated_by          "quick-skill"
+    confidence_distribution.t1, t2, t3                             0
+    tool_versions.ast_grep, tool_versions.qmd                      null
+    stats.exports_internal, stats.scripts_count, stats.assets_count 0
+    stats.public_api_coverage, stats.total_coverage                 1.0
+
+  Input-derived (from stdin payload):
+    name, version, description, language, source_repo,
+    source_root, source_commit, source_package,
+    exports[], dependencies[], compatibility,
+    provenance.language_hint, provenance.scope_hint,
+    tool_versions.skf
+
+  Computed:
+    generation_date                 ISO 8601 UTC ("YYYY-MM-DDTHH:MM:SSZ")
+    confidence_distribution.t1_low  count(exports)
+    stats.exports_documented / public_api / total  count(exports)
+
+Input JSON shape (stdin):
+
+  {
+    "name":           "foo",
+    "version":        "1.2.3",                      (default "1.0.0")
+    "description":    "...",                         (default "")
+    "language":       "python",
+    "source_repo":    "https://github.com/x/y",
+    "source_root":    "src/foo",                     (optional)
+    "source_commit":  "abc123",                      (optional)
+    "source_package": "foo",                         (optional)
+    "exports":        [{"name":"fn","type":"def"}]   or list of strings
+    "dependencies":   ["a", "b"],                    (default [])
+    "compatibility":  ">=3.10",                      (optional, default "")
+    "language_hint":  null,                          (echoed verbatim)
+    "scope_hint":     null,                          (echoed verbatim)
+    "skf_version":    "1.2.0"                        (default "unknown")
+  }
+
+CLI:
+
+  python3 skf-render-quick-metadata.py < input.json
+
+Exit codes:
+
+  0   success
+  1   payload-level error (missing required field)
+  2   stdin / argparse / JSON-decode error
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+
+
+REQUIRED_FIELDS = ("name", "language", "source_repo")
+
+
+def _normalize_exports(raw) -> list[str]:
+    """Accept either a list of strings or a list of {name, type, ...} dicts.
+    Returns a flat list of export names in declaration order, deduplicated.
+    """
+    out: list[str] = []
+    seen: set[str] = set()
+    if not isinstance(raw, list):
+        return out
+    for item in raw:
+        name: str | None = None
+        if isinstance(item, str):
+            name = item
+        elif isinstance(item, dict):
+            v = item.get("name")
+            if isinstance(v, str):
+                name = v
+        if name and name not in seen:
+            seen.add(name)
+            out.append(name)
+    return out
+
+
+def _iso_utc_now() -> str:
+    """Returns 'YYYY-MM-DDTHH:MM:SSZ' for the current UTC instant."""
+    return dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def render_metadata(payload: dict, *, now_fn=_iso_utc_now) -> dict:
+    """Render the metadata.json envelope. Pass `now_fn` to inject a
+    deterministic timestamp in tests.
+    """
+    missing = [f for f in REQUIRED_FIELDS if not payload.get(f)]
+    if missing:
+        return {"_error": f"missing required field(s): {', '.join(missing)}"}
+
+    exports = _normalize_exports(payload.get("exports"))
+    export_count = len(exports)
+
+    metadata = {
+        "name": payload["name"],
+        "version": payload.get("version") or "1.0.0",
+        "description": payload.get("description") or "",
+        "skill_type": "single",
+        "source_authority": "community",
+        "source_repo": payload["source_repo"],
+        "source_root": payload.get("source_root") or "",
+        "source_commit": payload.get("source_commit") or "",
+        "source_package": payload.get("source_package") or payload["name"],
+        "language": payload["language"],
+        "generated_by": "quick-skill",
+        "generation_date": now_fn(),
+        "confidence_tier": "Quick",
+        "spec_version": "1.3",
+        "exports": exports,
+        "confidence_distribution": {
+            "t1": 0,
+            "t1_low": export_count,
+            "t2": 0,
+            "t3": 0,
+        },
+        "tool_versions": {
+            "ast_grep": None,
+            "qmd": None,
+            "skf": payload.get("skf_version") or "unknown",
+        },
+        "stats": {
+            "exports_documented": export_count,
+            "exports_public_api": export_count,
+            "exports_internal": 0,
+            "exports_total": export_count,
+            "public_api_coverage": 1.0,
+            "total_coverage": 1.0,
+            "scripts_count": 0,
+            "assets_count": 0,
+        },
+        "dependencies": payload.get("dependencies") or [],
+        "compatibility": payload.get("compatibility") or "",
+        "provenance": {
+            "language_hint": payload.get("language_hint"),
+            "scope_hint": payload.get("scope_hint"),
+        },
+    }
+    return metadata
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Render skf-quick-skill metadata.json from extracted state on stdin.",
+    )
+    parser.parse_args(argv)  # currently no flags; kept for forward compat
+
+    raw = sys.stdin.read()
+    if not raw.strip():
+        sys.stderr.write("error: no input on stdin (expected JSON payload)\n")
+        return 2
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as e:
+        sys.stderr.write(f"error: stdin JSON parse error: {e}\n")
+        return 2
+    if not isinstance(payload, dict):
+        sys.stderr.write("error: stdin payload must be a JSON object\n")
+        return 2
+
+    result = render_metadata(payload)
+    if "_error" in result:
+        sys.stderr.write(f"error: {result['_error']}\n")
+        return 1
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

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

@@ -0,0 +1,264 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Resolve Package — resolve a package name to a GitHub repository URL.
+
+Walks the canonical fallback chain documented in
+`src/skf-quick-skill/references/registry-resolution.md`:
+
+  1. npm registry        (JavaScript/TypeScript)
+  2. PyPI registry       (Python)
+  3. crates.io registry  (Rust)
+
+Per-call timeout (default 10s); a timeout is treated as a soft failure
+and the resolver falls through to the next entry. Web-search fallback
+is intentionally NOT in this helper — registries are deterministic;
+web search is judgment, and stays in the LLM step.
+
+CLI:
+
+  python3 skf-resolve-package.py <package_name> [--timeout 10]
+
+Output JSON (stdout):
+
+  status:           "ok" | "fallthrough"
+  package_name:     "<input>"
+  resolved_url:     "https://github.com/<owner>/<repo>"  (when status == "ok")
+  repo_owner:       "<owner>"                            (when status == "ok")
+  repo_name:        "<repo>"                             (when status == "ok")
+  registry_used:    "npm" | "pypi" | "crates"            (when status == "ok")
+  registries_tried: ["npm", ...]
+  registry_outcomes: {"npm": "ok|404|timeout|error|no-github-link", ...}
+
+Exit codes:
+
+  0  status == "ok"
+  1  status == "fallthrough" — every registry replied without a GitHub
+     URL; the LLM step should fall back to web search.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import socket
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Optional
+
+REGISTRY_TIMEOUT_SECONDS = 10.0
+USER_AGENT = "skf-resolve-package/1.0 (+https://github.com/armelhbobdad/bmad-module-skill-forge)"
+
+_GITHUB_URL_RE = re.compile(
+    r"https?://(?:www\.)?github\.com/([^/\s]+)/([^/\s.]+?)(?:\.git)?/?$",
+    re.IGNORECASE,
+)
+
+
+def parse_github_url(url: str) -> Optional[tuple[str, str, str]]:
+    """Parse a GitHub URL/string into (canonical_url, owner, repo).
+
+    Handles the variants registries actually emit:
+      - https://github.com/owner/repo
+      - http://github.com/owner/repo
+      - github.com/owner/repo
+      - git+https://github.com/owner/repo.git
+      - git@github.com:owner/repo.git
+      - github:owner/repo (npm shortcut)
+    """
+    if not url or not isinstance(url, str):
+        return None
+
+    s = url.strip()
+
+    if s.startswith("github:"):
+        rest = s[len("github:") :]
+        if "/" in rest:
+            owner, _, repo = rest.partition("/")
+            repo = repo.removesuffix(".git").rstrip("/")
+            if owner and repo:
+                return f"https://github.com/{owner}/{repo}", owner, repo
+        return None
+
+    if s.startswith("git+"):
+        s = s[len("git+") :]
+
+    if s.startswith("git@github.com:"):
+        rest = s[len("git@github.com:") :]
+        rest = rest.removesuffix(".git").rstrip("/")
+        if "/" in rest:
+            owner, _, repo = rest.partition("/")
+            if owner and repo:
+                return f"https://github.com/{owner}/{repo}", owner, repo
+        return None
+
+    if s.startswith("github.com/"):
+        s = "https://" + s
+
+    m = _GITHUB_URL_RE.match(s)
+    if m:
+        owner, repo = m.group(1), m.group(2)
+        return f"https://github.com/{owner}/{repo}", owner, repo
+
+    return None
+
+
+def _http_get_json(url: str, timeout: float) -> tuple[Optional[dict], str]:
+    """Fetch JSON. Returns (payload_or_None, outcome).
+
+    Outcome values:
+      "ok"       — valid JSON object returned
+      "404"      — HTTP 404 (package does not exist on this registry)
+      "timeout"  — socket / urlopen timed out
+      "error"    — any other transport / parse error
+    """
+    req = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": USER_AGENT})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+            if isinstance(payload, dict):
+                return payload, "ok"
+            return None, "error"
+    except urllib.error.HTTPError as e:
+        return None, "404" if e.code == 404 else "error"
+    except urllib.error.URLError as e:
+        if isinstance(getattr(e, "reason", None), (socket.timeout, TimeoutError)):
+            return None, "timeout"
+        return None, "error"
+    except (TimeoutError, socket.timeout):
+        return None, "timeout"
+    except (ValueError, json.JSONDecodeError):
+        return None, "error"
+
+
+def try_npm(package_name: str, timeout: float) -> tuple[Optional[tuple[str, str, str]], str]:
+    """Try the npm registry. Returns (parsed_or_None, outcome)."""
+    encoded = urllib.parse.quote(package_name, safe="@")
+    url = f"https://registry.npmjs.org/{encoded}"
+    payload, outcome = _http_get_json(url, timeout)
+    if payload is None:
+        return None, outcome
+    candidates: list[str] = []
+    repo = payload.get("repository")
+    if isinstance(repo, dict) and isinstance(repo.get("url"), str):
+        candidates.append(repo["url"])
+    elif isinstance(repo, str):
+        candidates.append(repo)
+    homepage = payload.get("homepage")
+    if isinstance(homepage, str):
+        candidates.append(homepage)
+    for c in candidates:
+        parsed = parse_github_url(c)
+        if parsed:
+            return parsed, "ok"
+    return None, "no-github-link"
+
+
+def try_pypi(package_name: str, timeout: float) -> tuple[Optional[tuple[str, str, str]], str]:
+    """Try the PyPI registry. Returns (parsed_or_None, outcome)."""
+    encoded = urllib.parse.quote(package_name, safe="")
+    url = f"https://pypi.org/pypi/{encoded}/json"
+    payload, outcome = _http_get_json(url, timeout)
+    if payload is None:
+        return None, outcome
+    info = payload.get("info") or {}
+    candidates: list[str] = []
+    project_urls = info.get("project_urls") or {}
+    if isinstance(project_urls, dict):
+        for key in ("Source", "Source Code", "Repository", "Homepage"):
+            v = project_urls.get(key)
+            if isinstance(v, str):
+                candidates.append(v)
+    home_page = info.get("home_page")
+    if isinstance(home_page, str):
+        candidates.append(home_page)
+    for c in candidates:
+        parsed = parse_github_url(c)
+        if parsed:
+            return parsed, "ok"
+    return None, "no-github-link"
+
+
+def try_crates(package_name: str, timeout: float) -> tuple[Optional[tuple[str, str, str]], str]:
+    """Try the crates.io registry. Returns (parsed_or_None, outcome)."""
+    encoded = urllib.parse.quote(package_name, safe="")
+    url = f"https://crates.io/api/v1/crates/{encoded}"
+    payload, outcome = _http_get_json(url, timeout)
+    if payload is None:
+        return None, outcome
+    crate = payload.get("crate") or {}
+    for key in ("repository", "homepage"):
+        v = crate.get(key)
+        if isinstance(v, str):
+            parsed = parse_github_url(v)
+            if parsed:
+                return parsed, "ok"
+    return None, "no-github-link"
+
+
+_RESOLVER_NAMES: tuple[tuple[str, str], ...] = (
+    ("npm", "try_npm"),
+    ("pypi", "try_pypi"),
+    ("crates", "try_crates"),
+)
+
+
+def resolve_package(package_name: str, timeout: float = REGISTRY_TIMEOUT_SECONDS) -> dict:
+    registries_tried: list[str] = []
+    outcomes: dict[str, str] = {}
+
+    # Dynamic lookup so test code can monkeypatch try_npm / try_pypi / try_crates
+    # without re-binding entries in a module-level tuple of function refs.
+    for name, fn_name in _RESOLVER_NAMES:
+        registries_tried.append(name)
+        fn = globals()[fn_name]
+        result, outcome = fn(package_name, timeout)
+        outcomes[name] = outcome
+        if result is not None:
+            url, owner, repo = result
+            return {
+                "status": "ok",
+                "package_name": package_name,
+                "resolved_url": url,
+                "repo_owner": owner,
+                "repo_name": repo,
+                "registry_used": name,
+                "registries_tried": registries_tried,
+                "registry_outcomes": outcomes,
+            }
+
+    return {
+        "status": "fallthrough",
+        "package_name": package_name,
+        "registries_tried": registries_tried,
+        "registry_outcomes": outcomes,
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Resolve a package name to a GitHub repository URL via npm/PyPI/crates.io.",
+    )
+    parser.add_argument(
+        "package_name",
+        help="Package name to resolve (e.g., lodash, @tanstack/query, requests, serde).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=REGISTRY_TIMEOUT_SECONDS,
+        help=f"Per-registry timeout in seconds (default: {REGISTRY_TIMEOUT_SECONDS}).",
+    )
+    args = parser.parse_args(argv)
+
+    result = resolve_package(args.package_name, timeout=args.timeout)
+    print(json.dumps(result, indent=2))
+    return 0 if result["status"] == "ok" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/src/shared/scripts/skf-validate-frontmatter.py

@@ -11,9 +11,15 @@ agentskills/agentskills/skills-ref/src/skills_ref/validator.py.
 Designed for pre-check use in test-skill, create-skill, update-skill, and
 export-skill workflows. Returns structured JSON for deterministic integration.
 
-CLI:
-  python3 skf-validate-frontmatter.py <skill-md-path>
-  python3 skf-validate-frontmatter.py <skill-md-path> --skill-dir-name <name>
+CLI — invoke via `uv run` so the PEP 723 PyYAML dependency declared
+above is auto-resolved on first call and cached. `docs/getting-started.md`
+documents uv as the runtime prerequisite for exactly this. Bare
+`python3` will fail with `ModuleNotFoundError: No module named 'yaml'`
+on a fresh interpreter where pyyaml has not been pip-installed
+system-wide:
+
+  uv run skf-validate-frontmatter.py <skill-md-path>
+  uv run skf-validate-frontmatter.py <skill-md-path> --skill-dir-name <name>
 
 Input:
   Path to a SKILL.md file.

package/src/shared/scripts/skf-validate-output.py

@@ -9,6 +9,7 @@ schema against agentskills.io specification. Outputs JSON validation results.
 
 CLI: python3 skf-validate-output.py <skill-package-dir>
      python3 skf-validate-output.py <skill-package-dir> --generated-by quick-skill
+     python3 skf-validate-output.py <skill-package-dir> --skip-frontmatter
 """
 
 from __future__ import annotations
@@ -73,7 +74,7 @@ def validate_body_structure(content):
     issues = []
     body = content.split("---", 2)[-1] if content.startswith("---") else content
 
-    required_sections = ["Overview", "Key Exports", "Usage"]
+    required_sections = ["Overview", "Description", "Key Exports", "Usage"]
     for section in required_sections:
         pattern = rf"^##\s+.*{re.escape(section)}"
         if not re.search(pattern, body, re.MULTILINE | re.IGNORECASE):
@@ -155,8 +156,13 @@ def validate_metadata_json(data, generated_by=None):
     return issues
 
 
-def validate_skill_package(skill_dir, generated_by=None):
-    """Validate a complete skill package directory."""
+def validate_skill_package(skill_dir, generated_by=None, skip_frontmatter=False):
+    """Validate a complete skill package directory.
+
+    When `skip_frontmatter` is True, the SKILL.md frontmatter pass is omitted —
+    intended for callers that already validated frontmatter via skill-check or
+    skf-validate-frontmatter.py and only want body / snippet / metadata checks.
+    """
     skill_dir = Path(skill_dir)
     skill_name = skill_dir.name
 
@@ -183,9 +189,14 @@ def validate_skill_package(skill_dir, generated_by=None):
     skill_md_path = files["SKILL.md"]
     if skill_md_path.exists():
         content = skill_md_path.read_text(encoding="utf-8")
-        fm_issues = validate_frontmatter(content, skill_name)
+        if skip_frontmatter:
+            fm_section = {"skipped": "frontmatter validation skipped (--skip-frontmatter)"}
+            fm_issues = []
+        else:
+            fm_issues = validate_frontmatter(content, skill_name)
+            fm_section = fm_issues
         body_issues = validate_body_structure(content)
-        result["validation"]["skill_md"] = {"frontmatter": fm_issues, "body": body_issues}
+        result["validation"]["skill_md"] = {"frontmatter": fm_section, "body": body_issues}
         for issue in fm_issues + body_issues:
             result["summary"]["total_issues"] += 1
             result["summary"]["by_severity"][issue["severity"]] += 1
@@ -232,7 +243,11 @@ def validate_skill_package(skill_dir, generated_by=None):
 
 if __name__ == "__main__":
     if len(sys.argv) < 2:
-        print("Usage: python3 skf-validate-output.py <skill-package-dir> [--generated-by <generator>]", file=sys.stderr)
+        print(
+            "Usage: python3 skf-validate-output.py <skill-package-dir> "
+            "[--generated-by <generator>] [--skip-frontmatter]",
+            file=sys.stderr,
+        )
         sys.exit(1)
 
     pkg_dir = sys.argv[1]
@@ -242,6 +257,8 @@ if __name__ == "__main__":
         if idx + 1 < len(sys.argv):
             gen_by = sys.argv[idx + 1]
 
-    result = validate_skill_package(pkg_dir, generated_by=gen_by)
+    skip_fm = "--skip-frontmatter" in sys.argv
+
+    result = validate_skill_package(pkg_dir, generated_by=gen_by, skip_frontmatter=skip_fm)
     print(json.dumps(result, indent=2))
     sys.exit(0 if result["result"] == "PASS" else 1)

package/src/skf-create-skill/steps-c/step-06-validate.md

@@ -40,7 +40,7 @@ To prevent this, any tool invocation that may touch SKILL.md must run inside the
 2. **Execute.** Run the tool as specified in its section.
 3. **Verify.** After the tool completes, re-read the on-disk SKILL.md and compare its frontmatter `description` against `guarded_description` as **token streams**: split each string on whitespace (`str.split()` — any run of spaces/tabs/newlines collapses) and compare the resulting lists element-by-element. This catches content divergence (missing words, replaced phrases, truncation, angle-bracket re-introduction) while ignoring cosmetic whitespace changes that a tool may apply (trailing newline, re-wrapped quoted strings). Do NOT use a normalized-string equality — a tool that rewrites `"foo  bar"` to `"foo bar"` (collapsed inner run) would trip a naive normalization even though no semantic content changed, and a tool that swapped one word would slip past a looser fuzzy match. Token-stream comparison is the sweet spot.
 4. **Restore on divergence.** If the post-tool description differs from `guarded_description` in any way other than whitespace normalization, write `guarded_description` back to the on-disk SKILL.md frontmatter and update the in-context copy to match. Record `description_guard_restored: true` with the tool name in context for the evidence report.
-5. **Re-validate restored description.** After a restore, run `python3 {project-root}/src/shared/scripts/skf-validate-frontmatter.py <staging-skill-dir>/SKILL.md` against the on-disk file to confirm the restored description still satisfies the frontmatter contract (length limits, forbidden tokens, required fields). Capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field: flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step-09 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
+5. **Re-validate restored description.** After a restore, run `uv run {project-root}/src/shared/scripts/skf-validate-frontmatter.py <staging-skill-dir>/SKILL.md` against the on-disk file to confirm the restored description still satisfies the frontmatter contract (length limits, forbidden tokens, required fields). The script declares pyyaml in its PEP 723 inline metadata; `uv run` resolves it automatically (per `docs/getting-started.md`'s uv prereq), while bare `python3` would `ModuleNotFoundError` on a fresh interpreter. Capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field: flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step-09 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
 
 **What counts as divergence:**