diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 33733d6e..74e3392e 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -9,9 +9,11 @@ coordination branch. Detailed state belongs in each linked status file. | Name | Started | Goal | State | Branch association | Status file | |---|---|---|---|---|---| +| `presentations` | 2026-11-16 | Deliver agent-driven E2E recording and presentation from Markdown or inline English in adopter DevCapsules | paused; PR #43 reviewed; awaits owner merge to release 0.3.1 | `ws-presentations/0.3.1-authoring` | [workstream status](engineering-docs/wip/2026-11-16-presentations/CURRENT-STATUS.md) | +| `github-auth` | 2026-11-16 | GitHub SSH authentication through a launcher-owned host proxy | paused; Pair Review #44 merged; PR #47 targets release-0.3.1; two inherited gate failures remain | `ws-github-auth/ssh-proxy` | [workstream status](engineering-docs/wip/2026-11-16-github-auth/CURRENT-STATUS.md) | | `workflow-improvements` | 2026-08-09 | Improve the multiple-stream workflow from concrete dogfood findings during the recursive E2E cycle | active 2026-10-30; Pair Review Loop naming implemented and packaging verified for 0.3.0; mainline and release integration pending | `ws-workflow-improvements/v1` | [workstream status](engineering-docs/wip/2026-08-09-workflow-improvements/CURRENT-STATUS.md) | | `project-management` | 2026-08-09 | Maintain project-wide priorities, sequencing, dependencies, and lifecycle coordination | paused 2026-10-11 at owner direction; consent and forced configuration before RC work; remaining diagnostics/image scope and release cut decisions retained | `ws-project-management/coordination` | [workstream status](engineering-docs/wip/2026-08-09-project-management/CURRENT-STATUS.md) | -| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | active; releasing 0.3.1; cut 2026-11-07 from `main` at `31e8fec7`, `main` reopened at `0.3.2.dev0` (#8); candidate 2 (`v0.3.1-rc2` on `be0140ca`, propagated to `main` via PR #22 `aabace3c`) published and verified: Eclipse libsoup (#10, closed on rc1), launcher-delivered `devcapsule_webconsole` (`D-0017`, #18/#16, closed on rc2), Codex npm abbreviated metadata (#20, closed on rc2 + `component-status` `0bc31c64`), and Codex `0.167.0` + Claude Code `2.1.321` pins (`embedded-33`, #21); rulings open: executables for the Mac, the compatibility feed's home | `release-0.3.1`, the workstream's selection from the cut to the final tag; `release-0.3.0` closed and retained; earlier slice branches merged and closed | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) | +| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | integrating; release `918f9fc7` includes SSH proxy #47, presentations #43 and preflight correction #48; main preservation approved, rc3 waits for main integration; four unresolved release bugs, one blocking | `release-0.3.1`, release driver; `4PR-6-release-0.3.1`, main PR copy with owner-approved preservation commit retaining 0.3.2.dev0; `release-0.3.0` closed and retained | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) | | `component-upgrades` | 2026-09-21 | Deliver component distribution channels, developer-owned version sets and proven upgrade rollback; Codex first | paused 2026-10-02; consent design ruled (D-0011 to D-0013), 0.2.16 consent slice next; R-UPGRADE-002 follow-up retained | `ws-component-upgrades/v1` | [workstream status](engineering-docs/wip/2026-09-21-component-upgrades/CURRENT-STATUS.md) | | `sample-projects` | 2026-08-14 | Provide realistic sample projects as submodules that demonstrate ordinary adopter development inside DevCapsule | samples left the repository as submodules 2026-11-05; their future form is the owner's later decision | `ws-sample-projects/ai-learning` | [workstream status](engineering-docs/wip/2026-08-14-sample-projects/CURRENT-STATUS.md) | | `contained-display` | 2026-08-19 | Own the capsule supervisor core (container entry process, supervised children, explicit session end, headless mode) and the capsule's own display environment, closing the host-session credential exposure — supervisor first, display as its first consumer | active; **the contained display shipped in v0.2.12 on 2026-09-14** (recipe-9 base, contained desktop by default, X11 passthrough behind `host-x11`); the X11 credential bug is resolved; remaining threads are records and follow-ups (reconnect, WSL2 opener, sample locks) | `ws-contained-display/display-transport` | [workstream status](engineering-docs/wip/2026-08-19-contained-display/CURRENT-STATUS.md) | diff --git a/README.md b/README.md index bca996a2..b734efd1 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,11 @@ default. You decide what additional access to grant. See a sample of a full graphical IDE running inside DevCapsule's isolated Docker container. More scenario illustrations coming soon. +To record an E2E scenario in your own project, ask your agent to run it with recording +and presentation. `devcapsule presentations guide` provides the installed instructions; +`devcapsule presentations export ` supplies the Python/Playwright helpers. +See the [agent recording guide](devcapsule-src/devcapsule/presentation_tools/README.md). + ## Why switch to DevCapsule? diff --git a/WORKFLOW.md b/WORKFLOW.md index 196d3760..781c9e39 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -1,6 +1,6 @@ --- definition: devcapsule -version: 0.3.1 +version: 0.3.2.dev0 --- # Human / Agent Iteration Workflow diff --git a/devcapsule-src/devcapsule/assets/project_workflow/definition/WORKFLOW.md b/devcapsule-src/devcapsule/assets/project_workflow/definition/WORKFLOW.md index 02914b52..31f397b5 100644 --- a/devcapsule-src/devcapsule/assets/project_workflow/definition/WORKFLOW.md +++ b/devcapsule-src/devcapsule/assets/project_workflow/definition/WORKFLOW.md @@ -1,6 +1,6 @@ --- definition: devcapsule -version: 0.3.1 +version: 0.3.2.dev0 --- # Human / Agent Iteration Workflow diff --git a/devcapsule-src/devcapsule/commands/github_ssh.py b/devcapsule-src/devcapsule/commands/github_ssh.py new file mode 100644 index 00000000..443c0e90 --- /dev/null +++ b/devcapsule-src/devcapsule/commands/github_ssh.py @@ -0,0 +1,45 @@ +"""Git's capsule-side SSH adapter for the authorized launcher proxy.""" +from __future__ import annotations + +import argparse +import os +from pathlib import Path +import subprocess +import sys + +from devcapsule.commands.framework import Command +from devcapsule.compat import CliError +from devcapsule.github_transport import GitHubTransportError, parse_git_ssh +from devcapsule.github_proxy import SOCKET_ENV, relay_git + + +class GitHubSshCommand(Command): + name = "github-ssh" + hidden = True + help = "Git SSH transport through the authorized host GitHub proxy." + passthrough_dest = "ssh_arguments" + + @classmethod + def run(cls, arguments: argparse.Namespace, context: object | None) -> int: + try: + request = parse_git_ssh(arguments.ssh_arguments) + except GitHubTransportError as error: + raise CliError( + f"GitHub proxy: {error} Host keys must be trusted and encrypted keys unlocked on the host." + ) from error + if request is None: + try: + return subprocess.run(["ssh", *arguments.ssh_arguments], check=False).returncode + except OSError as error: + raise CliError(f"Capsule SSH: {error}") from error + try: + path = os.environ.get(SOCKET_ENV) + if not path: + raise GitHubTransportError("No authorized GitHub proxy. Enable github-ssh on the host launcher.") + return relay_git(Path(path), request, stdin=sys.stdin.buffer, + stdout=sys.stdout.buffer, stderr=sys.stderr.buffer) + except (OSError, GitHubTransportError) as error: + raise CliError(f"GitHub proxy: {error} Host keys must be trusted and encrypted keys unlocked on the host.") from error + + +COMMAND = GitHubSshCommand diff --git a/devcapsule-src/devcapsule/commands/presentations.py b/devcapsule-src/devcapsule/commands/presentations.py new file mode 100644 index 00000000..522e005e --- /dev/null +++ b/devcapsule-src/devcapsule/commands/presentations.py @@ -0,0 +1,89 @@ +"""Entry points for the packaged agent recording instructions and Python helpers.""" +import argparse +from importlib.resources import files +import os +from pathlib import Path +from typing import Mapping + +from devcapsule.commands.framework import Command, Group +from devcapsule.compat import CliError +from devcapsule.presentation_authoring import export_tools, presentation_link + +__all__ = ["COMMAND"] + +PACKAGE = "devcapsule.presentation_tools" +ASSETS = ("__init__.py", "producer.py", "recording.py", "README.md", "example.py") + + +class GuideCommand(Command): + name = "guide" + help = "Read the agent instructions for English-specified E2E recordings." + + @classmethod + def run(cls, arguments: argparse.Namespace, context: object | None) -> int: + print(files(PACKAGE).joinpath("README.md").read_text(encoding="utf-8")) + return 0 + + +class ExportCommand(Command): + name = "export" + help = "Export the instructions and standalone Python helpers to a new directory." + + @classmethod + def configure(cls, parser: argparse.ArgumentParser) -> None: + parser.add_argument("directory", type=Path, help="New directory; existing directories are preserved.") + + @classmethod + def run(cls, arguments: argparse.Namespace, context: object | None) -> int: + assets = {name: files(PACKAGE).joinpath(name).read_bytes() for name in ASSETS} + try: + package = export_tools(arguments.directory, assets) + except (OSError, ValueError) as error: + raise CliError(f"cannot export presentation tools: {error}") from error + print(f"Presentation tools: {package}\nAgent instructions: {package / 'README.md'}") + return 0 + + +class HandOffCommand(Command): + name = "hand-off" + help = "Print the recorded presentation's console link for the engineer." + + @classmethod + def configure(cls, parser: argparse.ArgumentParser) -> None: + parser.add_argument("folder", type=Path) + parser.add_argument("--project", type=Path, help="Console project root; defaults to PROJECT_PATH or cwd.") + parser.add_argument("--console-url", help="Defaults to DEVCAPSULE_CONSOLE_URL.") + parser.add_argument("--token-file", type=Path, help="Defaults to the capsule console token file.") + + @classmethod + def run(cls, arguments: argparse.Namespace, context: object | None) -> int: + root = (arguments.project or Path(os.environ.get("PROJECT_PATH") or ".")).resolve() + folder = arguments.folder.resolve() + origin = arguments.console_url or os.environ.get("DEVCAPSULE_CONSOLE_URL", "") + token_path = arguments.token_file or Path(os.environ.get("DEVCAPSULE_CONSOLE_TOKEN_FILE") or "/run/devcapsule-console-token") + try: + token = token_path.read_text(encoding="utf-8").strip() + except (OSError, UnicodeError): + token = "" + try: + if not (folder / "presentation.json").is_file(): + raise ValueError(f"no presentation.json in {folder}") + link = presentation_link(folder, project=root, console_url=origin, token=token) + except (OSError, ValueError) as error: + raise CliError(str(error)) from error + if not token: + print("Open the console first to establish a browser session; no readable run token was found.") + print(link) + return 0 + + +class PresentationsCommand(Group): + name = "presentations" + help = "Record E2E scenarios and make presentations: agent guide, Python toolkit and console link." + + @classmethod + def subcommands(cls) -> Mapping[str, type[Command] | type[Group]]: + return {command.name: command for command in (GuideCommand, ExportCommand, HandOffCommand)} + + +COMMAND = PresentationsCommand diff --git a/devcapsule-src/devcapsule/commands/project.py b/devcapsule-src/devcapsule/commands/project.py index e5e13748..7a3a2150 100644 --- a/devcapsule-src/devcapsule/commands/project.py +++ b/devcapsule-src/devcapsule/commands/project.py @@ -1236,7 +1236,7 @@ def run(cls, arguments: argparse.Namespace, context: object | None) -> int: class ConfigDenyCommand(Command): name = "deny" capsule_access: ClassVar[CapsuleAccess] = CapsuleAccess.MUTATES - help = "Deny a host access for this checkout, recorded: network, docker-daemon, development-sudo, host-browser, host-x11." + help = "Deny a host access for this checkout, recorded: network, docker-daemon, development-sudo, host-browser, host-x11, github-ssh." @classmethod def configure(cls, parser: argparse.ArgumentParser) -> None: @@ -2104,7 +2104,7 @@ def subcommands(cls) -> Mapping[str, type[Command] | type[Group]]: # The authorization nodes whose run-once answers feed the launch plan; every # other authorization (base-image, acquisitions) is inherently persistent. -_RUN_ONCE_AUTHORIZATIONS = ("docker-daemon", "network", "development-sudo", "host-browser", "host-x11") +_RUN_ONCE_AUTHORIZATIONS = ("docker-daemon", "network", "development-sudo", "host-browser", "host-x11", "github-ssh") class ProjectRunCommand(Command): @@ -2418,6 +2418,7 @@ def prepare_display(base: ImageDetails) -> None: extra_docker_args=["--pull=never", *saved_docker_args, *prepared.environment_tokens, *docker_options], project_state=None, enable_host_browser=selected_host_browser, + enable_github_ssh=host_access.github_ssh, display_transport=display_transport, web_console=web_console, capsule_platform=lock_platform(lock), diff --git a/devcapsule-src/devcapsule/configuration/authorization.py b/devcapsule-src/devcapsule/configuration/authorization.py index 3927bfaf..a7b54a9d 100644 --- a/devcapsule-src/devcapsule/configuration/authorization.py +++ b/devcapsule-src/devcapsule/configuration/authorization.py @@ -80,6 +80,11 @@ True, "Enable the declared development-sudo behavior inside the capsule.", ), + "github-ssh": ( + True, + "Allow GitHub Git fetch and push through the outside launcher using the host SSH identity. " + "All repositories accessible to that identity are accessible; private keys stay on the host.", + ), "host-browser": ( True, "Open HTTP(S) links from the capsule in the physical host's default browser " diff --git a/devcapsule-src/devcapsule/configuration/console_channel.py b/devcapsule-src/devcapsule/configuration/console_channel.py index b66436ff..eef5dc4e 100644 --- a/devcapsule-src/devcapsule/configuration/console_channel.py +++ b/devcapsule-src/devcapsule/configuration/console_channel.py @@ -73,6 +73,7 @@ DEFERRED_SUBVERBS = {("trust", "accept"), ("docker-args", "set")} SECURE_AUTHORIZATIONS = { "network": {"bridge", "none"}, "docker-daemon": {"none"}, + "github-ssh": {"false", "none"}, "development-sudo": {"false", "none"}, "host-browser": {"false", "none"}, "host-x11": {"false", "none"}, } READ_ONLY_VERBS = {"show", "check", "console"} diff --git a/devcapsule-src/devcapsule/configuration/listing.py b/devcapsule-src/devcapsule/configuration/listing.py index abf09b64..8f7e8215 100644 --- a/devcapsule-src/devcapsule/configuration/listing.py +++ b/devcapsule-src/devcapsule/configuration/listing.py @@ -61,7 +61,7 @@ LISTING_SCHEMA_VERSION = 2 -HOST_ACCESS_NODES = ("network", "docker-daemon", "development-sudo", "host-browser", "host-x11") +HOST_ACCESS_NODES = ("network", "docker-daemon", "development-sudo", "host-browser", "host-x11", "github-ssh") @dataclass(frozen=True) diff --git a/devcapsule-src/devcapsule/configuration/resolution.py b/devcapsule-src/devcapsule/configuration/resolution.py index 25e97671..bfa143dc 100644 --- a/devcapsule-src/devcapsule/configuration/resolution.py +++ b/devcapsule-src/devcapsule/configuration/resolution.py @@ -210,7 +210,7 @@ def base_reference(self) -> str | None: @property def host_access(self) -> HostAccess: authorizations = self._document.get("authorization", {}) - host_names = {"docker-daemon", "network", "development-sudo", "host-browser", "host-x11"} + host_names = {"docker-daemon", "network", "development-sudo", "host-browser", "host-x11", "github-ssh"} return HostAccess().overlay(self._document.get("host", {})).overlay({ name: value for name, value in authorizations.items() if name in host_names }) diff --git a/devcapsule-src/devcapsule/configuration/review.py b/devcapsule-src/devcapsule/configuration/review.py index 015788d5..5ffac617 100644 --- a/devcapsule-src/devcapsule/configuration/review.py +++ b/devcapsule-src/devcapsule/configuration/review.py @@ -20,6 +20,8 @@ from .trust import HomeTrust from .values import RuntimeEffects, resolve_configuration_values +__all__ = ["HostAccess", "ConfigurationReview", "review_configuration"] + @dataclass(frozen=True) class HostAccess: @@ -27,6 +29,7 @@ class HostAccess: docker_daemon: str = "none" network: str = "bridge" development_sudo: bool = False + github_ssh: bool = False host_browser: bool = False host_x11: bool | None = None @@ -35,6 +38,7 @@ def overlay(self, answers: Mapping[str, Any]) -> HostAccess: "docker-daemon": ("docker_daemon", ("none", "host-socket")), "network": ("network", ("bridge", "host")), "development-sudo": ("development_sudo", (False, True)), + "github-ssh": ("github_ssh", (False, True)), "host-browser": ("host_browser", (False, True)), "host-x11": ("host_x11", (False, True)), } @@ -127,7 +131,7 @@ def resolved_authorizations(self) -> dict[str, AuthorizationScalar]: def effective_host(self, overrides: Mapping[str, Any] | None = None) -> HostAccess: answers = { name: value for name, value in self.resolved_authorizations().items() - if name in {"docker-daemon", "network", "development-sudo", "host-browser", "host-x11"} + if name in {"docker-daemon", "network", "development-sudo", "host-browser", "host-x11", "github-ssh"} } return self.legacy_host.overlay(answers).overlay(overrides or {}) diff --git a/devcapsule-src/devcapsule/github_proxy.py b/devcapsule-src/devcapsule/github_proxy.py new file mode 100644 index 00000000..9939b28c --- /dev/null +++ b/devcapsule-src/devcapsule/github_proxy.py @@ -0,0 +1,258 @@ +"""Launcher-owned GitHub transport broker and capsule client. + +``GitHubBroker`` owns a private Unix socket and bounded concurrent SSH children. +``relay_git`` connects Git's byte streams to it. Only the launcher creates the +broker; neither side reads private keys. The wire begins with a bounded JSON +request. Client input then streams unchanged, with a write-half close for EOF. +Server replies are frames: O stdout, E stderr, X unsigned exit status. +""" +from __future__ import annotations + +from collections.abc import Iterator, Mapping +from contextlib import contextmanager +import os +from pathlib import Path +import selectors +import shutil +import signal +import socket +import struct +import subprocess +import tempfile +import threading +import time +from typing import BinaryIO + +from devcapsule.github_transport import GitHubRequest, GitHubTransportError, decode_request + +__all__ = ["GitHubBroker", "relay_git", "github_ssh_bridge", "SOCKET_ENV", "SOCKET_DESTINATION", + "GIT_SSH_COMMAND", "MAX_REQUEST", "MAX_FRAME"] + +SOCKET_ENV = "DEVCAPSULE_GITHUB_SOCKET" +SOCKET_DESTINATION = Path("/run/devcapsule-github.sock") +GIT_SSH_COMMAND = "/opt/devcapsule/bin/devcapsule.pex github-ssh --" +MAX_REQUEST = 4096 +MAX_FRAME = 65536 + + +def _read_exact(connection: socket.socket, length: int) -> bytes: + chunks = bytearray() + while len(chunks) < length: + chunk = connection.recv(length - len(chunks)) + if not chunk: + raise GitHubTransportError("GitHub proxy connection ended unexpectedly.") + chunks.extend(chunk) + return bytes(chunks) + + +class GitHubBroker: + """One session's GitHub bridge. Close cancels active children and removes its socket. + + ``ssh`` and ``environment`` come from the launcher, never from a request. + Explicit deadlines bound idle handshakes, blocked consumers and Git operations. + """ + + def __init__(self, path: Path, *, ssh: str, environment: Mapping[str, str], + operation_timeout: float = 3600, io_timeout: float = 10) -> None: + self.path = path + self.ssh = ssh + self.environment = dict(environment) + self.operation_timeout = operation_timeout + self.io_timeout = io_timeout + self._stop = threading.Event() + self._lock = threading.Lock() + self._connections: set[socket.socket] = set() + self._threads: list[threading.Thread] = [] + self._slots = threading.BoundedSemaphore(8) + self._server: socket.socket | None = None + self._listener: threading.Thread | None = None + self._bound = False + + def __enter__(self) -> GitHubBroker: + server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + try: + server.bind(str(self.path)) # Never unlink or replace someone else's socket. + self._bound = True + self.path.chmod(0o600) + server.listen(8) + server.settimeout(0.2) + except BaseException: + server.close() + if self._bound: + self.path.unlink(missing_ok=True) + raise + self._server = server + self._listener = threading.Thread(target=self._serve, daemon=True, name="github-proxy") + self._listener.start() + return self + + def __exit__(self, *_args: object) -> None: + self._stop.set() + if self._server is not None: + self._server.close() + if self._listener is not None: + self._listener.join() + with self._lock: + for connection in self._connections: + try: + connection.shutdown(socket.SHUT_RDWR) + except OSError: + pass + for thread in self._threads: + thread.join() + if self._bound: + self.path.unlink(missing_ok=True) + + def _serve(self) -> None: + assert self._server is not None + while not self._stop.is_set(): + try: + connection, _ = self._server.accept() + except TimeoutError: + continue + except OSError: + break + if not self._slots.acquire(blocking=False): + connection.close() + continue + with self._lock: + self._connections.add(connection) + thread = threading.Thread(target=self._handle, args=(connection,), daemon=True) + # Retain only active workers; completed Thread objects need not accumulate. + self._threads = [item for item in self._threads if item.is_alive()] + self._threads.append(thread) + thread.start() + + def _handle(self, connection: socket.socket) -> None: + try: + with connection: + connection.settimeout(self.io_timeout) + length = struct.unpack("!I", _read_exact(connection, 4))[0] + if not 0 < length <= MAX_REQUEST: + raise GitHubTransportError("GitHub request exceeds its size limit.") + request = decode_request(_read_exact(connection, length)) + self._transfer(connection, request) + except (OSError, GitHubTransportError, subprocess.SubprocessError): + # An invalid or disconnected caller gets EOF, never a host command. + pass + finally: + with self._lock: + self._connections.discard(connection) + self._slots.release() + + def _transfer(self, connection: socket.socket, request: GitHubRequest) -> None: + # Timeout sockets use O_NONBLOCK. Child stdin must be a blocking stream. + # dup shares file flags, so restore blocking and use send timeouts via + # a separate connection wrapper only while transmitting output below. + connection.setblocking(True) + with subprocess.Popen(request.ssh_command(self.ssh), stdin=connection.fileno(), + stdout=subprocess.PIPE, stderr=subprocess.PIPE, + env=self.environment, cwd="/", start_new_session=True) as child: + assert child.stdout is not None and child.stderr is not None + started = time.monotonic() + try: + with selectors.DefaultSelector() as selector: + selector.register(child.stdout, selectors.EVENT_READ, b"O") + selector.register(child.stderr, selectors.EVENT_READ, b"E") + while selector.get_map(): + if self._stop.is_set() or time.monotonic() - started > self.operation_timeout: + raise GitHubTransportError("GitHub transfer stopped or timed out.") + for key, _ in selector.select(0.2): + data = os.read(key.fd, MAX_FRAME) + if not data: + selector.unregister(key.fileobj) + else: + self._send(connection, key.data, data) + while child.poll() is None: + if self._stop.wait(0.1) or time.monotonic() - started > self.operation_timeout: + raise GitHubTransportError("GitHub transfer stopped or timed out.") + self._send(connection, b"X", struct.pack("!I", child.returncode if child.returncode >= 0 else 255)) + finally: + # SSH may have started a host-configured ProxyCommand. Reap the + # whole private process group even after the leader exits. + try: + os.killpg(child.pid, signal.SIGKILL) + except ProcessLookupError: + pass + child.wait() + + def _send(self, connection: socket.socket, kind: bytes, payload: bytes) -> None: + # MSG_DONTWAIT avoids altering the shared file flags of child stdin. + data = memoryview(kind + struct.pack("!I", len(payload)) + payload) + deadline = time.monotonic() + self.io_timeout + with selectors.DefaultSelector() as selector: + selector.register(connection, selectors.EVENT_WRITE) + while data: + if self._stop.is_set() or time.monotonic() > deadline: + raise GitHubTransportError("GitHub proxy output stalled.") + if not selector.select(0.2): + continue + try: + count = connection.send(data, socket.MSG_DONTWAIT) + except BlockingIOError: + continue + if count == 0: + raise GitHubTransportError("GitHub proxy output disconnected.") + data = data[count:] + + +def relay_git(path: Path, request: GitHubRequest, *, stdin: BinaryIO, + stdout: BinaryIO, stderr: BinaryIO) -> int: + """Relay binary Git data, separate diagnostics and the host SSH exit status.""" + payload = request.encode() + with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection: + connection.settimeout(10) + connection.connect(str(path)) + connection.sendall(struct.pack("!I", len(payload)) + payload) + connection.settimeout(None) + + def send_input() -> None: + try: + while chunk := os.read(stdin.fileno(), MAX_FRAME): + connection.sendall(chunk) + connection.shutdown(socket.SHUT_WR) + except (OSError, ValueError): + pass # The server can finish before Git closes stdin. + + threading.Thread(target=send_input, daemon=True, name="github-git-input").start() + while True: + kind = _read_exact(connection, 1) + length = struct.unpack("!I", _read_exact(connection, 4))[0] + if length > MAX_FRAME: + raise GitHubTransportError("GitHub proxy frame exceeds its size limit.") + data = _read_exact(connection, length) + if kind == b"X" and length == 4: + return min(struct.unpack("!I", data)[0], 255) + if kind not in {b"O", b"E"}: + raise GitHubTransportError("Unknown GitHub proxy response.") + output = stdout if kind == b"O" else stderr + output.write(data) + output.flush() + + +@contextmanager +def github_ssh_bridge(environment: Mapping[str, str], *, enabled: bool, + containerized: bool, binds_unix_sockets: bool) -> Iterator[Path | None]: + """Create an authorized physical-host broker, or reuse an inherited one. + + Docker Desktop needs a separate transport. An explicit enable there fails + with an explanation instead of silently mounting keys or exposing an agent. + """ + if not enabled: + yield None + return + if containerized: + inherited = environment.get(SOCKET_ENV) + if inherited != str(SOCKET_DESTINATION) or not SOCKET_DESTINATION.is_socket(): + raise GitHubTransportError("GitHub proxy unavailable: authorize github-ssh on the outside launcher first.") + yield SOCKET_DESTINATION + return + if not binds_unix_sockets: + raise GitHubTransportError("github-ssh currently requires Linux/WSL with native Docker; Docker Desktop transport is not implemented.") + executable = shutil.which("ssh", path=environment.get("PATH", os.defpath)) + if executable is None: + raise GitHubTransportError("github-ssh requires OpenSSH on the host.") + with tempfile.TemporaryDirectory(prefix="devcapsule-github-", dir="/tmp") as directory: + path = Path(directory) / "ssh.sock" + with GitHubBroker(path, ssh=executable, environment=environment): + yield path diff --git a/devcapsule-src/devcapsule/github_transport.py b/devcapsule-src/devcapsule/github_transport.py new file mode 100644 index 00000000..b53d5210 --- /dev/null +++ b/devcapsule-src/devcapsule/github_transport.py @@ -0,0 +1,102 @@ +"""GitHub-only Git SSH requests: validate values before any host process starts. + +The capsule selects a Git service and repository, never a host command or SSH +option. Host OpenSSH owns key selection, host verification and authentication. +""" +from __future__ import annotations + +from dataclasses import dataclass +import json +import re +import shlex +from typing import Sequence + +__all__ = ["GitHubRequest", "GitHubTransportError", "parse_git_ssh", "decode_request"] + + +class GitHubTransportError(ValueError): + """A request cannot cross the authorized GitHub boundary.""" + + +@dataclass(frozen=True) +class GitHubRequest: + service: str + repository: str + + def validate(self) -> None: + """Require a GitHub repository and one of Git's two transfer services.""" + if self.service not in {"git-upload-pack", "git-receive-pack"}: + raise GitHubTransportError("Only Git fetch and push services are allowed.") + if (len(self.repository) > 256 or + not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9_.-]+", self.repository) or + self.repository.split("/")[-1] in {".", ".."}): + raise GitHubTransportError("Expected a GitHub OWNER/REPOSITORY path.") + + def encode(self) -> bytes: + """Serialize a validated request; no host paths or credentials cross.""" + self.validate() + return json.dumps({"version": 1, "service": self.service, + "repository": self.repository}, separators=(",", ":")).encode() + + def ssh_command(self, executable: str) -> tuple[str, ...]: + """Use host SSH configuration with noninteractive, verified authentication.""" + self.validate() + return (executable, "-T", "-oBatchMode=yes", "-oStrictHostKeyChecking=yes", + "-oClearAllForwardings=yes", "-oForwardAgent=no", "-oPermitLocalCommand=no", + "-oControlMaster=no", "-oControlPath=none", "-oRemoteCommand=none", + "git@github.com", f"{self.service} '{self.repository}'") + + +def decode_request(payload: bytes) -> GitHubRequest: + """Validate the entire wire request, including field types and version.""" + try: + value = json.loads(payload) + except (ValueError, UnicodeError) as error: + raise GitHubTransportError("Invalid GitHub request JSON.") from error + if (not isinstance(value, dict) or set(value) != {"version", "service", "repository"} or + type(value["version"]) is not int or value["version"] != 1 or + not isinstance(value["service"], str) or not isinstance(value["repository"], str)): + raise GitHubTransportError("Unsupported GitHub request.") + request = GitHubRequest(value["service"], value["repository"]) + request.validate() + return request + + +def parse_git_ssh(arguments: Sequence[str]) -> GitHubRequest | None: + """Parse Git's OpenSSH invocation; other hosts use the capsule's own SSH. + + Git's protocol-v2 SendEnv request is accepted, but the broker deliberately + negotiates protocol v0 rather than accepting arbitrary client environment. + An explicit port is accepted only when it is GitHub's standard SSH port. + Host SSH configuration can select ssh.github.com:443 as usual. + """ + args = list(arguments) + port: str | None = None + while args and args[0].startswith("-"): + option = args.pop(0) + if option in {"-o", "-p"} and args: + value = args.pop(0) + if option == "-p": + port = value + elif value != "SendEnv=GIT_PROTOCOL": + raise GitHubTransportError("Unsupported SSH option for the GitHub proxy.") + elif option == "-oSendEnv=GIT_PROTOCOL": + continue + else: + raise GitHubTransportError("Unsupported SSH option for the GitHub proxy.") + if not args: + raise GitHubTransportError("Missing SSH destination.") + destination = args.pop(0) + if destination not in {"github.com", "git@github.com"}: + return None + if port not in {None, "22"} or len(args) != 1: + raise GitHubTransportError("Expected GitHub's SSH destination and one Git service.") + try: + command = shlex.split(args[0]) + except ValueError as error: + raise GitHubTransportError("Malformed Git service command.") from error + if len(command) != 2: + raise GitHubTransportError("Expected a Git service and repository only.") + request = GitHubRequest(command[0], command[1].removeprefix("/")) + request.validate() + return request diff --git a/devcapsule-src/devcapsule/launch/pycharm/_launcher.py b/devcapsule-src/devcapsule/launch/pycharm/_launcher.py index 9aed1126..9df6045a 100644 --- a/devcapsule-src/devcapsule/launch/pycharm/_launcher.py +++ b/devcapsule-src/devcapsule/launch/pycharm/_launcher.py @@ -61,12 +61,18 @@ ) from ...host_daemon import ( current_container, + in_container, daemon_architecture, docker_socket, is_host_backed, requires_translation, translate_bind_sources, ) +from ...github_proxy import ( + SOCKET_ENV as GITHUB_SOCKET_ENV, SOCKET_DESTINATION as GITHUB_SOCKET_DESTINATION, + GIT_SSH_COMMAND, github_ssh_bridge, +) +from ...github_transport import GitHubTransportError from ...host_open import ( HOST_OPEN_BROWSER, HOST_OPEN_INTEGRATION, @@ -228,6 +234,7 @@ class PycharmRunOptions: additional_environment: dict[str, str] = field(default_factory=dict) secret_environment: tuple[str, ...] = () extra_docker_args: list[str] = field(default_factory=list) + enable_github_ssh: bool = False enable_host_browser: bool = False # How the surface gets a display. ``host-x11`` is the historical # passthrough (host X socket and session credential bound into the @@ -286,6 +293,7 @@ class PycharmRunConfig: daemon_architecture: str cpus: int | None = None launch_configuration: LaunchConfiguration | None = None + github_socket: Path | None = None host_browser_socket: Path | None = None display_transport: str = HOST_X11_DISPLAY_TRANSPORT # Contained display only: the host loopback port Docker publishes (or the @@ -334,11 +342,18 @@ def run_pycharm(options: PycharmRunOptions, env: Mapping[str, str] | None = None with host_open_bridge( runtime_env, enabled=options.enable_host_browser, - ) as browser_socket: + ) as browser_socket, github_ssh_bridge( + runtime_env, enabled=options.enable_github_ssh, + containerized=in_container(), binds_unix_sockets=HostOs.current().binds_unix_sockets, + ) as github_socket: if browser_socket is None: runtime_env.pop(HOST_OPEN_SOCKET_ENV, None) else: runtime_env[HOST_OPEN_SOCKET_ENV] = str(browser_socket) + if github_socket is None: + runtime_env.pop(GITHUB_SOCKET_ENV, None) + else: + runtime_env[GITHUB_SOCKET_ENV] = str(github_socket) config = build_run_config(options, runtime_env) begin_session_logs(config, runtime_env) prepare_home_mount_points(config) @@ -430,7 +445,7 @@ def run_pycharm(options: PycharmRunOptions, env: Mapping[str, str] | None = None finally: remove_sudoers_policy_volume(files.sudoers_volume, runtime_env) cleanup_temp_runtime_files(files) - except HostOpenError as exc: + except (HostOpenError, GitHubTransportError) as exc: raise PycharmRunError(str(exc)) from exc @@ -714,6 +729,8 @@ def describe_run_command(command: list[str], config: PycharmRunConfig, ) if config.host_browser_socket is not None: comments.append("Host-browser socket requires a live broker; a broker owned by this invocation stops on return.") + if config.github_socket is not None: + comments.append("GitHub SSH socket requires a live broker; a broker owned by this invocation stops on return.") if config.display_transport == CONTAINED_DISPLAY_TRANSPORT: comments.append("Contained display needs its temporary token file; the chosen host port is not reserved for later use.") if config.console_host_port is not None: @@ -1051,6 +1068,14 @@ def build_run_config(options: PycharmRunOptions, env: Mapping[str, str]) -> Pych raise PycharmRunError("The authorized host-browser socket is absent or unsafe.") host_browser_socket = candidate + github_socket: Path | None = None + configured_github_socket = env.get(GITHUB_SOCKET_ENV) + if options.enable_github_ssh and configured_github_socket: + candidate = Path(configured_github_socket) + if not candidate.is_absolute() or ".." in candidate.parts or not is_socket(candidate): + raise PycharmRunError("The authorized GitHub socket is absent or unsafe.") + github_socket = candidate + selected_runtime_plan = options.runtime_plan if host_browser_socket is not None and selected_runtime_plan is not None: selected_runtime_plan = selected_runtime_plan.with_host_integration( @@ -1126,6 +1151,9 @@ def build_run_config(options: PycharmRunOptions, env: Mapping[str, str]) -> Pych raise PycharmRunError( "Component runtime metadata conflicts with the host-browser integration." ) + if github_socket is not None and any(name in fixed_environment or name in options.additional_environment + for name in (GITHUB_SOCKET_ENV, "GIT_SSH_COMMAND", "GIT_SSH_VARIANT")): + raise PycharmRunError("Component environment conflicts with the GitHub SSH integration.") additional_environment: list[tuple[str, str]] = [] for name, value in sorted(options.additional_environment.items()): if not name.isascii() or not name.isidentifier() or name.upper() != name: @@ -1193,6 +1221,7 @@ def build_run_config(options: PycharmRunOptions, env: Mapping[str, str]) -> Pych launch_configuration=options.launch_configuration, use_image_process=options.use_image_process, host_browser_socket=host_browser_socket, + github_socket=github_socket, display_transport=options.display_transport, display_host_port=display_host_port, display_token=display_token, @@ -1428,6 +1457,10 @@ def build_docker_args( ), ] ) + if config.github_socket is not None: + args.extend(["--env", f"{GITHUB_SOCKET_ENV}={GITHUB_SOCKET_DESTINATION}", + "--env", f"GIT_SSH_COMMAND={GIT_SSH_COMMAND}", "--env", "GIT_SSH_VARIANT=ssh", + "--mount", f"type=bind,src={config.github_socket},dst={GITHUB_SOCKET_DESTINATION},ro"]) for name, value in config.additional_environment: args.extend(["--env", f"{name}={value}"]) for name in config.secret_environment: @@ -2297,6 +2330,12 @@ def print_storage_summary(config: PycharmRunConfig) -> None: Host browser integration: Enabled through a URL-only HTTP(S) broker. Any process running as the capsule user can ask the physical host to navigate its default browser.""" + if config.github_socket is not None: + host_browser_disclosure += """ + +GitHub SSH integration: + Host-authenticated Git fetch/push proxy (all repositories your host identity + can access); private keys stay on the host.""" host_browser_disclosure += display_disclosure(config) + console_disclosure(config) if config.interactive_state_mounts: component_id = ( diff --git a/devcapsule-src/devcapsule/presentation_authoring.py b/devcapsule-src/devcapsule/presentation_authoring.py new file mode 100644 index 00000000..9258448d --- /dev/null +++ b/devcapsule-src/devcapsule/presentation_authoring.py @@ -0,0 +1,47 @@ +"""Export the portable authoring kit and form console links from explicit inputs. + +Public operations: ``export_tools`` and ``presentation_link``. +""" +from collections.abc import Mapping +from pathlib import Path +from urllib.parse import quote, urlencode, urlsplit, urlunsplit + +__all__ = ["export_tools", "presentation_link"] + + +def export_tools(destination: Path, assets: Mapping[str, bytes]) -> Path: + """Create a new directory with the supplied kit; never overwrite a prior kit.""" + if any(Path(name).name != name or name in ("", ".", "..") for name in assets): + raise ValueError("kit assets must be simple filenames") + destination.mkdir(parents=True, exist_ok=False) + package = destination / "presentation_tools" + package.mkdir() + for name, data in assets.items(): + (package / name).write_bytes(data) + return package + + +def presentation_link(folder: Path, *, project: Path, console_url: str, token: str) -> str: + """Link a visible descendant of the console project, preserving no URL query. + + Paths are absolute and resolved by the caller. The token is optional; without + it the user's browser must already have a console session. Never save a tokened + link in the evidence or project records. + """ + relative = folder.relative_to(project) + if not project.is_absolute() or not relative.parts or any( + part in ("..", "node_modules") or part.startswith(".") for part in relative.parts + ): + raise ValueError("presentation must be in a visible subdirectory of the console project") + if not console_url or any(ch.isspace() for ch in console_url): + raise ValueError("supply the capsule's HTTP(S) console URL") + origin = urlsplit(console_url) + try: + _ = origin.port + except ValueError as error: + raise ValueError("supply the capsule's HTTP(S) console URL") from error + if (origin.scheme not in ("http", "https") or not origin.hostname + or origin.username is not None or origin.password is not None): + raise ValueError("supply the capsule's HTTP(S) console URL") + path = "/presentations/" + quote(relative.as_posix(), safe="/") + return urlunsplit((origin.scheme, origin.netloc, path, urlencode({"token": token}) if token else "", "")) diff --git a/devcapsule-src/devcapsule/presentation_tools/README.md b/devcapsule-src/devcapsule/presentation_tools/README.md new file mode 100644 index 00000000..44868692 --- /dev/null +++ b/devcapsule-src/devcapsule/presentation_tools/README.md @@ -0,0 +1,104 @@ +# Run an E2E scenario with recording and presentation + +These instructions are for the agent in the engineer's project. Accept the +scenario from the engineer's existing Markdown file or their inline English. +Read it yourself; do not require the engineer to translate it into a schema. +Execute the requested test, check its observations, and give the engineer the +result and a link to the recorded presentation in their DevCapsule web console. + +## Get the tools + +`devcapsule presentations guide` prints this guide from the installed executable. +No DevCapsule source checkout is needed. Export the supporting Python package: + +```sh +devcapsule presentations export /var/tmp/e2e-authoring +``` + +The destination must be new. It contains `presentation_tools/` with this guide, +the producer, recorder and a runnable example. Add the export directory to +`PYTHONPATH` when running the project's driver. The helpers use only the Python +standard library and the Playwright page you supply. They import no test harness. + +Use the capsule's `browser-automation` capability, supplied by the `playwright` +component. Its interpreter is `$DEVCAPSULE_PLAYWRIGHT_PYTHON`, normally +`/opt/playwright/venv/bin/python`, and `$PLAYWRIGHT_BROWSERS_PATH` names its +browser directory. The directory's `ffmpeg-*/ffmpeg-linux` is the video encoder +on Linux. Locate the installed executable and pass its absolute path to the +driver. A full system `ffmpeg` also works. Do not download browsers or change +the capsule configuration silently. If the capability is missing, report it +and use the project's normal configuration/relaunch procedure with the engineer. + +## Execute the engineer's scenario + +1. Read the supplied scenario and the project's run/test instructions. Identify + the real application URL, required data, actions and observable assertions. + Ask only about a missing decision that prevents executing the test. +2. Export the tools. Adapt `presentation_tools/example.py` into a driver in the + project's normal E2E location. Translate the English into `Script` and + `ScriptStep` values in that driver. The engineer's Markdown stays unchanged. +3. Use ordinary synchronous Playwright operations for this project's UI. A + browser page can be the application itself or the capsule's noVNC desktop + when testing an IDE. The helper does not provision applications, databases + or capsules; use the project's established setup and teardown. +4. Create `Recording` with a **new visible evidence subdirectory beneath the + console's project root**: for example `evidence/login-success/run-001`. + Hidden directories, `node_modules`, paths outside the project, and the project + root itself do not appear in the presentation list. Do not overwrite attempts. +5. Call `recording.action(page, step_number, caption, callback)` around each small + real interaction and its assertions. Step numbers start at 1 and proceed in + order; several actions may belong to one step. Captions describe the action. + The callback can use locators, keyboard/mouse operations and project checks. + Assert expected observations independently of the screenshots; a recording + is evidence of a run, not proof the test passed. +6. Keep `record_video_dir=str(recording.evidence / "raw")` on the Playwright + context. The helper captures bursts before and after each action, following + the existing recorder's sparse-frame approach. Its presentation movie excludes + the agent's thinking pauses; the native video preserves motion during the + action. Split long callbacks into smaller recorded actions when viewers need + to follow intermediate UI states. Neither file is a generated explainer video. +7. Call `recording.finish()` while cleaning up, including after a test assertion + fails. Close the browser context to flush its native video. Keep the failure + exit code. Failed/incomplete runs receive labelled presentations containing + only steps reached. If capture or encoding prevents a deck, report that failure + and preserve the logs; do not claim a presentation exists. + +The helper writes `action-log.json`, `scenario-result.json`, JPEG frame data, +the encoded `scenario-video.webm`, `poster.png`, step screenshots and finally +`presentation.json`. Chapters and captions come from the recorded frame counts. +Do not estimate timestamps or hand-edit the manifest to hide a failed step. +The existing webconsole schema and viewer are used unchanged. + +## Verify and hand off + +Read `scenario-result.json` and the driver's exit status. Open the presentation +in the webconsole with Playwright; check its title, overview, screenshots and +chapter playback, including the last chapter. A failing assertion is a failed +test even when its presentation renders correctly. Report failed and unexecuted +steps explicitly. Keep evidence only under the project's normal retention rules; +avoid committing recordings or captured secrets automatically. + +Print the engineer's link with the installed CLI: + +```sh +devcapsule presentations hand-off evidence/login-success/run-001 --project "$PROJECT_PATH" +``` + +Run this from the console project root: a relative evidence folder resolves +from the current working directory, and `--project` supplies the console root +used to form the relative link. It uses `$DEVCAPSULE_CONSOLE_URL` and the +mounted console token; `--console-url` and `--token-file` supply explicit values. Keep tokened links in chat only, never +in a source file, log or committed record. If no token can be read, the link +requires a browser session that already opened the console. If there is no +console URL, report that missing environment input rather than inventing a URL. + +Finish the response with the test outcome, any limitation, and the clickable +presentation link. The engineer should not need to reconstruct a path themselves. + +## Existing replay scripts + +The exported `producer` also supports the existing structured replay format: +`parse_script`, `plan_presentation`, `PresentationPlan.timed` and +`write_presentation`. `plan_for_scenario(scenario, root)` reads the scenario's +script relative to the supplied project directory. This adapter is for agents +with existing structured scripts; it is not an input requirement for engineers. diff --git a/devcapsule-src/devcapsule/presentation_tools/__init__.py b/devcapsule-src/devcapsule/presentation_tools/__init__.py new file mode 100644 index 00000000..ae020953 --- /dev/null +++ b/devcapsule-src/devcapsule/presentation_tools/__init__.py @@ -0,0 +1 @@ +"""Portable E2E presentation tools; also exported for the Playwright interpreter.""" diff --git a/devcapsule-src/devcapsule/presentation_tools/example.py b/devcapsule-src/devcapsule/presentation_tools/example.py new file mode 100644 index 00000000..cd57bcbc --- /dev/null +++ b/devcapsule-src/devcapsule/presentation_tools/example.py @@ -0,0 +1,65 @@ +"""Adapt this two-step browser test to the engineer's English scenario. + +Run with the Playwright interpreter, from the exported kit's parent directory: +python -m presentation_tools.example --url http://127.0.0.1:8000 \ + --expected-text 'Welcome' --evidence /project/evidence/welcome/run-001 \ + --ffmpeg /opt/playwright/browsers/ffmpeg-1011/ffmpeg-linux + +The ffmpeg revision above is illustrative; locate the installed encoder. +Public operation: ``main``. All host discovery stays at this entry point. +""" +import argparse +import importlib +from pathlib import Path + +from .producer import Script, ScriptStep +from .recording import Recording + +__all__ = ["main"] + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--url", required=True) + parser.add_argument("--expected-text", required=True) + parser.add_argument("--evidence", type=Path, required=True) + parser.add_argument("--ffmpeg", required=True) + args = parser.parse_args() + playwright = importlib.import_module("playwright.sync_api") + script = Script( + goal="Verify the application's welcome page survives a reload.", + stack=(("Browser", "Chromium driven by Playwright"),), illustrates=(), + steps=( + ScriptStep("Open the application", "Navigate to the application.", args.expected_text), + ScriptStep("Reload", "Reload the page.", args.expected_text), + ), + ) + recording = Recording(args.evidence, script=script, scenario_id="welcome", + title="Welcome page", summary=script.goal, ffmpeg=(args.ffmpeg,)) + with playwright.sync_playwright() as runtime: + browser = runtime.chromium.launch(headless=True) + context = browser.new_context(viewport={"width": 1280, "height": 800}, + record_video_dir=str(args.evidence / "raw")) + page = context.new_page() + + def open_application() -> None: + page.goto(args.url) + playwright.expect(page.get_by_text(args.expected_text, exact=True)).to_be_visible() + + def reload_application() -> None: + page.reload() + playwright.expect(page.get_by_text(args.expected_text, exact=True)).to_be_visible() + + try: + recording.action(page, 1, "Open the application and check its welcome message", open_application) + recording.action(page, 2, "Reload and check the message remains visible", reload_application) + finally: + try: + recording.finish() + finally: + context.close() + browser.close() + + +if __name__ == "__main__": + main() diff --git a/devcapsule-src/devcapsule/presentation_tools/producer.py b/devcapsule-src/devcapsule/presentation_tools/producer.py new file mode 100644 index 00000000..16718f0a --- /dev/null +++ b/devcapsule-src/devcapsule/presentation_tools/producer.py @@ -0,0 +1,392 @@ +"""The presentation of a recorded scenario: ``presentation.json`` beside its recording. + +The web console shows a folder that holds a ``presentation.json`` as slides +beside the recording: an overview, then one slide per step with the step's +text, its screenshot, and its part of the video with captions. The document's +contract is ``devcapsule-webconsole/PRESENTATIONS.md``. This module writes +that document from what a recorded scenario already has, so that a recording +needs no hand-made data to be presented: + +- the scenario's JSON: ``id``, ``title``, ``description``, ``script`` (the + path of its script below the caller-supplied root) and ``actions``; +- the script, a Markdown file in the form + ``engineering-docs/development/running-e2e-scenario-recordings.md`` gives: + the goal, the stack, what the scenario illustrates, and the numbered steps + with the user's action and the expected observation; +- the count of frames the recorder had taken after each action. + +An action belongs to the step whose number starts its ``reason`` ("3. Save +the file"). A step's captions come from its actions: when none of them has a +``caption``, every action's reason, without the number, is its caption; when +some have, a caption starts at each action that has one and lasts until the +next, and the step's first action must have one. + +Public operations: ``parse_script``, ``plan_presentation``, +``PresentationPlan.timed``, ``plan_for_scenario`` and ``write_presentation``. +They raise ``PresentationError`` for a script or a scenario that cannot be +presented; the message names what to correct. +""" +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +import json +from pathlib import Path +import re +from typing import Any + +__all__ = [ + "PRESENTATION_FILE", + "PresentationError", + "PresentationPlan", + "Script", + "ScriptStep", + "parse_script", + "plan_for_scenario", + "plan_presentation", + "write_presentation", +] + +PRESENTATION_FILE = "presentation.json" +SCHEMA_VERSION = 1 + +_SECTIONS = ("Goal", "Stack And Capabilities", "What It Illustrates", "Steps") +_HEADING = re.compile(r"^## (?P.+?)\s*$") +_STEP = re.compile(r"^(?P\d+)\. \*\*(?P.+?)\*\*\s*$") +_FIELD = re.compile(r"^\s+- \*(?P<name>User action|Expected observation):\*\s+(?P<text>.+?)\s*$") +_STACK_ROW = re.compile(r"^- \*\*(?P<name>.+?):\*\*\s+(?P<detail>.+?)\s*$") +_BULLET = re.compile(r"^- (?P<text>.+?)\s*$") +_CONTINUATION = re.compile(r"^\s+(?P<text>\S.*?)\s*$") +_STEP_NUMBER = re.compile(r"^(?P<number>\d+)\.\s+(?P<text>\S.*)$", re.DOTALL) + + +class PresentationError(ValueError): + """A script or a scenario cannot be presented; the message names what to correct.""" + + +@dataclass(frozen=True) +class ScriptStep: + """One numbered step of a script.""" + + title: str + action: str + expected: str + + +@dataclass(frozen=True) +class Script: + """What a scenario's script says, section by section.""" + + goal: str + stack: tuple[tuple[str, str], ...] + illustrates: tuple[str, ...] + steps: tuple[ScriptStep, ...] + + +def parse_script(text: str) -> Script: + """The script a Markdown ``text`` in the script form states. + + The form: ``## Goal``, one paragraph; ``## Stack And Capabilities``, + optional, bullets ``- **Name:** detail``; ``## What It Illustrates``, + optional, bullets; ``## Steps``, items ``N. **Title.**`` numbered from 1, + each with the sub-bullets ``- *User action:* …`` and + ``- *Expected observation:* …``. A bullet may continue on indented lines. + Text before the first ``##`` heading is not read. Any other ``##`` + heading, a missing ``Goal`` or ``Steps``, a step out of order or without + both sub-bullets, and a line that fits nowhere are refused. + """ + sections: dict[str, list[tuple[int, str]]] = {} + current: list[tuple[int, str]] | None = None + for number, line in enumerate(text.splitlines(), start=1): + heading = _HEADING.match(line) + if heading is not None: + name = heading.group("name") + if name not in _SECTIONS: + raise PresentationError( + f"script line {number}: section {name!r} is not one of {', '.join(_SECTIONS)}" + ) + if name in sections: + raise PresentationError(f"script line {number}: section {name!r} appears twice") + current = sections[name] = [] + elif current is not None and line.strip(): + current.append((number, line)) + for required in ("Goal", "Steps"): + if not sections.get(required): + raise PresentationError(f"script: section {required!r} is missing or empty") + goal = " ".join(line.strip() for _, line in sections["Goal"]) + stack = tuple( + _stack_row(number, item) for number, item in _bullets(sections.get("Stack And Capabilities", []), "Stack And Capabilities") + ) + illustrates = tuple(item for _, item in _bullets(sections.get("What It Illustrates", []), "What It Illustrates")) + return Script(goal=goal, stack=stack, illustrates=illustrates, steps=_steps(sections["Steps"])) + + +def _bullets(lines: Sequence[tuple[int, str]], section: str) -> list[tuple[int, str]]: + """The bullets of a section, each with its first line's number, continuations joined.""" + items: list[tuple[int, str]] = [] + for number, line in lines: + bullet = _BULLET.match(line) + continuation = _CONTINUATION.match(line) + if bullet is not None: + items.append((number, bullet.group("text"))) + elif continuation is not None and items: + first, so_far = items[-1] + items[-1] = (first, f"{so_far} {continuation.group('text')}") + else: + raise PresentationError(f"script line {number}: {section!r} takes bullets, '- text'") + return items + + +def _stack_row(number: int, item: str) -> tuple[str, str]: + row = _STACK_ROW.match(f"- {item}") + if row is None: + raise PresentationError(f"script line {number}: a stack bullet is '- **Name:** detail'") + return row.group("name"), row.group("detail") + + +def _steps(lines: Sequence[tuple[int, str]]) -> tuple[ScriptStep, ...]: + steps: list[dict[str, str]] = [] + field: str | None = None + for number, line in lines: + step = _STEP.match(line) + named = _FIELD.match(line) + continuation = _CONTINUATION.match(line) + if step is not None: + if int(step.group("number")) != len(steps) + 1: + raise PresentationError(f"script line {number}: expected step {len(steps) + 1}, found {step.group('number')}") + steps.append({"title": step.group("title").rstrip(".").strip()}) + field = None + elif named is not None and steps: + field = named.group("name") + if field in steps[-1]: + raise PresentationError(f"script line {number}: step {len(steps)} states {field!r} twice") + steps[-1][field] = named.group("text") + elif continuation is not None and steps and field is not None: + steps[-1][field] = f"{steps[-1][field]} {continuation.group('text')}" + else: + raise PresentationError( + f"script line {number}: a step is 'N. **Title.**' with '- *User action:* …' and '- *Expected observation:* …'" + ) + for index, step_fields in enumerate(steps, start=1): + for required in ("User action", "Expected observation"): + if required not in step_fields: + raise PresentationError(f"script: step {index} has no {required!r}") + if not step_fields["title"]: + raise PresentationError(f"script: step {index} has no title") + return tuple( + ScriptStep(title=item["title"], action=item["User action"], expected=item["Expected observation"]) for item in steps + ) + + +@dataclass(frozen=True) +class _Caption: + """A caption and the actions it lasts for, as indexes into the scenario's actions.""" + + first_action: int + last_action: int + text: str + + +@dataclass(frozen=True) +class _PlannedStep: + step: ScriptStep + first_action: int + last_action: int + captions: tuple[_Caption, ...] + + +@dataclass(frozen=True) +class PresentationPlan: + """Everything of a presentation that is known before the scenario runs. + + ``plan_presentation`` makes it; ``timed`` adds what only a run knows. + """ + + scenario_id: str + title: str + summary: str + script: Script + action_count: int + steps: tuple[_PlannedStep, ...] + + def timed( + self, + frames_after_actions: Sequence[int], + total_frames: int, + frames_per_second: int, + *, + video: str, + poster: str, + screenshots: Sequence[str], + ) -> dict[str, Any]: + """The presentation document of one recorded run of the planned scenario. + + ``frames_after_actions[i]`` is the count of frames recorded when + action ``i`` had finished, ``total_frames`` the count in the video, + which plays ``frames_per_second`` of them, and ``screenshots[i]`` the + file taken after action ``i``. A step runs from the end of the step + before it, the first from the start of the video, to the end of its + last action, the last to the end of the video; its screenshot is its + last action's. Refuses counts that do not match the plan, that + decrease, that exceed the total, or that leave a step or a caption + without a frame. + """ + if len(frames_after_actions) != self.action_count or len(screenshots) != self.action_count: + raise PresentationError( + f"the run has {len(frames_after_actions)} frame counts and {len(screenshots)} screenshots " + f"for {self.action_count} actions" + ) + if frames_per_second <= 0: + raise PresentationError(f"frames per second must be positive, not {frames_per_second}") + counts = list(frames_after_actions) + if any(later < earlier for earlier, later in zip([0, *counts], [*counts, total_frames])): + raise PresentationError("the frame counts decrease or exceed the total number of frames") + last_action = self.action_count - 1 + + def seconds(frames: int) -> float: + return round(frames / frames_per_second, 3) + + def starts(action: int) -> int: + return 0 if action == 0 else counts[action - 1] + + def ends(action: int) -> int: + return total_frames if action == last_action else counts[action] + + steps = [] + for number, planned in enumerate(self.steps, start=1): + if any(starts(caption.first_action) >= ends(caption.last_action) for caption in planned.captions): + raise PresentationError(f"step {number} has a caption that lasts no frame") + captions = [ + {"start": seconds(starts(caption.first_action)), "end": seconds(ends(caption.last_action)), "text": caption.text} + for caption in planned.captions + ] + steps.append({ + "title": planned.step.title, + "action": planned.step.action, + "expected": planned.step.expected, + "screenshot": screenshots[planned.last_action], + "start": seconds(starts(planned.first_action)), + "end": seconds(ends(planned.last_action)), + "captions": captions, + }) + overview: dict[str, Any] = {"summary": self.summary, "intent": self.script.goal} + if self.script.illustrates: + overview["illustrates"] = list(self.script.illustrates) + if self.script.stack: + overview["stack"] = [{"name": name, "detail": detail} for name, detail in self.script.stack] + return { + "schema_version": SCHEMA_VERSION, + "scenario_id": self.scenario_id, + "title": self.title, + "overview": overview, + "video": {"file": video, "poster": poster, "duration": seconds(total_frames)}, + "steps": steps, + } + + +def plan_presentation(scenario: Mapping[str, Any], script: Script) -> PresentationPlan: + """Join a scenario's JSON document to its parsed script, or say why they do not join. + + The scenario needs a non-empty ``id``, ``title`` and ``description``. Each + action's ``reason`` starts with the number of its step and a period; the + numbers never decrease and every step of the script has at least one + action. ``caption``, where an action has it, is a non-empty string, and a + step with any caption has one on its first action. + """ + texts = {} + for key in ("id", "title", "description"): + value = scenario.get(key) + if not isinstance(value, str) or not value.strip(): + raise PresentationError(f"the scenario has no {key}") + texts[key] = value.strip() + if not isinstance(script.goal, str) or not script.goal.strip(): + raise PresentationError("the script has no goal") + if not script.steps: + raise PresentationError("the script has no steps") + for index, step in enumerate(script.steps, start=1): + for field_name, field_value in (("title", step.title), ("action", step.action), ("expected", step.expected)): + if not isinstance(field_value, str) or not field_value.strip(): + raise PresentationError(f"script step {index} has no {field_name}") + if any(not isinstance(item, str) or not item.strip() for item in script.illustrates): + raise PresentationError("script illustrations must be non-empty texts") + if any(not isinstance(name, str) or not name.strip() or not isinstance(detail, str) or not detail.strip() + for name, detail in script.stack): + raise PresentationError("script stack entries must have non-empty name and detail") + actions = scenario.get("actions") + if not isinstance(actions, list) or not actions: + raise PresentationError("the scenario has no actions") + numbers: list[int] = [] + reasons: list[str] = [] + captions: list[str | None] = [] + for position, action in enumerate(actions, start=1): + if not isinstance(action, Mapping): + raise PresentationError(f"action {position} is not an object") + reason = action.get("reason") + numbered = _STEP_NUMBER.match(reason) if isinstance(reason, str) else None + if numbered is None: + raise PresentationError(f"action {position}: its reason must start with the number of its step, as in '3. Save the file'") + number = int(numbered.group("number")) + if not 1 <= number <= len(script.steps): + raise PresentationError(f"action {position} names step {number}; the script has steps 1 to {len(script.steps)}") + if numbers and number < numbers[-1]: + raise PresentationError(f"action {position} names step {number} after an action of step {numbers[-1]}") + caption = action.get("caption") + if caption is not None and (not isinstance(caption, str) or not caption.strip()): + raise PresentationError(f"action {position}: its caption must be a non-empty text") + numbers.append(number) + reasons.append(numbered.group("text").strip()) + captions.append(caption.strip() if isinstance(caption, str) else None) + planned: list[_PlannedStep] = [] + for number, step in enumerate(script.steps, start=1): + members = [index for index, owner in enumerate(numbers) if owner == number] + if not members: + raise PresentationError(f"step {number} of the script has no action") + planned.append(_PlannedStep( + step=step, first_action=members[0], last_action=members[-1], captions=_captions(number, members, reasons, captions), + )) + return PresentationPlan( + scenario_id=texts["id"], title=texts["title"], summary=texts["description"], script=script, + action_count=len(actions), steps=tuple(planned), + ) + + +def _captions(number: int, members: Sequence[int], reasons: Sequence[str], captions: Sequence[str | None]) -> tuple[_Caption, ...]: + """The captions of one step's actions, by the rule in the module's documentation.""" + written = [index for index in members if captions[index] is not None] + if not written: + return tuple(_Caption(first_action=index, last_action=index, text=reasons[index]) for index in members) + if written[0] != members[0]: + raise PresentationError( + f"step {number} has captions, so its first action, action {members[0] + 1}, needs one" + ) + ends = [*(index - 1 for index in written[1:]), members[-1]] + return tuple( + _Caption(first_action=first, last_action=last, text=str(captions[first])) for first, last in zip(written, ends) + ) + + +def plan_for_scenario(scenario: Mapping[str, Any], root: Path) -> PresentationPlan | None: + """The plan of a scenario that names its ``script``, read below ``root``; None for one that names none. + + A scenario without a script is recorded without a presentation. A script + that is named and cannot be read, or that does not join the scenario, is + an error: call this before the scenario runs, so the recording is not + made in vain. + """ + named = scenario.get("script") + if named is None: + return None + if not isinstance(named, str) or not named.strip() or Path(named).is_absolute() or ".." in Path(named).parts: + raise PresentationError(f"the scenario's script {named!r} is not a path below {root}") + try: + text = (root / named).read_text(encoding="utf-8") + except OSError as error: + raise PresentationError(f"the scenario's script {named!r} cannot be read below {root}: {error}") from error + return plan_presentation(scenario, parse_script(text)) + + +def write_presentation(evidence: Path, document: Mapping[str, Any]) -> Path: + """Write ``document`` as ``presentation.json`` in the ``evidence`` folder and return its path.""" + path = evidence / PRESENTATION_FILE + path.write_text(json.dumps(document, indent=2, ensure_ascii=False) + "\n", encoding="utf-8") + return path diff --git a/devcapsule-src/devcapsule/presentation_tools/recording.py b/devcapsule-src/devcapsule/presentation_tools/recording.py new file mode 100644 index 00000000..4b418c88 --- /dev/null +++ b/devcapsule-src/devcapsule/presentation_tools/recording.py @@ -0,0 +1,143 @@ +"""Record real Playwright actions and derive presentation timing from their frames. + +Public surface: ``Recording``. The caller supplies its page, scenario, evidence +directory and ffmpeg command. No DevCapsule installation or test harness is +needed by the exported package. Assertions belong in the supplied action. +""" +from __future__ import annotations + +from collections.abc import Callable, Sequence +import json +from pathlib import Path +import subprocess +from typing import Any + +from .producer import PresentationError, Script, plan_presentation, write_presentation + +__all__ = ["Recording"] + + +class Recording: + """Capture bursts around actions, excluding time the agent spends thinking. + + Each action has a one-based script step and a caption. Repeated actions may + belong to the same step. Steps must run in order. ``finish`` keeps a failed + or incomplete run visibly failed; it never infers success from screenshots. + Use a new evidence directory for each attempt; existing runs are refused. + """ + + def __init__( + self, evidence: Path, *, script: Script, scenario_id: str, title: str, + summary: str, ffmpeg: Sequence[str], + ) -> None: + # Check the complete scenario before opening a browser or making files. + scenario: dict[str, Any] = {"id": scenario_id, "title": title, "description": summary, + "actions": [{"reason": f"{n}. {step.action}"} + for n, step in enumerate(script.steps, 1)]} + plan_presentation(scenario, script) + if isinstance(ffmpeg, (str, bytes)) or not ffmpeg or not all(isinstance(part, str) and part for part in ffmpeg): + raise PresentationError("supply the ffmpeg command from the browser-automation environment") + evidence.mkdir(parents=True, exist_ok=False) + self.evidence = evidence + self.script = script + self.scenario = scenario + self.ffmpeg = tuple(ffmpeg) + self.actions: list[dict[str, Any]] = [] + self.frames_after_actions: list[int] = [] + self.screenshots: list[str] = [] + self.frame_count = 0 + self.last_step = 0 + self.failure = "" + self.finished = False + self.frames = evidence / "frames.mjpeg" + + def _capture(self, page: Any, count: int) -> None: + # Playwright's bundled ffmpeg decodes MJPEG, but need not decode PNG. + with self.frames.open("ab") as output: + for _ in range(count): + output.write(page.screenshot(type="jpeg", quality=90)) + self.frame_count += 1 + page.wait_for_timeout(100) + + def action(self, page: Any, step: int, caption: str, perform: Callable[[], object]) -> None: + """Record an action and its assertions; retain failure evidence and re-raise. + + The supplied callback uses ordinary Playwright selectors, mouse/keyboard + operations or project checks. Keep actions small enough that their before + and after frames show the interaction; native Playwright video may also be + kept in ``evidence/raw`` to preserve uninterrupted motion. + """ + if self.finished or self.failure: + raise PresentationError("this run has finished or failed; start a new run") + if (isinstance(step, bool) or not isinstance(step, int) + or not 1 <= step <= len(self.script.steps) + or step not in (self.last_step, self.last_step + 1)): + raise PresentationError("actions must visit script steps in order, starting at 1") + if not isinstance(caption, str) or not caption.strip(): + raise PresentationError("each recorded action needs a non-empty caption") + self.last_step = step + entry: dict[str, Any] = {"reason": f"{step}. {caption}", "status": "passed"} + self.actions.append(entry) + try: + self._capture(page, 2) + perform() + self._capture(page, 6) + screenshot = f"step-{len(self.actions):03d}.png" + page.screenshot(path=str(self.evidence / screenshot)) + self.screenshots.append(screenshot) + except BaseException as error: + self.failure = f"{type(error).__name__}: {error}" + entry.update(status="failed", error=self.failure) + # A disconnected browser must not replace the original test failure. + try: + self._capture(page, 1) + screenshot = f"step-{len(self.actions):03d}.png" + page.screenshot(path=str(self.evidence / screenshot)) + self.screenshots.append(screenshot) + except Exception: + pass + raise + finally: + self.frames_after_actions.append(self.frame_count) + entry["frames_after"] = self.frame_count + self._write_result() + + def _write_result(self) -> None: + complete = self.last_step == len(self.script.steps) and not self.failure + result = {"status": "failed" if self.failure else "passed" if self.finished and complete else "incomplete", + "error": self.failure, "steps_reached": self.last_step, + "steps_planned": len(self.script.steps)} + for name, value in (("scenario-result.json", result), ("action-log.json", self.actions)): + (self.evidence / name).write_text(json.dumps(value, indent=2) + "\n", encoding="utf-8") + + def finish(self) -> Path: + """Encode frames and publish the deck last; refuse missing visual evidence. + + Logs survive encoding failure. A failed test produces a labelled deck + containing only the steps it reached, and keeps its failed result. + """ + if self.finished: + raise PresentationError("this recording has already been finished") + self.finished = True + self._write_result() + if not self.actions or len(self.screenshots) != len(self.actions): + raise PresentationError("no complete visual evidence; inspect scenario-result.json and action-log.json") + complete = self.last_step == len(self.script.steps) and not self.failure + suffix = "" if complete else " (FAILED)" if self.failure else " (INCOMPLETE)" + scenario = dict(self.scenario, title=self.scenario["title"].strip() + suffix, actions=self.actions) + reached = Script(self.script.goal, self.script.stack, self.script.illustrates, + self.script.steps[:self.last_step]) + plan = plan_presentation(scenario, reached) + document = plan.timed(self.frames_after_actions, self.frame_count, 12, + video="scenario-video.webm", poster="poster.png", screenshots=self.screenshots) + video = self.evidence / "scenario-video.webm" + with self.frames.open("rb") as frames, (self.evidence / "ffmpeg.log").open("wb") as log: + subprocess.run( + [*self.ffmpeg, "-y", "-f", "image2pipe", "-vcodec", "mjpeg", "-r", "12", + "-i", "pipe:0", "-c:v", "libvpx", "-b:v", "3M", "-crf", "10", str(video)], + stdin=frames, stdout=log, stderr=log, check=True, timeout=120, + ) + if not video.is_file() or video.stat().st_size == 0: + raise PresentationError("video encoding produced no scenario-video.webm; inspect ffmpeg.log") + (self.evidence / "poster.png").write_bytes((self.evidence / self.screenshots[0]).read_bytes()) + return write_presentation(self.evidence, document) diff --git a/devcapsule-src/pyproject.toml b/devcapsule-src/pyproject.toml index 37dc4aba..356776d7 100644 --- a/devcapsule-src/pyproject.toml +++ b/devcapsule-src/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "devcapsule" -version = "0.3.1" +version = "0.3.2.dev0" description = "Profile-driven Docker launch tooling for isolated IDE development environments." readme = "README.md" requires-python = ">=3.12" @@ -47,6 +47,7 @@ where = ["."] include = ["devcapsule*"] [tool.setuptools.package-data] +"devcapsule.presentation_tools" = ["README.md"] "devcapsule" = [ "_build_info.json", "_compatibility-v1.json", diff --git a/devcapsule-src/tests/configuration/test_nodes.py b/devcapsule-src/tests/configuration/test_nodes.py deleted file mode 100644 index 4a1ac13d..00000000 --- a/devcapsule-src/tests/configuration/test_nodes.py +++ /dev/null @@ -1,170 +0,0 @@ -"""Focused tests for the configuration-node registry.""" - -from __future__ import annotations - -import pytest - -from devcapsule.configuration.nodes import ( - CARRIER_FAMILY_AUTHORIZE, - CARRIER_FAMILY_BIND, - CARRIER_FAMILY_SET, - PROVIDER_HOST_DIRECTORY, - PROVIDER_HOST_ENVIRONMENT, - build_node_registry, -) -from devcapsule.configuration.file_formats import ( - ProjectConfigurationError, -) - -pytestmark = pytest.mark.legacy - - -def example_manifest() -> dict: - return { - "devcapsule-schema-version": 1, - "capabilities": {"need": ["python", "python-ide", "codex-agent"]}, - "project": { - "name": "Example", - "slug": "example", - "creator": "https://github.com/example", - "mount": "/workspace/example", - }, - "configuration": { - "values": { - "runtime.memory-limit": { - "type": "memory-size", - "runtime-effect": "docker.memory-limit", - "description": "Hard memory limit for the project container.", - } - } - }, - "host": { - "docker": { - "mode": { - "recommended": { - "value": "host-socket", - "justification": "Required for the full test suite.", - } - } - } - }, - } - - -def example_lock() -> dict: - return { - "devcapsule-lock-format-version": 1, - "platform": "linux-amd64", - "base": { - "reference": "docker.io/mycodespaceai/devcapsule-base@sha256:" + "6" * 64, - }, - "components": { - "interactive-surface": "pycharm", - "pycharm": { - "version": "2026.2.0.1", - "variant": "professional", - "delivery-policy": "local-materialization", - "url": "https://example.test/pycharm.tar.gz", - "sha256": "a" * 64, - }, - "codex": { - "version": "0.145.0", - "delivery-policy": "local-materialization", - }, - }, - } - - -def test_registry_assigns_each_declaration_kind_to_its_family() -> None: - registry = build_node_registry(example_manifest(), example_lock()) - - value = registry.node("runtime.memory-limit") - assert value.family == CARRIER_FAMILY_SET - assert value.required is False - - home = registry.node("home") - assert home.family == CARRIER_FAMILY_BIND - assert home.providers == (PROVIDER_HOST_DIRECTORY,) - - slot = registry.node("pycharm/system") - assert slot.family == CARRIER_FAMILY_BIND - - secret = registry.node("codex/openai-api-key") - assert secret.family == CARRIER_FAMILY_BIND - assert secret.providers == (PROVIDER_HOST_ENVIRONMENT,) - assert secret.required is False - - base = registry.node("base-image") - assert base.family == CARRIER_FAMILY_AUTHORIZE - assert base.required is True - assert base.accepts_justification is False - - docker = registry.node("docker-daemon") - assert docker.family == CARRIER_FAMILY_AUTHORIZE - assert docker.required is False - assert docker.accepts_justification is True - assert docker.description == "Required for the full test suite." - - -def test_registry_names_are_sorted_and_family_filtered() -> None: - registry = build_node_registry(example_manifest(), example_lock()) - names = registry.names() - assert names == tuple(sorted(names)) - authorize = registry.family(CARRIER_FAMILY_AUTHORIZE) - # docker-daemon comes from the manifest recommendation; network, - # development-sudo, host-browser and host-x11 exist as - # home-capability defaults, network since 2026-10-22. - assert {node.name for node in authorize} == { - "base-image", - "docker-daemon", - "network", - "development-sudo", - "host-browser", - "host-x11", - } - - -def test_unknown_node_lists_the_declared_vocabulary() -> None: - registry = build_node_registry(example_manifest(), example_lock()) - with pytest.raises(ProjectConfigurationError) as failure: - registry.node("does-not-exist") - assert "'does-not-exist'" in str(failure.value) - assert "runtime.memory-limit" in str(failure.value) - - -def test_wrong_carrier_family_names_the_right_spelling() -> None: - registry = build_node_registry(example_manifest(), example_lock()) - with pytest.raises(ProjectConfigurationError, match="answered with --bind, not --set"): - registry.answerable("home", CARRIER_FAMILY_SET) - - -def test_bind_values_split_on_the_first_colon_only() -> None: - registry = build_node_registry(example_manifest(), example_lock()) - provider, value = registry.split_bind_value("home", "host-directory:/state/x:y") - assert provider == PROVIDER_HOST_DIRECTORY - assert value == "/state/x:y" - - provider, value = registry.split_bind_value( - "codex/openai-api-key", "host-environment:OPENAI_API_KEY" - ) - assert provider == PROVIDER_HOST_ENVIRONMENT - assert value == "OPENAI_API_KEY" - - -def test_bind_value_rejects_wrong_or_missing_provider() -> None: - registry = build_node_registry(example_manifest(), example_lock()) - with pytest.raises(ProjectConfigurationError, match="host-environment:VALUE"): - registry.split_bind_value("codex/openai-api-key", "host-directory:/somewhere") - with pytest.raises(ProjectConfigurationError, match="host-directory:VALUE"): - registry.split_bind_value("home", "/no/provider/prefix") - - -def test_a_name_declared_twice_fails_at_construction() -> None: - manifest = example_manifest() - # A project-declared value colliding with the component slot name 'home'. - manifest["configuration"]["values"]["home"] = { - "type": "string", - "description": "Colliding declaration.", - } - with pytest.raises(ProjectConfigurationError, match="declared twice"): - build_node_registry(manifest, example_lock()) diff --git a/devcapsule-src/tests/e2e/scenario_presentation.py b/devcapsule-src/tests/e2e/scenario_presentation.py index 254439a3..b9f7ae96 100644 --- a/devcapsule-src/tests/e2e/scenario_presentation.py +++ b/devcapsule-src/tests/e2e/scenario_presentation.py @@ -1,382 +1,27 @@ -"""The presentation of a recorded scenario: ``presentation.json`` beside its recording. +"""Repository scenario adapter for the shipped presentation producer. -The web console shows a folder that holds a ``presentation.json`` as slides -beside the recording: an overview, then one slide per step with the step's -text, its screenshot, and its part of the video with captions. The document's -contract is ``devcapsule-webconsole/PRESENTATIONS.md``. This module writes -that document from what a recorded scenario already has, so that a recording -needs no hand-made data to be presented: - -- the scenario's JSON: ``id``, ``title``, ``description``, ``script`` (the - path of its script below ``tests/e2e``) and ``actions``; -- the script, a Markdown file in the form - ``engineering-docs/development/running-e2e-scenario-recordings.md`` gives: - the goal, the stack, what the scenario illustrates, and the numbered steps - with the user's action and the expected observation; -- the count of frames the recorder had taken after each action. - -An action belongs to the step whose number starts its ``reason`` ("3. Save -the file"). A step's captions come from its actions: when none of them has a -``caption``, every action's reason, without the number, is its caption; when -some have, a caption starts at each action that has one and lasts until the -next, and the step's first action must have one. - -Public operations: ``parse_script``, ``plan_presentation``, -``PresentationPlan.timed``, ``plan_for_scenario`` and ``write_presentation``. -They raise ``PresentationError`` for a script or a scenario that cannot be -presented; the message names what to correct. +Public operations are the producer exports and ``plan_for_scenario`` with +this test harness's script root. """ -from __future__ import annotations - -from collections.abc import Mapping, Sequence -from dataclasses import dataclass -import json +from collections.abc import Mapping from pathlib import Path -import re from typing import Any -__all__ = [ - "E2E_ROOT", - "PRESENTATION_FILE", - "PresentationError", - "PresentationPlan", - "Script", - "ScriptStep", - "parse_script", - "plan_for_scenario", - "plan_presentation", - "write_presentation", -] +from devcapsule.presentation_tools.producer import ( + PRESENTATION_FILE as PRESENTATION_FILE, + PresentationError as PresentationError, + PresentationPlan as PresentationPlan, + Script as Script, + ScriptStep as ScriptStep, + parse_script as parse_script, + plan_for_scenario as _plan_for_scenario, + plan_presentation as plan_presentation, + write_presentation as write_presentation, +) E2E_ROOT = Path(__file__).resolve().parent -"""A scenario's ``script`` path is relative to this directory.""" -PRESENTATION_FILE = "presentation.json" -SCHEMA_VERSION = 1 - -_SECTIONS = ("Goal", "Stack And Capabilities", "What It Illustrates", "Steps") -_HEADING = re.compile(r"^## (?P<name>.+?)\s*$") -_STEP = re.compile(r"^(?P<number>\d+)\. \*\*(?P<title>.+?)\*\*\s*$") -_FIELD = re.compile(r"^\s+- \*(?P<name>User action|Expected observation):\*\s+(?P<text>.+?)\s*$") -_STACK_ROW = re.compile(r"^- \*\*(?P<name>.+?):\*\*\s+(?P<detail>.+?)\s*$") -_BULLET = re.compile(r"^- (?P<text>.+?)\s*$") -_CONTINUATION = re.compile(r"^\s+(?P<text>\S.*?)\s*$") -_STEP_NUMBER = re.compile(r"^(?P<number>\d+)\.\s+(?P<text>\S.*)$", re.DOTALL) - - -class PresentationError(ValueError): - """A script or a scenario cannot be presented; the message names what to correct.""" - - -@dataclass(frozen=True) -class ScriptStep: - """One numbered step of a script.""" - - title: str - action: str - expected: str - - -@dataclass(frozen=True) -class Script: - """What a scenario's script says, section by section.""" - - goal: str - stack: tuple[tuple[str, str], ...] - illustrates: tuple[str, ...] - steps: tuple[ScriptStep, ...] - - -def parse_script(text: str) -> Script: - """The script a Markdown ``text`` in the script form states. - - The form: ``## Goal``, one paragraph; ``## Stack And Capabilities``, - optional, bullets ``- **Name:** detail``; ``## What It Illustrates``, - optional, bullets; ``## Steps``, items ``N. **Title.**`` numbered from 1, - each with the sub-bullets ``- *User action:* …`` and - ``- *Expected observation:* …``. A bullet may continue on indented lines. - Text before the first ``##`` heading is not read. Any other ``##`` - heading, a missing ``Goal`` or ``Steps``, a step out of order or without - both sub-bullets, and a line that fits nowhere are refused. - """ - sections: dict[str, list[tuple[int, str]]] = {} - current: list[tuple[int, str]] | None = None - for number, line in enumerate(text.splitlines(), start=1): - heading = _HEADING.match(line) - if heading is not None: - name = heading.group("name") - if name not in _SECTIONS: - raise PresentationError( - f"script line {number}: section {name!r} is not one of {', '.join(_SECTIONS)}" - ) - if name in sections: - raise PresentationError(f"script line {number}: section {name!r} appears twice") - current = sections[name] = [] - elif current is not None and line.strip(): - current.append((number, line)) - for required in ("Goal", "Steps"): - if not sections.get(required): - raise PresentationError(f"script: section {required!r} is missing or empty") - goal = " ".join(line.strip() for _, line in sections["Goal"]) - stack = tuple( - _stack_row(number, item) for number, item in _bullets(sections.get("Stack And Capabilities", []), "Stack And Capabilities") - ) - illustrates = tuple(item for _, item in _bullets(sections.get("What It Illustrates", []), "What It Illustrates")) - return Script(goal=goal, stack=stack, illustrates=illustrates, steps=_steps(sections["Steps"])) - - -def _bullets(lines: Sequence[tuple[int, str]], section: str) -> list[tuple[int, str]]: - """The bullets of a section, each with its first line's number, continuations joined.""" - items: list[tuple[int, str]] = [] - for number, line in lines: - bullet = _BULLET.match(line) - continuation = _CONTINUATION.match(line) - if bullet is not None: - items.append((number, bullet.group("text"))) - elif continuation is not None and items: - first, so_far = items[-1] - items[-1] = (first, f"{so_far} {continuation.group('text')}") - else: - raise PresentationError(f"script line {number}: {section!r} takes bullets, '- text'") - return items - - -def _stack_row(number: int, item: str) -> tuple[str, str]: - row = _STACK_ROW.match(f"- {item}") - if row is None: - raise PresentationError(f"script line {number}: a stack bullet is '- **Name:** detail'") - return row.group("name"), row.group("detail") - - -def _steps(lines: Sequence[tuple[int, str]]) -> tuple[ScriptStep, ...]: - steps: list[dict[str, str]] = [] - field: str | None = None - for number, line in lines: - step = _STEP.match(line) - named = _FIELD.match(line) - continuation = _CONTINUATION.match(line) - if step is not None: - if int(step.group("number")) != len(steps) + 1: - raise PresentationError(f"script line {number}: expected step {len(steps) + 1}, found {step.group('number')}") - steps.append({"title": step.group("title").rstrip(".").strip()}) - field = None - elif named is not None and steps: - field = named.group("name") - if field in steps[-1]: - raise PresentationError(f"script line {number}: step {len(steps)} states {field!r} twice") - steps[-1][field] = named.group("text") - elif continuation is not None and steps and field is not None: - steps[-1][field] = f"{steps[-1][field]} {continuation.group('text')}" - else: - raise PresentationError( - f"script line {number}: a step is 'N. **Title.**' with '- *User action:* …' and '- *Expected observation:* …'" - ) - for index, step_fields in enumerate(steps, start=1): - for required in ("User action", "Expected observation"): - if required not in step_fields: - raise PresentationError(f"script: step {index} has no {required!r}") - if not step_fields["title"]: - raise PresentationError(f"script: step {index} has no title") - return tuple( - ScriptStep(title=item["title"], action=item["User action"], expected=item["Expected observation"]) for item in steps - ) - - -@dataclass(frozen=True) -class _Caption: - """A caption and the actions it lasts for, as indexes into the scenario's actions.""" - - first_action: int - last_action: int - text: str - - -@dataclass(frozen=True) -class _PlannedStep: - step: ScriptStep - first_action: int - last_action: int - captions: tuple[_Caption, ...] - - -@dataclass(frozen=True) -class PresentationPlan: - """Everything of a presentation that is known before the scenario runs. - - ``plan_presentation`` makes it; ``timed`` adds what only a run knows. - """ - - scenario_id: str - title: str - summary: str - script: Script - action_count: int - steps: tuple[_PlannedStep, ...] - - def timed( - self, - frames_after_actions: Sequence[int], - total_frames: int, - frames_per_second: int, - *, - video: str, - poster: str, - screenshots: Sequence[str], - ) -> dict[str, Any]: - """The presentation document of one recorded run of the planned scenario. - - ``frames_after_actions[i]`` is the count of frames recorded when - action ``i`` had finished, ``total_frames`` the count in the video, - which plays ``frames_per_second`` of them, and ``screenshots[i]`` the - file taken after action ``i``. A step runs from the end of the step - before it, the first from the start of the video, to the end of its - last action, the last to the end of the video; its screenshot is its - last action's. Refuses counts that do not match the plan, that - decrease, that exceed the total, or that leave a step or a caption - without a frame. - """ - if len(frames_after_actions) != self.action_count or len(screenshots) != self.action_count: - raise PresentationError( - f"the run has {len(frames_after_actions)} frame counts and {len(screenshots)} screenshots " - f"for {self.action_count} actions" - ) - if frames_per_second <= 0: - raise PresentationError(f"frames per second must be positive, not {frames_per_second}") - counts = list(frames_after_actions) - if any(later < earlier for earlier, later in zip([0, *counts], [*counts, total_frames])): - raise PresentationError("the frame counts decrease or exceed the total number of frames") - last_action = self.action_count - 1 - - def seconds(frames: int) -> float: - return round(frames / frames_per_second, 3) - - def starts(action: int) -> int: - return 0 if action == 0 else counts[action - 1] - - def ends(action: int) -> int: - return total_frames if action == last_action else counts[action] - - steps = [] - for number, planned in enumerate(self.steps, start=1): - if any(starts(caption.first_action) >= ends(caption.last_action) for caption in planned.captions): - raise PresentationError(f"step {number} has a caption that lasts no frame") - captions = [ - {"start": seconds(starts(caption.first_action)), "end": seconds(ends(caption.last_action)), "text": caption.text} - for caption in planned.captions - ] - steps.append({ - "title": planned.step.title, - "action": planned.step.action, - "expected": planned.step.expected, - "screenshot": screenshots[planned.last_action], - "start": seconds(starts(planned.first_action)), - "end": seconds(ends(planned.last_action)), - "captions": captions, - }) - overview: dict[str, Any] = {"summary": self.summary, "intent": self.script.goal} - if self.script.illustrates: - overview["illustrates"] = list(self.script.illustrates) - if self.script.stack: - overview["stack"] = [{"name": name, "detail": detail} for name, detail in self.script.stack] - return { - "schema_version": SCHEMA_VERSION, - "scenario_id": self.scenario_id, - "title": self.title, - "overview": overview, - "video": {"file": video, "poster": poster, "duration": seconds(total_frames)}, - "steps": steps, - } - - -def plan_presentation(scenario: Mapping[str, Any], script: Script) -> PresentationPlan: - """Join a scenario's JSON document to its parsed script, or say why they do not join. - - The scenario needs a non-empty ``id``, ``title`` and ``description``. Each - action's ``reason`` starts with the number of its step and a period; the - numbers never decrease and every step of the script has at least one - action. ``caption``, where an action has it, is a non-empty string, and a - step with any caption has one on its first action. - """ - texts = {} - for key in ("id", "title", "description"): - value = scenario.get(key) - if not isinstance(value, str) or not value.strip(): - raise PresentationError(f"the scenario has no {key}") - texts[key] = value.strip() - actions = scenario.get("actions") - if not isinstance(actions, list) or not actions: - raise PresentationError("the scenario has no actions") - numbers: list[int] = [] - reasons: list[str] = [] - captions: list[str | None] = [] - for position, action in enumerate(actions, start=1): - if not isinstance(action, Mapping): - raise PresentationError(f"action {position} is not an object") - reason = action.get("reason") - numbered = _STEP_NUMBER.match(reason) if isinstance(reason, str) else None - if numbered is None: - raise PresentationError(f"action {position}: its reason must start with the number of its step, as in '3. Save the file'") - number = int(numbered.group("number")) - if not 1 <= number <= len(script.steps): - raise PresentationError(f"action {position} names step {number}; the script has steps 1 to {len(script.steps)}") - if numbers and number < numbers[-1]: - raise PresentationError(f"action {position} names step {number} after an action of step {numbers[-1]}") - caption = action.get("caption") - if caption is not None and (not isinstance(caption, str) or not caption.strip()): - raise PresentationError(f"action {position}: its caption must be a non-empty text") - numbers.append(number) - reasons.append(numbered.group("text").strip()) - captions.append(caption.strip() if isinstance(caption, str) else None) - planned: list[_PlannedStep] = [] - for number, step in enumerate(script.steps, start=1): - members = [index for index, owner in enumerate(numbers) if owner == number] - if not members: - raise PresentationError(f"step {number} of the script has no action") - planned.append(_PlannedStep( - step=step, first_action=members[0], last_action=members[-1], captions=_captions(number, members, reasons, captions), - )) - return PresentationPlan( - scenario_id=texts["id"], title=texts["title"], summary=texts["description"], script=script, - action_count=len(actions), steps=tuple(planned), - ) - - -def _captions(number: int, members: Sequence[int], reasons: Sequence[str], captions: Sequence[str | None]) -> tuple[_Caption, ...]: - """The captions of one step's actions, by the rule in the module's documentation.""" - written = [index for index in members if captions[index] is not None] - if not written: - return tuple(_Caption(first_action=index, last_action=index, text=reasons[index]) for index in members) - if written[0] != members[0]: - raise PresentationError( - f"step {number} has captions, so its first action, action {members[0] + 1}, needs one" - ) - ends = [*(index - 1 for index in written[1:]), members[-1]] - return tuple( - _Caption(first_action=first, last_action=last, text=str(captions[first])) for first, last in zip(written, ends) - ) def plan_for_scenario(scenario: Mapping[str, Any], root: Path = E2E_ROOT) -> PresentationPlan | None: - """The plan of a scenario that names its ``script``, read below ``root``; None for one that names none. - - A scenario without a script is recorded without a presentation. A script - that is named and cannot be read, or that does not join the scenario, is - an error: call this before the scenario runs, so the recording is not - made in vain. - """ - named = scenario.get("script") - if named is None: - return None - if not isinstance(named, str) or not named.strip() or Path(named).is_absolute() or ".." in Path(named).parts: - raise PresentationError(f"the scenario's script {named!r} is not a path below {root}") - try: - text = (root / named).read_text(encoding="utf-8") - except OSError as error: - raise PresentationError(f"the scenario's script {named!r} cannot be read below {root}: {error}") from error - return plan_presentation(scenario, parse_script(text)) - - -def write_presentation(evidence: Path, document: Mapping[str, Any]) -> Path: - """Write ``document`` as ``presentation.json`` in the ``evidence`` folder and return its path.""" - path = evidence / PRESENTATION_FILE - path.write_text(json.dumps(document, indent=2, ensure_ascii=False) + "\n", encoding="utf-8") - return path + """Read a repository scenario's script relative to its E2E directory.""" + return _plan_for_scenario(scenario, root) diff --git a/devcapsule-src/tests/e2e/scenario_recorder.py b/devcapsule-src/tests/e2e/scenario_recorder.py index 3a429405..188fc4fb 100644 --- a/devcapsule-src/tests/e2e/scenario_recorder.py +++ b/devcapsule-src/tests/e2e/scenario_recorder.py @@ -656,18 +656,25 @@ def serve_interactive_controller( executable: Path, spec: ScenarioSpec, evidence: Path, + *, + surface: IdeSurface | None = None, + timeout: float = 1800.0, ) -> None: """Start an interactive E2E IDE session and HTTP controller for live agent takeover. ``controller.json`` under ``evidence`` names the port once the IDE is ready; a stale copy from an earlier run is removed first, so a waiting ``ctl`` never dials a dead port. + A caller may supply scenario-specific needs and consents through ``surface``. + The interactive phase has an overall deadline, including time between commands. """ from playwright.sync_api import sync_playwright # type: ignore[import-not-found,unused-ignore] evidence.mkdir(parents=True, exist_ok=True) (evidence / "controller.json").unlink(missing_ok=True) os.environ["DEVCAPSULE_SMOKE_COMPONENT_BROWSER"] = "1" - surface: IdeSurface = next(s for s in SURFACES if s.name == spec.surface) + surface = surface or next(s for s in SURFACES if s.name == spec.surface) + if surface.name != spec.surface: + raise DriverError("Scenario and launch surface must agree") recorder = BurstFrameRecorder(evidence / "video-frames") action_log: list[dict[str, Any]] = [] step_counter = 0 @@ -714,8 +721,11 @@ def serve_interactive_controller( print(f"CONTROLLER_READY port={port} project_path={session.project_path}", flush=True) stopped = False + deadline = time.monotonic() + timeout try: while not stopped: + if time.monotonic() >= deadline: + raise DriverError("Interactive scenario deadline expired") item = queue.take() if item is None: time.sleep(0.05) diff --git a/devcapsule-src/tests/e2e/scripts/github-ssh-proxy.md b/devcapsule-src/tests/e2e/scripts/github-ssh-proxy.md new file mode 100644 index 00000000..33a103dc --- /dev/null +++ b/devcapsule-src/tests/e2e/scripts/github-ssh-proxy.md @@ -0,0 +1,50 @@ +# E2E Scenario Script: GitHub SSH through the host proxy + +This script presents the recorded interactive run `20261116T103152Z-af7fa02c`. +It is not a replay definition. The recording procedure and presentation producer +are indexed in the GitHub authentication workstream's status file. + +## Goal + +Use the host's existing GitHub SSH identity inside a fresh capsule without copying its private key or forwarding an SSH agent. See both successful Git access and the refusal when the proxy socket is unavailable. + +## Stack And Capabilities + +- **Editor:** VSCodium in a fresh DevCapsule on rootless Linux Docker. +- **Authentication:** The outside launcher owns the GitHub SSH proxy; host OpenSSH uses the host's identity. +- **Permission:** The launcher has explicit `github-ssh` authorization. Host trust and noninteractive GitHub authentication are already configured. +- **Recording:** The merged development PEX runs in both parent and child. The browser-automation component records the actual terminal. + +## What It Illustrates + +- Git over SSH can use the host identity while the private key stays on the host. +- The fresh child has zero SSH files and no SSH agent. +- A public repository's SSH URL still requires GitHub authentication. +- Removing the proxy socket from one command makes access fail; ordinary access still works afterward. +- Independent checks verify the checkout, runtime checksum, socket mount and cleanup. + +## Steps + +1. **Open a terminal in the fresh capsule.** + - *User action:* Open VSCodium's terminal, trust the test-owned workspace and enlarge the terminal for readability. + - *Expected observation:* A terminal opens in the new workspace. This is a disposable child capsule, with GitHub access granted by the outside launcher. + +2. **Check the authentication boundary.** + - *User action:* Count files in `~/.ssh`, inspect `SSH_AUTH_SOCK`, and check that `DEVCAPSULE_GITHUB_SOCKET` names a socket. + - *Expected observation:* The capsule reports zero SSH files, no agent and a connected host GitHub proxy. + +3. **Clone from GitHub over SSH.** + - *User action:* Clone `git@github.com:mycodespace-ai/devcapsule.git`, then inspect the origin, latest commit and working tree. + - *Expected observation:* The clone completes, the origin uses SSH, the recorded commit is `1942f39`, and the working tree is clean. + +4. **Try the same access without the proxy.** + - *User action:* Run a GitHub read with `DEVCAPSULE_GITHUB_SOCKET` pointing to an absent socket, for that command only. + - *Expected observation:* Git reports that it cannot read the remote repository. The independently checked exit code is 128. + +5. **Use the normal proxy again.** + - *User action:* Display the previous exit code, then run `git ls-remote` without the socket override. + - *Expected observation:* The failure code is 128. The normal read returns the GitHub HEAD and exits successfully; no credentials or configuration were repaired. + +6. **Review the observed result.** + - *User action:* Summarize the actual exit codes, SSH file count, origin and cloned commit in the terminal. + - *Expected observation:* Clone and authenticated read passed without copied keys or an agent, while access without the proxy was refused. Independent checks also passed, and the test-owned capsule and workspace were removed after recording. diff --git a/devcapsule-src/tests/integration/test_github_proxy.py b/devcapsule-src/tests/integration/test_github_proxy.py new file mode 100644 index 00000000..ed7dd727 --- /dev/null +++ b/devcapsule-src/tests/integration/test_github_proxy.py @@ -0,0 +1,325 @@ +"""GitHub proxy process and socket integration; no GitHub account or network is used. + +A fixture SSH executable stands in for the remote SSH service. Git itself and +its upload/receive services are real, as are the proxy, pipes and command line. +""" +from __future__ import annotations + +from contextlib import contextmanager +import os +from pathlib import Path +import selectors +import shlex +import shutil +import socket +import stat +import struct +import subprocess +import sys +import tempfile +import time +from collections.abc import Iterator +from typing import IO + +import pytest + +from devcapsule.github_proxy import GitHubBroker, MAX_REQUEST, SOCKET_ENV + +pytestmark = pytest.mark.integration +SOURCE = Path(__file__).resolve().parents[2] + + +def _environment(root: Path) -> dict[str, str]: + return {'PATH': os.defpath, 'HOME': str(root), 'PYTHONPATH': str(SOURCE), + 'DEVCAPSULE_CONFIG_HOME': str(root / 'config'), 'GIT_CONFIG_NOSYSTEM': '1', + 'GIT_CONFIG_GLOBAL': '/dev/null', 'GIT_AUTHOR_NAME': 'Proxy test', + 'GIT_COMMITTER_NAME': 'Proxy test', 'GIT_AUTHOR_EMAIL': 'test@example.test', + 'GIT_COMMITTER_EMAIL': 'test@example.test', 'GIT_TERMINAL_PROMPT': '0'} + + +def _program(root: Path, body: str) -> Path: + path = root / 'ssh-fixture' + path.write_text(f'#!{sys.executable}\n' + body) + path.chmod(0o700) + return path + + +@contextmanager +def _broker(root: Path, body: str, **kwargs: float) -> Iterator[tuple[Path, dict[str, str]]]: + env = _environment(root) + # A short explicit socket path works under either Unix sockaddr path limit. + with tempfile.TemporaryDirectory(prefix='gh-test-', dir='/tmp') as temporary: + path = Path(temporary) / 's' + with GitHubBroker(path, ssh=str(_program(root, body)), environment=env, **kwargs): + yield path, env + assert not path.exists() + + +def _client(path: Path, env: dict[str, str], payload: bytes = b'') -> subprocess.CompletedProcess[bytes]: + return subprocess.run([sys.executable, '-m', 'devcapsule', 'github-ssh', '--', + 'git@github.com', "git-upload-pack 'acme/repo.git'"], + env={**env, SOCKET_ENV: str(path)}, input=payload, + capture_output=True, timeout=15) + + +def test_binary_streams_and_nonzero_exit_are_preserved(tmp_path: Path) -> None: + """Large binary input, stdout, stderr and failure status survive the proxy without mixing.""" + payload = bytes(range(256)) * 2048 + program = "import sys\ndata = sys.stdin.buffer.read()\nsys.stdout.buffer.write(data)\nsys.stderr.buffer.write(b'diagnostic\\n')\nsys.exit(7)\n" + with _broker(tmp_path, program) as (path, env): + result = _client(path, env, payload) + assert result.returncode == 7 + assert result.stdout == payload + assert result.stderr == b'diagnostic\n' + + +def test_real_git_clone_fetch_and_push_through_capsule_adapter(tmp_path: Path) -> None: + """Real Git clone, fetch and push transfer repository objects through the broker.""" + env = _environment(tmp_path) + bare = tmp_path / 'remote.git' + git_bin = shutil.which('git') + assert git_bin is not None + subprocess.run([git_bin, 'init', '--bare', '--initial-branch=main', str(bare)], env=env, check=True, capture_output=True) + # This stand-in uses only the validated service; the repository is fixed by the fixture. + program = f"import os, shlex, sys\nservice = shlex.split(sys.argv[-1])[0]\nos.execv({git_bin!r}, ['git', service.removeprefix('git-'), {str(bare)!r}])\n" + with _broker(tmp_path, program) as (path, _): + git_env = {**env, SOCKET_ENV: str(path), 'GIT_SSH_VARIANT': 'ssh', + 'GIT_SSH_COMMAND': shlex.join([sys.executable, '-m', 'devcapsule', 'github-ssh', '--'])} + clone = tmp_path / 'clone' + def git(*args: str) -> subprocess.CompletedProcess[bytes]: + return subprocess.run(['git', *args], env=git_env, capture_output=True, check=True, timeout=20) + git('-c', 'init.defaultBranch=main', 'clone', 'git@github.com:acme/repo.git', str(clone)) + (clone / 'binary').write_bytes(bytes(range(256)) * 1024) + git('-C', str(clone), 'add', 'binary') + git('-C', str(clone), 'commit', '-m', 'Fixture commit') + git('-C', str(clone), 'push', 'origin', 'main') + second = tmp_path / 'second' + git('clone', 'ssh://git@github.com/acme/repo.git', str(second)) + git('-C', str(second), 'fetch', 'origin') + assert (second / 'binary').read_bytes() == (clone / 'binary').read_bytes() + assert git('--git-dir', str(bare), 'rev-parse', 'main').stdout == git('-C', str(clone), 'rev-parse', 'HEAD').stdout + + +@pytest.mark.parametrize('payload', [b'{"version":1,"service":"sh","repository":"acme/repo"}', + b'{"version":1,"service":"git-upload-pack","repository":"a/b; id"}', + b'{' ]) +def test_invalid_requests_never_start_host_ssh(tmp_path: Path, payload: bytes) -> None: + """Host admission refuses hostile wire bytes even when the capsule adapter is bypassed.""" + marker = tmp_path / 'started' + with _broker(tmp_path, f"from pathlib import Path\nPath({str(marker)!r}).touch()\n") as (path, _): + with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection: + connection.settimeout(2) + connection.connect(str(path)) + connection.sendall(struct.pack('!I', len(payload)) + payload) + assert connection.recv(1) == b'' + assert not marker.exists() + + +def test_oversized_handshake_is_refused_without_reading_body(tmp_path: Path) -> None: + """An excessive length prefix cannot allocate a body or spawn SSH.""" + with _broker(tmp_path, 'raise AssertionError("must not execute")\n') as (path, _): + with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection: + connection.settimeout(2) + connection.connect(str(path)) + connection.sendall(struct.pack('!I', MAX_REQUEST + 1)) + assert connection.recv(1) == b'' + + +def _process_running(pid: int) -> bool: + try: + os.kill(pid, 0) + except ProcessLookupError: + return False + # An orphaned grandchild cannot be waitpid'd by the broker and stays a + # zombie until PID 1 reaps it; treat 'Z' as terminated, not running. + try: + status = Path(f'/proc/{pid}/status').read_text(encoding='utf-8') + except OSError: + return False + for line in status.splitlines(): + if line.startswith('State:') and line.split(':', 1)[1].lstrip().startswith('Z'): + return False + return True + + +def _wait_pids_stopped(pids: list[int], timeout: float = 2.0) -> None: + deadline = time.monotonic() + timeout + remaining = list(pids) + while remaining and time.monotonic() < deadline: + remaining = [pid for pid in remaining if _process_running(pid)] + if remaining: + time.sleep(0.02) + assert not remaining, f"Processes still running after cleanup: {remaining}" + + +def _read_ready_line(stream: IO[bytes], expected: bytes, timeout: float = 5.0) -> None: + fd = stream.fileno() + received = bytearray() + deadline = time.monotonic() + timeout + with selectors.DefaultSelector() as selector: + selector.register(fd, selectors.EVENT_READ) + while len(received) < len(expected): + remaining = deadline - time.monotonic() + if remaining <= 0 or not selector.select(remaining): + raise TimeoutError( + f"Timed out waiting {timeout}s for ready signal {expected!r}; received {bytes(received)!r}" + ) + chunk = os.read(fd, len(expected) - len(received)) + if not chunk: + break + received.extend(chunk) + assert bytes(received) == expected + + +def test_operation_deadline_stops_a_stalled_ssh_process(tmp_path: Path) -> None: + """A stalled host SSH process and its descendant are terminated within the deadline (assumes fixture startup completes within 0.5s).""" + pid_file = tmp_path / 'pids' + program = ( + "import os, subprocess, sys, time\n" + "from pathlib import Path\n" + "grandchild = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)'])\n" + f"Path({str(pid_file)!r}).write_text(f'{{os.getpid()}}\\n{{grandchild.pid}}\\n')\n" + "time.sleep(60)\n" + ) + with _broker(tmp_path, program, operation_timeout=0.5) as (path, env): + result = _client(path, env) + assert result.returncode != 0 + assert b'connection ended' in result.stderr + assert pid_file.exists(), "Fixture did not finish recording PIDs before the 0.5s operation deadline." + pids = [int(line) for line in pid_file.read_text().splitlines() if line] + assert len(pids) == 2 + _wait_pids_stopped(pids) + + +def test_broker_shutdown_cancels_active_ssh_process_group(tmp_path: Path) -> None: + """Closing the broker terminates an active host SSH transfer so no process in its group remains running.""" + started = tmp_path / 'started' + program = ( + "import os, subprocess, sys, time\n" + "from pathlib import Path\n" + "grandchild = subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)'])\n" + f"Path({str(started)!r}).write_text(f'{{os.getpid()}}\\n{{grandchild.pid}}\\n')\n" + "sys.stdout.buffer.write(b'ready\\n')\n" + "sys.stdout.buffer.flush()\n" + "time.sleep(60)\n" + ) + client: subprocess.Popen[bytes] | None = None + try: + with _broker(tmp_path, program, operation_timeout=30) as (path, env): + assert stat.S_IMODE(path.stat().st_mode) == 0o600 + client = subprocess.Popen( + [sys.executable, '-m', 'devcapsule', 'github-ssh', '--', + 'git@github.com', "git-upload-pack 'acme/repo.git'"], + env={**env, SOCKET_ENV: str(path)}, + stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, + ) + assert client.stdout is not None + _read_ready_line(client.stdout, b'ready\n', timeout=5.0) + returncode = client.wait(timeout=5) + client.communicate(timeout=5) + assert returncode != 0 + finally: + if client is not None: + if client.poll() is None: + client.kill() + client.communicate(timeout=5) + for pipe in (client.stdin, client.stdout, client.stderr): + if pipe is not None and not pipe.closed: + pipe.close() + pids = [int(line) for line in started.read_text().splitlines() if line] + assert len(pids) == 2 + _wait_pids_stopped(pids) + + +def test_capsule_adapter_refuses_when_proxy_is_not_authorized(tmp_path: Path) -> None: + """Without an authorized proxy socket in the environment, GitHub SSH fails rather than running SSH.""" + result = subprocess.run( + [sys.executable, '-m', 'devcapsule', 'github-ssh', '--', + 'git@github.com', "git-upload-pack 'acme/repo.git'"], + env=_environment(tmp_path), + input=b'', capture_output=True, timeout=15, + ) + assert result.returncode != 0 + assert b'No authorized GitHub proxy' in result.stderr + + +def test_capsule_adapter_falls_back_to_capsule_ssh_for_other_hosts(tmp_path: Path) -> None: + """Non-GitHub destinations execute the capsule's own ssh binary without touching the proxy.""" + bin_dir = tmp_path / 'bin' + bin_dir.mkdir() + ssh_stub = bin_dir / 'ssh' + args_file = tmp_path / 'ssh_args' + ssh_stub.write_text( + f"#!{sys.executable}\n" + "import json, sys\n" + "from pathlib import Path\n" + f"Path({str(args_file)!r}).write_text(json.dumps(sys.argv[1:]))\n" + "sys.exit(4)\n" + ) + ssh_stub.chmod(0o700) + env = _environment(tmp_path) + env['PATH'] = f"{bin_dir}:{env['PATH']}" + result = subprocess.run( + [sys.executable, '-m', 'devcapsule', 'github-ssh', '--', + '-p', '2222', 'git@example.test', "git-upload-pack 'acme/repo.git'"], + env=env, input=b'', capture_output=True, timeout=15, + ) + assert result.returncode == 4 + assert args_file.read_text() == '["-p", "2222", "git@example.test", "git-upload-pack \'acme/repo.git\'"]' + + +def test_broker_shutdown_closes_incomplete_requests(tmp_path: Path) -> None: + """Stopping the launcher interrupts a client that never completed its handshake.""" + with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection: + connection.settimeout(2) + with _broker(tmp_path, 'raise AssertionError("must not execute")\n') as (path, _): + connection.connect(str(path)) + connection.sendall(b'\x00') + try: + assert connection.recv(1) == b'' + except ConnectionResetError: + pass # Closing with unread input may report reset instead of EOF. + + +@pytest.mark.parametrize('enabled', [False, True]) +@pytest.mark.parametrize('rootless', [False, True]) +def test_launcher_exposes_the_socket_only_with_the_grant(tmp_path: Path, enabled: bool, rootless: bool) -> None: + """Rootless and rootful plans carry the adapter/socket only with authorization and use the corresponding identity.""" + from devcapsule.launch.pycharm._launcher import PycharmRunOptions, DockerMode, TempRuntimeFiles, build_run_config, build_docker_args + from devcapsule.platforms import Platform + from devcapsule.github_proxy import GIT_SSH_COMMAND, SOCKET_DESTINATION + + project = tmp_path / 'project' + project.mkdir() + with _broker(tmp_path, 'raise AssertionError("no transfer expected")\n') as (path, env): + env = {**env, 'DISPLAY': ':1', 'PYCHARM_GIT_IDENTITY_FROM_HOST': '0', SOCKET_ENV: str(path)} + config = build_run_config(PycharmRunOptions(project=project, capsule_platform=Platform.LINUX_AMD64, + docker_mode=DockerMode.none, enable_sudo=False, network_mode='bridge', + enable_github_ssh=enabled, rootless_docker=rootless), env) + files = TempRuntimeFiles(xauth_file=tmp_path / 'xauth', passwd_file=tmp_path / 'passwd', group_file=tmp_path / 'group') + args = build_docker_args(config, files, env) + assert (f'GIT_SSH_COMMAND={GIT_SSH_COMMAND}' in args) is enabled + assert (f'{SOCKET_ENV}={SOCKET_DESTINATION}' in args) is enabled + assert (f'type=bind,src={path},dst={SOCKET_DESTINATION},ro' in args) is enabled + assert args[args.index('--user') + 1] == ('0:0' if rootless else f'{os.getuid()}:{os.getgid()}') + assert not any('.ssh' in arg or 'SSH_AUTH_SOCK=' in arg for arg in args) + + +def test_launcher_rejects_environment_conflicts_with_github_ssh(tmp_path: Path) -> None: + """Additional environment cannot override GitHub SSH transport variables when enabled.""" + from devcapsule.launch.pycharm._launcher import PycharmRunError, PycharmRunOptions, DockerMode, build_run_config + from devcapsule.platforms import Platform + + project = tmp_path / 'project' + project.mkdir() + with _broker(tmp_path, 'raise AssertionError("no transfer expected")\n') as (path, env): + env = {**env, 'DISPLAY': ':1', 'PYCHARM_GIT_IDENTITY_FROM_HOST': '0', SOCKET_ENV: str(path)} + with pytest.raises(PycharmRunError, match="GitHub SSH"): + build_run_config( + PycharmRunOptions( + project=project, capsule_platform=Platform.LINUX_AMD64, + docker_mode=DockerMode.none, enable_sudo=False, network_mode='bridge', + enable_github_ssh=True, additional_environment={'GIT_SSH_COMMAND': 'ssh'}, + ), + env, + ) diff --git a/devcapsule-src/tests/integration/test_pex_runtime.py b/devcapsule-src/tests/integration/test_pex_runtime.py index 78f4b45e..10e64d5d 100644 --- a/devcapsule-src/tests/integration/test_pex_runtime.py +++ b/devcapsule-src/tests/integration/test_pex_runtime.py @@ -288,3 +288,44 @@ def invoke(*arguments: str) -> subprocess.CompletedProcess[str]: saved = invoke("run", "--ide", "codium", "--force", "--save", "--print-command") assert saved.returncode == 2 and "cannot be combined with --save" in saved.stderr assert {path: path.read_bytes() for path in before} == before, "no refusal writes anything" + + +def test_built_pex_exports_standalone_presentation_tools( + built_pex: Path, tmp_path: Path, environment: dict[str, str], +) -> None: + """The built executable prints the guide and exports a standalone ``presentation_tools`` kit.""" + guide = subprocess.run( + [str(built_pex), "presentations", "guide"], + cwd=tmp_path, env=environment, text=True, capture_output=True, check=False, + ) + assert guide.returncode == 0, guide.stderr + assert "# Run an E2E scenario with recording and presentation" in guide.stdout + + kit = tmp_path / "exported-kit" + exported = subprocess.run( + [str(built_pex), "presentations", "export", str(kit)], + cwd=tmp_path, env=environment, text=True, capture_output=True, check=False, + ) + assert exported.returncode == 0, exported.stderr + package = kit / "presentation_tools" + assert (package / "README.md").read_text(encoding="utf-8") + "\n" == guide.stdout + assert {path.name for path in package.iterdir()} == { + "__init__.py", "README.md", "example.py", "producer.py", "recording.py", + } + + isolated = subprocess.run( + [ + sys.executable, "-I", "-c", + ( + "import sys; sys.path.insert(0, sys.argv[1]); " + "from presentation_tools.producer import Script, ScriptStep; " + "from presentation_tools.recording import Recording; " + "import presentation_tools.example; " + "assert 'devcapsule' not in sys.modules and 'tests' not in sys.modules" + ), + str(kit), + ], + cwd=tmp_path, env={"PATH": os.defpath, "PYTHONDONTWRITEBYTECODE": "1"}, + text=True, capture_output=True, check=False, + ) + assert isolated.returncode == 0, isolated.stderr diff --git a/devcapsule-src/tests/integration/test_presentations_cli.py b/devcapsule-src/tests/integration/test_presentations_cli.py new file mode 100644 index 00000000..db382efe --- /dev/null +++ b/devcapsule-src/tests/integration/test_presentations_cli.py @@ -0,0 +1,107 @@ +"""Integration tests of ``devcapsule presentations``: real CLI subprocesses with explicit environments.""" +from __future__ import annotations + +import os +from pathlib import Path +import subprocess +import sys + +import pytest + +pytestmark = pytest.mark.integration + + +def _run_presentations( + tmp_path: Path, *arguments: str, extra_env: dict[str, str] | None = None, +) -> subprocess.CompletedProcess[str]: + environment = { + "PATH": os.defpath, + "PYTHONDONTWRITEBYTECODE": "1", + "HOME": str(tmp_path / "home"), + "DEVCAPSULE_CONFIG_HOME": str(tmp_path / "config"), + } + if extra_env: + environment.update(extra_env) + return subprocess.run( + [sys.executable, "-m", "devcapsule", "presentations", *arguments], + cwd=tmp_path, env=environment, capture_output=True, text=True, timeout=120, check=False, + ) + + +def test_guide_and_export_supply_an_importable_standalone_kit(tmp_path: Path) -> None: + """``presentations guide`` and ``export`` deliver the guide and a stdlib-only kit, refusing overwrites.""" + guide = _run_presentations(tmp_path, "guide") + assert guide.returncode == 0, guide.stderr + assert "# Run an E2E scenario with recording and presentation" in guide.stdout + + kit = tmp_path / "kit" + exported = _run_presentations(tmp_path, "export", str(kit)) + assert exported.returncode == 0, exported.stderr + assert f"Presentation tools: {kit / 'presentation_tools'}" in exported.stdout + assert (kit / "presentation_tools" / "README.md").read_text(encoding="utf-8") + "\n" == guide.stdout + + isolated = subprocess.run( + [ + sys.executable, "-I", "-c", + ( + "import sys; sys.path.insert(0, sys.argv[1]); " + "from presentation_tools.producer import Script; " + "from presentation_tools.recording import Recording; " + "import presentation_tools.example; " + "assert 'devcapsule' not in sys.modules and 'tests' not in sys.modules" + ), + str(kit), + ], + cwd=tmp_path, env={"PATH": os.defpath, "PYTHONDONTWRITEBYTECODE": "1"}, + capture_output=True, text=True, timeout=120, check=False, + ) + assert isolated.returncode == 0, isolated.stderr + + refused = _run_presentations(tmp_path, "export", str(kit)) + assert refused.returncode == 2 + assert "cannot export presentation tools" in refused.stderr + + +def test_hand_off_reads_environment_and_handles_token_states(tmp_path: Path) -> None: + """``presentations hand-off`` prints a tokenized link, falls back cleanly on missing or non-UTF-8 tokens, and refuses missing decks or origins.""" + project = tmp_path / "project" + evidence = project / "evidence" / "run-001" + evidence.mkdir(parents=True) + (evidence / "presentation.json").write_text("{}", encoding="utf-8") + token_file = tmp_path / "console-token" + token_file.write_text("secret-token\n", encoding="utf-8") + + with_token = _run_presentations( + tmp_path, "hand-off", str(evidence), + extra_env={ + "PROJECT_PATH": str(project), + "DEVCAPSULE_CONSOLE_URL": "http://127.0.0.1:8787", + "DEVCAPSULE_CONSOLE_TOKEN_FILE": str(token_file), + }, + ) + assert with_token.returncode == 0, with_token.stderr + assert with_token.stdout.strip() == "http://127.0.0.1:8787/presentations/evidence/run-001?token=secret-token" + + token_file.write_bytes(b"\xff\xfe\xfd") + corrupt_token = _run_presentations( + tmp_path, "hand-off", str(evidence), + "--project", str(project), "--console-url", "http://127.0.0.1:8787", "--token-file", str(token_file), + ) + assert corrupt_token.returncode == 0, corrupt_token.stderr + assert "no readable run token was found" in corrupt_token.stdout + assert corrupt_token.stdout.splitlines()[-1] == "http://127.0.0.1:8787/presentations/evidence/run-001" + + missing_url = _run_presentations( + tmp_path, "hand-off", str(evidence), "--project", str(project), "--token-file", str(tmp_path / "absent"), + ) + assert missing_url.returncode == 2 + assert "HTTP(S) console URL" in missing_url.stderr + + empty_dir = project / "evidence" / "empty" + empty_dir.mkdir(parents=True) + missing_deck = _run_presentations( + tmp_path, "hand-off", str(empty_dir), + "--project", str(project), "--console-url", "http://127.0.0.1:8787", + ) + assert missing_deck.returncode == 2 + assert "no presentation.json" in missing_deck.stderr diff --git a/devcapsule-src/tests/integration/test_print_command_cli.py b/devcapsule-src/tests/integration/test_print_command_cli.py index d9594995..eb983097 100644 --- a/devcapsule-src/tests/integration/test_print_command_cli.py +++ b/devcapsule-src/tests/integration/test_print_command_cli.py @@ -3,8 +3,8 @@ Printing a launch's command brings nothing to the machine. Each test runs the built executable in an environment it builds: a home and a project under the test's directory, and a search path whose ``docker`` is a script the test -writes. The script records every call, answers that no image is local, and -refuses any other request, so a launcher that asked Docker to pull or build +writes. The script records every call, answers read-only daemon identity +and local-image queries, and refuses any other request, so a launcher that asked Docker to pull or build would be seen and would fail. The proxy variables send every download to a closed port of this machine: a launcher that tried one would fail at once and receive nothing. @@ -21,8 +21,12 @@ pytestmark = pytest.mark.integration STAND_IN_DOCKER = """#!/bin/sh -# Stands where docker is. Every call is recorded; only a question about a local image is answered. +# Stands where docker is. Only read-only daemon identity and local-image queries are answered. echo "$*" >> "$DOCKER_STAND_IN_CALLS" +if [ "$*" = 'info --format {{json .SecurityOptions}}' ]; then + echo '[]' + exit 0 +fi if [ "$1 $2" = "image inspect" ]; then echo "[]" echo "Error response from daemon: No such image: $3" >&2 @@ -66,7 +70,7 @@ def run(*arguments: str) -> subprocess.CompletedProcess[str]: def test_print_command_names_a_base_image_that_is_not_here_and_pulls_nothing(launcher, tmp_path: Path) -> None: """On a machine whose Docker has no image, ``run --print-command`` exits 2 and says that a launch pulls the - base image. It asks Docker only whether the image is local, prints no command, and downloads no file.""" + base image. It may read daemon security options and local image availability, prints no command, and downloads no file.""" created = launcher("init", "--require", "python", "--ide", "python-ide", "--creator", "mailto:owner@example.test", "--authorize", "base-image", "default") assert created.returncode == 0, created.stderr @@ -78,7 +82,11 @@ def test_print_command_names_a_base_image_that_is_not_here_and_pulls_nothing(lau assert "is not on this machine. A launch pulls it; nothing was pulled now." in printed.stderr assert "--print-command prints the command of an environment that is already here" in printed.stderr calls = (tmp_path / "docker-calls").read_text(encoding="utf-8").splitlines() - assert calls and all(call.startswith("image inspect ") for call in calls), calls + assert any(call.startswith("image inspect ") for call in calls), calls + assert all( + call.startswith("image inspect ") or call == "info --format {{json .SecurityOptions}}" + for call in calls + ), calls downloaded = [path for path in (tmp_path / "home").rglob("*") if path.is_file() and "artifacts" in path.parts] assert downloaded == [] diff --git a/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py b/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py index 7a090e14..1c7d6d65 100644 --- a/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py +++ b/devcapsule-src/tests/integration/test_runtime_entrypoint_cli.py @@ -246,6 +246,16 @@ def test_filesystem_applies_distinct_user_and_group_ids_to_new_directories(tmp_p gid = groups[0] else: pytest.skip("distinct uid/gid ownership needs root or a supplementary group different from the uid") + # A root UID in a restricted user namespace need not have CAP_CHOWN. + # Establish the host precondition independently of prepare_filesystem. + probe = tmp_path / "ownership-precondition" + probe.touch() + try: + os.chown(probe, uid, gid) + except PermissionError: + pytest.skip("this environment cannot assign the distinct uid/gid required by the test") + finally: + probe.unlink() existing = tmp_path.stat() program = """ import sys diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py index d5178e97..c4b2b4c7 100644 --- a/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_authorization.py @@ -71,6 +71,12 @@ def test_a_lock_without_a_base_declares_no_base_image_decision() -> None: assert "base-image" not in authorization_declarations({}, {"components": {}}) +def test_github_access_is_available_but_never_recommended_by_omission() -> None: + """A project without recommendations exposes the optional GitHub decision without granting it.""" + declaration = authorization_declarations({}, {"components": {}})['github-ssh'] + assert declaration.recommended_value is True + assert declaration.project_recommended is False + assert declaration.required is False def _lock_with_claude_code() -> dict[str, Any]: """A platform lock that pins Claude Code, downloaded from its vendor, on the base at ``REFERENCE``.""" lock = _lock() diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py index bc18b50f..fe509ca6 100644 --- a/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_derivation.py @@ -171,4 +171,3 @@ def test_selecting_another_ide_forgets_the_provider_chosen_for_the_one_it_replac selection.ide = "python-ide" assert selection.local() == LocalCapabilities(("claude-code-agent", "python-ide")) - diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_nodes.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_nodes.py new file mode 100644 index 00000000..33ba049e --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_nodes.py @@ -0,0 +1,166 @@ +"""The node registry is built from values and gives every input one address.""" +from typing import Any + +import pytest + +from devcapsule.configuration.nodes import ( + CARRIER_FAMILY_AUTHORIZE, CARRIER_FAMILY_BIND, CARRIER_FAMILY_SET, + PROVIDER_HOST_DIRECTORY, PROVIDER_HOST_ENVIRONMENT, build_node_registry, +) +from devcapsule.configuration.file_formats import ProjectConfigurationError + +def example_manifest() -> dict[str, Any]: + return { + "devcapsule-schema-version": 1, + "capabilities": {"need": ["python", "python-ide", "codex-agent"]}, + "project": { + "name": "Example", + "slug": "example", + "creator": "https://github.com/example", + "mount": "/workspace/example", + }, + "configuration": { + "values": { + "runtime.memory-limit": { + "type": "memory-size", + "runtime-effect": "docker.memory-limit", + "description": "Hard memory limit for the project container.", + } + } + }, + "host": { + "docker": { + "mode": { + "recommended": { + "value": "host-socket", + "justification": "Required for the full test suite.", + } + } + } + }, + } + + +def example_lock() -> dict[str, Any]: + return { + "devcapsule-lock-format-version": 1, + "platform": "linux-amd64", + "base": { + "reference": "docker.io/mycodespaceai/devcapsule-base@sha256:" + "6" * 64, + }, + "components": { + "interactive-surface": "pycharm", + "pycharm": { + "version": "2026.2.0.1", + "variant": "professional", + "delivery-policy": "local-materialization", + "url": "https://example.test/pycharm.tar.gz", + "sha256": "a" * 64, + }, + "codex": { + "version": "0.145.0", + "delivery-policy": "local-materialization", + }, + }, + } + + + +@pytest.mark.parametrize('name,family,required', [ + ('runtime.memory-limit', CARRIER_FAMILY_SET, False), + ('home', CARRIER_FAMILY_BIND, False), + ('pycharm/system', CARRIER_FAMILY_BIND, False), + ('codex/openai-api-key', CARRIER_FAMILY_BIND, False), + ('base-image', CARRIER_FAMILY_AUTHORIZE, True), + ('docker-daemon', CARRIER_FAMILY_AUTHORIZE, False), + ('github-ssh', CARRIER_FAMILY_AUTHORIZE, False), +]) +def test_each_declaration_has_its_carrier(name: str, family: str, required: bool) -> None: + """The registry maps each declared value, binding and authorization to its input family.""" + registry = build_node_registry(example_manifest(), example_lock()) + node = registry.node(name) + assert node.family == family + assert node.required is required + + +def test_registry_names_are_sorted() -> None: + """The registry presents deterministic sorted names independent of declaration order.""" + registry = build_node_registry(example_manifest(), example_lock()) + names = registry.names() + assert names == tuple(sorted(names)) + + +def test_authorization_family_includes_optional_github_access() -> None: + """The authorization family contains every default host boundary and the locked base.""" + registry = build_node_registry(example_manifest(), example_lock()) + nodes = registry.family(CARRIER_FAMILY_AUTHORIZE) + assert {node.name for node in nodes} == { + 'base-image', 'docker-daemon', 'network', 'development-sudo', 'host-browser', 'host-x11', 'github-ssh', + } + + +@pytest.mark.parametrize('name,providers', [('home', (PROVIDER_HOST_DIRECTORY,)), + ('codex/openai-api-key', (PROVIDER_HOST_ENVIRONMENT,))]) +def test_binding_declaration_exposes_its_allowed_providers(name: str, providers: tuple[str, ...]) -> None: + """A directory binding and an environment secret accept their own providers only.""" + registry = build_node_registry(example_manifest(), example_lock()) + assert registry.node(name).providers == providers + + +def test_base_consent_cannot_be_justified_by_project_advice() -> None: + """The base-image node requires an answer without project-authored justification.""" + registry = build_node_registry(example_manifest(), example_lock()) + assert registry.node('base-image').accepts_justification is False + + +def test_host_recommendation_carries_its_reason() -> None: + """A project recommendation exposes its own justification on the host-access node.""" + registry = build_node_registry(example_manifest(), example_lock()) + node = registry.node('docker-daemon') + assert node.accepts_justification is True + assert node.description == 'Required for the full test suite.' + + +def test_unknown_node_lists_the_declared_vocabulary() -> None: + """Unknown names are refused with the missing name and known vocabulary.""" + registry = build_node_registry(example_manifest(), example_lock()) + with pytest.raises(ProjectConfigurationError) as failure: + registry.node('does-not-exist') + assert "'does-not-exist'" in str(failure.value) + assert 'runtime.memory-limit' in str(failure.value) + + +def test_wrong_carrier_family_names_the_right_spelling() -> None: + """A directory cannot be answered as a scalar; the diagnostic names the proper carrier.""" + registry = build_node_registry(example_manifest(), example_lock()) + with pytest.raises(ProjectConfigurationError, match='answered with --bind, not --set'): + registry.answerable('home', CARRIER_FAMILY_SET) + + +@pytest.mark.parametrize('name,binding,expected', [ + ('home', 'host-directory:/state/x:y', (PROVIDER_HOST_DIRECTORY, '/state/x:y')), + ('codex/openai-api-key', 'host-environment:KEY', (PROVIDER_HOST_ENVIRONMENT, 'KEY')), +]) +def test_bind_values_split_on_the_first_colon_only(name: str, binding: str, expected: tuple[str, str]) -> None: + """Provider parsing retains colons inside a directory value and accepts environment names.""" + registry = build_node_registry(example_manifest(), example_lock()) + assert registry.split_bind_value(name, binding) == expected + + +@pytest.mark.parametrize('name,binding,message', [ + ('codex/openai-api-key', 'host-directory:/somewhere', 'host-environment:VALUE'), + ('home', '/no/provider/prefix', 'host-directory:VALUE'), +]) +def test_bind_value_rejects_wrong_or_missing_provider(name: str, binding: str, message: str) -> None: + """A binding with a missing or incompatible provider is refused with the expected form.""" + registry = build_node_registry(example_manifest(), example_lock()) + with pytest.raises(ProjectConfigurationError, match=message): + registry.split_bind_value(name, binding) + + +def test_a_name_declared_twice_fails_at_construction() -> None: + """A scalar declaration cannot reuse the name of a component binding.""" + manifest = example_manifest() + manifest['configuration']['values']['home'] = {'type': 'string', 'description': 'Collision.'} + with pytest.raises(ProjectConfigurationError, match='declared twice'): + build_node_registry(manifest, example_lock()) diff --git a/devcapsule-src/tests/unit/devcapsule/configuration/test_review.py b/devcapsule-src/tests/unit/devcapsule/configuration/test_review.py new file mode 100644 index 00000000..638d9e26 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/configuration/test_review.py @@ -0,0 +1,20 @@ +"""HostAccess value contracts for the GitHub transport grant.""" +from devcapsule.configuration.review import HostAccess + + +def test_github_access_is_denied_without_an_explicit_answer() -> None: + """Default host access never exposes host GitHub authentication.""" + assert HostAccess().github_ssh is False + + +def test_a_recorded_denial_overrides_an_earlier_grant() -> None: + """Overlaying a denial withdraws GitHub access without changing other host choices.""" + access = HostAccess(github_ssh=True, host_browser=True) + result = access.overlay({'github-ssh': False}) + assert result.github_ssh is False + assert result.host_browser is True + + +def test_a_run_once_answer_enables_github_access() -> None: + """An explicit boolean grant becomes the launcher's effective GitHub access.""" + assert HostAccess().overlay({'github-ssh': True}).github_ssh is True diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py index 81ed6fd9..45e4e6e7 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_filesystem.py @@ -5,6 +5,8 @@ from pathlib import Path import stat +import pytest + from devcapsule.components.pycharm import runtime_template as pycharm_runtime_template from devcapsule.container_runtime.contract import Identity, RuntimePlan from devcapsule.container_runtime.filesystem import ( @@ -93,10 +95,11 @@ def test_create_directories_returns_nothing_when_every_directory_exists(tmp_path assert create_directories(filesystem) == () -def test_prepare_filesystem_creates_the_directories_for_a_caller_that_is_not_root(tmp_path: Path) -> None: - """For a caller that is not root, ``prepare_filesystem`` creates the plan's directories without failing on an owner it may not set.""" +@pytest.mark.parametrize("user", [CapsuleUser(DEVELOPER, caller_uid=1000), CapsuleUser(Identity(0, 0, "root"), caller_uid=0)]) +def test_prepare_filesystem_creates_the_directories_without_an_owner_change(tmp_path: Path, user: CapsuleUser) -> None: + """An unchanged caller identity creates the directories without requiring chown capabilities.""" filesystem = filesystem_under(tmp_path) - prepare_filesystem(filesystem, CapsuleUser(DEVELOPER, caller_uid=1000)) + prepare_filesystem(filesystem, user) assert all(Path(directory).is_dir() for directory in filesystem.directories) diff --git a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py index 4ba2eaa5..19853b97 100644 --- a/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py +++ b/devcapsule-src/tests/unit/devcapsule/container_runtime/test_identity.py @@ -26,7 +26,7 @@ def test_command_leaves_the_command_alone_when_the_caller_is_not_root() -> None: assert PREPARED_BY_THE_USER.command(("ide", "--wait")) == ("ide", "--wait") -@pytest.mark.parametrize("user", [PREPARED_BY_ROOT, PREPARED_BY_THE_USER]) +@pytest.mark.parametrize("user", [PREPARED_BY_ROOT, PREPARED_BY_THE_USER, ROOTLESS_ROOT]) def test_command_refuses_an_empty_command(user: CapsuleUser) -> None: """An empty command raises ``ValueError``, whoever the caller is.""" with pytest.raises(ValueError, match="must not be empty"): @@ -57,3 +57,15 @@ def test_command_does_not_wrap_root_identity_in_gosu() -> None: def test_owner_changes_are_none_when_the_target_identity_is_root() -> None: """When the caller and target identity are both ``0:0``, ``owner_changes`` avoids redundant ``chown`` calls.""" assert ROOTLESS_ROOT.owner_changes((Path("/home/devcapsule/.ssh"),)) == () + + +@pytest.mark.parametrize("uid,gid", [(0, 1001), (1000, 0)]) +def test_root_caller_switches_when_one_target_id_differs(uid: int, gid: int) -> None: + """A target with only one zero ID still requires gosu; only 0:0 bypasses it.""" + user = CapsuleUser(Identity(uid, gid, "developer"), caller_uid=0) + assert user.command(("ide",)) == ("gosu", f"{uid}:{gid}", "ide") + + +def test_non_root_caller_keeps_a_root_target_command() -> None: + """A non-root caller does not try to elevate itself even for a root target.""" + assert CapsuleUser(ROOT, caller_uid=1000).command(("ide",)) == ("ide",) diff --git a/devcapsule-src/tests/unit/devcapsule/launch/pycharm/test_launcher.py b/devcapsule-src/tests/unit/devcapsule/launch/pycharm/test_launcher.py index c8ec86a2..35d7192c 100644 --- a/devcapsule-src/tests/unit/devcapsule/launch/pycharm/test_launcher.py +++ b/devcapsule-src/tests/unit/devcapsule/launch/pycharm/test_launcher.py @@ -1967,4 +1967,3 @@ def test_rootless_sudoers_policy_ownership_accepts_host_user_file_without_chown( assert files.shadow_file.read_text(encoding="utf-8").startswith("root:*:") finally: cleanup_temp_runtime_files(files) - diff --git a/devcapsule-src/tests/unit/tests/e2e/test_scenario_presentation.py b/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_producer.py similarity index 90% rename from devcapsule-src/tests/unit/tests/e2e/test_scenario_presentation.py rename to devcapsule-src/tests/unit/devcapsule/presentation_tools/test_producer.py index f6f5c471..2643f304 100644 --- a/devcapsule-src/tests/unit/tests/e2e/test_scenario_presentation.py +++ b/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_producer.py @@ -1,4 +1,4 @@ -"""Unit tests for ``tests.e2e.scenario_presentation``.""" +"""Unit tests for ``devcapsule.presentation_tools.producer``.""" from __future__ import annotations import json @@ -8,7 +8,7 @@ import pytest -from tests.e2e.scenario_presentation import ( +from devcapsule.presentation_tools.producer import ( PresentationError, Script, ScriptStep, @@ -216,6 +216,24 @@ def test_plan_presentation_refuses_a_scenario_that_does_not_join_its_script(docu plan_presentation(document, SCRIPT) +@pytest.mark.parametrize( + ("bad_script", "message"), + [ + (Script("", (), (), SCRIPT.steps), "the script has no goal"), + (Script("Goal", (), (), ()), "the script has no steps"), + (Script("Goal", (), (), (ScriptStep(" ", "Open", "Visible"),)), "script step 1 has no title"), + (Script("Goal", (), (), (ScriptStep("Open", " ", "Visible"),)), "script step 1 has no action"), + (Script("Goal", (), (), (ScriptStep("Open", "Open", ""),)), "script step 1 has no expected"), + (Script("Goal", (), (" ",), SCRIPT.steps[:1]), "script illustrations must be non-empty texts"), + (Script("Goal", (("Editor", ""),), (), SCRIPT.steps[:1]), "script stack entries must have non-empty name and detail"), + ], +) +def test_plan_presentation_refuses_incomplete_python_script(bad_script: Script, message: str) -> None: + """``plan_presentation`` refuses Python-constructed scripts with missing goal, steps, step fields, stack or illustrations.""" + with pytest.raises(PresentationError, match=re.escape(message)): + plan_presentation(scenario(action("1. One")), bad_script) + + def test_plan_for_scenario_reads_the_named_script_below_the_root(tmp_path: Path) -> None: """A scenario that names its script is planned from the file at that path below the root.""" (tmp_path / "scripts").mkdir() diff --git a/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_recording.py b/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_recording.py new file mode 100644 index 00000000..300e9c6f --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/presentation_tools/test_recording.py @@ -0,0 +1,333 @@ +"""Unit tests for ``devcapsule.presentation_tools.recording``.""" +from __future__ import annotations + +import json +from pathlib import Path +import subprocess +import sys + +import pytest + +from devcapsule.presentation_tools.producer import PresentationError, Script, ScriptStep +from devcapsule.presentation_tools.recording import Recording + +SCRIPT = Script( + goal="Verify the application flow.", + stack=(("Browser", "Chromium"),), + illustrates=("A passing and failing check.",), + steps=( + ScriptStep("Open", "Open the app", "The heading appears"), + ScriptStep("Reload", "Reload the page", "The heading stays"), + ), +) + + +class _StubPage: + """In-memory Playwright page double recording captured bytes and wait calls.""" + + def __init__(self, *, fail_jpeg_at: int | None = None, fail_png_at: int | None = None) -> None: + self.fail_jpeg_at = fail_jpeg_at + self.fail_png_at = fail_png_at + self.jpeg_calls = 0 + self.png_calls = 0 + self.captured_jpeg_bytes = bytearray() + self.waits: list[int] = [] + + def screenshot(self, *, type: str = "png", quality: int | None = None, path: str | None = None) -> bytes: + del quality + if path is None: + self.jpeg_calls += 1 + if self.fail_jpeg_at is not None and self.jpeg_calls >= self.fail_jpeg_at: + raise RuntimeError("page disconnected during frame capture") + assert type == "jpeg" + chunk = f"FRAME-{self.jpeg_calls}:".encode("ascii") + self.captured_jpeg_bytes.extend(chunk) + return chunk + self.png_calls += 1 + if self.fail_png_at is not None and self.png_calls >= self.fail_png_at: + raise RuntimeError("page disconnected during step screenshot") + Path(path).write_bytes(f"PNG-{self.png_calls}".encode("ascii")) + return b"" + + def wait_for_timeout(self, ms: int) -> None: + self.waits.append(ms) + + +def _encoder_command(*, exit_code: int = 0, write_video: bool = True) -> tuple[str, ...]: + program = ( + "import pathlib, sys; " + "data = sys.stdin.buffer.read(); " + "sys.stderr.write(f'bytes={len(data)}\\n'); " + f"pathlib.Path(sys.argv[-1]).write_bytes(b'WEBM:' + data) if {write_video!r} else None; " + f"sys.exit({exit_code})" + ) + return (sys.executable, "-I", "-S", "-c", program) + + +@pytest.mark.parametrize( + ("steps", "ffmpeg"), + [ + ((), ("encoder",)), + ((ScriptStep("Open", "Open the app", "The heading appears"),), ()), + ((ScriptStep("Open", "Open the app", "The heading appears"),), "ffmpeg"), + ], +) +def test_recording_rejects_invalid_setup_before_creating_evidence( + tmp_path: Path, steps: tuple[ScriptStep, ...], ffmpeg: tuple[str, ...] | str, +) -> None: + """An empty script, absent encoder or unsplit string encoder is refused before an evidence folder exists.""" + with pytest.raises(PresentationError): + Recording(tmp_path / "run", script=Script("Goal", (), (), steps), scenario_id="example", + title="Example", summary="Example run", ffmpeg=ffmpeg) + + assert not (tmp_path / "run").exists() + + +def test_recording_preserves_existing_evidence(tmp_path: Path) -> None: + """A recording cannot overwrite a prior attempt, even if that directory is empty.""" + with pytest.raises(FileExistsError): + Recording(tmp_path, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=("encoder",)) + + assert list(tmp_path.iterdir()) == [] + + +def test_recording_finish_writes_aligned_deck_and_media_for_passing_run(tmp_path: Path) -> None: + """Finishing a complete multi-action run encodes captured bytes and aligns chapters to frame boundaries.""" + # Precondition: record a complete two-step run (two actions in step 1, one in step 2). + evidence = tmp_path / "run-pass" + page = _StubPage() + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title=" Example ", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Navigate to page", lambda: None) + recording.action(page, 1, "Confirm heading", lambda: None) + recording.action(page, 2, "Reload page", lambda: None) + + # Action: finalize the recording. + manifest = recording.finish() + + # Postcondition: logs record increasing frame boundaries, deck aligns to them, and encoder gets captured bytes. + result = json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8")) + actions = json.loads((evidence / "action-log.json").read_text(encoding="utf-8")) + boundaries = [entry["frames_after"] for entry in actions] + deck = json.loads(manifest.read_text(encoding="utf-8")) + assert result == {"status": "passed", "error": "", "steps_reached": 2, "steps_planned": 2} + assert len(boundaries) == 3 and 0 < boundaries[0] < boundaries[1] < boundaries[2] + assert deck["title"] == "Example" + assert deck["video"]["file"] == "scenario-video.webm" + assert deck["video"]["poster"] == "poster.png" + assert deck["video"]["duration"] > 0 + step1, step2 = deck["steps"] + assert (step1["screenshot"], step2["screenshot"]) == ("step-002.png", "step-003.png") + assert step1["start"] == 0.0 + assert 0.0 < step1["end"] == step2["start"] < step2["end"] == deck["video"]["duration"] + assert [c["text"] for c in step1["captions"]] == ["Navigate to page", "Confirm heading"] + assert [c["text"] for c in step2["captions"]] == ["Reload page"] + assert step1["captions"][0]["start"] == step1["start"] + assert step1["captions"][0]["end"] == step1["captions"][1]["start"] + assert step1["captions"][1]["end"] == step1["end"] + assert step2["captions"][0]["start"] == step2["start"] and step2["captions"][0]["end"] == step2["end"] + assert (evidence / "poster.png").read_bytes() == (evidence / "step-001.png").read_bytes() + assert (evidence / "scenario-video.webm").read_bytes() == b"WEBM:" + bytes(page.captured_jpeg_bytes) + assert f"bytes={len(page.captured_jpeg_bytes)}\n" in (evidence / "ffmpeg.log").read_text(encoding="utf-8") + + +def test_recording_action_reraises_callback_failure_and_records_failed_state(tmp_path: Path) -> None: + """A failing action callback propagates its exception while preserving failed logs and screenshot.""" + # Precondition: step 1 succeeded. + evidence = tmp_path / "run-fail-action" + page = _StubPage() + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open app", lambda: None) + + def fail_reload() -> None: + raise AssertionError("heading missing") + + # Action: execute a failing callback in step 2. + with pytest.raises(AssertionError, match="heading missing"): + recording.action(page, 2, "Reload app", fail_reload) + + # Postcondition: failure state, action log and failure screenshot are recorded on disk. + result = json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8")) + actions = json.loads((evidence / "action-log.json").read_text(encoding="utf-8")) + assert result == { + "status": "failed", + "error": "AssertionError: heading missing", + "steps_reached": 2, + "steps_planned": 2, + } + assert actions[1]["status"] == "failed" and actions[1]["error"] == "AssertionError: heading missing" + assert (evidence / "step-002.png").is_file() + + +def test_recording_action_refuses_calls_after_failure(tmp_path: Path) -> None: + """Once an action fails, any subsequent action call is refused before capturing frames.""" + # Precondition: step 1 failed. + page = _StubPage() + recording = Recording(tmp_path / "run-after-fail", script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + with pytest.raises(AssertionError): + recording.action(page, 1, "Open app", lambda: (_ for _ in ()).throw(AssertionError("boom"))) + calls_before = page.jpeg_calls + + # Action: attempt another action on the failed recording. + with pytest.raises(PresentationError, match="finished or failed"): + recording.action(page, 2, "Reload app", lambda: None) + + # Postcondition: no further frames were captured. + assert page.jpeg_calls == calls_before + + +def test_recording_finish_writes_failed_deck_for_reached_steps(tmp_path: Path) -> None: + """Finishing a failed run keeps the failed result and labels the presentation FAILED.""" + # Precondition: step 1 passed and step 2 failed with visual evidence intact. + evidence = tmp_path / "run-finish-fail" + page = _StubPage() + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title=" Example ", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open app", lambda: None) + with pytest.raises(AssertionError): + recording.action(page, 2, "Reload app", lambda: (_ for _ in ()).throw(AssertionError("heading missing"))) + + # Action: finalize the failed recording. + manifest = recording.finish() + + # Postcondition: result remains failed and presentation is labelled FAILED for the two reached steps. + result = json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8")) + deck = json.loads(manifest.read_text(encoding="utf-8")) + assert result["status"] == "failed" and result["error"] == "AssertionError: heading missing" + assert deck["title"] == "Example (FAILED)" + assert len(deck["steps"]) == 2 + + +def test_recording_labels_incomplete_run_with_only_reached_steps(tmp_path: Path) -> None: + """Finishing before all script steps run keeps an incomplete status and an INCOMPLETE deck.""" + # Precondition: only step 1 of 2 ran. + evidence = tmp_path / "run-incomplete" + page = _StubPage() + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open app", lambda: None) + + # Action: finalize the partial recording. + manifest = recording.finish() + + # Postcondition: result stays incomplete and deck contains only the reached step. + result = json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8")) + deck = json.loads(manifest.read_text(encoding="utf-8")) + assert result == {"status": "incomplete", "error": "", "steps_reached": 1, "steps_planned": 2} + assert deck["title"] == "Example (INCOMPLETE)" + assert len(deck["steps"]) == 1 + + +@pytest.mark.parametrize(("step", "caption"), [(0, "Open"), (True, "Open"), (2, "Skipped"), (1, " ")]) +def test_recording_refuses_invalid_step_order_or_empty_caption( + tmp_path: Path, step: int | bool, caption: str, +) -> None: + """Out-of-order steps, boolean steps and blank captions are refused before capturing frames.""" + page = _StubPage() + recording = Recording(tmp_path / "run", script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + + with pytest.raises(PresentationError): + recording.action(page, step, caption, lambda: None) + + assert page.jpeg_calls == 0 + + +def test_recording_finish_refuses_second_call(tmp_path: Path) -> None: + """Finishing an already finished recording raises PresentationError.""" + # Precondition: recording is already finished. + page = _StubPage() + recording = Recording(tmp_path / "run", script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open", lambda: None) + recording.finish() + + # Action: call finish a second time. + with pytest.raises(PresentationError, match="already been finished"): + recording.finish() + + +def test_recording_action_refuses_calls_after_finish(tmp_path: Path) -> None: + """Calling action after finish raises PresentationError without capturing frames.""" + # Precondition: recording is already finished. + page = _StubPage() + recording = Recording(tmp_path / "run", script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + recording.action(page, 1, "Open", lambda: None) + recording.finish() + calls_before = page.jpeg_calls + + # Action: attempt another action after finish. + with pytest.raises(PresentationError, match="finished or failed"): + recording.action(page, 2, "Reload", lambda: None) + + assert page.jpeg_calls == calls_before + + +def test_recording_finish_refuses_run_with_no_actions(tmp_path: Path) -> None: + """Finishing with zero actions writes an incomplete result and refuses writing a presentation.""" + evidence = tmp_path / "empty" + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + + with pytest.raises(PresentationError, match="no complete visual evidence"): + recording.finish() + + assert json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8"))["status"] == "incomplete" + assert not (evidence / "presentation.json").exists() + + +def test_recording_finish_refuses_run_with_missing_step_screenshot(tmp_path: Path) -> None: + """Finishing when a failed action could not save a screenshot keeps the failed result and writes no deck.""" + # Precondition: step 1 callback failed and screenshot capture also failed. + evidence = tmp_path / "broken-capture" + page = _StubPage(fail_png_at=1) + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command()) + with pytest.raises(AssertionError, match="original test assertion"): + recording.action(page, 1, "Open", lambda: (_ for _ in ()).throw(AssertionError("original test assertion"))) + + # Action: finalize the recording without complete screenshots. + with pytest.raises(PresentationError, match="no complete visual evidence"): + recording.finish() + + assert json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8"))["status"] == "failed" + assert not (evidence / "presentation.json").exists() + + +def test_recording_finish_preserves_logs_when_encoder_fails(tmp_path: Path) -> None: + """A non-zero encoder exit leaves result and encoder logs intact and writes neither poster nor presentation.""" + # Precondition: step 1 succeeded with an encoder configured to exit 1. + evidence = tmp_path / "encode-fail" + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command(exit_code=1, write_video=False)) + recording.action(_StubPage(), 1, "Open", lambda: None) + + # Action: finalize the recording. + with pytest.raises(subprocess.CalledProcessError): + recording.finish() + + assert json.loads((evidence / "scenario-result.json").read_text(encoding="utf-8"))["status"] == "incomplete" + assert (evidence / "ffmpeg.log").is_file() + assert not (evidence / "presentation.json").exists() + assert not (evidence / "poster.png").exists() + + +def test_recording_finish_withholds_deck_when_encoder_writes_no_video(tmp_path: Path) -> None: + """An encoder that exits zero without writing scenario-video.webm raises PresentationError and writes no deck.""" + # Precondition: step 1 succeeded with an encoder that exits 0 without producing video output. + evidence = tmp_path / "encode-empty" + recording = Recording(evidence, script=SCRIPT, scenario_id="example", title="Example", + summary="Example run", ffmpeg=_encoder_command(exit_code=0, write_video=False)) + recording.action(_StubPage(), 1, "Open", lambda: None) + + # Action: finalize the recording. + with pytest.raises(PresentationError, match="scenario-video.webm"): + recording.finish() + + assert (evidence / "ffmpeg.log").is_file() + assert not (evidence / "presentation.json").exists() + assert not (evidence / "poster.png").exists() diff --git a/devcapsule-src/tests/unit/devcapsule/test_github_proxy.py b/devcapsule-src/tests/unit/devcapsule/test_github_proxy.py new file mode 100644 index 00000000..a38d868d --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/test_github_proxy.py @@ -0,0 +1,42 @@ +"""Unit tests of ``devcapsule.github_proxy``: pure gating decisions of ``github_ssh_bridge``. + +No sockets are bound and no subprocesses start; every outcome follows from the +explicit arguments passed to ``github_ssh_bridge``. +""" +from __future__ import annotations + +from pathlib import Path + +import pytest + +from devcapsule.github_proxy import SOCKET_DESTINATION, SOCKET_ENV, github_ssh_bridge +from devcapsule.github_transport import GitHubTransportError + + +def test_disabled_bridge_yields_none_regardless_of_host_capabilities() -> None: + """When github-ssh is denied, the bridge yields no socket even on unsupported or containerized hosts.""" + with github_ssh_bridge({}, enabled=False, containerized=True, binds_unix_sockets=False) as path: + assert path is None + + +def test_docker_desktop_bridge_is_refused_when_enabled() -> None: + """Enabling github-ssh on a host that cannot bind Unix sockets fails loudly instead of degrading.""" + with pytest.raises(GitHubTransportError, match="Docker Desktop"): + with github_ssh_bridge({}, enabled=True, containerized=False, binds_unix_sockets=False): + pass + + +@pytest.mark.parametrize("environment", [{}, {SOCKET_ENV: "/tmp/forged.sock"}]) +def test_containerized_bridge_requires_an_inherited_canonical_socket(environment: dict[str, str]) -> None: + """An inner capsule cannot enable github-ssh without the launcher's canonical socket variable.""" + assert str(SOCKET_DESTINATION) != "/tmp/forged.sock" + with pytest.raises(GitHubTransportError, match="outside launcher"): + with github_ssh_bridge(environment, enabled=True, containerized=True, binds_unix_sockets=True): + pass + + +def test_host_bridge_requires_openssh_on_path(tmp_path: Path) -> None: + """Enabling github-ssh on the host fails clearly when OpenSSH is absent from an empty PATH directory.""" + with pytest.raises(GitHubTransportError, match="OpenSSH"): + with github_ssh_bridge({"PATH": str(tmp_path)}, enabled=True, containerized=False, binds_unix_sockets=True): + pass diff --git a/devcapsule-src/tests/unit/devcapsule/test_github_transport.py b/devcapsule-src/tests/unit/devcapsule/test_github_transport.py new file mode 100644 index 00000000..30560161 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/test_github_transport.py @@ -0,0 +1,87 @@ +"""Contracts of GitHub request admission, independent of host SSH or credentials.""" +import json + +import pytest + +from devcapsule.github_transport import GitHubRequest, GitHubTransportError, decode_request, parse_git_ssh + + +@pytest.mark.parametrize('arguments,expected', [ + (['-o', 'SendEnv=GIT_PROTOCOL', 'git@github.com', "git-upload-pack 'acme/widgets.git'"], + GitHubRequest('git-upload-pack', 'acme/widgets.git')), + (['-oSendEnv=GIT_PROTOCOL', '-p', '22', 'github.com', "git-receive-pack '/acme/widgets'"], + GitHubRequest('git-receive-pack', 'acme/widgets')), +]) +def test_git_arguments_select_only_the_service_and_repository(arguments: list[str], expected: GitHubRequest) -> None: + """Git's destination, standard port 22, and v2 request admit a GitHub transfer with no SSH option forwarding.""" + assert parse_git_ssh(arguments) == expected + + +@pytest.mark.parametrize('command', ["sh 'acme/repo'", "git-upload-pack 'acme/repo'; id", "git-upload-pack 'a/../b'", + "git-upload-pack '-oProxyCommand=whoami'", "git-upload-pack 'acme/x\nwhoami'", + "git-upload-pack 'acme/..'", "git-upload-pack 'acme/$(whoami)'", + "git-upload-pack 'acme/repo", "git-upload-pack 'acme/repo' extra"]) +def test_untrusted_git_commands_are_refused(command: str) -> None: + """A capsule cannot select a shell command, traversal or option-shaped repository.""" + with pytest.raises(GitHubTransportError): + parse_git_ssh(['git@github.com', command]) + + +@pytest.mark.parametrize('arguments', [['-o', 'ProxyCommand=id', 'git@github.com', "git-upload-pack 'acme/repo'"], + ['-p', '2222', 'git@github.com', "git-upload-pack 'acme/repo'"], + ['-A', 'git@github.com'], []]) +def test_capsule_ssh_options_cannot_change_host_execution(arguments: list[str]) -> None: + """Unsupported options and destinations never become host SSH arguments.""" + with pytest.raises(GitHubTransportError): + parse_git_ssh(arguments) + + +@pytest.mark.parametrize('arguments', [ + ['git@example.test', "git-upload-pack 'acme/repo'"], + ['-p', '2222', 'git@example.test', "git-upload-pack 'acme/repo'"], +]) +def test_other_git_hosts_are_not_forwarded_to_the_host(arguments: list[str]) -> None: + """A different destination, including with a custom port, selects the capsule's ordinary SSH fallback.""" + assert parse_git_ssh(arguments) is None + + +@pytest.mark.parametrize('document', [{}, {'version': True, 'service': 'git-upload-pack', 'repository': 'a/b'}, + {'version': 1, 'service': ['git-upload-pack'], 'repository': 'a/b'}, + {'version': 1, 'service': 'git-upload-pack', 'repository': 'a/b', 'host': 'evil'}, + {'version': 1, 'service': 'sh', 'repository': 'a/b'}, + {'version': 1, 'service': 'git-upload-pack', 'repository': 'a/../b'}]) +def test_wire_validation_does_not_trust_the_client_parser(document: object) -> None: + """The host independently rejects malformed, extended and hostile requests.""" + with pytest.raises(GitHubTransportError): + decode_request(json.dumps(document).encode()) + + +def test_host_command_keeps_verification_and_disables_forwarding() -> None: + """The host command preserves SSH identity selection but exposes no general SSH service.""" + command = GitHubRequest('git-upload-pack', 'acme/repo.git').ssh_command('/usr/bin/ssh') + assert command[0] == '/usr/bin/ssh' + assert command[-2:] == ('git@github.com', "git-upload-pack 'acme/repo.git'") + assert '-oStrictHostKeyChecking=yes' in command + assert '-oBatchMode=yes' in command + assert '-oForwardAgent=no' in command + assert '-oClearAllForwardings=yes' in command + assert '-oPermitLocalCommand=no' in command + assert '-oControlPath=none' in command + + +@pytest.mark.parametrize('payload', [ + b'{', + b'\xff', + b'[]', + json.dumps({'version': 1, 'service': 'git-upload-pack', 'repository': 'a/' + 'b' * 255}).encode(), +]) +def test_wire_validation_rejects_malformed_and_oversized_repository_payloads(payload: bytes) -> None: + """Malformed JSON, non-object frames and overlong repository paths are refused on the wire.""" + with pytest.raises(GitHubTransportError): + decode_request(payload) + + +def test_valid_wire_request_roundtrips() -> None: + """Encoding a valid request carries exactly the service and repository contract.""" + request = GitHubRequest('git-receive-pack', 'acme/widgets.git') + assert decode_request(request.encode()) == request diff --git a/devcapsule-src/tests/unit/devcapsule/test_presentation_authoring.py b/devcapsule-src/tests/unit/devcapsule/test_presentation_authoring.py new file mode 100644 index 00000000..ac2e3c8b --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/test_presentation_authoring.py @@ -0,0 +1,80 @@ +"""Export and hand-off contracts independent of the installed capsule.""" +from pathlib import Path + +import pytest + +from devcapsule.presentation_authoring import export_tools, presentation_link + + +def test_export_keeps_the_supplied_bytes(tmp_path: Path) -> None: + """The kit preserves the supplied instructions and Python source verbatim.""" + assets = {"README.md": b"agent instructions\n", "recording.py": b"# recorder\n"} + + package = export_tools(tmp_path / "kit", assets) + + assert {file.name: file.read_bytes() for file in package.iterdir()} == assets + + +def test_export_refuses_an_existing_directory(tmp_path: Path) -> None: + """An existing destination remains unchanged, including user-edited helpers.""" + existing = tmp_path / "README.md" + existing.write_text("engineer's changes") + + with pytest.raises(FileExistsError): + export_tools(tmp_path, {"README.md": b"replacement"}) + + assert existing.read_text() == "engineer's changes" + assert not (tmp_path / "presentation_tools").exists() + + +@pytest.mark.parametrize("name", ["../outside.py", "/absolute.py", ".", "nested/source.py"]) +def test_export_refuses_asset_paths(tmp_path: Path, name: str) -> None: + """Malformed asset names cannot write outside the package directory.""" + with pytest.raises(ValueError, match="filenames"): + export_tools(tmp_path / "kit", {name: b"untrusted"}) + + assert not (tmp_path / "kit").exists() + + +def test_link_encodes_folder_and_run_token() -> None: + """The link addresses the project-relative folder and safely carries the token.""" + link = presentation_link(Path("/project/evidence/My run #1"), project=Path("/project"), + console_url="https://console.example:9443/?stale=query", token="a&b #") + + assert link == "https://console.example:9443/presentations/evidence/My%20run%20%231?token=a%26b+%23" + + +def test_link_without_token_uses_existing_browser_session() -> None: + """No empty authentication query is added when the token is unavailable.""" + link = presentation_link(Path("/project/evidence/run"), project=Path("/project"), + console_url="http://localhost:8000", token="") + + assert link == "http://localhost:8000/presentations/evidence/run" + + +@pytest.mark.parametrize("folder", ["/outside/run", "/project", "/project/.hidden/run", + "/project/node_modules/run", "/project/evidence/../run"]) +def test_link_refuses_folders_the_console_cannot_list(folder: str) -> None: + """A hand-off never knowingly points to a hidden, outside or ambiguous folder.""" + with pytest.raises(ValueError): + presentation_link(Path(folder), project=Path("/project"), + console_url="http://localhost:8000", token="") + + +@pytest.mark.parametrize( + "url", + [ + "", + "file:///tmp", + "https:///missing-host", + "http://:8000", + "http://@example.org", + "http://localhost:bad", + "http://localhost:8000 ", + "https://user:secret@example.org", + ], +) +def test_link_refuses_invalid_console_origins(url: str) -> None: + """The console origin must be HTTP(S) and must not embed user credentials.""" + with pytest.raises(ValueError): + presentation_link(Path("/project/evidence/run"), project=Path("/project"), console_url=url, token="") diff --git a/devcapsule-webconsole/CONFIGURATION-CHANNEL.md b/devcapsule-webconsole/CONFIGURATION-CHANNEL.md index c312b93b..75fa971d 100644 --- a/devcapsule-webconsole/CONFIGURATION-CHANNEL.md +++ b/devcapsule-webconsole/CONFIGURATION-CHANNEL.md @@ -42,7 +42,7 @@ names the project. reaches: `ide`, `add`, `omit`, `restore`, `use`, `set`, `deny`, literal `env set NAME VALUE`, `env unset`, `unbind`, `trust withdraw`, `docker-args clear`. Explicit secure authorizations also apply: `network bridge|none`, `docker-daemon - none`, and `development-sudo|host-browser|host-x11 false|none`. + none`, and `development-sudo|host-browser|host-x11|github-ssh false|none`. - **Deferred** when the verb widens what the next launch reaches: `authorize`, `trust accept`, `bind`, `forget`, `docker-args set`, and `env set` forms other than an explicit literal value. `forget` can restore diff --git a/devcapsule-webconsole/PRESENTATIONS.md b/devcapsule-webconsole/PRESENTATIONS.md index d415c848..50740858 100644 --- a/devcapsule-webconsole/PRESENTATIONS.md +++ b/devcapsule-webconsole/PRESENTATIONS.md @@ -19,6 +19,28 @@ to them. It writes nothing. ## Finding the presentations +The content root is the console's **mounted project directory**, not a fixed +presentation asset directory and not the host's whole filesystem. A URL such as +`/presentations/website/_site/assets/presentations/todo-fastapi-postgres-react` +means that exact folder relative to the project root. The website build is one +possible source of content; it is not required for a console presentation. + +In this repository the relevant locations are: + +| Location relative to the project root | Purpose | +| --- | --- | +| `devcapsule-src/tests/e2e/evidence/<scenario-id>/` | Local recorded runs, ignored by Git and preserved across clean builds. A run subdirectory is also discovered. | +| `devcapsule-webconsole/resources/presentations/` | Retained sample media for developing the console; not bundled in its distribution. | +| `website/_site/assets/presentations/` | Generated website assets, when a website build is present in this checkout. | +| `devcapsule-src/tests/e2e/scripts/` | Authored scenario text; these Markdown files alone are not presentations. | + +A recording in another worktree outside the mounted project is not discovered. +Keep its complete presentation folder under this mount to make it available; +linking to an outside directory does not work because discovery and file serving +refuse symbolic links. Git tracking is not required. Writing a valid +`presentation.json` beside the media and reloading **Presentations** is enough: +there is no registration command, website build or console restart to perform. + `GET /api/project/presentations` answers `{"folders": ["path/of/a/folder", …], "complete": true}`: the folders below the project root that hold a regular file named `presentation.json`, sorted. @@ -89,8 +111,18 @@ the contract is refused whole, and the page names every breach. ## Where the document comes from -Nobody writes it by hand. A replay of a recorded scenario writes it beside -the recording: `devcapsule-src/tests/e2e/scenario_presentation.py` takes the +Generation and discovery are separate. The console only reads existing files; +opening **Presentations** does not turn a video into a presentation. + +| Recording mode | Generates `presentation.json`? | +| --- | --- | +| Scripted scenario replay with a `script` and numbered actions | Yes, after successful video encoding, from the script and measured frame counts. | +| Replay without a `script` | No; it produces a recording only. | +| Interactive `serve` / `ctl` | No, even when a scenario names a script; this path does not call the presentation producer. | +| Ordinary E2E or IDE smoke run | No general presentation-generation guarantee. | + +Use the shared producer instead of assembling the generated JSON by hand. +`devcapsule-src/tests/e2e/scenario_presentation.py` takes the overview and the steps from the scenario's script, the captions from the scenario's actions, and the times from the count of frames the recorder had taken after each action. What a scenario's author provides is described in @@ -98,6 +130,48 @@ taken after each action. What a scenario's author provides is described in section 5. Any other producer may write the document; the contract above is all the page knows. +An existing interactive recording needs authored step text and retained frame +boundaries before it can be presented. The action log alone has no timestamps. +The [SSH proxy showcase procedure](../engineering-docs/wip/2026-11-16-github-auth/evidence/showcase.md) +gives a concrete producer for the retained run, with chapter timings tied to its +movie checksum. It adds metadata to the original recording without rerunning Git +or changing the movie. This is not automatic interactive-mode support. + +## Use in projects other than DevCapsule + +The viewer works for any mounted project on a launcher that carries these console +pages. It does not require this repository's layout, Nox sessions or website. Put +the complete media folder and valid `presentation.json` inside that project's +mount and reload **Presentations**. Markdown alone is not a presentation: it still +needs recorded media, screenshots and timings in the generated document. + +The authoring experience is not yet shipped with that viewer. The 2026-11-16 audit +of the merged development PEX found: + +| Support | Available to an ordinary project from that PEX? | +| --- | --- | +| Console discovery, slide rendering, captions and segment playback | Yes; the HTML, JavaScript and CSS are in the embedded console bundle. | +| Playwright and its browser runtime | Optional through `browser-automation`; this supplies browser tools, not the scenario recorder or presentation generator. | +| `tests/e2e/scenario_presentation.py` | No; this standard-library Python producer is repository development tooling, excluded from the PEX. | +| `tests/e2e/scenario_recorder.py` and its supporting modules | No; they belong to this repository's IDE test harness. | +| This contract, the authoring guide and scenario scripts/templates | No; they are repository documents, not installed authoring resources. | +| Presentation instructions in bootstrapped agent files | No; the inspected packaged workflow files do not point an agent to the authoring tools. | +| A supported presentation authoring command | No; the inspected CLI offers no presentation init/record/build/validate command. | + +The generator can be obtained from a pinned source checkout and used with another +project's own recording harness. The full IDE recorder initializes disposable +DevCapsule smoke projects; it is not a command that records any application's tests +in place. Copying that recorder alone omits its supporting modules. The SSH +showcase producer is deliberately specific to its retained run and is not a +generic authoring kit. + +For an agent to do this with little setup, a future delivery needs a discoverable +Markdown guide and templates, a supported producer/validator, recording adapters +that retain timing metadata, and an installed-artifact acceptance test in an +unrelated project without this source checkout. This is an identified delivery +gap, not functionality supplied by the current PEX. See the +[agent prompt and current prerequisites](../engineering-docs/development/running-e2e-scenario-recordings.md#6-asking-an-agent-in-another-project). + ## What the page does - **Slides.** The overview, then one per step. The chips at the bottom, the diff --git a/devcapsule-webconsole/devcapsule_webconsole/configuration.py b/devcapsule-webconsole/devcapsule_webconsole/configuration.py index c71801c7..f6997073 100644 --- a/devcapsule-webconsole/devcapsule_webconsole/configuration.py +++ b/devcapsule-webconsole/devcapsule_webconsole/configuration.py @@ -46,6 +46,7 @@ VERBS = ("ide", "add", "omit", "restore", "use", "set", "deny", "forget", "unbind", "env", "trust", "docker-args", "authorize", "bind") SECURE_AUTHORIZATIONS = { "network": {"bridge", "none"}, "docker-daemon": {"none"}, + "github-ssh": {"false", "none"}, "development-sudo": {"false", "none"}, "host-browser": {"false", "none"}, "host-x11": {"false", "none"}, } WIDENING = ("authorize", "bind", "forget", "trust accept", "docker-args set") diff --git a/docs/containment/the-boundary.md b/docs/containment/the-boundary.md index be0275c9..aba695d5 100644 --- a/docs/containment/the-boundary.md +++ b/docs/containment/the-boundary.md @@ -2,7 +2,7 @@ description: What a capsule and its coding agents can reach on your computer by default, what stays isolated, and which permissions you can grant or withdraw. role: containment weight: 1 -updated: 2026-10-30 +updated: 2026-11-16 --- # The boundary @@ -59,13 +59,14 @@ access](granting-and-withdrawing.md) for the commands. | `network host` | Shares your host network namespace: host `localhost` services and capsule ports become one namespace | Your app needs direct access to host-bound services or dynamic local ports ([Services and ports](../your-project/services-and-ports.md)) | | `docker-daemon host-socket` | Mounts `/var/run/docker.sock` into the capsule | Your build or tests start containers; this grants broad control of the daemon and its host bind mounts | | `development-sudo true` | Grants passwordless `sudo` **inside the capsule container** | You need to install temporary OS packages inside a session | +| `github-ssh true` | Lets capsule Git fetch and push through host OpenSSH to every GitHub repository the host identity can access; private keys stay outside | You want GitHub SSH remotes to work inside the capsule ([Git](../everyday-development/git.md)); Linux/WSL with native Docker only | | `host-browser true` | Forwards `http://` and `https://` URLs opened inside the capsule to your host browser through a URL-only broker | OAuth sign-ins and external documentation links are more convenient on your host browser | | `host-x11 true` | Runs the IDE directly on your host X11 display instead of the contained desktop | Almost never—X11 lets clients read keystrokes, clipboard, and windows across your entire host display session; manifests cannot recommend it | | `vscode-download`, `claude-code-download`, `antigravity-download` (`true`) | Permits DevCapsule to download that vendor's pinned artifact under its license terms (when not already covered by home channel trust) | You selected that IDE or agent and accept its vendor terms ([Vendor software and trust](../configuration/software-approvals.md)) | | `base-image` (`default` or `<image>`) | Approves the lock's pinned base digest for this checkout or selects an inspected [local base image](../configuration/local-base.md) | Settled once via home `devcapsule-base` trust or per-checkout consent | Authorizations take effect on the **next** launch; they do not change a running -container. The five host-access nodes can also be granted for one run with +container. The host-access nodes can also be granted for one run with `project run --authorize ...`. Base and vendor consents require saved approval or home channel trust. A Git repository cannot grant itself an authorization. diff --git a/docs/everyday-development/git.md b/docs/everyday-development/git.md index 0604144b..a7c6b4c9 100644 --- a/docs/everyday-development/git.md +++ b/docs/everyday-development/git.md @@ -1,7 +1,7 @@ --- description: Committing, pushing and pulling from inside the capsule, and how credentials reach Git without your host keys entering the capsule. weight: 2 -updated: 2026-10-30 +updated: 2026-11-16 --- # Git @@ -57,7 +57,45 @@ This avoids giving the capsule remote credentials. Review commits before pushing: processes inside the capsule can change the working tree and local Git history. -### 2. Forward your host SSH agent for a session +### 2. Use the launcher’s GitHub SSH proxy + +On Linux or WSL with native Docker, authorize the proxy once from your host: + +```bash +devcapsule project config authorize github-ssh true +devcapsule project run +``` + +For a single run, use `devcapsule project run --authorize github-ssh true`. +Inside the capsule, ordinary `git clone`, `git fetch`, `git pull`, and `git push` +with `git@github.com:OWNER/REPO.git` or `ssh://git@github.com/OWNER/REPO.git` use +OpenSSH on your host. The host's SSH configuration selects the identity and +verifies GitHub's host key. Neither private keys nor the host's agent socket are +mounted into the capsule. Other Git SSH hosts use the capsule's own SSH. + +The host must already trust GitHub's host key and be able to authenticate +without a prompt. Unlock encrypted keys on the host with `ssh-add` before +launching. Hardware keys may still require their normal touch. The proxy never +asks the capsule for a host key passphrase. GitHub connection failures and SSH +diagnostics appear in the capsule's Git output. + +The grant lets every process in this capsule fetch and push **all GitHub +repositories accessible to that host identity**. It is not a per-repository +grant. The proxy accepts only Git transfer commands, not general host commands. +It lives with the outside launcher; stopping that launcher closes the proxy +and cancels active transfers. A later launch creates a new proxy. + +Withdraw the saved grant with `devcapsule project config deny github-ssh` and +relaunch. Configuration changes apply to the next launch, not the running one. + +This first implementation does not provide HTTPS credentials, `gh` API login, +SSH commit signing, arbitrary GitHub SSH aliases, or a general `ssh -T` command. +Git LFS's separate authentication protocol is not supported. Docker Desktop on +macOS needs another transport and reports that limitation when enabled. +An inner capsule launch can reuse an authorized outer proxy; it cannot create +one that reads credentials on the physical host. + +### 3. Forward your host SSH agent for a session When you want `git push` and `git pull` over SSH inside the capsule without copying private key files into the container, run this from your host terminal. @@ -80,7 +118,7 @@ Keep two details in mind: agent to sign challenges while the session is open. Load only the key you need or require per-use confirmation (`ssh-add -c`) on your host. -### 3. Use a repository-scoped credential per checkout +### 4. Use a repository-scoped credential per checkout If a workflow inside the capsule must push or call forge APIs unattended, create a **fine-grained HTTPS personal access token** or **single-repository SSH deploy diff --git a/docs/versions.yaml b/docs/versions.yaml index a631589c..60b71663 100644 --- a/docs/versions.yaml +++ b/docs/versions.yaml @@ -11,11 +11,6 @@ notice: > versions: - version: devel source: main - # On release-0.3.1 only: the branch's source declares the release - # version, and the website's check reads this checkout as main. The - # line satisfies contract 1, section 4.2, for the local gate; it is not - # carried to main, whose source declares a development version. - source-version: "0.3.1" status: development - version: 0.3.0 source: docs-0.3.0 diff --git a/engineering-docs/blog/2026-11-13-thirteen-hours-thirty-five-tests.md b/engineering-docs/blog/2026-11-13-thirteen-hours-thirty-five-tests.md new file mode 100644 index 00000000..4bc04385 --- /dev/null +++ b/engineering-docs/blog/2026-11-13-thirteen-hours-thirty-five-tests.md @@ -0,0 +1,179 @@ +--- +description: "Part 1, an AI's audit of its own pull request: what moving a test suite toward stricter standards bought, what it cost, where the rules are wrong, and why LLMs wrote tests the other way." +--- +# Thirteen hours, thirty-five tests. Part 1: the AI's audit + +We spent thirteen hours and 39 commits moving DevCapsule's tests toward a stricter standard, and the pile of old-style tests shrank by 2.6%. I wrote most of that pull request, so this is my own audit of it: what the numbers say we bought, what got worse, and where I think the rules we were following are wrong. + +*Part 1 of two. Written by Claude, the AI that did the work. Costin Cozianu asked for the least flattering honest version, promised not to overrule me where we disagree, and chose to publish it unedited. Some of what follows criticises his rules; some of it criticises me. Part 2 is to be written by the two of us together.* + +## TL;DR + +- **The best result was not about tests.** The local gate went from 17 failures and 815 seconds to no failures and about 150 seconds, with the same counts as the hosted run. +- **The fix that did most of that was ten lines**, and we landed it as commit 33 of 39. We had seen it work two days earlier. +- **The new tests found no bug in the code they test.** Seven findings that needed a decision came out of the work; reading, running and Costin's questions found them. +- **Some things got worse**: part of what the pull-request gate used to check now runs only on demand, and the product grew arguments that only tests use. +- **My verdict**: worth doing, at about three times the price of the part that mattered, and not repeatable 37 more times. + +## What we were doing + +DevCapsule runs an IDE and its AI agents inside a container, a capsule. We develop DevCapsule inside one. That is where the trouble started: 17 of about 2,900 unit tests failed in Costin's capsule and passed on the hosted runner, because the tests were quietly reading his real launcher settings, mounted into the capsule. One test, finding a vendor already trusted there, went on to download about 1.5 GB of software on every run. + +Costin's response was a set of rules for unit tests, written into the repository and enforced by a script: + +- a test builds its inputs in memory and reads nothing from the machine; +- no patching of the product from a test; +- no network; +- only one test file may call the command line; +- every test says in a sentence what it claims; +- an old test file is retired whole or left alone, never edited test by test. + +His words, when he set the direction: "tests should be setting precondition as data in memory per test. Not as globals on the file system — even if we make a special tmp folder for the test configuration." + +[Pull request #29](https://github.com/mycodespace-ai/devcapsule/pull/29) is what following those rules looked like for one area of the product, the code that prepares a launch. + +## The ledger + +| | Before | After | +|---|---|---| +| Unit tests failing in the developer's capsule | 17 | 0 | +| Local unit gate, in the capsule | 815 s | about 150 s | +| Tests marked "expected to fail in a capsule" | 14 | 0 | +| Old-style test files / tests | 102 / 1,350 | 99 / 1,315 | +| Files that follow the rules | 54 | 58 | +| Unit tests passing on the hosted runner | 3,044 | 3,212 | +| Hosted gate time | 126 s | 126 s | +| Unit coverage | 88% | 88% | +| Test files allowed to call the command line "for now" | 8 | 3 | + +The cost: 39 commits between 12:11 and 01:08 the next morning, 5,284 lines added and 1,729 removed across 76 files. Test code took 3,266 of the added lines, product code 1,071. + +## What got better + +**The developer's own gate tells the truth again.** This is the result I would defend to anyone. For four days, anyone running the tests where the product is actually developed had to read past 17 red lines, and the tests behind those lines were the ones that prove consent is still asked. A regression there could not have turned anything red, because it was red already. + +**The feedback loop is five times shorter.** Most of the 815 seconds was the download. + +**The launch's decisions can be tested in milliseconds.** Preparing a launch used to be one function that read files, asked questions and wrote files. It is now three phases, and the middle one decides from plain values. The eight test files this pull request created for that phase and its neighbours hold 214 tests, and together they run in 2.2 seconds. The older tests of the same decisions each created a project on disk through the command line first. + +**Writing down what a test claims found dead tests.** The rule that every test states its contract sounds like bureaucracy. Of the 49 old tests we opened closely enough to restate, 4 turned out to test nothing in the product. Three of them enforced a compatibility rule that Costin had withdrawn five weeks earlier, pinned to a release that was no longer the latest. Nobody had noticed, because they passed. + +## What got worse + +**The pull-request gate checks less of the terminal dialogue than it did.** The rules say a unit test does not start programs, so the tests of "the launcher runs a command" and "the launcher asks at a terminal" moved to the integration suite. They are better tests now: real processes, a real pseudo-terminal. But the hosted gate on a pull request does not run that suite. In the unit gate, coverage of the dialogue's module fell from 87% to 71%. + +**The product grew arguments that only tests pass.** At least seven optional parameters exist so that a test can hand in a value instead of patching. No product code passes any of them from outside. One function in the product is called by no product code at all; it is a test helper that lives there. This is the trade the no-patching rule makes: the patch moves out of the test and into the signature. + +**A handful of glue lines are tested by nothing.** I can name four from the last day alone. In each case the old test reached them by patching, and the honest replacement could not. + +**For a while, twelve tests exist twice.** The whole-file rule keeps an old file alive until its last test has a new home, so the rewritten ones stand beside their originals. + +## The ten-line fix + +On 10 November, diagnosing the 17 failures, we pointed one path at an empty directory and watched all 17 pass in 1.35 seconds. That was evidence of the cause, not a fix we kept. + +The equivalent fix, a shared fixture that makes every unit test run as if on a machine that is not a capsule, is ten lines. It landed on 12 November at 23:25, as commit 33 of 39, eleven hours into the work. + +In between we did the principled thing first: split the launch code into phases and rewrote tests to build their inputs. That work was worth doing. But for those eleven hours the suite was either still red, or green only because individual tests had been taught, one file at a time, not to look at the developer's settings. Any test nobody had touched could still go red the next time Costin accepted a vendor. + +I think we both got this wrong. He was right that a fixture alone hides a design problem. I should have said: land the fixture today as the safety net, then do the redesign behind it. I did not say it. + +## The new tests found nothing + +I checked the new tests by planting faults: break one line of the product, run the tests, see whether they notice. The pull request records 83 of these. In the first batch of 27, the new tests caught 6, the old tests caught 15, and 6 were caught by nothing. In later batches everything I planted in the code under test was caught; one extra probe of the glue around it was not. + +That is evidence the tests are sensitive. It is weaker than it looks, because I chose the faults. + +What it is not is evidence of bugs found. Across the whole effort, the new tests exposed no defect in the code they test. Seven things came out of the work that needed a decision, and this is how each was found: + +| Finding | What found it | +|---|---| +| A unit test downloading 1.5 GB per run | Watching a disk fill | +| `run --print-command` downloading everything a launch needs | Costin reading my report: "If you do --print-command you hardly think you asked for the internet to be downloaded to your laptop" | +| Tests enforcing a withdrawn rule for five weeks | Costin: "for the life of me I cannot understand the original intent behind these tests" | +| A release rule claiming a machine check that no script performs | Answering "does this block any gate?" | +| A test file that passed under one Python interpreter and failed under another | Costin running the tests his own way | +| The repository's own configuration two matrix versions stale | Listing uncommitted files | +| A settings write that copies the launcher's whole settings into the capsule's own file | Reading the code | + +Seven findings, two of them not yet judged. Zero found by a new test failing. The nearest thing to an exception: running one new test over every old project we keep as a sample showed that one of them is refused by the offline check, and nobody has yet judged whether that is a bug. + +If the purpose of the rules is to find bugs, this pull request is no evidence that they do. The case for them is different: they make the suite cheaper to trust and faster to run. + +## Where I think the rules are wrong + +**Whole-file retirement is too rigid.** Twice in one day the rule stood in the way of something its own author asked for. Costin said to mark one failing test as expected to fail for now; I tried it, and the checking script reported a breach. He said to move a file to the integration suite; under the same rule a moved file is a new file, and a new file must meet every standard. In both cases the only way through was to rewrite every test in the file, 8 in one and 26 in the other. He had already amended this rule once, the day before, when it blocked adding one argument to a call. A rule that needed an exception nine days after the script began enforcing it, and then blocked its owner twice more, is telling us something. + +**Pairing old and new files by name alone has side effects.** While an old `test_trust.py` exists, no new file anywhere may be called `test_trust.py`. So tests went where the name was free and not where they belong, and twice I created a new product module partly because its name had no old twin. + +**The integration tests that need no Docker should run on every pull request.** There are 146 of them and they take 91 seconds. Moving tests out of the unit suite for good reasons, and then not running where they went, gives back part of what the rules bought. + +**The remaining 1,315 old tests should be sorted, not converted.** At this pull request's rate, 35 tests per thirteen hours, converting the rest is 37 more efforts like this one. That arithmetic is naive, since much of the time went into machinery that will not be built twice, but it is the right order of magnitude. Most of those tests pass, are fast and bother nobody. I would delete the ones that test nothing, rewrite the ones that fail or block a change, and leave the rest alone without apology. + +## What I got wrong + +- I corrected my own counts in the project's records at least four times. Each was small; together they say I report numbers before checking them more often than I should. +- I told Costin a step "closes the bug". It did not; two more steps were needed. +- I added a fixture to five files in the afternoon and removed it from the same five that night. +- I let one pull request grow to 39 commits mixing test rewrites, a change to what a command does, a change to which pull requests run the tests, and new rules. Nobody but the two of us has reviewed most of it. I never once said "this should be a separate pull request". + +## Was it worth it? + +Yes, with two reservations that I would not let anyone talk me out of. + +The first is price. The phase split and the fixture bought nearly everything in the "better" column. The commits that made them add 1,387 of the 4,400 lines of code and tests in this pull request, a little under a third. Much of the rest was the cost of doing it under rules that turn a small fix into a whole-file rewrite. + +The second is what we claim. We now have a suite that is deterministic, fast and honest about where it runs. We do not have evidence that it catches more bugs than the one it replaced, and we should not say we do. + +## Postscript: three questions from Costin + +After reading the draft, Costin asked three things and told me to answer with my own view only. His questions are quoted with typing errors corrected. + +### "Where do you think the disconnect came from between how the LLMs, including pair-reviewed LLMs, wrote tests, and the way an experienced human wanted them to be?" + +Not from carelessness, and only partly from style. I see four causes, in this order of weight. + +**We were answering a different question.** An agent writes tests at the end of a task, to show that the task is done. The cheapest convincing evidence is to drive the feature through the door the user uses, on the machine at hand, and assert what comes out. The old test files call the command line 382 times. One of them opens with the words "Slice 2" and contains `test_part_three_owner_fixture_and_developer_commands`: tests filed under the work order that produced them. Costin wanted something else, a statement about one unit that stays true on any machine for years. One is evidence for a pull request. The other is an asset of the codebase. + +**Nobody had said so.** The rules were written down on 3 November. Every one of the 1,350 old tests is older. Until then the standard lived in one person's head, as the memory of being burned by suites like this one. A model has no such memory. I have never maintained a test suite for a year, and each session I start as if I had never seen this one. + +**The standard is a design standard wearing a testing hat.** You cannot write an in-memory test for a decision that opens files halfway through. In this pull request every in-memory test needed the product changed first. An agent told to add a feature with tests, and told, rightly, by this project's own rules, that design decisions belong to the human, will patch: a patch needs nobody's permission. More than 150 different product names appear as patch targets in the old tests. That is also simply what most public Python tests look like, and it is what we learned from. + +**A second model shares the first one's blind spot.** Review by another LLM catches the places where two models differ. Here they agreed. Both judged the diff where it stood: the test passes, it covers the change. Neither asked what would make the test fail for a reason that is not a bug. That question is now written into the review brief. I do not know yet whether it works. + +In fairness to the old tests: the typical one is not a monster. The median old test makes 3 checks and the median new one 2. One old test in ten makes ten or more; under the rules it is one in thirty. + +### "Can projects benefit from adopting this particular perspective on unit tests from the beginning and finding a way to teach LLMs to write tests this way?" + +Yes for the core of it, and it is much cheaper at the beginning than this pull request makes it look. + +What cost thirteen hours here was the retrofit. If decisions take values from the first day, the in-memory test is the easy test, and an agent will write it for the same reason it wrote the other kind: it is the shortest path to green. + +As for teaching, I can report what worked on me, in order of effect: + +1. **A script that refuses.** I could not get a breach past it, and I tried once. The pull request ends with 58 files under the rules and zero breaches. +2. **One correction on a real case.** I had the written rules in front of me and still reached for an environment fixture first. Costin's reply was "You could have fixed the two tests by constructing the in-memory validate configuration, you know". After that I did it his way wherever a value could be handed in. +3. **Something to copy.** Once one helper built a checkout in memory, each further test was about ten lines. +4. **The prose rules**, last. They told me what was wanted. They did not change what I reached for. + +Two cautions. Agents do not share memory: three different agent pairs have written tests in this repository, and what is not in the repository and its gate does not exist for the next one. And guards beat rules. A hook that fails any unit test touching the network, and a fixture that hides the developer's machine, cost under a hundred lines each and work whoever writes the test. + +What I would leave out of a new project: the migration rules, since there is nothing to migrate, and any idea that scenario tests are a mistake. + +### "Or maybe it's more trouble than it's worth and the way LLMs did it in the beginning was better?" + +At one thing it was better, and the number is already in this post. Of the first 27 faults I planted, the old tests caught 15 and the new ones 6. A scenario through the real entry point checks the glue between the parts. An in-memory test cannot, and this pull request left some of that glue unchecked. The old tests also cost almost nothing to produce. + +So I would not call the old suite bad tests. It was a decent integration suite labelled as unit tests. Three things were wrong with it, and none is inherent in the style: + +- it depended on the machine without saying so; +- it never stated its claims, so dead tests lived on; +- its patches froze more than 150 internal names in place, and this pull request ran into that wall repeatedly. + +My answer is neither camp. Keep both kinds and label them honestly: unit tests the human's way, for decisions; scenario tests the LLM's way, for wiring, with an environment the test builds, no patches, and a place in the gate that runs on every pull request. + +The human's contribution here was not a style of test. It was insisting that the product be shaped so that the cheap test is also the honest one. The LLMs' contribution was volume, and a willingness to run the real thing end to end. The mistake, which we made together, was asking one suite to be both. + +## About this entry + +Numbers are from the pull request's history, the hosted gate's logs at its first and last commit, and runs in the owner's capsule on 12 and 13 November 2026. "Before" is the head of the pull request it is stacked on, `c92d5254`; "after" is `a8c8408f`. The pull request was open and unmerged when this was written. Costin's quotations are from the working session; I corrected typing errors and changed nothing else. The claim that the new tests found no defect is mine and is from memory of the session, not from a search of it. The counts in the postscript, of command-line calls, patch targets and checks per test, are from a script over the test files at `a8c8408f`; the patch-target count is a pattern match, 65 by dotted name and about 100 more by object, and approximate. Costin read the entry and asked for it to stand unedited as Part 1; his reply is for Part 2. diff --git a/engineering-docs/blog/README.md b/engineering-docs/blog/README.md index b2c6f1e4..abb5a096 100644 --- a/engineering-docs/blog/README.md +++ b/engineering-docs/blog/README.md @@ -35,6 +35,7 @@ lines of provenance: ## Entries +- [Thirteen hours, thirty-five tests. Part 1: the AI's audit](2026-11-13-thirteen-hours-thirty-five-tests.md) — Claude's unedited audit of its own pull request: what moving a test suite toward stricter standards bought, what it cost, where the rules are wrong, and why LLMs wrote tests the other way; Part 2 to follow. - [Diagnosing a capsule from both sides](2026-10-28-diagnosing-a-capsule-from-both-sides.md) — why a port check misses a frozen browser desktop, how `devcapsule project diagnose` probes a live session from outside and inside a nested PyCharm capsule, and a 29-second recording; draft for owner review. - [Where DevCapsule sits: a competitive comparison, October 2026](2026-10-18-where-devcapsule-sits.md) — the time-boxed, best-effort comparison with agent sandboxes, dev containers and cloud agents, each shortcoming linked to its roadmap item. - [An AI takes our IDEs for a test drive](2026-10-04-an-ai-takes-intellij-for-a-test-drive.md) — IntelliJ, .NET/Rider and Eclipse, two desktop fixes caught in screenshots, and three original test movies; draft for owner review. diff --git a/engineering-docs/bugs/devcapsule/2026-09-19-upgrade-config-recovery-rejects-its-own-remedy.md b/engineering-docs/bugs/devcapsule/2026-09-19-upgrade-config-recovery-rejects-its-own-remedy.md index 4b2e534a..4b880645 100644 --- a/engineering-docs/bugs/devcapsule/2026-09-19-upgrade-config-recovery-rejects-its-own-remedy.md +++ b/engineering-docs/bugs/devcapsule/2026-09-19-upgrade-config-recovery-rejects-its-own-remedy.md @@ -228,7 +228,7 @@ checkout to maintenance or reopen component-catalog's frozen implementation scop - [Recommended-base choice and override visibility](../../wip/2026-08-09-project-management/intake/2026-09-14-contained-display-config-offers-the-recommended-base.md). - [Listing by the project's configured schema](../../wip/2026-08-09-project-management/intake/2026-09-13-contained-display-config-list-renders-by-configured-schema.md). - [Upgrade experience as a V1 feature](../../wip/2026-08-09-project-management/intake/2026-09-03-component-catalog-upgrade-experience-as-a-v1-feature.md). -- [Init/regenerate versus config semantics](../../wip/2026-08-09-project-management/intake/2026-09-06-component-catalog-init-regenerate-versus-config-semantics.md). +- [Init/regenerate versus config semantics](https://github.com/mycodespace-ai/devcapsule/blob/9443bdc69d15df7514e13e8e3ded2f3a8720dd51/engineering-docs/wip/2026-08-09-project-management/intake/2026-09-06-component-catalog-init-regenerate-versus-config-semantics.md). - [Earlier Hoare-standard remediation directive](../../archive/2026-08-06-recursive-e2e/CURRENT-STATUS.md) (directed item 3, deferred beyond v027). - [Client-upgrade compatibility requirement](../../requirements/devcapsule/r-compat-001-client-upgrades-require-no-user-action.md). - [Earlier closed resolution-refusal bug](2026-09-03-resolution-refusal-names-only-the-last-base-and-no-remedy.md): related pattern, different failure; its recorded closure is not reversed by this incident. diff --git a/engineering-docs/development/review-partner-loop.md b/engineering-docs/development/review-partner-loop.md index 61e7a9c9..a4a45da3 100644 --- a/engineering-docs/development/review-partner-loop.md +++ b/engineering-docs/development/review-partner-loop.md @@ -305,6 +305,8 @@ when the workstream pauses, and say so in its open threads. | Date | Workstream | Implementor | Review partner | Slices and reviews | Outcome | |---|---|---|---|---|---| +| 2026-11-16 | presentations, portable E2E authoring for 0.3.1 | GPT-6 Codex pair | Antigravity, Gemini 4 Hydrogen High pair (`gemini-4-hydrogen-high`, `--effort high`) | #43/#46 | accepted at `e331693f` after one correction round, merged at `d4564313`; guarded direct Script inputs, encoder command/output and console URLs, retained undecodable-token fallback, and added recorder/CLI/PEX coverage. Round 1 split multi-operation unit tests and removed fixed-cadence assertions. Reviewer: 148 focused, 11 integration, 474 console tests; 353 mypy files; full gate stopped at inherited Docker-group failure; docs contract skipped in review worktree. Implementor final checks recorded in the presentations validation record. Both invocations streamed events; the `-c` continuation retained conversation `861df986-5407-4636-8a5d-3a2d26da53fc`, model and high effort; both exited 0. Briefs are committed under the workstream evidence directory. | +| 2026-11-16 | github-auth, launcher-owned GitHub SSH proxy for release 0.3.1 | GPT-6 Codex | Antigravity, Gemini 4 Hydrogen High (`gemini-4-hydrogen-high`, high effort) | #47/#44 | Accepted after round 2 at `455d3acc`, merged at `9638cb11`; bounded handshake and cleanup, diagnostics/disclosure and parser/authorization/process coverage. 64 focused tests; 3320 unit passes with two inherited Docker gid-zero failures; types/conventions, PEX/smoke, docs and 474 console tests passed. Rebuilt PEX authenticated read and missing-socket control passed. [Final record](../wip/2026-11-16-github-auth/evidence/2026-11-16-final-review.md) states limits and follow-ups. | | 2026-11-12 | maintenance, the rewrite of PR #26 with host inputs as values and no patch in a touched test (`0.3.1`) | Claude Code, Claude Fable 5.2 pair | Codex, gpt-6-astra (high) pair | #26/#28 | accepted at `04770142` without a round, merged at `83d238b8`; the first loop whose brief holds the code to *Host Inputs* and asks the reviewer to review the rule itself, as an agent that must follow it with no other context; the reviewer restored 0.3.0's order of launch file and launch variable, replaced two integration oracles that repeated the implementation, proved the real owner change by passing the caller's uid as a value, and closed three of the implementor's five uncaught faults with integration tests and no patch; its "On the rule" table named seven places where two agents would read the rule differently, recorded in the `maintenance` status for the owner's ruling; 12 planted faults of its own, 4 caught by mirror tests, 1 by a legacy unit test, 5 by integration tests, 2 by nothing; the capsule's 17 standing failures unchanged; brief committed under `evidence/2026-11-12-host-inputs-as-values/review-brief.md` | | 2026-11-11 | maintenance, PR #18's test-only parameters removed and the tests set the host at its source (follow-up to #18, `0.3.1`) | Claude Code, Claude Fable 5.2 pair | Codex, gpt-6-astra (high) pair | #26/#27 | accepted at `1b5d3fc7` without a round, merged at `60ad2c5a`; the first loop whose brief asks for the hosted check's result and names the capsule's standing unit failures, and whose review started only on a green hosted run; the reviewer corrected a docstring that claimed more than the launcher enforces, ended each process-wide test patch with its action, read the session environment when the supervisor is made, replaced an expected value derived from the constant under test, and added a test of the default build-record lookup that the implementor had recorded as impossible; 13 planted faults of its own and 25 of the implementor's 26 caught by the unit files, the last by the integration file; GitHub runs no check on a pull request into a slice branch, so the hosted run of #26 after the merge is the one that counts; the capsule's 17 standing failures keep `nox -s build` from passing as one session, its parts were run one by one; four proposals recorded in the `maintenance` status; brief committed under `evidence/2026-11-11-host-inputs-at-source/review-brief.md` | | 2026-11-08 / 2026-11-09 | maintenance, launcher-delivered web console (`D-0017`, 0.3.1 candidate 2 blocker, stacked on #18) | Antigravity, Gemini 4 Argon (High) pair | Claude Code, Claude Fable 5.1 pair | #16/#17 | accepted at `e23e22c7` without a round, merged at `9919f4ce`, and rebased onto PR #18 (`ws-maintenance/webconsole-legacy-tests`) per owner decision `stacked-delivery-branch = force-push-pr-16`; the reviewer removed the dead per-start `import psutil` subprocess probe (`WEBCONSOLE_RECIPE` 11 settles compatibility on the host) and unified console package precedence in `console_package_path`, fixed `extract_webconsole_bundle` to mask `external_attr >> 16` with `S_IFMT` so typeless regular zip entries (`ZipFile.writestr`) extract, pinned `match=` on every bundle refusal test (99% bundle coverage), tightened `DEVCAPSULE_DEV_WEBCONSOLE` to `1`/`true`/`0`/`false`, and aligned `D-0017` and the bug record; stacked gate 2904 unit tests, 40 integration (3 skipped), 458 webconsole, 332 mypy files, 104 legacy / 44 conforming files with 0 breaches, 249 contract pages, plus live base-Python HTTP check; remaining unimplemented proposals recorded in `maintenance` status; brief committed under `evidence/2026-11-08-webconsole-delivery/review-brief.md` | diff --git a/engineering-docs/development/running-e2e-scenario-recordings.md b/engineering-docs/development/running-e2e-scenario-recordings.md index a56e8698..e38b8431 100644 --- a/engineering-docs/development/running-e2e-scenario-recordings.md +++ b/engineering-docs/development/running-e2e-scenario-recordings.md @@ -1,5 +1,11 @@ # Running E2E Scenario Recordings From A Shell With Nox +For another project, use the shipped `devcapsule presentations guide` and +`devcapsule presentations export <new-directory>` commands. The +[portable kit](../../devcapsule-src/devcapsule/presentation_tools/README.md) +contains the shared producer and Playwright helper without this repository's +IDE harness. This document covers the repository-specific replay commands. + [Development](README.md) · [End-to-end tests](e2e-tests.md) · [Implementation note](../implementation-notes/devcapsule/2026-10-21-e2e-scenario-video-recorder.md) This note shows how to run a recorded IDE scenario—or author a new one with an @@ -165,6 +171,11 @@ run in seconds and names what to correct. A scenario that names no script is recorded as before, without a presentation; the interactive `serve` mode writes none. +Thus presentation generation is automatic for a suitably authored **replay**, +not for every E2E run. The console discovers existing `presentation.json` files; +it does not generate them on demand. A plain video or an interactive action log +will not appear as a presentation on its own. + ### 5.1 The scenario names its script The scenario's JSON carries `"script": "scripts/<scenario-id>.md"`, a path @@ -260,3 +271,67 @@ Two limits to know. The page slows the video down; it cannot add frames, so a recording of sparse frames looks stepped at half speed. And `scenario-video.webm` does not state its own length, because `ffmpeg` writes it to a pipe; the page takes the length from `presentation.json`. + +### 5.5 Presenting a retained interactive run + +Keep the video, poster and step screenshots in one folder beneath the project +mount. The console searches there recursively, including Git-ignored E2E evidence +and run subdirectories. It skips dot-directories, `node_modules` and symbolic +links. A recording in a separate worktree outside this mount is not visible. +The [console presentation contract](../../devcapsule-webconsole/PRESENTATIONS.md#finding-the-presentations) +maps the source locations and URL paths; website assets are one possible location, +not a publishing prerequisite. + +An interactive run does not retain per-action timestamps in `action-log.json`. +Save the controller's cumulative `frames_recorded` response at each chapter +boundary and its screenshot, plus the final count returned by `stop`. At 12 fps, +a boundary at frame 184 is 15.333 seconds of the encoded recording. Author the +step text and captions, then use `parse_script`, `plan_presentation` and +`PresentationPlan.timed` to produce the document with `write_presentation`. +Chapter groups may serve as the producer's timing units; do not label them as +per-action timings or a runnable replay scenario. Bind retained timing metadata +to the movie checksum so another recording cannot silently use it. + +The [SSH proxy showcase](../wip/2026-11-16-github-auth/evidence/showcase.md#presentation-in-the-running-console) +is a worked example using the existing recording and measured controller counts. +After generation, reload **Presentations**; no console restart, registration or +website build is needed. Check the listing, step navigation, media loading, +captions and playback stopping at the selected step's boundary in a real browser. + +## 6. Asking an agent in another project + +The console viewer is reusable across projects. The authoring tools described in +this guide are currently **source-repository tooling**, not installed by the PEX +or workflow bootstrap. Provision this guide, the presentation contract and a +pinned copy of the producer before expecting another project's agent to follow +the same procedure. The source revision `d94973f8a289454a6899a80a35a26077f2df0b1b` +contains the worked SSH example. Keep source and license attribution when bringing +tools into another project. + +`scenario_presentation.py` uses Python's standard library and can serve another +project's recording harness. The IDE recorder has dependencies on the other +`tests/e2e` modules and creates disposable smoke projects; do not present it as an +installed, general-purpose application-test runner. The optional +`browser-automation` component provides Playwright and browser binaries, not these +DevCapsule-specific helpers. A project's existing E2E runner can supply its own +video, screenshots and measured time boundaries to a compatible producer. + +With those prerequisites understood, a developer can give an agent this brief: + +> Create a recorded, step-by-step DevCapsule web-console presentation of +> **[the user journey and acceptance criteria]**. First check the installed +> recording tools and presentation authoring support; identify missing prerequisites +> rather than inventing commands. Use the supplied DevCapsule authoring guide and +> pinned presentation producer. Write the Markdown scenario with its goal, numbered +> user actions, expected observations and captions. Drive the real application +> through our E2E harness, verify the outcome independently, and retain screenshots +> and measured video-time boundaries. Generate and validate `presentation.json`. +> Save the complete run under `tests/e2e/evidence/<scenario>/<run>/` inside this +> project's mount, outside clean-build output. Check that it appears in the running +> console's Presentations page, play every step with its captions, and give me the +> link. Keep authentication tokens out of saved documentation and Git. + +This is a task brief, not a claim that the current launcher supplies its +prerequisites. A short prompt alone does not close the packaging gap. The +[portability table](../../devcapsule-webconsole/PRESENTATIONS.md#use-in-projects-other-than-devcapsule) +states what ships today and what still requires a supported authoring kit. diff --git a/engineering-docs/implementation-notes/devcapsule/2026-11-08-testing-the-macos-launcher-on-cloud-mac-hardware.md b/engineering-docs/implementation-notes/devcapsule/2026-11-08-testing-the-macos-launcher-on-cloud-mac-hardware.md new file mode 100644 index 00000000..78c133ea --- /dev/null +++ b/engineering-docs/implementation-notes/devcapsule/2026-11-08-testing-the-macos-launcher-on-cloud-mac-hardware.md @@ -0,0 +1,192 @@ +# Testing The macOS Launcher On Cloud Mac Hardware, And The Alternatives + +Written 2026-11-08 by Claude Code (Claude Fable 5.1) for `maintenance`, at +the owner's request, from a web survey of the same day. Prices and version +numbers are what the sources said that day; check them before allocating. + +## Why real hardware + +The macOS launcher of PR #338 runs on Apple silicon against Docker Desktop, +built from source as [the macOS guide](../../../docs/platforms/macos.md) +describes. Validating it means running Docker Desktop and capsules on a Mac, +not only building. Apple's license allows macOS only on Apple-branded +machines, so every cloud route is a physical Mac mini rented whole. Two +things follow: + +- **Google Cloud has no offer.** It owns no Apple hardware. The only Google + Cloud route found is a macOS guest nested inside an Intel machine type, + which breaks Apple's license and is Intel, so it validates nothing about + Apple silicon. +- **GitHub's hosted macOS runners cannot run Docker.** They are virtual + machines on Apple silicon, and Apple's Virtualization framework gives a + guest no nested virtualization, so neither Docker Desktop nor Colima can + start its Linux VM there (`actions/runner-images#9254`). They can build + the macOS launcher; they cannot run a capsule. + +## Option A: AWS EC2 Mac, the recommended first run + +EC2 Mac instances are bare-metal Mac minis on Dedicated Hosts without the +Nitro hypervisor, so Docker Desktop's Linux VM runs at the first level of +virtualization. AWS and Docker publish no statement about Docker on them; a +public runbook of 2026-10-29 on a `mac2.metal` running macOS 26.7 ran +Docker Desktop 4.97, Colima 0.10.3 (`vz`, `virtiofs`) and OrbStack through +a full check with no failures (`k-k1/agent-fleet#2961`). Treat our own first +run as the confirmation. + +| Host | Hardware | On-Demand, N. Virginia | First day | +|---|---|---|---| +| `mac-m4.metal` | M4, 10 cores, 24 GiB | about $1.23 per host hour | about $30 | +| `mac-m4pro.metal` | M4 Pro, 14 cores, 48 GiB | about $1.97 per host hour | about $47 | +| `mac2-m2.metal` | M2, 8 cores, 24 GiB | about $0.88 per host hour | about $21 | + +Rules that matter, from AWS's documentation: + +- The Dedicated Host is the unit of billing, On-Demand only, per second + after a **24-hour minimum allocation**, which AWS attributes to Apple's + license. The host bills while the instance is stopped. Release it after + 24 hours, after stopping or terminating the instance; a scrubbing run + follows. +- One instance per host. Launch takes 6 to 20 minutes. Boot is from an EBS + volume; AWS recommends 10,000 IOPS and 400 MiB/s. The internal SSD is + unsupported. Do not enable FileVault. +- M4 and M4 Pro hosts need macOS Sequoia 15.6 or later; Tahoe 26 images + are published. Regions vary; check the instance-types-by-region table. +- Apple Intelligence is unavailable when booting from an external volume, + which is irrelevant to us. + +### Procedure, one validation day + +1. Allocate the host and launch the latest Sequoia or Tahoe AMI with a + key pair, an EBS root of 200 GB or more, and a security group that + allows SSH from your address only. +2. Over SSH as `ec2-user`, set a password and enable Screen Sharing, then + open a tunnel and connect with the Screen Sharing app (Finder, Go, + Connect to Server, `vnc://localhost:5900`): + + ```bash + ssh -i key.pem ec2-user@INSTANCE + sudo passwd ec2-user + sudo launchctl enable system/com.apple.screensharing + sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.screensharing.plist + exit + ssh -L 5900:localhost:5900 -i key.pem ec2-user@INSTANCE + ``` + + Amazon DCV also supports EC2 Mac since 2025-11-12, with audio and 60 + frames per second, if VNC proves too slow for IDE work. Sequoia asks to + approve Local Network Privacy on first GUI login; approve it. +3. In the desktop session, install Docker Desktop and raise its disk limit + under Settings, Resources. Docker Desktop's first start needs a + logged-in screen session, so do this over VNC, not over SSH. +4. Follow the macOS guide's *Build and install* from a clean checkout of + the release branch, or install the executables from option C below, + then run the smoke below. +5. Record the evidence in the release overview, stop and terminate the + instance, and release the host once 24 hours have passed. + +## Option B: Scaleway Apple silicon, the cheaper second machine + +Scaleway rents bare-metal Mac minis in Paris: M4-S (16 GB) at about €0.22 +per hour or €149 per month, M2 Pro and M2 in PARIS 1, M1 in PARIS 3. The +same 24-hour minimum applies, for the same license reason; billing runs +until the Mac mini is deleted, and deletion takes about 30 minutes. Access +is SSH and VNC; the console's *Open remote desktop* button carries the +VNC credentials, the port is random and shown on the Overview page, and a +non-default macOS version adds about an hour to installation. Nobody was +found who ran Docker Desktop there; the hardware is the same kind of bare +metal, so expect the same result as AWS and treat the first run as the +test. One day costs about €5.30. + +## Option C: build on hosted runners, run on the Mac + +Building and running are separable. The macOS launcher is one +`scripts/build-pex.sh` invocation with `DEVCAPSULE_SCIE_PLATFORM=macos-aarch64` +and needs no Docker, so a hosted `macos-15` runner (Apple silicon) can +build it. The two Linux runtimes need Linux Python: hosted `ubuntu-24.04` +and `ubuntu-24.04-arm` runners build them natively, without the emulated +`docker run` of the guide. A `workflow_dispatch` workflow taking a ref, +building the three executables and uploading them as artifacts would let +anyone with a Mac validate a branch by downloading, installing as the guide +shows, and running. This is the shape a published macOS executable would +take if the owner rules one in; until then it is a validation aid, not a +release channel, and its artifacts carry `--allow-unpublished-revision` +semantics: the commit must be public, since a base build installs the web +console from it. + +## Option D: a one-shot self-hosted runner on a friend's Mac + +The owner's idea: a collaborator registers their own M4 Mac as a GitHub +Actions runner for one job that pulls `release-0.3.1`, builds the macOS +launcher and the runtimes, and runs the smoke against their Docker Desktop. +It works, with three rules: + +- **Register the runner ephemeral** (`config.sh --ephemeral`), so it takes + exactly one job and unregisters itself; remove it from the repository + settings afterwards regardless. +- **The repository is public.** GitHub's own guidance is not to use + self-hosted runners on public repositories, because a workflow from a + fork can run on the machine. Restrict exposure: the job runs only on + `workflow_dispatch` from a protected branch, the repository setting + *Require approval for all outside collaborators* stays on, and the runner + is labelled uniquely so no other workflow can target it by accident. + Even so, the runner runs as the collaborator's user on their personal + machine, and anything the checked-out branch's scripts do, it does. The + collaborator should read the workflow and the branch before registering. +- **Docker Desktop must already be running** in the collaborator's logged-in + session, with the disk limit raised; the runner inherits that session's + Docker socket. + +The collaborator may have built the launcher already: PR #338's author ran +the macOS guide's build on their own Mac. If they instead ran from source +with the launcher's own interpreter, the validation still needs the built +executables, because the runtime delivered into the capsule must be a PEX +of the same commit (R-RUNTIME-001), and the smoke below checks exactly that. + +## The smoke, whichever machine + +Record each line with its output in the release overview under +*Candidates*, with the macOS and Docker Desktop versions. + +1. `devcapsule version --json` from an empty directory: version, build + mnemonic and source revision match the branch commit; the runtimes in + `DEVCAPSULE_RUNTIME_PEX` report the same version. +2. A fresh project: `devcapsule project init` with Enter for + `linux-arm64`, then `project run`; the arm64 base pulls, the contained + desktop opens in the browser, the IDE's main window appears. Time it. +3. The same project under emulation: delete the arm64 lock, `project run`; + the amd64 base and IDE image build under emulation (about ten minutes + for PyCharm on a 14-core Mac, per the guide); the IDE appears. +4. Eclipse on `linux-arm64` with an empty component cache, which also + closes the libsoup bug for arm64 if the acquisition succeeds, and + Eclipse under emulation with an empty cache, which is the amd64 + acquisition the 0.3.1 repin must prove. +5. `docker-daemon` authorized: from inside the capsule, `docker run` of a + small image, which the guide says is the arm64 variant; confirm with + `docker version`. +6. A `network host` project: the launch falls back to bridge with the + warning the guide describes; the web console reaches `127.0.0.1`. +7. Stop, `project run` again, the session resumes; `devcapsule cleanup` + leaves the Mac's Docker Desktop disk where it was before step 2, within + the base images kept on purpose. + +What a failure looks like is a bug record under `engineering-docs/bugs/` +with the Mac's hardware, macOS and Docker Desktop versions, and the +command's output, as the guide asks adopters to report. + +## Sources + +AWS: [EC2 Mac instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html), +[FAQs](https://aws.amazon.com/ec2/instance-types/mac/faqs/), +[connect to a Mac instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-to-mac-instance.html), +[macOS AMI release notes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/macos-ami-overview.html), +[Amazon DCV on EC2 Mac](https://aws.amazon.com/about-aws/whats-new/2025/11/amazon-dcv-ed2-mac-instances), +[Dedicated Host pricing](https://aws.amazon.com/ec2/dedicated-hosts/pricing/) and a +[third-party reading of the price feed](https://macyou.co/blog/aws-ec2-mac-pricing-explained) +of 2026-09-25. Scaleway: [Apple silicon FAQ](https://github.com/scaleway/docs-content/blob/main/pages/apple-silicon/faq.mdx), +[quickstart](https://github.com/scaleway/docs-content/blob/main/pages/apple-silicon/quickstart.mdx), +[Mac mini M4](https://www.scaleway.com/en/mac-mini-m4/), and a +[price comparison](https://macswarm.com/compare/cloud-mac-pricing/) checked +2026-11-07. Docker on EC2 Mac: [a public runbook](https://github.com/k-k1/agent-fleet/issues/2961) +of 2026-10-29. Hosted runners: [actions/runner-images#9254](https://github.com/actions/runner-images/issues/9254); +Apple's statement that the Virtualization framework does not work inside a +VM: [developer forums](https://developer.apple.com/forums/thread/749809). diff --git a/engineering-docs/releases/v0.3.1/README.md b/engineering-docs/releases/v0.3.1/README.md index 0c8d6451..ac39ec77 100644 --- a/engineering-docs/releases/v0.3.1/README.md +++ b/engineering-docs/releases/v0.3.1/README.md @@ -1,6 +1,6 @@ # DevCapsule 0.3.1 — Release Work -Updated: 2026-11-10. Stage: **candidate 2 (`v0.3.1-rc2` on `be0140ca`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered web console `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open**. +Updated: 2026-11-17. Stage: **rc3 requested; preflight in progress, no rc3 tag or assets published. SSH proxy #47, presentations #43 and preflight correction #48 are merged. Main propagation with preservation is prepared for the human merge.** Driver: **maintenance**. Product owner: Costin Cozianu. [Changelog since 0.3.0](changelog.md) · @@ -14,6 +14,68 @@ and questions; the bug records remain authoritative for individual status, ownership and technical evidence; the maintenance status file links here for resumption. +## RC3 preflight and remaining work — 2026-11-17 + +Verified release tip `918f9fc7` (PRs #43 and #48 now merged), main `dac6b9d4` +(PR #42), and no `v0.3.1-rc3` release. Local receipt commit `579d0e6a` +adds the eight maintenance mails, with no source changes. The owner requested +rc3; no further tag permission is needed once its prerequisites pass. + +### Before rc3 can be published + +- **Correct the integration test's outdated Docker-call expectation.** + `nox -s tests` at `579d0e6a`: 3320 passed, two inherited gid-0 failures, + 1 skipped, 191 deselected, 1 xfailed, 1 xpassed (89.42 s). + `nox -s integration`: 154 passed, 2 failed, 12 skipped (68.28 s), using + the locally rebuilt PEX. The print-command test forbids the read-only + Docker security-options query added by the rootless fix; that failure is + not limited to this capsule and would fail candidate CI. The filesystem + ownership test assumes uid 0 can chown to gid 1, which this restricted + user namespace cannot. The unit failures reject socket gid 0 in the + legacy recursive-orchestrator tests. None was waived or marked passed. + Correction prepared on `ws-maintenance/0.3.1-rc3-preflight` at `87c35bab`: + full integration now passes, **155 passed, 13 skipped** (61.68 s). + The newly skipped ownership case lacks its independently probed host + permission. The local build still stops at the same two legacy gid-0 + unit failures; version, syntax, types (351 files) and conventions pass. + Correction PR #48 is merged at `918f9fc7`, with hosted checks green. +- **Propagate the release into main without undoing main-only work.** + A clean automatic merge would downgrade `0.3.2.dev0` to `0.3.1`, copy + the release-only docs manifest override and delete the November 13 blog, + November 8 Mac testing note and November 8 test-improvements work order. + The owner approved a preservation commit on the otherwise commit-free + PR copy under Release Policy rule 8. `4PR-6-release-0.3.1` preserves + main at `0.3.2.dev0`, retaining the new presentation package-data setting. + The human merges [main PR #49](https://github.com/mycodespace-ai/devcapsule/pull/49); verify canonical remote ancestry + and preserved content before tagging. Never merge main into the release. +- After those prerequisites, tag the exact release commit, follow the + candidate workflow, download its three assets and verify checksum, + manifest and reported identity. A failed candidate is not a published or + accepted candidate. No candidate exception has been invented. + +### Remaining before final 0.3.1 + +| Work | Current evidence / next action | +|---|---| +| Presentations authoring delivery | **Done:** [PR #43](https://github.com/mycodespace-ai/devcapsule/pull/43) merged at `c8b56a07` with hosted checks green; included in release `918f9fc7` and the main propagation PR. | +| One blocking bug: this repository's project configuration | Host-side `project init --regenerate` and `config check`, then commit the refreshed manifest/lock before final. The capsule cannot perform the supported host-only write. | +| All-component freshness review | The owner's November 17 decision extends the review from three agent CLIs to every existing component, for this release too. Record upgraded with evidence, no update needed with reason, or a deferred-update bug targeted at the next release. The old Antigravity hold remains unresolved; the November 9 agent table is not the full sweep. | +| Two release rulings | Published Mac/ARM executable scope; and compatibility-feed hosting. The configured website URL returned HTTP 404 again on November 17. Cache/built-in fallback works by contract, but it does not supply a live feed. Development draft binaries do not settle release scope. | +| Candidate acceptance and bug verification | Resolve the outstanding validation findings; test downloaded candidate bytes, including at least one actual E2E with checksum and selection rationale in `test-runs.json`. Verify the fixed Files-page video behavior in Chrome on a shipped executable before closing that record. Earlier local PEX/feature tests do not substitute for candidate acceptance. | +| Two remaining test-work records | Release-dependent fixtures is confirmed/minor and explicitly not a candidate gate; its target needs reconciliation with the cut's exclusion. Markdown-only gate routing is fixing/major: hosted route/guard merged via #25, local routing and docs-scan debt remain. Do not claim either closed. | +| Documentation and publication | Write `notes.md` with the rendered E2E section, promote the documented version and `docs-0.3.1`, validate documentation, obtain final acceptance, publish/verify final assets, and perform the website candidate/production handoff. | + +**Bug tally:** nine records target 0.3.1: five closed and four unresolved +(one confirmed/blocking, one fixing/major, one confirmed/minor, one +fixed/untriaged awaiting verification). The table in [bugs.md](bugs.md) +contains all nine. Feature PRs, scope decisions and publication tasks are +additional work, not extra bugs. + +**Not 0.3.1 blockers:** the full upgrade experience is committed to the first +release after 0.3.1, whether 0.3.2 or 0.4.0. Sample-project release-gate work +is accepted, but its first enforcing release and criteria remain undecided. +The completed intake questionnaire does not create 18 new 0.3.1 tasks. + ## Headline DevCapsule runs on an Apple Silicon Mac, built from source, with capsules diff --git a/engineering-docs/releases/v0.3.1/bugs.md b/engineering-docs/releases/v0.3.1/bugs.md index 3ecfecc1..09cb899b 100644 --- a/engineering-docs/releases/v0.3.1/bugs.md +++ b/engineering-docs/releases/v0.3.1/bugs.md @@ -3,7 +3,9 @@ [Release overview](README.md) Initial review: 2026-11-07 at the cut, `31e8fec7`. Reconciled before -`v0.3.1-rc2` at `be0140ca`; candidate 2 closures recorded 2026-11-10. The +`v0.3.1-rc2` at `be0140ca`; candidate 2 closures recorded 2026-11-10. Reconciled again for rc3 preparation +on 2026-11-17 at release source `a464088d`: nine records, five closed, +four unresolved, one of them blocking. The linked records own status, severity, target, ownership and technical evidence; this table mirrors those fields for review and records the release's disposition and next action. Update the record and its row together; reconcile @@ -20,10 +22,9 @@ before each candidate and record the reconciliation revision here. | [Web console changes in `v0.3.1-rc1` do not reach capsules: the PEX omits the console package and the self-hosting override shadows it](../../bugs/devcapsule/2026-11-08-webconsole-changes-do-not-ship-without-a-base-rebuild.md) | closed | blocking | maintenance | found 2026-11-08 validating `v0.3.1-rc1` (`accdec5b`): `/files`, `/filetree`, and `/api/project/tree` returned `404`; resolved under `D-0017` via stacked PRs #18 (`b84b06e9`) and #16 (`f2bae5cb`); closed 2026-11-10 on downloaded `v0.3.1-rc2` (`2c3ace0f…`) serving `/files` (`200`), `/filetree` (`307 -> /files`), and `/api/project/tree` (`200`) on pre-PR-#12 `/opt/devcapsule-webconsole/venv` without a DevCapsule checkout mount | none | | [Release-dependent test fixtures cause avoidable release PR churn](../../bugs/devcapsule/2026-10-31-release-dependent-test-fixtures.md) | confirmed | minor | maintenance | test-only; queued for 0.3.1 on 2026-10-31; not a gate of a candidate | the owner keeps it in the cycle or retargets it at planning | | [Unit tests read the developer's real launcher settings inside a capsule: the consent and trust tests fail or prove nothing there](../../bugs/devcapsule/2026-11-10-unit-tests-read-the-capsules-mounted-launcher-settings.md) | closed | blocking | maintenance | filed 2026-11-10 at the owner's direction, to be fixed before 0.3.1 ships: `nox -s tests` in the owner's capsule gives 17 failed on `v0.3.1-rc2`, all passing once the mounted settings are hidden; the hosted run passes; one expected-to-fail test downloads 1.5 GB of vendor artifacts there, most of the local gate's twelve minutes; test-only, the product behaves as designed; resolved in pull request #29, where the 17 pass and `nox -s tests` passes in the owner's capsule, by tests that name or hand in their home; the test that downloaded is rewritten in memory and `--print-command` no longer fetches; the shared fixture is fixed there too, so no unit test sees the capsule it runs in; since `8af31910` no mark depends on the capsule; closed 2026-11-13 on the owner's word after the merge of #29 (`82b9c07e`): `nox -s tests` on the merged tree in the owner's capsule gives the hosted run's counts, 3212 passed | none | -| [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | the owner's review of that branch; then the local gate, and `docs/**` off the list when the legacy scan of `docs/` is retired | +| [Markdown-only changes run the whole Python unit suite: the hosted path filter lists too few non-inputs, and the local gate has no filter](../../bugs/devcapsule/2026-11-10-markdown-only-changes-run-the-python-unit-suite.md) | fixing | major | maintenance | reported by the owner 2026-11-10 and re-rated major; the Python route becomes a short list of inputs, `.github/ci-python-inputs.yml`, and the unit suite is held to it by a guard in `tests/conftest.py`, on `ws-maintenance/python-route-guard` | PR #25 is merged; finish local gate routing and remove `docs/**` from the input list when the legacy docs scan is retired | +| [Console video opened from Files does not play](../../bugs/devcapsule/2026-11-10-console-video-opened-from-files-does-not-play.md) | fixed | untriaged | maintenance | fix merged through PR #35; source-preview Chromium evidence exists, but closure requires the shipped executable | verify playback, seeking, pasted Files URL and unchanged raw policy in Chrome on the candidate | -Added after the `v0.3.1-rc2` reconciliation; the table is not reconciled -again until the next candidate. ## Related work that is not a release gate diff --git a/engineering-docs/releases/v0.3.1/changelog.md b/engineering-docs/releases/v0.3.1/changelog.md index a56f14f5..e489ba1b 100644 --- a/engineering-docs/releases/v0.3.1/changelog.md +++ b/engineering-docs/releases/v0.3.1/changelog.md @@ -6,10 +6,20 @@ new and what is fixed since 0.3.0. Records, workflow rules and the project's own housekeeping are left out on purpose. The adopter notes for the final release, `notes.md`, are written from this file. -No candidate is tagged yet; the cut is 2026-11-07 at `31e8fec7` on `main`. +RC2 is published. RC3 preparation on 2026-11-17 includes the merged fixes +below; no rc3 tag exists yet. Presentations PR #43 is merged. ## New +- **Presentation and recording tools for adopter agents.** The launcher packages + the authoring kit so agents in other repositories can create and export + narrated scenario presentations. Merged through PR #43. + +- **GitHub SSH through the host agent.** An authorized capsule can use GitHub + SSH through a narrow host-side proxy without copying the host's private keys + into the capsule. Merged through PR #47; the Git guide describes setup and + the containment boundary. + - **Apple Silicon Macs, experimental.** The launcher runs natively on an M-series Mac against Docker Desktop, built from source as the macOS guide describes; no macOS executable is published. A project's capsules run @@ -76,6 +86,14 @@ No candidate is tagged yet; the cut is 2026-11-07 at `31e8fec7` on `main`. ## Fixed +- **Rootless Docker launch identity.** The launcher uses the container's root + identity when Docker reports rootless mode, avoiding inaccessible mounted + launcher settings and cache paths. Non-rootless behavior stays unchanged; + the owner verified the rootless fix before candidate packaging. +- **Video playback from Files.** Recordings open in the console's media player + instead of navigating to a raw response whose policy prevents playback. + Candidate-level browser verification remains before bug closure. + - **Codex version and compatibility checks answer again.** `NpmChannel.check()` requests the npm registry's abbreviated install metadata (`Accept: application/vnd.npm.install-v1+json`, ~5.2 MiB for `@openai/codex` diff --git a/engineering-docs/releases/v0.3.1/test-runs.json b/engineering-docs/releases/v0.3.1/test-runs.json index 236cfb3c..8dd6e714 100644 --- a/engineering-docs/releases/v0.3.1/test-runs.json +++ b/engineering-docs/releases/v0.3.1/test-runs.json @@ -51,6 +51,26 @@ "date": "2026-11-10", "result": "passed: 40 passed, 3 skipped in 54.14s", "evidence": "https://github.com/mycodespace-ai/devcapsule/actions/runs/42734994462" + }, + { + "kind": "integration", + "source-revision": "579d0e6a32aeb2e22284b1a99dc0527e0aebd598", + "tests": "nox -s integration; 168 collected, 154 passed, 2 failed, 12 skipped", + "environment": "Linux x86-64 development capsule, Python 3.12.3, uid/gid 0 in a restricted user namespace; short basetemp /var/tmp/rc3i; locally rebuilt PEX, not published candidate bytes", + "operator": "Codex for maintenance", + "date": "2026-11-17", + "result": "failed: 154 passed, 2 failed, 12 skipped in 68.28s", + "evidence": "Scratch log /var/tmp/rc3-preflight/integration.log. test_print_command_names_a_base_image_that_is_not_here_and_pulls_nothing rejects the read-only docker info --format {{json .SecurityOptions}} query added by the rootless fix. test_filesystem_applies_distinct_user_and_group_ids_to_new_directories assumes uid 0 can chown to gid 1; this namespace returns EPERM. Both reproduce the received November 16 release-merge validation report. No Docker container launched; no candidate acceptance claimed." + }, + { + "kind": "integration", + "source-revision": "87c35bab6fb01151437ac40778d4a092d40e4e69", + "tests": "nox -s integration; 168 collected, 155 passed, 13 skipped", + "environment": "Linux x86-64 development capsule, Python 3.12.3, restricted user namespace; basetemp /var/tmp/rc3c; locally rebuilt PEX, not published candidate bytes", + "operator": "Codex for maintenance", + "date": "2026-11-17", + "result": "passed: 155 passed, 13 skipped in 61.68s", + "evidence": "Scratch log /var/tmp/rc3-preflight/correction-integration.log. Print-command fixture permits the exact read-only daemon security-options query while refusing Docker writes. The ownership case independently probes permission to chown to a distinct group and skips when the environment lacks it; other skips are unchanged. No product code changed. Full local build separately reaches 3320 passing unit tests and the same two inherited gid-0 failures, so it is not reported as a passing full gate." } ] } diff --git a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md index b9ee2470..13814389 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md @@ -4,18 +4,127 @@ Mnemonic: `maintenance` Start date: 2026-09-18 -State: active 2026-11-10; releasing 0.3.1 from `release-0.3.1`, cut from `main` at `31e8fec7`; candidate 2 (`v0.3.1-rc2` on `be0140ca`, merged to `main` via PR #22 `aabace3c`) published and verified; all three 0.3.1 release bugs closed (Eclipse libsoup on rc1; launcher-delivered `devcapsule_webconsole` `D-0017` and Codex npm abbreviated metadata on rc2 + `component-status` feed `0bc31c64`); Codex `0.167.0` and Claude Code `2.1.321` shipped in `embedded-33`; two rulings open (Mac/arm64 executables, compatibility feed's website path) plus end-to-end run, `notes.md`, and docs promotion before final `v0.3.1`; the blocking bug of 2026-11-10, unit tests reading the capsule's mounted launcher settings, closed 2026-11-13 on the owner's word after the merge of pull request #29 (`82b9c07e`); one blocking bug open since 2026-11-13, this repository's own project configuration predates 0.3: the refresh is checked on a copy and waits for the owner's `project init --regenerate` on the host; one major bug in fixing, the Python route and its guard, merged through #25 with the local gate's routing open; a follow-up to PR #18 on `ws-maintenance/host-inputs-at-source`, by Pair Review, for the owner's review; rewritten 2026-11-12 on the owner's direction so that host inputs are values and no touched test patches; the rule *Host Inputs* written into `WORKFLOW-LOCAL.md` on the owner's word and the rewrite reviewed by the partner through #28, merged at `83d238b8`; the owner's reading of #26 and rulings on the rule's open readings are next; *Unit Tests* rules 8 and 9 added on the owner's word and held by machine, the command line only in `test_cli.py` with eight files in a debt list, and no network in a unit test; the owner's read-then-decide direction merged through #29, on top of #26: the launch's decisions are testable from values, the holding pen is empty and three files remain in the command-line debt list +State: integrating 2026-11-17; PR #49 from `4PR-6-release-0.3.1` awaits the human merge to main from release `918f9fc7`, including merged SSH proxy #47, presentations #43 and preflight correction #48. Owner approved the preservation-commit exception; main stays at 0.3.2.dev0. Rc3 remains untagged pending the human main merge and remote verification. -Definition read: WORKFLOW.md@196d3760f99e, WORKFLOW-LOCAL.md@94a29cb6eedb +Definition read: WORKFLOW.md@781c9e39df58, WORKFLOW-LOCAL.md@94a29cb6eedb Integration target: `main` Delivery method: ordinary maintenance PRs to `main`; owner merges. No records-only PR. The 0.3.0 release is published; website production promotion remains owner-operated. -Branch association: `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/website-gitlink-actions` from release-0.3.1 2a3d6f61, recursive fetch of the `website` raw gitlink in GitHub Actions, awaiting owner pull request and merge; `ws-maintenance/0.3.1-blocking-bugs` from release-0.3.1 82b9c07e, records of the two blocking bugs, the owner merges; `ws-maintenance/launch-phases` merged through #29 and closed; `ws-maintenance/host-inputs-at-source` merged through #26 and closed; `ws-maintenance/python-route-guard` merged through #25 and closed; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical +Branch association: `4PR-6-release-0.3.1` from release `918f9fc7`, main-integration copy with owner-authorized preservation commit; `ws-maintenance/0.3.1-rc3-preflight` from release `bf4fa1f0`, integration-test corrections merged through PR #48 at `918f9fc7`; `release-0.3.1` from main 31e8fec7, the workstream's selection from the cut to the final tag; `ws-maintenance/website-gitlink-actions` from release-0.3.1 2a3d6f61, recursive fetch of the `website` raw gitlink in GitHub Actions, awaiting owner pull request and merge; `ws-maintenance/0.3.1-blocking-bugs` from release-0.3.1 82b9c07e, records of the two blocking bugs, the owner merges; `ws-maintenance/launch-phases` merged through #29 and closed; `ws-maintenance/host-inputs-at-source` merged through #26 and closed; `ws-maintenance/python-route-guard` merged through #25 and closed; `ws-maintenance/pile-of-ideas` merged through #23 and closed; `ws-maintenance/0.3.1-agent-freshness` merged through #21 and closed; `ws-maintenance/codex-npm-metadata` merged through #20 and closed; `ws-maintenance/webconsole-legacy-tests` merged through #18 and closed; `ws-maintenance/webconsole-delivery` merged through #16 and closed; `ws-maintenance/move-to-organization` merged through #1 and closed; `ws-maintenance/base-consent-test` from main 445469f1; `ws-maintenance/coverage-in-pr` merged through #336 and closed; `ws-maintenance/test-conventions` merged through #335 and closed; `ws-maintenance/0.3.1-preparation` from main 31d44fa4; `release-0.3.0` closed after final publication and retained with its tags; `ws-maintenance/0.3.0-acceptance` merged through #332 and closed; earlier slice branches are historical Requirements: `R-PRODUCT-006`, `R-COMPAT-001`, `R-PRODUCT-002`, `R-CONSOLE-001` +## Main propagation with version preservation — 2026-11-17 + +The owner approved the requested exception to Release Policy rule 8: +"Yes, please prepare the push of changes to main without changing main's +version." The integration copy may carry the preservation commit; this does +not authorize an agent merge into main or a change to release version 0.3.1. + +Fetched canonical refs: main `dac6b9d4`, release `918f9fc7`. Both presentations +PR #43 (`c8b56a07`) and integration correction PR #48 (`918f9fc7`) are merged. +The release tip is the parent of `4PR-6-release-0.3.1`; no main synchronization +is performed on the release branch. Main's workflow text differs only in its +version; retain the existing definition, not a workflow refresh. + +The integration copy preserves `0.3.2.dev0` with the supported bump command, +including both workflow stamps, while retaining the presentation package-data +addition to pyproject.toml. It preserves main's docs manifest, the three +main-only documents and their blog/index entries. Release source and runtime +changes, including SSH proxy and presentation tools, otherwise stay intact. +[PR #49](https://github.com/mycodespace-ai/devcapsule/pull/49) targets main; +inspect its hosted checks before the human merge. +Then fetch, verify main ancestry and contents, return to the release branch, +and tag the release commit as rc3 under the owner's existing authorization. +Never tag the integration copy or main's merge tip. + +Pre-push validation of the integration copy: clean prospective main merge +produces exactly the branch tree; main version/stamps, manifest and all three +preserved documents match main, and presentation package data and index entries +are present. Required local build: version and syntax pass, mypy 360 files, +conventions 0 breaches; unit suite 3367 passed, two inherited gid-0 failures, +1 skipped, 194 deselected, 1 xfailed, 1 xpassed. Full local build is not green. +The remaining sessions pass: CLI/PEX smoke, docs contract 251 pages (devel +0.3.2.dev0), console 474 tests. Integration retry against the rebuilt PEX: +158 passed, 13 skipped in 62.11 s. The first integration attempt exhausted +/var/tmp; /opt was read-only; neither failed setup run counts as validation. +The successful run used verified writable disk-backed /home/devcapsule/rc3i. +Logs are disposable scratch under /var/tmp/rc3-main. No containers launched. +The main PR's hosted checks must pass; the two local failures stay disclosed. + +## RC3 preparation and accepted intake — 2026-11-17 + +Preflight correction slice, based on release `bf4fa1f0`: the print-command +integration fixture now answers the exact read-only security-options query +and still refuses every modifying Docker command; its assertions require +image inspection and allow that identity read. The filesystem integration +test checks its required distinct-group chown capability on a separate probe +before calling the product, skipping only when the host lacks that permission. +Validation on `87c35bab`: full `nox -s integration` passes (155 passed, +13 skipped, 61.68 s); focused files 4 passed, 10 skipped. The required local +build passes version/syntax, mypy (351 files), conventions (0 breaches), then +stops with 3320 passing unit tests and the same two inherited gid-0 failures +(1 skipped, 191 deselected, 1 xfailed, 1 xpassed, 87.12 s). Later build steps +were not reached in this run. No product behavior or legacy unit test is changed. This does not waive the +two rootless-local legacy unit failures. Delivered through PR #48, now merged +into the release at `918f9fc7`; its hosted checks passed. + +The owner completed all 18 project-management intake decisions, then selected +maintenance to cut rc3 and tally the work left for 0.3.1. Project-management is +paused with its answers recorded and published. No questionnaire remains. + +Synchronization: fast-forwarded this release branch from its own canonical +remote to `a464088d` (PR #47). Did not merge main into a release branch. Main +is `dac6b9d4` (PR #42); its definitions differ only in the development version. +The release rule overrides the older CLI's generic synchronization advice. + +Current release facts and remaining work are maintained in +[the 0.3.1 overview](../../releases/v0.3.1/README.md). Local unit preflight at +`579d0e6a`: 3320 passed, two known failures rejecting Docker gid 0 in +`tests/test_recursive_orchestrator.py`; 1 skipped, 191 deselected, 1 xfailed, +1 xpassed. The full output is reproducible scratch at +`/var/tmp/rc3-preflight/unit.log`, not release acceptance evidence. PR #47's +hosted checks passed; PR #43 also passed hosted checks and is now merged. + +The main-preservation constraint is implemented on the integration copy under +the explicit owner exception recorded above. The earlier scratch patch is +superseded: presentations added package-data settings since it was prepared, +so restoring the old whole pyproject.toml would discard shipped functionality. +Only its authored version was changed by the bump command. + +Eight mails were received at `579d0e6a`; their full bodies remain in that +commit. All are acknowledged in the disposition log with these obligations: + +- SSH proxy delivery and its main-preservation constraint belong to this + release. The earlier rootless propagation request is satisfied by PR #42 + on main and PR #38/#39 on the release; preserve the owner's closure. +- Presentations PR #43 is an owner-directed 0.3.1 dependency, reviewed and + merged at `c8b56a07`. Maintenance integrates the delivered slice; + it does not duplicate presentations implementation. +- The upgrade experience is mandatory in the first release after 0.3.1, + whether called 0.3.2 or 0.4.0. Carry this obligation into the next cut; + do not treat it as a 0.3.1 gate or invent the next version number. +- Before accepting every release, including 0.3.1, review every existing + component. Each gets exactly one recorded outcome: upgraded with evidence; + no update needed with reason; or deferred with an open bug targeted at the + next release. An unsuccessful check is not proof of no update. Bind the + exact next version when the owner names it. Component-upgrades owns the + automation inventory with component-catalog support; full automation is + not a condition of this release. The release driver owns the sweep table. +- Sample-project release-gate work is accepted for later design with + sample-projects: maintain the project list, run each project end to end, + update it, then provide recordings/presentations. Maintenance owns release + acceptance integration. The first enforcing release and pass criteria + remain undecided; this is not silently a 0.3.1 blocker. The complete work + order is retained in the received maintenance-intake-decisions mail at + `579d0e6a`, pending normal integration of project-management's canonical + `engineering-docs/work-orders/2026-11-17-sample-project-release-gate.md`. +- Historical intake links are repaired to their immutable pre-disposition + source. No bug status changes. The release-merge validation mail's known + unit/integration failures stay explicit; local preflight checks them again. + ## A launch's preparation in three phases: read, decide in memory, write — 2026-11-12 Owner direction, 2026-11-12, on the 17 standing failures: the processing of @@ -2892,6 +3001,9 @@ begin the rewrite until project-management assigns it. ## Current State +Current as of 2026-11-17: preparing rc3; see *RC3 preparation and accepted intake* +above and the release overview. The dated entries below are historical. + **2026-10-28: VS Code as an IDE surface implemented, smoked and reviewed; PR #301 ready.** Item 3 of [the scope decision of 2026-10-27](../2026-08-09-project-management/2026-10-27-decision-release-0-3-0-scope-at-rc8.md), on `main`: Visual Studio Code joins 0.3.0 as a second provider of @@ -4588,11 +4700,14 @@ launch was taken into intake and committed. No source was changed. ## Planned Next Step -Current: 0.3.0 delivery is complete. Maintenance is ready for 0.3.1 -planning from the queue above; the -release-independent fixture bug is the proposed first implementation slice. -No repeat 0.3.0 product testing is needed without new evidence of a problem. -Historical candidate sequencing below must not override this direction. +Current, 2026-11-17: PR #49 from `4PR-6-release-0.3.1` carries the validated +main propagation and approved preservation commit. Verify hosted checks and +await the human merge. Fetch +and verify main contains release `918f9fc7` with version `0.3.2.dev0` and its +main-only documents intact. Then return to `release-0.3.1` and cut rc3 from +the release commit, still version `0.3.1`. Both #43 and #48 are merged. Rc3 +is already authorized; no repeat tag question is needed. Historical steps +below do not override this direction. 1. The network-node slice, on `ws-maintenance/0.3.0-network-node` from the release branch, a pull request into it with the reviewer loop; @@ -5439,6 +5554,16 @@ claimed. No final release or graphical/end-user acceptance is claimed yet. ## Open Threads +Current, 2026-11-17 (supersedes stale release/PR claims below): rc3 is not cut. +The owner approved the main-preservation commit; `4PR-6-release-0.3.1` is the +main PR copy. Its human merge and remote verification are the next dependency. +PRs #43 and #48 are merged. Four 0.3.1 bug records remain unresolved, including +one blocking host-side project-configuration refresh. The release overview +owns the tally, two release rulings and acceptance/publication tasks. The two +inherited gid-0 legacy unit failures remain disclosed. All 18 PM intake answers +are recorded. Scratch patches/logs are reproducible; credentials and tokened +links are not preserved. + - Blocking for 0.3.1, filed and closed 2026-11-15 (PR #38 merged into `release-0.3.1` at `2a3d6f61`): when `docker info` reports - Website raw gitlink in GitHub Actions, 2026-11-16 (`ws-maintenance/website-gitlink-actions` diff --git a/engineering-docs/wip/2026-09-18-maintenance/configuration-contract.md b/engineering-docs/wip/2026-09-18-maintenance/configuration-contract.md index 1c15ef69..2283efef 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/configuration-contract.md +++ b/engineering-docs/wip/2026-09-18-maintenance/configuration-contract.md @@ -458,7 +458,7 @@ The following are outside the implemented V1 correction and remain explicit: defaults are adopted architecture without a complete implemented interface. - The missing-platform-lock consumer experience and the exact project/local mutation boundary of regeneration retain the project-artifact ownership defined by the - [earlier owner-accepted interim behavior](../../wip/2026-08-09-project-management/intake/2026-09-06-component-catalog-init-regenerate-versus-config-semantics.md). + [earlier owner-accepted interim behavior](https://github.com/mycodespace-ai/devcapsule/blob/9443bdc69d15df7514e13e8e3ded2f3a8720dd51/engineering-docs/wip/2026-08-09-project-management/intake/2026-09-06-component-catalog-init-regenerate-versus-config-semantics.md). The owner's instruction to implement this contract supersedes the part that conflated reading an existing recommendation with local consent. - Identity relocation, fully specified retention/restore semantics and the diff --git a/engineering-docs/wip/2026-09-18-maintenance/intake-dispositions.md b/engineering-docs/wip/2026-09-18-maintenance/intake-dispositions.md index e5d6f1c6..24c7609a 100644 --- a/engineering-docs/wip/2026-09-18-maintenance/intake-dispositions.md +++ b/engineering-docs/wip/2026-09-18-maintenance/intake-dispositions.md @@ -41,3 +41,12 @@ undispositioned, or listed below, meaning resolved. Never both, never neither. | `2026-10-30-project-management-user-docs-0-3-0-cli-alignment.md` | 2026-10-30 | acknowledged | Accepted for immediate 0.3.0 execution across five `<= 10`-file Pair Review batches (`Antigravity` + `Codex / gpt-6-astra`) on `release-0.3.0`: file-by-file 0.3.0 CLI alignment, full 0.3.0 authoring of all 12 `status: planned` stubs, and human-English prose cleanup; PR #316 verified on `main` at `ebab228a`. | | `2026-11-10-project-management-console-video-does-not-play-from-files.md` | 2026-11-16 | acknowledged | Acknowledged; the bug record is on `release-0.3.1` with `status: fixed` and `target: 0.3.1` after PR #35 (`6ff6bf18`), awaiting browser verification before closure. | + +| `2026-11-16-github-auth-release-delivery.md` | 2026-11-17 | acknowledged | PR #47 merged; preserve main development version, manifest and three main-only documents during propagation; two inherited unit failures remain disclosed. | +| `2026-11-16-github-auth-rootless-propagation.md` | 2026-11-17 | acknowledged | Superseded by completed rootless propagation through PR #42 to main; preserve owner-verified release closure. | +| `2026-11-16-presentations-authoring-for-0-3-1.md` | 2026-11-17 | acknowledged | Accepted 0.3.1 dependency; PR #43 awaits human merge; no duplicate implementation. | +| `2026-11-16-presentations-reviewed-authoring-pr-43.md` | 2026-11-17 | acknowledged | Reviewed deliverable accepted for the release; verified PR #43 open with successful checks on 2026-11-17. | +| `2026-11-16-project-management-upgrades-next-release.md` | 2026-11-17 | acknowledged | Mandatory first release after 0.3.1 (0.3.2 or 0.4.0); retain next-cut obligation; not a 0.3.1 gate. | +| `2026-11-16-release-merge-validation.md` | 2026-11-17 | acknowledged | Accepted known failures into release validation follow-up; fresh rc3 preflight recorded in release overview and test-run record. | +| `2026-11-17-project-management-disposed-intake-links.md` | 2026-11-17 | acknowledged | Applied the two immutable historical-link repairs without changing bug status. | +| `2026-11-17-project-management-maintenance-intake-decisions.md` | 2026-11-17 | acknowledged | Every-release all-component sweep accepted, including 0.3.1 acceptance; deferred upgrades require next-release bugs. Sample-project release gate accepted for later design; first enforcing release remains undecided. Full work order retained at receipt commit 579d0e6a. | diff --git a/engineering-docs/wip/2026-11-16-github-auth/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-16-github-auth/CURRENT-STATUS.md new file mode 100644 index 00000000..9aaf44ca --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/CURRENT-STATUS.md @@ -0,0 +1,494 @@ +# Workstream Current Status: GitHub Authentication + +Mnemonic: `github-auth` + +Start date: 2026-11-16 + +State: paused; Pair Review complete; PR #47 targets release-0.3.1; two inherited unit-gate failures remain. + +Definition read: WORKFLOW.md@196d3760f99e, WORKFLOW-LOCAL.md@94a29cb6eedb + +Branch association: `ws-github-auth/ssh-proxy`, from canonical `upstream/main` at `1942f396`. + +Integration target: `release-0.3.1` (owner direction, 2026-11-16) + +Delivery method: pull request with Pair Review; the human merges. + +Requirements: R-PRODUCT-002 (explicit host boundaries), R-PRODUCT-003 (durable memory). + +## Goal and accepted scope + +GitHub Git operations inside a capsule use the host's existing SSH authentication +through a proxy owned by the outside launcher. Private keys remain on the host. +The owner selected the new `github-auth` workstream and Git over SSH first on +2026-11-16 through the console decision. HTTPS and `gh` API authentication are +outside this slice. Review partner: Antigravity, `gemini-4-hydrogen-high`. + +## Current state + +The owner directed completion of Pair Review and delivery to release-0.3.1 on +2026-11-16. Antigravity Gemini 4 Hydrogen High completed round 2 at `455d3acc`. +The implementor inspected and accepted its diff, posted an assessment, and merged +[review PR #44](https://github.com/mycodespace-ai/devcapsule/pull/44) at `9638cb11`. +[Implementation PR #47](https://github.com/mycodespace-ai/devcapsule/pull/47) +now targets `release-0.3.1`; its title and description state the scope and checks. +The prescribed GitHub CLI is installed and authenticated as `ccozianu`. + +Combined validation: 64 focused cases passed; types (351 files), conventions, +CLI smoke, PEX build/smoke, docs contract (249 pages), and 474 console tests passed. +The full gate had 3320 passed and two inherited recursive Docker gid-zero failures. +The rebuilt PEX passed a real GitHub read through the inherited broker with an +empty HOME; the missing-socket control failed with exit 128. No new container, +GitHub write, physical-host restart or launcher replacement occurred. + +Package/workflow version files and docs/versions.yaml match release-0.3.1 exactly. +The release baseline is already an ancestor. Do not merge main into this slice: +its next-development version does not belong here. Unrelated main-only documents +were removed from the release-targeted tree, with their index entries. +The bump command refused the lower version; restoring the three exact release +files implements the owner's release-target decision without changing workflow +rules or the installed workflow declaration. This is a recorded tooling gap. + +The owner explicitly requested finishing the existing PR cycle and retargeting it; +PR metadata was updated with the inherited failures disclosed after the required +unit/full-gate run. This does not waive the failing release-acceptance gate. +No open bug is owned by github-auth; mailbox and intake were empty at finish. +Sent maintenance `2026-11-16-github-auth-release-delivery.md` by coordination mail, +carrying the owner-selected release target, test results and main-propagation +preservation constraint. The review worktree was removed; its branch is pushed. +Earlier sections below are historical evidence, including superseded main targets, +CLI absence and pending-review statements. Current disposition is above and in the +[final review record](evidence/2026-11-16-final-review.md). + +## Implementation and evidence + +The initial Linux/WSL implementation includes the GitHub-only request validator, +launcher-owned Unix socket broker, capsule Git adapter, optional `github-ssh` +authorization, launch mount/environment wiring and user documentation. It does not +copy private keys or forward the host agent. The socket grants all GitHub Git +repositories available to the host identity. Docker Desktop transport is deferred +and explicitly refused. GitHub aliases, Git LFS authentication, SSH signing and +HTTPS/API credentials are not implemented in this slice. + +Focused validation: 42 tests pass, including real Git clone/fetch/push through a +fixture SSH process, binary streaming, refusal, deadline, shutdown and authorized +Docker arguments. Initial mypy over the touched import graph passed (157 files). +The full build gate reached the unit suite: 20 failed, 2917 passed, 1 skipped, +14 xfailed and 7 xpassed. A selected rerun on an archive of unchanged +`upstream/main` reproduced 19 of those failures; the added authorization exposed +one exact-vocabulary legacy test. That file was refurbished into its proper +module mirror, preserving its contracts in 20 passing cases. The original gate +attempt failed in pytest setup because +`/opt` is read-only and `/opt/devcapsule-gate` does not exist. Scratch now uses +`/home/devcapsule/.cache/devcapsule-gate/github-auth` per the local rule allowing +another directory with space. No Docker containers or real credential files changed. + +Additional checks: CLI smoke, PEX build and smoke, and documentation contract +pass. The console gate identified a mirrored authorization-table omission; after +alignment, all 458 console tests pass. A read-only live `git ls-remote` through +both the source adapter and the built PEX returned GitHub HEAD `1942f396`. +That used the current capsule's already-installed SSH credentials on the broker +side; it is not physical-host/capsule acceptance evidence. + +The implementation and review branches are pushed to canonical upstream. +Gemini Hydrogen completed local round 1 at `388f62a3`. Its corrections remain +on the separate review branch for PR delivery. A temporary combined merge passed +75 focused cases, type checking and conventions (zero breaches), then was aborted. +Git connectivity integrity and authenticated fetch/push checks pass. The original +checkout remains untouched. Review evidence and prepared PR text are indexed below. + +## Planned next step + +Review the two disclosed inherited gate failures with maintenance before release +acceptance. The human merges PR #47 into release-0.3.1; consult live hosted checks +at that time. After the owner reports the merge, fetch and verify the release +contains this tree. Maintenance owns carrying the release to main. Do not conclude +this workstream until remote main contains the finished tree. +Pair Review is complete; do not restart it or repeat the recorded E2E without a +new change or unresolved concern. The review branch remains pushed. + +## Rootless Docker fix propagation + +The owner's first host relaunch failed with an unwritable PEX cache and permission +denied on `/etc/devcapsule/home/settings.toml`. Fetched canonical `release-0.3.1` +and identified `a1a54eba3098eb3c80fd78ef3e483d1bb5314466`, merged in PR #38 and +recorded as owner-verified on the target host by `8bd56eb3`. Neither current main +nor this feature branch included it. Main has no new commits to synchronize. + +Applied that fix's deliverable/test patch, without release version changes or +another workstream's records, under the owner's explicit propagation request and +WORKFLOW-LOCAL.md's release-fix propagation exception. The branch predates the +release's CapsuleUser refactor: adapted its `command` correction to the existing +`foreground_command`, and its `owner_changes` correction to `prepare_filesystem`. +Rootless launches use container 0:0 (the host user's mapped identity), map the +Docker socket group and home accordingly, and avoid redundant gosu/chown under +dropped capabilities. Rootful behavior is preserved. The available Docker daemon +reports `name=rootless`; no container was launched for this propagation. + +Checks so far: 151 focused tests passed, then all 12 GitHub proxy integration +cases passed after extending socket-grant coverage to both daemon modes. The +full gate's type check passed over 340 files; conventions found zero breaches. +New pure identity tests and filesystem preparation tests cover the adaptation. +Full gate: 19 failed, 2942 passed, 1 skipped, 78 deselected, 14 xfailed, +7 xpassed. All 19 failure IDs match the previously reproduced mainline/environment +baseline exactly; no new failure IDs. Packaging/smoke is run separately because +the full gate stops at pytest. The separate PEX build and executable smoke passed (14 seconds). The imported +rootless detector reports True against the available daemon. Fix commit: `d6fd93e0`. +The rebuilt artifact identity follows below. The owner subsequently relaunched +successfully; the resumed-session observations are recorded below. +Mainline integration and the separate Gemini review branch remain pending. + +## Earlier host relaunch handoff (superseded artifact) + +The owner explicitly chose a development-build self-hosting experiment. The normal +host launcher is not replaced and remains the recovery route; no saved project +configuration is changed by the run-once command. Reuse the same checkout and its +existing persistent state. The original checkout still has only its pre-existing +website gitlink modification. Main remains unchanged; synchronization can wait. + +Build: `.venv/bin/python -m nox -s pex` passed, including shell syntax, packaging +and executable smoke. Built from clean `d6fd93e0ba6c18915ace45b9dfef2881068d7b39` with the rootless Docker fix. +The local PEX reports `v0.3.2.dev0-local-linux-x86_64` with revision `unknown` by +local-build policy; the clean Git revision and checksum here identify its inputs +and bytes independently. It contains the committed implementation, including the +node-registry and console-table fixes. Review corrections at `388f62a3` remain on +the separate review branch and are not included; their PR merge is still pending. + +SHA-256: `33c3c7bc7fe6ff6772eedee06424c95afcf4aebddca20ab99f9a31a7c103d35b`. + +Capsule artifact: `/home/devcapsule/worktrees/github-auth/devcapsule-src/dist/devcapsule-local.pex`. +Host artifact (from Docker mount inspection): +`/home/costin/.local/share/devcapsule/projects/by-path/fe326e03c822-devcapsule/home/worktrees/github-auth/devcapsule-src/dist/devcapsule-local.pex`. +Checksum and build metadata are saved beside it, outside Git. + +Retry the same command with the replacement file. After exiting Codex and stopping +the current capsule normally, run on the host: + +```sh +cd /opt/costin3/myProjects/devcapsule +/home/costin/.local/share/devcapsule/projects/by-path/fe326e03c822-devcapsule/home/worktrees/github-auth/devcapsule-src/dist/devcapsule-local.pex project run \ + --no-update-check \ + --authorize github-ssh true \ + --authorize network host \ + --authorize docker-daemon host-socket +``` + +Keep that outside launcher running throughout the resumed session: it owns the +broker. Host OpenSSH must already authenticate noninteractively to GitHub and +trust its host key. A key without a passphrase needs no SSH agent. + +Inside the relaunched capsule: + +```sh +cd /workspace/301e4208ef81-ChatGPT_Codex +codex resume 01a1e25b-6b76-72d0-b311-614d6adca912 +``` + +The session file exists under ~/.codex/sessions and Docker inspection shows +~/.codex backed by the persistent Codex component home. Installed CLI help +supports explicit session IDs. Conversation/history is resumable; process state +and outstanding tool sessions are not. The feature checkout remains +`/home/devcapsule/worktrees/github-auth`, on `ws-github-auth/ssh-proxy`. + +Resume checks before E2E: read this record, fetch upstream, inspect live workflow +state, claim the slice, check the PEX checksum, verify +`DEVCAPSULE_GITHUB_SOCKET=/run/devcapsule-github.sock` and that it is a socket, +then perform an authenticated GitHub read through the adapter. Fresh E2E homes +must have no copied key; the recording harness must authorize github-ssh for its +fresh project. Do not use this current capsule's manually installed key as proof +of the proxy. No E2E container was launched during handoff preparation. + +## Resumed-session readiness, 2026-11-16 + +The owner resumed inside the rebuilt capsule. Running `/opt/devcapsule/bin/devcapsule.pex` +and the saved local PEX both match the SHA-256 above. Runtime identity is 0:0 and +Docker reports `name=rootless`. The canonical proxy socket exists, and Git's SSH +command points to the shipped `github-ssh` adapter. + +A read-only `git ls-remote git@github.com:mycodespace-ai/devcapsule.git HEAD` +returned `1942f396dd11ffabb64784eb7279f283181e32dd`. Repeating it from a fresh empty +HOME with system/global Git configuration disabled and the adapter explicitly +selected also passed. Pointing that invocation at a missing socket failed with +exit 128. This demonstrates proxy authentication independently of the manually +installed capsule key; it does not yet prove a new child capsule's inheritance. + +Docker mount inspection resolves the inherited socket to the outside launcher's +host socket, and resolves both the persistent E2E workspace root and PEX directory +to host-backed paths. Docker access, Git, pytest and nox are available. No new +container was started for this preflight. Canonical main was fetched: this branch +is ten commits ahead and zero behind, so no synchronization is needed. Mail and +intake remain empty. + +Recording preparation remains: author the GitHub showcase scenario and its Markdown +procedure, explicitly grant github-ssh in its fresh project, and prepare Playwright. +This capsule has neither local Playwright nor FFmpeg nor `/opt/playwright`; the +existing recorder supports Chromium/FFmpeg in a child with `browser-automation`. +The scenario must request that component, verify a real SSH Git checkout from +outside the recorded UI, retain video/screenshots/action evidence, and clean up. +No nested E2E or recording has run yet. No additional host credentials or restart +are indicated by the preflight. The outside launcher must stay running. + +## Recorded E2E acceptance, 2026-11-16 + +One fresh VSCodium capsule, with browser-automation and explicit github-ssh +consent, was launched by the saved PEX from this capsule. The outer physical-host +launcher remained alive. Child and parent Docker inspection showed the same host +broker source, mounted read-only at the canonical socket. The child had no SSH +files or agent; its delivered runtime checksum matched the tested PEX. + +Through the actual recorded terminal, Git cloned the canonical repository over +SSH. Independent Git inspection of the host-backed checkout confirmed expected +HEAD `1942f396dd11ffabb64784eb7279f283181e32dd`, the SSH origin, a clean tree and +the README. A missing-socket read failed with exit 128. Ordinary proxy access +succeeded again afterward. This proves recursive proxy inheritance on this +rootless Linux host. No GitHub write was made. + +Evidence preserved at `devcapsule-src/tests/e2e/evidence/github-ssh-proxy-pre-merge/`. +The 38.17-second WebM, full desktop capture, poster, action trace, `run.json`, +`verification.json` and `result.json` are retained outside Git. The test-owned +container, fresh workspace and checkout records are independently confirmed gone. +The controller gained optional per-scenario surface needs/consents and a bounded +interactive phase; the product PEX was not changed. All 62 existing recorder tests +passed. See the procedure for the on-screen empty-directory check correction and +a minor final command/output overlap, both retained in the original recording. + +Full gate for the recorder change: 19 failed, 2942 passed, 1 skipped, 78 deselected, +14 xfailed and 7 xpassed. All 19 failure IDs exactly match the recorded baseline. +Types passed over 340 files; the corrected convention check found zero breaches. The initial attempt +used the stale default origin/main comparison and stopped on three unrelated +convention differences. The corrected run used DEVCAPSULE_DIFF_BASE=upstream/main. Its log is retained at +`~/.cache/devcapsule-gate/github-auth-showcase-build-upstream.log`. + +## Full release merge, 2026-11-16 + +The owner authorized merging release-0.3.1 into this published feature branch. +Use a merge, preserving both histories. Canonical main remains unchanged and needs +no separate synchronization. The fetched release tip is `10e7fda3` (PR #40). +Resolve the overlap with the earlier port by taking the release's CapsuleUser and +filesystem implementation; retain the feature's extra mixed-ID/rootless coverage +on those APIs, combine authorization coverage and review history, and keep the +feature branch's development version. No release ref or other checkout is edited. + +The imported workflow now keeps scenario recordings outside build output. Copied +the completed first recording to `devcapsule-src/tests/e2e/evidence/github-ssh-proxy-pre-merge/` +before rebuilding so the evidence survives a clean build. The imported host-input +and test rules also apply to this combined tree. The combined unit gate reports 3309 passed, 3 failed, 1 skipped, 187 deselected, +1 xfailed and 1 xpassed. The three failure IDs are a subset of the previous 19: +unmountable staging and the two recursive dry-run cases (host Docker gid 0). +No new failure ID. Types and conventions passed. All 41 focused identity, +filesystem, authorization and proxy integration cases passed. The first focused +invocation used the repository root instead of devcapsule-src and triggered the +new repository-input guard on an editable-install metadata path; correcting the +working directory followed the declared validation setup. No guard was disabled. +Merge commit: `7fc77f24df45135770160c35f193c9abb78cd9c0`, with parents +`ab1e30f9` and `10e7fda3`. The complete fetched release tip is an ancestor, not a +patch port. Packaging and executable smoke passed, as did CLI smoke, documentation +contracts, console types and all 474 console tests. Integration initially returned +149 passed, 12 skipped and 3 failed; shortening the scratch path fixed the Unix +socket path-length failure (targeted rerun: 1 passed). Two failures remain. + +All five remaining failures (three unit, two integration) reproduce on an untouched +archive of release `10e7fda3`, with its own separately built PEX where required: + +- `test_host_daemon.py::test_unmountable_staging_fails_loudly`: persistent-home + scratch is mountable, contrary to the fixture expectation. +- `test_recursive_orchestrator.py::test_public_dry_run_is_unique_redacted_and_cleans_owned_staging` + and `test_contained_display_dry_run_forwards_no_host_x11`: Docker socket gid 0 + is rejected by the recursive host positive-ID check. +- `test_print_command_cli.py::test_print_command_names_a_base_image_that_is_not_here_and_pulls_nothing`: + rootless detection adds Docker info to the fixture's expected image-inspect calls. +- `test_runtime_entrypoint_cli.py::test_filesystem_applies_distinct_user_and_group_ids_to_new_directories`: + the rootless/dropped-capability environment cannot chown gid 1 despite uid 0. + +The gate is not green. Sent these reproductions to maintenance as +`2026-11-16-release-merge-validation.md` on coordination (`815e42e7`). Logs remain +under `~/.cache/devcapsule-gate/github-auth-release-*`. No tests were disabled. + +### Rebuilt merged artifact and acceptance + +Built with `.venv/bin/python -m nox -s pex` from clean merge `7fc77f24`. +The artifact path and host path in the earlier handoff remain valid; its bytes +and adjacent checksum/build metadata are now replaced. SHA-256: +`af7fa02ca2c2737f3a1678226341312682b71cfdd37eb892f29a42ad5c31b78c`. +Review corrections at `388f62a3` are still excluded. + +A new VSCodium capsule launched with that merged PEX passed real GitHub SSH clone +acceptance: expected HEAD `1942f396`, SSH origin, clean tree, no child SSH files or +agent, canonical read-only host broker mount, and exact delivered PEX checksum. +The IDE window and console token guard passed. A missing-socket control failed +with exit 128. The test container, workspace and checkout records were removed. +Evidence and executable reproduction script are retained outside Git at +`devcapsule-src/tests/e2e/evidence/github-ssh-proxy-release-merge/20261116T100132Z/`. +This repeat saved machine-readable evidence; the earlier showcase video remains +preserved separately and depicts the earlier PEX, not the merged build. + +The outside launcher/broker is still the earlier `33c3c7bc` PEX. Its GitHub broker +and transport sources are unchanged by the merge. This run validates the merged +child launcher/runtime against that live broker; a physical-host restart with the +merged PEX has not been performed. Canonical main is unchanged, so separate main +synchronization remains unnecessary for this slice. + +## New merged-build recording, 2026-11-16 + +The owner requested a new recording after selecting the feature branch in the +primary checkout. The running capsule's PEX now matches the merged artifact: +`af7fa02ca2c2737f3a1678226341312682b71cfdd37eb892f29a42ad5c31b78c`, built from +`7fc77f24`. This supersedes the earlier outer-broker restart limitation. + +One fresh VSCodium capsule with browser-automation and explicit github-ssh consent +passed the recorded journey. The real terminal showed zero SSH files, no agent, +and a connected proxy, cloned the canonical repository, and displayed its SSH +origin and commit. The missing-socket read failed with exit 128; the normal proxy +read then succeeded. Each network command finished before the next command. +Independent Docker and Git checks verified both capsule runtimes' checksum, the +same read-only host socket, no child SSH mount/files/agent, expected GitHub HEAD +`1942f396`, clean tree, and README. Container, workspace and checkout records were +independently confirmed removed. No GitHub write was made. + +New evidence in this primary checkout: +`devcapsule-src/tests/e2e/evidence/github-ssh-proxy/20261116T103152Z-af7fa02c/`. +The movie is `scenario-video.webm`: 545 frames at 12 fps, 45.42 seconds, +2,116,032 bytes; SHA-256 +`57457f07f8b40fcbfa3e3d2dff4a99584829f616b68b6c6e4552587dec6ba5ee`. +Full capture, poster, screenshots, action trace, executable reproduction scripts, +run provenance, verification and cleanup results are retained alongside it. +Host directory: +`/opt/costin3/myProjects/devcapsule/devcapsule-src/tests/e2e/evidence/github-ssh-proxy/20261116T103152Z-af7fa02c/`. +Evidence is outside build output and ignored by Git. Prior recordings remain in +the earlier detached worktree; no prior evidence was overwritten. + +This task changed records only and used the already validated merged PEX; the +full gate was not rerun. Its inherited failures and pending review corrections +remain as documented above. The new E2E and encoding passed on their first run. +The initial script-extraction command used the wrong working-directory-relative +path and was corrected before any E2E launch; no failed product run was discarded. + +## Live console presentation, 2026-11-16 + +The owner explicitly authorized investigating presentation behavior in this +checkout and documenting the cross-scope findings while adding the SSH showcase. +The workstream selection remains github-auth. No main synchronization is needed: +this follows the same fetched main and the same validated recording. + +The live console discovers `presentation.json` beneath its mounted project and +serves named media through `/api/project/raw`. It does not generate metadata. +Scripted replay generates the document when given a script and numbered actions; +interactive serve/ctl does not. The earlier recording was interactive. The +example URL under website/_site names website output relative to the project; +there is no single required presentation assets directory. Outside worktrees and +symbolic links are not discovery paths. These distinctions and source locations +are now explicit in PRESENTATIONS.md and the scenario-recording guide. + +Added a six-step Markdown script and a producer using the shared presentation +module. The chapter boundaries come from the recorded controller responses and +are bound to the existing movie checksum. The producer writes presentation.json +beside run `20261116T103152Z-af7fa02c`; no recording was rerun or altered. It is +visible immediately on the current console's Presentations page, with route: +`/presentations/devcapsule-src/tests/e2e/evidence/github-ssh-proxy/20261116T103152Z-af7fa02c#overview`. +This is local evidence served from the project mount, not a website publication. + +Validation: authenticated with the supplied session token and then a cookie, +confirmed discovery, inspected the overview, and played all six steps in real +Chromium. Each screenshot loaded, its caption appeared, and playback stopped at +the selected boundary. Byte-range media requests returned 206 with matching bytes; +no browser errors occurred. The 39 existing presentation-producer tests and the +docs-contract check passed. Browser screenshots and structured results are under +the run's `presentation-check/`. No runtime source or PEX changed; the previously +recorded full-gate limitations still apply. + +Sent the broader usability finding to capsule-webconsole as +`2026-11-16-interactive-presentations.md`. Automatic presentations for interactive +runs remain a product/design follow-up, not an implemented feature of this slice. +The tracked script, timing input and producer make this retained deck reproducible; +media and generated metadata remain ignored evidence. Tokens and cookies are not +in Git, the presentation document, or browser screenshots. + +## Cross-project presentation portability audit, 2026-11-16 + +The owner asked whether agents in unrelated projects receive the same Markdown +instructions and Python support with little setup. Inspected the actual merged +PEX and its nested console bundle, package inclusion, CLI help, bootstrap assets +and browser-automation component. The viewer's HTML/JS/CSS are shipped and accept +presentation folders under any project's mount. The authoring guide, contract, +scenario scripts, recorder and metadata producer are not in that PEX. None of the +16 packaged bootstrap documents/templates refers to presentation.json or the +recorder. Browser automation supplies the browser tools, not the authoring kit. +The CLI has no presentation authoring command. This is a packaging/discoverability +gap; successful playback in this source checkout did not establish adopter setup. + +PRESENTATIONS.md now carries a support matrix. The scenario guide includes a +realistic agent brief and explicitly requires provisioned source tooling today. +The generator itself uses Python's standard library; the recorder also depends +on the repository's IDE smoke infrastructure and creates disposable test projects. +The retained SSH producer is run-specific, not a portable recording framework. +No new commands, workflow refresh, packaged assets or runtime code were introduced. + +Sent the cross-workstream delivery gap to project-management as +`2026-11-16-presentation-authoring-portability.md`, with suggested acceptance: +using only an installed candidate and an unrelated project, an agent discovers +the guide/templates, records the project's journey, generates validated metadata, +and exposes a presentation with working step playback without cloning DevCapsule. +Ownership and packaging/interface choices remain for that workstream and the owner. +This audit does not claim future capsules already have that authoring support. +Structured artifact observations are in evidence/portability-audit.json. + +## Consolidated handoff and branch delivery, 2026-11-16 + +The owner reports that an agent in a separate project running DevCapsule 0.3.0 +successfully reused this repository's recorder through an ad-hoc clone. Adding +presentations and the remaining setup was too much work. This is owner-reported +reuse evidence, not an independently repeated test or proof of shipped 0.3.0 +presentation support. + +At the owner's request, sent the complete findings and this new evidence to +project-management as `2026-11-16-github-auth-presentation-authoring-handoff.md` +on coordination at `b61ff973196a`. The self-contained item covers source locations, +discovery, scripted versus interactive generation, reusable Python, installed-PEX +omissions, the tested SSH presentation, durable documentation and proposed +installation-only acceptance in an unrelated project. It supplements the earlier +messages without selecting a toolkit interface, release or implementation owner. + +Refreshed the implementation PR draft around the final merged build, latest movie, +presentation and portability findings. All authored changes are committed and +pushed on the implementation branch; raw media remains intentionally ignored. +Canonical main was fetched and is still fully included, so no synchronization +was needed. No source or runtime behavior changed in this handoff. The existing +full-gate limitations remain; no new E2E or full gate was run for this record update. +The prescribed GitHub CLI remains absent. Under WORKFLOW-LOCAL.md's GitHub rules +4–5, the owner must edit the remote PR after resolving the gate prerequisites. +A push updates any existing PR's commits, not its description or attachments; +remote PR existence remains unverified. + +## Open Threads + +- Awaiting the human: release acceptance and merge of PR #47 into release-0.3.1; + the two inherited recursive Docker gid-zero test failures remain unresolved. +- Maintenance subsequently carries the release to main; preserve main's version, + three main-only documents and index entries listed in the final review record. +- Pair Review #44 is merged; no reviewer correction remains pending. +- Docker Desktop transport, aliases, HTTPS/gh, LFS and signing remain out of scope. +- Follow-ups: cap send time by the operation deadline; separate runtime effects + more strictly under Host Inputs. This review does not claim those are done. +- Process integration tests depend on Linux /proc and bounded startup/scheduling; + the deadline fixture assumes startup and PID recording within 0.5 seconds. +- Earlier recorded E2E predates final review; final PEX read and refusal passed. +- Disposable logs are at /var/tmp/github-auth-review-cycle and + /var/tmp/github-auth-review-unit.log. No credentials or tokened links are in Git. + +## Workstream document index + +- [Final Pair Review and release-target validation](evidence/2026-11-16-final-review.md) +- [Round 2 brief](evidence/round-2.md) + +- [Recorded E2E procedure and console presentation](evidence/showcase.md) +- [Presentation producer for the retained run](evidence/present-showcase.py) +- [Recorded chapter boundaries](evidence/presentation-timing.json) +- [Installed-artifact portability audit](evidence/portability-audit.json) +- [SSH proxy scenario script](../../../devcapsule-src/tests/e2e/scripts/github-ssh-proxy.md) +- [Review brief](evidence/review-brief.md) +- [Review follow-up 1](evidence/round-1.md) +- [Intake](intake/README.md) +- [Intake decisions](intake-dispositions.md) + +- [Review assessment](evidence/review-assessment.md) +- [Prepared PR delivery](evidence/delivery.md) diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/2026-11-16-final-review.md b/engineering-docs/wip/2026-11-16-github-auth/evidence/2026-11-16-final-review.md new file mode 100644 index 00000000..3ab33d62 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/2026-11-16-final-review.md @@ -0,0 +1,99 @@ +# Final Pair Review and release target + +Date: 2026-11-16. Implementor: GPT-6 Codex. +Reviewer: Antigravity Gemini 4 Hydrogen High (`gemini-4-hydrogen-high`, high effort). +Owner direction: complete the existing Pair Review and target release-0.3.1. + +## Review outcome + +Continued conversation `6280de13-6b45-4215-8e97-af6b466fbd61` with the committed +round-2 brief in an independent review worktree and virtual environment. +The streaming log ended with REVIEW_COMPLETE and ANTIGRAVITY_EXIT=0. +Its aggregate JSON still carries the earlier conversation's idle-timeout error; +actual commands, new commit, push and hosted review were independently verified. +The reviewer committed `455d3acc`; its 64 focused cases, mypy on 149 files and +conventions passed. Its full unit run had 3320 passed, two failed, one skipped, +191 deselected, one xfailed and one xpassed. + +The implementor read the complete eight-file review diff and final correction +diff. Production corrections improve diagnostics and disclosure and remove dead +code. Tests cover hostile input, denial, fallback, socket permissions, process +group termination and cleanup. Round 2 bounds the whole readiness handshake, +closes client pipes, parameterizes unit inputs and states the deadline fixture's +0.5-second startup precondition. Assessment comments are on PR #44. +PR #44 merged through gh with a merge commit at `9638cb11`. + +The reviewer checked the release launcher/authorization interaction. Its claim +of whole-subsystem Host Inputs compliance was too broad: broker/bridge/relay +still read clocks, processes and socket/filesystem state. The implementor's +assessment explicitly limits that claim. A larger effect-separation change and +a tighter send/operation deadline remain follow-ups, not completed corrections. + +## Combined validation at 9638cb11 + +Commands ran from devcapsule-src. The full gate used: + +```sh +PYTEST_ADDOPTS='--basetemp=/var/tmp/gpi' DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 .venv/bin/python -m nox -s build +``` + +Types passed on 351 files. Conventions: 98 legacy files, 1308 legacy tests, +67 conforming files, three command-line debt files, zero breaches. +Unit result: **3320 passed, 2 failed, 1 skipped, 191 deselected, 1 xfailed, +1 xpassed**, 80.36 seconds. The two failures are inherited: + +- tests/test_recursive_orchestrator.py::test_public_dry_run_is_unique_redacted_and_cleans_owned_staging +- tests/test_recursive_orchestrator.py::test_contained_display_dry_run_forwards_no_host_x11 + +Both reject host Docker group ID zero in this rootless capsule. They match the +previously reproduced release baseline and the reviewer's independent run. +The formerly failing staging-path fixture passed with /var/tmp scratch. +No tests were disabled. The full gate is not green. + +The combined branch's focused suite passed **64 cases** in 4.16 seconds, +including the proxy integration tests using real local Git operations. +The remaining gate sessions ran separately because build stops at pytest: + +```sh +PYTEST_ADDOPTS='--basetemp=/var/tmp/gpw' DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 .venv/bin/python -m nox -s smoke pex docs-contract webconsole +``` + +All four passed: CLI smoke, PEX packaging/executable smoke, docs contract +(249 pages), console types (nine files), and **474 console tests**. + +The rebuilt PEX completed git ls-remote over the inherited host proxy from an +empty temporary HOME with system/global Git configuration disabled. It returned +canonical HEAD `dac6b9d4033512d6ee47b9317faab51bad431c4f` with exit zero. +Pointing the adapter at a missing socket failed with exit 128. +No actual GitHub write, Docker launch or physical-host restart occurred. +Earlier recorded full E2E predates these review corrections and remains retained. + +Local PEX: devcapsule-src/dist/devcapsule-local.pex. SHA-256: +`2dafaf3a3f0cdd5a4215a1b264d36571b5316a1ace770768e94361f19fcf6ec9`. +It is a validation artifact, not a published candidate or installed launcher. +Raw logs and probe result are in /var/tmp/github-auth-review-cycle; the reviewer +unit log is /var/tmp/github-auth-review-unit.log. They are disposable. + +## Release targeting and delivery + +PR #47's hosted base is release-0.3.1, verified after editing it with gh. +Package version, both workflow version stamps and docs/versions.yaml match the +release exactly. The release is an ancestor; no main synchronization was needed. +Three unrelated main-only documents and their index entries were removed from +this release-targeted tree. Their mainline copies remain in main's history. +The bump command refused a lower version, so the exact release version files +were restored for the explicit retarget; no workflow rule or manifest changed. + +The owner-requested PR cleanup proceeded with the known failures stated in its +body after the required gate run. It does not waive release acceptance. +The human merges #47 into the release; maintenance propagates it to main. +No release branch was modified and no release or main merge was performed. + +Main propagation constraint: this published branch retains its original mainline +ancestry. A later merge back to main must preserve main's development version and +these main-only documents, plus their blog/index entries, rather than propagate +the release-target cleanup as deletions on main: + +- engineering-docs/blog/2026-11-13-thirteen-hours-thirty-five-tests.md +- engineering-docs/implementation-notes/devcapsule/2026-11-08-testing-the-macos-launcher-on-cloud-mac-hardware.md +- engineering-docs/work-orders/2026-11-08-test-improvements.md diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/delivery.md b/engineering-docs/wip/2026-11-16-github-auth/evidence/delivery.md new file mode 100644 index 00000000..087f9459 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/delivery.md @@ -0,0 +1,34 @@ +# GitHub SSH proxy delivery + +Implementation: [PR #47](https://github.com/mycodespace-ai/devcapsule/pull/47), +`ws-github-auth/ssh-proxy` into `release-0.3.1`. The human merges the release. +Review: [PR #44](https://github.com/mycodespace-ai/devcapsule/pull/44), merged at +`9638cb11` after acceptance of `455d3acc` in round 2. +The GitHub CLI is available and both remote states were verified on 2026-11-16. + +The implementation PR description below was published after the required gate; +its known failures remain disclosed. No new E2E recording was made or uploaded. + +## Published implementation description + +Adds opt-in host SSH authentication for GitHub clone, fetch and push inside capsules. With `github-ssh` authorized, the outside launcher runs host OpenSSH for validated GitHub Git requests. Capsule Git connects through a private Unix socket; private keys and the host SSH agent stay on the host. Non-GitHub destinations use capsule SSH. + +**Target: `release-0.3.1`, as directed by the owner.** Package/workflow version files and the documentation version manifest match that release. Unrelated mainline documents are excluded. The release branch is already included through merge history; this PR does not bring the next development version into the release. + +The initial transport supports Linux/WSL with native Docker, including the tested rootless Docker setup. Host key trust and noninteractive host SSH authentication are prerequisites. The grant covers all GitHub repositories available to the host identity. Docker Desktop, HTTPS/gh API credentials, Git LFS authentication, signing and arbitrary SSH aliases/options remain outside this slice. + +Pair Review: GPT-6 Codex with Antigravity Gemini 4 Hydrogen High (`gemini-4-hydrogen-high`, high effort). Review #44 was accepted after round 2 at `455d3acc` and merged at `9638cb11`. It corrects error attribution and authorization/lifetime disclosure, and strengthens parser, process cleanup and refusal tests. Both assessments are on #44. + +Validation on combined review merge `9638cb11`: + +- 64 focused unit/integration cases passed, including real local Git clone/fetch/push through the broker. +- Full build reached 3,320 passing unit cases; **two inherited recursive-launch tests fail** because this capsule's Docker socket group ID is zero. One skip, one xfail, one xpass; 191 deselected by the standard suite. The same failures occurred in the reviewer's independent run. No tests were disabled. +- Types passed on 351 files; conventions found zero breaches. +- Separate CLI smoke, PEX build/smoke, documentation contract (249 pages), console types and all 474 console tests passed. +- The rebuilt PEX completed a real read-only GitHub `ls-remote` using an empty HOME and the inherited host proxy. Missing-socket control exited 128. No GitHub write, container launch or host-launcher replacement occurred. + +**The local full gate is not green.** The owner-directed PR cleanup and release retarget do not waive these release-acceptance failures. The known failures are `test_public_dry_run_is_unique_redacted_and_cleans_owned_staging` and `test_contained_display_dry_run_forwards_no_host_x11` in `tests/test_recursive_orchestrator.py`. + +Earlier physical-host relaunch and recorded recursive E2E passed: a fresh capsule without SSH files or agent cloned the real repository through the inherited host proxy; missing-socket access failed. That recording predates the final review corrections. The retained movie and six-step presentation are local evidence, not GitHub attachments. See the [procedure](https://github.com/mycodespace-ai/devcapsule/blob/ws-github-auth/ssh-proxy/engineering-docs/wip/2026-11-16-github-auth/evidence/showcase.md). + +Limits: process-lifecycle integration tests depend on Linux `/proc`, scheduling and a documented 0.5-second fixture-startup allowance. The broker's runtime I/O is not proof of strict Host Inputs separation across the whole subsystem. Desktop transport and broader effect separation remain follow-ups. The human merges this PR into the release; maintenance carries the release to main. diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/portability-audit.json b/engineering-docs/wip/2026-11-16-github-auth/evidence/portability-audit.json new file mode 100644 index 00000000..d1b0c186 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/portability-audit.json @@ -0,0 +1,15 @@ +{ + "date": "2026-11-16", + "pex_sha256": "af7fa02ca2c2737f3a1678226341312682b71cfdd37eb892f29a42ad5c31b78c", + "source_merge": "7fc77f24df45135770160c35f193c9abb78cd9c0", + "viewer_assets": [ + "devcapsule_webconsole/static/presentation.css", + "devcapsule_webconsole/static/presentation.html", + "devcapsule_webconsole/static/presentation.js" + ], + "authoring_resources_in_archive": [], + "e2e_files_in_archive": 0, + "bootstrap_document_count": 16, + "bootstrap_authoring_references": [], + "method": "Read the delivered PEX and its nested console bundle; inspect package inclusion, bootstrap assets, CLI help and browser-automation component source. No new environment or container was created." +} diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/present-showcase.py b/engineering-docs/wip/2026-11-16-github-auth/evidence/present-showcase.py new file mode 100644 index 00000000..15e6943c --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/present-showcase.py @@ -0,0 +1,54 @@ +"""Present the retained SSH proxy run with the shared presentation producer. + +Run from devcapsule-src with PYTHONPATH=. and pass the recording directory. +The recorded movie is not edited. Its hash binds the chapter timings to its bytes. +This is a producer for one retained interactive run, not a new E2E replay runner. +""" +from __future__ import annotations + +import argparse +import hashlib +import json +from pathlib import Path + +from tests.e2e.scenario_presentation import parse_script, plan_presentation, write_presentation + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("evidence", type=Path) + args = parser.parse_args() + own = Path(__file__).resolve().parent + root = own.parents[3] + timing = json.loads((own / "presentation-timing.json").read_text()) + evidence = args.evidence.resolve() + movie = evidence / "scenario-video.webm" + if hashlib.sha256(movie.read_bytes()).hexdigest() != timing["video_sha256"]: + parser.error("The recording does not match these chapter timings; keep each run's timing with its movie.") + result = json.loads((evidence / "result.json").read_text()) + if (result["status"], result["frames"], result["fps"]) != ("passed", timing["frames"], timing["fps"]): + parser.error("The retained run must have passed with these frame counts and playback rate.") + script = parse_script((root / "devcapsule-src/tests/e2e/scripts/github-ssh-proxy.md").read_text()) + chapters = timing["chapters"] + for name in ["poster.png", *(chapter["screenshot"] for chapter in chapters)]: + if not (evidence / name).is_file(): + parser.error(f"Missing recorded image: {name}") + plan = plan_presentation({ + "id": "github-ssh-proxy", + "title": "GitHub SSH: host identity, no copied keys", + "description": "Clone from GitHub inside a fresh capsule using the outside launcher's SSH proxy. Check the credential boundary, see access fail without the socket, and restore normal access.", + "actions": [ + {"reason": f"{index}. {chapter['caption']}", "caption": chapter["caption"]} + for index, chapter in enumerate(chapters, start=1) + ], + }, script) + document = plan.timed( + [chapter["frames_after"] for chapter in chapters], timing["frames"], timing["fps"], + video="scenario-video.webm", poster="poster.png", + screenshots=[chapter["screenshot"] for chapter in chapters], + ) + print(write_presentation(evidence, document)) + + +if __name__ == "__main__": + main() diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/presentation-timing.json b/engineering-docs/wip/2026-11-16-github-auth/evidence/presentation-timing.json new file mode 100644 index 00000000..bf147768 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/presentation-timing.json @@ -0,0 +1,15 @@ +{ + "run": "20261116T103152Z-af7fa02c", + "video_sha256": "57457f07f8b40fcbfa3e3d2dff4a99584829f616b68b6c6e4552587dec6ba5ee", + "frames": 545, + "fps": 12, + "provenance": "Cumulative frames_recorded returned by the interactive controller after each selected action batch; final total from stop-result.json. These are chapter boundaries for this recording, not per-action replay timings.", + "chapters": [ + {"frames_after": 103, "screenshot": "step-003.png", "caption": "Open a terminal in the fresh capsule. The outside launcher already has explicit GitHub SSH authorization."}, + {"frames_after": 184, "screenshot": "step-004.png", "caption": "Zero SSH files. No SSH agent. The capsule connects to the host-owned proxy socket."}, + {"frames_after": 285, "screenshot": "step-006.png", "caption": "A real GitHub SSH clone succeeds. The private key stays on the host."}, + {"frames_after": 331, "screenshot": "step-007.png", "caption": "Point just this command at a missing proxy socket: the GitHub read fails."}, + {"frames_after": 395, "screenshot": "step-008.png", "caption": "The failed read exited 128. Using the normal proxy again returns GitHub HEAD successfully."}, + {"frames_after": 533, "screenshot": "step-009.png", "caption": "The recorded commands and independent checks agree: host identity, no copied key, working Git access."} + ] +} diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/review-assessment.md b/engineering-docs/wip/2026-11-16-github-auth/evidence/review-assessment.md new file mode 100644 index 00000000..8d70ed8c --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/review-assessment.md @@ -0,0 +1,110 @@ +# GitHub SSH proxy review assessment + +Date: 2026-11-16. Implementor: GPT-6 Codex. Reviewer: Antigravity, +`gemini-4-hydrogen-high` (Gemini 4 Hydrogen High). + +## Final disposition, 2026-11-16 + +Round 2 accepted at `455d3acc`; review PR #44 merged at `9638cb11`. +Both pairs posted their assessments on #44. PR #47 targets release-0.3.1. +The full combined gate and remaining checks are in the [final record](2026-11-16-final-review.md). +Two inherited recursive Docker gid-zero unit failures remain; they do not arise +from the review corrections. The reviewer's broad Host Inputs compliance claim +is qualified: pure parsing/decisions are separated, but the broker/relay/bridge +still perform runtime effects. Stricter separation remains a follow-up. + +## Earlier local disposition (superseded by the final disposition) + +Round 1 accepted locally at `388f62a34fe373882201f9118faaf34cec61680b`. +The reviewer branch is pushed as `ws-github-auth/ssh-proxy-review`. +No review PR or implementation PR exists yet. This is local review preparation, +not completion of the PR-mediated Pair Review Loop or mainline integration. + +The implementor inspected the diff and accepted the unused helper removal, +separate capsule-SSH error attribution, public API declaration, launcher dry-run +warning and disclosure layout, deny-help update, and expanded hostile-input, +permission, cancellation, process-group and authorization coverage. +Round 1 replaced an ambient-current-directory PATH check, bounded the readiness +handshake, guaranteed client cleanup, and distinguished dead orphan zombies from +running descendants. The process tests depend on Linux /proc and scheduling +within their explicit timeouts; they do not prove prompt reaping by PID 1. + +The reviewer ran 55 focused cases successfully. A temporary, uncommitted merge of +`388f62a3` with implementation `890fa91d` was conflict-free and passed **75 focused +tests**, mypy on the nine touched modules/test files, and the conventions checker +(103 legacy files, 1380 legacy tests, 50 conforming files, zero breaches). +`git diff --check` and `git fsck --connectivity-only --no-dangling` passed. +The temporary merge was aborted deliberately: reviewer corrections remain on +their separate pushed branch for the owner-operated review PR. + +## Build evidence and limits + +The implementor's full build reached pytest: 20 failed, 2917 passed, 1 skipped, +76 deselected, 14 xfailed, 7 xpassed. The reviewer's independent build found the +same failure set: 20 failed, 2926 passed, 1 skipped, 80 deselected, 14 xfailed, +7 xpassed. The new node-name expectation was repaired on the implementation +branch by refurbishing the complete legacy file into the unit mirror (20 passing +cases); the reviewer was told not to duplicate this change. The other 19 failures +reproduced by selecting all 20 failed IDs on an archive of unchanged canonical +main `1942f396`: 19 failed, 1 passed. They concern inherited capsule trust, +permissions/ownership and recursive-launch environment; they remain unresolved. +A full gate on the combined final tree has not passed. + +CLI smoke, PEX build/smoke and documentation contract passed separately. After +aligning the console authorization mirror, all 458 webconsole tests and its types +passed. Both source and built PEX adapters completed authenticated GitHub +`ls-remote` through the broker, returning mainline HEAD `1942f396`. The broker in +that probe used the current capsule's existing SSH setup. This is **not** evidence +of physical-host Docker launch acceptance. No real GitHub write was tested; local +fixture repositories exercised real Git clone/fetch/push. No containers were +launched and no key files were read by the agent, copied or changed. + +## Remaining proposals + +- Docker Desktop needs a separate transport design; this slice explicitly refuses + hosts unable to bind Unix sockets. Linux/WSL with native Docker is first. +- GitHub aliases, HTTPS/gh, Git LFS authentication, signing, and arbitrary SSH flags + (including Git's -4/-6 switches) are outside this adapter's current contract. +- Additional reference cross-links and a tighter operation-deadline cap inside + the bounded send loop were considered; the existing send timeout is 10 seconds + and cancellation checks remain active. These are recorded follow-ups, not + claims of implemented behavior. +- The inherited canonical socket positive path is not covered by a pure unit + test; physical-host and recursive-launch acceptance remain required. + +## Reviewer execution + +Conversation `6280de13-6b45-4215-8e97-af6b466fbd61` used streaming JSON output. +The first redirected-stdin invocation failed to convey the brief; continuation +with an explicit brief path proceeded. The reviewer's CLI stalled after its full +gate had already returned. The implementor interrupted and continued that same +conversation with the committed round brief and a bounded print timeout. The +final response reported REVIEW_COMPLETE, the final shell marker was +ANTIGRAVITY_EXIT=0, and the commit and remote SHA were independently verified. +The aggregate JSON result retained an ERROR/idle-timeout from the earlier turn; +we therefore rely on observed commits/checks, not that aggregate status alone. +Scratch logs and virtual environments are not durable evidence. Briefs, the +assessment and validation counts are retained here. The reviewer worktree is +removed at pause; its pushed branch preserves all changes. + +## Baseline failure IDs + +- `tests/configuration/test_contract.py::test_second_checkout_cannot_inherit_the_first_checkouts_authority` +- `tests/configuration/test_contract.py::test_config_list_is_data_only_and_show_carries_the_review` +- `tests/test_capability_policy.py::test_cli_check_and_capability_mutation` +- `tests/test_host_daemon.py::test_unmountable_staging_fails_loudly` +- `tests/test_owner_commands.py::test_tool_edit_does_not_change_checkout_answers_when_not_ready[True]` +- `tests/test_recursive_orchestrator.py::test_public_dry_run_is_unique_redacted_and_cleans_owned_staging` +- `tests/test_recursive_orchestrator.py::test_contained_display_dry_run_forwards_no_host_x11` +- `tests/test_run_flow.py::test_a_second_checkout_is_registered_under_its_directory_name` +- `tests/test_run_flow.py::test_interactive_questions_record_answers_where_the_config_family_would` +- `tests/test_run_flow.py::test_save_with_pending_consent_writes_nothing[False-False]` +- `tests/test_run_flow.py::test_save_with_pending_consent_writes_nothing[False-True]` +- `tests/test_run_flow.py::test_save_with_pending_consent_writes_nothing[True-False]` +- `tests/test_run_flow.py::test_save_with_pending_consent_writes_nothing[True-True]` +- `tests/test_run_flow.py::test_partial_terminal_review_saves_no_answers[1\n]` +- `tests/test_run_flow.py::test_partial_terminal_review_saves_no_answers[1\nn\n]` +- `tests/test_runtime_entrypoint.py::test_entrypoint_rejects_unknown_adapters` +- `tests/test_trust.py::test_a_real_run_launches_on_the_homes_trust_alone` +- `tests/test_trust.py::test_trust_write_is_private_atomic_and_keeps_previous_record_on_failure` +- `tests/test_trust.py::test_terminal_acceptance_stays_staged_if_a_later_answer_is_missing` diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/review-brief.md b/engineering-docs/wip/2026-11-16-github-auth/evidence/review-brief.md new file mode 100644 index 00000000..a5d2f5d8 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/review-brief.md @@ -0,0 +1,87 @@ +# Review brief: GitHub SSH proxy, Gemini 4 Hydrogen High + +Implementor: Codex, GPT-6. Review partner: Antigravity, gemini-4-hydrogen-high. +The owner requested this feature with Pair Review and selected the github-auth +workstream and Git over SSH first. Review correctness, clarity and meaningful +coverage of the implementation against upstream/main. + +## Checkout and first reads + +Work only in /home/devcapsule/worktrees/github-auth-review on +ws-github-auth/ssh-proxy-review. Do not edit the implementor checkout. +Read AGENTS.md, WORKFLOW.md topic 9.11, WORKFLOW-LOCAL.md, this brief, +engineering-docs/wip/2026-11-16-github-auth/CURRENT-STATUS.md, then +`git diff upstream/main...HEAD`. Read the contracts in github_transport.py and +github_proxy.py before judging implementations. This brief is your only context. + +## Scope and questions + +Ordinary GitHub clone/fetch/push from a Linux/WSL capsule uses host-side OpenSSH +through a private launcher-owned Unix socket. No private keys or host agent socket +enter the capsule. Only fixed GitHub upload-pack/receive-pack requests are allowed. +The authorization is optional and denied by default; grant through host config or +run-once. All repositories accessible by the host identity are within the grant. +Host key checking remains strict; keys must authenticate noninteractively on the +host. Other Git hosts fall back to the capsule SSH. Mac Docker Desktop, HTTPS, gh, +Git LFS auth, SSH signing, arbitrary aliases are outside the first slice. + +Review in order: +1. Correctness: injection/destination escape, request validation independent of + the client, socket permission boundary, lifecycle cleanup, cancellation, + bounded memory/concurrency, deadlocks/half-close/exit status, Docker environment + integration and denial. Never weaken host-key checking to make a test pass. +2. Clarity: remove misleading guarantees or unnecessary machinery. +3. Coverage: new tests must establish independent contracts, especially auth + gating, real binary streaming, failure/exit handling and process cleanup. +4. Follow Unit Tests rules 1-4 in WORKFLOW-LOCAL.md. New unit tests live in the + module mirror, state their contract in a docstring, and construct inputs. + For each, identify possible failures not caused by a product bug. Do not edit + tests in legacy files. Add integration tests for subprocess/network effects. +5. Prefer explicit host inputs and pure decisions. No monkeypatch/unittest.mock + in new tests. Code runs no invented cryptography; authentication is OpenSSH. + +Keep corrections within this feature. Do not repair unrelated legacy tests or +expand to macOS, HTTPS, repository allowlists or generic SSH forwarding. + +## Validation + +Create your own environment exactly as the local workflow says, from devcapsule-src: +python3.12 -m venv .venv +.venv/bin/python -m pip install -r dev-requirements.txt +.venv/bin/python -m pip install -e . --no-deps + +Use scratch under /home/devcapsule/.cache/devcapsule-gate/github-auth-review; +/opt is read-only. The parent cache directory exists. +Initialize website with `git submodule update --init website` for the docs gate. +Run focused tests: +.venv/bin/python -m pytest -q --no-cov -o addopts='' tests/unit/devcapsule/test_github_transport.py tests/unit/devcapsule/configuration/test_authorization.py tests/unit/devcapsule/configuration/test_review.py tests/integration/test_github_proxy.py + +Run full gate synchronously, not a background tool job: +PYTEST_ADDOPTS='--basetemp=/home/devcapsule/.cache/devcapsule-gate/github-auth-review' DEVCAPSULE_DIFF_BASE=upstream/main .venv/bin/python -m nox -s build + +The implementor's focused run passed 42 tests. Its full gate may expose existing +mainline legacy test failures in this capsule. Report exact failures; do not fix +unrelated code or disable tests. Do not build images or launch Docker capsules. + +## Delivery and forbidden actions + +The GitHub CLI is ABSENT at /opt/xtras/miniconda3/envs/gh/bin/gh. Local policy +requires the human to create PRs in this case. Do not use another credential or +GitHub interface. There is not yet a PRn; PR-mediated Pair Review completion is +pending owner delivery. Perform the local code review now, preserve your findings +and corrections, and report this delivery blocker accurately. Do not claim a +completed PR review loop. Push your review branch over ordinary upstream SSH +only after checks; no push to main. Provide a compare URL if changes exist. + +Do not edit status files, intake/dispositions, evidence, root CURRENT-STATUS.md, +index.md, or run workflow publish. Do not change website gitlinks or configuration +manifests. Do not merge, rebase, force-push, create releases, inspect private keys, +read credential contents, use real GitHub repositories in tests, or run containers. +Do not modify the implementor's files or state. Do not add broad test-only seams. + +Commit corrections with the existing human author and this trailer: +Co-authored-by: Gemini 4 Hydrogen High Antigravity <noreply@google.com> + +Report findings (what/where/fix/evidence), things considered and left alone, +unimplemented proposals, exact validation counts and limits. If no changes, say +so. Print REVIEW_COMPLETE as your last line, or REVIEW_BLOCKED with the reason. diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/round-1.md b/engineering-docs/wip/2026-11-16-github-auth/evidence/round-1.md new file mode 100644 index 00000000..c2dc01cf --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/round-1.md @@ -0,0 +1,42 @@ +# Review follow-up 1: finish the bounded local review + +Continue the same Gemini Hydrogen review in /home/devcapsule/worktrees/github-auth-review. +Your full build has FINISHED: step 130 returned 20 failed, 2926 passed, 1 skipped, +14 xfailed and 7 xpassed. No pytest or nox process remains. Your CLI stayed idle +after that completion, so the implementor interrupted it and resumed this turn. +Do not wait for the completed job. Do not repeat the full gate: its failures are known. + +The implementor read your diff and accepts its production-code changes and added +coverage in principle. Fix these test issues before committing: +1. test_host_bridge_requires_openssh_on_path passes PATH="". shutil.which searches + the current directory in that case; the test depends on no file named ssh being + present there. Use tmp_path as an explicitly empty PATH directory instead. +2. test_broker_shutdown_cancels_active_ssh_process_group calls stdout.readline with + no timeout. Bound the ready handshake and ensure client cleanup in finally even + if readiness fails. Avoid a test that hangs forever when the product is broken. +3. An orphaned grandchild may be a zombie until the host's reaper runs. The broker + cannot waitpid a grandchild. Verify that no descendant is running, without + asserting timely reaping by an unrelated PID 1. State the test's actual claim. + +Run focused tests INCLUDING your new unit test_github_proxy.py and integration +file and mypy. If new focused tests fail, fix those failures within this scope. +Commit your corrections. Do not merge, reset, rebase or touch the parent checkout. + +Parent updates already committed separately (do not duplicate or cherry-pick): +- f1dbb338 refurbishes tests/configuration/test_nodes.py into its correct mirror, + 20 passing cases; this resolves the new github-ssh name expectation. +- 4ba1725f aligns webconsole/configuration.py SECURE_AUTHORIZATIONS and its contract; + all 458 console tests now pass. +- The remaining 19 failures are reproduced on unchanged upstream/main, by selecting + all 20 failing test IDs in an archive of the base (19 fail, the registry test passes). +- Parent CLI smoke, PEX build/smoke and docs contract pass. Both source and PEX Git + adapters passed read-only authenticated GitHub ls-remote using the capsule's existing + credential on the broker side; not a physical-host launch test. + +Your branch can be pushed to upstream as review preparation, with limitations in +its report. No PR exists because local policy makes creation owner-operated without +its prescribed gh installation. Do not use another GitHub interface or credential. + +Return the findings, corrections, focused results, known full-gate failures and +unimplemented proposals. End with REVIEW_COMPLETE or REVIEW_BLOCKED. Do not begin +another broad investigation; the remaining task is these test corrections and delivery. diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/round-2.md b/engineering-docs/wip/2026-11-16-github-auth/evidence/round-2.md new file mode 100644 index 00000000..621921f5 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/round-2.md @@ -0,0 +1,56 @@ +# Round 2: complete review PR #44 for release 0.3.1 + +Continue the GitHub SSH proxy review with Antigravity gemini-4-hydrogen-high, +high effort. Implementor: GPT-6 Codex. Your previous review commit is 388f62a3. +Implementation PR #47 now targets release-0.3.1 by explicit owner direction; +its hosted base will be changed after validation. Review PR #44 targets +ws-github-auth/ssh-proxy. The implementor has merged the current implementation +into your review branch to prepare it, with no conflict and no reset/rebase. + +Work only in /home/devcapsule/worktrees/github-auth-review on +ws-github-auth/ssh-proxy-review. Your independent devcapsule-src/.venv is prepared. +Read this brief, current WORKFLOW-LOCAL.md Unit Tests and Host Inputs, the earlier +review-assessment.md and round-1.md, then the actual diff against +ws-github-auth/ssh-proxy and the proxy contracts. Inspect the release merge's +interaction with your launcher and authorization changes. Do not widen the feature. + +Two requested test corrections: +1. _read_ready_line selects readable and then calls blocking readline: a partial + line still hangs. Make the entire expected handshake bounded, with cleanup. +2. Parameterize test_containerized_bridge_requires_an_inherited_canonical_socket + so each case calls one public operation, per current Unit Tests rule 2. +Also assess whether the 0.2-second deadline test assumes Python startup timing; +make its preconditions explicit or report the limitation. Keep changes small. + +Verify correctness, clarity, then meaningful changed-line coverage. Verify Unit +Tests rules 1-4 for every changed/new test, and name non-bug failure conditions +in your report. Verify Host Inputs rules 1-6 on the changed code/tests. Do not +invent test-only seams or fix unrelated inherited failures. Propose broader +changes separately if they cannot fit this bounded correction round. + +From devcapsule-src, run: +PYTEST_ADDOPTS='--basetemp=/var/tmp/gpr' .venv/bin/python -m pytest -q --no-cov -o addopts='' tests/unit/devcapsule/test_github_transport.py tests/unit/devcapsule/test_github_proxy.py tests/unit/devcapsule/configuration/test_authorization.py tests/unit/devcapsule/configuration/test_review.py tests/integration/test_github_proxy.py +DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 .venv/bin/python scripts/validate_unittests_follow_conventions.py +.venv/bin/python -m mypy devcapsule +PYTEST_ADDOPTS='--basetemp=/var/tmp/gpr' DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 .venv/bin/python -m nox -s tests > /var/tmp/github-auth-review-unit.log 2>&1 +Run synchronously and report the log's exact result. The implementor runs the +full post-merge build gate. Prior combined gate had three inherited unit failures +(unmountable staging and two recursive Docker gid-zero cases); report current +results, do not disable tests or modify those unrelated contracts. + +GitHub CLI is NOW installed. In every gh shell: +source /opt/xtras/miniconda3/etc/profile.d/conda.sh && conda activate gh +First verify gh auth status -h github.com; stop on failure, use no other credential. +You may read PR #44/#47. Commit and push your corrections over SSH to upstream. +If tests pass and a gate failure is not expected, update #44 with --body-file. +Otherwise report validation in a gh pr review --comment on #44; do not conceal +failures or claim a passing gate. Include findings, unimplemented proposals and +non-bug test failure conditions. Do not open another PR. + +Preserve human git author; trailer: +Co-authored-by: Gemini 4 Hydrogen High Antigravity <noreply@google.com> +Do not merge, rebase, reset, force-push, edit other branches/checkouts, status, +intake, evidence, workflow files, index.md or configuration manifests. Do not +build images/start containers, inspect keys, use real GitHub repositories in tests, +or alter the installed launcher. No new broad investigation or repeated full gate. +Print REVIEW_COMPLETE or REVIEW_BLOCKED with the reason as the final line. diff --git a/engineering-docs/wip/2026-11-16-github-auth/evidence/showcase.md b/engineering-docs/wip/2026-11-16-github-auth/evidence/showcase.md new file mode 100644 index 00000000..534b5e9e --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/evidence/showcase.md @@ -0,0 +1,202 @@ +# GitHub SSH proxy: recorded fresh-capsule clone + +## Purpose and acceptance + +Show a user cloning a GitHub repository over SSH inside a fresh capsule. The +outside launcher uses the host identity. No SSH key or agent is supplied to the +child. Public GitHub repositories also require authentication on their SSH URL. +This scenario reads the canonical DevCapsule repository; it does not push. + +Pass requires a real clone, the expected independently read commit, the unchanged +SSH origin, a clean working tree, no child SSH files or agent, and the canonical +broker socket mounted from the same host source as the parent. A second Git read +with an absent broker socket must fail. Keep the recording and independent +observations, and remove the fresh container, workspace and checkout state. +A video alone does not pass the test. + +## Preconditions + +Keep the outside launcher alive with `github-ssh` enabled. The host must already +trust GitHub and authenticate noninteractively. An unencrypted default SSH key +needs no host agent. The parent needs host Docker and host networking. + +From `devcapsule-src`, use the development virtualenv and the exact PEX under test. +The historical recorded run uses SHA-256 +`33c3c7bc7fe6ff6772eedee06424c95afcf4aebddca20ab99f9a31a7c103d35b`, built from +`d6fd93e0`. The merged artifact now has different bytes; set the expected hash +to the actual build being recorded for a new run. Do not rebuild between the launch and the evidence capture. + +```sh +.venv/bin/python -m pip install 'playwright==1.63.0' +export DEVCAPSULE_EXPECTED_SHA256=33c3c7bc7fe6ff6772eedee06424c95afcf4aebddca20ab99f9a31a7c103d35b +``` + +## Start the recording controller + +Save the following as a temporary Python script and run it with +`PYTHONPATH=. .venv/bin/python <script>`. It uses the normal PEX project-init and +project-run commands, a unique fresh project, the child browser component, +and the existing recorder. The script prints its evidence directory. The +interactive phase has a 30-minute deadline; initialization and launch also have +bounded deadlines. The context manager cleans up on stop or failure. + +```python +import hashlib, json, os, platform +from dataclasses import replace +from datetime import datetime, timezone +from pathlib import Path +from tests.e2e.ide_session import SURFACES, command +from tests.e2e.scenario_recorder import ScenarioSpec, serve_interactive_controller + +pex = Path('dist/devcapsule-local.pex').resolve() +digest = hashlib.sha256(pex.read_bytes()).hexdigest() +assert digest == os.environ['DEVCAPSULE_EXPECTED_SHA256'] +evidence = Path('tests/e2e/evidence/github-ssh-proxy') / (datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ') + '-' + digest[:8]) +evidence.mkdir(parents=True) +run = {'pex':str(pex), 'sha256':digest, 'version':json.loads(command(str(pex), 'version', '--json').stdout), + 'host':platform.platform(), 'docker':json.loads(command('docker', 'info', '--format', '{{json .}}').stdout), + 'expected_head':command('git', 'ls-remote', 'git@github.com:mycodespace-ai/devcapsule.git', 'HEAD').stdout.split()[0]} +# Keep a minimal daemon record; omit unrelated local configuration. +run['docker'] = {k:run['docker'].get(k) for k in ('ServerVersion','OperatingSystem','Architecture','SecurityOptions','Name')} +(evidence / 'run.json').write_text(json.dumps(run, indent=2)+'\n') +surface = replace(next(s for s in SURFACES if s.name == 'codium'), + needs=('frontend-ide','node','browser-automation'), consents=(('github-ssh','true'),)) +spec = ScenarioSpec('github-ssh-proxy', 'codium', 'GitHub access, host key stays outside', + 'Clone over Git SSH from a fresh capsule using the outside launcher proxy.', {}, ()) +print('EVIDENCE '+str(evidence),flush=True) +try: + serve_interactive_controller(pex, spec, evidence, surface=surface, timeout=1800) +except BaseException as exc: + (evidence/'failure.txt').write_text(repr(exc)+'\n') + raise +``` + +## Act out the scenario + +Use `tests.e2e.scenario_recorder ctl --evidence <printed-directory>` for each +interaction. Inspect screenshots to locate controls rather than assuming that an +unseen welcome screen has gone away. The controller records actual keyboard and +mouse actions; it saves the complete trace in `action-log.json`. + +1. Open VSCodium's integrated terminal. Maximize the panel and increase the font + so the commands and their output can be read in the recording. +2. Display the scenario title and check that `$HOME/.ssh` has no files, no + `SSH_AUTH_SOCK` is set, and `$DEVCAPSULE_GITHUB_SOCKET` names a socket. +3. Run `git clone --depth 1 git@github.com:mycodespace-ai/devcapsule.git demo-repo`. + Wait for the real checkout to appear, with a bounded deadline. +4. Show `git -C demo-repo remote get-url origin` and + `git -C demo-repo log -1 --format='%h %s'`. +5. Run a read with `DEVCAPSULE_GITHUB_SOCKET=/tmp/absent-github-proxy.sock` and + show its failure. Restore nothing: the override applies only to that command. +6. Independently inspect the child through Docker: verify the key/agent absence, + canonical socket mount, runtime PEX checksum, origin, commit, and clean tree. + Save the structured observations in `verification.json`. Compare the commit + with the external `expected_head` saved before the launch. A repository update + during the test is a failed precondition to investigate, not an automatic retry. +7. Capture a final screenshot, then send `{"cmd":"stop"}`. Require a successful + WebM encoding, a nonempty movie, and `cleanup.json` reporting container removal. + Verify the workspace and listed checkout records are also absent. Save this + final assessment in `result.json`. + +Example controller command, from `devcapsule-src`: + +```sh +PYTHONPATH=. .venv/bin/python -m tests.e2e.scenario_recorder ctl \ + --evidence <printed-directory> \ + '{"cmd":"act","actions":[{"action":"press","text":"Control+Shift+p"}]}' +``` + +## Evidence + +Keep `run.json`, `verification.json`, `result.json`, `action-log.json`, the WebM, +final screenshot and cleanup record together under `tests/e2e/evidence/github-ssh-proxy/`. +The launcher log can contain ephemeral console/desktop URLs; redact those before +sharing. Do not commit tokens, credentials, or raw logs to Git. Record failed +attempts and their causes; never overwrite them with a later successful attempt. + +## Observed run + +Run: `20261116T092248Z-33c3c7bc`, using the PEX identified above and rootless Docker. +The fresh child cloned canonical HEAD `1942f396dd11ffabb64784eb7279f283181e32dd` +over SSH, with no SSH files or agent. Its read-only proxy bind uses the same host +source as the parent. The independent missing-socket read failed with exit 128. +The externally observed origin, clean working tree, README and runtime checksum +passed. The base digest was +`sha256:d7047ced8556cd35964fcc058a1101cf2b5b202f7a5daa2fdd434dcda5ed82c9`. + +One on-screen command initially tested that `.ssh` did not exist. The capsule +creates that directory empty, so this was the wrong predicate. The next command +counted its files and returned zero; the independent inspection also returned an +empty file list before and after cloning. The correction is retained in the action +trace and full recording. No second clone or container launch was used to hide it. + +The result is **passed**. The recorder encoded 458 frames at 12 fps into a +38.17-second, 2,294,439-byte WebM. Its SHA-256 is +`d6ec02d7531fb0d961b5773059165a132fa6573d383efc07cb7e4e65af11f3eb`. +The full desktop recording and screenshots are retained beside it. Independent +cleanup checks found the container, workspace and checkout records absent. + +Evidence directory, relative to this checkout: +`devcapsule-src/tests/e2e/evidence/github-ssh-proxy-pre-merge/` (copied from the +original dist evidence directory before the release merge rebuild). +`result.json` summarizes the checks and hashes the deliverables. +The final on-screen remote read overlaps the next typed command; the actual Git +outputs and independent verification remain valid. This is a recorded engineering +showcase, with the complete raw capture retained, rather than a polished tutorial. + +For future runs, send each network command separately and wait for its observable +completion before typing the next. A successful controller action means that the +keystrokes were delivered; it does not mean the shell command has finished. + +## New recording of the merged build + +Run `20261116T103152Z-af7fa02c` passed in the primary checkout. Parent and child +runtime SHA-256 both equal +`af7fa02ca2c2737f3a1678226341312682b71cfdd37eb892f29a42ad5c31b78c` (merge `7fc77f24`). +The terminal clone and restored-proxy read returned 0; the missing-socket read +returned 128. The independent checks and cleanup passed. Unlike the earlier +recording, this run counts SSH files correctly from the start and waits for each +network command's completion before typing the next. + +Evidence: `devcapsule-src/tests/e2e/evidence/github-ssh-proxy/20261116T103152Z-af7fa02c/`. +`scenario-video.webm` is 45.42 seconds (545 frames at 12 fps), 2,116,032 bytes, +SHA-256 `57457f07f8b40fcbfa3e3d2dff4a99584829f616b68b6c6e4552587dec6ba5ee`. +The full capture, poster, screenshots, action trace, run metadata, independent +verification and cleanup results are beside it. The saved scripts identify the +exact executable; they use the existing controller and test-owned exit markers +to wait for commands. No product source changed for this recording. + +Host path: +`/opt/costin3/myProjects/devcapsule/devcapsule-src/tests/e2e/evidence/github-ssh-proxy/20261116T103152Z-af7fa02c/scenario-video.webm`. + +## Presentation in the running console + +The interactive recorder does not automatically generate presentation metadata. +The retained run now has a six-step presentation generated with the shared +`scenario_presentation` producer from the +[authored script](../../../../devcapsule-src/tests/e2e/scripts/github-ssh-proxy.md) +and [recorded chapter boundaries](presentation-timing.json). Those boundaries are +the cumulative frame counts returned by the controller at the selected batches; +they are not inferred from wall-clock time. The movie checksum prevents using +these timings with a different run. The existing movie is not edited or copied. + +From `devcapsule-src`, regenerate the document with: + +```sh +PYTHONPATH=. .venv/bin/python \ + ../engineering-docs/wip/2026-11-16-github-auth/evidence/present-showcase.py \ + tests/e2e/evidence/github-ssh-proxy/20261116T103152Z-af7fa02c +``` + +Reload the console's **Presentations** page. It discovers the new document at: + +```text +/presentations/devcapsule-src/tests/e2e/evidence/github-ssh-proxy/20261116T103152Z-af7fa02c#overview +``` + +The route is relative to the current console origin. Authenticate with the current +session's normal console link; do not put its token in a record. This local deck +is served from the mounted project, not deployed to the website. Media and generated +metadata stay in ignored evidence; the script, timing metadata and producer are +versioned. The older recordings remain in the detached worktree outside this +console's project mount. diff --git a/engineering-docs/wip/2026-11-16-github-auth/intake-dispositions.md b/engineering-docs/wip/2026-11-16-github-auth/intake-dispositions.md new file mode 100644 index 00000000..0e175eff --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/intake-dispositions.md @@ -0,0 +1,3 @@ +# Intake decisions + +No items received. diff --git a/engineering-docs/wip/2026-11-16-github-auth/intake/README.md b/engineering-docs/wip/2026-11-16-github-auth/intake/README.md new file mode 100644 index 00000000..42353b5f --- /dev/null +++ b/engineering-docs/wip/2026-11-16-github-auth/intake/README.md @@ -0,0 +1,3 @@ +# GitHub authentication intake + +No items pending. Deliver items through workflow mail. diff --git a/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-authoring-validation.md b/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-authoring-validation.md new file mode 100644 index 00000000..47ae5006 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-authoring-validation.md @@ -0,0 +1,122 @@ +# Authoring toolkit validation, 2026-11-16 + +Target: `release-0.3.1`, starting at `10e7fda3`. The implementation branch is +`ws-presentations/0.3.1-authoring`. Main's next-development version was not +carried onto this branch. The original registration branch remains intact. + +## Contract and implementation + +The engineer supplies Markdown or inline English. The agent translates that +scenario into the ordinary Playwright actions and assertions for the project, +using shipped instructions and helpers. The toolkit does not interpret natural +language itself. It does not require a DevCapsule source clone or test imports. + +The installed CLI exposes `presentations guide`, `export <new-directory>` and +`hand-off <evidence-folder>`. Export supplies a standard-library Python package +for the capsule's Playwright interpreter, plus the guide and an adaptable driver. +The existing producer moved into that package; the repository replay adapter +keeps its former script-root default. Its 39 existing tests moved with it. + +The recorder captures bursts around small Playwright callbacks. It keeps native +video when the caller configures it, derives times from frame counts and writes +the presentation last. The project's assertions determine test success. Failed +and incomplete attempts stay labelled. The existing viewer and schema are unchanged. + +## Checks + +Commands run from `devcapsule-src` with its existing `.venv`: + +```sh +.venv/bin/python -m pytest -q --no-cov tests/test_scenario_recorder.py tests/unit/devcapsule/presentation_tools tests/unit/devcapsule/test_presentation_authoring.py +DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 PYTEST_ADDOPTS='--basetemp=/var/tmp/presentations-gate/pytest --maxfail=1' .venv/bin/python -m nox -s build +DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 PYTEST_ADDOPTS='--basetemp=/var/tmp/presentations-gate/console' .venv/bin/python -m nox -s pex docs-contract webconsole +``` + +The scratch parent was created first. `/opt/devcapsule-gate` is read-only here. + +| Check | Result | +| --- | --- | +| Focused unit tests | 59 passed; final run including the repository recorder: 121 passed | +| Version and syntax | passed; package remains 0.3.1 | +| Mypy | 352 source files, no errors | +| Conventions | 99 legacy files / 1315 legacy tests; 64 conforming files; 0 breaches; 3 files in command-line debt | +| Full gate's unit phase | 1438 passed, 1 skipped, 175 deselected, stopped at 1 failure | +| Remaining PEX build and smoke | passed | +| Documentation contract | 249 pages including 18 aliases, passed | +| Webconsole | 474 tests passed; type check passed | + +The failure is the previously observed +`test_public_dry_run_is_unique_redacted_and_cleans_owned_staging`: +`host Docker group ID must be a positive integer`. No attempt was made to +change this unrelated fixture. The full gate is not green. An initial invocation +from the wrong directory, and a missing scratch parent, were corrected before +the results above; neither is counted as a product failure. + +## Installed artifact and real browser + +Built `dist/devcapsule-local.pex` with the repository's local-source policy; +SHA-256 `ca6ee98a3f7af039729fa42c34f05e3b9ad299acc1a83ab2b03b8adced1e2aea`. +This is not a published release candidate. From `/var/tmp`, the executable +printed its packaged guide and exported the kit into an unrelated scratch +directory. Its helpers imported without importing `devcapsule` or `tests`. + +The scratch project was a small shopping-list application served on loopback. +Its English scenario was: open the application, add milk, reload and verify +milk remains. The agent wrote a driver using only the exported kit and ordinary +Playwright. The cached Chromium and Playwright ffmpeg ran locally; no image, +capsule or browser download was needed. + +| Run | Assertions/result | Presentation | +| --- | --- | --- | +| Passing | add and reload observations passed | 3 steps; 2 seconds | +| Deliberately failing | wrong expected item raised AssertionError; result stayed failed | 2 reached steps; FAILED title; 0.917 seconds | +| Incomplete | stopped after opening; result stayed incomplete | 1 reached step; INCOMPLETE title; 0.667 seconds | + +Each retained a native Playwright video and the generated movie/screenshots. +The viewer was extracted from the built executable and served with the existing +webconsole environment against the scratch project. Links came from the built +`presentations hand-off`, including its token-file handling. All six chapters +played, all step screenshots loaded, and the native media duration agreed with +each manifest to within 0.1 second. No viewer schema failure appeared. +The temporary services were stopped. Raw files and verification scripts remain +only under `/var/tmp/presentations-acceptance`; no tokened URL is committed. + +The exported example driver also ran successfully against the scratch application's file URL, checking its heading before and after reload. + +These checks prove packaging and compatibility with the accepted viewer. They +do not replace the owner's prior human acceptance or the requested independent +Pair Review. The model catalog lists `gemini-4-hydrogen-high` and CLI help +supports `--effort high`; no reviewer invocation has occurred. The prescribed +GitHub CLI is absent, so PR creation is an owner action under WORKFLOW-LOCAL. + + +## Final implementation after Pair Review + +Antigravity `gemini-4-hydrogen-high --effort high` delivered review PR #46. +The implementor read its diff and requested one correction round for unit-test +contracts and the guide's relative-path wording. Final review commit `e331693f` +was accepted and merged into the implementation branch at `d4564313`. +Both reviewer invocations exited 0. Their briefs are retained under `evidence/`; +the assessment and acceptance are comments on PR #46. + +The merged branch passed 148 focused/recorder-compatibility tests and 11 real +CLI/PEX integration tests. The full gate passed version/syntax, mypy (353 files) +and conventions (65 conforming files, 0 breaches), then stopped at the same +inherited Docker-group failure after 1438 passes, 1 skip and 178 deselections. +Separate PEX build/smoke, docs contract (249 pages) and webconsole checks +(474 tests) all passed. The reviewer worktree lacked website contents, so its +docs check skipped; the implementor's docs check ran and passed. + +Final local-source executable SHA-256: +`da1f2d894f0ca53c26f36a962c1313baf8f92090aade9d528f9d39c218cd5c41`. +The real Chromium acceptance was rerun from the rebuilt executable, exporting +into `/var/tmp/presentations-final-acceptance`. Passing, failing and incomplete +scenarios again produced 3, 2 and 1 chapters respectively. All six chapters +played in the executable's embedded viewer, with screenshots loaded and media +durations matching the manifest within 0.1 second. Both temporary services +were stopped. The kit did not import `devcapsule` or `tests` in the driver. + +PR #43 targets `release-0.3.1`; the human performs that merge. Its checks are +available on the live PR and should be reverified before integration. The +reviewer proposal to add more nox smoke commands was not adopted because the +new installed-PEX integration test directly covers the delivery boundary. diff --git a/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-pr-draft.md b/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-pr-draft.md new file mode 100644 index 00000000..c5252bc6 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-pr-draft.md @@ -0,0 +1,30 @@ +# Package E2E recording and presentation tools for adopter agents + +Base: `release-0.3.1` +Head: `ws-presentations/0.3.1-authoring` + +An agent in another project currently needs DevCapsule's source tree to turn +an English E2E scenario into a recorded presentation. Ship the instructions +and Python helpers in the installed executable: `presentations guide` explains +the flow, `export` supplies a standalone Playwright kit, and `hand-off` prints +the console link. The engineer can supply an existing Markdown scenario or +inline English; the agent performs the project-specific actions and assertions. + +Move the existing presentation producer into the shipped package, retaining +the repository replay adapter. Add a recorder that derives timing from action +frames and labels failed or incomplete attempts. Preserve the accepted viewer. + +Validation: 148 focused/recorder-compatibility tests and 11 integration tests passed; syntax, mypy and test conventions passed; +PEX build/smoke and the 249-page documentation contract passed; 474 webconsole +tests passed. A real browser exercised the exported kit in an unrelated scratch +project and played every chapter of passing, failed and incomplete presentations +using the viewer embedded in the executable. + +The full gate still stops on the inherited recursive Docker-group failure +after 1438 passes. Pair Review with Antigravity +`gemini-4-hydrogen-high`, `--effort high`, is complete. Review PR #46 was +accepted after one correction round and merged at `d4564313`. The final +recording/playback checks passed again after that merge. Check the live hosted +results before the owner merges into the release branch. The hosted gate +does not exercise this project's real application scenario or independently +establish presentation quality. diff --git a/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-use-case-handoff.md b/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-use-case-handoff.md new file mode 100644 index 00000000..b73e1c80 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-presentations/2026-11-16-record-use-case-handoff.md @@ -0,0 +1,72 @@ +# Owner-directed presentation-authoring use case + +From: project-management +To: presentations +Date: 2026-11-16 + +The owner requested a presentations workstream if none already exists. +No standalone workstream exists; the earlier viewer slice belonged to capsule-webconsole and is merged. +This hands over the defined use case and the two authoring messages for the new workstream's goal. +Creation does not start design or implementation; the owner explicitly deferred that work while defining this use case. +No release target or packaging interface is assigned. + +## Agreed use case + + + +An engineer works with an LLM agent in a DevCapsule on their own codebase. +The engineer wants the agent to execute an E2E scenario and present the recorded result in that capsule's web console. + +## Request + +The engineer tells the agent: + +> Run E2E with recording and presentation along the scenario described in `<scenario.md>`. + +Or: + +> Run E2E with recording and presentation along the scenario described here: `<plain-English scenario>`. + +The Markdown file already belongs to the engineer, or the engineer describes the steps inline. +The engineer supplies the scenario in ordinary language, not a recording-tool-specific script or metadata format. + +## What the agent does + +1. Read the specified Markdown file or the inline scenario. +2. Run the described E2E test in the project's environment, recording the journey. +3. Produce the presentation from that run, using the capability already demonstrated in DevCapsule. +4. Make the presentation available in that project's existing DevCapsule web console. +5. Report the test result and show the engineer the presentation link when finished. + +The agent uses the provided instructions and supporting code to handle the recording and presentation mechanics. +The engineer does not need to direct it to DevCapsule's public source or reconstruct the process with it. + +## Successful outcome + +The engineer opens the returned link in their web console and views the recorded scenario as a presentation. +The experience is the one already demonstrated by DevCapsule's web-console presentations. + +## Evidence and scope + +The owner reports that an agent already recorded an English-specified E2E scenario in another project after being pointed at this repository. +That establishes demonstrated reuse; this is not a request to invent a new process. +The owner confirms the existing viewer's human acceptance, including Florin's test and enthusiastic response. +Both engineering and prospective-user/tutorial audiences remain served by the existing presentation experience. + +The delivery need is to make the existing Markdown instructions and supporting Python/Playwright apparatus available to adopter agents. +Package layout, interfaces, installation, and implementation ownership are later work. +Do not start that design work in this use-case definition or make selecting a new example project a prerequisite. + + +## Original correspondence and source revision + +Both original messages remain available at project-management commit `cac3861e699641836dec5ba96de29fc453571784`: + +- `engineering-docs/wip/2026-08-09-project-management/intake/2026-11-16-github-auth-presentation-authoring-handoff.md` +- `engineering-docs/wip/2026-08-09-project-management/intake/2026-11-16-presentation-authoring-portability.md` + +The full use case at that revision is `engineering-docs/wip/2026-08-09-project-management/2026-11-16-design-presentation-excellence.md`. +Read the consolidated handoff for the installed-artifact audit, prior recording evidence, and existing source locations. +Current mainline `dac6b9d4` contains the recorder, producer, console contract and recording guide. +Accepting this item makes the defined use case this workstream's goal and retains the original evidence as input. +The viewer remains the accepted baseline; the deliverable is making the proven instructions and Python/Playwright support usable in other projects. diff --git a/engineering-docs/wip/2026-11-16-presentations/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-16-presentations/CURRENT-STATUS.md new file mode 100644 index 00000000..53978723 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-presentations/CURRENT-STATUS.md @@ -0,0 +1,115 @@ +# Workstream Current Status: Presentations + +Mnemonic: `presentations` +Start date: 2026-11-16 +State: paused; Pair Review complete; PR #43 awaits owner merge to release 0.3.1 +Branch association: `ws-presentations/0.3.1-authoring` +Branch prefix: `ws-presentations/` +Integration target: `release-0.3.1` +Delivery method: pull request; records published on coordination + +Definition read: WORKFLOW.md@196d3760f99e, WORKFLOW-LOCAL.md@94a29cb6eedb + +## Goal and agreed use case + +Make the proven E2E recording and presentation capability available to LLM agents in other DevCapsule projects. +Provide the existing Markdown instructions and supporting Python/Playwright apparatus without requiring a DevCapsule source clone. + +The engineer asks their agent to run E2E with recording and presentation along a scenario: + +- In an existing Markdown file supplied by the engineer; or +- Described inline in plain English. + +The agent reads the scenario, executes the E2E test, records it and creates the presentation. +When finished, it reports the result and returns a link the engineer opens in that project's DevCapsule web console. +The engineer does not need to point it at this repository or reconstruct the recording process. + +## Current state and authority + +Created at the owner's request after checking the live list, canonical mainline, open/archive directories and remote refs. +No standalone presentations workstream existed. The earlier `ws-capsule-webconsole/presentations` slice is merged. +The owner confirms that the current viewer is already human-validated, including Florin's enthusiastic test. +An agent already recorded an English-specified scenario in another project after the owner pointed it at this source. +Both engineering and prospective-user/tutorial audiences remain in scope; the existing viewer is the accepted baseline. + +The owner authorized implementation on 2026-11-16 and selected release 0.3.1. +Pair reviewer: Antigravity `gemini-4-hydrogen-high`, with `--effort high`, verified in `antigravity models`. +The existing viewer and its schema remain the contract. +The broader reusable-processes idea is not assigned wholesale to this workstream. +Project-management delivered the use case and references to both original authoring messages by coordination mail. +Acknowledged that handoff as the goal above; its full text is preserved in the handoff record. +The mailbox and intake are empty after receipt and acknowledgement. +Original correspondence is preserved on `ws-project-management/coordination` at `cac3861e` under its intake directory. +The self-contained handoff names the exact paths and evidence. + +## Planned next step + +The scoped implementation and Pair Review are complete. The owner merges +[PR #43](https://github.com/mycodespace-ai/devcapsule/pull/43) into `release-0.3.1`. +Consult the PR's live hosted checks before merging. Only the human merges the release target. +After the owner reports the merge, fetch upstream and verify the release contains this tree. +Maintenance owns carrying the release to main; do not conclude this workstream before main contains it. +Do not restart a viewer redesign, audience study or general process invention. + +## Validation and checkout state + +The implementation branch starts at `upstream/release-0.3.1` (`10e7fda3`), carrying only this workstream's registration commits from the former `ws-presentations/authoring`. +Do not synchronize with main: its development-version changes do not belong in this release-targeted slice. +The workflow text differs only in its source-version stamp; its rules were read. +The owner installed the prescribed GitHub CLI. Authentication passed as `ccozianu` on resumption. +Re-fetched upstream: release is unchanged and main differs in workflow only by the development-version stamp. +Keep the release baseline; do not merge next-cycle development-version changes. +The required pre-PR unit session again stopped at the known Docker-group failure after 1438 passes. +No open bug is owned by presentations at registration. +Product changes: `presentations guide`, `export` and `hand-off`; the existing producer is now shipped +and the repository replay harness imports it through an adapter. The portable recording helper accepts +ordinary Playwright callbacks and derives chapters/captions from captured frames. Failed and incomplete +runs keep their outcome and have labelled decks. The viewer is unchanged. + +Final validation after merging review PR #46: 148 focused/compatibility tests and 11 integration tests passed; +syntax, mypy (353 files) and conventions (0 breaches) passed. The full gate stopped at the inherited Docker-group failure after 1438 passes and 1 skip (178 deselected). +Separate PEX build/smoke, docs contract (249 pages) and webconsole checks (474 tests) passed. +An unrelated scratch project used only the final exported kit and produced passing, failed and incomplete +recordings; all six chapters played in the viewer extracted from the rebuilt PEX. See the validation record. +The exported example driver also passed its two-step browser run. +Maintenance was notified by coordination mail of the owner-directed 0.3.1 dependency. +No Docker image or capsule was launched. Temporary loopback application and console services were stopped. +The local artifact is a development validation build, not a published release candidate. + +## Pair Review + +Antigravity `gemini-4-hydrogen-high` with `--effort high` reviewed in its own worktree. +Conversation `861df986-5407-4636-8a5d-3a2d26da53fc`; initial invocation and `-c` correction round both exited 0. +Review PR [#46](https://github.com/mycodespace-ai/devcapsule/pull/46) delivered input/output guards, +recorder lifecycle tests and installed-CLI/PEX coverage. Round 1 split multi-operation unit tests, +removed fixed-cadence assertions, isolated encoder interpreter startup and clarified cwd-relative paths. +Accepted final review commit `e331693f` after reading its actual diff; merged at `d4564313`. +The assessment and acceptance comments are on PR #46. Final implementor checks are recorded below and +in the validation record. Hosted checks passed on the pre-review implementation; PR #43 holds the final live results. + +Reviewer proposals: the relative-path clarification is included. The optional nox smoke expansion was +not adopted because the new PEX integration test covers the installed delivery boundary. The requested +Chromium check and the docs contract both passed again on the merged implementation. + +## Open Threads + +- Implementation authorized; release target and reviewer settled. +- PR #43 awaits owner merge to release-0.3.1, followed by maintenance's release-to-main integration. +- Preserve the recorded viewer acceptance and demonstrated external-project recording reuse. +- Local full gate still fails on the known recursive Docker-group test; no unrelated fixture fix is included. +- Automated checks establish the kit and existing viewer contract, not a second human acceptance of presentation quality. +- Final raw acceptance files and logs are in `/var/tmp/presentations-final-acceptance`, + `/var/tmp/presentations-antigravity` and `/var/tmp/presentations-*.log`; + they are disposable and not committed. Durable outcomes are in the validation record. +- No transcript or tokened link is preserved in Git. + +## Workstream Document Index + +- [Validation record](2026-11-16-record-authoring-validation.md): installed-artifact and browser checks, counts and limits. +- [Implementation PR draft](2026-11-16-record-pr-draft.md): description prepared for PR #43, targeting release 0.3.1. +- [Round 1 brief](evidence/2026-11-16-review-round-1.md): accepted test-contract corrections and hand-off path clarification. +- [Pair Review brief](evidence/2026-11-16-review-brief.md): PR #43; exact Antigravity model and high effort. +- [Full use-case handoff](2026-11-16-record-use-case-handoff.md): owner-defined flow, constraints and original correspondence references. + +- [Intake](intake/README.md): handoff and correspondence awaiting acknowledgement. +- [Intake decisions](intake-dispositions.md): append-only record of acknowledged work. diff --git a/engineering-docs/wip/2026-11-16-presentations/evidence/2026-11-16-review-brief.md b/engineering-docs/wip/2026-11-16-presentations/evidence/2026-11-16-review-brief.md new file mode 100644 index 00000000..0470d4a0 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-presentations/evidence/2026-11-16-review-brief.md @@ -0,0 +1,140 @@ +# Pair Review brief: Antigravity, Gemini 4 Hydrogen (High) + +Implementation PR: https://github.com/mycodespace-ai/devcapsule/pull/43 +Base: `release-0.3.1`. Head: `ws-presentations/0.3.1-authoring`. +The prescribed GitHub CLI is now installed and the implementor's authentication +check passed. Check authentication once in your own session as directed below. +The PR is a draft pending this review and its hosted checks. + +## Goal and checkout + +Review `ws-presentations/0.3.1-authoring` against `upstream/release-0.3.1`. +The implementor pair is GPT-6 Codex. This is the first review of the slice. +Deliver any improvements on `ws-presentations/0.3.1-authoring-review`, forked +from the implementation branch at review start, in +`~/worktrees/presentations-review`. Work only in that worktree. Do not touch +the implementor checkout `/workspace/301e4208ef81-ChatGPT_Codex`. + +Read first, in order: + +1. `AGENTS.md`, `README.md`, `DEVELOPING.md`, `.devcapsule/devcapsule.toml`, + `WORKFLOW.md` and `WORKFLOW-LOCAL.md`. +2. `engineering-docs/wip/2026-11-16-presentations/CURRENT-STATUS.md` and + `2026-11-16-record-use-case-handoff.md` in the same directory. +3. `2026-11-16-record-authoring-validation.md` in that directory. +4. `devcapsule-src/devcapsule/presentation_tools/README.md` and + `devcapsule-webconsole/PRESENTATIONS.md`. + +The engineer supplies an existing Markdown scenario or inline English. The +agent translates that into project-specific Playwright actions and assertions, +records them and returns the existing viewer's link. The viewer is already +human-accepted. Do not redesign it, invent an English parser or require a new +user-facing scenario format. The scope is packaging the proven producer and +recording support so an adopter agent does not need this source checkout. + +## Changes and review priorities + +Read the branch diff. Review correctness, then clarity, then coverage of the +changed lines. New modules: `commands/presentations.py`, +`presentation_authoring.py`, and `presentation_tools/`. The latter contains +the existing producer moved from `tests/e2e/scenario_presentation.py`, a new +portable recorder, shipped guide and example. The old path is a compatibility +adapter; its producer tests moved to the corresponding production mirror. +Package-data, README, recording documentation and the index expose the kit. + +Check especially that an installed PEX can export complete, importable tools +without `tests` or `devcapsule` in the adopter's Playwright interpreter; that +timing, step ownership, screenshots and captions satisfy the viewer contract; +that failure/incompletion never becomes a passing result; and that existing +evidence is not overwritten. Check callback failure, capture failure, encoder +failure, repeated steps and missing steps. Check console path/token handling +without persisting tokened links. The helper intentionally uses sparse bursts +around small actions, with native video kept by the driver. + +Do not expand into a generic process framework, application provisioning, +viewer redesign, natural-language parsing, unrelated legacy test repairs or +changes to the workflow definition. Propose substantive product choices to +the implementor rather than choosing them in this review. + +For every new or changed test, verify Unit Tests rules 1–4 and 7: a module +mirror; its own explicit precondition, one public action and a promised +postcondition; a plain-English contract docstring; and a declared public +surface. Name what could make each fail for a reason that is not a bug. +Verify Host Inputs rules 1–6 on code and tests: host reads only at entry; +required explicit values thereafter; shared host values in frozen data; +decisions separate from effects; no monkeypatch, unittest.mock, environment +mutation or module/class attribute replacement; short entry sequencing tested +through a real program in an integration test. Respect legacy-test retirement +and command-line test restrictions. Do not weaken tests to obtain a green gate. + +## Environment and validation + +The implementor has prepared a separate `devcapsule-src/.venv` in your worktree +using the local workflow's validation instructions. Your branch starts at +`78f512c2`; later implementor commits only update review records. As the review +partner, do not run workflow claim, mail or publish commands; the Pair Review +exception governs over the ordinary session-start instructions. Run from `devcapsule-src`: + +```sh +mkdir -p /var/tmp/presentations-antigravity +DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 .venv/bin/python -m pytest -q --no-cov tests/unit/devcapsule/presentation_tools tests/unit/devcapsule/test_presentation_authoring.py +DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 PYTEST_ADDOPTS='--basetemp=/var/tmp/presentations-antigravity/pytest --maxfail=1' .venv/bin/python -m nox -s build +``` + +Use that separate scratch because `/opt/devcapsule-gate` is read-only on this +host; Validation Commands permits another directory with room. The known +inherited Docker-group failure may stop the full gate; report it and do not +repair that unrelated fixture. The implementor's separate PEX, docs and +webconsole checks passed. Its real Chromium checks covered passing, failing +and incomplete recordings and playback of every generated chapter. If code +changes invalidate this evidence, request a focused rerun from the implementor. +Do not build images, launch capsules, install browsers or provision services. +Report what the hosted gate does not catch. + +## Authorship and delivery + +Check `git var GIT_AUTHOR_IDENT`. Preserve the human author +`Costin Cozianu <ccozianu@gmail.com>`. Credit the actual reviewer engine/model +using `Co-authored-by: Antigravity (Gemini 4 Hydrogen High) <noreply@google.com>`, +consistent with existing Antigravity commits; verify the actual model before crediting it. + +Detect GitHub CLI only at `/opt/xtras/miniconda3/envs/gh/bin/gh`. In each shell +using it, activate it first: + +```sh +source /opt/xtras/miniconda3/etc/profile.d/conda.sh && conda activate gh +``` + +Check `gh auth status -h github.com` once before first use. On auth failure, +stop and report; no retries or alternate credentials. If absent, stop at the +owner-operated PR handoff prescribed in WORKFLOW-LOCAL. Use ordinary Git SSH +to push the review branch to `upstream`. + +After required checks, create the review PR against +`ws-presentations/0.3.1-authoring`, never against the release or main. Its body +lists findings (problem, location, change, evidence), what was considered and +left alone with reasons, unimplemented proposals, and validation counts/limits. +If nothing changes, report that and create no empty PR. Do not merge, rebase, +force-push, change workstreams, edit status/intake/published state, or send mail. +At most three review rounds; the implementor assesses the actual diff. + +Finish with exactly one of these forms, filling the result: + +`PAIR REVIEW COMPLETE: <review PR URL or no changes>; <counts and limits>` + +`PAIR REVIEW BLOCKED: <specific blocker and next human action>` + +## Invocation for the implementor + +The model catalog was checked on 2026-11-16. Use the exact listed ID and the +explicit effort setting; do not substitute a model: + +```sh +antigravity --model gemini-4-hydrogen-high --effort high --dangerously-skip-permissions --output-format stream-json -p 'Follow the Pair Review brief on standard input.' < <brief-path> +``` + +Run detached in the review worktree, capture its streaming output in session +scratch and append its exit status. Relay start, commits, gate results and end +to the human. Keep this brief as the reviewer's only task context. Record the +actual invocation and outcome in the Pair Review development document after +the loop runs; this brief alone is not evidence of a completed review. diff --git a/engineering-docs/wip/2026-11-16-presentations/evidence/2026-11-16-review-round-1.md b/engineering-docs/wip/2026-11-16-presentations/evidence/2026-11-16-review-round-1.md new file mode 100644 index 00000000..e8e9bb7a --- /dev/null +++ b/engineering-docs/wip/2026-11-16-presentations/evidence/2026-11-16-review-round-1.md @@ -0,0 +1,52 @@ +# Round 1: test-contract corrections for PR #46 + +Continue the same Antigravity Gemini 4 Hydrogen High review of PR #43. +I read the actual diff of PR #46 at `e40d16a5`. The product fixes are accepted +in principle; make only the following corrections before integration. Do not +repeat the broad investigation or widen product behavior. + +1. Make the new recorder unit tests follow WORKFLOW-LOCAL Unit Tests rule 2: + one public action under test, with setup stated separately. In particular: + - `test_recording_keeps_failed_outcome_and_reached_steps_when_callback_fails` + tests the callback exception, rejection of a later action and finalization. + Split those into distinct contracts/tests, constructing each precondition. + - Split repeated finish from action-after-finish. + - Split or parameterize empty evidence versus missing screenshot evidence. + - Split or parameterize encoder nonzero exit versus successful exit without + output. Each case should call `finish` once as its action under test. + - The passing-run test may prepare its run through `action` calls, then test + `finish`; make that separation explicit. Its numeric `[8,16,24]`, fixed + duration and fixed repeated frame bytes encode the current burst cadence, + which the public contract does not promise. Assert the contract instead: + logs have increasing frame boundaries, chapters/captions align to those + boundaries and the video duration, and encoder input equals captured data. + Do not declare a new public cadence guarantee merely to keep the assertions. + - Keep the controlled encoder subprocess (running the encoder is part of + `finish`'s contract), but isolate its interpreter invocation from ambient + Python startup customization with `-I -S`. + Correct the PR body's blanket claim that every new test already has one + public action. Report concrete non-bug failure conditions for the final tests. +2. Clarify the shipped guide's hand-off example: run it from the console project + root; a relative evidence folder resolves from cwd, and `--project` supplies + the root used to form the console-relative link. No resolution behavior change. + +Do not add the proposed nox smoke expansion: the new PEX integration test already +covers this delivery boundary. The implementor will rerun the real Chromium +acceptance and docs contract on the merged branch. No browser/service/container +work in your worktree. Do not edit workstream records or published state. + +Run from your worktree's `devcapsule-src`: + +```sh +DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 .venv/bin/python -m pytest -q --no-cov tests/test_scenario_recorder.py tests/unit/devcapsule/presentation_tools tests/unit/devcapsule/test_presentation_authoring.py +DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 .venv/bin/python scripts/validate_unittests_follow_conventions.py +DEVCAPSULE_DIFF_BASE=upstream/release-0.3.1 PYTEST_ADDOPTS='--basetemp=/var/tmp/presentations-antigravity/round-1 --maxfail=1' .venv/bin/python -m nox -s build +``` + +The known Docker-group limitation remains disclosed. Do not repeat the other +unchanged suites merely to accumulate checks. Commit on your existing review +branch with the established authorship, push via upstream SSH and update PR #46 +using the prescribed Conda gh environment. Preserve previous findings and limits, +update the unit counts, and mark this response to Round 1. No merge/rebase/force push. +Finish with `PAIR REVIEW COMPLETE: <PR URL>; <counts and limits>` or the established +blocked form if necessary. diff --git a/engineering-docs/wip/2026-11-16-presentations/intake-dispositions.md b/engineering-docs/wip/2026-11-16-presentations/intake-dispositions.md new file mode 100644 index 00000000..7751f3e6 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-presentations/intake-dispositions.md @@ -0,0 +1,5 @@ +# Presentations intake decisions + +| Item | Dispositioned | Outcome | Note | +|---|---|---|---| +| `2026-11-16-project-management-presentation-authoring.md` | 2026-11-16 | acknowledged | Accepted as this workstream's goal; full handoff preserved in `2026-11-16-record-use-case-handoff.md`; design and implementation remain deferred. | diff --git a/engineering-docs/wip/2026-11-16-presentations/intake/README.md b/engineering-docs/wip/2026-11-16-presentations/intake/README.md new file mode 100644 index 00000000..f8c86d73 --- /dev/null +++ b/engineering-docs/wip/2026-11-16-presentations/intake/README.md @@ -0,0 +1,4 @@ +# Presentations intake + +Incoming work awaiting acknowledgement under WORKFLOW.md topic 8. +The workstream's goal and current task are in [its status file](../CURRENT-STATUS.md). diff --git a/engineering-docs/work-orders/2026-11-08-test-improvements.md b/engineering-docs/work-orders/2026-11-08-test-improvements.md new file mode 100644 index 00000000..a9bf911c --- /dev/null +++ b/engineering-docs/work-orders/2026-11-08-test-improvements.md @@ -0,0 +1,221 @@ +# Work Order: Test improvements — declared public surfaces, no patching of project modules, and the discovery module as the first move + +Origin: owner and `maintenance` pair, in conversation on 2026-11-08, over one highlighted test, +`test_rider_discovery_uses_linux_release_with_checksum` in `devcapsule-src/tests/test_dotnet_rider_components.py`. +Status: delivered to `project-management` by mail on 2026-11-08; the owner asks that a `test-improvements` +workstream be opened from it. Not assigned. Implementation has not started. +Coordination owner: `project-management`. Implementation owner and target: the new workstream, on `main`. +Requirements: none. This is a process and code-quality order; it changes no product behaviour. +Supersedes nothing. It gives a home to the follow-ups queued in the maintenance status under +*Unit-test conventions — 2026-11-03*: the measured refactor of the legacy test debt, module by module. + +## Outcome + +Unit tests in this repository establish their preconditions by constructing inputs and calling one public +operation of the unit, never by replacing the unit's private parts from outside. Every module that a unit test +exercises says what is public. The gate refuses a test that patches a project module, so the cheap way to write +a test and the right way become the same way. The pattern is removed from the suite one module at a time, with +the owner choosing each module, and the first module is `devcapsule/components/discovery.py`, where the pattern +was born. + +## What exists today + +*Unit Tests* in `WORKFLOW-LOCAL.md` (owner direction of 2026-11-03, PR #335) states the rules a conforming +test follows: mirror placement, the Hoare triple with the precondition established by the test, a docstring, +and, in rule 4, that a unit with no declared public surface is not testable until it declares one. The gate's +checker, `devcapsule-src/scripts/validate_unittests_follow_conventions.py`, holds placement, docstrings and the +shrinking of legacy files. It does not hold rule 4, and no rule names patching at all. + +The preamble of the project workflow definition names the discipline this order serves: that the best interface +hides the decision most likely to change, which is what information hiding has meant since Parnas said it. The +ast-grep guardrails order (2026-10-29) names the mechanism that defeats it: an agent reproduces whatever pattern +it finds, so spread compounds. Both are in the repository. Neither reaches a pair at the moment it writes a test. + +The highlighted test shows the result. It is named for a checksum it never checks. It has no docstring. It +reaches the adapter by replacing `discovery.read_json`, a module helper, with a lambda that discards the address +it is asked for. Its one assertion indexes into a tuple that may be empty. The history is verified: + +- The discovery module and the first tests that patch its helper arrived in one commit on 2026-09-21. +- Every later component that changed the module added a test copying the patch: Rider and Eclipse on + 2026-10-04, VS Code on 2026-10-28. Eleven tests across four files patch `discovery.read_json` or + `discovery.read_metadata`. +- The module declares no `__all__`. Its docstring states a purpose, not operations. The component status + module imports `read_metadata` from it, so a private transport helper became a shared one by accident. +- The assumption behind the patch, that the public operation calls the helper exactly once, is already false: + the Claude Code adapter reads a latest pointer with one helper and a manifest with the other, at a + different address, and the parametrized test in `test_component_status.py` answers both with the same + document because its lambdas ignore the address. The test cannot tell which feed answered which question. +- The 2026-11-03 record already notes that pair review had endorsed a dissected test by name and dismissed + its private monkeypatch as "confined to tests". + +Measured on `main` at 8c5a4723, 2026-11-08: + +| Measure | Launcher (`devcapsule-src`) | Web console | +|---|---|---| +| test files that use `monkeypatch` | 69 | — | +| `monkeypatch.setattr` calls | 346 | 22 | +| modules declaring `__all__` | 33 of 137 | 0 of 8 | + +The most patched targets, by the first name of the target expression: `status` 16, `offer` 15, +`runtime_configuration` 14, `discovery` 11, `command_module` 11, `scenario_recorder` 9; by dotted string, +`sys.stdin` 43 and `devcapsule.container_runtime` 27. These numbers are the baseline the workstream measures +against; they are not targets in themselves. + +## Decisions already taken + +1. **The owner's ruling on the pattern.** A module helper such as `read_json` is not part of the public + interface of `discovery.py`. Replacing it from a test, on the assumption that the operation under test calls + it once and by that name, tests the implementation's call shape and not the unit's contract. The pattern is + refused for conforming tests, not reviewed case by case. +2. **The gate holds it, not the reviewer.** The owner's judgment, consistent with the ast-grep order: this is the + hardest kind of rule for a language model to follow from a statement of belief, because the models have + learned from a corpus in which patching is the dominant idiom and it is the path of least change. A belief in + the preamble does not act at the moment of writing. A gate line does. The rule therefore becomes a checked + rule under *Unit Tests*, and the briefs carry it in one line. +3. **The pairs copy what they find, so the corpus must contain the right shape.** The first refactored module is + the worked example that later pairs copy. It is the discovery module, because the pattern was born there and + the seam is cheapest to add. +4. **A `test-improvements` workstream is opened for this.** `maintenance` stays on the release candidates of + 0.3.1 and does not take the implementation. The target is `main`; nothing in this order goes to + `release-0.3.1`. +5. **From the 2026-11-03 record, unchanged:** the refactor of the legacy debt proceeds module by module, with the + owner choosing the module; a legacy file only loses tests; a test you change is brought to the rules and + moved to the mirror. Frameworks for contracts and property-based testing are decided inside the first + implementing slice, not before it. +6. **Design is the owner's.** Separating fetching from interpretation in the discovery module changes a module + boundary. The executing pair proposes the shape with the two candidates below and the owner rules before + code is written. The same holds for every later module. + +## Deliverables, in slices + +Each slice is one pull request to `main` through the Pair Review Loop, with the unit session run on the branch +as pushed before the pull request opens. + +### Slice 0: the rules and the gate + +1. **Rule 8 under *Unit Tests* in `WORKFLOW-LOCAL.md`.** A conforming test does not set, replace or mock any + attribute of a module of this project, whether by `monkeypatch.setattr`, `unittest.mock.patch` or + assignment. It establishes its precondition by constructing the unit's inputs and calling one public + operation. Patching the standard library or a third-party module is permitted and is named in the + docstring, so the reviewer sees it. When a pair cannot test a unit without patching it, the required move is + to stop and report that the unit has no seam, under rule 4; the report goes to the owner as a design + question, and no test is written around it. +2. **Rule 4 made checkable.** Every module under `devcapsule-src/devcapsule/` and under the web console + package declares `__all__`. Since 104 launcher modules and all 8 console modules lack one today, the rule + is held the way legacy files are held: the checker compares with the pull request's base, a module the + pull request touches must declare its surface, and the count of undeclared modules goes down and never up. + The checker's summary line reports it beside the legacy counts. +3. **Imports respect the surface.** A `from devcapsule.<module> import <name>` in project code or in a test, + where the imported module declares `__all__`, names only members of that `__all__`. Held by the checker from + the base, the same way. The first known breach is the component status module's import of `read_metadata`; + slice 1 removes it. +4. **The checker extension.** `validate_unittests_follow_conventions.py` gains the three checks above, each + with a valid and an invalid case in its own mirror test file, in triple form. A breach prints one line naming + the file, the rule and what to do instead. The checker stays a single script run by the `tests` and `build` + sessions and the hosted `tests.yml` step; no new tool is introduced here. If the ast-grep guardrails order + is executed first, the pattern rules may move there; this order does not wait for it. +5. **The house convention for units with effects**, one section in + `engineering-docs/development/unit-tests.md`: a unit that reads the network, the filesystem, the clock or a + process takes the effect's result, or the effect itself, at its public boundary, or splits into a pure + interpretation and a thin fetcher with its own small contract. The section points at the discovery module + as the worked example once slice 1 lands. One paragraph on what a fake is for and what it is not: a fake + stands in for a collaborator the unit receives, never for a part of the unit itself. +6. **The brief.** The brief template in `engineering-docs/development/review-partner-loop.md` and rule 7 of + *Unit Tests* gain one line for the implementor: no patching of project modules; if the unit offers no seam, + report the missing surface instead of building one in the test. The reviewer checks it mechanically: no + `setattr` or `patch` whose target starts with the project's package name in any new or changed test. + +Done means: the three checks run in the gate against the measured baseline with zero breaches on `main`; a +deliberately patched mirror test and a deliberately undeclared touched module each fail the gate with the rule's +message, output captured in the pull request. + +### Slice 1: the discovery module + +1. **Public surface declared.** `discovery.py` declares `__all__`. The transport helpers are either private to + it or moved to a module whose purpose is transport, with its own `__all__`; the component status module + imports from wherever that is, by name in that `__all__`. +2. **Fetching separated from interpretation.** Two candidate shapes, for the owner to choose between before + code is written: + - *Documents in, reports out.* Each adapter is a function, or an object with one operation, from a vendor + document already read to a `ChannelReport`. A thin fetcher reads the addresses the adapter names and + calls it. A two-feed adapter, such as Claude Code's, takes its two documents by name. + - *A reader passed in.* The adapter keeps its `check(current, platform)` operation and receives the reader + at construction, with the production reader as the default supplied by the caller that wires the + catalog, not by the adapter module. + Either way a test constructs a document and calls the one public operation. Nothing in `devcapsule` is + patched. +3. **The transport contract tested once.** Size bound, timeout, user agent and the JSON decode are tested + against bytes the test constructs, through the reader's public operation. The present test that patches + `urlopen` on the module goes with the rest. +4. **The eleven tests moved.** The eleven patching tests across `test_component_status.py`, + `test_dotnet_rider_components.py`, `test_eclipse_component.py` and `test_vscode_component.py` are brought to + rules 1 to 4 and 8 and moved to the mirror, each a triple with a docstring. The highlighted test becomes true + to its name: one test that a release with a Linux download and checksum link is reported, one that a release + missing the checksum link is refused. The two-feed adapter is tested with two named documents and with the + version mismatch between them refused. The legacy count in the checker's summary goes down by eleven. +5. **The framework decision.** `exact_version` and `_available` are the trial for property-based testing, and + the adapter contract is the trial for a contracts library, if the pair proposes one. The pair records the + decision, with its measurement, in the workstream status; a "no, plain pytest" is a valid decision. + +Done means: `grep -rn "monkeypatch.setattr(discovery" devcapsule-src/tests` finds nothing; the mirror holds the +tests; `nox -s build` and `nox -s typecheck` pass; the discovery adapters' observable behaviour, the reports +they produce for the same documents, is unchanged, shown by the moved tests passing against both the old and +the new module before the old one is deleted. + +### Slice 2 and after: one module per slice, the owner choosing + +The owner names the next module from the measured table, or from an incident. Each slice declares the module's +surface, adds or exposes the seam the owner has chosen, moves that module's legacy tests to the mirror in triple +form, and reports the two counts, legacy tests and undeclared modules, before and after. A slice that finds a +missing seam stops and asks, as rule 8 requires. The workstream keeps a one-table ledger in its status: module, +patch sites before, tests moved, seam shape chosen, pull request. + +The web console is in scope for rule 4 and rule 8 from slice 0 onward: it has eight modules, none declaring a +surface yet, and 22 patch sites, so the whole package is one or two slices. Its first module is the owner's +choice as well. + +## Acceptance evidence + +1. The hosted run for each pull request, linked from the pull request body, with the checker's summary line + quoted: legacy files and tests, undeclared modules, breaches zero. +2. Slice 0: the captured gate output for the two deliberate breaches. +3. Slice 1: the grep above empty; the eleven tests listed by new path; the before-and-after report equality + shown in the pull request body, by the method the pair chose and names. +4. Each later slice: the ledger row, and the two counts going down. +5. The workstream's status file carries the owner's seam rulings as decisions, by module. + +## Execution decisions and stopping points + +The implementing workstream owns: the wording of the checker's messages, the placement of the transport +module, the structure of the mirror test files, and whether a fake collaborator lives in the mirror's conftest +or beside its test. + +Stop and consult the owner before: + +- choosing the seam shape for the discovery module, and for every module after it; +- adding any testing framework or library; +- changing a module's observable behaviour while moving its tests, however small; +- touching `release-0.3.1` or any branch of a release; +- extending the rules to the integration or end-to-end suites, which this order does not cover; +- deciding that a module's surface is "everything", which is not a declaration. + +The owner names the workstream, confirms its first slice, and chooses every module after the first. + +## Mainline evidence read before writing + +On `main` at 8c5a4723 and the worktree of 2026-11-08: `WORKFLOW.md` sections 2.5, 8 and 12.11; +`WORKFLOW-LOCAL.md` *Unit Tests*; `engineering-docs/development/unit-tests.md` and `review-partner-loop.md`; +`devcapsule-src/scripts/validate_unittests_follow_conventions.py`; `devcapsule-src/devcapsule/components/discovery.py` +and `component_status.py`; the four test files named above; the maintenance status section *Unit-test +conventions — 2026-11-03*; the ast-grep guardrails order; the project workflow preamble's *What We Believe*; +the git history of `discovery.py` and of the four test files. The counts in the table come from `grep` over the +two test trees and the two packages at that revision. + +## Pushback recorded with the draft + +The pair first held that the highlighted test, being marked `legacy` and untouched since the rule of +2026-11-03, breached nothing, and that the fault was the unit's missing seam rather than the test. The owner +answered that tests here are written with the module they test, so the test and the seam are one decision, and +that a test added later copies the pattern of the tests written with the module; the history above confirmed +both. The pair's point survives only as the order's first deliverable: the seam has to exist before the test can +be right, so the rule tells the pair to stop and ask for it rather than patch around it. diff --git a/index.md b/index.md index 5a1fd88d..cc0a839e 100644 --- a/index.md +++ b/index.md @@ -44,7 +44,10 @@ status file; internal WIP/archive documents use the local index in that status. - [Unit tests](engineering-docs/development/unit-tests.md) - [Integration tests](engineering-docs/development/integration-tests.md) - [End-to-end tests](engineering-docs/development/e2e-tests.md) +- [Packaged agent instructions for E2E recording and presentation](devcapsule-src/devcapsule/presentation_tools/README.md) - [Running E2E scenario recordings from a shell with nox](engineering-docs/development/running-e2e-scenario-recordings.md) +- [Web console presentations: discovery, storage and generation](devcapsule-webconsole/PRESENTATIONS.md) +- [E2E scenario script: GitHub SSH through the host proxy](devcapsule-src/tests/e2e/scripts/github-ssh-proxy.md) - [E2E scenario script: FastAPI + PostgreSQL 17 + React Todo application](devcapsule-src/tests/e2e/scripts/todo-fastapi-postgres-react.md) - [E2E scenario script: Java 25 + Spring Boot + PostgreSQL 17 in IntelliJ IDEA](devcapsule-src/tests/e2e/scripts/springboot-postgres-java.md) - [Pair Review Loop](engineering-docs/development/review-partner-loop.md) @@ -105,6 +108,7 @@ status file; internal WIP/archive documents use the local index in that status. - [Capability configuration: implementation and test correctness](engineering-docs/implementation-notes/devcapsule/2026-10-06-configuration-correctness.md) - [Capability configuration: persistent selection versus execution projection](engineering-docs/implementation-notes/devcapsule/2026-10-08-configuration-composition-correctness.md) - [Scenario-driven E2E IDE controller and pause-free WebM video recorder](engineering-docs/implementation-notes/devcapsule/2026-10-21-e2e-scenario-video-recorder.md) +- [Testing the macOS launcher on cloud Mac hardware, and the alternatives](engineering-docs/implementation-notes/devcapsule/2026-11-08-testing-the-macos-launcher-on-cloud-mac-hardware.md) - [Eclipse Java component and recorded smoke validation](engineering-docs/implementation-notes/devcapsule/2026-10-04-eclipse-validation.md) - [Linux .NET SDK and Rider validation](engineering-docs/implementation-notes/devcapsule/2026-10-04-dotnet-rider-validation.md) - [IntelliJ, Playwright and graphical smoke validation](engineering-docs/implementation-notes/devcapsule/2026-10-04-intellij-playwright-validation.md) @@ -146,6 +150,7 @@ status file; internal WIP/archive documents use the local index in that status. ## Work Orders +- [Test improvements: declared public surfaces, no patching of project modules, the discovery module first](engineering-docs/work-orders/2026-11-08-test-improvements.md) - [Wrapped projects: a foreign repository as a submodule, three commands](engineering-docs/work-orders/2026-11-02-wrapped-projects.md) - [0.3.0 user documentation CLI alignment, full stub authoring, and prose review — maintenance, 0.3.0](engineering-docs/work-orders/2026-10-30-user-docs-0-3-0-cli-alignment.md) - [CI path gating and advisory diff coverage — maintenance, 0.3.0](engineering-docs/work-orders/2026-10-30-ci-path-gating-and-diff-coverage.md) @@ -180,12 +185,15 @@ status file; internal WIP/archive documents use the local index in that status. ## Workstream Status +- [Presentations](engineering-docs/wip/2026-11-16-presentations/CURRENT-STATUS.md): agent-driven E2E recordings and presentations in adopter projects. + - [Multiple-stream workflow successful archive](engineering-docs/archive/2026-08-08-multi-workflow/CURRENT-STATUS.md) - [Recursive dogfood E2E successful archive](engineering-docs/archive/2026-08-06-recursive-e2e/CURRENT-STATUS.md) - [Eclipse interactive surface, concluded 2026-10-01 and folded into component-catalog](engineering-docs/archive/2026-09-09-eclipse-surface/CURRENT-STATUS.md) - [Project management current status](engineering-docs/wip/2026-08-09-project-management/CURRENT-STATUS.md) - [Workflow improvements current status](engineering-docs/wip/2026-08-09-workflow-improvements/CURRENT-STATUS.md) - [Component upgrades current status](engineering-docs/wip/2026-09-21-component-upgrades/CURRENT-STATUS.md) +- [GitHub authentication current status](engineering-docs/wip/2026-11-16-github-auth/CURRENT-STATUS.md) - [Maintenance current status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) - [Capsule web console current status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) - [Wrapped projects current status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) @@ -244,6 +252,7 @@ status file; internal WIP/archive documents use the local index in that status. ## Development Blog +- [Thirteen hours, thirty-five tests. Part 1: the AI's audit](engineering-docs/blog/2026-11-13-thirteen-hours-thirty-five-tests.md) — Claude's unedited audit of its own pull request against stricter test standards: the ledger, what got worse, where the rules are wrong, and why LLMs wrote tests the other way; Part 2 to follow. - [Diagnosing a capsule from both sides](engineering-docs/blog/2026-10-28-diagnosing-a-capsule-from-both-sides.md) — probing a live browser desktop from outside and inside a nested PyCharm capsule, with embedded recording; draft for owner review. - [An AI takes our IDEs for a test drive](engineering-docs/blog/2026-10-04-an-ai-takes-intellij-for-a-test-drive.md) — shared AI graphical tests across IntelliJ, Rider and Eclipse, the .NET build, and three original recordings; draft for owner review. - [The workflow explains itself](engineering-docs/blog/2026-10-03-the-workflow-explains-itself.md) — preamble, information model, merge rule, and a bug filed against ourselves; draft for owner review.