@qawolf/cli 1.39.0 → 1.41.0

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
@@ -9262,6 +9262,20 @@ function makeDefaultFs() {
9262
9262
  await fs2.promises.writeFile(path, data, options ?? undefined);
9263
9263
  }
9264
9264
  },
9265
+ async writeFileExclusive(path, data, options) {
9266
+ try {
9267
+ await fs2.promises.writeFile(path, data, {
9268
+ encoding: typeof data === "string" ? "utf8" : undefined,
9269
+ flag: "wx",
9270
+ mode: options?.mode
9271
+ });
9272
+ return true;
9273
+ } catch (error) {
9274
+ if (errorCode(error) === "EEXIST")
9275
+ return false;
9276
+ throw error;
9277
+ }
9278
+ },
9265
9279
  openWriteHandle: openFsWriteHandle,
9266
9280
  readdir(path) {
9267
9281
  return fs2.promises.readdir(path);
@@ -16860,6 +16874,7 @@ var defaultIdSchemas = {
16860
16874
  flow: string2().min(1).describe("The id of the flow."),
16861
16875
  issue: string2().min(1).describe("The id of the issue."),
16862
16876
  legacyTrigger: string2().min(1).describe("The id of the legacy trigger, from legacyTrigger.find."),
16877
+ promotion: string2().min(1).describe("The id of the promotion, from promotion.find or environment.promote."),
16863
16878
  run: string2().min(1).describe("The id of the run."),
16864
16879
  runAttempt: string2().min(1).describe("The id of the run attempt."),
16865
16880
  trigger: string2().min(1).describe("The id of the trigger."),
@@ -17180,7 +17195,7 @@ var makeInspectOnRunnerContract = (ids) => {
17180
17195
  openWorldHint: false,
17181
17196
  readOnlyHint: false
17182
17197
  },
17183
- description: "Inspect one thing on an interactive runner: an element's HTML, the page's HTML simplified for a model, or a top-level variable's value as JSON. This refreshes the inactivity timer and can extend the runner's billed lifetime. `nothing-to-inspect` means the runner had nothing to answer with: no live page, no element matching the selector, or no variable under that name. A runner cannot tell those apart, so it reports the one reason and puts whatever it did say in `errorMessage`. `runner-is-not-a-browser` on a mobile runner — call `runner.inspectMobile` for its equivalent surface instead. " + retryableRunnerUnreachableDescription,
17198
+ description: "Inspect one thing on an interactive runner: an element's HTML, the page's HTML simplified for a model, or a top-level variable's value as JSON. This refreshes the inactivity timer and can extend the runner's billed lifetime. `nothing-to-inspect` means the runner had nothing to answer with: no live page, no element matching the selector, or no variable under that name. A runner cannot tell those apart, so it reports the one reason and puts whatever it did say in `errorMessage`. A mobile or Windows runner answers `variable`; for `element-html` or `page-html` it answers `runner-is-not-a-browser` — call `runner.inspectMobile` for its equivalent surface instead. " + retryableRunnerUnreachableDescription,
17184
17199
  input,
17185
17200
  kind: "read",
17186
17201
  name: "runner.inspect",
@@ -17250,8 +17265,8 @@ var elementsRequestSchema = discriminatedUnion("by", [
17250
17265
  by: literal("point"),
17251
17266
  context: string2().min(1).optional(),
17252
17267
  what: literal("elements"),
17253
- x: int().min(0).describe("Whole pixels on the device's own screen."),
17254
- y: int().min(0).describe("Whole pixels on the device's own screen.")
17268
+ x: int().min(0).describe("Whole pixels in the same space as `runner.takeScreenshot`."),
17269
+ y: int().min(0).describe("Whole pixels in the same space as `runner.takeScreenshot`.")
17255
17270
  }),
17256
17271
  object({
17257
17272
  by: literal("text"),
@@ -17313,7 +17328,7 @@ var inspectMobileAnswerSchema = discriminatedUnion("what", [
17313
17328
  context: string2(),
17314
17329
  orientation: orientationSchema,
17315
17330
  outcome: literal("success"),
17316
- pageSource: pageSourceNodeSchema,
17331
+ pageSource: pageSourceNodeSchema.describe("The element tree. Its bounds are in the device's own pixels, not the screenshot's; to find a point to act on, ask for `elements`, whose bounds and centers are in screenshot pixels."),
17317
17332
  what: literal("page")
17318
17333
  }),
17319
17334
  object({
@@ -17349,7 +17364,7 @@ var makeInspectMobileOnRunnerContract = (ids) => {
17349
17364
  openWorldHint: false,
17350
17365
  readOnlyHint: true
17351
17366
  },
17352
- description: `Inspect one thing on a mobile interactive runner: the Appium session's status, the WebView contexts available, the current context's page source, or the elements at a point, carrying some text, or matching a selector. This does not refresh the runner's inactivity timer. Mobile only — a browser runner answers \`runner-is-not-mobile\`; call \`runner.inspect\` for a browser's equivalent surface instead. \`what: "session"\` always answers with the session's own status rather than \`screen-needs-a-run\`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same \`screen-needs-a-run\` or \`screen-not-ready\` outcomes \`runner.performAction\` and \`runner.takeScreenshot\` use, instead of reading anything when there is none. \`screen-needs-a-run\` means no Appium session has started on this runner yet — call \`runner.runFlow\` with a flow that opens one, then inspect again. \`screen-not-ready\` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. \`runner-is-not-mobile\` means there is nothing here to inspect, and retrying will never help — launch an \`android\` or \`ios\` runner instead. \`invalid-selector\` (elements by selector only) means the selector itself could not be parsed under the given \`strategy\` — distinct from a selector that parsed fine but matched nothing, which answers \`matches: []\` instead. ${retryableRunnerUnreachableDescription}`,
17367
+ description: `Inspect one thing on a mobile or Windows interactive runner: the Appium session's status, the contexts available (WebViews on mobile, top-level windows on Windows), the current context's page source, or the elements at a point, carrying some text, or matching a selector. This does not refresh the runner's inactivity timer. Mobile and Windows only — a browser runner answers \`runner-is-not-mobile\`; call \`runner.inspect\` for a browser's equivalent surface instead. \`what: "session"\` always answers with the session's own status rather than \`screen-needs-a-run\`, since that is the question it exists to answer; the other three request kinds need a live session first and answer the same \`screen-needs-a-run\` or \`screen-not-ready\` outcomes \`runner.performAction\` and \`runner.takeScreenshot\` use, instead of reading anything when there is none. \`screen-needs-a-run\` means no Appium session has started on this runner yet — call \`runner.runFlow\` with a flow that opens one, then inspect again. \`screen-not-ready\` means the runner's Appium session exists but did not answer this instant, or more than one is somehow live — retry once; if it persists, relaunch the runner. \`runner-is-not-mobile\` means there is nothing here to inspect, and retrying will never help — launch an \`android\`, \`ios\` or \`windows\` runner instead. \`invalid-selector\` (elements by selector only) means the selector itself could not be parsed under the given \`strategy\` — distinct from a selector that parsed fine but matched nothing, which answers \`matches: []\` instead. ${retryableRunnerUnreachableDescription}`,
17353
17368
  input,
17354
17369
  kind: "read",
17355
17370
  name: "runner.inspectMobile",
@@ -17478,19 +17493,20 @@ var screenFailureReasons = [
17478
17493
  "screen-not-ready"
17479
17494
  ];
17480
17495
  var screenNotReadyDescription = "`screen-not-ready` if the runner has a screen that cannot serve this instant. Retry in a second or two: the desktop restarts when a run changes the display size, and it serves one see-or-act request at a time, so a screenshot or action already in flight is the usual reason. Do not submit a run to clear this — a run may restart the display and discard what is on it.";
17481
- var screenNeedsARunDescription = "`screen-needs-a-run` if the runner's virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` with a flow that opens a browser, then ask for the screen again. On a runner image with a browser that has never run anything, any `runner.performAction` also starts the browser itself. Evaluating a snippet does not start the desktop.";
17482
- var runnerHasNoScreenDescription = "`runner-has-no-screen` if this runner has no browser desktop to see or drive, and retrying will never help. Launch a `playwright` runner, or on `windows` use `runner.runFlow`.";
17496
+ var screenNeedsARunDescription = "`screen-needs-a-run` if the runner's virtual desktop has never started. Waiting will not change this and retrying is pointless — call `runner.runFlow` with a flow that opens a browser, then ask for the screen again. On a Windows runner any flow run claims the VM and brings up its screen. On a runner image with a browser that has never run anything, any `runner.performAction` also starts the browser itself. Evaluating a snippet does not start the desktop.";
17497
+ var runnerHasNoScreenDescription = "`runner-has-no-screen` if this runner has no browser desktop to see or drive, and retrying will never help. Launch a `playwright` runner.";
17483
17498
  var screenshotImageSchema = string2().min(1).describe("The screenshot, as a base64-encoded JPEG. Decode it and write the bytes to a `.jpg` file — writing this string to the file leaves you with base64 text rather than an image.");
17484
17499
 
17485
17500
  // node_modules/@qawolf/api-contracts/dist/v1/runner/performAction.js
17486
17501
  var unreachableDescription = "`runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may have stopped answering mid-action. This does not mean the action was not performed — take a screenshot before repeating it.";
17487
- var notSupportedOnMobileDescription = "`action-not-supported-on-mobile` if the runner is a mobile device and this action has no touchscreen equivalent: `double_click`, `scroll`, `move`, `keypress` and `navigate`, and a `click` whose `button` is not `left`, are all pointer-device concepts a touchscreen has nothing to offer for. `type` types into whatever the last tap focused. Deprecated on mobile and to be removed: `click` taps and `drag` swipes between its path's first and last point; send `tap` and `swipe` instead.";
17488
- var mobileActionsDescription = "Only a mobile runner performs `tap`, `swipe` and `fill`: `tap` touches a point or the element a `selector` names, `swipe` moves from one point to another over `duration_ms`, and `fill` replaces the value of the field a `selector` names. A browser runner answers them with `action-not-supported-on-browser`.";
17489
- var withScreenshotDescription = "With `withScreenshot: true`, the answer also carries `imageJpegBase64`: a screenshot taken after the action. One call instead of `runner.performAction` followed by `runner.takeScreenshot`. The action itself is performed exactly as without the option; if the screen could serve no frame after it — a display restart, or a `navigate` on a desktop that is still starting — the action's result comes back without `imageJpegBase64`, so take a screenshot separately rather than repeating the action. On a mobile runner the screenshot is the device's own, taken right after a performed action.";
17502
+ var notSupportedOnMobileDescription = "`action-not-supported-on-mobile` if the runner is a mobile device and this is a browser action other than `type`: `click`, `double_click`, `drag`, `scroll`, `move`, `keypress` and `navigate` describe a mouse and keyboard, so send `tap` and `swipe` instead. `type` types into whatever the last tap focused.";
17503
+ var mobileActionsDescription = "Only a mobile or Windows runner performs `tap`, `swipe` and `fill`: `tap` touches a point or the element a `selector` names, `swipe` moves from one point to another over `duration_ms`, and `fill` replaces the value of the field a `selector` names. A browser runner answers them with `action-not-supported-on-browser`.";
17504
+ var windowsActionsDescription = "On a Windows runner, `click`, `double_click`, `move`, `scroll`, `drag`, `keypress` and `type` act on the whole desktop with a mouse and keyboard, at screenshot coordinates; a `drag` takes only its start and end point, and `swipe` is a drag. `tap` and `fill` also accept a UI Automation XPath `selector` (as in `runner.inspectMobile`) in place of a point. `navigate` is refused with `action-failed` because it needs a browser: open the page from a flow instead. Take points to act on from `runner.inspectMobile` `elements` (their `center`), not from page-source bounds, which are in the desktop's own pixels.";
17505
+ var withScreenshotDescription = "With `withScreenshot: true`, the answer also carries `imageJpegBase64`: a screenshot taken after the action. One call instead of `runner.performAction` followed by `runner.takeScreenshot`. The action itself is performed exactly as without the option; if the screen could serve no frame after it — a display restart, or a `navigate` on a desktop that is still starting — the action's result comes back without `imageJpegBase64`, so take a screenshot separately rather than repeating the action. On a mobile or Windows runner the screenshot is the device's own screen (on Windows, the whole desktop), taken right after a performed action.";
17490
17506
  var maxActionErrorMessageLength = 1000;
17491
17507
  var makePerformActionOnRunnerContract = (ids) => {
17492
17508
  const input = object({
17493
- action: runnerActionSchema.describe(`The action to perform. Coordinates are whole pixels on the runner's virtual desktop, in the same space as \`runner.takeScreenshot\`. The browser action shapes follow the computer-use vocabulary, minus \`screenshot\` (use \`runner.takeScreenshot\`) and \`wait\` (delay on the caller's side). A \`navigate\` does not go through the screen, so a screen that is not ready does not stop it. ${notSupportedOnMobileDescription} ${mobileActionsDescription}`),
17509
+ action: runnerActionSchema.describe(`The action to perform. Coordinates are whole pixels on the runner's virtual desktop, in the same space as \`runner.takeScreenshot\`. The browser action shapes follow the computer-use vocabulary, minus \`screenshot\` (use \`runner.takeScreenshot\`) and \`wait\` (delay on the caller's side). A \`navigate\` does not go through the screen, so a screen that is not ready does not stop it. ${notSupportedOnMobileDescription} ${mobileActionsDescription} ${windowsActionsDescription}`),
17494
17510
  id: runnerIdSchema.describe("Id of the runner to act on."),
17495
17511
  withScreenshot: boolean2().optional().describe(withScreenshotDescription),
17496
17512
  workspaceId: ids.workspace.optional().describe(runnerWorkspaceIdDescription)
@@ -17528,7 +17544,7 @@ var makePerformActionOnRunnerContract = (ids) => {
17528
17544
  openWorldHint: true,
17529
17545
  readOnlyHint: false
17530
17546
  },
17531
- description: `Perform one raw action on an interactive runner: click, double_click, move, drag, scroll, keypress, type, or navigate; on mobile, tap, swipe, fill, or type. One action per request, and the runner serves one at a time. A success means the action took effect. \`action-failed\`, with a reason, if it reached the runner and did not take effect. On a runner image with a browser, the first action on a runner that has never run anything starts its browser and waits for it, so it can take up to a minute to answer — no \`runner.runFlow\` is needed before acting; if the browser is still starting when the wait runs out, the answer is \`screen-not-ready\` and retrying converges. On a mobile runner, the same \`screen-needs-a-run\` and \`screen-not-ready\` outcomes mean no Appium session has started yet, or it did not answer this instant; \`runner.runFlow\` is what starts one, same as a browser. \`screen-needs-a-run\` if the browser could not be started that way — usually a runner whose runs all finished without starting its desktop; call \`runner.runFlow\` with a flow that opens a browser. ${screenNotReadyDescription} ${runnerHasNoScreenDescription} ${unreachableDescription}`,
17547
+ description: `Perform one raw action on an interactive runner: click, double_click, move, drag, scroll, keypress, type, or navigate; on mobile or Windows, also tap, swipe, or fill. One action per request, and the runner serves one at a time. A success means the action took effect. \`action-failed\`, with a reason, if it reached the runner and did not take effect. On a runner image with a browser, the first action on a runner that has never run anything starts its browser and waits for it, so it can take up to a minute to answer — no \`runner.runFlow\` is needed before acting; if the browser is still starting when the wait runs out, the answer is \`screen-not-ready\` and retrying converges. On a mobile or Windows runner, the same \`screen-needs-a-run\` and \`screen-not-ready\` outcomes mean no Appium session has started yet, or it did not answer this instant; \`runner.runFlow\` is what starts one, same as a browser. \`screen-needs-a-run\` if the browser could not be started that way — usually a runner whose runs all finished without starting its desktop; call \`runner.runFlow\` with a flow that opens a browser. ${screenNotReadyDescription} ${runnerHasNoScreenDescription} ${unreachableDescription}`,
17532
17548
  input,
17533
17549
  kind: "write",
17534
17550
  name: "runner.performAction",
@@ -17637,7 +17653,7 @@ var makePerformActionsOnRunnerContract = (ids) => {
17637
17653
  openWorldHint: true,
17638
17654
  readOnlyHint: false
17639
17655
  },
17640
- description: "Perform a sequence of raw actions on an interactive runner in one request, one after another, and answer with what happened to each. A `success` means every action took effect. A `failure` names the first action that did not (`failedIndex`, `failureReason`), the last one that did (`lastCompletedIndex`), and whether actions were left unperformed (`stoppedEarly`); `results` has one entry per action reached, in order. Read `effect` on an entry before sending its action again: `performed` means the runner did it; `not-performed` means the runner answered that it did not take effect, though a `navigate` that timed out may still be loading; `unknown` means the runner stopped answering with the action in flight (`runner-unreachable`), or its screen went quiet mid-action (`action-unconfirmed`), and it may have taken effect — a click that submitted a form, say — so take a screenshot instead of repeating it. A sequence gets about a minute to start its actions; an action it did not reach in time is `out-of-time`, nothing after it was attempted, and the rest can go in a new request. Everything `runner.performAction` says about a runner that has never run anything, a mobile runner, and the `screen-needs-a-run`, `screen-not-ready`, `runner-has-no-screen`, `action-not-supported-on-mobile` and `action-not-supported-on-browser` reasons holds for each action here.",
17656
+ description: "Perform a sequence of raw actions on an interactive runner in one request, one after another, and answer with what happened to each. A `success` means every action took effect. A `failure` names the first action that did not (`failedIndex`, `failureReason`), the last one that did (`lastCompletedIndex`), and whether actions were left unperformed (`stoppedEarly`); `results` has one entry per action reached, in order. Read `effect` on an entry before sending its action again: `performed` means the runner did it; `not-performed` means the runner answered that it did not take effect, though a `navigate` that timed out may still be loading; `unknown` means the runner stopped answering with the action in flight (`runner-unreachable`), or its screen went quiet mid-action (`action-unconfirmed`), and it may have taken effect — a click that submitted a form, say — so take a screenshot instead of repeating it. A sequence gets about a minute to start its actions; an action it did not reach in time is `out-of-time`, nothing after it was attempted, and the rest can go in a new request. Everything `runner.performAction` says about a runner that has never run anything, a mobile or Windows runner, and the `screen-needs-a-run`, `screen-not-ready`, `runner-has-no-screen`, `action-not-supported-on-mobile` and `action-not-supported-on-browser` reasons holds for each action here.",
17641
17657
  input,
17642
17658
  kind: "write",
17643
17659
  name: "runner.performActions",
@@ -18230,6 +18246,88 @@ var makeAgentSendContract = (ids) => {
18230
18246
  };
18231
18247
  };
18232
18248
 
18249
+ // node_modules/@qawolf/api-contracts/dist/v1/attempt/get.js
18250
+ var makeGetAttemptContract = (ids) => {
18251
+ const input = object({ attemptId: ids.runAttempt });
18252
+ const attemptStatus = _enum([
18253
+ "passed",
18254
+ "failed",
18255
+ "canceled",
18256
+ "aborted",
18257
+ "skipped"
18258
+ ]);
18259
+ const attemptNeighbor = object({
18260
+ attemptId: ids.runAttempt,
18261
+ status: attemptStatus
18262
+ });
18263
+ const response = object({
18264
+ flowId: ids.flow,
18265
+ flowStatus: _enum(publicRunStatusValues),
18266
+ retryContext: object({
18267
+ currentOrdinal: number2().int().min(1),
18268
+ next: attemptNeighbor.optional(),
18269
+ previous: attemptNeighbor.optional(),
18270
+ total: number2().int().min(1)
18271
+ }),
18272
+ runId: ids.run,
18273
+ runStatus: _enum(publicRunSummaryStatusValues)
18274
+ });
18275
+ const attempt = object({
18276
+ attemptId: ids.runAttempt,
18277
+ completedAt: exports_iso.datetime().optional(),
18278
+ createdAt: exports_iso.datetime(),
18279
+ error: string2().optional(),
18280
+ startedAt: exports_iso.datetime().optional()
18281
+ });
18282
+ const output = discriminatedUnion("artifactStatus", [
18283
+ response.extend({
18284
+ artifacts: object({
18285
+ logsUrl: url().optional(),
18286
+ traceUrl: url().optional(),
18287
+ videoUrl: url().optional()
18288
+ }),
18289
+ artifactStatus: literal("signed"),
18290
+ attempt: attempt.extend({
18291
+ kind: literal("automated"),
18292
+ status: attemptStatus
18293
+ })
18294
+ }),
18295
+ response.extend({
18296
+ artifacts: object({}).strict(),
18297
+ artifactStatus: literal("signing-failed"),
18298
+ attempt: attempt.extend({
18299
+ kind: literal("automated"),
18300
+ status: attemptStatus
18301
+ })
18302
+ }),
18303
+ response.extend({
18304
+ artifacts: object({}).strict(),
18305
+ artifactStatus: literal("not-captured"),
18306
+ attempt: attempt.extend({
18307
+ kind: literal("manual"),
18308
+ status: literal("passed")
18309
+ })
18310
+ })
18311
+ ]);
18312
+ return {
18313
+ annotationJustifications: {
18314
+ destructiveHint: "Does not retry, cancel or alter the run attempt.",
18315
+ openWorldHint: "Reads recorded QA Wolf artifacts without changing the application under test.",
18316
+ readOnlyHint: "Retrieves a finished attempt's metadata and signed artifact URLs."
18317
+ },
18318
+ annotations: {
18319
+ destructiveHint: false,
18320
+ openWorldHint: false,
18321
+ readOnlyHint: true
18322
+ },
18323
+ description: "Get a finished run attempt: its run and flow status, its place among that flow's attempts in the run, and signed links to its logs, trace, and video when they were captured.",
18324
+ input,
18325
+ kind: "read",
18326
+ name: "attempt.get",
18327
+ output
18328
+ };
18329
+ };
18330
+
18233
18331
  // node_modules/@qawolf/api-contracts/dist/v1/codeHostIntegration/resource.js
18234
18332
  var makeCodeHostIntegrationResourceSchema = () => resource({
18235
18333
  connectedAt: exports_iso.datetime().describe("When the code host was connected to the workspace."),
@@ -18796,6 +18894,32 @@ var makeDeleteEnvironmentVariableContract = (ids) => {
18796
18894
  };
18797
18895
  };
18798
18896
 
18897
+ // node_modules/@qawolf/api-contracts/dist/v1/environment/discard.js
18898
+ var makeDiscardEnvironmentContract = (ids) => {
18899
+ const input = object({
18900
+ environmentId: ids.environmentRef,
18901
+ workspaceId: workspaceForEnvironmentRef(ids.workspace)
18902
+ });
18903
+ const output = makeEnvironmentResourceSchema(ids);
18904
+ return {
18905
+ annotationJustifications: {
18906
+ destructiveHint: "Terminates the environment for good: its runs are canceled and its flow changes are never promoted.",
18907
+ openWorldHint: "Changes QA Wolf environments only, not the customer's own repository or deployments.",
18908
+ readOnlyHint: "Terminates an environment and returns it terminated."
18909
+ },
18910
+ annotations: {
18911
+ destructiveHint: true,
18912
+ openWorldHint: false,
18913
+ readOnlyHint: false
18914
+ },
18915
+ description: "Declare a preview environment's work discarded, typically when its pull request closes without merging: the environment is terminated and its flow changes are not promoted into its base. Returns the environment, now terminated. A terminated environment cannot be discarded again. Use environment.promote instead when the work is accepted.",
18916
+ input,
18917
+ kind: "write",
18918
+ name: "environment.discard",
18919
+ output
18920
+ };
18921
+ };
18922
+
18799
18923
  // node_modules/@qawolf/api-contracts/dist/v1/environment/find.js
18800
18924
  var makeFindEnvironmentsContract = (ids) => {
18801
18925
  const input = object({
@@ -18941,6 +19065,58 @@ var makeSetEnvironmentVariableContract = (ids) => {
18941
19065
  };
18942
19066
  };
18943
19067
 
19068
+ // node_modules/@qawolf/api-contracts/dist/v1/promotion/resource.js
19069
+ var promotionStatusSchema = _enum([
19070
+ "pending",
19071
+ "conflicted",
19072
+ "resolving",
19073
+ "promoted",
19074
+ "no-changes",
19075
+ "abandoned"
19076
+ ]).describe("pending (requested, the merge has not run yet), conflicted (the head's flow changes clash with the base and await a resolution), resolving (a submitted resolution is being applied), promoted (merged into the base and the head environment terminated), no-changes (the head had nothing to promote and was terminated), abandoned (the head environment was discarded or terminated before the promotion settled).");
19077
+ var conflictSchema = object({
19078
+ paths: array(string2()).describe("Every path that conflicts between the head and the base. A resolution must cover exactly these paths."),
19079
+ sourceCommitHash: string2().describe("The head environment's flow code commit the conflict was computed against."),
19080
+ targetCommitHash: string2().describe("The base environment's flow code commit the conflict was computed against.")
19081
+ });
19082
+ var makePromotionResourceSchema = (ids) => resource({
19083
+ aiTaskId: ids.aiTask.optional().describe("The AI task dispatched to resolve this promotion's conflicts. Absent until the agent is dispatched. A promotion that stays conflicted after this is set means the agent could not resolve it."),
19084
+ baseEnvironmentId: ids.environment.describe("The environment the flow changes promote into."),
19085
+ conflict: conflictSchema.optional().describe("The conflict awaiting resolution. Present while status is conflicted or resolving. A resolution must name both commit hashes and cover exactly these paths; if either branch moves, the conflict is recomputed and this changes."),
19086
+ createdAt: exports_iso.datetime().describe("When the promotion was requested."),
19087
+ headEnvironmentId: ids.environment.describe("The environment whose flow changes are promoted."),
19088
+ id: ids.promotion,
19089
+ promotedCommitHash: string2().optional().describe("The commit the promotion landed on the base environment's flow code branch. Present when status is promoted."),
19090
+ settledAt: exports_iso.datetime().optional().describe("When the promotion reached promoted, no-changes or abandoned. Absent while it is open."),
19091
+ status: promotionStatusSchema
19092
+ }, { urlFieldDescription: "Absolute URL of the head environment's page." });
19093
+
19094
+ // node_modules/@qawolf/api-contracts/dist/v1/environment/promote.js
19095
+ var makePromoteEnvironmentContract = (ids) => {
19096
+ const input = object({
19097
+ environmentId: ids.environmentRef,
19098
+ workspaceId: workspaceForEnvironmentRef(ids.workspace)
19099
+ });
19100
+ const output = makePromotionResourceSchema(ids);
19101
+ return {
19102
+ annotationJustifications: {
19103
+ destructiveHint: "Merges the environment's flow changes into its base and terminates the environment once they land.",
19104
+ openWorldHint: "Changes QA Wolf flow code branches only, not the customer's own repository or deployments.",
19105
+ readOnlyHint: "Records a promotion request that a background executor carries out."
19106
+ },
19107
+ annotations: {
19108
+ destructiveHint: true,
19109
+ openWorldHint: false,
19110
+ readOnlyHint: false
19111
+ },
19112
+ description: "Declare a preview environment's work accepted, typically when its pull request merges: its flow changes are promoted into its base environment and the environment is terminated once they land. Returns the promotion in pending; poll promotion.get to learn how it settled. Calling again while a promotion is open returns that promotion. A conflict settles the promotion conflicted and cancels the environment's in-progress runs; promotion.get names the conflicting paths. Use environment.discard instead when the work is abandoned.",
19113
+ input,
19114
+ kind: "write",
19115
+ name: "environment.promote",
19116
+ output
19117
+ };
19118
+ };
19119
+
18944
19120
  // node_modules/@qawolf/api-contracts/dist/v1/environment/update.js
18945
19121
  var makeUpdateEnvironmentContract = (ids) => {
18946
19122
  const nameSchema = string2().trim().min(1).max(255).describe("New display name. Must be unique within the team.");
@@ -19303,7 +19479,8 @@ var makeInvestigationFindingSchema = (ids) => object({
19303
19479
  answer: string2().optional(),
19304
19480
  at: exports_iso.datetime(),
19305
19481
  reason: string2().optional(),
19306
- type: string2().describe('Known values: "answer" and "dispute". New values can appear.')
19482
+ text: string2().optional().describe("A person's answer in their own words, when they typed one."),
19483
+ type: string2().describe('Known values: "answer", "dispute" and "reply". New values can appear.')
19307
19484
  }).optional().describe("A person's answer or dispute that the investigation hasn't acted on yet."),
19308
19485
  state: string2().describe(investigationFindingStateDescription),
19309
19486
  steps: array(string2()).optional(),
@@ -19627,6 +19804,66 @@ var makeLegacyTriggerContracts = (ids) => ({
19627
19804
  resume: makeResumeLegacyTriggerContract(ids)
19628
19805
  });
19629
19806
 
19807
+ // node_modules/@qawolf/api-contracts/dist/v1/promotion/find.js
19808
+ var makeFindPromotionsContract = (ids) => {
19809
+ const input = object({
19810
+ environmentId: ids.environmentRef.optional().describe("Only list promotions out of this head environment, by id or alias. Omit to list the whole workspace's promotions."),
19811
+ status: promotionStatusSchema.optional().describe("Only list promotions in this status. Use conflicted to see the promotions that need attention."),
19812
+ workspaceId: ids.workspace.optional().describe("The workspace to list promotions from, which an environment alias resolves in. Required when authenticating with an organization or user API key."),
19813
+ ...makePaginationInputFields({ defaultLimit: 20, maxLimit: 100 })
19814
+ });
19815
+ const output = object({
19816
+ nextCursor: nextCursorSchema,
19817
+ promotions: array(makePromotionResourceSchema(ids)).describe("The workspace's promotions, newest first.")
19818
+ });
19819
+ return {
19820
+ annotationJustifications: {
19821
+ destructiveHint: "Does not change promotions, environments or flow code branches.",
19822
+ openWorldHint: "Reads private QA Wolf promotion records without changing external systems.",
19823
+ readOnlyHint: "Lists promotions in the authorized workspace without changing them."
19824
+ },
19825
+ annotations: {
19826
+ destructiveHint: false,
19827
+ openWorldHint: false,
19828
+ readOnlyHint: true
19829
+ },
19830
+ description: "List environment promotions, newest first. A promotion moves the flow changes made in a head environment into its base environment. Filter by status conflicted to find the promotions whose conflicts still need a resolution.",
19831
+ input,
19832
+ kind: "read",
19833
+ name: "promotion.find",
19834
+ output
19835
+ };
19836
+ };
19837
+
19838
+ // node_modules/@qawolf/api-contracts/dist/v1/promotion/get.js
19839
+ var makeGetPromotionContract = (ids) => {
19840
+ const input = object({ promotionId: ids.promotion });
19841
+ const output = makePromotionResourceSchema(ids);
19842
+ return {
19843
+ annotationJustifications: {
19844
+ destructiveHint: "Does not change the promotion, its environments or flow code branches.",
19845
+ openWorldHint: "Reads a private QA Wolf promotion record without changing external systems.",
19846
+ readOnlyHint: "Retrieves one authorized promotion's status and conflict without changing it."
19847
+ },
19848
+ annotations: {
19849
+ destructiveHint: false,
19850
+ openWorldHint: false,
19851
+ readOnlyHint: true
19852
+ },
19853
+ description: "Read one environment promotion: its status, the conflicting paths and commit hashes while it is conflicted or resolving, the commit it landed when promoted, and the AI task resolving it. Poll it after environment.promote to learn how the promotion settled. It does not serve file contents; a resolver reads both branches from the flow code repository.",
19854
+ input,
19855
+ kind: "read",
19856
+ name: "promotion.get",
19857
+ output
19858
+ };
19859
+ };
19860
+
19861
+ // node_modules/@qawolf/api-contracts/dist/v1/promotion/index.js
19862
+ var makePromotionContracts = (ids) => ({
19863
+ find: makeFindPromotionsContract(ids),
19864
+ get: makeGetPromotionContract(ids)
19865
+ });
19866
+
19630
19867
  // node_modules/@qawolf/api-contracts/dist/v1/run/investigationSessionId.js
19631
19868
  var investigationSessionId = string2().trim().min(1).max(100).optional();
19632
19869
 
@@ -19842,88 +20079,6 @@ var makeGetRunContract = (ids) => {
19842
20079
  };
19843
20080
  };
19844
20081
 
19845
- // node_modules/@qawolf/api-contracts/dist/v1/run/getAttemptArtifacts.js
19846
- var makeGetRunAttemptArtifactsContract = (ids) => {
19847
- const input = object({ attemptId: ids.runAttempt });
19848
- const attemptStatus = _enum([
19849
- "passed",
19850
- "failed",
19851
- "canceled",
19852
- "aborted",
19853
- "skipped"
19854
- ]);
19855
- const attemptNeighbor = object({
19856
- attemptId: ids.runAttempt,
19857
- status: attemptStatus
19858
- });
19859
- const response = object({
19860
- flowId: ids.flow,
19861
- flowStatus: _enum(publicRunStatusValues),
19862
- retryContext: object({
19863
- currentOrdinal: number2().int().min(1),
19864
- next: attemptNeighbor.optional(),
19865
- previous: attemptNeighbor.optional(),
19866
- total: number2().int().min(1)
19867
- }),
19868
- runId: ids.run,
19869
- runStatus: _enum(publicRunSummaryStatusValues)
19870
- });
19871
- const attempt = object({
19872
- attemptId: ids.runAttempt,
19873
- completedAt: exports_iso.datetime().optional(),
19874
- createdAt: exports_iso.datetime(),
19875
- error: string2().optional(),
19876
- startedAt: exports_iso.datetime().optional()
19877
- });
19878
- const output = discriminatedUnion("artifactStatus", [
19879
- response.extend({
19880
- artifacts: object({
19881
- logsUrl: url().optional(),
19882
- traceUrl: url().optional(),
19883
- videoUrl: url().optional()
19884
- }),
19885
- artifactStatus: literal("signed"),
19886
- attempt: attempt.extend({
19887
- kind: literal("automated"),
19888
- status: attemptStatus
19889
- })
19890
- }),
19891
- response.extend({
19892
- artifacts: object({}).strict(),
19893
- artifactStatus: literal("signing-failed"),
19894
- attempt: attempt.extend({
19895
- kind: literal("automated"),
19896
- status: attemptStatus
19897
- })
19898
- }),
19899
- response.extend({
19900
- artifacts: object({}).strict(),
19901
- artifactStatus: literal("not-captured"),
19902
- attempt: attempt.extend({
19903
- kind: literal("manual"),
19904
- status: literal("passed")
19905
- })
19906
- })
19907
- ]);
19908
- return {
19909
- annotationJustifications: {
19910
- destructiveHint: "Does not retry, cancel or alter the run attempt.",
19911
- openWorldHint: "Reads recorded QA Wolf artifacts without changing the application under test.",
19912
- readOnlyHint: "Retrieves a finished attempt's metadata and signed artifact URLs."
19913
- },
19914
- annotations: {
19915
- destructiveHint: false,
19916
- openWorldHint: false,
19917
- readOnlyHint: true
19918
- },
19919
- description: "Get metadata and signed artifact URLs for one finished run attempt.",
19920
- input,
19921
- kind: "read",
19922
- name: "run.getAttemptArtifacts",
19923
- output
19924
- };
19925
- };
19926
-
19927
20082
  // node_modules/@qawolf/api-contracts/dist/v1/run/optOutOfInvestigation.js
19928
20083
  var makeOptOutOfInvestigationRunContract = (ids) => {
19929
20084
  const input = object({
@@ -20520,7 +20675,7 @@ var makeTakeScreenshotOnRunnerContract = (ids) => {
20520
20675
  openWorldHint: false,
20521
20676
  readOnlyHint: false
20522
20677
  },
20523
- description: `Take one screenshot of an interactive runner's screen. On a runner with a browser the image is the whole virtual desktop, browser window and all; this refreshes the inactivity timer and can extend the runner's billed lifetime. On a mobile runner it is the device's own screen, re-encoded to JPEG on the pod so this contract reads one image format regardless of runner family. ${screenNeedsARunDescription} ${screenNotReadyDescription} ${runnerHasNoScreenDescription} ${retryableRunnerUnreachableDescription}`,
20678
+ description: `Take one screenshot of an interactive runner's screen. On a runner with a browser the image is the whole virtual desktop, browser window and all; this refreshes the inactivity timer and can extend the runner's billed lifetime. On a mobile runner it is the device's own screen, and on Windows the VM's whole desktop, re-encoded to JPEG on the pod so this contract reads one image format regardless of runner family. ${screenNeedsARunDescription} ${screenNotReadyDescription} ${runnerHasNoScreenDescription} ${retryableRunnerUnreachableDescription}`,
20524
20679
  input,
20525
20680
  kind: "read",
20526
20681
  name: "runner.takeScreenshot",
@@ -20652,6 +20807,9 @@ var makeContractsV1 = (ids) => {
20652
20807
  get: makeAgentGetContract(resolvedIds),
20653
20808
  send: makeAgentSendContract(resolvedIds)
20654
20809
  },
20810
+ attempt: {
20811
+ get: makeGetAttemptContract(resolvedIds)
20812
+ },
20655
20813
  codeHostIntegration: {
20656
20814
  find: makeFindCodeHostIntegrationsContract(resolvedIds),
20657
20815
  listRepositories: makeListCodeHostRepositoriesContract(resolvedIds)
@@ -20668,10 +20826,12 @@ var makeContractsV1 = (ids) => {
20668
20826
  environment: {
20669
20827
  create: makeCreateEnvironmentContract(resolvedIds),
20670
20828
  deleteVariable: makeDeleteEnvironmentVariableContract(resolvedIds),
20829
+ discard: makeDiscardEnvironmentContract(resolvedIds),
20671
20830
  find: makeFindEnvironmentsContract(resolvedIds),
20672
20831
  get: makeGetEnvironmentContract(resolvedIds),
20673
20832
  getVariable: makeGetEnvironmentVariableContract(resolvedIds),
20674
20833
  listVariableNames: makeListEnvironmentVariableNamesContract(resolvedIds),
20834
+ promote: makePromoteEnvironmentContract(resolvedIds),
20675
20835
  setVariable: makeSetEnvironmentVariableContract(resolvedIds),
20676
20836
  update: makeUpdateEnvironmentContract(resolvedIds)
20677
20837
  },
@@ -20692,13 +20852,13 @@ var makeContractsV1 = (ids) => {
20692
20852
  update: makeUpdateIssueContract(resolvedIds)
20693
20853
  },
20694
20854
  legacyTrigger: makeLegacyTriggerContracts(resolvedIds),
20855
+ promotion: makePromotionContracts(resolvedIds),
20695
20856
  run: {
20696
20857
  acceptScreenshotBaseline: makeAcceptScreenshotBaselineContract(resolvedIds),
20697
20858
  create: makeCreateRunContract(resolvedIds),
20698
20859
  diagnose: makeDiagnoseRunContract(resolvedIds),
20699
20860
  find: makeFindRunsContract(resolvedIds),
20700
20861
  get: makeGetRunContract(resolvedIds),
20701
- getAttemptArtifacts: makeGetRunAttemptArtifactsContract(resolvedIds),
20702
20862
  listScreenshotComparisons: makeListScreenshotComparisonsContract(resolvedIds),
20703
20863
  optOutOfInvestigation: makeOptOutOfInvestigationRunContract(resolvedIds),
20704
20864
  reattempt: makeReattemptRunContract(resolvedIds),
@@ -23219,7 +23379,7 @@ function startUpdateCheck(deps) {
23219
23379
  // package.json
23220
23380
  var package_default = {
23221
23381
  name: "@qawolf/cli",
23222
- version: "1.39.0",
23382
+ version: "1.41.0",
23223
23383
  description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
23224
23384
  keywords: [
23225
23385
  "automation",
@@ -23247,6 +23407,7 @@ var package_default = {
23247
23407
  "LICENSE",
23248
23408
  "README.md",
23249
23409
  "dist/cli.js",
23410
+ "dist/investigation-parser.js",
23250
23411
  "dist/runner-sdk.js",
23251
23412
  "dist/types/runnerSdk/index.d.ts",
23252
23413
  "dist/types/runnerSdk/types.d.ts",
@@ -23290,13 +23451,14 @@ var package_default = {
23290
23451
  "@clack/prompts": "1.5.1",
23291
23452
  "@napi-rs/keyring": "1.3.0",
23292
23453
  "@oxc-node/core": "0.1.0",
23293
- "@qawolf/api-contracts": "0.81.0",
23454
+ "@qawolf/api-contracts": "0.83.0",
23294
23455
  "@qawolf/emails": "1.1.1",
23295
23456
  "@qawolf/flow-targets": "1.0.0",
23296
23457
  "@qawolf/flows": "0.1.4",
23297
23458
  "@qawolf/testkit": "1.2.1",
23298
23459
  commander: "14.0.3",
23299
23460
  "env-paths": "4.0.0",
23461
+ jszip: "3.10.1",
23300
23462
  picomatch: "4.0.4",
23301
23463
  pino: "10.3.1",
23302
23464
  playwright: "1.62.0",
@@ -35785,6 +35947,106 @@ function registerFlowsCommand(program, signals, deps = { withResolvedEnv }) {
35785
35947
  registerFlowsPullCommand(flows, signals);
35786
35948
  }
35787
35949
 
35950
+ // src/commands/help/commandTree.ts
35951
+ function listVisibleSubcommands(command) {
35952
+ return new Help2().visibleCommands(command).filter((child) => child.name() !== "help");
35953
+ }
35954
+ function commandPath(command) {
35955
+ return command.parent === null ? [command.name()] : [...commandPath(command.parent), command.name()];
35956
+ }
35957
+ function findSubcommand(root, path) {
35958
+ return path.reduce((command, segment) => command?.commands.find((child) => child.name() === segment || child.aliases().includes(segment)), root);
35959
+ }
35960
+
35961
+ // src/commands/help/referenceGuide.ts
35962
+ var guides = new WeakMap;
35963
+ function declareReferenceGuide(command, markdown) {
35964
+ guides.set(command, markdown);
35965
+ return command;
35966
+ }
35967
+ function shiftHeadings(markdown, levels) {
35968
+ const lines = markdown.trim().split(`
35969
+ `);
35970
+ const shifted = lines.reduce((state, line) => {
35971
+ if (line.startsWith("```")) {
35972
+ return { inFence: !state.inFence, lines: [...state.lines, line] };
35973
+ }
35974
+ const isHeading = !state.inFence && /^#{1,6} /.test(line);
35975
+ const shiftedLine = isHeading ? `${"#".repeat(levels)}${line}` : line;
35976
+ return { inFence: state.inFence, lines: [...state.lines, shiftedLine] };
35977
+ }, { inFence: false, lines: [] });
35978
+ return shifted.lines.join(`
35979
+ `);
35980
+ }
35981
+ function renderReferenceGuide(command, depth) {
35982
+ const guide = guides.get(command);
35983
+ return guide === undefined ? undefined : shiftHeadings(guide, depth - 1);
35984
+ }
35985
+
35986
+ // src/commands/help/reference.ts
35987
+ var referenceHelpWidth = 100;
35988
+ var deepestHeadingLevel = 6;
35989
+ function formatCommandHelp(command) {
35990
+ const originalOutput = command.configureOutput();
35991
+ const chunks = [];
35992
+ command.configureOutput({
35993
+ getOutHasColors: () => false,
35994
+ getOutHelpWidth: () => referenceHelpWidth,
35995
+ writeOut: (text) => chunks.push(text)
35996
+ });
35997
+ try {
35998
+ command.outputHelp();
35999
+ } finally {
36000
+ command.configureOutput(originalOutput);
36001
+ }
36002
+ return chunks.join("").trimEnd();
36003
+ }
36004
+ function renderSections(command, path, depth) {
36005
+ const heading = `${"#".repeat(Math.min(depth, deepestHeadingLevel))} ${path.join(" ")}`;
36006
+ const help = ["```text", formatCommandHelp(command), "```"].join(`
36007
+ `);
36008
+ const guide = renderReferenceGuide(command, depth);
36009
+ const section = [heading, ...guide === undefined ? [] : [guide], help].join(`
36010
+
36011
+ `);
36012
+ return [
36013
+ section,
36014
+ ...listVisibleSubcommands(command).flatMap((child) => renderSections(child, [...path, child.name()], depth + 1))
36015
+ ];
36016
+ }
36017
+ function renderHelpReference(command, path) {
36018
+ return `${renderSections(command, path, 1).join(`
36019
+
36020
+ `)}
36021
+ `;
36022
+ }
36023
+
36024
+ // src/commands/help/index.ts
36025
+ var referenceExamples = `
36026
+ Examples:
36027
+ $ qawolf help ref runner
36028
+ $ qawolf help ref runner inspect
36029
+ $ qawolf help reference`;
36030
+ function resolveCommand(program, path) {
36031
+ const command = findSubcommand(program, path);
36032
+ if (command === undefined) {
36033
+ program.error(`error: unknown command '${path.join(" ")}'`, {
36034
+ code: "commander.unknownCommand",
36035
+ exitCode: exitCodes.invalidArgs
36036
+ });
36037
+ }
36038
+ return command;
36039
+ }
36040
+ function registerHelpCommand(program) {
36041
+ const help = program.helpCommand(false).command("help").description("Display help for a command").usage("[command...]").argument("[command...]", "Command to show help for").action((path) => {
36042
+ resolveCommand(program, path).outputHelp();
36043
+ });
36044
+ help.command("ref").alias("reference").description("Print the full help of a command and of every command under it, as Markdown. Omit the command for the whole CLI").argument("[command...]", "Command whose subtree to print").addHelpText("after", referenceExamples).action((path) => {
36045
+ const command = resolveCommand(program, path);
36046
+ program.configureOutput().writeOut?.(renderHelpReference(command, commandPath(command)));
36047
+ });
36048
+ }
36049
+
35788
36050
  // src/domains/init/init.ts
35789
36051
  import { dirname as dirname14, join as join50, relative as relative9 } from "node:path";
35790
36052
 
@@ -36277,6 +36539,387 @@ Examples:
36277
36539
  });
36278
36540
  }
36279
36541
 
36542
+ // src/domains/investigation/handle.ts
36543
+ import { basename as basename8 } from "node:path";
36544
+
36545
+ // src/domains/investigation/download.ts
36546
+ var traceLimit = 50 * 1024 * 1024;
36547
+ var logTailLimit = 5 * 1024 * 1024;
36548
+ var logTransferLimit = 50 * 1024 * 1024;
36549
+ var downloadTimeoutMs = 120000;
36550
+ function downloadFailure(error) {
36551
+ return { status: isTimeoutError(error) ? "timed-out" : "unavailable" };
36552
+ }
36553
+ async function responseFailure(response) {
36554
+ await response.body?.cancel().catch(() => {
36555
+ return;
36556
+ });
36557
+ if (response.status === 404)
36558
+ return { status: "not-found" };
36559
+ if (response.status === 401 || response.status === 403)
36560
+ return { status: "expired-url" };
36561
+ return { status: "unavailable" };
36562
+ }
36563
+ async function readBounded(response, options) {
36564
+ if (!response.ok)
36565
+ return responseFailure(response);
36566
+ const declaredLength = Number(response.headers.get("content-length"));
36567
+ if (Number.isFinite(declaredLength) && declaredLength > options.transferBytes) {
36568
+ await response.body?.cancel().catch(() => {
36569
+ return;
36570
+ });
36571
+ return { status: "too-large" };
36572
+ }
36573
+ if (!response.body)
36574
+ return { status: "unavailable" };
36575
+ const reader = response.body.getReader();
36576
+ const chunks = [];
36577
+ let retained = 0;
36578
+ let transferred = 0;
36579
+ while (true) {
36580
+ const next = await reader.read();
36581
+ if (next.done)
36582
+ break;
36583
+ const chunk = next.value;
36584
+ if (!(chunk instanceof Uint8Array)) {
36585
+ await reader.cancel();
36586
+ return { status: "unavailable" };
36587
+ }
36588
+ transferred += chunk.byteLength;
36589
+ if (transferred > options.transferBytes) {
36590
+ await reader.cancel();
36591
+ return { status: "too-large" };
36592
+ }
36593
+ chunks.push(chunk);
36594
+ retained += chunk.byteLength;
36595
+ if (options.keepTail) {
36596
+ while (chunks.length > 1 && retained - chunks[0].byteLength >= options.retainBytes) {
36597
+ retained -= chunks.shift().byteLength;
36598
+ }
36599
+ } else if (retained > options.retainBytes) {
36600
+ await reader.cancel();
36601
+ return { status: "too-large" };
36602
+ }
36603
+ }
36604
+ let bytes = Buffer.concat(chunks);
36605
+ const contentRange = response.headers.get("content-range");
36606
+ const rangeStart = contentRange ? Number(/^bytes (\d+)-/.exec(contentRange)?.[1]) : Number.NaN;
36607
+ let offset = Number.isFinite(rangeStart) ? rangeStart : transferred - bytes.byteLength;
36608
+ if (bytes.byteLength > options.retainBytes) {
36609
+ const removed = bytes.byteLength - options.retainBytes;
36610
+ bytes = bytes.subarray(removed);
36611
+ offset += removed;
36612
+ }
36613
+ return { bytes, offset, status: "available" };
36614
+ }
36615
+ async function downloadTrace(url, fetchImpl = globalThis.fetch) {
36616
+ try {
36617
+ const signal = AbortSignal.timeout(downloadTimeoutMs);
36618
+ const response = await fetchImpl(url, { redirect: "follow", signal });
36619
+ return await readBounded(response, {
36620
+ keepTail: false,
36621
+ retainBytes: traceLimit,
36622
+ transferBytes: traceLimit
36623
+ });
36624
+ } catch (error) {
36625
+ return downloadFailure(error);
36626
+ }
36627
+ }
36628
+ async function downloadLogTail(url, fetchImpl = globalThis.fetch) {
36629
+ try {
36630
+ const signal = AbortSignal.timeout(downloadTimeoutMs);
36631
+ const response = await fetchImpl(url, {
36632
+ headers: { range: `bytes=-${logTailLimit}` },
36633
+ redirect: "follow",
36634
+ signal
36635
+ });
36636
+ return await readBounded(response, {
36637
+ keepTail: true,
36638
+ retainBytes: logTailLimit,
36639
+ transferBytes: logTransferLimit
36640
+ });
36641
+ } catch (error) {
36642
+ return downloadFailure(error);
36643
+ }
36644
+ }
36645
+
36646
+ // src/domains/investigation/lazyParser.ts
36647
+ var parserPromise;
36648
+ function loadInvestigationParser() {
36649
+ parserPromise ??= import(parserSpecifier());
36650
+ return parserPromise;
36651
+ }
36652
+ function parserSpecifier() {
36653
+ const embedded = globalThis.qawolfInvestigationParserPath;
36654
+ if (embedded)
36655
+ return embedded;
36656
+ const sourceModule = import.meta.url.includes("/src/domains/investigation/");
36657
+ return new URL(sourceModule ? "./parser/index.ts" : "./investigation-parser.js", import.meta.url).href;
36658
+ }
36659
+
36660
+ // src/domains/investigation/handle.ts
36661
+ function artifactUnavailable(status) {
36662
+ return { status };
36663
+ }
36664
+ async function loadSummaryArtifacts(value) {
36665
+ if (value.artifactStatus !== "signed") {
36666
+ const unavailable = artifactUnavailable(value.artifactStatus);
36667
+ return { logs: unavailable, trace: unavailable };
36668
+ }
36669
+ const [logs, trace] = await Promise.all([
36670
+ value.artifacts.logsUrl ? downloadLogTail(value.artifacts.logsUrl) : artifactUnavailable("not-captured"),
36671
+ value.artifacts.traceUrl ? downloadTrace(value.artifacts.traceUrl) : artifactUnavailable("not-captured")
36672
+ ]);
36673
+ return { logs, trace };
36674
+ }
36675
+ async function loadInspectArtifact(value, type) {
36676
+ const inactive = artifactUnavailable("not-captured");
36677
+ if (value.artifactStatus !== "signed") {
36678
+ const unavailable = artifactUnavailable(value.artifactStatus);
36679
+ return type === "log" ? { logs: unavailable, trace: inactive } : { logs: inactive, trace: unavailable };
36680
+ }
36681
+ if (type === "log") {
36682
+ return {
36683
+ logs: value.artifacts.logsUrl ? await downloadLogTail(value.artifacts.logsUrl) : inactive,
36684
+ trace: inactive
36685
+ };
36686
+ }
36687
+ return {
36688
+ logs: inactive,
36689
+ trace: value.artifacts.traceUrl ? await downloadTrace(value.artifacts.traceUrl) : inactive
36690
+ };
36691
+ }
36692
+ var defaultInspectLimit = "20";
36693
+ var maxInspectLimit = 100;
36694
+ var filterSelectors = [
36695
+ ["evidenceId", "--evidence-id", ["console", "log"]],
36696
+ ["limit", "--limit", ["timeline", "network", "console", "log"]],
36697
+ ["startTimeMs", "--start-time-ms", ["network", "console"]],
36698
+ ["endTimeMs", "--end-time-ms", ["network", "console"]],
36699
+ ["startTimestamp", "--start-timestamp", ["log"]],
36700
+ ["endTimestamp", "--end-timestamp", ["log"]],
36701
+ ["source", "--source", ["log"]],
36702
+ ["method", "--method", ["network"]],
36703
+ ["status", "--status", ["network"]],
36704
+ ["urlContains", "--url-contains", ["network"]]
36705
+ ];
36706
+ function inapplicableFilter(options) {
36707
+ for (const [field, flag, selectors] of filterSelectors) {
36708
+ if (options[field] === undefined || selectors.includes(options.type))
36709
+ continue;
36710
+ const allowed = selectors.map((selector) => `--${selector}`).join(", ");
36711
+ return {
36712
+ error: `${flag} does not apply to --${options.type}; use it with ${allowed}.`
36713
+ };
36714
+ }
36715
+ return;
36716
+ }
36717
+ function numberFlag(value, name, options = {}) {
36718
+ if (value === undefined)
36719
+ return;
36720
+ const parsed = Number(value);
36721
+ if (!Number.isFinite(parsed) || options.integer === true && !Number.isInteger(parsed) || options.min !== undefined && parsed < options.min)
36722
+ return { error: `Invalid ${name}: ${value}.` };
36723
+ if (options.max !== undefined && parsed > options.max)
36724
+ return { error: `${name} must be at most ${options.max}, got ${value}.` };
36725
+ return parsed;
36726
+ }
36727
+ function timestampFlag(value, name) {
36728
+ if (value === undefined || !Number.isNaN(Date.parse(value)))
36729
+ return;
36730
+ return {
36731
+ error: `Invalid ${name}: ${value}. Use an ISO 8601 timestamp such as 2026-01-31T12:00:00Z.`
36732
+ };
36733
+ }
36734
+ function validateInspect(options) {
36735
+ if (options.type === "action" && !options.actionId)
36736
+ return { error: "--action requires an evidence ID." };
36737
+ if (options.type === "request" && !options.requestId)
36738
+ return { error: "--request requires an evidence ID." };
36739
+ if (options.type === "snapshot" && !options.snapshotId)
36740
+ return { error: "--snapshot requires an evidence ID." };
36741
+ if (options.type === "screenshot" && !options.screenshotId)
36742
+ return { error: "--screenshot requires an evidence ID." };
36743
+ if (options.format === "html" && options.type !== "snapshot")
36744
+ return { error: "--format html is supported only with --snapshot." };
36745
+ if (options.type === "screenshot" && !options.outputFile)
36746
+ return {
36747
+ error: "--output-file is required for screenshot evidence."
36748
+ };
36749
+ if (options.outputFile && options.format !== "html" && options.type !== "screenshot")
36750
+ return {
36751
+ error: "--output-file is supported only with --snapshot and --format html, or with --screenshot."
36752
+ };
36753
+ return;
36754
+ }
36755
+ function renderText(result) {
36756
+ return JSON.stringify(result, undefined, 2);
36757
+ }
36758
+ async function fetchAttempt(ctx, attemptId) {
36759
+ return ctx.platformClient.callPublicApi(publicContractsV1.attempt.get, {
36760
+ attemptId
36761
+ });
36762
+ }
36763
+ async function handleInvestigationSummary(ctx, attemptId) {
36764
+ const authorized = await fetchAttempt(ctx, attemptId);
36765
+ if (!authorized.ok)
36766
+ return failureFields(authorized);
36767
+ const artifacts = await loadSummaryArtifacts(authorized.value);
36768
+ const parser = await loadInvestigationParser();
36769
+ const evidence = await parser.investigate({
36770
+ artifacts,
36771
+ attempt: authorized.value.attempt,
36772
+ flowId: authorized.value.flowId,
36773
+ mode: "summary",
36774
+ runId: authorized.value.runId
36775
+ });
36776
+ const result = {
36777
+ ...authorized.value,
36778
+ artifacts: undefined,
36779
+ evidence
36780
+ };
36781
+ ctx.ui.output(result, renderText(result));
36782
+ return;
36783
+ }
36784
+ async function handleInvestigationInspect(ctx, options) {
36785
+ const invalid = validateInspect(options) ?? inapplicableFilter(options);
36786
+ if (invalid)
36787
+ return invalid;
36788
+ if (options.outputFile && await ctx.fs.pathExists(options.outputFile))
36789
+ return {
36790
+ error: `Refusing to overwrite existing file: ${options.outputFile}`
36791
+ };
36792
+ const limit = numberFlag(options.limit ?? defaultInspectLimit, "--limit", {
36793
+ integer: true,
36794
+ max: maxInspectLimit,
36795
+ min: 1
36796
+ });
36797
+ if (typeof limit !== "number")
36798
+ return limit;
36799
+ const startTimeMilliseconds = numberFlag(options.startTimeMs, "--start-time-ms");
36800
+ if (typeof startTimeMilliseconds === "object")
36801
+ return startTimeMilliseconds;
36802
+ const endTimeMilliseconds = numberFlag(options.endTimeMs, "--end-time-ms");
36803
+ if (typeof endTimeMilliseconds === "object")
36804
+ return endTimeMilliseconds;
36805
+ const status = numberFlag(options.status, "--status", {
36806
+ integer: true,
36807
+ min: 0
36808
+ });
36809
+ if (typeof status === "object")
36810
+ return status;
36811
+ const timestampError = timestampFlag(options.startTimestamp, "--start-timestamp") ?? timestampFlag(options.endTimestamp, "--end-timestamp");
36812
+ if (timestampError)
36813
+ return timestampError;
36814
+ const authorized = await fetchAttempt(ctx, options.attemptId);
36815
+ if (!authorized.ok)
36816
+ return failureFields(authorized);
36817
+ const artifacts = await loadInspectArtifact(authorized.value, options.type);
36818
+ const request = {
36819
+ artifacts,
36820
+ attempt: authorized.value.attempt,
36821
+ flowId: authorized.value.flowId,
36822
+ inspect: {
36823
+ actionId: options.actionId,
36824
+ endTimeMilliseconds,
36825
+ endTimestamp: options.endTimestamp,
36826
+ evidenceId: options.evidenceId,
36827
+ format: options.format,
36828
+ limit,
36829
+ method: options.method,
36830
+ requestId: options.requestId,
36831
+ screenshotId: options.screenshotId,
36832
+ snapshotId: options.snapshotId,
36833
+ source: options.source,
36834
+ startTimeMilliseconds,
36835
+ startTimestamp: options.startTimestamp,
36836
+ status,
36837
+ type: options.type,
36838
+ urlContains: options.urlContains
36839
+ },
36840
+ mode: "inspect",
36841
+ runId: authorized.value.runId
36842
+ };
36843
+ const parser = await loadInvestigationParser();
36844
+ const parsed = await parser.investigate(request);
36845
+ return outputInvestigationInspection(ctx, options, parsed);
36846
+ }
36847
+ async function outputInvestigationInspection(ctx, options, parsed) {
36848
+ const { binary, ...result } = parsed;
36849
+ if (options.outputFile) {
36850
+ if (!binary)
36851
+ return {
36852
+ error: "The requested evidence did not contain exportable data."
36853
+ };
36854
+ const written = await ctx.fs.writeFileExclusive(options.outputFile, Buffer.from(binary.bytesBase64, "base64"), { mode: 384 });
36855
+ if (!written)
36856
+ return {
36857
+ error: `Refusing to overwrite existing file: ${options.outputFile}`
36858
+ };
36859
+ const output = { ...result, outputFile: options.outputFile };
36860
+ ctx.ui.output(output, `${renderText(result)}
36861
+ Saved ${binary.extension}: ${basename8(options.outputFile)}`);
36862
+ return;
36863
+ }
36864
+ if (binary?.extension === "html") {
36865
+ const html = Buffer.from(binary.bytesBase64, "base64").toString("utf8");
36866
+ ctx.ui.output({ ...result, html }, html);
36867
+ return;
36868
+ }
36869
+ ctx.ui.output(result, renderText(result));
36870
+ return;
36871
+ }
36872
+
36873
+ // src/commands/attempt/inspectSelection.ts
36874
+ function resolveInspectSelection(options) {
36875
+ const candidates = [
36876
+ options.action === undefined ? undefined : { actionId: options.action, type: "action" },
36877
+ options.timeline ? { type: "timeline" } : undefined,
36878
+ options.network ? { type: "network" } : undefined,
36879
+ options.request === undefined ? undefined : { requestId: options.request, type: "request" },
36880
+ options.snapshot === undefined ? undefined : { snapshotId: options.snapshot, type: "snapshot" },
36881
+ options.screenshot === undefined ? undefined : { screenshotId: options.screenshot, type: "screenshot" },
36882
+ options.console ? { type: "console" } : undefined,
36883
+ options.log ? { type: "log" } : undefined
36884
+ ];
36885
+ const selected = candidates.filter((selection) => selection !== undefined);
36886
+ return selected.length === 1 ? selected[0] : {
36887
+ error: "Choose exactly one evidence selector: --action, --timeline, --network, --request, --snapshot, --screenshot, --console, or --log."
36888
+ };
36889
+ }
36890
+
36891
+ // src/commands/attempt/index.ts
36892
+ function parseFormat(value) {
36893
+ if (value === "html" || value === "text")
36894
+ return value;
36895
+ throw new Error("Expected text or html.");
36896
+ }
36897
+ function registerAttemptCommand(program, signals) {
36898
+ const attempt = program.command("attempt").description("Investigate a finished run attempt from recorded evidence");
36899
+ declareCommandKind(attempt.command("investigate"), "read").description("Summarize the evidence for one finished attempt").requiredOption("--attempt-id <id>", "Attempt to summarize").action((options, command) => withAuthContext(signals, (ctx) => handleInvestigationSummary(ctx, options.attemptId))(options, command));
36900
+ declareCommandKind(attempt.command("inspect"), "read").description("Inspect one kind of evidence for a finished attempt").requiredOption("--attempt-id <id>", "Attempt to inspect").option("--action <id>", "Inspect one action evidence ID").option("--timeline", "Inspect the action timeline").option("--network", "Inspect network requests").option("--request <id>", "Inspect one network request evidence ID").option("--snapshot <id>", "Inspect one page snapshot evidence ID").option("--screenshot <id>", "Export one screenshot evidence ID").option("--console", "Inspect browser console evidence").option("--log", "Inspect execution log evidence").option("--evidence-id <id>", "Return only this console or log record").option("--limit <number>", "Maximum entries to return, 20 by default and up to 100: the most recent for --timeline, --network and --log, the earliest for --console").option("--start-time-ms <number>", "Earliest trace timestamp in milliseconds").option("--end-time-ms <number>", "Latest trace timestamp in milliseconds").option("--start-timestamp <iso>", "Earliest execution log timestamp").option("--end-timestamp <iso>", "Latest execution log timestamp").addOption(new Option2("--source <source>", "Execution log source").choices([
36901
+ "qawolfTraceCollection",
36902
+ "serverConsole"
36903
+ ])).option("--method <method>", "Network HTTP method").option("--status <code>", "Network HTTP status").option("--url-contains <text>", "Network URL substring").option("--format <format>", "Snapshot format (text or html)", parseFormat, "text").option("--output-file <path>", "Write HTML or screenshot bytes without overwriting").action((options, command) => {
36904
+ const selection = resolveInspectSelection(options);
36905
+ if ("error" in selection)
36906
+ return command.error(selection.error);
36907
+ const {
36908
+ action: _action,
36909
+ console: _console,
36910
+ log: _log,
36911
+ network: _network,
36912
+ request: _request,
36913
+ screenshot: _screenshot,
36914
+ snapshot: _snapshot,
36915
+ timeline: _timeline,
36916
+ ...common
36917
+ } = options;
36918
+ const normalized = { ...common, ...selection };
36919
+ return withAuthContext(signals, (ctx) => handleInvestigationInspect(ctx, normalized))(options, command);
36920
+ });
36921
+ }
36922
+
36280
36923
  // src/core/publicApi/flagNames.ts
36281
36924
  var kebabCase = (segment) => segment.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
36282
36925
  var capitalize = (segment) => `${segment.slice(0, 1).toUpperCase()}${segment.slice(1)}`;
@@ -37422,6 +38065,338 @@ function runnerDeps(ctx) {
37422
38065
  });
37423
38066
  }
37424
38067
 
38068
+ // src/commands/runner/guides/act.txt
38069
+ var act_default = `# Seeing and acting
38070
+
38071
+ There is no hosted vision loop: you look with screenshot, decide with your own model, and act. act performs exactly one action per call, in the computer-use tool vocabulary a vision model already emits. The names and the field names are unchanged from that vocabulary on purpose, so you can forward a tool call rather than translate it with \`act -\`.
38072
+
38073
+ Every action in a see-and-act loop is followed by a look at the result, so ask for it in the same call with --screenshot. Prefer it over act and then screenshot: each step is one call instead of two, with no delay to guess at between them. The screen the runner answers with is taken once it has changed from just before the action or half a second has passed, whichever comes first. An action that reached the screen and did not take effect answers with one too, so an exit 1 still leaves you a picture of why the click missed. A 4 whose message starts with "Performed" means the action happened and only the picture is missing: take a screenshot, never send the action again to get it. As with \`screenshot --out -\`, a terminal on stdout is refused.
38074
+
38075
+ Coordinates are pixels on the same screenshot you just read. The runner serves one see-or-act request at a time, so never have two in flight; when the next few steps are already known, send them as one \`runner actions\` sequence instead. Bounds are checked before anything is sent, so an over-long --text or an out-of-range coordinate comes back immediately naming the limit.
38076
+
38077
+ On a 4, the answer may have been lost with the action in flight: take a screenshot before repeating a click, and repeat only what the screen says did not happen.
38078
+
38079
+ # Mobile
38080
+
38081
+ A mobile runner has a touchscreen, not a mouse, so it has actions of its own:
38082
+ - tap touches a point (--x, --y) or the element --selector names. Check the selector first with \`inspect elements --selector\`, and pass --strategy ios-predicate or shadow when it is not XPath.
38083
+ - swipe --from x,y --to x,y moves in a straight line between two points. --duration-ms sets how long it takes, up to 10000: a slow swipe scrolls, a fast one flings.
38084
+ - fill --selector ... --text ... replaces the value of that field, and --text "" clears it. To add to what a field already holds, tap it and then type.
38085
+ - type types into whatever the last tap focused, the same as on a browser.
38086
+
38087
+ On mobile, send tap and swipe, never click or drag. The other browser actions, double_click, scroll, move, keypress and navigate, answer action-not-supported-on-mobile rather than doing something approximate. navigate is the one to watch for, since it works on a browser runner without a run first but has no meaning on mobile at all. A browser runner answers tap, swipe and fill with action-not-supported-on-browser.
38088
+
38089
+ # Before the first run
38090
+
38091
+ 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.
38092
+ `;
38093
+
38094
+ // src/commands/runner/guides/actions.txt
38095
+ var actions_default = `# Batching
38096
+
38097
+ Use a sequence for the steps you already know: click the field, type into it, press Enter. One round trip instead of three, with no delay to guess at between them. On a mobile runner the steps are tap, swipe, fill and type, the same as act, and a step the runner does not take fails with the same reason act would give, action-not-supported-on-mobile or action-not-supported-on-browser.
38098
+
38099
+ Batch only steps whose targets are all on the screen you last saw and are not moved by the steps before them, and make the step that changes the page, a submit, a navigation, opening a menu, the last one. Then read the frame and decide the next batch from it.
38100
+
38101
+ # Screenshots
38102
+
38103
+ --screenshot after.jpg writes the screen after the last action, as \`act --screenshot\` does, and - puts those bytes on stdout with the confirmation on stderr. Stdout then carries the image and nothing else, so - trades the per-action results for the frame: give --screenshot a file path whenever you need to read \`effect\` per action. --screenshot-mode each --screenshot step.jpg writes one frame per action instead, step-0.jpg, step-1.jpg and so on; each is a full image, so keep those sequences short.
38104
+
38105
+ # Reading the answer
38106
+
38107
+ The answer holds one entry per action reached, and the field to read on each is \`effect\`:
38108
+ - performed means the runner did it.
38109
+ - not-performed means the runner answered that it did not take effect.
38110
+ - unknown means the runner stopped answering with the action in flight, or its screen went quiet mid-action, so it may have taken effect. Take a screenshot before repeating anything from that step on, and never send it again blind.
38111
+
38112
+ The sequence stops at the first action that fails. --continue-on-failure carries on past one that reached the runner and did not take effect, which is only safe for actions that do not depend on each other: a type after a failed click goes to whatever has focus. A runner that cannot be reached, a screen that cannot serve, or running out of time ends the sequence either way, and the message names every action that did not succeed.
38113
+
38114
+ # Exit codes
38115
+
38116
+ A sequence exits by the worst thing that happened to any one of its actions: an effect nobody can confirm (4) first, then running out of time (6), then a refusal (2), then an action that plainly did not happen (1). Whatever the code, the message names the last action that took effect, and only what follows it goes in a new request. A sequence also exits 2 before it sends anything for an argument that is not a JSON array, an array of more than ten actions, and --screenshot flags that contradict each other.
38117
+ `;
38118
+
38119
+ // src/commands/runner/guides/events.txt
38120
+ var events_default = `# Streams
38121
+
38122
+ Everything observable is an append-only stream on the pod, read by cursor or tail rather than subscribed to, so attaching late still gets you the history that is still there. QA Wolf writes recorder, console, run-events, run-logs and run-status; a stream nobody has written reads as empty rather than as an error, and a stream this CLI version does not know about is still readable by name. One payload per line, so shell tools compose:
38123
+
38124
+ $ qawolf runner events console --tail 20 | jq -r '.message'
38125
+ $ qawolf runner events run-logs --run <runId> --follow > run.log
38126
+
38127
+ --tail N takes the newest N, --since <sequence> reads everything after a cursor, and --run <id> narrows the run-scoped streams.
38128
+
38129
+ History is not unbounded: a size cap drops the oldest entries on a long-lived runner, and a --tail N read can stop early and hand back fewer than N even when more matched. Both are warned about on stderr, dropped entries only once a read holds a cursor, a stopped-early read with a pointer at --since. Watch stderr, treat a short answer as "at least this" rather than "all there was", and read what you care about as you go rather than at the end.
38130
+
38131
+ # The recorder
38132
+
38133
+ \`events recorder\` is what has no equivalent in a screenshot. As you drive the browser, the runner records each interaction and publishes \`locator\` (the real Playwright locator it resolved), \`alternates\` (the others that matched the same element) and \`code\` (the generated Playwright call), alongside \`type\`, \`sourceUrl\` and \`timestamp\`:
38134
+
38135
+ $ qawolf runner events recorder --tail 5 | jq -r '.code // .type'
38136
+ $ qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
38137
+
38138
+ \`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.
38139
+
38140
+ # Following
38141
+
38142
+ --follow polls and prints as entries arrive. It is tail -f with a bound: it ends only at its --timeout (an hour by default, exit 6), because reading keeps the runner alive and billing. It does not end when a run settles, so it cannot be used to wait for a run: use \`runner run --follow\`, or poll run-status. Redirect it to a file and stop it yourself, or use repeated --since reads when you need the command to end sooner.
38143
+
38144
+ Where --follow wins is the cursor. The pod reports how far a read scanned rather than how far it matched, and --follow carries that number, so a filtered read that matched nothing still moves forward. A caller paging by hand cannot see it, because the CLI does not print it, and the best available substitute is the highest \`sequence\` you actually saw. So a narrow --run filter over a busy stream stalls: with nothing matching, there is no new \`sequence\` to move on to, and you re-read the same window until something matches.
38145
+
38146
+ events never launches a runner.
38147
+ `;
38148
+
38149
+ // src/commands/runner/guides/exec.txt
38150
+ var exec_default = `# Getting a value back
38151
+
38152
+ exec does not return what the snippet evaluated to, only whether it ran. To get a value back, print it and read the \`console\` stream with \`qawolf runner events console\`. Print it behind a marker you chose, and match on that rather than taking the newest line: the page logs to the same stream, so anything it prints after your snippet would be what --tail 1 hands back. Entries carry \`source\`, which is \`serverConsole\` for your snippet and \`browserConsole\` for the page, so filtering on both is what pins the value down:
38153
+
38154
+ $ echo 'console.log("qw-title:", await page.title())' | qawolf runner exec -
38155
+ $ qawolf runner events console --tail 20 | jq -r 'select(.source == "serverConsole" and (.message | contains("qw-title:"))) | .message'
38156
+
38157
+ To read a top-level variable of the running workflow, \`qawolf runner inspect variable\` is one call and the value, where exec is two calls and a marker.
38158
+
38159
+ # Scope
38160
+
38161
+ The snippet imports nothing of yours by default. Pass --file <path> to evaluate it in that file's scope, which also ships the directory's other files, so the snippet can use your own page objects and helpers.
38162
+
38163
+ # Failures
38164
+
38165
+ 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.
38166
+ `;
38167
+
38168
+ // src/commands/runner/guides/formatGuide.ts
38169
+ var guideWidth = 80;
38170
+ function wrapWords(text, firstPrefix, restPrefix) {
38171
+ const words = text.split(/\s+/).filter((word) => word.length > 0);
38172
+ return words.reduce((lines, word) => {
38173
+ const last = lines.at(-1);
38174
+ if (last === undefined)
38175
+ return [`${firstPrefix}${word}`];
38176
+ if (last.length + 1 + word.length <= guideWidth) {
38177
+ return [...lines.slice(0, -1), `${last} ${word}`];
38178
+ }
38179
+ return [...lines, `${restPrefix}${word}`];
38180
+ }, []);
38181
+ }
38182
+ function formatLine(line) {
38183
+ if (line.startsWith("# "))
38184
+ return [`${line.slice(2)}:`];
38185
+ if (line.startsWith("$ "))
38186
+ return [` ${line}`];
38187
+ if (line.startsWith("- "))
38188
+ return wrapWords(line.slice(2), " - ", " ");
38189
+ return wrapWords(line, " ", " ");
38190
+ }
38191
+ function formatGuide(source) {
38192
+ const paragraphs = source.trim().split(/\n\s*\n/).map((paragraph) => paragraph.split(`
38193
+ `));
38194
+ const rendered = paragraphs.map((lines, index) => {
38195
+ const text = lines.flatMap(formatLine).join(`
38196
+ `);
38197
+ const followsTitle = paragraphs[index - 1]?.[0]?.startsWith("# ") === true;
38198
+ return index === 0 ? text : `${followsTitle ? `
38199
+ ` : `
38200
+
38201
+ `}${text}`;
38202
+ });
38203
+ return `
38204
+ ${rendered.join("")}`;
38205
+ }
38206
+
38207
+ // src/commands/runner/guides/highlightSelector.txt
38208
+ var highlightSelector_default = `# Reading the result
38209
+
38210
+ \`inspect element-html\` tells you what a selector matched; highlight-selector shows you where it is, by drawing on the page itself. The highlight stays until it is replaced or cleared, which is the point: you cannot see the runner's screen, so the only way to read the result is the next screenshot.
38211
+
38212
+ Three answers are worth telling apart. A selector that matched prints how many elements it hit and exits 0. A selector the page read fine but that matched nothing also exits 0, because the call did what was asked and the count is the answer; the message says the syntax was fine so you look at the page, not the locator. A selector the page could not read at all exits 2, because that one is yours to correct and retrying will not change it.
38213
+
38214
+ runner-cannot-highlight-selectors exits 2 and means the runner has no browser to draw on. no-answer exits 4: a highlight runs inside the page, so a page that is gone or mid-navigation does not answer at all rather than answering slowly.
38215
+ `;
38216
+
38217
+ // src/commands/runner/guides/importPackage.txt
38218
+ var importPackage_default = `# Installing mid-session
38219
+
38220
+ The package goes into the runner's live run, so a snippet or a selection can import it without a whole run to reinstall dependencies. The flag is --package-version because --version belongs to the CLI itself. The install resolves against your project's own dependencies, read from package.json, so it needs a run already going: there is no live run on a runner that has not run anything. npm's own refusal comes back verbatim on an exit 2, which is a name or a version to correct rather than something to retry.
38221
+ `;
38222
+
38223
+ // src/commands/runner/guides/inspect.txt
38224
+ var inspect_default = `# Browser
38225
+
38226
+ inspect answers one question about the live page and prints the answer on stdout by itself, so you can redirect or pipe it. \`page-html\` is simplified for a model to read rather than being the browser's exact markup, and --selector narrows it to one subtree. \`variable\` reads a top-level variable of the running workflow and prints it as JSON, which is how you see what your own code computed rather than what the page shows. Use it before reaching for exec: reading a value through a snippet means printing it and then fishing it back out of the console stream, which is two calls and a marker.
38227
+
38228
+ One failure covers three causes, because a runner cannot tell them apart: no live page, no element matching the selector, no variable under that name. All three exit 2 and none clears by waiting, so read the message, which carries whatever the runner said. An unreachable runner exits 4 and is worth retrying; a runner that is not running at all exits 8 and is not.
38229
+
38230
+ # Mobile
38231
+
38232
+ element-html and page-html are a browser's shapes, and a mobile runner answers them with runner-is-not-a-browser. It answers session, contexts, page-source and elements instead, and variable works on both.
38233
+
38234
+ session prints one summary line, ready or why not, because that line is the whole answer. contexts, page-source and elements print their answer as JSON on stdout, on its own, so you can pipe it (| jq .current, | jq .matches, | jq .pageSource) rather than getting a count with no way to see what was found.
38235
+
38236
+ session is the one subcommand that never answers screen-needs-a-run: readiness is the question it exists to answer, so it reports ready (with the platform, device and session id), unreachable, ambiguous (more than one session is somehow live) or no-session. The other three need a live session first. screen-needs-a-run exits 2 and means no Appium session has started on this runner yet: run a flow that opens one, then inspect again. screen-not-ready exits 4 and means the session exists but did not answer this instant, or more than one is somehow live: retry once, and relaunch the runner if it persists.
38237
+
38238
+ elements takes one of three ways to search: whole-pixel --x/--y on the device's own screen, the same coordinates a screenshot is measured in; --text, which matches exactly unless --partial is passed; or --selector, resolved the same way a screen object's own selector is, with --strategy naming how (xpath, ios-predicate or shadow; defaults to xpath). Prefer --selector when checking a selector you are about to write: it answers what that exact string resolves to, where --text and --x/--y only approximate it. The three do not mix: flags from more than one are refused before a runner is addressed. An unparseable selector answers invalid-selector, exit 2, distinctly from a selector that parsed fine but matched nothing, which answers an empty \`matches\` list, exit 0. --context on page-source or elements reads a context other than the current one, once contexts has told you which are available.
38239
+
38240
+ A browser runner answers runner-is-not-mobile to session, contexts, page-source and elements, exit 2, since retrying never helps: launch with --name android or --name ios instead. runner-unreachable exits 4 and is worth retrying.
38241
+ `;
38242
+
38243
+ // src/commands/runner/guides/keepalive.txt
38244
+ var keepalive_default = `# When to call it
38245
+
38246
+ A runner is reaped after a period of inactivity, and every command that talks to the runner counts as activity, including a journal read. keepalive exists for the gap that creates: a harness that thinks, or waits on a human, for minutes between actions would otherwise come back to a pod that is gone. It resets the clock and tells you the runner is still there. It never launches a runner.
38247
+
38248
+ It is a read with a cost: keeping the clock reset keeps a billed pod alive. Call it while you are genuinely still working, not on a timer you forget, and call \`qawolf runner terminate\` when you are done rather than leaving a pod to time out. A loop that keeps a runner alive and never stops it bills until someone notices.
38249
+ `;
38250
+
38251
+ // src/commands/runner/guides/launch.txt
38252
+ var launch_default = `# Ids
38253
+
38254
+ 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.
38255
+
38256
+ 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.
38257
+
38258
+ 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.
38259
+
38260
+ # The page
38261
+
38262
+ 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.
38263
+
38264
+ # Browser or mobile
38265
+
38266
+ --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.
38267
+ `;
38268
+
38269
+ // src/commands/runner/guides/list.txt
38270
+ var list_default = `# What the list holds
38271
+
38272
+ 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.
38273
+
38274
+ 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.
38275
+
38276
+ Nothing is billed by listing, but everything in the list is billing. Terminate what you are done with.
38277
+
38278
+ The table leaves out the page address, which beside a 63-character id outgrows a terminal. --json carries it as \`url\` on every runner:
38279
+
38280
+ $ qawolf runner list --json | jq -r '.[] | [.id, .url] | @tsv'
38281
+ `;
38282
+
38283
+ // src/commands/runner/guides/listRecordings.txt
38284
+ var listRecordings_default = "# Reading pages\n\n$ qawolf runner list-recordings --runner ci --json\n$ qawolf runner list-recordings --runner ci --recording-id <uuid> --json\n$ qawolf runner list-recordings --runner ci --page-token '<nextPageToken>' --json\n\nEach response is one page with `recordings` and an optional `nextPageToken`. Follow that token for more; the order is storage-key order, not newest-first. Entries include status, run ids, a stable platform `url`, and an expiring `videoUrl` when video is available. An empty lookup means the recording has not been published or does not exist. Abrupt runner loss may leave video unavailable. Keep the runner id for history lookups after termination clears the local default.\n";
38285
+
38286
+ // src/commands/runner/guides/promoteSnapshot.txt
38287
+ var promoteSnapshot_default = `# Paths
38288
+
38289
+ Use it when a run's image diff fails and the new screenshot is the one you want. Both paths are the ones the diff reported in its imageDiffArtifact run event, and both are named rather than positional, because two paths with one unlabelled is easy to get backwards and swapping them promotes the wrong image. They are paths inside the run's own screenshot storage, not files on your machine.
38290
+
38291
+ snapshot-not-found exits 2 and means the run wrote no screenshot at that path, which nearly always means the paths did not come from a diff this run produced. Nothing is changed, so correcting the path and repeating is safe. Promoting twice is also safe, so an unreachable runner is worth retrying.
38292
+ `;
38293
+
38294
+ // src/commands/runner/guides/record.txt
38295
+ var record_default = `# Recording
38296
+
38297
+ Start a flow first so the runner has a screen, then start a manual capture and keep \`result.state.active.id\` from the \`record start --json\` answer to stop that capture:
38298
+
38299
+ $ qawolf runner record start --runner ci --json
38300
+ $ qawolf runner record stop <recording-id> --runner ci
38301
+ $ qawolf runner record status --runner ci
38302
+ $ qawolf runner record auto on --runner ci
38303
+
38304
+ Start generates a UUID unless you pass --recording-id <uuid>. If a start response is lost, the error includes that UUID: check \`record status\` and reuse the UUID when retrying. Stop always names a specific recording, so retrying it cannot stop a later capture. Manual recordings span runs and suppress automatic capture until stopped. The auto setting affects subsequent full runs. An active automatic recording ends with its run; \`record stop\` cannot interrupt it. If a stop publishes a recording with status "failed", the CLI exits 1 and still prints the manifest so callers can inspect it.
38305
+
38306
+ Published recordings stay readable after the runner terminates, with \`qawolf runner list-recordings\`.
38307
+ `;
38308
+
38309
+ // src/commands/runner/guides/run.txt
38310
+ var run_default = `# What travels
38311
+
38312
+ run ships the flow file, everything it imports, and your package.json and tsconfig.json. Nothing else travels, so you can run from the root of a large project without sending it. The runner holds no copy of your project, so what runs is exactly what is on disk at that moment, uncommitted edits included.
38313
+
38314
+ Imports are followed the same way a run from the QA Wolf app follows them: relative paths and tsconfig.json path aliases, resolving .ts and .js. An \`export ... from\` re-export is not followed, and neither is require(), so a barrel file does not pull in what it re-exports. A package.json has to be there, since the run reads its npm dependencies from it, and the files may carry at most 30 MiB in total. A missing file, a missing package.json and files over the cap are all refused before any runner is resolved or launched, so a typo costs nothing.
38315
+
38316
+ After the first run on a runner, later runs send only the files whose content changed, so iterating on one flow costs a small request rather than the whole graph again. --json reports which happened in \`fileSync\`: delta or full. Nothing about this needs managing: the baseline lives in .qawolf/runner-files.json, a switch to another runner ignores it, and a runner that turns out not to hold what was claimed gets the whole set resent automatically.
38317
+
38318
+ # Waiting for the outcome
38319
+
38320
+ The call answers with a run id as soon as the run is accepted. The outcome is not in that answer; it is in the run-status stream, whose entries carry \`runId\`, \`status\` and an \`errorMessage\` when there is one.
38321
+
38322
+ Pass --follow and let run wait for you. It reports the run's status, in progress, then passed or failed, and ends on the settled status. Exit 1 means the run did not pass. --logs, --run-events and --recorder-events mirror more streams into the follow, and each implies --follow on its own. The recorder is runner-wide rather than run-scoped, so --recorder-events carries whatever is recorded after an anchor taken just before submission. Whatever mirrors are on, the follow still ends on the status, never on them, so a run that prints nothing still ends the follow and a run that dies mid-sentence still reports how. Combining mirror flags interleaves their lines with nothing saying which stream a line came from: fine for eyeballs; when parsing, follow one stream at a time.
38323
+
38324
+ To submit and come back later, poll with the same rule the CLI uses: \`status\` is in-progress while the run is going, and any other value means it has settled. \`events --follow\` does not end when the run settles, so it cannot be used to wait for one.
38325
+
38326
+ $ qawolf runner run flows/checkout.flow.ts --json
38327
+ $ qawolf runner events run-status --run <runId> --tail 1 | jq -r '.status'
38328
+
38329
+ # When the runner could not be reached
38330
+
38331
+ If run reports that the runner could not be reached, that does not mean the run did not start. The runner may have accepted it and been too slow to answer, and resubmitting bills and journals a second run.
38332
+
38333
+ There is no clean recovery. The journal lives on the same pod, so while the runner stays unreachable a run-status read fails the same way. Wait for the runner to answer again, then read run-status without --run and look at the newest \`runId\`. Nothing ties that id back to your submission, and a runner takes work from anyone addressing it, so treat the newest id as your run only if you know nothing else submits to this runner. An empty read is not proof the run did not start either: run returns the moment the run is accepted, and its first run-status entry may not be written yet. A resubmit always risks a second billed run, so prefer polling run-status a while longer, and only submit again once you are willing to accept that risk.
38334
+
38335
+ # Running part of a flow
38336
+
38337
+ --lines 12-40 runs those lines against the browser as it stands, so nothing is re-navigated and nothing is signed in again. Use it to iterate on a step without paying for the whole flow to reach it again.
38338
+
38339
+ The two file paths are the thing to get right, because getting them backwards runs the wrong code and nothing reports it:
38340
+ - the positional is always the flow file. It is the run's entry point, and it is required for every run, selection or not.
38341
+ - --lines-file is where the lines live. It defaults to the positional, so pass it only when the range is in another file, typically a page object whose method you want to run against the instance your last run left alive.
38342
+
38343
+ The lines-file has to be one of the files that travel, so it lives under the directory you run from. A range whose file is not collected is refused before a runner is addressed, naming the path.
38344
+
38345
+ A --lines selection is the one call that does not need a run first. If the runner had no browser, one is started before your lines run, and the command says so on stderr. Those lines then ran against a fresh page rather than the one an earlier run left, which is worth reading before you act on what you see.
38346
+
38347
+ # Environment variables
38348
+
38349
+ A run takes one of two. --env-id names a QA Wolf environment by id or alias, the same reference \`qawolf flows\` takes as --env. --env-file .env gives the run the variables in a dotenv file, in the format \`qawolf flows pull\` writes. Passing both is refused: each gives the run its whole environment, so there is no order in which they would combine.
38350
+
38351
+ A run with neither flag falls back to QAWOLF_ENVIRONMENT, the same variable \`qawolf flows\` reads, so one export covers both. The run says on stderr which environment it picked up, because those variables reach your flow's code and a run should never be given an environment silently. --env-id wins over it, and --env-file suppresses it, so a run reading a dotenv file is not handed a second environment on top.
38352
+
38353
+ Prefer --env-id. QA Wolf reads and decrypts the environment itself, so the values never leave the server, nothing has to be pulled to disk first, and no size limit applies to them. It is the only way to run a flow whose environment holds something large, such as a session cookie.
38354
+
38355
+ A run that sends its own variables with --env-file may carry at most 200 of them, each value at most 16 KiB. Names follow what a shell accepts, and QAWOLF_TEAM_ID is reserved because QA Wolf sets it from the key you authenticated with. All of that is refused before a runner is addressed, naming the variable at fault.
38356
+ `;
38357
+
38358
+ // src/commands/runner/guides/screenshot.txt
38359
+ var screenshot_default = `# Reading the screen
38360
+
38361
+ 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.
38362
+
38363
+ 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.
38364
+ `;
38365
+
38366
+ // src/commands/runner/guides/stopOrTerminate.txt
38367
+ var stopOrTerminate_default = `# Stopping a run or ending a runner
38368
+
38369
+ Two different things, and the names are the only warning you get:
38370
+ - stop-run stops what the runner is executing and leaves the runner up, its browser on whatever page the run reached. The run settles as stopped rather than passed or failed. Use it to abandon a run and keep the browser you were working against.
38371
+ - terminate ends the runner and the pod with it. Everything on it is gone, and the next command under that id launches and bills a new one.
38372
+
38373
+ Both succeed when there was nothing to do, and say which: \`wasRunning\` is false when no run was going, and when no runner was running. Neither is an error, so a retry needs no special handling. terminate never launches a runner in order to end it.
38374
+ `;
38375
+
38376
+ // src/commands/runner/guides/workflow.md
38377
+ 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";
38378
+
38379
+ // src/commands/runner/guides/index.ts
38380
+ var runnerGuides = {
38381
+ act: formatGuide(act_default),
38382
+ actions: formatGuide(actions_default),
38383
+ events: formatGuide(events_default),
38384
+ exec: formatGuide(exec_default),
38385
+ highlightSelector: formatGuide(highlightSelector_default),
38386
+ importPackage: formatGuide(importPackage_default),
38387
+ inspect: formatGuide(inspect_default),
38388
+ keepalive: formatGuide(keepalive_default),
38389
+ launch: formatGuide(launch_default),
38390
+ list: formatGuide(list_default),
38391
+ listRecordings: formatGuide(listRecordings_default),
38392
+ promoteSnapshot: formatGuide(promoteSnapshot_default),
38393
+ record: formatGuide(record_default),
38394
+ run: formatGuide(run_default),
38395
+ screenshot: formatGuide(screenshot_default),
38396
+ stopOrTerminate: formatGuide(stopOrTerminate_default)
38397
+ };
38398
+ var runnerWorkflowGuide = workflow_default;
38399
+
37425
38400
  // src/commands/runner/actions.register.ts
37426
38401
  var actionsExamples = `
37427
38402
  Examples:
@@ -37434,7 +38409,7 @@ Mobile:
37434
38409
  $ qawolf runner actions '[{"type":"tap","selector":"//*[@content-desc=\\"Email\\"]"},{"type":"type","text":"hello@example.com"},{"type":"tap","x":540,"y":1650}]' --screenshot after-login.jpg
37435
38410
  $ qawolf runner actions '[{"type":"fill","selector":"name == \\"Postal code\\"","strategy":"ios-predicate","text":"94107"},{"type":"swipe","from":{"x":540,"y":1600},"to":{"x":540,"y":600}}]'`;
37436
38411
  function registerRunnerActionsCommand(runner, signals) {
37437
- declareCommandKind(runner.command("actions <sequence>"), "write").description("Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back, so batch only steps whose targets are on the screen you last saw, and end the sequence at the step that changes the page. Each result carries an effect: performed, not-performed, or unknown when the runner stopped answering and the action may have landed").option("--continue-on-failure", "Carry on past an action that reached the runner and did not take effect; a runner that cannot be reached or a screen that cannot serve still ends the sequence").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Save a JPEG of the screen after the last action to this file. With --screenshot-mode each, one file per action, with the action's index before the extension. - writes the final frame to stdout and moves the confirmation to stderr").addOption(new Option2("--screenshot-mode <mode>", "Defaults to final when --screenshot is given, none otherwise").choices([...screenshotModes])).addHelpText("after", actionsExamples).action((sequence, opts, command) => withAuthContext(signals, (ctx) => handleRunnerActions(ctx, {
38412
+ declareCommandKind(runner.command("actions <sequence>"), "write").description("Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back, so batch only steps whose targets are on the screen you last saw, and end the sequence at the step that changes the page. Each result carries an effect: performed, not-performed, or unknown when the runner stopped answering and the action may have landed").option("--continue-on-failure", "Carry on past an action that reached the runner and did not take effect; a runner that cannot be reached or a screen that cannot serve still ends the sequence").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Save a JPEG of the screen after the last action to this file. With --screenshot-mode each, one file per action, with the action's index before the extension. - writes the final frame to stdout and moves the confirmation to stderr").addOption(new Option2("--screenshot-mode <mode>", "Defaults to final when --screenshot is given, none otherwise").choices([...screenshotModes])).addHelpText("after", actionsExamples).addHelpText("after", runnerGuides.actions).action((sequence, opts, command) => withAuthContext(signals, (ctx) => handleRunnerActions(ctx, {
37438
38413
  actions: sequence,
37439
38414
  continueOnFailure: opts.continueOnFailure === true,
37440
38415
  runner: opts.runner,
@@ -37605,7 +38580,7 @@ Examples:
37605
38580
  $ echo 'console.log(await page.title())' | qawolf runner exec -
37606
38581
  $ qawolf runner exec snippet.ts --file flows/checkout.flow.ts`;
37607
38582
  function registerRunnerExecCommand(runner, signals) {
37608
- declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).action((file, opts, command) => withAuthContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file }, runnerDeps(ctx)))(opts, command));
38583
+ declareCommandKind(runner.command("exec <file>"), "write").description("Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin").option("--file <path>", "File whose scope the snippet is evaluated in; it and the directory's other files travel with it").option("--runner <id>", runnerFlagDescription).addHelpText("after", execExamples).addHelpText("after", runnerGuides.exec).action((file, opts, command) => withAuthContext(signals, (ctx) => handleRunnerExec(ctx, { contextFile: opts.file, runner: opts.runner, source: file }, runnerDeps(ctx)))(opts, command));
37609
38584
  }
37610
38585
 
37611
38586
  // src/domains/interactiveRunner/highlightSelector.ts
@@ -37680,7 +38655,7 @@ Examples:
37680
38655
  $ qawolf runner highlight-selector "#checkout" && qawolf runner screenshot
37681
38656
  $ qawolf runner highlight-selector`;
37682
38657
  function registerRunnerHighlightSelectorCommand(runner, signals) {
37683
- declareCommandKind(runner.command("highlight-selector [selector]"), "write").description("Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight").option("--runner <id>", runnerFlagDescription).addHelpText("after", highlightExamples).action((selector, opts, command) => withAuthContext(signals, (ctx) => handleRunnerHighlightSelector(ctx, { runner: opts.runner, selector }, runnerDeps(ctx)))(opts, command));
38658
+ declareCommandKind(runner.command("highlight-selector [selector]"), "write").description("Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight").option("--runner <id>", runnerFlagDescription).addHelpText("after", highlightExamples).addHelpText("after", runnerGuides.highlightSelector).action((selector, opts, command) => withAuthContext(signals, (ctx) => handleRunnerHighlightSelector(ctx, { runner: opts.runner, selector }, runnerDeps(ctx)))(opts, command));
37684
38659
  }
37685
38660
 
37686
38661
  // src/domains/interactiveRunner/importPackage.ts
@@ -37791,7 +38766,7 @@ Examples:
37791
38766
  $ qawolf runner import-package dayjs
37792
38767
  $ qawolf runner import-package dayjs --package-version 1.11.13`;
37793
38768
  function registerRunnerImportPackageCommand(runner, signals) {
37794
- declareCommandKind(runner.command("import-package <name>"), "write").description("Install a package into a runner's live run, so a snippet or a selection can import it").option("--package-version <version>", "Version to install", "latest").option("--runner <id>", runnerFlagDescription).addHelpText("after", importPackageExamples).action((name, opts, command) => withAuthContext(signals, (ctx) => handleRunnerImportPackage(ctx, { name, runner: opts.runner, version: opts.packageVersion }, runnerDeps(ctx)))(opts, command));
38769
+ declareCommandKind(runner.command("import-package <name>"), "write").description("Install a package into a runner's live run, so a snippet or a selection can import it").option("--package-version <version>", "Version to install", "latest").option("--runner <id>", runnerFlagDescription).addHelpText("after", importPackageExamples).addHelpText("after", runnerGuides.importPackage).action((name, opts, command) => withAuthContext(signals, (ctx) => handleRunnerImportPackage(ctx, { name, runner: opts.runner, version: opts.packageVersion }, runnerDeps(ctx)))(opts, command));
37795
38770
  }
37796
38771
 
37797
38772
  // src/core/interactiveRunner/inspectRequest.ts
@@ -38051,7 +39026,7 @@ Examples:
38051
39026
  $ qawolf runner inspect elements --text "Sign in" --partial
38052
39027
  $ qawolf runner inspect elements --selector "//android.widget.Button[@text='Sign in']"`;
38053
39028
  function registerRunnerInspectCommands(runner, signals) {
38054
- const inspect = runner.command("inspect").description("Read one thing off a runner's live page (browser) or Appium session (mobile)").addHelpText("after", inspectExamples);
39029
+ const inspect = runner.command("inspect").description("Read one thing off a runner's live page (browser) or Appium session (mobile)").addHelpText("after", inspectExamples).addHelpText("after", runnerGuides.inspect);
38055
39030
  declareCommandKind(inspect.command("element-html"), "read").description("Print the HTML of the first element a selector matches").requiredOption("--selector <selector>", "Playwright selector to inspect").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerInspect(ctx, {
38056
39031
  flags: { name: undefined, selector: opts.selector },
38057
39032
  runner: opts.runner,
@@ -38345,8 +39320,8 @@ Examples:
38345
39320
  $ qawolf runner screenshot --out - > step-3.jpg
38346
39321
  $ qawolf runner screenshot --out - | my-vision-tool`;
38347
39322
  function registerRunnerInteractCommands(runner, signals) {
38348
- declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out -").option("--out <path>", "File to write the image to. - writes the JPEG bytes to stdout on their own and moves the confirmation, JSON included, to stderr", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
38349
- declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from stdin").option("--button <button>", "click: left, right, wheel, back or forward").option("--duration-ms <ms>", "swipe: how long it takes, up to 10000. Slow scrolls, fast flings").option("--from <x,y>", "swipe: the point it starts at").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Also save a JPEG of the screen, taken after the action, to this file, in place of a separate screenshot. An action that did not take effect answers with one too. - writes it to stdout and moves the confirmation, JSON included, to stderr").option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--selector <selector>", "tap or fill: the element to act on, as a screen object would find it. tap takes it in place of --x and --y").option("--strategy <strategy>", "how --selector is resolved: xpath (default), ios-predicate or shadow").option("--text <text>", "type: the text to type into what has focus. fill: the field's new value").option("--to <x,y>", "swipe: the point it ends at").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "click, tap and the like: x, in screenshot pixels").option("--y <pixels>", "click, tap and the like: y, in screenshot pixels").addHelpText("after", actExamples).action((action, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
39323
+ declareCommandKind(runner.command("screenshot"), "read").description("Save a JPEG of an interactive runner's screen to a file, or write it to stdout with --out -").option("--out <path>", "File to write the image to. - writes the JPEG bytes to stdout on their own and moves the confirmation, JSON included, to stderr", defaultScreenshotPath).option("--runner <id>", runnerFlagDescription).addHelpText("after", screenshotExamples).addHelpText("after", runnerGuides.screenshot).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerScreenshot(ctx, { out: opts.out, runner: opts.runner }, runnerDeps(ctx)))(opts, command));
39324
+ declareCommandKind(runner.command("act <action>"), "write").description("Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from stdin").option("--button <button>", "click: left, right, wheel, back or forward").option("--duration-ms <ms>", "swipe: how long it takes, up to 10000. Slow scrolls, fast flings").option("--from <x,y>", "swipe: the point it starts at").option("--keys <keys...>", "keypress: modifiers and the key, e.g. Control a").option("--path <json>", "drag: JSON array of points to drag through").option("--runner <id>", runnerFlagDescription).option("--screenshot <path>", "Also save a JPEG of the screen, taken after the action, to this file, in place of a separate screenshot. An action that did not take effect answers with one too. - writes it to stdout and moves the confirmation, JSON included, to stderr").option("--scroll-x <delta>", "scroll: horizontal wheel delta").option("--scroll-y <delta>", "scroll: vertical wheel delta").option("--selector <selector>", "tap or fill: the element to act on, as a screen object would find it. tap takes it in place of --x and --y").option("--strategy <strategy>", "how --selector is resolved: xpath (default), ios-predicate or shadow").option("--text <text>", "type: the text to type into what has focus. fill: the field's new value").option("--to <x,y>", "swipe: the point it ends at").option("--url <url>", "navigate: the http or https URL to go to").option("--x <pixels>", "click, tap and the like: x, in screenshot pixels").option("--y <pixels>", "click, tap and the like: y, in screenshot pixels").addHelpText("after", actExamples).addHelpText("after", runnerGuides.act).action((action, opts, command) => withAuthContext(signals, (ctx) => handleRunnerAct(ctx, {
38350
39325
  flags: {
38351
39326
  button: opts.button,
38352
39327
  durationMs: opts.durationMs,
@@ -38559,11 +39534,11 @@ Examples:
38559
39534
  $ qawolf runner keepalive
38560
39535
  $ qawolf runner keepalive --runner ci`;
38561
39536
  function registerRunnerLifecycleCommands(runner, signals) {
38562
- 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).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerLaunch(ctx, { id: opts.id, name: opts.name }, runnerDeps(ctx)))(opts, command));
38563
- declareCommandKind(runner.command("list"), "read").description("List the runners running on your team").option("--here", "Only the runners this directory launched").addHelpText("after", listExamples2).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerList(ctx, { here: opts.here === true }, runnerDeps(ctx)))(opts, command));
38564
- declareCommandKind(runner.command("terminate"), "write").description("End an interactive runner, and the pod it runs on with it").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerTerminate(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
38565
- declareCommandKind(runner.command("stop-run"), "write").description("Stop what a runner is currently executing, leaving the runner up").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerStopRun(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
38566
- 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).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerKeepalive(ctx, { runner: opts.runner }, runnerDeps(ctx)))(opts, command));
39537
+ 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));
39538
+ 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));
39539
+ 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));
39540
+ 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));
39541
+ 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));
38567
39542
  }
38568
39543
 
38569
39544
  // src/domains/interactiveRunner/promoteSnapshot.ts
@@ -38620,7 +39595,7 @@ Examples:
38620
39595
  $ qawolf runner promote-snapshot --screenshot checkout-1-actual.png --baseline checkout-1.png
38621
39596
  $ qawolf runner events run-events --tail 20 | jq 'select(.type == "imageDiffArtifact")'`;
38622
39597
  function registerRunnerPromoteSnapshotCommand(runner, signals) {
38623
- declareCommandKind(runner.command("promote-snapshot"), "write").description("Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it").requiredOption("--screenshot <path>", "The screenshot to promote, as the image diff named it").requiredOption("--baseline <path>", "The baseline to replace, as the image diff named it").option("--runner <id>", runnerFlagDescription).addHelpText("after", promoteSnapshotExamples).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerPromoteSnapshot(ctx, {
39598
+ declareCommandKind(runner.command("promote-snapshot"), "write").description("Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it").requiredOption("--screenshot <path>", "The screenshot to promote, as the image diff named it").requiredOption("--baseline <path>", "The baseline to replace, as the image diff named it").option("--runner <id>", runnerFlagDescription).addHelpText("after", promoteSnapshotExamples).addHelpText("after", runnerGuides.promoteSnapshot).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerPromoteSnapshot(ctx, {
38624
39599
  baselinePath: opts.baseline,
38625
39600
  runner: opts.runner,
38626
39601
  screenshotPath: opts.screenshot
@@ -38814,7 +39789,7 @@ Examples:
38814
39789
  $ qawolf runner events run-logs --run <runId> --follow
38815
39790
  $ qawolf runner events console --since 120 --json`;
38816
39791
  function registerRunnerEventsCommand(runner, signals) {
38817
- declareCommandKind(runner.command("events <stream>"), "read").description(`Print a runner's journal, one entry per line. QA Wolf writes ${knownJournalStreams.join(", ")}`).option("--follow", "Keep reading as new entries arrive. Reading counts as activity, so a follow left open keeps the runner alive and billing", false).option("--run <id>", "Restrict run-scoped streams to one run").option("--runner <id>", runnerFlagDescription).option("--since <sequence>", "Read entries after this sequence").option("--tail <count>", "Read only the newest <count> entries").option("--timeout <seconds>", "Give up following after this long. Reading keeps the runner alive, so a follow left open would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", eventsExamples).action((stream, opts, command) => withAuthContext(signals, (ctx) => handleRunnerEvents(ctx, {
39792
+ declareCommandKind(runner.command("events <stream>"), "read").description(`Print a runner's journal, one entry per line. QA Wolf writes ${knownJournalStreams.join(", ")}`).option("--follow", "Keep reading as new entries arrive. Reading counts as activity, so a follow left open keeps the runner alive and billing", false).option("--run <id>", "Restrict run-scoped streams to one run").option("--runner <id>", runnerFlagDescription).option("--since <sequence>", "Read entries after this sequence").option("--tail <count>", "Read only the newest <count> entries").option("--timeout <seconds>", "Give up following after this long. Reading keeps the runner alive, so a follow left open would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", eventsExamples).addHelpText("after", runnerGuides.events).action((stream, opts, command) => withAuthContext(signals, (ctx) => handleRunnerEvents(ctx, {
38818
39793
  envelope: Boolean(command.optsWithGlobals().json),
38819
39794
  follow: opts.follow,
38820
39795
  run: opts.run,
@@ -39284,7 +40259,7 @@ Examples:
39284
40259
  $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts
39285
40260
  $ qawolf runner run flows/checkout.flow.ts --env-id staging`;
39286
40261
  function registerRunCommand(runner, signals) {
39287
- declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).action((flowFile, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
40262
+ declareCommandKind(runner.command("run <flowFile>"), "write").description("Run a flow on an interactive runner, shipping the flow and what it imports").option("--follow", "Report the run's status until it settles: in progress, then passed or failed", false).option("--logs", "Stream every log line the run produces while following. Implies --follow", false).option("--run-events", "Stream the run's progress events as JSON lines while following. Implies --follow", false).option("--recorder-events", "Stream the browser actions the runner records as JSON lines while following, from an anchor taken just before submission: the recorder is runner-wide, not run-scoped. Implies --follow", false).option("--env-id <env>", "QA Wolf environment whose variables the run is given, by id or alias. Defaults to QAWOLF_ENVIRONMENT. QA Wolf reads and decrypts them itself, so they never leave the server and no size limit applies to them").option("--env-file <path>", "Dotenv file on this machine whose variables the run is given. Pass this or --env-id, not both").option("--lines <start-end>", "Run only these 1-indexed lines against the browser as it stands, instead of the whole flow from a fresh one").option("--lines-file <path>", "File the --lines range lives in. Defaults to <flowFile>; pass it only when the lines are in another file, such as a page object").option("--runner <id>", runnerFlagDescription).option("--timeout <seconds>", "Give up following after this long. Following keeps the runner alive, so a run that never settles would otherwise bill until the terminal closed", String(defaultFollowTimeoutSeconds)).addHelpText("after", runExamples2).addHelpText("after", runnerGuides.run).action((flowFile, opts, command) => withAuthContext(signals, (ctx) => handleRunnerRun(ctx, {
39288
40263
  entryPoint: flowFile,
39289
40264
  envFile: opts.envFile,
39290
40265
  envId: opts.envId,
@@ -39473,7 +40448,7 @@ async function handleRunnerRecordings(ctx, options, deps) {
39473
40448
 
39474
40449
  // src/commands/runner/recording.register.ts
39475
40450
  function registerRunnerRecordingCommands(runner, signals) {
39476
- const record = runner.command("record").description("Control video recording on a Playwright runner");
40451
+ const record = runner.command("record").description("Control video recording on a Playwright runner").addHelpText("after", runnerGuides.record);
39477
40452
  declareCommandKind(record.command("start"), "write").description("Start manual video capture across runs. Requires a ready screen and suppresses automatic capture until stopped").option("--recording-id <uuid>", "Recording UUID. Generated when omitted; reuse it when retrying this start").option("--runner <id>", runnerFlagDescription).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecord(ctx, {
39478
40453
  command: { action: "start", recordingId: opts.recordingId },
39479
40454
  runner: opts.runner
@@ -39493,7 +40468,7 @@ function registerRunnerRecordingCommands(runner, signals) {
39493
40468
  command: { action: "auto", enabled: setting === "on" },
39494
40469
  runner: opts.runner
39495
40470
  }, runnerDeps(ctx)))(opts, command));
39496
- declareCommandKind(runner.command("list-recordings"), "read").description("Read a page of published video recordings, including after the runner terminates. Platform URLs persist; video URLs expire").option("--runner <id>", runnerFlagDescription).option("--recording-id <uuid>", "Look up one recording; an empty result means it is not published or does not exist").option("--page-token <token>", "Continue from nextPageToken returned by the previous page").action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecordings(ctx, {
40471
+ declareCommandKind(runner.command("list-recordings"), "read").description("Read a page of published video recordings, including after the runner terminates. Platform URLs persist; video URLs expire").option("--runner <id>", runnerFlagDescription).option("--recording-id <uuid>", "Look up one recording; an empty result means it is not published or does not exist").option("--page-token <token>", "Continue from nextPageToken returned by the previous page").addHelpText("after", runnerGuides.listRecordings).action((opts, command) => withAuthContext(signals, (ctx) => handleRunnerRecordings(ctx, {
39497
40472
  runner: opts.runner,
39498
40473
  ...opts.recordingId === undefined ? {} : { recordingId: opts.recordingId },
39499
40474
  ...opts.pageToken === undefined ? {} : { pageToken: opts.pageToken }
@@ -39502,7 +40477,7 @@ function registerRunnerRecordingCommands(runner, signals) {
39502
40477
 
39503
40478
  // src/commands/runner/index.ts
39504
40479
  function registerRunnerCommand(program, signals) {
39505
- const runner = program.command("runner").description("Drive an interactive runner on the QA Wolf platform");
40480
+ const runner = declareReferenceGuide(program.command("runner"), runnerWorkflowGuide).description("Drive an interactive runner on the QA Wolf platform");
39506
40481
  registerRunnerLifecycleCommands(runner, signals);
39507
40482
  registerRunCommand(runner, signals);
39508
40483
  registerRunnerEventsCommand(runner, signals);
@@ -39529,8 +40504,10 @@ function createProgram({
39529
40504
  registerFlowsCommand(program, signals);
39530
40505
  registerInitCommand(program, signals);
39531
40506
  registerInstallCommand(program, signals);
40507
+ registerAttemptCommand(program, signals);
39532
40508
  registerRunnerCommand(program, signals);
39533
40509
  registerPublicApiCommands(program, signals);
40510
+ registerHelpCommand(program);
39534
40511
  return program;
39535
40512
  }
39536
40513
 
@@ -39544,4 +40521,4 @@ createProgram({ signals }).parseAsync().catch(() => {
39544
40521
  process.exitCode = 1;
39545
40522
  }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
39546
40523
 
39547
- //# debugId=1A1CE11EA6A4398C64756E2164756E21
40524
+ //# debugId=60ABEEB099A36FAE64756E2164756E21