autokap 1.0.7 → 1.0.8

package/dist/execution-schema.js

@@ -0,0 +1,507 @@
+/**
+ * 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(),
+};
+/**
+ * Strict URL validator: rejects schemes without a host (e.g. `"https://"`),
+ * which Zod's built-in `.url()` regex accepts but Playwright crashes on at
+ * navigation time. We use the WHATWG `URL` parser as the source of truth.
+ */
+const StrictUrlSchema = z.string().min(1).refine((value) => {
+    try {
+        const parsed = new URL(value);
+        return Boolean(parsed.host);
+    }
+    catch {
+        return false;
+    }
+}, {
+    message: 'Must be a fully-qualified URL with a host (e.g. "https://app.example.com/dashboard"), not a bare scheme like "https://"',
+});
+// ── Individual opcode schemas ───────────────────────────────────────
+const NavigateOpcodeSchema = z.object({
+    kind: z.literal('NAVIGATE'),
+    ...opcodeBase,
+    url: StrictUrlSchema,
+});
+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(),
+    button: z.enum(['right', 'middle']).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(),
+    textByLocale: z.record(z.string().min(1), z.string()).optional(),
+    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', 'cookie']),
+    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', '$variant']),
+    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 CaptureDomOpcodeSchema = z.object({
+    kind: z.literal('CAPTURE_DOM'),
+    ...opcodeBase,
+    stateName: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, 'stateName must be kebab-case'),
+    selector: z.string().min(1).optional(),
+});
+const CaptureFragmentOpcodeSchema = z.object({
+    kind: z.literal('CAPTURE_FRAGMENT'),
+    ...opcodeBase,
+    fragmentName: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, 'fragmentName must be kebab-case'),
+    // Variants let the same fragment be captured in multiple states (e.g.
+    // default / purple-bg / text-bottom). Defaults to `'default'` when omitted.
+    // Player swaps variants in place via parentNode.replaceChild so the
+    // surrounding DOM keeps its scroll position, focus, and sibling layout.
+    variantName: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, 'variantName must be kebab-case').optional(),
+    parentState: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, 'parentState must be kebab-case'),
+    selector: z.string().min(1),
+    triggerSelector: z.string().min(1).optional(),
+    mountStrategy: z.string().min(1).optional(),
+    mountTargetSelector: z.string().min(1).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(),
+});
+const HoverOpcodeSchema = z.object({
+    kind: z.literal('HOVER'),
+    ...opcodeBase,
+    selector: z.string().min(1),
+    target: SemanticTargetSchema.optional(),
+    fingerprint: z.string().optional(),
+    selectorAlternates: z.array(z.string().min(1)).optional(),
+});
+const SelectOptionOpcodeSchema = z.object({
+    kind: z.literal('SELECT_OPTION'),
+    ...opcodeBase,
+    selector: z.string().min(1),
+    target: SemanticTargetSchema.optional(),
+    optionLabel: z.string().optional(),
+    optionValue: z.string().optional(),
+    optionIndex: z.number().int().min(0).optional(),
+    fingerprint: z.string().optional(),
+    selectorAlternates: z.array(z.string().min(1)).optional(),
+}).superRefine((value, ctx) => {
+    if (value.optionLabel === undefined && value.optionValue === undefined && value.optionIndex === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'SELECT_OPTION requires at least one of optionLabel, optionValue, or optionIndex',
+        });
+    }
+});
+const CheckOpcodeSchema = z.object({
+    kind: z.literal('CHECK'),
+    ...opcodeBase,
+    selector: z.string().min(1),
+    target: SemanticTargetSchema.optional(),
+    checked: z.boolean(),
+    fingerprint: z.string().optional(),
+    selectorAlternates: z.array(z.string().min(1)).optional(),
+});
+const DoubleClickOpcodeSchema = z.object({
+    kind: z.literal('DOUBLE_CLICK'),
+    ...opcodeBase,
+    selector: z.string().min(1),
+    target: SemanticTargetSchema.optional(),
+    fingerprint: z.string().optional(),
+    selectorAlternates: z.array(z.string().min(1)).optional(),
+});
+// ── Mock data opcodes (soft / non-blocking) ─────────────────────────
+const CloneElementOpcodeSchema = z.object({
+    kind: z.literal('CLONE_ELEMENT'),
+    ...opcodeBase,
+    sourceSelector: z.string().min(1),
+    containerSelector: z.string().min(1),
+    count: z.number().int().min(1).max(500),
+    removeSource: z.boolean().optional(),
+});
+const InjectMockDataOpcodeSchema = z.object({
+    kind: z.literal('INJECT_MOCK_DATA'),
+    ...opcodeBase,
+    groupName: z.string().min(1),
+    // Clone fields
+    containerSelector: z.string().min(1).optional(),
+    templateSelector: z.string().min(1).optional(),
+    count: z.number().int().min(1).max(500).optional(),
+    removeTemplate: z.boolean().optional(),
+    slotMappings: z.array(z.object({
+        slot: z.string().min(1),
+        selector: z.string().min(1),
+        attribute: z.string().min(1).optional(),
+    })).min(1).optional(),
+    // Trigger fields
+    inputSelector: z.string().min(1).optional(),
+    triggerSelector: z.string().min(1).optional(),
+}).superRefine((value, ctx) => {
+    // The two delivery mechanisms are independent and additive. An opcode must
+    // declare AT LEAST ONE complete mechanism — typically both — but if only
+    // one is provided that's still valid.
+    const hasClone = Boolean(value.containerSelector && value.slotMappings && value.slotMappings.length > 0);
+    const hasTrigger = Boolean(value.inputSelector && value.triggerSelector);
+    if (!hasClone && !hasTrigger) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'INJECT_MOCK_DATA must declare at least one mechanism: clone (containerSelector + slotMappings) and/or trigger (inputSelector + triggerSelector). Typically both should be provided.',
+            path: ['containerSelector'],
+        });
+        return;
+    }
+    // Partial-clone validation: if some clone fields are present, they all must
+    // make sense together. removeTemplate is optional and defaults to false.
+    if (value.containerSelector && (!value.slotMappings || value.slotMappings.length === 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'INJECT_MOCK_DATA: when `containerSelector` is provided, at least one entry in `slotMappings` is required',
+            path: ['slotMappings'],
+        });
+    }
+    if (value.slotMappings && value.slotMappings.length > 0 && !value.containerSelector) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'INJECT_MOCK_DATA: when `slotMappings` is provided, `containerSelector` is required',
+            path: ['containerSelector'],
+        });
+    }
+    // Partial-trigger validation: trigger is all-or-nothing.
+    if (value.inputSelector && !value.triggerSelector) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'INJECT_MOCK_DATA: when `inputSelector` is provided, `triggerSelector` is required',
+            path: ['triggerSelector'],
+        });
+    }
+    if (value.triggerSelector && !value.inputSelector) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'INJECT_MOCK_DATA: when `triggerSelector` is provided, `inputSelector` is required',
+            path: ['inputSelector'],
+        });
+    }
+});
+const RemoveElementOpcodeSchema = z.object({
+    kind: z.literal('REMOVE_ELEMENT'),
+    ...opcodeBase,
+    selector: z.string().min(1),
+});
+const SetAttributeOpcodeSchema = z.object({
+    kind: z.literal('SET_ATTRIBUTE'),
+    ...opcodeBase,
+    selector: z.string().min(1),
+    attribute: z.string().min(1),
+    value: z.string(),
+});
+// ── Discriminated union ─────────────────────────────────────────────
+export const ExecutionOpcodeSchema = z.discriminatedUnion('kind', [
+    NavigateOpcodeSchema,
+    DismissOverlaysOpcodeSchema,
+    AssertRouteOpcodeSchema,
+    AssertSurfaceOpcodeSchema,
+    ClickOpcodeSchema,
+    TypeOpcodeSchema,
+    PressKeyOpcodeSchema,
+    WaitForOpcodeSchema,
+    SetLocaleOpcodeSchema,
+    SetThemeOpcodeSchema,
+    ScrollOpcodeSchema,
+    CaptureScreenshotOpcodeSchema,
+    CaptureDomOpcodeSchema,
+    CaptureFragmentOpcodeSchema,
+    BeginClipOpcodeSchema,
+    EndClipOpcodeSchema,
+    HoverOpcodeSchema,
+    SelectOptionOpcodeSchema,
+    CheckOpcodeSchema,
+    DoubleClickOpcodeSchema,
+    CloneElementOpcodeSchema,
+    InjectMockDataOpcodeSchema,
+    RemoveElementOpcodeSchema,
+    SetAttributeOpcodeSchema,
+]);
+// ── Mock data group ─────────────────────────────────────────────────
+export const MockDataSlotSchema = z.object({
+    name: z.string().min(1),
+    description: z.string(),
+    // Free-form hint string. The dashboard editor recognizes a small set of
+    // canonical values (`text`, `number`, `image`, `color`, `date`, `url`)
+    // and falls back to a plain text input for everything else, so any
+    // descriptive label is safe here. See `inputTypeForHint()` in
+    // web/components/mock-data-editor.tsx.
+    hint: z.string().optional(),
+});
+export const MockDataRowSchema = z.record(z.string(), z.string());
+export const MockDataGroupSchema = z.object({
+    name: z.string().min(1),
+    description: z.string(),
+    slots: z.array(MockDataSlotSchema).min(1),
+    defaultValues: z.array(MockDataRowSchema),
+    replaceExisting: z.boolean().optional(),
+});
+// ── 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(),
+});
+// `auth` enum removed: bootstrap is auto-detected from cookies / storageState /
+// sessionStorage (injected into the browser context) and/or credentials
+// (substituted into {{email}}/{{password}}/{{loginUrl}} placeholders inside
+// opcodes). Old programs carrying an `auth` field still parse — Zod strips
+// unknown keys silently — and the runtime ignores it.
+export const PreconditionSpecSchema = z.object({
+    credentialsId: z.string().optional(),
+    credentials: z.object({
+        email: z.string().optional(),
+        password: z.string().optional(),
+        loginUrl: z.string().optional(),
+    }).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', 'dom']),
+    format: z.object({
+        clipFormat: z.enum(['gif', 'mp4', 'both']).optional(),
+        screenshotFormat: z.enum(['png', 'jpeg']).optional(),
+    }).optional(),
+    cursorTheme: z.enum(['minimal', 'macos', 'windows']).optional(),
+    maxClipDurationSec: z.number().positive().optional(),
+    applyMockup: z.boolean().optional(),
+    applyStatusBar: z.boolean().optional(),
+    domOptions: z.object({
+        sanitize: z.boolean().optional(),
+    }).optional(),
+});
+// ── Full program ────────────────────────────────────────────────────
+export const ExecutionProgramSchema = z.object({
+    presetId: z.string().min(1),
+    programVersion: z.number().int().positive(),
+    mediaMode: z.enum(['screenshot', 'clip', 'dom']),
+    baseUrl: StrictUrlSchema,
+    maxParallelCaptures: z.number().int().positive().optional(),
+    variants: z.array(VariantSpecSchema).min(1),
+    preconditions: PreconditionSpecSchema,
+    steps: z.array(ExecutionOpcodeSchema).min(1),
+    artifactPlan: ArtifactSpecSchema,
+    outputScale: z.number().positive().optional(),
+    compileFingerprint: z.string().min(1),
+    variantFingerprint: z.string().optional(),
+    compiledAt: z.string().datetime(),
+    compiledWith: z.string().optional(),
+    mockDataGroups: z.array(MockDataGroupSchema).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=execution-schema.js.map