@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/pack_render.py

@@ -0,0 +1,434 @@
+#!/usr/bin/env python3
+"""pack_render.py -- regenerate content-pack projections from canonical sources.
+
+Pack-agnostic renderer (#1294 lessons pilot, generalized in #1295). Each pack's
+render shape is declared by an entry in ``RENDER_REGISTRY``:
+
+- ``collection`` mode renders all of a pack's entries into ONE projection. The
+  lessons pack uses it: ``packs/lessons/lessons-pack-0.1.json`` ->
+  ``meta/lessons.md`` (banner + ``# Lessons Learned`` title + ``## {title}\\n\\n
+  {body}`` per entry). Output is preserved byte-for-byte.
+- ``documents`` mode renders each entry that carries a body into its own
+  per-entry path. The renderer dispatched per entry is selected by the registry
+  ``doc_kind``: ``skill`` reconstructs YAML frontmatter + banner + body (the
+  skills pack proof SKILL.md); ``markdown`` emits banner + body for a plain
+  hand-authored doc (the rules pack proof coding/testing.md and the strategies
+  pack proof strategies/yolo.md). Metadata-only entries (body null) are skipped.
+
+The renderer OWNS the document chrome: the canonical machine-generated banner
+(``conventions/machine-generated-banner.md``) plus an ADR-001 Layer-A slice
+deflection pointer. The same target-collection backs both the write path
+(``task packs:render``) and the drift gate (``--check`` / ``task
+verify:pack-drift``), so committed projections and freshly re-rendered buffers
+match by construction -- across BOTH packs.
+
+Usage::
+
+    uv run python scripts/pack_render.py            # write all packs' projections
+    uv run python scripts/pack_render.py --check     # drift gate over all packs
+    uv run python scripts/pack_render.py --pack skills [--check]
+    uv run python scripts/pack_render.py --source <json> --output <md>  # legacy
+
+Exit codes:
+    0 -- rendered (write mode) OR no drift (check mode)
+    1 -- drift detected (check mode) OR source missing
+    2 -- usage error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import textwrap
+from pathlib import Path
+from typing import Any
+
+# Repo root resolved from this file's location (scripts/ -> repo root) so the
+# default source / output paths are CWD-independent.
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _content_root import content_root  # noqa: E402
+
+# Shippable content moved under content/ in the source repo and is
+# flattened to the framework root in a consumer deposit (#1875 C1).
+CONTENT_ROOT = content_root(REPO_ROOT)
+DEFAULT_SOURCE = CONTENT_ROOT / "packs" / "lessons" / "lessons-pack-0.1.json"
+DEFAULT_OUTPUT = REPO_ROOT / "meta" / "lessons.md"
+
+# Canonical 4-line machine-generated banner (conventions/machine-generated-banner.md)
+# plus a 5th ADR-001 Layer-A deflection line pointing humans/agents at the
+# slice surface instead of loading the whole projection. Banner lines are kept
+# per-pack in RENDER_REGISTRY so the renderer is pack-agnostic; the lessons
+# tuple below is preserved byte-for-byte so the committed meta/lessons.md and
+# its drift gate stay green.
+_LESSONS_BANNER: tuple[str, ...] = (
+    "<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->",
+    "<!-- Purpose: rendered lessons -->",
+    "<!-- Source of truth: packs/lessons/lessons-pack-0.1.json -->",
+    "<!-- Regenerate with: task packs:render -->",
+    "<!-- Edit the source, not this file. Slice instead of loading the whole file: "
+    "task packs:slice lessons <name> (e.g. recent --since, by-tag --tag) -->",
+)
+
+_SKILLS_BANNER: tuple[str, ...] = (
+    "<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->",
+    "<!-- Purpose: rendered skill -->",
+    "<!-- Source of truth: packs/skills/skills-pack-0.1.json -->",
+    "<!-- Regenerate with: task packs:render -->",
+    "<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: "
+    "task packs:slice skills by-trigger --trigger <kw> (or list) -->",
+)
+
+_RULES_BANNER: tuple[str, ...] = (
+    "<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->",
+    "<!-- Purpose: rendered coding rules -->",
+    "<!-- Source of truth: packs/rules/rules-pack-0.1.json -->",
+    "<!-- Regenerate with: task packs:render -->",
+    "<!-- Edit the source, not this file. Slice instead of loading every coding doc: "
+    "task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->",
+)
+
+_STRATEGIES_BANNER: tuple[str, ...] = (
+    "<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->",
+    "<!-- Purpose: rendered strategy -->",
+    "<!-- Source of truth: packs/strategies/strategies-pack-0.1.json -->",
+    "<!-- Regenerate with: task packs:render -->",
+    "<!-- Edit the source, not this file. Slice instead of loading every strategy: "
+    "task packs:slice strategies by-trigger --trigger <kw> (or list) -->",
+)
+
+_PATTERNS_BANNER: tuple[str, ...] = (
+    "<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->",
+    "<!-- Purpose: rendered pattern -->",
+    "<!-- Source of truth: packs/patterns/patterns-pack-0.1.json -->",
+    "<!-- Regenerate with: task packs:render -->",
+    "<!-- Edit the source, not this file. Slice instead of loading every pattern: "
+    "task packs:slice patterns by-trigger --trigger <kw> (or list) -->",
+)
+
+_SWARM_SPEC_BANNER: tuple[str, ...] = (
+    "<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->",
+    "<!-- Purpose: rendered swarm spec -->",
+    "<!-- Source of truth: packs/swarm-spec/swarm-spec-pack-0.1.json -->",
+    "<!-- Regenerate with: task packs:render -->",
+    "<!-- Edit the source, not this file. Slice instead of loading the whole spec: "
+    "task packs:slice swarm-spec list -->",
+)
+
+# BANNER retained (lessons banner as a single trailing-newline string) for any
+# back-compat importers; the active renderer composes banners from the tuples.
+BANNER = "\n".join(_LESSONS_BANNER) + "\n"
+
+DOC_TITLE = "# Lessons Learned"
+
+# Per-pack render configuration ("a registry entry" per #1295). Each entry
+# drives the pack-agnostic engine: ``collection`` renders all entries into one
+# projection (lessons -> meta/lessons.md); ``documents`` renders each entry that
+# carries a body into its own per-entry path (skills -> the proof SKILL.md).
+RENDER_REGISTRY: dict[str, dict[str, Any]] = {
+    "lessons": {
+        "mode": "collection",
+        "source": CONTENT_ROOT / "packs" / "lessons" / "lessons-pack-0.1.json",
+        "output": REPO_ROOT / "meta" / "lessons.md",
+        "items_field": "lessons",
+        "heading_field": "title",
+        "body_field": "body",
+        "title": DOC_TITLE,
+        "banner": _LESSONS_BANNER,
+    },
+    "skills": {
+        "mode": "documents",
+        "doc_kind": "skill",
+        "source": CONTENT_ROOT / "packs" / "skills" / "skills-pack-0.1.json",
+        "items_field": "skills",
+        "name_field": "id",
+        "description_field": "description",
+        "path_field": "path",
+        "body_field": "body",
+        "banner": _SKILLS_BANNER,
+    },
+    "rules": {
+        "mode": "documents",
+        "doc_kind": "markdown",
+        "source": CONTENT_ROOT / "packs" / "rules" / "rules-pack-0.1.json",
+        "items_field": "rules",
+        "path_field": "path",
+        "body_field": "body",
+        "banner": _RULES_BANNER,
+    },
+    "strategies": {
+        "mode": "documents",
+        "doc_kind": "markdown",
+        "source": CONTENT_ROOT / "packs" / "strategies" / "strategies-pack-0.1.json",
+        "items_field": "strategies",
+        "path_field": "path",
+        "body_field": "body",
+        "banner": _STRATEGIES_BANNER,
+    },
+    "patterns": {
+        "mode": "documents",
+        "doc_kind": "markdown",
+        "source": CONTENT_ROOT / "packs" / "patterns" / "patterns-pack-0.1.json",
+        "items_field": "patterns",
+        "path_field": "path",
+        "body_field": "body",
+        "banner": _PATTERNS_BANNER,
+    },
+    "swarm-spec": {
+        "mode": "documents",
+        "doc_kind": "markdown",
+        "source": CONTENT_ROOT / "packs" / "swarm-spec" / "swarm-spec-pack-0.1.json",
+        "items_field": "entries",
+        "path_field": "path",
+        "body_field": "body",
+        "banner": _SWARM_SPEC_BANNER,
+    },
+}
+
+
+def _banner_text(banner_lines: tuple[str, ...] | list[str]) -> str:
+    """Join banner lines into the canonical trailing-newline banner block."""
+    return "\n".join(banner_lines) + "\n"
+
+
+def render_collection(pack: dict, cfg: dict[str, Any]) -> str:
+    """Render a pack's entries into one whole-document projection.
+
+    The lessons pack uses this mode; the emitted shape (banner, title, then
+    ``## {heading}\\n\\n{body}`` per entry) is preserved byte-for-byte.
+    """
+    parts: list[str] = [_banner_text(cfg["banner"]), f"\n{cfg['title']}\n"]
+    for entry in pack.get(cfg["items_field"], []):
+        heading = entry[cfg["heading_field"]]
+        body = entry[cfg["body_field"]]
+        parts.append(f"\n## {heading}\n\n{body}\n")
+    return "".join(parts)
+
+
+def _emit_description(description: str) -> str:
+    """Re-emit a folded description as a YAML folded block scalar (``>-``).
+
+    Block scalars carry arbitrary punctuation without escaping, so this is a
+    safe, deterministic reconstruction. Per ADR-001 a reformat diff against the
+    hand-authored frontmatter is expected and accepted (regenerate-and-commit).
+    """
+    wrapped = textwrap.wrap(description, width=76) or [""]
+    lines = ["description: >-"]
+    lines.extend(f"  {line}" for line in wrapped)
+    return "\n".join(lines)
+
+
+def render_skill_document(entry: dict, cfg: dict[str, Any]) -> str:
+    """Render one skill entry into its SKILL.md projection.
+
+    Output = reconstructed YAML frontmatter (name + folded description + any
+    verbatim ``frontmatter_extra`` block) + the provenance banner + the captured
+    body (verbatim). The ``frontmatter_extra`` round-trip keeps every
+    hand-authored frontmatter key (``triggers:``, ``metadata:``, ...) so the
+    projection is LOSSLESS (#1637). A single blank line always separates the
+    banner from the body so re-migration is idempotent.
+    """
+    name = entry[cfg["name_field"]]
+    description = entry[cfg["description_field"]]
+    body = entry[cfg["body_field"]] or ""
+    extra = entry.get("frontmatter_extra")
+    extra_block = f"{extra}\n" if extra else ""
+    frontmatter = f"---\nname: {name}\n{_emit_description(description)}\n{extra_block}---\n"
+    return frontmatter + _banner_text(cfg["banner"]) + "\n" + body
+
+
+def render_markdown_document(entry: dict, cfg: dict[str, Any]) -> str:
+    """Render one plain-markdown entry into its banner-marked projection.
+
+    Output = the provenance banner + a single blank-line separator + the
+    captured body (verbatim). Used by the rules + strategies packs, whose proof
+    documents are hand-authored markdown (no YAML frontmatter to reconstruct). A
+    single blank line always separates the banner from the body so re-migration
+    (which strips the banner) is idempotent.
+    """
+    body = entry[cfg["body_field"]] or ""
+    return _banner_text(cfg["banner"]) + "\n" + body
+
+
+# Per-``doc_kind`` document renderer for the ``documents`` mode. Data-driven so
+# the engine dispatches by registry config rather than per-pack branching.
+_DOCUMENT_RENDERERS = {
+    "skill": render_skill_document,
+    "markdown": render_markdown_document,
+}
+
+
+def _targets_for_pack(
+    pack: dict, cfg: dict[str, Any]
+) -> list[tuple[Path, str]]:
+    """Return the (output_path, rendered_text) targets for one loaded pack."""
+    if cfg["mode"] == "collection":
+        return [(cfg["output"], render_collection(pack, cfg))]
+    doc_renderer = _DOCUMENT_RENDERERS[cfg.get("doc_kind", "skill")]
+    targets: list[tuple[Path, str]] = []
+    for entry in pack.get(cfg["items_field"], []):
+        if not entry.get(cfg["body_field"]):
+            continue
+        out_path = CONTENT_ROOT / entry[cfg["path_field"]]
+        targets.append((out_path, doc_renderer(entry, cfg)))
+    return targets
+
+
+def collect_targets(pack_filter: str | None = None) -> list[tuple[str, Path, str]]:
+    """Collect (pack_name, output_path, rendered_text) targets across all packs.
+
+    Drives both the multi-pack write path and the multi-pack drift gate, so the
+    committed projections and freshly rendered buffers match by construction.
+    """
+    targets: list[tuple[str, Path, str]] = []
+    for name, cfg in RENDER_REGISTRY.items():
+        if pack_filter is not None and name != pack_filter:
+            continue
+        source = cfg["source"]
+        if not source.is_file():
+            raise FileNotFoundError(f"pack source not found: {source}")
+        pack = json.loads(source.read_text(encoding="utf-8"))
+        for out_path, text in _targets_for_pack(pack, cfg):
+            targets.append((name, out_path, text))
+    return targets
+
+
+def render(pack: dict) -> str:
+    """Render a lessons pack object to the meta/lessons.md projection text.
+
+    Back-compat entrypoint: delegates to the pack-agnostic collection engine
+    using the lessons registry config.
+    """
+    return render_collection(pack, RENDER_REGISTRY["lessons"])
+
+
+def render_file(source: Path) -> str:
+    """Load the pack JSON at ``source`` and return the rendered projection text."""
+    if not source.is_file():
+        raise FileNotFoundError(f"pack source not found: {source}")
+    pack = json.loads(source.read_text(encoding="utf-8"))
+    return render(pack)
+
+
+def write_render(source: Path, output: Path) -> str:
+    """Render ``source`` and write the projection to ``output``. Returns the text."""
+    text = render_file(source)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(text, encoding="utf-8")
+    return text
+
+
+def check_drift(source: Path, output: Path) -> tuple[bool, str, str]:
+    """Compare a freshly rendered projection against the committed ``output``.
+
+    Returns ``(has_drift, rendered, current)``. ``has_drift`` is True when the
+    committed file is missing or differs from the freshly rendered text.
+    """
+    rendered = render_file(source)
+    current = output.read_text(encoding="utf-8") if output.is_file() else ""
+    return rendered != current, rendered, current
+
+
+def _first_diff_line(rendered: str, current: str) -> int:
+    """Return the 1-indexed line number of the first difference (0 if none)."""
+    r_lines = rendered.splitlines()
+    c_lines = current.splitlines()
+    for i, (r, c) in enumerate(zip(r_lines, c_lines, strict=False)):
+        if r != c:
+            return i + 1
+    if len(r_lines) != len(c_lines):
+        return min(len(r_lines), len(c_lines)) + 1
+    return 0
+
+
+def _run_legacy(source: Path, output: Path, *, check: bool) -> int:
+    """Single-file render / drift mode (explicit --source/--output overrides)."""
+    if check:
+        has_drift, rendered, current = check_drift(source, output)
+        if has_drift:
+            line = _first_diff_line(rendered, current)
+            print(
+                f"pack-drift: {output} is out of sync with {source} "
+                f"(first difference near line {line}). "
+                f"Run `task packs:render` to regenerate.",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"pack-drift: {output} is in sync with {source}.")
+        return 0
+    write_render(source, output)
+    print(f"Rendered {output} from {source}")
+    return 0
+
+
+def _run_multipack(pack_filter: str | None, *, check: bool) -> int:
+    """Multi-pack render / drift mode across RENDER_REGISTRY (default mode)."""
+    targets = collect_targets(pack_filter)
+    if check:
+        drifted: list[Path] = []
+        for _name, out_path, text in targets:
+            current = out_path.read_text(encoding="utf-8") if out_path.is_file() else ""
+            if text != current:
+                drifted.append(out_path)
+        if drifted:
+            listing = ", ".join(str(p) for p in drifted)
+            print(
+                f"pack-drift: {len(drifted)} projection(s) out of sync: {listing}. "
+                f"Run `task packs:render` to regenerate.",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"pack-drift: all {len(targets)} projection(s) in sync.")
+        return 0
+    for _name, out_path, text in targets:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(text, encoding="utf-8")
+    print(f"Rendered {len(targets)} projection(s) across {len(RENDER_REGISTRY)} pack(s).")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pack_render.py",
+        description="Render content-pack projections from their canonical sources (ADR-001).",
+    )
+    parser.add_argument(
+        "--source",
+        type=Path,
+        default=None,
+        help="Legacy single-file mode: pack source JSON (lessons collection).",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="Legacy single-file mode: projection output path.",
+    )
+    parser.add_argument(
+        "--pack",
+        default=None,
+        help="Limit multi-pack mode to one pack short-name (e.g. lessons, skills).",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Drift gate: render to a buffer and fail (exit 1) on divergence "
+        "instead of writing. Covers every pack unless --pack narrows it.",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.source is not None or args.output is not None:
+            source = args.source or DEFAULT_SOURCE
+            output = args.output or DEFAULT_OUTPUT
+            return _run_legacy(source, output, check=args.check)
+        return _run_multipack(args.pack, check=args.check)
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())