verikun 0.4.1

package/dist/agent/ir.js

@@ -0,0 +1,212 @@
+"use strict";
+// The plan IR: the deterministic, replayable program the LLM compiles a natural-
+// language test down to. The LLM is a COMPILER here, not a runtime — once an IR
+// exists it is re-run with zero model calls on the happy path. The model is woken
+// only to repair a step that genuinely fails (see ../agent/engine.ts).
+//
+// Shape rules (load-bearing, decided in plan-eng-review):
+//  - Nodes are a UNIFORM typed union — a leaf command, or a control node. (Mixing
+//    command-strings with structured control nodes would be the ugly split we
+//    avoided.) A leaf carries the verikun command triple {command, positionals,
+//    flags} directly, so the engine feeds it straight to executeOutcome.
+//  - SHALLOW: control-node bodies hold LEAF steps only — no loop-inside-loop / if-
+//    inside-loop in v1. That keeps the JSON schema NON-RECURSIVE, which is what lets
+//    Anthropic structured output (output_config.format) guarantee a valid IR.
+//    (A real flow that needs deeper nesting is the trigger to revisit — bounded-depth
+//    schema or prompt-and-parse; see the design doc's validation gate.)
+//  - flags are an array of {name,value} pairs (string values), NOT an open map —
+//    structured-output schemas can't express an arbitrary-key object. A pure boolean
+//    flag is value:"true" (flagBool reads 'true' as true; flagStr reads the string).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidPlanError = exports.REPAIR_DECISION_JSON_SCHEMA = exports.PLAN_JSON_SCHEMA = exports.DEFAULT_LOOP_CAP = exports.KNOWN_COMMANDS = void 0;
+exports.validateNode = validateNode;
+exports.parsePlan = parsePlan;
+exports.leafToFlags = leafToFlags;
+/** Commands a leaf step is allowed to carry — the agent-emittable ACTION/assertion verbs
+ *  the grammar offers, a SUBSET of cli.ts's dispatch (inspection/diagnostic commands are
+ *  excluded; see the note in the set). The engine validates every step — including a
+ *  model-generated REPAIR — against this set before executing it, so a hallucinated
+ *  command is rejected instead of hitting executeCommand's `default` (exit 2 + abort). */
+exports.KNOWN_COMMANDS = new Set([
+    'tap', 'click',
+    'text', 'type',
+    'key', 'back', 'home', 'enter',
+    'swipe', 'scroll',
+    'screenshot', 'shot',
+    'wait', 'assert',
+    'launch', 'open', 'stop', 'clear',
+    // 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
+    // (`--since`) and a host write (`--out`). Restricting the allowlist to the grammar's
+    // action set also preserves a load-bearing invariant: every command that can raise a
+    // heal trigger (a selector miss/ambiguity) is RECORDABLE, so markLastStepHealed ("heal
+    // the last recorded step") always targets the step that actually failed — a
+    // non-recordable selector-resolver here (e.g. `find`) would corrupt an unrelated step.
+]);
+exports.DEFAULT_LOOP_CAP = 25;
+/**
+ * JSON Schema for `output_config.format` so the model returns a guaranteed-valid
+ * Plan. Deliberately NON-RECURSIVE: control-node `body` arrays reference only the
+ * leaf schema, so there is no `Plan -> node -> Plan` cycle (structured output
+ * rejects recursive schemas). One nesting level, by design.
+ */
+exports.PLAN_JSON_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['version', 'steps'],
+    properties: {
+        version: { type: 'integer', enum: [1] },
+        package: { type: 'string' },
+        platform: { type: 'string', enum: ['android', 'ios'] },
+        steps: {
+            type: 'array',
+            items: {
+                anyOf: [
+                    leafSchema(),
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['type', 'selector', 'body'],
+                        properties: {
+                            type: { type: 'string', enum: ['if-present'] },
+                            selector: { type: 'string' },
+                            body: { type: 'array', items: leafSchema() },
+                        },
+                    },
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['type', 'selector', 'cap', 'body'],
+                        properties: {
+                            type: { type: 'string', enum: ['repeat'] },
+                            selector: { type: 'string' },
+                            cap: { type: 'integer' },
+                            body: { type: 'array', items: leafSchema() },
+                        },
+                    },
+                ],
+            },
+        },
+    },
+};
+/**
+ * Schema for a repair RESPONSE. A repair is a DECISION, not a forced substitution:
+ *  - "repair" + `step`: the screen has an element serving the failed step's intent.
+ *  - "give_up" + `reason`: it does NOT (the flow drifted to an unexpected screen),
+ *    so the test must FAIL rather than tap a loosely-related element and pass falsely.
+ * Non-recursive (the `step` is a flat leaf), so structured output can guarantee it.
+ */
+exports.REPAIR_DECISION_JSON_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['decision'],
+    properties: {
+        decision: { type: 'string', enum: ['repair', 'give_up'] },
+        step: leafSchema(),
+        reason: { type: 'string' },
+    },
+};
+function leafSchema() {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['type', 'command', 'positionals', 'flags'],
+        properties: {
+            type: { type: 'string', enum: ['command'] },
+            command: { type: 'string' },
+            positionals: { type: 'array', items: { type: 'string' } },
+            flags: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    required: ['name', 'value'],
+                    properties: { name: { type: 'string' }, value: { type: 'string' } },
+                },
+            },
+        },
+    };
+}
+/** Raised when a model-produced plan (or repair) is structurally invalid. Kept
+ *  out of errors.ts because it is an agent-layer concern, not a CLI exit code. */
+class InvalidPlanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidPlanError';
+    }
+}
+exports.InvalidPlanError = InvalidPlanError;
+function isFlagSpecArray(v) {
+    return (Array.isArray(v) &&
+        v.every((f) => f && typeof f === 'object' && typeof f.name === 'string' && typeof f.value === 'string'));
+}
+/** Validate a single node (used for both compile output and a spliced repair). */
+function validateNode(node, where) {
+    if (!node || typeof node !== 'object')
+        throw new InvalidPlanError(`${where}: not an object`);
+    const n = node;
+    switch (n.type) {
+        case 'command': {
+            if (typeof n.command !== 'string' || !exports.KNOWN_COMMANDS.has(n.command)) {
+                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[]`);
+            }
+            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 };
+        }
+        case 'if-present':
+        case 'repeat': {
+            if (typeof n.selector !== 'string' || !n.selector)
+                throw new InvalidPlanError(`${where}: ${n.type} needs a selector`);
+            if (!Array.isArray(n.body))
+                throw new InvalidPlanError(`${where}: ${n.type} body must be an array`);
+            const body = n.body.map((b, i) => {
+                const leaf = validateNode(b, `${where}.body[${i}]`);
+                if (leaf.type !== 'command')
+                    throw new InvalidPlanError(`${where}.body[${i}]: only leaf commands allowed (no nesting in v1)`);
+                return leaf;
+            });
+            if (n.type === 'if-present')
+                return { type: 'if-present', selector: n.selector, body };
+            const cap = typeof n.cap === 'number' && n.cap > 0 ? Math.floor(n.cap) : exports.DEFAULT_LOOP_CAP;
+            return { type: 'repeat', selector: n.selector, cap, body };
+        }
+        default:
+            throw new InvalidPlanError(`${where}: unknown node type ${JSON.stringify(n.type)}`);
+    }
+}
+/** Validate + normalize a parsed plan object (belt-and-suspenders even with
+ *  structured output, and the parse path when structured output is unavailable). */
+function parsePlan(raw) {
+    if (!raw || typeof raw !== 'object')
+        throw new InvalidPlanError('plan: not an object');
+    const p = raw;
+    if (p.version !== 1)
+        throw new InvalidPlanError(`plan: unsupported version ${JSON.stringify(p.version)} (expected 1)`);
+    if (!Array.isArray(p.steps))
+        throw new InvalidPlanError('plan: steps must be an array');
+    const steps = p.steps.map((s, i) => validateNode(s, `steps[${i}]`));
+    // A plan with zero steps would "pass" green having done nothing — reject it so a
+    // compiler misfire, prompt injection, or truncated cache entry can't be a false green.
+    if (steps.length === 0)
+        throw new InvalidPlanError('plan: has no steps (a test must have at least one step)');
+    return {
+        version: 1,
+        package: typeof p.package === 'string' ? p.package : undefined,
+        platform: typeof p.platform === 'string' ? p.platform : undefined,
+        steps,
+    };
+}
+/** Convert a leaf's {name,value}[] flags into the args-parser Flags record that
+ *  executeOutcome consumes. A boolean flag is carried as value "true" (flagBool
+ *  reads 'true' as true); a valued flag keeps its string. */
+function leafToFlags(step) {
+    const out = {};
+    for (const { name, value } of step.flags)
+        out[name] = value;
+    return out;
+}

package/dist/agent/provider.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/args.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.flagStr = flagStr;
+exports.flagBool = flagBool;
+exports.flagNum = flagNum;
+const errors_1 = require("./errors");
+const ALIASES = {
+    d: 'device',
+    i: 'index',
+    o: 'out',
+    p: 'platform',
+    c: 'contains',
+    j: 'json',
+    q: 'quiet',
+    h: 'help',
+    v: 'version',
+    t: 'timeout',
+    w: 'wait',
+    n: 'lines',
+};
+// Flags that never consume a following value.
+const BOOLEAN = new Set([
+    'json',
+    'contains',
+    'all',
+    'gone',
+    'enter',
+    'clear',
+    'tree',
+    'help',
+    'quiet',
+    'version',
+    'ios',
+    'android',
+    'fix',
+    'no-wait',
+    'full',
+    'more',
+    'show-plan',
+    'recompile',
+    'no-cache',
+    'no-restart',
+]);
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (tok.startsWith('-') && tok !== '-') {
+            let name = tok.replace(/^-+/, '');
+            let inlineValue;
+            const eq = name.indexOf('=');
+            if (eq >= 0) {
+                inlineValue = name.slice(eq + 1);
+                name = name.slice(0, eq);
+            }
+            name = ALIASES[name] ?? name;
+            if (inlineValue !== undefined) {
+                flags[name] = inlineValue;
+            }
+            else if (BOOLEAN.has(name)) {
+                flags[name] = true;
+            }
+            else {
+                const next = argv[i + 1];
+                if (next !== undefined && !(next.startsWith('-') && next !== '-')) {
+                    flags[name] = next;
+                    i++;
+                }
+                else {
+                    flags[name] = true;
+                }
+            }
+        }
+        else {
+            positionals.push(tok);
+        }
+    }
+    const command = positionals.shift();
+    return { command, positionals, flags };
+}
+function flagStr(flags, name) {
+    const v = flags[name];
+    return typeof v === 'string' ? v : undefined;
+}
+function flagBool(flags, name) {
+    return flags[name] === true || flags[name] === 'true';
+}
+function flagNum(flags, name) {
+    const v = flagStr(flags, name);
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isFinite(n))
+        throw new errors_1.CliError(`--${name} must be a number, got '${v}'`, 2);
+    return n;
+}

package/dist/bin/verikun.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("../cli");
+(0, cli_1.run)(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    process.stderr.write('Fatal: ' + (e instanceof Error ? e.message : String(e)) + '\n');
+    process.exit(3);
+});