shell-next 0.1.0__py3-none-any.whl

shell_next/__init__.py

@@ -0,0 +1,71 @@
+"""Persistent asynchronous shell sessions and deterministic downstream testing."""
+
+from shell_next.backends.mock.scenario import (
+    Advance,
+    Emit,
+    Failure,
+    MockExpectation,
+    MockScenario,
+    Receive,
+)
+from shell_next.backends.mock.session import MockShellSession
+from shell_next.frontend.handle import CommandHandle
+from shell_next.frontend.session import ShellSession, use_shell_session
+from shell_next.models.capabilities import SessionCapabilities
+from shell_next.models.commands import Command, ProcessCommand, SessionScript
+from shell_next.models.config import CaptureConfig, CommandOptions, SessionConfig, TimeoutPolicy
+from shell_next.models.input import CloseStdin, Expect, InputPlan, InputSummary, Send, SendLine
+from shell_next.models.privilege import PasswordProvider, PrivilegeReport, PrivilegeRequest
+from shell_next.models.results import (
+    BackendStatus,
+    CleanupReport,
+    CommandResult,
+    CommandSnapshot,
+    OutputEvent,
+    OutputResult,
+    SessionSnapshot,
+)
+from shell_next.models.state import Backend, ConcurrencyPolicy, Outcome, SessionState, StdinMode
+
+__all__ = [
+    "Advance",
+    "Backend",
+    "BackendStatus",
+    "CaptureConfig",
+    "CleanupReport",
+    "CloseStdin",
+    "Command",
+    "CommandHandle",
+    "CommandOptions",
+    "CommandResult",
+    "CommandSnapshot",
+    "ConcurrencyPolicy",
+    "Emit",
+    "Expect",
+    "Failure",
+    "InputPlan",
+    "InputSummary",
+    "MockExpectation",
+    "MockScenario",
+    "MockShellSession",
+    "Outcome",
+    "OutputEvent",
+    "OutputResult",
+    "PasswordProvider",
+    "PrivilegeReport",
+    "PrivilegeRequest",
+    "ProcessCommand",
+    "Receive",
+    "Send",
+    "SendLine",
+    "SessionCapabilities",
+    "SessionConfig",
+    "SessionScript",
+    "SessionSnapshot",
+    "SessionState",
+    "ShellSession",
+    "StdinMode",
+    "TimeoutPolicy",
+    "use_shell_session",
+]
+"""Curated public API names; transport modules remain implementation details."""

shell_next/backends/__init__.py

@@ -0,0 +1 @@
+"""Backends domain for shell-next."""

shell_next/backends/bash/__init__.py

@@ -0,0 +1 @@
+"""Bash-native script and privilege semantics."""

shell_next/backends/bash/authentication.py

@@ -0,0 +1,64 @@
+"""Dedicated sudo authentication in the business bridge's parent identity scope."""
+
+import subprocess
+from typing import BinaryIO
+
+
+def authenticate(
+    target: str | None,
+    attempts: int,
+    prompt: bytes,
+    requests: BinaryIO | None,
+    responses: BinaryIO | None,
+) -> tuple[bool, int]:
+    """Authenticate sudo without ever sharing the business stdin transport.
+
+    Authentication and business sudo invocations must have the same parent
+    bridge so sudo's non-terminal parent-process timestamp scope remains valid.
+
+    :param target: Optional sudo target user.
+    :param attempts: Maximum password submissions.
+    :param prompt: Unique private ASCII password prompt.
+    :param requests: Separate password-request pipe, or None for noninteractive sudo.
+    :param responses: Separate secret response pipe, or None for noninteractive sudo.
+    :returns: Authentication success and password-submission count.
+    """
+    argv = ["sudo", *(["-u", target] if target is not None else [])]
+    if requests is None or responses is None:
+        code = subprocess.run(
+            [*argv, "-n", "-v"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        ).returncode
+        return code == 0, 0
+    used = 0
+    with subprocess.Popen(
+        [*argv, "-S", "-p", prompt.decode("ascii"), "-v"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+    ) as process:
+        assert process.stdin is not None and process.stderr is not None
+        window = bytearray()
+        while data := process.stderr.read(1):
+            window.extend(data)
+            del window[: -len(prompt)]
+            if bytes(window) != prompt:
+                continue
+            if used >= attempts:
+                process.stdin.close()
+                break
+            requests.write(b"password\n")
+            requests.flush()
+            password = responses.readline(65536)
+            if not password.endswith(b"\n"):
+                process.stdin.close()
+                break
+            process.stdin.write(password)
+            process.stdin.flush()
+            del password
+            used += 1
+            window.clear()
+        process.stdin.close()
+        return process.wait() == 0, used

shell_next/backends/bash/containment.py

@@ -0,0 +1,34 @@
+"""POSIX process-group termination for persistent Bash sessions."""
+
+import os
+import signal
+import sys
+
+
+class PosixGroup:
+    """Own a process group whose leader was created with start_new_session=True.
+
+    :param pid: Interpreter PID, also its process-group identifier.
+    """
+
+    def __init__(self, pid: int) -> None:
+        """Retain the group identifier without acquiring another OS handle.
+
+        :param pid: Native process-group leader identifier.
+        """
+        self.pid = pid
+
+    def terminate(self, force: bool = True) -> None:
+        """Signal every member of the interpreter's process group.
+
+        :param force: SIGKILL if true, otherwise the cooperative SIGTERM request.
+        :raises OSError: Permissions or another OS error prevent termination.
+        """
+        if sys.platform != "win32":
+            try:
+                os.killpg(self.pid, signal.SIGKILL if force else signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+
+    def close(self) -> None:
+        """Release bookkeeping; process-group IDs have no closeable OS handle."""

shell_next/backends/bash/password_channel.py

@@ -0,0 +1,43 @@
+"""Frontend authentication transport, isolated from business input and capture."""
+
+from typing import TYPE_CHECKING
+
+from shell_next.errors import PrivilegeAuthenticationError
+
+if TYPE_CHECKING:
+    from shell_next.backends.native.channels import CommandChannel
+    from shell_next.frontend.handle import CommandHandle
+
+
+async def supply_passwords(
+    handle: CommandHandle, requests: CommandChannel, responses: CommandChannel
+) -> None:
+    """Call a secret supplier only for explicit private sudo password requests.
+
+    :param handle: Command holding the configured asynchronous password provider.
+    :param requests: Private authentication request channel.
+    :param responses: Private secret response channel.
+    :raises PrivilegeAuthenticationError: The request or supplied secret is invalid.
+    """
+    request = handle.options.privilege
+    provider = request.password_provider
+    assert provider is not None
+    count = 0
+    buffer = bytearray()
+    while data := await requests.read(64):
+        buffer.extend(data)
+        if len(buffer) > 128:
+            raise PrivilegeAuthenticationError("Invalid authentication request")
+        while b"\n" in buffer:
+            line, _, remaining = buffer.partition(b"\n")
+            buffer[:] = remaining
+            if line != b"password" or count >= request.attempts:
+                raise PrivilegeAuthenticationError("Authentication attempt limit reached")
+            password = await provider()
+            if not isinstance(password, bytes) or any(
+                value in password for value in (b"\n", b"\r", b"\0")
+            ):
+                raise PrivilegeAuthenticationError("Password provider returned an invalid secret")
+            await responses.send(password + b"\n")
+            del password
+            count += 1

shell_next/backends/bash/syntax.py

@@ -0,0 +1,30 @@
+"""Persistent Bash command wrappers with separate private control output."""
+
+import shlex
+
+
+def quote(value: str) -> str:
+    """Represent one literal Bash word using standard POSIX quoting.
+
+    :param value: Literal value.
+    :returns: Quoted native shell word.
+    """
+    return shlex.quote(value)
+
+
+def wrapper(text: str, token: str, script: bool, channels: dict[str, str]) -> str:
+    """Execute in current Bash scope and report status on reserved descriptor 9.
+
+    :param text: Trusted private script or bridge invocation.
+    :param token: Random command control marker.
+    :param script: Whether business stream redirection is required.
+    :param channels: stdin, stdout, and stderr FIFO paths.
+    :returns: Native wrapper text.
+    """
+    if script:
+        redirect = " ".join(
+            f"{fd}{direction}{quote(channels[name])}"
+            for fd, direction, name in ((0, "<", "stdin"), (1, ">", "stdout"), (2, ">", "stderr"))
+        )
+        text = f"{{ printf '{token}:ready\\n' >&9; {text}; }} {redirect}"
+    return f"{text}\nsn_status=$?\nprintf '{token}:%s\\n' \"$sn_status\" >&9\n"

shell_next/backends/cmd/__init__.py

@@ -0,0 +1 @@
+"""cmd-compatible batch semantics and ERRORLEVEL reporting."""

shell_next/backends/cmd/syntax.py

@@ -0,0 +1,32 @@
+"""Persistent cmd batch wrappers and conservative control-path validation."""
+
+from shell_next.errors import ConfigurationError
+
+
+def quote(value: str) -> str:
+    """Quote a trusted batch-control path without expansion or command injection.
+
+    :param value: Literal path.
+    :returns: Double-quoted batch word.
+    :raises ConfigurationError: Batch expansion makes this path unsafe.
+    """
+    if any(character in value for character in '\r\n"%!'):
+        raise ConfigurationError("cmd control paths cannot contain quotes, %, !, CR or LF")
+    return '"' + value + '"'
+
+
+def wrapper(text: str, token: str, script: bool, channels: dict[str, str]) -> str:
+    """Call a batch file in persistent state and preserve its ERRORLEVEL.
+
+    :param text: Private batch or bridge invocation.
+    :param token: Random command status marker.
+    :param script: Whether native stream redirection is required.
+    :param channels: Command-specific named pipe endpoints.
+    :returns: Native batch wrapper.
+    """
+    if script:
+        text += " " + " ".join(
+            f"{fd}{direction}{quote(channels[name])}"
+            for fd, direction, name in ((0, "<", "stdin"), (1, ">", "stdout"), (2, ">", "stderr"))
+        )
+    return f"@echo off\n{text}\necho {token}:%errorlevel%\n"

shell_next/backends/mock/__init__.py

@@ -0,0 +1 @@
+"""Mock domain for shell-next."""

shell_next/backends/mock/driver.py

@@ -0,0 +1,198 @@
+"""In-memory backend adapter running the production command lifecycle."""
+
+import asyncio
+from collections import deque
+from typing import TYPE_CHECKING
+
+from shell_next.backends.mock.scenario import (
+    Advance,
+    Emit,
+    MockExpectation,
+    MockScenario,
+    Receive,
+)
+from shell_next.errors import (
+    InputError,
+    MockUnexpectedInputError,
+    PrivilegeAuthenticationError,
+    SessionProtocolError,
+)
+from shell_next.models.commands import Command
+from shell_next.models.privilege import PrivilegeReport
+from shell_next.models.results import BackendStatus, CleanupReport
+
+if TYPE_CHECKING:
+    from shell_next.frontend.handle import CommandHandle
+    from shell_next.frontend.session import ShellSession
+
+
+class MockDriver:
+    """Deterministic transport that cannot start subprocesses or write files.
+
+    :param scenario: Ordered commands, input, and output expectations.
+    :param session: Owning frontend for simulated persistent state.
+    """
+
+    def __init__(self, scenario: MockScenario, session: ShellSession) -> None:
+        """Initialize pure in-memory execution state.
+
+        :param scenario: Strict expected behavior.
+        :param session: Owning frontend.
+        """
+        self.scenario = scenario
+        self.session = session
+        self.active: MockExpectation | None = None
+        self.inputs: deque[bytes | None] = deque()
+        self.changed = asyncio.Event()
+        self.handle: CommandHandle | None = None
+
+    async def start(self) -> None:
+        """Enter the mock without consulting or changing ambient process state."""
+
+    def reserve(self, command: Command) -> MockExpectation:
+        """Match and reserve the next command in deterministic FIFO order.
+
+        :param command: Submitted process or native script description.
+        :returns: The exact reserved expectation, even when other queued commands are stopped.
+        :raises MockUnexpectedCommandError: No strict expectation matches.
+        """
+        return self.scenario.reserve(command)
+
+    async def prepare(self, handle: CommandHandle) -> None:
+        """Adopt the reserved expectation without filesystem or subprocess work.
+
+        :param handle: Command receiving simulated transport behavior.
+        """
+        assert isinstance(handle.reservation, MockExpectation)
+        self.active = handle.reservation
+        self.handle = handle
+        self.inputs.clear()
+
+    async def execute(self, handle: CommandHandle) -> BackendStatus:
+        """Emit deterministic events, wait for input, and advance only virtual time.
+
+        :param handle: Command receiving output and readiness.
+        :returns: Configured backend-native status.
+        :raises MockUnexpectedInputError: Submitted input differs from the scenario.
+        :raises TimeoutError: Virtual execution reaches its configured deadline.
+        :raises InputError: An input failure was configured.
+        :raises OSError: A startup failure was configured.
+        :raises SessionProtocolError: A session loss was configured.
+        """
+        assert self.active is not None
+        if handle.privilege.requested:
+            request = handle.options.privilege
+            for _ in range(min(self.active.authentication_prompts, request.attempts)):
+                if request.password_provider is not None:
+                    try:
+                        await request.password_provider()
+                    except Exception:
+                        handle.privilege = PrivilegeReport(True, False)
+                        raise PrivilegeAuthenticationError("Password provider failed") from None
+                self.session.record("authenticate", "<redacted>")
+            handle.privilege = PrivilegeReport(
+                True,
+                self.active.authenticated,
+                min(self.active.authentication_prompts, request.attempts),
+            )
+            if not self.active.authenticated:
+                handle.ready.set()
+                return BackendStatus(126)
+        handle.ready.set()
+        elapsed = 0.0
+        for step in self.active.steps:
+            if isinstance(step, Emit):
+                await handle.emit(step.stream, step.data)
+            elif isinstance(step, Receive):
+                await self.receive(step.data)
+            elif isinstance(step, Advance):
+                deadline = handle.options.timeouts.execution
+                if deadline is not None and elapsed + step.seconds >= deadline:
+                    self.scenario.elapsed += max(0, deadline - elapsed)
+                    raise TimeoutError("Virtual command deadline expired")
+                elapsed += step.seconds
+                self.scenario.elapsed += step.seconds
+            else:
+                if step.kind == "input":
+                    raise InputError("Simulated input failure")
+                if step.kind == "startup":
+                    raise OSError("Simulated startup failure")
+                if step.kind == "session":
+                    raise SessionProtocolError("Simulated session loss")
+                handle.captures["stdout"].error = "Simulated capture failure"
+        if self.active.cwd is not None:
+            self.session.cwd = self.active.cwd
+        for name, value in self.active.env:
+            if value is None:
+                self.session.environment.pop(name, None)
+            else:
+                self.session.environment[name] = value
+        if any(self.inputs):
+            raise MockUnexpectedInputError("Unexpected input remained after the scenario ended")
+        return self.active.status
+
+    async def receive(self, expected: bytes | None) -> None:
+        """Match expected byte-stream input independently of transport chunk boundaries.
+
+        :param expected: Required bytes, or an explicit EOF marker.
+        :raises MockUnexpectedInputError: Bytes or EOF do not match the scenario.
+        """
+        offset = 0
+        while True:
+            while not self.inputs:
+                assert self.handle is not None
+                self.handle.virtual_blocked = True
+                self.changed.clear()
+                await self.changed.wait()
+            actual = self.inputs.popleft()
+            if expected is None:
+                if actual is not None:
+                    raise MockUnexpectedInputError("Expected stdin closure")
+                return
+            if actual is None:
+                raise MockUnexpectedInputError("Input ended before the expected bytes")
+            count = min(len(actual), len(expected) - offset)
+            if actual[:count] != expected[offset : offset + count]:
+                raise MockUnexpectedInputError("Input did not match the scenario")
+            offset += count
+            if len(actual) > count:
+                self.inputs.appendleft(actual[count:])
+            if offset == len(expected):
+                return
+
+    async def send(self, data: bytes) -> None:
+        """Queue one in-memory input submission without retaining a history copy.
+
+        :param data: Raw expected business input.
+        """
+        self.inputs.append(data)
+        assert self.handle is not None
+        self.handle.virtual_blocked = False
+        self.changed.set()
+
+    async def close_stdin(self) -> None:
+        """Queue an explicit in-memory EOF operation."""
+        self.inputs.append(None)
+        assert self.handle is not None
+        self.handle.virtual_blocked = False
+        self.changed.set()
+
+    async def finish(self) -> None:
+        """Discard transient input payloads after finalization."""
+        self.inputs.clear()
+        self.active = None
+
+    async def stop(self) -> CleanupReport:
+        """Simulate forced session invalidation without signals or real processes.
+
+        :returns: Deterministic successful containment report.
+        """
+        return CleanupReport(forced=True)
+
+    async def close(self) -> CleanupReport:
+        """Release in-memory input state without any operating-system side effect.
+
+        :returns: Deterministic shutdown report.
+        """
+        self.inputs.clear()
+        return CleanupReport()

shell_next/backends/mock/scenario.py

@@ -0,0 +1,131 @@
+"""Strict, deterministic command expectations without operating-system side effects."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from shell_next.errors import MockExpectationNotConsumedError, MockUnexpectedCommandError
+from shell_next.models.commands import Command
+from shell_next.models.config import validate_seconds
+from shell_next.models.input import StreamName
+from shell_next.models.results import BackendStatus
+
+
+@dataclass(frozen=True)
+class Emit:
+    """Emit one raw mock output chunk.
+
+    :param data: Raw bytes delivered to capture and prompt matching.
+    :param stream: Destination transport, defaulting to stdout.
+    """
+
+    data: bytes
+    stream: StreamName = "stdout"
+
+
+@dataclass(frozen=True)
+class Receive:
+    """Require one input submission or explicit EOF.
+
+    :param data: Expected bytes, or None for stdin closure; always hidden in repr.
+    """
+
+    data: bytes | None = field(repr=False)
+
+
+@dataclass(frozen=True)
+class Advance:
+    """Advance virtual command time without sleeping.
+
+    :param seconds: Nonnegative virtual duration in seconds.
+    """
+
+    seconds: float
+
+    def __post_init__(self) -> None:
+        """Reject virtual time moving backwards or becoming nonfinite.
+
+        :raises ConfigurationError: The virtual duration is invalid.
+        """
+        validate_seconds(self.seconds, "virtual seconds")
+
+
+@dataclass(frozen=True)
+class Failure:
+    """Inject a transport or protocol failure deterministically.
+
+    :param kind: Input, output, startup, or session failure category.
+    """
+
+    kind: Literal["input", "output", "startup", "session"]
+
+
+@dataclass(frozen=True)
+class MockExpectation:
+    """One expected command with ordered interaction and simulated native status.
+
+    :param command: Exact expected structural process or script.
+    :param steps: Ordered output, input, time, and failure steps.
+    :param status: Native result after all interaction steps.
+    :param cwd: Optional simulated persistent directory change.
+    :param env: Simulated exported environment updates; None removes a variable.
+    :param authentication_prompts: Simulated private password requests; zero models a cache hit.
+    :param authenticated: Whether simulated privilege authentication succeeds.
+    """
+
+    command: Command
+    steps: tuple[Emit | Receive | Advance | Failure, ...] = ()
+    status: BackendStatus = field(default_factory=lambda: BackendStatus(0))
+    cwd: str | None = None
+    env: tuple[tuple[str, str | None], ...] = ()
+    authentication_prompts: int = 0
+    authenticated: bool = True
+
+
+@dataclass
+class MockScenario:
+    """FIFO expectations, strict by default, with deterministic observable history.
+
+    :param expectations: Ordered expected commands.
+    :param strict: Reject unexpected commands and unconsumed required expectations.
+    :param calls: Observable operations; secrets must already be redacted.
+    :param elapsed: Virtual monotonic seconds, starting at zero.
+    :param cursor: Number of expectations reserved by submissions.
+    """
+
+    expectations: list[MockExpectation] = field(default_factory=list)
+    strict: bool = True
+    calls: list[tuple[object, ...]] = field(default_factory=list)
+    elapsed: float = 0.0
+    cursor: int = 0
+
+    def reserve(self, command: Command) -> MockExpectation:
+        """Consume the next command expectation without starting any execution.
+
+        :param command: Submitted command description.
+        :returns: The matching expectation or permissive empty result.
+        :raises MockUnexpectedCommandError: Strict FIFO expectations do not match.
+        """
+        if self.cursor < len(self.expectations):
+            expected = self.expectations[self.cursor]
+            if expected.command == command:
+                self.cursor += 1
+                return expected
+        if self.strict:
+            raise MockUnexpectedCommandError("Command did not match the next scenario expectation")
+        return MockExpectation(command)
+
+    def assert_consumed(self) -> None:
+        """Require all declared command expectations to have been submitted.
+
+        :raises MockExpectationNotConsumedError: Strict expectations remain unused.
+        """
+        if self.strict and self.cursor != len(self.expectations):
+            raise MockExpectationNotConsumedError("Required command expectations remain unused")
+
+    def assert_called(self, command: Command) -> None:
+        """Assert that a command was submitted through the normal frontend.
+
+        :param command: Expected submitted description.
+        :raises AssertionError: No matching submission exists.
+        """
+        assert ("submit", command) in self.calls, "Command was not submitted"