sequential-hooks 0.1.0__py3-none-any.whl

sequential_hooks/_registry.py

@@ -0,0 +1,103 @@
+"""Discover and load host adapters through entry points."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, cast
+
+from sequential_hooks.hosts import API_VERSION, HostSpec
+
+if TYPE_CHECKING:
+    from importlib.metadata import EntryPoints
+
+_ENTRY_POINT_GROUP = 'sequential_hooks.hosts'
+_REQUIRED_ATTRIBUTES = (
+    'adapter',
+    'configuration_response',
+    'doctor_loader',
+    'events',
+    'name',
+    'payload_event',
+    'requires_event',
+)
+
+
+class HostLoadError(Exception):
+    """Report that no functioning host adapter exists for the selected name."""
+
+
+def _entry_points() -> EntryPoints:
+    """Read host entry points without loading metadata during CLI import."""
+    # Delay importing metadata until the caller selects or inventories hosts.
+    module = import_module('importlib.metadata')
+    return cast('EntryPoints', module.entry_points(group=_ENTRY_POINT_GROUP))
+
+
+def _registered_hosts() -> list[str]:
+    """Return sorted names in the host entry-point group."""
+    return sorted({entry.name for entry in _entry_points()})
+
+
+def _validate_host(name: str, spec: object) -> HostSpec:
+    """Validate and return one constructed host specification."""
+    for attribute in _REQUIRED_ATTRIBUTES:
+        if not hasattr(spec, attribute):
+            raise HostLoadError(f'host {name!r} does not provide {attribute}')
+    version = getattr(spec, 'api_version', None)
+    if version != API_VERSION:
+        raise HostLoadError(
+            f'host {name!r} implements host API {version!r}; '
+            f'sequential-hooks requires {API_VERSION}'
+        )
+    host_spec = cast('HostSpec', spec)
+    reported_name = host_spec.name
+    if reported_name != name:
+        raise HostLoadError(f'host {name!r} reports the name {reported_name!r}')
+    return host_spec
+
+
+def load_host(name: str) -> HostSpec:
+    """Load the host registered under one entry-point name.
+
+    Args:
+        name: Host name given to `--agent`.
+
+    Returns:
+        The registered host specification.
+
+    Raises:
+        HostLoadError: If the name is unregistered or registered more than
+            once, the entry point cannot be loaded, the object lacks a contract
+            attribute, its `api_version` differs from `API_VERSION`, or its
+            reported `name` differs from the entry-point name.
+    """
+    matches = [entry for entry in _entry_points() if entry.name == name]
+    if not matches:
+        hosts = ', '.join(_registered_hosts()) or 'none'
+        raise HostLoadError(f'unknown host {name!r}; registered hosts: {hosts}')
+    if len(matches) > 1:
+        raise HostLoadError(f'host {name!r} is registered {len(matches)} times')
+    try:
+        factory = matches[0].load()
+        spec = _validate_host(name, factory())
+    except HostLoadError:
+        raise
+    except Exception as error:
+        raise HostLoadError(f'host {name!r} failed to load: {error}') from error
+    return spec
+
+
+def host_requirements() -> dict[str, HostSpec]:
+    """Return each loadable host specification keyed by its registered name.
+
+    Returns:
+        Names in sorted order; hosts that fail to load are omitted.
+    """
+    requirements: dict[str, HostSpec] = {}
+    for name in _registered_hosts():
+        try:
+            spec = load_host(name)
+        except HostLoadError:
+            continue
+        requirements[name] = spec
+    return requirements

sequential_hooks/_runner.py

@@ -0,0 +1,48 @@
+"""Run ordered child steps through one host adapter."""
+
+from collections.abc import Iterable
+
+from sequential_hooks import _executor
+from sequential_hooks._types import Step
+from sequential_hooks.hosts import FinalResponse, HostAdapter
+
+
+def run_pipeline(
+    adapter: HostAdapter,
+    steps: Iterable[Step],
+    executor: _executor.ProcessExecutor,
+    step_timeout: float | None,
+    *,
+    allow_on_failure: bool,
+) -> FinalResponse:
+    """Run ordered steps until the adapter stops or finalizes.
+
+    Args:
+        adapter: Host-neutral interface to native protocol state.
+        steps: Child commands in execution order.
+        executor: Bounded process executor for each child.
+        step_timeout: Independent timeout in seconds for each child, or `None`
+            for no step execution deadline.
+        allow_on_failure: Whether explicit uncontained fallback is allowed.
+
+    Returns:
+        Terminal or finalized native host response.
+
+    Raises:
+        _executor.ForwardedSignal: If the executor forwards a handled wrapper
+            signal, propagated unchanged.
+        Exception: Any executor or adapter invariant exception, propagated
+            unchanged.
+    """
+    if not adapter.should_run_steps:
+        return adapter.finalize()
+    for step in steps:
+        result = executor.run(
+            step,
+            adapter.step_input(),
+            step_timeout,
+            allow_uncontained=allow_on_failure,
+        )
+        if adapter.consume(step, result) == 'stop':
+            break
+    return adapter.finalize()

sequential_hooks/_types.py

@@ -0,0 +1,125 @@
+"""Define the runner's concrete step, result, and failure records."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+
+class ContainmentState(StrEnum):
+    """Describe whether a child owns native process-tree containment.
+
+    The values are the documented `CONTAINMENT_STATES` strings that adapters
+    compare.
+
+    Attributes:
+        CONTAINED: Native process-tree containment is active.
+        UNCONTAINED: The child runs through an explicitly allowed fallback
+            without process-tree containment.
+    """
+
+    CONTAINED = 'contained'
+    UNCONTAINED = 'uncontained'
+
+
+class FailureKind(StrEnum):
+    """Classify an infrastructure failure before adapter interpretation.
+
+    The values are the documented `FAILURE_KINDS` strings that adapters
+    compare.
+
+    Attributes:
+        NOT_FOUND: The executable could not be resolved or started.
+        SPAWN: The operating system refused process creation.
+        CRASH: The child terminated with a native crash status.
+        TIMEOUT: The child exceeded its execution deadline.
+        OUTPUT_LIMIT: Standard output exceeded its byte budget.
+        OUTPUT_WORKER_TIMEOUT: A pipe worker did not stop within cleanup
+            bounds.
+        CONTAINMENT: Required process-tree containment could not be
+            established.
+        UNSUPPORTED_EXECUTABLE: Resolution found an unsupported executable
+            shim.
+    """
+
+    NOT_FOUND = 'not_found'
+    SPAWN = 'spawn'
+    CRASH = 'crash'
+    TIMEOUT = 'timeout'
+    OUTPUT_LIMIT = 'output_limit'
+    OUTPUT_WORKER_TIMEOUT = 'output_worker_timeout'
+    CONTAINMENT = 'containment'
+    UNSUPPORTED_EXECUTABLE = 'unsupported_executable'
+
+
+@dataclass(frozen=True)
+class Step:
+    """Describe one child command in its configured chain position.
+
+    Args:
+        index: One-based position used in diagnostics.
+        argv: Literal executable token and arguments.
+
+    Attributes:
+        index: One-based position used in diagnostics.
+        argv: Literal executable token and arguments.
+        name: Executable basename used in diagnostics.
+    """
+
+    index: int
+    argv: tuple[str, ...]
+
+    @property
+    def name(self) -> str:
+        """Return the executable basename used in diagnostics.
+
+        Returns:
+            Basename, or the original executable token when it has no basename.
+        """
+        basename = Path(self.argv[0]).name
+        return basename or self.argv[0]
+
+
+@dataclass(frozen=True)
+class StepFailure:
+    """Describe one bounded infrastructure failure.
+
+    Args:
+        kind: Stable infrastructure failure category.
+        message: Safe user-facing failure detail.
+        returncode: Child status when one was observed.
+
+    Attributes:
+        kind: Stable infrastructure failure category.
+        message: Safe user-facing failure detail.
+        returncode: Child status when one was observed.
+    """
+
+    kind: FailureKind
+    message: str
+    returncode: int | None = None
+
+
+@dataclass(frozen=True)
+class StepResult:
+    """Carry one child's bounded process outcome to an adapter.
+
+    Args:
+        returncode: Child status when one was observed.
+        stdout: Bounded child standard-output bytes.
+        blocking_stderr: Bounded decoded stderr retained for native responses.
+        failure: Infrastructure failure, if one occurred.
+        containment: Effective process-tree containment state.
+
+    Attributes:
+        returncode: Child status when one was observed.
+        stdout: Bounded child standard-output bytes.
+        blocking_stderr: Bounded decoded stderr retained for native responses.
+        failure: Infrastructure failure, if one occurred.
+        containment: Effective process-tree containment state.
+    """
+
+    returncode: int | None
+    stdout: bytes
+    blocking_stderr: str
+    failure: StepFailure | None = None
+    containment: ContainmentState = ContainmentState.CONTAINED

sequential_hooks/hosts/__init__.py

@@ -0,0 +1,130 @@
+"""Public host adapter contract, doctor records, and composition skeleton.
+
+An adapter package depends on this subpackage alone. It publishes the
+structural types a `sequential_hooks.hosts` entry point must satisfy, the
+doctor record types a loader produces, and `Composer`, the shared response
+composition skeleton a host may subclass instead of implementing `HostAdapter`
+directly.
+"""
+
+from sequential_hooks.hosts._contract import (
+    API_VERSION,
+    CONTAINMENT_STATES,
+    FAILURE_KINDS,
+    ChainControl,
+    Diagnostics,
+    DoctorLoader,
+    FinalResponse,
+    HostAdapter,
+    HostInputError,
+    HostSpec,
+    JsonObject,
+    JsonValue,
+    Step,
+    StepFailure,
+    StepResult,
+)
+from sequential_hooks.hosts._inspection import (
+    deduplicate_source_paths,
+    parse_timeout,
+    project_layers,
+)
+from sequential_hooks.hosts._json import (
+    JsonObjectExpectedError,
+    JsonProtocolError,
+    load_object,
+    load_object_text,
+)
+from sequential_hooks.hosts._records import (
+    ConfigSource,
+    ContractError,
+    Finding,
+    FindingSeverity,
+    InspectedCommand,
+    LaunchSemantics,
+    Registration,
+    SourceKind,
+    WrapperInvocation,
+    WrapperStep,
+)
+from sequential_hooks.hosts._skeleton import (
+    DIAGNOSTIC_LIMIT_CHARACTERS,
+    FINAL_RESPONSE_LIMIT_BYTES,
+    TERMINATION_FAILURES,
+    TRUNCATION_MARKER,
+    UNCONTAINED_WARNING,
+    AdapterOutputError,
+    Composer,
+    CompositionState,
+    Contribution,
+    NativeResponse,
+    Outcome,
+    OutputFailureKind,
+    UserContribution,
+    bounded_contributions,
+    bounded_diagnostic,
+    continue_after_failure,
+    encode_plain_response,
+    encode_response,
+    labeled,
+    optional_string,
+    reject_unsupported,
+    unsupported_fields,
+)
+
+__all__ = [
+    'API_VERSION',
+    'CONTAINMENT_STATES',
+    'DIAGNOSTIC_LIMIT_CHARACTERS',
+    'FAILURE_KINDS',
+    'FINAL_RESPONSE_LIMIT_BYTES',
+    'TERMINATION_FAILURES',
+    'TRUNCATION_MARKER',
+    'UNCONTAINED_WARNING',
+    'AdapterOutputError',
+    'ChainControl',
+    'Composer',
+    'CompositionState',
+    'ConfigSource',
+    'ContractError',
+    'Contribution',
+    'Diagnostics',
+    'DoctorLoader',
+    'FinalResponse',
+    'Finding',
+    'FindingSeverity',
+    'HostAdapter',
+    'HostInputError',
+    'HostSpec',
+    'InspectedCommand',
+    'JsonObject',
+    'JsonObjectExpectedError',
+    'JsonProtocolError',
+    'JsonValue',
+    'LaunchSemantics',
+    'NativeResponse',
+    'Outcome',
+    'OutputFailureKind',
+    'Registration',
+    'SourceKind',
+    'Step',
+    'StepFailure',
+    'StepResult',
+    'UserContribution',
+    'WrapperInvocation',
+    'WrapperStep',
+    'bounded_contributions',
+    'bounded_diagnostic',
+    'continue_after_failure',
+    'deduplicate_source_paths',
+    'encode_plain_response',
+    'encode_response',
+    'labeled',
+    'load_object',
+    'load_object_text',
+    'optional_string',
+    'parse_timeout',
+    'project_layers',
+    'reject_unsupported',
+    'unsupported_fields',
+]