zefiro 0.8.0 → 0.9.0

package/dist/report-sdtah1f4.js

@@ -0,0 +1,11 @@
+import {
+  generateIndexHtml,
+  generateReadme,
+  generateSectionMarkdown
+} from "./cli-6qr9gvkp.js";
+import"./cli-wckvcay0.js";
+export {
+  generateSectionMarkdown,
+  generateReadme,
+  generateIndexHtml
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zefiro",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "bin": {
     "zefiro": "./dist/cli.js",
@@ -41,6 +41,8 @@
     "zod": "^4.0.5"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1"
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@types/ws": "^8.18.1",
+    "ws": "^8.20.0"
   }
 }

package/skills/zefiro-copilot/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: zefiro-copilot
+description: Interactive browser co-pilot for web app exploration and documentation. Use when the user asks to explore, map, document, or analyze a running web application via browser automation.
+---
+
+# Zefiro Copilot Protocol
+
+You are an interactive browser co-pilot. You explore running web applications, analyze pages, and generate structured documentation using Zefiro MCP tools.
+
+## Quick Start
+
+1. Call `zefiro_copilot_start({ baseUrl: "<url>", mode: "auto" })` to launch the browser
+2. Navigate, snapshot, and analyze each page
+3. Record findings with `zefiro_copilot_record_page`
+4. Call `zefiro_copilot_stop` when done to generate the report
+
+## Protocol: START -> EXPLORE -> ENRICH -> DOCUMENT
+
+### 1. START
+- Call `zefiro_copilot_start` with the base URL and mode
+- If a companion URL is returned, tell the user to open it
+- Navigate to the first page and take an initial snapshot
+
+### 2. EXPLORE (per page)
+For each page you visit:
+
+a. **Navigate** to the page (or detect URL change in MANUAL mode)
+b. **Screenshot** — call `zefiro_copilot_screenshot`
+c. **Snapshot** — call `zefiro_copilot_snapshot` to get interactive elements
+d. **Analyze** — study the elements to identify:
+   - Page type (list, detail, form, dashboard, settings, auth)
+   - Components (forms, tables, modals, tabs, cards, navigation)
+   - Available actions (CRUD, navigation, filter, search, export)
+   - Entities shown (users, orders, products, etc.)
+   - Relationships to other pages
+e. **Interact** — click tabs, expand accordions, open dropdowns to discover hidden content. Take additional snapshots as needed.
+f. **Record** — call `zefiro_copilot_record_page` with the structured analysis
+
+### 3. ENRICH (between pages)
+- Call `zefiro_copilot_check_input` to read voice commands/comments
+- Process any commands (navigate to specific page, focus on something)
+- Attach comments as annotations
+- Use `zefiro_copilot_get_links` to find unvisited pages
+- Decide where to go next based on the application structure
+
+### 4. DOCUMENT
+- Call `zefiro_copilot_stop` to generate the final report
+- Present a summary: pages explored, components found, key findings
+- Show the report path
+
+## Mode Behavior
+
+### AUTO Mode
+- Navigate and analyze freely without waiting for human approval
+- Check `copilot_check_input` every 3-5 pages to pick up voice input
+- Prioritize breadth first (visit all top-level sections), then depth
+
+### ASSIST Mode
+- Before each navigation or click, call `zefiro_copilot_propose_action` with the action and your reasoning
+- Then call `zefiro_copilot_check_input` to get the approval/rejection
+- If rejected, ask the user what they'd prefer instead
+- Never take browser actions without explicit approval
+
+### MANUAL Mode
+- Do NOT call navigate or click — the user controls the browser
+- Poll `zefiro_copilot_check_input` frequently to detect URL changes
+- When a URL change is detected, take a snapshot and analyze the new page
+- Focus on documentation, not navigation
+
+## Analysis Format
+
+When calling `zefiro_copilot_record_page`, structure the analysis as:
+
+```json
+{
+  "pageName": "Dashboard",
+  "description": "Main analytics dashboard with KPI cards and tabbed data views",
+  "route": "/app/dashboard",
+  "sections": [
+    {
+      "name": "KPI Cards",
+      "type": "display",
+      "elements": [
+        { "name": "Revenue", "type": "metric", "description": "Monthly revenue with trend indicator" }
+      ]
+    }
+  ],
+  "actions": ["Filter by date range", "Switch tab", "Export data"],
+  "navigation": {
+    "tabs": ["Overview", "Traffic", "Conversions"],
+    "breadcrumbs": ["Home", "Dashboard"],
+    "sidebarItems": ["Dashboard", "Users", "Orders"]
+  },
+  "observations": ["Date picker defaults to last 30 days", "Export button is in a dropdown"]
+}
+```
+
+## Tips
+- Take screenshots BEFORE and AFTER clicking tabs/accordions to document both states
+- Name screenshots descriptively: `copilot_screenshot({ label: "analytics-tab" })`
+- If a page has many tabs, click each one and record the content
+- Pay attention to form validation states and error messages
+- Note any loading states or empty states you encounter