@tonys-software/mimic 0.1.0-stg.3.1 → 0.1.1-stg.5.1

package/README.md

@@ -20,8 +20,12 @@ mimic list -f scenarios
 mimic run
 mimic run --group smoke
 mimic run --cloud
+mimic run --cloud --tunnel 5173
 ```
 
+With `--tunnel` the cloud workers open `localhost:5173` on your machine through a tunnel, so they can test an app
+that only runs locally. Scenarios must navigate to `localhost`, not `127.0.0.1`; Safari workers can't run them.
+
 `mimic --help` lists every command, and `mimic <command> --help` shows its options.
 
 ## Update

package/dist/cli.js

@@ -45,19 +45,23 @@ function stepWithDefaults(step, baseUrl, where) {
     case "Fill":
       return { ...step, locator: requiredLocator(step.locator, where), value: step.value ?? "", invalid: invalidValues(step.invalid, where) };
     case "Assertion":
-      return assertionWithDefaults(step);
+      return assertionWithDefaults(step, where);
     default:
       throw new Error(`${where}: unknown step type "${step.type}"`);
   }
 }
-function assertionWithDefaults(step) {
-  return { ...step, locator: step.locator && withDefaults(step.locator) };
+function checkWithDefaults(check) {
+  return { ...check, locator: check.locator && withDefaults(check.locator) };
+}
+function assertionWithDefaults(step, where) {
+  if (!Array.isArray(step.checks) || step.checks.length === 0) throw new Error(`${where}: an Assertion step needs a non-empty "checks"`);
+  return { ...step, checks: step.checks.map(checkWithDefaults) };
 }
 function expectSteps(expect, where) {
   if (!Array.isArray(expect) || expect.some((step) => typeof step !== "object" || step === null || (step.type ?? "Assertion") !== "Assertion")) {
     throw new Error(`${where}: "expect" must be a list of Assertion steps`);
   }
-  return expect.map((step) => assertionWithDefaults({ ...step, type: "Assertion" }));
+  return expect.map((step) => assertionWithDefaults({ ...step, type: "Assertion" }, where));
 }
 function invalidValues(invalid, where) {
   if (invalid === void 0) return [];
@@ -221,6 +225,7 @@ import path2 from "node:path";
 // src/shared/config.ts
 var API_URL = "https://app.stg.mimicus.dev";
 var WORKOS_CLIENT_ID = "client_01M4VM6E40X8NEXB778AQTE9KC";
+var VERSION = "0.1.1-stg.5.1";
 
 // src/shared/auth.ts
 var WORKOS_URL = "https://api.workos.com";
@@ -251,6 +256,10 @@ async function saveSession(session) {
   await mkdir(path2.dirname(file), { recursive: true });
   await writeFile(file, JSON.stringify(session), { mode: 384 });
 }
+async function signedInEmail() {
+  const session = await loadSession();
+  return session ? session.email : void 0;
+}
 function deleteSession() {
   return rm(sessionFile(), { force: true });
 }
@@ -393,20 +402,23 @@ function findGroups(slugs, groups) {
   }
   return slugs.map((slug) => bySlug.get(slug));
 }
-function parseGroups(tokens) {
-  const slugs = [];
-  let collecting = false;
+function parseLists(tokens, names) {
+  const lists = new Map(names.map((name) => [name, []]));
+  let collecting;
   for (const token of tokens) {
     if (token.kind === "option") {
-      collecting = token.name === "group";
-      if (collecting && token.value !== void 0) slugs.push(token.value);
+      collecting = lists.get(token.name);
+      if (collecting && token.value !== void 0) collecting.push(token.value);
     } else if (token.kind === "positional") {
       if (!collecting) throw new Error(`Unexpected argument "${token.value}"`);
-      slugs.push(token.value);
+      collecting.push(token.value);
     } else {
-      collecting = false;
+      collecting = void 0;
     }
   }
+  return lists;
+}
+function parseGroups(tokens, slugs = parseLists(tokens, ["group"]).get("group")) {
   const normalized = slugs.map((slug) => slug.trim().toLowerCase());
   if (normalized.some((slug) => !slug)) {
     throw new Error("--group needs group slugs");
@@ -553,6 +565,7 @@ Options:
 
 // src/commands/run.ts
 import { spawn, spawnSync } from "node:child_process";
+import net2 from "node:net";
 import os2 from "node:os";
 import { parseArgs as parseArgs5 } from "node:util";
 
@@ -627,6 +640,15 @@ var ListScenariosEndpoint_default = (handler) => () => send(handler, "GET", `api
 // ../jsclient/src/gen/client/Endpoints/Scenarios/UpdateScenarioEndpoint.ts
 var UpdateScenarioEndpoint_default = (handler) => (id, payload) => send(handler, "PUT", `api/scenario/${encodeURIComponent(id)}`, payload);
 
+// ../jsclient/src/gen/client/Endpoints/Screenshots/AcceptScreenshotEndpoint.ts
+var AcceptScreenshotEndpoint_default = (handler) => (runId, stepId, checkIndex) => send(handler, "POST", `api/run/${encodeURIComponent(runId)}/screenshot/${encodeURIComponent(stepId)}/${encodeURIComponent(checkIndex)}/accept`);
+
+// ../jsclient/src/gen/client/Endpoints/Screenshots/GetScreenshotEndpoint.ts
+var GetScreenshotEndpoint_default = (handler) => (id) => send(handler, "GET", `api/screenshot/${encodeURIComponent(id)}`);
+
+// ../jsclient/src/gen/client/Endpoints/Screenshots/UploadScreenshotEndpoint.ts
+var UploadScreenshotEndpoint_default = (handler) => (payload) => send(handler, "POST", `api/screenshot`, payload);
+
 // ../jsclient/src/gen/client/Endpoints/Users/InviteUserEndpoint.ts
 var InviteUserEndpoint_default = (handler) => (payload) => send(handler, "POST", `api/invitation`, payload);
 
@@ -660,6 +682,9 @@ function createClient(handler) {
     getScenario: GetScenarioEndpoint_default(handler),
     listScenarios: ListScenariosEndpoint_default(handler),
     updateScenario: UpdateScenarioEndpoint_default(handler),
+    acceptScreenshot: AcceptScreenshotEndpoint_default(handler),
+    getScreenshot: GetScreenshotEndpoint_default(handler),
+    uploadScreenshot: UploadScreenshotEndpoint_default(handler),
     inviteUser: InviteUserEndpoint_default(handler),
     listInvitations: ListInvitationsEndpoint_default(handler),
     listMembers: ListMembersEndpoint_default(handler),
@@ -856,7 +881,11 @@ async function playFill(page, step, element) {
   const target = await typeInto(page, step, element);
   if (!await isConnected(target)) await typeInto(page, step, target);
 }
+function rejectScreenshot(step) {
+  if (step.checks.some((check) => check.type === "Screenshot")) throw new Error("Screenshot assertions are only supported by the worker, not by the CLI");
+}
 async function playAssertion(page, step) {
+  rejectScreenshot(step);
   const deadline = Date.now() + LOCATE_TIMEOUT_MS;
   for (; ; ) {
     let problem;
@@ -865,7 +894,7 @@ async function playAssertion(page, step) {
       problem = await page.evaluate((s) => window.__scenarioRunner.assertionProblem(s), step);
     } catch (e) {
       if (!isNavigationError(e)) throw e;
-      problem = `${step.assertionType} assertion failed: page navigated while checking`;
+      problem = `${step.checks.map((check) => check.type).join(", ")} assertion failed: page navigated while checking`;
     }
     if (!problem) return;
     if (Date.now() >= deadline) throw new Error(problem);
@@ -873,6 +902,7 @@ async function playAssertion(page, step) {
   }
 }
 async function playExpect(page, expect) {
+  expect.forEach(rejectScreenshot);
   const pending = expect.map((step, i) => ({ index: i + 1, step, problem: void 0 }));
   const deadline = Date.now() + LOCATE_TIMEOUT_MS;
   for (; ; ) {
@@ -888,7 +918,7 @@ async function playExpect(page, expect) {
     }
     if (pending.length === 0) return;
     if (Date.now() >= deadline) {
-      throw new Error(pending.map((a, i) => `expect ${a.index} (${a.step.assertionType}): ${a.problem}${i === 0 ? ` (on ${page.url()})` : ""}`).join("\n"));
+      throw new Error(pending.map((a, i) => `expect ${a.index} (${a.step.checks.map((check) => check.type).join(", ")}): ${a.problem}${i === 0 ? ` (on ${page.url()})` : ""}`).join("\n"));
     }
     await page.waitForTimeout(POLL_INTERVAL_MS);
   }
@@ -994,6 +1024,199 @@ var Runner = class _Runner {
   }
 };
 
+// src/shared/tunnel.ts
+import http2 from "node:http";
+import net from "node:net";
+import WebSocket, { createWebSocketStream } from "ws";
+var STREAM_ID = /^[0-9a-f]{1,64}$/;
+var PROXY_HEADERS = /* @__PURE__ */ new Set(["proxy-connection", "proxy-authorization"]);
+function allowedTarget(ports, host, port) {
+  return host.toLowerCase() === "localhost" && ports.has(port) ? port : void 0;
+}
+function absoluteTarget(ports, rawUrl) {
+  if (!rawUrl || !URL.canParse(rawUrl)) return void 0;
+  const url = new URL(rawUrl);
+  if (url.protocol !== "http:" && url.protocol !== "ws:") return void 0;
+  const port = allowedTarget(ports, url.hostname, Number(url.port || 80));
+  return port === void 0 ? void 0 : { port, path: url.pathname + url.search };
+}
+function connectTarget(ports, authority) {
+  const match = authority?.match(/^([^:]+):(\d+)$/);
+  return match ? allowedTarget(ports, match[1], Number(match[2])) : void 0;
+}
+function forwardedHeaders(rawHeaders, port) {
+  const headers = [];
+  for (let i = 0; i < rawHeaders.length; i += 2) {
+    const name = rawHeaders[i].toLowerCase();
+    if (name === "host") headers.push(rawHeaders[i], `localhost:${port}`);
+    else if (!PROXY_HEADERS.has(name)) headers.push(rawHeaders[i], rawHeaders[i + 1]);
+  }
+  return headers;
+}
+function refuse(socket, ports) {
+  const body = `mimic tunnel only forwards ${[...ports].map((p) => `localhost:${p}`).join(", ")}
+`;
+  socket.end(`HTTP/1.1 403 Forbidden\r
+Content-Type: text/plain\r
+Content-Length: ${Buffer.byteLength(body)}\r
+Connection: close\r
+\r
+${body}`);
+}
+function splice(socket, port, onConnect) {
+  let connected = false;
+  const upstream = net.connect({ host: "localhost", port, autoSelectFamily: true }, () => {
+    connected = true;
+    onConnect(upstream);
+    upstream.pipe(socket);
+    socket.pipe(upstream);
+  });
+  upstream.on("error", (error) => {
+    if (connected) return socket.destroy();
+    const body = `localhost:${port} did not answer: ${error.message}
+`;
+    socket.end(`HTTP/1.1 502 Bad Gateway\r
+Content-Type: text/plain\r
+Content-Length: ${Buffer.byteLength(body)}\r
+Connection: close\r
+\r
+${body}`);
+  });
+  socket.on("error", () => upstream.destroy());
+  socket.on("close", () => upstream.destroy());
+}
+function createProxy(ports) {
+  const server = http2.createServer((req, res) => {
+    const target = absoluteTarget(ports, req.url);
+    if (!target) {
+      res.writeHead(403, { "content-type": "text/plain", connection: "close" });
+      res.end(`mimic tunnel only forwards ${[...ports].map((p) => `localhost:${p}`).join(", ")}
+`, () => req.socket.destroy());
+      return;
+    }
+    const upstream = http2.request({
+      host: "localhost",
+      port: target.port,
+      method: req.method,
+      path: target.path,
+      headers: forwardedHeaders(req.rawHeaders, target.port),
+      autoSelectFamily: true
+    }, (response) => {
+      res.writeHead(response.statusCode, response.statusMessage, response.rawHeaders);
+      response.pipe(res);
+    });
+    upstream.on("error", (error) => {
+      if (res.headersSent) {
+        res.destroy();
+      } else {
+        res.writeHead(502, { "content-type": "text/plain" });
+        res.end(`localhost:${target.port} did not answer: ${error.message}
+`);
+      }
+    });
+    res.on("close", () => upstream.destroy());
+    req.pipe(upstream);
+  });
+  server.on("connect", (req, socket, head) => {
+    const port = connectTarget(ports, req.url);
+    if (port === void 0) return refuse(socket, ports);
+    splice(socket, port, (upstream) => {
+      socket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      upstream.write(head);
+    });
+  });
+  server.on("upgrade", (req, socket, head) => {
+    const target = absoluteTarget(ports, req.url);
+    if (!target) return refuse(socket, ports);
+    splice(socket, target.port, (upstream) => {
+      const headers = forwardedHeaders(req.rawHeaders, target.port);
+      const lines = [`${req.method} ${target.path} HTTP/1.1`];
+      for (let i = 0; i < headers.length; i += 2) lines.push(`${headers[i]}: ${headers[i + 1]}`);
+      upstream.write(`${lines.join("\r\n")}\r
+\r
+`);
+      upstream.write(head);
+    });
+  });
+  server.on("clientError", (_error, socket) => socket.destroy());
+  return server;
+}
+function asSocket(stream) {
+  let idleMs = 0;
+  let timer;
+  const arm = () => {
+    clearTimeout(timer);
+    timer = idleMs > 0 ? setTimeout(() => stream.emit("timeout"), idleMs) : void 0;
+  };
+  const push = stream.push.bind(stream);
+  const write = stream.write.bind(stream);
+  stream.on("close", () => clearTimeout(timer));
+  return Object.assign(stream, {
+    push: (chunk, encoding) => {
+      arm();
+      return push(chunk, encoding);
+    },
+    write: (...args) => {
+      arm();
+      return write(...args);
+    },
+    setTimeout: (ms, callback) => {
+      idleMs = ms;
+      if (callback) stream.once("timeout", callback);
+      arm();
+      return stream;
+    },
+    setNoDelay: () => stream,
+    setKeepAlive: () => stream
+  });
+}
+function openTunnel({ connectUrl, ticket, ports, ca }) {
+  const allowed = new Set(ports);
+  const proxy = createProxy(allowed);
+  const headers = { authorization: `Bearer ${ticket}` };
+  const open = /* @__PURE__ */ new Set();
+  const control = new WebSocket(connectUrl, { headers, ca });
+  const openStream = (streamId) => {
+    const socket = new WebSocket(connectUrl.replace(/\/control$/, `/stream/${streamId}`), { headers, ca });
+    open.add(socket);
+    socket.on("close", () => open.delete(socket));
+    const stream = createWebSocketStream(socket);
+    stream.on("error", () => stream.destroy());
+    proxy.emit("connection", asSocket(stream));
+  };
+  control.on("message", (data, isBinary) => {
+    if (isBinary) return;
+    try {
+      const { open: streamId } = JSON.parse(data.toString());
+      if (typeof streamId === "string" && STREAM_ID.test(streamId)) openStream(streamId);
+    } catch {
+      return;
+    }
+  });
+  const closed = new Promise((resolve) => control.once("close", () => {
+    for (const socket of open) socket.terminate();
+    proxy.close();
+    resolve();
+  }));
+  return new Promise((resolve, reject) => {
+    control.once("unexpected-response", (_request, response) => {
+      reject(new Error(`the relay refused the tunnel (HTTP ${response.statusCode})`));
+      control.terminate();
+    });
+    control.once("error", (error) => reject(new Error(`could not reach the relay at ${connectUrl}: ${error.message}`)));
+    control.once("open", () => {
+      control.on("error", () => control.terminate());
+      resolve({
+        get streams() {
+          return open.size;
+        },
+        closed,
+        close: () => control.close()
+      });
+    });
+  });
+}
+
 // src/commands/run.ts
 var MEMORY_PER_WORKER = 400 * 1024 * 1024;
 var CLOUD_POLL_INTERVAL_MS = 1e3;
@@ -1188,16 +1411,65 @@ async function runLocally(workers, windows, slugs, source) {
   }
   return printSummary(lines, started);
 }
-async function runInCloud(slugs) {
+function parsePorts(values) {
+  const ports = values.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean);
+  const invalid = ports.find((port) => !/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535);
+  if (invalid !== void 0) {
+    throw new Error(`--tunnel takes ports between 1 and 65535, got "${invalid}"`);
+  }
+  return [...new Set(ports.map(Number))];
+}
+function listens(port, timeoutMs) {
+  return new Promise((resolve) => {
+    const socket = net2.connect({ host: "localhost", port, autoSelectFamily: true, timeout: Math.max(timeoutMs, 1) });
+    const done = (result) => {
+      socket.destroy();
+      resolve(result);
+    };
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+async function waitForPorts(ports, start) {
+  const probe = (port) => (timeoutMs) => listens(port, timeoutMs);
+  const app = start === void 0 ? void 0 : await startApp(start, `http://localhost:${ports[0]}`, probe(ports[0]));
+  for (const port of ports) {
+    await waitForApp(`localhost:${port}`, port === ports[0] ? app : void 0, probe(port));
+  }
+}
+async function runInCloud(slugs, ports, start) {
   const started = Date.now();
   const groups = findGroups(slugs, slugs.length === 0 ? [] : await api.listGroups());
-  let run2 = await api.startRun({ groups: groups.map((g) => g.id) });
+  if (ports.length > 0) {
+    await waitForPorts(ports, start);
+  }
+  const run2 = await api.startRun({ groups: groups.map((g) => g.id), tunnelPorts: ports });
   if (run2.scenarios.length === 0) {
     console.log("No scenarios found.");
     return 0;
   }
-  console.log(gray(`Started run ${run2.id}: ${run2.scenarios.length} scenarios${inGroupsLabel(slugs)} on the cloud workers
-`));
+  const { connection } = run2;
+  const tunnel = connection ? await openTunnel({ connectUrl: connection.connectUrl, ticket: connection.ticket, ports, ca: trustedCertificates() }) : void 0;
+  try {
+    const reach = connection && `${ports.map((p) => `localhost:${p}`).join(", ")} through ${new URL(connection.connectUrl).host}`;
+    return await pollCloudRun(slugs, run2, tunnel, reach, started);
+  } finally {
+    tunnel?.close();
+  }
+}
+async function pollCloudRun(slugs, firstReport, tunnel, reach, started) {
+  let run2 = firstReport;
+  let tunnelLost = false;
+  void tunnel?.closed.then(() => {
+    tunnelLost = true;
+  });
+  console.log(gray(`Started run ${run2.id}: ${run2.scenarios.length} scenarios${inGroupsLabel(slugs)} on the cloud workers`));
+  if (reach) {
+    console.log(gray(`Tunnel open: workers reach ${reach}`));
+  }
+  console.log();
+  let lostShown = false;
   const reported = /* @__PURE__ */ new Set();
   let lastProgress = Date.now();
   let waitingShown = false;
@@ -1219,9 +1491,14 @@ async function runInCloud(slugs) {
       });
     }
     if (run2.status === "Completed") break;
+    if (tunnelLost && !lostShown) {
+      console.log(red("The tunnel closed; the remaining scenarios cannot reach your app"));
+      lostShown = true;
+    }
     if (!waitingShown && Date.now() - lastProgress >= WAITING_NOTICE_MS) {
       const pending = run2.scenarios.filter((s) => s.status === "Pending").length;
-      console.log(gray(`Waiting for workers (${pending} pending)...`));
+      const streams = tunnel && !tunnelLost ? `, tunnel: ${tunnel.streams} open connections` : "";
+      console.log(gray(`Waiting for workers (${pending} pending${streams})...`));
       waitingShown = true;
     }
     await new Promise((resolve) => setTimeout(resolve, CLOUD_POLL_INTERVAL_MS));
@@ -1240,8 +1517,8 @@ async function answers(baseUrl, timeoutMs) {
     return false;
   }
 }
-async function startApp(command, baseUrl) {
-  if (await answers(baseUrl, 1e3)) {
+async function startApp(command, baseUrl, probe = (ms) => answers(baseUrl, ms)) {
+  if (await probe(1e3)) {
     throw new Error(`${baseUrl} already answers before --start ran; stop what is running there, or leave out --start to test it`);
   }
   const url = new URL(baseUrl);
@@ -1288,7 +1565,7 @@ async function startApp(command, baseUrl) {
   }
   return { exited, logTail: () => [...lines, partial].filter((line) => line.trim() !== "").join("\n") };
 }
-async function waitForApp(baseUrl, app) {
+async function waitForApp(baseUrl, app, probe = (ms) => answers(baseUrl, ms)) {
   const deadline = Date.now() + APP_WAIT_MS;
   let exitCode;
   void app?.exited.then((code) => {
@@ -1301,7 +1578,7 @@ Last app output:
 ${tail}` : message;
   };
   for (; ; ) {
-    if (await answers(baseUrl, Math.min(deadline - Date.now(), 2e3))) {
+    if (await probe(Math.min(deadline - Date.now(), 2e3))) {
       return;
     }
     if (exitCode !== void 0) {
@@ -1325,6 +1602,7 @@ async function execute5(args) {
       start: { type: "string" },
       group: { type: "string", short: "g", multiple: true },
       workers: { type: "string", short: "w" },
+      tunnel: { type: "string", short: "t", multiple: true },
       windows: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false }
     }
@@ -1333,7 +1611,9 @@ async function execute5(args) {
     console.log(run.usage);
     return 0;
   }
-  const slugs = parseGroups(tokens);
+  const lists = parseLists(tokens, ["group", "tunnel"]);
+  const slugs = parseGroups(tokens, lists.get("group"));
+  const ports = parsePorts(lists.get("tunnel"));
   const folders = values.folder ?? [];
   const baseUrl = values["base-url"];
   if (baseUrl !== void 0 && !URL.canParse(baseUrl)) {
@@ -1342,14 +1622,17 @@ async function execute5(args) {
   if (baseUrl !== void 0 && folders.length === 0) {
     throw new Error("--base-url only applies with --folder");
   }
-  if (values.start !== void 0 && baseUrl === void 0) {
-    throw new Error("--start needs --folder and --base-url");
+  if (ports.length > 0 && !values.cloud) {
+    throw new Error("--tunnel only applies with --cloud; local runs reach localhost directly");
+  }
+  if (values.start !== void 0 && baseUrl === void 0 && ports.length === 0) {
+    throw new Error("--start needs --folder and --base-url, or --cloud and --tunnel");
   }
   if (values.cloud) {
-    if (values.workers !== void 0 || values.windows || folders.length > 0 || values.start !== void 0) {
-      throw new Error("--workers, --windows, --folder and --start only apply to local runs, not --cloud");
+    if (values.workers !== void 0 || values.windows || folders.length > 0) {
+      throw new Error("--workers, --windows and --folder only apply to local runs, not --cloud");
     }
-    return runInCloud(slugs);
+    return runInCloud(slugs, ports, values.start);
   }
   const source = folders.length > 0 ? async () => {
     const loaded = await loadFolders(folders, baseUrl);
@@ -1381,14 +1664,19 @@ checked after the steps; each "invalid" value on a Fill step adds a run that typ
 instead (run k types every field's k-th invalid value). Relative Navigate URLs resolve against --base-url, and the run waits up to 30s for it to answer, so it can start right after the app.
 With --start the run starts the app itself (a shell command, with PORT set to --base-url's port), waits for it,
 and stops it when the run ends; if it doesn't come up, its last output is printed.
+With --cloud --tunnel the cloud workers reach these ports on this machine as localhost:<port>, through a tunnel that
+stays open until the run completes (scenarios must navigate to localhost, not 127.0.0.1); --start then starts the
+app with PORT set to the first tunnel port.
 
 Options:
   -g, --group <slug...>  run only the scenarios in these groups (and their prerequisites)
   -f, --folder <path>    run the scenario files in this folder (recursively) instead of the API's; can repeat
       --base-url <url>   with --folder: base for relative Navigate URLs (e.g. http://localhost:5173); waits up
                          to 30s for it to answer
-      --start <command>  with --base-url: start the app with this command (PORT set) and stop it afterwards
+      --start <command>  with --base-url or --tunnel: start the app with this command (PORT set) and stop it
+                         afterwards
       --cloud            run on the cloud workers instead of locally
+  -t, --tunnel <port...> with --cloud: let the workers reach localhost:<port> on this machine (e.g. -t 5173)
   -w, --workers <n>      local only: parallel browser contexts (default: based on CPUs and free memory)
       --windows          local only: show the browser windows
   -h, --help             show this help`,
@@ -1399,10 +1687,19 @@ Options:
 var COMMANDS = [login2, logout, run, list, setPrerequisite];
 var USAGE = `Usage: mimic <command> [options]
 
+Options:
+  -h, --help        show this help
+  -v, --version     print the version
+
 Commands:
 ${COMMANDS.map((command) => `  ${command.name.padEnd(17)} ${command.summary}`).join("\n")}
 
 Run "mimic <command> --help" for a command's options.`;
+async function header() {
+  const email = await signedInEmail();
+  const user = email === void 0 ? 'not signed in (run "mimic login")' : `signed in as ${email ?? "unknown user"}`;
+  return gray(`mimic ${VERSION}, ${API_URL}, ${user}`);
+}
 async function main() {
   const [name, ...args] = process.argv.slice(2);
   const command = COMMANDS.find((c) => c.name === name);
@@ -1410,11 +1707,19 @@ async function main() {
     return command.execute(args);
   }
   if (name === "-h" || name === "--help") {
-    console.log(USAGE);
+    console.log(`${await header()}
+
+${USAGE}`);
+    return 0;
+  }
+  if (name === "-v" || name === "--version") {
+    console.log(VERSION);
     return 0;
   }
   if (name === void 0) {
-    console.log(USAGE);
+    console.log(`${await header()}
+
+${USAGE}`);
     return 1;
   }
   console.error(`Unknown command "${name}"

package/dist/inject.js

@@ -154,15 +154,16 @@
       return value;
     }
   }
-  function assertionCheck(step) {
-    const expected = step.value ?? "";
-    if (step.assertionType === "UrlEquals") {
+  function checkProblem(check) {
+    const expected = check.value ?? "";
+    if (check.type === "UrlEquals") {
       const url = expectedUrl(expected);
       return location.href === url ? void 0 : `expected URL "${url}", but got "${location.href}"`;
     }
-    const { element, error } = locate(step.locator);
+    if (check.type === "Screenshot") return void 0;
+    const { element, error } = locate(check.locator);
     if (!element) return error ?? "element not found";
-    switch (step.assertionType) {
+    switch (check.type) {
       case "ElementExists":
         return void 0;
       case "ElementVisible":
@@ -181,14 +182,24 @@
         }
         return element.value === expected ? void 0 : `expected value "${expected}", but got "${element.value}"`;
       default: {
-        const unhandled = step.assertionType;
+        const unhandled = check.type;
         return `unknown assertion type: ${unhandled}`;
       }
     }
   }
+  function firstFailure(step) {
+    for (const [i, check] of step.checks.entries()) {
+      const problem = checkProblem(check);
+      if (problem) return { check, problem, prefix: step.checks.length > 1 ? `check ${i + 1}: ` : "" };
+    }
+  }
+  function assertionCheck(step) {
+    const failure = firstFailure(step);
+    return failure && `${failure.prefix}${failure.problem}`;
+  }
   function assertionProblem(step) {
-    const problem = assertionCheck(step);
-    return problem && `${step.assertionType} assertion failed: ${problem}`;
+    const failure = firstFailure(step);
+    return failure && `${failure.prefix}${failure.check.type} assertion failed: ${failure.problem}`;
   }
 
   // src/shared/inject.ts
@@ -196,6 +207,7 @@
     find(locator, kind) {
       const { element, error } = locate(locator);
       if (!element) return error ?? "element not found";
+      if (kind === "assert") return element;
       return (kind === "click" ? clickProblem : fillProblem)(element) ?? element;
     },
     isConnected: (el) => el.isConnected,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tonys-software/mimic",
   "type": "module",
-  "version": "0.1.0-stg.3.1",
+  "version": "0.1.1-stg.5.1",
   "description": "Run Mimic scenarios from the command line",
   "license": "UNLICENSED",
   "repository": {
@@ -25,14 +25,17 @@
   "scripts": {
     "postinstall": "playwright install chromium",
     "build": "tsc --noEmit && node build.mjs",
-    "run-all": "node dist/cli.js run"
+    "run-all": "node dist/cli.js run",
+    "tunnel-dev": "node scripts/tunnel-dev.ts"
   },
   "dependencies": {
-    "playwright": "^1.64.0"
+    "playwright": "^1.64.0",
+    "ws": "^8.22.0"
   },
   "devDependencies": {
     "@service/jsclient": "file:../jsclient",
     "@types/node": "^22.18.0",
+    "@types/ws": "^8.18.2",
     "esbuild": "^0.25.10",
     "typescript": "~5.9.3"
   }