playwright-intelligence-engine 0.0.0-stage → 2.0.0

package/src/memory/stability-ledger.ts

@@ -0,0 +1,243 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export interface SelectorHistoryRecord {
+  selector: string;
+  successes: number;
+  failures: number;
+  semanticVerifications: number;
+  repairsAccepted: number;
+  falseRepairIncidents: number;
+  lastSuccess?: number | undefined;
+  lastFailure?: number | undefined;
+  failureCategories: string[];
+  reliabilityScore: number;
+  historicalExecutionReliability: number;
+}
+
+export interface StabilityLedgerData {
+  version: number;
+  updatedAt: number;
+  scope: {
+    projectRoot: string;
+    repositoryName: string;
+  };
+  selectors: Record<string, SelectorHistoryRecord>;
+}
+
+export type RepairFeedbackOutcome = 'accepted' | 'rejected';
+
+/** Applies bounded time decay toward the neutral prior without mutating history. */
+export function effectiveReliabilityScore(
+  record: SelectorHistoryRecord,
+  now = Date.now(),
+  halfLifeMs = 30 * 24 * 60 * 60 * 1000,
+): number {
+  if (record.falseRepairIncidents > 0) return 0.1;
+  const latestEvidence = Math.max(record.lastSuccess ?? 0, record.lastFailure ?? 0);
+  if (latestEvidence <= 0 || halfLifeMs <= 0) return record.reliabilityScore;
+  const ageMs = Math.max(0, now - latestEvidence);
+  const decay = Math.exp(-ageMs / halfLifeMs);
+  const score = 0.8 + (record.reliabilityScore - 0.8) * decay;
+  return Number(Math.max(0, Math.min(1, score)).toFixed(3));
+}
+
+export class StabilityLedger {
+  private readonly ledgerPath: string;
+  private data: StabilityLedgerData | null = null;
+
+  constructor(baseDir = '.') {
+    this.ledgerPath = path.resolve(baseDir, '.pw-intelligence', 'stability-ledger.json');
+  }
+
+  public async init(): Promise<void> {
+    await fs.mkdir(path.dirname(this.ledgerPath), { recursive: true });
+    try {
+      const raw = await fs.readFile(this.ledgerPath, 'utf8');
+      const parsed = JSON.parse(raw) as Partial<StabilityLedgerData>;
+      this.data = {
+        version: parsed.version ?? 3,
+        updatedAt: parsed.updatedAt ?? Date.now(),
+        scope: parsed.scope ?? {
+          projectRoot: path.resolve(path.dirname(this.ledgerPath), '..'),
+          repositoryName: path.basename(path.resolve(path.dirname(this.ledgerPath), '..')),
+        },
+        selectors: parsed.selectors ?? {},
+      };
+      if (!parsed.scope || parsed.version !== 3) await this.save();
+    } catch {
+      this.data = {
+        version: 3,
+        updatedAt: Date.now(),
+        scope: {
+          projectRoot: path.resolve(path.dirname(this.ledgerPath), '..'),
+          repositoryName: path.basename(path.resolve(path.dirname(this.ledgerPath), '..')),
+        },
+        selectors: {},
+      };
+      await this.save();
+    }
+  }
+
+  public getScore(selector: string): number {
+    if (!this.data) return 0.8; // Default baseline score
+    const record = this.data.selectors[selector];
+    if (!record) return 0.8;
+    return record.reliabilityScore;
+  }
+
+  public getEffectiveScore(selector: string, now = Date.now(), halfLifeMs?: number): number {
+    if (!this.data) return 0.8;
+    const record = this.data.selectors[selector];
+    return record ? effectiveReliabilityScore(record, now, halfLifeMs) : 0.8;
+  }
+
+  public async recordSuccess(selector: string): Promise<void> {
+    await this.ensureLoaded();
+    const existing = this.data!.selectors[selector] ?? {
+      selector,
+      successes: 0,
+      failures: 0,
+      semanticVerifications: 1,
+      repairsAccepted: 0,
+      falseRepairIncidents: 0,
+      failureCategories: [],
+      reliabilityScore: 0.8,
+      historicalExecutionReliability: 0.8,
+    };
+
+    existing.successes += 1;
+    existing.lastSuccess = Date.now();
+    existing.reliabilityScore = this.computeScore(existing);
+    existing.historicalExecutionReliability = existing.reliabilityScore;
+    this.data!.selectors[selector] = existing;
+    await this.save();
+  }
+
+  public async recordFailure(selector: string, category: string): Promise<void> {
+    await this.ensureLoaded();
+    const existing = this.data!.selectors[selector] ?? {
+      selector,
+      successes: 0,
+      failures: 0,
+      semanticVerifications: 0,
+      repairsAccepted: 0,
+      falseRepairIncidents: 0,
+      failureCategories: [],
+      reliabilityScore: 0.8,
+      historicalExecutionReliability: 0.8,
+    };
+
+    existing.failures += 1;
+    existing.lastFailure = Date.now();
+    if (!existing.failureCategories.includes(category)) {
+      existing.failureCategories.push(category);
+    }
+    existing.reliabilityScore = this.computeScore(existing);
+    existing.historicalExecutionReliability = existing.reliabilityScore;
+    this.data!.selectors[selector] = existing;
+    await this.save();
+  }
+
+  public async recordSemanticVerification(selector: string): Promise<void> {
+    await this.ensureLoaded();
+    const existing = this.data!.selectors[selector] ?? this.createRecord(selector);
+    existing.semanticVerifications += 1;
+    // A semantic verification is produced only after the isolated execution
+    // and intent gates pass. Count it as one successful observation so future
+    // candidate ranking can learn from verified repairs, while keeping the
+    // separate repairsAccepted field as operator-approval metadata.
+    existing.successes += 1;
+    existing.lastSuccess = Date.now();
+    existing.reliabilityScore = this.computeScore(existing);
+    existing.historicalExecutionReliability = existing.reliabilityScore;
+    this.data!.selectors[selector] = existing;
+    await this.save();
+  }
+
+  public async recordRepairAccepted(selector: string): Promise<void> {
+    await this.ensureLoaded();
+    const existing = this.data!.selectors[selector] ?? this.createRecord(selector);
+    existing.repairsAccepted += 1;
+    this.data!.selectors[selector] = existing;
+    await this.save();
+  }
+
+  public getSnapshot(): StabilityLedgerData {
+    if (!this.data) {
+      return {
+        version: 3,
+        updatedAt: 0,
+        scope: {
+          projectRoot: path.resolve(path.dirname(this.ledgerPath), '..'),
+          repositoryName: path.basename(path.resolve(path.dirname(this.ledgerPath), '..')),
+        },
+        selectors: {},
+      };
+    }
+    return JSON.parse(JSON.stringify(this.data)) as StabilityLedgerData;
+  }
+
+  public async recordFalseRepairIncident(selector: string): Promise<void> {
+    await this.ensureLoaded();
+    const existing = this.data!.selectors[selector] ?? {
+      selector,
+      successes: 0,
+      failures: 1,
+      semanticVerifications: 0,
+      repairsAccepted: 0,
+      falseRepairIncidents: 0,
+      failureCategories: ['FALSE_REPAIR'],
+      reliabilityScore: 0.2,
+      historicalExecutionReliability: 0.2,
+    };
+
+    existing.falseRepairIncidents += 1;
+    existing.reliabilityScore = this.computeScore(existing);
+    existing.historicalExecutionReliability = existing.reliabilityScore;
+    this.data!.selectors[selector] = existing;
+    await this.save();
+  }
+
+  /** Records operator review feedback without erasing the underlying history. */
+  public async recordRepairFeedback(selector: string, outcome: RepairFeedbackOutcome): Promise<void> {
+    if (outcome === 'accepted') await this.recordRepairAccepted(selector);
+    else await this.recordFalseRepairIncident(selector);
+  }
+
+  private computeScore(record: { successes: number; failures: number; falseRepairIncidents: number }): number {
+    // If any false repair incident occurred, severely penalize (fail-safe against confirmation bias)
+    if (record.falseRepairIncidents > 0) {
+      return 0.1;
+    }
+    const total = record.successes + record.failures * 2; // Penalize failures with double weight
+    if (total === 0) return 0.8;
+    const score = record.successes / total;
+    return parseFloat(score.toFixed(3));
+  }
+
+  private createRecord(selector: string): SelectorHistoryRecord {
+    return {
+      selector,
+      successes: 0,
+      failures: 0,
+      semanticVerifications: 0,
+      repairsAccepted: 0,
+      falseRepairIncidents: 0,
+      failureCategories: [],
+      reliabilityScore: 0.8,
+      historicalExecutionReliability: 0.8,
+    };
+  }
+
+  private async ensureLoaded(): Promise<void> {
+    if (!this.data) await this.init();
+  }
+
+  private async save(): Promise<void> {
+    if (!this.data) return;
+    this.data.updatedAt = Date.now();
+    await fs.writeFile(this.ledgerPath, JSON.stringify(this.data, null, 2), 'utf8');
+  }
+}
+

package/src/perception/app-model.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+export const AppElementSchema = z.object({
+  tag: z.string().min(1),
+  role: z.string().optional(),
+  accessibleName: z.string().optional(),
+  label: z.string().optional(),
+  testId: z.string().optional(),
+  placeholder: z.string().optional(),
+  type: z.string().optional(),
+  frameSelector: z.string().optional(),
+  count: z.number().int().min(1).default(1),
+  visible: z.boolean().default(true),
+});
+export type AppElement = z.infer<typeof AppElementSchema>;
+
+export const AppRouteSchema = z.object({
+  route: z.string().min(1),
+  title: z.string().optional(),
+  elements: z.array(AppElementSchema).default([]),
+});
+export type AppRoute = z.infer<typeof AppRouteSchema>;
+
+export const AppModelSchema = z.object({
+  version: z.literal('1').default('1'),
+  baseUrl: z.string().min(1),
+  fingerprint: z.string().min(1),
+  capturedAt: z.string(),
+  routes: z.array(AppRouteSchema).default([]),
+});
+export type AppModel = z.infer<typeof AppModelSchema>;
+

package/src/perception/crawler.ts

@@ -0,0 +1,263 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { AppModel, AppModelSchema, AppRoute, AppElement } from './app-model.js';
+
+export interface CrawlerOptions {
+  baseUrl: string;
+  fingerprint?: string;
+  maxRoutes?: number;
+  maxDepth?: number;
+  storageStatePath?: string;
+  cacheDir?: string;
+  browser?: any;
+  page?: any;
+}
+
+export function computeCacheKey(baseUrl: string, fingerprint?: string): string {
+  const normalized = baseUrl.replace(/\/+$/, '').toLowerCase();
+  const raw = `${normalized}::${fingerprint ?? 'default'}`;
+  return crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16);
+}
+
+export async function getCachedAppModel(cacheDir: string, baseUrl: string, fingerprint?: string): Promise<AppModel | null> {
+  try {
+    const key = computeCacheKey(baseUrl, fingerprint);
+    const filePath = path.join(cacheDir, `app-model-${key}.json`);
+    const content = await fs.readFile(filePath, 'utf8');
+    const parsed = JSON.parse(content);
+    const validated = AppModelSchema.safeParse(parsed);
+    if (validated.success) {
+      return validated.data;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveCachedAppModel(cacheDir: string, model: AppModel): Promise<void> {
+  try {
+    await fs.mkdir(cacheDir, { recursive: true });
+    const key = computeCacheKey(model.baseUrl, model.fingerprint);
+    const filePath = path.join(cacheDir, `app-model-${key}.json`);
+    await fs.writeFile(filePath, JSON.stringify(model, null, 2), 'utf8');
+  } catch {
+    // Non-fatal if cache cannot be written
+  }
+}
+
+async function extractFrameSelector(frame: any): Promise<string> {
+  try {
+    if (typeof frame.name === 'function' && frame.name()) {
+      return `iframe[name="${frame.name()}"]`;
+    }
+    if (typeof frame.frameElement === 'function') {
+      const handle = await frame.frameElement();
+      if (handle) {
+        const selector = await handle.evaluate((el: any) => {
+          const title = el.getAttribute('title');
+          if (title) return `iframe[title="${title}"]`;
+          const name = el.getAttribute('name');
+          if (name) return `iframe[name="${name}"]`;
+          const id = el.getAttribute('id');
+          if (id) return `iframe#${id}`;
+          const src = el.getAttribute('src');
+          if (src) return `iframe[src="${src}"]`;
+          return 'iframe';
+        });
+        if (selector) return selector;
+      }
+    }
+  } catch {
+    // Fallback if frame element lookup fails
+  }
+  return 'iframe';
+}
+
+async function collectFrameElements(frameHandle: any, frameSelector?: string): Promise<AppElement[]> {
+  try {
+    const raw = await frameHandle.$$eval('button, a, input, select, textarea, [role="button"], [role="textbox"], [role="status"], [role="list"], [role="listitem"], ul, ol, heading, h1, h2, h3', (nodes: any[]) => {
+      return nodes.map((el) => {
+        const tag = el.tagName.toLowerCase();
+        const type = el.getAttribute('type') || undefined;
+        let role = el.getAttribute('role');
+        if (!role) {
+          if (tag === 'button') role = 'button';
+          else if (tag === 'input') {
+            if (type === 'checkbox') role = 'checkbox';
+            else if (type === 'radio') role = 'radio';
+            else if (type === 'submit' || type === 'button') role = 'button';
+            else role = 'textbox';
+          } else if (tag === 'textarea') role = 'textbox';
+          else if (tag === 'select') role = 'combobox';
+          else if (/^h[1-6]$/.test(tag)) role = 'heading';
+          else if (tag === 'ul' || tag === 'ol') role = 'list';
+        }
+        const placeholder = el.getAttribute('placeholder') || undefined;
+        const accessibleName = el.getAttribute('aria-label') || el.innerText?.trim() || placeholder || undefined;
+        const label = el.getAttribute('aria-label') || el.getAttribute('name') || undefined;
+        const testId = el.getAttribute('data-testid') || el.getAttribute('data-test') || undefined;
+        const visible = Boolean(el.offsetWidth || el.offsetHeight || el.getClientRects().length);
+        return { tag, role, accessibleName, label, testId, placeholder, type, visible };
+      });
+    });
+
+    const elements: AppElement[] = raw.map((item: any) => ({
+      tag: item.tag,
+      role: item.role,
+      accessibleName: item.accessibleName,
+      label: item.label,
+      testId: item.testId,
+      placeholder: item.placeholder,
+      type: item.type,
+      frameSelector,
+      count: 1,
+      visible: item.visible,
+    }));
+    return elements;
+  } catch {
+    if (frameSelector) {
+      return [{
+        tag: 'iframe',
+        role: 'cross-origin-unavailable',
+        frameSelector,
+        count: 1,
+        visible: true,
+      }];
+    }
+    return [];
+  }
+}
+
+export class AppCrawler {
+  public static async crawl(options: CrawlerOptions): Promise<AppModel> {
+    const cacheDir = options.cacheDir ?? path.join(process.cwd(), '.pie', 'cache');
+    const fingerprint = options.fingerprint ?? 'default';
+
+    // 1. Check cache
+    const cached = await getCachedAppModel(cacheDir, options.baseUrl, fingerprint);
+    if (cached) {
+      return cached;
+    }
+
+    const maxRoutes = options.maxRoutes ?? 20;
+    const maxDepth = options.maxDepth ?? 2;
+    const baseHost = new URL(options.baseUrl).host;
+
+    const routes: AppRoute[] = [];
+    let browserToClose: any = null;
+
+    try {
+      let page = options.page;
+      if (!page) {
+        if (options.browser) {
+          const context = await options.browser.newContext({
+            storageState: options.storageStatePath,
+          });
+          page = await context.newPage();
+        } else {
+          // Attempt dynamic import of playwright
+          try {
+            const { chromium } = await import('@playwright/test');
+            browserToClose = await chromium.launch({ headless: true });
+            const context = await browserToClose.newContext({
+              storageState: options.storageStatePath,
+            });
+            page = await context.newPage();
+          } catch {
+            // If browser cannot be launched, return minimal bounded model
+            const fallbackModel: AppModel = {
+              version: '1',
+              baseUrl: options.baseUrl,
+              fingerprint,
+              capturedAt: new Date().toISOString(),
+              routes: [{ route: '/', elements: [] }],
+            };
+            return fallbackModel;
+          }
+        }
+      }
+
+      const queue: Array<{ url: string; depth: number }> = [{ url: options.baseUrl, depth: 0 }];
+      const visited = new Set<string>();
+
+      while (queue.length > 0 && routes.length < maxRoutes) {
+        const item = queue.shift()!;
+        if (visited.has(item.url)) continue;
+        visited.add(item.url);
+
+        try {
+          await page.goto(item.url, { waitUntil: 'domcontentloaded', timeout: 15_000 });
+        } catch {
+          continue;
+        }
+
+        const elements: AppElement[] = [];
+
+        // Main frame elements
+        const mainElements = await collectFrameElements(page, undefined);
+        elements.push(...mainElements);
+
+        // Child frame elements
+        if (typeof page.frames === 'function') {
+          const childFrames = page.frames().slice(1);
+          for (const childFrame of childFrames) {
+            const frameSelector = await extractFrameSelector(childFrame);
+            const childElements = await collectFrameElements(childFrame, frameSelector);
+            elements.push(...childElements);
+          }
+        }
+
+        const urlObj = new URL(item.url);
+        routes.push({
+          route: urlObj.pathname || '/',
+          title: typeof page.title === 'function' ? await page.title().catch(() => undefined) : undefined,
+          elements,
+        });
+
+        // Bounded exploration: collect links without clicking destructive elements
+        if (item.depth < maxDepth && routes.length < maxRoutes) {
+          try {
+            const hrefs: string[] = await page.$$eval('a[href]', (anchors: any[]) =>
+              anchors.map((a) => a.getAttribute('href')).filter(Boolean),
+            );
+            for (const href of hrefs) {
+              try {
+                const resolved = new URL(href, item.url);
+                // Allowlisted host only, no logout/delete/submit paths
+                if (resolved.host === baseHost && !/logout|signout|delete|destroy/i.test(resolved.pathname)) {
+                  const cleaned = resolved.origin + resolved.pathname;
+                  if (!visited.has(cleaned) && !queue.some((q) => q.url === cleaned)) {
+                    queue.push({ url: cleaned, depth: item.depth + 1 });
+                  }
+                }
+              } catch {
+                // Ignore invalid URLs
+              }
+            }
+          } catch {
+            // Ignore link evaluation failure
+          }
+        }
+      }
+    } catch {
+      // Bounded fallback
+    } finally {
+      if (browserToClose) {
+        await browserToClose.close().catch(() => {});
+      }
+    }
+
+    const model: AppModel = {
+      version: '1',
+      baseUrl: options.baseUrl,
+      fingerprint,
+      capturedAt: new Date().toISOString(),
+      routes: routes.length > 0 ? routes : [{ route: '/', elements: [] }],
+    };
+
+    await saveCachedAppModel(cacheDir, model);
+    return model;
+  }
+}

package/src/perception/index.ts

@@ -0,0 +1,3 @@
+export * from './app-model.js';
+export * from './crawler.js';
+