ghostrun-cli 1.0.0

package/mcp-server.js

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// mcp-server.ts
+var import_server = require("@modelcontextprotocol/sdk/server/index.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_types = require("@modelcontextprotocol/sdk/types.js");
+var import_child_process = require("child_process");
+var import_better_sqlite3 = __toESM(require("better-sqlite3"));
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var HOME_DIR = process.env.HOME || process.env.USERPROFILE || ".";
+var DATA_PATH = path.join(HOME_DIR, ".ghostrun");
+var DB_PATH = path.join(DATA_PATH, "data", "ghostrun.db");
+var GHOSTRUN_BIN = path.join(__dirname, "ghostrun.js");
+function openDb() {
+  if (!fs.existsSync(DB_PATH)) return null;
+  const db = new import_better_sqlite3.default(DB_PATH, { readonly: true });
+  db.pragma("foreign_keys = ON");
+  return db;
+}
+function mapFlow(r) {
+  return {
+    id: r.id,
+    name: r.name,
+    description: r.description,
+    appUrl: r.app_url,
+    graph: r.graph,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at
+  };
+}
+function mapRun(r) {
+  return {
+    id: r.id,
+    flowId: r.flow_id,
+    status: r.status,
+    startedAt: r.started_at,
+    completedAt: r.completed_at,
+    duration: r.duration,
+    errorMessage: r.error_message,
+    summary: r.summary
+  };
+}
+function mapStep(r) {
+  return {
+    id: r.id,
+    runId: r.run_id,
+    stepNumber: r.step_number,
+    name: r.name,
+    action: r.action,
+    selector: r.selector,
+    value: r.value,
+    status: r.status,
+    duration: r.duration,
+    errorMessage: r.error_message,
+    screenshotPath: r.screenshot_path
+  };
+}
+function runFlowViaCli(flowId, vars) {
+  return new Promise((resolve, reject) => {
+    const varArgs = [];
+    if (vars) {
+      for (const [k, v] of Object.entries(vars)) varArgs.push("--var", `${k}=${v}`);
+    }
+    const proc = (0, import_child_process.spawn)("node", [GHOSTRUN_BIN, "run", flowId, "--output", "json", ...varArgs], {
+      env: { ...process.env },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    proc.on("close", () => {
+      const jsonLine = stdout.split("\n").find((l) => l.trim().startsWith("{"));
+      if (jsonLine) {
+        try {
+          resolve(JSON.parse(jsonLine));
+          return;
+        } catch {
+        }
+      }
+      reject(new Error(`ghostrun run failed: ${stderr || stdout || "(no output)"}`));
+    });
+    proc.on("error", (err) => reject(new Error(`Failed to spawn ghostrun: ${err.message}`)));
+  });
+}
+var server = new import_server.Server(
+  { name: "ghostrun", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(import_types.ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "list_flows",
+      description: "List all saved GhostRun flows with their IDs, names, step counts, and last updated date. Works for both browser automation flows and API test flows.",
+      inputSchema: { type: "object", properties: {} }
+    },
+    {
+      name: "get_flow",
+      description: "Get detailed information about a specific GhostRun flow, including all action steps with their selectors and values.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          flowId: { type: "string", description: "Flow ID or first 8 characters of it" }
+        },
+        required: ["flowId"]
+      }
+    },
+    {
+      name: "run_flow",
+      description: "Execute a GhostRun flow. Handles browser automation flows (Playwright), pure API test flows (no browser needed), and hybrid flows. Returns run ID, pass/fail status, per-step results, extracted data, and error details.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          flowId: { type: "string", description: "Flow ID or first 8 characters of it (also accepts flow name)" },
+          vars: {
+            type: "object",
+            description: 'Optional key=value variables to inject into the flow (e.g. { "username": "alice", "env": "staging" })',
+            additionalProperties: { type: "string" }
+          }
+        },
+        required: ["flowId"]
+      }
+    },
+    {
+      name: "get_run_result",
+      description: "Get detailed results of a previous flow run: step-by-step status, timing, error messages, extracted data, AI failure summary, and screenshot paths.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          runId: { type: "string", description: "Run ID or first 8 characters of it" }
+        },
+        required: ["runId"]
+      }
+    },
+    {
+      name: "list_runs",
+      description: "List recent flow runs with status, duration, and flow name. Optionally filter by flow ID.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          flowId: { type: "string", description: "Optional: filter runs to a specific flow" },
+          limit: { type: "number", description: "Max results to return (default 20)" }
+        }
+      }
+    },
+    {
+      name: "delete_flow",
+      description: "Delete a GhostRun flow and all its run history.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          flowId: { type: "string", description: "Flow ID or first 8 characters of it" }
+        },
+        required: ["flowId"]
+      }
+    },
+    {
+      name: "get_status",
+      description: "Get GhostRun system statistics: total flows, total runs, pass/fail counts, success rate, and data path.",
+      inputSchema: { type: "object", properties: {} }
+    }
+  ]
+}));
+server.setRequestHandler(import_types.CallToolRequestSchema, async (request) => {
+  const { name, arguments: toolArgs } = request.params;
+  try {
+    switch (name) {
+      case "list_flows": {
+        const db = openDb();
+        if (!db) return text("No flows yet. Record your first flow with: ghostrun learn <url>");
+        const flows = db.prepare("SELECT * FROM flows ORDER BY updated_at DESC").all().map(mapFlow);
+        db.close();
+        if (flows.length === 0) return text("No flows saved yet. Use `ghostrun learn <url>` to record your first flow.");
+        const rows = flows.map((f) => {
+          let stepCount = 0;
+          let isApiFlow = false;
+          try {
+            const nodes = (JSON.parse(f.graph).nodes || []).filter((n) => n.type === "action");
+            stepCount = nodes.length;
+            const apiActions = /* @__PURE__ */ new Set(["http:request", "assert:response", "set:variable", "extract:json", "env:switch"]);
+            isApiFlow = nodes.length > 0 && nodes.every((n) => apiActions.has(n.action));
+          } catch {
+          }
+          return { id: f.id.slice(0, 8), name: f.name, description: f.description || "", steps: stepCount, type: isApiFlow ? "api" : "browser", url: f.appUrl || "", updated: f.updatedAt };
+        });
+        return text(JSON.stringify({ total: flows.length, flows: rows }, null, 2));
+      }
+      case "get_flow": {
+        const { flowId } = toolArgs;
+        const db = openDb();
+        if (!db) return error("No database found. Run `ghostrun init` first.");
+        const row = db.prepare("SELECT * FROM flows WHERE id LIKE ? OR name = ?").get(flowId + "%", flowId);
+        db.close();
+        if (!row) return error(`Flow not found: ${flowId}`);
+        const flow = mapFlow(row);
+        const graph = JSON.parse(flow.graph);
+        const actionNodes = (graph.nodes || []).filter((n) => n.type === "action");
+        return text(JSON.stringify({
+          id: flow.id,
+          name: flow.name,
+          description: flow.description,
+          appUrl: flow.appUrl,
+          createdAt: flow.createdAt,
+          updatedAt: flow.updatedAt,
+          stepCount: actionNodes.length,
+          steps: actionNodes.map((n, i) => ({
+            step: i + 1,
+            label: n.label,
+            action: n.action,
+            selector: n.selector || null,
+            value: n.value ? "***" : null,
+            url: n.url || null
+          }))
+        }, null, 2));
+      }
+      case "run_flow": {
+        const { flowId, vars } = toolArgs;
+        let result;
+        try {
+          result = await runFlowViaCli(flowId, vars);
+        } catch (err) {
+          return error(err instanceof Error ? err.message : String(err));
+        }
+        return text(JSON.stringify({
+          runId: result.runId,
+          runIdShort: result.runId?.slice(0, 8),
+          status: result.passed ? "passed" : "failed",
+          flowName: result.flowName,
+          duration: result.duration ? `${result.duration}ms` : null,
+          stepsTotal: result.steps?.length ?? 0,
+          stepsPassed: result.steps?.filter((s) => s.status === "passed").length ?? 0,
+          stepsFailed: result.steps?.filter((s) => s.status === "failed").length ?? 0,
+          extractedData: result.extractedData || {},
+          steps: result.steps,
+          errorMessage: result.steps?.find((s) => s.errorMessage)?.errorMessage ?? null,
+          hint: !result.passed ? `Run failed. Use get_run_result with runId "${result.runId?.slice(0, 8)}" for details.` : "All steps passed."
+        }, null, 2));
+      }
+      case "get_run_result": {
+        const { runId } = toolArgs;
+        const db = openDb();
+        if (!db) return error("No database found.");
+        const runRow = db.prepare("SELECT * FROM runs WHERE id LIKE ?").get(runId + "%");
+        if (!runRow) {
+          db.close();
+          return error(`Run not found: ${runId}`);
+        }
+        const run = mapRun(runRow);
+        const flowRow = db.prepare("SELECT * FROM flows WHERE id = ?").get(run.flowId);
+        const flow = flowRow ? mapFlow(flowRow) : null;
+        const steps = db.prepare("SELECT * FROM steps WHERE run_id = ? ORDER BY step_number").all(run.id).map(mapStep);
+        db.close();
+        return text(JSON.stringify({
+          runId: run.id,
+          flowName: flow?.name || "Unknown",
+          status: run.status,
+          startedAt: run.startedAt,
+          completedAt: run.completedAt,
+          duration: run.duration ? `${run.duration}ms` : null,
+          errorMessage: run.errorMessage,
+          aiSummary: run.summary || null,
+          steps: steps.map((s) => ({
+            step: s.stepNumber,
+            name: s.name,
+            action: s.action,
+            selector: s.selector,
+            status: s.status,
+            duration: s.duration ? `${s.duration}ms` : null,
+            errorMessage: s.errorMessage,
+            screenshotPath: s.screenshotPath
+          }))
+        }, null, 2));
+      }
+      case "list_runs": {
+        const { flowId, limit = 20 } = toolArgs || {};
+        const db = openDb();
+        if (!db) return text('{ "runs": [] }');
+        const sql = flowId ? "SELECT r.*, f.name as flow_name FROM runs r LEFT JOIN flows f ON r.flow_id = f.id WHERE r.flow_id LIKE ? ORDER BY r.started_at DESC LIMIT ?" : "SELECT r.*, f.name as flow_name FROM runs r LEFT JOIN flows f ON r.flow_id = f.id ORDER BY r.started_at DESC LIMIT ?";
+        const params = flowId ? [flowId + "%", limit] : [limit];
+        const rows = db.prepare(sql).all(...params);
+        db.close();
+        return text(JSON.stringify({
+          total: rows.length,
+          runs: rows.map((r) => ({
+            id: r.id.slice(0, 8),
+            flowName: r.flow_name || "Unknown",
+            status: r.status,
+            startedAt: r.started_at,
+            duration: r.duration ? `${r.duration}ms` : null,
+            hasAiSummary: !!r.summary
+          }))
+        }, null, 2));
+      }
+      case "delete_flow": {
+        const { flowId } = toolArgs;
+        const db = openDb();
+        if (!db) return error("No database found.");
+        const row = db.prepare("SELECT * FROM flows WHERE id LIKE ? OR name = ?").get(flowId + "%", flowId);
+        if (!row) {
+          db.close();
+          return error(`Flow not found: ${flowId}`);
+        }
+        const flow = mapFlow(row);
+        const writeDb = new import_better_sqlite3.default(DB_PATH);
+        writeDb.prepare("DELETE FROM flows WHERE id = ?").run(flow.id);
+        writeDb.close();
+        db.close();
+        return text(`Deleted flow "${flow.name}" (${flow.id.slice(0, 8)})`);
+      }
+      case "get_status": {
+        const db = openDb();
+        if (!db) return text(JSON.stringify({ flows: 0, totalRuns: 0, passed: 0, failed: 0, successRate: "N/A", dataPath: DATA_PATH, aiEnabled: !!process.env.ANTHROPIC_API_KEY }, null, 2));
+        const flowCount = db.prepare("SELECT COUNT(*) as c FROM flows").get().c;
+        const runCount = db.prepare("SELECT COUNT(*) as c FROM runs").get().c;
+        const passedCount = db.prepare("SELECT COUNT(*) as c FROM runs WHERE status = 'passed'").get().c;
+        const failedCount = db.prepare("SELECT COUNT(*) as c FROM runs WHERE status = 'failed'").get().c;
+        db.close();
+        return text(JSON.stringify({
+          flows: flowCount,
+          totalRuns: runCount,
+          passed: passedCount,
+          failed: failedCount,
+          successRate: runCount > 0 ? `${Math.round(passedCount / runCount * 100)}%` : "N/A",
+          dataPath: DATA_PATH,
+          aiEnabled: !!process.env.ANTHROPIC_API_KEY
+        }, null, 2));
+      }
+      default:
+        return error(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    return error(err instanceof Error ? err.message : String(err));
+  }
+});
+function text(content) {
+  return { content: [{ type: "text", text: content }] };
+}
+function error(message) {
+  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+async function main() {
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("GhostRun MCP Server running. Connect via Claude Desktop or any MCP client.\n");
+}
+main().catch((err) => {
+  process.stderr.write(`Fatal: ${err}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ghostrun-cli",
+  "version": "1.0.0",
+  "description": "Browser automation + API testing + load testing in one tool. Record flows, test REST APIs, run VU-based load tests, export to k6. Entirely local.",
+  "main": "ghostrun.js",
+  "bin": {
+    "ghostrun": "ghostrun.js",
+    "ghostrun-mcp": "mcp-server.js"
+  },
+  "keywords": [
+    "browser-automation", "api-testing", "load-testing", "playwright",
+    "test-runner", "cli", "k6", "local-first", "mcp", "e2e-testing"
+  ],
+  "homepage": "https://ghostrun.builtbysharan.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/builtbysharan/ghostrun"
+  },
+  "license": "MIT",
+  "scripts": {
+    "start": "node ghostrun.js",
+    "cli": "node ghostrun.js",
+    "mcp": "npx tsx mcp-server.ts",
+    "build": "npx esbuild ghostrun.ts --platform=node --format=cjs --outfile=ghostrun.js --bundle --external:playwright --external:better-sqlite3 --external:chalk --external:uuid --external:@anthropic-ai/sdk --external:@clack/prompts && npx esbuild mcp-server.ts --platform=node --format=cjs --outfile=mcp-server.js --bundle --external:playwright --external:better-sqlite3 --external:uuid --external:@anthropic-ai/sdk --external:@modelcontextprotocol/sdk",
+    "test": "./TEST-DEMO.sh",
+    "demo": "./TEST-DEMO.sh"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.37.0",
+    "@clack/prompts": "^1.2.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^9.4.3",
+    "chalk": "^4.1.2",
+    "node-cron": "^4.2.1",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.41.0",
+    "pngjs": "^7.0.0",
+    "uuid": "^9.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/node": "^20.11.0",
+    "@types/node-cron": "^3.0.11",
+    "@types/pngjs": "^6.0.5",
+    "@types/uuid": "^9.0.7",
+    "electron": "^41.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3"
+  }
+}

package/templates/api-health.flow.json

@@ -0,0 +1,26 @@
+{
+  "version": "1.0.0",
+  "template": true,
+  "name": "API Health Check",
+  "description": "Hit the /api/health or /api/status endpoint and assert it returns OK",
+  "tags": ["api", "health", "monitoring", "ci"],
+  "variables": ["BASE_URL"],
+  "flow": {
+    "name": "API Health Check",
+    "description": "Verify API health endpoint returns OK status",
+    "appUrl": "{{BASE_URL}}",
+    "graph": {
+      "nodes": [
+        { "id": "start",  "type": "start",  "label": "Start", "url": "{{BASE_URL}}" },
+        { "id": "step-1", "type": "action", "label": "Navigate to API health endpoint", "action": "navigate", "url": "{{BASE_URL}}/api/health" },
+        { "id": "step-2", "type": "action", "label": "Assert OK response", "action": "assert:text", "value": "ok" },
+        { "id": "end",    "type": "end",    "label": "End" }
+      ],
+      "edges": [
+        { "id": "e0", "source": "start",  "target": "step-1" },
+        { "id": "e1", "source": "step-1", "target": "step-2" },
+        { "id": "e2", "source": "step-2", "target": "end" }
+      ]
+    }
+  }
+}

package/templates/checkout-guest.flow.json

@@ -0,0 +1,38 @@
+{
+  "version": "1.0.0",
+  "template": true,
+  "name": "Checkout Guest",
+  "description": "Add a product to cart and complete guest checkout flow",
+  "tags": ["ecommerce", "checkout", "cart"],
+  "variables": ["BASE_URL", "EMAIL", "FIRST_NAME", "LAST_NAME"],
+  "flow": {
+    "name": "Checkout Guest",
+    "description": "Add to cart → guest checkout → assert order confirmation",
+    "appUrl": "{{BASE_URL}}",
+    "graph": {
+      "nodes": [
+        { "id": "start",  "type": "start",  "label": "Start", "url": "{{BASE_URL}}" },
+        { "id": "step-1", "type": "action", "label": "Navigate to products", "action": "navigate", "url": "{{BASE_URL}}/products" },
+        { "id": "step-2", "type": "action", "label": "Click first product", "action": "click", "selector": ".product-card:first-child, .product:first-child a, [data-testid='product']:first-child" },
+        { "id": "step-3", "type": "action", "label": "Add to cart", "action": "click", "selector": "button:has-text('Add to cart'), .add-to-cart, #add-to-cart" },
+        { "id": "step-4", "type": "action", "label": "View cart", "action": "navigate", "url": "{{BASE_URL}}/cart" },
+        { "id": "step-5", "type": "action", "label": "Proceed to checkout", "action": "click", "selector": "button:has-text('Checkout'), a:has-text('Checkout'), .checkout-btn" },
+        { "id": "step-6", "type": "action", "label": "Fill email", "action": "fill", "selector": "input[type='email'], input[name='email'], #email", "value": "{{EMAIL}}" },
+        { "id": "step-7", "type": "action", "label": "Continue as guest", "action": "click", "selector": "button:has-text('Continue'), button:has-text('Guest'), .guest-checkout" },
+        { "id": "step-8", "type": "action", "label": "Assert on checkout page", "action": "assert:url", "value": "/checkout" },
+        { "id": "end",    "type": "end",    "label": "End" }
+      ],
+      "edges": [
+        { "id": "e0", "source": "start",  "target": "step-1" },
+        { "id": "e1", "source": "step-1", "target": "step-2" },
+        { "id": "e2", "source": "step-2", "target": "step-3" },
+        { "id": "e3", "source": "step-3", "target": "step-4" },
+        { "id": "e4", "source": "step-4", "target": "step-5" },
+        { "id": "e5", "source": "step-5", "target": "step-6" },
+        { "id": "e6", "source": "step-6", "target": "step-7" },
+        { "id": "e7", "source": "step-7", "target": "step-8" },
+        { "id": "e8", "source": "step-8", "target": "end" }
+      ]
+    }
+  }
+}

package/templates/contact-form.flow.json

@@ -0,0 +1,34 @@
+{
+  "version": "1.0.0",
+  "template": true,
+  "name": "Contact Form",
+  "description": "Fill and submit a contact form, assert success message",
+  "tags": ["forms", "contact", "marketing"],
+  "variables": ["BASE_URL", "NAME", "EMAIL", "MESSAGE"],
+  "flow": {
+    "name": "Contact Form",
+    "description": "Fill contact form and verify submission",
+    "appUrl": "{{BASE_URL}}",
+    "graph": {
+      "nodes": [
+        { "id": "start",  "type": "start",  "label": "Start", "url": "{{BASE_URL}}" },
+        { "id": "step-1", "type": "action", "label": "Navigate to contact page", "action": "navigate", "url": "{{BASE_URL}}/contact" },
+        { "id": "step-2", "type": "action", "label": "Fill name", "action": "fill", "selector": "input[name='name'], #name, input[placeholder*='name' i]", "value": "{{NAME}}" },
+        { "id": "step-3", "type": "action", "label": "Fill email", "action": "fill", "selector": "input[type='email'], input[name='email'], #email", "value": "{{EMAIL}}" },
+        { "id": "step-4", "type": "action", "label": "Fill message", "action": "fill", "selector": "textarea, textarea[name='message'], #message", "value": "{{MESSAGE}}" },
+        { "id": "step-5", "type": "action", "label": "Submit form", "action": "click", "selector": "button[type='submit'], input[type='submit'], .submit-btn" },
+        { "id": "step-6", "type": "action", "label": "Assert success message", "action": "assert:text", "value": "Thank you" },
+        { "id": "end",    "type": "end",    "label": "End" }
+      ],
+      "edges": [
+        { "id": "e0", "source": "start",  "target": "step-1" },
+        { "id": "e1", "source": "step-1", "target": "step-2" },
+        { "id": "e2", "source": "step-2", "target": "step-3" },
+        { "id": "e3", "source": "step-3", "target": "step-4" },
+        { "id": "e4", "source": "step-4", "target": "step-5" },
+        { "id": "e5", "source": "step-5", "target": "step-6" },
+        { "id": "e6", "source": "step-6", "target": "end" }
+      ]
+    }
+  }
+}

package/templates/login-basic.flow.json

@@ -0,0 +1,32 @@
+{
+  "version": "1.0.0",
+  "template": true,
+  "name": "Login Basic",
+  "description": "Navigate to login page, fill credentials, submit and assert redirect to dashboard",
+  "tags": ["auth", "login", "starter"],
+  "variables": ["BASE_URL", "EMAIL", "PASSWORD"],
+  "flow": {
+    "name": "Login Basic",
+    "description": "Standard login flow — fill email + password, submit, assert dashboard",
+    "appUrl": "{{BASE_URL}}",
+    "graph": {
+      "nodes": [
+        { "id": "start",  "type": "start",  "label": "Start", "url": "{{BASE_URL}}" },
+        { "id": "step-1", "type": "action", "label": "Navigate to login page", "action": "navigate", "url": "{{BASE_URL}}/login" },
+        { "id": "step-2", "type": "action", "label": "Fill email", "action": "fill", "selector": "input[type='email'], input[name='email'], #email", "value": "{{EMAIL}}" },
+        { "id": "step-3", "type": "action", "label": "Fill password", "action": "fill", "selector": "input[type='password'], input[name='password'], #password", "value": "{{PASSWORD}}" },
+        { "id": "step-4", "type": "action", "label": "Click Sign In", "action": "click", "selector": "button[type='submit'], input[type='submit'], .login-btn, #login-btn" },
+        { "id": "step-5", "type": "action", "label": "Assert redirected away from /login", "action": "assert:url", "value": "/dashboard" },
+        { "id": "end",    "type": "end",    "label": "End" }
+      ],
+      "edges": [
+        { "id": "e0", "source": "start",  "target": "step-1" },
+        { "id": "e1", "source": "step-1", "target": "step-2" },
+        { "id": "e2", "source": "step-2", "target": "step-3" },
+        { "id": "e3", "source": "step-3", "target": "step-4" },
+        { "id": "e4", "source": "step-4", "target": "step-5" },
+        { "id": "e5", "source": "step-5", "target": "end" }
+      ]
+    }
+  }
+}

package/templates/logout.flow.json

@@ -0,0 +1,28 @@
+{
+  "version": "1.0.0",
+  "template": true,
+  "name": "Logout",
+  "description": "Click logout button or link and assert redirect to login/home page",
+  "tags": ["auth", "logout", "smoke"],
+  "variables": ["BASE_URL"],
+  "flow": {
+    "name": "Logout",
+    "description": "Logout and verify session ended",
+    "appUrl": "{{BASE_URL}}",
+    "graph": {
+      "nodes": [
+        { "id": "start",  "type": "start",  "label": "Start", "url": "{{BASE_URL}}" },
+        { "id": "step-1", "type": "action", "label": "Navigate to dashboard", "action": "navigate", "url": "{{BASE_URL}}/dashboard" },
+        { "id": "step-2", "type": "action", "label": "Click logout", "action": "click", "selector": "a[href*='logout'], button:has-text('Logout'), button:has-text('Sign out'), .logout-btn" },
+        { "id": "step-3", "type": "action", "label": "Assert redirected to login", "action": "assert:url", "value": "/login" },
+        { "id": "end",    "type": "end",    "label": "End" }
+      ],
+      "edges": [
+        { "id": "e0", "source": "start",  "target": "step-1" },
+        { "id": "e1", "source": "step-1", "target": "step-2" },
+        { "id": "e2", "source": "step-2", "target": "step-3" },
+        { "id": "e3", "source": "step-3", "target": "end" }
+      ]
+    }
+  }
+}

package/templates/nav-smoke.flow.json

@@ -0,0 +1,38 @@
+{
+  "version": "1.0.0",
+  "template": true,
+  "name": "Navigation Smoke",
+  "description": "Visit key pages (home, about, pricing, contact) and assert each loads without error",
+  "tags": ["smoke", "navigation", "ci"],
+  "variables": ["BASE_URL"],
+  "flow": {
+    "name": "Navigation Smoke",
+    "description": "Visit home, about, pricing, contact — assert no 404s",
+    "appUrl": "{{BASE_URL}}",
+    "graph": {
+      "nodes": [
+        { "id": "start",  "type": "start",  "label": "Start", "url": "{{BASE_URL}}" },
+        { "id": "step-1", "type": "action", "label": "Visit homepage", "action": "navigate", "url": "{{BASE_URL}}" },
+        { "id": "step-2", "type": "action", "label": "Assert homepage loaded", "action": "assert:element", "selector": "body" },
+        { "id": "step-3", "type": "action", "label": "Visit /about", "action": "navigate", "url": "{{BASE_URL}}/about" },
+        { "id": "step-4", "type": "action", "label": "Assert about page loaded", "action": "assert:element", "selector": "body" },
+        { "id": "step-5", "type": "action", "label": "Visit /pricing", "action": "navigate", "url": "{{BASE_URL}}/pricing" },
+        { "id": "step-6", "type": "action", "label": "Assert pricing page loaded", "action": "assert:element", "selector": "body" },
+        { "id": "step-7", "type": "action", "label": "Visit /contact", "action": "navigate", "url": "{{BASE_URL}}/contact" },
+        { "id": "step-8", "type": "action", "label": "Assert contact page loaded", "action": "assert:element", "selector": "body" },
+        { "id": "end",    "type": "end",    "label": "End" }
+      ],
+      "edges": [
+        { "id": "e0", "source": "start",  "target": "step-1" },
+        { "id": "e1", "source": "step-1", "target": "step-2" },
+        { "id": "e2", "source": "step-2", "target": "step-3" },
+        { "id": "e3", "source": "step-3", "target": "step-4" },
+        { "id": "e4", "source": "step-4", "target": "step-5" },
+        { "id": "e5", "source": "step-5", "target": "step-6" },
+        { "id": "e6", "source": "step-6", "target": "step-7" },
+        { "id": "e7", "source": "step-7", "target": "step-8" },
+        { "id": "e8", "source": "step-8", "target": "end" }
+      ]
+    }
+  }
+}