verikun 0.9.0 → 0.10.0

package/README.md

@@ -103,7 +103,7 @@ vk screenshot                   # -> ./.verikun/screen.png
 ### AI
 | Command | Description |
 |---|---|
-| `ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--cost-override in/out] [--effort e] [--package pkg] [--app-build id] [--server url] [--show-plan] [--recompile] [--json]` | Run a plain-English test: compile it to a deterministic plan once, replay it model-free, and self-heal failures via the model. Needs `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (per model), or no key with `--model codex-cli` (a logged-in `codex` CLI). See [AI](#ai--natural-language-tests). |
+| `ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--cost-override in/out] [--effort e] [--package pkg] [--app-build id] [--server url] [--show-plan] [--recompile] [--json]` | Run a plain-English test: compile it to a deterministic plan once, replay it model-free, and self-heal failures via the model. Needs `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (per model), or no key with `--model codex-cli` / `cursor-cli` (a logged-in `codex` / `cursor-agent` CLI). See [AI](#ai--natural-language-tests). |
 | `suite <dir> [--app <id>] [--name n] [--server url] [--json]` (+ all `ai` flags) | Run every `*.md` in `<dir>` as one sequential suite with an overview report and a non-zero exit on failure — the CI gate. See [Suites](#suites--run-a-directory-of-tests). |
 
 ### Remote
@@ -211,8 +211,9 @@ with no model calls on the happy path**. The model is woken only to *repair* a s
 whose selector stops resolving; a green run persists the repaired plan, so the next
 run is free again. That is what keeps a CI suite's steady-state token cost near zero.
 Needs `ANTHROPIC_API_KEY` (Claude models) or `OPENAI_API_KEY` (OpenAI models) — or **no
-key** with `--model codex-cli`, which drives an already-logged-in `codex` CLI off your
-ChatGPT subscription (`codex login` once; verikun just needs the binary on PATH).
+key** with `--model codex-cli` / `--model cursor-cli`, which drive an already-logged-in
+`codex` or `cursor-agent` CLI off your ChatGPT / Cursor subscription (log in once;
+verikun just needs the binary on PATH).
 
 ```sh
 # onboarding.md (plain English):
@@ -243,9 +244,12 @@ a hard iteration cap and stop early if the screen stops changing.
 - **`--model`** picks the model and its provider — Anthropic (`claude-haiku-4-5` ·
   `claude-sonnet-4-6` (default) · `claude-opus-4-8` · `claude-fable-5`), OpenAI
   (`gpt-5.4-mini` · `gpt-5.4` · `gpt-5.5`), each read from its own key
-  (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`), or the CLI backend **`codex-cli`** (no key —
-  the logged-in `codex` binary; spend is on your subscription, so its cost line is `$0` and
-  `--max-cost-usd` / `--cost-override` are no-ops); **`--recompile`** ignores the cache.
+  (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`), or a CLI backend — **`codex-cli`** (the
+  logged-in `codex` binary) or **`cursor-cli`** (`cursor-agent`) — which need no key at
+  all: spend is on your subscription, so their cost line is `$0` and `--max-cost-usd` /
+  `--cost-override` are no-ops. Each CLI picks its own underlying model, and runs
+  read-only in a scratch directory so it never touches your working tree.
+  **`--recompile`** ignores the cache.
 - An `ai` run records like any other flow, so it produces the same JUnit + HTML report —
   with the cost line and any **suggested test improvements** (workarounds the model
   applied, which you can fold back into the prose to stabilize the test and cut tokens).
@@ -282,8 +286,8 @@ vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"   # remote devi
   - **`index.html`** — a summary page linking every test's `report.html`.
 - **Exit code is the CI gate:** `1` if any test failed, `0` all green, `2` bad/empty
   directory. All `ai` flags (`--model`, `--max-cost-usd`, `--timeout`, …) apply to
-  every test; the provider (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or the `codex` CLI for
-  `--model codex-cli`) is checked up front.
+  every test; the provider (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or the `codex` /
+  `cursor-agent` CLI for `--model codex-cli` / `cursor-cli`) is checked up front.
 
 ## Remote devices — `vk server`
 

package/dist/agent/cli-provider.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CliProvider = exports.CODEX_SPEC = void 0;
+exports.CliProvider = exports.CURSOR_SPEC = exports.CODEX_SPEC = void 0;
+exports.cursorResultText = cursorResultText;
 exports.schemaInstruction = schemaInstruction;
 exports.extractJson = extractJson;
 const node_fs_1 = require("node:fs");
@@ -69,6 +70,67 @@ exports.CODEX_SPEC = {
     rawText: (stdout) => stdout, // fallback only; the message is read from --output-last-message
     loginHint: 'run `codex login` to sign in with your ChatGPT subscription (no API key needed)',
 };
+/** cursor-agent (Cursor CLI): non-interactive `--print` with a JSON envelope on stdout. Unlike
+ *  codex it has NO schema flag of any kind, so the schema is injected into the prompt and
+ *  extractJson/parsePlan do the rest. Two flags are load-bearing beyond the obvious ones:
+ *  `--trust`, without which a headless call dies at a "Workspace Trust Required" gate and exits 1
+ *  before the model ever runs; and `--mode ask`, cursor's documented read-only Q&A mode, which
+ *  stands in for codex's `--sandbox read-only` (cursor's own `--sandbox` only takes enabled/
+ *  disabled). Plain `--print` "has access to all tools, including write and shell", so `--mode ask`
+ *  plus the neutral `--workspace` are what keep this a pure transform — and we deliberately never
+ *  pass --force/--yolo/--approve-mcps. */
+exports.CURSOR_SPEC = {
+    id: 'cursor',
+    bin: 'cursor-agent',
+    schema: 'prompt', // no native schema flag — schemaInstruction() injects it into the prompt
+    usesOutputFile: false, // stdout is the only channel out; no --output-last-message equivalent
+    buildArgs(prompt, { cwd, model }) {
+        const args = [
+            '--print', // non-interactive one-shot
+            '--output-format', 'json', // a stable envelope instead of TTY-decorated text
+            '--mode', 'ask', // read-only Q&A mode: no edits, no shell
+            '--workspace', cwd, // root the agent in a neutral temp dir, not the verikun working tree
+            '--trust', // required: else headless stops at the workspace-trust prompt
+        ];
+        if (model)
+            args.push('--model', model);
+        args.push(prompt); // prompt is the trailing positional
+        return args;
+    },
+    rawText: cursorResultText,
+    loginHint: 'run `cursor-agent login` to sign in with your Cursor subscription (no API key needed)',
+};
+/** Peel the model's final message out of cursor-agent's `--output-format json` envelope:
+ *  `{type:"result", subtype:"success", is_error:false, result:"<final text>", …}`.
+ *  Two things a plain `JSON.parse(s).result` would get wrong:
+ *  - cursor can exit 0 while reporting failure via `is_error:true` (e.g. it hit a turn limit), which
+ *    CliProvider's exit-code check cannot see. Left alone, the error prose would flow into
+ *    extractJson and surface as a misleading "did not return parseable JSON", so map it to the same
+ *    exit 3 a non-zero exit gets.
+ *  - an envelope shape drift (or a future default of --output-format text) falls back to the raw
+ *    stdout, so extractJson's tolerant scan still gets a chance instead of failing outright. */
+function cursorResultText(stdout) {
+    let envelope;
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            envelope = parsed;
+    }
+    catch {
+        /* not JSON at all (e.g. --output-format text) — fall through to the raw stdout */
+    }
+    if (!envelope)
+        return stdout;
+    if (envelope.is_error === true) {
+        const detail = typeof envelope.result === 'string' ? tail(envelope.result) : '';
+        throw new errors_1.CliError(`\`cursor-agent\` reported an error: ${detail || '(no detail)'}`, 3);
+    }
+    // Only peel when this really IS the envelope. Parsing alone isn't enough: if cursor ever returns
+    // the plan object bare (or renames the field), treating any JSON object as an envelope would
+    // blank it to '' and report "returned an empty response" — so anything without a string
+    // `result` falls through to the raw stdout, where extractJson can still find the object.
+    return typeof envelope.result === 'string' ? envelope.result : stdout;
+}
 // Collision-free temp-file names within a process without needing Math.random() (which the
 // plan-cache/version paths keep deterministic); pid + a counter is enough.
 let tempCounter = 0;

package/dist/agent/cost.js

@@ -21,11 +21,13 @@ const MODELS = {
     'gpt-5.4-mini': { input: 0.75, output: 4.5, provider: 'openai' },
     'gpt-5.4': { input: 2.5, output: 15, provider: 'openai' },
     'gpt-5.5': { input: 5, output: 30, provider: 'openai' },
-    // CLI-agent backend: billed to the user's ChatGPT subscription via the `codex` CLI, not per
-    // token — so price is $0 and --max-cost-usd/--cost-override are inert no-ops (the run is
-    // bounded by maxRepairs + --timeout instead). Named `codex-cli` to read clearly as "the CLI"
-    // and to avoid colliding with cursor's own `gpt-5.x-codex` model aliases.
+    // CLI-agent backends: billed to the user's ChatGPT/Cursor subscription via an already-logged-in
+    // CLI, not per token — so price is $0 and --max-cost-usd/--cost-override are inert no-ops (the
+    // run is bounded by maxRepairs + --timeout instead). The `-cli` suffix reads clearly as "the
+    // CLI" and keeps these from colliding with the CLIs' own model aliases — cursor in particular
+    // offers `gpt-5.3-codex`, `gpt-5.4-high`, `claude-opus-4-8-thinking-high` and friends.
     'codex-cli': { input: 0, output: 0, provider: 'codex' },
+    'cursor-cli': { input: 0, output: 0, provider: 'cursor' },
 };
 exports.MODEL_PRICES = Object.fromEntries(Object.entries(MODELS).map(([m, s]) => [m, { input: s.input, output: s.output }]));
 exports.ALLOWED_MODELS = Object.keys(MODELS);

package/dist/cli.js

@@ -984,45 +984,43 @@ function readAiTest(file) {
         throw new errors_1.CliError(`ai: '${file}' is empty`, 2);
     return nl;
 }
+/** The CLI-agent backends, by ProviderId. Adding a CLI provider is one entry here rather than a
+ *  new arm in each of the three functions below — they all ask the same question of it. */
+const CLI_SPECS = { codex: cli_provider_1.CODEX_SPEC, cursor: cli_provider_1.CURSOR_SPEC };
 /** Is the backend for `model` usable right now? HTTP providers need their API key in env;
  *  a CLI provider needs its binary on PATH (auth lives in the CLI's own login, not an env key). */
 function providerAvailable(model) {
-    switch ((0, cost_1.providerFor)(model)) {
-        case 'openai':
-            return !!process.env.OPENAI_API_KEY;
-        case 'codex':
-            return (0, exec_1.commandExists)(cli_provider_1.CODEX_SPEC.bin);
-        default:
-            return !!process.env.ANTHROPIC_API_KEY;
-    }
+    const id = (0, cost_1.providerFor)(model);
+    const spec = CLI_SPECS[id];
+    if (spec)
+        return (0, exec_1.commandExists)(spec.bin);
+    return id === 'openai' ? !!process.env.OPENAI_API_KEY : !!process.env.ANTHROPIC_API_KEY;
 }
 /** What's missing when a provider is unavailable — the tail of the preflight error message. */
 function providerRequirement(model) {
-    switch ((0, cost_1.providerFor)(model)) {
-        case 'openai':
-            return 'OPENAI_API_KEY is not set';
-        case 'codex':
-            return `the \`${cli_provider_1.CODEX_SPEC.bin}\` CLI was not found on PATH — install it and run \`codex login\` (ChatGPT subscription, no API key)`;
-        default:
-            return 'ANTHROPIC_API_KEY is not set';
-    }
+    const id = (0, cost_1.providerFor)(model);
+    const spec = CLI_SPECS[id];
+    // Reuse the spec's own loginHint rather than restating it, so the two can't drift apart.
+    if (spec)
+        return `the \`${spec.bin}\` CLI was not found on PATH — install it and ${spec.loginHint}`;
+    return id === 'openai' ? 'OPENAI_API_KEY is not set' : 'ANTHROPIC_API_KEY is not set';
 }
 /** Route the model to its backend. HTTP providers read their own key; a CLI provider shells
  *  out to its logged-in binary. Unavailable → null (compile/repair off), the same graceful
- *  degradation as before: a cached plan can still replay for free without any provider. */
+ *  degradation as before: a cached plan can still replay for free without any provider.
+ *  CLI providers get no `model`, so the CLI picks its own default — the "I just have a
+ *  subscription" path; --effort is likewise inapplicable to them. */
 function makeProvider(opts) {
-    switch ((0, cost_1.providerFor)(opts.model)) {
-        case 'openai': {
-            const apiKey = process.env.OPENAI_API_KEY;
-            return apiKey ? new openai_1.OpenAiProvider({ model: opts.model, apiKey, effort: opts.effort }) : null;
-        }
-        case 'codex':
-            return (0, exec_1.commandExists)(cli_provider_1.CODEX_SPEC.bin) ? new cli_provider_1.CliProvider({ spec: cli_provider_1.CODEX_SPEC }) : null;
-        default: {
-            const apiKey = process.env.ANTHROPIC_API_KEY;
-            return apiKey ? new claude_1.ClaudeProvider({ model: opts.model, apiKey, effort: opts.effort }) : null;
-        }
-    }
+    const id = (0, cost_1.providerFor)(opts.model);
+    const spec = CLI_SPECS[id];
+    if (spec)
+        return (0, exec_1.commandExists)(spec.bin) ? new cli_provider_1.CliProvider({ spec }) : null;
+    if (id === 'openai') {
+        const apiKey = process.env.OPENAI_API_KEY;
+        return apiKey ? new openai_1.OpenAiProvider({ model: opts.model, apiKey, effort: opts.effort }) : null;
+    }
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    return apiKey ? new claude_1.ClaudeProvider({ model: opts.model, apiKey, effort: opts.effort }) : null;
 }
 /** Obtain the plan: a cache hit (free) or a compile (pays tokens; may seed from a
  *  prior build's plan to avoid a full recompile). The fresh compile is cached right
@@ -1587,15 +1585,18 @@ AI (run a natural-language test — compile once, replay model-free, self-heal)
                                       that fails to resolve; a green run persists the
                                       (repaired) plan so the next run is free. Needs
                                       ANTHROPIC_API_KEY (Claude), OPENAI_API_KEY (gpt-5.x),
-                                      or a logged-in agent CLI (--model codex-cli uses your
-                                      'codex login' ChatGPT subscription — no API key; cost
-                                      is $0 so --max-cost-usd/--cost-override are no-ops).
+                                      or a logged-in agent CLI — no API key: --model
+                                      codex-cli uses your 'codex login' ChatGPT
+                                      subscription, cursor-cli your 'cursor-agent login'
+                                      Cursor one (cost is $0 for both, so
+                                      --max-cost-usd/--cost-override are no-ops).
                                       Progress -> stderr; the report path ->
                                       stdout. --show-plan prints the compiled IR without
                                       running; --recompile ignores the cache.
                                       Models: claude-haiku-4-5 | claude-sonnet-4-6
                                       (default) | claude-opus-4-8 | claude-fable-5 |
-                                      gpt-5.4-mini | gpt-5.4 | gpt-5.5 | codex-cli.
+                                      gpt-5.4-mini | gpt-5.4 | gpt-5.5 | codex-cli |
+                                      cursor-cli.
 
 SUITE (run a directory of natural-language tests as one gated suite)
   suite <dir> [--app <id>] [--name n] [--json]  (+ all \`ai\` flags, incl. --server)

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.9.0';
+exports.VERSION = '0.10.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",

package/dist/drivers/simctl.js

@@ -1,156 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SimctlDriver = void 0;
-const node_os_1 = require("node:os");
-const node_path_1 = require("node:path");
-const node_fs_1 = require("node:fs");
-const errors_1 = require("../errors");
-const exec_1 = require("../exec");
-const XCRUN = 'xcrun';
-function listPhysicalDevices() {
-    const r = (0, exec_1.runText)(XCRUN, ['devicectl', 'list', 'devices']);
-    if (r.code !== 0)
-        return [];
-    const lines = r.stdout.split('\n');
-    const headerIdx = lines.findIndex((l) => l.includes('Identifier'));
-    if (headerIdx < 0)
-        return [];
-    const header = lines[headerIdx];
-    const nameCol = header.indexOf('Name');
-    const hostCol = header.indexOf('Hostname');
-    const idCol = header.indexOf('Identifier');
-    const stateCol = header.indexOf('State');
-    const modelCol = header.indexOf('Model');
-    const devices = [];
-    for (const line of lines.slice(headerIdx + 2)) {
-        if (!line.trim() || line.startsWith('-'))
-            continue;
-        const identifier = line.slice(idCol, stateCol).trim();
-        const state = line.slice(stateCol, modelCol).trim();
-        const name = line.slice(nameCol, hostCol).trim();
-        const model = line.slice(modelCol).trim();
-        if (!identifier)
-            continue;
-        const productMatch = model.match(/\(([^)]+)\)$/);
-        devices.push({
-            serial: identifier,
-            state,
-            model: name,
-            product: productMatch?.[1],
-            platform: 'ios',
-            note: 'physical — screenshot only, tap/ui not supported',
-        });
-    }
-    return devices;
-}
-// iOS support is intentionally partial. `simctl` covers screenshots, launch,
-// and stop. Full interaction (tap, swipe, type) and the accessibility hierarchy
-// require WebDriverAgent (https://github.com/appium/WebDriverAgent) — the
-// planned next step. WDA is an open-source XCTest HTTP server: build it once
-// in Xcode, sign it with your Apple developer certificate, and run it on the
-// target device or simulator. No Python required; works on both simulators and
-// physical devices. The Driver seam is already in place so the command layer
-// won't change when WDA support is added.
-function notSupported(feature) {
-    throw new errors_1.CliError(`iOS ${feature} is not supported yet.\n` +
-        'Screenshots, launch, and stop work today via xcrun simctl.\n' +
-        'Full interaction (tap / swipe / type) and UI hierarchy inspection are planned\n' +
-        'via WebDriverAgent — build it once in Xcode and vk will drive it over HTTP.\n' +
-        'See: https://github.com/appium/WebDriverAgent', 3);
-}
-class SimctlDriver {
-    platform = 'ios';
-    udid;
-    constructor(device) {
-        this.udid = device || 'booted';
-    }
-    listDevices() {
-        const devices = [];
-        // Simulators via simctl
-        const { stdout } = (0, exec_1.runText)(XCRUN, ['simctl', 'list', 'devices', 'available', '--json']);
-        try {
-            const data = JSON.parse(stdout);
-            for (const [runtime, list] of Object.entries(data.devices)) {
-                for (const d of list) {
-                    devices.push({
-                        serial: d.udid,
-                        state: d.state.toLowerCase(),
-                        model: d.name,
-                        product: runtime.split('.').pop(),
-                        platform: 'ios',
-                    });
-                }
-            }
-        }
-        catch {
-            /* tolerate unexpected simctl output */
-        }
-        // Physical devices via devicectl (Xcode 15+)
-        devices.push(...listPhysicalDevices());
-        return devices;
-    }
-    resolvedSerial() {
-        return this.udid;
-    }
-    screenshot() {
-        const tmp = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `verikun-ios-${process.pid}.png`);
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'io', this.udid, 'screenshot', tmp]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl screenshot failed: ${r.stderr.trim()}`, 3);
-        const buf = (0, node_fs_1.readFileSync)(tmp);
-        try {
-            (0, node_fs_1.unlinkSync)(tmp);
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-        return buf;
-    }
-    launch(appId) {
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'launch', this.udid, appId]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl launch failed: ${r.stderr.trim()}`, 3);
-    }
-    stop(appId) {
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'terminate', this.udid, appId]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl terminate failed: ${r.stderr.trim()}`, 3);
-    }
-    clearApp(appId) {
-        // simctl has no per-app data reset. The manual equivalent is to uninstall and
-        // reinstall, which also removes the app itself — so we don't do it implicitly.
-        throw new errors_1.CliError(`iOS app-data clearing is not supported yet (requested for '${appId}').\n` +
-            'simctl has no per-app data reset; uninstall + reinstall ' +
-            '(`xcrun simctl uninstall <udid> <bundleId>`) is the manual equivalent, but it removes the app too.', 3);
-    }
-    getElements() {
-        return notSupported('hierarchy inspection');
-    }
-    screenSize() {
-        return notSupported('screen size');
-    }
-    tap() {
-        notSupported('tap');
-    }
-    swipe() {
-        notSupported('swipe');
-    }
-    inputText() {
-        notSupported('text input');
-    }
-    pressKey() {
-        notSupported('key events');
-    }
-    currentApp() {
-        return notSupported('current app');
-    }
-    getLogs() {
-        // Eventually: `xcrun simctl spawn <udid> log show` (simulators) / devicectl
-        // (physical). Heavier (predicate language, large output) — deferred with WDA.
-        return notSupported('log capture');
-    }
-    deviceTime() {
-        return ''; // no log window to anchor while iOS log capture is unsupported
-    }
-}
-exports.SimctlDriver = SimctlDriver;