zefiro 0.6.1 → 0.6.2

package/dist/cli.js

@@ -8102,16 +8102,19 @@ function registerAuth(program2) {
 // src/commands/mcp.ts
 var import_picocolors = __toESM(require_picocolors(), 1);
 var TOOLS = [
-  "zefiro_scan_codebase    — scan project test infrastructure",
-  "zefiro_scan_ast         — deep AST scan: routes, components, hooks",
-  "zefiro_scan_ast_detail  — drill into a specific AST category",
-  "zefiro_build_qa_map     — validate + write QAMapV2Payload",
-  "zefiro_read_qa_map      — read existing QA map file"
+  "zefiro_scan_codebase           — scan project test infrastructure",
+  "zefiro_scan_ast                — deep AST scan: routes, components, hooks",
+  "zefiro_scan_ast_detail         — drill into a specific AST category",
+  "zefiro_extract_state_variables — V4: extract state variables from AST",
+  "zefiro_build_v4_graph          — V4: build formal model from AST + state",
+  "zefiro_build_qa_map            — validate + write QA map (V2/V3/V4)",
+  "zefiro_read_qa_map             — read existing QA map file"
 ];
 var DESKTOP_CONFIG = JSON.stringify({
   mcpServers: {
     zefiro: {
-      command: "zefiro-mcp"
+      command: "npx",
+      args: ["-y", "@qai/zefiro", "mcp", "start"]
     }
   }
 }, null, 2);
@@ -8122,10 +8125,10 @@ function registerMcp(program2) {
     console.log(import_picocolors.default.dim("  " + "─".repeat(42)));
     console.log("");
     console.log(import_picocolors.default.bold("  Claude Code — add to project:"));
-    console.log(import_picocolors.default.cyan("    claude mcp add zefiro -- zefiro-mcp"));
+    console.log(import_picocolors.default.cyan("    claude mcp add zefiro -- npx -y @qai/zefiro mcp start"));
     console.log("");
     console.log(import_picocolors.default.bold("  Claude Code — add globally:"));
-    console.log(import_picocolors.default.cyan("    claude mcp add zefiro -s user -- zefiro-mcp"));
+    console.log(import_picocolors.default.cyan("    claude mcp add zefiro -s user -- npx -y @qai/zefiro mcp start"));
     console.log("");
     console.log(import_picocolors.default.bold("  Claude Desktop / other clients"));
     console.log(import_picocolors.default.dim("  ~/.config/claude/claude_desktop_config.json"));

package/dist/mcp.js

@@ -15046,16 +15046,59 @@ var SERVER_INSTRUCTIONS = `
 # Zefiro — Scanner & QA Map Guide
 
 You have access to Zefiro, an AI-powered codebase scanner and QA map generator.
-Supports three schema versions: V2 (flat/linear), V3 (hierarchical/DAG), and V4 (formal model). **Default to V3 for AI analysis, V4 for formal graph-based analysis.**
-
-## Core Workflow
-
-1. **Scan.** Call \`zefiro_scan_ast()\` to run the AST scanner and get a compact summary.
-2. **Explore.** Use \`zefiro_scan_ast_detail()\` to drill into routes, components, hooks, files, or navigationPatterns.
-3. **Propose & discuss.** Present candidate features to the user, ask clarifying questions.
-4. **Build.** Construct the QA map payload and validate with \`zefiro_build_qa_map({ dryRun: true })\`.
-5. **Write.** Once validated and approved, call \`zefiro_build_qa_map({ dryRun: false })\` to save.
-6. **Read existing.** Use \`zefiro_read_qa_map()\` to load a previously generated QA map.
+Supports three schema versions: V2 (flat/linear), V3 (hierarchical/DAG), and V4 (formal model).
+
+## IMPORTANT: Ask for Schema Version First
+
+Before starting any analysis, **ask the user which QA map version to build**:
+
+- **V2** — Flat features, linear workflows, string-based conditions. Best for simple apps.
+- **V3** — Hierarchical sections → features → sub-features, DAG workflows, typed conditions. Best for complex apps with many user flows.
+- **V4** — Formal layered model (structural graph + state space + transition system + semantic projection). Best for apps where state management, guards, and permissions are critical.
+
+Default to **V3** if the user has no preference.
+
+## Version-Specific Workflows
+
+### V2 Workflow (flat/linear)
+1. **Scan.** \`zefiro_scan_ast()\`
+2. **Explore.** \`zefiro_scan_ast_detail()\` — focus on routes, components
+3. **Analyze.** Act as the \`feature-analyzer-agent\`: identify flat features from routes, group by domain
+4. **Enrich.** Act as the \`workflow-agent\`: map linear workflow steps per feature
+5. **Scenarios.** Act as the \`scenario-planner-agent\`: generate test scenarios per workflow
+6. **Build.** \`zefiro_build_qa_map({ payload, dryRun: true })\` — payload must NOT include schemaVersion
+7. **Write.** \`zefiro_build_qa_map({ dryRun: false })\`
+
+### V3 Workflow (hierarchical/DAG)
+1. **Scan.** \`zefiro_scan_ast()\`
+2. **Explore.** \`zefiro_scan_ast_detail()\` — use routes (layoutChain, routeGroup), navigationPatterns, components (conditionalCount, guardPatterns)
+3. **Analyze.** Act as the \`feature-analyzer-agent-v3\`: group into sections, identify hierarchical features with entry points
+4. **Enrich.** Act as the \`workflow-agent-v3\`: build DAG workflows with typed conditions, edges, and entry/exit steps
+5. **Scenarios.** Act as the \`scenario-planner-agent-v3\`: generate scenarios that trace DAG paths
+6. **Build.** \`zefiro_build_qa_map({ payload, dryRun: true })\` — payload must include \`schemaVersion: 3\`
+7. **Write.** \`zefiro_build_qa_map({ dryRun: false })\`
+
+### V4 Workflow (formal model)
+1. **Scan.** \`zefiro_scan_ast()\`
+2. **Extract state.** \`zefiro_extract_state_variables()\` — gets auth guards, roles, flags, permissions
+3. **Build graph.** \`zefiro_build_v4_graph()\` — builds structural graph + state space + transition system deterministically
+4. **Label.** Act as the \`feature-analyzer-agent-v4\`: add semantic projection (feature labels over the formal model)
+5. **Build.** \`zefiro_build_qa_map({ payload, dryRun: true })\` — payload must include \`schemaVersion: 4\`
+6. **Write.** \`zefiro_build_qa_map({ dryRun: false })\`
+
+## Agent Reference
+
+Each version uses different agents. When acting as an agent, load its prompt from \`.qai/zefiro/agents/\` (project-local) or the package defaults:
+
+| Version | Agent | Purpose |
+|---------|-------|---------|
+| V2 | \`feature-analyzer-agent\` | Identify flat features from routes |
+| V2 | \`workflow-agent\` | Map linear workflow steps per feature |
+| V2 | \`scenario-planner-agent\` | Generate test scenarios |
+| V3 | \`feature-analyzer-agent-v3\` | Group sections, hierarchical features, entry points |
+| V3 | \`workflow-agent-v3\` | Build DAG workflows with typed conditions |
+| V3 | \`scenario-planner-agent-v3\` | Generate DAG-path scenarios |
+| V4 | \`feature-analyzer-agent-v4\` | Label semantic projection over formal model |
 
 ## Tools
 
@@ -15064,16 +15107,16 @@ Supports three schema versions: V2 (flat/linear), V3 (hierarchical/DAG), and V4
 - \`zefiro_scan_ast_detail\` — drill into a specific AST category (routes, components, hooks, dependencies, files, navigationPatterns)
 - \`zefiro_extract_state_variables\` — V4: extract state variables (auth, roles, flags, permissions) from scanned AST
 - \`zefiro_build_v4_graph\` — V4: build formal model (structural graph + state space + transition system) from AST + state variables
-- \`zefiro_build_qa_map\` — validate + write QA map payload (V2, V3, or V4 auto-detected)
+- \`zefiro_build_qa_map\` — validate + write QA map payload (V2, V3, or V4 — auto-detected by schemaVersion field)
 - \`zefiro_read_qa_map\` — read existing QA map
 
-## Scanner V3 Enhancements
+## Scanner Enhancements (V3/V4)
 
-The AST scanner extracts additional data useful for V3 map generation:
-- **Navigation patterns**: \`<Link>\`, \`router.push()\`, \`redirect()\` — used for entry point detection
-- **Layout chains**: layout files in route hierarchy — used for section grouping
-- **Route groups**: Next.js route groups like \`(authenticated)\` — section boundaries
-- **Conditional logic**: if/ternary/switch counts and guard patterns per component — branching hints
+The AST scanner extracts additional data useful for V3 and V4 map generation:
+- **Navigation patterns**: \`<Link>\`, \`router.push()\`, \`redirect()\` — used for entry point detection (V3) and structural edges (V4)
+- **Layout chains**: layout files in route hierarchy — used for section grouping (V3)
+- **Route groups**: Next.js route groups like \`(authenticated)\` — section boundaries (V3) and guard patterns (V4)
+- **Conditional logic**: if/ternary/switch counts and guard patterns per component — branching hints (V3) and state variable extraction (V4)
 
 Use \`zefiro_scan_ast_detail({ category: "navigationPatterns" })\` to explore navigation links.
 Routes returned by \`zefiro_scan_ast_detail({ category: "routes" })\` include \`layoutChain\` and \`routeGroup\`.
@@ -15240,6 +15283,55 @@ V3 payloads include \`schemaVersion: 3\` and support hierarchical features, DAG
 
 ---
 
+## QAMapV4Payload Schema Reference (formal model)
+
+V4 payloads include \`schemaVersion: 4\` and use a 4-layer deterministic model.
+
+### Top-level structure
+\`\`\`
+{
+  schemaVersion: 4
+  structuralGraph:   { nodes: StructuralNode[], edges: StructuralEdge[], entryPoints: string[] }
+  stateSpace:        { variables: StateVariable[], constraints: StateConstraint[], configurations: StateConfig[] }
+  transitionSystem:  { nodes: TransitionNode[], transitions: Transition[], stats: object }
+  semanticProjection: { features: FeatureV4[], labels: SemanticLabel[] }
+  commitSha?: string
+  metadata?:  object
+}
+\`\`\`
+
+### StructuralNode (Layer 0 — routes/pages)
+\`\`\`
+{ id, routePath, filePath, isDynamic, layoutChain, components[], forms[], apiCalls[], guards[] }
+\`\`\`
+
+### StateVariable (Layer 1 — state dimensions)
+\`\`\`
+{ id, name, category: "auth-guard"|"role"|"feature-flag"|"permission"|"ui-state"|"url-param", domain: string[], extractionConfidence: "high"|"medium"|"low" }
+\`\`\`
+
+### TransitionNode (Layer 2 — route × state config)
+\`\`\`
+{ id, routeId, stateConfigId, availableActions[], isEntryPoint }
+\`\`\`
+
+### Transition (Layer 2 — state machine edges)
+\`\`\`
+{ id, fromNodeId, toNodeId, trigger, guards: { variableId, operator, value }[], effects: { variableId, newValue }[] }
+\`\`\`
+
+### FeatureV4 (Layer 3 — semantic labels)
+\`\`\`
+{ name, subgraph: { routeIds[], transitionIds[], stateVariableIds[] }, complexity, criticalPaths }
+\`\`\`
+
+### V4 rules
+- Layers 0-2 are built deterministically by \`zefiro_build_v4_graph\`
+- Layer 3 (semantic projection) is the only AI-generated layer
+- All node/edge IDs must be internally consistent across layers
+
+---
+
 ## QAMapV2Payload Schema Reference (legacy)
 
 V2 payloads do NOT include a schemaVersion field. Flat features, linear workflow steps.
@@ -15262,7 +15354,7 @@ V2 payloads do NOT include a schemaVersion field. Flat features, linear workflow
 ### V2 ConditionalBranch: \`{ condition, outcome, type: "validation"|"permission"|"error"|"business-logic" }\`
 ### V2 Scenario: \`{ id, workflowId, featureId, name, description, category, preconditions: string[], steps: ScenarioStep[], expectedOutcome, componentIds: string[], workflowStepIds: string[], priority }\`
 `.trim();
-var server = new McpServer({ name: "zefiro", version: "0.6.1" }, { instructions: SERVER_INSTRUCTIONS });
+var server = new McpServer({ name: "zefiro", version: "0.6.2" }, { instructions: SERVER_INSTRUCTIONS });
 server.registerTool("zefiro_scan_codebase", {
   title: "Scan Codebase",
   description: "Scan a project directory for test files, configs, fixtures, path aliases, and sample test content.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zefiro",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "bin": {
     "zefiro": "./dist/cli.js",