@michaelxwb/code-flow 0.8.1 → 1.0.0

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

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

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

@@ -1,92 +0,0 @@
-#!/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/codeflow/core/cf_log.py

@@ -1,160 +0,0 @@
-#!/usr/bin/env python3
-"""Session activity log: JSONL event stream for the quality-loop feature.
-
-Design contract (spec-quality-loop.design.md §3.3):
-- One event per line: {"v", "ts", "sid", "event", "data"}.
-- append is O(1) single-write; failures are swallowed (stderr only) so the
-  hook protocol is never broken by logging (RULE-01 / E-03).
-- Reads are line-tolerant: corrupt lines are skipped, never raised (RULE-05).
-- Rotation: when the live file reaches MAX_BYTES it is archived to
-  sessions/YYYY-MM/session-log-<ts>.jsonl and a fresh file starts (B-02).
-"""
-import json
-import os
-import sys
-from datetime import datetime, timedelta
-
-LOG_NAME = ".session-log.jsonl"
-SESSIONS_DIR = "sessions"
-MAX_BYTES = 5 * 1024 * 1024
-SCHEMA_VERSION = 1
-
-KNOWN_EVENTS = (
-    "inject",
-    "edit",
-    "violation",
-    "correction",
-    "false_positive",
-    "degrade",
-    "stop_check",
-    "spec_candidate",
-    "spec_bound",
-    "spec_applied",
-    "spec_read",
-    "spec_drift",
-    "spec_gate",
-    "late_violation",
-    "metrics_degraded",
-)
-
-
-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")
-
-
-def log_path(project_root: str) -> str:
-    return os.path.join(project_root, ".code-flow", LOG_NAME)
-
-
-def _archive_dir(project_root: str, month: str) -> str:
-    return os.path.join(project_root, ".code-flow", SESSIONS_DIR, month)
-
-
-def _rotate_if_needed(project_root: str, path: str) -> None:
-    try:
-        if os.path.getsize(path) < MAX_BYTES:
-            return
-    except OSError:
-        return
-    now = datetime.now()
-    month_dir = _archive_dir(project_root, now.strftime("%Y-%m"))
-    os.makedirs(month_dir, exist_ok=True)
-    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)
-
-
-def append_event(project_root: str, event: str, data: dict, sid: str) -> bool:
-    """Append one event line. Never raises; returns False on failure (E-03)."""
-    try:
-        path = log_path(project_root)
-        os.makedirs(os.path.dirname(path), exist_ok=True)
-        _rotate_if_needed(project_root, path)
-        line = json.dumps(
-            {
-                "v": SCHEMA_VERSION,
-                "ts": datetime.now().isoformat(timespec="seconds"),
-                "sid": sid,
-                "event": event,
-                "data": data or {},
-            },
-            ensure_ascii=False,
-        )
-        with open(path, "a", encoding="utf-8") as f:
-            f.write(line + "\n")
-        return True
-    except Exception as exc:
-        warn(f"append_event failed: {exc}")
-        return False
-
-
-def degrade(project_root: str, component: str, error: object, sid: str = "") -> None:
-    """Record a degrade event (FEAT-02). Never raises — degrading the
-    degrade-logger itself must stay invisible (RULE-01)."""
-    append_event(
-        project_root,
-        "degrade",
-        {"component": component, "error": str(error)[:200]},
-        sid,
-    )
-
-
-def _candidate_files(project_root: str, days: int) -> list:
-    """Live log + archived months overlapping the [now-days, now] window."""
-    paths = []
-    base = os.path.join(project_root, ".code-flow", SESSIONS_DIR)
-    if os.path.isdir(base):
-        cutoff = datetime.now() - timedelta(days=days)
-        for month in sorted(os.listdir(base)):
-            try:
-                month_start = datetime.strptime(month, "%Y-%m")
-            except ValueError:
-                continue
-            # keep a month if any part of it can fall inside the window
-            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)
-                    for name in sorted(os.listdir(month_dir))
-                    if name.endswith(".jsonl")
-                )
-    live = log_path(project_root)
-    if os.path.exists(live):
-        paths.append(live)
-    return paths
-
-
-def read_events(project_root: str, days: int = 30, events: tuple = ()) -> list:
-    """Read events within the window, oldest first. Corrupt lines skipped."""
-    cutoff = (datetime.now() - timedelta(days=days)).isoformat(timespec="seconds")
-    wanted = set(events) if events else None
-    out = []
-    for path in _candidate_files(project_root, days):
-        try:
-            with open(path, "r", encoding="utf-8") as f:
-                for raw in f:
-                    raw = raw.strip()
-                    if not raw:
-                        continue
-                    try:
-                        item = json.loads(raw)
-                    except Exception:
-                        continue
-                    if not isinstance(item, dict) or "event" not in item:
-                        continue
-                    if wanted is not None and item["event"] not in wanted:
-                        continue
-                    if str(item.get("ts", "")) < cutoff:
-                        continue
-                    out.append(item)
-        except Exception as exc:
-            warn(f"read_events skipped {path}: {exc}")
-            continue
-    return out