@qawolf/cli 1.20.0 → 1.21.0

package/README.md

@@ -93,6 +93,28 @@ Omit `--global` to install the skill only for the current project. The skill als
 
 The skill is generated from its [source template](src/commands/qawolfCliSkill.template.md) and the command tree (`bun run generate`), and kept in sync by the test suite.
 
+## Runner SDK
+
+Drive interactive runners from TypeScript instead of spawning commands. Every verb names the runner it addresses, so nothing is launched or billed implicitly.
+
+```ts
+import { createRunnerSdk } from "@qawolf/cli/runner-sdk";
+
+const runner = createRunnerSdk({ apiKey: process.env.QAWOLF_API_KEY });
+
+await runner.launch({ id: "agent-1", runnerFamily: "default" });
+
+const submitted = await runner.run({
+  entryPointPath: "src/flows/smoke.flow.ts",
+  environment: "ambient",
+  runnerId: "agent-1",
+  selection: "whole-flow",
+});
+if (submitted.ok) console.log(submitted.value.runId, submitted.value.fileSync);
+```
+
+`ok: false` is a transport or auth failure. A runner that refused the request comes back as `ok: true` with `value.outcome === "failure"` and a `failureReason` from the published contract, so a caller can switch on it exhaustively.
+
 ## Reference
 
 - [Commands](https://docs.qawolf.com/qawolf/libraries/cli/api-reference/commands) — full command and flag reference

package/dist/cli.js

@@ -325968,6 +325968,7 @@ var flowsMessages = {
   flowCount: (count) => pluralize(count, "flow"),
   list: {
     remoteRequiresEnv: "--remote requires an environment. Pass --env <env> or set QAWOLF_ENVIRONMENT.",
+    aiTaskIdRequiresRemote: "--ai-task-id requires --remote",
     draftsRequireRemote: "--include-drafts requires --remote"
   },
   selectors: {
@@ -326122,7 +326123,6 @@ var interactMessages = {
   actionAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
   screenshotAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
   runnerHasNoScreen: "This runner does not run a browser on a virtual desktop, so there is nothing about it to see or drive. Retrying will never help: launch a playwright runner instead.",
-  runnerHasNoScreenToEvaluate: "The runner could not evaluate the snippet. This covers a runner that is still starting or busy, and also one with no live page to evaluate against: a freshly launched runner has no page until a run opens one, so run a flow on it with qawolf runner run first. If it is not a runner that runs a browser at all, this will never clear. It is not proof the snippet did not run, so do not resubmit one that mutates the page without reading qawolf runner events console first.",
   inspectNeedsABrowserRunner: "This runner is a mobile device, and element and page HTML are a browser's shapes. Retrying will never help. Launch a playwright runner to inspect one.",
   nothingToInspect: (errorMessage2) => `The runner had nothing to inspect${errorMessage2 === undefined ? "" : `: ${errorMessage2}`}. There is no live page, nothing matched the selector, or no variable has that name; a runner cannot tell those apart. Run a flow on it first, or check the selector or name.`,
   inspectAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
@@ -326137,7 +326137,10 @@ var interactMessages = {
   snippetErrored: (errorMessage2) => errorMessage2 === undefined ? "The snippet threw and reported no message." : `The snippet threw: ${errorMessage2}`,
   snippetFileUnreadable: (path) => `Could not read "${path}". Name a readable file, or "-" to read the snippet from stdin.`,
   snippetRan: "The snippet ran. Its value is not returned: read anything it printed with qawolf runner events console.",
+  snippetRunnerUnreachable: "The runner could not be reached. It may still be starting, or it may have terminated after inactivity. It is not proof the snippet did not run: a snippet that outlives the answer window is still executing when you read this, so do not blindly resubmit one that mutates the page without reading qawolf runner events console first.",
   snippetStopped: "The snippet was interrupted before it finished. Anything it printed first is in qawolf runner events console.",
+  runnerCannotEvaluateSnippets: "This runner has no snippet evaluator attached, so there is nothing to run code against. Retrying will never help: launch a playwright, android, ios, or windows runner instead.",
+  snippetAnsweredUnknown: (failureReason) => `The runner answered "${failureReason}", which this version of the CLI does not know how to report. Upgrade with npm install -g @qawolf/cli.`,
   stdinEmptyAction: 'Nothing arrived on stdin. Pipe the action in, or name the action type instead of "-".',
   stdinEmptySnippet: 'Nothing arrived on stdin. Pipe the snippet in, or name a file instead of "-".',
   missingPackageJsonForImport: "No package.json in the current directory. The install resolves against the run's own dependencies, which are read from one.",
@@ -326153,7 +326156,7 @@ var interactMessages = {
   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.`,
+  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 imageDiffArtifact 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.`
 };
@@ -342694,8 +342697,9 @@ var runSelectionSchema = exports_external.object({
 // node_modules/@qawolf/api-contracts/dist/v1/automate/index.js
 var makeAutomateContract = (ids) => {
   const input = exports_external.object({
+    aiTaskId: ids.aiTask.describe("The AI task to build the automation on: drafts are read from and the automation branches off the task's branch instead of the environment's.").optional(),
     environmentId: ids.environmentRef,
-    flowIds: exports_external.array(ids.flow).min(1).max(300).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("IDs of every requested draft flow the automation builds. Reuse an existing draft only when its name matches the requested journey; a generic starter or placeholder is not a match. After publishing, resolve the IDs with `qawolf --json flows list --remote --env <environment-id-or-alias> --include-drafts`."),
+    flowIds: exports_external.array(ids.flow).min(1).max(300).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("IDs of every requested draft flow the automation builds. Reuse an existing draft only when its name matches the requested journey; a generic starter or placeholder is not a match. After publishing, resolve the IDs with `qawolf --json flows list --remote --env <environment-id-or-alias> --include-drafts`, adding `--ai-task-id` when the drafts live on an AI task's branch."),
     patch: exports_external.string().min(1).max(1e6).optional().describe("Unified diff applied to the automation's working branch before it runs. It cannot create or rename a selected flow; publish selected flows with Git first.")
   });
   const output = resource({ automationId: ids.automation }, { urlFieldDescription: "Absolute URL of the automation review page." });
@@ -342926,6 +342930,7 @@ var flowReadinessSchema = exports_external.enum(["draft", "active"]);
 // node_modules/@qawolf/api-contracts/dist/v1/flow/index.js
 var makeListFlowsContract = (ids) => {
   const input = exports_external.object({
+    aiTaskId: ids.aiTask.describe("List the flows on this AI task's branch, including drafts, instead of the ones in the environment. The task must belong to the environment.").optional(),
     environmentId: ids.environmentRef,
     includeDrafts: exports_external.boolean().default(false).describe("Include draft flows in the listing.")
   });
@@ -342943,7 +342948,7 @@ var makeListFlowsContract = (ids) => {
     }))
   });
   return {
-    description: "List the flows of an environment at its latest reconciled commit.",
+    description: "List the flows of an environment at its latest reconciled commit, or, when an AI task is given, the flows on that task's branch.",
     input,
     kind: "read",
     name: "flow.list",
@@ -343269,10 +343274,13 @@ var makeEvaluateSnippetOnRunnerContract = () => {
       outcome: exports_external.literal("success"),
       result: exports_external.enum(["success", "stopped", "error"]).describe("`success` if the snippet ran to completion, `stopped` if it was interrupted, `error` if it threw. Whether it ran, not what it evaluated to.")
     }),
-    makeRunnerFailureSchema([runnerUnreachableFailureReason])
+    makeRunnerFailureSchema([
+      "runner-cannot-evaluate-snippets",
+      runnerUnreachableFailureReason
+    ])
   ]);
   return {
-    description: "Evaluate a snippet against whatever the runner's browser is showing right now. Answers whether the snippet ran, and its error if it threw — not the value it evaluated to, so read anything you want back out of the runner's journal (a snippet's `console.log` lands in the `console` stream). A snippet starts no run and leaves no run-scoped journal entries of its own. `runner-unreachable` if the runner could not be reached or could not evaluate: as well as a runner that is still starting, has terminated after inactivity, or is busy, this covers a runner with no live page to evaluate against — which will never clear, so check that the runner you launched is one that runs a browser before retrying. It is NOT proof the snippet did not run: a snippet that outlives the answer window is still executing when you read this, so do not blindly resubmit one that mutates what the page is looking at.",
+    description: "Evaluate a snippet against whatever the runner's browser is showing right now. Answers whether the snippet ran, and its error if it threw — not the value it evaluated to, so read anything you want back out of the runner's journal (a snippet's `console.log` lands in the `console` stream). A snippet starts no run and leaves no run-scoped journal entries of its own. `runner-cannot-evaluate-snippets` on a runner with nothing attached to serve one — which will never clear, so check that the runner you launched is one that runs a browser or app before retrying. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Neither is proof the snippet did not run: a snippet that outlives the answer window is still executing when you read this, so do not blindly resubmit one that mutates what the page is looking at.",
     input,
     kind: "write",
     name: "runner.evaluateSnippet",
@@ -346156,7 +346164,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.20.0",
+  version: "1.21.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -346184,16 +346192,27 @@ var package_default = {
     "LICENSE",
     "README.md",
     "dist/cli.js",
+    "dist/runner-sdk.js",
+    "dist/types/runnerSdk/index.d.ts",
+    "dist/types/runnerSdk/types.d.ts",
     "skills"
   ],
   type: "module",
+  exports: {
+    "./runner-sdk": {
+      types: "./dist/types/runnerSdk/index.d.ts",
+      import: "./dist/runner-sdk.js"
+    },
+    "./package.json": "./package.json"
+  },
   publishConfig: {
     access: "public"
   },
   scripts: {
     build: "bun run build:bundle",
-    "build:bundle": "bun run generate && bun scripts/build.ts",
     "build:binary": "bun run build && bun scripts/buildBinary.ts",
+    "build:bundle": "bun run generate && bun scripts/build.ts",
+    "build:types-gate": "bun scripts/checkSdkTypes.ts",
     dev: "bun run src/main.ts",
     format: "oxfmt .",
     "format:check": "oxfmt --check .",
@@ -346216,7 +346235,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.35.0",
+    "@qawolf/api-contracts": "0.37.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -349119,6 +349138,7 @@ async function fetchKnownTags(ctx) {
 // src/domains/flows/listRemote.ts
 async function flowsListRemote(ctx, pattern, options) {
   const result = await ctx.platformClient.callPublicApi(publicContractsV1.flow.list, {
+    aiTaskId: options.aiTaskId,
     environmentId: options.env,
     includeDrafts: options.includeDrafts
   });
@@ -356431,25 +356451,32 @@ Examples:
   $ qawolf flows list --tag auth
   $ qawolf flows list --env staging --tag auth
   $ qawolf flows list --remote --env staging --tag auth --tag smoke
-  $ qawolf flows list "**/checkout/**" --remote --env staging --include-drafts`;
-function registerFlowsCommand(program2, signals) {
+  $ qawolf flows list "**/checkout/**" --remote --env staging --include-drafts
+  $ qawolf flows list --remote --env staging --ai-task-id ait_123`;
+function registerFlowsCommand(program2, signals, deps = { withResolvedEnv }) {
   const flows = program2.command("flows").description("Manage and run QA Wolf flows");
   registerFlowsRunCommand(flows, signals);
   registerRunWorkerCommand(flows, signals);
   declareCommandKind(flows.command("list [pattern]"), "local", {
     kindNote: "read with --remote"
-  }).description("List flows matching [pattern] from the local project, or from a QA Wolf environment with --remote").option("--remote", "List flows from the QA Wolf platform instead of the local project", false).option("--env <env>", "Environment to list flows from: a QA Wolf environment with --remote, otherwise a pulled one by slug or id").option("--include-drafts", "Include draft flows in the listing (requires --remote)", false).option("--tag <name>", "Only list flows carrying this tag; repeat for several. Without --remote, matches against tags cached by the last pull", collectValue, []).addHelpText("after", listExamples).action((pattern, opts, command) => {
+  }).description("List flows matching [pattern] from the local project, or from a QA Wolf environment with --remote").option("--remote", "List flows from the QA Wolf platform instead of the local project", false).option("--env <env>", "Environment to list flows from: a QA Wolf environment with --remote, otherwise a pulled one by slug or id").option("--include-drafts", "Include draft flows in the listing (requires --remote)", false).option("--tag <name>", "Only list flows carrying this tag; repeat for several. Without --remote, matches against tags cached by the last pull", collectValue, []).addOption(new Option("--ai-task-id <aiTaskId>", "List the flows on this AI task's branch, including drafts, instead of the ones in the environment (requires --remote)").env("QAWOLF_AI_TASK_ID")).addHelpText("after", listExamples).action((pattern, opts, command) => {
     const tags = opts.tag;
     if (opts.remote) {
-      return withResolvedEnv(signals, {
+      return deps.withResolvedEnv(signals, {
         explicit: opts.env,
         requiredMessage: flowsMessages.list.remoteRequiresEnv
       }, (ctx, env3) => flowsListRemote(ctx, pattern, {
         env: env3,
         includeDrafts: opts.includeDrafts,
+        aiTaskId: opts.aiTaskId,
         tags
       }))(opts, command);
     }
+    if (command.getOptionValueSource("aiTaskId") === "cli") {
+      return withContext(signals, async () => ({
+        error: flowsMessages.list.aiTaskIdRequiresRemote
+      }))(opts, command);
+    }
     if (opts.includeDrafts) {
       return withContext(signals, async () => ({
         error: flowsMessages.list.draftsRequireRemote
@@ -358322,6 +358349,28 @@ function registerRunnerInspectCommands(runner, signals) {
   registerRunnerInspectMobileCommands(inspect, signals);
 }
 
+// src/domains/interactiveRunner/evaluateSnippetFailure.ts
+function describeEvaluateSnippetFailure(failure) {
+  const { failureReason } = failure;
+  switch (failureReason) {
+    case "runner-cannot-evaluate-snippets":
+      return {
+        error: interactiveRunnerMessages.runnerCannotEvaluateSnippets,
+        exitCode: exitCodes.invalidArgs
+      };
+    case "runner-unreachable":
+      return {
+        error: interactiveRunnerMessages.snippetRunnerUnreachable,
+        exitCode: exitCodes.network
+      };
+    default:
+      return {
+        error: interactiveRunnerMessages.snippetAnsweredUnknown(failureReason),
+        exitCode: exitCodes.network
+      };
+  }
+}
+
 // src/core/interactiveRunner/runFiles.ts
 import { isAbsolute as isAbsolute5, relative as relative10, resolve as resolve11, sep as sep5 } from "node:path";
 function toCollectedPath(cwd, path9) {
@@ -358383,9 +358432,8 @@ function describeRunFilesCheck(check2) {
   }
 }
 
-// src/domains/interactiveRunner/evaluateSnippet.ts
-var stdinArgument = "-";
-async function resolveScope(contextFile, deps) {
+// src/domains/interactiveRunner/snippetScope.ts
+async function resolveSnippetScope(contextFile, deps) {
   if (contextFile === undefined) {
     return { filePath: undefined, files: undefined, ok: true };
   }
@@ -358397,6 +358445,9 @@ async function resolveScope(contextFile, deps) {
   }
   return { filePath, files, ok: true };
 }
+
+// src/domains/interactiveRunner/evaluateSnippet.ts
+var stdinArgument = "-";
 async function readCode(source, deps) {
   const code = source === stdinArgument ? await deps.readStdin() : await deps.readFile(source).catch(() => {
     return;
@@ -358416,7 +358467,7 @@ async function handleRunnerExec(ctx, options, deps) {
   const code = await readCode(options.source, deps);
   if (!code.ok)
     return { error: code.error, exitCode: exitCodes.invalidArgs };
-  const scope = await resolveScope(options.contextFile, deps);
+  const scope = await resolveSnippetScope(options.contextFile, deps);
   if (!scope.ok)
     return { error: scope.error, exitCode: exitCodes.invalidArgs };
   const resolved = await resolveRunner(ctx, { autoLaunch: true, runner: options.runner }, deps);
@@ -358437,11 +358488,7 @@ async function handleRunnerExec(ctx, options, deps) {
     };
   }
   if (result.value.outcome === "failure") {
-    result.value.failureReason;
-    return {
-      error: interactiveRunnerMessages.runnerHasNoScreenToEvaluate,
-      exitCode: exitCodes.network
-    };
+    return describeEvaluateSnippetFailure(result.value);
   }
   switch (result.value.result) {
     case "success":
@@ -358792,14 +358839,13 @@ async function probeRunner(ctx, runner) {
     return { ...failureFields(result), ok: false };
   return { ok: true, runner, running: result.value.running };
 }
-async function handleRunnerList(ctx, deps) {
+async function listRunners(ctx, deps) {
   const { candidates, defaultRunnerId } = await readCandidates(deps);
   const running = [];
   const gone = [];
   for await (const probe of batchMap(candidates, (runner) => probeRunner(ctx, runner), probeBatchSize)) {
-    if (!probe.ok) {
-      return { ...failureFields(probe), exitCode: exitCodes.network };
-    }
+    if (!probe.ok)
+      return { ...failureFields(probe), ok: false };
     if (probe.running)
       running.push(probe.runner);
     else
@@ -358808,14 +358854,24 @@ async function handleRunnerList(ctx, deps) {
   await deps.store.dropRunners(gone).catch(() => {
     return;
   });
-  const items = [
-    ...running.filter((runner) => runner.id === defaultRunnerId),
-    ...running.filter((runner) => runner.id !== defaultRunnerId)
-  ].map((runner) => ({
-    id: runner.id,
-    isDefault: runner.id === defaultRunnerId,
-    runnerName: runner.runnerName
-  }));
+  return {
+    items: [
+      ...running.filter((runner) => runner.id === defaultRunnerId),
+      ...running.filter((runner) => runner.id !== defaultRunnerId)
+    ].map((runner) => ({
+      id: runner.id,
+      isDefault: runner.id === defaultRunnerId,
+      runnerName: runner.runnerName
+    })),
+    ok: true
+  };
+}
+async function handleRunnerList(ctx, deps) {
+  const listed = await listRunners(ctx, deps);
+  if (!listed.ok) {
+    return { ...failureFields(listed), exitCode: exitCodes.network };
+  }
+  const items = listed.items;
   if (ctx.ui.mode === "json") {
     ctx.ui.json(items);
     return;
@@ -358948,7 +359004,7 @@ async function handleRunnerPromoteSnapshot(ctx, options, deps) {
 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")'`;
+  $ qawolf runner events run-events --tail 20 | jq 'select(.type == "imageDiffArtifact")'`;
 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,
@@ -359691,4 +359747,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=58EAA3A3DA667AC464756E2164756E21
+//# debugId=65DBB9A4D5E4AFCD64756E2164756E21