@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/core/code-flow/scripts/codeflow/core/cf_exec_base.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""Shared execution substrate: deadline-aware argv subprocess runner.
+
+All check executors (acceptance scenarios, Spec verifiers, session
+validators) funnel through here so one entry deadline constrains the whole
+chain, commands never pass through a shell, and unrun work is reported as
+`incomplete` instead of silently skipped or falsely passed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import signal
+import shlex
+import json
+import subprocess
+import sys
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Callable, Iterator, Mapping, Optional, Sequence
+
+_EXECUTIONS: ContextVar[Optional[dict[str, dict[str, object]]]] = ContextVar("cf_executions", default=None)
+_REPORTS: ContextVar[Optional[list[dict[str, object]]]] = ContextVar("cf_reports", default=None)
+_SECRET_OPTION = re.compile(r"(?i)^--?(?:api[-_]?key|access[-_]?token|token|password|passwd|secret|credential)$")
+_SECRET_ASSIGNMENT = re.compile(r"(?i)(--?(?:api[-_]?key|access[-_]?token|token|password|passwd|secret|credential)=)([^\s]+)")
+_RUNTIME_ENV = frozenset(("CF_RUNTIME_COMMAND", "CF_RUNTIME_ACTION", "CF_CLI_VERSION"))
+
+
+def redact_sensitive_text(value: str) -> str:
+    """Hide inherited sensitive environment values from diagnostics."""
+    names = ("SECRET", "TOKEN", "PASSWORD", "PASSWD", "CREDENTIAL", "API_KEY", "PRIVATE_KEY")
+    secrets = {item for key, item in os.environ.items()
+               if item and any(name in key.upper() for name in names)}
+    for secret in sorted(secrets, key=len, reverse=True):
+        value = value.replace(secret, "[REDACTED]")
+    return _SECRET_ASSIGNMENT.sub(r"\1[REDACTED]", value)
+
+
+def _redact_sequence(values: Sequence[object]) -> list[object]:
+    result: list[object] = []
+    hide_next = False
+    for item in values:
+        if hide_next:
+            result.append("[REDACTED]")
+            hide_next = False
+            continue
+        result.append(redact_sensitive_payload(item))
+        hide_next = isinstance(item, str) and bool(_SECRET_OPTION.fullmatch(item))
+    return result
+
+
+def redact_sensitive_payload(value: object) -> object:
+    """Return a JSON-compatible copy with sensitive strings redacted."""
+    if isinstance(value, str):
+        return redact_sensitive_text(value)
+    if isinstance(value, Mapping):
+        return {key: redact_sensitive_payload(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return _redact_sequence(value)
+    return value
+
+
+@contextmanager
+def report_session() -> Iterator[list[dict[str, object]]]:
+    reports: list[dict[str, object]] = []
+    token = _REPORTS.set(reports)
+    try:
+        yield reports
+    finally:
+        _REPORTS.reset(token)
+
+
+def record_report(report: Mapping[str, object]) -> None:
+    reports = _REPORTS.get()
+    if reports is not None:
+        reports.append(dict(report))
+
+
+def report_requested() -> bool:
+    return _REPORTS.get() is not None
+
+
+@contextmanager
+def execution_session() -> Iterator[None]:
+    """Share results only inside one validation operation, never across turns."""
+    if _EXECUTIONS.get() is not None:
+        yield
+        return
+    token = _EXECUTIONS.set({})
+    try:
+        yield
+    finally:
+        _EXECUTIONS.reset(token)
+
+
+def invalidate_executions() -> None:
+    cache = _EXECUTIONS.get()
+    if cache is not None:
+        cache.clear()
+
+
+def command_environment(env: Optional[Mapping[str, str]] = None) -> dict[str, str]:
+    """Do not pass CLI dispatch metadata into user checks."""
+    environment = {key: value for key, value in os.environ.items() if key not in _RUNTIME_ENV}
+    environment.update({str(key): str(value) for key, value in (env or {}).items()})
+    return environment
+
+
+def execution_key(argv: Sequence[str], cwd: str, timeout: float,
+                  env: Optional[Mapping[str, str]] = None) -> str:
+    """Identity of a command under the current process environment."""
+    environment = command_environment(env)
+    payload: list[object] = [list(argv), str(Path(cwd).resolve()), float(timeout), sorted(environment.items())]
+    return hashlib.sha256(json.dumps(payload, ensure_ascii=False).encode()).hexdigest()
+
+
+def execution_environment_hash(env: Optional[Mapping[str, str]] = None) -> str:
+    """Bind evidence to inherited and explicit environment without exposing values."""
+    environment = command_environment(env)
+    payload = json.dumps(sorted(environment.items()), ensure_ascii=False)
+    return hashlib.sha256(payload.encode()).hexdigest()
+
+
+def remaining_seconds(deadline: Optional[float]) -> Optional[float]:
+    """Seconds left until the absolute monotonic deadline (None = unbounded)."""
+    if deadline is None:
+        return None
+    return deadline - time.monotonic()
+
+
+def build_argv(template: str, files: Sequence[str]) -> list[str]:
+    """Expand a validator command template into argv without a shell.
+
+    `{files}` must be a standalone token and expands to one argv entry per
+    file (spaces/metachars safe). Embedded usage is a config error — refusing
+    is safer than reintroducing shell splitting.
+    """
+    tokens = shlex.split(template or "")
+    if not tokens:
+        return []
+    argv: list[str] = []
+    for token in tokens:
+        if token == "{files}":
+            argv.extend(files)
+        elif "{files}" in token:
+            raise ValueError(f"validator command must keep {{files}} as a standalone token: {template!r}")
+        else:
+            argv.append(token)
+    return argv
+
+
+def run_command(
+    argv: Sequence[str],
+    cwd: str,
+    timeout: float,
+    deadline: Optional[float] = None,
+    env: Optional[Mapping[str, str]] = None,
+    identity_context: Optional[Mapping[str, object]] = None,
+) -> dict[str, object]:
+    """Run argv synchronously under timeout+deadline. Never uses a shell."""
+    key = execution_key(argv, cwd, timeout, env)
+    if identity_context:
+        payload = json.dumps(identity_context, sort_keys=True, ensure_ascii=False, default=str)
+        key = hashlib.sha256(f"{key}:{payload}".encode()).hexdigest()
+    cache = _EXECUTIONS.get()
+    fingerprint = ""
+    if cache is not None:
+        root = _fingerprint_git(cwd, "rev-parse", "--show-toplevel")
+        if root is not None and root.returncode == 0:
+            fingerprint = worktree_fingerprint(root.stdout.strip())
+    key = hashlib.sha256(f"{key}:{fingerprint}".encode()).hexdigest() if fingerprint else ""
+    if cache is not None and key and key in cache:
+        return {**cache[key], "execution_ms": 0.0, "execution_reused": True}
+    started = time.monotonic()
+    result = _execute(argv, cwd, timeout, deadline, env)
+    result["execution_ms"] = ((time.monotonic() - started) * 1000
+                              if result.get("execution_started", True) else 0.0)
+    result["execution_reused"] = False
+    if cache is not None and key and result["status"] == "ok" and result["returncode"] == 0:
+        cache[key] = result
+    return result
+
+
+def hash_worktree_paths(project_root: str, paths: Sequence[str]) -> Optional[list]:
+    """Batch-hash worktree file contents (single `git hash-object` process)."""
+    if not paths:
+        return []
+    try:
+        completed = subprocess.run(
+            ("git", "-C", project_root, "hash-object", "--stdin-paths"),
+            input="\n".join(paths) + "\n", text=True, capture_output=True, timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        sys.stderr.write(f"worktree hashing failed: {exc}\n")
+        return None
+    if completed.returncode != 0:
+        return None
+    hashes = completed.stdout.splitlines()
+    if len(hashes) != len(paths):
+        return None
+    return [(path, sha.strip()) for path, sha in zip(paths, hashes)]
+
+
+def _fingerprint_git(root: str, *arguments: str) -> Optional[subprocess.CompletedProcess]:
+    try:
+        return subprocess.run(
+            ("git", "-C", root, *arguments), text=True, encoding="utf-8",
+            capture_output=True, check=False, timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        sys.stderr.write(f"worktree fingerprint failed: {exc}\n")
+        return None
+
+
+def _runtime_path(path: str) -> bool:
+    return path.startswith(".code-flow/") or Path(path).name == ".acceptance-manifest.json"
+
+
+def _fingerprint_changes(status: str, contents: dict[str, str], include_untracked: bool,
+                         untracked_filter: Optional[Callable[[str], bool]]) -> Optional[list[str]]:
+    changed: list[str] = []
+    for line in status.splitlines():
+        code, path = line[:2], line[3:].strip()
+        if " -> " in path:
+            path = path.split(" -> ", 1)[1].strip()
+        if not path or _runtime_path(path):
+            continue
+        if path.startswith('"'):
+            return None  # Quoted/escaped paths cannot be identified reliably.
+        if code.strip() == "??":
+            if include_untracked and (untracked_filter is None or untracked_filter(path)):
+                changed.append(path)
+        elif "D" in code:
+            contents.pop(path, None)
+        else:
+            changed.append(path)
+    return changed
+
+
+def worktree_fingerprint(project_root: str, untracked_filter: Optional[Callable[[str], bool]] = None,
+                         include_untracked: bool = True) -> str:
+    """Hash real content including new files, excluding workflow runtime state.
+
+    Staging/committing unchanged bytes does not change identity. Ignored files
+    never participate; test outputs must be Git-ignored. Explicit check inputs
+    are hashed separately. Return an empty identity when it cannot be proven.
+    """
+    tree = _fingerprint_git(project_root, "ls-tree", "-r", "HEAD")
+    status = _fingerprint_git(project_root, "status", "--porcelain", "--untracked-files=all")
+    if tree is None or status is None or tree.returncode != 0 or status.returncode != 0:
+        return ""
+    contents: dict[str, str] = {}
+    for line in tree.stdout.splitlines():
+        meta, _, path = line.partition("\t")
+        fields = meta.split()
+        if path and len(fields) >= 3 and not _runtime_path(path):
+            contents[path] = fields[2]
+    changed = _fingerprint_changes(status.stdout, contents, include_untracked, untracked_filter)
+    if changed is None:
+        return ""
+    hashed = hash_worktree_paths(project_root, changed)
+    if hashed is None:
+        return ""
+    for path, sha in hashed:
+        contents[path] = sha
+    digest = hashlib.sha256()
+    for path in sorted(contents):
+        digest.update(path.encode())
+        digest.update(b"\0")
+        digest.update(contents[path].encode())
+        digest.update(b"\n")
+    return digest.hexdigest()
+
+
+def _execute(argv: Sequence[str], cwd: str, timeout: float, deadline: Optional[float],
+             env: Optional[Mapping[str, str]] = None) -> dict[str, object]:
+    remaining = remaining_seconds(deadline)
+    if remaining is not None and remaining <= 0:
+        return {"status": "deadline_exceeded", "returncode": None, "stdout": "", "stderr": "",
+                "execution_started": False}
+    # When the entry deadline is tighter than the command timeout, expiry is
+    # unexecuted work (`incomplete`), never a product failure.
+    deadline_bounded = remaining is not None and remaining <= timeout
+    effective = min(timeout, remaining) if remaining is not None else timeout
+    child_env = command_environment(env)
+    try:
+        proc = subprocess.Popen(
+            list(argv), cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+            env=child_env, start_new_session=os.name != "nt",
+        )
+        out, err = proc.communicate(timeout=max(effective, 0.01))
+    except subprocess.TimeoutExpired as exc:
+        return _timeout_result(proc, exc, deadline_bounded)
+    except OSError as exc:
+        return {"status": "spawn_error", "returncode": None, "stdout": "", "stderr": str(exc),
+                "execution_started": False}
+    return {"status": "ok", "returncode": proc.returncode, "stdout": out or "", "stderr": err or ""}
+
+
+def _timeout_result(proc: subprocess.Popen, expired: subprocess.TimeoutExpired,
+                    deadline_bounded: bool) -> dict[str, object]:
+    if os.name != "nt":
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass  # The process group already exited between timeout and kill.
+    else:
+        subprocess.run(("taskkill", "/F", "/T", "/PID", str(proc.pid)),
+                       capture_output=True, timeout=2, check=False)
+        proc.kill()
+    try:
+        out, err = proc.communicate(timeout=1)
+    except subprocess.TimeoutExpired:
+        out, err = expired.stdout, expired.stderr
+        for pipe in (proc.stdout, proc.stderr):
+            if pipe is not None:
+                pipe.close()
+    def tail(value: object) -> str:
+        return (value.decode(errors="replace") if isinstance(value, bytes) else str(value or ""))[-4000:]
+    return {"status": "deadline_exceeded" if deadline_bounded else "timeout", "returncode": None,
+            "stdout": tail(out), "stderr": tail(err)}

package/src/core/code-flow/scripts/codeflow/core/cf_fs.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""L0 filesystem primitives: text reads and atomic replacement writes."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Optional, Union
+
+PathLike = Union[str, os.PathLike]
+
+
+def read_text(path: PathLike) -> Optional[str]:
+    """Read UTF-8 text; a missing file is None, other IO errors propagate."""
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+
+
+def write_text(path: PathLike, text: str) -> None:
+    """Write UTF-8 text in place (non-atomic convenience writer)."""
+    Path(path).write_text(text, encoding="utf-8")
+
+
+def atomic_write_text(path: PathLike, text: str) -> None:
+    """Replace path with exact UTF-8 text via a temp file and os.replace.
+
+    On any failure the target keeps its previous content and the temp file is
+    removed before the original exception propagates. Disable native newline
+    translation so transaction snapshots also round-trip unchanged on Windows.
+    """
+    target = Path(path)
+    temporary = ""
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            newline="",
+            dir=str(target.parent),
+            prefix=f".{target.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temporary = handle.name
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, target)
+    except Exception:
+        if temporary:
+            try:
+                os.unlink(temporary)
+            except OSError:
+                pass  # best effort: the original failure is what callers need
+        raise

package/src/core/code-flow/scripts/codeflow/core/cf_git.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""L0 Git primitives: one implementation of the git CLI for every consumer."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Mapping, Optional, Sequence
+
+_STATUS_ARGV = ("status", "--porcelain=v1", "-z", "--untracked-files=all")
+_STATUS_NO_UNTRACKED_ARGV = ("status", "--porcelain=v1", "-z", "--untracked-files=no")
+
+
+class GitError(RuntimeError):
+    """Stable git failure carrying a machine code and the failing argv."""
+
+    def __init__(self, code: str, message: str, *, argv: Sequence[str] = (),
+                 returncode: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.argv = tuple(argv)
+        self.returncode = returncode
+
+
+def run_git(root: str, argv: Sequence[str], *, timeout: float = 30) -> str:
+    """Run git in root and return stdout; any failure raises GitError."""
+    try:
+        result = subprocess.run(
+            ("git", *argv), cwd=root, text=True, encoding="utf-8",
+            capture_output=True, check=False, timeout=timeout,
+        )
+    except OSError as exc:
+        raise GitError("git_unavailable", str(exc), argv=argv) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise GitError("git_timeout", f"git timed out after {timeout}s", argv=argv) from exc
+    if result.returncode != 0:
+        message = result.stderr.strip() or "Git command failed"
+        raise GitError("git_error", message, argv=argv, returncode=result.returncode)
+    return result.stdout
+
+
+def _status_name(code: str) -> str:
+    if code == "??":
+        return "untracked"
+    if "D" in code:
+        return "deleted"
+    if "A" in code:
+        return "added"
+    if "M" in code:
+        return "modified"
+    return "changed"
+
+
+def changed_entries(root: str, *, include_untracked: bool = True) -> Mapping[str, str]:
+    """Working-tree changes keyed by relative path; renames also name the old path."""
+    argv = _STATUS_ARGV if include_untracked else _STATUS_NO_UNTRACKED_ARGV
+    records = run_git(root, argv).split("\0")
+    changes: dict[str, str] = {}
+    index = 0
+    while index < len(records) and records[index]:
+        record = records[index]
+        if len(record) < 4:
+            raise GitError("invalid_git_status", record, argv=argv)
+        code, path = record[:2], record[3:]
+        index += 1
+        if "R" in code or "C" in code:
+            # porcelain -z rename/copy emits two records: "XY <new>" then "<old>"
+            if index >= len(records) or not records[index]:
+                raise GitError("invalid_git_status", f"{code} {path}", argv=argv)
+            old_path = records[index]
+            index += 1
+            changes[path] = _status_name(code)
+            changes[old_path] = "deleted"
+            continue
+        changes[path] = _status_name(code)
+    return changes
+
+
+def changed_files(root: str, *, include_untracked: bool = True) -> tuple[str, ...]:
+    """Relative paths with uncommitted changes (working tree and index)."""
+    return tuple(changed_entries(root, include_untracked=include_untracked))
+
+
+def tracked_files(root: str) -> tuple[str, ...]:
+    """Tracked relative paths; non-git projects read as an empty set."""
+    try:
+        output = run_git(root, ("ls-files",))
+    except GitError:
+        return ()
+    return tuple(
+        line.replace("\\", "/").strip() for line in output.splitlines() if line.strip()
+    )

package/src/core/code-flow/scripts/{cf_log.py → codeflow/core/cf_log.py}

@@ -38,7 +38,8 @@ KNOWN_EVENTS = (
 )
 
 
-def _log(msg: str) -> None:
+def warn(msg: str) -> None:
+    """Write one diagnostic line to stderr; stdout stays reserved for protocol JSON."""
     sys.stderr.write(f"[cf-log] {msg}\n")
 
 
@@ -59,9 +60,14 @@ def _rotate_if_needed(project_root: str, path: str) -> None:
     now = datetime.now()
     month_dir = _archive_dir(project_root, now.strftime("%Y-%m"))
     os.makedirs(month_dir, exist_ok=True)
-    target = os.path.join(
-        month_dir, f"session-log-{now.strftime('%Y%m%dT%H%M%S')}.jsonl"
-    )
+    stamp = now.strftime("%Y%m%dT%H%M%S")
+    target = os.path.join(month_dir, f"session-log-{stamp}.jsonl")
+    # Second-resolution names collide when a log rotates twice quickly; never
+    # overwrite an existing archive.
+    counter = 1
+    while os.path.exists(target):
+        counter += 1
+        target = os.path.join(month_dir, f"session-log-{stamp}-{counter}.jsonl")
     os.replace(path, target)
 
 
@@ -85,7 +91,7 @@ def append_event(project_root: str, event: str, data: dict, sid: str) -> bool:
             f.write(line + "\n")
         return True
     except Exception as exc:
-        _log(f"append_event failed: {exc}")
+        warn(f"append_event failed: {exc}")
         return False
 
 
@@ -112,7 +118,7 @@ def _candidate_files(project_root: str, days: int) -> list:
             except ValueError:
                 continue
             # keep a month if any part of it can fall inside the window
-            if month_start >= cutoff.replace(day=1):
+            if month_start >= cutoff.replace(day=1, hour=0, minute=0, second=0, microsecond=0):
                 month_dir = os.path.join(base, month)
                 paths.extend(
                     os.path.join(month_dir, name)
@@ -149,6 +155,6 @@ def read_events(project_root: str, days: int = 30, events: tuple = ()) -> list:
                         continue
                     out.append(item)
         except Exception as exc:
-            _log(f"read_events skipped {path}: {exc}")
+            warn(f"read_events skipped {path}: {exc}")
             continue
     return out

package/src/core/code-flow/scripts/codeflow/core/cf_markdown.py

@@ -0,0 +1,77 @@
+"""Shared Markdown primitives: frontmatter splitting and pipe-table headers.
+
+Pure parsing only — no I/O, no schema knowledge. Feature modules keep their own
+field aliases and value semantics.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Mapping, Optional, Sequence
+
+
+_FRONTMATTER_RE = re.compile(r"\A---[ \t]*\n(.*?)\n---[ \t]*\n?", re.DOTALL)
+_SEPARATOR_CELL_RE = re.compile(r"^:?-{2,}:?$")
+
+
+def parse_frontmatter(text: str) -> tuple[Mapping[str, object], str]:
+    """Split optional frontmatter into flat metadata + body.
+
+    Parses only flat `key: value` string pairs — enough for `description:` —
+    so the hook hot path never needs pyyaml for this. Content without
+    frontmatter returns ({}, text) unchanged.
+    """
+    if not isinstance(text, str):
+        return {}, text
+    match = _FRONTMATTER_RE.match(text)
+    if match is None:
+        return {}, text
+    meta: dict[str, object] = {}
+    for line in match.group(1).splitlines():
+        key, sep, value = line.partition(":")
+        if not sep:
+            continue
+        key = key.strip()
+        if key:
+            meta[key] = value.strip().strip('"').strip("'")
+    return meta, text[match.end():]
+
+
+def frontmatter_block(text: str) -> Optional[str]:
+    """Return the raw frontmatter text (no delimiters), or None when absent."""
+    if not isinstance(text, str):
+        return None
+    match = _FRONTMATTER_RE.match(text)
+    return match.group(1) if match else None
+
+
+def table_cells(line: str) -> tuple[str, ...]:
+    """Split one pipe-table line into trimmed cells; () for non-table lines."""
+    stripped = line.strip()
+    if not stripped.startswith("|"):
+        return ()
+    return tuple(cell.strip() for cell in stripped.strip("|").split("|"))
+
+
+def is_separator_row(cells: Sequence[str]) -> bool:
+    """True for the `|---|:--:|` alignment row."""
+    return bool(cells) and all(_SEPARATOR_CELL_RE.match(cell.replace(" ", "")) for cell in cells)
+
+
+def table_columns(lines: Sequence[str]) -> Mapping[str, int]:
+    """Map header names to column offsets; {} when no header row exists."""
+    for line in lines:
+        cells = table_cells(line)
+        if not cells or is_separator_row(cells):
+            continue
+        return {cell: index for index, cell in enumerate(cells)}
+    return {}
+
+
+def column_index(header: Sequence[str], *names: str) -> int:
+    """Lowest header index containing any alias (case-insensitive), else -1."""
+    for index, cell in enumerate(header):
+        lowered = cell.lower()
+        if any(name.lower() in lowered for name in names):
+            return index
+    return -1

package/src/core/code-flow/scripts/codeflow/core/cf_native_paths.py

@@ -0,0 +1,26 @@
+"""Native runtime project discovery and all-or-nothing path validation."""
+import os
+from pathlib import Path
+from codeflow.core.cf_patch import FileOperation
+
+
+def project_root(cwd: str) -> str:
+    directory = Path(cwd).absolute()
+    for candidate in (directory, *directory.parents):
+        if (candidate / ".code-flow/config.yml").is_file():
+            return str(candidate)
+    return ""
+
+
+def validated_paths(root: str, cwd: str, operations: tuple[FileOperation, ...]) -> tuple[tuple[str, bool], ...]:
+    paths: dict[str, bool] = {}
+    for operation in operations:
+        for path, deleted in ((operation.path, operation.kind in {"delete", "move"}),
+                              (operation.destination, False)):
+            if not path:
+                continue
+            absolute = Path(os.path.abspath(os.path.join(cwd, path)))
+            if not absolute.is_relative_to(Path(root)) or not absolute.resolve().is_relative_to(Path(root).resolve()):
+                raise ValueError(f"patch path is outside project: {path}")
+            paths[str(absolute)] = deleted
+    return tuple(paths.items())

package/src/core/code-flow/scripts/codeflow/core/cf_patch.py

@@ -0,0 +1,33 @@
+"""Shared structured patch parser for native platform entries."""
+from dataclasses import dataclass, replace
+
+
+@dataclass(frozen=True)
+class FileOperation:
+    kind: str
+    path: str
+    destination: str = ""
+
+
+def parse_patch(command: str) -> tuple[FileOperation, ...]:
+    lines = command.splitlines()
+    if len(lines) < 3 or lines[0] != "*** Begin Patch" or lines[-1] != "*** End Patch":
+        raise ValueError("patch must contain a complete Begin/End envelope")
+    operations: list[FileOperation] = []
+    headers = {"*** Add File: ": "add", "*** Update File: ": "update", "*** Delete File: ": "delete"}
+    for line in lines[1:-1]:
+        header = next((prefix for prefix in headers if line.startswith(prefix)), "")
+        if header:
+            path = line[len(header):]
+            if not path or "\x00" in path:
+                raise ValueError("patch file path is empty or invalid")
+            operations.append(FileOperation(headers[header], path))
+        elif line.startswith("*** Move to: "):
+            if not operations or operations[-1].kind != "update" or not line[13:]:
+                raise ValueError("Move to must follow an Update File")
+            operations[-1] = replace(operations[-1], kind="move", destination=line[13:])
+        elif not operations or (line and not line.startswith(("+", "-", " ", "@@", "*** End of File"))):
+            raise ValueError("unrecognized patch syntax")
+    if not operations:
+        raise ValueError("patch contains no file operations")
+    return tuple(operations)