specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/artifacts.py

@@ -0,0 +1,303 @@
+"""Immutable run-artifact addressing and integrity verification."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from ._config.config_models import PhaseConfig, PipelineConfig
+from .errors import SpecromancyError
+from .exit_codes import ExitCode
+from .hashing import normalize_relative_path, resolve_relative_path, sha256_bytes, sha256_file
+
+
+class ArtifactError(SpecromancyError):
+    """An expected missing, unsafe, or inconsistent artifact failure."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        diagnostic_code: str,
+        details: dict[str, Any] | None = None,
+        not_found: bool = False,
+    ) -> None:
+        values = {"error_code": diagnostic_code}
+        if details:
+            values.update(details)
+        super().__init__(
+            ExitCode.NOT_FOUND if not_found else ExitCode.INTERNAL_ERROR,
+            message,
+            values,
+        )
+        self.diagnostic_code = diagnostic_code
+
+
+def render_output_path(
+    pipeline: PipelineConfig, phase: PhaseConfig, visit_number: int
+) -> str:
+    """Render a phase's globally addressed output path inside a run."""
+
+    if visit_number < 1:
+        raise ValueError("visit number must be positive")
+    try:
+        output_name = phase.output_name.format(
+            visit=visit_number,
+            phase=phase.id,
+            output_name="output.md",
+        )
+        rendered = pipeline.artifact_pattern.format(
+            visit=visit_number,
+            phase=phase.id,
+            output_name=output_name,
+        )
+        return normalize_relative_path(rendered)
+    except (KeyError, IndexError, ValueError) as exc:
+        raise ArtifactError(
+            f"could not render output path for phase {phase.id!r}: {exc}",
+            diagnostic_code="invalid-output-path",
+            details={"phase": phase.id, "visit_number": visit_number},
+        ) from exc
+
+
+def artifact_record(
+    run_directory: Path,
+    path: str,
+    *,
+    reference: str | None = None,
+) -> dict[str, Any]:
+    """Create a literal path/hash record for an existing regular artifact."""
+
+    resolved = _required_regular_artifact(run_directory, path)
+    record: dict[str, Any] = {
+        "path": normalize_relative_path(path),
+        "sha256": sha256_file(resolved),
+    }
+    if reference is not None:
+        record["reference"] = reference
+    return record
+
+
+def resolve_input_reference(
+    reference: str,
+    manifest: dict[str, Any],
+    run_directory: Path,
+) -> dict[str, Any]:
+    """Resolve a symbolic input to a completed, immutable artifact record."""
+
+    source: dict[str, Any] | None = None
+    if reference == "request":
+        value = manifest.get("request")
+        if isinstance(value, dict):
+            source = value
+    elif reference.startswith("latest:"):
+        phase_id = reference.removeprefix("latest:")
+        if not phase_id:
+            return _invalid_reference(reference)
+        for visit in reversed(manifest.get("visits", [])):
+            if (
+                isinstance(visit, dict)
+                and visit.get("phase_id") == phase_id
+                and visit.get("status") == "completed"
+            ):
+                value = visit.get("output")
+                if isinstance(value, dict):
+                    source = value
+                break
+    elif reference.startswith("visit:"):
+        raw_number = reference.removeprefix("visit:")
+        if not raw_number.isascii() or not raw_number.isdigit() or int(raw_number) < 1:
+            return _invalid_reference(reference)
+        number = int(raw_number)
+        for visit in manifest.get("visits", []):
+            if (
+                isinstance(visit, dict)
+                and visit.get("ordinal") == number
+                and visit.get("status") == "completed"
+            ):
+                value = visit.get("output")
+                if isinstance(value, dict):
+                    source = value
+                break
+    else:
+        return _invalid_reference(reference)
+
+    if source is None:
+        raise ArtifactError(
+            f"artifact reference is not available: {reference}",
+            diagnostic_code="artifact-not-found",
+            details={"reference": reference},
+            not_found=True,
+        )
+    path = source.get("path")
+    expected_hash = source.get("sha256")
+    if not isinstance(path, str) or not isinstance(expected_hash, str):
+        raise ArtifactError(
+            f"artifact record for {reference!r} is incomplete",
+            diagnostic_code="invalid-artifact-record",
+            details={"reference": reference},
+        )
+    actual = artifact_record(run_directory, path, reference=reference)
+    if actual["sha256"] != expected_hash:
+        raise ArtifactError(
+            f"artifact changed after it became immutable: {path}",
+            diagnostic_code="artifact-hash-mismatch",
+            details={
+                "path": path,
+                "expected": expected_hash,
+                "actual": actual["sha256"],
+            },
+        )
+    return actual
+
+
+def verify_manifest_artifacts(
+    manifest: dict[str, Any], run_directory: Path
+) -> tuple[dict[str, Any], ...]:
+    """Verify the request and every completed visit output from disk alone."""
+
+    records: list[dict[str, Any]] = []
+    request = manifest.get("request")
+    if not isinstance(request, dict):
+        raise ArtifactError(
+            "run manifest has no request artifact record",
+            diagnostic_code="invalid-artifact-record",
+        )
+    records.append(_verify_record(request, run_directory, "request"))
+    for visit in manifest.get("visits", []):
+        if not isinstance(visit, dict) or visit.get("status") != "completed":
+            continue
+        records.append(
+            _verify_record(
+                visit.get("output"),
+                run_directory,
+                f"visit:{visit.get('ordinal')}",
+            )
+        )
+    return tuple(records)
+
+
+def write_artifact_atomic(
+    run_directory: Path,
+    path: str,
+    content: str | bytes,
+    *,
+    replace: bool = False,
+) -> str:
+    """Atomically write an artifact, refusing accidental replacement by default."""
+
+    normalized = normalize_relative_path(path)
+    try:
+        target = resolve_relative_path(run_directory, normalized)
+    except (OSError, ValueError) as exc:
+        raise ArtifactError(
+            f"artifact path escapes the run directory: {path!r}",
+            diagnostic_code="unsafe-artifact-path",
+            details={"path": path},
+        ) from exc
+    if target.exists() and not replace:
+        raise ArtifactError(
+            f"artifact already exists and will not be overwritten: {normalized}",
+            diagnostic_code="artifact-already-exists",
+            details={"path": normalized},
+        )
+    target.parent.mkdir(parents=True, exist_ok=True)
+    # Re-resolve after creating parents so a pre-existing symlink cannot redirect us.
+    try:
+        target = resolve_relative_path(run_directory, normalized)
+    except (OSError, ValueError) as exc:
+        raise ArtifactError(
+            f"artifact path escapes the run directory: {path!r}",
+            diagnostic_code="unsafe-artifact-path",
+            details={"path": path},
+        ) from exc
+    payload = content.encode("utf-8") if isinstance(content, str) else content
+    descriptor, temporary_name = tempfile.mkstemp(
+        dir=target.parent, prefix=f".{target.name}.", suffix=".tmp"
+    )
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(payload)
+            stream.flush()
+            os.fsync(stream.fileno())
+        if target.exists() and not replace:
+            raise ArtifactError(
+                f"artifact already exists and will not be overwritten: {normalized}",
+                diagnostic_code="artifact-already-exists",
+                details={"path": normalized},
+            )
+        os.replace(temporary, target)
+        _fsync_directory(target.parent)
+    finally:
+        temporary.unlink(missing_ok=True)
+    return sha256_bytes(payload)
+
+
+def _invalid_reference(reference: str) -> dict[str, Any]:
+    raise ArtifactError(
+        f"invalid artifact reference: {reference!r}",
+        diagnostic_code="invalid-artifact-reference",
+        details={"reference": reference},
+        not_found=True,
+    )
+
+
+def _required_regular_artifact(run_directory: Path, path: str) -> Path:
+    try:
+        normalized = normalize_relative_path(path)
+        resolved = resolve_relative_path(run_directory, normalized, must_exist=True)
+    except (OSError, ValueError) as exc:
+        raise ArtifactError(
+            f"artifact path is missing or unsafe: {path!r}",
+            diagnostic_code="unsafe-artifact-path",
+            details={"path": path},
+            not_found=True,
+        ) from exc
+    literal = run_directory / normalized
+    if literal.is_symlink() or not resolved.is_file():
+        raise ArtifactError(
+            f"artifact is not a regular file: {path!r}",
+            diagnostic_code="invalid-artifact-type",
+            details={"path": path},
+        )
+    return resolved
+
+
+def _verify_record(value: Any, run_directory: Path, reference: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ArtifactError(
+            f"artifact record for {reference!r} is invalid",
+            diagnostic_code="invalid-artifact-record",
+            details={"reference": reference},
+        )
+    path = value.get("path")
+    expected = value.get("sha256")
+    if not isinstance(path, str) or not isinstance(expected, str):
+        raise ArtifactError(
+            f"artifact record for {reference!r} is incomplete",
+            diagnostic_code="invalid-artifact-record",
+            details={"reference": reference},
+        )
+    actual = artifact_record(run_directory, path, reference=reference)
+    if actual["sha256"] != expected:
+        raise ArtifactError(
+            f"artifact changed after it became immutable: {path}",
+            diagnostic_code="artifact-hash-mismatch",
+            details={"path": path, "expected": expected, "actual": actual["sha256"]},
+        )
+    return actual
+
+
+def _fsync_directory(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+resolve_artifact_reference = resolve_input_reference
+verify_artifacts = verify_manifest_artifacts

specromancy_engine/cli.py

@@ -0,0 +1,338 @@
+"""Dependency-free command-line boundary for Specromancy."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+from typing import Any, TextIO
+
+from .contracts import RESERVED_COMMANDS
+from .actions import render_action_packet
+from ._cli.cli_commands import adapter_command_metadata, command_definitions
+from ._config.config_models import PipelineConfig
+from .engine import Engine
+from .errors import SpecromancyError, UsageError
+from .exit_codes import EXIT_CODE_DESCRIPTIONS, ExitCode
+from ._cli.pipeline_selection import selected_pipeline as _selected_pipeline
+from .registry import load_registry
+from .status import render_status
+
+ACTIONABLE_CODES = frozenset(
+    {
+        ExitCode.APPROVAL_REQUIRED,
+        ExitCode.AGENT_ACTION_REQUIRED,
+        ExitCode.RUN_BLOCKED,
+        ExitCode.RUN_PAUSED,
+    }
+)
+
+
+def discover_repository_root(
+    start: str | os.PathLike[str] | None = None,
+    explicit_root: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Return an explicit root or walk upward until a Git marker is found.
+
+    A ``.git`` marker may be either a directory or a file, as used by Git
+    worktrees. Explicit roots intentionally do not need to be Git repositories,
+    which keeps fixture and non-Git use deterministic.
+    """
+
+    if explicit_root is not None:
+        root = Path(explicit_root).expanduser().resolve()
+        if not root.exists():
+            raise UsageError(
+                f"explicit repository root does not exist: {root}",
+                {"root": str(root)},
+            )
+        if not root.is_dir():
+            raise UsageError(
+                f"explicit repository root is not a directory: {root}",
+                {"root": str(root)},
+            )
+        return root
+
+    candidate = Path.cwd() if start is None else Path(start)
+    candidate = candidate.expanduser().resolve()
+    if candidate.is_file():
+        candidate = candidate.parent
+
+    for directory in (candidate, *candidate.parents):
+        if (directory / ".git").exists():
+            return directory
+
+    raise UsageError(
+        "could not find a repository root; pass --root PATH",
+        {"start": str(candidate)},
+    )
+
+
+class CommandParser(argparse.ArgumentParser):
+    """Argument parser that reports expected failures through our contract."""
+
+    def error(self, message: str) -> None:
+        raise UsageError(message, {"usage": self.format_usage().strip()})
+
+
+def _exit_code_help() -> str:
+    lines = ["exit codes:"]
+    for code, description in EXIT_CODE_DESCRIPTIONS.items():
+        lines.append(f"  {int(code):>2}  {description}")
+    return "\n".join(lines)
+
+
+def _add_common_options(parser: argparse.ArgumentParser) -> None:
+    # SUPPRESS prevents a subparser's default from overwriting a value supplied
+    # before the command name on the root parser.
+    parser.add_argument(
+        "--root",
+        metavar="PATH",
+        default=argparse.SUPPRESS,
+        help="repository root (required when no .git marker can be discovered)",
+    )
+    parser.add_argument(
+        "--pipeline",
+        metavar="ID",
+        default=argparse.SUPPRESS,
+        help="registered pipeline ID (required for init)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="emit exactly one JSON object",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="suppress human-readable non-error output",
+    )
+
+
+def _add_command(
+    subparsers: Any,
+    name: str,
+    help_text: str,
+    arguments: Iterable[tuple[tuple[str, ...], dict[str, Any]]],
+) -> argparse.ArgumentParser:
+    command = subparsers.add_parser(name, help=help_text, description=help_text)
+    _add_common_options(command)
+    for names, options in arguments:
+        command.add_argument(*names, **options)
+    command.set_defaults(command=name)
+    return command
+
+
+def build_parser(dynamic_phases: Iterable[str] = ()) -> CommandParser:
+    """Build the stable parser, optionally adding validated dynamic aliases."""
+
+    parser = CommandParser(
+        prog="specromancy",
+        description="Run a configured, artifact-based agentic pipeline.",
+        epilog=_exit_code_help(),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    _add_common_options(parser)
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    for definition in command_definitions(dynamic_phases):
+        command = _add_command(
+            subparsers, definition.name, definition.description, definition.arguments
+        )
+        if definition.name not in RESERVED_COMMANDS:
+            command.set_defaults(command="dynamic-phase", phase=definition.name)
+        elif definition.name == "adapters":
+            adapters = command
+
+    adapter_commands = adapters.add_subparsers(
+        dest="adapter_command", metavar="COMMAND"
+    )
+    generate = adapter_commands.add_parser(
+        "generate", help="generate harness adapters"
+    )
+    _add_common_options(generate)
+    generate.add_argument(
+        "--check",
+        action="store_true",
+        help="report adapter drift without writing files",
+    )
+    generate.set_defaults(command="adapters", adapter_command="generate")
+
+    return parser
+
+
+def _write_payload(payload: dict[str, Any], stream: TextIO, as_json: bool) -> None:
+    if as_json:
+        stream.write(json.dumps(payload, sort_keys=True, separators=(",", ":")))
+        stream.write("\n")
+        return
+    if payload.get("kind") == "action":
+        stream.write(payload["message"])
+        stream.write("\n\n")
+        stream.write(render_action_packet(payload["action"]))
+    elif payload.get("kind") == "status":
+        stream.write(payload["message"])
+        stream.write("\n\n")
+        stream.write(render_status(payload["status"]))
+    elif payload.get("kind") == "approval":
+        stream.write(payload["message"])
+        approval = payload.get("approval")
+        if approval is not None:
+            stream.write(
+                f"\nReason: {approval['reason']}\nPhase: {approval['phase_id']}"
+            )
+    else:
+        stream.write(payload["message"])
+    stream.write("\n")
+
+
+def _description(arguments: argparse.Namespace, root: Path) -> str:
+    inline = arguments.description
+    declared_file = getattr(arguments, "description_file", None)
+    if inline is not None and declared_file is not None:
+        raise UsageError("pass DESCRIPTION or --description-file, not both")
+    if declared_file is None:
+        if inline is None:
+            raise UsageError("DESCRIPTION or --description-file is required")
+        return inline
+    path = Path(declared_file).expanduser()
+    path = (root / path).resolve() if not path.is_absolute() else path.resolve()
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise UsageError(
+            f"cannot read description file: {path}", {"path": str(path)}
+        ) from exc
+
+
+def _dispatch(
+    arguments: argparse.Namespace, root: Path, pipeline: PipelineConfig
+) -> dict[str, Any]:
+    engine = Engine(pipeline)
+    if arguments.command == "init":
+        return engine.initialize(_description(arguments, root))
+    if arguments.command in {"phase", "dynamic-phase"}:
+        return engine.start_phase(arguments.run_id, arguments.phase)
+    if arguments.command == "validate":
+        return engine.validate(
+            arguments.run_id, arguments.phase, outcome=arguments.outcome
+        )
+    if arguments.command == "request-approval":
+        return engine.request_approval(
+            arguments.run_id,
+            reason=arguments.reason,
+            details=arguments.details,
+            outcome=arguments.outcome,
+        )
+    if arguments.command == "approve":
+        return engine.approve(arguments.run_id, arguments.phase)
+    if arguments.command == "block":
+        return engine.block(
+            arguments.run_id, reason=arguments.reason, details=arguments.details
+        )
+    if arguments.command == "status":
+        return engine.status(arguments.run_id)
+    if arguments.command == "resume":
+        return engine.resume(arguments.run_id)
+    if arguments.command == "run":
+        return engine.run(arguments.run_id)
+    raise UsageError(f"unsupported command: {arguments.command}")
+
+
+def _initial_arguments(raw_args: Sequence[str]) -> argparse.Namespace:
+    """Parse stable commands and provisionally parse a run-specific alias."""
+
+    probe = CommandParser(add_help=False)
+    _add_common_options(probe)
+    probe.add_argument("command", nargs="?")
+    probe.add_argument("remainder", nargs=argparse.REMAINDER)
+    command = probe.parse_args(raw_args)
+    if command.command and command.command not in RESERVED_COMMANDS:
+        if not command.remainder:
+            return build_parser().parse_args(raw_args)
+        return build_parser([command.command]).parse_args(raw_args)
+    return build_parser().parse_args(raw_args)
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    """Parse and dispatch a command, returning a stable process exit code."""
+
+    raw_args = list(sys.argv[1:] if argv is None else argv)
+    output = sys.stdout if stdout is None else stdout
+    errors = sys.stderr if stderr is None else stderr
+    wants_json = "--json" in raw_args
+    wants_quiet = "--quiet" in raw_args
+
+    # argparse renders help and raises SystemExit before returning a namespace.
+    # Handle JSON help at the process boundary so --json still keeps its
+    # one-object guarantee. Human-readable help retains argparse's normal form.
+    if wants_json and ("--help" in raw_args or "-h" in raw_args):
+        _write_payload(
+            {
+                "code": int(ExitCode.SUCCESS),
+                "message": build_parser().format_help(),
+            },
+            output,
+            True,
+        )
+        return int(ExitCode.SUCCESS)
+
+    try:
+        if any(arg in {"-h", "--help"} for arg in raw_args):
+            build_parser().parse_args(raw_args)
+            return int(ExitCode.SUCCESS)
+        arguments = _initial_arguments(raw_args)
+        if arguments.command is None:
+            raise UsageError("a command is required")
+        root = discover_repository_root(
+            explicit_root=getattr(arguments, "root", None)
+        )
+        registry = load_registry(root)
+        selector = getattr(arguments, "pipeline", None)
+        if arguments.command == "adapters" and not getattr(
+            arguments, "adapter_command", None
+        ):
+            raise UsageError("an adapters command is required")
+        if arguments.command == "adapters":
+            if selector is not None:
+                raise UsageError("adapters generate processes all registered pipelines; omit --pipeline")
+            from .adapters import generate_adapters
+
+            payload = generate_adapters(
+                root,
+                registry,
+                check=arguments.check,
+            )
+        else:
+            pipeline = _selected_pipeline(arguments, root, registry)
+            arguments = build_parser(pipeline.phase_ids).parse_args(raw_args)
+            payload = _dispatch(arguments, root, pipeline)
+        if wants_json or not wants_quiet:
+            _write_payload(payload, output, wants_json)
+        return int(payload["code"])
+    except SpecromancyError as exc:
+        payload = exc.as_dict()
+        # Approval, agent-action, and blocked statuses are actionable responses;
+        # all other expected failures are errors.
+        stream = output if exc.code in ACTIONABLE_CODES else errors
+        if wants_json or not (wants_quiet and exc.code in ACTIONABLE_CODES):
+            _write_payload(payload, stream, wants_json)
+        return int(exc.code)
+    except Exception as exc:  # pragma: no cover - defensive process boundary
+        payload = {
+            "code": int(ExitCode.INTERNAL_ERROR),
+            "message": "internal Specromancy error",
+            "details": {"error": str(exc)},
+        }
+        _write_payload(payload, errors, wants_json)
+        return int(ExitCode.INTERNAL_ERROR)