bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/shared/scripts/skf-hash-content.py

@@ -19,6 +19,17 @@ Two patterns recur across the update-skill workflow's stage prose:
      iterated, plus a stat-and-compare. NEW_FILE detection is intentionally
      out of scope here — that lives in `skf-detect-scripts-assets.py`.
 
+  3. **[MANUAL]-section integrity** — the update-skill workflow's headline
+     Workflow Rule is "[MANUAL] sections survive regeneration with zero
+     content loss." init.md §5 captures a pre-write inventory of every
+     `<!-- [MANUAL:name] --> … <!-- [/MANUAL:name] -->` block; write.md §1
+     (HALT gate) and validate.md Check B verify the post-merge SKILL.md
+     against it. Doing that by an LLM marker-count + eyeball can silently
+     pass a block whose interior was truncated (marker count unchanged).
+     The `manual-inventory` / `manual-verify` subcommands extract each block
+     by marker regex, hash its byte-exact interior, and emit an exact
+     {preserved, modified, missing, moved, ok} verdict.
+
 Subcommands:
   hash <path> [--include-path]
       Emit JSON {"content_hash": "sha256:...", "size_bytes": N, "line_count": L}
@@ -40,6 +51,69 @@ Subcommands:
       The provenance file must contain `file_entries` as a top-level array
       OR be the array itself (handles both schemas).
 
+  manual-inventory <skill-md>
+      Extract every `<!-- [MANUAL:name] --> … <!-- [/MANUAL:name] -->` block
+      and emit
+        {
+          "blocks": [
+            {"name": "...", "content_hash": "sha256:...",
+             "byte_offset": N, "parent_heading": "..."|null}, ...
+          ],
+          "count": N
+        }
+      `content_hash` is the SHA-256 of the block's byte-exact interior (the
+      bytes between the open marker's `-->` and the close marker's `<!--`,
+      including surrounding newlines — zero normalization). `byte_offset` is
+      the byte position of the opening marker; `parent_heading` is the text
+      of the nearest preceding Markdown heading (or null). Blocks are sorted
+      by `byte_offset`. Persist this JSON as the captured pre-write inventory.
+
+  manual-verify --inventory <inventory.json> <skill-md>
+      Re-extract the blocks from the (post-merge) on-disk file and classify
+      each inventory block by name + hash + parent heading:
+        - name present, hash matches, same parent heading  → preserved
+        - name present, hash matches, parent heading changed → moved
+        - name present, hash differs                        → modified
+        - name absent                                       → missing
+      Emits {"preserved":[names], "modified":[names], "missing":[names],
+      "moved":[names], "ok": bool} where `ok = (modified empty AND missing
+      empty)`. A `moved` block does NOT fail the verdict — a byte-identical
+      block relocated with its logical parent section is a clean outcome.
+      The inventory may be the object emitted by `manual-inventory` OR a bare
+      `blocks[]` array (handles both shapes).
+
+  compare-constituent-hashes <provenance-map.json> [--skills-root <root>]
+      Constituent-drift detection for compose-mode stack skills. Replaces the
+      per-constituent read + SHA-256 + compare loop at
+      `src/skf-audit-skill/references/init.md` (Stack Skill Detection). Reads
+      the `constituents[]` array from a compose-mode provenance map (each
+      entry carrying `skill_name`, `skill_path`, and the compile-time
+      `metadata_hash`), reads each constituent's live
+      `{skill_path}/active/{skill_name}/metadata.json`, recomputes its
+      SHA-256 with the same `sha256:` prefix convention the writer used
+      (`skf-enumerate-stack-skills._sha256_of_bytes`), and buckets each
+      constituent:
+        {
+          "drifted":  [{"skill_name","skill_path","stored_hash","current_hash"}],
+          "fresh":    [{"skill_name"}],
+          "missing":  [{"skill_name","skill_path","stored_hash","reason"}],
+          "skipped_null_hash": [{"skill_name"}],
+          "stats": {"total":N,"drifted":N,"fresh":N,"missing":N,
+                    "skipped_null_hash":N}
+        }
+      `drifted` is the audit's HIGH-severity constituent-drift signal (the
+      live metadata.json differs from the compile-time snapshot). `missing`
+      carries a `reason` (`"metadata-not-found"` when the file is absent on
+      disk, `"incomplete-record"` when the provenance entry lacks
+      skill_name/skill_path). `skipped_null_hash` holds constituents whose
+      stored `metadata_hash` was null (recorded from a references/ cascade —
+      no baseline to compare against, so never reported as drift). Relative
+      `skill_path` values resolve against `--skills-root` (default: current
+      directory); absolute `skill_path` values are used as-is. A provenance
+      map with no `constituents` field (a single skill) yields all-empty
+      buckets. Stored hashes are prefix-normalized before comparison so a
+      bare-hex writer form still matches. Buckets are sorted by skill_name.
+
 Hash format: `sha256:` prefix on a hex digest. Matches the convention used
 by skf-detect-scripts-assets.py and the existing prose ("SHA-256 content
 hash" — agnostic about prefix, but the prefix is the SKF convention to make
@@ -50,10 +124,14 @@ CLI examples:
   uv run skf-hash-content.py hash docs/AGENTS.md --include-path
   uv run skf-hash-content.py compare /path/to/source \\
       --provenance-map /path/to/provenance-map.json
+  uv run skf-hash-content.py manual-inventory SKILL.md
+  uv run skf-hash-content.py manual-verify --inventory inventory.json SKILL.md
 
 Exit codes:
-  0  — operation succeeded (including: file in compare missing on disk;
-       its classification is DELETED_FILE, not an error)
+  0  — operation succeeded (including: file in compare missing on disk, its
+       classification is DELETED_FILE; and manual-verify completing with
+       ok=false — an integrity failure is a *result*, read from the `ok`
+       field, not an operation error)
   1  — user error (bad path, malformed JSON, missing required field)
 """
 
@@ -62,6 +140,7 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
+import re
 import sys
 from pathlib import Path
 
@@ -104,6 +183,21 @@ def hash_record(path: Path, *, include_path: bool = False) -> dict:
     return rec
 
 
+_HASH_PREFIX_RE = re.compile(r"^[a-z0-9]+:")
+
+
+def normalize_hash(value: str | None) -> str | None:
+    """Strip a leading algorithm-name prefix (`sha256:`, `sha1:`, …) from a
+    stored hash so bare-hex and prefixed forms compare equal.
+
+    Mirrors skf-compare-file-hashes.normalize_hash. Returns None for a
+    non-string input; idempotent on bare hex.
+    """
+    if not isinstance(value, str):
+        return None
+    return _HASH_PREFIX_RE.sub("", value, count=1)
+
+
 # --------------------------------------------------------------------------
 # Provenance comparison
 # --------------------------------------------------------------------------
@@ -208,6 +302,314 @@ def compare(source_root: Path, provenance_path: Path) -> dict:
     }
 
 
+# --------------------------------------------------------------------------
+# [MANUAL]-section integrity
+# --------------------------------------------------------------------------
+
+
+# Open marker:  <!-- [MANUAL:name] -->      (whitespace-tolerant)
+# Close marker: <!-- [/MANUAL:name] -->     (note the leading slash)
+# The open pattern cannot match a close marker: after `<!--` it requires
+# `[MANUAL` with no slash, whereas a close has `[/MANUAL`.
+_OPEN_RE = re.compile(rb"<!--\s*\[MANUAL:([^\]]+)\]\s*-->")
+_CLOSE_RE = re.compile(rb"<!--\s*\[/MANUAL:([^\]]+)\]\s*-->")
+_HEADING_RE = re.compile(rb"^(#{1,6})[ \t]+(.*)$")
+
+
+def sha256_of_bytes(data: bytes) -> str:
+    """SHA-256 of an in-memory byte string, with sha256: prefix."""
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _parent_heading(data: bytes, offset: int) -> str | None:
+    """Text of the nearest Markdown heading preceding `offset` (or None).
+
+    Returns the heading text with leading `#` markers and surrounding
+    whitespace stripped — e.g. b"## Usage Patterns\\n" -> "Usage Patterns".
+    """
+    heading: str | None = None
+    for line in data[:offset].split(b"\n"):
+        m = _HEADING_RE.match(line)
+        if m:
+            heading = m.group(2).strip().decode("utf-8", errors="replace")
+    return heading
+
+
+def find_manual_blocks(data: bytes) -> list[dict]:
+    """Extract every well-formed [MANUAL] block from `data`.
+
+    A block is an opening `<!-- [MANUAL:name] -->` paired with the *earliest*
+    following `<!-- [/MANUAL:name] -->` of the same (whitespace-stripped)
+    name. `content_hash` covers the byte-exact interior — the bytes between
+    the open marker's `-->` and the close marker's `<!--`, with zero
+    normalization, so any interior edit (including an equal-marker-count
+    truncation) changes the hash.
+
+    An opening marker with no matching close is malformed and skipped.
+    Result is sorted by `byte_offset` for deterministic ordering.
+    """
+    closes = [
+        (m.start(), m.group(1).decode("utf-8", errors="replace").strip())
+        for m in _CLOSE_RE.finditer(data)
+    ]
+    blocks: list[dict] = []
+    for om in _OPEN_RE.finditer(data):
+        name = om.group(1).decode("utf-8", errors="replace").strip()
+        open_end = om.end()
+        close_start = None
+        for c_start, c_name in closes:
+            if c_start >= open_end and c_name == name:
+                if close_start is None or c_start < close_start:
+                    close_start = c_start
+        if close_start is None:
+            continue  # unclosed opening marker — malformed, skip
+        content = data[open_end:close_start]
+        blocks.append({
+            "name": name,
+            "content_hash": sha256_of_bytes(content),
+            "byte_offset": om.start(),
+            "parent_heading": _parent_heading(data, om.start()),
+        })
+    blocks.sort(key=lambda b: b["byte_offset"])
+    return blocks
+
+
+def classify_manual_blocks(inv_blocks: list[dict], cur_blocks: list[dict]) -> dict:
+    """Classify each inventory block against the current on-disk blocks.
+
+    Buckets are mutually exclusive per inventory block:
+      - missing:   name not present in the current file
+      - modified:  name present but no current block's hash matches
+      - preserved: a current block matches name + hash + parent_heading
+      - moved:     a current block matches name + hash but parent_heading
+                   changed (relocated with its logical section — clean)
+
+    `ok = (modified empty AND missing empty)`; `moved` does not fail it.
+    """
+    from collections import defaultdict
+
+    cur_by_name: dict[str, list[dict]] = defaultdict(list)
+    for b in cur_blocks:
+        cur_by_name[b["name"]].append(b)
+
+    preserved: list[str] = []
+    modified: list[str] = []
+    missing: list[str] = []
+    moved: list[str] = []
+
+    for inv in inv_blocks:
+        name = inv.get("name")
+        candidates = cur_by_name.get(name, [])
+        if not candidates:
+            missing.append(name)
+            continue
+        hash_matches = [c for c in candidates if c["content_hash"] == inv.get("content_hash")]
+        if not hash_matches:
+            modified.append(name)
+            continue
+        if any(c.get("parent_heading") == inv.get("parent_heading") for c in hash_matches):
+            preserved.append(name)
+        else:
+            moved.append(name)
+
+    return {
+        "preserved": preserved,
+        "modified": modified,
+        "missing": missing,
+        "moved": moved,
+        "ok": not modified and not missing,
+    }
+
+
+def manual_inventory(path: Path) -> dict:
+    """Build the [MANUAL] inventory for a file: {blocks[], count}."""
+    data = path.read_bytes()
+    blocks = find_manual_blocks(data)
+    return {"blocks": blocks, "count": len(blocks)}
+
+
+def load_inventory_blocks(inventory_path: Path) -> list[dict]:
+    """Read the blocks[] list from a manual-inventory JSON file.
+
+    Accepts the object emitted by `manual_inventory` (has a `blocks` key)
+    OR a bare list of block records. Raises ValueError on malformed input.
+    """
+    try:
+        data = json.loads(inventory_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise ValueError(
+            f"failed to read inventory file {inventory_path}: {exc}"
+        ) from exc
+    if isinstance(data, list):
+        return list(data)
+    if isinstance(data, dict):
+        blocks = data.get("blocks")
+        if blocks is None:
+            raise ValueError(
+                f"inventory file {inventory_path} has no `blocks` field"
+            )
+        if not isinstance(blocks, list):
+            raise ValueError(
+                f"`blocks` in {inventory_path} is not an array"
+            )
+        return list(blocks)
+    raise ValueError(
+        f"inventory file {inventory_path} must be an object or array; "
+        f"got {type(data).__name__}"
+    )
+
+
+def manual_verify(inventory_path: Path, skill_md_path: Path) -> dict:
+    """Verify a post-merge file against a captured [MANUAL] inventory."""
+    inv_blocks = load_inventory_blocks(inventory_path)
+    cur_blocks = find_manual_blocks(skill_md_path.read_bytes())
+    return classify_manual_blocks(inv_blocks, cur_blocks)
+
+
+# --------------------------------------------------------------------------
+# Constituent-hash comparison (compose-mode stack drift)
+# --------------------------------------------------------------------------
+
+
+def load_constituents(provenance_path: Path) -> list[dict]:
+    """Extract the `constituents[]` list from a compose-mode provenance map.
+
+    Accepts three shapes:
+      - top-level object with a `constituents` key (canonical provenance map)
+      - top-level object with NO `constituents` field → empty list (a single
+        skill omits the array entirely per skill-sections.md — valid, no drift)
+      - top-level array of constituent records (already extracted)
+
+    Raises ValueError on read failure, malformed JSON, or a non-array
+    `constituents` field.
+    """
+    try:
+        text = provenance_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(
+            f"failed to read provenance file {provenance_path}: {exc}"
+        ) from exc
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"malformed JSON in provenance file {provenance_path}: {exc}"
+        ) from exc
+
+    if isinstance(data, list):
+        return list(data)
+    if isinstance(data, dict):
+        constituents = data.get("constituents")
+        if constituents is None:
+            return []  # single skill — no constituents to verify
+        if not isinstance(constituents, list):
+            raise ValueError(
+                f"`constituents` in {provenance_path} is not an array"
+            )
+        return list(constituents)
+    raise ValueError(
+        f"provenance file {provenance_path} must be an object or array; "
+        f"got {type(data).__name__}"
+    )
+
+
+def _constituent_metadata_path(skills_root: Path, skill_path: str, skill_name: str) -> Path:
+    """Resolve a constituent's live metadata.json path.
+
+    Mirrors init.md's Stack Skill Detection prose:
+    `{skill_path}/active/{skill_name}/metadata.json`. A relative `skill_path`
+    resolves against `skills_root`; an absolute one is used as-is.
+    """
+    base = Path(skill_path)
+    if not base.is_absolute():
+        base = skills_root / base
+    return base / "active" / skill_name / "metadata.json"
+
+
+def compare_constituents(provenance_path: Path, skills_root: Path) -> dict:
+    """Classify each compose-mode constituent as drifted / fresh / missing.
+
+    For each constituent, the live `metadata.json` is re-hashed with the same
+    `sha256:`-prefixed convention the writer used and compared (prefix-
+    normalized) against the compile-time `metadata_hash`.
+    """
+    constituents = load_constituents(provenance_path)
+
+    drifted: list[dict] = []
+    fresh: list[dict] = []
+    missing: list[dict] = []
+    skipped_null_hash: list[dict] = []
+
+    for entry in constituents:
+        if not isinstance(entry, dict):
+            missing.append({
+                "skill_name": None,
+                "skill_path": None,
+                "stored_hash": None,
+                "reason": "incomplete-record",
+            })
+            continue
+        skill_name = entry.get("skill_name")
+        skill_path = entry.get("skill_path")
+        stored_hash = entry.get("metadata_hash")
+
+        if not isinstance(skill_name, str) or not skill_name or \
+                not isinstance(skill_path, str) or not skill_path:
+            missing.append({
+                "skill_name": skill_name if isinstance(skill_name, str) else None,
+                "skill_path": skill_path if isinstance(skill_path, str) else None,
+                "stored_hash": stored_hash if isinstance(stored_hash, str) else None,
+                "reason": "incomplete-record",
+            })
+            continue
+
+        if not isinstance(stored_hash, str) or not stored_hash:
+            # No compile-time baseline (recorded from a references/ cascade) —
+            # cannot be drift; do not flag.
+            skipped_null_hash.append({"skill_name": skill_name})
+            continue
+
+        meta_path = _constituent_metadata_path(skills_root, skill_path, skill_name)
+        if not meta_path.is_file():
+            missing.append({
+                "skill_name": skill_name,
+                "skill_path": skill_path,
+                "stored_hash": stored_hash,
+                "reason": "metadata-not-found",
+            })
+            continue
+
+        current_hash = sha256_of_file(meta_path)
+        if normalize_hash(stored_hash) == normalize_hash(current_hash):
+            fresh.append({"skill_name": skill_name})
+        else:
+            drifted.append({
+                "skill_name": skill_name,
+                "skill_path": skill_path,
+                "stored_hash": stored_hash,
+                "current_hash": current_hash,
+            })
+
+    drifted.sort(key=lambda r: (r.get("skill_name") or ""))
+    fresh.sort(key=lambda r: (r.get("skill_name") or ""))
+    missing.sort(key=lambda r: (r.get("skill_name") or ""))
+    skipped_null_hash.sort(key=lambda r: (r.get("skill_name") or ""))
+
+    return {
+        "drifted": drifted,
+        "fresh": fresh,
+        "missing": missing,
+        "skipped_null_hash": skipped_null_hash,
+        "stats": {
+            "total": len(constituents),
+            "drifted": len(drifted),
+            "fresh": len(fresh),
+            "missing": len(missing),
+            "skipped_null_hash": len(skipped_null_hash),
+        },
+    }
+
+
 # --------------------------------------------------------------------------
 # CLI
 # --------------------------------------------------------------------------
@@ -243,6 +645,55 @@ def _cmd_compare(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_manual_inventory(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if not path.is_file():
+        print(f"error: file not found: {path}", file=sys.stderr)
+        return 1
+    result = manual_inventory(path)
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _cmd_manual_verify(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    inventory = Path(args.inventory)
+    if not path.is_file():
+        print(f"error: file not found: {path}", file=sys.stderr)
+        return 1
+    if not inventory.is_file():
+        print(f"error: inventory not found: {inventory}", file=sys.stderr)
+        return 1
+    try:
+        result = manual_verify(inventory, path)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _cmd_compare_constituents(args: argparse.Namespace) -> int:
+    provenance = Path(args.provenance_map)
+    skills_root = Path(args.skills_root)
+    if not provenance.is_file():
+        print(f"error: provenance map not found: {provenance}", file=sys.stderr)
+        return 1
+    if not skills_root.is_dir():
+        print(f"error: skills root not a directory: {skills_root}", file=sys.stderr)
+        return 1
+    try:
+        result = compare_constituents(provenance, skills_root)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="skf-hash-content",
@@ -271,6 +722,40 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     p_cmp.set_defaults(func=_cmd_compare)
 
+    p_inv = sub.add_parser(
+        "manual-inventory",
+        help="extract [MANUAL] blocks and emit {blocks[], count} JSON",
+    )
+    p_inv.add_argument("path", help="path to the SKILL.md (or reference file)")
+    p_inv.set_defaults(func=_cmd_manual_inventory)
+
+    p_ver = sub.add_parser(
+        "manual-verify",
+        help="verify a file against a captured [MANUAL] inventory",
+    )
+    p_ver.add_argument("path", help="path to the post-merge SKILL.md (or reference file)")
+    p_ver.add_argument(
+        "--inventory",
+        required=True,
+        help="path to the manual-inventory JSON captured before the write",
+    )
+    p_ver.set_defaults(func=_cmd_manual_verify)
+
+    p_con = sub.add_parser(
+        "compare-constituent-hashes",
+        help="classify compose-mode stack constituents as drifted/fresh/missing",
+    )
+    p_con.add_argument(
+        "provenance_map",
+        help="path to the compose-mode provenance-map.json (object with constituents[] or bare array)",
+    )
+    p_con.add_argument(
+        "--skills-root",
+        default=".",
+        help="base directory for resolving relative constituent skill_path values (default: current directory)",
+    )
+    p_con.set_defaults(func=_cmd_compare_constituents)
+
     return parser
 
 

package/src/shared/scripts/skf-language-corpora.py

@@ -0,0 +1,100 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Language Corpora — canonical companion prose corpora for a language.
+
+A whole-language skill (issue #427) is forged from a language-reference repo
+(a compiler/interpreter such as rust-lang/rust). That repo carries the
+language's CODE, but a skill's value comes from the language's PROSE — the
+guide/Book, the standard/library API docs, idioms. README detection
+(skf-detect-docs.py) is the primary source for those; this lookup guarantees
+the canonical corpora for well-known languages even when the repo's README
+does not link them.
+
+Pure static lookup over src/shared/data/language-corpora.json — no network,
+no git, no `gh`. Output is the brief `doc_urls` contract (`{url, label,
+source}`), with `source` fixed to `"language-registry"` (issue #432), so the
+result can be seeded directly into a skill brief and later distinguished from
+README-detected docs.
+
+CLI:
+  uv run src/shared/scripts/skf-language-corpora.py --language <id>
+
+Output (JSON array on stdout): [{"url": "...", "label": "...", "source": "language-registry"}, ...]
+
+Exit codes:
+  0  registry hit — one or more corpora emitted
+  1  no entry for this language (long-tail / unknown) — emits []
+  2  error (bad args, missing/unreadable/invalid data file)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_DATA_FILE = Path(__file__).resolve().parent.parent / "data" / "language-corpora.json"
+
+
+def _die(message: str, code: str = "INTERNAL_ERROR") -> None:
+    json.dump({"error": message, "code": code}, sys.stderr, ensure_ascii=False)
+    sys.stderr.write("\n")
+    sys.exit(2)
+
+
+def _load_registry() -> dict:
+    try:
+        data = json.loads(_DATA_FILE.read_text(encoding="utf-8"))
+    except OSError as exc:
+        _die(f"Cannot read {_DATA_FILE.as_posix()}: {exc}", "DATA_READ_ERROR")
+    except json.JSONDecodeError as exc:
+        _die(f"Cannot parse {_DATA_FILE.as_posix()}: {exc}", "DATA_PARSE_ERROR")
+    if not isinstance(data, dict):
+        _die("Corpora registry must be a JSON object", "DATA_PARSE_ERROR")
+    return data
+
+
+def corpora_for(language: str) -> list[dict]:
+    """Return the `{url, label, source}` corpora for a language id, or [] if none.
+
+    Every emitted entry is stamped `source: "language-registry"` (issue #432) so
+    downstream — the brief writer, the noise-suppression filter (#431), and the
+    assembly tier-ordering (#430) — can distinguish a registry-guaranteed
+    corpus from an opportunistically README-detected doc.
+    """
+    registry = _load_registry()
+    entries = registry.get((language or "").strip().lower())
+    if not isinstance(entries, list):
+        return []
+    out: list[dict] = []
+    for e in entries:
+        if isinstance(e, dict) and e.get("url"):
+            out.append({
+                "url": e["url"],
+                "label": e.get("label", ""),
+                "source": "language-registry",
+            })
+    return out
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Look up canonical companion prose corpora for a language.",
+    )
+    parser.add_argument(
+        "--language", required=True,
+        help="Lowercase language id (rust, python, go, typescript, ruby, ...)",
+    )
+    args = parser.parse_args(argv)
+
+    result = corpora_for(args.language)
+    json.dump(result, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0 if result else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))