High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
chore: update docs, e2e tooling, and drop stale generated types
Bosch9e0ba426d9d7
diff --git a/dev b/devindex f13c660e..b16d0607 100755--- a/dev+++ b/dev@@ -42,7 +42,7 @@ COMMANDS=(" cli-extended:π³:CLI extended tests"" infra-extended:π³:Infra extended (multi-instance)"" test <name>:π³:Run a single E2E test by start_test name"- "smoke:π¨:Docker smoke checks (use --browser=chrome|cloak|ghost-chrome|all or filter names)"+ "smoke:π¨:Docker smoke checks (use --browser=chrome|cloak|all or filter names)"" cloakbrowser:π¨:Docker browser parity / CloakBrowser smoke"" cdp-attach:π¨:Docker CDP attach smoke"" live-detection:π¨:Advisory live detection-site probe (external network)"diff --git a/docs/architecture/browser-abstraction.md b/docs/architecture/browser-abstraction.mdindex 8873f777..dac32d59 100644--- a/docs/architecture/browser-abstraction.md+++ b/docs/architecture/browser-abstraction.md@@ -1,21 +1,24 @@# Browser Abstraction-Status: partially implemented (BridgeAPI encapsulation complete; browser registry extraction in progress)+Status: implemented (BridgeAPI encapsulation and browser registry extraction complete)Owner: bridge-## Problem+## Problem (historical)-Adding a new browser (e.g. lightpanda, brave, firefox) requires editing at least five unrelated files. Provider-specific logic is scattered across `config/`, `bridge/runtime/`, `browserprobe/`, and `doctor/`, coupled by string switches on `NormalizeBrowserProvider()` and predicates like `IsCloakBrowserProvider()`.+Before the registry extraction, adding a new browser required editing at least+five unrelated files: provider-specific logic was scattered across `config/`,+`bridge/runtime/`, `browserprobe/`, and `doctor/`, coupled by string switches+and per-provider predicates. Those branch points now route through one+abstraction each:-Current branch points:--| Concern | Location | Mechanism |+| Concern | Location | Mechanism today ||---|---|---|-| Launch flags | `internal/bridge/runtime/init.go` | `IsCloakBrowserProvider()` gate + `CloakBrowserFlagArgs()` |-| Geo alignment | `internal/bridge/runtime/geo_align.go` | `switch NormalizeBrowserProvider(...)` |-| Binary discovery | `internal/browsers/runtimekit/runtimekit.go` | Provider-driven `FindBrowserBinary(...)` discovery |-| Doctor registry | `internal/doctor/runner.go` | `if IsCloakBrowserProvider()` adds checks |-| Config validation | `internal/config/browser_targets.go` | Hardcoded `{chrome, cloak}` allowlist |+| Launch flags | `internal/browsers/<id>/` + `internal/browsers/runtimekit/` | per-provider `BuildLaunchArgs` via `ResolveProviderLaunchPlan` |+| Geo alignment | `internal/browsers/` config | provider capabilities + `GeoConfig` on the launch plan |+| Binary discovery | `internal/browsers/<id>/` | per-provider `DiscoverBinary()` |+| Doctor checks | `internal/doctor/browsers.go` | per-provider `DoctorChecks()` from the registry |+| Config validation | `internal/config/browser_targets.go` | registry-driven (`browsers.Get`/`browsers.IDs`) |+| Lifecycle cleanup | `internal/browsers/providerhooks/` | registered `Hooks` (decorate, cleanup, shutdown) |`Engine` (`chrome` / `lite` / `auto`) β **deprecated**; replaced by the browser provider model (`chrome` / `cloak` / `ghost-chrome`). See [routing-contract.md](routing-contract.md) and [terminology.md](terminology.md) for the canonical provider definitions. `Capabilities` are additional concepts layered on top, partially wired.@@ -297,6 +300,14 @@ The target architecture is implemented through Phase 6. Key components:- **Handlers** β use only `BridgeAPI`. Navigate and Snapshot handlers call`Bridge.Navigate()` and `Bridge.Snapshot()` respectively. No `StaticBrowser`field, no ghost-chrome conditionals, no routing package imports.+- **Deferred-launch two-phase navigate** β for fresh new-tab navigates the+ handler probes `StaticFirstNavigate()` and runs phase 1 with+ `NavigateParams.NoEscalate`: the adapter attempts the static browser only+ and signals `*bridge.StaticEscalateError` instead of escalating internally,+ so Chrome is launched only when actually needed. Phase 2 re-runs with+ `SkipStatic`. The timeout budget is per phase (each phase gets+ `NavigateTimeout`, default 30s), so a navigate that escalates can take up+ to twice the configured timeout.- **Route metadata** β `usedProvider` is consistently `"ghost-chrome"` for alladapter paths. Static vs Chrome routing recorded in `Attempts[]`.- **`internal/routing/`** β deleted.diff --git a/docs/guides/attach-chrome.md b/docs/guides/attach-chrome.mdindex 03a66be3..cd3e13e7 100644--- a/docs/guides/attach-chrome.md+++ b/docs/guides/attach-chrome.md@@ -52,13 +52,15 @@ The attach request body is:"name": "shared-chrome","cdpUrl": "ws://127.0.0.1:9222/devtools/browser/...","provider": "chrome",- "browserTarget": "chrome-local"+ "browser": "chrome-local"}```-`browserTarget` is optional. When `browser.targets` is configured, an omitted-value attaches to the configured default target and the target's browser is used.-If you also pass `provider`, it must match that target. Without browser targets,+`browser` is optional and accepts a provider name (`chrome`, `cloak`) or a+configured target name from `browser.targets`. When `browser.targets` is+configured, an omitted value attaches to the configured default target and the+target's browser is used. If you also pass `provider`, it must agree with the+`browser` value. Without browser targets,`provider` defaults to `chrome`; use `cloak` for a CloakBrowser endpoint(equivalent to `--browser cloak` on the CLI).@@ -145,7 +147,7 @@ curl -X POST http://localhost:9867/instances/attach \-d '{"name": "shared-chrome","cdpUrl": "ws://127.0.0.1:9222/devtools/browser/abc123",- "browserTarget": "chrome-local"+ "browser": "chrome-local"}'# Response{@@ -158,8 +160,7 @@ curl -X POST http://localhost:9867/instances/attach \"status": "running","attached": true,"cdpUrl": "ws://127.0.0.1:9222/devtools/browser/abc123",- "browserTarget": "chrome-local",- "browserProvider": "chrome"+ "browser": "chrome"}```diff --git a/docs/guides/cloakbrowser.md b/docs/guides/cloakbrowser.mdindex 567054cc..5a2aa902 100644--- a/docs/guides/cloakbrowser.md+++ b/docs/guides/cloakbrowser.md@@ -341,13 +341,13 @@ curl -X POST http://localhost:9867/instances/attach \"name": "cloak-manager-profile","cdpUrl": "ws://127.0.0.1:9222/devtools/browser/abc123","provider": "cloak",- "browserTarget": "cloak-1"+ "browser": "cloak-1"}'```For a remote CloakBrowser attach:-- `browserTarget` should name a CloakBrowser target when `browser.targets` is configured; if omitted, the configured default target is used+- `browser` should name a CloakBrowser target (or the `cloak` provider) when `browser.targets` is configured; if omitted, the configured default target is used- `provider` in the JSON body must be `cloak` when no browser target is configured, or must match the selected target when both fields are present- `/stealth/status` reports `provider=cloak`, `launchMode=remote-cdp`,`native=true`, and `pinchtabOverlaysDisabled=true` β PinchTab does not injectdiff --git a/docs/guides/docker.md b/docs/guides/docker.mdindex 40c87ce4..d715c45e 100644--- a/docs/guides/docker.md+++ b/docs/guides/docker.md@@ -284,8 +284,8 @@ This image is local-only:### Run a CloakBrowser-backed container locallyCreate a config that points PinchTab at the in-image CloakBrowser binary-(`"provider": "cloak"` in the config file is equivalent to `--browser cloak`-on the CLI):+(`"browsers": {"default": "cloak"}` in the config file is equivalent to+`--browser cloak` on the CLI):```json{@@ -295,8 +295,10 @@ on the CLI):"token": "replace-me","stateDir": "/data"},+ "browsers": {+ "default": "cloak"+ },"browser": {- "provider": "cloak","binary": "/opt/cloakbrowser/chrome","cloak": {"fingerprintSeed": "42069",diff --git a/docs/guides/security.md b/docs/guides/security.mdindex 4c32b970..d1b79ea4 100644--- a/docs/guides/security.md+++ b/docs/guides/security.md@@ -309,6 +309,7 @@ For navigation trust overrides:- `security.trustedResolveCIDRs` lets a hostname resolve to a non-public IP during navigation preflight. This is intended for operator-controlled DNS or proxy setups such as internal proxies, lab networks, or benchmark ranges- `security.trustedProxyCIDRs` trusts browser-reported remote IPs from known internal proxies during runtime navigation checks- keep both lists narrow. Broad ranges such as `10.0.0.0/8` reduce SSRF protections and should only be used when the full network segment is intentionally trusted+- known limitation: responses served from the browser cache or a service worker report no remote IP, so the runtime remote-IP check passes them through by design; the resolve-time checks remain the primary gate for those navigationsSupported domain patterns are:diff --git a/docs/index.json b/docs/index.jsonindex 7304309d..a682e9ba 100644--- a/docs/index.json+++ b/docs/index.json@@ -22,6 +22,7 @@"guides/memory-monitoring.md","guides/data-storage.md","guides/docker.md",+ "guides/headed-mode.md","guides/raspberry-pi.md"],"architecture": [diff --git a/docs/reference/config.md b/docs/reference/config.mdindex 4ae1d432..ae46bbc2 100644--- a/docs/reference/config.md+++ b/docs/reference/config.md@@ -139,6 +139,10 @@ Supported environment variables:- `PINCHTAB_CONFIG`: choose the config file path- `PINCHTAB_TOKEN`: override the API token at runtime+- `PINCHTAB_RATE_LIMIT_MAX`: per-client request cap per 10-second window+ (default 3000, sized for agent-driven snapshot/action bursts). Lower it+ (e.g. to 300) when exposing the port beyond localhost. Child instances+ inherit it from the orchestrator's environment.For remote CLI targeting, use the root `--server` flag instead of config.@@ -356,16 +360,31 @@ config file.### Browser SelectionThe CLI uses `--browser <name>` to select a browser. In the config file the-equivalent field is `browser.provider`.+equivalent field is `browsers.default`:-`browser.provider` selects the local browser backend:+```json+{+ "browsers": { "default": "cloak" }+}+```++`browsers.default` selects the local browser backend:- `chrome` is the default and uses the normal Chrome/Chromium launch path.+- `ghost-chrome` serves static-friendly reads from a lightweight fetcher and+ escalates to Chrome when a page needs rendering.- `cloak` uses a user-installed CloakBrowser Chromium binary from `browser.binary`.-When `browser.provider` is `cloak`, `browser.binary` must point at the local-CloakBrowser Chromium executable. PinchTab does not download, bundle, or-redistribute the CloakBrowser binary.+`browsers.available` optionally restricts which browsers requests may select.+For multiple named configurations of the same provider (different binaries,+proxies, or fingerprints), use `browser.targets` with `browser.defaultTarget`+and `browser.fallbackOrder` β see [Terminology](../architecture/terminology.md).+The legacy `browser.provider` field is no longer supported and is rejected at+validation time.++When the selected browser is `cloak`, `browser.binary` (or the target's+`binary`) must point at the local CloakBrowser Chromium executable. PinchTab+does not download, bundle, or redistribute the CloakBrowser binary.`browser.cloak` maps supported CloakBrowser fingerprint settings to native launchflags:diff --git a/docs/reference/instances.md b/docs/reference/instances.mdindex 1c009513..e9fc620f 100644--- a/docs/reference/instances.md+++ b/docs/reference/instances.md@@ -195,7 +195,7 @@ curl -X POST http://localhost:9867/instances/attach \"name":"shared-chrome","cdpUrl":"ws://127.0.0.1:9222/devtools/browser/...","provider":"chrome",- "browserTarget":"chrome-local"+ "browser":"chrome-local"}'```@@ -218,10 +218,11 @@ Accepted `cdpUrl` shapes:Page-level URLs (`/devtools/page/...`) are rejected.-`browserTarget` is optional. When `browser.targets` is configured, an omitted-value attaches to the configured default target and the target's browser is used.-When `browserTarget` is present, it must name a configured target. If `provider`-is also present, it must match that target's browser. Without `browser.targets`,+`browser` is optional and accepts a provider name (`chrome`, `cloak`) or a+configured target name from `browser.targets`. When `browser.targets` is+configured, an omitted value attaches to the configured default target and the+target's browser is used. If `provider` is also present, it must agree with+the `browser` value. Without `browser.targets`,`provider` is `chrome` (default) or `cloak`; the cloak browser disablesPinchTab JS overlays on the assumption that the external browser owns nativefingerprint behavior.@@ -246,14 +247,14 @@ curl -X POST http://localhost:9867/instances/attach-bridge \"name":"shared-bridge","baseUrl":"http://10.0.12.24:9868","token":"bridge-secret-token",- "browserTarget":"chrome-local"+ "browser":"chrome-local"}'```Notes:- `baseUrl` must be a bare bridge origin; do not include credentials, query strings, fragments, or a path-- `browserTarget` is optional; with `browser.targets` configured, an omitted value attaches to the default target+- `browser` is optional and accepts a provider or target name; with `browser.targets` configured, an omitted value attaches to the default target- the orchestrator performs a health check before registering it- `security.attach.allowHosts` must allow the bridge host- `allowHosts: ["*"]` is a documented, non-default, security-reducing override. It disables host allowlisting entirely and allows any reachable bridge host with an allowed scheme. Use it only on isolated, operator-controlled networks.diff --git a/skills/pinchtab-stealth-score/SKILL.md b/skills/pinchtab-stealth-score/SKILL.mdindex 4789774a..836f6dda 100644--- a/skills/pinchtab-stealth-score/SKILL.md+++ b/skills/pinchtab-stealth-score/SKILL.md@@ -147,12 +147,11 @@ using the Go runner:"$RESULTS_DIR"/*_${TIMESTAMP}.json```-If the `runner` binary isn't built yet (it's gitignored β built on demand by `./dev`):--```bash-go build -o "$PROJECT_ROOT/tests/tools/scripts/runner" \- ./tests/tools/runner-```+`tests/tools/scripts/runner` is a tracked self-building shim: on first use it+compiles the Go runner into the gitignored `tests/tools/scripts/.runner.bin`+and rebuilds it automatically after source changes β no manual `go build`+needed (and never build over the shim path itself; that would overwrite the+checked-in script with a binary).The summarizer:diff --git a/src/generated/types.ts b/src/generated/types.tsdeleted file mode 100644index d147ab9f..00000000--- a/src/generated/types.ts+++ /dev/null@@ -1,241 +0,0 @@-// Code generated by tygo. DO NOT EDIT.--//////////-// source: types.go-/*-Package types contains shared API types for the dashboard.-These types are exported to TypeScript via tygo.-*/--/**- * Profile represents a browser profile stored on disk.- * Matches internal/bridge/api.go ProfileInfo- */-export interface Profile {- id?: string;- name: string;- path?: string;- pathExists?: boolean;- created: string;- lastUsed: string;- diskUsage: number /* int64 */;- sizeMB?: number /* float64 */;- running: boolean;- temporary?: boolean;- source?: string;- chromeProfileName?: string;- accountEmail?: string;- accountName?: string;- hasAccount?: boolean;- useWhen?: string;- description?: string;-}-export interface SecurityPolicy {- allowedDomains?: string[];-}-/**- * Instance represents a running browser instance.- * Matches internal/bridge/api.go Instance- */-export interface Instance {- id: string;- profileId: string;- profileName: string;- port: string; // Note: string not int- url?: string;- mode: string;- headless: boolean;- status: string; // starting/running/stopping/stopped/error- startTime: string;- error?: string;- attached: boolean; // True if attached rather than locally launched- attachType?: string;- cdpUrl?: string; // CDP WebSocket URL (for CDP-attached instances)- securityPolicy?: SecurityPolicy;- browser?: string;- /**- * FallbackFrom/FallbackReason are reserved for a future phase (always- * empty in P2.4a).- */- fallbackFrom?: string;- fallbackReason?: string;-}-/**- * Agent represents a connected AI agent.- */-export interface Agent {- id: string;- name?: string;- connectedAt: string;- lastActivity?: string;- requestCount: number /* int */;-}-/**- * AgentDetail returns agent-centric dashboard data for a single agent.- */-export interface AgentDetail {- agent: Agent;- events: ActivityEvent[];-}-/**- * ActivityEvent represents an action in the activity feed.- */-export interface ActivityEvent {- id: string;- agentId: string;- channel: string; // "tool_call" or "progress"- type: string; // navigate/snapshot/action/screenshot/other- method: string;- path: string;- message?: string; // human-readable (progress channel)- progress?: number /* int */; // 0-100 numeric progress- total?: number /* int */; // total steps- timestamp: string;- details?: { [key: string]: any};-}-/**- * RouteAttempt records a single browser that was considered during routing.- */-export interface RouteAttempt {- provider: string;- accepted: boolean;- reason?: string;-}-/**- * RouteMetadata records the browser-selection decision for a request.- */-export interface RouteMetadata {- requestedProvider: string;- usedProvider: string;- escalated: boolean;- reason?: string;- quality?: number /* int */;- fallbackAttempts?: number /* int */;- attempts?: RouteAttempt[];-}-/**- * ActivityLogEvent represents a queryable backend activity record.- */-export interface ActivityLogEvent {- timestamp: string;- source: string;- requestId?: string;- sessionId?: string;- agentId?: string;- method: string;- path: string;- status: number /* int */;- durationMs: number /* int64 */;- remoteAddr?: string;- instanceId?: string;- profileId?: string;- profileName?: string;- tabId?: string;- url?: string;- action?: string;- route?: RouteMetadata;- ref?: string;-}-/**- * ActivityLogResponse is returned by the /api/activity endpoint.- */-export interface ActivityLogResponse {- events: ActivityLogEvent[];- count: number /* int */;-}-/**- * ScreencastSettings configures live tab previews.- */-export interface ScreencastSettings {- fps: number /* int */;- quality: number /* int */;- maxWidth: number /* int */;-}-/**- * BrowserSettings configures browser behavior.- */-export interface BrowserSettings {- blockImages: boolean;- blockMedia: boolean;- noAnimations: boolean;-}-/**- * Settings contains all dashboard settings.- */-export interface Settings {- screencast: ScreencastSettings;- stealth: string; // light/medium/full- browser: BrowserSettings;- monitoring: MonitoringSettings;- agents: AgentSettings;-}-/**- * AgentSettings controls agent reasoning output visibility.- */-export interface AgentSettings {- reasoningMode: string; // "tool_calls" (default), "progress", "both"-}-/**- * MonitoringSettings controls dashboard monitoring features.- */-export interface MonitoringSettings {- memoryMetrics: boolean; // Enable per-tab memory aggregation (can be heavy)- pollInterval: number /* int */; // Poll interval in seconds (default 30)-}-/**- * ServerInfo contains health/status information.- */-export interface ServerInfo {- version: string;- uptime: number /* int64 */;- profiles: number /* int */;- instances: number /* int */;- agents: number /* int */;-}-/**- * CreateProfileRequest is the request body for creating a profile.- */-export interface CreateProfileRequest {- name: string;- description?: string;- useWhen?: string;-}-/**- * CreateProfileResponse is returned after creating a profile.- */-export interface CreateProfileResponse {- status: string;- id: string;- name: string;-}-/**- * InstanceTab represents a browser tab in an instance.- */-export interface InstanceTab {- id: string;- instanceId: string;- url: string;- title: string;-}-/**- * InstanceMetrics represents memory metrics for an instance.- */-export interface InstanceMetrics {- instanceId: string;- profileName: string;- jsHeapUsedMB: number /* float64 */;- jsHeapTotalMB: number /* float64 */;- documents: number /* int64 */;- frames: number /* int64 */;- nodes: number /* int64 */;- listeners: number /* int64 */;-}-/**- * LaunchInstanceRequest is the request body for launching an instance.- */-export interface LaunchInstanceRequest {- profileId?: string; // profile ID (prof_XXXXXXXX) or existing profile name- mode?: string; // "headed" or empty for headless- port?: string; // port number as string- browser?: string; // browser override (chrome, cloak, ghost-chrome)-}diff --git a/tests/e2e/README.md b/tests/e2e/README.mdindex dfaee2d9..cebd5b25 100644--- a/tests/e2e/README.md+++ b/tests/e2e/README.md@@ -11,7 +11,7 @@ End-to-end tests for PinchTab that exercise the full stack including browser aut./dev e2e --browser=cloak./dev e2e basic # Run the basic suite (api + cli + infra basic tests)./dev e2e extended # Run the extended suite-./dev smoke ci # Run the CI-backed smoke subset+./dev e2e smoke # Run the CI-backed smoke subset./dev smoke # Run all local smoke categories./dev smoke --browser=cloak./dev smoke cdp-attach # Run only the CDP attach smoke@@ -66,11 +66,11 @@ By default, tier comes from the filename suffix: `*-basic.sh` is `basic`, `*-smo- `basic` is the PR happy path: fast, representative coverage with small setup. `./dev e2e basic` runs the API, CLI, and Infra basic suites.- `extended` is deeper coverage: edge cases, detailed interaction checks, and tests that are useful before release. Extended suites include the matching `basic` scenarios plus `extended` scenarios for that group.-- `smoke` is independent high-setup coverage: lifecycle, multi-instance, host Docker, and production-like checks that do not belong in PR flow. `./dev smoke ci` runs only the CI-backed `*-smoke.sh` scenarios plus host Docker smoke checks; it does not include `basic`, `extended`, or opt-in provider/live-detection smokes. `./dev smoke` is the local full-smoke entrypoint and also runs provider parity, CDP attach, and live-detection categories unless filtered.+- `smoke` is independent high-setup coverage: lifecycle, multi-instance, host Docker, and production-like checks that do not belong in PR flow. `./dev e2e smoke` runs only the CI-backed `*-smoke.sh` scenarios; it does not include `basic`, `extended`, or opt-in provider/live-detection smokes. `./dev smoke` is the local full-smoke entrypoint and also runs provider parity, CDP attach, and live-detection categories unless filtered.CloakBrowser smoke checks need a Linux CloakBrowser binary and a compatiblePinchTab image, so they are exposed through local `./dev smoke` filters-instead of being included in the CI-backed `./dev smoke ci` subset. The+instead of being included in the CI-backed `./dev e2e smoke` subset. The`./dev smoke cloakbrowser` filter builds`tests/tools/docker/cloakbrowser-smoke.Dockerfile` into`pinchtab-cloakbrowser:test` and uses tmpfs mounts for browser profile and@@ -95,7 +95,7 @@ go run ./tests/tools/runner e2e --suite extended --filter feature --dry-rungo run ./tests/tools/runner e2e --suite smoke --filter feature --dry-run```- ### Filtering+### Filtering`--filter TEXT` selects scenario files before compose planning. It is a case-sensitive substring match against the scenario file name, manifest key, group, tier, helper, and tags. Suites with no matching scenarios are skipped, and the runner only starts services required by the remaining scenarios.diff --git a/tests/e2e/scenarios/infra/browser-routing-extended.sh b/tests/e2e/scenarios/infra/browser-routing-extended.shindex 64d357a9..830146e1 100755--- a/tests/e2e/scenarios/infra/browser-routing-extended.sh+++ b/tests/e2e/scenarios/infra/browser-routing-extended.sh@@ -12,18 +12,18 @@ source "${GROUP_DIR}/../../helpers/api.sh"CHROME_SERVER="$E2E_SERVER"-# These tests compare two providers β they only make sense when the-# ghost-chrome server is available and the primary provider is NOT chrome-# (chrome vs ghost-chrome parity is what we're testing; running these when-# the primary is also ghost-chrome or cloak doesn't add signal).+# These tests compare the chrome primary against the dedicated ghost-chrome+# server β chrome vs ghost-chrome parity. They run in the chrome lane (the+# default, blocking one). In non-chrome lanes the primary is a different+# provider, so the comparison would not be the parity this scenario tests.requires_providers() {if [ -z "${E2E_SERVER_GHOSTCHROME:-}" ]; thenecho " β οΈ Skipping browser-routing tests (E2E_SERVER_GHOSTCHROME not set)"return 1filocal primary="${PINCHTAB_E2E_BROWSER:-chrome}"- if [ "$primary" = "chrome" ]; then- echo " β οΈ Skipping browser-routing tests (primary provider is chrome β these tests need a non-chrome primary)"+ if [ "$primary" != "chrome" ]; then+ echo " β οΈ Skipping browser-routing tests (primary provider is ${primary} β chrome vs ghost-chrome parity needs the chrome lane)"return 1fireturn 0diff --git a/tests/tools/docker/cloakbrowser-smoke.Dockerfile b/tests/tools/docker/cloakbrowser-smoke.Dockerfileindex c168f783..1dae649e 100644--- a/tests/tools/docker/cloakbrowser-smoke.Dockerfile+++ b/tests/tools/docker/cloakbrowser-smoke.Dockerfile@@ -26,10 +26,15 @@ RUN go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab# Stage 3: Download CloakBrowser through its official Python package.FROM python:3.12-slim AS cloakbrowser-binary+# Pinned so smoke/parity lanes are reproducible and upstream releases can't+# silently change what they test; bump deliberately. The package's+# ensure_binary() below still downloads a Chromium build at image build time+# (local-only image, never published β see header).+ARG CLOAKBROWSER_VERSION=0.3.31ENV CLOAKBROWSER_CACHE_DIR=/cloak-cache \CLOAKBROWSER_AUTO_UPDATE=false \PYTHONUNBUFFERED=1-RUN python -m pip install --disable-pip-version-check --root-user-action=ignore --no-cache-dir cloakbrowser && \+RUN python -m pip install --disable-pip-version-check --root-user-action=ignore --no-cache-dir "cloakbrowser==${CLOAKBROWSER_VERSION}" && \python - <<'PY'import loggingfrom pathlib import Pathdiff --git a/tests/tools/runner/internal/e2e/provider.go b/tests/tools/runner/internal/e2e/provider.goindex e6d7a224..64ad6c3b 100644--- a/tests/tools/runner/internal/e2e/provider.go+++ b/tests/tools/runner/internal/e2e/provider.go@@ -14,18 +14,87 @@ import (const defaultCloakImage = "pinchtab-cloakbrowser:test"const defaultCloakDockerfile = "tests/tools/docker/cloakbrowser-smoke.Dockerfile"const dryRunCloakComposeOverride = "<generated-cloak-compose-override>"+const dryRunGhostChromeComposeOverride = "<generated-ghost-chrome-compose-override>"+const stockPinchtabImage = "e2e-pinchtab:latest"-// pinchtabServices enumerates every pinchtab variant present in the e2e-// compose files. Anything not listed here is left untouched by the cloak-// override (notably the runner-* services and fixtures).-var pinchtabServices = []string{- "pinchtab",- "pinchtab-secure",- "pinchtab-autoclose",- "pinchtab-medium",- "pinchtab-full",- "pinchtab-ghostchrome",- "pinchtab-bridge",+type extensionMount struct {+ sourceDir string+ target string+}++// pinchtabServiceTable enumerates every pinchtab variant present in the e2e+// compose files, with the attributes a provider override must preserve from+// docker-compose-multi.yml: the config it mounts, the subcommand it execs+// (bridge services must stay bridges), and its extension fixture mounts.+// Anything not listed here is left untouched by overrides (notably the+// runner-* services and fixtures).+var pinchtabServiceTable = []struct {+ name string+ configName string+ subcommand string // "server" or "bridge" β must match docker-compose-multi.yml+ extensionMounts []extensionMount+ // keepStockProvider pins the service to the stock image and its own+ // config flavor in every provider lane: pinchtab-ghostchrome is the+ // dedicated ghost-chrome comparison server and must not become cloak.+ keepStockProvider bool+}{+ {+ name: "pinchtab",+ configName: "pinchtab.json",+ subcommand: "server",+ extensionMounts: []extensionMount{+ {sourceDir: "test-extension", target: "/extensions/test-extension"},+ {sourceDir: "test-extension-api", target: "/extensions/test-extension-api"},+ },+ },+ {+ name: "pinchtab-secure",+ configName: "pinchtab-secure.json",+ subcommand: "server",+ },+ {+ name: "pinchtab-autoclose",+ configName: "pinchtab-autoclose.json",+ subcommand: "server",+ extensionMounts: []extensionMount{+ {sourceDir: "test-extension", target: "/extensions/test-extension"},+ },+ },+ {+ name: "pinchtab-medium",+ configName: "pinchtab-medium-permissive.json",+ subcommand: "server",+ extensionMounts: []extensionMount{+ {sourceDir: "test-extension", target: "/extensions/test-extension"},+ },+ },+ {+ name: "pinchtab-full",+ configName: "pinchtab-full-permissive.json",+ subcommand: "server",+ extensionMounts: []extensionMount{+ {sourceDir: "test-extension", target: "/extensions/test-extension"},+ },+ },+ {+ name: "pinchtab-retain",+ configName: "pinchtab-network-retain-bodies.json",+ subcommand: "server",+ extensionMounts: []extensionMount{+ {sourceDir: "test-extension", target: "/extensions/test-extension"},+ },+ },+ {+ name: "pinchtab-ghostchrome",+ configName: "pinchtab-ghostchrome.json",+ subcommand: "bridge",+ keepStockProvider: true,+ },+ {+ name: "pinchtab-bridge",+ configName: "pinchtab-bridge.json",+ subcommand: "bridge",+ },}// providerOverrides bundles the override compose file + any generated cloak@@ -77,7 +146,14 @@ func (r *Runner) prepareCloakOverrides() (*providerOverrides, error) {return nil, fmt.Errorf("create cloak tmp dir: %w", err)}- configs, err := r.rewriteE2EConfigs(tmp, writeCloakConfig)+ configs, err := r.rewriteE2EConfigs(tmp, func(src, dst string) error {+ // The dedicated ghost-chrome comparison server keeps its ghost-chrome+ // flavor in every provider lane; only the primary services go cloak.+ if filepath.Base(src) == "pinchtab-ghostchrome.json" {+ return writeGhostChromeConfig(src, dst)+ }+ return writeCloakConfig(src, dst)+ })if err != nil {_ = os.RemoveAll(tmp)return nil, err@@ -102,7 +178,7 @@ func (r *Runner) prepareGhostChromeOverrides() (*providerOverrides, error) {if r.args.DryRun {return &providerOverrides{provider: "ghost-chrome",- composeFiles: []string{dryRunCloakComposeOverride},+ composeFiles: []string{dryRunGhostChromeComposeOverride},}, nil}@@ -307,176 +383,57 @@ func writeGhostChromeConfig(src, dst string) error {// Used by ghost-chrome where the same Chrome image is used but the config// selects a different browsers.default.func writeConfigOnlyComposeOverride(path string, configs map[string]string, fixturesDir string) error {- type extensionMount struct {- sourceDir string- target string- }- type serviceOverrideConfig struct {- configName string- extensionMounts []extensionMount- }-- serviceConfig := map[string]serviceOverrideConfig{- "pinchtab": {- configName: "pinchtab.json",- extensionMounts: []extensionMount{- {sourceDir: "test-extension", target: "/extensions/test-extension"},- {sourceDir: "test-extension-api", target: "/extensions/test-extension-api"},- },- },- "pinchtab-secure": {- configName: "pinchtab-secure.json",- },- "pinchtab-autoclose": {- configName: "pinchtab-autoclose.json",- extensionMounts: []extensionMount{- {sourceDir: "test-extension", target: "/extensions/test-extension"},- },- },- "pinchtab-medium": {- configName: "pinchtab-medium-permissive.json",- extensionMounts: []extensionMount{- {sourceDir: "test-extension", target: "/extensions/test-extension"},- },- },- "pinchtab-full": {- configName: "pinchtab-full-permissive.json",- extensionMounts: []extensionMount{- {sourceDir: "test-extension", target: "/extensions/test-extension"},- },- },- "pinchtab-ghostchrome": {- configName: "pinchtab-ghostchrome.json",- },- "pinchtab-bridge": {- configName: "pinchtab-bridge.json",- },- }-- var b strings.Builder- b.WriteString("# Generated by tests/tools/runner β provider=ghost-chrome override.\n")- b.WriteString("# Mounts ghost-chrome-flavoured runtime config in place of the chrome one.\n")- b.WriteString("services:\n")-- for _, svc := range pinchtabServices {- cfg, ok := serviceConfig[svc]- if !ok {- continue- }- baseName := cfg.configName- configPath, ok := configs[baseName]- if !ok {- continue- }- fmt.Fprintf(&b, " %s:\n", svc)- fmt.Fprintf(&b, " image: e2e-pinchtab:latest\n")- fmt.Fprintf(&b, " pull_policy: never\n")- b.WriteString(" environment:\n")- b.WriteString(" PINCHTAB_RATE_LIMIT_MAX: \"3000\"\n")- b.WriteString(" volumes:\n")- fmt.Fprintf(&b, " - %s:/fixture-config-ghost/%s:ro\n", configPath, baseName)- for _, mount := range cfg.extensionMounts {- source := filepath.Join(fixturesDir, mount.sourceDir)- fmt.Fprintf(&b, " - %s:%s:ro\n", source, mount.target)- }- fmt.Fprintf(&b, " command: [\"/bin/sh\", \"-lc\", \"mkdir -p /data/e2e-config && cp /fixture-config-ghost/%s /data/e2e-config/%s && exec /usr/local/bin/docker-entrypoint.sh pinchtab server\"]\n",- baseName, baseName)- }+ return writeProviderComposeOverride(path, configs, fixturesDir, "ghost-chrome", "")+}- return os.WriteFile(path, []byte(b.String()), 0o644) // #nosec G306 -- consumed read-only by docker compose.+// writeCloakComposeOverride writes a compose file that swaps each pinchtab+// service onto the cloak provider image (except keepStockProvider services)+// and remaps the config bind mount onto the cloak-flavoured copy.+func writeCloakComposeOverride(path string, cloakConfigs map[string]string, fixturesDir, image string) error {+ return writeProviderComposeOverride(path, cloakConfigs, fixturesDir, "cloak", image)}-// writeCloakComposeOverride writes a compose file that targets each pinchtab-// service: swaps the image to the cloak provider image, drops the build-// directive (via image-only + pull_policy:never), remaps the config bind mount-// onto the cloak-flavoured copy we just generated, and preserves extension-// fixture mounts needed by extension-parity E2E tests.-//-// The override is intentionally written as YAML by hand (no third-party deps)+// writeProviderComposeOverride emits the per-provider compose override. It+// preserves each service's base-compose subcommand (bridge services stay+// bridges) and pins keepStockProvider services to the stock image. The+// override is intentionally written as YAML by hand (no third-party deps)// since the structure is small and stable.-func writeCloakComposeOverride(path string, cloakConfigs map[string]string, fixturesDir, image string) error {- type extensionMount struct {- sourceDir string- target string- }- type serviceOverrideConfig struct {- configName string- extensionMounts []extensionMount- }-- // Map service name to original config basename and extension bind mounts.- // The config bind-mount target inside the container is- // /fixture-config/<basename>:ro, which the entrypoint command copies into- // /data/e2e-config/<basename>.- serviceConfig := map[string]serviceOverrideConfig{- "pinchtab": {- configName: "pinchtab.json",- extensionMounts: []extensionMount{- {sourceDir: "test-extension", target: "/extensions/test-extension"},- {sourceDir: "test-extension-api", target: "/extensions/test-extension-api"},- },- },- "pinchtab-secure": {- configName: "pinchtab-secure.json",- },- "pinchtab-autoclose": {- configName: "pinchtab-autoclose.json",- extensionMounts: []extensionMount{- {sourceDir: "test-extension", target: "/extensions/test-extension"},- },- },- "pinchtab-medium": {- configName: "pinchtab-medium-permissive.json",- extensionMounts: []extensionMount{- {sourceDir: "test-extension", target: "/extensions/test-extension"},- },- },- "pinchtab-full": {- configName: "pinchtab-full-permissive.json",- extensionMounts: []extensionMount{- {sourceDir: "test-extension", target: "/extensions/test-extension"},- },- },- "pinchtab-ghostchrome": {- configName: "pinchtab-ghostchrome.json",- },- "pinchtab-bridge": {- configName: "pinchtab-bridge.json",- },+func writeProviderComposeOverride(path string, configs map[string]string, fixturesDir, provider, image string) error {+ // Mount configs at a provider-distinct path to avoid volume merge+ // ambiguity with the base compose's /fixture-config mount; the command+ // copies from this path instead.+ mountDir := "/fixture-config-ghost"+ if provider == "cloak" {+ mountDir = "/fixture-config-cloak"}var b strings.Builder- b.WriteString("# Generated by tests/tools/runner β provider=cloak override.\n")- b.WriteString("# Swaps every pinchtab* service onto the cloak provider image and\n")- b.WriteString("# mounts the cloak-flavoured runtime config in place of the chrome one.\n")+ fmt.Fprintf(&b, "# Generated by tests/tools/runner β provider=%s override.\n", provider)+ fmt.Fprintf(&b, "# Mounts %s-flavoured runtime config in place of the chrome one.\n", provider)b.WriteString("services:\n")- for _, svc := range pinchtabServices {- cfg, ok := serviceConfig[svc]- if !ok {- continue- }- baseName := cfg.configName- cloakPath, ok := cloakConfigs[baseName]+ for _, svc := range pinchtabServiceTable {+ configPath, ok := configs[svc.configName]if !ok {// No config generated (probably renamed); skip silently β the// service will fail at startup and surface a clear error.continue}- fmt.Fprintf(&b, " %s:\n", svc)- fmt.Fprintf(&b, " image: %s\n", image)+ svcImage := stockPinchtabImage+ if provider == "cloak" && !svc.keepStockProvider {+ svcImage = image+ }+ fmt.Fprintf(&b, " %s:\n", svc.name)+ fmt.Fprintf(&b, " image: %s\n", svcImage)fmt.Fprintf(&b, " pull_policy: never\n")- // Mount the cloak config at a distinct path to avoid volume merge- // ambiguity with the base compose's /fixture-config mount. Override- // the command to copy from this path instead.b.WriteString(" volumes:\n")- fmt.Fprintf(&b, " - %s:/fixture-config-cloak/%s:ro\n", cloakPath, baseName)- for _, mount := range cfg.extensionMounts {+ fmt.Fprintf(&b, " - %s:%s/%s:ro\n", configPath, mountDir, svc.configName)+ for _, mount := range svc.extensionMounts {source := filepath.Join(fixturesDir, mount.sourceDir)fmt.Fprintf(&b, " - %s:%s:ro\n", source, mount.target)}- fmt.Fprintf(&b, " command: [\"/bin/sh\", \"-lc\", \"mkdir -p /data/e2e-config && cp /fixture-config-cloak/%s /data/e2e-config/%s && exec /usr/local/bin/docker-entrypoint.sh pinchtab server\"]\n",- baseName, baseName)+ fmt.Fprintf(&b, " command: [\"/bin/sh\", \"-lc\", \"mkdir -p /data/e2e-config && cp %s/%s /data/e2e-config/%s && exec /usr/local/bin/docker-entrypoint.sh pinchtab %s\"]\n",+ mountDir, svc.configName, svc.configName, svc.subcommand)}return os.WriteFile(path, []byte(b.String()), 0o644) // #nosec G306 -- consumed read-only by docker compose.diff --git a/tests/tools/runner/internal/e2e/provider_test.go b/tests/tools/runner/internal/e2e/provider_test.goindex 646d7798..16c1e550 100644--- a/tests/tools/runner/internal/e2e/provider_test.go+++ b/tests/tools/runner/internal/e2e/provider_test.go@@ -14,13 +14,14 @@ func TestWriteCloakComposeOverrideMountsExtensionFixtures(t *testing.T) {outPath := filepath.Join(tmp, "docker-compose.cloak.yml")configs := map[string]string{- "pinchtab.json": filepath.Join(tmp, "pinchtab.json"),- "pinchtab-secure.json": filepath.Join(tmp, "pinchtab-secure.json"),- "pinchtab-autoclose.json": filepath.Join(tmp, "pinchtab-autoclose.json"),- "pinchtab-medium-permissive.json": filepath.Join(tmp, "pinchtab-medium-permissive.json"),- "pinchtab-full-permissive.json": filepath.Join(tmp, "pinchtab-full-permissive.json"),- "pinchtab-ghostchrome.json": filepath.Join(tmp, "pinchtab-ghostchrome.json"),- "pinchtab-bridge.json": filepath.Join(tmp, "pinchtab-bridge.json"),+ "pinchtab.json": filepath.Join(tmp, "pinchtab.json"),+ "pinchtab-secure.json": filepath.Join(tmp, "pinchtab-secure.json"),+ "pinchtab-autoclose.json": filepath.Join(tmp, "pinchtab-autoclose.json"),+ "pinchtab-medium-permissive.json": filepath.Join(tmp, "pinchtab-medium-permissive.json"),+ "pinchtab-full-permissive.json": filepath.Join(tmp, "pinchtab-full-permissive.json"),+ "pinchtab-network-retain-bodies.json": filepath.Join(tmp, "pinchtab-network-retain-bodies.json"),+ "pinchtab-ghostchrome.json": filepath.Join(tmp, "pinchtab-ghostchrome.json"),+ "pinchtab-bridge.json": filepath.Join(tmp, "pinchtab-bridge.json"),}if err := writeCloakComposeOverride(outPath, configs, fixturesDir, defaultCloakImage); err != nil {@@ -60,6 +61,7 @@ func TestWriteCloakComposeOverrideMountsExtensionFixtures(t *testing.T) {"pinchtab-autoclose": "pinchtab-autoclose.json","pinchtab-medium": "pinchtab-medium-permissive.json","pinchtab-full": "pinchtab-full-permissive.json",+ "pinchtab-retain": "pinchtab-network-retain-bodies.json","pinchtab-ghostchrome": "pinchtab-ghostchrome.json","pinchtab-bridge": "pinchtab-bridge.json",} {@@ -68,12 +70,26 @@ func TestWriteCloakComposeOverrideMountsExtensionFixtures(t *testing.T) {if !strings.Contains(block, want) {t.Fatalf("%s override missing cloak config mount %q:\n%s", svc, want, block)}- if !strings.Contains(block, "image: "+defaultCloakImage) {- t.Fatalf("%s override missing cloak image:\n%s", svc, block)- }if !strings.Contains(block, "pull_policy: never") {t.Fatalf("%s override missing pull_policy: never:\n%s", svc, block)}+ // The dedicated ghost-chrome comparison server keeps the stock image+ // in a cloak lane; everything else swaps to the cloak image.+ wantImage := defaultCloakImage+ if svc == "pinchtab-ghostchrome" {+ wantImage = stockPinchtabImage+ }+ if !strings.Contains(block, "image: "+wantImage) {+ t.Fatalf("%s override image mismatch (want %s):\n%s", svc, wantImage, block)+ }+ // Bridge services must keep their base-compose subcommand.+ wantCmd := "pinchtab server"+ if svc == "pinchtab-ghostchrome" || svc == "pinchtab-bridge" {+ wantCmd = "pinchtab bridge"+ }+ if !strings.Contains(block, wantCmd) {+ t.Fatalf("%s override must exec %q:\n%s", svc, wantCmd, block)+ }}}