shell-next 0.1.0__py3-none-any.whl

shell_next/backends/mock/session.py

@@ -0,0 +1,151 @@
+"""First-class session test double using the production ownership frontend."""
+
+import ntpath
+import posixpath
+import re
+from dataclasses import replace
+
+from shell_next.backends.mock.driver import MockDriver
+from shell_next.backends.mock.scenario import MockScenario
+from shell_next.backends.mock.state import state_access
+from shell_next.errors import ConfigurationError
+from shell_next.frontend.session import ShellSession
+from shell_next.models.config import SessionConfig
+from shell_next.models.state import Backend
+
+
+class MockShellSession(ShellSession):
+    """Side-effect-free session with virtual state and strict command expectations.
+
+    :param config: Normal application session configuration.
+    :param scenario: Optional predetermined commands and interactions.
+    """
+
+    def __init__(self, config: SessionConfig, scenario: MockScenario | None = None) -> None:
+        """Replace native transport before session entry and disable implicit files.
+
+        :param config: Normal session configuration.
+        :param scenario: Strict scenario, or a new empty strict scenario.
+        """
+        super().__init__(replace(config, capture=replace(config.capture, directory=None)))
+        self.scenario = scenario if scenario is not None else MockScenario()
+        self.driver = MockDriver(self.scenario, self)
+        self.cwd = config.cwd or ("C:\\" if config.backend != Backend.BASH else "/")
+        self.session_id = "mock-session"
+        self.virtual_time = True
+        self.command_count = 0
+
+    def next_command_id(self) -> str:
+        """Allocate deterministic scenario-local identifiers.
+
+        :returns: Sequential readable mock command identifier.
+        """
+        self.command_count += 1
+        return f"mock-command-{self.command_count}"
+
+    @classmethod
+    def configured(cls, scenario: MockScenario) -> type[MockShellSession]:
+        """Bind a scenario to the official config._session_cls injection point.
+
+        :param scenario: Predetermined application behavior to assert.
+        :returns: Session implementation class bound to this scenario.
+        """
+
+        class ScenarioSession(MockShellSession):
+            """Session implementation bound to one explicitly supplied test scenario."""
+
+            def __init__(self, config: SessionConfig) -> None:
+                """Attach the bound scenario without affecting application configuration.
+
+                :param config: Application's normal configuration.
+                """
+                super().__init__(config, scenario)
+
+        return ScenarioSession
+
+    def clock(self) -> float:
+        """Read virtual time without consulting the real monotonic clock.
+
+        :returns: Scenario time in simulated seconds.
+        """
+        return self.scenario.elapsed
+
+    def record(self, operation: str, *args: object) -> None:
+        """Record ordered observable operations with pre-redacted secret payloads.
+
+        :param operation: Operation name.
+        :param args: Safe arguments; input secrets have already been redacted.
+        """
+        self.scenario.calls.append((operation, *args))
+
+    async def __aexit__(self, *exc: object) -> None:
+        """Close and validate strict expectations without masking a body exception.
+
+        :param exc: Python context exception information.
+        :raises MockExpectationNotConsumedError: Required expectations remain unused.
+        """
+        await self.aclose()
+        if not exc or exc[0] is None:
+            self.scenario.assert_consumed()
+
+    async def chdir(self, path: str) -> None:
+        """Change only virtual working-directory state.
+
+        :param path: Virtual path; POSIX relative paths resolve against virtual cwd.
+        """
+        async with state_access(self):
+            paths = posixpath if self.config.backend == Backend.BASH else ntpath
+            self.cwd = paths.normpath(paths.join(self.cwd or "/", path))
+            self.record("chdir", path)
+
+    async def set_env(self, name: str, value: str) -> None:
+        """Update only the virtual exported environment.
+
+        :param name: Nonempty environment name without equals or NUL.
+        :param value: NUL-free environment value.
+        :raises ConfigurationError: The name or value is invalid.
+        """
+        async with state_access(self):
+            if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name) is None or "\0" in value:
+                raise ConfigurationError("Invalid portable environment name or value")
+            self.environment[name] = value
+            self.record("set_env", name)
+
+    async def unset_env(self, name: str) -> None:
+        """Remove an exported variable from the virtual environment.
+
+        :param name: Virtual variable name.
+        """
+        async with state_access(self):
+            if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name) is None:
+                raise ConfigurationError("Invalid portable environment name")
+            self.environment.pop(name, None)
+            self.record("unset_env", name)
+
+    async def get_cwd(self) -> str:
+        """Read the virtual working directory without calling os.getcwd.
+
+        :returns: Virtual directory string.
+        """
+        async with state_access(self):
+            self.record("get_cwd")
+            return self.cwd or "/"
+
+    async def get_env(self, name: str | None = None) -> str | dict[str, str] | None:
+        """Read virtual exported state without consulting os.environ.
+
+        :param name: Specific variable or None for a copied environment view.
+        :returns: Value, missing marker, or copied environment dictionary.
+        """
+        async with state_access(self):
+            self.record("get_env", name)
+            return self.environment.get(name) if name is not None else dict(self.environment)
+
+    async def ping(self) -> bool:
+        """Observe virtual session health without consuming a user expectation.
+
+        :returns: Whether the mock remains usable.
+        """
+        async with state_access(self):
+            self.record("ping")
+            return self.is_usable

shell_next/backends/mock/state.py

@@ -0,0 +1,25 @@
+"""Virtual state access through the common lifecycle and execution lease."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+from shell_next.frontend.observation import checkpoint
+
+if TYPE_CHECKING:
+    from shell_next.frontend.session import ShellSession
+
+
+@asynccontextmanager
+async def state_access(session: ShellSession) -> AsyncIterator[None]:
+    """Serialize a virtual state operation after previously submitted command work.
+
+    :param session: Owning mock session with normal concurrency configuration.
+    :returns: Scope holding the session's execution lease.
+    :raises SessionError: Lifecycle, busy, or reentrancy validation fails.
+    """
+    session.validate_submission()
+    await checkpoint()
+    async with session.lease:
+        session.validate_submission()
+        yield

shell_next/backends/native/__init__.py

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

shell_next/backends/native/bridge.py

@@ -0,0 +1,65 @@
+"""Structural subprocess execution inside the current shell's exported state."""
+
+import json
+import subprocess
+import sys
+from contextlib import ExitStack
+from pathlib import Path
+
+from shell_next.backends.bash.authentication import authenticate
+
+
+def main(path: str) -> int:
+    """Run a JSON-described executable without interpreting its arguments as shell text.
+
+    :param path: Private command manifest containing argv and pipe endpoints.
+    :returns: Native process exit code, or 127 if the executable cannot start.
+    """
+    manifest = json.loads(Path(path).read_text(encoding="utf-8"))
+    with (
+        open(manifest["stdout"], "wb", buffering=0) as stdout,
+        open(manifest["stderr"], "wb", buffering=0) as stderr,
+        open(manifest["stdin"], "rb", buffering=0) as stdin,
+    ):
+        argv = manifest["argv"]
+        try:
+            if manifest.get("elevated"):
+                with ExitStack() as stack:
+                    requests = responses = None
+                    if manifest["interactive"]:
+                        requests = stack.enter_context(
+                            open(manifest["auth_out"], "wb", buffering=0)
+                        )
+                        responses = stack.enter_context(
+                            open(manifest["auth_in"], "rb", buffering=0)
+                        )
+                        print(manifest["token"] + ":auth_ready", flush=True)
+                    authenticated, attempts = authenticate(
+                        manifest["target"],
+                        manifest["attempts"],
+                        (manifest["token"] + "-password:").encode("ascii"),
+                        requests,
+                        responses,
+                    )
+                print(f"{manifest['token']}:auth:{int(authenticated)}:{attempts}", flush=True)
+                if not authenticated:
+                    print(manifest["token"] + ":ready", flush=True)
+                    return 126
+                argv = [
+                    "sudo",
+                    "-n",
+                    *(["-u", manifest["target"]] if manifest["target"] else []),
+                    "--",
+                    *argv,
+                ]
+            print(manifest["token"] + ":ready", flush=True)
+            return subprocess.run(argv, stdin=stdin, stdout=stdout, stderr=stderr).returncode
+        except OSError:
+            print(manifest["token"] + ":ready", flush=True)
+            print(manifest["token"] + ":startup_failure", flush=True)
+            stderr.write(b"shell-next: executable could not start\n")
+            return 127
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1]))

shell_next/backends/native/channels.py

@@ -0,0 +1,116 @@
+"""Command-specific byte pipes; no shell control bytes share business input."""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+
+class CommandChannel:
+    """One named pipe endpoint, using Windows IOCP or a POSIX FIFO.
+
+    :param path: Private pipe name or FIFO path.
+    :param input_channel: True when the package writes business input.
+    """
+
+    def __init__(self, path: str, input_channel: bool = False) -> None:
+        """Initialize endpoint ownership without creating operating-system resources.
+
+        :param path: Private endpoint name.
+        :param input_channel: Whether this endpoint supplies stdin.
+        """
+        self.path = path
+        self.input_channel = input_channel
+        self.reader = asyncio.StreamReader()
+        self.writer: asyncio.StreamWriter | None = None
+        self.connected = asyncio.Event()
+        self.transport: asyncio.BaseTransport | None = None
+        self.servers: list[Any] = []
+        self.keeper: int | None = None
+
+    def accept(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        """Adopt the first Windows pipe client and reject additional connections.
+
+        :param reader: Client input stream.
+        :param writer: Client output stream.
+        """
+        if self.connected.is_set():
+            writer.close()
+            return
+        self.reader = reader
+        self.writer = writer
+        self.connected.set()
+
+    async def open(self) -> None:
+        """Create a private endpoint with bounded asyncio transport buffering.
+
+        :raises OSError: The operating system cannot create the endpoint.
+        """
+        loop = asyncio.get_running_loop()
+        if sys.platform == "win32":
+
+            def protocol_factory() -> asyncio.StreamReaderProtocol:
+                """Build the Windows pipe server's stream adapter.
+
+                :returns: Protocol accepting one client into this channel.
+                """
+                return asyncio.StreamReaderProtocol(asyncio.StreamReader(), self.accept)
+
+            self.servers = await cast(Any, loop).start_serving_pipe(protocol_factory, self.path)
+        else:
+            os.mkfifo(self.path, 0o600)
+            read_fd = os.open(self.path, os.O_RDONLY | os.O_NONBLOCK)
+            self.keeper = os.open(self.path, os.O_WRONLY | os.O_NONBLOCK)
+            if self.input_channel:
+                protocol = asyncio.streams.FlowControlMixin(loop=loop)
+                pipe = os.fdopen(self.keeper, "wb", buffering=0)
+                self.keeper = read_fd
+                transport, _ = await loop.connect_write_pipe(lambda: protocol, pipe)
+                self.transport = transport
+                self.writer = asyncio.StreamWriter(transport, protocol, None, loop)
+            else:
+                pipe = os.fdopen(read_fd, "rb", buffering=0)
+                read_transport, _ = await loop.connect_read_pipe(
+                    lambda: asyncio.StreamReaderProtocol(self.reader), pipe
+                )
+                self.transport = read_transport
+            self.connected.set()
+
+    def release_keeper(self) -> None:
+        """Release the POSIX bootstrap descriptor after native redirection opens."""
+        if self.keeper is not None:
+            os.close(self.keeper)
+            self.keeper = None
+
+    async def read(self, size: int) -> bytes:
+        """Read command bytes after the shell connects the endpoint.
+
+        :param size: Maximum bytes returned in one transport chunk.
+        :returns: Bytes, or empty bytes at EOF.
+        """
+        await self.connected.wait()
+        return await self.reader.read(size)
+
+    async def send(self, data: bytes) -> None:
+        """Submit bytes through the endpoint with transport backpressure.
+
+        :param data: Business input bytes.
+        :raises ConnectionError: The native command closed its input.
+        """
+        await self.connected.wait()
+        assert self.writer is not None
+        self.writer.write(data)
+        await self.writer.drain()
+
+    def close(self) -> None:
+        """Idempotently close the endpoint and its bootstrap descriptors."""
+        self.release_keeper()
+        if self.writer is not None:
+            self.writer.close()
+        if self.transport is not None:
+            self.transport.close()
+        for server in self.servers:
+            server.close()
+        if sys.platform != "win32":
+            Path(self.path).unlink(missing_ok=True)

shell_next/backends/native/containment.py

@@ -0,0 +1,17 @@
+"""Dispatch containment to the selected operating-system domain."""
+
+import asyncio
+import sys
+
+from shell_next.backends.bash.containment import PosixGroup
+from shell_next.backends.windows.containment import WindowsJob
+
+
+def create_containment(process: asyncio.subprocess.Process) -> PosixGroup | WindowsJob:
+    """Contain an idle shell before any user-controlled command executes.
+
+    :param process: Newly created persistent interpreter.
+    :returns: Process-group or Job Object containment owner.
+    :raises OSError: The operating system rejects containment assignment.
+    """
+    return WindowsJob(process) if sys.platform == "win32" else PosixGroup(process.pid)

shell_next/backends/native/driver.py

@@ -0,0 +1,215 @@
+"""Command preparation and stream collection for persistent native interpreters."""
+
+import asyncio
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from shell_next.backends.bash.password_channel import supply_passwords
+from shell_next.backends.native.channels import CommandChannel
+from shell_next.backends.native.preparation import prepare_command
+from shell_next.backends.native.process import NativeProcess
+from shell_next.backends.native.syntax import quote, source_script
+from shell_next.backends.native.termination import stop_native
+from shell_next.errors import CaptureError, SessionProtocolError
+from shell_next.models.commands import Command
+from shell_next.models.config import SessionConfig
+from shell_next.models.privilege import PrivilegeReport
+from shell_next.models.results import BackendStatus, CleanupReport
+from shell_next.models.state import Backend
+
+if TYPE_CHECKING:
+    from shell_next.frontend.handle import CommandHandle
+
+
+class NativeDriver:
+    """Transport implementation shared by the three native shell languages.
+
+    :param config: Session configuration.
+    """
+
+    def __init__(self, config: SessionConfig) -> None:
+        """Create resource bookkeeping without starting the interpreter.
+
+        :param config: Validated session setup.
+        """
+        self.config = config
+        self.native = NativeProcess(config)
+        self.channels: dict[str, CommandChannel] = {}
+        self.files: list[Path] = []
+        self.pumps: list[asyncio.Task[None]] = []
+        self.activation: asyncio.Task[None] | None = None
+        self.ready = asyncio.Event()
+        self.timeouts = config.defaults.timeouts
+        self.authentication: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        """Start the interpreter and its containment unit.
+
+        :raises SessionProtocolError: The configured interpreter cannot start.
+        """
+        await self.native.start()
+
+    def reserve(self, command: Command) -> None:
+        """Accept a validated command; native preparation occurs after lease acquisition.
+
+        :param command: Submitted command description.
+        """
+
+    async def prepare(self, handle: CommandHandle) -> None:
+        """Create private command pipes and native wrapper files.
+
+        :param handle: Command owning these resources.
+        :raises OSError: Pipe or private file creation fails.
+        """
+        self.timeouts = handle.options.timeouts
+        await prepare_command(self, handle)
+
+    async def activate(self, handle: CommandHandle) -> None:
+        """Open caller input only after native command-specific channels exist.
+
+        :param handle: Command receiving the readiness notification.
+        """
+        if os.name == "nt":
+            await self.channels["stdin"].connected.wait()
+        else:
+            await self.ready.wait()
+        for channel in self.channels.values():
+            channel.release_keeper()
+        handle.ready.set()
+
+    async def pump(self, handle: CommandHandle, name: str) -> None:
+        """Continuously drain one command stream independently of subscribers.
+
+        :param handle: Owning command capture.
+        :param name: stdout or stderr endpoint.
+        """
+        channel = self.channels[name]
+        while data := await channel.read(65536):
+            await handle.emit("stdout" if name == "stdout" else "stderr", data)
+
+    async def execute(self, handle: CommandHandle) -> BackendStatus:
+        """Execute the prepared wrapper and await status plus bounded stream EOF.
+
+        :param handle: Command owning the current execution lease.
+        :returns: Backend-native completion status.
+        :raises SessionProtocolError: The shell loses its control channel.
+        :raises TimeoutError: Descendant output exceeds the drain deadline.
+        """
+        self.pumps = [asyncio.create_task(self.pump(handle, name)) for name in ("stdout", "stderr")]
+        self.activation = asyncio.create_task(self.activate(handle))
+        if "auth_out" in self.channels:
+            self.authentication = asyncio.create_task(
+                supply_passwords(handle, self.channels["auth_out"], self.channels["auth_in"])
+            )
+
+            def authentication_finished(task: asyncio.Task[None]) -> None:
+                """Stop execution if the secret provider fails.
+
+                :param task: Completed private authentication task.
+                """
+                if not task.cancelled() and task.exception() is not None:
+                    handle.startup_failed = True
+                    handle.privilege = PrivilegeReport(True, False)
+                    handle.stop_requested.set()
+
+            self.authentication.add_done_callback(authentication_finished)
+        wrapper = self.files[-1]
+        line = (
+            quote(str(wrapper), self.config.backend)
+            if self.config.backend == Backend.POWERSHELL
+            else source_script(wrapper, self.config.backend)
+        )
+        # PowerShell's driver accepts literal paths rather than expressions.
+        if self.config.backend == Backend.POWERSHELL:
+            line = str(wrapper)
+        await self.native.write(line + "\n")
+        process = self.native.process
+        assert process is not None and process.stdout is not None
+        token = (handle.command_id + ":").encode()
+        while True:
+            data = await self.native.read_control()
+            if not data:
+                raise SessionProtocolError(
+                    "Persistent shell exited before reporting command status"
+                )
+            index = data.find(token)
+            if index < 0:
+                continue
+            payload = data[index + len(token) :].strip()
+            if payload == b"auth_ready":
+                self.channels["auth_out"].release_keeper()
+                self.channels["auth_in"].release_keeper()
+                continue
+            if payload.startswith(b"auth:"):
+                _, authenticated, attempts = payload.split(b":")
+                handle.privilege = PrivilegeReport(True, authenticated == b"1", int(attempts))
+                continue
+            if payload == b"ready":
+                self.ready.set()
+                continue
+            if payload == b"startup_failure":
+                handle.startup_failed = True
+                continue
+            if payload.startswith(b"{"):
+                status = json.loads(payload)
+                result = BackendStatus(
+                    None, status["success"], status["native"], status["terminating"]
+                )
+            else:
+                result = BackendStatus(int(payload))
+            break
+        handle.backend_status = result
+        try:
+            async with asyncio.timeout(handle.options.timeouts.drain):
+                await asyncio.gather(*self.pumps)
+        except TimeoutError as exc:
+            raise CaptureError("Output drain deadline expired") from exc
+        return result
+
+    async def send(self, data: bytes) -> None:
+        """Send business input on the active command's dedicated pipe.
+
+        :param data: Input bytes, never shell control text.
+        """
+        await self.channels["stdin"].send(data)
+
+    async def close_stdin(self) -> None:
+        """Close only the active command's business input pipe."""
+        self.channels["stdin"].close()
+
+    async def finish(self) -> None:
+        """Release per-command pipes, pump tasks, and private wrapper files."""
+        tasks = [*self.pumps]
+        if self.authentication is not None:
+            tasks.append(self.authentication)
+        if self.activation is not None:
+            tasks.append(self.activation)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        for channel in self.channels.values():
+            channel.close()
+        self.channels.clear()
+        for path in self.files:
+            path.unlink(missing_ok=True)
+        self.files.clear()
+        self.pumps.clear()
+        self.activation = None
+        self.authentication = None
+
+    async def stop(self) -> CleanupReport:
+        """Invalidate and terminate the persistent shell's entire containment unit.
+
+        :returns: Process cleanup report.
+        """
+        return await stop_native(self)
+
+    async def close(self) -> CleanupReport:
+        """Close all session resources idempotently.
+
+        :returns: Process containment cleanup report.
+        """
+        await self.finish()
+        return await self.native.close()

shell_next/backends/native/preparation.py

@@ -0,0 +1,85 @@
+"""Private pipe, manifest, and wrapper preparation for native commands."""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from shell_next.backends.native.channels import CommandChannel
+from shell_next.backends.native.syntax import command_wrapper, invocation, source_script
+from shell_next.models.commands import ProcessCommand
+from shell_next.models.state import Backend
+
+if TYPE_CHECKING:
+    from shell_next.backends.native.driver import NativeDriver
+    from shell_next.frontend.handle import CommandHandle
+
+
+async def prepare_command(driver: NativeDriver, handle: CommandHandle) -> None:
+    """Allocate only the current command's native transport resources.
+
+    :param driver: Resource-owning native driver.
+    :param handle: Command with a validated identity request.
+    :raises OSError: Pipe or private manifest creation fails.
+    """
+    driver.ready.clear()
+    backend = driver.config.backend
+    token = handle.command_id
+    privilege = handle.options.privilege
+    elevated = privilege.requirement == "elevated"
+    driver.native.privileged_used |= elevated
+    names = ["stdout", "stderr", "stdin"]
+    if elevated and privilege.interactive:
+        names.extend(("auth_out", "auth_in"))
+    for name in names:
+        path = (
+            rf"\\.\pipe\shell-next-{token}-{name}"
+            if os.name == "nt"
+            else str(driver.native.path / f"{token}.{name}")
+        )
+        driver.channels[name] = CommandChannel(path, name in ("stdin", "auth_in"))
+        await driver.channels[name].open()
+    paths = {name: channel.path for name, channel in driver.channels.items()}
+    suffix = {Backend.BASH: ".sh", Backend.POWERSHELL: ".ps1", Backend.CMD: ".cmd"}[backend]
+    native_script = not isinstance(handle.command, ProcessCommand)
+    if isinstance(handle.command, ProcessCommand):
+        argv = [handle.command.executable, *handle.command.args]
+    else:
+        script = driver.native.path / f"{token}.user{suffix}"
+        driver.files.append(script)
+        script.write_text(handle.command.text + "\n", encoding="utf-8")
+        text = source_script(script, backend)
+        argv = [
+            driver.config.executable or "bash",
+            "--noprofile",
+            "--norc",
+            "-c",
+            handle.command.text,
+        ]
+    if not native_script or elevated:
+        manifest = driver.native.path / f"{token}.json"
+        driver.files.append(manifest)
+        manifest.write_text(
+            json.dumps(
+                {
+                    **paths,
+                    "argv": argv,
+                    "token": token,
+                    "elevated": elevated,
+                    "interactive": privilege.interactive,
+                    "target": privilege.target_identity,
+                    "attempts": privilege.attempts,
+                }
+            ),
+            encoding="utf-8",
+        )
+        text = invocation(
+            [sys.executable, str(Path(__file__).with_name("bridge.py")), str(manifest)], backend
+        )
+    wrapper = driver.native.path / f"{token}{suffix}"
+    driver.files.append(wrapper)
+    wrapper.write_text(
+        command_wrapper(backend, text, token, native_script and not elevated, paths),
+        encoding="utf-8",
+    )