@keepsnappy/agent 0.1.0-alpha.11 → 0.1.0-alpha.12

package/README.md

@@ -22,7 +22,7 @@ perflab doctor                                         # xcrun, simctl, devicect
 - `--arms`: `NAME=<.app/.ipa path>` (installed with `simctl install` / `devicectl device install app`, only when the arm changes) or `NAME=<bundle id>` (already installed). Without `--arms` there is one arm `A`: plain repetition, usable for `keepsnappy aa`.
 - `--arm-env 'A:KEY=VAL'` (repeatable): extra env for the test command on that arm's runs, also exported as `MAESTRO_KEY` (Maestro forwards only `MAESTRO_*` to flows). Used for same-binary arms that differ only in knobs, e.g. `--arms A=dev.perflab.reference,B=dev.perflab.reference --arm-env 'A:REF_KNOBS=…' --arm-env 'B:REF_KNOBS=…'`. The arms with their env are written to `<out>/arms.json`. Order stays ABBA.
 - `--platform ios-device` needs `--device <udid>`. The simulator default target is `booted`.
-- The test command runs as argv (no shell) with `PERFLAB_RUN_ID`, `PERFLAB_ARM`, `PERFLAB_RUN_DIR`, `PERFLAB_MARKER_URL` and `MAESTRO_PERFLAB_MARKER_URL` / `MAESTRO_PERFLAB_RUN_ID` in its environment.
+- The test command runs as argv (no shell) with `KEEPSNAPPY_RUN_ID`, `KEEPSNAPPY_ARM`, `KEEPSNAPPY_RUN_DIR`, `KEEPSNAPPY_MARKER_URL` and `MAESTRO_KEEPSNAPPY_MARKER_URL` / `MAESTRO_KEEPSNAPPY_RUN_ID` in its environment.
 - Declared steps (Maestro): call `maestro/perflab/step.yaml` with `STEP`/`PHASE` (start|end) from your flow; `measure` adds `step:<name>.*` rows (source=declared). `--no-markers` turns the endpoint off, `--clock-offset-ms` overrides the clock estimate. See docs/research/28-step-markers-prototype.md.
 
 ## `keepsnappy run` and `keepsnappy.yml` (customer entry point)
@@ -148,9 +148,9 @@ that arrives after a run was finished is added by the server and the run re-proc
 result, `3` with `--fail-on-worse` on "More work", `2` for configuration, `1` when the API fails or nothing could be
 judged ("Blocked": no iteration sent any data).
 
-Slack: set `PERFLAB_SLACK_WEBHOOK` (an incoming-webhook URL kept as a CI secret) and `farm close --wait` posts the
+Slack: set `KEEPSNAPPY_SLACK_WEBHOOK` (an incoming-webhook URL kept as a CI secret) and `farm close --wait` posts the
 result: a pull request only when something got worse (a table of the 3 biggest changes, main vs PR), main only when
-something changed (`PERFLAB_SLACK_ALWAYS=1` also posts "no change"), and a measurement that sent no data always. The
+something changed (`KEEPSNAPPY_SLACK_ALWAYS=1` also posts "no change"), and a measurement that sent no data always. The
 commit's title and author come from `git log` in the checkout. A Slack failure is printed and never changes the exit code.
 
 Declared steps on the farm: `maestro/perflab/step.yaml` / `step.js` / `send-markers.js` (copy them into the suite).
@@ -162,9 +162,9 @@ run is invalid through its missing completion marker, and its markers stay for d
 (`examples/farm/flows/perflab/`) ships its own copy of `send-markers.js`. Without a token, `step.js` posts to the local
 CLI endpoint at once; there a step started but never ended invalidates its run (`unclosed-steps`).
 
-Detox (Jest): `packages/detox` (`@keepsnappy/detox`) gives `step(name, fn)` / `stepStart` / `stepEnd`, posting the same markers: to the local endpoint from `PERFLAB_MARKER_URL` + `PERFLAB_RUN_ID` (set by `keepsnappy run`/`measure`), or on the farm to `KEEPSNAPPY_API_URL/v1/markers` with `PERFLAB_RUN_TOKEN` as the bearer token. Optional per-test step names via `@keepsnappy/detox/auto-steps`. See its README.
+Detox (Jest): `packages/detox` (`@keepsnappy/detox`) gives `step(name, fn)` / `stepStart` / `stepEnd`, posting the same markers: to the local endpoint from `KEEPSNAPPY_MARKER_URL` + `KEEPSNAPPY_RUN_ID` (set by `keepsnappy run`/`measure`), or on the farm to `KEEPSNAPPY_API_URL/v1/markers` with `KEEPSNAPPY_RUN_TOKEN` as the bearer token. Optional per-test step names via `@keepsnappy/detox/auto-steps`. See its README.
 
-Farm e2e against a local API: `KEEPSNAPPY_KEY=… PERFLAB_INGEST_KEY=… e2e/farm/run.sh <new out dir>` (fake session using
+Farm e2e against a local API: `KEEPSNAPPY_KEY=… KEEPSNAPPY_INGEST_KEY=… e2e/farm/run.sh <new out dir>` (fake session using
 the SDK push client, one late batch, one empty iteration).
 
 ## `keepsnappy findings` and friends (read-only questions)
@@ -258,4 +258,4 @@ Memory slopes (Theil-Sen over the cycle index, 3+ cycles of `--mem-window`, defa
 `bun run typecheck` and `bun run test` first build the workspace packages the CLI imports (`bun run deps`: stats, derive,
 verdicts, profile-analysis, mcp), so both work from a clean checkout.
 
-The `perflab` command and `perflab.yml` / `perflab.yaml` remain supported. Without `--config`, configuration is read in this order: `keepsnappy.yml`, `keepsnappy.yaml`, `perflab.yml`, `perflab.yaml`. `KEEPSNAPPY_*` variables take precedence over matching `PERFLAB_*` variables, including explicit empty values. Explicit `--key-env` or `project.key_env` names are read exactly.
+Only `keepsnappy` and `keepsnappy.yml` / `keepsnappy.yaml` are supported. Configure `KEEPSNAPPY_*` variables. Explicit `--key-env`, `project.key_env`, and `--config` remain arbitrary user-supplied names and paths.

package/dist/appium-driver.js

@@ -448,9 +448,12 @@ class Driver {
   }
   async tapElement(el) {
     const r = this.rects.get(el) ?? await this.cmd("GET", `/element/${el}/rect`);
+    await this.tapPoint({ x: r.x + r.width / 2, y: r.y + r.height / 2 });
+  }
+  async tapPoint(p) {
     const w = await this.screen();
-    const x = Math.round(Math.min(Math.max(r.x + r.width / 2, 1), w.width - 1));
-    const y = Math.round(Math.min(Math.max(r.y + r.height / 2, 1), w.height - 1));
+    const x = Math.round(Math.min(Math.max(p.x, 1), w.width - 1));
+    const y = Math.round(Math.min(Math.max(p.y, 1), w.height - 1));
     await this.cmd("POST", "/actions", {
       actions: [
         {
@@ -674,6 +677,13 @@ var MARKERS_PER_REQUEST = 500;
 var MARKER_TRIES = 3;
 var HOST_CLOCK_TRIPS = 6;
 var RETRY_BASE_MS = 1000;
+var FLING_MS = 80;
+var FLING_FROM = 0.8;
+var FLING_TO = 0.3;
+var FLING_TIMEOUT_MS = 30000;
+var STALE_REFINDS = 3;
+var FRAME_POLL_MS = 50;
+var sameRect = (a, b) => a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
 var RETRY_AFTER_CAP_MS = 30000;
 async function post(fetchImpl, url, token, body, now) {
   const t0 = now();
@@ -780,6 +790,10 @@ class Session {
   endGc;
   gcN = 0;
   stepDepth = 0;
+  refinds = 0;
+  get staleRefinds() {
+    return this.refinds;
+  }
   constructor(o) {
     this.driver = o.driver;
     this.scheme = o.scheme;
@@ -992,6 +1006,118 @@ class Session {
       await this.swipe([50, 50], direction === "down" ? [50, 10] : [50, 90], durationMs);
     }
   }
+  async frameOf(sel, el) {
+    for (let refinds = 0;; refinds++) {
+      try {
+        return { el, rect: await this.driver.cmd("GET", `/element/${el}/rect`) };
+      } catch (e) {
+        if (!(e instanceof WdError && e.wdError === "stale element reference"))
+          throw e;
+        const what = describeSelector(toSelector(sel));
+        if (refinds >= STALE_REFINDS)
+          throw new Error(`${what} went stale ${refinds + 1} times in a row (${refinds} re-finds): ${e.message}`);
+        this.refinds++;
+        try {
+          el = await this.waitVisible(sel);
+        } catch (lost) {
+          throw new Error(`${what} went stale and was not found again: ${lost instanceof Error ? lost.message : String(lost)}`);
+        }
+      }
+    }
+  }
+  async settledFrame(sel, timeoutMs) {
+    const start = this.now();
+    let at = await this.frameOf(sel, await this.waitVisible(sel));
+    for (;; ) {
+      await this.driver.sleep(FRAME_POLL_MS);
+      const now = await this.frameOf(sel, at.el);
+      if (sameRect(at.rect, now.rect))
+        return now;
+      if (this.now() - start > timeoutMs)
+        throw new Error(`${describeSelector(toSelector(sel))} did not stop moving within ${timeoutMs} ms`);
+      at = now;
+    }
+  }
+  async flingIn(r, toward, durationMs) {
+    const [from, to] = toward === "end" ? [FLING_FROM, FLING_TO] : [FLING_TO, FLING_FROM];
+    const x = Math.round(r.x + r.width / 2);
+    await this.driver.drag({ x, y: Math.round(r.y + r.height * from) }, { x, y: Math.round(r.y + r.height * to) }, durationMs);
+  }
+  async flingTimes(list, times, toward, { durationMs = FLING_MS, timeoutMs = FLING_TIMEOUT_MS } = {}) {
+    if (!Number.isInteger(times) || times < 1)
+      throw new Error(`flingTimes needs a whole number of flings >= 1, got ${times}`);
+    await this.ready();
+    const start = this.now();
+    const refindsBefore = this.refinds;
+    let flings = 0;
+    let status = 1;
+    try {
+      const { rect } = await this.settledFrame(list, timeoutMs);
+      for (;flings < times; flings++)
+        await this.flingIn(rect, toward, durationMs);
+      status = 0;
+    } finally {
+      this.driver.log.push({ ...this.driver.context, cmd: `fling-${toward}-times`, t: this.now(), ms: this.now() - start, status, flings, refinds: this.refinds - refindsBefore });
+    }
+  }
+  async flingUntil(list, target, toward, { blind = 0, durationMs = FLING_MS, timeoutMs = FLING_TIMEOUT_MS } = {}) {
+    await this.ready();
+    const start = this.now();
+    const refindsBefore = this.refinds;
+    let flings = 0;
+    let checks = 0;
+    let status = 1;
+    try {
+      let at = await this.settledFrame(list, timeoutMs);
+      const fling = async () => {
+        if (flings > 0)
+          at = await this.frameOf(list, at.el);
+        await this.flingIn(at.rect, toward, durationMs);
+        flings++;
+      };
+      while (flings < blind)
+        await fling();
+      const sel = toSelector(target);
+      while (checks++, !await this.driver.findShown(sel, true)) {
+        if (this.now() - start > timeoutMs)
+          throw new Error(`the ${toward} of the list did not show within ${timeoutMs} ms (${flings} flings)`);
+        await fling();
+      }
+      status = 0;
+      return flings;
+    } finally {
+      this.driver.log.push({ ...this.driver.context, cmd: `fling-to-${toward}`, t: this.now(), ms: this.now() - start, status, flings, checks, blind, refinds: this.refinds - refindsBefore });
+    }
+  }
+  async stableCentres(sels, timeoutMs = FLING_TIMEOUT_MS) {
+    await this.ready();
+    const start = this.now();
+    const els = [];
+    for (const sel of sels)
+      els.push(await this.waitVisible(sel));
+    const frames = async () => {
+      const out = [];
+      for (let i = 0;i < sels.length; i++) {
+        const f = await this.frameOf(sels[i], els[i]);
+        els[i] = f.el;
+        out.push(f.rect);
+      }
+      return out;
+    };
+    for (let before = await frames();; ) {
+      await this.driver.sleep(FRAME_POLL_MS);
+      const now = await frames();
+      if (now.every((r, i) => sameRect(r, before[i])))
+        return now.map((r) => ({ x: Math.round(r.x + r.width / 2), y: Math.round(r.y + r.height / 2) }));
+      if (this.now() - start > timeoutMs)
+        throw new Error(`the elements did not stop moving within ${timeoutMs} ms`);
+      before = now;
+    }
+  }
+  async tapAt(point) {
+    await this.ready();
+    await this.driver.tapPoint(point);
+  }
   async type(sel, value) {
     await this.ready();
     const el = await this.waitVisible(sel);
@@ -1081,7 +1207,7 @@ var DRIVER_OPTIONS = {
   repeat: { type: "string", default: "1" },
   device: { type: "string" },
   "local-identifier": { type: "string" },
-  "build-name": { type: "string", default: "perflab-appium" },
+  "build-name": { type: "string", default: "keepsnappy-appium" },
   "appium-version": { type: "string", default: "2.19.0" },
   out: { type: "string", default: "farm-run" },
   platform: { type: "string", default: "ios" },

package/dist/keepsnappy.js

@@ -3,12 +3,12 @@
 // apps/agent/src/compat.ts
 import { resolve } from "node:path";
 function envValue(env, name) {
-  return env[`KEEPSNAPPY_${name}`] ?? env[`PERFLAB_${name}`];
+  return env[`KEEPSNAPPY_${name}`];
 }
 function projectKey(env, name = "KEEPSNAPPY_KEY") {
   return name === "KEEPSNAPPY_KEY" ? envValue(env, "KEY") : env[name];
 }
-var CONFIG_NAMES = ["keepsnappy.yml", "keepsnappy.yaml", "perflab.yml", "perflab.yaml"];
+var CONFIG_NAMES = ["keepsnappy.yml", "keepsnappy.yaml"];
 async function readProjectConfig(read, explicit) {
   if (explicit !== undefined)
     return read(resolve(explicit));
@@ -5248,10 +5248,7 @@ function startMarkerServer(now = Date.now) {
 var markerEnv = (url, runId) => ({
   KEEPSNAPPY_MARKER_URL: url,
   MAESTRO_KEEPSNAPPY_MARKER_URL: url,
-  MAESTRO_KEEPSNAPPY_RUN_ID: runId,
-  PERFLAB_MARKER_URL: url,
-  MAESTRO_PERFLAB_MARKER_URL: url,
-  MAESTRO_PERFLAB_RUN_ID: runId
+  MAESTRO_KEEPSNAPPY_RUN_ID: runId
 });
 
 // apps/agent/src/upload.ts
@@ -9124,7 +9121,7 @@ async function measure(deps, source, installer, opts) {
     let exit = null;
     if (!reason) {
       const r = await spawner.run(cmd, args, {
-        env: { ...armEnv.get(p.arm), KEEPSNAPPY_RUN_ID: p.runId, KEEPSNAPPY_ARM: p.arm, KEEPSNAPPY_RUN_DIR: dir, PERFLAB_RUN_ID: p.runId, PERFLAB_ARM: p.arm, PERFLAB_RUN_DIR: dir, ...opts.markers ? markerEnv(opts.markers.url, p.runId) : {} },
+        env: { ...armEnv.get(p.arm), KEEPSNAPPY_RUN_ID: p.runId, KEEPSNAPPY_ARM: p.arm, KEEPSNAPPY_RUN_DIR: dir, ...opts.markers ? markerEnv(opts.markers.url, p.runId) : {} },
         ...opts.testTimeoutMs ? { timeoutMs: opts.testTimeoutMs } : {}
       });
       exit = r.code;
@@ -10072,7 +10069,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname as dirname2, join as join12, relative as relative2, resolve as resolve4 } from "node:path";
 import { fileURLToPath } from "node:url";
 function driverVersion() {
-  const built = process.env.KEEPSNAPPY_DRIVER_VERSION ?? "0.1.0-alpha.11";
+  const built = "0.1.0-alpha.12";
   if (built)
     return built;
   let dir = dirname2(fileURLToPath(import.meta.url));
@@ -10082,7 +10079,7 @@ function driverVersion() {
       continue;
     try {
       const pkg = JSON.parse(readFileSync(file, "utf8"));
-      if ((pkg.name === "@keepsnappy/appium-driver" || pkg.name === "@perf-labs/appium-driver") && pkg.version)
+      if (pkg.name === "@keepsnappy/appium-driver" && pkg.version)
         return pkg.version;
     } catch {}
   }
@@ -11144,7 +11141,7 @@ function substitute(value, s) {
   return value.replace(/\{tunnel:(\d+)\}/g, (_m, port) => `http://bs-local.com:${port}`).replace(/\{run_id\}/g, s.runId ?? "{run_id}").replace(/\{out\}/g, s.out ?? "{out}").replace(/\{tokens_js\}/g, s.tokensJs ?? "{tokens_js}").replace(/\{run_set_id\}/g, s.runSetId ?? "{run_set_id}");
 }
 function secretsOf(p, f, env) {
-  const out = [env.KEEPSNAPPY_KEY, env.PERFLAB_KEY, env.KEEPSNAPPY_SLACK_WEBHOOK, env.PERFLAB_SLACK_WEBHOOK, env.BROWSERSTACK_ACCESS_KEY, projectKey(env, f["key-env"]), env.EXPO_TOKEN, envValue(env, "SLACK_WEBHOOK")];
+  const out = [env.KEEPSNAPPY_KEY, env.KEEPSNAPPY_SLACK_WEBHOOK, env.BROWSERSTACK_ACCESS_KEY, projectKey(env, f["key-env"]), env.EXPO_TOKEN, envValue(env, "SLACK_WEBHOOK")];
   for (const [k, v] of p.env)
     if (SECRETISH.test(k))
       out.push(v);
@@ -11634,7 +11631,7 @@ async function get(t, path, query = {}) {
   if (!r.ok) {
     const code = typeof body.error === "string" ? body.error : String(r.status);
     const message = typeof body.message === "string" ? body.message : code;
-    const hint = r.status === 401 ? " (check KEEPSNAPPY_KEY or PERFLAB_KEY)" : r.status === 403 ? " (the key needs the read or run scope)" : "";
+    const hint = r.status === 401 ? " (check KEEPSNAPPY_KEY)" : r.status === 403 ? " (the key needs the read or run scope)" : "";
     throw new ApiError(r.status, code, `${message}${hint}`);
   }
   return body;

package/examples/farm/flows/perflab/send-markers.js

@@ -13,8 +13,7 @@
 try {
   var g = typeof globalThis !== 'undefined' ? globalThis : this;
   var pick = function (name, dflt) {
-    var modern = name.replace(/^PERFLAB_/, 'KEEPSNAPPY_');
-    var names = modern === name ? [name, 'MAESTRO_' + name] : [modern, 'MAESTRO_' + modern, name, 'MAESTRO_' + name];
+    var names = [name, 'MAESTRO_' + name];
     for (var i = 0; i < names.length; i++) {
       var v = g[names[i]];
       if (typeof v === 'string' && (v !== '' || names[i].indexOf('KEEPSNAPPY_') >= 0)) return v;
@@ -29,7 +28,7 @@ try {
   var out = typeof output !== 'undefined' && output ? output : {};
   var list = out.perflabMarkers || [];
   out.perflabMarkers = [];
-  var api = pick('PERFLAB_API_URL', typeof out.perflabApi === 'string' ? out.perflabApi : '').replace(/\/+$/, '');
+  var api = pick('KEEPSNAPPY_API_URL', typeof out.perflabApi === 'string' ? out.perflabApi : '').replace(/\/+$/, '');
   var wait = function (ms) {
     try {
       java.lang.Thread.sleep(ms);

package/examples/farm/workflows/perflab-measure.yml

@@ -37,7 +37,7 @@ jobs:
       BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
       KEEPSNAPPY_KEY: ${{ secrets.KEEPSNAPPY_KEY }}                  # run scope; never leaves this runner
       KEEPSNAPPY_API: https://perflab-api-864539138788.europe-west1.run.app
-      PERFLAB_CLI: '@keepsnappy/agent@0.1.0-alpha.1'           # first version with `farm` (not published yet)
+      KEEPSNAPPY_CLI: '@keepsnappy/agent@0.1.0-alpha.1'           # first version with `farm` (not published yet)
       OUT_DIR: ${{ github.workspace }}/farm-run
       RUN_ID: perflab-${{ inputs.platform }}-${{ github.run_id }}-${{ github.run_attempt }}
       JOURNEYS: e2e-community-and-live-chat                    # = the JOURNEY values in run-perflab.yaml
@@ -71,7 +71,7 @@ jobs:
           APP_COMMIT: ${{ steps.app.outputs.app_commit }}
         run: |
           [ -n "$APP_COMMIT" ] || { echo '::error::the artifact carries no commit'; exit 1; }
-          npx --yes "$PERFLAB_CLI" farm open \
+          npx --yes "$KEEPSNAPPY_CLI" farm open \
             --api "$KEEPSNAPPY_API" --branch main --commit "$APP_COMMIT" \
             --device-model 'iPhone 15 Pro' --device-os 17 --device-provider browserstack \
             --journeys "$JOURNEYS" --repeat "$REPEAT" \
@@ -99,7 +99,7 @@ jobs:
       - name: Close the run set and print the verdict
         if: always() && hashFiles('farm-run/perflab-farm.json') != ''
         run: |
-          npx --yes "$PERFLAB_CLI" farm close \
+          npx --yes "$KEEPSNAPPY_CLI" farm close \
             --state "$OUT_DIR/perflab-farm.json" \
             --bs-build "$OUT_DIR/browserstack.${{ inputs.platform }}.json" --settle-seconds 60 --wait
 

package/examples/github-actions.yml

@@ -1,14 +1,14 @@
-# .github/workflows/perflab.yml: measure every pull request against main, and grow main's history on every merge.
+# .github/workflows/keepsnappy.yml: measure every pull request against main, and grow main's history on every merge.
 #
 # Needs: a perf build of your app (built with PERFLAB=1, so the KeepSnappy SDK writes its data), Maestro flows, a
-# perflab.yml in the repo root (see examples/perflab.yml), and a project key with `run` scope stored as the repository
-# secret KEEPSNAPPY_KEY. The key never appears in logs; perflab reads it from the environment variable perflab.yml names.
+# keepsnappy.yml in the repo root (see examples/keepsnappy.yml), and a project key with `run` scope stored as the repository
+# secret KEEPSNAPPY_KEY. The key never appears in logs; keepsnappy reads it from the environment variable keepsnappy.yml names.
 #
 # What you get: on main, the runs join the history of each journey (one journey per Maestro flow file). On a pull
 # request, each journey is compared with main's recent history; the verdict ("More work", "Less work", "No change",
 # "Not enough data yet") is printed in the log and written to the job summary with a link to the comparison page.
 # The job does not fail on "More work" (no blocking checks for now); add --fail-on-worse to make it exit 3 instead.
-# Exit 2 = configuration problem (perflab.yml, flags), exit 1 = infrastructure (device log, upload).
+# Exit 2 = configuration problem (keepsnappy.yml, flags), exit 1 = infrastructure (device log, upload).
 
 name: perflab
 

package/examples/keepsnappy.yml

@@ -1,4 +1,4 @@
-# perflab.yml: the only file you maintain for KeepSnappy. Run it with `keepsnappy run`.
+# keepsnappy.yml: the only file you maintain for KeepSnappy. Run it with `keepsnappy run`.
 
 project:
   key_env: KEEPSNAPPY_KEY            # NAME of the env var holding the project key (a CI secret), never the key itself

package/maestro/perflab/send-markers.js

@@ -13,8 +13,7 @@
 try {
   var g = typeof globalThis !== 'undefined' ? globalThis : this;
   var pick = function (name, dflt) {
-    var modern = name.replace(/^PERFLAB_/, 'KEEPSNAPPY_');
-    var names = modern === name ? [name, 'MAESTRO_' + name] : [modern, 'MAESTRO_' + modern, name, 'MAESTRO_' + name];
+    var names = [name, 'MAESTRO_' + name];
     for (var i = 0; i < names.length; i++) {
       var v = g[names[i]];
       if (typeof v === 'string' && (v !== '' || names[i].indexOf('KEEPSNAPPY_') >= 0)) return v;
@@ -29,7 +28,7 @@ try {
   var out = typeof output !== 'undefined' && output ? output : {};
   var list = out.perflabMarkers || [];
   out.perflabMarkers = [];
-  var api = pick('PERFLAB_API_URL', typeof out.perflabApi === 'string' ? out.perflabApi : '').replace(/\/+$/, '');
+  var api = pick('KEEPSNAPPY_API_URL', typeof out.perflabApi === 'string' ? out.perflabApi : '').replace(/\/+$/, '');
   var wait = function (ms) {
     try {
       java.lang.Thread.sleep(ms);

package/maestro/perflab/step.js

@@ -2,17 +2,16 @@
 // Rhino). Must not throw: a marker is never a test failure.
 // Inputs: STEP, PHASE (from step.yaml). t_host is taken now, when the action happens, whenever the marker is sent.
 // Farm mode (`perflab farm open`): the flow has set `output.perflabToken` (one run token per iteration, from the
-// generated tokens.js) and the API base comes from `output.perflabApi` or PERFLAB_API_URL. The marker is only recorded
+// generated tokens.js) and the API base comes from `output.perflabApi` or KEEPSNAPPY_API_URL. The marker is only recorded
 // in the flow's memory; send-markers.js (end-run.yaml) posts the iteration's markers to <api>/v1/markers after it
 // ended, so the test never waits on the network between actions.
-// Local mode (`perflab run` / `measure`): PERFLAB_MARKER_URL, PERFLAB_RUN_ID point at the CLI's own endpoint on this
+// Local mode (`keepsnappy run` / `measure`): KEEPSNAPPY_MARKER_URL, KEEPSNAPPY_RUN_ID point at the CLI's own endpoint on this
 // host, posted at once (local flows have no end-run step). Maestro only forwards host env vars with the MAESTRO_ prefix,
 // unprefixed, so both spellings are read (docs/research/28).
 try {
   var g = typeof globalThis !== 'undefined' ? globalThis : this;
   var pick = function (name, dflt) {
-    var modern = name.replace(/^PERFLAB_/, 'KEEPSNAPPY_');
-    var names = modern === name ? [name, 'MAESTRO_' + name] : [modern, 'MAESTRO_' + modern, name, 'MAESTRO_' + name];
+    var names = [name, 'MAESTRO_' + name];
     for (var i = 0; i < names.length; i++) {
       var v = g[names[i]];
       if (typeof v === 'string' && (v !== '' || names[i].indexOf('KEEPSNAPPY_') >= 0)) return v;
@@ -23,15 +22,15 @@ try {
   var step = pick('STEP', '');
   var phase = pick('PHASE', '');
   var token = typeof out.perflabToken === 'string' ? out.perflabToken : '';
-  var api = pick('PERFLAB_API_URL', typeof out.perflabApi === 'string' ? out.perflabApi : '');
+  var api = pick('KEEPSNAPPY_API_URL', typeof out.perflabApi === 'string' ? out.perflabApi : '');
   if (token !== '' && api !== '') {
     out.perflabMarkers = out.perflabMarkers || [];
     out.perflabMarkers.push({ token: token, step: step, phase: phase, t_host: Date.now() });
   } else {
-    var base = pick('PERFLAB_MARKER_URL', 'http://127.0.0.1:47321');
+    var base = pick('KEEPSNAPPY_MARKER_URL', 'http://127.0.0.1:47321');
     http.post(base + '/marker', {
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ run: pick('PERFLAB_RUN_ID', ''), step: step, phase: phase, t_host: Date.now() }),
+      body: JSON.stringify({ run: pick('KEEPSNAPPY_RUN_ID', ''), step: step, phase: phase, t_host: Date.now() }),
     });
   }
 } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keepsnappy/agent",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.12",
   "description": "KeepSnappy CLI: runs your app journeys, measures from inside the app and reports More work / Less work / No change per step.",
   "type": "module",
   "license": "UNLICENSED",
@@ -16,8 +16,7 @@
     "node": ">=22"
   },
   "bin": {
-    "keepsnappy": "dist/keepsnappy.js",
-    "perflab": "dist/keepsnappy.js"
+    "keepsnappy": "dist/keepsnappy.js"
   },
   "files": [
     "dist",

package/examples/perflab.yml

@@ -1,36 +0,0 @@
-# perflab.yml: the only file you maintain for KeepSnappy. Run it with `keepsnappy run`.
-
-project:
-  key_env: KEEPSNAPPY_KEY            # NAME of the env var holding the project key (a CI secret), never the key itself
-  ingest_url: https://ingest.example.com   # optional; only used with `keepsnappy run --upload`
-
-app:
-  bundle_id: com.example.app      # the app under test; its perf-lab data is read from the device after every run
-
-platform: ios-sim                 # ios-sim | ios-device
-device: booted                    # simulator UDID or "booted"; required (UDID) for ios-device
-
-repetitions: 10                   # how many times the whole flow set runs
-baseline_branch: main             # the branch your baseline comes from (CI passes --baseline <its out dir>)
-
-flows:
-  runner: maestro                 # maestro: build `maestro test ...` from this file | command: run flows.command
-  maestro_version: 2.6.1          # note only: printed at the start, so a drifting Maestro is visible in logs
-  tags: [perf]                    # maestro --include-tags=perf
-  exclude_tags: [flaky]           # maestro --exclude-tags=flaky
-  paths:                          # files, directories or globs (*, ?, **); default "." when only tags are given
-    - e2e/flows/**/*.yaml
-    # - path: e2e/flows/chat/open.yaml  # one flow file with its dashboard title (else its `name:` / opening comment)
-    #   title: Open the chat
-    #   description: Community screen -> chat sheet, first message visible
-  # command: bun run e2e          # runner: command. Anything that exits 0 on success (Appium, Detox, ...)
-
-steps:
-  rename:                         # stable names in history; keys are window/step names as they appear in metrics.csv
-    "screen:(app)/community/[handle]/(tabs)": community.open
-  pin: [community.open]           # always listed in the summary, even without a change
-
-output:
-  dir: perflab-out                # runs.ndjson, metrics.csv, <run>/ logs, verdict (compare/verdict.json)
-
-timeout_seconds: 600              # per run of the command; optional