@keepsnappy/agent 0.1.0-alpha.13 → 0.1.0-alpha.14

package/README.md

@@ -1,6 +1,6 @@
 # @keepsnappy/agent
 
-The `keepsnappy` host CLI. It runs the customer's own test command several times, collects the keepsnappy data the app wrote during each run, turns it into metrics, and asks `@keepsnappy/stats` for a verdict. v1 is local only and measure-only: no code changes in the customer app, no driver of our own (the test command is Maestro, Appium, XCUITest, anything that exits 0 on success).
+The `keepsnappy` host CLI. It runs the customer's own test command several times, collects the keepsnappy data the app wrote during each run, turns it into metrics, and with `--upload` sends the runs to the server, which judges them. v1 is measure-only: no code changes in the customer app, no driver of our own (the test command is Maestro, Appium, XCUITest, anything that exits 0 on success).
 
 ## Commands
 
@@ -13,7 +13,6 @@ keepsnappy measure --repeat 10 \
   --platform ios-sim [--device <udid>] [--bundle-id com.x.app] [--out runs/s1] [--timeout 600] \
   [--ri-capture observations.ndjson] [--mem-window chat.open] \
   -- maestro test flows/open-chat.yaml
-keepsnappy verdict runs/s1 [--baseline A --candidate B]   # table + verdict.json
 keepsnappy extract runs/s1 --ri-capture observations.ndjson   # re-derive metrics.csv (adds ri.* / mem.*)
 keepsnappy aa runs/s1 [--reps 300 --boot 400]             # noise floor / MDE per metric
 keepsnappy doctor                                         # xcrun, simctl, devicectl, maestro, appium, node, booted sims, devices
@@ -27,15 +26,15 @@ keepsnappy doctor                                         # xcrun, simctl, devic
 
 ## `keepsnappy run` and `keepsnappy.yml` (customer entry point)
 
-`keepsnappy run` is the wrapper for the e2e command you already have (mode A in docs/research/23-execution-modes-and-data-flow.md). It runs the command N times, drops runs where it failed, pulls the app's keepsnappy data after each run, derives metrics and writes the out dir. With `--baseline <earlier out dir>` it also says what changed. Nothing is built or installed by it: your CI supplies the build (with `KEEPSNAPPY=1`) and the device.
+`keepsnappy run` is the wrapper for the e2e command you already have (mode A in docs/research/23-execution-modes-and-data-flow.md). It runs the command N times, drops runs where it failed, pulls the app's keepsnappy data after each run, derives metrics and writes the out dir. It does not judge anything itself: `--upload` sends the runs and the server says what changed. Nothing is built or installed by it: your CI supplies the build (with `KEEPSNAPPY=1`) and the device.
 
 ```sh
 keepsnappy run                                   # command built from keepsnappy.yml
 keepsnappy run -- maestro test --include-tags perf e2e/flows/   # wrap your own command (config still gives bundle id, device, repetitions)
-keepsnappy run --baseline main-out --upload      # compare with the baseline run, then send results to the ingest
+keepsnappy run --upload --wait                   # send the results; the server judges them and the CLI prints its verdict
 ```
 
-Flags: `--config` (default `keepsnappy.yml`), `--repeat N`, `--out DIR`, `--baseline DIR`, `--upload [--ingest-url URL]`, `--wait`, `--fail-on-worse`, `--commit SHA` / `--branch NAME` (default `GITHUB_SHA` / `GITHUB_HEAD_REF` on a pull request, else `GITHUB_REF_NAME`), `--base-commit SHA`, `--device-model` / `--device-os` (default: read from the booted simulator), `--scenario NAME` (flow name for a command given after `--`), `--replay <out dir>[:ARM]` (repeatable: take recorded runs instead of running anything), `--no-markers`, `--clock-offset-ms`.
+Flags: `--config` (default `keepsnappy.yml`), `--repeat N`, `--out DIR`, `--upload [--ingest-url URL]`, `--wait`, `--fail-on-worse`, `--commit SHA` / `--branch NAME` (default `GITHUB_SHA` / `GITHUB_HEAD_REF` on a pull request, else `GITHUB_REF_NAME`), `--base-commit SHA`, `--device-model` / `--device-os` (default: read from the booted simulator), `--scenario NAME` (flow name for a command given after `--`), `--replay <out dir>[:ARM]` (repeatable: take recorded runs instead of running anything), `--no-markers`, `--clock-offset-ms`.
 
 Commit details: when a run set opens (`keepsnappy run --upload`, `keepsnappy farm open`), the CLI reads the subject, author
 name and committer date of `--commit` and `--base-commit` with `git log` in the checkout (argv only, 5 s timeout) and
@@ -45,6 +44,8 @@ or outside a pull request, the fields are left out and nothing fails. On a GitHu
 the merge commit, so its title is "Merge … into …"; pass `--commit ${{ github.event.pull_request.head.sha }}` (with the
 head commit fetched) to get the branch's own commit.
 
+Base commit: without `--base-commit`, a run that is not on main sends `base_commit_sha` = `git merge-base origin/main <commit>` (then `main`), the merge-base of main with the commit recorded as `commit_sha` (`--commit`, else `GITHUB_SHA`): the two fields always name one commit. It is never taken from `HEAD`: without a recorded commit nothing is sent. After main was merged into the branch it is the last merged main commit, not where the branch was cut; on a `pull_request` checkout `commit_sha` is GitHub's merge commit, so it is main's tip (pass `--commit ${{ github.event.pull_request.head.sha }}` and both fields name the branch's own commit). `GITHUB_BASE_REF` names another target branch (`origin/<it>`) and `KEEPSNAPPY_BASE_REF` overrides both; a repo whose default branch is not `main` sets it, e.g. `KEEPSNAPPY_BASE_REF=origin/master`. It is recorded only; the verdict does not read it. Nothing is sent when the commit is already on main (including a run on main under any remote name). If git cannot tell (no commit recorded, no git, main or the commit not in the checkout), nothing is sent, one warning line is printed and the run goes on: a wrong base is worse than none. In CI, check out with `fetch-depth: 0` (or fetch main and the commit).
+
 Journey titles: on `--upload` the run set carries `journeys[]` — per flow its key (the file stem), `source_path` (the flow file relative to the git repo root) and a title and description: from the `{path, title, description}` form of `flows.paths`, else the flow's own `name:` (when it differs from the stem) and the first paragraph of the comment that opens the file. Given values update the journey on the dashboard; absent ones keep what is stored.
 
 Flows: with `runner: maestro` every flow file is run on its own (one `maestro test` per file per repetition, tag filters applied) and its file stem is the journey name (`meta.scenario`, plan D1). A directory in `flows.paths` means the flow files directly in it (not `config.yaml`). A command after `--` or `flows.command` is one flow, named by `--scenario`, its only `.yaml` argument, or `e2e`. With several flows, run ids get the flow as a suffix and `runs.ndjson` records `scenario`.
@@ -58,29 +59,26 @@ Annotated example: `examples/keepsnappy.yml`. Every setting:
 | `app.bundle_id` | Required. App whose keepsnappy log is read after each run. |
 | `platform`, `device` | `ios-sim` (default; `device` = UDID or `booted`) or `ios-device` (UDID required). One device per invocation in v1. |
 | `repetitions` | Runs of the whole flow set (default 5). |
-| `baseline_branch` | Branch the baseline comes from (default `main`). Recorded for CI; the CLI compares with the directory you pass to `--baseline`. |
 | `flows.runner` | `maestro` (build `maestro test ...`) or `command` (run `flows.command`). |
 | `flows.tags`, `flows.exclude_tags` | `--include-tags=` / `--exclude-tags=`. |
 | `flows.paths` | Files, directories or globs (`*`, `?`, `**`); expanded by keepsnappy (no shell). With only tags the path defaults to `.`. An entry can also be `{path, title, description}` (one flow file): how the dashboard names the journey. |
 | `flows.command` | Any command that exits 0 on success (Appium, Detox, ...); text or list, run without a shell. |
 | `flows.maestro_version` | Note only: printed at the start of the run. |
 | `steps.rename` | `old: new` names applied to metrics (`old.dur_ms` becomes `new.dur_ms`, `step:old.*` too), so history keeps stable names. |
-| `steps.pin` | Names always listed in the summary. |
-| `output.dir` | Out dir (default `keepsnappy-out`): `runs.ndjson`, `metrics.csv`, `<run>/test.log`, `<run>/keepsnappy.log`, `<run>/markers.ndjson`, and with a baseline `compare/metrics.csv` + `compare/verdict.json`. |
+| `output.dir` | Out dir (default `keepsnappy-out`): `runs.ndjson`, `metrics.csv`, `<run>/test.log`, `<run>/keepsnappy.log`, `<run>/markers.ndjson`. |
 | `timeout_seconds` | Per run of the command. |
 
 Unknown settings and wrong types are errors, all listed together.
 
-Results and exit codes: results never change the exit code by default (ruling D9, no blocking PR checks): `0` also for "More work". `--fail-on-worse` (needs `--wait`) makes "More work" exit `3`. The CLI exits `2` for a configuration problem (bad or missing `keepsnappy.yml`, flags, a glob matching nothing, `--wait` without a branch or key) and `1` for an infrastructure problem (cannot read the device log, baseline dir without `metrics.csv`, an API request failing; results stay in the out dir). Failed runs are marked invalid in `runs.ndjson` / `metrics.csv` and ignored by the statistics. The ending summary reads like:
+Results and exit codes: results never change the exit code by default (ruling D9, no blocking PR checks): `0` also for "More work". `--fail-on-worse` (needs `--wait`) makes "More work" exit `3`. The CLI exits `2` for a configuration problem (bad or missing `keepsnappy.yml`, flags, a glob matching nothing, `--wait` without a branch or key) and `1` for an infrastructure problem (cannot read the device log, an API request failing; results stay in the out dir). Failed runs are marked invalid in `runs.ndjson` / `metrics.csv` and ignored by the statistics. The ending summary reads like:
 
 ```
 7/8 runs valid (dropped: 1 test-failed: exit 1)
-Compared with main-out: 42 metrics
-Top changes:
-  More work chat.open: renders  +100% (100 -> 200)
-More work: 1  Less work: 0  No change: 38  Not enough data yet: 3
+Results: keepsnappy-out
 ```
 
+With `--upload --wait` the server's result follows it.
+
 `--upload` (off by default) needs a project key with `run` scope in the env var named by `project.key_env` (default `KEEPSNAPPY_KEY`); the API URL defaults to the hosted KeepSnappy API. With a branch it opens a run set (`POST /v1/run-sets`) before measuring, so a wrong key fails before device time is spent; then sends each valid run: `POST /v1/runs` (header `x-keepsnappy-key`, `meta.scenario`, `meta.run_set_id`), `POST /v1/windows` with the run's own `KEEPSNAPPY window` log lines (run token, 200 per batch, deterministic batch ids so a retry is safe), `POST /v1/markers` with its declared step markers, `POST /v1/runs/:id/finish`. A 429 is retried after `retry-after`. Then it closes the run set:
 
 - with `--wait`: `POST /v1/run-sets/:id/complete` computes the verdicts inline and the CLI prints them in plain words (More work / Less work / No change / Not enough data yet per journey and device, the top changed checks, "Few runs — result may be noisy" when the server flags it) plus a dashboard link that opens the comparison;
@@ -88,7 +86,7 @@ More work: 1  Less work: 0  No change: 38  Not enough data yet: 3
 
 On the baseline branch (`main` by default, set per app on the server) the runs grow each journey's history; on any other branch they are compared with it. Without a branch the runs are uploaded as before, without a run set and without a verdict. The CLI writes `<out>/keepsnappy-result.json` (`run_set_id`, `dashboard_url`, `state`, summary) and `<out>/keepsnappy-run.json` (device, branch), and on GitHub Actions appends the result to `$GITHUB_STEP_SUMMARY`. Ready workflow: `examples/github-actions.yml`.
 
-`keepsnappy verdict <out> --baseline remote [--branch main] [--limit N]` compares each flow's local runs with the server baseline of the same flow and device (`GET /v1/baselines`: the history of the baseline branch, inside the same window the dashboard uses), for the metrics the server judges.
+There is no local verdict. `keepsnappy run --baseline <dir>` and `keepsnappy verdict` (any form) exit `2` with "use --upload; the server judges", and `GET /v1/baselines` answers `410`.
 
 ## `keepsnappy farm` (device farm, the app pushes)
 
@@ -207,7 +205,7 @@ branch was measured differently from main.
 <out>/<run_id>/test.log      stdout/stderr of the test command
 <out>/<run_id>/keepsnappy.log  Documents/keepsnappy/log.txt pulled from the app
 <out>/metrics.csv            long format: run_id,arm,block,metric,value,valid,invalid_reason
-<out>/verdict.json           written by verdict / aa
+<out>/aa.json                written by aa
 ```
 
 ## Architecture
@@ -219,7 +217,7 @@ branch was measured differently from main.
                ├─ Spawner.run(test command)            t0 .. t1, exit code
                ├─ DataSource.fetchLog ── IosSimulatorDataSource | IosDeviceDataSource
                └─ window-log (parse, slice by time) ► metrics (per-window medians) ► metrics.csv
- cli.ts ──► verdict / aa ──► @keepsnappy/stats (compareRuns / aaRuns) ──► table + verdict.json
+ cli.ts ──► aa ──► @keepsnappy/stats (aaRuns) ──► table + aa.json
 ```
 
 Pure core (`schedule`, `window-log`, `metrics`, table formatting) plus thin adapters. Process spawning, clock and filesystem come in through `Deps` (`ports.ts`), so every test runs on fakes and fixtures; nothing touches a simulator or device.