verikun 0.4.1

package/dist/drivers/adb.js

@@ -0,0 +1,300 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdbDriver = void 0;
+exports.escapeText = escapeText;
+const errors_1 = require("../errors");
+const exec_1 = require("../exec");
+const android_parse_1 = require("../ui/android-parse");
+const ADB = process.env.ADB || 'adb';
+// Named keys -> Android keycodes. Numeric codes are also accepted directly.
+const KEYCODES = {
+    enter: 66,
+    back: 4,
+    home: 3,
+    tab: 61,
+    space: 62,
+    del: 67,
+    delete: 67,
+    backspace: 67,
+    forward_del: 112,
+    escape: 111,
+    esc: 111,
+    menu: 82,
+    search: 84,
+    up: 19,
+    down: 20,
+    left: 21,
+    right: 22,
+    center: 23,
+    dpad_up: 19,
+    dpad_down: 20,
+    dpad_left: 21,
+    dpad_right: 22,
+    dpad_center: 23,
+    power: 26,
+    app_switch: 187,
+    recents: 187,
+    volume_up: 24,
+    volume_down: 25,
+    mute: 164,
+    move_home: 122,
+    move_end: 123,
+    page_up: 92,
+    page_down: 93,
+};
+const DUMP_PATHS = ['/sdcard/window_dump.xml', '/data/local/tmp/window_dump.xml'];
+const DEFAULT_LOG_LINES = 200;
+/**
+ * Escape a string for `adb shell input text <arg>`. The argument is parsed twice
+ * before it reaches the field: once by the on-device shell (mksh), then by
+ * `input`, which maps the literal token "%s" back to a space.
+ *
+ * Strategy is an ALLOWLIST: leave ASCII letters/digits and any non-ASCII bytes
+ * untouched, and backslash-escape EVERY ASCII punctuation/symbol. For a char mksh
+ * treats as ordinary (e.g. @ . + _ - , : /) the backslash is a no-op (\x -> x),
+ * so `input` receives the same character; for one mksh would interpret
+ * (quote, backtick, $ & | ; < > ( ) * ? ~ # ! { } [ ] backslash) the escape keeps
+ * it literal. So bob@mail.com (or a value with + = % # & ;) types verbatim.
+ * Spaces are encoded last as the token %s, which `input` decodes back to a space.
+ * (One inherent limit of that convention, unchanged here: a literal "%s" in the
+ * text also decodes to a space. The backslash on % only guards the shell, not
+ * `input`'s own %s handling.)
+ *
+ * Arbitrary Unicode (accents, emoji) is a known limitation of `input text` and is
+ * passed through unchanged; use an IME like ADBKeyboard for that — see SKILL.md.
+ */
+function escapeText(s) {
+    return s
+        // Backslash-escape every ASCII punctuation/symbol the device shell might
+        // interpret. Ranges cover all ASCII punctuation, excluding space (\x20),
+        // 0-9, A-Z, a-z. $& is the matched char.
+        .replace(/[\x21-\x2F\x3A-\x40\x5B-\x60\x7B-\x7E]/g, '\\$&')
+        // `input` maps the literal token %s back to a space, so encode spaces last.
+        .replace(/ /g, '%s');
+}
+class AdbDriver {
+    platform = 'android';
+    requested;
+    cachedSerial;
+    constructor(serial) {
+        this.requested = serial;
+    }
+    listDevices() {
+        const { stdout } = (0, exec_1.runText)(ADB, ['devices', '-l']);
+        const devices = [];
+        for (const line of stdout.split('\n').slice(1)) {
+            const t = line.trim();
+            if (!t || t.startsWith('*'))
+                continue;
+            const fields = t.split(/\s+/);
+            const serial = fields[0];
+            const state = fields[1];
+            if (!serial || !state)
+                continue;
+            const info = { serial, state, platform: 'android' };
+            for (const kv of fields.slice(2)) {
+                const idx = kv.indexOf(':');
+                if (idx < 0)
+                    continue;
+                const k = kv.slice(0, idx);
+                const v = kv.slice(idx + 1);
+                if (k === 'model')
+                    info.model = v;
+                if (k === 'product')
+                    info.product = v;
+            }
+            devices.push(info);
+        }
+        return devices;
+    }
+    resolvedSerial() {
+        if (this.cachedSerial)
+            return this.cachedSerial;
+        if (this.requested) {
+            this.cachedSerial = this.requested;
+            return this.cachedSerial;
+        }
+        const all = this.listDevices();
+        const usable = all.filter((d) => d.state === 'device');
+        if (usable.length === 0) {
+            if (all.length) {
+                const states = all.map((d) => `${d.serial}=${d.state}`).join(', ');
+                throw new errors_1.CliError(`No usable Android device (states: ${states}). Authorize/reconnect it.`, 3);
+            }
+            throw new errors_1.CliError('No Android devices/emulators connected. Start one, then `verikun devices`.', 3);
+        }
+        if (usable.length > 1) {
+            const list = usable.map((d) => '  ' + d.serial + (d.model ? ` (${d.model})` : '')).join('\n');
+            throw new errors_1.CliError(`Multiple devices connected; pass --device <serial> (or set VERIKUN_DEVICE):\n${list}`, 2);
+        }
+        this.cachedSerial = usable[0].serial;
+        return this.cachedSerial;
+    }
+    withSerial(args) {
+        return ['-s', this.resolvedSerial(), ...args];
+    }
+    shell(args, timeout) {
+        return (0, exec_1.runText)(ADB, this.withSerial(['shell', ...args]), { timeout }).stdout;
+    }
+    getElements(opts = {}) {
+        return (0, android_parse_1.parseHierarchy)(this.dumpXml(), opts);
+    }
+    dumpXml() {
+        let lastErr = '';
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const path = DUMP_PATHS[Math.min(attempt, DUMP_PATHS.length - 1)];
+            const dump = (0, exec_1.runText)(ADB, this.withSerial(['shell', 'uiautomator', 'dump', path]), { timeout: 15000 });
+            const cat = (0, exec_1.runBinary)(ADB, this.withSerial(['exec-out', 'cat', path]));
+            const xml = cat.stdout.toString('utf8');
+            if (xml.includes('<hierarchy'))
+                return xml;
+            lastErr = `${dump.stdout} ${dump.stderr} ${cat.stderr}`.replace(/\s+/g, ' ').trim();
+        }
+        throw new errors_1.CliError(`Failed to capture UI hierarchy after 3 attempts. ${lastErr}\n` +
+            'Tip: disable animations (`verikun doctor --fix`) and ensure the screen is idle.', 3);
+    }
+    screenshot() {
+        const r = (0, exec_1.runBinary)(ADB, this.withSerial(['exec-out', 'screencap', '-p']));
+        if (r.stdout.length < 8 || r.stdout[0] !== 0x89 || r.stdout[1] !== 0x50) {
+            throw new errors_1.CliError(`screencap did not return a PNG. ${r.stderr}`.trim(), 3);
+        }
+        return r.stdout;
+    }
+    screenSize() {
+        const out = this.shell(['wm', 'size']);
+        const lines = out.split('\n');
+        const override = lines.find((l) => /Override size/i.test(l));
+        const physical = lines.find((l) => /Physical size/i.test(l));
+        const m = /(\d+)x(\d+)/.exec(override ?? physical ?? out);
+        if (!m)
+            throw new errors_1.CliError(`Could not determine screen size from: ${out.trim()}`, 3);
+        return { width: +m[1], height: +m[2] };
+    }
+    tap(x, y) {
+        this.shell(['input', 'tap', String(Math.round(x)), String(Math.round(y))]);
+    }
+    swipe(x1, y1, x2, y2, durationMs) {
+        this.shell([
+            'input',
+            'swipe',
+            String(Math.round(x1)),
+            String(Math.round(y1)),
+            String(Math.round(x2)),
+            String(Math.round(y2)),
+            String(Math.round(durationMs)),
+        ]);
+    }
+    inputText(text) {
+        if (!text)
+            return;
+        this.shell(['input', 'text', escapeText(text)]);
+    }
+    pressKey(name) {
+        const code = KEYCODES[name.toLowerCase()] ?? (/^\d+$/.test(name) ? Number(name) : undefined);
+        if (code === undefined) {
+            throw new errors_1.CliError(`Unknown key '${name}'. Known: ${Object.keys(KEYCODES).join(', ')}, or a numeric keycode.`, 2);
+        }
+        this.shell(['input', 'keyevent', String(code)]);
+    }
+    launch(appId) {
+        // Resolve the app's default LAUNCHER activity, then start it with `am start -n`.
+        // We deliberately avoid `monkey -c LAUNCHER`: on some OEM skins (MIUI/HyperOS) it
+        // hangs indefinitely rather than returning, tripping the exec timeout.
+        const resolved = this.shell([
+            'cmd',
+            'package',
+            'resolve-activity',
+            '--brief',
+            '-a',
+            'android.intent.action.MAIN',
+            '-c',
+            'android.intent.category.LAUNCHER',
+            appId,
+        ]);
+        // `--brief` may print a header line before the component; the component is the
+        // last non-empty line and looks like `pkg/.Activity`.
+        const component = resolved
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .pop();
+        if (!component || !component.includes('/')) {
+            throw new errors_1.CliError(`Could not resolve a launcher activity for '${appId}' (is it installed?).`, 3);
+        }
+        // Capture stdout+stderr+exit code: `am start` reports failures via `Error:`/`Error
+        // type` (on EITHER stream) and/or a non-zero exit, but shell() returns only stdout —
+        // so a failed launch would otherwise read as success. The benign `Warning: Activity
+        // not started` (intent delivered to a running instance, e.g. --no-restart) is NOT a
+        // failure.
+        const r = (0, exec_1.runText)(ADB, this.withSerial(['shell', 'am', 'start', '-n', component]));
+        const combined = `${r.stdout}\n${r.stderr}`;
+        const benignWarning = /Warning: Activity not started/.test(combined);
+        if (/^Error\b/im.test(combined) || (r.code !== 0 && !benignWarning)) {
+            throw new errors_1.CliError(`Failed to launch '${appId}': ${r.stderr.trim() || r.stdout.trim() || `exit code ${r.code}`}`, 3);
+        }
+    }
+    stop(appId) {
+        this.shell(['am', 'force-stop', appId]);
+    }
+    clearApp(appId) {
+        // `pm clear` deletes the app's data dirs (shared-prefs, databases, caches) and
+        // force-stops it — resetting it to a just-installed state (logged out, no local
+        // data). It prints "Success", or "Failed" if the package is unknown/protected.
+        const result = this.shell(['pm', 'clear', appId]);
+        if (!/success/i.test(result)) {
+            throw new errors_1.CliError(`Failed to clear app data for '${appId}': ${result.trim() || 'no output from pm clear'}`, 3);
+        }
+    }
+    currentApp() {
+        const resumed = /mResumedActivity[^\n]*?\s([A-Za-z0-9_.]+\/[A-Za-z0-9_.]+)/.exec(this.shell(['dumpsys', 'activity', 'activities']));
+        if (resumed)
+            return resumed[1];
+        const focus = /mCurrentFocus[^\n]*?\s([A-Za-z0-9_.]+\/[A-Za-z0-9_.]+)/.exec(this.shell(['dumpsys', 'window']));
+        return focus ? focus[1] : '(unknown)';
+    }
+    getLogs(opts = {}) {
+        // One-shot dump: -d (and -t) make logcat EXIT. NEVER add -f/follow — it would
+        // stream forever and hang until the spawnSync timeout. The default buffers
+        // (main,system,crash) already include crash traces, so no -b needed.
+        const args = ['logcat', '-d'];
+        if (opts.since) {
+            // A logcat timestamp is `MM-DD HH:MM:SS.mmm` — digits, space, `-`, `:`, `.` only.
+            // Reject anything else so a caller-supplied `--since` cannot break out of the
+            // device-shell single-quoting below into command injection (device-shell escaping
+            // is the driver's job — see escapeText / CLAUDE.md).
+            if (!/^[0-9 :.\-]+$/.test(opts.since)) {
+                throw new errors_1.CliError(`Invalid --since '${opts.since}': only a logcat timestamp (digits, space, '-', ':', '.') is allowed.`, 2);
+            }
+            // `-t '<time>'` prints lines at/after that time, then exits. The marker
+            // contains a space and adb concatenates the post-`shell` args into one
+            // device-side command line, so single-quote it for the device shell to
+            // keep it a single token. (The marker is digits/`-`/`:`/`.`/space only.)
+            args.push('-t', `'${opts.since}'`);
+        }
+        else {
+            const n = opts.lines && opts.lines > 0 ? Math.floor(opts.lines) : DEFAULT_LOG_LINES;
+            args.push('-t', String(n));
+        }
+        if (opts.appId) {
+            // Scope to the app's process when it's alive. If pidof is empty the app
+            // isn't running (likely crashed) — fall through to a system-wide dump so
+            // the FATAL EXCEPTION, still in the crash buffer, is not missed.
+            const pid = this.shell(['pidof', opts.appId]).trim().split(/\s+/)[0];
+            if (pid)
+                args.push(`--pid=${pid}`);
+        }
+        return this.shell(args, 15000);
+    }
+    deviceTime() {
+        // logcat's default timestamp is MM-DD HH:MM:SS.mmm in the device's LOCAL time.
+        // Sample it from the device clock with a space-free format (so no device-shell
+        // quoting is needed), then restore the space to match logcat's `-t` form.
+        try {
+            return this.shell(['date', '+%m-%dT%H:%M:%S.000']).trim().replace('T', ' ');
+        }
+        catch {
+            return '';
+        }
+    }
+}
+exports.AdbDriver = AdbDriver;

package/dist/drivers/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimctlDriver = exports.AdbDriver = void 0;
+exports.getDriver = getDriver;
+const adb_1 = require("./adb");
+const simctl_1 = require("./simctl");
+var adb_2 = require("./adb");
+Object.defineProperty(exports, "AdbDriver", { enumerable: true, get: function () { return adb_2.AdbDriver; } });
+var simctl_2 = require("./simctl");
+Object.defineProperty(exports, "SimctlDriver", { enumerable: true, get: function () { return simctl_2.SimctlDriver; } });
+function getDriver(platform, device) {
+    return platform === 'ios' ? new simctl_1.SimctlDriver(device) : new adb_1.AdbDriver(device);
+}

package/dist/drivers/simctl.js

@@ -0,0 +1,156 @@
+"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;

package/dist/errors.js

@@ -0,0 +1,51 @@
+"use strict";
+// CliError carries the process exit code so the dispatcher can map failures to
+// stable, agent-readable exit statuses:
+//   0  success / found / assertion passed
+//   1  not found / assertion failed / wait timeout
+//   2  usage error or ambiguous selector (caller must refine)
+//   3  environment error (adb/simctl missing, no/multiple devices, dump failed)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AmbiguousSelectorError = exports.SelectorNotFoundError = exports.envError = exports.notFound = exports.usageError = exports.CliError = void 0;
+class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'CliError';
+    }
+}
+exports.CliError = CliError;
+const usageError = (m) => new CliError(m, 2);
+exports.usageError = usageError;
+const notFound = (m) => new CliError(m, 1);
+exports.notFound = notFound;
+const envError = (m) => new CliError(m, 3);
+exports.envError = envError;
+// --- Selector-resolution errors (heal triggers for the agent runner) --------
+//
+// A selector miss (zero matches) and an ambiguous match (>1) are still ordinary
+// CliErrors with the same exit codes as before (1 and 2) — printing, exit codes,
+// and `instanceof CliError` are unchanged for every existing caller. They are
+// subclassed only so the `vk ai` engine can tell a *resolvable-by-repair* failure
+// (these) apart from an assertion failure (`assert` returns exit 1, never throws),
+// which it must never "heal" or it would mask a real regression.
+/** Selector matched zero elements. Exit 1. The agent runner treats it as a heal trigger. */
+class SelectorNotFoundError extends CliError {
+    constructor(message) {
+        super(message, 1);
+        this.name = 'SelectorNotFoundError';
+    }
+}
+exports.SelectorNotFoundError = SelectorNotFoundError;
+/** Selector matched >1 element. Exit 2. Carries the candidates so the agent runner
+ *  can ask the model to disambiguate (a heal trigger) instead of aborting. */
+class AmbiguousSelectorError extends CliError {
+    candidates;
+    constructor(message, candidates) {
+        super(message, 2);
+        this.candidates = candidates;
+        this.name = 'AmbiguousSelectorError';
+    }
+}
+exports.AmbiguousSelectorError = AmbiguousSelectorError;

package/dist/exec.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runText = runText;
+exports.runBinary = runBinary;
+const node_child_process_1 = require("node:child_process");
+const errors_1 = require("./errors");
+const MAX_BUFFER = 64 * 1024 * 1024; // screenshots can be a few MB
+function describeError(cmd, args, err) {
+    if (err.code === 'ENOENT') {
+        return new errors_1.CliError(`'${cmd}' was not found on PATH. Is it installed and on your PATH?`, 3);
+    }
+    if (err.code === 'ETIMEDOUT') {
+        return new errors_1.CliError(`'${cmd} ${args.join(' ')}' timed out`, 3);
+    }
+    return new errors_1.CliError(`Failed to run '${cmd}': ${err.message}`, 3);
+}
+/** Run a command and capture stdout/stderr as UTF-8 text. */
+function runText(cmd, args, opts = {}) {
+    const r = (0, node_child_process_1.spawnSync)(cmd, args, {
+        encoding: 'utf8',
+        timeout: opts.timeout ?? 30000,
+        input: opts.input,
+        maxBuffer: MAX_BUFFER,
+    });
+    if (r.error)
+        throw describeError(cmd, args, r.error);
+    return { code: r.status ?? 0, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+/** Run a command and capture stdout as raw bytes (e.g. PNG screenshots). */
+function runBinary(cmd, args, opts = {}) {
+    const r = (0, node_child_process_1.spawnSync)(cmd, args, {
+        timeout: opts.timeout ?? 30000,
+        maxBuffer: MAX_BUFFER,
+    });
+    if (r.error)
+        throw describeError(cmd, args, r.error);
+    return {
+        code: r.status ?? 0,
+        stdout: r.stdout ?? Buffer.alloc(0),
+        stderr: r.stderr?.toString('utf8') ?? '',
+    };
+}