Files
pipelines/web/AGENTS.md
T
alan d1f09f499f Merge branch 'main' into web-layout
Take main's newer smoke behaviour where they met: the binary capture is run 449
(opened through openRunDetail), and a running run must show no aggregate Changes
section. Keep the layout's shell-aware checks and its L2-L4 rows; L7 stays todo
with the view-level fixes recorded.
2026-10-19 20:06:25 +01:00

5.5 KiB

The web client — working map

Read this before touching web/. This is the browser client for the Pipelines server. Its target is feature parity with the Android app (android/), not a reimplementation of it: same features, the same wire protocol, the same words, rendered for a browser. web/PARITY.md is the acceptance checklist; that file, not this one, decides whether a feature is done.

What it is

  • Browser-native (plain ES modules in the browser). Deliberately no framework and no runtime dependency — no React/Vue/Svelte, no bundler required. Keep it that way unless a concrete feature cannot be built without one, and say why in the item's note.
  • Simple but beautiful: hand-written CSS split by area (base.css, lists.css, run-detail.css, chat.css, graph.css, dialogs.css, settings.css), the app's dark palette and spacing, real attention to hierarchy and detail. "Simple" is about the stack, never about the finish.
  • Trusted LAN/VPN only. The server has no authentication; the page stores nothing but the server URL in localStorage. Never bake in a server address, never store secrets, never expose the API to an untrusted network.

Layout

File Android counterpart Notes
src/protocol.js data/protocol/Message.kt message type constants, #success/#failure
src/serverUrl.js data/transport/ServerUrl.kt validateServerUrl, resolveArtifactUrl
src/client.js data/transport/PipelinesClient.kt one reused socket, id matching, timeout, backoff. DOM-free
src/repository.js data/PipelinesRepository.kt typed request builders
src/app.js ui/** page shell: boot, state, client wiring, navigation/routes, render dispatch, persistent rail/workspace/dock
src/shell.js ui/WindowSize.kt, ui/components/DetailTabs.kt pure shell model: destinations, view/route mapping, roving-tabindex arithmetic, status words
src/dom.js — h(), shared DOM helpers and clipboard/share actions
src/format.js ui/Format.kt (DOM-facing bits) status tone and error-text helpers
src/views/*.js ui/** one module per destination/dialog surface: attention, settings, pipelines, templates, runs, runDetail, chat, search, dialogs
index.html, *.css — shell + area styles linked in a fixed order
serve.mjs — static server + /connect proxy
test/*.test.mjs app/src/test/** node --test, no server needed (including the shell/tab helpers)
test/smoke.mjs — protocol smoke against a live server
test/browser.mjs — zero-dep Chrome DevTools driver
test/ui-smoke.mjs UI review captures live browser check + screenshots

Keep client.js DOM-free: the smoke tests and the page must drive the same transport module.

Build and run

cd web
node serve.mjs                    # http://127.0.0.1:8090/  (proxies /connect -> 127.0.0.1:8080)
node serve.mjs --port 8091 --pipelines 127.0.0.1:8080

There is no build step and nothing to compile. node serve.mjs is the whole "install".

Test

cd web
node --test test/                                         # unit tests, no server
PIPELINES_WS_URL=ws://127.0.0.1:8080/connect node test/smoke.mjs   # protocol, live
node test/ui-smoke.mjs --out /path/to/run/artifacts       # browser, live, screenshots

ui-smoke.mjs starts serve.mjs, launches the installed Chrome headless, drives the real page and writes PNGs into --out. It picks a free port unless one is given, so concurrent checks never collide.

capture-manifest.mjs compares two capture directories. A behaviour-preserving refactor must keep the same capture SET; --compare BEFORE AFTER exits non-zero when a capture is missing or unexpected and lists the files whose pixels drifted (live durations legitimately change bytes, so inspect that list by eye). That is the UI evidence: a review stage must run it (or an extension of it) and report the capture paths, not describe what it thinks would render. Set CHROME_PATH if Chrome is not at the default macOS location.

Why the page connects through serve.mjs, not the server directly

internal/server/websocket.go calls websocket.Accept(w, r, nil), which rejects an upgrade whose Origin host does not match the request Host. A page served from port 8090 opening ws://HOST:8080/connect is refused with 403. The static server therefore also proxies /connect (dropping Origin), so the page and the socket are one origin. It proxies /artifacts/ too: artifact URLs resolve against the configured server (the page origin when proxied), so without it images, the viewer and session.html 404 even though the socket works. Do not "fix" this by relaxing the server's Origin check — that check is the only thing standing between a random web page and an unauthenticated control API. Keep the proxy.

The web server is spawned alongside the Pipelines server; it is not part of the Go binary and needs no server change.

Rules

  • One small, independently verifiable change per item; keep the diff tight.
  • Match the Android app's wording and behaviour; where the browser genuinely cannot match (local notifications need HTTPS, deep links become URL routes), say so in the parity row rather than inventing a difference.
  • Every new user-visible state needs a capture from ui-smoke.mjs.
  • Do not edit android/ from this workstream.
  • Update web/PARITY.md in the same commit when a row's status changes.
  • node --check every file you touch; node --test test/ must stay green.