levante 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,256 @@
+# Levante
+
+AI-powered end-to-end test pipeline for Playwright. Record, transcribe, generate, refine, heal, and document your tests — all driven by LLM agents.
+
+## Installation
+
+```bash
+npm install -g levante
+```
+
+Levante requires Playwright as a peer dependency:
+
+```bash
+npm install -D @playwright/test
+```
+
+### 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
+levante init
+
+# Run full pipeline for a test case
+levante run --key PROJ-101
+
+# Or run individual steps
+levante record --key PROJ-101
+levante transcribe --key PROJ-101
+levante scenario --key PROJ-101
+levante generate --key PROJ-101
+levante test --key PROJ-101
+```
+
+## 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
+--no-voice               Disable voice recording
+--no-trace               Disable trace replay
+```
+
+### Commands
+
+#### `levante init`
+
+Initialize levante in your project. Creates `.qai/levante/` with config, agents, and workflow guide.
+
+```bash
+levante init
+levante init --non-interactive
+```
+
+#### `levante record [session]`
+
+Launch Playwright codegen with optional audio narration capture.
+
+```bash
+levante record --key PROJ-101
+levante record --key PROJ-101 --no-voice
+```
+
+#### `levante transcribe [session]`
+
+Transcribe `.wav` voice recording via OpenAI Whisper.
+
+```bash
+levante transcribe --key PROJ-101
+```
+
+#### `levante scenario [session]`
+
+Generate a structured YAML scenario from codegen output and transcript.
+
+```bash
+levante scenario --key PROJ-101
+```
+
+#### `levante generate [scenario]`
+
+Generate a Playwright `.test.ts` file from a YAML scenario.
+
+```bash
+levante generate --key PROJ-101
+```
+
+#### `levante refine [test]`
+
+Refactor a generated test with AI — replaces raw selectors, adds best practices.
+
+```bash
+levante refine --key PROJ-101
+```
+
+#### `levante test [test]`
+
+Run the Playwright test with trace/video/screenshot capture.
+
+```bash
+levante test --key PROJ-101
+```
+
+#### `levante heal [test]`
+
+Self-heal a failing test (up to 3 retries). Diagnoses failures and patches automatically.
+
+```bash
+levante heal --key PROJ-101
+```
+
+#### `levante qa [test]`
+
+Generate QA documentation (markdown and/or Zephyr XML).
+
+```bash
+levante qa --key PROJ-101
+```
+
+#### `levante run [session]`
+
+Run the full pipeline: record → transcribe → scenario → generate → refine → test → heal → qa.
+
+```bash
+levante run --key PROJ-101
+levante run --key PROJ-101 --from generate
+levante run --key PROJ-101 --skip transcribe,heal
+```
+
+| Option | Description |
+|--------|-------------|
+| `--from <step>` | Start from a specific step |
+| `--skip <steps>` | Skip comma-separated steps |
+
+## MCP Server
+
+Levante includes an MCP server for use with AI coding assistants.
+
+### Claude Code
+
+```bash
+claude mcp add levante -- npx levante-mcp
+```
+
+### Manual Configuration
+
+Add to your MCP client config (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "levante": {
+      "command": "npx",
+      "args": ["levante-mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `e2e_ai_plan_workflow` | Get ordered step list with prerequisite checks |
+| `e2e_ai_execute_step` | Execute a single pipeline step |
+| `e2e_ai_get_workflow_guide` | Get the full workflow guide |
+| `e2e_ai_scan_codebase` | Scan project for test infrastructure |
+| `e2e_ai_validate_context` | Validate context.md completeness |
+| `e2e_ai_read_agent` | Load an agent prompt by name |
+| `e2e_ai_get_example` | Get example context.md template |
+| `e2e_ai_scan_ast` | Run AST scanner |
+| `e2e_ai_scan_ast_detail` | Drill into routes/components/hooks |
+| `e2e_ai_build_qa_map` | Build and validate QA map |
+| `e2e_ai_read_qa_map` | Load existing QA map |
+
+## Configuration
+
+Configuration lives in `.qai/levante/config.ts`:
+
+```typescript
+import { defineConfig } from 'levante/config';
+
+export default defineConfig({
+  inputSource: 'jira',           // 'none' | 'jira' | 'linear'
+  outputTarget: 'both',          // 'markdown' | 'zephyr' | 'both'
+  baseUrl: 'http://localhost:3000',
+
+  llm: {
+    provider: 'openai',          // 'openai' | 'anthropic'
+    model: 'gpt-4o',             // Override default model
+    agentModels: {                // Per-agent overrides
+      'scenario-agent': 'claude-sonnet-4-20250514',
+    },
+  },
+
+  playwright: {
+    browser: 'chromium',
+    timeout: 120_000,
+    traceMode: 'on',
+  },
+
+  paths: {
+    tests: 'e2e/tests',
+    scenarios: 'e2e/scenarios',
+    recordings: 'e2e/recordings',
+    transcripts: 'e2e/transcripts',
+    traces: 'e2e/traces',
+    qaOutput: 'qa',
+  },
+
+  integrations: {
+    jira: { /* ... */ },
+    zephyr: { titlePrefix: 'UI Automation' },
+  },
+
+  push: {
+    apiUrl: 'https://your-api.com/qa-map',
+    apiKey: 'your-key',
+  },
+});
+```
+
+## Project Structure
+
+After initialization, levante creates:
+
+```
+your-project/
+  .qai/levante/
+    config.ts          # Configuration
+    context.md         # Project context for AI agents
+    agents/            # Agent prompts (customizable)
+    workflow.md        # Pipeline workflow guide
+  e2e/
+    tests/{key}/       # Generated test files
+    recordings/        # Codegen + voice recordings
+    transcripts/       # Transcription output
+    traces/            # Playwright traces
+  qa/                  # QA documentation output
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -7426,7 +7426,7 @@ function buildSteps() {
 
 // src/commands/init.ts
 import { join as join14 } from "node:path";
-import { readdirSync as readdirSync3, readFileSync as readFileSync3, existsSync as existsSync3 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync3, existsSync as existsSync3 } from "node:fs";
 // ../../node_modules/.bun/@inquirer+core@11.1.5+aab3160543ca59a9/node_modules/@inquirer/core/dist/lib/key.js
 var isUpKey = (key, keybindings = []) => key.name === "up" || keybindings.includes("vim") && key.name === "k" || keybindings.includes("emacs") && key.ctrl && key.name === "p";
 var isDownKey = (key, keybindings = []) => key.name === "down" || keybindings.includes("vim") && key.name === "j" || keybindings.includes("emacs") && key.ctrl && key.name === "n";
@@ -8938,7 +8938,7 @@ var dist_default6 = createPrompt((config, done) => {
 var import_picocolors = __toESM(require_picocolors(), 1);
 
 // src/config/migrate.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, rmSync, cpSync } from "node:fs";
+import { cpSync, existsSync as existsSync2, readFileSync as readFileSync2, rmSync } from "node:fs";
 import { join as join13 } from "node:path";
 var LEGACY_DIR = ".e2e-ai";
 async function migrateFromLegacy(projectRoot, nonInteractive) {
@@ -8958,7 +8958,7 @@ async function migrateFromLegacy(projectRoot, nonInteractive) {
       const src = join13(legacyPath, name);
       if (existsSync2(src)) {
         let content = readFileSync2(src, "utf-8");
-        content = content.replace(/from\s+['"]e2e-ai\/config['"]/g, "from '@qai/levante/config'");
+        content = content.replace(/from\s+['"]e2e-ai\/config['"]/g, "from 'levante/config'");
         writeFile(join13(newPath, name), content);
         migrated++;
         break;
@@ -9109,7 +9109,7 @@ function buildConfigFromAnswers(answers) {
 }
 function generateConfigFile(config) {
   const lines = [
-    `import { defineConfig } from '@qai/levante/config';`,
+    `import { defineConfig } from 'levante/config';`,
     "",
     "export default defineConfig({"
   ];
@@ -9133,7 +9133,7 @@ async function copyAgentsToLocal(projectRoot, nonInteractive) {
   const targetDir = join14(projectRoot, CONFIG_DIR, "agents");
   let agentFiles;
   try {
-    agentFiles = readdirSync3(sourceDir).filter((f) => f.endsWith(".md"));
+    agentFiles = readdirSync2(sourceDir).filter((f) => f.endsWith(".md"));
   } catch {
     warn("Could not read package agents directory");
     return 0;
@@ -9142,7 +9142,7 @@ async function copyAgentsToLocal(projectRoot, nonInteractive) {
     return 0;
   const targetExists = existsSync3(targetDir);
   if (targetExists) {
-    const existingFiles = readdirSync3(targetDir).filter((f) => f.endsWith(".md"));
+    const existingFiles = readdirSync2(targetDir).filter((f) => f.endsWith(".md"));
     if (existingFiles.length > 0) {
       if (nonInteractive) {
         info(`Agent files already exist in ${CONFIG_DIR}/agents/, skipping`);

package/package.json

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