@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/prd_render.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""prd_render.py -- Export plan.narratives from specification.vbrief.json to PRD.md.
+
+PRD.md is a read-only export artifact for stakeholder consumption.
+The vBRIEF specification.vbrief.json is the authoritative source of truth.
+
+Usage:
+    python3 scripts/prd_render.py [--spec PATH] [--output PATH]
+
+Options:
+    --spec PATH     Path to specification.vbrief.json (default: vbrief/specification.vbrief.json)
+    --output PATH   Path to output PRD.md (default: PRD.md)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Make sibling ``_stdio_utf8`` importable when run as ``__main__``.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+
+reconfigure_stdio()
+
+# Narrative key ordering for PRD output -- most important first.
+NARRATIVE_KEY_ORDER = [
+    "Overview",
+    "ProblemStatement",
+    "Goals",
+    "UserStories",
+    "Requirements",
+    "SuccessMetrics",
+    "Architecture",
+]
+
+# Canonical 4-line machine-generated banner per
+# ``conventions/machine-generated-banner.md`` (#572). Every writer that
+# emits a machine-managed markdown file uses the same shape so
+# downstream detectors can match on a stable token.
+BANNER = (
+    "<!-- AUTO-GENERATED by task prd:render -- DO NOT EDIT MANUALLY -->\n"
+    "<!-- Purpose: rendered PRD -->\n"
+    "<!-- Source of truth: vbrief/specification.vbrief.json -->\n"
+    "<!-- Regenerate with: task prd:render -->\n"
+)
+
+# The BANNER substring used to detect a deft-generated PRD; a pre-existing
+# hand-authored PRD (e.g. the framework's own ``PRD.md``) lacks this sentinel
+# and MUST NOT be overwritten silently (#539).
+_GENERATED_SENTINEL = "AUTO-GENERATED by task prd:render"
+
+
+def _is_deft_generated(path: Path) -> bool:
+    """Return True iff *path* is a previously-generated PRD we may overwrite."""
+    if not path.is_file():
+        return True  # nothing there; writing is safe
+    # Read only the first ~4KB so a multi-MB hand-authored PRD is not
+    # fully loaded into memory (Greptile P2 on #562; prior implementation
+    # used ``read_text()`` + slice which contradicted this comment).
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            head = fh.read(4096)
+    except OSError:
+        return False
+    return _GENERATED_SENTINEL in head
+
+
+def render_prd(spec_path: Path, output_path: Path, *, force: bool = False) -> None:
+    """Read specification.vbrief.json and write PRD.md."""
+    if not spec_path.is_file():
+        print(f"Error: specification file not found: {spec_path}", file=sys.stderr)
+        sys.exit(1)
+
+    # Refuse to overwrite a PRD.md that was not produced by this script,
+    # so consumer invocations that mis-resolve paths cannot silently
+    # clobber a hand-authored file (e.g. deft's own PRD.md was being
+    # overwritten from consumer projects before #539). --force overrides.
+    if not force and not _is_deft_generated(output_path):
+        print(
+            f"Error: refusing to overwrite non-generated PRD at {output_path}. "
+            "This file lacks the "
+            f'"{_GENERATED_SENTINEL}" banner -- it was likely hand-authored. '
+            "Re-run with --force to overwrite, or point --output at a "
+            "different file (#539).",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    with open(spec_path, encoding="utf-8") as f:
+        data = json.load(f)
+
+    plan = data.get("plan", {})
+    title = plan.get("title", "Project")
+    narratives = plan.get("narratives", {})
+
+    if not narratives:
+        print(f"Warning: no narratives found in {spec_path}", file=sys.stderr)
+
+    lines: list[str] = [
+        BANNER,
+        f"# {title} -- Product Requirements Document\n",
+    ]
+
+    # Render ordered keys first, then any remaining keys alphabetically.
+    rendered_keys: set[str] = set()
+    for key in NARRATIVE_KEY_ORDER:
+        if key in narratives:
+            lines.append(f"## {key}\n")
+            lines.append(f"{narratives[key]}\n")
+            rendered_keys.add(key)
+
+    for key in sorted(narratives.keys()):
+        if key not in rendered_keys:
+            lines.append(f"## {key}\n")
+            lines.append(f"{narratives[key]}\n")
+
+    lines.append(
+        "---\n"
+        "*This document is auto-generated from `vbrief/specification.vbrief.json` "
+        "via `task prd:render`. Do not edit directly.*\n"
+    )
+
+    output_path.write_text("\n".join(lines), encoding="utf-8")
+    print(f"PRD.md written to {output_path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Export plan.narratives from specification.vbrief.json to PRD.md"
+    )
+    parser.add_argument(
+        "--spec",
+        default="vbrief/specification.vbrief.json",
+        help="Path to specification.vbrief.json",
+    )
+    parser.add_argument(
+        "--output",
+        default="PRD.md",
+        help="Path to output PRD.md",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help=(
+            "Overwrite a non-generated PRD.md. Without this flag the "
+            "script refuses to clobber files that lack the auto-generated "
+            "banner (#539)."
+        ),
+    )
+    args = parser.parse_args()
+    render_prd(Path(args.spec), Path(args.output), force=args.force)
+
+
+if __name__ == "__main__":
+    main()