Files
pipelines/app/notes/P3-run.md
T
alan 53a8f668ca feat(app): start a pipeline from the detail view
Native Run action opens the web's prompt/workspace/notify dialog, sends the exact run_pipeline body against the pinned resolved version with one request key per confirmed attempt, keeps refusals in the dialog, reconciles a lost reply by key, and opens only the server-named run through the existing run route with one fresh Runs list read.

Adds a shared failure-reason helper so operators never see Dart runtime prefixes, and records the slice boundary in notes/P3-run.md.
2026-10-22 02:07:49 +01:00

167 lines
9.0 KiB
Markdown

# P3 — Start a pipeline (native client)
## Outcome
The pipeline detail now has a native **Run** action that opens the browser's
prompt/workspace/notify dialog. Confirming sends the web's exact `run_pipeline`
request against the pipeline detail's resolved (pinned) version, opens only the
run id the server returns on the existing `/runs/:id` route, and makes the Runs
destination re-read its list exactly once. Nothing is sent while opening,
typing, cancelling or for either local validation failure.
## Behavior
- **Dialog**: title `Run <name>` (`Run pipeline` when the name is empty).
Fields and words match `web/src/views/pipelines.js`:
- `Prompt` / placeholder `What should this run do?`
- `Working directory (on the server)` / placeholder
`/absolute/path/on/the/server` plus
`Choose a recent directory or type an absolute path.`
- `Notifications for this run` with `Pipeline default`, `Notify me` and
`Silent`.
- `Cancel` and `Run`; while sending the primary action reads `Starting…`.
- **Validation**: `Enter a prompt for this run.` for a blank prompt;
`Choose an absolute working directory on the server.` unless the workspace as
typed starts with `/` (the sent value is trimmed, matching the browser's raw
check plus `String(workspace).trim()` request body). Neither sends
`run_pipeline`.
- **Request identity**: `pipeline_id` is the detail id and `version` is
`detail.resolvedVersion`, so a historical selection pins that recorded
version (not latest). `input.prompt` is trimmed; `workspace` is trimmed;
`notify_mode` is present only for `on`/`off`. No `title` or `output_format`
is sent. The request key is `app-run-<pipeline>-<version>-<stamp>-<entropy>`,
bounded well under 128 characters.
- **One key per confirmed attempt**: the first confirmation mints it; a second
confirmation while the first is in flight is ignored, so a double tap sends
once. A confirmed refusal clears the intent and the corrected attempt mints
a fresh key.
- **Refusal**: the dialog stays open with the server's own reason. Before
treating it as a correctable refusal, the client reads
`get_run {request_key}`; if that read finds an admitted run, that run opens
instead. If the read itself fails, admission is still unknown.
- **Lost reply**: a transport failure keeps the dialog open with the web's
honest wording (`… Admission may be unknown. Check/retry uses the same
request key.`), locks the fields and offers `Check / retry`. The deliberate
retry reads by the same key first and resends with that same key only when no
run is found. The pending intent is held per pinned identity in
`PipelinesController`, so closing and reopening the dialog in the session
restores the same check/retry state.
- **Acceptance**: only a reply that names a usable run id is opened. The action
reports that id to composition; `PipelinesApp` advances a Runs list token and
navigates to `AppRoute.run(id)`. The Runs destination performs one fresh
`list_runs` read (or its mount read if it was not mounted yet). No row is
inserted from the run reply.
## Deliberate slice boundary / remaining parity
- This slice implements the three fields named in the task. The browser dialog
also has a **Report format** select and loads `chat_directories` for workspace
suggestions, seeding the workspace from Settings/recent directories. Those are
**not** implemented here; the workspace starts empty on both hosts. This is a
known remaining gap for full dialog parity, not a silent fallback.
- Pending launch intents survive dialog close/reopen in the running app
(`PipelinesController`) but not a page reload. The browser persists them in
sessionStorage. No automatic replay exists in either case.
## Files
Added:
- `lib/features/pipelines/run_pipeline_intent.dart` — intent, notify mapping,
request-key minting, accepted/refused outcome.
- `lib/core/error_reason.dart` — shared failure-reason text without runtime
diagnostics (used by the launch dialog and retry action).
- `lib/features/pipelines/ui/run_pipeline_wording.dart` — verbatim browser copy
and stable keys.
- `lib/features/pipelines/ui/run_pipeline_fields.dart` — native Material /
Cupertino prompt, workspace and notification controls.
- `lib/features/pipelines/ui/run_pipeline_dialog.dart` — dialog state,
validation, locked immutable request, refusal/unknown handling.
- `lib/features/pipelines/ui/run_pipeline_action.dart` — submit/reconcile
transport, pending intent use, navigation callback.
- `test/features/pipelines/ui/run_pipeline_launch_test.dart`
- `test/application/run_start_wiring_test.dart`
- `test/features/runs/ui/runs_list_refresh_test.dart`
- `test/core/error_reason_test.dart`
- `tool/run_pipeline_probe.dart`, `tool/run_pipeline_probe.mjs`
Changed:
- `lib/features/pipelines/pipelines_controller.dart` — pending launch intents
keyed by pipeline/version.
- `lib/features/pipelines/widgets/pipeline_detail_panel.dart` — Run action in
the detail header and the `onRunStarted` callback.
- `lib/features/pipelines/screen.dart` — forwards `onRunStarted`.
- `lib/features/runs/data/runs_repository.dart` — adds the read-only
`runByRequestKey` (`get_run {request_key}`) used to reconcile a lost reply;
`startRun` takes the nullable notify wire value so the default omits the field.
- `lib/features/runs/actions/retry_wording.dart` — uses the shared reason text,
so the retry prompt no longer leaks `Bad state:` either.
- `lib/features/runs/screen.dart` — optional `listRefreshToken`.
- `lib/application/pipelines_destination.dart`, `runs_destination.dart`,
`pipelines_app.dart` — route wiring: accepted launch → `/runs/:id` + one Runs
list invalidation. This is the small composition wiring the task allowed; no
new route helper was added — the existing `AppRoute.run(id)` is used.
- `lib/features/runs/screen.dart` is the Runs route screen (not the run-detail
UI): it accepts the one-shot list invalidation token.
- `test/features/pipelines/pipeline_graph_tab_test.dart` — scrolls the
content-driven header to the Graph tab before tapping it. The header gained
the native Run action; the canvas assertion is unchanged.
## Review fixes
The UI review found two rendered defects; both are corrected here.
- **Readable Cupertino labels.** Field labels now use the host theme's label
text style (primary label colour, no invented point size), matching
`schedules/ui/editor/schedule_editor_fields.dart`. Only helper copy uses
`secondaryLabel` via `tabLabelTextStyle`. The placeholder now uses
`CupertinoColors.placeholderText.resolveFrom(context)` instead of copied
light/dark constants. A widget test asserts the label role, helper role and
placeholder source colour.
- **No Dart diagnostics in copy.** New `lib/core/error_reason.dart` reduces a
failure to its reason: `StateError` contributes only its message (not
`Bad state: `), and `Exception:`/`Bad state:` prefixes are stripped. Both
`describeRunPipelineError` and the shared `describeRetryError` use it, with
their existing fallbacks. The unknown-admission suffix is unchanged, and a
test asserts the dialog renders `Connection closed` with no `Bad state`.
- **Smaller review cleanup.** The run action now sends
`RunNotifyMode.wireValue` (the unused duplicate mapping is gone), and the
workspace check is the browser's raw check while the request keeps the
trimmed value.
- **Coverage added.** `Starting…` is asserted while submitting; closing and
reopening an unknown launch restores `Check / retry` with the same key; a
refusal whose by-key read finds an admitted run opens it without a second
launch; `test/core/error_reason_test.dart` covers diagnostic stripping.
## Checks (actual)
- `flutter analyze` — **No issues found**.
- `flutter test` — **999 passed** (full suite; includes the new launch, app
wiring, error-reason and runs-list tests). The focused
`flutter test test/features/pipelines test/application test/features/runs`
run also passed (274 tests).
- `flutter build web` — **succeeded** (normal app entrypoint).
- `flutter build web --target=tool/run_pipeline_probe.dart -o
build/run_probe_web` — **succeeded**.
- `node tool/run_pipeline_probe.mjs build/run_probe_web` — **passed** for both
host control sets against the isolated loopback fixture. The original capture
set is in
`/Users/alan/.local/share/pipelines/data/artifacts/97/public/run-pipeline-probe/`;
post-review frames are in `…/public/code-fix-p3-run/`.
Probe checks:
- Cupertino: Cancel sent nothing; both validation messages; exact payload
(`input`, `pipeline_id`, `request_key`, `version`, `workspace` only;
`pipeline_id=1`, `version=2`, `/work/release`,
`Review the release.`, key prefix `app-run-1-2-`); route `/runs/100`;
one fresh `list_runs` read after acceptance.
- Material: validation, exact payload, route `/runs/101`, one fresh
`list_runs` read.
Not verified: Android/iOS builds or device behavior (development is web-only in
this phase). No live production run was started; the probe fixture creates the
runs. No commit, push or deployment was performed; the candidate is left as
working-tree changes for the manager to land.