ffl-python 0.1.4__py3-none-any.whl

ffl/_runtime.py

@@ -0,0 +1,1136 @@
+# Generated by APEBind. Do not edit directly.
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class APEProcessResult:
+    argv: tuple[str, ...]
+    return_code: int
+    stdout: str
+    stderr: str
+
+
+@dataclass(frozen=True)
+class APEEvent:
+    name: str
+    data: dict[str, Any]
+    raw: dict[str, Any]
+    known: bool
+
+
+class APEProcessError(RuntimeError):
+    def __init__(self, result: APEProcessResult):
+        super().__init__(
+            f'APE exited with code {result.return_code}: {result.stderr.strip()}'
+            f'{_wsl_interop_guidance(result.stderr)}'
+        )
+        self.result = result
+
+
+class APEEventError(RuntimeError):
+    pass
+
+
+def _normalize_ape_return_code(return_code: int) -> int:
+    """Convert Cosmopolitan's Windows wait status to the program exit code."""
+    if os.name == 'nt' and return_code > 0 and return_code % 256 == 0:
+        return return_code // 256
+
+    return return_code
+
+
+def _is_wsl2() -> bool:
+    try:
+        version = Path('/proc/version').read_text(encoding='utf-8').lower()
+    except OSError:
+        return False
+
+    return 'microsoft' in version or 'wsl' in version
+
+
+def _wsl_interop_guidance(stderr: str) -> str:
+    if 'tlserror([0x6300])' not in stderr.lower() or not _is_wsl2():
+        return ''
+
+    return (
+        '\n\nWSL2 may be executing this .com APE through Windows interop. '
+        'Run the following command in WSL, then restart the WSL session:\n\n'
+        "    sudo sh -c 'echo -1 > /proc/sys/fs/binfmt_misc/WSLInterop'"
+    )
+
+
+def _extract_field(value: Any, field_path: str | None) -> Any:
+    if not field_path:
+        return value
+
+    current = value
+
+    for part in field_path.split('.'):
+        current = current[part]
+
+    return current
+
+
+class _RuntimeFiles:
+    def __init__(self, directory: Path, paths: dict[str, Path]):
+        self._directory = directory
+        self._paths = paths
+        self._cleaned = False
+
+    @classmethod
+    def create(cls, operation: dict[str, Any]) -> _RuntimeFiles | None:
+        roles: dict[str, str] = {}
+        if operation['result']['format'] == 'json_file':
+            roles['result'] = 'result.json'
+
+        events = operation.get('events')
+        if events is not None and events['source']['kind'] == 'jsonl_file':
+            roles['events'] = 'events.jsonl'
+
+        if not roles:
+            return None
+
+        directory = Path(tempfile.mkdtemp(prefix='apebind-'))
+        paths = {
+            role: directory / file_name
+            for role, file_name in roles.items()
+        }
+
+        return cls(directory, paths)
+
+    def path(self, role: str) -> Path | None:
+        return self._paths.get(role)
+
+    def cleanup(self) -> None:
+        if self._cleaned:
+            return
+
+        shutil.rmtree(self._directory)
+        self._cleaned = True
+
+
+class _EventDecoder:
+    _MISSING = object()
+
+    def __init__(self, config: dict[str, Any]):
+        self._config = config
+        self._types = {
+            event_type['source_value']: event_type
+            for event_type in config['types']
+        }
+
+    @classmethod
+    def _field_value(cls, raw: dict[str, Any], field_path: str) -> Any:
+        try:
+            return _extract_field(raw, field_path)
+        except (KeyError, TypeError):
+            return cls._MISSING
+
+    @staticmethod
+    def _validated_value(event_name: str, field: dict[str, Any], value: Any) -> Any:
+        value_type = field['value_type']
+        valid = False
+
+        if value_type in ('string', 'path'):
+            valid = isinstance(value, str)
+        elif value_type == 'boolean':
+            valid = isinstance(value, bool)
+        elif value_type == 'integer':
+            valid = isinstance(value, int) and not isinstance(value, bool)
+        elif value_type == 'float':
+            valid = isinstance(value, (int, float)) and not isinstance(value, bool)
+        else:
+            raise APEEventError(f'Unsupported event field type: {value_type}')
+
+        if not valid:
+            raise APEEventError(
+                f"Event {event_name} field {field['name']} must be {value_type}"
+            )
+
+        if value_type == 'float':
+            return float(value)
+
+        return value
+
+    def decode(self, line: str) -> APEEvent:
+        try:
+            raw = json.loads(line)
+        except json.JSONDecodeError as error:
+            raise APEEventError(f'Invalid JSONL event: {line!r}') from error
+
+        if not isinstance(raw, dict):
+            raise APEEventError('JSONL event must be a JSON object')
+
+        try:
+            source_name = _extract_field(raw, self._config['discriminator'])
+        except (KeyError, TypeError) as error:
+            raise APEEventError(
+                f"Event is missing discriminator: {self._config['discriminator']}"
+            ) from error
+
+        if not isinstance(source_name, str) or not source_name:
+            raise APEEventError('Event discriminator must resolve to a non-empty string')
+
+        event_type = self._types.get(source_name)
+        if event_type is None:
+            return APEEvent(source_name, dict(raw), raw, False)
+
+        data: dict[str, Any] = {}
+
+        for event_field in event_type['fields']:
+            value = self._field_value(raw, event_field['name'])
+            if value is self._MISSING:
+                if event_field['required']:
+                    raise APEEventError(
+                        f"Event {event_type['name']} is missing field: {event_field['name']}"
+                    )
+
+                continue
+
+            data[event_field['api_name']] = self._validated_value(
+                event_type['name'],
+                event_field,
+                value,
+            )
+
+        return APEEvent(event_type['name'], data, raw, True)
+
+
+class _JSONLFileEventChannel:
+    def __init__(
+        self,
+        path: Path,
+        config: dict[str, Any],
+        is_running: Callable[[], bool],
+    ):
+        self._path = path
+        self._decoder = _EventDecoder(config)
+        self._is_running = is_running
+        self._events: list[APEEvent] = []
+        self._listeners: dict[str, list[Callable[[dict[str, Any]], None]]] = {}
+        self._condition = threading.Condition()
+        self._thread: threading.Thread | None = None
+        self._error: BaseException | None = None
+        self._finished = False
+        self._offset = 0
+        self._buffer = ''
+
+    def start(self) -> None:
+        with self._condition:
+            if self._thread is not None:
+                return
+
+            self._thread = threading.Thread(
+                target=self._run,
+                name='apebind-event-channel',
+                daemon=True,
+            )
+            self._thread.start()
+
+    def _read_new_text(self) -> str:
+        if not self._path.exists():
+            return ''
+
+        text = self._path.read_text(encoding='utf-8', errors='strict')
+        if len(text) < self._offset:
+            raise APEEventError('JSONL event file was truncated while being consumed')
+
+        chunk = text[self._offset:]
+        self._offset = len(text)
+        return chunk
+
+    def _publish(self, event: APEEvent) -> None:
+        with self._condition:
+            self._events.append(event)
+            listeners = tuple(self._listeners.get(event.name, ()))
+            self._condition.notify_all()
+
+        for listener in listeners:
+            listener(event.data)
+
+    def _consume_available(self, *, final: bool = False) -> None:
+        self._buffer += self._read_new_text()
+        lines = self._buffer.splitlines(keepends=True)
+        self._buffer = ''
+
+        for line in lines:
+            if not line.endswith(('\n', '\r')):
+                self._buffer = line
+                continue
+
+            content = line.strip()
+            if content:
+                self._publish(self._decoder.decode(content))
+
+        if final and self._buffer.strip():
+            self._publish(self._decoder.decode(self._buffer.strip()))
+            self._buffer = ''
+
+    def _run(self) -> None:
+        try:
+            while self._is_running():
+                self._consume_available()
+                time.sleep(0.02)
+
+            self._consume_available(final=True)
+        except BaseException as error:
+            with self._condition:
+                self._error = error
+        finally:
+            with self._condition:
+                self._finished = True
+                self._condition.notify_all()
+
+    def on(
+        self,
+        event_name: str,
+        listener: Callable[[dict[str, Any]], None],
+    ) -> None:
+        self.start()
+
+        with self._condition:
+            history = tuple(event for event in self._events if event.name == event_name)
+            self._listeners.setdefault(event_name, []).append(listener)
+
+        for event in history:
+            listener(event.data)
+
+    def events(self, timeout: float | None = None) -> Iterator[APEEvent]:
+        self.start()
+        index = 0
+        deadline = None if timeout is None else time.monotonic() + timeout
+
+        while True:
+            with self._condition:
+                while index >= len(self._events) and not self._finished:
+                    remaining = None
+                    if deadline is not None:
+                        remaining = deadline - time.monotonic()
+                        if remaining <= 0:
+                            raise TimeoutError('Timed out waiting for an APE event')
+
+                    self._condition.wait(timeout=remaining)
+
+                if index < len(self._events):
+                    event = self._events[index]
+                    index += 1
+                else:
+                    if self._error is not None:
+                        raise self._error
+
+                    return
+
+            yield event
+
+    def wait(self) -> None:
+        thread = self._thread
+        if thread is None:
+            return
+
+        thread.join()
+
+        if self._error is not None:
+            raise self._error
+
+
+class ProcessSession:
+    def __init__(
+        self,
+        process: subprocess.Popen[bytes],
+        argv: list[str],
+        runtime_files: _RuntimeFiles | None = None,
+        event_config: dict[str, Any] | None = None,
+        capture_stdout: bool = True,
+    ):
+        self._process = process
+        self._argv = tuple(argv)
+        self._runtime_files = runtime_files
+        self._result: Any = None
+        self._process_result: APEProcessResult | None = None
+        self._stopped_by_client = False
+        self._capture_stdout = capture_stdout
+        self._streamed_stdout_consumed = capture_stdout
+        self._streamed_stdout_iterating = False
+        self._streamed_stdout_lock = threading.Lock()
+        self._stdout_chunks: list[bytes] = []
+        self._stderr_chunks: list[bytes] = []
+        self._output_condition = threading.Condition()
+        self._stdout_finished = not capture_stdout
+        self._stderr_finished = False
+        self._stdout_error: OSError | None = None
+        self._stderr_error: OSError | None = None
+        self._stdin_source: Any = None
+        self._stdin_thread: threading.Thread | None = None
+        self._stdin_error: BaseException | None = None
+        self._stdin_lock = threading.Lock()
+        self._event_channel = self._create_event_channel(event_config)
+        self._exit_listeners: list[Callable[[], None]] = []
+        self._exit_lock = threading.Lock()
+        self._exit_notified = False
+
+        if self._event_channel is not None:
+            self._event_channel.start()
+
+        self._stdout_thread = self._start_output_reader(
+            self._process.stdout,
+            self._stdout_chunks,
+            is_stdout=True,
+        ) if capture_stdout else None
+        self._stderr_thread = self._start_output_reader(
+            self._process.stderr,
+            self._stderr_chunks,
+            is_stdout=False,
+        )
+
+        threading.Thread(
+            target=self._watch_for_exit,
+            name='apebind-process-session',
+            daemon=True,
+        ).start()
+
+    def _watch_for_exit(self) -> None:
+        self._process.wait()
+        self._close_stdin_source()
+        self._notify_exit()
+
+    def _start_output_reader(
+        self,
+        stream: Any,
+        chunks: list[bytes],
+        *,
+        is_stdout: bool,
+    ) -> threading.Thread | None:
+        if stream is None:
+            with self._output_condition:
+                if is_stdout:
+                    self._stdout_finished = True
+                else:
+                    self._stderr_finished = True
+                self._output_condition.notify_all()
+            return None
+
+        thread = threading.Thread(
+            target=self._drain_output,
+            args=(stream, chunks, is_stdout),
+            name='apebind-stdout' if is_stdout else 'apebind-stderr',
+            daemon=True,
+        )
+        thread.start()
+        return thread
+
+    def _drain_output(
+        self,
+        stream: Any,
+        chunks: list[bytes],
+        is_stdout: bool,
+    ) -> None:
+        try:
+            while chunk := stream.read(65536):
+                with self._output_condition:
+                    chunks.append(chunk)
+                    self._output_condition.notify_all()
+        except OSError as error:
+            with self._output_condition:
+                if is_stdout:
+                    self._stdout_error = error
+                else:
+                    self._stderr_error = error
+        finally:
+            stream.close()
+            with self._output_condition:
+                if is_stdout:
+                    self._stdout_finished = True
+                else:
+                    self._stderr_finished = True
+                self._output_condition.notify_all()
+
+    def _notify_exit(self) -> None:
+        with self._exit_lock:
+            if self._exit_notified:
+                return
+
+            self._exit_notified = True
+            listeners = tuple(self._exit_listeners)
+            self._exit_listeners.clear()
+
+        for listener in listeners:
+            listener()
+
+    def _create_event_channel(
+        self,
+        event_config: dict[str, Any] | None,
+    ) -> _JSONLFileEventChannel | None:
+        if event_config is None:
+            return None
+
+        if self._runtime_files is None:
+            raise RuntimeError('Event operation has no runtime-owned files')
+
+        event_path = self._runtime_files.path('events')
+        if event_path is None:
+            raise RuntimeError('Event operation has no runtime-owned event path')
+
+        return _JSONLFileEventChannel(event_path, event_config, lambda: self.running)
+
+    @property
+    def argv(self) -> tuple[str, ...]:
+        return self._argv
+
+    @property
+    def pid(self) -> int:
+        return self._process.pid
+
+    @property
+    def running(self) -> bool:
+        return self._process.poll() is None
+
+    @property
+    def return_code(self) -> int | None:
+        return_code = self._process.poll()
+        if return_code is None:
+            return None
+
+        if self._stopped_by_client:
+            return 0
+
+        return _normalize_ape_return_code(return_code)
+
+    @property
+    def stdout(self):
+        return self._process.stdout
+
+    @property
+    def stderr(self):
+        return self._process.stderr
+
+    @property
+    def result(self) -> Any:
+        return self._result
+
+    @property
+    def process_result(self) -> APEProcessResult:
+        if self._process_result is None:
+            raise RuntimeError('APE process has not completed')
+
+        return self._process_result
+
+    def set_result(self, result: Any) -> None:
+        self._result = result
+
+    def on_exit(self, listener: Callable[[], None]) -> ProcessSession:
+        with self._exit_lock:
+            if not self._exit_notified:
+                self._exit_listeners.append(listener)
+                return self
+
+        listener()
+        return self
+
+    def on(
+        self,
+        event_name: str,
+        listener: Callable[[dict[str, Any]], None],
+    ) -> ProcessSession:
+        if self._event_channel is None:
+            raise RuntimeError('This operation does not define an event stream')
+
+        self._event_channel.on(event_name, listener)
+        return self
+
+    def events(self, timeout: float | None = None) -> Iterator[APEEvent]:
+        if self._event_channel is None:
+            raise RuntimeError('This operation does not define an event stream')
+
+        yield from self._event_channel.events(timeout=timeout)
+
+    def iter_stdout(self) -> Iterator[str]:
+        for chunk in self.iter_stdout_bytes():
+            yield chunk.decode('utf-8', errors='replace')
+
+    def iter_stdout_bytes(self) -> Iterator[bytes]:
+        if self._process.stdout is None:
+            self._streamed_stdout_consumed = True
+            return
+
+        if not self._capture_stdout:
+            with self._streamed_stdout_lock:
+                if self._streamed_stdout_iterating:
+                    raise RuntimeError('streamed stdout can only be consumed once')
+
+                self._streamed_stdout_iterating = True
+
+            consumed = False
+
+            try:
+                while chunk := self._process.stdout.read(65536):
+                    yield chunk
+
+                consumed = True
+            finally:
+                self._process.stdout.close()
+
+                with self._streamed_stdout_lock:
+                    self._streamed_stdout_consumed = consumed
+                    self._streamed_stdout_iterating = False
+
+            return
+
+        index = 0
+        while True:
+            with self._output_condition:
+                while index == len(self._stdout_chunks) and not self._stdout_finished:
+                    self._output_condition.wait()
+
+                if index < len(self._stdout_chunks):
+                    chunk = self._stdout_chunks[index]
+                    index += 1
+                else:
+                    if self._stdout_error is not None and not self._stopped_by_client:
+                        raise self._stdout_error
+                    return
+
+            yield chunk
+
+    def attach_stdin(self, source: Any) -> None:
+        self._stdin_source = source
+        self._stdin_thread = threading.Thread(
+            target=self._copy_stdin,
+            args=(source,),
+            name='apebind-stdin',
+            daemon=True,
+        )
+        self._stdin_thread.start()
+
+    def _copy_stdin(self, source: Any) -> None:
+        if self._process.stdin is None:
+            raise RuntimeError('APE stdin pipe was not created')
+
+        try:
+            while chunk := source.read(65536):
+                self._process.stdin.write(chunk)
+
+            self._process.stdin.flush()
+        except BrokenPipeError:
+            # The child can close stdin before it exits; the producer must not
+            # turn that normal process lifecycle into an unhandled failure.
+            pass
+        except OSError as error:
+            if self.running and not self._stopped_by_client:
+                self._stdin_error = error
+                self._process.terminate()
+        except BaseException as error:
+            if self.running and not self._stopped_by_client:
+                self._stdin_error = error
+                self._process.terminate()
+        finally:
+            if self._process.stdin is not None:
+                self._process.stdin.close()
+
+    def _close_stdin_source(self) -> None:
+        with self._stdin_lock:
+            source = self._stdin_source
+            self._stdin_source = None
+
+        if source is not None and hasattr(source, 'close'):
+            source.close()
+
+    def _wait_for_stdin(self) -> None:
+        if self._stdin_thread is not None:
+            self._stdin_thread.join()
+
+        if self._stdin_error is not None and not self._stopped_by_client:
+            raise self._stdin_error
+
+    def _wait_for_event_channel(self) -> None:
+        if self._event_channel is not None:
+            self._event_channel.wait()
+
+    def _wait_for_output(self, ignore_read_errors: bool) -> None:
+        for thread in (self._stdout_thread, self._stderr_thread):
+            if thread is not None:
+                thread.join()
+
+        if not ignore_read_errors:
+            if self._stdout_error is not None:
+                raise self._stdout_error
+            if self._stderr_error is not None:
+                raise self._stderr_error
+
+    def _captured_stdout(self) -> bytes:
+        if not self._capture_stdout:
+            return b''
+
+        with self._output_condition:
+            return b''.join(self._stdout_chunks)
+
+    def _captured_stderr(self) -> bytes:
+        with self._output_condition:
+            return b''.join(self._stderr_chunks)
+
+    def _wait(
+        self,
+        timeout: float | None = None,
+        *,
+        require_streamed_stdout: bool,
+    ) -> int:
+        if not self._capture_stdout and not self._streamed_stdout_consumed:
+            if require_streamed_stdout:
+                raise RuntimeError(
+                    'streamed stdout must be consumed before waiting for the process'
+                )
+
+            if self._process.stdout is not None and not self._process.stdout.closed:
+                self._process.stdout.close()
+
+        return_code = _normalize_ape_return_code(self._process.wait(timeout=timeout))
+        self._close_stdin_source()
+        self._wait_for_stdin()
+        self._wait_for_event_channel()
+        self._wait_for_output(self._stopped_by_client)
+
+        process_result = APEProcessResult(
+            self._argv,
+            return_code,
+            self._captured_stdout().decode('utf-8', errors='replace'),
+            self._captured_stderr().decode('utf-8', errors='replace'),
+        )
+        self._process_result = process_result
+
+        if return_code != 0 and not self._stopped_by_client:
+            raise APEProcessError(process_result)
+
+        return 0 if self._stopped_by_client else return_code
+
+    def wait(self, timeout: float | None = None) -> int:
+        return self._wait(timeout, require_streamed_stdout=True)
+
+    def _cleanup_runtime_files(self) -> None:
+        if self._runtime_files is None:
+            return
+
+        runtime_files = self._runtime_files
+        self._runtime_files = None
+        runtime_files.cleanup()
+
+    def stop(self, timeout: float = 5.0) -> None:
+        if not self.running:
+            try:
+                self._wait(require_streamed_stdout=False)
+            finally:
+                self._cleanup_runtime_files()
+
+            return
+
+        self._stopped_by_client = True
+        self._close_stdin_source()
+        self._process.terminate()
+
+        try:
+            self._process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            self._process.kill()
+            self._process.wait()
+
+        try:
+            if (
+                not self._capture_stdout
+                and self._process.stdout is not None
+                and not self._process.stdout.closed
+            ):
+                self._process.stdout.close()
+
+            self._wait_for_event_channel()
+            self._wait_for_output(True)
+        finally:
+            self._cleanup_runtime_files()
+
+    def close(self) -> None:
+        if self.running:
+            self.stop()
+            return
+
+        try:
+            self._wait(require_streamed_stdout=False)
+        finally:
+            self._cleanup_runtime_files()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exception_type, exception_value, traceback_value) -> None:
+        del exception_type, exception_value, traceback_value
+        self.close()
+
+
+class APEClient:
+    def __init__(
+        self,
+        binary_path: Path,
+        operations: dict[str, dict[str, Any]],
+        runtime: dict[str, Any] | None = None,
+    ):
+        self._binary_path = binary_path.resolve()
+        self._operations = operations
+        self._runtime = {} if runtime is None else runtime
+
+    @staticmethod
+    def _multiple_values(value: Any) -> Iterable[Any]:
+        if isinstance(value, (str, bytes, os.PathLike)):
+            return (value,)
+
+        if isinstance(value, Iterable):
+            return value
+
+        return (value,)
+
+    @classmethod
+    def _append_optional_value(
+        cls,
+        argv: list[str],
+        option: dict[str, Any],
+        value: Any,
+    ) -> bool:
+        if not option['value_optional']:
+            return False
+
+        if value is None or value is False:
+            return True
+
+        argv.append(option['primary_flag'])
+
+        if value is True:
+            return True
+
+        argv.append(str(value))
+        return True
+
+    @staticmethod
+    def _runtime_path(
+        option: dict[str, Any],
+        runtime_files: _RuntimeFiles | None,
+        operation: dict[str, Any],
+    ) -> tuple[str, Path]:
+        if runtime_files is None:
+            raise RuntimeError('Runtime-owned option has no runtime files')
+
+        role = option.get('runtime_role', 'result')
+        path = runtime_files.path(role)
+        if path is None:
+            raise RuntimeError(f'Runtime-owned option has no {role} path')
+
+        if role == 'events':
+            flag = operation['events']['source']['option_flag']
+        else:
+            flag = operation['result']['option_flag']
+
+        return flag, path
+
+    @classmethod
+    def _append_options(
+        cls,
+        argv: list[str],
+        options: list[dict[str, Any]],
+        values: dict[str, Any],
+        runtime_files: _RuntimeFiles | None,
+        operation: dict[str, Any],
+    ) -> None:
+        for option in options:
+            if option['runtime_owned']:
+                flag, path = cls._runtime_path(option, runtime_files, operation)
+                argv.extend([flag, str(path)])
+                continue
+
+            value = values.get(option['api_name'])
+            if option['boolean']:
+                if value:
+                    argv.append(option['primary_flag'])
+
+                continue
+
+            if cls._append_optional_value(argv, option, value):
+                continue
+
+            if value is None:
+                if option['required']:
+                    raise TypeError(
+                        f"Missing required argument: {option['api_name']}"
+                    )
+
+                continue
+
+            if option['multiple']:
+                for item in cls._multiple_values(value):
+                    argv.extend([option['primary_flag'], str(item)])
+
+                continue
+
+            argv.extend([option['primary_flag'], str(value)])
+
+    @classmethod
+    def _append_positionals(
+        cls,
+        argv: list[str],
+        positionals: list[dict[str, Any]],
+        values: dict[str, Any],
+    ) -> None:
+        for positional in positionals:
+            value = values.get(positional['api_name'])
+            if value is None:
+                if positional['required']:
+                    raise TypeError(
+                        f"Missing required argument: {positional['api_name']}"
+                    )
+
+                continue
+
+            if positional['multiple']:
+                argv.extend(str(item) for item in cls._multiple_values(value))
+                continue
+
+            argv.append(str(value))
+
+    def _build_argv(
+        self,
+        operation: dict[str, Any],
+        values: dict[str, Any],
+        runtime_files: _RuntimeFiles | None,
+    ) -> list[str]:
+        argv: list[str] = []
+
+        for level_index, level in enumerate(operation['levels']):
+            if level_index > 0:
+                argv.append(level['token'])
+
+            self._append_options(
+                argv,
+                level['options'],
+                values,
+                runtime_files,
+                operation,
+            )
+            self._append_positionals(argv, level['positionals'], values)
+
+        return argv
+
+    def _environment(self) -> dict[str, str]:
+        environment = os.environ.copy()
+
+        for variable_name in self._runtime.get('env_unset', []):
+            environment.pop(variable_name, None)
+
+        return environment
+
+    def _launch_command(self, argv: list[str]) -> list[str]:
+        executable = str(self._binary_path)
+        if os.name == 'nt':
+            return [executable, *argv]
+
+        return ['/bin/sh', '-c', 'exec "$0" "$@"', executable, *argv]
+
+    def _run_command(
+        self,
+        argv: list[str],
+        timeout_seconds: float | None = None,
+    ) -> APEProcessResult:
+        process = subprocess.run(
+            self._launch_command(argv),
+            capture_output=True,
+            text=True,
+            encoding='utf-8',
+            errors='replace',
+            check=False,
+            timeout=timeout_seconds,
+            env=self._environment(),
+        )
+        result = APEProcessResult(
+            tuple(argv),
+            _normalize_ape_return_code(process.returncode),
+            process.stdout,
+            process.stderr,
+        )
+
+        if result.return_code != 0:
+            raise APEProcessError(result)
+
+        return result
+
+    def _start_persistent(
+        self,
+        argv: list[str],
+        runtime_files: _RuntimeFiles | None,
+        event_config: dict[str, Any] | None = None,
+        stdin_source: Any = None,
+        capture_stdout: bool = True,
+    ) -> ProcessSession:
+        process = subprocess.Popen(
+            self._launch_command(argv),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            stdin=subprocess.PIPE if stdin_source is not None else None,
+            env=self._environment(),
+        )
+
+        session = ProcessSession(
+            process,
+            argv,
+            runtime_files,
+            event_config,
+            capture_stdout,
+        )
+
+        if stdin_source is not None:
+            session.attach_stdin(stdin_source)
+
+        return session
+
+    def _decode_result(
+        self,
+        result: APEProcessResult,
+        result_path: Path | None,
+        result_config: dict[str, Any],
+    ) -> Any:
+        result_format = result_config['format']
+        if result_format == 'command':
+            return result
+
+        if result_format == 'text':
+            return result.stdout.strip() if result_config['strip'] else result.stdout
+
+        if result_format == 'json':
+            value = json.loads(result.stdout)
+            return _extract_field(value, result_config['field'])
+
+        if result_format == 'json_file':
+            if result_path is None or not result_path.exists():
+                raise RuntimeError('APE did not create the configured JSON result file')
+
+            value = json.loads(result_path.read_text(encoding='utf-8'))
+            return _extract_field(value, result_config['field'])
+
+        raise RuntimeError(f'Unsupported result format: {result_format}')
+
+    def _run_oneshot(
+        self,
+        argv: list[str],
+        runtime_files: _RuntimeFiles | None,
+        operation: dict[str, Any],
+    ) -> Any:
+        result_path = None if runtime_files is None else runtime_files.path('result')
+
+        try:
+            result = self._run_command(
+                argv,
+                operation['process']['timeout_seconds'],
+            )
+            return self._decode_result(result, result_path, operation['result'])
+        finally:
+            if runtime_files is not None:
+                runtime_files.cleanup()
+
+    def _read_json_result(
+        self,
+        result_path: Path,
+        result_config: dict[str, Any],
+    ) -> Any:
+        value = json.loads(result_path.read_text(encoding='utf-8'))
+        return _extract_field(value, result_config['field'])
+
+    def _wait_for_json_result(
+        self,
+        session: ProcessSession,
+        result_path: Path | None,
+        result_config: dict[str, Any],
+    ) -> Any:
+        if result_path is None:
+            raise RuntimeError('JSON result path was not created')
+
+        timeout = float(result_config['ready_timeout_seconds'])
+        deadline = time.monotonic() + timeout
+        last_size = -1
+        stable_count = 0
+
+        while time.monotonic() < deadline:
+            if result_path.exists():
+                size = result_path.stat().st_size
+                if size > 0 and size == last_size:
+                    stable_count += 1
+                    if stable_count >= 2:
+                        return self._read_json_result(result_path, result_config)
+                else:
+                    stable_count = 0
+
+                last_size = size
+
+            if not session.running:
+                session.wait()
+                if result_path.exists() and result_path.stat().st_size > 0:
+                    return self._read_json_result(result_path, result_config)
+
+                raise RuntimeError('APE exited before producing the JSON result file')
+
+            time.sleep(0.02)
+
+        raise TimeoutError(f'JSON result was not ready within {timeout} seconds')
+
+    def invoke(self, operation_name: str, values: dict[str, Any]) -> Any:
+        operation = self._operations[operation_name]
+        result_config = operation['result']
+        runtime_files = _RuntimeFiles.create(operation)
+
+        try:
+            argv = self._build_argv(operation, values, runtime_files)
+        except Exception:
+            if runtime_files is not None:
+                runtime_files.cleanup()
+
+            raise
+
+        if operation['execution'] == 'persistent':
+            session = self._start_persistent(
+                argv,
+                runtime_files,
+                operation.get('events'),
+                values.get('stdin'),
+                values.get('_apebind_capture_stdout', True),
+            )
+            result_path = None if runtime_files is None else runtime_files.path('result')
+
+            try:
+                if (
+                    result_config['format'] == 'json_file'
+                    and result_config['ready_timeout_seconds'] is not None
+                ):
+                    session.set_result(
+                        self._wait_for_json_result(session, result_path, result_config)
+                    )
+            except Exception:
+                if session.running:
+                    session.stop()
+                else:
+                    session._cleanup_runtime_files()
+
+                raise
+
+            return session
+
+        return self._run_oneshot(argv, runtime_files, operation)
+
+    def raw(self, arguments: list[str], persistent: bool = False):
+        argv = [str(value) for value in arguments]
+        if persistent:
+            return self._start_persistent(argv, None)
+
+        return self._run_command(argv)