@qawolf/cli 1.20.1 → 1.21.0

package/dist/types/runnerSdk/index.d.ts

@@ -0,0 +1,24 @@
+import type { ListedRunner, RunnerSdkOptions, SdkResult } from "./types.js";
+export type { ActRequest, EvaluateSnippetRequest, EvaluatedSnippet, EventsRequest, FileSync, HighlightRequest, HighlightSelectorRequest, HighlightedSelector, ImportPackageRequest, ImportedPackage, InspectRequest, Inspected, Journal, JournalWindow, KeptAlive, LaunchRequest, LaunchedRunner, LinesLocation, ListedRunner, PackageVersion, PerformedAction, PromoteSnapshotRequest, PromotedSnapshot, RunEnvironment, RunFilter, RunRequest, RunSelection, RunnerFamily, RunnerRequest, RunnerSdkOptions, Screenshot, SdkResult, SnippetScope, StoppedRun, SubmittedRun, TerminatedRunner, } from "./types.js";
+export type RunnerSdk = ReturnType<typeof createRunnerSdk>;
+/**
+ * Drives interactive runners on the caller's team through the QA Wolf public
+ * API. Every verb names the runner it addresses, so nothing is launched or
+ * billed implicitly: call `launch` for that.
+ */
+export declare function createRunnerSdk(options: RunnerSdkOptions): {
+    list(): Promise<SdkResult<ListedRunner[]>>;
+    evaluateSnippet({ runnerId, scope, source, }: import("./types.js").EvaluateSnippetRequest): Promise<SdkResult<import("./types.js").EvaluatedSnippet>>;
+    importPackage({ name, runnerId, version, }: import("./types.js").ImportPackageRequest): Promise<SdkResult<import("./types.js").ImportedPackage>>;
+    act({ action, runnerId, }: import("./types.js").ActRequest): Promise<SdkResult<import("./types.js").PerformedAction>>;
+    highlightSelector({ highlight, runnerId, }: import("./types.js").HighlightSelectorRequest): Promise<SdkResult<import("./types.js").HighlightedSelector>>;
+    inspect({ request, runnerId, }: import("./types.js").InspectRequest): Promise<SdkResult<import("./types.js").Inspected>>;
+    promoteSnapshot({ baselinePath, runnerId, screenshotPath, }: import("./types.js").PromoteSnapshotRequest): Promise<SdkResult<import("./types.js").PromotedSnapshot>>;
+    screenshot({ runnerId, }: import("./types.js").RunnerRequest): Promise<SdkResult<import("./types.js").Screenshot>>;
+    events({ runFilter, runnerId, stream, window, }: import("./types.js").EventsRequest): Promise<SdkResult<import("./types.js").Journal>>;
+    run({ entryPointPath, environment, runnerId, selection, }: import("./types.js").RunRequest): Promise<SdkResult<import("./types.js").SubmittedRun>>;
+    keepalive({ runnerId, }: import("./types.js").RunnerRequest): Promise<SdkResult<import("./types.js").KeptAlive>>;
+    launch({ id, runnerFamily, }: import("./types.js").LaunchRequest): Promise<SdkResult<import("./types.js").LaunchedRunner>>;
+    stopRun({ runnerId }: import("./types.js").RunnerRequest): Promise<SdkResult<import("./types.js").StoppedRun>>;
+    terminate({ runnerId, }: import("./types.js").RunnerRequest): Promise<SdkResult<import("./types.js").TerminatedRunner>>;
+};

package/dist/types/runnerSdk/types.d.ts

@@ -0,0 +1,120 @@
+import type { BrowserAction, InspectOnRunnerRequest, JournalStream, PublicApiOutput, ReadJournalResponse, RunnerNameForPublicApi, publicContractsV1 } from "@qawolf/api-contracts/v1";
+type Runner = typeof publicContractsV1.runner;
+export type RunnerSdkOptions = {
+    /** A QA Wolf team API key. The SDK never reads the CLI's stored credentials. */
+    apiKey: string;
+    /** Defaults to `QAWOLF_HOST_URL`, then `https://app.qawolf.com`. */
+    baseUrl?: string | undefined;
+    /** Where a run collects its files from. Defaults to `process.cwd()`. */
+    cwd?: string | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+};
+export type SdkResult<Value> = {
+    error: string;
+    ok: false;
+} | {
+    ok: true;
+    value: Value;
+};
+export type RunSelection = "whole-flow" | {
+    endLine: number;
+    linesIn: LinesLocation;
+    startLine: number;
+};
+export type LinesLocation = "entry-point" | {
+    filePath: string;
+};
+export type RunEnvironment = "ambient" | {
+    id: string;
+};
+export type SnippetScope = "no-imports" | {
+    filePath: string;
+};
+export type HighlightRequest = "clear" | {
+    selector: string;
+};
+export type PackageVersion = "latest" | {
+    exact: string;
+};
+export type RunnerFamily = "default" | {
+    name: RunnerNameForPublicApi;
+};
+export type JournalWindow = "newest" | {
+    sinceSequence: number;
+} | {
+    tail: number;
+};
+export type RunFilter = "all-runs" | {
+    runId: string;
+};
+export type LaunchRequest = {
+    id: string;
+    runnerFamily: RunnerFamily;
+};
+export type RunnerRequest = {
+    runnerId: string;
+};
+export type RunRequest = RunnerRequest & {
+    entryPointPath: string;
+    environment: RunEnvironment;
+    selection: RunSelection;
+};
+export type EventsRequest = RunnerRequest & {
+    runFilter: RunFilter;
+    stream: JournalStream;
+    window: JournalWindow;
+};
+export type ActRequest = RunnerRequest & {
+    action: BrowserAction;
+};
+export type EvaluateSnippetRequest = RunnerRequest & {
+    scope: SnippetScope;
+    source: string;
+};
+export type InspectRequest = RunnerRequest & {
+    request: InspectOnRunnerRequest;
+};
+export type ImportPackageRequest = RunnerRequest & {
+    name: string;
+    version: PackageVersion;
+};
+export type HighlightSelectorRequest = RunnerRequest & {
+    highlight: HighlightRequest;
+};
+export type PromoteSnapshotRequest = RunnerRequest & {
+    baselinePath: string;
+    screenshotPath: string;
+};
+export type LaunchedRunner = PublicApiOutput<Runner["launch"]>;
+export type TerminatedRunner = PublicApiOutput<Runner["terminate"]>;
+export type StoppedRun = PublicApiOutput<Runner["stopRun"]>;
+export type Screenshot = PublicApiOutput<Runner["takeScreenshot"]>;
+export type PerformedAction = PublicApiOutput<Runner["performAction"]>;
+export type EvaluatedSnippet = PublicApiOutput<Runner["evaluateSnippet"]>;
+export type Inspected = PublicApiOutput<Runner["inspect"]>;
+export type ImportedPackage = PublicApiOutput<Runner["importPackage"]>;
+export type HighlightedSelector = PublicApiOutput<Runner["highlightSelector"]>;
+export type PromotedSnapshot = PublicApiOutput<Runner["promoteSnapshot"]>;
+/** A journal window, as the public API answers it. */
+export type Journal = ReadJournalResponse;
+/** The CLI's own answer: the file set it sent whole, or only what changed. */
+export type FileSync = "delta" | "full";
+/**
+ * `fileSync` and `bootstrappedRunner` are the CLI's own, so this is not the
+ * `runner.runFlow` output verbatim.
+ */
+export type SubmittedRun = {
+    bootstrappedRunner: boolean;
+    fileSync: FileSync;
+    runId: string;
+};
+/** Runners this working directory launched, which the API has no notion of. */
+export type ListedRunner = {
+    id: string;
+    isDefault: boolean;
+    runnerName: string | undefined;
+};
+export type KeptAlive = {
+    id: string;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.20.1",
+  "version": "1.21.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -28,16 +28,27 @@
     "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 .",
@@ -60,7 +71,7 @@
     "@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",

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

@@ -92,7 +92,7 @@ something:
 - `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
-- `exec` fails with exit code `4`
+- `exec` fails with exit code `2`
 - `events recorder` reads as empty
 
 None of that is a fault, and none of it clears on its own. **Only
@@ -120,9 +120,6 @@ Retry on the exit code, not on the message text:
   run a flow, or the runner has no browser at all, so launch with
   `--name playwright` instead. The message says which.
 
-The one exception is `exec`, which reports both as `4`; read its message to tell
-them apart.
-
 ## Seeing and acting: the loop is yours
 
 Two primitives, and you close the loop with your own model. There is no hosted
@@ -288,7 +285,7 @@ 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 events run-events --tail 20 | jq 'select(.type == "imageDiffArtifact")'
 qawolf runner promote-snapshot --screenshot checkout-1-actual.png --baseline checkout-1.png
 ```