@qawolf/cli 2.2.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -8440,6 +8440,7 @@ var authErrorMessages = {
8440
8440
  rejected401: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 401). Check your API key.`,
8441
8441
  rejected402: (noun) => `QA Wolf API refused the${noun ? ` ${noun}` : ""} request (HTTP 402): billing prevented it.`,
8442
8442
  rejected403: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 403). Check that your API key has access to this environment.`,
8443
+ blocked403: (noun) => `The${noun ? ` ${noun}` : ""} request was blocked before it reached the QA Wolf API (HTTP 403), so your API key was not checked.`,
8443
8444
  notFound404Environment: (noun) => `QA Wolf API could not find ${noun ? `${noun} for that environment` : "that environment"} (HTTP 404). Check the --env value.`,
8444
8445
  notFound404Runner: (runnerId) => runnerId === undefined ? "That runner is not running (HTTP 404)." : `Runner ${runnerId} is not running (HTTP 404).`,
8445
8446
  runnerIsGone: "It was never launched, or it has since been terminated or idled out.",
@@ -8935,10 +8936,10 @@ var lifecycleMessages = {
8935
8936
  launched: (id, url) => `Launched runner ${id}. ${pageAt(url)}`,
8936
8937
  launchedForCommand: (id, url) => `No runner was given, so launched ${id} for this command. Its browser is fresh: nothing has been run on it and nothing is signed in. It bills until it is terminated or idles out, so terminate it with qawolf runner terminate --runner ${id} when you are done. ${pageAt(url)}`,
8937
8938
  noRunnerIdForImport: `${noRunnerId} An install also needs a live run to go into, which a runner gets from qawolf runner run.`,
8938
- noRunnerIdForHighlight: `${noRunnerId} Highlighting also needs a live page to draw on, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
8939
- noRunnerIdForInspect: `${noRunnerId} Inspecting also needs a page, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
8939
+ noRunnerIdForHighlight: `${noRunnerId} A playwright runner has a page to draw on as soon as it launches.`,
8940
+ noRunnerIdForInspect: `${noRunnerId} A playwright runner can be inspected as soon as it launches, and any other runner once a flow has run on it with qawolf runner run.`,
8940
8941
  noRunnerIdForPromoteSnapshot: `${noRunnerId} A baseline is replaced on the runner that produced the screenshot, so it has to be the runner the diff came from.`,
8941
- noRunnerIdForScreenshot: `${noRunnerId} A screenshot also needs a screen, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
8942
+ noRunnerIdForScreenshot: `${noRunnerId} A playwright runner has a screen as soon as it launches, and any other runner once a flow has run on it with qawolf runner run.`,
8942
8943
  noRunnerId,
8943
8944
  wasNotRunning: (id) => `Runner ${id} was not running.`,
8944
8945
  terminated: (id) => `Terminated runner ${id}.`,
@@ -15446,6 +15447,15 @@ function applyWorkspaceId(inputSchema, input, workspaceId) {
15446
15447
  return { ...input, workspaceId };
15447
15448
  }
15448
15449
 
15450
+ // src/core/parseJson.ts
15451
+ function parseJson(text) {
15452
+ try {
15453
+ return JSON.parse(text);
15454
+ } catch {
15455
+ return;
15456
+ }
15457
+ }
15458
+
15449
15459
  // src/shell/platform/describeNotFound.ts
15450
15460
  var m = authMessages.errors.request;
15451
15461
  var saysNothingMore = (reason) => /^(\w+ )*not ?found\.?$/i.test(reason.trim());
@@ -15563,7 +15573,7 @@ function describeRequestError(err, baseUrl, noun, notFound) {
15563
15573
  ...body
15564
15574
  };
15565
15575
  if (err.status === 403)
15566
- return { error: m2.request.rejected403(noun), ...body };
15576
+ return parseJson(err.body) === undefined ? { error: m2.request.blocked403(noun) } : { error: m2.request.rejected403(noun), ...body };
15567
15577
  if (err.status === 404)
15568
15578
  return describeNotFound(notFound, noun, reason);
15569
15579
  return { error: m2.request.failedWithStatus(err.status, noun), ...body };
@@ -23624,7 +23634,7 @@ function startUpdateCheck(deps) {
23624
23634
  // package.json
23625
23635
  var package_default = {
23626
23636
  name: "@qawolf/cli",
23627
- version: "2.2.0",
23637
+ version: "2.2.1",
23628
23638
  description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
23629
23639
  keywords: [
23630
23640
  "automation",
@@ -24206,15 +24216,6 @@ async function handleAgentGet(ctx, options, deps) {
24206
24216
  // src/shell/agent/sessionStore.ts
24207
24217
  import { join as join14 } from "node:path";
24208
24218
 
24209
- // src/core/parseJson.ts
24210
- function parseJson(text) {
24211
- try {
24212
- return JSON.parse(text);
24213
- } catch {
24214
- return;
24215
- }
24216
- }
24217
-
24218
24219
  // src/shell/jsonFile.ts
24219
24220
  var pendingWrites = 0;
24220
24221
  async function readJsonFile(fs, path, schema) {
@@ -39397,7 +39398,7 @@ On mobile, send tap and swipe, never click or drag. The other browser actions, d
39397
39398
 
39398
39399
  # Before the first run
39399
39400
 
39400
- A runner has no screen until its first run, so act exits 2 until then, except navigate, which exits 1 (action-failed): it skips the screen but still needs the runner to have run something. With no runner named at all, act launches one and says so on stderr.
39401
+ A playwright runner's screen starts as it launches, so act works on it before anything has run. Any other runner has no screen until its first run, so act exits 2 on it until then. With no runner named at all, act launches one and says so on stderr.
39401
39402
  `;
39402
39403
 
39403
39404
  // src/commands/runner/guides/actions.txt
@@ -39444,7 +39445,7 @@ History is not unbounded: a size cap drops the oldest entries on a long-lived ru
39444
39445
  $ qawolf runner events recorder --tail 5 | jq -r '.code // .type'
39445
39446
  $ qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
39446
39447
 
39447
- \`code\` is absent on events with no call of their own, such as a navigation, which is why the first line falls back to \`type\`. Use these to turn a session you drove by pixel coordinates into durable selectors, and to check that a click landed on the element you meant rather than near it. The stream is empty until the runner's first run gives it a browser context, so an early empty answer means "not yet", not "broken". Do not add --json here: it wraps each line in an envelope and these field paths stop matching.
39448
+ \`code\` is absent on events with no call of their own, such as a navigation, which is why the first line falls back to \`type\`. Use these to turn a session you drove by pixel coordinates into durable selectors, and to check that a click landed on the element you meant rather than near it. The stream stays empty while a playwright runner still shows its welcome page, and on any other runner until its first run, so an early empty answer means "not yet", not "broken". Do not add --json here: it wraps each line in an envelope and these field paths stop matching.
39448
39449
 
39449
39450
  # Following
39450
39451
 
@@ -39471,7 +39472,7 @@ The snippet imports nothing of yours by default. Pass --file <path> to evaluate
39471
39472
 
39472
39473
  # Failures
39473
39474
 
39474
- exec exits 2 until the runner's first run, since there is no page to evaluate against. On a 4 the message says the snippet could not be evaluated, but a lost answer looks the same from outside, so treat a 4 from a snippet that changes something as "may have run" rather than "did not run", and check its effect before running it again. With no runner named at all, exec launches one and says so on stderr.
39475
+ A playwright runner has a page to evaluate against as soon as it launches. On a 4 the message says the snippet could not be evaluated, but a lost answer looks the same from outside, so treat a 4 from a snippet that changes something as "may have run" rather than "did not run", and check its effect before running it again. With no runner named at all, exec launches one and says so on stderr.
39475
39476
  `;
39476
39477
 
39477
39478
  // src/commands/runner/guides/formatGuide.ts
@@ -39558,27 +39559,12 @@ It is a read with a cost: keeping the clock reset keeps a billed pod alive. Call
39558
39559
  `;
39559
39560
 
39560
39561
  // src/commands/runner/guides/launch.txt
39561
- var launch_default = `# Ids
39562
-
39563
- Runner ids are yours to choose and are scoped to your team, so agent-1 is a fine id. Launching an id that is already running attaches to that runner instead of starting and billing a second one, and the answer says which happened: read \`alreadyRunning\`. Reusing one id is therefore the cheap and safe pattern. The same id with a different --name is refused rather than silently ignored.
39564
-
39565
- launch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare \`qawolf runner launch\` invents a random id, bills a pod under it and stores it, so a harness that exported the variable and then launched without --id ends up with a pod it is not addressing. Pass --id whenever you have an id in mind.
39566
-
39567
- Launching an id that differs from QAWOLF_RUNNER_ID prints a warning on stderr naming both ids: the variable still outranks the directory default, so commands that omit --runner keep going to whatever it names, not the runner you just launched. That is expected when you launch an additional runner on purpose. Address that one with --runner rather than re-exporting the variable, which would repoint every other runner-less command too.
39568
-
39569
- # The page
39570
-
39571
- Either answer carries a \`url\`, which launch prints, as does a command that launched its own runner. It is a QA Wolf page showing what the runner is doing, where a person can also take over with their own mouse and keyboard. Hand it to a person who asks what your runner is up to. The page opens for anyone on the runner's team, however the runner was launched. There is nothing to see until the runner's first run starts its screen, so the page waits until then. You read the screen with \`screenshot\`, not with the page.
39572
-
39573
- # Browser or mobile
39574
-
39575
- --name also chooses between a browser and a mobile device: --name android or --name ios starts an Appium session instead of a browser. A command built for the other kind answers a failureReason naming the mismatch rather than doing something approximate: runner-is-not-mobile from inspect session, contexts, page-source and elements on a browser runner, and runner-is-not-a-browser from inspect element-html and page-html on a mobile one. Launch the right family up front rather than discovering it from a refusal mid-session.
39576
- `;
39562
+ var launch_default = "# Ids\n\nRunner ids are yours to choose and are scoped to your team, so agent-1 is a fine id. Launching an id that is already running attaches to that runner instead of starting and billing a second one, and the answer says which happened: read `alreadyRunning`. Reusing one id is therefore the cheap and safe pattern. --name does not change a runner that is already running: the answer's `runnerName` says what you attached to.\n\nlaunch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare `qawolf runner launch` invents a random id, bills a pod under it and stores it, so a harness that exported the variable and then launched without --id ends up with a pod it is not addressing. Pass --id whenever you have an id in mind.\n\nLaunching an id that differs from QAWOLF_RUNNER_ID prints a warning on stderr naming both ids: the variable still outranks the directory default, so commands that omit --runner keep going to whatever it names, not the runner you just launched. That is expected when you launch an additional runner on purpose. Address that one with --runner rather than re-exporting the variable, which would repoint every other runner-less command too.\n\n# The page\n\nEither answer carries a `url`, which launch prints, as does a command that launched its own runner. It is a QA Wolf page showing what the runner is doing, where a person can also take over with their own mouse and keyboard. Hand it to a person who asks what your runner is up to. The page opens for anyone on the runner's team, however the runner was launched. A playwright runner's screen starts as it launches, showing a QA Wolf welcome page. Any other runner's screen starts with its first run, so its page waits until then. You read the screen with `screenshot`, not with the page.\n\n# Browser or mobile\n\n--name also chooses between a browser and a mobile device: --name android or --name ios starts an Appium session instead of a browser. A command built for the other kind answers a failureReason naming the mismatch rather than doing something approximate: runner-is-not-mobile from inspect session, contexts, page-source and elements on a browser runner, and runner-is-not-a-browser from inspect element-html and page-html on a mobile one. Launch the right family up front rather than discovering it from a refusal mid-session.\n";
39577
39563
 
39578
39564
  // src/commands/runner/guides/list.txt
39579
39565
  var list_default = `# What the list holds
39580
39566
 
39581
- The list names the runners this directory has launched that are still running, and marks the one a command with no --runner would reach. It also includes the runner named by QAWOLF_RUNNER_ID even though this directory did not launch it, so a harness handed a runner sees it alongside the ones it started itself. Use the id column with --runner to address any of them; addressing one does not make it the default.
39567
+ The list names every active runner on your team, marking the ones this directory launched and the default, the one a command with no --runner would reach. --here keeps only this directory's runners and the one QAWOLF_RUNNER_ID names. Use the id column with --runner to address any of them; addressing one does not make it the default.
39582
39568
 
39583
39569
  Every runner is looked up before it is listed, so a runner that idled out is absent rather than reported. The lookup neither starts a runner nor resets an inactivity clock, which is what separates list from keepalive: listing tells you what is there and changes nothing. A lookup that cannot be answered fails the command rather than returning a shorter list, because a short list reads as the whole truth.
39584
39570
 
@@ -39669,7 +39655,7 @@ var screenshot_default = `# Reading the screen
39669
39655
 
39670
39656
  The image is a real JPEG on disk, decoded, because every coding harness can open an image file. Read it with whatever vision you have. --out - writes the JPEG bytes to stdout instead, on their own, for a caller that is a process rather than an agent: the confirmation, and the JSON line under --json, goes to stderr so nothing follows the image on stdout. A terminal on stdout is refused: redirect or pipe it.
39671
39657
 
39672
- A runner has no screen until its first run, so until then screenshot exits 2. It never launches a runner. When you are about to act anyway, \`act --screenshot\` performs the action and returns the screen in one call.
39658
+ A playwright runner's screen starts as it launches. Any other runner has no screen until its first run, so until then screenshot exits 2 on it. It never launches a runner. When you are about to act anyway, \`act --screenshot\` performs the action and returns the screen in one call.
39673
39659
  `;
39674
39660
 
39675
39661
  // src/commands/runner/guides/stopOrTerminate.txt
@@ -39683,7 +39669,7 @@ Both succeed when there was nothing to do, and say which: \`wasRunning\` is fals
39683
39669
  `;
39684
39670
 
39685
39671
  // src/commands/runner/guides/workflow.md
39686
- var workflow_default = "An interactive runner is a live pod with a browser or a mobile device in it. You launch one, look at it, act on it, run flows on it, and read what it recorded. Everything is a plain request to one host, so there is no connection to hold open. This guide covers what spans commands; each command's own help below covers the rest.\n\n## Which runner a command reaches\n\nCommands that target a runner find one in this order: `--runner`, then `QAWOLF_RUNNER_ID`, then the runner stored for the current directory, which `qawolf runner launch` sets. Setting the environment variable once is the most robust for a harness whose working directory may not be stable, with two catches:\n\n- `qawolf runner launch` is not in that order: it takes its id from `--id` and never reads `QAWOLF_RUNNER_ID`. Pass `--id` whenever you have an id in mind.\n- A runner id that is set is treated as found, whether or not anything is running under it. Exporting `QAWOLF_RUNNER_ID=agent-1` turns off the auto-launch described next: instead of starting `agent-1`, commands try to reach it and fail with exit code `8`, naming the id and saying the variable is what chose it. Launch that id once yourself and the rest follows.\n\nIf nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and no page is open. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.\n\nNo read command ever launches a runner. `screenshot`, `events` and `keepalive` tell you there is no runner rather than quietly billing one, and so does `terminate`.\n\n## The order that matters\n\nA freshly launched runner has no screen. The virtual desktop starts with the runner's first run and nothing else starts it, so until you have run something:\n\n- `screenshot` and `act` fail with exit code `2`, except `navigate`, which fails with exit code `1` (`action-failed`): it skips the screen but still needs the runner to have run something\n- `exec` fails with exit code `2`\n- `events recorder` reads as empty\n\nNone of that is a fault, and none of it clears on its own. Only `qawolf runner run <flow>` starts the screen. A bare navigate does not: it fails until the first run, however long you wait.\n\nSo the first thing you do to a new runner has to put a browser on it. That means a flow file and a `package.json` on disk, even if all you want is to drive the browser by hand; there is no \"just give me a screen\" call. Once one run has happened, the screenshot-and-act loop works for the rest of the runner's life. A `--lines` selection is the one call that does not need a run first.\n\n## Exit codes\n\nRetry on the exit code, not on the message text:\n\n- `4` is transient, with one exception. The screen is up but cannot serve this instant: restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run. For `exec`, check the effect the snippet was meant to have before running it again.\n- `6` means the work ran out of the time it is given.\n- `8` means there is no such runner. It was never launched, or it was terminated, or it idled out. Retrying never brings one back, so stop and launch the id or name one that is running. The message says which runner was meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored default chose it; read that line before you pick an id to launch.\n- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. The message says which.\n\n`act`, `actions`, `run` and `exec` are the commands whose lost answer may still have taken effect.\n\n## End to end\n\nRun from a directory holding a flow and a `package.json`. The run is what starts the screen, so it is not optional even though the goal here is to drive by hand.\n\n```sh\nexport QAWOLF_API_KEY=... # the only credential\nexport QAWOLF_RUNNER_ID=agent-1 # so no command below needs --runner\n\nqawolf runner launch --id agent-1 --json # --id, not the variable; read .alreadyRunning and .url\nqawolf runner run flows/smoke.flow.ts --follow # starts the screen; exit 1 if it failed\n\nqawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg # then read step-1.jpg yourself\nqawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg\nqawolf runner act type --text \"someone@example.com\" --screenshot step-3.jpg\n\nqawolf runner inspect element-html --selector \"#email\"\nqawolf runner inspect variable --name cart | jq .total\n\nqawolf runner run flows/smoke.flow.ts --lines 12-40 --follow # just those lines\nqawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'\nqawolf runner terminate\n```\n\nOn a mobile runner, launch with `--name android` or `--name ios`, and drive it with `tap`, `swipe`, `fill` and `type` instead of the browser actions.\n";
39672
+ var workflow_default = "An interactive runner is a live pod with a browser or a mobile device in it. You launch one, look at it, act on it, run flows on it, and read what it recorded. Everything is a plain request to one host, so there is no connection to hold open. This guide covers what spans commands; each command's own help below covers the rest.\n\n## Which runner a command reaches\n\nCommands that target a runner find one in this order: `--runner`, then `QAWOLF_RUNNER_ID`, then the runner stored for the current directory, which `qawolf runner launch` sets. Setting the environment variable once is the most robust for a harness whose working directory may not be stable, with two catches:\n\n- `qawolf runner launch` is not in that order: it takes its id from `--id` and never reads `QAWOLF_RUNNER_ID`. Pass `--id` whenever you have an id in mind.\n- A runner id that is set is treated as found, whether or not anything is running under it. Exporting `QAWOLF_RUNNER_ID=agent-1` turns off the auto-launch described next: instead of starting `agent-1`, commands try to reach it and fail with exit code `8`, naming the id and saying the variable is what chose it. Launch that id once yourself and the rest follows.\n\nIf nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act`, `actions` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and it shows only the QA Wolf welcome page. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.\n\nNo read command ever launches a runner. `screenshot`, `events` and `keepalive` tell you there is no runner rather than quietly billing one, and so does `terminate`.\n\n## The order that matters\n\nA playwright runner's screen starts as it launches, showing a QA Wolf welcome page, so the screenshot-and-act loop works before you run anything.\n\nAny other runner, such as a mobile one, has no screen until its first run, and nothing else starts it. Until you have run something on it, `screenshot` and `act` fail with exit code `2`. That is not a fault, and it does not clear on its own: run a flow with `qawolf runner run <flow>`, which needs a flow file and a `package.json` on disk.\n\n## Exit codes\n\nRetry on the exit code, not on the message text:\n\n- `4` is transient, with one exception. The screen cannot serve this instant: still coming up just after launch, restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run. For `exec`, check the effect the snippet was meant to have before running it again.\n- `6` means the work ran out of the time it is given.\n- `7` means billing prevented the request, such as a plan that does not cover the runner you asked for. The message says what was refused and what clears it.\n- `8` means there is no such runner. It was never launched, or it was terminated, or it idled out. Retrying never brings one back, so stop and launch the id or name one that is running. The message says which runner was meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored default chose it; read that line before you pick an id to launch.\n- `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. The message says which.\n\n`act`, `actions`, `run` and `exec` are the commands whose lost answer may still have taken effect.\n\n## End to end\n\nRun from a directory holding a flow and a `package.json`.\n\n```sh\nexport QAWOLF_API_KEY=... # the only credential\nexport QAWOLF_RUNNER_ID=agent-1 # so no command below needs --runner\n\nqawolf runner launch --id agent-1 --json # --id, not the variable; read .alreadyRunning and .url\nqawolf runner run flows/smoke.flow.ts --follow # exit 1 if it failed\n\nqawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg # then read step-1.jpg yourself\nqawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg\nqawolf runner act type --text \"someone@example.com\" --screenshot step-3.jpg\n\nqawolf runner inspect element-html --selector \"#email\"\nqawolf runner inspect variable --name cart | jq .total\n\nqawolf runner run flows/smoke.flow.ts --lines 12-40 --follow # just those lines\nqawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'\nqawolf runner terminate\n```\n\nOn a mobile runner, launch with `--name android` or `--name ios`, and drive it with `tap`, `swipe`, `fill` and `type` instead of the browser actions.\n";
39687
39673
 
39688
39674
  // src/commands/runner/guides/index.ts
39689
39675
  var runnerGuides = {
@@ -40768,7 +40754,7 @@ async function handleRunnerList(ctx, options, deps) {
40768
40754
  if (!listed.ok) {
40769
40755
  return { ...failureFields(listed), exitCode: exitCodes.network };
40770
40756
  }
40771
- const items = options.here ? listed.items.filter((item) => item.launchedHere) : listed.items;
40757
+ const items = options.here ? listed.items.filter((item) => item.launchedHere || item.isDefault) : listed.items;
40772
40758
  if (ctx.ui.mode === "json") {
40773
40759
  ctx.ui.json(items);
40774
40760
  return;
@@ -40844,7 +40830,7 @@ Examples:
40844
40830
  $ qawolf runner keepalive --runner ci`;
40845
40831
  function registerRunnerLifecycleCommands(runner, signals) {
40846
40832
  declareCommandKind(runner.command("launch"), "write").description("Launch an interactive runner and make it this directory's default").option("--id <id>", "Id to launch under. Relaunching an id attaches to that runner").option("--name <family>", "Runner family to run, e.g. playwright").addHelpText("after", launchExamples).addHelpText("after", runnerGuides.launch).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerLaunch(ctx, { id: opts.id, name: opts.name }, runnerDeps(ctx)))(opts, command));
40847
- declareCommandKind(runner.command("list"), "read").description("List the runners running on your team").option("--here", "Only the runners this directory launched").addHelpText("after", listExamples2).addHelpText("after", runnerGuides.list).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerList(ctx, { here: opts.here === true }, runnerDeps(ctx)))(opts, command));
40833
+ declareCommandKind(runner.command("list"), "read").description("List the runners running on your team").option("--here", "Only the runners this directory launched or QAWOLF_RUNNER_ID names").addHelpText("after", listExamples2).addHelpText("after", runnerGuides.list).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerList(ctx, { here: opts.here === true }, runnerDeps(ctx)))(opts, command));
40848
40834
  declareCommandKind(runner.command("terminate"), "write").description("End an interactive runner, and the pod it runs on with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", runnerGuides.stopOrTerminate).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerTerminate(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40849
40835
  declareCommandKind(runner.command("stop-run"), "write").description("Stop what a runner is currently executing, leaving the runner up").option("--runner <id>", runnerFlagDescription).addHelpText("after", runnerGuides.stopOrTerminate).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerStopRun(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
40850
40836
  declareCommandKind(runner.command("keepalive"), "read").description("Reset a runner's inactivity clock, for a caller that pauses between actions").option("--runner <id>", runnerFlagDescription).addHelpText("after", keepaliveExamples).addHelpText("after", runnerGuides.keepalive).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerKeepalive(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
@@ -41830,4 +41816,4 @@ createProgram({ signals }).parseAsync().catch(() => {
41830
41816
  process.exitCode = 1;
41831
41817
  }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
41832
41818
 
41833
- //# debugId=59930438C8ECAB2864756E2164756E21
41819
+ //# debugId=F8E2C24048CC67D764756E2164756E21
@@ -11449,6 +11449,7 @@ var authErrorMessages = {
11449
11449
  rejected401: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 401). Check your API key.`,
11450
11450
  rejected402: (noun) => `QA Wolf API refused the${noun ? ` ${noun}` : ""} request (HTTP 402): billing prevented it.`,
11451
11451
  rejected403: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 403). Check that your API key has access to this environment.`,
11452
+ blocked403: (noun) => `The${noun ? ` ${noun}` : ""} request was blocked before it reached the QA Wolf API (HTTP 403), so your API key was not checked.`,
11452
11453
  notFound404Environment: (noun) => `QA Wolf API could not find ${noun ? `${noun} for that environment` : "that environment"} (HTTP 404). Check the --env value.`,
11453
11454
  notFound404Runner: (runnerId) => runnerId === undefined ? "That runner is not running (HTTP 404)." : `Runner ${runnerId} is not running (HTTP 404).`,
11454
11455
  runnerIsGone: "It was never launched, or it has since been terminated or idled out.",
@@ -11842,10 +11843,10 @@ var lifecycleMessages = {
11842
11843
  launched: (id, url) => `Launched runner ${id}. ${pageAt(url)}`,
11843
11844
  launchedForCommand: (id, url) => `No runner was given, so launched ${id} for this command. Its browser is fresh: nothing has been run on it and nothing is signed in. It bills until it is terminated or idles out, so terminate it with qawolf runner terminate --runner ${id} when you are done. ${pageAt(url)}`,
11844
11845
  noRunnerIdForImport: `${noRunnerId} An install also needs a live run to go into, which a runner gets from qawolf runner run.`,
11845
- noRunnerIdForHighlight: `${noRunnerId} Highlighting also needs a live page to draw on, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
11846
- noRunnerIdForInspect: `${noRunnerId} Inspecting also needs a page, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
11846
+ noRunnerIdForHighlight: `${noRunnerId} A playwright runner has a page to draw on as soon as it launches.`,
11847
+ noRunnerIdForInspect: `${noRunnerId} A playwright runner can be inspected as soon as it launches, and any other runner once a flow has run on it with qawolf runner run.`,
11847
11848
  noRunnerIdForPromoteSnapshot: `${noRunnerId} A baseline is replaced on the runner that produced the screenshot, so it has to be the runner the diff came from.`,
11848
- noRunnerIdForScreenshot: `${noRunnerId} A screenshot also needs a screen, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
11849
+ noRunnerIdForScreenshot: `${noRunnerId} A playwright runner has a screen as soon as it launches, and any other runner once a flow has run on it with qawolf runner run.`,
11849
11850
  noRunnerId,
11850
11851
  wasNotRunning: (id) => `Runner ${id} was not running.`,
11851
11852
  terminated: (id) => `Terminated runner ${id}.`,
@@ -13768,7 +13769,7 @@ function describeRequestError(err, baseUrl, noun, notFound) {
13768
13769
  ...body
13769
13770
  };
13770
13771
  if (err.status === 403)
13771
- return { error: m2.request.rejected403(noun), ...body };
13772
+ return parseJson(err.body) === undefined ? { error: m2.request.blocked403(noun) } : { error: m2.request.rejected403(noun), ...body };
13772
13773
  if (err.status === 404)
13773
13774
  return describeNotFound(notFound, noun, reason);
13774
13775
  return { error: m2.request.failedWithStatus(err.status, noun), ...body };
@@ -16074,4 +16075,4 @@ export {
16074
16075
  createRunnerSdk
16075
16076
  };
16076
16077
 
16077
- //# debugId=56D1BCF300A31BCC64756E2164756E21
16078
+ //# debugId=7D41A06F682D4C5564756E2164756E21
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qawolf/cli",
3
- "version": "2.2.0",
3
+ "version": "2.2.1",
4
4
  "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
5
5
  "keywords": [
6
6
  "automation",
@@ -312,9 +312,9 @@ of calling `act` and then `screenshot`. One call performs the action and writes
312
312
  the screen the runner answers with: half the calls per step, and no delay to
313
313
  guess at between them.
314
314
 
315
- The full workflow is its own guide: how a runner is billed, why the first call
316
- must be a run, the order the commands go in, the see-and-act loop, `exec`, the
317
- recorder, reading history, staying alive, and an end-to-end example. **Run
315
+ The full workflow is its own guide: how a runner is billed, the order the
316
+ commands go in, the see-and-act loop, `exec`, the recorder, reading history,
317
+ staying alive, and an end-to-end example. **Run
318
318
  `qawolf help ref runner` before driving a runner for the first time.** It prints
319
319
  that guide and the help of every runner command, for the CLI version you have.
320
320
  Each command's `--help` carries its own part, so `qawolf runner exec --help`
@@ -11,28 +11,23 @@ Commands that target a runner find one in this order: `--runner`, then `QAWOLF_R
11
11
  - `qawolf runner launch` is not in that order: it takes its id from `--id` and never reads `QAWOLF_RUNNER_ID`. Pass `--id` whenever you have an id in mind.
12
12
  - A runner id that is set is treated as found, whether or not anything is running under it. Exporting `QAWOLF_RUNNER_ID=agent-1` turns off the auto-launch described next: instead of starting `agent-1`, commands try to reach it and fail with exit code `8`, naming the id and saying the variable is what chose it. Launch that id once yourself and the rest follows.
13
13
 
14
- If nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and no page is open. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.
14
+ If nothing names a runner, the commands that change something launch one and say so on stderr, naming it: `run`, `act`, `actions` and `exec`. Read that announcement. The browser it just started is fresh: nothing has been run on it, nothing is signed in, and it shows only the QA Wolf welcome page. Acting as though your earlier setup survived is the single most likely way to drive the wrong page.
15
15
 
16
16
  No read command ever launches a runner. `screenshot`, `events` and `keepalive` tell you there is no runner rather than quietly billing one, and so does `terminate`.
17
17
 
18
18
  ## The order that matters
19
19
 
20
- A freshly launched runner has no screen. The virtual desktop starts with the runner's first run and nothing else starts it, so until you have run something:
20
+ A playwright runner's screen starts as it launches, showing a QA Wolf welcome page, so the screenshot-and-act loop works before you run anything.
21
21
 
22
- - `screenshot` and `act` fail with exit code `2`, except `navigate`, which fails with exit code `1` (`action-failed`): it skips the screen but still needs the runner to have run something
23
- - `exec` fails with exit code `2`
24
- - `events recorder` reads as empty
25
-
26
- None of that is a fault, and none of it clears on its own. Only `qawolf runner run <flow>` starts the screen. A bare navigate does not: it fails until the first run, however long you wait.
27
-
28
- So the first thing you do to a new runner has to put a browser on it. That means a flow file and a `package.json` on disk, even if all you want is to drive the browser by hand; there is no "just give me a screen" call. Once one run has happened, the screenshot-and-act loop works for the rest of the runner's life. A `--lines` selection is the one call that does not need a run first.
22
+ Any other runner, such as a mobile one, has no screen until its first run, and nothing else starts it. Until you have run something on it, `screenshot` and `act` fail with exit code `2`. That is not a fault, and it does not clear on its own: run a flow with `qawolf runner run <flow>`, which needs a flow file and a `package.json` on disk.
29
23
 
30
24
  ## Exit codes
31
25
 
32
26
  Retry on the exit code, not on the message text:
33
27
 
34
- - `4` is transient, with one exception. The screen is up but cannot serve this instant: restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run. For `exec`, check the effect the snippet was meant to have before running it again.
28
+ - `4` is transient, with one exception. The screen cannot serve this instant: still coming up just after launch, restarting after a display-size change, or busy with another request. Retry in a second or two, and bound the retries. The exception is a command that changes something, where a `4` can instead mean the answer was lost with the work in flight. For `act` and `actions`, take a screenshot first and repeat only what the screen says did not happen. For `run`, poll `run-status` instead of submitting again, since a second submission risks a second billed run. For `exec`, check the effect the snippet was meant to have before running it again.
35
29
  - `6` means the work ran out of the time it is given.
30
+ - `7` means billing prevented the request, such as a plan that does not cover the runner you asked for. The message says what was refused and what clears it.
36
31
  - `8` means there is no such runner. It was never launched, or it was terminated, or it idled out. Retrying never brings one back, so stop and launch the id or name one that is running. The message says which runner was meant and whether `--runner`, `QAWOLF_RUNNER_ID` or this directory's stored default chose it; read that line before you pick an id to launch.
37
32
  - `2` will not clear on its own. Nothing has run on this runner yet, so run a flow; or the runner has no browser at all, so launch with `--name playwright` instead; or the action belongs to the other runner family, so send `tap`, `swipe` or `fill` to a mobile runner and the browser actions to a browser runner. The message says which.
38
33
 
@@ -40,14 +35,14 @@ Retry on the exit code, not on the message text:
40
35
 
41
36
  ## End to end
42
37
 
43
- Run from a directory holding a flow and a `package.json`. The run is what starts the screen, so it is not optional even though the goal here is to drive by hand.
38
+ Run from a directory holding a flow and a `package.json`.
44
39
 
45
40
  ```sh
46
41
  export QAWOLF_API_KEY=... # the only credential
47
42
  export QAWOLF_RUNNER_ID=agent-1 # so no command below needs --runner
48
43
 
49
44
  qawolf runner launch --id agent-1 --json # --id, not the variable; read .alreadyRunning and .url
50
- qawolf runner run flows/smoke.flow.ts --follow # starts the screen; exit 1 if it failed
45
+ qawolf runner run flows/smoke.flow.ts --follow # exit 1 if it failed
51
46
 
52
47
  qawolf runner act navigate --url https://example.com/login --screenshot step-1.jpg # then read step-1.jpg yourself
53
48
  qawolf runner act click --button left --x 480 --y 260 --screenshot step-2.jpg
@@ -144,8 +139,8 @@ Ids:
144
139
  fine id. Launching an id that is already running attaches to that runner
145
140
  instead of starting and billing a second one, and the answer says which
146
141
  happened: read `alreadyRunning`. Reusing one id is therefore the cheap and
147
- safe pattern. The same id with a different --name is refused rather than
148
- silently ignored.
142
+ safe pattern. --name does not change a runner that is already running: the
143
+ answer's `runnerName` says what you attached to.
149
144
 
150
145
  launch takes its id from --id and never reads QAWOLF_RUNNER_ID. A bare `qawolf
151
146
  runner launch` invents a random id, bills a pod under it and stores it, so a
@@ -164,9 +159,10 @@ The page:
164
159
  launched its own runner. It is a QA Wolf page showing what the runner is
165
160
  doing, where a person can also take over with their own mouse and keyboard.
166
161
  Hand it to a person who asks what your runner is up to. The page opens for
167
- anyone on the runner's team, however the runner was launched. There is nothing
168
- to see until the runner's first run starts its screen, so the page waits until
169
- then. You read the screen with `screenshot`, not with the page.
162
+ anyone on the runner's team, however the runner was launched. A playwright
163
+ runner's screen starts as it launches, showing a QA Wolf welcome page. Any
164
+ other runner's screen starts with its first run, so its page waits until then.
165
+ You read the screen with `screenshot`, not with the page.
170
166
 
171
167
  Browser or mobile:
172
168
  --name also chooses between a browser and a mobile device: --name android or
@@ -186,7 +182,7 @@ Usage: qawolf runner list [options]
186
182
  List the runners running on your team
187
183
 
188
184
  Options:
189
- --here Only the runners this directory launched
185
+ --here Only the runners this directory launched or QAWOLF_RUNNER_ID names
190
186
  -h, --help display help for command
191
187
 
192
188
  Examples:
@@ -195,12 +191,11 @@ Examples:
195
191
  $ qawolf runner list --json
196
192
 
197
193
  What the list holds:
198
- The list names the runners this directory has launched that are still running,
199
- and marks the one a command with no --runner would reach. It also includes the
200
- runner named by QAWOLF_RUNNER_ID even though this directory did not launch it,
201
- so a harness handed a runner sees it alongside the ones it started itself. Use
202
- the id column with --runner to address any of them; addressing one does not
203
- make it the default.
194
+ The list names every active runner on your team, marking the ones this
195
+ directory launched and the default, the one a command with no --runner would
196
+ reach. --here keeps only this directory's runners and the one QAWOLF_RUNNER_ID
197
+ names. Use the id column with --runner to address any of them; addressing one
198
+ does not make it the default.
204
199
 
205
200
  Every runner is looked up before it is listed, so a runner that idled out is
206
201
  absent rather than reported. The lookup neither starts a runner nor resets an
@@ -514,10 +509,11 @@ The recorder:
514
509
  `code` is absent on events with no call of their own, such as a navigation,
515
510
  which is why the first line falls back to `type`. Use these to turn a session
516
511
  you drove by pixel coordinates into durable selectors, and to check that a
517
- click landed on the element you meant rather than near it. The stream is empty
518
- until the runner's first run gives it a browser context, so an early empty
519
- answer means "not yet", not "broken". Do not add --json here: it wraps each
520
- line in an envelope and these field paths stop matching.
512
+ click landed on the element you meant rather than near it. The stream stays
513
+ empty while a playwright runner still shows its welcome page, and on any other
514
+ runner until its first run, so an early empty answer means "not yet", not
515
+ "broken". Do not add --json here: it wraps each line in an envelope and these
516
+ field paths stop matching.
521
517
 
522
518
  Following:
523
519
  --follow polls and prints as entries arrive. It is tail -f with a bound: it
@@ -566,9 +562,10 @@ Reading the screen:
566
562
  to stderr so nothing follows the image on stdout. A terminal on stdout is
567
563
  refused: redirect or pipe it.
568
564
 
569
- A runner has no screen until its first run, so until then screenshot exits 2.
570
- It never launches a runner. When you are about to act anyway, `act
571
- --screenshot` performs the action and returns the screen in one call.
565
+ A playwright runner's screen starts as it launches. Any other runner has no
566
+ screen until its first run, so until then screenshot exits 2 on it. It never
567
+ launches a runner. When you are about to act anyway, `act --screenshot`
568
+ performs the action and returns the screen in one call.
572
569
  ```
573
570
 
574
571
  ## qawolf runner act
@@ -670,10 +667,10 @@ Mobile:
670
667
  swipe and fill with action-not-supported-on-browser.
671
668
 
672
669
  Before the first run:
673
- A runner has no screen until its first run, so act exits 2 until then, except
674
- navigate, which exits 1 (action-failed): it skips the screen but still needs
675
- the runner to have run something. With no runner named at all, act launches
676
- one and says so on stderr.
670
+ A playwright runner's screen starts as it launches, so act works on it before
671
+ anything has run. Any other runner has no screen until its first run, so act
672
+ exits 2 on it until then. With no runner named at all, act launches one and
673
+ says so on stderr.
677
674
  ```
678
675
 
679
676
  ## qawolf runner actions
@@ -798,12 +795,12 @@ Scope:
798
795
  files, so the snippet can use your own page objects and helpers.
799
796
 
800
797
  Failures:
801
- exec exits 2 until the runner's first run, since there is no page to evaluate
802
- against. On a 4 the message says the snippet could not be evaluated, but a
803
- lost answer looks the same from outside, so treat a 4 from a snippet that
804
- changes something as "may have run" rather than "did not run", and check its
805
- effect before running it again. With no runner named at all, exec launches one
806
- and says so on stderr.
798
+ A playwright runner has a page to evaluate against as soon as it launches. On
799
+ a 4 the message says the snippet could not be evaluated, but a lost answer
800
+ looks the same from outside, so treat a 4 from a snippet that changes
801
+ something as "may have run" rather than "did not run", and check its effect
802
+ before running it again. With no runner named at all, exec launches one and
803
+ says so on stderr.
807
804
  ```
808
805
 
809
806
  ## qawolf runner inspect