autokap 1.0.7 → 1.0.8

package/dist/v2/schema.js

@@ -0,0 +1,295 @@
+/**
+ * Capture Agent — Zod Validation Schemas
+ *
+ * Validates ExecutionProgram at compile output (server) and CLI input boundaries.
+ */
+import { z } from 'zod';
+// ── Postcondition ───────────────────────────────────────────────────
+export const PostconditionSpecSchema = z.object({
+    type: z.enum([
+        'route_matches',
+        'element_visible',
+        'element_absent',
+        'text_contains',
+        'overlay_dismissed',
+        'screenshot_stable',
+        'any_change',
+        'always',
+    ]),
+    pattern: z.string().optional(),
+    selector: z.string().optional(),
+    text: z.string().optional(),
+    threshold: z.number().min(0).max(1).optional(),
+    waitMs: z.number().int().positive().optional(),
+}).superRefine((value, ctx) => {
+    if (value.type === 'route_matches' && !value.pattern) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'route_matches postconditions require `pattern`',
+            path: ['pattern'],
+        });
+    }
+    if (['element_visible', 'element_absent', 'text_contains'].includes(value.type) && !value.selector) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${value.type} postconditions require \`selector\``,
+            path: ['selector'],
+        });
+    }
+    if (value.type === 'text_contains' && !value.text) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'text_contains postconditions require `text`',
+            path: ['text'],
+        });
+    }
+});
+// ── Recovery policy ─────────────────────────────────────────────────
+export const RecoveryPolicySchema = z.object({
+    retries: z.number().int().min(0).max(10),
+    useSelectorMemory: z.boolean(),
+    useAltInteraction: z.boolean(),
+    allowReload: z.boolean(),
+    allowHealer: z.boolean(),
+});
+// ── Opcode base fields ──────────────────────────────────────────────
+const opcodeBase = {
+    description: z.string().min(1),
+    postcondition: PostconditionSpecSchema,
+    recovery: RecoveryPolicySchema,
+    timeoutMs: z.number().int().positive(),
+    maxFailures: z.number().int().positive(),
+};
+// ── Individual opcode schemas ───────────────────────────────────────
+const NavigateOpcodeSchema = z.object({
+    kind: z.literal('NAVIGATE'),
+    ...opcodeBase,
+    url: z.string().min(1),
+});
+const DismissOverlaysOpcodeSchema = z.object({
+    kind: z.literal('DISMISS_OVERLAYS'),
+    ...opcodeBase,
+});
+const AssertRouteOpcodeSchema = z.object({
+    kind: z.literal('ASSERT_ROUTE'),
+    ...opcodeBase,
+    urlPattern: z.string().min(1),
+});
+const AssertSurfaceOpcodeSchema = z.object({
+    kind: z.literal('ASSERT_SURFACE'),
+    ...opcodeBase,
+    selectors: z.array(z.string().min(1)).min(1),
+    matchAll: z.boolean(),
+});
+const SemanticTargetSchema = z.object({
+    text: z.string().optional(),
+    role: z.string().optional(),
+    label: z.string().optional(),
+    near: z.string().optional(),
+    placeholder: z.string().optional(),
+    exact: z.boolean().optional(),
+}).refine((value) => Boolean(value.text || value.role || value.label || value.near || value.placeholder), 'semantic targets need at least one identifying field');
+const ClickOpcodeSchema = z.object({
+    kind: z.literal('CLICK'),
+    ...opcodeBase,
+    selector: z.string().min(1),
+    target: SemanticTargetSchema.optional(),
+    fingerprint: z.string().optional(),
+    selectorAlternates: z.array(z.string().min(1)).optional(),
+});
+const TypeOpcodeSchema = z.object({
+    kind: z.literal('TYPE'),
+    ...opcodeBase,
+    selector: z.string().min(1),
+    target: SemanticTargetSchema.optional(),
+    text: z.string(),
+    clearFirst: z.boolean(),
+    fingerprint: z.string().optional(),
+    selectorAlternates: z.array(z.string().min(1)).optional(),
+});
+const PressKeyOpcodeSchema = z.object({
+    kind: z.literal('PRESS_KEY'),
+    ...opcodeBase,
+    key: z.string().min(1),
+});
+const WaitForOpcodeSchema = z.object({
+    kind: z.literal('WAIT_FOR'),
+    ...opcodeBase,
+    selector: z.string().min(1).optional(),
+    target: SemanticTargetSchema.optional(),
+    state: z.enum(['visible', 'attached']),
+}).superRefine((value, ctx) => {
+    if (!value.selector && !value.target) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'WAIT_FOR requires either `selector` or `target`',
+            path: ['selector'],
+        });
+    }
+});
+const storageHintSchema = z.object({
+    storage: z.enum(['localStorage', 'sessionStorage']),
+    key: z.string().min(1),
+    value: z.string(),
+});
+const SetLocaleOpcodeSchema = z.object({
+    kind: z.literal('SET_LOCALE'),
+    ...opcodeBase,
+    locale: z.string().min(1),
+    method: z.enum(['browser_context', 'ui_interaction', 'storage']),
+    selector: z.string().optional(),
+    storageHints: z.array(storageHintSchema).optional(),
+}).superRefine((value, ctx) => {
+    if (value.method === 'ui_interaction' && !value.selector) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'SET_LOCALE with `ui_interaction` requires `selector`',
+            path: ['selector'],
+        });
+    }
+    if (value.method === 'storage' && (!value.storageHints || value.storageHints.length === 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'SET_LOCALE with `storage` requires at least one `storageHints` entry',
+            path: ['storageHints'],
+        });
+    }
+});
+const SetThemeOpcodeSchema = z.object({
+    kind: z.literal('SET_THEME'),
+    ...opcodeBase,
+    theme: z.enum(['light', 'dark']),
+    method: z.enum(['color_scheme', 'ui_interaction', 'storage']),
+    selector: z.string().optional(),
+    storageHints: z.array(storageHintSchema).optional(),
+}).superRefine((value, ctx) => {
+    if (value.method === 'ui_interaction' && !value.selector) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'SET_THEME with `ui_interaction` requires `selector`',
+            path: ['selector'],
+        });
+    }
+    if (value.method === 'storage' && (!value.storageHints || value.storageHints.length === 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'SET_THEME with `storage` requires at least one `storageHints` entry',
+            path: ['storageHints'],
+        });
+    }
+});
+const ScrollOpcodeSchema = z.object({
+    kind: z.literal('SCROLL'),
+    ...opcodeBase,
+    direction: z.enum(['up', 'down', 'left', 'right']),
+    amount: z.number().int().positive().optional(),
+    targetSelector: z.string().optional(),
+    target: SemanticTargetSchema.optional(),
+});
+const CaptureScreenshotOpcodeSchema = z.object({
+    kind: z.literal('CAPTURE_SCREENSHOT'),
+    ...opcodeBase,
+    captureId: z.string().optional(),
+    captureName: z.string().optional(),
+    elementSelector: z.string().optional(),
+});
+const BeginClipOpcodeSchema = z.object({
+    kind: z.literal('BEGIN_CLIP'),
+    ...opcodeBase,
+    clipId: z.string().optional(),
+    clipName: z.string().optional(),
+});
+const EndClipOpcodeSchema = z.object({
+    kind: z.literal('END_CLIP'),
+    ...opcodeBase,
+    clipId: z.string().optional(),
+    clipName: z.string().optional(),
+});
+// ── Discriminated union ─────────────────────────────────────────────
+export const ExecutionOpcodeSchema = z.discriminatedUnion('kind', [
+    NavigateOpcodeSchema,
+    DismissOverlaysOpcodeSchema,
+    AssertRouteOpcodeSchema,
+    AssertSurfaceOpcodeSchema,
+    ClickOpcodeSchema,
+    TypeOpcodeSchema,
+    PressKeyOpcodeSchema,
+    WaitForOpcodeSchema,
+    SetLocaleOpcodeSchema,
+    SetThemeOpcodeSchema,
+    ScrollOpcodeSchema,
+    CaptureScreenshotOpcodeSchema,
+    BeginClipOpcodeSchema,
+    EndClipOpcodeSchema,
+]);
+// ── Variant & precondition ──────────────────────────────────────────
+export const VariantSpecSchema = z.object({
+    id: z.string().min(1),
+    viewport: z.object({
+        width: z.number().int().positive(),
+        height: z.number().int().positive(),
+    }),
+    deviceScaleFactor: z.number().positive().optional(),
+    locale: z.string().optional(),
+    theme: z.enum(['light', 'dark']).optional(),
+    targetId: z.string().optional(),
+    targetLabel: z.string().optional(),
+    deviceFrame: z.string().optional(),
+});
+const cookieSchema = z.object({
+    name: z.string().min(1),
+    value: z.string(),
+    domain: z.string().min(1),
+    path: z.string().optional(),
+});
+export const PreconditionSpecSchema = z.object({
+    auth: z.enum(['authenticated', 'anonymous', 'any']),
+    credentialsId: z.string().optional(),
+    storageState: z.any().optional(),
+    sessionStorage: z.record(z.string(), z.record(z.string(), z.string())).optional(),
+    cookies: z.array(cookieSchema).optional(),
+});
+// ── Artifact spec ───────────────────────────────────────────────────
+export const ArtifactSpecSchema = z.object({
+    mediaMode: z.enum(['screenshot', 'clip']),
+    format: z.object({
+        clipFormat: z.enum(['gif', 'mp4', 'both']).optional(),
+        screenshotFormat: z.enum(['png', 'jpeg']).optional(),
+    }).optional(),
+    cursorTheme: z.enum(['minimal', 'macos', 'windows']).optional(),
+    applyMockup: z.boolean().optional(),
+    applyStatusBar: z.boolean().optional(),
+});
+// ── Full program ────────────────────────────────────────────────────
+export const ExecutionProgramSchema = z.object({
+    presetId: z.string().min(1),
+    programVersion: z.number().int().positive(),
+    mediaMode: z.enum(['screenshot', 'clip']),
+    baseUrl: z.string().url(),
+    variants: z.array(VariantSpecSchema).min(1),
+    preconditions: PreconditionSpecSchema,
+    steps: z.array(ExecutionOpcodeSchema).min(1),
+    artifactPlan: ArtifactSpecSchema,
+    compileFingerprint: z.string().min(1),
+    compiledAt: z.string().datetime(),
+    compiledWith: z.string().optional(),
+});
+// ── Healer patch ────────────────────────────────────────────────────
+export const HealerPatchSchema = z.object({
+    opcodeIndex: z.number().int().min(0),
+    originalOpcode: ExecutionOpcodeSchema,
+    replacementOpcodes: z.array(ExecutionOpcodeSchema).min(1).max(3),
+    reason: z.string().min(1),
+    patchedAt: z.string().datetime(),
+});
+// ── Typed parse helpers ─────────────────────────────────────────────
+export function parseProgram(data) {
+    return ExecutionProgramSchema.parse(data);
+}
+export function parseOpcode(data) {
+    return ExecutionOpcodeSchema.parse(data);
+}
+export function safeParseProgramResult(data) {
+    return ExecutionProgramSchema.safeParse(data);
+}
+//# sourceMappingURL=schema.js.map

package/dist/v2/selector-resolver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Capture Agent — Selector Resolver
+ *
+ * Progressive selector resolution for opcodes that target elements:
+ * 1. Primary selector from compiled program
+ * 2. AKTree fingerprint match
+ * 3. Selector memory candidates (from Supabase)
+ * 4. Fuzzy text match on AKTree nodes
+ */
+import type { RuntimeAdapter } from './types.js';
+export interface ResolvedSelector {
+    selector: string;
+    strategy: 'primary' | 'fingerprint' | 'memory' | 'fuzzy_text' | 'alternate';
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface SelectorResolverOptions {
+    /** Primary selector from the compiled opcode */
+    primary: string;
+    /** AKTree fingerprint for fuzzy matching */
+    fingerprint?: string;
+    /** Alternative selectors from the compiled opcode */
+    alternates?: string[];
+    /** Selector memory map: stepSignature -> known-good selectors */
+    selectorMemory?: Record<string, string[]>;
+    /** Step signature for memory lookup */
+    stepSignature?: string;
+    /** Human-readable description of the target element (for fuzzy matching) */
+    description?: string;
+}
+/**
+ * Resolves a selector by trying multiple strategies in order.
+ * Returns the first working selector, or null if nothing matches.
+ */
+export declare function resolveSelector(adapter: RuntimeAdapter, options: SelectorResolverOptions): Promise<ResolvedSelector | null>;

package/dist/v2/selector-resolver.js

@@ -0,0 +1,181 @@
+/**
+ * Capture Agent — Selector Resolver
+ *
+ * Progressive selector resolution for opcodes that target elements:
+ * 1. Primary selector from compiled program
+ * 2. AKTree fingerprint match
+ * 3. Selector memory candidates (from Supabase)
+ * 4. Fuzzy text match on AKTree nodes
+ */
+/**
+ * Resolves a selector by trying multiple strategies in order.
+ * Returns the first working selector, or null if nothing matches.
+ */
+export async function resolveSelector(adapter, options) {
+    const tree = await adapter.getAKTree();
+    // 1. Try primary selector
+    if (await selectorExists(adapter, options.primary)) {
+        return { selector: options.primary, strategy: 'primary', confidence: 'high' };
+    }
+    // 2. Try alternate selectors
+    if (options.alternates) {
+        for (const alt of options.alternates) {
+            if (await selectorExists(adapter, alt)) {
+                return { selector: alt, strategy: 'alternate', confidence: 'high' };
+            }
+        }
+    }
+    // 3. Try fingerprint match in AKTree
+    if (options.fingerprint) {
+        const match = findNodeByFingerprint(tree, options.fingerprint);
+        if (match) {
+            return { selector: match, strategy: 'fingerprint', confidence: 'medium' };
+        }
+    }
+    // 4. Try selector memory
+    if (options.selectorMemory && options.stepSignature) {
+        const candidates = options.selectorMemory[options.stepSignature];
+        if (candidates) {
+            for (const candidate of candidates) {
+                if (await selectorExists(adapter, candidate)) {
+                    return { selector: candidate, strategy: 'memory', confidence: 'medium' };
+                }
+            }
+        }
+    }
+    // 5. Try fuzzy text match
+    if (options.description) {
+        const match = findNodeByFuzzyText(tree, options.description);
+        if (match) {
+            return { selector: match, strategy: 'fuzzy_text', confidence: 'low' };
+        }
+    }
+    return null;
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+async function selectorExists(adapter, selector) {
+    try {
+        const found = await adapter.waitFor({
+            selector,
+            state: 'attached',
+            timeoutMs: 2000,
+        });
+        return found;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Finds an AKTree node whose sourceRef/attributes match a fingerprint string.
+ * Returns a CSS selector that can be used to interact with the element.
+ */
+function findNodeByFingerprint(tree, fingerprint) {
+    const parts = fingerprint.split(':');
+    // Fingerprint format: "type:label:context" e.g. "button:submit:login-form"
+    const [expectedType, expectedLabel, expectedContext] = parts;
+    let bestMatch = null;
+    let bestScore = 0;
+    function walk(node) {
+        if (!node.visible || !node.interactive) {
+            node.children.forEach(walk);
+            return;
+        }
+        let score = 0;
+        // Match type
+        if (expectedType && node.type === expectedType)
+            score += 3;
+        // Match label (fuzzy)
+        if (expectedLabel) {
+            const nodeLabelLower = node.label.toLowerCase();
+            const expectedLabelLower = expectedLabel.toLowerCase();
+            if (nodeLabelLower === expectedLabelLower)
+                score += 5;
+            else if (nodeLabelLower.includes(expectedLabelLower))
+                score += 3;
+            else if (expectedLabelLower.includes(nodeLabelLower))
+                score += 1;
+        }
+        // Match context (check sourceRef)
+        if (expectedContext && node.sourceRef.toLowerCase().includes(expectedContext.toLowerCase())) {
+            score += 2;
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            bestMatch = node;
+        }
+        node.children.forEach(walk);
+    }
+    walk(tree.root);
+    if (bestMatch && bestScore >= 4) {
+        return buildSelectorFromNode(bestMatch);
+    }
+    return null;
+}
+/**
+ * Finds a visible interactive node by fuzzy text matching against the description.
+ */
+function findNodeByFuzzyText(tree, description) {
+    const descTokens = tokenize(description);
+    if (descTokens.length === 0)
+        return null;
+    let bestMatch = null;
+    let bestOverlap = 0;
+    function walk(node) {
+        if (!node.visible || !node.interactive) {
+            node.children.forEach(walk);
+            return;
+        }
+        const nodeTokens = tokenize(node.label);
+        const overlap = countOverlap(descTokens, nodeTokens);
+        if (overlap > bestOverlap) {
+            bestOverlap = overlap;
+            bestMatch = node;
+        }
+        node.children.forEach(walk);
+    }
+    walk(tree.root);
+    // Require at least 2 token overlap or >50% match
+    if (bestMatch && (bestOverlap >= 2 || bestOverlap / descTokens.length > 0.5)) {
+        return buildSelectorFromNode(bestMatch);
+    }
+    return null;
+}
+function buildSelectorFromNode(node) {
+    // Try to build the most specific selector from node attributes
+    const ref = node.sourceRef;
+    // Extract data-testid
+    const testIdMatch = ref.match(/data-testid="([^"]+)"/);
+    if (testIdMatch)
+        return `[data-testid="${testIdMatch[1]}"]`;
+    // Extract id
+    const idMatch = ref.match(/ id="([^"]+)"/);
+    if (idMatch)
+        return `#${idMatch[1]}`;
+    // Extract tag + role + text
+    const tagMatch = ref.match(/^<(\w+)/);
+    const tag = tagMatch?.[1] ?? '*';
+    const role = node.attributes['role'];
+    if (role) {
+        return `${tag}[role="${role}"]`;
+    }
+    // Fallback: use AKNode id as a CSS selector via data attribute
+    if (node.id) {
+        return `[data-ak-id="${node.id}"]`;
+    }
+    return `${tag}:has-text("${escapeText(node.label.slice(0, 50))}")`;
+}
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(t => t.length >= 2);
+}
+function countOverlap(a, b) {
+    const setB = new Set(b);
+    return a.filter(t => setB.has(t)).length;
+}
+function escapeText(text) {
+    return text.replace(/"/g, '\\"').replace(/\n/g, ' ');
+}
+//# sourceMappingURL=selector-resolver.js.map

package/dist/v2/semantic-resolver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Capture Agent — Semantic Target Resolver
+ *
+ * Resolves a SemanticTarget to a concrete Playwright locator.
+ * This is the core mechanism that allows opcodes to work WITHOUT CSS selectors.
+ *
+ * Resolution cascade:
+ * 1. CSS selector (if provided, fast path)
+ * 2. Playwright semantic locators (getByRole, getByText, getByLabel, getByPlaceholder)
+ * 3. Selector alternates
+ * 4. Composite: role + name + near (for disambiguation)
+ *
+ * All resolution happens via Playwright's built-in locator API — no AKTree needed.
+ */
+import type { Page, Locator } from 'playwright';
+import type { SemanticTarget } from './types.js';
+export interface ResolvedTarget {
+    locator: Locator;
+    method: 'selector' | 'role' | 'text' | 'label' | 'placeholder' | 'alternate' | 'composite';
+}
+export interface ResolveOptions {
+    /** Primary CSS selector */
+    selector?: string;
+    /** Semantic target description */
+    target?: SemanticTarget;
+    /** Fallback selectors */
+    selectorAlternates?: string[];
+    /** Timeout for visibility check (ms). Default: 3000 */
+    timeoutMs?: number;
+}
+/**
+ * Resolves an element on the page using the best available method.
+ * Returns the first visible locator found, or null if nothing matches.
+ */
+export declare function resolveTarget(page: Page, options: ResolveOptions): Promise<ResolvedTarget | null>;