@qawolf/cli 1.12.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.12.0",
+  "version": "1.13.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.26.0",
+    "@qawolf/api-contracts": "0.27.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -73,7 +73,7 @@
     "superjson": "2.2.6",
     "tar": "7.5.21",
     "tinyglobby": "0.2.17",
-    "webdriverio": "9.27.1",
+    "typescript": "6.0.3",
     "zod": "4.4.3"
   },
   "devDependencies": {
@@ -82,6 +82,8 @@
     "@tsconfig/strictest": "2.0.8",
     "@types/bun": "1.3.14",
     "@types/picomatch": "4.0.3",
+    "@wdio/globals": "9.29.1",
+    "@wdio/logger": "9.18.0",
     "appium": "3.6.0",
     "appium-uiautomator2-driver": "8.4.0",
     "expect-webdriverio": "5.6.5",
@@ -89,7 +91,7 @@
     "oxfmt": "0.54.0",
     "oxlint": "1.69.0",
     "oxlint-tsgolint": "0.23.0",
-    "typescript": "6.0.3"
+    "webdriverio": "9.27.1"
   },
   "engines": {
     "node": ">=20.19.0"

package/skills/qawolf-cli/SKILL.md

@@ -53,7 +53,7 @@ An interactive runner is a live pod holding a browser, and it is billed while it
 runs. `qawolf runner launch` starts one; `qawolf runner run` starts one too when
 no runner is already available, and says so when it does. Reading a runner
 counts as activity, so `qawolf runner events --follow` left open keeps it alive
-and billing. `qawolf runner stop` is what ends it, so stop a runner you launched
+and billing. `qawolf runner terminate` is what ends it, so terminate a runner you launched
 rather than leaving it to time out.
 
 `qawolf runner launch` remembers its runner as this directory's default, so the
@@ -144,11 +144,16 @@ 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 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 run` | write | Run a flow on an interactive runner, shipping the current directory's files with 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` | write | Stop an interactive runner |
+| `qawolf runner stop-run` | write | Stop what a runner is currently executing, leaving the runner up |
+| `qawolf runner terminate` | write | End an interactive runner, and the pod it runs on with it |
 | `qawolf tag create` | write | Create a tag on the caller's team. Tags select flows in run.create. |
 | `qawolf tag list` | read | List the team's tags, alphabetical by name. Tag names select flows in run.create. |
 
@@ -164,7 +169,8 @@ call the QA Wolf API and require auth.
 The `runner` commands drive a live cloud browser: `launch` one, `screenshot` to
 see it, `act` to click and type, `run` a flow on it, `exec` a snippet against its
 page, `events` to read its journal (including the `recorder` stream, which turns
-your actions into Playwright locators), `keepalive` to hold it open, and `stop`
+your actions into Playwright locators), `keepalive` to hold it open, and
+`terminate`
 when done. Everything is a plain request to one host, so a shell with an API key
 and its own vision model can close the see-and-act loop with no other tooling.
 

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

@@ -9,7 +9,7 @@ plain request to one host, so there is no connection to hold open.
 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
-`outcome` for `launched` or `already-running`. Reusing one id is therefore the
+`alreadyRunning`. Reusing one id is therefore the
 cheap and safe pattern, and the same id with a different `--name` is refused
 rather than silently ignored.
 
@@ -38,8 +38,8 @@ 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.
 
 No `read` command ever launches a runner. `screenshot`, `events` and `keepalive`
-tell you there is no runner rather than quietly billing one, and so does `stop`,
-since starting a pod in order to stop it would be absurd.
+tell you there is no runner rather than quietly billing one, and so does
+`terminate`, since starting a pod in order to end it would be absurd.
 
 ## The order that matters
 
@@ -57,10 +57,15 @@ None of that is a fault, and none of it clears on its own. **Only
 `qawolf runner run <flow>` starts the screen.** A bare navigate does not: it
 fails until the first run, however long you wait.
 
-So the first call on a new runner has to be a run. 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 below works for the rest of the runner's life.
+So the first thing you do to a new runner has to put a browser on it. That means
+a flow file and a `package.json` on disk, even if all you want is to drive the
+browser by hand; there is no "just give me a screen" call. Once one run has
+happened, the screenshot-and-act loop below works for the rest of the runner's
+life.
+
+A `--lines` selection is the one call that does not need a run first. Sent to a
+runner with no browser, the runner starts one and runs your lines against it,
+and says so on stderr. Everything else on this page waits for a run.
 
 Retry on the exit code, not on the message text:
 
@@ -71,7 +76,7 @@ Retry on the exit code, not on the message text:
   persists past a few tries, relaunch the id.
 - `2` will not clear on its own. Either nothing has run on this runner yet, so
   run a flow, or the runner has no browser at all, so launch with
-  `--name node20WithPlaywright` instead. The message says which.
+  `--name playwright` instead. The message says which.
 
 The one exception is `exec`, which reports both as `4`; read its message to tell
 them apart.
@@ -128,6 +133,50 @@ has 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.
 
+## Reading the page: `inspect`
+
+`qawolf runner inspect` answers one question about the live page and prints the
+answer on stdout by itself, so you can redirect or pipe it:
+
+```sh
+qawolf runner inspect element-html --selector "#email"
+qawolf runner inspect page-html > page.html
+qawolf runner inspect page-html --selector "#cart"      # just that subtree
+qawolf runner inspect variable --name cart | jq .total
+```
+
+`page-html` is simplified for a model to read rather than being the browser's
+exact markup. `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.
+
+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.
+
+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.
+
+## Installing a package mid-session
+
+`qawolf runner import-package <name>` installs a package into the runner's live
+run, so a snippet or a selection can import it without a whole run to reinstall
+dependencies:
+
+```sh
+qawolf runner import-package dayjs
+qawolf runner import-package dayjs --package-version 1.11.13
+```
+
+The version defaults to `latest`, and 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.
+
 ## Reading the page: `exec`
 
 `qawolf runner exec <file>` evaluates a snippet against whatever the runner's
@@ -153,19 +202,73 @@ so the snippet can use your own page objects and helpers.
 
 ## Running a flow
 
-`qawolf runner run <file>` ships the current directory's runnable files with the
-request. The runner holds no copy of your project, so what runs is exactly what
-is on disk at that moment, uncommitted edits included. A `package.json` has to
-be there, since the run reads its npm dependencies from it, and the files may
-carry at most 4 MiB in total: run from a directory holding the flow and what it
-imports rather than from the root of a large monorepo. 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.
+`qawolf runner run <flowFile>` 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.
+
+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.
+
+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 as `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.
 
 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.
 
+### Running part of a flow
+
+`--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.
+
+The two file paths are the thing to get right, because getting them backwards
+runs the wrong code and nothing reports it:
+
+- the positional is **always the flow file**. It is the run's entry point, and it
+  is required for every run, selection or not.
+- `--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.
+
+```sh
+qawolf runner run flows/checkout.flow.ts --lines 12-40          # lines in the flow file
+qawolf runner run flows/checkout.flow.ts --lines 4-9 \
+  --lines-file pages/login.ts                                   # lines in a page object
+```
+
+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.
+
+### Giving the run environment variables
+
+`--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.
+
+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.
+
+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.
+
 **Pass `--follow` to `run` and let it wait for you.** It reports the run's
 status — in progress, then passed or failed — and ends on the settled status.
 Exit code `1` means the run did not pass. Three flags mirror more streams into
@@ -264,10 +367,25 @@ pod that is gone. It resets the clock and tells you the runner is still there.
 
 It is listed as a `read`, but it is the one 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 stop` when you are done rather
+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.
 
+## Stopping a run vs ending a runner
+
+Two different things, and the names are the only warning you get:
+
+- `qawolf runner 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.
+- `qawolf runner 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.
+
+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.
+
 ## End to end
 
 Run from a directory holding a flow and a `package.json`. The run is what starts
@@ -277,7 +395,7 @@ the screen, so it is not optional even though the goal here is to drive by hand.
 export QAWOLF_API_KEY=...          # the only credential
 export QAWOLF_RUNNER_ID=agent-1    # so no command below needs --runner
 
-qawolf runner launch --id agent-1 --json          # --id, not the variable; read .outcome
+qawolf runner launch --id agent-1 --json          # --id, not the variable; read .alreadyRunning
 qawolf runner run flows/smoke.flow.ts --follow    # starts the screen; exit 1 if it failed
 
 qawolf runner act navigate --url https://example.com/login
@@ -285,6 +403,10 @@ qawolf runner screenshot --out page.jpg           # then read page.jpg yourself
 qawolf runner act click --button left --x 480 --y 260
 qawolf runner act type --text "someone@example.com"
 
+qawolf runner inspect element-html --selector "#email"
+qawolf runner inspect variable --name cart | jq .total
+
+qawolf runner run flows/smoke.flow.ts --lines 12-40 --follow   # just those lines
 qawolf runner events recorder --tail 5 | jq -r '[.locator] + (.alternates // []) | @tsv'
-qawolf runner stop
+qawolf runner terminate
 ```