@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/pack_render.py

@@ -1,434 +0,0 @@
-#!/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())