Add reproducible Nix development and preview environment #20

Challenge #

Trawler’s Linux automation exercises trawler-core, but a clean NixOS environment cannot build or test the complete workspace because the GPUI application’s native XCB, xkbcommon, font, Wayland, and Vulkan dependencies are not available through a coherent linker and runtime environment.

The project also lacks a safe way to launch and visually inspect the real GPUI application on a headless development host. Existing fake-platform tests and devtools automation cover substantial behavior, but they do not provide a reproducible path from a clean checkout to a real rendered window, semantic inspection, and screenshot capture without relying on a Windows machine or risking the user’s graph.

Specifications #

Added: nix-development-environment #

This change proposes, implements, verifies, and archives a new capability specification covering:

• a pinned x86_64 Linux Nix development shell for the full Rust workspace;
• successful linking and execution of the GPUI and core test suites;
• isolated real-application preview under a private virtual display and software Vulkan renderer;
• long-lived, rediscoverable preview sessions for iterative agent interaction;
• deterministic semantic dumps and PNG screenshots through Trawler’s existing devtools protocol;
• structural isolation from the user’s default graph;
• bounded startup failures, stale-session diagnosis, signal-safe cleanup, and preserved artifacts;
• concrete documentation for headless automation and native Linux scratch-graph development.

No existing capability specification is modified. The new specification consumes the existing fixture-graphs, ui-test-harness, and dev-automation-server contracts without changing their behavior.

The completed change history is retained at:

openspec/changes/archive/2026-08-01-add-nix-devshell/

The synced project specification is:

openspec/specs/nix-development-environment/spec.md

Implementation #

• Adds a locked Nix flake whose Rust toolchain is derived from rust-toolchain.toml.
• Provides the native GPUI/X11/XCB/xkbcommon/font/Wayland/Vulkan and screenshot dependencies needed by the complete workspace.
• Adds tools/trawler-preview.py with:
  • start
  • status
  • send
  • screenshot
  • stop
  • smoke
• Runs the real devtools-enabled GPUI binary against a fresh fixture graph under Xvfb, Mesa lavapipe, and a minimal EWMH window manager.
• Validates session ownership and process identity before control or cleanup operations.
• Validates screenshot structure, CRCs, compressed image data, dimensions, and termination before reporting success.
• Documents both deterministic headless preview and manual native-desktop development using an explicit scratch graph.

Effective outcome #

A developer or agent can enter nix develop from a clean checkout and build, lint, and test the complete workspace without installing host-global packages.

The same environment can launch the real Trawler application without a graphical login session, navigate it through the existing JSONL devtools protocol, inspect semantic UI state across multiple operations, and capture a previewable 900×600 PNG. Automated preview cannot infer or open the user’s default graph and cleans up its application, window-manager, display, and disposable graph state after success, interruption, or explicit stop.

This expands Trawler’s development and verification capability on Linux; it does not declare Linux an end-user release target. Windows 11 remains the authoritative product and final interaction-check platform.

Verification #

nix flake check --no-build                              pass
cargo check --workspace --all-targets                   pass
cargo test --workspace                                  150 passed, 0 failed, 5 ignored
cargo clippy --workspace --all-targets -- -D warnings   pass
cargo fmt --all -- --check                              pass
ruff check tools/trawler-preview.py                     pass
openspec validate nix-development-environment --strict  pass

Both lifecycle modes were exercised from clean temporary state:

• long-lived start → status → send → dump → screenshot → stop across separate shell invocations;
• one-shot semantic and visual smoke verification;
• duplicate-start refusal;
• SIGINT/SIGTERM cleanup;
• stale-session recovery after a hard child exit;
• malformed-manifest handling;
• idempotent cleanup with no leaked preview processes or fixture graph.

The devshell sets RUST_TEST_THREADS=1 because the existing Steel interruption test enforces a strict wall-clock bound and can fail spuriously under parallel debug load; this is scoped to the development shell and can be overridden for a faster best-effort parallel run.

Agent disclosure #

I am Hollis, a persistent software-engineering agent operated by Graham Barber and represented on AT Protocol as did:plc:aqicwyouvv65bm5vpmvcodui.

I am currently operating with openai-codex/gpt-5.6-sol at high reasoning effort through Letta Code. I developed this implementation against the repository’s OpenSpec artifacts, validated it through the checks above, and committed it under my own authorship and SSH signing identity.