zefiro 0.9.0 → 0.10.0

package/README.md

@@ -17,7 +17,7 @@ bun add -g zefiro
 zefiro init
 
 # 2. Explore a running application
-zefiro scan          # static AST scan (optional)
+zefiro explore
 ```
 
 ---
@@ -52,27 +52,18 @@ On re-run (`.qai/zefiro/agents/` already exists), preserves your existing setup
 **After init:**
 1. Generate `.qai/zefiro/context.md` using the `init-agent` prompt in your AI tool, or via MCP (`zefiro_scan_codebase`)
 2. Review the generated context
-3. Run `zefiro scan`
+3. Run `zefiro explore`
 
 ---
 
-### `zefiro scan`
+### `zefiro explore`
 
-Scan your codebase AST — extracts routes, components, hooks, imports, and dependencies.
+Explore a running web application via browser automation. Navigates pages, captures screenshots, and generates structured documentation.
 
 ```bash
-zefiro scan
-zefiro scan --scan-dir src/app
-zefiro scan --output custom-scan.json
-zefiro scan --no-cache
+zefiro explore
 ```
 
-| Option | Description |
-|--------|-------------|
-| `--output <file>` | Output file (default: `.qai/zefiro/ast-scan.json`) |
-| `--scan-dir <dir>` | Directory to scan (overrides config) |
-| `--no-cache` | Disable file-level MD5 caching |
-
 ---
 
 ### `zefiro auth`

package/dist/cli-5w708rbb.js

@@ -0,0 +1,167 @@
+// src/browser/url-tracker.ts
+import { createHash } from "node:crypto";
+var SKIP_EXTENSIONS = new Set([
+  ".pdf",
+  ".zip",
+  ".csv",
+  ".xlsx",
+  ".xls",
+  ".doc",
+  ".docx",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".svg",
+  ".ico",
+  ".webp",
+  ".mp3",
+  ".mp4",
+  ".wav",
+  ".avi",
+  ".mov"
+]);
+var SKIP_PATTERNS = [
+  /\/logout/i,
+  /\/signout/i,
+  /\/api\//i,
+  /\/auth\/callback/i,
+  /\/oauth/i,
+  /javascript:/i,
+  /mailto:/i,
+  /tel:/i,
+  /#$/
+];
+function normalizeUrl(url, baseUrl) {
+  try {
+    const resolved = new URL(url, baseUrl);
+    resolved.hash = "";
+    let normalized = resolved.href;
+    if (normalized.endsWith("/") && resolved.pathname !== "/") {
+      normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+  } catch {
+    return url;
+  }
+}
+function shouldVisit(url, baseUrl, excludePatterns, visited) {
+  try {
+    const parsed = new URL(url);
+    const base = new URL(baseUrl);
+    if (parsed.origin !== base.origin)
+      return false;
+    const normalized = normalizeUrl(url, baseUrl);
+    if (visited.has(normalized))
+      return false;
+    const ext = parsed.pathname.match(/\.\w+$/)?.[0]?.toLowerCase();
+    if (ext && SKIP_EXTENSIONS.has(ext))
+      return false;
+    for (const pattern of SKIP_PATTERNS) {
+      if (pattern.test(url))
+        return false;
+    }
+    for (const pattern of excludePatterns) {
+      try {
+        if (new RegExp(pattern).test(url))
+          return false;
+      } catch {
+        if (url.includes(pattern))
+          return false;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function extractHrefsFromElements(elements) {
+  return elements.filter((el) => el.role === "link").map((el) => el.ref);
+}
+function urlToSlug(url, baseUrl) {
+  try {
+    const parsed = new URL(url, baseUrl);
+    const path = parsed.pathname;
+    if (path === "/" || path === "")
+      return "home";
+    return path.replace(/^\/|\/$/g, "").replace(/\//g, "-").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").toLowerCase();
+  } catch {
+    return "unknown";
+  }
+}
+function buildTopology(pages) {
+  const root = { path: "/", slug: "root", stableId: generatePageId("root"), title: "Application", children: [] };
+  const nodeMap = new Map;
+  nodeMap.set("/", root);
+  const sortedPages = Array.from(pages.values()).filter((p) => p.status === "visited").sort((a, b) => a.depth - b.depth);
+  for (const page of sortedPages) {
+    const segments = page.path.replace(/^\/|\/$/g, "").split("/").filter(Boolean);
+    const node = {
+      path: page.path,
+      slug: page.slug,
+      stableId: page.stableId,
+      title: page.title || page.slug,
+      children: []
+    };
+    let parentPath = "/";
+    if (segments.length > 1) {
+      parentPath = "/" + segments.slice(0, -1).join("/");
+    }
+    const parent = nodeMap.get(parentPath) ?? root;
+    parent.children.push(node);
+    nodeMap.set(page.path, node);
+  }
+  return root.children;
+}
+function labelHash(label) {
+  return createHash("sha256").update(label.trim().toLowerCase()).digest("hex").slice(0, 8);
+}
+function toKebab(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function generatePageId(slug) {
+  return `page:${slug}`;
+}
+function generateSectionId(pageSlug, sectionName) {
+  return `section:${pageSlug}:${toKebab(sectionName)}`;
+}
+function generateElementId(pageSlug, role, label) {
+  return `element:${pageSlug}:${role}:${labelHash(label)}`;
+}
+function generateEdgeId(sourceId, targetId) {
+  return `edge:${sourceId}->${targetId}`;
+}
+function classifySectionType(sectionType) {
+  const t = sectionType.toLowerCase();
+  if (t.includes("modal") || t.includes("dialog") || t.includes("popup"))
+    return "dialog";
+  if (t.includes("form"))
+    return "form";
+  if (t.includes("table") || t.includes("list") || t.includes("grid"))
+    return "table";
+  if (t.includes("tab"))
+    return "tab";
+  if (t.includes("filter") || t.includes("search"))
+    return "filter";
+  if (t.includes("action") || t.includes("toolbar") || t.includes("button"))
+    return "action";
+  if (t.includes("panel") || t.includes("card") || t.includes("section"))
+    return "page";
+  return "page";
+}
+function topologyToAscii(nodes, prefix = "") {
+  const lines = [];
+  for (let i = 0;i < nodes.length; i++) {
+    const isLast = i === nodes.length - 1;
+    const connector = isLast ? "└── " : "├── ";
+    const childPrefix = isLast ? "    " : "│   ";
+    lines.push(`${prefix}${connector}${nodes[i].path} — ${nodes[i].title}`);
+    if (nodes[i].children.length > 0) {
+      lines.push(topologyToAscii(nodes[i].children, prefix + childPrefix));
+    }
+  }
+  return lines.join(`
+`);
+}
+
+export { normalizeUrl, shouldVisit, extractHrefsFromElements, urlToSlug, buildTopology, generatePageId, generateSectionId, generateElementId, generateEdgeId, classifySectionType, topologyToAscii };

package/dist/cli-7hvj61ht.js

@@ -0,0 +1,150 @@
+import {
+  AgentBrowser,
+  authenticate,
+  error,
+  info,
+  success,
+  verbose
+} from "./cli-b26q1e27.js";
+import {
+  generateSectionMarkdown
+} from "./cli-kjyet1n8.js";
+import {
+  ensureDir,
+  writeFile
+} from "./cli-zvk8gwe4.js";
+import {
+  buildTopology,
+  classifySectionType,
+  extractHrefsFromElements,
+  generateElementId,
+  generatePageId,
+  generateSectionId,
+  normalizeUrl,
+  shouldVisit,
+  urlToSlug
+} from "./cli-5w708rbb.js";
+
+// src/browser/explorer.ts
+import { join } from "node:path";
+async function runExploration(config) {
+  const state = {
+    baseUrl: config.baseUrl,
+    startedAt: new Date().toISOString(),
+    pages: new Map,
+    queue: [],
+    topology: []
+  };
+  const browser = new AgentBrowser({
+    session: config.sessionName,
+    headed: config.headed || config.auth.method === "manual"
+  });
+  const visited = new Set;
+  const screenshotsDir = join(config.outputDir, "screenshots");
+  const sectionsDir = join(config.outputDir, "sections");
+  ensureDir(screenshotsDir);
+  ensureDir(sectionsDir);
+  try {
+    await authenticate(browser, config);
+    await browser.setViewport(1440, 900);
+    const startUrl = normalizeUrl(config.baseUrl, config.baseUrl);
+    state.queue.push(startUrl);
+    let pageCount = 0;
+    while (state.queue.length > 0 && pageCount < config.maxPages) {
+      const url = state.queue.shift();
+      const normalized = normalizeUrl(url, config.baseUrl);
+      if (visited.has(normalized))
+        continue;
+      if (!shouldVisit(url, config.baseUrl, config.excludePatterns, visited)) {
+        continue;
+      }
+      visited.add(normalized);
+      const slug = urlToSlug(url, config.baseUrl);
+      info(`[${pageCount + 1}/${config.maxPages}] Exploring: ${url}`);
+      const page = {
+        url: normalized,
+        path: new URL(normalized).pathname,
+        title: "",
+        slug,
+        stableId: generatePageId(slug),
+        depth: 0,
+        screenshot: "",
+        elements: [],
+        outgoingLinks: [],
+        status: "pending"
+      };
+      try {
+        await browser.open(url);
+        await browser.waitForLoad(config.waitStrategy, config.waitDelay);
+        const actualUrl = await browser.getUrl();
+        const actualNormalized = normalizeUrl(actualUrl, config.baseUrl);
+        if (actualNormalized !== normalized) {
+          page.url = actualNormalized;
+          page.path = new URL(actualNormalized).pathname;
+          page.slug = urlToSlug(actualUrl, config.baseUrl);
+          page.stableId = generatePageId(page.slug);
+          if (visited.has(actualNormalized)) {
+            verbose(`  Redirected to already-visited ${actualUrl}, skipping`);
+            continue;
+          }
+          visited.add(actualNormalized);
+        }
+        page.title = await browser.getTitle();
+        const slugDir = join(screenshotsDir, page.slug);
+        ensureDir(slugDir);
+        const screenshotPath = join(slugDir, "01-default.png");
+        await browser.screenshot(screenshotPath);
+        page.screenshot = `screenshots/${page.slug}/01-default.png`;
+        page.elements = await browser.snapshot();
+        for (const el of page.elements) {
+          el.stableId = generateElementId(page.slug, el.role, el.label);
+        }
+        if (page.analysis?.sections) {
+          for (const section of page.analysis.sections) {
+            section.stableId = generateSectionId(page.slug, section.name);
+            section.nodeType = classifySectionType(section.type);
+          }
+        }
+        const linkRefs = extractHrefsFromElements(page.elements);
+        for (const ref of linkRefs) {
+          try {
+            const href = await browser.getAttribute(ref, "href");
+            if (href) {
+              const linkUrl = normalizeUrl(href, actualUrl);
+              page.outgoingLinks.push(linkUrl);
+              if (shouldVisit(linkUrl, config.baseUrl, config.excludePatterns, visited)) {
+                state.queue.push(linkUrl);
+              }
+            }
+          } catch {}
+        }
+        page.depth = calculateDepth(page.path);
+        const relatedPages = Array.from(state.pages.values()).filter((p) => p.status === "visited").map((p) => ({ slug: p.slug, name: p.analysis?.pageName ?? p.title, path: p.path }));
+        const markdown = generateSectionMarkdown(page, relatedPages);
+        writeFile(join(sectionsDir, `${page.slug}.md`), markdown);
+        page.status = "visited";
+        page.visitedAt = new Date().toISOString();
+        pageCount++;
+        success(`  ${page.title || page.slug} — ${page.elements.length} elements, ${page.outgoingLinks.length} links`);
+      } catch (err) {
+        page.status = "error";
+        page.error = err.message;
+        error(`  Error: ${err.message}`);
+      }
+      state.pages.set(page.url, page);
+    }
+    state.topology = buildTopology(state.pages);
+    state.completedAt = new Date().toISOString();
+    await browser.close();
+  } catch (err) {
+    error(`Exploration failed: ${err.message}`);
+    await browser.close();
+    throw err;
+  }
+  return state;
+}
+function calculateDepth(path) {
+  const segments = path.replace(/^\/|\/$/g, "").split("/").filter(Boolean);
+  return segments.length;
+}
+export { runExploration };

package/dist/cli-ewbvvxm8.js

@@ -0,0 +1,145 @@
+import {
+  classifySectionType,
+  generateEdgeId,
+  generateSectionId
+} from "./cli-5w708rbb.js";
+
+// src/browser/graph-builder.ts
+function toReportNodeType(sectionType) {
+  const classified = classifySectionType(sectionType);
+  switch (classified) {
+    case "form":
+      return "page";
+    case "table":
+      return "page";
+    case "tab":
+      return "page";
+    default:
+      return classified;
+  }
+}
+var SECTION_ICONS = {
+  home: "home",
+  dashboard: "layout-dashboard",
+  settings: "settings",
+  auth: "shield",
+  login: "log-in",
+  users: "users",
+  admin: "shield-check",
+  reports: "bar-chart",
+  analytics: "trending-up"
+};
+function guessIcon(slug) {
+  for (const [key, icon] of Object.entries(SECTION_ICONS)) {
+    if (slug.includes(key))
+      return icon;
+  }
+  return;
+}
+function buildReportGraph(state) {
+  const nodes = [];
+  const edges = [];
+  const edgeSet = new Set;
+  const visitedPages = Array.from(state.pages.values()).filter((p) => p.status === "visited");
+  const slugToStableId = new Map;
+  for (const page of visitedPages) {
+    slugToStableId.set(page.slug, page.stableId);
+    nodes.push({
+      id: page.stableId,
+      sectionSlug: page.slug,
+      type: "page",
+      label: page.analysis?.pageName ?? page.title ?? page.slug,
+      description: page.analysis?.description ?? `Page at ${page.path}`,
+      route: page.path,
+      screenshotFilename: "01-default.png"
+    });
+    if (page.analysis?.sections) {
+      for (const section of page.analysis.sections) {
+        const sectionId = section.stableId ?? generateSectionId(page.slug, section.name);
+        const nodeType = toReportNodeType(section.type);
+        nodes.push({
+          id: sectionId,
+          sectionSlug: page.slug,
+          type: nodeType,
+          label: section.name,
+          description: `${section.type} section with ${section.elements.length} elements`
+        });
+        const containEdgeId = generateEdgeId(page.stableId, sectionId);
+        if (!edgeSet.has(containEdgeId)) {
+          edgeSet.add(containEdgeId);
+          edges.push({
+            id: containEdgeId,
+            source: page.stableId,
+            target: sectionId,
+            label: "contains"
+          });
+        }
+      }
+    }
+  }
+  const urlToStableId = new Map;
+  for (const page of visitedPages) {
+    urlToStableId.set(page.url, page.stableId);
+  }
+  for (const page of visitedPages) {
+    for (const linkUrl of page.outgoingLinks) {
+      const targetId = urlToStableId.get(linkUrl);
+      if (targetId && targetId !== page.stableId) {
+        const navEdgeId = generateEdgeId(page.stableId, targetId);
+        if (!edgeSet.has(navEdgeId)) {
+          edgeSet.add(navEdgeId);
+          edges.push({
+            id: navEdgeId,
+            source: page.stableId,
+            target: targetId,
+            label: "navigates"
+          });
+        }
+      }
+    }
+  }
+  const sectionGroups = buildSectionGroups(state.topology, visitedPages);
+  return { nodes, edges, sectionGroups };
+}
+function buildSectionGroups(topology, visitedPages) {
+  const groups = [];
+  const assignedSlugs = new Set;
+  for (const branch of topology) {
+    const descendantSlugs = collectSlugs(branch);
+    for (const s of descendantSlugs)
+      assignedSlugs.add(s);
+    groups.push({
+      sectionSlug: branch.slug,
+      name: branch.title || branch.slug,
+      icon: guessIcon(branch.slug)
+    });
+  }
+  for (const page of visitedPages) {
+    if (!assignedSlugs.has(page.slug)) {
+      groups.push({
+        sectionSlug: page.slug,
+        name: page.analysis?.pageName ?? page.title ?? page.slug,
+        icon: guessIcon(page.slug)
+      });
+    }
+  }
+  return groups;
+}
+function collectSlugs(node) {
+  const slugs = [node.slug];
+  for (const child of node.children) {
+    slugs.push(...collectSlugs(child));
+  }
+  return slugs;
+}
+function buildReportSections(visitedPages, sectionMarkdowns) {
+  return visitedPages.map((page, i) => ({
+    slug: page.slug,
+    name: page.analysis?.pageName ?? page.title ?? page.slug,
+    description: page.analysis?.description,
+    markdown: sectionMarkdowns.get(page.slug) ?? "",
+    sortOrder: i
+  }));
+}
+
+export { buildReportGraph, buildReportSections };