@monoes/monobrowse 1.0.1 → 1.0.3

package/src/__tests__/ref-cache.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, readFile, rm, stat } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+// We need to mock process.cwd() before importing ref-cache so CACHE_DIR
+// resolves to our temp directory.
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'monobrowse-test-'));
+  vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+// Dynamic import so each test picks up the mocked cwd.
+// We must bust the module cache between tests.
+async function importRefCache() {
+  // Vitest module cache means re-import returns the same module.
+  // Since CACHE_DIR is set at module-load time, we need resetModules.
+  vi.resetModules();
+  return import('../browser/ref-cache.js');
+}
+
+function makeRefs(count = 2): Map<string, { ref: string; role: string; name: string; nodeId: number }> {
+  const map = new Map();
+  for (let i = 1; i <= count; i++) {
+    map.set(`ref${i}`, { ref: `ref${i}`, role: 'button', name: `Button ${i}`, nodeId: i });
+  }
+  return map;
+}
+
+describe('ref-cache', () => {
+  it('round-trip: save then load returns equivalent data', async () => {
+    const mod = await importRefCache();
+    const refs = makeRefs(2);
+
+    await mod.saveRefCache('target-1', 'https://example.com', refs as any);
+    const loaded = await mod.loadRefCache('target-1');
+
+    expect(loaded).not.toBeNull();
+    expect(loaded!.url).toBe('https://example.com');
+    expect(loaded!.refs.size).toBe(2);
+    expect(loaded!.refs.get('ref1')!.role).toBe('button');
+    expect(loaded!.refs.get('ref2')!.name).toBe('Button 2');
+    expect(typeof loaded!.savedAt).toBe('number');
+    expect(typeof loaded!.ageMs).toBe('number');
+  });
+
+  it('targetId mismatch returns null', async () => {
+    const mod = await importRefCache();
+    const refs = makeRefs(1);
+
+    await mod.saveRefCache('target-A', 'https://a.com', refs as any);
+    const loaded = await mod.loadRefCache('target-B');
+
+    expect(loaded).toBeNull();
+  });
+
+  it('corrupt JSON file returns null', async () => {
+    const mod = await importRefCache();
+    // First save a valid cache to create the directory structure
+    await mod.saveRefCache('t', 'https://x.com', makeRefs(1) as any);
+
+    // Now overwrite the file with invalid JSON
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    const { writeFile: wf } = await import('fs/promises');
+    await wf(cacheFile, '{{{not valid json!!!');
+
+    const loaded = await mod.loadRefCache('t');
+    expect(loaded).toBeNull();
+  });
+
+  it('clearRefCache removes the cache file', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    // Verify file exists
+    const before = await stat(cacheFile).catch(() => null);
+    expect(before).not.toBeNull();
+
+    await mod.clearRefCache();
+
+    const after = await stat(cacheFile).catch(() => null);
+    expect(after).toBeNull();
+  });
+
+  it('load after clear returns null', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+    await mod.clearRefCache();
+
+    const loaded = await mod.loadRefCache('t1');
+    expect(loaded).toBeNull();
+  });
+
+  it('freshly saved cache is not stale', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+
+    const loaded = await mod.loadRefCache('t1');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.stale).toBe(false);
+    expect(loaded!.ageMs).toBeLessThan(mod.REF_CACHE_STALE_MS);
+  });
+
+  it('cache older than REF_CACHE_STALE_MS is flagged stale', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+
+    // Manually backdate the savedAt timestamp
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    const raw = JSON.parse(await readFile(cacheFile, 'utf8'));
+    raw.savedAt = Date.now() - mod.REF_CACHE_STALE_MS - 5000;
+    const { writeFile: wf } = await import('fs/promises');
+    await wf(cacheFile, JSON.stringify(raw));
+
+    const loaded = await mod.loadRefCache('t1');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.stale).toBe(true);
+    expect(loaded!.ageMs).toBeGreaterThan(mod.REF_CACHE_STALE_MS);
+  });
+
+  it('loading with no cache file returns null (no crash)', async () => {
+    const mod = await importRefCache();
+    const loaded = await mod.loadRefCache('nonexistent');
+    expect(loaded).toBeNull();
+  });
+});

package/src/browser/action-builder/analyzer.ts

@@ -1,15 +1,14 @@
 // src/browser/action-builder/analyzer.ts
-import Anthropic from '@anthropic-ai/sdk';
+import { spawn } from 'child_process';
 import type { ActionDef } from './types.js';
-const MODEL_DEFAULTS = { sonnet: 'claude-sonnet-4-6' } as const;
 
 export interface AnalyzerPage {
   evaluate<T>(expression: string): Promise<T>;
   url(): Promise<string>;
 }
 
+// monolean: no options needed — routes through claude --print, no API key required
 export interface AnalyzerOptions {
-  apiKey?: string;
   model?: string;
 }
 
@@ -42,6 +41,40 @@ JSON.stringify(
     }))
 )`;
 
+function claudeCliCall(prompt: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      'claude',
+      ['--print', '--model', 'haiku', '--strict-mcp-config', '--no-session-persistence', '--', prompt],
+      { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true },
+    );
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try { child.kill('SIGTERM'); } catch { /* ignore */ }
+      reject(new Error('claude --print timed out after 60s'));
+    }, 60_000);
+    child.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
+    child.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code === 0) resolve(stdout.trim());
+      else reject(new Error(stderr.trim() || `claude exited with code ${code}`));
+    });
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(new Error(`claude CLI not found — is Claude Code installed? (${(err as NodeJS.ErrnoException).code})`));
+    });
+  });
+}
+
 const SYSTEM_PROMPT = `You are an expert browser automation engineer. Given a webpage's interactive elements and a task description, generate a browser automation ActionDef JSON.
 
 Rules:
@@ -94,33 +127,18 @@ ${elements.map((el, i) => {
   return `${i + 1}. <${el.tag}${attrs ? ' ' + attrs : ''}>${el.text}</${el.tag}>`;
 }).join('\n')}`;
 
-  const client = new Anthropic({ apiKey: options.apiKey ?? process.env['ANTHROPIC_API_KEY'] });
-  const model = options.model ?? MODEL_DEFAULTS.sonnet;
-
-  const message = await client.messages.create({
-    model,
-    max_tokens: 2048,
-    system: SYSTEM_PROMPT,
-    messages: [
-      {
-        role: 'user',
-        content: `Task: ${task}\n\nPage context:\n${domContext}`,
-      },
-    ],
-  });
-
-  const content = message.content[0];
-  if (content.type !== 'text') throw new Error('Claude returned non-text response');
+  const fullPrompt = `${SYSTEM_PROMPT}\n\nTask: ${task}\n\nPage context:\n${domContext}`;
+  const responseText = await claudeCliCall(fullPrompt);
 
   let actionDef: ActionDef;
   try {
-    actionDef = JSON.parse(content.text) as ActionDef;
+    actionDef = JSON.parse(responseText) as ActionDef;
   } catch {
-    throw new Error(`Claude returned invalid JSON:\n${content.text.slice(0, 500)}`);
+    throw new Error(`Claude returned invalid JSON:\n${responseText.slice(0, 500)}`);
   }
 
   if (!actionDef.id || !actionDef.steps || !Array.isArray(actionDef.steps)) {
-    throw new Error(`Claude returned invalid ActionDef: missing id or steps\n${content.text.slice(0, 500)}`);
+    throw new Error(`Claude returned invalid ActionDef: missing id or steps\n${responseText.slice(0, 500)}`);
   }
 
   return actionDef;

package/src/browser/dashboard/server.ts

@@ -5,23 +5,23 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
-import type { StepEvent, RunRecord, PlaybookDef } from '@monoes/monoplaybook';
 
-const RUNS_FILE = join(homedir(), '.monomind', 'browse-runs.json');
-const PLAYBOOKS_FILE = join(homedir(), '.monomind', 'playbooks.json');
-
-async function loadPlaybooks(): Promise<PlaybookDef[]> {
-  if (!existsSync(PLAYBOOKS_FILE)) return [];
-  try {
-    return JSON.parse(await readFile(PLAYBOOKS_FILE, 'utf-8')) as PlaybookDef[];
-  } catch { return []; }
+export interface StepEvent {
+  type: string;
+  projectDir?: string;
+  [key: string]: unknown;
 }
 
-async function savePlaybooks(playbooks: PlaybookDef[]): Promise<void> {
-  await mkdir(join(homedir(), '.monomind'), { recursive: true });
-  await writeFile(PLAYBOOKS_FILE, JSON.stringify(playbooks, null, 2));
+export interface RunRecord {
+  id: string;
+  startedAt: number;
+  status: string;
+  itemsProcessed?: number;
+  [key: string]: unknown;
 }
 
+const RUNS_FILE = join(homedir(), '.monomind', 'browse-runs.json');
+
 function readBody(req: IncomingMessage): Promise<string> {
   return new Promise((resolve, reject) => {
     let body = '';
@@ -90,7 +90,6 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
     }
 
     if (url === '/runs' && req.method === 'GET') {
-      // Merge in-memory runs with persisted runs so the UI shows history even across restarts
       const persisted = await loadPersistedRuns().catch(() => [] as RunRecord[]);
       const seen = new Set(runHistory.map(r => r.id));
       const merged = [...runHistory, ...persisted.filter(r => !seen.has(r.id))]
@@ -109,12 +108,9 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
       return;
     }
 
-    // Parse the URL to correctly handle query parameters such as ?dir=
     const parsed = new URL(url, 'http://localhost');
     if (parsed.pathname === '/events' && (req.method === 'GET' || req.method === 'HEAD') && !WebSocketServer) {
-      // SSE endpoint (fallback when ws not available).
-      // No CORS header — the dashboard is served from 127.0.0.1:4242 and no cross-origin
-      // access is needed. A wildcard ACAO would let any web page subscribe to playbook events.
+      // SSE fallback when ws not available
       const subscribedDir = parsed.searchParams.get('dir') ?? null;
       res.writeHead(200, {
         'Content-Type': 'text/event-stream',
@@ -123,7 +119,6 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
       });
       res.write(`data: ${JSON.stringify({ type: 'connected' })}\n\n`);
       clientDirs.set(res, subscribedDir);
-      // 30-second keep-alive heartbeat prevents proxy idle-timeout drops.
       const heartbeat = setInterval(() => {
         try { res.write(': keep-alive\n\n'); } catch { clearInterval(heartbeat); }
       }, 30_000);
@@ -134,176 +129,6 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
       return;
     }
 
-    // ── Playbook CRUD ────────────────────────────────────────────────────
-    // GET  /api/playbooks          → list all saved playbooks
-    // POST /api/playbooks          → create/update a playbook (body: PlaybookDef)
-    // GET  /api/playbooks/:id      → get single playbook
-    // DELETE /api/playbooks/:id    → delete a playbook
-    // POST /api/playbooks/:id/run  → run a playbook (delegates to engine)
-    if (parsed.pathname === '/api/playbooks' && req.method === 'GET') {
-      const list = await loadPlaybooks().catch(() => [] as PlaybookDef[]);
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify(list));
-      return;
-    }
-
-    if (parsed.pathname === '/api/playbooks' && req.method === 'POST') {
-      try {
-        const raw = await readBody(req);
-        const pb = JSON.parse(raw) as PlaybookDef;
-        if (!pb.id || !pb.name) {
-          res.writeHead(400, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({ error: 'id and name are required' }));
-          return;
-        }
-        const list = await loadPlaybooks().catch(() => [] as PlaybookDef[]);
-        const idx = list.findIndex(w => w.id === pb.id);
-        if (idx >= 0) list[idx] = pb; else list.push(pb);
-        await savePlaybooks(list);
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify(pb));
-      } catch (e) {
-        res.writeHead(500, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: String(e) }));
-      }
-      return;
-    }
-
-    const pbIdMatch = parsed.pathname.match(/^\/api\/playbooks\/([^/]+)$/);
-    const pbRunMatch = parsed.pathname.match(/^\/api\/playbooks\/([^/]+)\/run$/);
-
-    if (pbRunMatch && req.method === 'POST') {
-      const pbId = pbRunMatch[1];
-      const list = await loadPlaybooks().catch(() => [] as PlaybookDef[]);
-      const pb = list.find(w => w.id === pbId);
-      if (!pb) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: `Playbook ${pbId} not found` }));
-        return;
-      }
-      // Import engine and builtin handlers dynamically to avoid circular deps at startup
-      res.writeHead(202, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, playbookId: pbId, message: 'Playbook run started' }));
-      // Run async, broadcast events via dashboard
-      Promise.resolve().then(async () => {
-        try {
-          const { runPlaybook, createDefaultHandlers } = await import('../../index.js');
-          const handlers = createDefaultHandlers();
-          const record = await runPlaybook(pb, {
-            handlers,
-            onEvent: (evt) => { instance?.broadcast(evt); },
-            isStopRequested: (id) => instance?.isStopRequested(id) ?? false,
-          });
-          instance?.addRunRecord(record);
-        } catch (err) {
-          console.error('[dashboard] playbook run error:', err);
-        }
-      });
-      return;
-    }
-
-    if (pbIdMatch && req.method === 'GET') {
-      const pbId = pbIdMatch[1];
-      const list = await loadPlaybooks().catch(() => [] as PlaybookDef[]);
-      const pb = list.find(w => w.id === pbId);
-      if (!pb) { res.writeHead(404); res.end('Not found'); return; }
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify(pb));
-      return;
-    }
-
-    if (pbIdMatch && req.method === 'DELETE') {
-      const pbId = pbIdMatch[1];
-      const list = await loadPlaybooks().catch(() => [] as PlaybookDef[]);
-      const newList = list.filter(w => w.id !== pbId);
-      await savePlaybooks(newList);
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, deleted: pbId }));
-      return;
-    }
-
-    // ── Webhook trigger ──────────────────────────────────────────────────────
-    // POST /webhooks/:playbookId
-    //   Body (optional): JSON object or array — merged as `params` into the playbook run.
-    //   Header (optional): X-Webhook-Signature: sha256=<hex> for HMAC verification.
-    //   Response: 202 { ok, runId, playbookId } — run executes asynchronously.
-    const webhookMatch = parsed.pathname.match(/^\/webhooks\/([^/]+)$/);
-    if (webhookMatch && req.method === 'POST') {
-      const pbId = webhookMatch[1];
-      const list = await loadPlaybooks().catch(() => [] as PlaybookDef[]);
-      const pb = list.find(w => w.id === pbId);
-      if (!pb) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: `Playbook ${pbId} not found` }));
-        return;
-      }
-
-      const rawBody = await readBody(req).catch(() => '');
-
-      // Optional HMAC-SHA256 signature verification
-      const sigHeader = (req.headers['x-webhook-signature'] as string | undefined) ?? '';
-      if (sigHeader) {
-        try {
-          const { createHmac } = await import('node:crypto');
-          // Secret is stored in the playbook's trigger config (first schedule/webhook trigger)
-          const triggers = (pb as unknown as Record<string, unknown>)['triggers'];
-          const secret: string | undefined =
-            Array.isArray(triggers)
-              ? (triggers as Array<Record<string, unknown>>).find(t => t['secret'])?.[
-                  'secret'
-                ] as string | undefined
-              : undefined;
-          if (secret) {
-            const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
-            if (sigHeader !== expected) {
-              res.writeHead(403, { 'Content-Type': 'application/json' });
-              res.end(JSON.stringify({ error: 'Invalid webhook signature' }));
-              return;
-            }
-          }
-        } catch {
-          // crypto not available or other error — skip verification
-        }
-      }
-
-      // Parse body into params (string values only, per engine contract)
-      const params: Record<string, string> = {};
-      try {
-        if (rawBody.trim()) {
-          const parsed2 = JSON.parse(rawBody);
-          if (parsed2 && typeof parsed2 === 'object' && !Array.isArray(parsed2)) {
-            for (const [k, v] of Object.entries(parsed2 as Record<string, unknown>)) {
-              params[k] = typeof v === 'string' ? v : JSON.stringify(v);
-            }
-          }
-          params['__body'] = rawBody;
-        }
-      } catch {
-        params['__body'] = rawBody;
-      }
-
-      const runId = `webhook-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
-      res.writeHead(202, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, runId, playbookId: pbId }));
-
-      Promise.resolve().then(async () => {
-        try {
-          const { runPlaybook, createDefaultHandlers } = await import('../../index.js');
-          const handlers = createDefaultHandlers();
-          const record = await runPlaybook(pb, {
-            handlers,
-            params,
-            onEvent: (evt) => { instance?.broadcast(evt); },
-            isStopRequested: (id) => instance?.isStopRequested(id) ?? false,
-          });
-          instance?.addRunRecord(record);
-        } catch (err) {
-          console.error('[dashboard] webhook run error:', err);
-        }
-      });
-      return;
-    }
-
     res.writeHead(404);
     res.end('Not found');
   });
@@ -311,12 +136,10 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
   if (WebSocketServer) {
     const wss = new WebSocketServer({ server });
     wss.on('connection', async (ws: any, req: any) => {
-      // Extract optional project-dir filter from the WebSocket upgrade URL
       const upgradeUrl = req?.url ?? '/ws';
       const upgradeParsed = new URL(upgradeUrl, 'http://localhost');
       const subscribedDir = upgradeParsed.searchParams.get('dir') ?? null;
       clientDirs.set(ws, subscribedDir);
-      // Merge in-memory and persisted runs so history survives server restarts
       const persisted = await loadPersistedRuns().catch(() => [] as RunRecord[]);
       const seen = new Set(runHistory.map(r => r.id));
       const merged = [...runHistory, ...persisted.filter(r => !seen.has(r.id))]
@@ -329,11 +152,10 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
 
   server.on('error', (err: NodeJS.ErrnoException) => {
     if (err.code === 'EADDRINUSE') {
-      console.log(`Dashboard port ${port} in use — playbook will run without live dashboard.`);
+      console.log(`Dashboard port ${port} in use — continuing without live dashboard.`);
     } else {
       console.error(`Dashboard server error: ${err.message}`);
     }
-    // Replace with a no-op instance so the engine doesn't crash
     instance = {
       broadcast: () => {},
       addRunRecord: () => {},
@@ -348,17 +170,14 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
   function broadcast(event: StepEvent): void {
     const msg = JSON.stringify(event);
     for (const [client, subscribedDir] of clientDirs) {
-      // Server-side project filtering: if the client subscribed with ?dir=<path>, only
-      // deliver events whose projectDir matches.  Clients without a dir filter (subscribedDir
-      // === null) receive all events, preserving backward-compatibility with ui.html.
       if (subscribedDir !== null && event.projectDir !== undefined && subscribedDir !== event.projectDir) {
         continue;
       }
       try {
         if (typeof client.send === 'function') {
-          client.send(msg); // WebSocket
+          client.send(msg);
         } else {
-          client.write(`data: ${msg}\n\n`); // SSE
+          client.write(`data: ${msg}\n\n`);
         }
       } catch {
         clientDirs.delete(client);
@@ -374,7 +193,6 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
       runHistory.unshift(record);
       if (runHistory.length > MAX_RUN_HISTORY) runHistory.pop();
     }
-    // Persist to disk so the CLI dashboard (/api/workflow-runs) can read run history
     const dir = join(homedir(), '.monomind');
     mkdir(dir, { recursive: true }).then(() =>
       writeFile(RUNS_FILE, JSON.stringify(runHistory, null, 2))

package/src/browser/index.ts

@@ -20,3 +20,4 @@ export * from './trace.js';
 export * from './profiler.js';
 export * from './vitals.js';
 export * from './har.js';
+export * from './ref-cache.js';