zefiro 0.8.1 → 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 };