verikun 0.22.1 → 0.24.0

package/.claude/skills/verikun/SKILL.md

@@ -17,7 +17,9 @@ description: >-
   directory of natural-language tests as a gated suite with `vk suite <dir>`
   (overview report + non-zero exit on failure — the CI gate). A remote device is
   reachable via `--server <url>` (ai/suite/install) against a `vk server` running
-  next to it. iOS (--ios): full parity via idb (tap/type/swipe/`ui` +
+  next to it. If no device is available, or one has gone flaky, start or restart it
+  with `vk devices start|stop|restart <name>` (`vk devices --all` lists what is
+  startable). iOS (--ios): full parity via idb (tap/type/swipe/`ui` +
   screenshot/launch/stop), on simulators and devices; install idb and see
   `vk doctor --ios`.
 ---
@@ -91,6 +93,8 @@ usually don't need a `wait` before an action — `vk tap @next` already polls fo
 - `vk swipe up|down|left|right [--on <selector>] [--distance f] [--duration ms]`
 - `vk swipe --from x,y --to x,y [--duration ms]`
 - `vk key <name|code>`  ·  `vk back`  ·  `vk home`  ·  `vk enter`
+  Named keys include `sleep` and `wakeup`. `power` is a **toggle**, so use `sleep`/`wakeup`
+  when you mean a direction.
 - `vk screenshot [--out path] [--more] [--max px] [--full]` — saves a PNG (default
   `./.verikun/screen.png`) and prints the path; then read that file to *see* the
   screen. It's **downscaled to a 700px longest edge by default** to save tokens
@@ -116,11 +120,15 @@ banner, the retry path, dark theme, a layout that breaks at accessibility text s
 
   | key | values | Android | iOS simulator |
   |---|---|---|---|
+  | `animations` | `on\|off` | yes | **no** — nothing disables UIKit animation |
   | `airplane` | `on\|off` | yes | **no** — a simulator has no radio |
   | `dark` | `on\|off` | yes | yes |
   | `font-scale` | `0.5`–`3.0`, `default` | yes | yes (nearest Dynamic Type category) |
   | `rotation` | `portrait\|landscape\|portrait-reverse\|landscape-reverse\|auto` | yes | **no** |
   | `stay-awake` | `on\|off` | yes | no-op (simulators don't sleep) |
+  | `screen-timeout` | `30s` / `10m` / ms / `max` | yes | no-op (simulators don't sleep) |
+  | `dnd` | `on\|off` | yes | **no** — Focus is not scriptable |
+  | `doze` | `on\|off` | yes | no-op (no Doze equivalent) |
 
   Set several at once: `vk device set dark=on font-scale=1.3`. Each change is **verified by
   reading it back**, so success means it actually landed — these device commands silently
@@ -132,6 +140,14 @@ banner, the retry path, dark theme, a layout that breaks at accessibility text s
   even when the flow *fails* — but a bare `vk device set` from a shell stays applied until
   you reset it, so don't leave someone's phone in airplane mode.
 
+- `vk device prep [--dry-run] [--revert]` — set a **test** device up once, stickily:
+  `animations=off stay-awake=on screen-timeout=max dnd=on doze=off`.
+
+  Unlike `device set`, prep **survives the run** and is undone only by `--revert`. A physical
+  device must be named (`--device <serial>`) — that requirement is deliberate, so prep can
+  never land on a personal phone that happened to be plugged in. Do not run it on a device
+  the user did not point you at. `vk doctor` reports whether a device is prepared.
+
   Two traps:
   - **`airplane=off` brings the radio back, not the internet.** Follow it with
     `vk assert <selector> --wait 10s`, never an immediate `tap`.
@@ -376,7 +392,12 @@ vk ai onboarding.md --timeout 5m        # tighten the run timeout (default 15m)
   failure).
 - **Bounded by default:** the run aborts if the estimated spend crosses **$3**
   (`--max-cost-usd`) or the wall-clock passes **15m** (`--timeout`), so a runaway
-  compile/repair loop can't spend or hang without limit.
+  compile/repair loop can't spend or hang without limit. The ceiling is **per test, not per
+  suite** — `vk suite` gives each `*.md` its own fresh budget, so 20 tests at the default can
+  reach $60; there is no suite-wide cap, so lower the per-test figure instead. A model is only
+  ever called to **compile** (once, on a cache miss) or to **repair** (≤3 per failing step);
+  replay is always $0, and every non-`ai` command is $0 always. Full mechanism, the estimate
+  formula and the cache multipliers: <https://ddikman.github.io/verikun/reference/cost/>.
 - Exit `0` pass · `1` a step failed (or the budget/timeout was hit) · `2` usage · `3` environment
   (e.g. the model's API key — `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` — unset, or the `codex` /
   `cursor-agent` CLI missing / not logged in for `--model codex-cli` / `cursor-cli`).
@@ -427,9 +448,29 @@ vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"
 ```
 
 A wrong URL/key fails fast with exit 3; `409` means another run holds the
-device. To expose a device from THIS machine: `vk server --allow-install`
+device; `503` means the server has no device attached — boot one (below). To
+expose a device from THIS machine: `vk server --allow-install`
 (add `--bind <addr>` to leave loopback; auth key auto-generates if unset).
 
+## The device is missing or wedged
+
+```sh
+vk devices --all                    # what's attached AND what could be started
+vk devices start Pixel_6_API_34     # boot it; prints the serial when drivable
+vk devices restart Pixel_6_API_34   # a live device gone flaky
+```
+
+Exit codes tell you whether to retry: **1** = unknown name, or the boot timed out
+(the device is still starting — retrying often works, and it is left running).
+**2** = ambiguous name (simulator names repeat across iOS runtimes — pass the UDID
+from `vk devices --all`), or the target is a physical device (never power-cycled).
+**3** = the toolchain is missing (set `VERIKUN_EMULATOR` to the SDK's `emulator`
+binary) — retrying will not help.
+
+`start` is idempotent, so it is safe to call when unsure. Add `--ensure-device` to
+`vk ai` / `vk suite` / `vk install` to boot once before the first step instead. Both
+work against a remote server (`--server <url>`) when it runs `--allow-device-control`.
+
 ## Test runs & reports
 
 Every action is **recorded into a test run** — one auto-starts on your first
@@ -471,11 +512,11 @@ identifier memory described above. Set `VERIKUN_NO_RUN=1` to disable recording.
 When **verikun itself** — not the app, not your selector — is the friction (a model heal on
 a *cached* replay: `[ai] plan cache hit` + a repair, or `"cached": true` with
 `modelRepairs > 0` in `--json`; a `drifted, not repaired` give-up; or a recurring gotcha in
-vk's own operation), use the **`suggest-verikun-improvement`** skill. It drafts a light,
+vk's own operation), use the **`suggest-verikun-improvement`** skill. It writes a light,
 TL;DR-first suggestion — **redacted** of every app-under-test specific (package, on-screen
-text, selector values, test prose, logs) — for you to **review before it's submitted** to
-`ddikman/verikun`. Don't hand-roll the issue: that skill owns the redaction and the
-draft-first flow.
+text, selector values, test prose, logs) — to a **local file for you to read and edit**, and
+files nothing to `ddikman/verikun` until you say so. Don't hand-roll the issue: that skill
+owns the redaction and the review-first flow.
 
 ## Exit codes — rely on these for control flow
 
@@ -488,8 +529,13 @@ draft-first flow.
 
 ## Gotchas
 
-- **Disable animations once** for reliable dumps: `vk doctor --fix`. Live
-  animations can make `vk ui` flaky (it already retries 3×).
+- **Prepare the device once** for reliable dumps: `vk device prep` (a physical device
+  needs `--device <serial>`). Live animations can make `vk ui` flaky (it already retries 3×).
+- **A slept device returns the LOCK SCREEN, not an error.** The dump succeeds and hands
+  back `com.android.systemui` — so selectors miss for a reason unrelated to the app.
+  verikun detects this, wakes the device and clears a *swipe* lock automatically; on a
+  PIN/pattern/password it exits **3** naming the lock rather than returning that dump.
+  Tell the user to remove the lock in Settings > Security — verikun never asks for a PIN.
 - **Ambiguous selector → exit 2**, never a random tap. `vk` prints the candidate
   matches; add `--index N` or use a more specific selector.
 - **Indexes are per-snapshot.** `vk tap 3` taps `[3]` from the *latest* dump;
@@ -527,13 +573,15 @@ draft-first flow.
   use `xcrun simctl`. Run `vk doctor --ios` to check the toolchain. Caveats: `clear`
   is unsupported (no per-app reset), `current` is `(unknown)`, device logs are
   simulator-only, and `device set` is partial — `dark`/`font-scale` work on a simulator
-  while `airplane`/`rotation` do not exist there at all (`vk device caps --ios`). iOS
+  while `animations`/`airplane`/`rotation`/`dnd` do not exist there at all, and
+  `stay-awake`/`screen-timeout`/`doze` are no-ops (`vk device caps --ios`). That makes
+  `vk device prep` effectively Android-only: on iOS it applies nothing and says so. iOS
   accessibility ids are often unset, so prefer `text:`/`desc:` selectors there.
 
 ## Worked example — verify a login flow
 
 ```sh
-vk doctor --fix                              # deterministic UI
+vk doctor                                    # is the device set up? (read-only)
 vk launch com.example.app
 vk text @email_input "user@example.com"      # field lookup auto-waits up to 5s
 vk text @password_input "hunter2" --enter

package/CHANGELOG.md

@@ -6,6 +6,68 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-08-20
+
+### Added
+- **`vk device prep`**: prepare a test device once — animations off, display awake, DND on, doze off.
+- **`vk device prep --revert`**: restore what prep changed, from a host-global snapshot that outlives the run.
+- **`vk device prep --dry-run`**: show each knob's current and target value without writing.
+- **`vk device set animations|screen-timeout|dnd|doze`**: four new keys, each verified by readback.
+- **`vk key sleep` / `vk key wakeup`**: directional screen keys; `power` remains a toggle.
+- **`vk doctor`**: reports whether the device is prepared and whether it has a screen lock.
+- **Docs site**: a `Cost & budget` reference page — when a model is called, the estimate formula,
+  and that `--max-cost-usd` is per test, not per suite. ([#94])
+
+### Changed
+- **`vk doctor --fix`**: now an alias for `device prep`, so a physical device must be named with `--device`.
+- **`vk doctor`**: read-only without `--fix`; it no longer writes animation scales directly.
+- **`vk batch|ai|suite`**: put a prepped device to sleep on teardown; `--no-sleep-when-idle` opts out.
+
+### Fixed
+- **UI reads**: a locked device returned the lock screen as a successful dump; now woken, unlocked if
+  the lock is a swipe, else exit `3` naming it.
+- **Docs site**: the `vk ai` cost line was printed in a format the CLI never emitted.
+
+[#94]: https://github.com/ddikman/verikun/issues/94
+
+## [0.23.0] - 2026-08-17
+
+### Added
+- **`npm run docs` / `docs:install` / `docs:build`**: run the documentation site from the repo
+  root; README covers the local setup.
+- **`vk devices start|stop|restart <name>`**: boot, shut down or power-cycle an Android AVD or iOS
+  simulator. `start` is idempotent and waits until the device is actually drivable.
+- **`vk devices --all`**: also lists startable (not-yet-booted) AVDs and simulators.
+- **`vk devices start|restart --wipe`**: erase the device's data first (`-wipe-data` / `simctl erase`).
+- **`vk server --allow-device-control[=names]`**: let a client restart/stop the server's device;
+  `=names` also permits starting those targets. The server may then listen with no device bound.
+- **`--ensure-device[=name]`** on `ai`/`suite`/`install`: boot a device once before the first step.
+- **`VERIKUN_EMULATOR`**: path to the SDK `emulator` binary when it is not on `PATH`.
+
+### Changed
+- **`vk devices`**: gains `KIND` and `NAME` columns, so an emulator shows the AVD name you pass to
+  `stop`/`restart`.
+- **`/v1/health`**: `serial` may now be `null`; adds `deviceControlEnabled`, `deviceNamingEnabled`
+  and `deviceState` for feature detection.
+
+### Fixed
+- **`vk devices start --server`**: releases the device lock when it finishes, instead of `409`ing
+  the run it just booted the device for.
+
+### Changed
+- **Docs site**: content column widened to 60rem, giving the reference tables more room on
+  large screens.
+
+## [0.22.2] - 2026-08-17
+
+### Changed
+- **`suggest-verikun-improvement`**: the draft is written to `.context/` for review; nothing is
+  filed until you say so. ([#66])
+- **Improvement reports**: `Shape of the fix` becomes a short `Proposed fix` — a few bullets,
+  not a spec. ([#66])
+
+[#66]: https://github.com/ddikman/verikun/issues/66
+
 ## [0.22.1] - 2026-08-15
 
 ### Added
@@ -437,22 +499,6 @@ All notable changes to this project are documented here. The format is based on
   e2e fixture app, 74 files of Gradle/Xcode/PNG that no end user installing the CLI should download.
 - `publish.yml` also verifies `package-lock.json` is in sync with `package.json`'s version. `npm ci`
   does not catch this — it errors only on dependency drift, never on the root `version` field.
-
-### Fixed
-- **The Claude Code plugin no longer ships the contributor-only `create-pr` skill.** The manifest
-  pointed `skills` at the container `.claude/skills/`, and that field only ever *adds* to the scan,
-  so every skill in it reached end users — costing roughly 260 always-on tokens per session for one
-  they cannot use. It now lists the two user-facing skills explicitly. Naming a single skill would
-  not do: that drops `suggest-verikun-improvement`, which the main skill hands off to.
-
-- **`CHANGELOG.md` is now included in the published npm package.** `package.json`'s `"files"` is an
-  allowlist, and npm force-includes only `package.json`, `README`, `LICENSE`, the `main` file and the
-  `bin` file(s) — a changelog is *not* on that list (npm 5/6 included one; modern npm does not).
-  Every release up to 0.19.0 therefore published without a changelog, and did so silently: the
-  publish succeeded, CI was green, and nothing anywhere reported the omission.
-  `tests/package-files.test.ts` now guards the allowlist, including against an entry whose path no
-  longer exists.
-
 ## [0.19.0] - 2026-08-08
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@
 
 - **Agent CLI** — `vk <command>`: one-shot commands to inspect the screen as a semantic tree (or screenshot) and act on it.
 - **Puppeteer for native mobile** — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
-- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step.
+- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. [What that costs](https://ddikman.github.io/verikun/reference/cost/), and how the `--max-cost-usd` ceiling bounds it.
 - **Self-improving** — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
 - **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run; `vk server` exposes a real device over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive it.
 
@@ -37,7 +37,8 @@ The package also carries the agent [`SKILL.md`](.claude/skills/verikun/SKILL.md)
 ## Quick start
 
 ```sh
-vk doctor --fix                 # check adb/device; disable animations for stable dumps
+vk doctor                       # check adb/device (read-only — never changes anything)
+vk device prep --device <id>    # set a TEST device up once: animations off, stays awake
 vk devices                      # list attached devices
 vk ui                           # semantic snapshot of the current screen
 vk tap @login_button            # tap by resource-id
@@ -71,7 +72,7 @@ There is also no need for an MCP here: verikun runs locally with all its depende
 
 verikun improves from the rough edges people hit while driving it. When verikun *itself* is the friction — a step that heals on every cached replay (an unstable compiled selector, often a label-only control with no resource-id), a repair "give-up", or a gotcha in its own operation — that's worth an issue at [github.com/ddikman/verikun/issues](https://github.com/ddikman/verikun/issues).
 
-Driving verikun with an AI agent + the [skill](.claude/skills/verikun/SKILL.md)? It hands off to the **`suggest-verikun-improvement`** skill, which drafts a short, TL;DR-first suggestion, **reviews it with you before anything is submitted**, and **redacts every app-under-test specific** (package, on-screen text, selector values, test prose, logs) so no client code or logic can leak.
+Driving verikun with an AI agent + the [skill](.claude/skills/verikun/SKILL.md)? It hands off to the **`suggest-verikun-improvement`** skill, which writes a short, TL;DR-first suggestion **to a local file for you to read and edit**, **files nothing until you say so**, and **redacts every app-under-test specific** (package, on-screen text, selector values, test prose, logs) so no client code or logic can leak.
 
 ## Contributing
 
@@ -84,6 +85,16 @@ npm link         # optional: put `verikun` and `vk` on your PATH
 
 Zero runtime dependencies; the only dev dependencies are `typescript` and `@types/node`. The full contributor guide — the test loop, the Flutter device fixture, versioning and releasing — is in [Contributing](https://ddikman.github.io/verikun/internals/contributing/).
 
+To work on the [documentation site](https://ddikman.github.io/verikun/), which is an Astro Starlight project in `docs/` with its own dependencies (so `npm install` above does not cover it):
+
+```sh
+npm run docs:install   # once — installs the site's dependencies (needs Node >= 22.12)
+npm run docs           # dev server with live reload at http://localhost:4321/verikun/
+npm run docs:build     # production build; fails on a dead internal link
+```
+
+Open **http://localhost:4321/verikun/** — the site is served under a base path, so bare `localhost:4321` is a 404. Astro needs **Node ≥ 22.12** while the CLI supports Node ≥ 18, so `nvm use 22` first if your shell's Node is older.
+
 ## License
 
 [MIT](LICENSE)

package/dist/agent/remote.js

@@ -10,6 +10,8 @@
 // local one. Recording stays a caller concern: this module never touches ./.verikun.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pingServer = pingServer;
+exports.remoteDeviceOp = remoteDeviceOp;
+exports.remoteDeviceList = remoteDeviceList;
 exports.createRemoteBackend = createRemoteBackend;
 const node_fs_1 = require("node:fs");
 const node_crypto_1 = require("node:crypto");
@@ -22,6 +24,11 @@ const HEALTH_TIMEOUT_MS = 10_000;
 const ELEMENTS_TIMEOUT_MS = 60_000;
 const EXEC_TIMEOUT_MS = 10 * 60_000;
 const INSTALL_TIMEOUT_MS = 15 * 60_000;
+const DEVICE_LIST_TIMEOUT_MS = 30_000;
+// Above the server's own 4-minute boot ceiling, so the SERVER reports why a boot
+// timed out rather than the client aborting into a generic "timed out after 300s".
+const DEVICE_START_TIMEOUT_MS = 5 * 60_000;
+const DEVICE_STOP_TIMEOUT_MS = 60_000;
 const trimUrl = (url) => url.replace(/\/+$/, '');
 function describeStatus(status, body, url) {
     const detail = body?.error ? `: ${body.error}` : '';
@@ -31,6 +38,9 @@ function describeStatus(status, body, url) {
     if (status === 409) {
         return new errors_1.CliError(`verikun server device is busy (409)${detail || ' — another run holds the device; retry when it finishes'}.`, 3);
     }
+    if (status === 503) {
+        return new errors_1.CliError(`verikun server has no device attached (503)${detail}.`, 3);
+    }
     // The server sends the intended exit code (usage 2 / env 3) in the body; fall
     // back on the HTTP class when it didn't.
     const exitCode = body?.exitCode ?? (status === 400 || status === 404 || status === 413 ? 2 : 3);
@@ -89,6 +99,15 @@ class RemoteTransport {
     postJson(path, payload, timeoutMs) {
         return this.request('POST', path, JSON.stringify(payload), timeoutMs, { 'content-type': 'application/json' });
     }
+    /** Best-effort: give the device lock back. A lock we fail to release ages out. */
+    async release() {
+        try {
+            await this.postJson('/v1/release', {}, HEALTH_TIMEOUT_MS);
+        }
+        catch {
+            /* the idle takeover covers it */
+        }
+    }
 }
 /** GET /v1/health — the `--server` preflight. Reachability, the server's platform +
  *  serial (which become the run's context), and — when a key is supplied — an auth
@@ -101,6 +120,31 @@ async function pingServer(opts) {
     }
     return health;
 }
+/**
+ * POST /v1/devices/{start,restart,stop}. Standalone beside pingServer rather than on
+ * the ExecBackend seam: that seam is the engine's DEVICE WORK (exec/getElements/
+ * install/reset), and adding administration to it would oblige the local backend to
+ * implement a verb nothing in the engine ever calls.
+ */
+async function remoteDeviceOp(opts, op, body = {}) {
+    const t = new RemoteTransport(opts);
+    const timeout = op === 'stop' ? DEVICE_STOP_TIMEOUT_MS : DEVICE_START_TIMEOUT_MS;
+    try {
+        return await t.postJson(`/v1/devices/${op}`, body, timeout);
+    }
+    finally {
+        // This is a one-shot administrative call under its own run token, not a run —
+        // so hand the device lock straight back. Without this, `vk devices start
+        // --server` (and the --ensure-device preflight, which uses its own token) would
+        // 409 the very run it just booted the device for, until the 5-minute idle takeover.
+        await t.release();
+    }
+}
+/** GET /v1/devices — what the server can see and what it will boot on request. */
+async function remoteDeviceList(opts) {
+    const t = new RemoteTransport(opts);
+    return t.request('GET', '/v1/devices', undefined, DEVICE_LIST_TIMEOUT_MS);
+}
 function decodeArtifacts(encoded) {
     const out = {};
     for (const [rel, b64] of Object.entries(encoded ?? {}))

package/dist/args.js

@@ -43,8 +43,16 @@ const BOOLEAN = new Set([
     'no-cache',
     'no-restart',
     'no-logs',
+    'wipe',
+    'dry-run',
+    'revert',
+    'no-sleep-when-idle',
     'allow-install',
     'allow-unsafe-anonymous',
+    // NOT here on purpose: 'allow-device-control' and 'ensure-device' are tri-state
+    // (absent / on / on-with-a-value), and the inline `--flag=value` branch is checked
+    // BEFORE this set — listing them would make `--allow-device-control=Pixel_6` parse
+    // fine but `--ensure-device Pixel_6` silently become a boolean plus a positional.
     // Selector state modifiers (STATE_ATTRS in ui/selector.ts) and their negations.
     // `enabled` was missing here until 0.15.0, and the omission was not cosmetic: a
     // non-BOOLEAN flag swallows the next token, so `vk tap --enabled @submit` bound