effing-use 0.1.1 → 0.2.0

package/src/browser/evidence.ts

@@ -0,0 +1,186 @@
+import type { Page } from "playwright";
+import { getConsoleLogs, getNetworkLogs } from "./session.js";
+
+export type Effect = {
+  urlChanged: boolean;
+  urlBefore?: string;
+  urlAfter?: string;
+  domChanged: string[];
+  consoleErrors: string[];
+  dialog?: string;
+  networkFailures?: string[];
+  mustObserve: boolean;
+};
+
+const EFFECT_MAX_CHARS_DEFAULT = 800;
+
+function capEffect(effect: Effect, maxChars: number): Effect {
+  // Hard cap 800 chars total — truncate domChanged/consoleErrors/networkFailures
+  let total = JSON.stringify(effect).length;
+  if (total <= maxChars) return effect;
+  // Trim arrays until under cap
+  while (total > maxChars && effect.domChanged.length > 0) {
+    effect.domChanged.pop();
+    total = JSON.stringify(effect).length;
+  }
+  while (total > maxChars && effect.consoleErrors.length > 0) {
+    effect.consoleErrors.pop();
+    total = JSON.stringify(effect).length;
+  }
+  while (total > maxChars && (effect.networkFailures?.length ?? 0) > 0) {
+    effect.networkFailures!.pop();
+    total = JSON.stringify(effect).length;
+  }
+  return effect;
+}
+
+export async function collectEffect(
+  page: Page,
+  sessionId: string,
+  urlBefore: string,
+  domBeforeHash: string | null,
+  consoleBeforeLen: number,
+  networkBeforeLen: number,
+  maxChars = EFFECT_MAX_CHARS_DEFAULT,
+): Promise<Effect> {
+  const urlAfter = page.url();
+  const urlChanged = urlBefore !== urlAfter;
+
+  // domChanged: try to get diff via delta module if available, else simple heuristic
+  let domChanged: string[] = [];
+  try {
+    const currentDom = await page.evaluate(
+      () => document.body?.innerText?.slice(0, 200) ?? "",
+    );
+    if (domBeforeHash !== null && currentDom !== domBeforeHash) {
+      domChanged = [
+        currentDom.slice(0, 120).replace(/\s+/g, " ").trim(),
+      ].filter(Boolean);
+    }
+  } catch {
+    // ignore
+  }
+
+  const consoleLogs = getConsoleLogs(sessionId);
+  const newConsole = consoleLogs.slice(consoleBeforeLen);
+  const consoleErrors = newConsole
+    .filter((c) => c.type === "error")
+    .slice(-3)
+    .map((c) => c.text.slice(0, 200));
+
+  const networkLogs = getNetworkLogs(sessionId);
+  const newNetwork = networkLogs.slice(networkBeforeLen);
+  const networkFailures = newNetwork
+    .filter((r) => r.status >= 400)
+    .slice(-3)
+    .map((r) => `${r.method} ${r.url.slice(0, 80)} → ${r.status}`);
+
+  // dialog detection: check if page has dialog handler armed? For now undefined
+  const effect: Effect = {
+    urlChanged,
+    ...(urlChanged ? { urlBefore, urlAfter } : {}),
+    domChanged: domChanged.slice(0, 5),
+    consoleErrors: consoleErrors.slice(0, 3),
+    ...(networkFailures.length ? { networkFailures } : {}),
+    mustObserve: false,
+  };
+
+  return capEffect(effect, maxChars);
+}
+
+const EXPECT_MAX_PATTERN = 200;
+
+export function parseExpect(
+  expect: string,
+): { kind: string; pattern: string } | null {
+  const s = expect.trim();
+  let parsed: { kind: string; pattern: string } | null = null;
+  if (s.startsWith("url~")) parsed = { kind: "url", pattern: s.slice(4) };
+  else if (s.startsWith("text~")) parsed = { kind: "text", pattern: s.slice(5) };
+  else if (s.startsWith("visible=")) parsed = { kind: "visible", pattern: s.slice(8) };
+  else if (s.startsWith("gone=")) parsed = { kind: "gone", pattern: s.slice(5) };
+  else return null;
+  if (parsed.pattern.length > EXPECT_MAX_PATTERN) return null;
+  // Validate regex patterns early for url~/text~
+  if (parsed.kind === "url" || parsed.kind === "text") {
+    try {
+      new RegExp(parsed.pattern);
+    } catch {
+      return null;
+    }
+  }
+  return parsed;
+}
+
+export async function evaluateExpect(
+  page: Page,
+  expect: string,
+): Promise<{ ok: boolean; message?: string }> {
+  const parsed = parseExpect(expect);
+  if (!parsed) {
+    return {
+      ok: false,
+      message: `Bad expect syntax "${expect}". Use url~<regex> | text~<regex> | visible=<css> | gone=<css>`,
+    };
+  }
+  try {
+    switch (parsed.kind) {
+      case "url": {
+        const re = new RegExp(parsed.pattern);
+        const url = page.url();
+        if (re.test(url)) return { ok: true };
+        return {
+          ok: false,
+          message: `url "${url}" does not match /${parsed.pattern}/`,
+        };
+      }
+      case "text": {
+        const text = await page.innerText("body").catch(() => "");
+        const slice = text.slice(0, 50000);
+        const re = new RegExp(parsed.pattern);
+        if (re.test(slice)) return { ok: true };
+        return {
+          ok: false,
+          message: `page text does not match /${parsed.pattern}/`,
+        };
+      }
+      case "visible": {
+        const loc = page.locator(parsed.pattern);
+        const count = await loc.count().catch(() => 0);
+        if (count === 0)
+          return {
+            ok: false,
+            message: `selector "${parsed.pattern}" not found`,
+          };
+        const visible = await loc
+          .first()
+          .isVisible()
+          .catch(() => false);
+        if (visible) return { ok: true };
+        return {
+          ok: false,
+          message: `selector "${parsed.pattern}" not visible`,
+        };
+      }
+      case "gone": {
+        const loc = page.locator(parsed.pattern);
+        const count = await loc.count().catch(() => 0);
+        if (count === 0) return { ok: true };
+        const visible = await loc
+          .first()
+          .isVisible()
+          .catch(() => false);
+        if (!visible) return { ok: true };
+        return {
+          ok: false,
+          message: `selector "${parsed.pattern}" still visible`,
+        };
+      }
+      default:
+        return { ok: false, message: `Unknown expect kind "${parsed.kind}"` };
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, message: `expect evaluation failed: ${msg}` };
+  }
+}

package/src/browser/identity.ts

@@ -0,0 +1,95 @@
+export type Fingerprint = {
+  role: string;
+  accessibleName: string;
+  textHash: string;
+  box: { x: number; y: number; w: number; h: number };
+  pathHash: string;
+};
+
+function hashText(s: string): string {
+  return s.trim().replace(/\s+/g, " ").slice(0, 80);
+}
+
+function boxKey(box: { x: number; y: number; w: number; h: number }): string {
+  return `${Math.round(box.x)}:${Math.round(box.y)}:${Math.round(box.w)}:${Math.round(box.h)}`;
+}
+
+// Per-session registry: sessionId -> Map<ref, Fingerprint>
+const registry = new Map<string, Map<string, Fingerprint>>();
+
+export function registerFingerprints(
+  sessionId: string,
+  entries: Array<{ ref: string; fp: Fingerprint }>,
+): void {
+  let m = registry.get(sessionId);
+  if (!m) {
+    m = new Map();
+    registry.set(sessionId, m);
+  }
+  // Never recycle within session — but allow overwrite on fresh snapshot
+  for (const { ref, fp } of entries) m.set(ref, fp);
+}
+
+export function getFingerprint(
+  sessionId: string,
+  ref: string,
+): Fingerprint | undefined {
+  return registry.get(sessionId)?.get(ref);
+}
+
+export function clearRegistry(sessionId: string): void {
+  registry.delete(sessionId);
+}
+
+export function fingerprintEquals(a: Fingerprint, b: Fingerprint): boolean {
+  return (
+    a.role === b.role &&
+    a.accessibleName === b.accessibleName &&
+    a.textHash === b.textHash &&
+    boxKey(a.box) === boxKey(b.box) &&
+    a.pathHash === b.pathHash
+  );
+}
+
+// Loose match for rebind: role + name + textHash (ignore box/path)
+export function looseMatch(a: Fingerprint, b: Fingerprint): boolean {
+  return (
+    a.role === b.role &&
+    a.accessibleName === b.accessibleName &&
+    a.textHash === b.textHash
+  );
+}
+
+export function fuzzyMatch(a: Fingerprint, b: Fingerprint): boolean {
+  // fuzzy: role must match, and either name or textHash matches (case-insensitive contains)
+  if (a.role !== b.role) return false;
+  const an = a.accessibleName.toLowerCase();
+  const bn = b.accessibleName.toLowerCase();
+  const at = a.textHash.toLowerCase();
+  const bt = b.textHash.toLowerCase();
+  const nameMatch = an && bn && (an.includes(bn) || bn.includes(an));
+  const textMatch = at && bt && (at.includes(bt) || bt.includes(at));
+  return Boolean(nameMatch || textMatch);
+}
+
+// Build fingerprint from evaluated element data
+export function buildFingerprint(data: {
+  role: string;
+  accessibleName: string;
+  text: string;
+  box: { x: number; y: number; w: number; h: number };
+  pathHash: string;
+}): Fingerprint {
+  return {
+    role: data.role || "generic",
+    accessibleName: (data.accessibleName || "").trim().slice(0, 80),
+    textHash: hashText(data.text || ""),
+    box: {
+      x: Math.round(data.box.x),
+      y: Math.round(data.box.y),
+      w: Math.round(data.box.w),
+      h: Math.round(data.box.h),
+    },
+    pathHash: data.pathHash || "",
+  };
+}

package/src/browser/macro.ts

@@ -0,0 +1,102 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Config } from "../config.js";
+import type { RecordStep } from "./record.js";
+
+const IRREVERSIBLE = /submit|send|buy|pay|delete|remove|publish|post|confirm/i;
+
+export function isIrreversible(step: RecordStep): boolean {
+  const hay = [step.op, step.target ?? "", step.value ?? ""].join(" ");
+  return IRREVERSIBLE.test(hay);
+}
+
+function selectorFor(step: RecordStep): string {
+  if (step.resolvedSelector) return step.resolvedSelector;
+  if (step.target) return step.target;
+  return "";
+}
+
+function sanitizeMacroName(s: string): string {
+  return s.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) || "macro";
+}
+
+export async function compileMacro(
+  config: Config,
+  name: string,
+  steps: RecordStep[],
+): Promise<{ tsPath: string; mdPath: string; warnings: string[] }> {
+  const safe = sanitizeMacroName(name);
+  const dir = join(config.outputDir, "macros");
+  await mkdir(dir, { recursive: true });
+
+  const warnings: string[] = [];
+  const irreversibleSteps = steps.filter(isIrreversible);
+  if (irreversibleSteps.length > 0) {
+    warnings.push(
+      `${irreversibleSteps.length} step(s) require approval: ${irreversibleSteps.map((s) => s.seq).join(", ")}`,
+    );
+  }
+
+  // TS macro
+  const tsLines: string[] = [
+    `// macro: ${name} — generated by effing-use compile`,
+    `// steps: ${steps.length}, requiresApproval: ${irreversibleSteps.length > 0}`,
+    `import type { Page } from "playwright";`,
+    ``,
+    `export async function run(page: Page) {`,
+  ];
+  for (const s of steps) {
+    const sel = selectorFor(s);
+    const val = (s.value ?? "").slice(0, 500);
+    const flag = isIrreversible(s) ? " // requiresApproval" : "";
+    switch (s.op) {
+      case "click":
+        tsLines.push(`  await page.locator(${JSON.stringify(sel)}).click();${flag}`);
+        break;
+      case "fill":
+        tsLines.push(`  await page.locator(${JSON.stringify(sel)}).fill(${JSON.stringify(val)});${flag}`);
+        break;
+      case "press":
+        tsLines.push(
+          `  await page.keyboard.press(${JSON.stringify(val || s.target || "Enter")});${flag}`,
+        );
+        break;
+      case "goto":
+      case "open":
+        tsLines.push(`  await page.goto(${JSON.stringify(val || sel)});${flag}`);
+        break;
+      default:
+        tsLines.push(`  // ${JSON.stringify(s.op)} ${JSON.stringify(sel)} ${JSON.stringify(val)}${flag}`);
+        break;
+    }
+  }
+  tsLines.push(`}`);
+  tsLines.push(``);
+
+  const tsPath = join(dir, `${safe}.ts`);
+  await writeFile(tsPath, tsLines.join("\n"), "utf-8");
+
+  // SKILL.md
+  const mdLines: string[] = [
+    `# Skill: ${safe}`,
+    ``,
+    `When to use: replay this ${steps.length}-step flow via \`browser_act action=replay value=${safe}\`.`,
+    ``,
+    `## Steps`,
+    ...steps.map((s) =>
+      `${s.seq + 1}. ${s.op} ${s.target ?? ""} ${s.value ?? ""}${isIrreversible(s) ? " (requires approval)" : ""}`.trim(),
+    ),
+    ``,
+    `## Verification`,
+    irreversibleSteps.length > 0
+      ? `This macro contains irreversible steps — replay will pause with E_APPROVAL_REQUIRED until approve:true.`
+      : `No approval-gated steps.`,
+    ``,
+    `## Inputs`,
+    `None in v1 — values are baked in. Parameterize in a future version if needed.`,
+  ];
+  const mdPath = join(dir, `${safe}.md`);
+  await writeFile(mdPath, mdLines.join("\n"), "utf-8");
+
+  return { tsPath, mdPath, warnings };
+}

package/src/browser/record.ts

@@ -0,0 +1,117 @@
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Config } from "../config.js";
+import type { Fingerprint } from "./identity.js";
+
+export type RecordStep = {
+  seq: number;
+  op: string;
+  target?: string;
+  value?: string;
+  targetFingerprint?: Fingerprint;
+  resolvedSelector?: string;
+  expect?: string;
+  valueRedacted?: boolean;
+};
+
+type Recording = {
+  name: string;
+  createdAt: string;
+  steps: RecordStep[];
+};
+
+const activeRecordings = new Map<
+  string,
+  { name: string; steps: RecordStep[] }
+>();
+
+const SECRET_HINT = /password|otp|secret|token|pin|ssn/i;
+
+function isSecretField(
+  fp?: Fingerprint,
+  target?: string,
+  value?: string,
+): boolean {
+  const hay = [fp?.accessibleName ?? "", fp?.role ?? "", target ?? ""].join(
+    " ",
+  );
+  if (SECRET_HINT.test(hay)) return true;
+  // also check input type=password via target string
+  if (/type\s*=\s*password/i.test(target ?? "")) return true;
+  return false;
+}
+
+export function isRecording(sessionId: string): boolean {
+  return activeRecordings.has(sessionId);
+}
+
+export function startRecording(sessionId: string, name: string): void {
+  activeRecordings.set(sessionId, { name, steps: [] });
+}
+
+export function stopRecording(
+  sessionId: string,
+): { name: string; steps: RecordStep[] } | null {
+  const r = activeRecordings.get(sessionId);
+  if (!r) return null;
+  activeRecordings.delete(sessionId);
+  return r;
+}
+
+export function captureStep(
+  sessionId: string,
+  step: Omit<RecordStep, "seq">,
+  config: Config,
+): void {
+  const rec = activeRecordings.get(sessionId);
+  if (!rec) return;
+  const seq = rec.steps.length;
+  let value = step.value;
+  let valueRedacted = false;
+  if (
+    config.recordRedact &&
+    value &&
+    isSecretField(step.targetFingerprint, step.target, value)
+  ) {
+    value = "«redacted»";
+    valueRedacted = true;
+  }
+  rec.steps.push({
+    seq,
+    ...step,
+    value,
+    ...(valueRedacted ? { valueRedacted: true } : {}),
+  });
+}
+
+function sanitizeName(s: string): string {
+  return s.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) || "recording";
+}
+
+export async function saveRecording(
+  config: Config,
+  name: string,
+  steps: RecordStep[],
+): Promise<string> {
+  const safe = sanitizeName(name);
+  const dir = join(config.outputDir, "recordings");
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, `${safe}.json`);
+  const rec: Recording = { name: safe, createdAt: new Date().toISOString(), steps };
+  await writeFile(path, JSON.stringify(rec, null, 2), "utf-8");
+  return path;
+}
+
+export async function loadRecording(
+  config: Config,
+  name: string,
+): Promise<Recording> {
+  const safe = sanitizeName(name);
+  const path = join(config.outputDir, "recordings", `${safe}.json`);
+  const raw = await readFile(path, "utf-8");
+  return JSON.parse(raw) as Recording;
+}
+
+export function getActiveName(sessionId: string): string | null {
+  return activeRecordings.get(sessionId)?.name ?? null;
+}

package/src/browser/refs.ts

@@ -1,4 +1,10 @@
 import type { Page, Locator } from "playwright";
+import {
+  getFingerprint,
+  looseMatch,
+  fuzzyMatch,
+  type Fingerprint,
+} from "./identity.js";
 
 export class EngineError extends Error {
   code: string;
@@ -30,17 +36,47 @@ export function resolveRef(page: Page, ref: string): Locator {
 export async function resolveLocator(
   page: Page,
   target: string,
+  sessionId?: string,
 ): Promise<Locator> {
   const t = target.trim();
-  // 0. eNN ref
+  // 0. eNN ref — with identity validation when sessionId is known
   if (/^e\d+$/i.test(t)) {
     const loc = resolveRef(page, t);
-    if ((await loc.count()) > 0) return loc;
-    throw new EngineError(
-      "E_NOT_FOUND",
-      `No element matches "${t}".`,
-      "Call browser_observe kind=snapshot first to refresh refs, then use a fresh e-ref.",
-    );
+    if ((await loc.count()) === 0) {
+      throw new EngineError(
+        "E_NOT_FOUND",
+        `No element matches "${t}".`,
+        "Call browser_observe kind=snapshot first to refresh refs, then use a fresh e-ref.",
+      );
+    }
+    if (sessionId) {
+      const expected = getFingerprint(sessionId, t);
+      if (expected) {
+        const actual = await fingerprintAt(page, loc).catch(() => null);
+        if (actual) {
+          const exact =
+            expected.role === actual.role &&
+            expected.accessibleName === actual.accessibleName &&
+            expected.textHash === actual.textHash;
+          if (!exact) {
+            // Try rebind: search tree for loose/fuzzy match
+            const rebound = await findRebound(page, expected);
+            if (rebound) {
+              // Return rebound locator; caller can check rebound flag via session
+              (page as unknown as Record<string, unknown>).__rebound = true;
+              return rebound;
+            }
+            throw new EngineError(
+              "E_STALE",
+              `Ref ${t} is stale — element changed.`,
+              "Call browser_observe kind=snapshot to refresh refs.",
+              { expected, actual },
+            );
+          }
+        }
+      }
+    }
+    return loc;
   }
   // 1. role= selector passes through
   if (t.startsWith("role=")) return page.locator(t);
@@ -73,3 +109,118 @@ export async function resolveLocator(
     "Call browser_observe kind=snapshot first, then use an e-ref, role= selector, or CSS selector.",
   );
 }
+
+async function fingerprintAt(page: Page, loc: Locator): Promise<Fingerprint> {
+  const box = await loc.boundingBox().catch(() => null);
+  const data = await loc
+    .evaluate((el) => {
+      const text = (el.textContent ?? "").trim().slice(0, 80);
+      const aria = el.getAttribute("aria-label") ?? "";
+      const role = el.getAttribute("role") ?? el.tagName.toLowerCase();
+      // simple path hash: tag chain
+      let cur: Element | null = el;
+      const parts: string[] = [];
+      while (cur && parts.length < 6) {
+        parts.push(cur.tagName.toLowerCase());
+        cur = cur.parentElement;
+      }
+      return { role, accessibleName: aria, text, pathHash: parts.join(">") };
+    })
+    .catch(() => ({
+      role: "generic",
+      accessibleName: "",
+      text: "",
+      pathHash: "",
+    }));
+  return {
+    role: data.role || "generic",
+    accessibleName: (data.accessibleName || "").trim().slice(0, 80),
+    textHash: (data.text || "").trim().replace(/\s+/g, " ").slice(0, 80),
+    box: {
+      x: Math.round(box?.x ?? 0),
+      y: Math.round(box?.y ?? 0),
+      w: Math.round(box?.width ?? 0),
+      h: Math.round(box?.height ?? 0),
+    },
+    pathHash: data.pathHash || "",
+  };
+}
+
+async function findRebound(
+  page: Page,
+  expected: Fingerprint,
+): Promise<Locator | null> {
+  // Scan interactive elements for loose/fuzzy match
+  const els = await page
+    .evaluate(() => {
+      const nodes = [
+        ...document.querySelectorAll(
+          "button, a, input, select, textarea, [role=button], [tabindex]",
+        ),
+      ];
+      return nodes.slice(0, 200).map((el, i) => {
+        const text = (el.textContent ?? "")
+          .trim()
+          .replace(/\s+/g, " ")
+          .slice(0, 80);
+        const aria = el.getAttribute("aria-label") ?? "";
+        const role = el.getAttribute("role") ?? el.tagName.toLowerCase();
+        let cur: Element | null = el;
+        const parts: string[] = [];
+        while (cur && parts.length < 6) {
+          parts.push(cur.tagName.toLowerCase());
+          cur = cur.parentElement;
+        }
+        return {
+          i,
+          role,
+          accessibleName: aria,
+          textHash: text,
+          pathHash: parts.join(">"),
+        };
+      });
+    })
+    .catch(
+      () =>
+        [] as Array<{
+          i: number;
+          role: string;
+          accessibleName: string;
+          textHash: string;
+          pathHash: string;
+        }>,
+    );
+  for (const e of els) {
+    const cand: Fingerprint = {
+      role: e.role,
+      accessibleName: e.accessibleName,
+      textHash: e.textHash,
+      box: { x: 0, y: 0, w: 0, h: 0 },
+      pathHash: e.pathHash,
+    };
+    if (looseMatch(expected, cand)) {
+      return page
+        .locator(
+          "button, a, input, select, textarea, [role=button], [tabindex]",
+        )
+        .nth(e.i);
+    }
+  }
+  for (const e of els) {
+    const cand: Fingerprint = {
+      role: e.role,
+      accessibleName: e.accessibleName,
+      textHash: e.textHash,
+      box: { x: 0, y: 0, w: 0, h: 0 },
+      pathHash: e.pathHash,
+    };
+    if (fuzzyMatch(expected, cand)) {
+      return page
+        .locator(
+          "button, a, input, select, textarea, [role=button], [tabindex]",
+        )
+        .nth(e.i);
+    }
+  }
+  return null;
+}