Files
pipelines/web/AGENTS.md
T

5.1 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, connection/banner, navigation/routes, render dispatch, header
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
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. 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.