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

package/README.md

@@ -70,7 +70,7 @@ Annotated example: `examples/keepsnappy.yml`. Every setting:
 
 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, 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`) fails the job (exit `3`) only when the verdict computed on that run set is Worse and blocking. Closing a run set never computes its verdict (decision 0031: the operator computes verdicts on demand), so with no computed verdict `--fail-on-worse` checks nothing: the CLI prints `Verdict not computed yet (computed on demand): --fail-on-worse checked nothing` and exits `0`. The CLI exits `2` for a configuration problem (bad or missing `keepsnappy.yml`, unknown or misspelt 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, an API URL that does not answer as the KeepSnappy API, `--upload` that sent no run: "Blocked"; 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)
@@ -137,7 +137,7 @@ runner. It writes:
    run with data. A measured iteration sends nothing until its end-of-iteration flush, so a run with data completed and
    is never blamed; a Maestro failure stops the session, so later iterations have no data;
 3. finishes every run not yet finished (a run without a single batch is reported as "no data", never judged), closes the
-   set (`--wait`: verdicts inline; else on read) and prints the iterations and the same plain-words verdict as
+   set (`--wait`: verdicts inline; else on read). It then prints the iterations and the same plain-words verdict as
    `keepsnappy run --upload --wait`, plus `$GITHUB_STEP_SUMMARY` and `<out>/keepsnappy-result.json` (`--out`, default the
    state's directory);
 4. puts the empty stub back into the tokens file, also when a step above failed. The example workflow also deletes the
@@ -145,13 +145,14 @@ runner. It writes:
 
 Running it again is safe: finished runs are left alone, the set is not reprocessed, the same result is printed. A batch
 that arrives after a run was finished is added by the server and the run re-processed at once. Exit codes: `0` for any
-result, `3` with `--fail-on-worse` on "More work", `2` for configuration, `1` when the API fails or nothing could be
+result, `3` with `--fail-on-worse` when the verdict computed on that run set is Worse and blocking (with no computed
+verdict it checks nothing and says so, exit `0`), `2` for configuration, `1` when the API fails or nothing could be
 judged ("Blocked": no iteration sent any data).
 
-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 (`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.
+Slack: set `KEEPSNAPPY_SLACK_WEBHOOK` (an incoming-webhook URL kept as a CI secret) and `farm close` posts a measurement that sent
+no data ("No result") at once. Results are posted after the verdict is computed, by the operator's recompute job (decision 0031), in
+two lines and one button (docs/mockups/2026-10-26-slack, present `resultSlackPayload`). `$GITHUB_STEP_SUMMARY` gets the same two
+lines: "No result", the computed result, or "Not judged yet · <branch> / Waiting for the judgement" with the run set's page. A Slack failure is printed and never changes the exit code.
 
 Declared steps on the farm: `maestro/keepsnappy/step.yaml` / `step.js` / `send-markers.js` (copy them into the suite).
 With a token set, `step.js` only records the marker; `send-markers.js`, run in `end-run.yaml` after each iteration,

package/dist/appium-driver.js

@@ -303,6 +303,10 @@ class WdError extends Error {
     this.wdError = wdError;
   }
 }
+var IOS_BOTTOM_INSET_PT = 34;
+var GESTURE_ZONE_MARGIN_PT = 16;
+var ANDROID_NAV_BAR_FALLBACK_DP = 48;
+var GESTURE_ZONE_MARGIN_DP = 16;
 
 class Driver {
   bundleId;
@@ -317,6 +321,8 @@ class Driver {
   deviceUnit;
   context = {};
   viewport = null;
+  pxPerDp = null;
+  bottomLimit = null;
   rects = new Map;
   constructor(o) {
     this.bundleId = o.bundleId;
@@ -381,6 +387,29 @@ class Driver {
     this.viewport ??= await this.cmd("GET", "/window/rect");
     return this.viewport;
   }
+  async density() {
+    if (this.pxPerDp === null) {
+      const dpi = Number(await this.execute("mobile: getDisplayDensity"));
+      if (!(dpi > 0))
+        throw new Error(`mobile: getDisplayDensity answered ${dpi}, not a density`);
+      this.pxPerDp = dpi / 160;
+    }
+    return this.pxPerDp;
+  }
+  async safeBottomY() {
+    if (this.bottomLimit === null) {
+      const { height } = await this.screen();
+      if (this.platform.name === "ios") {
+        this.bottomLimit = height - IOS_BOTTOM_INSET_PT - GESTURE_ZONE_MARGIN_PT;
+      } else {
+        const dp = await this.density();
+        const bar = await this.execute("mobile: getSystemBars").then((b) => Number(b?.navigationBar?.height), () => NaN);
+        const inset = bar > 0 ? bar : ANDROID_NAV_BAR_FALLBACK_DP * dp;
+        this.bottomLimit = Math.round(height - inset - GESTURE_ZONE_MARGIN_DP * dp);
+      }
+    }
+    return this.bottomLimit;
+  }
   async onScreen(el, full = false) {
     let r;
     try {
@@ -479,6 +508,7 @@ class Driver {
     await this.cmd("DELETE", "/actions").catch(() => null);
   }
   async drag(from, to, durationMs) {
+    to = { x: to.x, y: Math.min(to.y, await this.safeBottomY()) };
     await this.cmd("POST", "/actions", {
       actions: [
         {
@@ -676,7 +706,10 @@ function sessionCaps(i) {
       sessionName: i.sessionName,
       ...tunnel,
       idleTimeout: 300,
-      appiumVersion: i.appiumVersion
+      appiumVersion: i.appiumVersion,
+      video: i.capture ?? false,
+      deviceLogs: i.capture ?? false,
+      networkLogs: false
     }
   };
 }
@@ -693,7 +726,7 @@ 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";
+  const built = "0.1.0-alpha.18";
   if (built)
     return built;
   let dir = dirname(fileURLToPath(import.meta.url));
@@ -767,7 +800,7 @@ async function sendMarkers(fetchImpl, api, markers, opts = {}) {
   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) } : {} } };
+  const driverField = { driver: { name: DRIVER_NAME, ...version ? { version } : {}, ...opts.deviceUnit ? { unit: opts.deviceUnit.slice(0, 200) } : {}, ...opts.capture ? { capture: opts.capture } : {} } };
   let sent = 0;
   for (const [token, list] of byToken) {
     const trips = [];
@@ -824,6 +857,26 @@ 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 flushLoss = (detail) => {
+  if (!detail)
+    return "no detail";
+  const count = (re) => Number(re.exec(detail)?.[1] ?? 0);
+  const lost = [];
+  const rejected = count(/^rejected \d+: (\d+) batch/);
+  if (!detail.startsWith("batches=") && !rejected && !detail.startsWith("lines of the run dropped before sending")) {
+    lost.push(`lines not sent (${detail.replace(/ (?:dropped|artifacts)=.*$/, "")})`);
+  }
+  if (count(/ dropped=(\d+)/))
+    lost.push(`lines dropped=${count(/ dropped=(\d+)/)}`);
+  if (rejected)
+    lost.push(`line batches rejected=${rejected}`);
+  const files = /failed=(\d+) pending=(\d+) local=(\d+) rejected=(\d+)/.exec(detail);
+  if (files)
+    lost.push(`profile files not uploaded=${files.slice(1).reduce((n, x) => n + Number(x), 0)}`);
+  if (count(/ lost stream=(\d+)/))
+    lost.push(`stream segments lost=${count(/ lost stream=(\d+)/)}`);
+  return lost.length ? lost.join(", ") : detail;
+};
 var FLUSH_UNREADABLE = "not acknowledged (unreadable answer)";
 var FLUSH_STATUSES = new Set(["ok", "error", "off"]);
 var UNREADABLE_POLLS = 3;
@@ -849,9 +902,11 @@ class Session {
   readyWaits = [];
   actionGc;
   endGc;
+  capture;
   gcN = 0;
   stepDepth = 0;
   stepLog = [];
+  defects = { gestureRetry: 0, items: [] };
   onStepChange = null;
   refinds = 0;
   get staleRefinds() {
@@ -864,6 +919,7 @@ class Session {
     this.api = o.api ?? "";
     this.actionGc = o.actionGc ? "step" : "off";
     this.endGc = o.endGc ?? END_GC_DEFAULT;
+    this.capture = o.capture;
   }
   async gc(atEnd = false) {
     if (this.actionGc !== "step" && !(atEnd && this.endGc && this.actionGc === "off"))
@@ -1240,7 +1296,7 @@ class Session {
   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(), 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 }) });
+    await sendMarkers(this.fetch, this.api, this.markers, { sleep: (ms) => this.driver.sleep(ms), now: () => this.now(), deviceUnit: this.driver.deviceUnit, capture: this.capture, 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;
@@ -1357,7 +1413,8 @@ var DRIVER_OPTIONS = {
   out: { type: "string", default: "farm-run" },
   platform: { type: "string", default: "ios" },
   "action-gc": { type: "string", default: "off" },
-  "end-gc": { type: "string", default: END_GC_DEFAULT ? "on" : "off" }
+  "end-gc": { type: "string", default: END_GC_DEFAULT ? "on" : "off" },
+  capture: { type: "string", default: "off" }
 };
 function parseDriverArgs(argv, module) {
   const values = parseArgs({ args: [...argv], options: { ...module.options ?? {}, ...DRIVER_OPTIONS } }).values;
@@ -1397,13 +1454,16 @@ async function runDriver(argv, module, deps = realRunDeps()) {
     throw new Error("--action-gc must be on or off");
   if (a["end-gc"] !== "on" && a["end-gc"] !== "off")
     throw new Error("--end-gc must be on or off");
+  if (a.capture !== "on" && a.capture !== "off")
+    throw new Error("--capture must be on or off");
+  const capture = a.capture === "on";
   const out = String(a.out);
   const auth = basicAuth(user, key);
   mkdirSync(out, { recursive: true });
   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" });
+  const t = new Session({ driver, scheme: module.app.scheme, fetch: deps.fetch, api, actionGc: a["action-gc"] === "on", endGc: a["end-gc"] === "on", capture: capture ? "on" : "off" });
   const sessionName = module.sessionName ?? "keepsnappy (appium)";
   const device = String(a.device);
   const ctx = { fetch: deps.fetch, tokens, journeys, repeat, args: a };
@@ -1427,6 +1487,8 @@ async function runDriver(argv, module, deps = realRunDeps()) {
       driver: "appium",
       status,
       device,
+      unit: driver.deviceUnit ?? null,
+      capture,
       appUrl,
       session: driver.sessionId,
       buildId,
@@ -1444,6 +1506,7 @@ async function runDriver(argv, module, deps = realRunDeps()) {
       flushError,
       flushOff,
       finalFlush,
+      defects: t.defects,
       steps: t.stepLog,
       iterations,
       commands: log
@@ -1531,13 +1594,14 @@ async function runDriver(argv, module, deps = realRunDeps()) {
   try {
     appUrl = await resolveApp(String(a.app), String(a["app-custom-id"] ?? ""), auth, deps.fetch, platform);
     deps.print(`app: ${appUrl}`);
-    const caps = sessionCaps({ appUrl, device, buildName: String(a["build-name"]), sessionName, appiumVersion: String(a["appium-version"]), platform, localIdentifier: a["local-identifier"] });
+    const caps = sessionCaps({ appUrl, device, buildName: String(a["build-name"]), sessionName, appiumVersion: String(a["appium-version"]), platform, localIdentifier: a["local-identifier"], capture });
     startedAt = deps.now();
     try {
       await driver.start(caps);
       deps.print(`session ${driver.sessionId}`);
       progress();
       await driver.cmd("POST", "/appium/settings", { settings: platform.settings }).catch(() => null);
+      await driver.safeBottomY().catch(() => null);
       await module.setup?.(t, ctx);
       await runIterations(t, module, ctx, iterations, progress);
     } catch (e) {
@@ -1569,8 +1633,13 @@ async function runDriver(argv, module, deps = realRunDeps()) {
     flushOff = flushedAs(FLUSH_OFF, true);
     if (flushNotAcknowledged.length)
       deps.error(`::error::flush not acknowledged (no answer after the re-send, an unreadable answer, or a failed end-run): ${flushNotAcknowledged.join(", ")}`);
-    if (flushError.length)
-      deps.error(`::error::flush answered error (data not uploaded): ${flushError.join(", ")}`);
+    if (flushError.length) {
+      const losses = [
+        ...iterations.filter((r) => r.flushed === FLUSH_ERROR).map((r) => `${r.journey} #${r.iteration} (${flushLoss(r.flush?.detail)})`),
+        ...finalFlush?.flushed === FLUSH_ERROR ? [`final flush (${flushLoss(finalFlush.flush?.detail)})`] : []
+      ];
+      deps.error(`::error::flush answered error, data lost: ${losses.join(", ")}`);
+    }
     if (flushOff.length)
       deps.error(`::error::flush answered off in a run with a token (upload not configured, nothing uploaded): ${flushOff.join(", ")}`);
     endedAt = deps.now();