Files
pipelines/docs/feature-changes.md

5.4 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 /connect websocket. Home-folder access uses expandHomePath, resolveInsideHome and specialFilesystem; symlinks are operated on, not followed. Internal endpoints (for example /mcp) must not be reachable through the web proxy; add a proxy test. The server answers only loopback Hosts, refuses /connect with an Origin, and requires the shared server token (docs/notes/security-boundary.md); a new local client of the server sends the token, and the peer relay's address policy covers new remote paths. 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, claude control 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) and tool/analyze.sh. Web: cd web && node --test test/. Never bare flutter test.
  • Scratch end-to-end for server behaviour: build ./cmd/pipelines-server, run it with an isolated HOME, a scratch -db, -addr 127.0.0.1:0 (an OS-chosen port) and PIPELINES_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 with app/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 a umask 077 shell, internal/claude TestServiceTokenIsPassedOnlyFromAPrivateFile and internal/opencode TestStageDiscoveryRequiresPrivateRegistrationBeforeSessionWork. The installed server (and so the delivery gate) runs with Umask 63 (077), so the gate's Go check sets umask 022 first. Compare against a worktree of main before blaming a change.
  • Notes. Each feature leaves app/notes/<feature>.md with 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.