@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/_project_definition_io.py

@@ -1,164 +0,0 @@
-"""Atomic PROJECT-DEFINITION read/write helpers (D14 / #1133).
-
-Shared by ``scripts/triage_subscribe.py`` and
-``scripts/triage_scope_drift.py`` for the typed-policy mutation
-surface introduced by D14 (subscribe / unsubscribe / ignore verbs).
-
-Mirrors the atomic-write pattern in ``scripts/cache.py::_atomic_write_text``
-(tempfile + ``os.replace``) so a crash mid-write leaves the file
-untouched. The lifecycle file (``vbrief/PROJECT-DEFINITION.vbrief.json``)
-is the only file these helpers touch; the typed policy block lives at
-``data["plan"]["policy"]``.
-
-Pure stdlib. No third-party dependencies.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import json
-import os
-import sys
-import tempfile
-import threading
-import time
-from collections.abc import Iterator
-from pathlib import Path
-from typing import Any
-
-_PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json"
-_mutation_thread_lock = threading.Lock()
-
-
-class ProjectDefinitionIOError(Exception):
-    """Raised when the PROJECT-DEFINITION file is missing or malformed."""
-
-
-def project_definition_path(project_root: Path) -> Path:
-    return project_root / _PROJECT_DEFINITION_REL_PATH
-
-
-@contextlib.contextmanager
-def project_definition_mutation_lock(project_root: Path) -> Iterator[None]:
-    """Serialise PROJECT-DEFINITION read-modify-write critical sections.
-
-    The sidecar ``<file>.lock`` is removed on exit -- on the happy path AND
-    on an exception -- so a clean mutation never leaves
-    ``vbrief/PROJECT-DEFINITION.vbrief.json.lock`` behind for ``git add -A``
-    to trap on the next chore commit (#1311). The unlink runs in a
-    ``finally`` while the in-process ``_mutation_thread_lock`` is still held,
-    so no concurrent in-process acquirer can race it, and is best-effort: a
-    cross-process holder (Windows keeps the open file locked) or a benign
-    POSIX unlink race simply leaves the (gitignored) sidecar in place rather
-    than raising.
-    """
-    path = project_definition_path(project_root)
-    lock_path = path.parent / (path.name + ".lock")
-    lock_path.parent.mkdir(parents=True, exist_ok=True)
-    with _mutation_thread_lock:
-        try:
-            with open(lock_path, "a+b") as fh:
-                if not lock_path.stat().st_size:
-                    fh.write(b"\0")
-                    fh.flush()
-                fh.seek(0)
-                if sys.platform == "win32":
-                    import msvcrt
-
-                    acquired = False
-                    deadline = time.monotonic() + 30.0
-                    while True:
-                        try:
-                            msvcrt.locking(fh.fileno(), msvcrt.LK_NBLCK, 1)
-                            acquired = True
-                            break
-                        except OSError:
-                            if time.monotonic() > deadline:
-                                raise
-                            time.sleep(0.02)
-                    try:
-                        yield
-                    finally:
-                        if acquired:
-                            fh.seek(0)
-                            with contextlib.suppress(OSError):
-                                msvcrt.locking(fh.fileno(), msvcrt.LK_UNLCK, 1)
-                else:
-                    import fcntl
-
-                    fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
-                    try:
-                        yield
-                    finally:
-                        fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
-        finally:
-            # The sidecar handle is closed by the `with open(...)` block above
-            # BEFORE this unlink (Windows refuses to delete an open file); the
-            # unlink is held under _mutation_thread_lock so it cannot race an
-            # in-process re-acquire, and is best-effort across processes
-            # (#1311 -- do not leave PROJECT-DEFINITION.vbrief.json.lock behind).
-            with contextlib.suppress(OSError):
-                lock_path.unlink()
-
-
-def load_project_definition_for_mutation(
-    project_root: Path,
-) -> tuple[dict[str, Any], Path]:
-    """Read PROJECT-DEFINITION.vbrief.json and return ``(data, path)``.
-
-    Raises :class:`ProjectDefinitionIOError` if the file is missing or
-    cannot be parsed as a JSON object. The returned dict is a mutable
-    deep copy of the on-disk state; callers mutate it and pass it to
-    :func:`atomic_write_project_definition` to persist.
-    """
-    path = project_definition_path(project_root)
-    if not path.is_file():
-        raise ProjectDefinitionIOError(
-            f"PROJECT-DEFINITION not found at {path}; run task triage:welcome / "
-            "task triage:bootstrap to scaffold one first."
-        )
-    try:
-        raw = path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise ProjectDefinitionIOError(
-            f"Could not read PROJECT-DEFINITION at {path}: {exc}"
-        ) from exc
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError as exc:
-        raise ProjectDefinitionIOError(
-            f"PROJECT-DEFINITION at {path} is not valid JSON: {exc}"
-        ) from exc
-    if not isinstance(data, dict):
-        raise ProjectDefinitionIOError(
-            f"PROJECT-DEFINITION at {path} top-level value is not a JSON object"
-        )
-    return data, path
-
-
-def atomic_write_project_definition(path: Path, data: dict[str, Any]) -> None:
-    """Atomically write ``data`` to ``path`` as pretty-printed JSON.
-
-    Uses a tempfile + ``os.replace`` so the file is either fully
-    written or completely unchanged. The parent directory is created
-    on demand for first-write scenarios (fresh consumer installs).
-    """
-    path.parent.mkdir(parents=True, exist_ok=True)
-    payload = json.dumps(data, indent=2, ensure_ascii=False, sort_keys=False)
-    fd, tmp_name = tempfile.mkstemp(
-        prefix=path.name + ".", suffix=".tmp", dir=str(path.parent)
-    )
-    tmp = Path(tmp_name)
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8", newline="") as fh:
-            fh.write(payload)
-            if not payload.endswith("\n"):
-                fh.write("\n")
-            fh.flush()
-            with contextlib.suppress(OSError):
-                os.fsync(fh.fileno())
-        os.replace(tmp, path)
-    except BaseException:
-        with contextlib.suppress(FileNotFoundError):
-            tmp.unlink()
-        raise

package/scripts/_relocate_snapshot.py

@@ -1,209 +0,0 @@
-"""_relocate_snapshot.py -- snapshot tarball helpers for scripts/relocate.py (#992 PR2).
-
-Extracted from :mod:`scripts.relocate` to keep the parent under the deft
-1000-line MUST limit. Mirrors the
-``scripts/cache.py`` / ``scripts/_cache_validate.py`` /
-``scripts/_cache_fetch.py`` split pattern.
-
-Public API:
-
-- :func:`create_snapshot`  -- tar the consumer pre-relocate state.
-- :func:`extract_snapshot` -- untar a previously-written snapshot back.
-- :func:`latest_snapshot`  -- newest snapshot in ``.deft-cache/``.
-- :func:`snapshot_path`    -- conventional path for the next snapshot.
-- :func:`snapshot_dir`     -- ``<project-root>/.deft-cache``.
-- :func:`utc_timestamp`    -- ``YYYYMMDDTHHMMSSZ`` for snapshot filenames.
-
-The snapshot is gzip-compressed tar with members rooted at
-``project_root`` so ``tar.extractall(project_root, filter='data')``
-restores them directly into place.
-"""
-
-from __future__ import annotations
-
-import shutil
-import tarfile
-from datetime import UTC, datetime
-from pathlib import Path
-
-CANONICAL_FRAMEWORK_DIR: str = ".deft/core"
-LEGACY_FRAMEWORK_DIR: str = "deft"
-SNAPSHOT_PREFIX: str = "relocate-snapshot-"
-
-#: Project-relative paths the snapshot tarball is allowed to capture or
-#: leave residue for. The rollback path uses this set to clean any tracked
-#: path that was NOT captured in the snapshot (i.e. was created by the
-#: relocator post-snapshot) so the rollback restores a byte-equivalent
-#: pre-relocate state for tracked files. F3 fix (#1015): without this
-#: set the relocator-created ``.gitignore`` was left as residue after a
-#: rollback when the pre-relocate project had no ``.gitignore``.
-ROLLBACK_TRACKED_PATHS: tuple[str, ...] = (
-    LEGACY_FRAMEWORK_DIR,
-    CANONICAL_FRAMEWORK_DIR,
-    "AGENTS.md",
-    ".gitignore",
-)
-
-
-__all__ = [
-    "CANONICAL_FRAMEWORK_DIR",
-    "LEGACY_FRAMEWORK_DIR",
-    "ROLLBACK_TRACKED_PATHS",
-    "SNAPSHOT_PREFIX",
-    "SnapshotError",
-    "create_snapshot",
-    "extract_snapshot",
-    "latest_snapshot",
-    "snapshot_dir",
-    "snapshot_path",
-    "utc_timestamp",
-]
-
-
-class SnapshotError(RuntimeError):
-    """Snapshot create / extract failure (raised with a descriptive message)."""
-
-    def __init__(self, message: str, *, exit_code: int = 1) -> None:
-        super().__init__(message)
-        self.exit_code = exit_code
-
-
-def utc_timestamp() -> str:
-    """Return ``YYYYMMDDTHHMMSSZ`` suitable for the snapshot filename."""
-    return datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
-
-
-def snapshot_dir(project_root: Path) -> Path:
-    return project_root / ".deft-cache"
-
-
-def snapshot_path(project_root: Path, *, timestamp: str | None = None) -> Path:
-    stamp = timestamp or utc_timestamp()
-    return snapshot_dir(project_root) / f"{SNAPSHOT_PREFIX}{stamp}.tar.gz"
-
-
-def latest_snapshot(project_root: Path) -> Path | None:
-    sdir = snapshot_dir(project_root)
-    if not sdir.is_dir():
-        return None
-    candidates = sorted(sdir.glob(f"{SNAPSHOT_PREFIX}*.tar.gz"))
-    return candidates[-1] if candidates else None
-
-
-def create_snapshot(
-    project_root: Path,
-    *,
-    target: Path | None = None,
-    timestamp: str | None = None,
-) -> Path:
-    """Tarball the consumer's pre-relocate state into ``.deft-cache/``.
-
-    Captures (when present): every path in :data:`ROLLBACK_TRACKED_PATHS`
-    -- ``<project-root>/deft/``, ``<project-root>/.deft/core/``,
-    ``<project-root>/AGENTS.md``, and ``<project-root>/.gitignore``. The
-    tarball uses paths relative to ``project_root`` so
-    :func:`extract_snapshot` restores them directly. Tracked paths that
-    DID NOT exist pre-relocate are intentionally absent from the tarball;
-    the rollback path uses that absence to recognise relocator-created
-    residue and remove it (F3 fix #1015).
-    """
-    out = target or snapshot_path(project_root, timestamp=timestamp)
-    out.parent.mkdir(parents=True, exist_ok=True)
-    members = [project_root / name for name in ROLLBACK_TRACKED_PATHS]
-    captured = [m for m in members if m.exists()]
-    with tarfile.open(out, "w:gz") as tar:
-        for member in captured:
-            try:
-                arcname = member.relative_to(project_root).as_posix()
-            except ValueError:
-                arcname = member.name
-            tar.add(str(member), arcname=arcname, recursive=True)
-    return out
-
-
-def extract_snapshot(
-    project_root: Path,
-    *,
-    snapshot: Path | None = None,
-) -> Path:
-    """Extract ``snapshot`` (or the most recent) back into ``project_root``.
-
-    Tracked-paths contract (F3 fix, #1015): every path in
-    :data:`ROLLBACK_TRACKED_PATHS` is reset before extraction --
-
-    - paths captured in the tarball are removed first (so a
-      partially-relocated tree doesn't carry stale bytes forward) then
-      re-extracted, and
-    - paths NOT captured in the tarball are removed unconditionally
-      because the relocator created them post-snapshot (e.g. a
-      relocator-created ``.gitignore`` when the pre-relocate project had
-      none). Without this step, ``git status --porcelain`` post-rollback
-      would surface ``?? .gitignore`` and break the byte-equivalent
-      pre-relocate-state contract.
-
-    The ``.deft-cache/`` directory (which hosts the snapshot tarball
-    itself) is intentionally NOT in the tracked-paths set -- removing it
-    would break re-rollback against the same snapshot.
-
-    Returns the snapshot path that was actually extracted (handy for the
-    operator-facing log line).
-    """
-    chosen = snapshot or latest_snapshot(project_root)
-    if chosen is None:
-        raise SnapshotError(
-            f"no snapshot found under {snapshot_dir(project_root)} -- "
-            "rollback requires either --snapshot PATH or a prior wipe-and-reinstall"
-        )
-    if not chosen.is_file():
-        raise SnapshotError(
-            f"snapshot path {chosen} does not exist or is not a file",
-            exit_code=2,
-        )
-
-    # F3 residue fix (#1015): clear EVERY tracked path before extracting
-    # the tarball. Captured tracked paths are then restored by
-    # ``extractall``; uncaptured tracked paths (relocator-created
-    # post-snapshot residue, e.g. a fresh ``.gitignore`` written by
-    # ``_ensure_gitignore_lines`` when the pre-relocate project had
-    # none) stay absent so ``git status --porcelain`` is clean.
-    # Symmetrically removing captured paths up front also guarantees no
-    # partially-relocated bytes survive into the rolled-back state.
-    for name in ROLLBACK_TRACKED_PATHS:
-        target = project_root / name
-        if target.is_dir() and not target.is_symlink():
-            shutil.rmtree(target)
-        elif target.is_file() or target.is_symlink():
-            target.unlink()
-
-    with tarfile.open(chosen, "r:gz") as tar:
-        _safe_extract(tar, project_root)
-    return chosen
-
-
-def _captured_top_level_names(snapshot: Path) -> set[str]:
-    """Return the set of top-level paths captured in ``snapshot``.
-
-    Used by :func:`extract_snapshot` to distinguish tracked paths that
-    were captured (and thus will be restored by the tarball extract)
-    from tracked paths that the relocator created post-snapshot (which
-    must be removed without restoration to honour the byte-equivalent
-    pre-relocate-state contract -- F3 fix #1015).
-    """
-    with tarfile.open(snapshot, "r:gz") as tar:
-        names = tar.getnames()
-    return {n.split("/", 1)[0] for n in names if n}
-
-
-def _safe_extract(tar: tarfile.TarFile, dest: Path) -> None:
-    """Reject path traversal before extracting (per Python 3.12 best practice)."""
-    dest_resolved = dest.resolve()
-    for member in tar.getmembers():
-        member_target = (dest / member.name).resolve()
-        try:
-            member_target.relative_to(dest_resolved)
-        except ValueError:
-            raise SnapshotError(
-                f"snapshot member {member.name!r} would extract outside {dest}",
-                exit_code=2,
-            ) from None
-    tar.extractall(dest, filter="data")  # type: ignore[arg-type]