browserwire 0.1.0

package/cli/discovery/synthesize-workflows.js

@@ -0,0 +1,295 @@
+/**
+ * synthesize-workflows.js — LLM-driven workflow synthesis
+ *
+ * Takes a merged BrowserWireManifest and produces WorkflowActionDef[] —
+ * complete task blueprints covering navigation, interaction, and data reading.
+ *
+ * Three workflow kinds:
+ *   read  — navigate → read_view → return structured data
+ *   write — navigate → fill/select/click → submit → check outcomes
+ *   mixed — navigate → interact → read_view → return structured data
+ */
+
+import { callLLM, getLLMConfig } from "./llm-client.js";
+
+const SYSTEM_PROMPT = `You are a workflow architect for web automation. Given a site manifest, you synthesize high-level task workflows that developers actually want to call.
+
+You will receive:
+- pages[]: { id, routePattern, name, description }
+- actions[]: { id, interactionKind, semanticName, name }
+- views[]: { id, name, isList }
+- compositeActions[]: hints about multi-step operations
+
+## Three workflow kinds
+
+**READ workflows** (kind: "read") — fetch and return structured data:
+- Navigate to the listing/detail page
+- End with a read_view step referencing a viewId from views[]
+- No inputs required unless navigation needs a parameter (e.g., id for detail page)
+- No outcomes field needed
+- Examples: list_events, get_event_details, list_attendees
+
+**WRITE workflows** (kind: "write") — perform a mutation:
+- Navigate to form/action page
+- Fill fields (interactionKind=type → fill), select dropdowns (interactionKind=select → select), submit (form-submit click → submit, toggle → click)
+- Provide outcomes with success/failure signals
+- Examples: create_event, register_for_event, update_profile
+
+**MIXED workflows** (kind: "mixed") — interact then read:
+- Navigate, interact (search/filter), then read_view for results
+- Provide outcomes only if a submission is involved
+- Examples: search_events, filter_by_category
+
+## Rules
+- First step MUST always be navigate
+- Only reference actionIds from actions[] and viewIds from views[]
+- read_view MUST be the LAST step for read/mixed workflows
+- For write: infer step type from interactionKind: type→fill, select→select, form-submit click→submit, toggle→click
+- Map every workflow input to exactly one fill/select step via inputParam
+- Max 8 workflows — prioritize the most useful
+- URL: use routePattern from pages[]; replace :param with the input variable name
+
+## Output format (JSON only, no prose)
+{
+  "workflows": [
+    {
+      "name": "list_events",
+      "kind": "read",
+      "description": "Returns all events as a structured list",
+      "inputs": [],
+      "steps": [
+        { "type": "navigate", "url": "/events" },
+        { "type": "read_view", "viewId": "view_events_list" }
+      ]
+    },
+    {
+      "name": "create_event",
+      "kind": "write",
+      "description": "Creates a new event by filling the creation form",
+      "inputs": [
+        { "name": "title", "type": "string", "required": true, "description": "Event title" },
+        { "name": "start_date", "type": "string", "required": true, "description": "Start date" }
+      ],
+      "steps": [
+        { "type": "navigate", "url": "/events/new" },
+        { "type": "fill", "actionId": "action_type_into_title", "inputParam": "title" },
+        { "type": "fill", "actionId": "action_type_into_start_date", "inputParam": "start_date" },
+        { "type": "submit", "actionId": "action_click_create_event" }
+      ],
+      "outcomes": {
+        "success": { "kind": "url_change", "value": "/events/[0-9]+" },
+        "failure": { "kind": "element_appears", "value": ".error-message, .alert-danger" }
+      }
+    }
+  ]
+}`;
+
+/**
+ * Validate and clean up a raw workflow object from the LLM response.
+ * Returns a WorkflowActionDef or null if invalid.
+ */
+const validateWorkflow = (raw, actionIds, viewIds, capturedAt) => {
+  if (!raw || typeof raw !== "object") return null;
+  if (!raw.name || typeof raw.name !== "string") return null;
+  if (!["read", "write", "mixed"].includes(raw.kind)) return null;
+  if (!Array.isArray(raw.steps) || raw.steps.length === 0) return null;
+
+  // First step must be navigate
+  if (raw.steps[0]?.type !== "navigate") return null;
+
+  const steps = [];
+  for (const step of raw.steps) {
+    if (!step || typeof step.type !== "string") return null;
+
+    if (step.type === "navigate") {
+      if (!step.url || typeof step.url !== "string") return null;
+      steps.push({ type: "navigate", url: step.url });
+      continue;
+    }
+
+    if (step.type === "read_view") {
+      if (!step.viewId || !viewIds.has(step.viewId)) {
+        // skip invalid read_view references silently
+        continue;
+      }
+      steps.push({ type: "read_view", viewId: step.viewId });
+      continue;
+    }
+
+    if (["fill", "select", "click", "submit"].includes(step.type)) {
+      if (!step.actionId || !actionIds.has(step.actionId)) {
+        // skip unknown action references
+        continue;
+      }
+      const s = { type: step.type, actionId: step.actionId };
+      if (step.inputParam && typeof step.inputParam === "string") {
+        s.inputParam = step.inputParam;
+      }
+      steps.push(s);
+      continue;
+    }
+
+    // Unknown step type — skip
+  }
+
+  if (steps.length === 0) return null;
+  if (steps[0].type !== "navigate") return null;
+
+  // For read/mixed: require at least one read_view step
+  if (raw.kind === "read" || raw.kind === "mixed") {
+    if (!steps.some((s) => s.type === "read_view")) return null;
+    // read_view must be last
+    const lastIdx = steps.length - 1;
+    if (steps[lastIdx].type !== "read_view") {
+      // Move it to the end
+      const readViewSteps = steps.filter((s) => s.type === "read_view");
+      const nonReadView = steps.filter((s) => s.type !== "read_view");
+      steps.length = 0;
+      steps.push(...nonReadView, ...readViewSteps);
+    }
+  }
+
+  // For write: require at least one fill/select + submit/click
+  if (raw.kind === "write") {
+    const hasFillOrSelect = steps.some((s) => s.type === "fill" || s.type === "select");
+    const hasSubmitOrClick = steps.some((s) => s.type === "submit" || s.type === "click");
+    if (!hasFillOrSelect || !hasSubmitOrClick) return null;
+  }
+
+  // Validate inputs — only keep inputs referenced in a step
+  const referencedParams = new Set(
+    steps.filter((s) => s.inputParam).map((s) => s.inputParam)
+  );
+
+  const inputs = (Array.isArray(raw.inputs) ? raw.inputs : [])
+    .filter((i) => i && typeof i.name === "string" && referencedParams.has(i.name))
+    .map((i) => ({
+      name: i.name,
+      type: ["string", "number", "boolean", "enum"].includes(i.type) ? i.type : "string",
+      required: i.required === true,
+      description: typeof i.description === "string" ? i.description : undefined
+    }));
+
+  const workflowId = `workflow_${raw.name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+
+  const result = {
+    id: workflowId,
+    name: raw.name,
+    description: typeof raw.description === "string" ? raw.description : raw.name,
+    kind: raw.kind,
+    inputs,
+    steps,
+    provenance: {
+      source: "agent",
+      sessionId: "workflow-synthesis",
+      traceIds: [],
+      annotationIds: [],
+      capturedAt: capturedAt || new Date().toISOString()
+    }
+  };
+
+  // Add outcomes for write/mixed
+  if (raw.outcomes && typeof raw.outcomes === "object" && raw.kind !== "read") {
+    const outcomes = {};
+    for (const [key, signal] of Object.entries(raw.outcomes)) {
+      if (!signal || typeof signal !== "object") continue;
+      if (!["url_change", "element_appears", "text_contains", "element_disappears"].includes(signal.kind)) continue;
+      if (typeof signal.value !== "string") continue;
+      outcomes[key] = { kind: signal.kind, value: signal.value };
+      if (signal.selector && typeof signal.selector === "string") {
+        outcomes[key].selector = signal.selector;
+      }
+    }
+    if (Object.keys(outcomes).length > 0) {
+      result.outcomes = outcomes;
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Synthesize WorkflowActionDef[] from a merged manifest using the LLM.
+ *
+ * @param {object} manifest - BrowserWireManifest
+ * @returns {Promise<WorkflowActionDef[]>}
+ */
+export const synthesizeWorkflows = async (manifest) => {
+  const config = getLLMConfig();
+  if (!config) {
+    console.log("[browserwire-cli] workflow synthesis skipped: LLM not configured");
+    return [];
+  }
+
+  const actions = manifest.actions || [];
+  const views = manifest.views || [];
+  const pages = manifest.pages || [];
+  const compositeActions = manifest.compositeActions || [];
+
+  if (actions.length === 0 && views.length === 0) {
+    console.log("[browserwire-cli] workflow synthesis skipped: no actions or views");
+    return [];
+  }
+
+  const actionIds = new Set(actions.map((a) => a.id));
+  const viewIds = new Set(views.map((v) => v.id));
+
+  // Build compact manifest summary for the LLM
+  const userMessage = JSON.stringify({
+    pages: pages.map((p) => ({
+      id: p.id,
+      routePattern: p.routePattern,
+      name: p.name,
+      description: p.description || ""
+    })),
+    actions: actions.map((a) => ({
+      id: a.id,
+      interactionKind: a.interactionKind || "click",
+      semanticName: a.semanticName || a.name,
+      name: a.name
+    })),
+    views: views.map((v) => ({
+      id: v.id,
+      name: v.semanticName || v.name,
+      isList: v.isList || false
+    })),
+    compositeActions: compositeActions.map((ca) => ({
+      name: ca.name,
+      description: ca.description || "",
+      stepCount: (ca.stepActionIds || []).length
+    }))
+  }, null, 2);
+
+  let rawText;
+  try {
+    rawText = await callLLM(SYSTEM_PROMPT, userMessage, config);
+  } catch (error) {
+    console.warn(`[browserwire-cli] workflow synthesis LLM call failed: ${error.message}`);
+    return [];
+  }
+
+  // Parse JSON from response
+  let parsed;
+  try {
+    // Strip markdown code fences if present
+    const cleaned = rawText
+      .replace(/^```(?:json)?\s*/m, "")
+      .replace(/\s*```\s*$/m, "")
+      .trim();
+    parsed = JSON.parse(cleaned);
+  } catch (error) {
+    console.warn(`[browserwire-cli] workflow synthesis: failed to parse LLM response: ${error.message}`);
+    return [];
+  }
+
+  const rawWorkflows = Array.isArray(parsed.workflows) ? parsed.workflows : [];
+  const capturedAt = new Date().toISOString();
+
+  const workflows = rawWorkflows
+    .map((raw) => validateWorkflow(raw, actionIds, viewIds, capturedAt))
+    .filter(Boolean)
+    .slice(0, 8);
+
+  console.log(`[browserwire-cli] workflow synthesis: ${workflows.length} workflows synthesized (${rawWorkflows.length} raw)`);
+  return workflows;
+};

package/cli/index.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// Load .env file (if present) without overriding existing env vars
+const loadEnv = (filePath) => {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIndex = trimmed.indexOf("=");
+      if (eqIndex === -1) continue;
+      const key = trimmed.slice(0, eqIndex).trim();
+      let value = trimmed.slice(eqIndex + 1).trim();
+      // Strip surrounding quotes
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      // Don't override existing env vars
+      if (!(key in process.env)) {
+        process.env[key] = value;
+      }
+    }
+  } catch {
+    // .env file is optional — silently skip if missing
+  }
+};
+
+loadEnv(resolve(process.cwd(), ".env"));
+
+const args = process.argv.slice(2);
+const debug = args.includes("--debug");
+
+if (args.includes("--extension-path")) {
+  const extPath = resolve(import.meta.dirname, "../extension");
+  console.log(extPath);
+  process.exit(0);
+}
+
+// --- Server mode: run discovery pipeline + REST API ---
+const host = process.env.BROWSERWIRE_HOST || "127.0.0.1";
+const port = Number(process.env.BROWSERWIRE_PORT || 8787);
+
+if (!process.env.BROWSERWIRE_LLM_PROVIDER) {
+  console.error("[browserwire-cli] BROWSERWIRE_LLM_PROVIDER is required (set in .env or environment)");
+  console.error("[browserwire-cli] Supported: openai, anthropic, ollama");
+  process.exit(1);
+}
+
+const { startServer } = await import("./server.js");
+const server = await startServer({ host, port, debug });
+
+const shutdown = () => {
+  server.close(() => {
+    process.exit(0);
+  });
+};
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/cli/manifest-store.js

@@ -0,0 +1,140 @@
+/**
+ * manifest-store.js — File-based store for site-centric manifests.
+ *
+ * Directory layout:
+ *   manifests/
+ *     lu_ma/              # slug from hostname (dots → underscores)
+ *       manifest.json     # canonical manifest
+ *       meta.json         # { origin, createdAt, updatedAt, sessionHistory }
+ */
+
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export class ManifestStore {
+  constructor(baseDir = resolve(process.cwd(), "manifests")) {
+    this.baseDir = baseDir;
+  }
+
+  /**
+   * Convert a URL or origin string to a filesystem-safe slug.
+   * "https://lu.ma" → "lu_ma", "localhost:3000" → "localhost_3000"
+   */
+  static originSlug(urlOrOrigin) {
+    try {
+      const u = new URL(urlOrOrigin);
+      return u.host.replace(/[.:]/g, "_");
+    } catch {
+      // Already a bare host like "localhost:3000"
+      return urlOrOrigin.replace(/[.:]/g, "_");
+    }
+  }
+
+  /**
+   * List all known sites with summary metadata (no full manifest load).
+   * @returns {Promise<Array<{ origin: string, slug: string, updatedAt: string|null, entityCount: number, actionCount: number }>>}
+   */
+  async listSites() {
+    let entries;
+    try {
+      entries = await readdir(this.baseDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+
+    const sites = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const slug = entry.name;
+      const metaPath = resolve(this.baseDir, slug, "meta.json");
+      try {
+        const raw = await readFile(metaPath, "utf8");
+        const meta = JSON.parse(raw);
+        sites.push({
+          origin: meta.origin,
+          slug,
+          updatedAt: meta.updatedAt || meta.createdAt || null,
+          entityCount: meta.entityCount || 0,
+          actionCount: meta.actionCount || 0
+        });
+      } catch {
+        // Skip directories without valid meta.json
+      }
+    }
+    return sites;
+  }
+
+  /**
+   * Load the canonical manifest for a site.
+   * @returns {Promise<object|null>}
+   */
+  async load(urlOrOrigin) {
+    const slug = ManifestStore.originSlug(urlOrOrigin);
+    const manifestPath = resolve(this.baseDir, slug, "manifest.json");
+    try {
+      const raw = await readFile(manifestPath, "utf8");
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if a manifest exists for the given site.
+   * @returns {Promise<boolean>}
+   */
+  async has(urlOrOrigin) {
+    const slug = ManifestStore.originSlug(urlOrOrigin);
+    const manifestPath = resolve(this.baseDir, slug, "manifest.json");
+    try {
+      await readFile(manifestPath, "utf8");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Save a manifest for a site. Writes manifest.json and updates meta.json atomically.
+   */
+  async save(urlOrOrigin, manifest, sessionId) {
+    let origin;
+    try {
+      origin = new URL(urlOrOrigin).origin;
+    } catch {
+      origin = urlOrOrigin;
+    }
+
+    const slug = ManifestStore.originSlug(urlOrOrigin);
+    const dir = resolve(this.baseDir, slug);
+    await mkdir(dir, { recursive: true });
+
+    // Write manifest
+    await writeFile(resolve(dir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+
+    // Read or create meta
+    const metaPath = resolve(dir, "meta.json");
+    let meta;
+    try {
+      const raw = await readFile(metaPath, "utf8");
+      meta = JSON.parse(raw);
+    } catch {
+      meta = {
+        origin,
+        createdAt: new Date().toISOString(),
+        sessionHistory: []
+      };
+    }
+
+    meta.updatedAt = new Date().toISOString();
+    meta.entityCount = manifest.entities?.length || 0;
+    meta.actionCount = manifest.actions?.length || 0;
+    if (sessionId) {
+      meta.sessionHistory.push({ sessionId, timestamp: meta.updatedAt });
+    }
+
+    await writeFile(metaPath, JSON.stringify(meta, null, 2), "utf8");
+
+    console.log(`[browserwire-cli] manifest saved for ${origin} → manifests/${slug}/`);
+  }
+}