Files
pipelines/web
alan 95362134aa session export: write only session.html, retire the markdown export
A stage's session was exported twice, as session.md and session.html, and both
files were presented. It is now one html file; the markdown export is retired.

- internal/stage/session_export.go: ExportSession renders and writes exactly one
  file, session.html, via writeSessionFile; renderSessionMarkdown and its helpers
  are gone; SessionExportResult carries HTML/HTMLBytes only. The source read, the
  8 MiB source / 2 MiB rendered bounds, the truncation banner, the
  never-overwrite rule and the honest empty-session handling are unchanged.
- internal/protocol/runs.go: SessionExport drops markdown/markdown_bytes (a
  record written before the change still decodes; unknown fields are ignored),
  and adds LegacySessionMarkdownArtifact with RunStep.PresentedArtifacts(), the
  one Go rule that hides the retired session.md from every artifact listing.
- internal/server/runner.go: evidence.Markdown/MarkdownBytes are no longer copied.
- internal/tui: the artifacts panel, the recorded count and the per-visit summary
  derive from PresentedArtifacts(), so the terminal never lists session.md.
- web/src/app.js: the spike's renderArtifacts applies the same filter.
- android: the Session section is the html export alone in a WebView — SessionView,
  the Markdown/HTML toggle and the session markdown path are removed;
  presentedArtifacts(step) filters the retired session.md out of the per-visit
  gallery, the run gallery and its count, the verdict/selection lists and the
  timeline indicator; data/protocol SessionExport drops the markdown fields.
- Tests pin the single html file, prove no session.md is written and that a
  pre-existing one is neither overwritten nor presented, and prove a legacy
  export record still loads and its session.md is hidden.

The legacy session.md of an older run stays on disk (dated evidence); it is only
no longer produced and no longer presented.

Checks (macOS, Go 1.24, Android Gradle 8.11.1, 18 Oct 2026): gofmt -l . prints
nothing; go build ./... && go vet ./... clean; go test ./internal/... ./cmd/...
-> 19 packages ok, 0 failures; node --check web/src/app.js ok and node --test
web/test -> 20/20; gradle --offline --no-daemon :app:assembleDebug
:app:testDebugUnitTest -> BUILD SUCCESSFUL.

Packaged references checked: internal/author/skill/references/delivery.md and
operations.md both described the session.md+session.html pair, so both are
updated here to describe the single session.html export and the retired, hidden
session.md. README.md and internal/author/skill/SKILL.md carry no session.md
reference and install.go's managed inventory is unchanged (no reference added or
removed). docs/notes/session-html-only.md records the remaining stale shared
documentation (docs/stage-artifacts.md, docs/app-integration-verification.md) for
the docs-fold writer; shared docs are not edited by this item.
2026-10-18 10:06:49 +01:00
..

Pipelines web spike (Route B)

A throwaway, dependency-free browser client that proves the Pipelines WebSocket protocol works from a web page end to end. It is a spike, not a product: it renders a pipeline list and a run detail and nothing else.

This directory is deliberately separate from android/ and does not touch it. The Android app remains the Kotlin/Compose client.

Why this route

Two ways to expose the app as a web app were considered:

  • Route A — Compose Multiplatform Web (WASM): reuse the Kotlin protocol layer and Compose UI. Most code reuse, but needs the Kotlin/WASM toolchain.
  • Route B — browser-native client (this spike): a small JS app using the browser's native WebSocket. No toolchain, browser-native behaviour, and it can be verified against a live server immediately.

This spike is Route B. The android/ protocol models were the spec: the wire format, server-URL rules and reply matching here mirror android/app/src/main/java/net/awan/pipelines/data/.

Safety (unchanged from the Android client)

  • Trusted LAN/VPN only. The Pipelines API has no authentication and is not internet-safe. Do not expose the server to untrusted networks. A web page widens that surface: any tab can open the socket.
  • No secrets. Nothing is stored except the server URL, in localStorage.
  • No hardcoded server. The URL is entered by the user; there is no default address baked in.

Layout

File Android counterpart Notes
src/protocol.js data/protocol/Message.kt (constants) types + #success/#failure
src/serverUrl.js data/transport/ServerUrl.kt validateServerUrl, resolveArtifactUrl
src/client.js data/transport/PipelinesClient.kt one reused socket, id matching, backoff. DOM-free
src/repository.js data/PipelinesRepository.kt typed request builders
src/app.js ui/** DOM UI: pipeline list + run detail
serve.mjs — zero-dep static server
test/*.test.mjs app/src/test/** node --test
test/smoke.mjs — live end-to-end against a running server

client.js is DOM-free on purpose, so the smoke test drives the same transport module the page uses.

Run it

cd web
node serve.mjs                 # http://127.0.0.1:8090/
node serve.mjs --host 0.0.0.0  # reachable from other devices (trusted LAN/VPN)

serve.mjs both serves the page and proxies /connect to the Pipelines server (--pipelines 127.0.0.1:8080 by default), so the page and the WebSocket are one origin. The page defaults its URL field to ws://<this page's host>/connect (the proxy) — just press Connect. Nothing is hardcoded: the default is derived from wherever the page was loaded and can be overridden.

Why the page cannot connect directly (403)

internal/server/websocket.go calls websocket.Accept(w, r, nil) — github.com/coder/websocket — which rejects an upgrade whose Origin host does not match the request Host. A browser page served from :8090 opening ws://HOST:8080/connect sends Origin: http://HOST:8090 and is refused:

HTTP/1.1 403 Forbidden
request Origin "HOST:8090" is not authorized for Host "HOST:8080"

A Node or curl client sends no Origin and is accepted — which is why the smoke test passes while a browser does not. The proxy sidesteps this by making the page same-origin and dropping the Origin header on the way through (the server has no authentication, so nothing is lost). Any web client that is served from a different origin than the Pipelines server hits this same 403.

To open the page from another device, bind --host 0.0.0.0 and use this machine's Tailscale/LAN address for the page only, e.g. http://100.85.25.33:8090/, then press Connect (the field already holds ws://100.85.25.33:8090/connect). Both hops are plaintext, so there is no mixed-content block; only do this on a trusted tailnet/VPN.

Test it

cd web
node --test test/                                        # unit tests, no server
PIPELINES_WS_URL=ws://127.0.0.1:8080/connect node test/smoke.mjs   # live

node --test covers the ported URL validation/artifact resolution and the transport (id matching, serialization order, error replies, timeouts, not-connected guard, reconnect). smoke.mjs connects to a real server and runs ping, list_pipelines, list_runs, get_pipeline, get_run, and (when the newest run has artifacts) an artifact HEAD.

Verification status

Run on macOS with Node v26.9.0 against a live pipelines server on ws://127.0.0.1:8080/connect:

  • node --test test/ → 20 tests, 0 failures.
  • node test/smoke.mjs → SMOKE PASS (6 checks): websocket connected, ping -> pong, list_pipelines -> 14 pipelines, list_runs -> 189 runs, get_pipeline #1, get_run #189. No artifact fetch (that run had none).
  • node --check parses every source and test file.
  • serve.mjs serves /, index.html, styles.css and each src/*.js with the right content type (200); /favicon.ico is 204; /nope.js is 404; with curl --path-as-is no raw .. path escapes web/ (traversal attempts either serve a file inside web/ or 404).

The cross-origin 403 and the proxy fix were verified on macOS against the live server (ws://100.85.25.33:8080/connect):

  • Direct handshake with Origin: http://100.85.25.33:8090 → HTTP/1.1 403 Forbidden (request Origin "100.85.25.33:8090" is not authorized for Host "100.85.25.33:8080"); the same handshake without Origin → 101 Switching Protocols.
  • Through the proxy (:8090) with the same browser Origin → 101 Switching Protocols.
  • PIPELINES_WS_URL=ws://100.85.25.33:8090/connect node test/smoke.mjs → SMOKE PASS (6 checks) — a full request/reply session over the tunnel.

Not verified: the rendered page itself. No desktop browser was connected to this session, so the DOM UI was not opened, clicked or screenshotted. app.js parses and its data path is exercised through the shared client/repository/ serverUrl modules, but its rendering and event wiring are unproven. Also unverified: wss:///TLS (no TLS server was available) and multiple concurrent browser tabs.

Next step

Before committing to a route, open http://127.0.0.1:8090/ in a browser, connect to the running server, and confirm the list/detail flow. If Route A is chosen instead, the data/-layer mapping in the table above is the port checklist; the Android-API friction lives in the artifact viewer, navigation, lifecycle and SharedPreferences touchpoints (android/README.md documents them).