verikun 0.18.0 → 0.19.0

package/dist/cli.js

@@ -50,6 +50,7 @@ exports.chooseLogOpts = chooseLogOpts;
 exports.evalAssert = evalAssert;
 exports.tokenizeLine = tokenizeLine;
 exports.withBatchGlobals = withBatchGlobals;
+exports.terminalFailure = terminalFailure;
 exports.executeForServer = executeForServer;
 exports.run = run;
 const node_fs_1 = require("node:fs");
@@ -58,6 +59,8 @@ const args_1 = require("./args");
 const errors_1 = require("./errors");
 const exec_1 = require("./exec");
 const drivers_1 = require("./drivers");
+const adb_1 = require("./drivers/adb");
+const settings_1 = require("./device/settings");
 const selector_1 = require("./ui/selector");
 const state_support_1 = require("./ui/state-support");
 const format_1 = require("./ui/format");
@@ -923,6 +926,194 @@ function cmdClear(ctx) {
         (0, output_1.out)(`cleared ${appId}`);
     return 0;
 }
+// ---------------------------------------------------------------------------
+// device — control the device the app runs on (see device/settings.ts)
+// ---------------------------------------------------------------------------
+//
+// The capability table is the single source of truth: it validates values, decides
+// what each platform supports, and prints itself via `device caps`. Two properties
+// are load-bearing:
+//
+//  - FAIL EARLY. Every assignment is parsed and capability-checked before ANY device
+//    I/O, so `device set dark=on rotation=landscape` on iOS refuses up front instead
+//    of applying dark mode and then dying — a half-applied device is worse than none.
+//  - SNAPSHOT FIRST. The pre-change value is persisted before the change is made, so
+//    `device reset` can undo it even from a later process.
+const DEVICE_USAGE = 'Usage: verikun device set <key>=<value> [<key>=<value> ...] | device get [key] | device reset [key ...] | device caps\n' +
+    `Keys: ${settings_1.SETTING_KEYS.join(', ')}`;
+function cmdDevice(ctx) {
+    const sub = (ctx.positionals[0] ?? '').toLowerCase();
+    const rest = ctx.positionals.slice(1);
+    switch (sub) {
+        case 'set':
+            return deviceSet(ctx, rest);
+        case 'get':
+        case 'status':
+            return deviceGet(ctx, rest);
+        case 'reset':
+            return deviceReset(ctx, rest);
+        case 'caps':
+            return deviceCaps(ctx);
+        default:
+            throw new errors_1.CliError((sub ? `Unknown 'device' subcommand '${sub}'.\n` : '') + DEVICE_USAGE, 2);
+    }
+}
+/** Render a setting value for humans/JSON; a platform that cannot answer says so. */
+const showValue = (v) => v ?? 'n/a';
+function deviceSet(ctx, args) {
+    const assignments = (0, settings_1.parseDeviceAssignments)(args);
+    // Gate 1: capability, for EVERY key, before touching the device.
+    const support = new Map();
+    for (const { key } of assignments)
+        support.set(key, (0, settings_1.checkSupport)(key, ctx.platform));
+    // Gate 2: would this cut the wire we are talking over? Only wireless adb is at
+    // risk, and only from the radios. A stderr warning would be useless here — the
+    // command that reads it is the one that just lost its transport — so refuse, and
+    // require an explicit opt-in to accept losing the link.
+    if (ctx.platform === 'android') {
+        const transport = (0, adb_1.adbTransport)(ctx.driver.resolvedSerial());
+        for (const { key, value } of assignments) {
+            if ((0, adb_1.severanceRisk)(transport, key, value) && !(0, args_1.flagBool)(ctx.flags, 'allow-wireless')) {
+                throw new errors_1.CliError(`Refusing to set ${key}=${value} over a wireless adb connection (${ctx.driver.resolvedSerial()}): ` +
+                    'it would cut the link carrying this session, and nothing could turn it back on remotely.\n' +
+                    'Connect over USB, or pass --allow-wireless to accept losing the connection.', 2);
+            }
+        }
+    }
+    const applied = {};
+    for (const { key, value } of assignments) {
+        // A no-op key has nothing to put back, so it is never snapshotted.
+        if (support.get(key) !== 'noop')
+            snapshotSetting(ctx, key);
+        ctx.driver.setDeviceSetting(key, value);
+        applied[key] = value;
+    }
+    const summary = assignments.map((a) => `${a.key}=${a.value}`).join(' ');
+    ctx.record?.note({ message: `device set ${summary}` });
+    if ((0, args_1.flagBool)(ctx.flags, 'json'))
+        (0, output_1.json)({ set: applied });
+    else
+        (0, output_1.out)(`device set ${summary}`);
+    return 0;
+}
+/** Persist what a setting held before we change it. Warns rather than fails when the
+ *  value can't be captured — the change still happens, it just can't be auto-undone. */
+function snapshotSetting(ctx, key) {
+    if (!ctx.record) {
+        // Recording disabled (VERIKUN_NO_RUN=1): there is nowhere to persist the original,
+        // so this change is one-way. Say so rather than implying reset will handle it.
+        (0, output_1.err)(`warning: run recording is off, so '${key}' was not snapshotted — \`device reset\` cannot restore it`);
+        return;
+    }
+    const original = ctx.driver.getDeviceSetting(key);
+    if (original === null) {
+        (0, output_1.err)(`warning: could not read the current '${key}' — \`device reset\` will not restore it`);
+        return;
+    }
+    ctx.record.rememberDeviceOverride(key, original);
+}
+function deviceGet(ctx, args) {
+    const keys = args.length ? args.map(requireSettingKey) : settings_1.SETTING_KEYS;
+    const values = {};
+    for (const key of keys) {
+        values[key] = settings_1.SETTINGS[key].support[ctx.platform] === 'unsupported'
+            ? 'n/a'
+            : showValue(ctx.driver.getDeviceSetting(key));
+    }
+    if ((0, args_1.flagBool)(ctx.flags, 'json'))
+        (0, output_1.json)(values);
+    else
+        for (const key of keys)
+            (0, output_1.out)(`${key.padEnd(12)} ${values[key]}`);
+    return 0;
+}
+function deviceReset(ctx, args) {
+    // Read from the recorder's in-flight state, not from disk: this step's own commit()
+    // will write that state back, so a disk-level delete here would be undone.
+    const overrides = ctx.record?.deviceOverrides() ?? {};
+    const wanted = args.length ? args.map(requireSettingKey) : Object.keys(overrides);
+    const restored = {};
+    const failed = [];
+    for (const key of wanted) {
+        const original = overrides[key];
+        if (original === undefined)
+            continue; // never changed by this run — leave it alone
+        try {
+            ctx.driver.setDeviceSetting(key, original);
+            restored[key] = original;
+        }
+        catch (e) {
+            // Best-effort by design: reset is usually reached while cleaning up after a
+            // failure, and one stubborn setting must not stop the rest being put back.
+            failed.push(`${key} (${e instanceof Error ? e.message.split('\n')[0] : String(e)})`);
+        }
+    }
+    ctx.record?.forgetDeviceOverrides(Object.keys(restored));
+    const summary = Object.entries(restored).map(([k, v]) => `${k}=${v}`).join(' ');
+    ctx.record?.note({ message: summary ? `device reset ${summary}` : 'device reset (nothing to restore)' });
+    if (failed.length)
+        (0, output_1.err)(`warning: could not restore ${failed.join(', ')}`);
+    if ((0, args_1.flagBool)(ctx.flags, 'json'))
+        (0, output_1.json)({ restored, ...(failed.length ? { failed } : {}) });
+    else
+        (0, output_1.out)(summary ? `device reset ${summary}` : 'device reset: nothing to restore');
+    return 0;
+}
+function deviceCaps(ctx) {
+    const rows = settings_1.SETTING_KEYS.map((key) => {
+        const spec = settings_1.SETTINGS[key];
+        const support = spec.support[ctx.platform];
+        return {
+            key,
+            values: spec.values,
+            support,
+            describe: spec.describe,
+            ...(support === 'unsupported' && spec.manual[ctx.platform] ? { manual: spec.manual[ctx.platform] } : {}),
+            ...(spec.note[ctx.platform] ? { note: spec.note[ctx.platform] } : {}),
+        };
+    });
+    if ((0, args_1.flagBool)(ctx.flags, 'json')) {
+        (0, output_1.json)({ platform: ctx.platform, settings: rows });
+        return 0;
+    }
+    (0, output_1.out)(`device settings on ${ctx.platform}:`);
+    for (const r of rows) {
+        (0, output_1.out)(`  ${r.key.padEnd(12)} ${r.support.padEnd(12)} ${r.values}`);
+        (0, output_1.out)(`  ${' '.repeat(12)} ${r.describe}`);
+        if (r.manual)
+            (0, output_1.out)(`  ${' '.repeat(12)} unsupported: ${r.manual.replace(/\n/g, ' ')}`);
+        if (r.note)
+            (0, output_1.out)(`  ${' '.repeat(12)} note: ${r.note}`);
+    }
+    return 0;
+}
+function requireSettingKey(v) {
+    const k = v.trim().toLowerCase();
+    if (!(0, settings_1.isSettingKey)(k)) {
+        throw new errors_1.CliError(`Unknown device setting '${v}'. Known: ${settings_1.SETTING_KEYS.join(', ')}.`, 2);
+    }
+    return k;
+}
+/**
+ * Put back every device setting this run changed. Best-effort and silent about
+ * "nothing to do", because it runs from a `finally` — the flow may well be unwinding
+ * from the very failure that left the device in a modified state.
+ *
+ * Runs through the backend rather than a Driver so the local and remote paths are the
+ * same code. (Remote is a known gap: the overrides live in the *server's* run file, so
+ * a locally-empty snapshot means this correctly skips — see the issue's Out of scope.)
+ */
+async function restoreDeviceOverrides(backend) {
+    if (!run_1.Recorder.hasDeviceOverrides())
+        return;
+    try {
+        (0, output_1.err)('[verikun] restoring device settings changed by this run…');
+        await backend.exec('device', ['reset'], {});
+    }
+    catch {
+        /* the device may be exactly why we are unwinding — never mask the real error */
+    }
+}
 function cmdCurrent(ctx) {
     (0, output_1.out)(ctx.driver.currentApp());
     return 0;
@@ -1143,31 +1334,46 @@ async function cmdBatch(positionals, batchFlags) {
         (0, output_1.err)('[verikun] batch: no commands to run');
         return 0;
     }
-    for (const { n, text } of commands) {
-        let code;
-        try {
-            const { command, positionals: pos, flags } = (0, args_1.parseArgs)(tokenizeLine(text));
-            if (!command)
-                continue; // tokens were all flags — nothing to run
-            if (command === 'batch') {
-                throw new errors_1.CliError(`batch: a batch line may not itself be 'batch' (line ${n})`, 2);
+    // The finally is what makes `device set` safe to use in a batch: a line that fails
+    // (or a ^C) still puts the device back, instead of leaving it offline or rotated.
+    try {
+        for (const { n, text } of commands) {
+            let code;
+            try {
+                const { command, positionals: pos, flags } = (0, args_1.parseArgs)(tokenizeLine(text));
+                if (!command)
+                    continue; // tokens were all flags — nothing to run
+                if (command === 'batch') {
+                    throw new errors_1.CliError(`batch: a batch line may not itself be 'batch' (line ${n})`, 2);
+                }
+                if (!quiet)
+                    (0, output_1.err)(`[verikun] batch ${n}: ${text}`);
+                code = await executeParsed(command, pos, withBatchGlobals(flags, batchFlags));
+            }
+            catch (e) {
+                // A malformed line (bad quoting, nested batch) is itself an error to halt on.
+                code = mapError(e, batchFlags);
+            }
+            if (code !== 0) {
+                (0, output_1.err)(`[verikun] batch stopped at line ${n} (\`${text}\`) — exit ${code}`);
+                return code;
             }
-            if (!quiet)
-                (0, output_1.err)(`[verikun] batch ${n}: ${text}`);
-            code = await executeParsed(command, pos, withBatchGlobals(flags, batchFlags));
-        }
-        catch (e) {
-            // A malformed line (bad quoting, nested batch) is itself an error to halt on.
-            code = mapError(e, batchFlags);
         }
-        if (code !== 0) {
-            (0, output_1.err)(`[verikun] batch stopped at line ${n} (\`${text}\`) — exit ${code}`);
-            return code;
+        if (!quiet)
+            (0, output_1.err)(`[verikun] batch: ${commands.length} command(s) ok`);
+        return 0;
+    }
+    finally {
+        if (run_1.Recorder.hasDeviceOverrides()) {
+            (0, output_1.err)('[verikun] restoring device settings changed by this batch…');
+            try {
+                await executeParsed('device', ['reset'], withBatchGlobals({}, batchFlags));
+            }
+            catch {
+                /* the device may be exactly why we are unwinding — never mask the real error */
+            }
         }
     }
-    if (!quiet)
-        (0, output_1.err)(`[verikun] batch: ${commands.length} command(s) ok`);
-    return 0;
 }
 function parseAiOptions(flags) {
     const model = (0, cost_1.resolveModel)((0, args_1.flagStr)(flags, 'model'));
@@ -1322,6 +1528,24 @@ async function resolveBackend(platform, device, flags) {
                         driver.clearApp(appId);
                 },
                 preflight: () => driver.preflight(),
+                captureFailure: async () => {
+                    // Two independent tries: a screencap can succeed where a dump doesn't (and
+                    // vice versa), and neither is allowed to derail recording the failure.
+                    const out = {};
+                    try {
+                        out.png = driver.screenshot();
+                    }
+                    catch {
+                        /* device may be gone — that may be why we failed */
+                    }
+                    try {
+                        out.hierarchy = driver.getElements({ all: false });
+                    }
+                    catch {
+                        /* ditto */
+                    }
+                    return out;
+                },
             },
             platform,
             device,
@@ -1352,12 +1576,52 @@ async function resolveBackend(platform, device, flags) {
                 await (0, remote_1.pingServer)(opts);
                 await remote.getElements();
             },
+            // Hierarchy only: the server exposes no screenshot route, so a remote run's
+            // engine failure archives without a picture. Honest degrade over a protocol
+            // change here — tracked in #48.
+            captureFailure: async () => {
+                try {
+                    return { hierarchy: await remote.getElements() };
+                }
+                catch {
+                    return {};
+                }
+            },
         },
         platform: health.platform,
         device: health.serial,
         remote: { url: server, version: health.version },
     };
 }
+/**
+ * The one terminal-failure record for a non-ok engine result — `null` when the run
+ * passed. Exported for the unit suite.
+ *
+ * Budget and timeout aborts come back from the engine as a bare flag with NO `failure`
+ * object, so their reason is composed here; `where` is `run` because the abort is not
+ * attributable to one node. Both the recorded failure and the `[ai] …` status line are
+ * built from this, so the archive and the console cannot disagree about why a run died.
+ */
+function terminalFailure(r, opts) {
+    if (r.ok)
+        return null;
+    if (r.abortedForEnv) {
+        return { where: r.failure?.where ?? 'run', reason: r.failure?.reason ?? 'device unavailable', kind: 'env' };
+    }
+    if (r.abortedForBudget) {
+        return { where: r.failure?.where ?? 'run', reason: `cost ceiling $${opts.maxCostUsd} reached`, kind: 'budget' };
+    }
+    if (r.abortedForTimeout) {
+        return { where: 'run', reason: `run timeout (${Math.round(opts.timeoutMs / 1000)}s) reached`, kind: 'timeout' };
+    }
+    return { where: r.failure?.where ?? 'run', reason: r.failure?.reason ?? 'failed', kind: 'fail' };
+}
+/** The `[ai] …` console verdict for a terminal failure, phrased as it always was. */
+function terminalStatusLine(t) {
+    if (t.kind === 'fail')
+        return `FAIL at ${t.where}: ${t.reason}`;
+    return `ABORTED — ${t.kind === 'env' ? `environment: ${t.reason}` : t.reason}`;
+}
 /**
  * Best-effort archive-time device-log capture via an ExecBackend (local driver or
  * remote `/v1/logs`). Writes `artifacts/logcat.txt` onto the active run so a later
@@ -1470,6 +1734,13 @@ async function runAiTest(file, opts, backend, platform, device) {
         // seal the run so it is not left dangling in .verikun/run/ for the next command
         // to roll over. Then let the error map to an exit code as usual.
         run_1.Recorder.annotateRun({ ai: { ok: false, cost: cost.summaryLine(), modelRepairs: 0, improvements: [] } });
+        // No evidence capture here: a throw at this level usually IS the device dying, so
+        // the capture would fail the same way and only add noise to the error path.
+        run_1.Recorder.recordTerminalFailure({
+            where: 'run',
+            reason: e.message,
+            kind: (0, errors_1.isEnvError)(e) ? 'env' : 'fail',
+        });
         try {
             await prefetchArchiveLogs(backend);
             run_1.Recorder.archive();
@@ -1496,21 +1767,18 @@ async function runAiTest(file, opts, backend, platform, device) {
             (0, output_1.err)(`[ai] could not cache plan: ${e.message}`);
         }
     }
+    // A failure the engine produced (a control node giving up, a budget/timeout abort)
+    // never ran through a command, so nothing recorded it — without this the archive
+    // declares the failed test green. Must come BEFORE the archive that renders it.
+    const terminal = terminalFailure(result, opts);
+    if (terminal)
+        run_1.Recorder.recordTerminalFailure(terminal, await backend.captureFailure?.());
     run_1.Recorder.annotateRun({
         ai: { ok: result.ok, cost: costLine, modelRepairs: result.modelRepairs, improvements: result.improvements },
     });
     await prefetchArchiveLogs(backend);
     const { dir, xmlPath, htmlPath, state } = run_1.Recorder.archive();
-    const status = result.ok
-        ? 'PASS'
-        : result.abortedForBudget
-            ? `ABORTED — cost ceiling $${opts.maxCostUsd} reached`
-            : result.abortedForTimeout
-                ? `ABORTED — run timeout (${Math.round(opts.timeoutMs / 1000)}s) reached`
-                : result.abortedForEnv
-                    ? `ABORTED — environment: ${result.failure?.reason}`
-                    : `FAIL at ${result.failure?.where}: ${result.failure?.reason}`;
-    (0, output_1.err)(`[ai] ${status} · ${costLine}`);
+    (0, output_1.err)(`[ai] ${terminal ? terminalStatusLine(terminal) : 'PASS'} · ${costLine}`);
     (0, output_1.err)(`[ai] report: ${htmlPath}`);
     if (result.improvements.length) {
         (0, output_1.err)(`[ai] ${result.improvements.length} suggested improvement(s) (also in the report):`);
@@ -1557,6 +1825,9 @@ async function cmdAi(positionals, flags) {
         result = await runAiTest(file, opts, backend, platform, device);
     }
     finally {
+        // Undo any device setting the test changed, INCLUDING when it failed part-way —
+        // otherwise an unattended run leaves the phone offline or in dark mode.
+        await restoreDeviceOverrides(backend);
         await backend.close?.(); // frees a remote server's device lock for the next command
     }
     if ((0, args_1.flagBool)(flags, 'json')) {
@@ -1639,6 +1910,7 @@ async function cmdSuiteEntry(positionals, flags) {
         });
     }
     finally {
+        await restoreDeviceOverrides(backend);
         await backend.close?.();
     }
 }
@@ -1688,6 +1960,8 @@ async function executeCommand(command, ctx) {
             return cmdStop(ctx);
         case 'clear':
             return cmdClear(ctx);
+        case 'device':
+            return cmdDevice(ctx);
         case 'current':
             return cmdCurrent(ctx);
         case 'log':
@@ -1730,7 +2004,7 @@ async function executeOutcome(command, positionals, flags, sharedDriver) {
     // Recordable commands open a step (auto-starting an implicit run if needed);
     // the step is finalized with the outcome — and, on failure, screenshot + UI
     // hierarchy of the page are captured — whether the command returns or throws.
-    const recordable = (0, run_1.isRecordable)(command);
+    const recordable = (0, run_1.isRecordable)(command, positionals);
     let driver = sharedDriver;
     let recorder = null;
     try {
@@ -1908,6 +2182,22 @@ ACT
                                       idb install). With --server, uploads the file to a
                                       remote vk server (which must run --allow-install)
 
+DEVICE STATE (change the device the app runs on, then put it back)
+  device set <key>=<value> ...        Apply settings, snapshotting each original first.
+                                      Keys: ${settings_1.SETTING_KEYS.join(', ')}
+                                      e.g. \`device set airplane=on\` to test offline handling,
+                                      \`device set dark=on font-scale=1.3 rotation=landscape\`.
+                                      Each change is verified by reading it back — the
+                                      underlying device commands silently no-op on some skins.
+  device get [key] [--json]           Show current values ('n/a' where unsupported)
+  device reset [key ...]              Restore what this run changed. batch/ai/suite also
+                                      do this automatically when the flow ends OR fails,
+                                      so a dead test can't leave the phone offline.
+  device caps [--json]                What this platform supports, and the manual
+                                      equivalent where it doesn't
+                                      Refuses \`airplane=on\` over wireless adb (it would cut
+                                      this very connection); --allow-wireless overrides.
+
 BATCH (script many commands in one process)
   batch [--file path] [--quiet]       Run newline-separated commands — from --file,
                                       else piped stdin — each exactly as its own
@@ -2031,5 +2321,7 @@ EXIT CODES
 
 iOS (--ios): full parity via idb — ui/tap/text/swipe/key + screenshot/launch/stop.
   Needs idb (\`brew install idb-companion\` + \`pip install fb-idb\`); see \`vk doctor --ios\`.
-  Caveats: no \`clear\` (no per-app reset), \`current\` is (unknown), device logs are simulator-only.`;
+  Caveats: no \`clear\` (no per-app reset), \`current\` is (unknown), device logs are simulator-only.
+  \`device set\`: dark + font-scale work on a SIMULATOR (font-scale maps to the nearest
+  Dynamic Type category); airplane and rotation are unsupported — run \`vk device caps --ios\`.`;
 }