zefiro 0.3.4 → 0.3.7

package/README.md

@@ -6,56 +6,63 @@ AI-powered codebase scanner and QA map generator. Scans your project's AST, iden
 
 ```bash
 npm install -g zefiro
+# or
+bun add -g zefiro
 ```
 
-### Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `OPENAI_API_KEY` | Yes (if using OpenAI) | OpenAI API key |
-| `ANTHROPIC_API_KEY` | Yes (if using Anthropic) | Anthropic API key |
-| `E2E_AI_API_URL` | No | Remote API URL for QA map push |
-| `E2E_AI_API_KEY` | No | API key for push authentication |
-
 ## Quick Start
 
 ```bash
-# Initialize config and agents
+# 1. Initialize — copies agents, writes QAI_* env vars to .env
 zefiro init
 
-# Scan → Analyze → Push
+# 2. Scan → Analyze → Push
 zefiro scan
 zefiro analyze
 zefiro push
 ```
 
-## CLI Usage
+---
 
-### Global Options
+## Environment Variables
 
-```
--k, --key <KEY>          Issue key (e.g., PROJ-101)
---provider <provider>    LLM provider: openai | anthropic
---model <model>          LLM model override
--v, --verbose            Verbose output
-```
+`zefiro init` writes the `QAI_*` variables to your `.env`. You can also set them manually.
 
-### Commands
+| Variable | Description |
+|----------|-------------|
+| `QAI_INPUT_SOURCE` | Issue tracker: `none` \| `jira` \| `linear` |
+| `QAI_OUTPUT_TARGET` | QA format: `markdown` \| `zephyr` \| `both` |
+| `QAI_BASE_URL` | QA Intelligence API base URL |
+| `QAI_API_URL` | Full push endpoint (overrides base URL) |
+| `QAI_API_KEY` | API key for authenticated push |
+| `OPENAI_API_KEY` | OpenAI API key (for `analyze` with OpenAI) |
+| `ANTHROPIC_API_KEY` | Anthropic API key (for `analyze` with Anthropic) |
 
-#### `zefiro init`
+---
 
-Initialize zefiro in your project. Creates `.qai/zefiro/` with config and agent templates.
+## Commands
+
+### `zefiro init`
+
+Initialize zefiro in your project. Copies agent templates to `.qai/zefiro/agents/` and writes `QAI_*` variables to `.env`.
 
 ```bash
 zefiro init
-zefiro init --non-interactive
+zefiro init --non-interactive   # skip prompts, use defaults
 ```
 
-Interactive setup prompts for issue tracker, output format, LLM provider, and base URL.
+On re-run (`.qai/zefiro/agents/` already exists), preserves your existing setup and only updates agents and workflow guide.
+
+**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`
+
+---
 
-#### `zefiro scan`
+### `zefiro scan`
 
-Scan your codebase AST to extract routes, components, hooks, imports, and dependencies.
+Scan your codebase AST — extracts routes, components, hooks, imports, and dependencies.
 
 ```bash
 zefiro scan
@@ -70,17 +77,19 @@ zefiro scan --no-cache
 | `--scan-dir <dir>` | Directory to scan (overrides config) |
 | `--no-cache` | Disable file-level MD5 caching |
 
-#### `zefiro analyze [input]`
+---
 
-Run two-stage AI analysis to generate a QA map from the AST scan.
+### `zefiro analyze [input]`
 
-**Stage 1:** Feature analysis — identifies features, workflows, and components.
-**Stage 2:** Scenario planning — generates test scenarios for each workflow.
+Two-stage AI analysis that generates a QA map from the AST scan.
+
+**Stage 1:** Feature analysis — identifies features, workflows, and components (runs in parallel).
+**Stage 2:** Scenario planning — generates test scenarios for each workflow (runs in parallel).
 
 ```bash
 zefiro analyze
 zefiro analyze custom-scan.json
-zefiro analyze --skip-scenarios
+zefiro analyze --skip-scenarios          # features and workflows only
 zefiro analyze --output custom-qa-map.json
 ```
 
@@ -88,11 +97,15 @@ zefiro analyze --output custom-qa-map.json
 |--------|-------------|
 | `[input]` | AST scan file (default: `.qai/zefiro/ast-scan.json`) |
 | `--output <file>` | QA map output (default: `.qai/zefiro/qa-map.json`) |
-| `--skip-scenarios` | Only run feature analysis, skip scenario generation |
+| `--skip-scenarios` | Skip scenario generation |
+
+**Incremental:** if the AST is unchanged since the last run, analysis is skipped. If the AST changed, only affected features are re-analyzed.
 
-#### `zefiro push [input]`
+---
 
-Push the generated QA map to a remote API.
+### `zefiro push [input]`
+
+Push the generated QA map to QA Intelligence (or a custom endpoint).
 
 ```bash
 zefiro push
@@ -103,34 +116,108 @@ zefiro push --commit-sha abc1234
 | Option | Description |
 |--------|-------------|
 | `[input]` | QA map file (default: `.qai/zefiro/qa-map.json`) |
-| `--commit-sha <sha>` | Git commit SHA to associate with the push |
+| `--commit-sha <sha>` | Git commit SHA to associate with this version |
+
+Authenticates via `zefiro auth login` session first, falls back to `QAI_API_URL` + `QAI_API_KEY`.
+
+---
+
+### `zefiro auth`
+
+Manage authentication with QA Intelligence.
+
+```bash
+zefiro auth login    # open browser for OAuth sign-in
+zefiro auth logout   # revoke CLI token
+zefiro auth status   # show current auth status
+zefiro auth switch   # re-authenticate with a different org/project/app
+```
+
+---
+
+### `zefiro mcp`
+
+Print MCP server setup instructions.
+
+```bash
+zefiro mcp
+```
+
+**Claude Code:**
+```bash
+claude mcp add zefiro -- zefiro-mcp              # project-scoped
+claude mcp add zefiro -s user -- zefiro-mcp      # global
+```
+
+**Claude Desktop / other clients:**
+```json
+{
+  "mcpServers": {
+    "zefiro": { "command": "zefiro-mcp" }
+  }
+}
+```
+
+**Available MCP tools:**
+
+| Tool | Description |
+|------|-------------|
+| `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 and write a QAMapV2Payload |
+| `zefiro_read_qa_map` | Read the existing QA map file |
 
-Requires `push.apiUrl` and `push.apiKey` in config or via environment variables.
+---
+
+## Global Options
+
+```
+-k, --key <KEY>        Issue key context (e.g. PROJ-101, LIN-42)
+--provider <provider>  LLM provider: openai | anthropic
+--model <model>        LLM model override
+--verbose              Verbose output
+-v, --version          Show version
+-h, --help             Show help
+```
+
+---
 
 ## Configuration
 
-Configuration lives in `.qai/zefiro/config.ts`:
+For most projects, the `.env` variables written by `zefiro init` are sufficient. For advanced setups (custom paths, per-agent model overrides, integrations), create `.qai/zefiro/config.ts`:
 
 ```typescript
-import { defineConfig } from 'zefiro/config';
+import { defineConfig } from 'zefiro';
 
 export default defineConfig({
-  inputSource: 'jira',           // 'none' | 'jira' | 'linear'
-  outputTarget: 'markdown',      // 'markdown' | 'zephyr' | 'both'
+  inputSource: 'jira',            // 'none' | 'jira' | 'linear'
+  outputTarget: 'markdown',       // 'markdown' | 'zephyr' | 'both'
+  baseUrl: 'https://qaligent.space',
+
+  scanner: {
+    scanDir: 'src',
+    include: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+    exclude: ['**/node_modules/**', '**/dist/**', '**/*.test.*'],
+    cacheDir: '.qai/zefiro/scan-cache',
+  },
 
   llm: {
-    provider: 'openai',          // 'openai' | 'anthropic'
-    model: 'gpt-4o',             // Override default model
-    agentModels: {                // Per-agent overrides
+    provider: 'openai',           // 'openai' | 'anthropic'
+    model: 'gpt-4o',
+    agentModels: {                 // per-agent model overrides
       'feature-analyzer-agent': 'claude-sonnet-4-20250514',
     },
   },
 
-  scanner: {
-    scanDir: 'src',
-    include: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
-    exclude: ['**/node_modules/**', '**/dist/**'],
-    cacheDir: '.qai/zefiro/scan-cache',
+  paths: {
+    tests: 'e2e/tests',
+    scenarios: 'e2e/scenarios',
+    qaOutput: 'qa',
+  },
+
+  integrations: {
+    zephyr: { titlePrefix: 'UI Automation' },
   },
 
   push: {
@@ -140,41 +227,64 @@ export default defineConfig({
 });
 ```
 
+> `QAI_*` env vars take precedence over `config.ts` values when both are set.
+
+---
+
 ## AI Agents
 
-Zefiro ships with 3 agents (customizable in `.qai/zefiro/agents/`):
+Zefiro ships with agents copied to `.qai/zefiro/agents/` on `init`. Edit them to tune AI behavior for your project.
 
 | Agent | Purpose |
 |-------|---------|
-| `feature-analyzer-agent` | Identifies features, workflows, and components from AST |
-| `scenario-planner-agent` | Generates test scenarios for each workflow |
-| `scanner-agent` | Interactive agent for manual QA map building (MCP) |
+| `1.feature-analyzer-agent` | Identifies features, workflows, and components from AST |
+| `2.scenario-planner-agent` | Generates test scenarios for each workflow |
+| `3.scanner-agent` | Interactive QA map building (used via MCP) |
+| `input-agent` | Enriches form component input definitions |
+| `workflow-agent` | Maps user workflows within features |
+
+Add `.qai/zefiro/context.md` to inject project-specific context into every agent call.
+
+---
 
 ## QA Map Output
 
-The generated QA map contains:
+The generated `.qai/zefiro/qa-map.json` contains:
 
 - **Features** — User-facing capabilities grouped by routes
-- **Workflows** — User journeys (navigation, CRUD, multi-step, configuration, search/filter)
-- **Components** — UI elements (forms, modals, navigation, display)
-- **Scenarios** — Test cases with categories (happy-path, validation, error, edge-case, permission)
+- **Workflows** — User journeys (navigation, CRUD, multi-step, search/filter, configuration)
+- **Components** — UI elements (forms, modals, navigation, data display)
+- **Scenarios** — Test cases per workflow (happy-path, validation, error, edge-case, permission)
 
-## Project Structure
+---
 
-After initialization, zefiro creates:
+## Project Structure
 
 ```
 your-project/
+  .env                         # QAI_* variables (written by zefiro init)
   .qai/zefiro/
-    config.ts          # Configuration
-    context.md         # Project context for AI agents
-    agents/            # Agent prompts (customizable)
-    workflow.md        # Workflow guide
-    ast-scan.json      # AST scan output
-    qa-map.json        # Generated QA map
-    scan-cache/        # File-level MD5 cache
+    config.ts                  # Advanced config (optional)
+    context.md                 # Project context for AI agents
+    agents/                    # Agent prompts (customizable)
+    workflow.md                # Workflow guide
+    ast-scan.json              # Latest AST scan output
+    qa-map.json                # Generated QA map
+    scan-cache/                # File-level MD5 cache
 ```
 
+---
+
+## Interactive TUI
+
+Running `zefiro` with no arguments launches an interactive terminal UI (requires TTY, ≥ 60×20).
+
+```bash
+zefiro
+```
+
+---
+
 ## License
 
 MIT

package/agents/1.feature-analyzer-agent.md

@@ -1,5 +1,8 @@
 ---
 agent: feature-analyzer-agent
+model: claude-sonnet-4-20250514
+max_tokens: 8192
+temperature: 0.2
 ---
 
 # System Prompt

package/agents/2.scenario-planner-agent.md

@@ -1,5 +1,8 @@
 ---
 agent: scenario-planner-agent
+model: claude-sonnet-4-20250514
+max_tokens: 8192
+temperature: 0.2
 ---
 
 # System Prompt

package/agents/3.scanner-agent.md

@@ -6,19 +6,15 @@ temperature: 0.3
 
 # Scanner Agent — Interactive QA Map Generation
 
-You are an interactive scanner agent for e2e-ai. Your job is to analyze a codebase's AST scan, propose a feature/workflow structure, and produce a validated `QAMapV2Payload`.
+You are an interactive scanner agent for Zefiro. Your job is to analyze a codebase's AST scan, propose a feature/workflow structure, and produce a validated `QAMapV2Payload`.
 
 **You are the LLM.** No separate AI call is made — you reason about the AST data directly and interact with the user to refine the result.
 
-## How to Use
-
-Load this protocol via `e2e_ai_read_agent("scanner-agent")`, then follow the phases below in order.
-
 ---
 
 ## Phase 1: Scan
 
-1. Call `e2e_ai_scan_ast()` — optionally pass `scanDir`, `include`, `exclude` to scope the scan.
+1. Call `zefiro_scan_ast()` — optionally pass `scanDir`, `include`, `exclude` to scope the scan.
 2. Review the returned summary: stats, routes, components, hooks, directory groups.
 3. Present an overview to the user:
    - Total files, lines, routes, components, hooks
@@ -31,7 +27,7 @@ Load this protocol via `e2e_ai_read_agent("scanner-agent")`, then follow the pha
 
 ## Phase 2: Explore & Propose
 
-1. Drill into specific areas with `e2e_ai_scan_ast_detail()`:
+1. Drill into specific areas with `zefiro_scan_ast_detail()`:
    - `{ category: "routes" }` — understand navigation structure
    - `{ category: "components", filter: "src/components/**" }` — UI building blocks
    - `{ category: "hooks" }` — business logic patterns
@@ -84,11 +80,11 @@ Present the complete structure grouped by feature. Ask the user to review.
 
 ## Phase 4: Commit
 
-1. Build the full `QAMapV2Payload` JSON object.
-2. Call `e2e_ai_build_qa_map({ payload: <your JSON>, dryRun: true })` to validate.
+1. Build the full `QAMapV2Payload` JSON object (see schema below).
+2. Call `zefiro_build_qa_map({ payload: <your JSON>, dryRun: true })` to validate.
 3. If errors are returned, fix them and re-validate.
 4. Show the user: stats (features, workflows, scenarios), any warnings.
-5. Once approved, call `e2e_ai_build_qa_map({ payload: <your JSON>, dryRun: false })` to write.
+5. Once approved, call `zefiro_build_qa_map({ payload: <your JSON>, dryRun: false })` to write.
 6. Report the output path and final stats.
 
 ---
@@ -109,9 +105,9 @@ Present the complete structure grouped by feature. Ask the user to review.
 Use prefixed IDs for clarity:
 - Features: `feat:user-auth`, `feat:dashboard`
 - Workflows: `wf:login-flow`, `wf:create-invoice`
+- Workflow steps: `step:login-flow:1`, `step:login-flow:2`
 - Components: `comp:login-form`, `comp:nav-sidebar`
 - Scenarios: `sc:login-happy-path`, `sc:login-invalid-password`
-- Workflow steps: `step:enter-credentials`, `step:submit-form`
 
 IDs should be kebab-case, descriptive, and unique within their category.
 
@@ -120,7 +116,7 @@ IDs should be kebab-case, descriptive, and unique within their category.
 ## Incremental Updates
 
 If a QA map already exists:
-1. Call `e2e_ai_read_qa_map()` to load the existing map.
+1. Call `zefiro_read_qa_map()` to load the existing map.
 2. Preserve existing IDs — don't regenerate them.
 3. Only add/update/remove entities that changed.
 4. Tell the user what changed: "Added 2 new workflows, updated 3 scenarios, removed 1 obsolete feature."
@@ -128,19 +124,91 @@ If a QA map already exists:
 
 ---
 
-## Output Format
+## QAMapV2Payload Schema
 
-The final `QAMapV2Payload` must conform to this structure:
+The payload MUST conform exactly to this schema. All fields are required unless marked optional.
 
-```typescript
+```
 {
-  features: FeatureV2[],
-  workflows: WorkflowV2[],
-  components: ComponentV2[],
-  scenarios: ScenarioV2[],
-  commitSha?: string,    // auto-added by build tool
-  metadata?: {}          // optional project metadata
+  features:   Feature[]    // required
+  workflows:  Workflow[]   // required
+  components: Component[]  // required
+  scenarios:  Scenario[]   // required
+  commitSha?: string       // auto-injected by zefiro_build_qa_map
+  metadata?:  object       // optional
+}
+
+Feature {
+  id:          string    // e.g. "feat:auth"
+  name:        string
+  description: string
+  routes:      string[]  // URL paths, e.g. ["/login", "/register"]
+  workflowIds: string[]  // IDs of all workflows in this feature
+  sourceFiles: string[]  // relative paths, e.g. ["src/app/login/page.tsx"]
+}
+
+Workflow {
+  id:            string
+  name:          string
+  featureId:     string   // must match a Feature.id
+  type:          "navigation" | "crud" | "multi-step" | "configuration" | "search-filter"
+  preconditions: string[]
+  steps:         WorkflowStep[]
+  componentIds:  string[] // Component.id values used by this workflow
+}
+
+WorkflowStep {
+  id:                  string   // e.g. "step:login-flow:1"
+  order:               number   // 1-based
+  description:         string
+  componentIds:        string[] // Component.id values in this step
+  apiCalls:            string[] // e.g. ["POST /api/auth/login"]
+  conditionalBranches: ConditionalBranch[]
+}
+
+ConditionalBranch {
+  condition: string  // e.g. "invalid credentials"
+  outcome:   string  // e.g. "show error message"
+  type:      "validation" | "permission" | "error" | "business-logic"
+}
+
+Component {
+  id:                    string
+  name:                  string
+  type:                  "form" | "display" | "navigation" | "modal" | "layout" | "feedback"
+  sourceFiles:           string[]
+  props:                 string[]
+  referencedByWorkflows: string[] // Workflow.id values that use this component
+}
+
+Scenario {
+  id:              string
+  workflowId:      string   // must match a Workflow.id
+  featureId:       string   // must match a Feature.id
+  name:            string
+  description:     string
+  category:        "happy-path" | "permission" | "validation" | "error" | "edge-case" | "precondition"
+  preconditions:   string[]
+  steps:           ScenarioStep[]
+  expectedOutcome: string
+  componentIds:    string[]
+  workflowStepIds: string[] // WorkflowStep.id values this scenario covers
+  priority:        "critical" | "high" | "medium" | "low"
+}
+
+ScenarioStep {
+  order:          number  // 1-based
+  action:         string
+  expectedResult: string
 }
 ```
 
-See `src/scanner/types.ts` for the full type definitions.
+**Referential integrity** (all must hold or dry-run will fail):
+- `workflow.featureId` → exists in `features[].id`
+- `feature.workflowIds[]` → each exists in `workflows[].id`
+- `workflow.componentIds[]` → each exists in `components[].id`
+- `scenario.workflowId` → exists in `workflows[].id`
+- `scenario.featureId` → exists in `features[].id`
+- `scenario.componentIds[]` → each exists in `components[].id`
+- `scenario.workflowStepIds[]` → each exists in a `workflow.steps[].id`
+- `component.referencedByWorkflows[]` → each exists in `workflows[].id`

package/agents/input-agent.md

@@ -53,6 +53,7 @@ Respond with JSON only (no markdown fences, no extra text):
 
 ## Rules
 
+0. `inputAnalysis` is an internal enrichment field — it is NOT part of the QAMapV2 schema and must be stripped before passing components to `zefiro_build_qa_map`
 1. For each component that is a form (type="form"), analyze ALL input fields
 2. Merge data from AST-extracted forms with component props to produce complete field analysis
 3. Infer the submit action from: API calls in imports, fetch/axios calls, action props, form action attribute

package/agents/workflow-agent.md

@@ -27,7 +27,7 @@ Respond with JSON only (no markdown fences, no extra text):
 {
   "workflows": [
     {
-      "id": "wf:<feature-id-without-feat:>-<workflow-name>",
+      "id": "wf:<kebab-name>",
       "name": "Human-readable workflow name",
       "featureId": "feat:<kebab>",
       "type": "navigation|crud|multi-step|configuration|search-filter",