levante 0.3.5 → 0.3.6

package/README.md

@@ -1,11 +1,13 @@
 # Levante
 
-AI-powered end-to-end test pipeline for Playwright. Record, transcribe, generate, refine, heal, and document your tests — all driven by LLM agents.
+AI-powered end-to-end test pipeline for Playwright. Record interactions, transcribe narration, generate Playwright tests, self-heal failures, and produce QA documentation — all driven by LLM agents.
 
 ## Installation
 
 ```bash
 npm install -g levante
+# or
+bun add -g levante
 ```
 
 Levante requires Playwright as a peer dependency:
@@ -14,82 +16,109 @@ Levante requires Playwright as a peer dependency:
 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
+# 1. Initialize config and agents
 levante init
 
-# Run full pipeline for a test case
+# 2. Run full pipeline for a test case
 levante run --key PROJ-101
 
-# Or run individual steps
+# Or step by step
 levante record --key PROJ-101
 levante transcribe --key PROJ-101
 levante scenario --key PROJ-101
 levante generate --key PROJ-101
+levante refine --key PROJ-101
 levante test --key PROJ-101
+levante heal --key PROJ-101        # only if test fails
+levante qa --key PROJ-101
 ```
 
-## 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
---no-voice               Disable voice recording
---no-trace               Disable trace replay
-```
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_KEY` | OpenAI API key |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `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 |
 
-### Commands
+---
 
-#### `levante init`
+## Commands
 
-Initialize levante in your project. Creates `.qai/levante/` with config, agents, and workflow guide.
+### `levante init`
+
+Initialize levante in your project. Generates `.qai/levante/config.ts`, copies agent templates, and optionally connects to QA Intelligence.
 
 ```bash
 levante init
-levante init --non-interactive
+levante init --non-interactive   # skip prompts, use defaults
 ```
 
-#### `levante record [session]`
+On re-run, preserves your existing config and context, and only updates agents.
+
+**After init:**
+1. Generate `.qai/levante/context.md` using the `init-agent` prompt in your AI tool, or via MCP (`levante_scan_codebase`)
+2. Review the generated context
+3. Start recording: `levante record --key PROJ-101`
+
+---
 
-Launch Playwright codegen with optional audio narration capture.
+### `levante record [session]`
+
+Launch Playwright codegen with optional voice narration recording.
 
 ```bash
 levante record --key PROJ-101
-levante record --key PROJ-101 --no-voice
+levante record --key PROJ-101 --no-companion   # voice only, no companion UI
+levante record --key PROJ-101 --no-voice       # codegen only, no audio
 ```
 
-#### `levante transcribe [session]`
+| Option | Description |
+|--------|-------------|
+| `--no-companion` | Disable companion UI (voice recording only) |
+| `--no-voice` | Disable voice recording entirely |
 
-Transcribe `.wav` voice recording via OpenAI Whisper.
+**Output:** codegen TypeScript file + `.wav` audio (if voice enabled)
+
+---
+
+### `levante transcribe [session]`
+
+Transcribe the `.wav` voice recording via OpenAI Whisper. If a live transcript from the recording session exists, Whisper is skipped.
 
 ```bash
 levante transcribe --key PROJ-101
+levante transcribe --key PROJ-101 --force   # re-transcribe even if transcript exists
 ```
 
-#### `levante scenario [session]`
+Merges voice annotations (with timestamps) back into the codegen file as inline comments.
+
+**Output:** `*-transcript.json`, `*-transcript.md`, annotated codegen file
+
+---
+
+### `levante scenario [session]`
 
-Generate a structured YAML scenario from codegen output and transcript.
+Generate a structured YAML scenario from codegen output and voice transcript.
 
 ```bash
 levante scenario --key PROJ-101
 ```
 
-#### `levante generate [scenario]`
+Uses `transcript-agent` (if transcript available) to extract narrative and action intents, then `scenario-agent` to produce a YAML scenario with title, precondition, steps, and postcondition. Jira/Linear issue context is included automatically if `--key` is set.
+
+**Output:** `.yaml` scenario file in `e2e/tests/[key]/`
+
+---
+
+### `levante generate [scenario]`
 
 Generate a Playwright `.test.ts` file from a YAML scenario.
 
@@ -97,118 +126,238 @@ Generate a Playwright `.test.ts` file from a YAML scenario.
 levante generate --key PROJ-101
 ```
 
-#### `levante refine [test]`
+Uses `playwright-generator-agent` with scenario + project context. If Zephyr is configured, also generates a Zephyr test case export.
+
+**Output:** `[key].test.ts` in `e2e/tests/[key]/`
+
+---
 
-Refactor a generated test with AI — replaces raw selectors, adds best practices.
+### `levante refine [test]`
+
+Refactor a generated test with AI — replaces raw selectors, improves structure, applies project patterns.
 
 ```bash
 levante refine --key PROJ-101
 ```
 
-#### `levante test [test]`
+Uses `refactor-agent`. Rewrites the test file in-place.
+
+---
+
+### `levante test [test]`
 
-Run the Playwright test with trace/video/screenshot capture.
+Run the Playwright test with trace, video, and screenshot capture.
 
 ```bash
 levante test --key PROJ-101
+levante test --key PROJ-101 --no-trace
 ```
 
-#### `levante heal [test]`
+**Output:** Test execution logs, trace files in `e2e/traces/`
 
-Self-heal a failing test (up to 3 retries). Diagnoses failures and patches automatically.
+---
+
+### `levante heal [test]`
+
+Self-heal a failing test. Diagnoses the failure, patches the test, and re-runs — up to 3 retries.
 
 ```bash
 levante heal --key PROJ-101
 ```
 
-#### `levante qa [test]`
+Each attempt uses `self-healing-agent` with test content + error output + trace data to produce:
+- `diagnosis` (failure type, root cause, confidence)
+- `patchedTest` (updated test file)
+- `changes` (summary of what was fixed)
+
+Exits with error if all 3 attempts fail.
 
-Generate QA documentation (markdown and/or Zephyr XML).
+---
+
+### `levante qa [test]`
+
+Generate QA documentation from the test and scenario.
 
 ```bash
 levante qa --key PROJ-101
 ```
 
-#### `levante run [session]`
+Uses `qa-testcase-agent` with test + scenario + Jira context. Produces markdown and/or Zephyr export depending on `outputTarget`.
+
+**Output:** `qa/[testId].md` and/or Zephyr JSON
+
+---
+
+### `levante run [session]`
 
-Run the full pipeline: record → transcribe → scenario → generate → refine → test → heal → qa.
+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 --from generate     # resume from a specific step
 levante run --key PROJ-101 --skip transcribe,heal
+levante run --key PROJ-101 --no-voice          # skip recording + transcription
 ```
 
 | Option | Description |
 |--------|-------------|
-| `--from <step>` | Start from a specific step |
-| `--skip <steps>` | Skip comma-separated steps |
+| `--from <step>` | Start from a specific step (skips earlier steps) |
+| `--skip <steps>` | Comma-separated step names to skip |
+| `--no-voice` | Disable voice recording (skips transcription too) |
+| `--no-trace` | Disable trace capture |
 
-## MCP Server
+**Steps (in order):** `record` → `transcribe` → `scenario` → `generate` → `refine` → `test` → `heal` → `qa`
 
-Levante includes an MCP server for use with AI coding assistants.
+---
 
-### Claude Code
+### `levante auth`
+
+Manage authentication with QA Intelligence.
 
 ```bash
-claude mcp add levante -- npx levante-mcp
+levante auth login    # open browser for OAuth sign-in
+levante auth logout   # revoke CLI token
+levante auth status   # show current auth status
+levante auth switch   # re-authenticate with a different org/project/app
 ```
 
-### Manual Configuration
+---
+
+### `levante jira`
+
+Interactive Jira integration for issue discovery and workflow launch.
 
-Add to your MCP client config (e.g., `claude_desktop_config.json`):
+#### `levante jira browse`
 
+Interactive browser — search, view, and select Jira issues to start a test workflow.
+
+```bash
+levante jira browse
+```
+
+Select an issue to:
+- **run** — save context and launch `levante run --key <KEY>`
+- **save** — save issue context without running
+- **view** — display full issue details
+
+#### `levante jira search <query>`
+
+Search Jira issues by text or raw JQL.
+
+```bash
+levante jira search "login flow"
+levante jira search --jql "project = QA AND status = 'In Progress'"
+levante jira search "dashboard" --max 10
+```
+
+| Option | Description |
+|--------|-------------|
+| `<query>` | Text search query |
+| `--jql <jql>` | Use raw JQL instead of text search |
+| `--max <n>` | Maximum results to return (default: 20) |
+
+#### `levante jira show <issueKey>`
+
+Display full details for a Jira issue.
+
+```bash
+levante jira show PROJ-101
+levante jira show PROJ-101 --save    # also save context for pipeline use
+```
+
+| Option | Description |
+|--------|-------------|
+| `--save` | Save issue context to `.qai/levante/issues/[KEY].json` |
+
+---
+
+### `levante mcp`
+
+Print MCP server setup instructions.
+
+```bash
+levante mcp
+```
+
+**Claude Code:**
+```bash
+claude mcp add levante -- levante-mcp              # project-scoped
+claude mcp add levante -s user -- levante-mcp      # global
+```
+
+**Claude Desktop / other clients:**
 ```json
 {
   "mcpServers": {
-    "levante": {
-      "command": "npx",
-      "args": ["levante-mcp"]
-    }
+    "levante": { "command": "levante-mcp" }
   }
 }
 ```
 
-### Available MCP Tools
+**Available MCP tools:**
 
 | Tool | Description |
 |------|-------------|
 | `levante_plan_workflow` | Get ordered step list with prerequisite checks |
 | `levante_execute_step` | Execute a single pipeline step |
-| `levante_get_workflow_guide` | Get the full workflow guide |
+| `levante_get_workflow_guide` | Read the full workflow guide |
 | `levante_scan_codebase` | Scan project for test infrastructure |
 | `levante_validate_context` | Validate context.md completeness |
 | `levante_read_agent` | Load an agent prompt by name |
-| `levante_get_example` | Get example context.md template |
+| `levante_get_example` | Get an example context.md template |
 | `levante_scan_ast` | Run AST scanner |
 | `levante_scan_ast_detail` | Drill into routes/components/hooks |
 | `levante_build_qa_map` | Build and validate QA map |
 | `levante_read_qa_map` | Load existing QA map |
 
+---
+
+## Global Options
+
+```
+-k, --key <KEY>        Issue key (e.g. PROJ-101, LIN-42)
+--provider <provider>  LLM provider: openai | anthropic
+--model <model>        LLM model override
+--verbose              Verbose output
+--no-voice             Disable voice recording
+--no-trace             Disable trace capture
+-v, --version          Show version
+-h, --help             Show help
+```
+
+---
+
 ## Configuration
 
-Configuration lives in `.qai/levante/config.ts`:
+Configuration lives in `.qai/levante/config.ts` (generated by `levante init`):
 
 ```typescript
-import { defineConfig } from 'levante/config';
+import { defineConfig } from 'levante';
 
 export default defineConfig({
-  inputSource: 'jira',           // 'none' | 'jira' | 'linear'
-  outputTarget: 'both',          // 'markdown' | 'zephyr' | 'both'
+  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
+    provider: 'openai',           // 'openai' | 'anthropic'
+    model: 'gpt-4o',
+    agentModels: {                 // per-agent model overrides
       'scenario-agent': 'claude-sonnet-4-20250514',
     },
   },
 
   playwright: {
-    browser: 'chromium',
+    browser: 'chromium',          // 'chromium' | 'firefox' | 'webkit'
     timeout: 120_000,
-    traceMode: 'on',
+    retries: 0,
+    traceMode: 'on',              // 'on' | 'off' | 'retain-on-failure'
+  },
+
+  voice: {
+    enabled: true,
+    engine: 'webspeech',          // 'webspeech' | 'whisper'
+    language: 'en-US',
   },
 
   paths: {
@@ -221,36 +370,67 @@ export default defineConfig({
   },
 
   integrations: {
-    jira: { /* ... */ },
+    jira: { /* Jira config */ },
     zephyr: { titlePrefix: 'UI Automation' },
   },
 
   push: {
-    apiUrl: 'https://your-api.com/qa-map',
+    apiUrl: 'https://qaligent.space/api',
     apiKey: 'your-key',
   },
 });
 ```
 
-## Project Structure
+---
+
+## AI Agents
+
+Levante ships with agents copied to `.qai/levante/agents/` on `init`. Edit them to tune AI behavior for your project.
 
-After initialization, levante creates:
+| Agent | Purpose |
+|-------|---------|
+| `0.init-agent` | Generate project `context.md` |
+| `1_1.transcript-agent` | Analyze voice transcript + codegen into narrative |
+| `1_2.scenario-agent` | Generate YAML scenario from narrative and actions |
+| `2.playwright-generator-agent` | Generate Playwright test from YAML scenario |
+| `3.refactor-agent` | Refactor test code for quality and conventions |
+| `4.self-healing-agent` | Diagnose and patch failing tests |
+| `5.qa-testcase-agent` | Generate QA documentation and Zephyr export |
+
+Add `.qai/levante/context.md` to inject project-specific context into every agent call.
+
+---
+
+## Project Structure
 
 ```
 your-project/
   .qai/levante/
-    config.ts          # Configuration
-    context.md         # Project context for AI agents
-    agents/            # Agent prompts (customizable)
-    workflow.md        # Pipeline workflow guide
+    config.ts                  # Configuration
+    context.md                 # Project context for AI agents
+    agents/                    # Agent prompts (customizable)
+    workflow.md                # Pipeline workflow guide
+    issues/                    # Saved Jira issue contexts
   e2e/
-    tests/{key}/       # Generated test files
-    recordings/        # Codegen + voice recordings
-    transcripts/       # Transcription output
-    traces/            # Playwright traces
-  qa/                  # QA documentation output
+    tests/{key}/               # Generated test files + scenario YAML
+    recordings/                # Codegen + voice recordings
+    transcripts/               # Transcription output
+    traces/                    # Playwright traces
+  qa/                          # QA documentation output
 ```
 
+---
+
+## Interactive TUI
+
+Running `levante` with no arguments launches an interactive terminal UI (requires TTY, ≥ 60×20).
+
+```bash
+levante
+```
+
+---
+
 ## License
 
 MIT

package/dist/cli.js

@@ -57497,19 +57497,22 @@ async function launchTui(program2) {
       version: version2,
       onRunCommand: (argv) => {
         runningCommand = true;
-        instance.waitUntilExit().then(async () => {
-          process.stdin.resume();
-          process.stdout.write(`
+        instance.waitUntilExit().then(() => {
+          setTimeout(async () => {
+            process.stdin.resume();
+            process.stdin.ref();
+            process.stdout.write(`
 $ levante ${argv.join(" ")}
 
 `);
-          try {
-            await program2.parseAsync(argv, { from: "user" });
-          } catch (err) {
-            if (err?.name !== "ExitPromptError")
-              throw err;
-          }
-          done();
+            try {
+              await program2.parseAsync(argv, { from: "user" });
+            } catch (err) {
+              if (err?.name !== "ExitPromptError")
+                throw err;
+            }
+            done();
+          }, 50);
         });
       },
       onQuit: done
@@ -75507,54 +75510,61 @@ async function migrateFromLegacy(projectRoot, nonInteractive) {
 // src/commands/init.ts
 function registerInit(program2) {
   program2.command("init").description("Initialize levante configuration for your project").option("--non-interactive", "Skip interactive prompts, use defaults").action(async (cmdOpts) => {
-    const projectRoot = getProjectRoot();
-    const nonInteractive = !!cmdOpts?.nonInteractive;
-    header("levante init");
-    await migrateFromLegacy(projectRoot, nonInteractive);
-    const qaiDir = join17(projectRoot, CONFIG_DIR);
-    const configPath = join17(qaiDir, "config.ts");
-    const isReInit = fileExists(configPath);
-    if (isReInit) {
-      info(`Existing ${CONFIG_DIR}/ detected — preserving config and context.
+    try {
+      const projectRoot = getProjectRoot();
+      const nonInteractive = !!cmdOpts?.nonInteractive;
+      header("levante init");
+      await migrateFromLegacy(projectRoot, nonInteractive);
+      const qaiDir = join17(projectRoot, CONFIG_DIR);
+      const configPath = join17(qaiDir, "config.ts");
+      const isReInit = fileExists(configPath);
+      if (isReInit) {
+        info(`Existing ${CONFIG_DIR}/ detected — preserving config and context.
 `);
-      await copyAgentsToLocal(projectRoot, nonInteractive);
-      await copyWorkflowGuide(projectRoot, nonInteractive);
-    } else {
-      const answers = nonInteractive ? getDefaultAnswers() : await askConfigQuestions();
-      const config2 = buildConfigFromAnswers(answers);
-      writeFile(configPath, generateConfigFile(config2));
-      success2(`Config written: ${configPath}`);
-      await copyAgentsToLocal(projectRoot, nonInteractive);
-      await copyWorkflowGuide(projectRoot, nonInteractive);
-    }
-    if (!nonInteractive) {
-      const { confirm: confirmPrompt } = await Promise.resolve().then(() => (init_dist9(), exports_dist));
-      const connectAuth = await confirmPrompt({
-        message: "Connect to QA Intelligence?",
-        default: false
-      });
-      if (connectAuth) {
-        try {
-          const { login: login2 } = await Promise.resolve().then(() => (init_dist10(), exports_dist2));
-          const session = await login2({ webappUrl: "https://qaligent.space" });
-          success2(`Authenticated as ${session.user.email}`);
-          success2(`Linked to: ${session.scope.orgSlug} / ${session.scope.projectSlug} / ${session.scope.appSlug}`);
-        } catch (err) {
-          warn(`Authentication skipped: ${err instanceof Error ? err.message : "unknown error"}`);
+        await copyAgentsToLocal(projectRoot, nonInteractive);
+        await copyWorkflowGuide(projectRoot, nonInteractive);
+      } else {
+        const answers = nonInteractive ? getDefaultAnswers() : await askConfigQuestions();
+        const config2 = buildConfigFromAnswers(answers);
+        writeFile(configPath, generateConfigFile(config2));
+        success2(`Config written: ${configPath}`);
+        await copyAgentsToLocal(projectRoot, nonInteractive);
+        await copyWorkflowGuide(projectRoot, nonInteractive);
+      }
+      if (!nonInteractive) {
+        const { confirm: confirmPrompt } = await Promise.resolve().then(() => (init_dist9(), exports_dist));
+        const connectAuth = await confirmPrompt({
+          message: "Connect to QA Intelligence?",
+          default: false
+        });
+        if (connectAuth) {
+          try {
+            const { login: login2 } = await Promise.resolve().then(() => (init_dist10(), exports_dist2));
+            const session = await login2({ webappUrl: "https://qaligent.space" });
+            success2(`Authenticated as ${session.user.email}`);
+            success2(`Linked to: ${session.scope.orgSlug} / ${session.scope.projectSlug} / ${session.scope.appSlug}`);
+          } catch (err) {
+            warn(`Authentication skipped: ${err instanceof Error ? err.message : "unknown error"}`);
+          }
         }
       }
-    }
-    console.log("");
-    success2(`Initialization complete!
+      console.log("");
+      success2(`Initialization complete!
 `);
-    if (!isReInit) {
-      console.log(import_picocolors5.default.bold("Next steps:"));
-      console.log(`  1. Use the ${import_picocolors5.default.cyan("init-agent")} in your AI tool to generate ${import_picocolors5.default.cyan(`${CONFIG_DIR}/context.md`)}`);
-      console.log(`     (or use the MCP server: ${import_picocolors5.default.cyan("levante_scan_codebase")} + ${import_picocolors5.default.cyan("levante_read_agent")})`);
-      console.log(`  2. Review the generated ${import_picocolors5.default.cyan(`${CONFIG_DIR}/context.md`)}`);
-      console.log(`  3. Run: ${import_picocolors5.default.cyan("levante run --key PROJ-101")}`);
-    } else {
-      console.log(import_picocolors5.default.dim("Config and context.md were preserved. Only agents and workflow were checked."));
+      if (!isReInit) {
+        console.log(import_picocolors5.default.bold("Next steps:"));
+        console.log(`  1. Use the ${import_picocolors5.default.cyan("init-agent")} in your AI tool to generate ${import_picocolors5.default.cyan(`${CONFIG_DIR}/context.md`)}`);
+        console.log(`     (or use the MCP server: ${import_picocolors5.default.cyan("levante_scan_codebase")} + ${import_picocolors5.default.cyan("levante_read_agent")})`);
+        console.log(`  2. Review the generated ${import_picocolors5.default.cyan(`${CONFIG_DIR}/context.md`)}`);
+        console.log(`  3. Run: ${import_picocolors5.default.cyan("levante run --key PROJ-101")}`);
+      } else {
+        console.log(import_picocolors5.default.dim("Config and context.md were preserved. Only agents and workflow were checked."));
+      }
+    } catch (err) {
+      if (err?.name === "ExitPromptError") {
+        process.exit(0);
+      }
+      throw err;
     }
   });
 }

package/package.json

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