Files
pipelines/docs/feature-changes.md
T
alan 93682f9ce6 Add the Feature workflow and its full-stack change guide
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.
2026-11-09 23:38:57 +00:00

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 /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. 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.