specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/_adapters/adapter_sources.py

@@ -0,0 +1,140 @@
+"""Per-invocation capture of validated adapter sources and their hash inputs."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .adapter_contracts import ADAPTER_COMMANDS, AdapterError
+from .._cli.cli_commands import adapter_command_metadata
+from ..hashing import canonical_json_bytes, relative_path, sha256_bytes
+
+if TYPE_CHECKING:
+    from .._config.config_models import PipelineConfig
+    from ..registry import PipelineRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class SourceInput:
+    kind: str
+    path: str
+    content: bytes
+
+    def record(self) -> dict[str, str]:
+        return {"kind": self.kind, "path": self.path, "sha256": sha256_bytes(self.content)}
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterSources:
+    pipelines: tuple[PipelineConfig, ...]
+    agents: str
+    skills: tuple[tuple[str, str], ...]
+    inputs: tuple[SourceInput, ...]
+
+
+def capture_sources(
+    root: Path,
+    registry: PipelineRegistry,
+    command_metadata: Mapping[str, Any] | None,
+    *,
+    include_manifest_inputs: bool = True,
+) -> AdapterSources:
+    """Read sources once for rendering and hashing; retain no cross-call cache."""
+
+    if root != registry.repository_root:
+        raise AdapterError("registry and adapter roots differ", {"path": str(registry.path)})
+    pipelines = registry.load_all()
+    agents = _normalized_text(root / "AGENTS.md", "AGENTS.md")
+    skill_sources = _skill_sources(root)
+    if ".agents/skills/pipeline/SKILL.md" not in {path for path, _ in skill_sources}:
+        raise AdapterError(
+            "canonical pipeline orchestrator skill is missing",
+            {"path": ".agents/skills/pipeline/SKILL.md"},
+        )
+    if command_metadata is None:
+        phases = sorted({phase for pipeline in pipelines for phase in pipeline.phase_ids})
+        command_metadata = adapter_command_metadata(phases)
+    cli_commands = _known_cli_commands(command_metadata)
+    for command in ADAPTER_COMMANDS:
+        if command.cli_command not in cli_commands:
+            raise AdapterError(
+                "adapter command is absent from CLI metadata",
+                {"command": command.cli_command},
+            )
+
+    # Validate portable frontmatter before collecting manifest dependencies, as
+    # rendering did before source capture was extracted.
+    for path, text in skill_sources:
+        if not text.splitlines() or text.splitlines()[0] != "---":
+            raise AdapterError("canonical skill has no portable frontmatter", {"path": path})
+
+    # The public render-only facade historically did not read dependency bytes.
+    if not include_manifest_inputs:
+        return AdapterSources(pipelines, agents, tuple(skill_sources), ())
+
+    inputs = [
+        SourceInput("repository-instructions", "AGENTS.md", agents.encode("utf-8")),
+        SourceInput("validated-registry", relative_path(registry.path, root),
+                    registry.canonical_json.encode("utf-8")),
+    ]
+    dependencies: set[str] = set()
+    for pipeline in pipelines:
+        inputs.append(SourceInput(
+            "validated-pipeline", relative_path(pipeline.path, root),
+            pipeline.canonical_json.encode("utf-8"),
+        ))
+        for phase in pipeline.phases:
+            for path in (phase.output_template_path, phase.validator.resolved_path):
+                if path is not None:
+                    dependencies.add(relative_path(path, root))
+    for path in sorted(dependencies):
+        inputs.append(SourceInput("pipeline-dependency", path, (root / path).read_bytes()))
+    for path, text in skill_sources:
+        inputs.append(SourceInput("canonical-skill", path, text.encode("utf-8")))
+    inputs.append(SourceInput(
+        "cli-help-metadata", "@cli-help-metadata", canonical_json_bytes(command_metadata),
+    ))
+    return AdapterSources(pipelines, agents, tuple(skill_sources), tuple(inputs))
+
+
+def _skill_sources(root: Path) -> list[tuple[str, str]]:
+    skills_root = root / ".agents" / "skills"
+    paths = sorted(
+        (path for path in skills_root.glob("*/SKILL.md")
+         if not path.parent.name.startswith("specromancy-")),
+        key=lambda item: item.as_posix(),
+    )
+    if not paths:
+        raise AdapterError(
+            "no canonical skills found",
+            {"path": ".agents/skills/*/SKILL.md"},
+        )
+    return [
+        (relative_path(path, root), _normalized_text(path, relative_path(path, root)))
+        for path in paths
+    ]
+
+
+def _normalized_text(path: Path, label: str) -> str:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise AdapterError(
+            "cannot read canonical adapter source",
+            {"path": label, "error": str(exc)},
+        ) from exc
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    return text.rstrip("\n") + "\n"
+
+
+def _known_cli_commands(metadata: Mapping[str, Any]) -> set[str]:
+    commands = metadata.get("commands")
+    if not isinstance(commands, Sequence) or isinstance(commands, (str, bytes)):
+        raise AdapterError("invalid CLI help metadata", {"field": "commands"})
+    known: set[str] = set()
+    for item in commands:
+        if isinstance(item, Mapping) and isinstance(item.get("name"), str):
+            known.add(item["name"])
+    return known

specromancy_engine/_cli/__init__.py

@@ -0,0 +1 @@
+"""Private cli implementation components; use the public facades."""

specromancy_engine/_cli/cli_commands.py

@@ -0,0 +1,136 @@
+"""Static CLI descriptions shared by parser construction and adapter metadata."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from ..contracts import RESERVED_COMMANDS
+
+
+@dataclass(frozen=True, slots=True)
+class CommandDefinition:
+    name: str
+    description: str
+    arguments: list[tuple[tuple[str, ...], dict[str, Any]]]
+
+
+COMMANDS = (
+    CommandDefinition(
+        'init',
+        'create a run for DESCRIPTION',
+        [
+            (('description',), {'metavar': 'DESCRIPTION', 'nargs': '?'}),
+            (('--description-file',), {'metavar': 'PATH', 'help': 'read DESCRIPTION from a UTF-8 file'}),
+        ],
+    ),
+    CommandDefinition(
+        'phase',
+        'emit the action packet for PHASE',
+        [
+            (('run_id',), {'metavar': 'RUN_ID'}),
+            (('phase',), {'metavar': 'PHASE'}),
+        ],
+    ),
+    CommandDefinition(
+        'validate',
+        "validate a run's current or named phase",
+        [
+            (('run_id',), {'metavar': 'RUN_ID'}),
+            (('phase',), {'metavar': 'PHASE', 'nargs': '?'}),
+            (('--outcome',), {'metavar': 'OUTCOME'}),
+        ],
+    ),
+    CommandDefinition(
+        'approve',
+        'approve a phase artifact',
+        [
+            (('run_id',), {'metavar': 'RUN_ID'}),
+            (('phase',), {'metavar': 'PHASE'}),
+        ],
+    ),
+    CommandDefinition(
+        'request-approval',
+        'request approval for the current visit',
+        [
+            (('run_id',), {'metavar': 'RUN_ID'}),
+            (('--reason',), {'metavar': 'CODE'}),
+            (('--details',), {'metavar': 'TEXT'}),
+            (('--outcome',), {'metavar': 'OUTCOME'}),
+        ],
+    ),
+    CommandDefinition(
+        'block',
+        'mark a run blocked',
+        [
+            (('run_id',), {'metavar': 'RUN_ID'}),
+            (('--reason',), {'metavar': 'CODE'}),
+            (('--details',), {'metavar': 'TEXT'}),
+        ],
+    ),
+    CommandDefinition(
+        'status',
+        'show run status',
+        [
+            (('run_id',), {'metavar': 'RUN_ID'}),
+        ],
+    ),
+    CommandDefinition(
+        'resume',
+        'resume a run',
+        [
+            (('run_id',), {'metavar': 'RUN_ID'}),
+        ],
+    ),
+    CommandDefinition(
+        'run',
+        'advance a run',
+        [
+            (('run_id',), {'metavar': 'RUN_ID'}),
+        ],
+    ),
+    CommandDefinition(
+        'adapters',
+        'manage generated harness adapters',
+        [
+        ],
+    ),
+)
+
+if (
+    len(COMMANDS) != len(RESERVED_COMMANDS)
+    or {command.name for command in COMMANDS} != RESERVED_COMMANDS
+):
+    raise RuntimeError("CLI definitions and reserved commands disagree")
+
+
+def command_definitions(dynamic_phases: Iterable[str] = ()) -> tuple[CommandDefinition, ...]:
+    """Keep built-ins authoritative and aliases local to this invocation."""
+
+    commands = list(COMMANDS)
+    seen = set(RESERVED_COMMANDS)
+    for phase in dynamic_phases:
+        if phase in RESERVED_COMMANDS:
+            continue
+        if phase in seen:
+            raise argparse.ArgumentError(None, f"conflicting subparser: {phase}")
+        seen.add(phase)
+        commands.append(
+            CommandDefinition(
+                phase,
+                f"emit the action packet for the {phase} phase",
+                [(("run_id",), {"metavar": "RUN_ID"})],
+            )
+        )
+    return tuple(commands)
+
+
+def adapter_command_metadata(dynamic_phases: Iterable[str] = ()) -> dict[str, Any]:
+    """Return stable, sorted names and descriptions without inspecting argparse."""
+
+    commands = sorted(command_definitions(dynamic_phases), key=lambda command: command.name)
+    return {"commands": [
+        {"name": command.name, "help": command.description} for command in commands
+    ]}

specromancy_engine/_cli/pipeline_selection.py

@@ -0,0 +1,28 @@
+"""Select registered initialization graphs or an existing run's saved provenance."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .._config.config_loader import load_pipeline
+from .._config.config_models import PipelineConfig
+from ..errors import UsageError
+from ..registry import PipelineRegistry
+from ..run_store import RunStore
+
+
+def selected_pipeline(
+    arguments: argparse.Namespace, root: Path, registry: PipelineRegistry
+) -> PipelineConfig:
+    selector = getattr(arguments, "pipeline", None)
+    if arguments.command == "init":
+        if selector is None:
+            raise UsageError("init requires --pipeline ID; there is no default pipeline")
+        return registry.load(selector)
+
+    saved = RunStore(root).load(arguments.run_id, verify_artifacts=False)["pipeline"]
+    path = root / saved["path"]
+    if selector is not None and selector != saved["id"]:
+        raise UsageError("--pipeline must match the run's recorded pipeline ID")
+    return load_pipeline(path, root)

specromancy_engine/_config/__init__.py

@@ -0,0 +1 @@
+"""Private config implementation components; use the public facades."""

specromancy_engine/_config/config_errors.py

@@ -0,0 +1,57 @@
+"""Stable pipeline diagnostics and JSON-safe diagnostic values."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ..errors import SpecromancyError
+from ..exit_codes import ExitCode
+
+
+_MISSING = object()
+
+
+class PipelineConfigError(SpecromancyError):
+    """An expected pipeline error with a stable diagnostic code."""
+
+    def __init__(
+        self,
+        diagnostic_code: str,
+        message: str,
+        *,
+        path: Path,
+        phase: str | None = None,
+        field: str | None = None,
+        value: Any = _MISSING,
+        remediation: str,
+    ) -> None:
+        details: dict[str, Any] = {
+            "error_code": diagnostic_code,
+            "path": str(path),
+            "remediation": remediation,
+        }
+        if phase is not None:
+            details["phase"] = phase
+        if field is not None:
+            details["field"] = field
+        if value is not _MISSING:
+            details["value"] = _json_value(value)
+        super().__init__(ExitCode.INVALID_PIPELINE, message, details)
+        self.diagnostic_code = diagnostic_code
+
+
+def _json_value(value: Any) -> Any:
+    if isinstance(value, Path):
+        return str(value)
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [_json_value(item) for item in value]
+    if isinstance(value, Mapping):
+        return {str(key): _json_value(item) for key, item in value.items()}
+    isoformat = getattr(value, "isoformat", None)
+    if callable(isoformat):
+        return isoformat()
+    return repr(value)

specromancy_engine/_config/config_fields.py

@@ -0,0 +1,228 @@
+"""Field diagnostics and repository-contained resource resolution for configuration."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, NoReturn
+
+from .config_errors import PipelineConfigError, _MISSING
+
+
+IDENTIFIER_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+class FieldContext:
+    """Source and repository authority shared by configuration parsers."""
+
+    def __init__(self, path: Path, repository_root: Path) -> None:
+        self.path = path
+        self.repository_root = repository_root
+
+    def fail(
+        self,
+        diagnostic_code: str,
+        message: str,
+        *,
+        phase: str | None = None,
+        field: str | None = None,
+        value: Any = _MISSING,
+        remediation: str,
+    ) -> NoReturn:
+        raise PipelineConfigError(
+            diagnostic_code,
+            message,
+            path=self.path,
+            phase=phase,
+            field=field,
+            value=value,
+            remediation=remediation,
+        )
+
+    def require_mapping(
+        self, value: Any, field: str, *, phase: str | None = None
+    ) -> Mapping[str, Any]:
+        if not isinstance(value, Mapping):
+            self.fail(
+                "invalid-field-type",
+                f"{field} must be a table",
+                phase=phase,
+                field=field,
+                value=value,
+                remediation="replace it with a TOML table",
+            )
+        return value
+
+    def require_string(
+        self, value: Any, field: str, *, phase: str | None = None
+    ) -> str:
+        if not isinstance(value, str) or not value.strip():
+            self.fail(
+                "invalid-field-type",
+                f"{field} must be a non-empty string",
+                phase=phase,
+                field=field,
+                value=value,
+                remediation="provide a non-empty string",
+            )
+        return value
+
+    def require_identifier(
+        self, value: Any, field: str, *, phase: str | None = None
+    ) -> str:
+        identifier = self.require_string(value, field, phase=phase)
+        if not IDENTIFIER_PATTERN.fullmatch(identifier):
+            self.fail(
+                "invalid-identifier",
+                f"{field} has invalid identifier {identifier!r}",
+                phase=phase,
+                field=field,
+                value=identifier,
+                remediation="use lowercase words separated by single hyphens",
+            )
+        return identifier
+
+    def require_integer(
+        self,
+        value: Any,
+        field: str,
+        *,
+        phase: str | None = None,
+        minimum: int | None = None,
+    ) -> int:
+        if not isinstance(value, int) or isinstance(value, bool):
+            self.fail(
+                "invalid-field-type",
+                f"{field} must be an integer",
+                phase=phase,
+                field=field,
+                value=value,
+                remediation="provide an integer value",
+            )
+        if minimum is not None and value < minimum:
+            self.fail(
+                "invalid-bound",
+                f"{field} must be at least {minimum}",
+                phase=phase,
+                field=field,
+                value=value,
+                remediation=f"set {field} to {minimum} or greater",
+            )
+        return value
+
+    def string_list(
+        self,
+        value: Any,
+        field: str,
+        *,
+        phase: str | None = None,
+        allow_empty: bool = True,
+        identifiers: bool = False,
+    ) -> tuple[str, ...]:
+        if not isinstance(value, list):
+            self.fail(
+                "invalid-field-type",
+                f"{field} must be a list of strings",
+                phase=phase,
+                field=field,
+                value=value,
+                remediation="provide a TOML array of strings",
+            )
+        parsed: list[str] = []
+        for item in value:
+            parsed.append(
+                self.require_identifier(item, field, phase=phase)
+                if identifiers
+                else self.require_string(item, field, phase=phase)
+            )
+        if not parsed and not allow_empty:
+            self.fail(
+                "empty-field",
+                f"{field} must contain at least one value",
+                phase=phase,
+                field=field,
+                value=[],
+                remediation="add at least one entry",
+            )
+        if len(set(parsed)) != len(parsed):
+            self.fail(
+                "duplicate-value",
+                f"{field} contains duplicate values",
+                phase=phase,
+                field=field,
+                value=parsed,
+                remediation="remove duplicate entries",
+            )
+        return tuple(parsed)
+
+    def existing_path(
+        self,
+        declared: str,
+        field: str,
+        *,
+        phase: str | None = None,
+        base: Path | None = None,
+    ) -> Path:
+        if not _safe_declared_path(declared, allow_parent=True):
+            self.fail(
+                "unsafe-path",
+                f"{field} must be a safe repository-relative path",
+                phase=phase,
+                field=field,
+                value=declared,
+                remediation="use a relative path that resolves inside the repository",
+            )
+        candidate = ((base or self.path.parent) / declared).resolve()
+        if not candidate.is_relative_to(self.repository_root):
+            self.fail(
+                "unsafe-path",
+                f"{field} resolves outside the repository",
+                phase=phase,
+                field=field,
+                value=declared,
+                remediation="choose a file inside the repository",
+            )
+        if not candidate.is_file():
+            self.fail(
+                "missing-file",
+                f"referenced file does not exist: {declared}",
+                phase=phase,
+                field=field,
+                value=declared,
+                remediation="create the referenced file or correct the path",
+            )
+        return candidate
+
+    def check_unknown(
+        self,
+        raw: Mapping[str, Any],
+        allowed: set[str],
+        *,
+        phase: str | None = None,
+    ) -> None:
+        unknown = sorted(set(raw) - allowed)
+        if unknown:
+            self.fail(
+                "unknown-field",
+                f"unknown configuration field: {unknown[0]}",
+                phase=phase,
+                field=unknown[0],
+                value=raw[unknown[0]],
+                remediation="remove the field or use a supported field name",
+            )
+
+
+def _safe_declared_path(
+    value: str, *, allow_glob: bool = False, allow_parent: bool = False
+) -> bool:
+    if not value or "\\" in value or value.startswith("/"):
+        return False
+    if re.match(r"^[A-Za-z]:", value):
+        return False
+    parts = Path(value).parts
+    if (".." in parts and not allow_parent) or "." in parts:
+        return False
+    if not allow_glob and any(character in value for character in "*?["):
+        return False
+    return True