Merge main into sweep-ui: combine the UI sweep fixes with main's per-area agent maps
Main adds only documentation (per-area agent maps for the Android app, the TUI and the server); the sweep-ui side holds the UI/UX sweep fixes. No overlapping files, so both intents are kept unchanged.
This commit is contained in:
@@ -0,0 +1,65 @@
|
||||
# The Android app — working map
|
||||
|
||||
Read this before touching `android/`. It is the project-specific half; how Android projects in
|
||||
general are built, tested and reviewed belongs to the pipeline that started you.
|
||||
|
||||
## Build and test (offline, never with the daemon)
|
||||
|
||||
This checkout has no `gradlew`; the toolchain uses the installed distribution:
|
||||
|
||||
```sh
|
||||
export JAVA_HOME='/Applications/Android Studio.app/Contents/jbr/Contents/Home'
|
||||
export ANDROID_HOME="$HOME/Library/Android/sdk"
|
||||
GRADLE=/Users/alan/.gradle/wrapper/dists/gradle-8.11.1-bin/bpt9gzteqjrbo1mjrsomdt32c/gradle-8.11.1/bin/gradle
|
||||
"$GRADLE" --offline --no-daemon :app:assembleDebug # ~7 s incremental
|
||||
"$GRADLE" --offline --no-daemon :app:testDebugUnitTest # 400+ tests, ~8-13 s
|
||||
```
|
||||
|
||||
Always `--no-daemon`: a leftover daemon is what makes these look slow. Add **one** test class at a
|
||||
time while iterating — the full suite is for the end.
|
||||
|
||||
## The dev device
|
||||
|
||||
The only device is the operator's **Pixel 9 Pro XL, serial `47241FDAS00DLK`**. The operator's
|
||||
Pixel 10 Pro Fold (`58281FDCG000JF`) is theirs: use it only where an item's brief explicitly allows
|
||||
it, and never make it a default. **Never start or use an emulator.**
|
||||
|
||||
Before any capture: `svc power stayon usb`, `settings put global stay_on_while_plugged_in 7`,
|
||||
`input keyevent KEYCODE_WAKEUP`, `wm dismiss-keyguard`. Capture with
|
||||
`adb -s <serial> shell screencap -p /sdcard/shot.png` then `adb pull` — never `exec-out > file`.
|
||||
Wide layout: `wm size 2000x2244`; the fold's unfolded shape is `wm size 2076x2152`; `wm size reset`
|
||||
afterwards either way.
|
||||
|
||||
## Geometry is tokenised, and a test enforces it
|
||||
|
||||
Every dimension comes from `ui/theme/Dimens.kt` (plus the layout itself) — no new hardcoded `dp`, no
|
||||
percentages. `DimensTest` fails the build for a raw literal outside that file, so a value that
|
||||
genuinely needs a new token goes there, named for its purpose.
|
||||
|
||||
## Where things are
|
||||
|
||||
- `ui/PipelinesApp.kt` — the app shell: destinations, the floating pill, the omni-search morph.
|
||||
- `ui/chat/` — the chat: `ChatScreen`/`ChatTranscript`/`ChatComposer` (list, transcript, composer),
|
||||
`ChatStore` (multi-conversation state), `ChatFormat` (parts → rendering), `ChatOverrides` (local
|
||||
rename/hide), `Markdown`, `ChatScroll`.
|
||||
- `ui/screens/` — `PipelineListScreen`, `PipelineDetailScreen`, `RunHistoryScreen`, `RunDetailScreen`,
|
||||
`SettingsScreen`, `Timeline`.
|
||||
- `ui/graph/` — the workflow graph, stage panes, artifacts gallery and viewer.
|
||||
- `ui/components/` — `ListRow`, `DetailTabs`, `PaneIdentity`, `RunStatus`, `AttentionSurface`.
|
||||
- `data/` — `PipelinesRepository` (the socket client) and `data/protocol/` (wire shapes).
|
||||
- The app talks to the Pipelines server over the websocket in `data/PipelinesRepository.kt`; live run
|
||||
state arrives as pushed `run_event` frames, and every view that shows run state folds them.
|
||||
|
||||
## Publishing a build
|
||||
|
||||
Copy the APK into the running run's artifacts directory as `pipelines-debug-wip-<short-HEAD>.apk` and
|
||||
report the LAN URL. After any install, leave the operator's phone on **main's** build:
|
||||
`/private/var/folders/jp/q0qvjyg54fl_c5vhhk1ylz2m0000gn/T/opencode/deploy-app.sh main`.
|
||||
|
||||
## Traps
|
||||
|
||||
- A build made in a worktree that is behind main is missing features main has — sync before building,
|
||||
and say which revision you built.
|
||||
- Changing the app's server URL for a test (a stub) must be undone: `ws://10.0.0.75:8080/connect`,
|
||||
workspace `/Users/alan/repos/pipelines`, then force-stop and relaunch.
|
||||
- `mStayOn`/screen timeout are already set; do not "fix" the device by locking or sleeping it.
|
||||
@@ -0,0 +1,51 @@
|
||||
# The Pipelines server — working map
|
||||
|
||||
Read this before touching `internal/server/`, `internal/stage/`, `internal/pipeline/` or
|
||||
`internal/protocol/`. The generic half — how a Go service is built, tested and reviewed — belongs to
|
||||
the pipeline that started you.
|
||||
|
||||
## Build and test
|
||||
|
||||
```sh
|
||||
go build ./... && go vet ./...
|
||||
go test ./internal/server # ~10-15 s
|
||||
go test ./internal/stage ./internal/pipeline ./internal/protocol
|
||||
go test ./... # ~1 min for everything; `gofmt -l .` must print nothing
|
||||
```
|
||||
|
||||
## Where things are
|
||||
|
||||
- `internal/server/websocket.go` — the `/connect` transport and the request dispatch. Envelope
|
||||
validation lives here; every command returns its own typed reply.
|
||||
- `internal/server/runner.go` — run execution: the stage loop, stage outcomes, budgets, retries,
|
||||
ownership and settlement. This is where a run's state changes.
|
||||
- `internal/server/runevents.go` — the push hub: subscriptions scoped per workspace, per-run frames,
|
||||
coalescing. Live clients fold these instead of polling.
|
||||
- `internal/server/chat_*.go` — the chat broker: `chat_sessions`, claims, the stream, permissions,
|
||||
session registry.
|
||||
- `internal/stage/` — one client per harness and stage type: `opencode.go` (native sessions),
|
||||
`pi.go` (RPC), `model.go`, `agent.go`, `human.go` (decision stages), `ntfy.go` (notifications),
|
||||
`result_repair.go` (the strict-envelope repair ladder), `budget.go` (usage accounting).
|
||||
- `internal/pipeline/` — the store: definitions and immutable versions, runs and steps, the
|
||||
operator-session registry, retention, search.
|
||||
- `internal/protocol/` — every wire shape. A new command means a message field here, documentation in
|
||||
`docs/cli.md`, and tests both sides.
|
||||
- `cmd/pipelines-server/main.go` — flags and wiring, including which OpenCode endpoint chat brokers
|
||||
from (`-opencode-endpoint`, `PIPELINES_OPENCODE_ENDPOINT`, or the recorded choice).
|
||||
|
||||
## Checking behaviour without disturbing the live server
|
||||
|
||||
`scripts/run-local-server.sh` starts a scratch server, and the binary takes `-addr` and `-db`, so a
|
||||
live check runs against a **scratch database and a free loopback port**. The operator's deployment is
|
||||
`~/.local/share/pipelines` with the service on `0.0.0.0:8080` and ntfy on `8090`.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- **Never restart, rebuild or redeploy the deployed server, ntfy or a running run** to test a change:
|
||||
a restart kills every run in flight. Deploying is the operator's step.
|
||||
- Commit locally only, never push.
|
||||
- One run per workspace at a time — the server refuses a second one rather than sharing a tree.
|
||||
- The service is durable: sessions, runs and definitions live in SQLite, so a migration must open an
|
||||
existing database cleanly (see the `migrateRun*`/`addColumnIfMissing` pattern).
|
||||
- Artifacts are inventoried with bounds (`internal/server/artifacts.go`: file count, per-file and total
|
||||
size); a large file is served by direct URL, not by growing the inventory.
|
||||
@@ -0,0 +1,46 @@
|
||||
# The TUI — working map
|
||||
|
||||
Read this before touching `internal/tui/`. The generic side — how a Go CLI/TUI project is built,
|
||||
tested and reviewed — belongs to the pipeline that started you.
|
||||
|
||||
## Build and test
|
||||
|
||||
```sh
|
||||
go build ./...
|
||||
go test ./internal/tui # fast (~2-4 s); the whole tree is ~1 min
|
||||
go vet ./...
|
||||
```
|
||||
|
||||
No device, no capture, no network: a TUI change is verified by unit tests plus a rendered frame.
|
||||
|
||||
## How the TUI is put together
|
||||
|
||||
- `model.go` — the `Model`, the key map (`keys`), and `Update`/`View` dispatch. Key bindings are
|
||||
declared in one place; a new binding goes there, not inline.
|
||||
- `dashboard.go`, `pipeline.go`, `runs.go`, `run_detail.go` — the screens. A run's detail is built
|
||||
from sections, and a section can open as its own pane in the sliding stack.
|
||||
- `context_footer.go` — the footer for the current mode. A modal's footer replaces the page's; never
|
||||
inherit shortcuts that the modal does not honour.
|
||||
- `theme.go` / `style.go` — colours and text styles. Status colour comes from one vocabulary so a
|
||||
state looks the same in every screen.
|
||||
- `linetext.go`, `graph.go` — line building and the stage graph rendering.
|
||||
- Human decision stages are answered in the TUI: `↑/↓ choose · Tab feedback · Enter decide · Esc
|
||||
cancel`.
|
||||
|
||||
## Reviewing a TUI change without a terminal
|
||||
|
||||
The pinned frames in `internal/harness/tmp/ui-review/render/` (`empty-catalog-*`, `filter-no-match-*`,
|
||||
`narrow-long-model-*`, `plain-nocolor-*`, `wide-focused-*`, in dark and light) are the reference
|
||||
renders. Compare against them when a change alters layout, spacing, colour or the footer, and add a
|
||||
frame when you introduce a new state worth pinning. A change that alters a pinned frame and does not
|
||||
say why is a review finding.
|
||||
|
||||
## Conventions and traps
|
||||
|
||||
- No polling: state arrives from the server; do not add a ticker to look busy.
|
||||
- The footer and the pane stack are shared surfaces — a change there affects every screen, so say what
|
||||
you checked.
|
||||
- Terminal width matters: verify at a narrow width as well as a wide one, and never assume colour
|
||||
support (`plain-nocolor-*` exists for a reason).
|
||||
- Do not restart the deployed server, the lanes or ntfy to test a TUI change: run the binary against a
|
||||
scratch server or use the fixtures.
|
||||
Reference in New Issue
Block a user