docs/feature-changes.md records how cross-layer features (protocol, persistence, server, harness adapters, web proxy, app, fixtures) were built and verified in this session; docs/workflows/feature.md is the reviewed prepare → plan → implement → review → ui-review → land definition that follows it, with a delivery gate for Go, web and app checks.
5.1 KiB
Full-stack feature changes
How a Pipelines feature that crosses layers is built, checked and handed over.
The Feature workflow (docs/workflows/feature.md) follows this guide; it
records what worked for the chat, terminal, file and discovery features built on
2026-11-08/09 (turn diffs, shell commands and the interactive terminal, the
permanent terminal, Pipelines chat tools, thinking levels, file upload, rename,
move and delete, dismissible commands, connection recovery).
Layers and where a feature touches them
| Layer | Where | Typical change |
|---|---|---|
| Protocol | internal/protocol/ |
New request/frame types in their own file; the Message field in message.go is additive and omitempty so older peers keep working |
| Persistence | internal/pipeline/ |
A new table in its own file with init… called from store.go; bounded rows; survives restarts |
| Server | internal/server/ |
Handlers in new files named for the area (chat_*, terminal_*, home_files_*), routed from chat.go/websocket.go; pushed frames to every client watching |
| Harness adapters | internal/claude, internal/codex, internal/opencode |
Per-harness mechanism checked against the installed CLI or app-server schema; unsupported means no feature, never a fake |
| Web proxy | web/serve.mjs, web/src/peerRelay.js |
Only for new HTTP paths: authenticated route plus the peer-relay allowlist |
| App | app/lib/features/<area>/ |
Small files; Material and Cupertino; reached through the chat's own gateway so multi-machine chats work |
| Fixture | app/tool/perf/*_fixture.dart, app/tool/search_selection_probe_entry.dart |
A ?param=1 option that renders the new states for captures |
Shared files every feature touches (message.go, chat_hub.go, store.go,
chat_thread_view.dart, perf_fixture.dart): keep edits there to a few lines
and put the logic in new files. Parallel features then merge with small,
additive conflicts.
Rules that held up
- Security boundary. Everything goes through the authenticated
/connectwebsocket. Home-folder access usesexpandHomePath,resolveInsideHomeandspecialFilesystem; symlinks are operated on, not followed. Internal endpoints (for example/mcp) must not be reachable through the web proxy; add a proxy test. Typed input, passwords and tokens are never logged or stored. Credentials never cross machines. - Bounds. Every retained buffer, list and payload has a limit (for example 1 MiB output, 50 runs, 512 KiB views, 5 notifications a minute) and reports truncation instead of failing silently.
- Platform reality. Check what the installed tools accept (for example
codex app-server generate-json-schema,claudecontrol requests, OpenCode's API). Browsers reserve some shortcuts (Ctrl/Cmd+T, Ctrl+Tab); say which ones work where. - Desktop vs phone. Web themes are pinned to Android, so desktop checks use
prefersCompactHitTargets(device platform), not the theme platform. - Shared environments. Never use the production server (127.0.0.1:8080, web 8083), real chats, the personal Fold, or restart shared services.
Verification
- Focused tests while editing. Go:
go test ./internal/<pkg> -run <Name>. App:cd app && tool/memwatch/full.sh 'test/a_test.dart test/b'(the whole path list is one quoted argument) andtool/analyze.sh. Web:cd web && node --test test/. Never bareflutter test. - Scratch end-to-end for server behaviour: build
./cmd/pipelines-server, run it with an isolatedHOME, a scratch-db,-addr 127.0.0.1:0(an OS-chosen port) andPIPELINES_MDNS=off, drive it over the websocket, then stop every process. Real harness runs need credentials; when they are missing, say so rather than claim them. - Rendered evidence for visible changes: build the full-app fixture once
(
flutter build web --target tool/search_selection_probe_entry.dart --output build/probe-app) and capture withapp/tool/capture/at wide (1400x900) and narrow (560x1000) sizes, light and dark, Material and Cupertino where relevant. Open every PNG cited. - Known pre-existing failures (as of 2026-11-09, on untouched main): 44
tests in
app/test/application/*(pending launch-update timer) and, under aumask 077shell,internal/claudeTestServiceTokenIsPassedOnlyFromAPrivateFileandinternal/opencodeTestStageDiscoveryRequiresPrivateRegistrationBeforeSessionWork. The installed server (and so the delivery gate) runs withUmask 63(077), so the gate's Go check setsumask 022first. Compare against a worktree of main before blaming a change. - Notes. Each feature leaves
app/notes/<feature>.mdwith behaviour, protocol, limits, security and the exact verification output.
Delivery (manager, not the workflow)
The workflow commits a reviewed candidate; the server's delivery gate checks it
and lands it on main. Deployment is separate and only on request: ./install
(web and server), a restart only when no chat or run is active, then
./install --apk (native build), ./install --macos --publish --flutter <flutter executable> and ./install --linux --publish.