@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/_policy_show_cli.py

@@ -1,266 +0,0 @@
-#!/usr/bin/env python3
-"""``task policy:show`` argparse shim (#1148 / N8 of #1119 Wave-2d-1).
-
-Extracted from :mod:`scripts.policy` so the parent module stays well
-under the 1000-line MUST cap from ``coding/coding.md``. The CLI delegates
-to :func:`policy.inspect_all_policies` / :func:`policy.inspect_one_policy`
-for every read; the render layer here is purely cosmetic.
-
-Flags (mirror the #1148 issue body):
-
-* ``--format=text|json`` -- ``text`` is the default human form (one block
-  per field); ``json`` emits the stable schema
-  ``{generated_at, fields: [{name, current, default, source}, ...]}``.
-* ``--changed-only`` -- drop rows whose source is ``default`` so the
-  output focuses on what the operator actually configured. Combines
-  cleanly with ``--format=json`` for ``jq`` consumption.
-* ``--field=<canonical-dotted-path>`` -- show exactly one registered
-  field; exit 2 with the recognised-names list when ``<name>`` is not
-  a registered field. Mutually compatible with ``--format=json``.
-* ``--project-root <path>`` -- override the project root (defaults to
-  ``Path.cwd()``); useful for tests + tools dispatching from outside
-  the consumer working directory.
-
-Exit codes:
-
-* ``0`` -- success (including the "all defaults" + "missing
-  PROJECT-DEFINITION" cases; the verb is informational).
-* ``2`` -- argparse usage error OR unknown ``--field=<name>``.
-
-Pure-stdlib; runs anywhere :mod:`scripts.policy` does.
-"""
-
-from __future__ import annotations
-
-import argparse
-import contextlib
-import json
-import sys
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any
-
-# Make sibling scripts importable when invoked as
-# ``python scripts/_policy_show_cli.py`` (the dispatch shape go-task uses).
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-# UTF-8 self-reconfigure -- the rendered values for ``triageScope`` etc.
-# can include non-ASCII characters that crash cp1252 on Windows.
-for _stream in (sys.stdout, sys.stderr):
-    if hasattr(_stream, "reconfigure"):
-        with contextlib.suppress(AttributeError, ValueError):
-            _stream.reconfigure(encoding="utf-8", errors="replace")
-
-import policy  # noqa: E402  (sibling import after sys.path tweak)
-
-# ---------------------------------------------------------------------------
-# Public helpers (test-injectable)
-# ---------------------------------------------------------------------------
-
-
-def _utc_iso(dt: datetime | None = None) -> str:
-    """ISO-8601 UTC timestamp with seconds precision and ``Z`` suffix."""
-    return (dt or datetime.now(UTC)).astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def field_to_dict(field: policy.PolicyField) -> dict[str, Any]:
-    """Render one :class:`policy.PolicyField` as a JSON-stable dict.
-
-    Stable key order: ``name``, ``current``, ``default``, ``source``.
-    Stable across releases -- the JSON schema is the scripting contract.
-    """
-    return {
-        "name": field.name,
-        "current": field.current,
-        "default": field.default,
-        "source": field.source,
-    }
-
-
-def render_json(
-    fields: list[policy.PolicyField],
-    *,
-    now: datetime | None = None,
-) -> str:
-    """Render the JSON envelope ``{generated_at, fields: [...]}``.
-
-    ``ensure_ascii=False`` so non-ASCII operator values (rare but
-    possible -- e.g. milestone names with em dashes) survive the
-    serialisation round-trip without ``\\uXXXX`` escaping.
-    """
-    envelope = {
-        "generated_at": _utc_iso(now),
-        "fields": [field_to_dict(f) for f in fields],
-    }
-    return json.dumps(envelope, ensure_ascii=False, indent=2, sort_keys=False)
-
-
-def _format_value(value: Any) -> str:
-    """Render a value for the text format.
-
-    Booleans render as ``true`` / ``false`` (the issue-body example output
-    used lowercase JSON-style booleans). Lists and dicts round-trip
-    through ``json.dumps`` for a stable, copy-pasteable shape. Strings
-    render verbatim; numbers via ``repr`` so floats keep precision.
-    """
-    if isinstance(value, bool):
-        return "true" if value else "false"
-    if isinstance(value, (list, dict)):
-        return json.dumps(value, ensure_ascii=False, sort_keys=False)
-    if isinstance(value, str):
-        return value
-    return repr(value)
-
-
-def render_text(fields: list[policy.PolicyField]) -> str:
-    """Render the human-readable text format from the issue body.
-
-    Each field renders as a four-line block:
-
-    .. code-block:: text
-
-        [policy] <name>
-          current: <value>
-          default: <value>
-          source:  <typed|default|legacy>
-
-    Blocks are separated by a blank line. An empty ``fields`` list
-    (``--changed-only`` against an all-defaults config) renders a single
-    informational line so the operator does not see a blank screen.
-    """
-    if not fields:
-        return (
-            "[policy] (no fields changed)\n"
-            "  All registered policies are at their framework defaults. "
-            "Re-run without `--changed-only` to inspect them."
-        )
-    blocks: list[str] = []
-    for field in fields:
-        block = (
-            f"[policy] {field.name}\n"
-            f"  current: {_format_value(field.current)}\n"
-            f"  default: {_format_value(field.default)}\n"
-            f"  source:  {field.source}"
-        )
-        blocks.append(block)
-    return "\n\n".join(blocks)
-
-
-# ---------------------------------------------------------------------------
-# argparse setup
-# ---------------------------------------------------------------------------
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="task policy:show",
-        description=(
-            "Inspect every registered typed-policy field on "
-            "vbrief/PROJECT-DEFINITION.vbrief.json (#1148 / N8 of #1119)."
-        ),
-    )
-    parser.add_argument(
-        "--format",
-        choices=("text", "json"),
-        default="text",
-        help="Output format (default: text). Use json for stable scripting schema.",
-    )
-    parser.add_argument(
-        "--changed-only",
-        action="store_true",
-        help=(
-            "Filter out fields whose source is 'default'. "
-            "Keeps 'typed' and 'legacy' rows only."
-        ),
-    )
-    parser.add_argument(
-        "--field",
-        dest="field",
-        metavar="<name>",
-        default=None,
-        help=(
-            "Show exactly one registered field by canonical dotted path "
-            "(e.g. plan.policy.wipCap). Exits 2 on unknown name."
-        ),
-    )
-    parser.add_argument(
-        "--project-root",
-        dest="project_root",
-        metavar="<path>",
-        default=None,
-        help="Project root (default: current working directory).",
-    )
-    return parser
-
-
-def run_cli(argv: list[str] | None = None) -> int:
-    """Argparse + dispatch for ``task policy:show``.
-
-    Exit 0 in every success path (including all-defaults and missing
-    PROJECT-DEFINITION). Exit 2 for argparse usage errors and for
-    ``--field=<name>`` where ``<name>`` is not a registered field.
-    """
-    parser = _build_parser()
-    try:
-        args = parser.parse_args(argv)
-    except SystemExit as exc:
-        # argparse already emitted its error to stderr; preserve its code.
-        return int(exc.code) if isinstance(exc.code, int) else 2
-
-    project_root = (
-        Path(args.project_root).resolve() if args.project_root else Path.cwd()
-    )
-
-    # Surface a friendly informational line on missing PROJECT-DEFINITION so
-    # the operator understands why every row will be at default. Exit 0;
-    # show is informational by contract.
-    pd_path = project_root / policy.PROJECT_DEFINITION_REL_PATH
-    if not pd_path.is_file():
-        sys.stderr.write(
-            f"[policy:show] PROJECT-DEFINITION not found at {pd_path}; "
-            "rendering framework defaults.\n"
-        )
-
-    if args.field is not None:
-        return _dispatch_single_field(args, project_root)
-    return _dispatch_all_fields(args, project_root)
-
-
-def _dispatch_single_field(args: argparse.Namespace, project_root: Path) -> int:
-    field = policy.inspect_one_policy(args.field, project_root)
-    if field is None:
-        known = policy.registered_policy_names()
-        sys.stderr.write(
-            f"[policy:show] unknown --field={args.field!r}; "
-            f"registered fields: {known}\n"
-        )
-        return 2
-    # ``--changed-only`` against a single-field default is a no-op render --
-    # operators asking for a single field by name almost always want to see
-    # it regardless of source. The default branch keeps the row; the
-    # ``--changed-only`` filter only fires across the all-fields surface.
-    if args.format == "json":
-        sys.stdout.write(render_json([field]) + "\n")
-    else:
-        sys.stdout.write(render_text([field]) + "\n")
-    return 0
-
-
-def _dispatch_all_fields(args: argparse.Namespace, project_root: Path) -> int:
-    fields = policy.inspect_all_policies(project_root)
-    if args.changed_only:
-        fields = [f for f in fields if f.source != "default"]
-    if args.format == "json":
-        sys.stdout.write(render_json(fields) + "\n")
-    else:
-        sys.stdout.write(render_text(fields) + "\n")
-    return 0
-
-
-def main(argv: list[str] | None = None) -> int:
-    """CLI entry point. Alias for :func:`run_cli` so tests can patch it."""
-    return run_cli(argv)
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/_precutover.py

@@ -1,92 +0,0 @@
-"""Shared pre-v0.20 document-model detection helpers.
-
-The session-start guard, CLI gate, validator, and migration preflight all need
-the same distinction:
-
-* deprecation redirect stubs are migrated/current enough;
-* generated ``SPECIFICATION.md`` exports from ``task spec:render`` are not
-  hand-authored legacy docs when their source JSON exists, and are fully
-  current vBRIEF artifacts when their lifecycle folders also exist;
-* hand-authored root docs are legacy pre-cutover inputs.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-LIFECYCLE_FOLDERS: tuple[str, ...] = (
-    "proposed",
-    "pending",
-    "active",
-    "completed",
-    "cancelled",
-)
-
-DEPRECATED_REDIRECT_SENTINEL = "<!-- deft:deprecated-redirect -->"
-DEPRECATION_REDIRECT_PURPOSE = "<!-- Purpose: deprecation redirect -->"
-
-GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->"
-GENERATED_SPEC_SOURCE = "<!-- Source of truth: vbrief/specification.vbrief.json -->"
-SPEC_SOURCE_RELPATH = Path("vbrief") / "specification.vbrief.json"
-
-
-def missing_lifecycle_folders(project_root: Path) -> list[str]:
-    """Return missing vBRIEF lifecycle folder names for ``project_root``."""
-    vbrief_root = project_root / "vbrief"
-    return [folder for folder in LIFECYCLE_FOLDERS if not (vbrief_root / folder).is_dir()]
-
-
-def has_complete_lifecycle(project_root: Path) -> bool:
-    """Return True when every canonical lifecycle folder exists."""
-    return not missing_lifecycle_folders(project_root)
-
-
-def is_deprecation_redirect(content: str) -> bool:
-    """Return True when markdown content is a migration redirect stub."""
-    return DEPRECATED_REDIRECT_SENTINEL in content or DEPRECATION_REDIRECT_PURPOSE in content
-
-
-def is_generated_specification_export(project_root: Path, content: str) -> bool:
-    """Return True for a generated ``task spec:render`` root export.
-
-    The banner alone is not enough: the declared vBRIEF source must also
-    exist. Lifecycle completeness is checked separately by
-    ``is_current_generated_specification``.
-    """
-    return (
-        GENERATED_SPEC_PURPOSE in content
-        and GENERATED_SPEC_SOURCE in content
-        and (project_root / SPEC_SOURCE_RELPATH).is_file()
-    )
-
-
-def is_current_generated_specification(project_root: Path, content: str) -> bool:
-    """Return True for a fully current ``task spec:render`` root export."""
-    return is_generated_specification_export(project_root, content) and has_complete_lifecycle(
-        project_root
-    )
-
-
-def root_markdown_is_legacy(project_root: Path, filename: str, content: str) -> bool:
-    """Return True if a root markdown artifact should trigger migration."""
-    if is_deprecation_redirect(content):
-        return False
-    if filename == "SPECIFICATION.md" and is_generated_specification_export(project_root, content):
-        return False
-    return filename in {"SPECIFICATION.md", "PROJECT.md"}
-
-
-def detect_pre_cutover_legacy(project_root: Path) -> list[str]:
-    """Return root artifact filenames that are legacy pre-v0.20 inputs."""
-    legacy: list[str] = []
-    for filename in ("SPECIFICATION.md", "PROJECT.md"):
-        candidate = project_root / filename
-        if not candidate.is_file():
-            continue
-        try:
-            content = candidate.read_text(encoding="utf-8", errors="replace")
-        except OSError:
-            continue
-        if root_markdown_is_legacy(project_root, filename, content):
-            legacy.append(filename)
-    return legacy

package/scripts/_project_context.py

@@ -1,224 +0,0 @@
-"""_project_context.py -- resolve consumer project root + GitHub repo slug.
-
-Shared helpers used by ``scope_lifecycle``, ``issue_ingest``,
-``reconcile_issues`` and ``prd_render`` so every script follows the same
-precedence rules and fails loudly when no project context can be inferred.
-
-Precedence for ``resolve_project_root``:
-
-1. ``--project-root`` flag (explicit, highest precedence).
-2. ``$DEFT_PROJECT_ROOT`` environment variable.
-3. Walk upward from CWD looking for a ``vbrief/`` directory or a ``.git``
-   directory -- the first match is the project root.
-4. Fall back to the current working directory ONLY if it visibly looks
-   like a project root (contains either ``vbrief/`` or ``.git``).
-
-If none of those match, the caller gets ``None`` and is expected to emit
-a loud, actionable error -- silently falling back to ``deft/`` is exactly
-the bug that shipped #535 / #538.
-
-Precedence for ``resolve_project_repo``:
-
-1. ``--repo OWNER/NAME`` flag (explicit, highest precedence).
-2. ``$DEFT_PROJECT_REPO`` environment variable.
-3. ``git remote get-url origin`` run from the resolved project root --
-   this is the key anti-regression for #538: deft's own ``.git`` remote
-   (``deftai/directive``) is used only if the project root happens to be
-   deft itself.
-4. ``None`` -- caller must emit a loud error.
-"""
-
-from __future__ import annotations
-
-import argparse
-import os
-import re
-import subprocess
-from collections.abc import Callable
-from pathlib import Path
-
-from framework_commands import CommandResult, run_framework_command
-
-# Sentinel directories that mark a deft project root.
-_PROJECT_ROOT_SENTINELS = ("vbrief", ".git")
-
-
-def _is_project_root(candidate: Path) -> bool:
-    """Return True if *candidate* contains any deft project-root sentinel."""
-    return any((candidate / sentinel).exists() for sentinel in _PROJECT_ROOT_SENTINELS)
-
-
-def resolve_project_root(
-    cli_project_root: str | None = None,
-    *,
-    start: Path | None = None,
-) -> Path | None:
-    """Resolve the consumer project root using the documented precedence.
-
-    Returns ``None`` when no candidate matches; callers MUST fail loudly
-    in that case (never silently fall back to deft's own directory).
-    """
-    if cli_project_root:
-        candidate = Path(cli_project_root).resolve()
-        if candidate.is_dir():
-            return candidate
-        return None
-
-    env_root = os.environ.get("DEFT_PROJECT_ROOT")
-    if env_root:
-        candidate = Path(env_root).resolve()
-        if candidate.is_dir():
-            return candidate
-        return None
-
-    cwd = (start or Path.cwd()).resolve()
-    # Walk upward from CWD looking for a sentinel.
-    for candidate in (cwd, *cwd.parents):
-        if _is_project_root(candidate):
-            return candidate
-    return None
-
-
-def resolve_project_repo(
-    cli_repo: str | None = None,
-    *,
-    project_root: Path | None = None,
-) -> str | None:
-    """Resolve the consumer GitHub repo (``OWNER/NAME``).
-
-    Returns ``None`` when detection fails so the caller can emit an
-    actionable error. ``project_root`` narrows ``git remote`` detection to
-    the consumer repo; without it we fall back to CWD, which may be wrong
-    under a ``task deft:*`` include (#538).
-    """
-    if cli_repo:
-        slug = _normalise_repo_slug(cli_repo)
-        if slug:
-            return slug
-        return None
-
-    env_repo = os.environ.get("DEFT_PROJECT_REPO")
-    if env_repo:
-        slug = _normalise_repo_slug(env_repo)
-        if slug:
-            return slug
-        # Greptile P2 on #562: fail loudly when the env var is set but
-        # unparseable, to match the explicit-flag path (which returns
-        # None on a malformed value rather than falling through to git
-        # auto-detection). Silent fallback to git is exactly the
-        # anti-pattern this helper was introduced to prevent.
-        return None
-
-    return _detect_repo_from_git(project_root)
-
-
-def _normalise_repo_slug(value: str) -> str | None:
-    r"""Accept ``OWNER/NAME`` or a full GitHub URL, return ``OWNER/NAME``.
-
-    Allows dots in the name component (``acme/dotnet.runtime``,
-    ``acme/my.project.git``) -- the previous ``[^/\.\s]+`` pattern stopped
-    at the first dot and silently truncated the repo name, routing ``gh``
-    calls to the wrong (or non-existent) repository (Greptile P1 on #562).
-    Strips a trailing ``.git`` suffix explicitly so SSH clone URLs still
-    normalise to the bare ``OWNER/NAME`` form.
-    """
-    value = value.strip()
-    if not value:
-        return None
-    match = re.search(
-        r"github\.com[:/]([^/\s]+)/([^/\s]+?)(?:\.git)?(?:\s|$)",
-        value,
-    )
-    if match:
-        return f"{match.group(1)}/{match.group(2)}"
-    if re.match(r"^[^/\s]+/[^/\s]+$", value):
-        return value
-    return None
-
-
-def _detect_repo_from_git(project_root: Path | None) -> str | None:
-    """Run ``git remote get-url origin`` in *project_root* (or CWD)."""
-    cwd = str(project_root) if project_root else None
-    try:
-        result = subprocess.run(
-            ["git", "remote", "get-url", "origin"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-            cwd=cwd,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return None
-    if result.returncode != 0:
-        return None
-    return _normalise_repo_slug(result.stdout.strip())
-
-
-def is_framework_source_context(framework_root: Path, project_root: Path) -> bool:
-    """Return True when a task is running from the framework checkout itself.
-
-    Vendored consumer installs execute framework tasks from ``.deft/core`` while
-    the user working directory remains the consumer repo.  Equality of the two
-    lexical absolute roots is the stable distinction: only the source checkout
-    should run source-repo self-tests by default.  Do not resolve symlinks here:
-    a consumer project may symlink ``.deft/core`` to a local framework checkout
-    and should still run the consumer-safe gate.
-    """
-    return Path(os.path.abspath(framework_root)) == Path(os.path.abspath(project_root))
-
-
-def dispatch_task_check(
-    framework_root: Path,
-    project_root: Path,
-    *,
-    runner: Callable[
-        [str, Path, Path],
-        CommandResult | subprocess.CompletedProcess[str],
-    ]
-    | None = None,
-) -> int:
-    """Dispatch ``check`` to the context-appropriate aggregate target."""
-    target = (
-        "check:framework-source"
-        if is_framework_source_context(framework_root, project_root)
-        else "check:consumer"
-    )
-    command_runner = runner or (
-        lambda command, root, framework: run_framework_command(
-            command,
-            project_root=root,
-            framework_root=framework,
-        )
-    )
-    result = command_runner(target, project_root, framework_root)
-    code = getattr(result, "code", None)
-    if code is None:
-        code = result.returncode
-    return int(code)
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "--dispatch-task-check",
-        action="store_true",
-        help="Dispatch the check aggregate for the current install context.",
-    )
-    parser.add_argument("--framework-root", type=Path)
-    parser.add_argument("--project-root", type=Path)
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-    if args.dispatch_task_check:
-        if args.framework_root is None or args.project_root is None:
-            raise SystemExit("--framework-root and --project-root are required")
-        return dispatch_task_check(args.framework_root, args.project_root)
-    parser.print_help()
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())