bmad-module-skill-forge 1.2.0 → 1.4.0

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-brief-inputs.py

@@ -0,0 +1,293 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Validate Brief Inputs — pre-pass validation for brief-skill headless invocation.
+
+Validates and normalizes the headless argument set passed to skf-brief-skill
+before the workflow's interactive sequence runs. Catches malformed inputs at
+point of capture instead of letting them surface 5+ minutes later in step-02
+or step-05.
+
+CLI:
+  uv run skf-validate-brief-inputs.py --json '{...}'
+  echo '{...}' | uv run skf-validate-brief-inputs.py
+
+Input (JSON object on stdin or via --json):
+  Required:
+    target_repo  — string (URL or path); error if absent
+    skill_name   — string (kebab-case); error if absent or malformed
+
+  Optional with enum constraints:
+    source_type      — "source" | "docs-only" (default "source")
+    source_authority — "official" | "community" | "internal" (default "community")
+    scope_type       — "full-library" | "specific-modules" | "public-api"
+                       | "component-library" | "reference-app" | "docs-only"
+    scripts_intent   — "detect" | "none" | free-text (default "detect")
+    assets_intent    — "detect" | "none" | free-text (default "detect")
+
+  Optional with format constraints:
+    target_version — loose semver string (matches 1.2.3, 1.2.3-rc.1, 1.2.3+build.5)
+
+  Conditional:
+    doc_urls — required when source_type == "docs-only"
+
+  Free-text / pass-through:
+    scope_hint, language_hint, intent, include, exclude, force
+
+  Unrecognized keys are passed through unchanged but flagged as warnings.
+
+Output (JSON on stdout):
+  {
+    "valid": bool,
+    "errors":   [{"field": "...", "message": "..."}, ...],
+    "warnings": [{"field": "...", "message": "..."}, ...],
+    "normalized": { ...input dict with defaults applied... },
+    "halt_reason": "input-missing" | "input-invalid" | null
+  }
+
+Exit codes:
+  0 — valid (errors empty)
+  1 — invalid (errors present); halt_reason is set
+  2 — internal error (bad JSON input, IO failure)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from typing import Any
+
+KNOWN_FIELDS = {
+    "target_repo",
+    "skill_name",
+    "source_type",
+    "source_authority",
+    "scope_type",
+    "target_version",
+    "doc_urls",
+    "scope_hint",
+    "language_hint",
+    "intent",
+    "scripts_intent",
+    "assets_intent",
+    "include",
+    "exclude",
+    "force",
+}
+# `preset` is intentionally NOT in KNOWN_FIELDS — it is consumed at the step-01 §8 GATE
+# (the LLM merges the named preset YAML into the args dict and drops the `preset` key
+# before calling the validator). If the key leaks through, the validator's existing
+# unknown-field handling emits `"unrecognized field 'preset' — passed through unchanged"`
+# in `warnings[]` so the missed drop is debuggable rather than silent.
+
+VALID_SOURCE_TYPES = {"source", "docs-only"}
+VALID_SOURCE_AUTHORITIES = {"official", "community", "internal"}
+VALID_SCOPE_TYPES = {
+    "full-library",
+    "specific-modules",
+    "public-api",
+    "component-library",
+    "reference-app",
+    "docs-only",
+}
+
+KEBAB_RE = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+# Require full X.Y.Z form (with optional v prefix and pre-release/build suffix).
+# Loose forms like `1`, `1.2`, `v2` are rejected — the user should write the
+# explicit triple. CalVer (e.g. 2024.04.01) is accepted because it satisfies
+# the X.Y.Z shape.
+SEMVER_RE = re.compile(
+    r"^v?\d+\.\d+\.\d+([.\-+][0-9A-Za-z][0-9A-Za-z.\-+]*)?$"
+)
+URL_RE = re.compile(r"^https?://", re.IGNORECASE)
+
+
+def _err(field: str, message: str) -> dict[str, str]:
+    return {"field": field, "message": message}
+
+
+def validate(inp: dict[str, Any]) -> dict[str, Any]:
+    errors: list[dict[str, str]] = []
+    warnings: list[dict[str, str]] = []
+
+    # Required: target_repo, skill_name
+    target_repo = inp.get("target_repo")
+    skill_name = inp.get("skill_name")
+    if not target_repo:
+        errors.append(_err("target_repo", "missing required argument target_repo"))
+    if not skill_name:
+        errors.append(_err("skill_name", "missing required argument skill_name"))
+
+    # skill_name format
+    if skill_name and isinstance(skill_name, str) and not KEBAB_RE.match(skill_name):
+        errors.append(
+            _err(
+                "skill_name",
+                f"skill_name must be kebab-case (lowercase letters/digits/hyphens, "
+                f"no leading or trailing hyphen). Got: {skill_name!r}",
+            )
+        )
+
+    # source_type enum
+    source_type_raw = inp.get("source_type", "source")
+    if source_type_raw not in VALID_SOURCE_TYPES:
+        errors.append(
+            _err(
+                "source_type",
+                f"source_type must be one of {sorted(VALID_SOURCE_TYPES)}. Got: {source_type_raw!r}",
+            )
+        )
+        # Treat as default for downstream conditional logic
+        source_type = "source"
+    else:
+        source_type = source_type_raw
+
+    # source_authority enum
+    source_authority_raw = inp.get("source_authority", "community")
+    if source_authority_raw not in VALID_SOURCE_AUTHORITIES:
+        errors.append(
+            _err(
+                "source_authority",
+                f"source_authority must be one of {sorted(VALID_SOURCE_AUTHORITIES)}. "
+                f"Got: {source_authority_raw!r}",
+            )
+        )
+
+    # scope_type enum (when present)
+    scope_type = inp.get("scope_type")
+    if scope_type is not None and scope_type not in VALID_SCOPE_TYPES:
+        errors.append(
+            _err(
+                "scope_type",
+                f"scope_type must be one of {sorted(VALID_SCOPE_TYPES)}. Got: {scope_type!r}",
+            )
+        )
+
+    # target_version semver-ish
+    target_version = inp.get("target_version")
+    if target_version is not None:
+        if not isinstance(target_version, str):
+            errors.append(
+                _err(
+                    "target_version",
+                    f"target_version must be a string. Got type {type(target_version).__name__}",
+                )
+            )
+        elif not SEMVER_RE.match(target_version):
+            errors.append(
+                _err(
+                    "target_version",
+                    f"target_version does not look like semver. Got: {target_version!r}. "
+                    f"Expected forms: 1.2.3, v1.2.3, 1.2.3-rc.1, 1.2.3+build.5. "
+                    f"Partial forms like '1' or '1.2' are not accepted — write the explicit triple.",
+                )
+            )
+
+    # docs-only requires doc_urls
+    doc_urls = inp.get("doc_urls")
+    if source_type == "docs-only" and not doc_urls:
+        errors.append(
+            _err("doc_urls", "doc_urls is required when source_type is docs-only")
+        )
+
+    # target_repo shape (warning only — script doesn't HEAD-check)
+    if isinstance(target_repo, str) and target_repo:
+        looks_like_url = URL_RE.match(target_repo) is not None
+        looks_like_path = (
+            target_repo.startswith("/")
+            or target_repo.startswith("./")
+            or target_repo.startswith("~")
+        )
+        if not (looks_like_url or looks_like_path):
+            warnings.append(
+                _err(
+                    "target_repo",
+                    f"target_repo does not look like a URL or absolute/relative path: {target_repo!r}",
+                )
+            )
+
+    # Unknown fields → warn
+    for key in inp:
+        if key not in KNOWN_FIELDS:
+            warnings.append(_err(key, f"unrecognized field {key!r} — passed through unchanged"))
+
+    # Build normalized payload
+    normalized: dict[str, Any] = dict(inp)
+    normalized.setdefault("source_type", "source")
+    # `source_authority` is intentionally NOT setdefault'd here for source-type targets:
+    # step-01 §3.3's headless detection branch runs `gh api user` and may resolve to
+    # `official` for repos owned by the authenticated user. Stamping a default at
+    # validator time would pre-empt the detection because step-01 §8 GATE treats the
+    # `normalized` object as the source of truth. Absence is the signal "run detection."
+    # The docs-only branch below still forces `community` since detection cannot apply.
+    normalized.setdefault("scripts_intent", "detect")
+    normalized.setdefault("assets_intent", "detect")
+
+    # Force community when docs-only
+    if normalized.get("source_type") == "docs-only":
+        if normalized.get("source_authority") not in (None, "community"):
+            warnings.append(
+                _err(
+                    "source_authority",
+                    f"source_authority forced to 'community' because source_type=docs-only "
+                    f"(was {normalized['source_authority']!r})",
+                )
+            )
+        normalized["source_authority"] = "community"
+
+    # halt_reason classification
+    if errors:
+        missing_required = any(
+            e["message"].startswith("missing required") or "is required" in e["message"]
+            for e in errors
+        )
+        halt_reason = "input-missing" if missing_required else "input-invalid"
+    else:
+        halt_reason = None
+
+    return {
+        "valid": not errors,
+        "errors": errors,
+        "warnings": warnings,
+        "normalized": normalized,
+        "halt_reason": halt_reason,
+    }
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(prog="skf-validate-brief-inputs")
+    p.add_argument(
+        "--json",
+        help="JSON object as a string. If omitted, the script reads JSON from stdin.",
+    )
+    args = p.parse_args()
+
+    raw = args.json
+    if raw is None:
+        raw = sys.stdin.read()
+
+    if not raw or not raw.strip():
+        sys.stderr.write("skf-validate-brief-inputs: empty input\n")
+        return 2
+
+    try:
+        inp = json.loads(raw)
+    except json.JSONDecodeError as e:
+        sys.stderr.write(f"skf-validate-brief-inputs: invalid JSON input: {e}\n")
+        return 2
+
+    if not isinstance(inp, dict):
+        sys.stderr.write("skf-validate-brief-inputs: input must be a JSON object\n")
+        return 2
+
+    result = validate(inp)
+    json.dump(result, sys.stdout, indent=2, sort_keys=True)
+    sys.stdout.write("\n")
+    return 0 if result["valid"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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)