zefiro 0.1.2 → 0.1.3

package/README.md

@@ -0,0 +1,180 @@
+# Zefiro
+
+AI-powered codebase scanner and QA map generator. Scans your project's AST, identifies features and workflows, and generates structured test scenarios — all driven by LLM agents.
+
+## Installation
+
+```bash
+npm install -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
+zefiro init
+
+# Scan → Analyze → Push
+zefiro scan
+zefiro analyze
+zefiro push
+```
+
+## CLI Usage
+
+### Global Options
+
+```
+-k, --key <KEY>          Issue key (e.g., PROJ-101)
+--provider <provider>    LLM provider: openai | anthropic
+--model <model>          LLM model override
+-v, --verbose            Verbose output
+```
+
+### Commands
+
+#### `zefiro init`
+
+Initialize zefiro in your project. Creates `.qai/zefiro/` with config and agent templates.
+
+```bash
+zefiro init
+zefiro init --non-interactive
+```
+
+Interactive setup prompts for issue tracker, output format, LLM provider, and base URL.
+
+#### `zefiro scan`
+
+Scan your codebase AST to extract routes, components, hooks, imports, and dependencies.
+
+```bash
+zefiro scan
+zefiro scan --scan-dir src/app
+zefiro scan --output custom-scan.json
+zefiro scan --no-cache
+```
+
+| 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 analyze [input]`
+
+Run two-stage AI analysis to generate a QA map from the AST scan.
+
+**Stage 1:** Feature analysis — identifies features, workflows, and components.
+**Stage 2:** Scenario planning — generates test scenarios for each workflow.
+
+```bash
+zefiro analyze
+zefiro analyze custom-scan.json
+zefiro analyze --skip-scenarios
+zefiro analyze --output custom-qa-map.json
+```
+
+| Option | Description |
+|--------|-------------|
+| `[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 |
+
+#### `zefiro push [input]`
+
+Push the generated QA map to a remote API.
+
+```bash
+zefiro push
+zefiro push custom-qa-map.json
+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 |
+
+Requires `push.apiUrl` and `push.apiKey` in config or via environment variables.
+
+## Configuration
+
+Configuration lives in `.qai/zefiro/config.ts`:
+
+```typescript
+import { defineConfig } from 'zefiro/config';
+
+export default defineConfig({
+  inputSource: 'jira',           // 'none' | 'jira' | 'linear'
+  outputTarget: 'markdown',      // 'markdown' | 'zephyr' | 'both'
+
+  llm: {
+    provider: 'openai',          // 'openai' | 'anthropic'
+    model: 'gpt-4o',             // Override default model
+    agentModels: {                // Per-agent 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',
+  },
+
+  push: {
+    apiUrl: 'https://your-api.com/qa-map',
+    apiKey: 'your-key',
+  },
+});
+```
+
+## AI Agents
+
+Zefiro ships with 3 agents (customizable in `.qai/zefiro/agents/`):
+
+| 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) |
+
+## QA Map Output
+
+The generated QA map 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)
+
+## Project Structure
+
+After initialization, zefiro creates:
+
+```
+your-project/
+  .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
+```
+
+## License
+
+MIT

package/package.json

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