crewplane 0.1.0__py3-none-any.whl

crewplane/__init__.py

@@ -0,0 +1,3 @@
+from crewplane.version import SCHEMA_VERSION
+
+__all__ = ["SCHEMA_VERSION"]

crewplane/adapters/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

crewplane/adapters/artifacts/__init__.py

@@ -0,0 +1,3 @@
+from .filesystem import FilesystemArtifactsAdapter
+
+__all__ = ["FilesystemArtifactsAdapter"]

crewplane/adapters/artifacts/filesystem.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from crewplane.architecture.contracts import (
+    CanonicalIntegrationConfig,
+    FilesystemArtifactOptions,
+    JsonObject,
+)
+from crewplane.architecture.ports.artifacts import (
+    ArtifactStorePort,
+)
+from crewplane.artifacts import OutputManager
+
+
+def _parse_options(options: JsonObject | None) -> FilesystemArtifactOptions:
+    resolved_options = dict(options or {})
+
+    log_cli_output_raw = resolved_options.pop("log_cli_output", True)
+    if not isinstance(log_cli_output_raw, bool):
+        raise ValueError("artifacts option 'log_cli_output' must be a boolean")
+
+    allowed_template_paths_raw = resolved_options.pop("allowed_template_paths", [])
+    if not isinstance(allowed_template_paths_raw, list) or any(
+        not isinstance(path, str) for path in allowed_template_paths_raw
+    ):
+        raise ValueError(
+            "artifacts option 'allowed_template_paths' must be a list of strings"
+        )
+
+    if resolved_options:
+        raise ValueError(
+            "Unsupported filesystem artifacts options: "
+            f"{', '.join(sorted(resolved_options))}"
+        )
+
+    return FilesystemArtifactOptions(
+        log_cli_output=log_cli_output_raw,
+        allowed_template_paths=tuple(
+            Path(path).expanduser().resolve(strict=False).as_posix()
+            for path in allowed_template_paths_raw
+        ),
+    )
+
+
+class FilesystemArtifactsAdapter:
+    """Create the built-in filesystem-backed artifact store."""
+
+    def canonicalize_options(
+        self,
+        implementation: str,
+        resolved_identity: str,
+        options: JsonObject | None = None,
+    ) -> CanonicalIntegrationConfig:
+        parsed_options = _parse_options(options)
+        canonical_options = {
+            "allowed_template_paths": list(parsed_options.allowed_template_paths),
+            "log_cli_output": parsed_options.log_cli_output,
+        }
+        return CanonicalIntegrationConfig(
+            implementation=implementation,
+            resolved_identity=resolved_identity,
+            options=canonical_options,
+            option_scopes={
+                "allowed_template_paths": "artifact",
+                "log_cli_output": "artifact",
+            },
+        )
+
+    def create_store(
+        self,
+        workflow_name: str,
+        state_dir: Path,
+        project_root: Path,
+        options: JsonObject | None = None,
+    ) -> ArtifactStorePort:
+        """Build an artifact store rooted under Crewplane directory."""
+
+        parsed_options = _parse_options(options)
+
+        return OutputManager(
+            workflow_name,
+            base_dir=state_dir,
+            template_base_dir=project_root,
+            log_cli_output=parsed_options.log_cli_output,
+        )

crewplane/adapters/invokers/__init__.py

@@ -0,0 +1,4 @@
+from .cli import CliInvokerAdapter
+from .mock import MockInvokerAdapter
+
+__all__ = ["CliInvokerAdapter", "MockInvokerAdapter"]

crewplane/adapters/invokers/cli.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import os
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from crewplane.architecture.contracts import (
+    AgentInvoker,
+    CanonicalIntegrationConfig,
+    CliInvokerOptions,
+    InvokerAdapterCapabilities,
+    JsonObject,
+)
+from crewplane.core.config import Config
+from crewplane.core.workflow.models import WorkflowPlan
+from crewplane.runtime.agent.invoker import PlannedAgentInvoker
+
+from .cli_invoker import build_cli_invocation_plan, build_cli_log_presentation
+
+
+def collect_cli_availability_errors(
+    workflow: WorkflowPlan,
+    config: Config,
+    which_fn: Callable[[str], str | None] | None = None,
+    project_root: Path | None = None,
+) -> list[str]:
+    """Collect missing executable errors for configured CLI providers."""
+
+    executable_lookup = shutil.which if which_fn is None else which_fn
+    executable_base_dir = Path.cwd() if project_root is None else project_root
+    missing_cli_locations: dict[str, list[str]] = {}
+    for node in workflow.nodes:
+        for provider in node.providers:
+            agent_config = config.agents.get(provider.provider)
+            if agent_config is None:
+                continue
+            cli_executable = agent_config.cli_cmd[0]
+            if _cli_executable_available(
+                cli_executable,
+                executable_lookup,
+                executable_base_dir,
+            ):
+                continue
+            location = f"workflow '{workflow.name}' -> node '{node.id}'"
+            missing_cli_locations.setdefault(provider.provider, []).append(
+                f"{location} (CLI: {cli_executable})"
+            )
+    return _format_missing_cli_errors(config, missing_cli_locations)
+
+
+def _format_missing_cli_errors(
+    config: Config,
+    missing_cli_locations: dict[str, list[str]],
+) -> list[str]:
+    errors: list[str] = []
+    for provider_name, locations in sorted(missing_cli_locations.items()):
+        unique_locations = sorted(set(locations))
+        cli_executable = config.agents[provider_name].cli_cmd[0]
+        availability_message = (
+            "not found or not executable"
+            if Path(cli_executable).is_absolute()
+            or _contains_path_separator(cli_executable)
+            else "not found in PATH"
+        )
+        errors.append(
+            f"CLI '{cli_executable}' {availability_message} for provider "
+            f"'{provider_name}', referenced in: {', '.join(unique_locations)}"
+        )
+    return errors
+
+
+def _cli_executable_available(
+    executable: str,
+    executable_lookup: Callable[[str], str | None],
+    executable_base_dir: Path,
+) -> bool:
+    executable_path = Path(executable)
+    if executable_path.is_absolute():
+        return _is_executable_file(executable_path)
+    if _contains_path_separator(executable):
+        return _is_executable_file(executable_base_dir / executable_path)
+    return executable_lookup(executable) is not None
+
+
+def _is_executable_file(path: Path) -> bool:
+    resolved = path.resolve(strict=False)
+    return resolved.is_file() and os.access(resolved, os.X_OK)
+
+
+def _contains_path_separator(value: str) -> bool:
+    return "/" in value or "\\" in value
+
+
+class CliInvokerAdapter:
+    """Create the default CLI-backed agent invoker."""
+
+    def workspace_capabilities(self) -> InvokerAdapterCapabilities:
+        return InvokerAdapterCapabilities.workspace_supported(
+            launch_mode="runtime_command_runner",
+            controlled_child_environment=True,
+        )
+
+    def canonicalize_options(
+        self,
+        implementation: str,
+        resolved_identity: str,
+        options: JsonObject | None = None,
+    ) -> CanonicalIntegrationConfig:
+        CliInvokerOptions()
+        if options:
+            raise ValueError(
+                "cli invoker implementation does not support options; "
+                "set settings.integrations.invoker.options: {} when using "
+                f'implementation: "cli"; got: {sorted(options)}'
+            )
+        return CanonicalIntegrationConfig(
+            implementation=implementation,
+            resolved_identity=resolved_identity,
+            options={},
+            option_scopes={},
+            capabilities=self.workspace_capabilities().as_dict(),
+        )
+
+    def create_invoker(
+        self,
+        config: Config,
+        options: JsonObject | None = None,
+    ) -> AgentInvoker:
+        """Build the default subprocess-based invoker."""
+
+        _validate_config(config)
+        self.canonicalize_options("cli", self.__class__.__module__, options)
+        return PlannedAgentInvoker(
+            plan_builder=build_cli_invocation_plan,
+            log_presentation_builder=build_cli_log_presentation,
+        )
+
+
+def _validate_config(config: Config) -> None:
+    if not isinstance(config, Config):
+        raise TypeError("config must be a Config instance")

crewplane/adapters/invokers/cli_invoker/__init__.py

@@ -0,0 +1,13 @@
+from .capabilities import (
+    CliProviderCapability,
+    build_cli_invocation_plan,
+    build_cli_log_presentation,
+    get_cli_provider_capability,
+)
+
+__all__ = [
+    "CliProviderCapability",
+    "build_cli_invocation_plan",
+    "build_cli_log_presentation",
+    "get_cli_provider_capability",
+]

crewplane/adapters/invokers/cli_invoker/capabilities.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from crewplane.architecture.contracts import (
+    InvocationPlan,
+    LogPresentationDescriptor,
+    LogPresentationFormat,
+    OutputExtractionMode,
+    ProviderKind,
+    QuotaParserProfile,
+    StructuredOutputMode,
+    UsageParserProfile,
+)
+from crewplane.core.config import AgentConfig
+
+
+@dataclass(frozen=True)
+class CliProviderCapability:
+    provider_kind: ProviderKind
+    structured_output_mode: StructuredOutputMode
+    output_extraction_mode: OutputExtractionMode
+    quota_parser: QuotaParserProfile
+    usage_parser: UsageParserProfile
+    log_presentation_format: LogPresentationFormat
+    log_presentation_profile: str
+    model_arg: str | None = "--model"
+    structured_output_args: tuple[str, ...] = ()
+
+
+CAPABILITIES: dict[ProviderKind, CliProviderCapability] = {
+    ProviderKind.CLAUDE: CliProviderCapability(
+        provider_kind=ProviderKind.CLAUDE,
+        structured_output_mode="claude_json",
+        output_extraction_mode="claude_json",
+        quota_parser="claude",
+        usage_parser="claude",
+        log_presentation_format="json_object",
+        log_presentation_profile="claude",
+        structured_output_args=("--output-format", "json"),
+    ),
+    ProviderKind.CODEX: CliProviderCapability(
+        provider_kind=ProviderKind.CODEX,
+        structured_output_mode="codex_last_message_file",
+        output_extraction_mode="codex_last_message_file",
+        quota_parser="codex",
+        usage_parser="codex",
+        log_presentation_format="json_lines",
+        log_presentation_profile="codex",
+    ),
+    ProviderKind.COPILOT: CliProviderCapability(
+        provider_kind=ProviderKind.COPILOT,
+        structured_output_mode="none",
+        output_extraction_mode="visible",
+        quota_parser="copilot",
+        usage_parser="none",
+        log_presentation_format="plain",
+        log_presentation_profile="generic",
+    ),
+    ProviderKind.GEMINI: CliProviderCapability(
+        provider_kind=ProviderKind.GEMINI,
+        structured_output_mode="none",
+        output_extraction_mode="visible",
+        quota_parser="gemini",
+        usage_parser="none",
+        log_presentation_format="plain",
+        log_presentation_profile="generic",
+    ),
+    ProviderKind.KILO: CliProviderCapability(
+        provider_kind=ProviderKind.KILO,
+        structured_output_mode="none",
+        output_extraction_mode="visible",
+        quota_parser="kilo",
+        usage_parser="none",
+        log_presentation_format="plain",
+        log_presentation_profile="generic",
+    ),
+    ProviderKind.GENERIC: CliProviderCapability(
+        provider_kind=ProviderKind.GENERIC,
+        structured_output_mode="none",
+        output_extraction_mode="visible",
+        quota_parser="generic",
+        usage_parser="none",
+        log_presentation_format="plain",
+        log_presentation_profile="generic",
+    ),
+}
+
+
+def get_cli_provider_capability(provider_kind: ProviderKind) -> CliProviderCapability:
+    return CAPABILITIES[ProviderKind(provider_kind)]
+
+
+def build_cli_invocation_plan(
+    config: AgentConfig,
+    model: str | None,
+    prompt: str,
+    output_file: Path,
+) -> InvocationPlan:
+    capability = get_cli_provider_capability(config.provider_kind)
+    structured_output_file = _structured_output_file(capability)
+    cmd = _build_argv(config, capability, model, prompt, structured_output_file)
+    stdin_data = prompt.encode("utf-8") if config.prompt_transport == "stdin" else None
+    return InvocationPlan(
+        cmd=cmd,
+        stdin_data=stdin_data,
+        structured_output_file=structured_output_file,
+        structured_output_mode=capability.structured_output_mode,
+        output_extraction_mode=capability.output_extraction_mode,
+        quota_parser=capability.quota_parser,
+        usage_parser=capability.usage_parser,
+        failure_profile=capability.provider_kind,
+        log_provider_kind=capability.provider_kind,
+        log_header=_build_log_header(
+            cli_executable=cmd[0],
+            model=model,
+            output_file=output_file,
+        ),
+    )
+
+
+def build_cli_log_presentation(config: AgentConfig) -> LogPresentationDescriptor:
+    capability = get_cli_provider_capability(config.provider_kind)
+    return LogPresentationDescriptor(
+        format=capability.log_presentation_format,
+        profile=capability.log_presentation_profile,
+    )
+
+
+def _build_argv(
+    config: AgentConfig,
+    capability: CliProviderCapability,
+    model: str | None,
+    prompt: str,
+    structured_output_file: Path | None,
+) -> list[str]:
+    """Build the provider CLI argv and validate the executable.
+
+    The first argument identifies the process to launch, so it is resolved
+    before appending provider flags. This keeps command validation and log
+    headers tied to the actual executable while leaving user-supplied
+    arguments untouched.
+    """
+    cmd = config.get_command()
+    cmd[0] = _resolved_cli_executable(cmd[0])
+    model_arg = (
+        config.model_arg
+        if config.provider_kind == ProviderKind.GENERIC
+        else capability.model_arg
+    )
+    if model_arg is not None and model is not None:
+        cmd.extend([model_arg, model])
+    cmd.extend(config.extra_args)
+    cmd.extend(_structured_output_args(capability, structured_output_file))
+    if config.prompt_transport == "stdin":
+        if config.prompt_transport_arg:
+            cmd.append(config.prompt_transport_arg)
+        return cmd
+    if config.prompt_transport_arg is None:
+        raise ValueError("prompt_transport_arg is required for argv prompt transport.")
+    cmd.extend([config.prompt_transport_arg, prompt])
+    return cmd
+
+
+def _resolved_cli_executable(executable: str) -> str:
+    """Return an executable path suitable for subprocess invocation.
+
+    Bare executable names are resolved through `PATH` and validated. Absolute
+    paths are validated directly. Relative path-like commands are preserved so
+    subprocess can resolve them relative to the configured working directory.
+    """
+    executable_path = Path(executable)
+    if executable_path.is_absolute():
+        return _resolved_existing_executable(executable_path)
+    if _contains_path_separator(executable):
+        return executable
+    resolved = shutil.which(executable)
+    if resolved is None:
+        raise FileNotFoundError(f"CLI executable '{executable}' was not found.")
+    return _resolved_existing_executable(Path(resolved))
+
+
+def _resolved_existing_executable(executable: Path) -> str:
+    """Resolve an existing executable path and fail clearly if it is unusable."""
+    resolved = executable.resolve(strict=True)
+    if not resolved.is_file():
+        raise FileNotFoundError(
+            f"CLI executable '{executable.as_posix()}' is not a file."
+        )
+    if not os.access(resolved, os.X_OK):
+        raise PermissionError(
+            f"CLI executable '{resolved.as_posix()}' is not executable."
+        )
+    return resolved.as_posix()
+
+
+def _contains_path_separator(value: str) -> bool:
+    return "/" in value or "\\" in value
+
+
+def _structured_output_args(
+    capability: CliProviderCapability,
+    structured_output_file: Path | None,
+) -> tuple[str, ...]:
+    if capability.structured_output_mode == "codex_last_message_file":
+        if structured_output_file is None:
+            raise ValueError("Codex invocations require a structured output file.")
+        return ("--json", "--output-last-message", str(structured_output_file))
+    return capability.structured_output_args
+
+
+def _structured_output_file(capability: CliProviderCapability) -> Path | None:
+    if capability.structured_output_mode != "codex_last_message_file":
+        return None
+    file_descriptor, temp_path = tempfile.mkstemp(
+        prefix="crewplane-codex-",
+        suffix=".last-message.txt",
+    )
+    os.close(file_descriptor)
+    Path(temp_path).unlink(missing_ok=True)
+    return Path(temp_path)
+
+
+def _build_log_header(
+    cli_executable: str,
+    model: str | None,
+    output_file: Path,
+) -> bytes:
+    started_at = datetime.now(UTC).isoformat()
+    model_label = model if model is not None else "provider default"
+    header = (
+        f"started_at: {started_at}\n"
+        f"cli_executable: {cli_executable}\n"
+        f"model: {model_label}\n"
+        f"output_file: {output_file}\n"
+        "---\n"
+    )
+    return header.encode("utf-8")

crewplane/adapters/invokers/mock.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+__all__ = ["MockInvokerAdapter"]
+
+from crewplane.architecture.contracts import (
+    AgentInvoker,
+    CanonicalIntegrationConfig,
+    InvokerAdapterCapabilities,
+    JsonObject,
+)
+from crewplane.core.config import Config
+
+from .mock_invoker import MockAgentInvoker, parse_options
+
+
+class MockInvokerAdapter:
+    """Create deterministic mock invokers for local orchestration runs."""
+
+    def workspace_capabilities(self) -> InvokerAdapterCapabilities:
+        return InvokerAdapterCapabilities.workspace_supported(
+            launch_mode="mock_no_child_process",
+            controlled_child_environment=False,
+        )
+
+    def canonicalize_options(
+        self,
+        implementation: str,
+        resolved_identity: str,
+        options: JsonObject | None = None,
+    ) -> CanonicalIntegrationConfig:
+        parsed = parse_options(options)
+        canonical_options = {
+            "delay_seconds": parsed.delay_seconds,
+            "fail_when": [selector.__dict__ for selector in parsed.fail_when],
+            "observation_delay_seconds": parsed.observation_delay_seconds,
+            "output_dir": parsed.output_dir,
+            "output_mode": parsed.output_mode,
+            "seed": parsed.seed,
+            "strict_file_mode": parsed.strict_file_mode,
+        }
+        return CanonicalIntegrationConfig(
+            implementation=implementation,
+            resolved_identity=resolved_identity,
+            options=canonical_options,
+            option_scopes={key: "execution" for key in canonical_options},
+            capabilities=self.workspace_capabilities().as_dict(),
+        )
+
+    def create_invoker(
+        self,
+        config: Config,
+        options: JsonObject | None = None,
+    ) -> AgentInvoker:
+        """Build a mock invoker from the configured integration options."""
+
+        _validate_config(config)
+        return MockAgentInvoker(options=parse_options(options))
+
+
+def _validate_config(config: Config) -> None:
+    if not isinstance(config, Config):
+        raise TypeError("config must be a Config instance")

crewplane/adapters/invokers/mock_invoker/__init__.py

@@ -0,0 +1,4 @@
+from .invoker import MockAgentInvoker
+from .options import parse_options
+
+__all__ = ["MockAgentInvoker", "parse_options"]

crewplane/adapters/invokers/mock_invoker/context.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from crewplane.architecture.contracts import InvocationContext
+from crewplane.core.workflow.keywords import ProviderRole
+
+
+@dataclass(frozen=True)
+class ContextDisplay:
+    node_id: str
+    task_id: str
+    provider: str
+    role: str
+    audit_round_display: str
+    round_display: str
+
+
+def _or_na(value: int | None) -> str:
+    return str(value) if value is not None else "n/a"
+
+
+def context_display(context: InvocationContext | None) -> ContextDisplay:
+    if context is None:
+        return ContextDisplay(
+            node_id="<unknown>",
+            task_id="<unknown>",
+            provider="<unknown>",
+            role="<unknown>",
+            audit_round_display=_or_na(None),
+            round_display=_or_na(None),
+        )
+    return ContextDisplay(
+        node_id=context.node_id,
+        task_id=context.task_id,
+        provider=context.provider,
+        role=context.role,
+        audit_round_display=_or_na(context.audit_round_num),
+        round_display=_or_na(context.round_num),
+    )
+
+
+def is_reviewer_context(context: InvocationContext | None) -> bool:
+    return context is not None and context.role == ProviderRole.REVIEWER

crewplane/adapters/invokers/mock_invoker/fixtures.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from crewplane.architecture.contracts import InvocationContext
+
+
+def fixture_candidates(
+    output_dir: Path, context: InvocationContext | None
+) -> tuple[Path, ...]:
+    """Return candidate fixture paths from most specific to least specific."""
+
+    candidates: list[Path] = []
+    if context is not None:
+        node_dir = output_dir / context.node_id
+        role_name = context.role.strip().lower()
+        grouped_node_dir = (
+            node_dir / f"review-audit-round-{context.audit_round_num}"
+            if context.audit_round_num is not None
+            else None
+        )
+        search_dirs = [
+            candidate
+            for candidate in (grouped_node_dir, node_dir)
+            if candidate is not None
+        ]
+        for search_dir in search_dirs:
+            if context.round_num is not None:
+                candidates.append(
+                    search_dir / f"{context.task_id}_round{context.round_num}.md"
+                )
+                candidates.append(
+                    search_dir / f"{role_name}-round-{context.round_num}.md"
+                )
+            candidates.append(search_dir / f"{context.task_id}.md")
+            candidates.append(search_dir / f"{role_name}.md")
+            if search_dir == grouped_node_dir:
+                candidates.append(search_dir / f"default-{role_name}.md")
+        candidates.append(output_dir / f"{context.node_id}.md")
+        candidates.append(output_dir / f"default-{role_name}.md")
+    candidates.append(output_dir / "default.md")
+    return tuple(candidates)