Files
pipelines/web/AGENTS.md
T
alan 4721b8af10 web: prepare the client workstream for feature parity
Adds the area map (web/AGENTS.md), the parity acceptance checklist
(web/PARITY.md, one row per Android feature), and a zero-dependency browser
verification harness: test/browser.mjs drives the installed Chrome over the
DevTools protocol, and test/ui-smoke.mjs serves the page, connects it through
its own /connect proxy, and captures the rendered pipeline list, a pipeline
detail and a run detail as PNGs.

This closes the spike's 'rendered page not verified' gap (29 pipelines rendered,
three captures) and gives review stages real UI evidence without a phone or an
npm install. Hosting is unchanged: serve.mjs stays alongside the Pipelines
server and proxies /connect.
2026-10-19 02:13:39 +01:00

4.2 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 (styles.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/** the DOM UI. Grow it toward PARITY.md
index.html, styles.css — shell + styling
serve.mjs — static server + /connect proxy
test/*.test.mjs app/src/test/** node --test, no server needed
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. 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. 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.