autokap 1.0.6 → 1.0.8

package/dist/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/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 './execution-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>;

package/dist/semantic-resolver.js

@@ -0,0 +1,161 @@
+/**
+ * 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.
+ */
+/**
+ * Resolves an element on the page using the best available method.
+ * Returns the first visible locator found, or null if nothing matches.
+ */
+export async function resolveTarget(page, options) {
+    const timeout = options.timeoutMs ?? 3000;
+    // 1. Primary CSS selector
+    if (options.selector) {
+        const locator = page.locator(options.selector).first();
+        if (await isVisible(locator, timeout)) {
+            return { locator, method: 'selector' };
+        }
+    }
+    // 2. Semantic locators from target
+    if (options.target) {
+        const resolved = await resolveSemanticTarget(page, options.target, timeout);
+        if (resolved)
+            return resolved;
+    }
+    // 3. Alternate selectors
+    if (options.selectorAlternates) {
+        for (const alt of options.selectorAlternates) {
+            const locator = page.locator(alt).first();
+            if (await isVisible(locator, timeout)) {
+                return { locator, method: 'alternate' };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolves a SemanticTarget using Playwright's semantic locator API.
+ */
+async function resolveSemanticTarget(page, target, timeout) {
+    const exact = target.exact ?? false;
+    // Strategy A: getByRole with name (most precise)
+    if (target.role && (target.text || target.label)) {
+        const name = target.label || target.text;
+        try {
+            let locator = page.getByRole(target.role, {
+                name: name,
+                exact,
+            });
+            if (target.near) {
+                locator = narrowByNear(page, locator, target.near);
+            }
+            locator = locator.first();
+            if (await isVisible(locator, timeout)) {
+                return { locator, method: 'role' };
+            }
+        }
+        catch {
+            // Invalid role or no match
+        }
+    }
+    // Strategy B: getByRole without name
+    if (target.role && !target.text && !target.label) {
+        try {
+            let locator = page.getByRole(target.role);
+            if (target.near) {
+                locator = narrowByNear(page, locator, target.near);
+            }
+            locator = locator.first();
+            if (await isVisible(locator, timeout)) {
+                return { locator, method: 'role' };
+            }
+        }
+        catch {
+            // Invalid role
+        }
+    }
+    // Strategy C: getByText
+    if (target.text) {
+        let locator = page.getByText(target.text, { exact });
+        if (target.near) {
+            locator = narrowByNear(page, locator, target.near);
+        }
+        locator = locator.first();
+        if (await isVisible(locator, timeout)) {
+            return { locator, method: 'text' };
+        }
+    }
+    // Strategy D: getByLabel
+    if (target.label) {
+        let locator = page.getByLabel(target.label, { exact });
+        if (target.near) {
+            locator = narrowByNear(page, locator, target.near);
+        }
+        locator = locator.first();
+        if (await isVisible(locator, timeout)) {
+            return { locator, method: 'label' };
+        }
+    }
+    // Strategy E: getByPlaceholder (for inputs)
+    if (target.placeholder) {
+        let locator = page.getByPlaceholder(target.placeholder, { exact });
+        if (target.near) {
+            locator = narrowByNear(page, locator, target.near);
+        }
+        locator = locator.first();
+        if (await isVisible(locator, timeout)) {
+            return { locator, method: 'placeholder' };
+        }
+    }
+    // Strategy F: Composite — try role-based with looser matching
+    if (target.role) {
+        try {
+            const allByRole = page.getByRole(target.role);
+            const count = await allByRole.count();
+            for (let i = 0; i < Math.min(count, 10); i++) {
+                const candidate = allByRole.nth(i);
+                if (await isVisible(candidate, 500)) {
+                    const text = await candidate.textContent().catch(() => null);
+                    if (text && target.text && text.toLowerCase().includes(target.text.toLowerCase())) {
+                        return { locator: candidate, method: 'composite' };
+                    }
+                }
+            }
+        }
+        catch {
+            // No match
+        }
+    }
+    return null;
+}
+/**
+ * Narrows a locator to one near a specific text/heading on the page.
+ * Uses Playwright's `.filter()` with a parent locator containing the near text.
+ */
+function narrowByNear(page, locator, nearText) {
+    // Find a section/container that contains the near text
+    const container = page.locator(`section:has-text("${escapeForSelector(nearText)}"), div:has-text("${escapeForSelector(nearText)}"), [role="region"]:has-text("${escapeForSelector(nearText)}")`).first();
+    return container.locator(locator);
+}
+async function isVisible(locator, timeout) {
+    try {
+        await locator.waitFor({ state: 'visible', timeout });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function escapeForSelector(text) {
+    return text.replace(/"/g, '\\"').replace(/\n/g, ' ');
+}
+//# sourceMappingURL=semantic-resolver.js.map

package/dist/server-capture-runtime.d.ts

@@ -0,0 +1,125 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+export type BillingPlanId = 'free' | 'maker' | 'team';
+export interface BillingPlanEntitlements {
+    creditsPerMonth: number;
+    maxProjects: number | null;
+    maxPresetsPerProject: number | null;
+    allowFullPageCapture: boolean;
+    allowElementCapture: boolean;
+    retentionDays: number;
+    watermarkScreenshots: boolean;
+    maxLanguages: number | null;
+    maxThemes: number | null;
+    apiAccess: boolean;
+    captureCompleteWebhook: boolean;
+    priorityQueue: boolean;
+    maxParallelCaptures: number;
+    teamMembers: boolean;
+    aiDailyCostLimitUsd: number;
+    apiRateLimitRpm: number;
+    maxDevLinks: number | null;
+    maxCompositions: number | null;
+    maxTeamMembersPerProject: number | null;
+}
+export interface BillingPlan {
+    id: BillingPlanId;
+    nameKey: BillingPlanId;
+    descriptionKey: 'forEvaluation' | 'forMakers' | 'forTeams';
+    monthlyPriceEur: number;
+    yearlyPriceEur: number;
+    highlighted?: boolean;
+    previewCurrent?: boolean;
+    highlights: string[];
+    entitlements: BillingPlanEntitlements;
+}
+export interface BillingAccount {
+    user_id: string;
+    email: string | null;
+    admin_override_plan_id: BillingPlanId | null;
+    stripe_customer_id: string | null;
+    stripe_subscription_id: string | null;
+    stripe_plan_id: BillingPlanId | null;
+    stripe_subscription_status: string | null;
+    stripe_current_period_start: string | null;
+    stripe_current_period_end: string | null;
+    allow_capture_overages: boolean;
+    capture_overage_limit_cents: number | null;
+    signup_bonus_credits: number;
+    created_at: string;
+}
+export declare class PlanLimitError extends Error {
+    status: number;
+    code: string;
+    constructor(message: string, status?: number, code?: string);
+}
+export declare const SCREENSHOT_CREDIT_COST = 1;
+export declare function getBillingPlan(planId: BillingPlanId): BillingPlan;
+export declare function coerceBillingPlanId(value: unknown): BillingPlanId | null;
+export declare function getBillingAccountForUser(supabase: SupabaseClient, userId: string): Promise<BillingAccount | null>;
+export declare function getProjectOwnerBillingContext(supabase: SupabaseClient, projectId: string): Promise<{
+    ownerUserId: string;
+    plan: BillingPlan;
+}>;
+export declare function shouldUseStripePlan(status: string | null | undefined): boolean;
+export declare function isYearlySubscription(account: BillingAccount | null): boolean;
+export declare function getStripeOveragePriceIdForPlan(planId: BillingPlanId): string | null;
+export declare function recordStripeMeterEvent(params: {
+    customerId: string;
+    value: number;
+    identifier: string;
+}): Promise<void>;
+export declare function getCaptureConfigLimitViolations(config: {
+    langs: string[];
+    themes: string[];
+    elements?: unknown[];
+}, entitlements: BillingPlanEntitlements): string[];
+export declare function ensureCaptureConfigAllowed(plan: BillingPlan, config: {
+    langs: string[];
+    themes: string[];
+    elements?: unknown[];
+}): void;
+export declare function getLockedResourceIds(supabase: SupabaseClient, ownerUserId: string, plan: BillingPlan): Promise<{
+    lockedProjectIds: Set<string>;
+    lockedPresetIdsByProject: Map<string, Set<string>>;
+}>;
+export declare function ensureResourceNotLocked(resourceId: string, lockedIds: Set<string>, resourceType?: 'project' | 'preset'): void;
+export declare function getRemainingOverageCredits(params: {
+    planId: BillingPlanId;
+    quota: number;
+    usedCredits: number;
+    overageLimitCents: number | null;
+}): number | null;
+export declare function getCaptureOverageState(params: {
+    planId: BillingPlanId;
+    quota: number;
+    usedCredits: number;
+    allowOverages: boolean;
+    overageLimitCents: number | null;
+    hasActiveSubscription: boolean;
+    hasOveragePrice: boolean;
+    isYearlySubscription: boolean;
+}): {
+    eligible: boolean;
+    enabled: boolean;
+    limitReached: boolean;
+    spendCents: number;
+    remainingBudgetCents: number | null;
+    remainingCredits: number | null;
+};
+export declare function getSignupBonusCredits(account: {
+    signup_bonus_credits?: number;
+    created_at?: string;
+} | null, billingPeriodStart: string): number;
+export declare function ensureMonthlyCreditsQuota(plan: BillingPlan, usedCredits: number, requestedCredits: number, allowOverage?: boolean, overageLimitCents?: number | null, bonusCredits?: number): void;
+export declare function getOwnerBillingUsage(supabase: SupabaseClient, ownerUserId: string, billingPeriodStartOverride?: string): Promise<{
+    billingPeriodStart: string;
+    credits: number;
+}>;
+export declare function getIncrementalOverageCount(params: {
+    quota: number;
+    usedBefore: number;
+    completedCount: number;
+}): number;
+export declare function cleanupExpiredCapturesForOwner(supabase: SupabaseClient, ownerUserId: string): Promise<{
+    deletedCaptures: number;
+}>;