@deftai/directive-content 0.59.0 → 0.60.0

package/scripts/prd_render.py

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