@qawolf/cli 1.16.0 → 1.17.0

package/dist/cli.js

@@ -326123,7 +326123,18 @@ var interactMessages = {
   packageInstalled: (name, version) => `Installed ${name}@${version} into the runner's live run.`,
   packageJsonUnreadable: (reason) => `package.json could not be read because ${reason}. Fix it and try again.`,
   installFailed: (name, version, errorMessage2) => `npm could not install ${name}@${version}${errorMessage2 === undefined ? "" : `. ${errorMessage2}`}. Check the name and the version; waiting will not change this.`,
-  importAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`
+  importAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
+  highlightCleared: "Cleared the runner's highlight. Its next screenshot shows the page undrawn on.",
+  highlightMatched: (matchCount, targetPage) => `Highlighted ${pluralize(matchCount, "element", "elements")}${targetPage === undefined ? "" : ` on ${targetPage}`}. The highlight stays until it is replaced or cleared, so take a screenshot to see it.`,
+  highlightMatchedNothing: (selector) => `The page read "${selector}" as a selector and nothing matched it, so nothing is highlighted. The selector is well formed, so this is the page rather than the syntax: check what is actually on it with qawolf runner inspect page-html.`,
+  highlightSelectorInvalid: (selector) => `The page could not read "${selector}" as a selector, so nothing was highlighted. This is the syntax rather than the page, and retrying will not change it.`,
+  highlightNoAnswer: "The page did not answer, so nothing is highlighted. A highlight runs inside the page, so a page that is gone or part-way through navigating does not answer at all rather than answering slowly. Take a screenshot to see where the runner is, then try again.",
+  runnerCannotHighlightSelectors: "This runner has no browser to draw on, so there is nothing to highlight. Retrying will never help: launch a playwright runner instead.",
+  highlightAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
+  snapshotPromoted: (screenshotPath, baselinePath) => `Promoted ${screenshotPath} to the baseline at ${baselinePath}.`,
+  snapshotNotFound: (screenshotPath) => `The run wrote no screenshot at "${screenshotPath}", so nothing was changed. The two paths have to be the ones an image diff reported: read them from the image-diff-artifact entry on qawolf runner events run-events.`,
+  runnerCannotPromoteSnapshots: "This runner stores no screenshots, so it holds no baseline to replace. Retrying will never help.",
+  promoteSnapshotAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`
 };
 
 // src/core/messages/interactiveRunner/lifecycle.ts
@@ -326138,7 +326149,9 @@ var lifecycleMessages = {
   launched: (id) => `Launched runner ${id}.`,
   launchedForCommand: (id) => `No runner was given, so launched ${id} for this command. Its browser is fresh: nothing has been run on it and nothing is signed in. It bills until it is terminated or idles out, so terminate it with qawolf runner terminate --runner ${id} when you are done.`,
   noRunnerIdForImport: `${noRunnerId} An install also needs a live run to go into, which a runner gets from qawolf runner run.`,
+  noRunnerIdForHighlight: `${noRunnerId} Highlighting also needs a live page to draw on, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
   noRunnerIdForInspect: `${noRunnerId} Inspecting also needs a page, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
+  noRunnerIdForPromoteSnapshot: `${noRunnerId} A baseline is replaced on the runner that produced the screenshot, so it has to be the runner the diff came from.`,
   noRunnerIdForScreenshot: `${noRunnerId} A screenshot also needs a screen, which a runner gets from its first run: run a flow on it with qawolf runner run.`,
   noRunnerId,
   wasNotRunning: (id) => `Runner ${id} was not running.`,
@@ -326152,6 +326165,8 @@ var lifecycleMessages = {
 var runMessages = {
   envFileUnparseable: (reason) => `The --env-file could not be read. ${reason}`,
   envFileUnreadable: (path) => `No env file at ${path}. Pass a path that exists, or drop --env-file to send no environment.`,
+  envIdBlank: "--env-id was given nothing. Pass the id or alias of a QA Wolf environment, or drop the flag to send no environment.",
+  envIdWithEnvFile: "--env-id and --env-file both give the run its environment, so only one may be passed. Use --env-id for a QA Wolf environment, which QA Wolf reads itself, or --env-file for a dotenv file on this machine.",
   fileNotCollected: (path) => `"${path}" is not one of the files that travel to a runner. It must be inside the current directory and end in .ts, .tsx, .js, .mjs, .cjs or .json.`,
   fileUnreadable: (path, reason) => `${path} is one of the files that travel to a runner, but it could not be read: ${reason}. Move it out of the current directory, or make it readable.`,
   filesUnreadable: (reason) => `One of the files that travel to a runner could not be read: ${reason}.`,
@@ -342275,7 +342290,7 @@ function refusalForRunEnvironmentVariableName(name) {
   return;
 }
 var maxRunEnvironmentVariables = 200;
-var maxRunEnvironmentValueLength = 8 * 1024;
+var maxRunEnvironmentValueLength = 16 * 1024;
 var runEnvironmentSchema = exports_external.record(exports_external.string(), exports_external.string().max(maxRunEnvironmentValueLength)).superRefine((environment, refinementContext) => {
   for (const name of Object.keys(environment)) {
     const refusal = refusalForRunEnvironmentVariableName(name);
@@ -342384,6 +342399,49 @@ var makeInspectOnRunnerContract = () => {
     output
   };
 };
+// node_modules/@qawolf/api-contracts/dist/v1/runner/inspectMobileShapes.js
+var boundsSchema = exports_external.object({
+  bottom: exports_external.number(),
+  left: exports_external.number(),
+  right: exports_external.number(),
+  top: exports_external.number()
+});
+var pointSchema = exports_external.object({ x: exports_external.number(), y: exports_external.number() });
+var selectorSchema = exports_external.object({
+  strategy: exports_external.union([
+    exports_external.object({
+      name: exports_external.literal("xpath"),
+      type: exports_external.enum(["unique", "full-path", "sibling-of", "parent-of"])
+    }),
+    exports_external.object({ name: exports_external.literal("ios-predicate") }),
+    exports_external.object({
+      hostSelector: exports_external.string(),
+      innerSelector: exports_external.string(),
+      name: exports_external.literal("shadow")
+    })
+  ]),
+  value: exports_external.string()
+});
+var elementSchema = exports_external.object({
+  attributes: exports_external.record(exports_external.string(), exports_external.string()),
+  bounds: boundsSchema.optional().describe("The element's on-screen rectangle, absent off-screen."),
+  center: pointSchema.optional().describe("Derived from `bounds`; absent wherever `bounds` is."),
+  selectors: selectorSchema.array().describe("Ways to address this element again, most reliable first."),
+  tag: exports_external.string()
+});
+var basePageSourceNodeSchema = exports_external.object({
+  attributes: exports_external.object({
+    bounds: boundsSchema.optional(),
+    rest: exports_external.record(exports_external.string(), exports_external.string()).optional()
+  }).optional(),
+  selectors: selectorSchema.array(),
+  tag: exports_external.string()
+});
+var pageSourceNodeSchema = basePageSourceNodeSchema.extend({
+  children: exports_external.lazy(() => exports_external.union([pageSourceNodeSchema, exports_external.string()]).array()).optional().describe("A string child is a text node; there is no element to select.")
+});
+var orientationSchema = exports_external.enum(["PORTRAIT", "LANDSCAPE"]);
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/outcome.js
 function makeRunnerFailureSchema(reasons) {
   return exports_external.object({
@@ -342392,6 +342450,100 @@ function makeRunnerFailureSchema(reasons) {
   });
 }
 
+// node_modules/@qawolf/api-contracts/dist/v1/runner/inspectMobile.js
+var maxElementTextLength = 500;
+var inspectMobileRequestSchema = exports_external.discriminatedUnion("what", [
+  exports_external.object({
+    what: exports_external.literal("session").describe("The status of the Appium session driving the device: ready and what it is, or why not.")
+  }),
+  exports_external.object({
+    what: exports_external.literal("contexts").describe("The WebView contexts available on the device, and which one is current.")
+  }),
+  exports_external.object({
+    context: exports_external.string().min(1).optional().describe("Read this context instead of whichever is current."),
+    what: exports_external.literal("page").describe("The page source of the device's current context, as a tree.")
+  }),
+  exports_external.discriminatedUnion("by", [
+    exports_external.object({
+      by: exports_external.literal("point"),
+      context: exports_external.string().min(1).optional(),
+      what: exports_external.literal("elements"),
+      x: exports_external.int().min(0).describe("Whole pixels on the device's own screen."),
+      y: exports_external.int().min(0).describe("Whole pixels on the device's own screen.")
+    }),
+    exports_external.object({
+      by: exports_external.literal("text"),
+      context: exports_external.string().min(1).optional(),
+      partial: exports_external.boolean().optional().describe("Match text containing this, rather than exactly this."),
+      text: exports_external.string().min(1).max(maxElementTextLength),
+      what: exports_external.literal("elements")
+    })
+  ]).describe("Elements at a screen point, or elements carrying some text — never both at once.")
+]);
+var inspectMobileAnswerSchema = exports_external.discriminatedUnion("what", [
+  exports_external.object({
+    outcome: exports_external.literal("success"),
+    session: exports_external.discriminatedUnion("type", [
+      exports_external.object({
+        deviceName: exports_external.string().optional(),
+        platformName: exports_external.string(),
+        sessionId: exports_external.string(),
+        type: exports_external.literal("ready")
+      }),
+      exports_external.object({
+        error: exports_external.string(),
+        type: exports_external.literal("unreachable")
+      }),
+      exports_external.object({
+        sessionCount: exports_external.number(),
+        type: exports_external.literal("ambiguous")
+      }),
+      exports_external.object({ type: exports_external.literal("no-session") })
+    ]),
+    what: exports_external.literal("session")
+  }),
+  exports_external.object({
+    contexts: exports_external.string().array(),
+    current: exports_external.string(),
+    outcome: exports_external.literal("success"),
+    what: exports_external.literal("contexts")
+  }),
+  exports_external.object({
+    context: exports_external.string(),
+    orientation: orientationSchema,
+    outcome: exports_external.literal("success"),
+    pageSource: pageSourceNodeSchema,
+    what: exports_external.literal("page")
+  }),
+  exports_external.object({
+    matches: elementSchema.array(),
+    outcome: exports_external.literal("success"),
+    what: exports_external.literal("elements")
+  })
+]);
+var makeInspectMobileOnRunnerContract = () => {
+  const input = exports_external.object({
+    id: runnerIdSchema.describe("Id of the runner to inspect."),
+    request: inspectMobileRequestSchema
+  });
+  const output = exports_external.discriminatedUnion("outcome", [
+    inspectMobileAnswerSchema,
+    makeRunnerFailureSchema([
+      "runner-is-not-mobile",
+      "screen-needs-a-run",
+      "screen-not-ready",
+      runnerUnreachableFailureReason
+    ])
+  ]);
+  return {
+    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 or carrying some text. 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. ${retryableRunnerUnreachableDescription}`,
+    input,
+    kind: "read",
+    name: "runner.inspectMobile",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/journal.js
 var journalEntrySchema = exports_external.object({
   payload: exports_external.unknown(),
@@ -343090,6 +343242,43 @@ var makeEvaluateSnippetOnRunnerContract = () => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/runner/highlightSelector.js
+var maxHighlightSelectorLength = 2000;
+var makeHighlightSelectorOnRunnerContract = () => {
+  const input = exports_external.object({
+    id: runnerIdSchema.describe("Id of the runner to highlight on."),
+    selector: exports_external.string().max(maxHighlightSelectorLength).describe("The selector to highlight. An empty string clears whatever is highlighted.")
+  });
+  const output = exports_external.discriminatedUnion("outcome", [
+    exports_external.object({
+      matchCount: exports_external.number().int().gte(0).describe("How many elements the selector matched."),
+      outcome: exports_external.literal("success"),
+      selector: exports_external.string().describe("The selector the page matched on."),
+      status: exports_external.literal(["valid", "invalid", "empty"]).describe("`valid` when the selector parsed and matched, `empty` when it parsed and matched nothing, `invalid` when the page could not read it as a selector."),
+      targetPage: exports_external.string().optional().describe("Present when the match was on a page other than the default one.")
+    }),
+    exports_external.object({
+      outcome: exports_external.literal("cleared")
+    }),
+    exports_external.object({
+      errorMessage: exports_external.string().optional(),
+      failureReason: exports_external.enum([
+        "no-answer",
+        "runner-cannot-highlight-selectors",
+        "runner-unreachable"
+      ]),
+      outcome: exports_external.literal("failure")
+    })
+  ]);
+  return {
+    description: "Highlight the elements a selector matches on an interactive runner's live page, and answer how many it matched. The highlight stays until it is replaced or cleared, so it is visible in the next `runner.takeScreenshot` — which is the point, since a caller cannot see the runner's screen otherwise. Send an empty selector to clear, which answers `cleared`. `status` tells a selector that matched nothing (`empty`) from one the page could not parse (`invalid`), so a caller can tell a bad locator from a locator pointing at nothing. `no-answer` if the page did not answer in time: the highlight runs inside the page, so a page that is gone or mid-navigation does not answer slowly, it does not answer at all. `runner-cannot-highlight-selectors` on a runner with no browser to draw on. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity.",
+    input,
+    kind: "write",
+    name: "runner.highlightSelector",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/importPackage.js
 var maxPackageNameLength = 214;
 var maxPackageVersionLength = 256;
@@ -343153,6 +343342,34 @@ var makeTerminateRunnerContract = () => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/runner/promoteSnapshot.js
+var maxSnapshotPathLength = 1024;
+var makePromoteSnapshotOnRunnerContract = () => {
+  const input = exports_external.object({
+    baselinePath: exports_external.string().min(1).max(maxSnapshotPathLength).describe("The baseline to replace, as named in the image diff."),
+    id: runnerIdSchema.describe("Id of the runner holding the screenshot."),
+    screenshotPath: exports_external.string().min(1).max(maxSnapshotPathLength).describe("The screenshot to promote, as named in the image diff.")
+  });
+  const output = exports_external.discriminatedUnion("outcome", [
+    exports_external.object({ outcome: exports_external.literal("success") }),
+    exports_external.object({
+      failureReason: exports_external.enum([
+        "runner-cannot-promote-snapshots",
+        "runner-unreachable",
+        "snapshot-not-found"
+      ]),
+      outcome: exports_external.literal("failure")
+    })
+  ]);
+  return {
+    description: "Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it. The two paths are the ones the diff reported, which reach a caller as an `image-diff-artifact` entry on the runner's `run-events` journal stream. `snapshot-not-found` if the run wrote no screenshot at that path, which usually means the paths were not taken from a diff this run produced; nothing is changed, so correcting the path and repeating is safe. `runner-cannot-promote-snapshots` on a runner that stores no screenshots. `runner-unreachable` if the runner could not be reached: it may still be starting, or it may have terminated after inactivity. A promotion that lands is not undone by promoting again, so a retry after an unreachable answer is safe.",
+    input,
+    kind: "write",
+    name: "runner.promoteSnapshot",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/readJournal.js
 var makeReadRunnerJournalContract = () => {
   const input = readJournalRequestSchema.extend({
@@ -343184,14 +343401,18 @@ var unchangedFilesSchema = exports_external.record(exports_external.string(), ex
     });
   }
 });
-var makeRunFlowOnRunnerContract = () => {
+var makeRunFlowOnRunnerContract = (ids) => {
   const input = exports_external.object({
     entryPointPath: runFilePathSchema.describe("Path of the flow file to run, as it appears in `files`."),
     env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run."),
+    environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. Send this or `env`, not both."),
     files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
     id: runnerIdSchema.describe("Id of the runner to run the flow on."),
     selection: runSelectionSchema.optional().describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
     unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file.")
+  }).refine((request) => request.env === undefined || request.environmentId === undefined, {
+    error: "Send env or environmentId, not both. An environment's variables are taken as they are stored, so there is no order in which the two would combine.",
+    path: ["environmentId"]
   }).refine((request) => Object.hasOwn(request.files, request.entryPointPath), {
     error: "The entry point must be one of the files.",
     path: ["files"]
@@ -343342,12 +343563,15 @@ var makeContractsV1 = (ids) => {
     },
     runner: {
       evaluateSnippet: makeEvaluateSnippetOnRunnerContract(),
+      highlightSelector: makeHighlightSelectorOnRunnerContract(),
       importPackage: makeImportPackageOnRunnerContract(),
       inspect: makeInspectOnRunnerContract(),
+      inspectMobile: makeInspectMobileOnRunnerContract(),
       launch: makeLaunchRunnerContract(),
       performAction: makePerformActionOnRunnerContract(),
+      promoteSnapshot: makePromoteSnapshotOnRunnerContract(),
       readJournal: makeReadRunnerJournalContract(),
-      runFlow: makeRunFlowOnRunnerContract(),
+      runFlow: makeRunFlowOnRunnerContract(resolvedIds),
       stopRun: makeStopRunOnRunnerContract(),
       takeScreenshot: makeTakeScreenshotOnRunnerContract(),
       terminate: makeTerminateRunnerContract()
@@ -345874,7 +346098,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.16.0",
+  version: "1.17.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -345934,7 +346158,7 @@ var package_default = {
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.32.0",
+    "@qawolf/api-contracts": "0.34.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -356368,10 +356592,13 @@ async function handlePublicApiCommand(ctx, spec, options) {
 var skippedContractNames = new Set([
   "flow.list",
   "runner.evaluateSnippet",
+  "runner.highlightSelector",
   "runner.importPackage",
   "runner.inspect",
+  "runner.inspectMobile",
   "runner.launch",
   "runner.performAction",
+  "runner.promoteSnapshot",
   "runner.readJournal",
   "runner.runFlow",
   "runner.stopRun",
@@ -356430,45 +356657,6 @@ function registerPublicApiCommands(program2, signals, options = {}) {
   }
 }
 
-// src/domains/interactiveRunner/importPackage.ts
-import { join as join44 } from "node:path";
-
-// src/core/interactiveRunner/npmDependencies.ts
-var sectionsInPrecedenceOrder = ["dependencies", "devDependencies"];
-var isInstallable = (version2) => !version2.startsWith("workspace:");
-function isRecord5(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function readNpmDependencies(packageJsonContent) {
-  let parsed;
-  try {
-    parsed = JSON.parse(packageJsonContent);
-  } catch {
-    return { ok: false, reason: "it is not valid JSON" };
-  }
-  if (!isRecord5(parsed))
-    return { ok: false, reason: "it is not an object" };
-  const dependencies = {};
-  for (const section of sectionsInPrecedenceOrder) {
-    const declared = parsed[section];
-    if (declared === undefined)
-      continue;
-    if (!isRecord5(declared)) {
-      return { ok: false, reason: `${section} is not an object` };
-    }
-    for (const [name, version2] of Object.entries(declared)) {
-      if (typeof version2 !== "string") {
-        return { ok: false, reason: `${section}.${name} is not a string` };
-      }
-      if (Object.hasOwn(dependencies, name))
-        continue;
-      if (isInstallable(version2))
-        dependencies[name] = version2;
-    }
-  }
-  return { dependencies, ok: true };
-}
-
 // src/domains/interactiveRunner/runnerCallOptions.ts
 var runnerCallOptions = { timeoutMs: 90000 };
 
@@ -356583,71 +356771,73 @@ function announceRunner(ctx, resolved) {
   }
 }
 
-// src/domains/interactiveRunner/importPackage.ts
-var defaultPackageVersion = "latest";
-async function handleRunnerImportPackage(ctx, options, deps) {
-  const content = await deps.readFile(join44(deps.cwd, runPackageJsonPath)).catch(() => {
-    return;
-  });
-  if (content === undefined) {
-    return {
-      error: interactiveRunnerMessages.missingPackageJsonForImport,
-      exitCode: exitCodes.config
-    };
-  }
-  const dependencies = readNpmDependencies(content);
-  if (!dependencies.ok) {
-    return {
-      error: interactiveRunnerMessages.packageJsonUnreadable(dependencies.reason),
-      exitCode: exitCodes.config
-    };
-  }
+// src/domains/interactiveRunner/highlightSelector.ts
+async function handleRunnerHighlightSelector(ctx, options, deps) {
   const resolved = await resolveRunner(ctx, {
     autoLaunch: false,
-    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForImport,
+    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForHighlight,
     runner: options.runner
   }, deps);
   if (resolved.type === "failed") {
     return { ...failureFields(resolved), exitCode: resolved.exitCode };
   }
-  const packageVersion = options.version ?? defaultPackageVersion;
-  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.importPackage, {
-    id: resolved.runnerId,
-    npmDependencies: dependencies.dependencies,
-    packageName: options.name,
-    packageVersion
-  }, runnerCallOptions);
+  const selector = options.selector ?? "";
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.highlightSelector, { id: resolved.runnerId, selector }, runnerCallOptions);
   if (!result.ok) {
     return { ...failureFields(result), exitCode: exitCodes.network };
   }
-  if (result.value.outcome === "failure") {
-    const failure = result.value;
-    const { failureReason } = failure;
-    switch (failureReason) {
-      case "install-failed":
+  const { outcome } = result.value;
+  switch (outcome) {
+    case "cleared":
+      ctx.ui.output(result.value, interactiveRunnerMessages.highlightCleared);
+      return;
+    case "success": {
+      const answer = result.value;
+      if (answer.status === "invalid") {
         return {
-          error: interactiveRunnerMessages.installFailed(options.name, packageVersion, failure.errorMessage),
+          error: interactiveRunnerMessages.highlightSelectorInvalid(answer.selector),
           exitCode: exitCodes.invalidArgs
         };
-      case "runner-unreachable":
-        return {
-          error: interactiveRunnerMessages.runnerUnreachable,
-          exitCode: exitCodes.network
-        };
-      default: {
-        return {
-          error: interactiveRunnerMessages.importAnsweredUnknown(failureReason),
-          exitCode: exitCodes.network
-        };
       }
+      ctx.ui.output(answer, answer.status === "empty" ? interactiveRunnerMessages.highlightMatchedNothing(answer.selector) : interactiveRunnerMessages.highlightMatched(answer.matchCount, answer.targetPage));
+      return;
     }
+    case "failure":
+      return describeFailure(result.value.failureReason);
+    default:
+      return {
+        error: interactiveRunnerMessages.highlightAnsweredUnknown(outcome),
+        exitCode: exitCodes.network
+      };
+  }
+}
+function describeFailure(failureReason) {
+  switch (failureReason) {
+    case "no-answer":
+      return {
+        error: interactiveRunnerMessages.highlightNoAnswer,
+        exitCode: exitCodes.network
+      };
+    case "runner-cannot-highlight-selectors":
+      return {
+        error: interactiveRunnerMessages.runnerCannotHighlightSelectors,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.runnerUnreachable,
+        exitCode: exitCodes.network
+      };
+    default:
+      return {
+        error: interactiveRunnerMessages.highlightAnsweredUnknown(failureReason),
+        exitCode: exitCodes.network
+      };
   }
-  ctx.ui.output(result.value, interactiveRunnerMessages.packageInstalled(options.name, packageVersion));
-  return;
 }
 
 // src/shell/interactiveRunner/collectRunFiles.ts
-import { join as join46 } from "node:path";
+import { join as join45 } from "node:path";
 
 // src/core/interactiveRunner/getImports.ts
 function getImports(options) {
@@ -356686,14 +356876,14 @@ function isPathAlias(importPath, paths) {
 }
 
 // src/core/interactiveRunner/resolveImportPath.ts
-import { dirname as dirname15, join as join45, normalize as normalize3 } from "node:path/posix";
+import { dirname as dirname15, join as join44, normalize as normalize3 } from "node:path/posix";
 
 // src/core/interactiveRunner/tsconfigPaths.ts
-function isRecord6(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null;
 }
 function isTsconfigPaths(value) {
-  return isRecord6(value) && Object.values(value).every((targets) => Array.isArray(targets) && targets.every((target) => typeof target === "string"));
+  return isRecord5(value) && Object.values(value).every((targets) => Array.isArray(targets) && targets.every((target) => typeof target === "string"));
 }
 function parseTsconfigPaths(tsconfigContent) {
   let parsed;
@@ -356702,10 +356892,10 @@ function parseTsconfigPaths(tsconfigContent) {
   } catch {
     return;
   }
-  if (!isRecord6(parsed))
+  if (!isRecord5(parsed))
     return;
   const compilerOptions = parsed["compilerOptions"];
-  if (!isRecord6(compilerOptions))
+  if (!isRecord5(compilerOptions))
     return;
   const paths = compilerOptions["paths"];
   return isTsconfigPaths(paths) ? paths : undefined;
@@ -356739,7 +356929,7 @@ function candidatesForExplicitExtension(options) {
 }
 function resolveImportPath(options) {
   const aliasTarget = resolvePathAlias(options.importPath, options.tsconfigPaths);
-  const resolvedPath = aliasTarget === undefined ? normalize3(join45(dirname15(options.importingFilePath), options.importPath)) : normalize3(aliasTarget);
+  const resolvedPath = aliasTarget === undefined ? normalize3(join44(dirname15(options.importingFilePath), options.importPath)) : normalize3(aliasTarget);
   const hasExplicitExtension = supportedExtensions.some((extension) => options.importPath.endsWith(extension));
   const candidates = hasExplicitExtension ? candidatesForExplicitExtension({
     importPath: options.importPath,
@@ -356763,7 +356953,7 @@ function resolveImportPath(options) {
 var tsconfigPath = "tsconfig.json";
 async function collectRunFiles(options) {
   const held = await listShippablePaths(options);
-  const readFile2 = (path9) => options.fs.readFile(join46(options.cwd, path9));
+  const readFile2 = (path9) => options.fs.readFile(join45(options.cwd, path9));
   const tsconfigContent = held.has(tsconfigPath) ? await readFile2(tsconfigPath).catch(() => {
     return;
   }) : undefined;
@@ -356846,7 +357036,7 @@ function makeRunnerId() {
 }
 
 // src/shell/interactiveRunner/runFilesManifest.ts
-import { join as join47 } from "node:path";
+import { join as join46 } from "node:path";
 var manifestFileName = "runner-files.json";
 var manifestSchema2 = exports_external.object({
   files: exports_external.array(exports_external.object({ contentHash: exports_external.string(), path: exports_external.string() })),
@@ -356854,8 +357044,8 @@ var manifestSchema2 = exports_external.object({
   version: exports_external.literal(1)
 });
 function makeRunFilesManifestStore(options) {
-  const directory = join47(options.cwd, qawolfDir);
-  const path9 = join47(directory, manifestFileName);
+  const directory = join46(options.cwd, qawolfDir);
+  const path9 = join46(directory, manifestFileName);
   let pendingWrites = 0;
   return {
     async read() {
@@ -356885,7 +357075,7 @@ function parseJson(text3) {
 }
 
 // src/shell/interactiveRunner/runnerStore.ts
-import { join as join48 } from "node:path";
+import { join as join47 } from "node:path";
 var storeFileName = "runner.json";
 var storeSchema = exports_external.object({ defaultRunnerId: exports_external.string().optional() });
 function parseJson2(text3) {
@@ -356896,8 +357086,8 @@ function parseJson2(text3) {
   }
 }
 function makeRunnerStore(options) {
-  const directory = join48(options.cwd, qawolfDir);
-  const path9 = join48(directory, storeFileName);
+  const directory = join47(options.cwd, qawolfDir);
+  const path9 = join47(directory, storeFileName);
   let pendingWrites = 0;
   const nextPendingPath = () => `${path9}.${process.pid}.${++pendingWrites}.tmp`;
   return {
@@ -356979,6 +357169,118 @@ function runnerDeps(ctx) {
   });
 }
 
+// src/commands/runner/highlightSelector.register.ts
+var highlightExamples = `
+Examples:
+  $ qawolf runner highlight-selector "text=Sign in"
+  $ qawolf runner highlight-selector "#checkout" && qawolf runner screenshot
+  $ qawolf runner highlight-selector`;
+function registerRunnerHighlightSelectorCommand(runner, signals) {
+  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));
+}
+
+// src/domains/interactiveRunner/importPackage.ts
+import { join as join48 } from "node:path";
+
+// src/core/interactiveRunner/npmDependencies.ts
+var sectionsInPrecedenceOrder = ["dependencies", "devDependencies"];
+var isInstallable = (version2) => !version2.startsWith("workspace:");
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readNpmDependencies(packageJsonContent) {
+  let parsed;
+  try {
+    parsed = JSON.parse(packageJsonContent);
+  } catch {
+    return { ok: false, reason: "it is not valid JSON" };
+  }
+  if (!isRecord6(parsed))
+    return { ok: false, reason: "it is not an object" };
+  const dependencies = {};
+  for (const section of sectionsInPrecedenceOrder) {
+    const declared = parsed[section];
+    if (declared === undefined)
+      continue;
+    if (!isRecord6(declared)) {
+      return { ok: false, reason: `${section} is not an object` };
+    }
+    for (const [name, version2] of Object.entries(declared)) {
+      if (typeof version2 !== "string") {
+        return { ok: false, reason: `${section}.${name} is not a string` };
+      }
+      if (Object.hasOwn(dependencies, name))
+        continue;
+      if (isInstallable(version2))
+        dependencies[name] = version2;
+    }
+  }
+  return { dependencies, ok: true };
+}
+
+// src/domains/interactiveRunner/importPackage.ts
+var defaultPackageVersion = "latest";
+async function handleRunnerImportPackage(ctx, options, deps) {
+  const content = await deps.readFile(join48(deps.cwd, runPackageJsonPath)).catch(() => {
+    return;
+  });
+  if (content === undefined) {
+    return {
+      error: interactiveRunnerMessages.missingPackageJsonForImport,
+      exitCode: exitCodes.config
+    };
+  }
+  const dependencies = readNpmDependencies(content);
+  if (!dependencies.ok) {
+    return {
+      error: interactiveRunnerMessages.packageJsonUnreadable(dependencies.reason),
+      exitCode: exitCodes.config
+    };
+  }
+  const resolved = await resolveRunner(ctx, {
+    autoLaunch: false,
+    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForImport,
+    runner: options.runner
+  }, deps);
+  if (resolved.type === "failed") {
+    return { ...failureFields(resolved), exitCode: resolved.exitCode };
+  }
+  const packageVersion = options.version ?? defaultPackageVersion;
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.importPackage, {
+    id: resolved.runnerId,
+    npmDependencies: dependencies.dependencies,
+    packageName: options.name,
+    packageVersion
+  }, runnerCallOptions);
+  if (!result.ok) {
+    return { ...failureFields(result), exitCode: exitCodes.network };
+  }
+  if (result.value.outcome === "failure") {
+    const failure = result.value;
+    const { failureReason } = failure;
+    switch (failureReason) {
+      case "install-failed":
+        return {
+          error: interactiveRunnerMessages.installFailed(options.name, packageVersion, failure.errorMessage),
+          exitCode: exitCodes.invalidArgs
+        };
+      case "runner-unreachable":
+        return {
+          error: interactiveRunnerMessages.runnerUnreachable,
+          exitCode: exitCodes.network
+        };
+      default: {
+        return {
+          error: interactiveRunnerMessages.importAnsweredUnknown(failureReason),
+          exitCode: exitCodes.network
+        };
+      }
+    }
+  }
+  ctx.ui.output(result.value, interactiveRunnerMessages.packageInstalled(options.name, packageVersion));
+  return;
+}
+
 // src/commands/runner/importPackage.register.ts
 var importPackageExamples = `
 Examples:
@@ -357554,6 +357856,67 @@ function registerRunnerLifecycleCommands(runner, signals) {
   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));
 }
 
+// src/domains/interactiveRunner/promoteSnapshot.ts
+async function handleRunnerPromoteSnapshot(ctx, options, deps) {
+  const resolved = await resolveRunner(ctx, {
+    autoLaunch: false,
+    noRunnerIdMessage: interactiveRunnerMessages.noRunnerIdForPromoteSnapshot,
+    runner: options.runner
+  }, deps);
+  if (resolved.type === "failed") {
+    return { ...failureFields(resolved), exitCode: resolved.exitCode };
+  }
+  const result = await ctx.platformClient.callPublicApi(publicContractsV1.runner.promoteSnapshot, {
+    baselinePath: options.baselinePath,
+    id: resolved.runnerId,
+    screenshotPath: options.screenshotPath
+  }, runnerCallOptions);
+  if (!result.ok) {
+    return { ...failureFields(result), exitCode: exitCodes.network };
+  }
+  if (result.value.outcome === "success") {
+    ctx.ui.output(result.value, interactiveRunnerMessages.snapshotPromoted(options.screenshotPath, options.baselinePath));
+    return;
+  }
+  const { failureReason } = result.value;
+  switch (failureReason) {
+    case "snapshot-not-found":
+      return {
+        error: interactiveRunnerMessages.snapshotNotFound(options.screenshotPath),
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-cannot-promote-snapshots":
+      return {
+        error: interactiveRunnerMessages.runnerCannotPromoteSnapshots,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.runnerUnreachable,
+        exitCode: exitCodes.network
+      };
+    default: {
+      return {
+        error: interactiveRunnerMessages.promoteSnapshotAnsweredUnknown(failureReason),
+        exitCode: exitCodes.network
+      };
+    }
+  }
+}
+
+// src/commands/runner/promoteSnapshot.register.ts
+var promoteSnapshotExamples = `
+Examples:
+  $ qawolf runner promote-snapshot --screenshot checkout-1-actual.png --baseline checkout-1.png
+  $ qawolf runner events run-events --tail 20 | jq 'select(.type == "image-diff-artifact")'`;
+function registerRunnerPromoteSnapshotCommand(runner, signals) {
+  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, {
+    baselinePath: opts.baseline,
+    runner: opts.runner,
+    screenshotPath: opts.screenshot
+  }, runnerDeps(ctx)))(opts, command));
+}
+
 // src/core/interactiveRunner/followTimeout.ts
 var defaultFollowTimeoutSeconds = 3600;
 var followTimeoutSchema = exports_external.coerce.number().int().positive();
@@ -357942,6 +358305,13 @@ var refused = (error51, exitCode) => ({
   ok: false
 });
 async function prepareRun(options, deps) {
+  const environmentId = options.envId?.trim();
+  if (environmentId !== undefined && options.envFile !== undefined) {
+    return refused(interactiveRunnerMessages.envIdWithEnvFile, exitCodes.invalidArgs);
+  }
+  if (environmentId === "") {
+    return refused(interactiveRunnerMessages.envIdBlank, exitCodes.invalidArgs);
+  }
   const linesFilePath = options.linesFile === undefined ? undefined : toCollectedPath(deps.cwd, options.linesFile);
   const roots = linesFilePath === undefined || linesFilePath === options.entryPointPath ? [options.entryPointPath] : [options.entryPointPath, linesFilePath];
   const collected = await collectRunFiles2(deps, roots);
@@ -357958,14 +358328,26 @@ async function prepareRun(options, deps) {
   }
   const given = environment3?.ok === true ? environment3.environment : undefined;
   if (options.lines === undefined) {
-    return options.linesFile === undefined ? { environment: given, files, ok: true, selection: undefined } : refused(interactiveRunnerMessages.linesFileWithoutLines, exitCodes.invalidArgs);
+    return options.linesFile === undefined ? {
+      environment: given,
+      environmentId,
+      files,
+      ok: true,
+      selection: undefined
+    } : refused(interactiveRunnerMessages.linesFileWithoutLines, exitCodes.invalidArgs);
   }
   const path9 = linesFilePath ?? options.entryPointPath;
   if (!Object.hasOwn(files, path9)) {
     return refused(interactiveRunnerMessages.fileNotCollected(path9), exitCodes.invalidArgs);
   }
   const built = buildRunSelection({ lines: options.lines, path: path9 });
-  return built.ok ? { environment: given, files, ok: true, selection: built.selection } : refused(built.error, exitCodes.invalidArgs);
+  return built.ok ? {
+    environment: given,
+    environmentId,
+    files,
+    ok: true,
+    selection: built.selection
+  } : refused(built.error, exitCodes.invalidArgs);
 }
 async function readEnvironment(envFile, deps) {
   if (envFile === undefined)
@@ -358046,6 +358428,7 @@ async function sendRunFlowRequest(ctx, options, delta) {
     files: delta.files,
     id: options.resolved.runnerId,
     ...options.environment === undefined ? {} : { env: options.environment },
+    ...options.environmentId === undefined ? {} : { environmentId: options.environmentId },
     ...options.selection === undefined ? {} : { selection: options.selection },
     ...delta.unchangedFiles === undefined ? {} : { unchangedFiles: delta.unchangedFiles }
   }, runnerCallOptions);
@@ -358132,6 +358515,7 @@ async function handleRunnerRun(ctx, options, deps) {
   const prepared = await prepareRun({
     entryPointPath,
     envFile: options.envFile,
+    envId: options.envId,
     lines: options.lines,
     linesFile: options.linesFile
   }, deps);
@@ -358153,6 +358537,7 @@ async function handleRunnerRun(ctx, options, deps) {
   const submitted = await submitRun(ctx, {
     entryPointPath,
     environment: prepared.environment,
+    environmentId: prepared.environmentId,
     files: prepared.files,
     resolved,
     selection: prepared.selection
@@ -358191,11 +358576,13 @@ Examples:
   $ qawolf runner run flows/checkout.flow.ts --follow
   $ qawolf runner run flows/checkout.flow.ts --follow --logs
   $ qawolf runner run flows/checkout.flow.ts --lines 12-40
-  $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts`;
+  $ qawolf runner run flows/checkout.flow.ts --lines 4-9 --lines-file pages/login.ts
+  $ qawolf runner run flows/checkout.flow.ts --env-id staging`;
 function registerRunCommand(runner, signals) {
-  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-file <path>", "Dotenv file whose variables the run is given. Not --env, which on qawolf flows names a QA Wolf environment").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, {
+  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. 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, {
     entryPoint: flowFile,
     envFile: opts.envFile,
+    envId: opts.envId,
     follow: opts.follow,
     lines: opts.lines,
     linesFile: opts.linesFile,
@@ -358216,6 +358603,8 @@ function registerRunnerCommand(program2, signals) {
   registerRunnerInteractCommands(runner, signals);
   registerRunnerInspectCommands(runner, signals);
   registerRunnerImportPackageCommand(runner, signals);
+  registerRunnerHighlightSelectorCommand(runner, signals);
+  registerRunnerPromoteSnapshotCommand(runner, signals);
 }
 
 // src/commands/program.ts
@@ -358254,4 +358643,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=A9041D278FF748EF64756E2164756E21
+//# debugId=408E9965E881500264756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -60,7 +60,7 @@
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.32.0",
+    "@qawolf/api-contracts": "0.34.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",

package/skills/qawolf-cli/SKILL.md

@@ -145,12 +145,14 @@ current branch.
 | `qawolf runner act` | write | Perform one raw action on a runner's screen: click, double_click, scroll, move, drag, keypress, navigate or type. Use - to read a whole action as JSON from stdin |
 | `qawolf runner events` | read | Print a runner's journal, one entry per line. QA Wolf writes console, recorder, run-events, run-logs, run-status |
 | `qawolf runner exec` | write | Evaluate a snippet against a runner's live page. Use - to read the snippet from stdin |
+| `qawolf runner highlight-selector` | write | Highlight what a selector matches on a runner's live page, so the next screenshot shows it. Omit the selector to clear the highlight |
 | `qawolf runner import-package` | write | Install a package into a runner's live run, so a snippet or a selection can import it |
 | `qawolf runner inspect element-html` | read | Print the HTML of the first element a selector matches |
 | `qawolf runner inspect page-html` | read | Print the page's HTML, simplified for a model to read |
 | `qawolf runner inspect variable` | read | Print a top-level variable's value from the running workflow |
 | `qawolf runner keepalive` | read | Reset a runner's inactivity clock, for a caller that pauses between actions |
 | `qawolf runner launch` | write | Launch an interactive runner and make it this directory's default |
+| `qawolf runner promote-snapshot` | write | Accept a run's screenshot as the new baseline for an image diff, on the runner that produced it |
 | `qawolf runner run` | write | Run a flow on an interactive runner, shipping the flow and what it imports |
 | `qawolf runner screenshot` | read | Save a JPEG of an interactive runner's screen to a file |
 | `qawolf runner stop-run` | write | Stop what a runner is currently executing, leaving the runner up |

package/skills/qawolf-cli/references/runner.md

@@ -159,6 +159,53 @@ Use `inspect` 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; `inspect variable` is one call and the value.
 
+## Checking a selector: `highlight-selector`
+
+`inspect element-html` tells you what a selector matched. `highlight-selector`
+shows you _where_ it is, by drawing on the page itself:
+
+```sh
+qawolf runner highlight-selector "text=Sign in"
+qawolf runner screenshot                          # the highlight is in this
+qawolf runner highlight-selector                  # omit the selector to clear
+```
+
+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.
+
+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.
+
+`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.
+
+## Accepting a new baseline: `promote-snapshot`
+
+When a run's image diff fails and the new screenshot is the one you want, this
+replaces the baseline on the runner that produced it:
+
+```sh
+qawolf runner events run-events --tail 20 | jq 'select(.type == "image-diff-artifact")'
+qawolf runner promote-snapshot --screenshot checkout-1-actual.png --baseline checkout-1.png
+```
+
+Both paths are the ones the diff reported, 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.
+
+`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.
+
 ## Installing a package mid-session
 
 `qawolf runner import-package <name>` installs a package into the runner's live
@@ -255,14 +302,29 @@ runner is addressed, naming the path.
 
 ### Giving the run environment variables
 
+There are two ways, and a run takes one of them. `--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. It is `--env-file` and not `--env`, which on
-`qawolf flows` means a QA Wolf environment by id or slug.
+`qawolf flows pull` writes.
+
+```sh
+qawolf runner run flows/checkout.flow.ts --env-id staging
+qawolf runner run flows/checkout.flow.ts --env-file .env
+```
+
+**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.
+
+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.
 
-A run may carry at most 100 variables, each value at most 8 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.
+Passing both flags is refused. They each give the run its whole environment, so
+there is no order in which they would combine.
 
 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