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

package/README.md

@@ -103,10 +103,12 @@ keepsnappy farm open --api https://keepsnappy-api-….run.app --branch main --co
 keepsnappy farm close --state farm-run/keepsnappy-farm.json --bs-build farm-run/browserstack.ios.json --settle-seconds 60 --wait
 ```
 
-`keepsnappy farm run` does the whole night in one command (docs/plans/54a): resolve the app (`--app eas:<id>|file|bs://`), `farm open`, an optional BrowserStack Local tunnel (`--tunnel-for localhost:<port>`, repeatable), the device run (`--driver maestro` with `--suite-dir`/`--execute`, or `--driver appium --journey-module FILE` for the built-in Appium driver, `@keepsnappy/appium-driver`, docs/plans/54b; `--driver-script FILE` still runs your own driver), `farm close`, and cleanup (tunnel stopped, tokens file reset) whatever happened. `--env KEY=VALUE` values may use `{tunnel:<port>}`, `{run_id}`, `{out}`, `{tokens_js}`, `{run_set_id}`. Exit codes as `farm close`; a failed device run is 1. `--dry-run` prints the plan with no request. Needs `KEEPSNAPPY_KEY`, `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` (and `EXPO_TOKEN` for `eas:`).
+`keepsnappy farm run` does the whole night in one command (docs/plans/54a): resolve the app (`--app eas:<id>|file|bs://<id>|custom_id:<id>`), `farm open`, an optional BrowserStack Local tunnel (`--tunnel-for localhost:<port>`, repeatable), the device run (`--driver maestro` with `--suite-dir`/`--execute`, or `--driver appium --journey-module FILE` for the built-in Appium driver on iOS or Android, `@keepsnappy/appium-driver`, docs/plans/54b; `--driver-script FILE` still runs your own driver), `farm close`, and cleanup (tunnel stopped, tokens file reset) whatever happened. `--env KEY=VALUE` values may use `{tunnel:<port>}`, `{run_id}`, `{out}`, `{tokens_js}`, `{run_set_id}`. Pre-uploaded `bs://` and `custom_id:` app references pass through without a file upload. Appium uses `--timeout-minutes 80` by default: the driver receives SIGTERM at the timeout, then SIGKILL after `--kill-after-seconds 120` if it has not exited. A timeout is recorded in the failure message, including the terminating signal, and returns exit 1 even if the driver exits zero after SIGTERM. Exit codes as `farm close`; a failed device run is 1. `--dry-run` prints the plan with no request. Needs `KEEPSNAPPY_KEY`, `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` (and `EXPO_TOKEN` for `eas:`).
 
 Setup and completion (plan 51 stage 2): `--completion-marker` declares that the flow posts the step marker `run:complete` (end) at the end of every iteration, from the main flow and not from `onFlowComplete`; the API then marks a run without it invalid (`flow-incomplete`). `--driver-version`, `--app-build-id`, `--harness-version`, `--flag-set` go into every run's setup fingerprint; `farm close` adds the device farm's build id from `--bs-build`.
 
+The model a phone is stored under is the hardware code the OS reports (`SM-S911B`, `iPhone17,1`); the marketing name is only shown. With `--platform android|ios`, `--device-provider local|usb|customer|simulator|emulator` (the default `browserstack` needs an explicit model: a farm's phone is not on this machine) and no `--device-model`, `farm open` reads it from the device: Android `adb [-s <serial>] shell getprop ro.product.model`, an iPhone's machine id from `xcrun devicectl list devices`, a simulator's name from `xcrun simctl list devices` (kept with its "Simulator" word, so it never joins a real phone's row). With `--platform ios` and a `--device-id` that `xcrun simctl` lists as a simulator, `farm open` opens the run set as a simulator whatever provider and model were typed: provider `simulator`, the model with the "Simulator" word. It reads nothing it cannot pin to exactly one device (`--device-id` picks one); then `--device-model` is required. A typed `--device-model` is for a device this machine cannot ask (a farm's phone) and is sent as given.
+
 `farm open` also sends `journeys[]`: with `--config keepsnappy.yml` and/or `--flows <files|dirs|globs,...>` each `--journeys` name is matched to the flow file named like it (title, description, source path as for `keepsnappy run`); without them, keys only.
 
 `farm open` makes a run set (`source: farm`, the device of `--device-model/--device-os`: the journey history is keyed by
@@ -176,25 +178,31 @@ same words (`packages/mcp/README.md`).
 ```sh
 export KEEPSNAPPY_KEY=pl_rk_…        # a project key with read scope (a CI key with run scope works too)
 keepsnappy findings --branch feat/keepsnappy-integration     # what got worse or better on a PR, worst first
+keepsnappy status --branch feat/keepsnappy-integration       # is my PR ok? one answer: blocked / nothing blocks / ok, per journey × phone, ids of the worst findings, links
 keepsnappy findings --main --journey live-ui --phone "iPhone 15"
 keepsnappy findings --state all --json                    # also the resolved and not judged ones, as the API's JSON
 keepsnappy findings --state all --offset 200              # the next page (at most 200 per answer)
 keepsnappy finding f_0123456789abcdef                     # one finding with its evidence
 keepsnappy finding f_0123456789abcdef --prompt | pbcopy   # only the hand-off for a coding agent, ending with its id and page
 keepsnappy compare <runA> <runB>                          # two runs (ids or external ids), window by window, no statistics
-keepsnappy history live-ui "Tap: live chat send"          # one window on main, run by run (id or name)
+keepsnappy history live-ui press:live.chat.send           # one window on main, run by run (exact place id)
 keepsnappy commits a1b2c3d c3d4e5f [--branch main]        # the measured commits between two points
+keepsnappy places --journey live-ui --phone "iPhone 15"   # every place of the newest main session from its stored statistics, no verdict
+keepsnappy places --run-set <id> --measure commit_max_ms --sort p90 --limit 10
 keepsnappy layers                                         # which layer answers which question, and its certificate
+keepsnappy findings --branch feat/x --short               # the short form: what decides, no evidence detail (also status, finding, history, places, main, trend)
+keepsnappy trend live-ui Tap: live chat send --phone "iPhone 15"   # the words after the journey are one window name; more windows with repeated --window
 ```
 
-Flags: `--api URL` (or `KEEPSNAPPY_API`, default the hosted API), `--key-env NAME` (default `KEEPSNAPPY_KEY`), `--json`.
+Flags: `--api URL` (or `KEEPSNAPPY_API`, default the hosted API), `--key-env NAME` (default `KEEPSNAPPY_KEY`), `--json`, `--short`.
+`--short` prints the same text with the evidence detail left out (the MCP tools' `form: "short"`); its last line says what was left out, and the MCP tool descriptions list it per answer. `--json` is the same with or without it.
 A finding's id is stable: the same window, measure, journey and phone model keep the id across commits and PRs, so
 `keepsnappy finding <id>` after a fix tells whether it is resolved. `--state` (default `present`) filters on the state on
 the asked branch: `present` (in the newest run set), `resolved` (the newest run set judged the measure: No change, or the
 other way), `not-judged` (the newest run set did not judge it: not measured, unstable, not enough data; it may still be
 there). A list starts with whether and when the branch was measured ("No KeepSnappy measurement on branch X", or the
 newest measured commit, its word and runs), so an empty list on an unmeasured branch does not read as clean. `commits`
-lists each measured commit once, with how many sessions measured it. Words come from the one word table (Worse / Warning / Better …), "Worse (not blocking)" when the
+lists each measured commit once, with how many sessions measured it. `places` lists the places of one session (a run set, or the newest closed one of a journey on a phone and branch) with each measure's median, spread and the components with the most own time, ranked by `--measure` and `--sort`; a session without stored statistics says `not computed`, never zero. Words come from the one word table (Worse / Warning / Better …), "Worse (not blocking)" when the
 branch was measured differently from main.
 
 ## Output layout
@@ -257,3 +265,24 @@ Memory slopes (Theil-Sen over the cycle index, 3+ cycles of `--mem-window`, defa
 verdicts, profile-analysis, mcp), so both work from a clean checkout.
 
 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.
+
+### Source maps from an EAS build
+
+In an `eas-build-on-success` hook, run:
+
+```sh
+npx @keepsnappy/agent sourcemaps upload --eas
+```
+
+`--eas` runs only when `EAS_BUILD_PROFILE=e2e`. It uses `EAS_BUILD_GIT_COMMIT_HASH` as the build commit and `EAS_BUILD_PLATFORM` to select the map relative to the working directory:
+
+| Platform | Map | Kind |
+| --- | --- | --- |
+| `ios` | `main.jsbundle.packager.map` | `packager` |
+| `android` | `android/app/build/generated/sourcemaps/react/release/index.android.bundle.map` | `hermes` |
+
+The iOS packager map preserves the positions used by CPU profiles; Android profiles use the composed Hermes map. The upload flavour defaults to `e2e`.
+
+Set `KEEPSNAPPY_KEY` or `KEEPSNAPPY_CI_KEY` and `KEEPSNAPPY_API` or `EXPO_PUBLIC_KEEPSNAPPY_INGEST_URL`. The usual key/API names take precedence over the EAS hook names. Explicit `--key-env`, `--api`/`--ingest-url`, `--build`, `--platform`, `--kind`, `--flavour` and map files override these defaults. An explicit `--key-env` uses only that variable.
+
+A missing key, API URL, commit or map, an unsupported platform, or a profile other than `e2e` produces one skip line and exits 0. There is no default API URL in EAS mode. Upload, map parsing and argument failures also exit 0 with a generic failure line so the application build stays successful and error details cannot expose credentials. Ordinary `sourcemaps upload` keeps its existing validation and failure behavior. Source text (`sourcesContent`) is stripped before upload in both modes.

package/dist/appium-driver.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // packages/appium-driver/src/load.ts
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // packages/appium-driver/src/run.ts
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
 import { parseArgs } from "node:util";
 
 // packages/appium-driver/src/browserstack.ts
@@ -314,6 +314,7 @@ class Driver {
   now;
   sleep;
   sessionId = null;
+  deviceUnit;
   context = {};
   viewport = null;
   rects = new Map;
@@ -348,9 +349,14 @@ class Driver {
     }
     return value;
   }
+  async attribute(el, name) {
+    const value = await this.cmd("GET", `/element/${el}/attribute/${name}`);
+    return value === this.platform.absentAttributeText ? null : value;
+  }
   async start(capabilities) {
     const value = await this.cmd("POST", "/session", { capabilities: { alwaysMatch: capabilities } });
     this.sessionId = value.sessionId;
+    this.deviceUnit = [value.capabilities?.udid, value.capabilities?.deviceUDID].find((unit) => typeof unit === "string" && unit.length > 0);
     return value;
   }
   execute(script, arg) {
@@ -427,7 +433,7 @@ class Driver {
           break;
         let resourceId;
         try {
-          resourceId = String(await this.cmd("GET", `/element/${el}/attribute/resource-id`));
+          resourceId = String(await this.attribute(el, "resource-id") ?? "");
         } catch (e) {
           if (e instanceof WdError && e.wdError === "stale element reference")
             continue;
@@ -530,6 +536,7 @@ var IOS = {
     "appium:newCommandTimeout": NEW_COMMAND_TIMEOUT_S,
     "appium:waitForIdleTimeout": NO_WAIT_MS
   }),
+  absentAttributeText: null,
   settings: { animationCoolOffTimeout: NO_WAIT_MS, waitForIdleTimeout: NO_WAIT_MS, shouldUseCompactResponses: true },
   locators: (sel) => [locator(sel)],
   keyboardShown: async (driver) => Boolean(await driver.findShown(id("Return"))),
@@ -548,7 +555,7 @@ async function iosCommand(driver, link, cmd, n, state, waitMs) {
   for (;; ) {
     const el = await driver.find("-ios predicate string", want);
     if (el)
-      return driver.cmd("GET", `/element/${el}/attribute/label`).then(String).catch(() => {
+      return driver.attribute(el, "label").then(String).catch(() => {
         driver.log.push({ ...driver.context, cmd: `${cmd}-ack-label`, t: driver.now(), ms: 0, status: 1 });
         return `${cmd}:${n} ok`;
       });
@@ -568,6 +575,7 @@ var ANDROID = {
     "appium:autoGrantPermissions": true,
     "appium:newCommandTimeout": NEW_COMMAND_TIMEOUT_S
   }),
+  absentAttributeText: "null",
   settings: { waitForIdleTimeout: NO_WAIT_MS, actionAcknowledgmentTimeout: NO_WAIT_MS, waitForSelectorTimeout: NO_WAIT_MS, enableMultiWindows: true, ignoreUnimportantViews: true },
   locators: androidLocators,
   appArg: (appId) => ({ appId }),
@@ -635,7 +643,7 @@ var HUB = "https://hub-cloud.browserstack.com/wd/hub";
 var BS_API = "https://api-cloud.browserstack.com/app-automate";
 var basicAuth = (user, key) => `Basic ${Buffer.from(`${user}:${key}`).toString("base64")}`;
 async function resolveApp(app, customId, auth, fetchImpl, platform = IOS) {
-  if (app.startsWith("bs://"))
+  if (app.startsWith("bs://") || app.startsWith("custom_id:"))
     return app;
   const headers = { Authorization: auth };
   if (customId) {
@@ -679,6 +687,29 @@ async function sessionDetail(sessionId, auth, fetchImpl) {
   return (await res.json()).automation_session ?? {};
 }
 
+// packages/appium-driver/src/version.ts
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var DRIVER_NAME = "appium";
+function driverVersion() {
+  const built = "0.1.0-alpha.16";
+  if (built)
+    return built;
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0;i < 3; i++, dir = dirname(dir)) {
+    const file = join(dir, "package.json");
+    if (!existsSync(file))
+      continue;
+    try {
+      const pkg = JSON.parse(readFileSync(file, "utf8"));
+      if (pkg.name === "@keepsnappy/appium-driver" && pkg.version)
+        return pkg.version;
+    } catch {}
+  }
+  return null;
+}
+
 // packages/appium-driver/src/session.ts
 var MARKERS_PER_REQUEST = 500;
 var MARKER_TRIES = 3;
@@ -734,6 +765,9 @@ async function sendMarkers(fetchImpl, api, markers, opts = {}) {
   }
   const base = api.replace(/\/+$/, "");
   const url = `${base}/v1/markers`;
+  const version = (opts.driverVersion ?? driverVersion)();
+  const reported = opts.reported ?? new Set;
+  const driverField = { driver: { name: DRIVER_NAME, ...version ? { version } : {}, ...opts.deviceUnit ? { unit: opts.deviceUnit.slice(0, 200) } : {} } };
   let sent = 0;
   for (const [token, list] of byToken) {
     const trips = [];
@@ -742,7 +776,9 @@ async function sendMarkers(fetchImpl, api, markers, opts = {}) {
       return carried.length ? { ...body, clock: carried } : body;
     };
     const send = async (body) => {
-      const answer = await postWithRetry(fetchImpl, url, token, withClock(body), sleep, now);
+      const answer = await postWithRetry(fetchImpl, url, token, { ...withClock(body), ...reported.has(token) ? {} : driverField }, sleep, now);
+      if (answer && answer.status < 300)
+        reported.add(token);
       if (answer?.trip)
         trips.push(answer.trip);
       return answer;
@@ -771,6 +807,14 @@ async function sendMarkers(fetchImpl, api, markers, opts = {}) {
     if (trips.length)
       await post(fetchImpl, `${base}/v1/clock`, token, { source: "host", samples: trips.splice(0) }, now);
   }
+  for (const token of opts.tokens ?? []) {
+    if (byToken.has(token) || reported.has(token) || !token || !api)
+      continue;
+    const answer = await postWithRetry(fetchImpl, `${base}/v1/clock`, token, { source: "host", samples: [], ...driverField }, sleep, now);
+    reported.add(token);
+    if (!answer || answer.status >= 300)
+      opts.note?.(`driver report for a run not accepted (${answer?.status ?? "no answer"}); not tried again`);
+  }
   return sent;
 }
 var SDK_FLUSH_WORST_CASE_MS = 315000;
@@ -778,6 +822,7 @@ var FLUSH_MARGIN_MS = 30000;
 var FLUSH_WAIT_MS = SDK_FLUSH_WORST_CASE_MS + FLUSH_MARGIN_MS;
 var FLUSH_POLL_MS = 500;
 var FLUSH_RESEND_MS = 90000;
+var ACTIVATION_SETTLE_MS = 2000;
 var FLUSH_NOT_ACKNOWLEDGED = "not acknowledged (re-sent once)";
 var FLUSH_UNREADABLE = "not acknowledged (unreadable answer)";
 var FLUSH_STATUSES = new Set(["ok", "error", "off"]);
@@ -1179,17 +1224,23 @@ class Session {
   }
   async beginRun({ token, args = "", home }) {
     this.token = token;
+    if (token)
+      this.opened.add(token);
     this.pendingReady = null;
     await this.relaunch();
     await this.waitVisible(home, 30000);
-    return this.openLink(activationLink(this.scheme, token, args));
+    const alert = await this.openLink(activationLink(this.scheme, token, args));
+    await this.driver.sleep(ACTIVATION_SETTLE_MS);
+    return alert;
   }
+  opened = new Set;
+  told = new Set;
   lastFlush = null;
   flushSeq = 0;
   async endRun() {
     if (this.markers.some((m) => m.phase === "start"))
       await this.memRead(await this.gc(true));
-    await sendMarkers(this.fetch, this.api, this.markers, { sleep: (ms) => this.driver.sleep(ms), now: () => this.now() });
+    await sendMarkers(this.fetch, this.api, this.markers, { sleep: (ms) => this.driver.sleep(ms), now: () => this.now(), deviceUnit: this.driver.deviceUnit, tokens: [...this.opened], reported: this.told, note: (line) => this.driver.log.push({ ...this.driver.context, cmd: "driver-report", t: this.now(), ms: 0, status: 1, answer: line }) });
     const evidence = { linkAt: this.now(), resentAt: null, ackAt: null, gaveUpAt: null };
     this.lastFlush = evidence;
     const acks = new Set;
@@ -1226,8 +1277,8 @@ class Session {
       if (!el && flush.fallback && poll % FLUSH_FALLBACK_EVERY === 0)
         el = await this.findFallback(flush.fallback);
       if (el) {
-        const label = await this.driver.cmd("GET", `/element/${el}/attribute/${flush.statusAttribute}`).catch(() => null);
-        const raw = await this.driver.cmd("GET", `/element/${el}/attribute/${flush.detailAttribute}`).then((value) => ({ value }), () => null);
+        const label = await this.driver.attribute(el, flush.statusAttribute).catch(() => null);
+        const raw = await this.driver.attribute(el, flush.detailAttribute).then((value) => ({ value }), () => null);
         const detail = typeof raw?.value === "string" ? raw.value : null;
         const echoed = detail === null ? null : ACK_ECHO.exec(detail);
         if (raw === null) {
@@ -1322,8 +1373,8 @@ function writeAtomic(file, text) {
   renameSync(tmp, file);
 }
 async function captureFailure(driver, out) {
-  const source = driver.cmd("GET", "/source").then((s) => void (typeof s === "string" && writeFileSync(join(out, "failure-source.xml"), s)), () => null);
-  const screen = driver.cmd("GET", "/screenshot").then((png) => void (typeof png === "string" && writeFileSync(join(out, "failure-screen.png"), Buffer.from(png, "base64"))), () => null);
+  const source = driver.cmd("GET", "/source").then((s) => void (typeof s === "string" && writeFileSync(join2(out, "failure-source.xml"), s)), () => null);
+  const screen = driver.cmd("GET", "/screenshot").then((png) => void (typeof png === "string" && writeFileSync(join2(out, "failure-screen.png"), Buffer.from(png, "base64"))), () => null);
   await Promise.all([source, screen]);
 }
 async function runDriver(argv, module, deps = realRunDeps()) {
@@ -1349,7 +1400,7 @@ async function runDriver(argv, module, deps = realRunDeps()) {
   const out = String(a.out);
   const auth = basicAuth(user, key);
   mkdirSync(out, { recursive: true });
-  const { api, tokens } = parseTokensJs(readFileSync(String(a["tokens-js"]), "utf8"));
+  const { api, tokens } = parseTokensJs(readFileSync2(String(a["tokens-js"]), "utf8"));
   const log = [];
   const driver = new Driver({ hub: HUB, log, headers: { Authorization: auth }, bundleId: module.app.bundleId, platform, fetch: deps.fetch, now: deps.now, sleep: deps.sleep });
   const t = new Session({ driver, scheme: module.app.scheme, fetch: deps.fetch, api, actionGc: a["action-gc"] === "on", endGc: a["end-gc"] === "on" });
@@ -1369,7 +1420,7 @@ async function runDriver(argv, module, deps = realRunDeps()) {
   let flushOff = [];
   const iterations = [];
   let terminating = false;
-  const logFile = join(out, "driver-log.json");
+  const logFile = join2(out, "driver-log.json");
   const persist = () => {
     const last = t.stepLog.at(-1);
     const body = {
@@ -1410,7 +1461,7 @@ async function runDriver(argv, module, deps = realRunDeps()) {
     }
   };
   let dashboard = null;
-  const writeBuild = (failure) => writeAtomic(join(out, `browserstack.${String(a.platform)}.json`), `${JSON.stringify({
+  const writeBuild = (failure) => writeAtomic(join2(out, `browserstack.${String(a.platform)}.json`), `${JSON.stringify({
     driver: "appium",
     status: failure === null ? "passed" : "failed",
     buildId,
@@ -1578,7 +1629,7 @@ async function runIterations(t, module, ctx, iterations, progress) {
 
 // packages/appium-driver/src/load.ts
 async function loadJourneyModule(path, cwd = process.cwd()) {
-  const file = isAbsolute(path) ? path : resolve(cwd, path);
+  const file = isAbsolute(path) ? path : resolve2(cwd, path);
   const mod = await import(pathToFileURL(file).href);
   const m = mod.default ?? mod;
   if (!m.app?.bundleId || !m.app.scheme)