76 lines
7.0 KiB
Markdown
76 lines
7.0 KiB
Markdown
# Flutter client — working agreement
|
|
|
|
## Scope and acceptance
|
|
- Only change files under `app/`. The Go server, the web proxy (`web/`), installation and deployment are read-only. Never restart shared services or manipulate real operator chats/runs for testing.
|
|
- This Flutter app is the only client: it replaced the former JavaScript web client and the Kotlin Android app.
|
|
- No backend changes; report missing capabilities.
|
|
- Standard Material and Cupertino controls, including buttons/menus in custom graphs/diffs/chat. System typography, theme colors, light/dark, content-driven layout and text scaling. No fixed row/bubble/button dimensions, bespoke palette or CSS token port. Platform differences are intentional. Centralize necessary layout constraints; do not ban legitimate native default spacing or graph coordinates.
|
|
- Develop and test ONLY web now. No ADB, emulators, device changes, Android/iOS builds or installs. Keep source portable to all three targets. Explicitly report mobile as unverified.
|
|
- Small cohesive files (aim below 250 lines; split by responsibility, not arbitrary fragments). Each task owns a directory and its tests. Do not edit another lane or root pubspec/main unless assigned.
|
|
- Code quality is a delivery requirement. No minified implementations, silent capability fallbacks, fake data masking missing features, or workarounds that bypass the real defect. A pipeline success does not waive missing behavior, native controls, regression coverage or rendered evidence. Label incomplete work honestly and complete it before claiming parity.
|
|
- The manager drives authorized routine integration and recovery without repeatedly stopping for permission. Feature implementation stays in pipelines where appropriate; infrastructure blockers can be resolved directly within the user's authorized scope. Verify quiescence, preserve data and rollback, act, and report actual results. Ask only for genuinely new scope or unresolved destructive choices.
|
|
|
|
## Shared contract
|
|
- `lib/core/api_gateway.dart`: `JsonMap` alias; `ApiGateway.call(type, [fields])` yields the entire decoded reply envelope; `frames` yields unsolicited server envelopes. Gateway owns request IDs. Do not put domain interpretation in transport.
|
|
- Feature directories: `lib/features/{pipelines,runs,chat,schedules,search,artifacts,settings,templates}/`. Pure domain logic has no widget imports. Feature screens receive an `ApiGateway`; do not open their own sockets.
|
|
- `lib/ui/adaptive/` owns platform primitives; `lib/shell/` owns navigation and composition. Manager integrates feature registration. Feature lanes may supply `screen.dart` but do not edit shell/main.
|
|
- Use existing dependencies. Only the assigned foundation lane or manager edits pubspec/lock.
|
|
- Tests mirror directories under `test/`; tests use local fixtures/fake gateways, never mutate production. Put item evidence in `notes/<item>.md`, not shared queue.
|
|
|
|
## Tools and verification
|
|
Flutter: `/Users/alan/development/flutter/bin/flutter`; Dart beside it. Run pub get per worktree; never upgrade shared SDK. Focused `flutter test test/<area>` while editing, `flutter analyze` and `flutter build web` for integrated acceptance. No Go/legacy client checks needed for app-only changes.
|
|
Rendered changes require real browser interaction/captures; widget tests alone are not browser evidence. Use isolated loopback servers and OS-assigned ports. Browser automation may use Chrome DevTools, with independent scripts under `app/tool/`; do not modify legacy browser drivers. Never disable authentication on exposed services.
|
|
Keep commits referenced; do not discard unrelated work or delete branches. No deployment/canonical URL cutover. Land candidates per selected pipeline; manager verifies actual ancestry and serves a separate preview.
|
|
|
|
## Devices and the resource pool (Android builds)
|
|
|
|
The ADB executable is `/Users/alan/Library/Android/sdk/platform-tools/adb`.
|
|
Use that absolute path (or explicitly add its directory to PATH); `adb: command
|
|
not found` alone is not evidence that the leased device is disconnected.
|
|
|
|
For populated attention review, `TestExportReadyAttentionReviewFixture` exports a
|
|
create-only scratch database when `PIPELINES_ATTENTION_REVIEW_DIR` names a new
|
|
directory. Its fixture.json identifies one failed, one finished and one waiting
|
|
run and the workspace. Build a scratch server, read back those states, and keep
|
|
the owned server alive through all UI interactions. The export itself does not
|
|
leave a server running or configure a device. Never use a dead scratch endpoint.
|
|
|
|
Only the **UI reviewer**, while its stage holds the runner-granted resource for its
|
|
visit, may use a device. Implementers and code reviewers do code, builds, unit
|
|
tests and source review only: **no adb, installs, captures, device-setting changes
|
|
or main-build restoration**. Never acquire a device using sleep/check loops. The
|
|
runner grants exactly one concrete member of the `android-devices` resource pool
|
|
and passes it to the stage as `resource_target`; take the `adb -s` target from
|
|
`resource_target.metadata.adb_serial` and do not choose a device yourself.
|
|
|
|
The pool's two members are:
|
|
|
|
- `phone-47241FDAS00DLK` — the operator's **Pixel 9 Pro XL**, adb serial
|
|
`47241FDAS00DLK` (metadata `kind=phone`).
|
|
- `emulator-Pipelines_Fold_A` — one managed **foldable emulator**, adb serial
|
|
`emulator-5554` (metadata `kind=emulator`, `avd=Pipelines_Fold_A`). Its unfolded
|
|
built-in display is 2076x2152; its cover display is 1080x2424.
|
|
|
|
The operator's **Pixel 10 Pro Fold** (`58281FDCG000JF`) is delivery-only: never a
|
|
test target. Do not start an ad-hoc emulator — the one managed foldable AVD above
|
|
is the only emulator in scope.
|
|
|
|
The UI reviewer records original app connection/workspace, display size and power/settings
|
|
before changing them. 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.
|
|
|
|
Create controlled fixtures for changed screens/states (including human-decision sheets)
|
|
on a scratch server/database and throwaway session; never depend on incidental production
|
|
state, change a real operator session, or restart a deployed service. Use the configured
|
|
authoritative endpoint, never a scratch URL as a project default. Keep all shell/ADB work
|
|
foreground and awaited: no detached/background processes may outlive the lease.
|
|
UI review includes restoring the captured original settings and main's build before its
|
|
successful return. Confirm every tool has exited. If capture, restoration or cleanup fails,
|
|
report the failure explicitly; do not claim verification or readiness. Uncertain termination
|
|
must fail closed and keep ownership quarantined, not delete a lock or expire it by age.
|
|
Return `output.resource_cleanup_confirmed=false` if restoration/readiness is uncertain;
|
|
that generic release veto retains the runner lease even if the harness reports idle.
|