@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/migrate_preflight.py

@@ -0,0 +1,418 @@
+#!/usr/bin/env python3
+"""migrate_preflight.py -- agent-side environment preflight for ``task migrate:vbrief`` (#793).
+
+Reifies the prose contract documented in
+``skills/deft-directive-setup/SKILL.md`` § Environment Preflight as a runnable
+task so consumers running ``task migrate:vbrief`` directly (not via the
+agent-driven setup skill) get the same checks before any destructive mutation
+runs.
+
+Pure stdlib + ``subprocess``. Three-state exit (mirrors
+``scripts/preflight_branch.py`` (#747) and ``scripts/preflight_implementation.py``
+(#810) shape):
+
+- ``0`` -- ready: every check PASS (or non-blocking WARN, e.g. dirty git tree).
+- ``1`` -- not-ready: any check FAIL with an actionable remediation pointer.
+- ``2`` -- config error: e.g. ``--project-root`` does not exist or is not a
+  directory. Distinct from FAIL so callers can disambiguate "user can fix"
+  from "calling environment is wrong".
+
+The checks are:
+
+1. ``uv`` on PATH -- the migrator runs via ``uv run python``; absence is fatal.
+2. v0.20+ layout -- ``<deft-root>/scripts/migrate_vbrief.py`` and
+   ``<project>/vbrief/`` (with the ``schemas/`` subdirectory carried by the
+   framework checkout) must exist; absence indicates an incomplete or
+   pre-cutover checkout.
+3. Document-model state -- delegates to ``scripts/_precutover.py`` so a
+   generated ``SPECIFICATION.md`` from ``task spec:render`` does not send a
+   current vBRIEF project through destructive migration.
+4. Git working-tree state -- a dirty tree is reported as WARN (the migrator's
+   own dirty-tree guard fires with an actionable ``--force`` pointer; we do
+   NOT block here so ``--dry-run`` previews remain usable). Non-git
+   directories are also a WARN-level skip rather than a FAIL.
+
+The intent is to surface every fixable blocker at once, with one line per
+check, so operators can resolve them in a single pass instead of fighting
+through three separate subprocess error tracebacks.
+
+Soft-dep on #792 (``cmd_doctor`` uv-detection helper): a local
+``_uv_available()`` is defined here for now to keep this PR self-contained;
+when #792 lands a future small follow-up can DRY both surfaces against a
+single shared helper.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _content_root import content_root  # noqa: E402
+from _precutover import (  # noqa: E402
+    detect_pre_cutover_legacy,
+    is_current_generated_specification,
+    is_generated_specification_export,
+    missing_lifecycle_folders,
+)
+
+
+class CheckResult(NamedTuple):
+    """A single preflight check's outcome.
+
+    Attributes:
+        name: Short, stable identifier (e.g. ``uv``, ``layout``, ``git-clean``).
+        status: One of ``PASS`` / ``WARN`` / ``FAIL``.
+        message: Human-readable remediation pointer or status note.
+    """
+
+    name: str
+    status: str  # "PASS" | "WARN" | "FAIL"
+    message: str
+
+
+# ---------------------------------------------------------------------------
+# Individual check primitives
+# ---------------------------------------------------------------------------
+
+
+def _uv_available() -> bool:
+    """Return True when the ``uv`` executable is resolvable on PATH.
+
+    Local helper for #793; once #792 lands a shared ``cmd_doctor`` helper a
+    follow-up should DRY this against a single source of truth (the brief's
+    ``soft_dep_on: #792`` note).
+    """
+    return shutil.which("uv") is not None
+
+
+def check_uv() -> CheckResult:
+    """Verify ``uv`` is on PATH.
+
+    The migrator dispatches via ``uv run python ...``; without ``uv`` the
+    consumer hits a raw ``FileNotFoundError`` with no recovery pointer. This
+    check is the actionable replacement for that traceback.
+    """
+    if _uv_available():
+        return CheckResult("uv", "PASS", "uv is on PATH.")
+    return CheckResult(
+        "uv",
+        "FAIL",
+        "uv is not on PATH. Install from https://docs.astral.sh/uv/ and re-run.",
+    )
+
+
+def check_layout(deft_root: Path, project_root: Path) -> CheckResult:
+    """Verify the framework checkout + project root carry the v0.20+ layout.
+
+    Two pieces are required:
+
+    1. ``<deft-root>/scripts/migrate_vbrief.py`` -- the migrator script the
+       ``task migrate:vbrief`` target dispatches to. A missing file means the
+       framework checkout is incomplete or came from a pre-v0.20 release.
+    2. ``<project-root>/vbrief/`` -- the lifecycle root the migrator ingests
+       into. It is created on first run for greenfield projects, but most
+       v0.20+ projects already have it; existence here is informational
+       (``WARN`` when missing, not ``FAIL``).
+
+    The framework's ``vbrief/schemas/`` directory MUST exist on the deft root
+    too (carried by the checkout, not regenerated) -- absence indicates a
+    framework checkout problem and is FAIL.
+    """
+    migrator = deft_root / "scripts" / "migrate_vbrief.py"
+    if not migrator.is_file():
+        return CheckResult(
+            "layout",
+            "FAIL",
+            (
+                f"Migrator script missing at {migrator}. The framework checkout "
+                "appears incomplete or pre-v0.20; refresh per "
+                "deft/QUICK-START.md."
+            ),
+        )
+
+    schemas_dir = content_root(deft_root) / "vbrief" / "schemas"
+    if not schemas_dir.is_dir():
+        return CheckResult(
+            "layout",
+            "FAIL",
+            (
+                f"Framework schemas dir missing at {schemas_dir}. Refresh the "
+                "deft checkout (see deft/QUICK-START.md)."
+            ),
+        )
+
+    project_vbrief = project_root / "vbrief"
+    if not project_vbrief.exists():
+        return CheckResult(
+            "layout",
+            "WARN",
+            (
+                f"Project vbrief/ not present at {project_vbrief} -- migrator "
+                "will create it on first run; this is expected for greenfield "
+                "projects."
+            ),
+        )
+
+    return CheckResult(
+        "layout",
+        "PASS",
+        f"Framework migrator + schemas present; project vbrief/ at {project_vbrief}.",
+    )
+
+
+def check_git_clean(project_root: Path) -> CheckResult:
+    """Surface git working-tree state non-blockingly.
+
+    A dirty tree is reported as WARN (not FAIL) because:
+
+    - ``task migrate:vbrief -- --dry-run`` is the recommended preview path and
+      runs fine against a dirty tree.
+    - The migrator itself has a dirty-tree guard with a ``--force`` recovery
+      pointer (#497); double-blocking here would be redundant.
+
+    A non-git directory is also a WARN: the gate has nothing to assert, but
+    the operator deserves to know the standard recovery path won't apply.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=str(project_root),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return CheckResult(
+            "git-clean",
+            "WARN",
+            (
+                "git executable not on PATH; skipping working-tree check. "
+                "Migrator's dirty-tree guard will still fire if applicable."
+            ),
+        )
+
+    if proc.returncode != 0:
+        # Non-zero typically means "not a git repository". Treat as WARN.
+        return CheckResult(
+            "git-clean",
+            "WARN",
+            (
+                f"Not a git repository at {project_root} (git exit "
+                f"{proc.returncode}); skipping working-tree check."
+            ),
+        )
+
+    if proc.stdout.strip():
+        return CheckResult(
+            "git-clean",
+            "WARN",
+            (
+                "Working tree is dirty. The migrator will refuse to run "
+                "without --force; preview with `task migrate:vbrief -- "
+                "--dry-run` first."
+            ),
+        )
+
+    return CheckResult("git-clean", "PASS", "Working tree is clean.")
+
+
+def check_document_model(project_root: Path) -> CheckResult:
+    """Verify migration is aimed at legacy or incomplete document-model state.
+
+    The preflight is a safety check, so it must not send current vBRIEF
+    projects into the destructive migration path merely because a generated
+    root ``SPECIFICATION.md`` exists.
+    """
+    legacy = detect_pre_cutover_legacy(project_root)
+    if legacy:
+        return CheckResult(
+            "document-model",
+            "PASS",
+            "Legacy root artifact(s) detected: " + ", ".join(legacy) + ".",
+        )
+
+    spec_md = project_root / "SPECIFICATION.md"
+    if spec_md.is_file():
+        try:
+            content = spec_md.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            content = ""
+        if is_generated_specification_export(project_root, content):
+            missing = missing_lifecycle_folders(project_root)
+            if missing:
+                return CheckResult(
+                    "document-model",
+                    "FAIL",
+                    (
+                        "Generated SPECIFICATION.md detected "
+                        "(source: vbrief/specification.vbrief.json); "
+                        "repair missing lifecycle folder(s) instead of migrating: "
+                        + ", ".join(missing)
+                        + "."
+                    ),
+                )
+        if is_current_generated_specification(project_root, content):
+            return CheckResult(
+                "document-model",
+                "FAIL",
+                (
+                    "Current generated SPECIFICATION.md detected "
+                    "(source: vbrief/specification.vbrief.json); "
+                    "`task migrate:vbrief` is not needed."
+                ),
+            )
+
+    vbrief_root = project_root / "vbrief"
+    if vbrief_root.exists():
+        missing = missing_lifecycle_folders(project_root)
+        if missing:
+            return CheckResult(
+                "document-model",
+                "PASS",
+                "Partial vBRIEF layout detected; missing lifecycle folder(s): "
+                + ", ".join(missing)
+                + ".",
+            )
+
+    return CheckResult(
+        "document-model",
+        "WARN",
+        (
+            "No legacy root SPECIFICATION.md/PROJECT.md artifacts detected. "
+            "Migration may have nothing to do."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Aggregate evaluation
+# ---------------------------------------------------------------------------
+
+
+def evaluate(deft_root: Path, project_root: Path) -> tuple[int, list[CheckResult]]:
+    """Run every check and return ``(exit_code, results)``.
+
+    Pure function -- separated from :func:`main` so tests can drive every
+    state without ``capsys`` plumbing or env-var leak. Mirrors the
+    ``scripts/preflight_branch.py::evaluate`` surface.
+
+    Exit-code semantics:
+
+    - ``0`` -- every check PASS or WARN.
+    - ``1`` -- one or more checks FAIL.
+    - ``2`` is reserved for the CLI :func:`main` to signal config error
+      (e.g. ``--project-root`` does not exist); :func:`evaluate` itself never
+      emits 2.
+    """
+    results = [
+        check_uv(),
+        check_layout(deft_root, project_root),
+        check_document_model(project_root),
+        check_git_clean(project_root),
+    ]
+    if any(r.status == "FAIL" for r in results):
+        return 1, results
+    return 0, results
+
+
+# ---------------------------------------------------------------------------
+# CLI plumbing
+# ---------------------------------------------------------------------------
+
+
+def _format_result(result: CheckResult) -> str:
+    """Return the canonical ``CHECK <name>: <STATUS> <message>`` line."""
+    return f"CHECK {result.name}: {result.status} {result.message}"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="migrate_preflight.py",
+        description=(
+            "Agent-side environment preflight for `task migrate:vbrief` "
+            "(#793). Verifies uv on PATH, v0.20+ layout, document-model "
+            "state, and git working-tree state before destructive migration "
+            "mutations."
+        ),
+    )
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help=("Path to the consumer project root (default: current working " "directory)."),
+    )
+    parser.add_argument(
+        "--deft-root",
+        default=None,
+        help=(
+            "Path to the deft framework checkout (default: parent of this " "script's directory)."
+        ),
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress PASS lines (FAIL/WARN still print).",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # #814 + parity with scripts/preflight_branch.py: force UTF-8 stdout/stderr
+    # at entry so the gate's status lines render under Windows cp1252 default
+    # without a UnicodeEncodeError. Guarded by ``hasattr`` because reconfigure
+    # is only available on TextIOWrapper streams; ``errors='replace'`` is the
+    # belt-and-suspenders fallback per #814.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    project_root = Path(args.project_root).resolve()
+    if not project_root.exists() or not project_root.is_dir():
+        print(
+            f"ERROR: --project-root does not exist or is not a directory: " f"{project_root}",
+            file=sys.stderr,
+        )
+        return 2
+
+    if args.deft_root is None:
+        # Default: the directory containing scripts/ (this file's parent's
+        # parent). Mirrors the lookup pattern used by other framework scripts
+        # invoked via ``uv run python <script>`` from a Taskfile target.
+        deft_root = Path(__file__).resolve().parent.parent
+    else:
+        deft_root = Path(args.deft_root).resolve()
+        if not deft_root.exists() or not deft_root.is_dir():
+            print(
+                f"ERROR: --deft-root does not exist or is not a directory: " f"{deft_root}",
+                file=sys.stderr,
+            )
+            return 2
+
+    code, results = evaluate(deft_root, project_root)
+
+    for result in results:
+        if args.quiet and result.status == "PASS":
+            continue
+        stream = sys.stderr if result.status == "FAIL" else sys.stdout
+        print(_format_result(result), file=stream)
+
+    if code != 0:
+        print(
+            "migrate:preflight FAILED -- resolve the FAIL line(s) above before "
+            "re-running `task migrate:vbrief`.",
+            file=sys.stderr,
+        )
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())