devglide 0.1.1

package/src/apps/test/src/routes/trigger.ts

@@ -0,0 +1,285 @@
+import path from "path";
+import { Router } from "express";
+import type { Request, Response, Router as RouterType } from "express";
+import { ScenarioManager } from "../services/scenario-manager.js";
+import { ScenarioStore } from "../services/scenario-store.js";
+
+export const triggerRouter: RouterType = Router();
+const scenarioManager = ScenarioManager.getInstance();
+
+// ── SSE client management ──────────────────────────────────────────────────
+// Map of target key -> Set of SSE response objects
+const sseClients = new Map<string, Set<Response>>();
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+
+// Heartbeat timer — send a comment to all connected SSE clients every 30s
+const heartbeatTimer = setInterval(() => {
+  for (const clientSet of sseClients.values()) {
+    for (const res of clientSet) {
+      try {
+        res.write(": heartbeat\n\n");
+      } catch {
+        // client already gone — will be cleaned up on close
+      }
+    }
+  }
+}, HEARTBEAT_INTERVAL_MS);
+heartbeatTimer.unref(); // don't keep the process alive just for heartbeats
+
+/**
+ * Broadcast a scenario to all SSE clients listening on the given target.
+ */
+function broadcastScenario(target: string, scenario: unknown): void {
+  const key = scenarioManager.resolveTargetKey(target);
+  const clients = sseClients.get(key);
+  if (!clients || clients.size === 0) return;
+
+  const payload = `data: ${JSON.stringify(scenario)}\n\n`;
+  for (const res of clients) {
+    try {
+      res.write(payload);
+    } catch {
+      // ignore — will be cleaned up on close
+    }
+  }
+}
+
+/**
+ * GET /api/trigger/status — Return pending scenario count.
+ * Accepts optional ?projectPath= query param to filter by project.
+ * Returns 0 if no project is specified.
+ */
+triggerRouter.get("/status", (req: Request, res: Response) => {
+  const projectPath = (req.query.projectPath as string) || null;
+  res.json({ pendingScenarios: scenarioManager.getPendingCountForProject(projectPath) });
+});
+
+/**
+ * GET /api/trigger/commands — Return the command catalog.
+ */
+triggerRouter.get("/commands", (_req: Request, res: Response) => {
+  res.json(scenarioManager.getCommandsCatalog());
+});
+
+interface ScenarioBody {
+  name?: string;
+  description?: string;
+  steps?: Array<{
+    command: string;
+    selector?: string;
+    text?: string;
+    value?: string;
+    timeout?: number;
+    ms?: number;
+    clear?: boolean;
+    contains?: boolean;
+    path?: string;
+  }>;
+  target?: string;
+}
+
+/**
+ * POST /api/trigger/scenarios — Submit a scenario for browser execution.
+ * If SSE clients are listening for this target, the scenario is broadcast
+ * directly rather than being queued (SSE client will dequeue it).
+ */
+triggerRouter.post("/scenarios", (req: Request, res: Response) => {
+  const body = req.body as ScenarioBody;
+
+  if (!body.steps || body.steps.length === 0) {
+    res.status(400).end();
+    return;
+  }
+
+  const saved = scenarioManager.submitScenario(body);
+  // Broadcast to any SSE clients listening for this target
+  if (saved.target) {
+    broadcastScenario(saved.target, saved);
+  }
+  res.status(201).json(saved);
+});
+
+/**
+ * GET /api/trigger/scenarios/stream?target=... — SSE stream for scenario delivery.
+ * Sends any pending scenario immediately on connect, then pushes new scenarios
+ * as they are submitted. Heartbeat comment every 30 seconds.
+ */
+triggerRouter.get("/scenarios/stream", (req: Request, res: Response) => {
+  const target = (req.query.target as string) || "";
+
+  // Register the target so targetKey resolution works for app-name shortcuts
+  scenarioManager.registerTarget(target);
+
+  // Set up SSE headers
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.flushHeaders();
+
+  // Deliver any already-queued scenario immediately
+  const pending = scenarioManager.dequeueScenario(target);
+  if (pending) {
+    res.write(`data: ${JSON.stringify(pending)}\n\n`);
+  }
+
+  // Register this client for future broadcasts
+  const key = scenarioManager.resolveTargetKey(target);
+  if (!sseClients.has(key)) {
+    sseClients.set(key, new Set());
+  }
+  sseClients.get(key)!.add(res);
+
+  // Clean up on disconnect
+  req.on("close", () => {
+    const clientSet = sseClients.get(key);
+    if (clientSet) {
+      clientSet.delete(res);
+      if (clientSet.size === 0) {
+        sseClients.delete(key);
+      }
+    }
+  });
+});
+
+/**
+ * GET /api/trigger/scenarios/poll?target=... — Check for a queued scenario.
+ * Returns 200 with scenario if one is available, 204 otherwise.
+ * Kept for backwards compatibility — SSE stream is the preferred mechanism.
+ */
+triggerRouter.get("/scenarios/poll", (req: Request, res: Response) => {
+  const target = (req.query.target as string) || "";
+
+  const queued = scenarioManager.dequeueScenario(target);
+  if (queued) {
+    res.status(200).json(queued);
+  } else {
+    res.status(204).end();
+  }
+});
+
+/**
+ * GET /api/trigger/scenarios/results — List all recent results.
+ * Must be registered before the :id param routes to avoid ambiguity.
+ */
+triggerRouter.get("/scenarios/results", (req: Request, res: Response) => {
+  const projectPath = req.query.projectPath as string | undefined;
+  res.json(scenarioManager.listResults(projectPath || null));
+});
+
+/**
+ * POST /api/trigger/scenarios/:id/result — Receive result from browser after scenario completes.
+ */
+triggerRouter.post("/scenarios/:id/result", (req: Request, res: Response) => {
+  const id = req.params.id as string;
+  const { status, failedStep, error, duration } = req.body as {
+    status?: string;
+    failedStep?: number;
+    error?: string;
+    duration?: number;
+  };
+
+  if (status !== "passed" && status !== "failed") {
+    res.status(400).end();
+    return;
+  }
+
+  const result = scenarioManager.setResult(id, { status, failedStep, error, duration });
+  res.status(201).json(result);
+});
+
+/**
+ * GET /api/trigger/scenarios/:id/result — Retrieve result for a scenario.
+ */
+triggerRouter.get("/scenarios/:id/result", (req: Request, res: Response) => {
+  const id = req.params.id as string;
+  const result = scenarioManager.getResult(id);
+  if (!result) {
+    res.status(404).end();
+    return;
+  }
+  res.json(result);
+});
+
+const scenarioStore = ScenarioStore.getInstance();
+
+/**
+ * GET /api/trigger/scenarios/saved — List saved scenarios scoped to a target.
+ * Requires ?target= (exact match) or ?projectPath= (matches exact path or basename).
+ * Returns empty array if neither is provided.
+ */
+triggerRouter.get("/scenarios/saved", async (req: Request, res: Response) => {
+  const target = req.query.target as string | undefined;
+  const projectPath = req.query.projectPath as string | undefined;
+
+  if (target) {
+    res.json(await scenarioStore.list(target));
+  } else if (projectPath) {
+    const basename = path.basename(projectPath);
+    const byPath = await scenarioStore.list(projectPath);
+    const byName = basename !== projectPath ? await scenarioStore.list(basename) : [];
+    // Dedupe in case both match the same scenarios
+    const seen = new Set(byPath.map((s) => s.id));
+    res.json([...byPath, ...byName.filter((s) => !seen.has(s.id))]);
+  } else {
+    res.json([]);
+  }
+});
+
+/**
+ * POST /api/trigger/scenarios/save — Save a new scenario.
+ */
+triggerRouter.post("/scenarios/save", async (req: Request, res: Response) => {
+  const body = req.body as ScenarioBody;
+
+  if (!body.name || !body.target || !body.steps || body.steps.length === 0) {
+    res.status(400).end();
+    return;
+  }
+
+  const saved = await scenarioStore.save({
+    name: body.name,
+    description: body.description,
+    target: body.target,
+    steps: body.steps,
+  });
+  res.status(201).json(saved);
+});
+
+/**
+ * DELETE /api/trigger/scenarios/saved/:id — Delete a saved scenario by id.
+ */
+triggerRouter.delete("/scenarios/saved/:id", async (req: Request, res: Response) => {
+  const id = req.params.id as string;
+  const deleted = await scenarioStore.delete(id);
+  if (!deleted) {
+    res.status(404).end();
+    return;
+  }
+  res.status(204).end();
+});
+
+/**
+ * POST /api/trigger/scenarios/saved/:id/run — Re-run a saved scenario.
+ */
+triggerRouter.post("/scenarios/saved/:id/run", async (req: Request, res: Response) => {
+  const id = req.params.id as string;
+  const scenario = await scenarioStore.get(id);
+  if (!scenario) {
+    res.status(404).end();
+    return;
+  }
+
+  await scenarioStore.markRun(id);
+
+  const queued = scenarioManager.submitScenario({
+    name: scenario.name,
+    steps: scenario.steps,
+    target: scenario.target,
+  });
+  // Broadcast to any SSE clients listening for this target
+  if (queued.target) {
+    broadcastScenario(queued.target, queued);
+  }
+  res.status(201).json(queued);
+});

package/src/apps/test/src/services/scenario-broadcaster.ts

@@ -0,0 +1,60 @@
+import type { Response } from 'express';
+
+/**
+ * Manages SSE client connections, heartbeats, and broadcast logic
+ * for scenario delivery to browser targets.
+ */
+export class ScenarioBroadcaster {
+  private static instance: ScenarioBroadcaster;
+  private clients = new Map<string, Set<Response>>();
+  private heartbeatTimer: ReturnType<typeof setInterval>;
+
+  private constructor() {
+    this.heartbeatTimer = setInterval(() => {
+      for (const clientSet of this.clients.values()) {
+        for (const res of clientSet) {
+          try { res.write(': heartbeat\n\n'); } catch { /* cleaned up on close */ }
+        }
+      }
+    }, 30_000);
+    this.heartbeatTimer.unref();
+  }
+
+  static getInstance(): ScenarioBroadcaster {
+    if (!ScenarioBroadcaster.instance) {
+      ScenarioBroadcaster.instance = new ScenarioBroadcaster();
+    }
+    return ScenarioBroadcaster.instance;
+  }
+
+  /** Add an SSE client for a given target key. Returns a cleanup function. */
+  addClient(key: string, res: Response): () => void {
+    if (!this.clients.has(key)) {
+      this.clients.set(key, new Set());
+    }
+    this.clients.get(key)!.add(res);
+
+    return () => {
+      const clientSet = this.clients.get(key);
+      if (clientSet) {
+        clientSet.delete(res);
+        if (clientSet.size === 0) this.clients.delete(key);
+      }
+    };
+  }
+
+  /** Broadcast a scenario payload to all SSE clients for a target key. */
+  broadcast(key: string, scenario: unknown): void {
+    const clients = this.clients.get(key);
+    if (!clients || clients.size === 0) return;
+    const payload = `data: ${JSON.stringify(scenario)}\n\n`;
+    for (const res of clients) {
+      try { res.write(payload); } catch { /* cleaned up on close */ }
+    }
+  }
+
+  shutdown(): void {
+    clearInterval(this.heartbeatTimer);
+    this.clients.clear();
+  }
+}

package/src/apps/test/src/services/scenario-manager.ts

@@ -0,0 +1,361 @@
+import path from "path";
+import { v4 as uuidv4 } from "uuid";
+
+interface TriggerStep {
+  command: string;
+  selector?: string;
+  text?: string;
+  value?: string;
+  timeout?: number;
+  ms?: number;
+  clear?: boolean;
+  contains?: boolean;
+  path?: string;
+}
+
+interface Scenario {
+  id: string;
+  name?: string;
+  description?: string;
+  steps: TriggerStep[];
+  target?: string;
+  createdAt: string;
+}
+
+export interface ScenarioResult {
+  id: string;
+  status: "passed" | "failed";
+  failedStep?: number;
+  error?: string;
+  duration?: number;
+  target?: string;
+  createdAt: string;
+}
+
+/**
+ * In-memory scenario store with 5-minute auto-cleanup.
+ */
+export class ScenarioManager {
+  private static instance: ScenarioManager;
+
+  private scenariosByTarget = new Map<string, Scenario[]>();
+  private scenarioTargets = new Map<string, string>();
+  private results = new Map<string, ScenarioResult>();
+  private knownTargets = new Set<string>();
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  static getInstance(): ScenarioManager {
+    if (!ScenarioManager.instance) {
+      ScenarioManager.instance = new ScenarioManager();
+    }
+    return ScenarioManager.instance;
+  }
+
+  submitScenario(body: {
+    name?: string;
+    description?: string;
+    steps?: TriggerStep[];
+    target?: string;
+  }): Scenario {
+    const scenario: Scenario = {
+      id: uuidv4(),
+      name: body.name,
+      description: body.description,
+      steps: body.steps || [],
+      target: body.target,
+      createdAt: new Date().toISOString(),
+    };
+
+    const key = this.targetKey(scenario.target);
+
+    const queue = this.scenariosByTarget.get(key) || [];
+    queue.push(scenario);
+    this.scenariosByTarget.set(key, queue);
+
+    if (scenario.target) {
+      this.scenarioTargets.set(scenario.id, key);
+    }
+
+    return scenario;
+  }
+
+  setResult(id: string, result: Omit<ScenarioResult, "id" | "createdAt" | "target">): ScenarioResult {
+    const entry: ScenarioResult = {
+      id,
+      ...result,
+      target: this.scenarioTargets.get(id),
+      createdAt: new Date().toISOString(),
+    };
+    this.results.set(id, entry);
+    this.scenarioTargets.delete(id);
+    return entry;
+  }
+
+  getResult(id: string): ScenarioResult | undefined {
+    return this.results.get(id);
+  }
+
+  listResults(projectPath?: string | null): ScenarioResult[] {
+    if (!projectPath) return [];
+    const all = Array.from(this.results.values());
+    const prefix = projectPath;
+    const basename = path.basename(projectPath);
+    return all.filter((r) => {
+      if (!r.target) return false;
+      return r.target.startsWith(prefix) || r.target === basename;
+    });
+  }
+
+  dequeueScenario(target: string): Scenario | undefined {
+    // Track every absolute path that browsers poll with
+    if (path.isAbsolute(target)) {
+      this.knownTargets.add(target);
+    }
+
+    const key = this.targetKey(target);
+    const queue = this.scenariosByTarget.get(key);
+    if (queue && queue.length > 0) {
+      const scenario = queue.shift()!;
+      if (queue.length === 0) this.scenariosByTarget.delete(key);
+      return scenario;
+    }
+
+    // Fallback: browser polls with absolute path, check for unresolved app-name keys
+    if (path.isAbsolute(target)) {
+      const basename = path.basename(target);
+      const fallbackQueue = this.scenariosByTarget.get(basename);
+      if (fallbackQueue && fallbackQueue.length > 0) {
+        const scenario = fallbackQueue.shift()!;
+        if (fallbackQueue.length === 0) this.scenariosByTarget.delete(basename);
+        return scenario;
+      }
+    }
+
+    return undefined;
+  }
+
+  startCleanup(): void {
+    if (this.cleanupInterval) return;
+    this.cleanupInterval = setInterval(() => this.cleanupStale(), 60_000);
+  }
+
+  stopCleanup(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  private cleanupStale(): void {
+    const cutoff = Date.now() - 5 * 60 * 1000;
+    for (const [key, queue] of this.scenariosByTarget) {
+      const filtered = queue.filter(
+        (s) => new Date(s.createdAt).getTime() >= cutoff
+      );
+      if (filtered.length === 0) {
+        this.scenariosByTarget.delete(key);
+      } else {
+        this.scenariosByTarget.set(key, filtered);
+      }
+    }
+    for (const [id, result] of this.results) {
+      if (new Date(result.createdAt).getTime() < cutoff) {
+        this.results.delete(id);
+      }
+    }
+    // Clean orphaned target mappings (scenario submitted but never completed)
+    for (const id of this.scenarioTargets.keys()) {
+      if (!this.results.has(id)) {
+        // Check if scenario is still queued
+        let found = false;
+        for (const queue of this.scenariosByTarget.values()) {
+          if (queue.some((s) => s.id === id)) { found = true; break; }
+        }
+        if (!found) this.scenarioTargets.delete(id);
+      }
+    }
+  }
+
+  /**
+   * Public wrapper for targetKey — used by the SSE broadcast layer
+   * to resolve a target string to its canonical key.
+   */
+  resolveTargetKey(target?: string): string {
+    return this.targetKey(target);
+  }
+
+  /**
+   * Register an absolute target path as known (normally done by dequeue,
+   * but SSE clients also need to register themselves).
+   */
+  registerTarget(target: string): void {
+    if (path.isAbsolute(target)) {
+      this.knownTargets.add(target);
+    }
+  }
+
+  private targetKey(target?: string): string {
+    if (!target) return "";
+    // Already an absolute path — use as-is
+    if (path.isAbsolute(target)) return target;
+    // App name — search knownTargets for a path ending with /<target>
+    const suffix = `/${target}`;
+    for (const known of this.knownTargets) {
+      if (known.endsWith(suffix)) return known;
+    }
+    // No match yet — return the app name as-is (fallback at dequeue time)
+    return target;
+  }
+
+  getPendingCount(): number {
+    let total = 0;
+    for (const queue of this.scenariosByTarget.values()) {
+      total += queue.length;
+    }
+    return total;
+  }
+
+  getPendingCountForProject(projectPath: string | null): number {
+    if (!projectPath) return 0;
+    let count = 0;
+    for (const [target, scenarios] of this.scenariosByTarget) {
+      if (target.startsWith(projectPath)) count += scenarios.length;
+    }
+    return count;
+  }
+
+  getCommandsCatalog(): Record<string, unknown> {
+    return {
+      description:
+        "Console Trigger DSL — commands for browser UI automation via POST /api/trigger/scenarios",
+      usage:
+        "POST a JSON object with 'name' (string), optional 'description' (string), " +
+        "'target' (string), and 'steps' (array of command objects). Each step " +
+        "must have a 'command' field plus the required parameters listed below. Steps " +
+        "execute sequentially; execution stops on first failure. The 'target' field " +
+        "identifies which browser should run the scenario. It can be an absolute " +
+        "filesystem path (matching the devtools.js?target= query param, " +
+        "e.g. \"/home/user/devglide/apps/kanban\") or a simple app name " +
+        "(e.g. \"kanban\", \"dashboard\") which is automatically resolved to the " +
+        "full path once the browser has polled at least once. " +
+        "Use 'logPath' to check the current URL, 'logBody' and 'logHead' to inspect " +
+        "the rendered HTML (captured by console-sniffer from devglide-log). " +
+        "IMPORTANT: Prefer interacting with HTML elements (clicking links, buttons, nav items) " +
+        "over using 'navigate'. The 'navigate' command should only be used when there is no " +
+        "interactive element available — e.g. for the initial deep-link to a URL before the " +
+        "test starts. Normal in-app navigation must be done via click/type/select on real UI " +
+        "elements, because this reflects actual user behaviour. Overusing 'navigate' bypasses " +
+        "the UI interaction layer and can cause false positives where the scenario passes but " +
+        "the UI flow was never actually tested. " +
+        "When 'navigate' is used, scenario state is automatically persisted to localStorage " +
+        "and resumed after page reload. " +
+        "It is recommended to use persistent=true on the console-sniffer script tag when using 'navigate'.",
+      commands: [
+        cmd("click", "Click a DOM element", {
+          selector: param("string", true, "CSS selector for the target element"),
+        }),
+        cmd("dblclick", "Double-click a DOM element", {
+          selector: param("string", true, "CSS selector for the target element"),
+        }),
+        cmd(
+          "type",
+          "Type text into an input or textarea. Clears the field first by default.",
+          {
+            selector: param("string", true, "CSS selector for the input element"),
+            text: param("string", true, "Text to type"),
+            clear: param("boolean", false, "Clear the field before typing (default: true)"),
+          }
+        ),
+        cmd("select", "Select an option in a <select> dropdown by its value attribute", {
+          selector: param("string", true, "CSS selector for the <select> element"),
+          value: param("string", true, "The option value to select"),
+        }),
+        cmd("wait", "Pause execution for a fixed number of milliseconds", {
+          ms: param("integer", true, "Number of milliseconds to wait"),
+        }),
+        cmd(
+          "waitFor",
+          "Wait until an element appears in the DOM (polls until found or timeout)",
+          {
+            selector: param("string", true, "CSS selector to wait for"),
+            timeout: param("integer", false, "Max wait time in ms (default: 5000)"),
+          }
+        ),
+        cmd(
+          "waitForHidden",
+          "Wait until an element disappears from the DOM or becomes hidden",
+          {
+            selector: param("string", true, "CSS selector to wait for disappearance"),
+            timeout: param("integer", false, "Max wait time in ms (default: 5000)"),
+          }
+        ),
+        cmd(
+          "find",
+          "Alias for waitFor — locate a DOM element, retrying until found or timeout.",
+          {
+            selector: param("string", true, "CSS selector for the element"),
+            timeout: param("integer", false, "Max wait time in ms (default: 5000)"),
+          }
+        ),
+        cmd(
+          "assertExists",
+          "Assert that an element currently exists in the DOM. Fails immediately if not found.",
+          {
+            selector: param("string", true, "CSS selector to check"),
+          }
+        ),
+        cmd(
+          "assertText",
+          "Assert that an element's text content matches or contains the expected text",
+          {
+            selector: param("string", true, "CSS selector for the element"),
+            text: param("string", true, "Expected text"),
+            contains: param(
+              "boolean",
+              false,
+              "If true (default), checks substring match. If false, checks exact match."
+            ),
+          }
+        ),
+        cmd(
+          "logPath",
+          "Log the current page URL to the console. Captured by console-sniffer so the backend can check the URL from the log file.",
+          {}
+        ),
+        cmd(
+          "logBody",
+          "Log the current page body HTML to the console. Captured by console-sniffer so the backend can inspect the rendered DOM body.",
+          {}
+        ),
+        cmd(
+          "logHead",
+          "Log the current page head HTML to the console. Captured by console-sniffer so the backend can inspect the page head element.",
+          {}
+        ),
+        cmd(
+          "navigate",
+          "Navigate the browser to a given path. Use sparingly — only when no clickable " +
+            "element can achieve the navigation (e.g. initial page load or deep-linking " +
+            "before a test begins). For normal in-app navigation, prefer clicking links " +
+            "or buttons instead, as this better reflects real user behaviour and avoids " +
+            "false positives.",
+          {
+            path: param("string", true, "The URL path to navigate to (e.g. /dashboard, /users/123)"),
+          }
+        ),
+      ],
+    };
+  }
+}
+
+function param(type: string, required: boolean, description: string) {
+  return { type, required, description };
+}
+
+function cmd(
+  command: string,
+  description: string,
+  parameters: Record<string, { type: string; required: boolean; description: string }>
+) {
+  return { command, description, parameters };
+}