verikun 0.18.0 → 0.19.0

package/README.md

@@ -95,6 +95,16 @@ vk screenshot                   # -> ./.verikun/screen.png
 | `clear <app>` | Wipe the app's locally stored data — login/session, preferences, caches — resetting it to a just-installed state (Android `pm clear`, which also force-stops the app). iOS unsupported: there is no per-app data reset. |
 | `install <app.apk\|.ipa> [--server url]` | Install a build on the device (`adb install -r` / `idb install`). With `--server`, the file is uploaded to a remote [`vk server`](#remote-devices--vk-server) started with `--allow-install` (single-file `.apk`/`.ipa`, sha256-verified). |
 
+### Device state
+| Command | Description |
+|---|---|
+| `device set <key>=<value> …` | Change the *device* the app runs on, snapshotting each original first. Keys: `airplane`, `dark`, `font-scale`, `rotation`, `stay-awake`. Every change is **verified by reading it back** — `svc`/`cmd`/`settings put` are fire-and-forget and silently no-op on some OEM skins, so trusting the exit code would report success for a change that never happened. Refuses `airplane=on` over a wireless adb link (it would cut the connection carrying the next command); `--allow-wireless` overrides. |
+| `device get [key] [--json]` | Current values; `n/a` where the platform can't answer. |
+| `device reset [key …]` | Restore what this run changed. `batch`, `ai` and `suite` also do this automatically when the flow ends **or fails**, so a dead test can't leave your phone offline or rotated. |
+| `device caps [--json]` | What the active platform supports, and the manual equivalent where it doesn't. |
+
+See [Device state](#device-state-1) for the per-platform matrix.
+
 ### Batch
 | Command | Description |
 |---|---|
@@ -144,11 +154,17 @@ skips the archive dump on green runs (failures still capture).
 - **`report.html`** — a self-contained report: every step, the identifiers used,
   any screenshots taken, the screenshot + hierarchy of any failed page, a link to
   the full device log, an app-scoped log accordion when the run launched an app,
-  and any per-step logs from `vk log`.
+  and any per-step logs from `vk log`. A run that did not pass says so in a banner
+  at the top.
 - **`artifacts/logcat.txt`** — full device log for the run window (default).
 - **`artifacts/logcat-app.txt`** — app-scoped log (when a package/bundle was launched).
 - **`run.json`** — the raw recording.
 
+A `vk ai` run can also fail where no single command did — a `repeat` that never
+sees its target, a cost/timeout abort. That verdict is recorded too (as
+`run.json`'s `failure`, plus a failed step carrying the reason and a screenshot),
+so a failed test is never reported as `failures="0"` in the JUnit that CI reads.
+
 `vk run archive` exits non-zero when the run contained failures, so the same
 command both produces the report and gates CI.
 
@@ -602,6 +618,58 @@ at runtime, so driving a flow to a report should capture liberally around transi
 `vk ai` does this automatically (see [AI](#ai--natural-language-tests)); when driving by
 hand, `vk screenshot` around each screen change and leave the PNG in the report.
 
+## Device state
+
+Some behaviour only appears when the *device* changes underneath the app: the offline
+banner, the retry path, dark theme, a layout that breaks at accessibility text sizes,
+landscape. `vk device set` changes those, verifies each one landed, and — this is the part
+that makes it safe to point at your own phone — **puts them back**.
+
+```sh
+vk device set airplane=on                              # go offline
+vk tap @retry
+vk assert text:"No connection"
+vk device reset                                        # back online
+
+vk device set dark=on font-scale=1.3 rotation=landscape  # several at once
+vk device get --json
+vk device caps                                         # what this platform supports
+```
+
+| key | values | Android | iOS simulator | iOS device |
+|---|---|---|---|---|
+| `airplane` | `on\|off` | ✅ | ❌ no radio to switch off | ❌ |
+| `dark` | `on\|off` | ✅ | ✅ | ❌ |
+| `font-scale` | `0.5`–`3.0`, or `default` | ✅ | ✅ mapped to the nearest Dynamic Type category | ❌ |
+| `rotation` | `portrait\|landscape\|portrait-reverse\|landscape-reverse\|auto` | ✅ | ❌ neither simctl nor idb rotates | ❌ |
+| `stay-awake` | `on\|off` | ✅ | ⊘ no-op — simulators don't sleep | ❌ |
+
+An unsupported key exits **3 before any device I/O**, naming the manual equivalent, so a
+test asking for something the platform can't do fails on the first step rather than
+half-way through a half-modified device. `vk device caps --json` is the same matrix for
+whatever platform you're pointed at.
+
+**Restore is the point.** `device set` records what each setting held *before* it changed
+it, in the run file rather than in memory — so `vk device reset` works from a later process
+too. `batch`, `ai` and `suite` restore automatically in a `finally`, which is what stops a
+test that dies between `airplane=on` and `airplane=off` from leaving your phone offline.
+A bare `vk device set` from your shell stays applied until you reset it, deliberately.
+
+Three things worth knowing:
+
+- **`airplane=on` is verified by effect, not by the flag.** Android remembers a user who
+  re-enabled wifi during a previous flight, so `airplane-mode enable` can leave wifi *up*.
+  `vk` reads the device's own `airplane_mode_toggleable_radios` — the radios that can
+  survive the flag — confirms each actually went down, and forces any survivor. Reporting
+  "offline" while the app is still online would make an offline test pass for the wrong
+  reason. (Cellular is not in that list, and `mobile_data` is a stored preference rather
+  than live radio state, so it is deliberately not probed.)
+- **`airplane=off` re-enables the radio, not the internet.** Follow it with
+  `vk assert <selector> --wait 10s` rather than tapping straight away.
+- **Wireless adb is refused for `airplane=on`.** It would cut the very link carrying the
+  next command, and nothing could turn it back on remotely. Exit 2; `--allow-wireless` if
+  you mean it.
+
 ## How it works
 
 ```
@@ -652,6 +720,10 @@ your setup with `vk doctor --ios`. `vk --ios tap`, `vk --ios ui`, etc. then work
 - `log` capture is simulator-only (via `log show`); for a physical device use
   Console.app or `idb log` directly.
 - `--tree` renders flat — idb's accessibility list has no nesting depth.
+- `device set` is partial: `dark` and `font-scale` work on a **simulator** (`simctl ui`),
+  `stay-awake` is a no-op (simulators don't sleep), and `airplane`/`rotation` are
+  unsupported — neither `simctl ui` nor `idb ui` exposes a radio or an orientation.
+  A physical device supports none of them. Run `vk device caps --ios` for the live matrix.
 
 ## Using it from an AI agent
 

package/dist/agent/grammar.js

@@ -28,6 +28,20 @@ Each step is one of three node types:
      assert <selector> [--text <s>] [--gone]       — assert presence/text/absence (FAILS the test if false)
      wait <selector> [--gone] [--timeout <ms>]     — block until present/absent
      screenshot                   — capture the screen into the report
+     device <set|get|reset|caps>  — change the DEVICE (not the app) to test how the app
+                                  copes. The command name is EXACTLY "device"; the
+                                  subcommand is the FIRST POSITIONAL, never part of the
+                                  command name. Each assignment is one positional:
+                                    {"command":"device","positionals":["set","dark=on","font-scale=1.3"]}
+                                    {"command":"device","positionals":["reset"]}
+                                  Keys: airplane=on|off (go offline — for retry/error
+                                  handling), dark=on|off, font-scale=<0.5-3.0>,
+                                  rotation=portrait|landscape|portrait-reverse|
+                                  landscape-reverse|auto, stay-awake=on|off.
+                                  ALWAYS finish the scenario with a "reset" step. Do NOT
+                                  tap immediately after airplane=off — the radio is back
+                                  but the network is not; follow it with a wait/assert.
+                                  Android only for airplane + rotation.
 
 2. IF-PRESENT — { "type":"if-present", "selector":<sel>, "body":[<command leaves>] }
    Run body ONLY if the selector is on screen now. Use for OPTIONAL interstitials:

package/dist/agent/ir.js

@@ -23,6 +23,8 @@ exports.bodiesOf = bodiesOf;
 exports.validateNode = validateNode;
 exports.parsePlan = parsePlan;
 exports.leafToFlags = leafToFlags;
+const errors_1 = require("../errors");
+const settings_1 = require("../device/settings");
 /** Max control-node nesting. 1 = a control node at top level whose body is leaves
  *  (the v1 rule). 2 = a control node inside that body, whose own body is leaves —
  *  i.e. `repeat { when { … } }`, the loop-that-branches shape a real dynamic flow
@@ -50,6 +52,7 @@ exports.KNOWN_COMMANDS = new Set([
     'screenshot', 'shot',
     'wait', 'assert',
     'launch', 'open', 'stop', 'clear',
+    'device',
     // Inspection/diagnostic commands (`current`, `ui`, `find`, `log`, `logs`) are
     // deliberately NOT here: they are not test actions (the grammar never offers them), so
     // a plan or repair must never emit them — and `log`'s flags reach a device shell
@@ -253,6 +256,47 @@ const READ_FIELDS = new Set(['text', 'desc', 'id', 'idShort']);
 /** ctx keys are interpolated into selectors as {{ctx.NAME}}; keep them boring so a
  *  name can never smuggle regex/template metacharacters into a selector. */
 const CTX_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Fold `{command: "device set"}` back into `{command: "device", positionals: ["set", …]}`.
+ *
+ * `device` is the only verb in the grammar with a subcommand, and every other one is a
+ * single word — so the model reliably writes the pair as one command name. That is an
+ * unambiguous spelling of a REAL command, not a hallucination, so normalizing it is the
+ * same kind of leniency as the `click`/`tap` aliases rather than a hole in the
+ * allowlist: an unknown subcommand still falls through and is rejected below.
+ */
+function normalizeLeaf(command, positionals) {
+    const m = /^device[\s:_-]+(set|get|reset|caps)$/i.exec(command.trim());
+    return m ? { command: 'device', positionals: [m[1].toLowerCase(), ...positionals] } : { command, positionals };
+}
+/**
+ * Check a `device` leaf's subcommand and assignments at PLAN-VALIDATION time.
+ *
+ * Every other command is validated only by name, because a bad selector is a runtime
+ * fact the engine can heal. A device setting is different: whether it exists, and
+ * whether the value is legal, are known statically — so catching it here means a
+ * suite that asks for an unknown key fails before the first tap instead of twenty
+ * steps in, on a device it has already half-modified.
+ */
+function validateDeviceStep(positionals, where) {
+    const sub = (positionals[0] ?? '').toLowerCase();
+    if (!['set', 'get', 'reset', 'caps'].includes(sub)) {
+        throw new InvalidPlanError(`${where}: device subcommand must be set|get|reset|caps, got ${JSON.stringify(sub)}`);
+    }
+    const rest = positionals.slice(1);
+    try {
+        if (sub === 'set')
+            (0, settings_1.parseDeviceAssignments)(rest);
+        else
+            for (const k of rest) {
+                if (!(0, settings_1.isSettingKey)(k.trim().toLowerCase()))
+                    throw new errors_1.CliError(`unknown device setting '${k}'`, 2);
+            }
+    }
+    catch (e) {
+        throw new InvalidPlanError(`${where}: ${e instanceof Error ? e.message.split('\n')[0] : String(e)}`);
+    }
+}
 /** Validate a single node (used for both compile output and a spliced repair).
  *
  *  `depth` is how many control nodes enclose this one. It is the ONLY thing bounding
@@ -294,15 +338,20 @@ function validateNode(node, where, depth = 0) {
     const optional = (v, pick) => v === undefined || v === null ? undefined : pick(v);
     switch (n.type) {
         case 'command': {
-            if (typeof n.command !== 'string' || !exports.KNOWN_COMMANDS.has(n.command)) {
+            if (typeof n.command !== 'string')
                 throw new InvalidPlanError(`${where}: unknown command ${JSON.stringify(n.command)}`);
-            }
             if (!Array.isArray(n.positionals) || !n.positionals.every((p) => typeof p === 'string')) {
                 throw new InvalidPlanError(`${where}: positionals must be a string[]`);
             }
+            const { command, positionals } = normalizeLeaf(n.command, n.positionals);
+            if (!exports.KNOWN_COMMANDS.has(command)) {
+                throw new InvalidPlanError(`${where}: unknown command ${JSON.stringify(n.command)}`);
+            }
             if (!isFlagSpecArray(n.flags))
                 throw new InvalidPlanError(`${where}: flags must be {name,value}[]`);
-            return { type: 'command', command: n.command, positionals: n.positionals, flags: n.flags };
+            if (command === 'device')
+                validateDeviceStep(positionals, where);
+            return { type: 'command', command, positionals, flags: n.flags };
         }
         case 'read': {
             const selector = selectorOf();

package/dist/args.js

@@ -58,6 +58,7 @@ const BOOLEAN = new Set([
     'not-selected',
     'not-checked',
     'not-focused',
+    'allow-wireless',
 ]);
 function parseArgs(argv) {
     const positionals = [];