84 lines
5.4 KiB
Markdown
84 lines
5.4 KiB
Markdown
# 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 `Host`s, 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`.
|