engineering-process 0.1.0__py3-none-any.whl

engineering_process/runner.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+import subprocess
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .contracts import Check, ContractError, Project
+from .environment import (
+    environment_command_bindings,
+    environment_path_entries,
+    execute_command,
+)
+from .tooling import ManagedCommandBinding
+
+
+def _timestamp() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+def _git(root: Path, arguments: list[str]) -> subprocess.CompletedProcess[bytes]:
+    return subprocess.run(
+        ["git", *arguments],
+        cwd=root,
+        check=False,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        timeout=10,
+    )
+
+
+def _source_state(root: Path) -> dict[str, Any]:
+    status_result = _git(
+        root,
+        ["status", "--porcelain=v1", "-z", "--untracked-files=all"],
+    )
+    if status_result.returncode != 0:
+        return {"checkpoint": None, "dirty": None, "fingerprint": None}
+
+    head_result = _git(root, ["rev-parse", "HEAD"])
+    checkpoint = (
+        head_result.stdout.decode("ascii").strip()
+        if head_result.returncode == 0
+        else None
+    )
+    diff = b""
+    if checkpoint is not None:
+        diff_result = _git(
+            root,
+            ["diff", "--binary", "--no-ext-diff", "--no-textconv", "HEAD", "--"],
+        )
+        if diff_result.returncode != 0:
+            return {"checkpoint": checkpoint, "dirty": True, "fingerprint": None}
+        diff = diff_result.stdout
+
+    untracked_result = _git(
+        root,
+        ["ls-files", "--others", "--exclude-standard", "-z"],
+    )
+    if untracked_result.returncode != 0:
+        return {
+            "checkpoint": checkpoint,
+            "dirty": bool(status_result.stdout),
+            "fingerprint": None,
+        }
+
+    digest = hashlib.sha256()
+    digest.update(b"checkpoint\0")
+    digest.update((checkpoint or "").encode("ascii"))
+    digest.update(b"\0status\0")
+    digest.update(status_result.stdout)
+    digest.update(b"\0diff\0")
+    digest.update(diff)
+    for encoded_path in sorted(
+        path for path in untracked_result.stdout.split(b"\0") if path
+    ):
+        relative = os.fsdecode(encoded_path)
+        path = root / relative
+        digest.update(b"\0untracked\0")
+        digest.update(encoded_path)
+        try:
+            mode = path.lstat().st_mode
+            if stat.S_ISLNK(mode):
+                digest.update(b"\0symlink\0")
+                digest.update(os.fsencode(os.readlink(path)))
+            elif stat.S_ISREG(mode):
+                digest.update(b"\0file\0")
+                with path.open("rb") as source:
+                    while chunk := source.read(1024 * 1024):
+                        digest.update(chunk)
+            else:
+                digest.update(b"\0other\0")
+                digest.update(str(mode).encode("ascii"))
+        except OSError as error:
+            digest.update(b"\0unreadable\0")
+            digest.update(str(error).encode("utf-8", errors="replace"))
+    return {
+        "checkpoint": checkpoint,
+        "dirty": bool(status_result.stdout),
+        "fingerprint": f"sha256:{digest.hexdigest()}",
+    }
+
+
+def source_state(root: Path) -> dict[str, Any]:
+    """Return the checkpoint state used to bind lifecycle evidence."""
+    return _source_state(root)
+
+
+def _run_check(
+    root: Path,
+    check: Check,
+    *,
+    path_entries: tuple[Path, ...] = (),
+    command_bindings: dict[str, ManagedCommandBinding] | None = None,
+) -> dict[str, Any]:
+    print(f"[{check.identifier}] {' '.join(check.run)}", file=sys.stderr)
+    execution = execute_command(
+        root,
+        identifier=check.identifier,
+        run=check.run,
+        timeout_seconds=check.timeout_seconds,
+        working_directory=check.working_directory,
+        path_entries=path_entries,
+        command_bindings=command_bindings,
+        stream_output=True,
+    )
+    allowed = {
+        "id",
+        "status",
+        "exitCode",
+        "startedAt",
+        "durationMs",
+        "workingDirectory",
+        "command",
+        "commandSha256",
+        "error",
+        "pathEntries",
+    }
+    return {key: value for key, value in execution.items() if key in allowed}
+
+
+def run_profile(root: Path, project: Project, profile: str) -> dict[str, Any]:
+    checks = project.profiles.get(profile)
+    if checks is None:
+        available = ", ".join(sorted(project.profiles))
+        raise ContractError(
+            f"unknown profile {profile}; available profiles: {available}"
+        )
+    started = _timestamp()
+    source_before = _source_state(root)
+    path_entries = environment_path_entries(project, profile=profile)
+    command_bindings = environment_command_bindings(project, profile=profile)
+    results = [
+        _run_check(
+            root,
+            check,
+            path_entries=path_entries,
+            command_bindings=command_bindings,
+        )
+        for check in checks
+    ]
+    source_after = _source_state(root)
+    source_changed = (
+        source_before["fingerprint"] is not None
+        and source_after["fingerprint"] is not None
+        and source_before["fingerprint"] != source_after["fingerprint"]
+    )
+    status = (
+        "passed"
+        if all(item["status"] == "passed" for item in results) and not source_changed
+        else "failed"
+    )
+    return {
+        "schemaVersion": 1,
+        "project": project.identifier,
+        "profile": profile,
+        "checkpoint": source_before["checkpoint"],
+        "workingTreeDirty": source_before["dirty"],
+        "workspaceFingerprint": source_before["fingerprint"],
+        "completedWorkspaceFingerprint": source_after["fingerprint"],
+        "sourceChangedDuringVerification": source_changed,
+        "startedAt": started,
+        "completedAt": _timestamp(),
+        "status": status,
+        "checks": results,
+    }

engineering_process/runtime.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import re
+from importlib import metadata, resources
+
+from .contracts import ContractError
+
+
+PIN_PATTERN = re.compile(r"^([A-Za-z0-9][A-Za-z0-9._-]*)==([^\s]+)$")
+
+
+def runtime_dependency_pins() -> dict[str, str]:
+    text = (
+        resources.files("engineering_process")
+        .joinpath("requirements-runtime.txt")
+        .read_text(encoding="utf-8")
+    )
+    pins: dict[str, str] = {}
+    for line_number, raw_line in enumerate(text.splitlines(), 1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        match = PIN_PATTERN.fullmatch(line)
+        if match is None:
+            raise ContractError(
+                "engineering_process/requirements-runtime.txt:"
+                f"{line_number}: runtime dependencies must use exact name==version pins"
+            )
+        name, version = match.groups()
+        normalized = re.sub(r"[-_.]+", "-", name).lower()
+        if normalized in pins:
+            raise ContractError(
+                "engineering_process/requirements-runtime.txt: duplicate dependency "
+                f"{normalized}"
+            )
+        pins[normalized] = version
+    if not pins:
+        raise ContractError("runtime dependency lock must not be empty")
+    return pins
+
+
+def assert_runtime_dependencies() -> None:
+    mismatches: list[str] = []
+    for name, expected in runtime_dependency_pins().items():
+        try:
+            actual = metadata.version(name)
+        except metadata.PackageNotFoundError:
+            mismatches.append(f"{name} is missing; expected {expected}")
+            continue
+        if actual != expected:
+            mismatches.append(f"{name} is {actual}; expected {expected}")
+    if mismatches:
+        raise ContractError(
+            "engineering-process runtime dependency mismatch: " + "; ".join(mismatches)
+        )

engineering_process/skills.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+from .contracts import ContractError, SKILL_PATTERN
+
+
+FRONTMATTER = re.compile(
+    r"\A---\n(?P<header>.*?)\n---\n(?P<body>.*)\Z",
+    re.DOTALL,
+)
+FORBIDDEN_CORE_TERMS = (
+    "apply_patch",
+    "claude",
+    "codex",
+    "cursor",
+    "gemini",
+    "gpt-",
+    "reasoning_effort",
+    "spawn_agent",
+    "subagent",
+)
+MARKER_NAME = ".engineering-process.json"
+
+
+def skill_directories(root: Path) -> list[Path]:
+    if not root.is_dir():
+        raise ContractError(f"{root}: skills root does not exist")
+    return sorted(
+        path for path in root.iterdir() if path.is_dir() and (path / "SKILL.md").is_file()
+    )
+
+
+def validate_skills(root: Path, selected: tuple[str, ...] | None = None) -> list[str]:
+    directories = {path.name: path for path in skill_directories(root)}
+    names = tuple(sorted(directories)) if selected is None else selected
+    issues: list[str] = []
+    missing = sorted(set(names) - set(directories))
+    if missing:
+        issues.append(f"{root}: missing skills: {', '.join(missing)}")
+
+    for name in names:
+        directory = directories.get(name)
+        if directory is None:
+            continue
+        if SKILL_PATTERN.fullmatch(name) is None or len(name) > 64:
+            issues.append(f"{directory}: invalid skill directory name")
+        path = directory / "SKILL.md"
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError) as error:
+            issues.append(f"{path}: cannot read UTF-8 content: {error}")
+            continue
+        if text.startswith("\ufeff"):
+            issues.append(f"{path}: UTF-8 BOM is not allowed")
+        if "\r" in text:
+            issues.append(f"{path}: use LF line endings")
+        if "TODO" in text or "[TODO" in text:
+            issues.append(f"{path}: unresolved template marker")
+        if len(text.splitlines()) > 500:
+            issues.append(f"{path}: exceeds the 500-line portability limit")
+
+        match = FRONTMATTER.match(text)
+        if match is None:
+            issues.append(f"{path}: invalid YAML frontmatter boundary")
+            continue
+        header: dict[str, str] = {}
+        for line_number, line in enumerate(match.group("header").splitlines(), 2):
+            if not line or line.startswith((" ", "\t", "#")) or ":" not in line:
+                issues.append(f"{path}:{line_number}: unsupported frontmatter syntax")
+                continue
+            key, value = line.split(":", 1)
+            if key in header:
+                issues.append(f"{path}:{line_number}: duplicate frontmatter key {key}")
+            header[key] = value.strip()
+        extra = sorted(set(header) - {"name", "description"})
+        if extra:
+            issues.append(
+                f"{path}: core skills allow only name and description; found {extra}"
+            )
+        if header.get("name") != name:
+            issues.append(f"{path}: frontmatter name must match {name}")
+        description = header.get("description", "")
+        if not description or len(description) > 1024:
+            issues.append(f"{path}: description must contain 1 to 1024 characters")
+        if not match.group("body").lstrip().startswith("# "):
+            issues.append(f"{path}: body must start with an H1")
+
+        lowered = text.lower()
+        for term in FORBIDDEN_CORE_TERMS:
+            if term in lowered:
+                issues.append(f"{path}: agent-specific core term is forbidden: {term}")
+        for line_number, line in enumerate(text.splitlines(), 1):
+            if re.search(r"(?:^|[\s(])/(?:home|users|workspace|tmp)/", line.lower()):
+                issues.append(f"{path}:{line_number}: absolute local path is forbidden")
+    return issues
+
+
+def skill_digest(root: Path, selected: tuple[str, ...] | None = None) -> str:
+    issues = validate_skills(root, selected)
+    if issues:
+        raise ContractError("\n".join(issues))
+    directories = {path.name: path for path in skill_directories(root)}
+    names = tuple(sorted(directories)) if selected is None else selected
+    digest = hashlib.sha256()
+    for name in names:
+        directory = directories[name]
+        for path in sorted(item for item in directory.rglob("*") if item.is_file()):
+            if path.name == MARKER_NAME:
+                continue
+            relative = path.relative_to(root).as_posix()
+            digest.update(relative.encode("utf-8"))
+            digest.update(b"\0")
+            digest.update(path.read_bytes())
+            digest.update(b"\0")
+    return f"sha256:{digest.hexdigest()}"

engineering_process/supervision.py

@@ -0,0 +1,72 @@
+"""Portable foreground-task supervision.
+
+The public execution contract is deliberately platform-neutral.  Kernel-specific
+process containment lives in the selected backend and must not leak into consumer
+manifests, reports, or lifecycle code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import subprocess
+from typing import Mapping, Protocol
+
+
+@dataclass(frozen=True)
+class CleanupOutcome:
+    """Result of a bounded process-tree cleanup operation."""
+
+    bounded: bool
+    descendants_found: bool = False
+    error: str | None = None
+
+
+class ProcessSupervisor(Protocol):
+    """OS backend for one finite, non-interactive foreground task."""
+
+    def resolve_application(
+        self,
+        command: str,
+        *,
+        working_directory: Path,
+        environment: Mapping[str, str],
+    ) -> Path: ...
+
+    def spawn(
+        self,
+        command: tuple[str, ...],
+        *,
+        working_directory: Path,
+        environment: Mapping[str, str],
+    ) -> subprocess.Popen[bytes]: ...
+
+    def terminate(
+        self,
+        process: subprocess.Popen[bytes],
+        *,
+        grace_seconds: float,
+    ) -> CleanupOutcome: ...
+
+    def finalize(
+        self,
+        process: subprocess.Popen[bytes],
+        *,
+        grace_seconds: float,
+    ) -> CleanupOutcome: ...
+
+
+def process_supervisor(*, platform_name: str | None = None) -> ProcessSupervisor:
+    """Select the sole platform adapter used by the execution layer."""
+
+    selected = os.name if platform_name is None else platform_name
+    if selected == "posix":
+        from ._supervisor_posix import POSIX_SUPERVISOR
+
+        return POSIX_SUPERVISOR
+    if selected == "nt":
+        from ._supervisor_windows import WINDOWS_SUPERVISOR
+
+        return WINDOWS_SUPERVISOR
+    raise OSError(f"unsupported process supervision platform: {selected}")