@lisa.ai/agent 2.9.7 → 2.11.0

package/README.md

@@ -14,11 +14,32 @@ You need at least one LLM API key set as an environment variable:
 
 | Provider | Env var | Default model |
 |---|---|---|
-| Google Gemini | `GOOGLE_GENERATIVE_AI_API_KEY` | `gemini-2.0-flash` |
 | Anthropic Claude | `ANTHROPIC_API_KEY` | `claude-haiku-4-5` |
+| Google Gemini | `GOOGLE_GENERATIVE_AI_API_KEY` | `gemini-2.0-flash` |
 | OpenAI | `OPENAI_API_KEY` | `gpt-4o-mini` |
 
-Override the default model per provider with `LISA_GOOGLE_MODEL`, `LISA_CLAUDE_MODEL`, or `LISA_OPENAI_MODEL`.
+Override the default model per provider with `LISA_CLAUDE_MODEL`, `LISA_GOOGLE_MODEL`, or `LISA_OPENAI_MODEL`.
+
+## Quick Start
+
+```bash
+# 1. Set your API key
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# 2. (Optional) Create project config
+lisa-agent init
+
+# 3. Heal broken tests
+lisa-agent heal
+
+# 4. Generate missing unit tests
+lisa-agent unit
+
+# 5. Generate E2E tests
+lisa-agent e2e
+```
+
+**Zero config required.** The agent auto-detects your test framework, package manager, and builds the correct commands automatically.
 
 ## Commands
 
@@ -27,7 +48,7 @@ Override the default model per provider with `LISA_GOOGLE_MODEL`, `LISA_CLAUDE_M
 Runs your test command, identifies every failing spec, and autonomously fixes them using LLM-generated patches. Each fix is verified in isolation before moving on.
 
 ```bash
-lisa-agent heal --command "npm test" --model gemini
+lisa-agent heal
 
 # Heal specific files only (skip discovery)
 lisa-agent heal --files src/app/todo.spec.ts,src/app/auth.spec.ts
@@ -35,8 +56,8 @@ lisa-agent heal --files src/app/todo.spec.ts,src/app/auth.spec.ts
 # Heal E2E tests
 lisa-agent heal --type e2e
 
-# Heal specific E2E files
-lisa-agent heal --type e2e --files e2e/login.spec.ts
+# Heal in CI mode (commit + open PR)
+lisa-agent heal --ci
 ```
 
 **How it works:**
@@ -50,11 +71,10 @@ lisa-agent heal --type e2e --files e2e/login.spec.ts
 
 ### `unit` — Generate Unit Tests
 
-Runs your test suite with coverage enabled, identifies files below 100% coverage, and generates new test specs to close the gaps. Auto-detects your test framework and builds the correct coverage command.
+Runs your test suite with coverage enabled, identifies files below threshold, discovers source files with no tests at all, and generates new test specs to close the gaps.
 
 ```bash
-lisa-agent unit --model gemini
-lisa-agent unit --command "npx jest --coverage --coverageReporters=json-summary" --model claude
+lisa-agent unit
 
 # Generate tests for specific source files only
 lisa-agent unit --files src/services/auth.service.ts,src/services/user.service.ts
@@ -63,9 +83,9 @@ lisa-agent unit --files src/services/auth.service.ts,src/services/user.service.t
 **How it works:**
 1. Auto-detects test framework (Jest, Vitest, Karma, Mocha) and builds coverage command
 2. Runs tests with coverage, parses `coverage-summary.json`
-3. Identifies uncovered source files
+3. Identifies uncovered files from coverage report **and** source files with no spec at all
 4. Generates unit test specs targeting uncovered code via LLM
-5. If generated tests fail, delegates to the heal loop
+5. If generated tests fail, delegates to the heal loop automatically
 6. Re-runs coverage and reports delta
 
 **Auto-detected coverage commands:**
@@ -82,7 +102,7 @@ lisa-agent unit --files src/services/auth.service.ts,src/services/user.service.t
 Generates Playwright end-to-end tests by discovering your app's routes and creating specs for each page/flow. Auto-installs Playwright if no E2E framework is detected.
 
 ```bash
-lisa-agent e2e --model gemini
+lisa-agent e2e
 
 # Generate E2E test for a specific spec path
 lisa-agent e2e --files e2e/login.spec.ts
@@ -100,18 +120,12 @@ lisa-agent e2e --files e2e/login.spec.ts
 Generates integration tests that exercise module seams — testing 2+ modules together without full E2E overhead.
 
 ```bash
-lisa-agent integration --model gemini
+lisa-agent integration
 
 # Generate integration test for specific files
 lisa-agent integration --files src/services/auth.service.ts
 ```
 
-**How it works:**
-1. Detects app type (Angular, React, Express, NestJS, Node)
-2. Discovers integration targets: component+service pairs, controller files, multi-import modules
-3. Generates integration specs with real services (not mocked) via LLM
-4. Runs specs and heals failures
-
 **What it generates:**
 - **Angular:** TestBed with real services, multi-component interactions, `HttpClientTestingModule`
 - **Express/NestJS:** Supertest-based endpoint tests with test DB, middleware chains
@@ -122,7 +136,7 @@ lisa-agent integration --files src/services/auth.service.ts
 Scans your project for npm vulnerabilities, applies safe fixes automatically, and consults an LLM for breaking changes that need manual intervention.
 
 ```bash
-lisa-agent audit --model gemini
+lisa-agent audit
 ```
 
 **How it works:**
@@ -132,12 +146,52 @@ lisa-agent audit --model gemini
 4. **Targeted upgrades** — applies non-breaking semver-minor fixes
 5. **LLM guidance** — for remaining breaking/unfixable vulnerabilities, consults the LLM and saves a remediation report to `lisa-audit-report.md`
 
+### `chat` — Interactive Mode
+
+Multi-turn interactive REPL with streaming LLM responses. Ask questions about your project, analyze test failures, heal specific files, and generate tests — all in a conversational loop.
+
+```bash
+lisa-agent chat
+
+# Use a specific LLM provider
+lisa-agent chat -m claude
+```
+
+**Slash commands:**
+
+| Command | Description |
+|---|---|
+| `/test [cmd]` | Run tests and show results |
+| `/explain <file>` | Analyze why a test is failing (no file changes) |
+| `/heal <file>` | Auto-heal a specific failing test file |
+| `/generate <file>` | Generate test spec for a source file |
+| `/status` | Show test pass/fail summary |
+| `/help` | Show available commands |
+| `/exit` | Exit chat |
+
+**Example session:**
+```
+lisa> why would an Angular test get NullInjectorError for HttpClient?
+[streams explanation suggesting HttpClientTestingModule]
+
+lisa> /test
+Running: npx ng test --no-watch --browsers=ChromeHeadless...
+✗ 3 of 47 tests failed
+
+lisa> /heal src/app/services/auth.service.spec.ts
+Healing src/app/services/auth.service.spec.ts...
+✅ Healed via Cloud.
+
+lisa> /status
+[████████████████████] 100%  ✅ 47 passed  47 total
+```
+
 ### `diagnose` — Test LLM Connectivity
 
 Sends a simple probe to your configured LLM provider to verify your API key works and the model is reachable.
 
 ```bash
-lisa-agent diagnose --model claude
+lisa-agent diagnose
 ```
 
 ### `init` — Create Project Config
@@ -166,19 +220,19 @@ The generated workflow:
 4. If tests fail and Lisa heals them, opens a PR automatically
 5. Writes a step summary to the GitHub Actions UI
 
-**Required setup:** Add your LLM API key as a repository secret in GitHub (Settings > Secrets > Actions). The secret name depends on the provider:
+**Required setup:** Add your LLM API key as a repository secret in GitHub (Settings > Secrets > Actions).
 
 | Provider | Secret name |
 |---|---|
-| Gemini | `GOOGLE_GENERATIVE_AI_API_KEY` |
 | Claude | `ANTHROPIC_API_KEY` |
+| Gemini | `GOOGLE_GENERATIVE_AI_API_KEY` |
 | OpenAI | `OPENAI_API_KEY` |
 
 `GITHUB_TOKEN` is provided automatically by GitHub Actions — no PAT needed.
 
 ## Common Options
 
-All test commands (`heal`, `unit`, `e2e`, `integration`, `audit`) accept:
+All test commands (`heal`, `unit`, `e2e`, `integration`) accept:
 
 | Flag | Description | Default |
 |---|---|---|
@@ -197,8 +251,9 @@ Place a `.lisai.json` in your project root to configure the agent without CLI fl
 
 ```json
 {
-  "provider": "gemini",
-  "model": "gemini-2.0-flash",
+  "projectId": "my-project-123",
+  "provider": "claude",
+  "model": "claude-haiku-4-5",
   "testCommand": "npm test",
   "testingFramework": "jest",
   "e2eFramework": "playwright",
@@ -207,12 +262,17 @@ Place a `.lisai.json` in your project root to configure the agent without CLI fl
   "maxRetries": 5,
   "skipFiles": ["server.js", "app.js"],
   "skipDirs": ["scripts", "migrations"],
-  "skipPaths": ["src/generated", "src/fixtures"]
+  "skipPaths": ["src/generated", "src/fixtures"],
+  "lisaLlm": {
+    "enabled": true,
+    "model": "qwen2.5-coder:7b"
+  }
 }
 ```
 
 | Field | Type | Description |
 |---|---|---|
+| `projectId` | `string` | Control Plane project ID — saves you from passing `--project-id` every time |
 | `provider` | `gemini \| claude \| openai` | LLM provider |
 | `model` | `string` | Pin a specific model ID (e.g. `claude-sonnet-4-6`) |
 | `testCommand` | `string` | Override unit test command (skips auto-detection) |
@@ -220,27 +280,99 @@ Place a `.lisai.json` in your project root to configure the agent without CLI fl
 | `e2eFramework` | `playwright \| cypress` | Override E2E framework detection |
 | `e2eCommand` | `string` | Override E2E test command |
 | `testTypes` | `string[]` | Types of tests to generate: `unit`, `integration`, `e2e` |
-| `maxRetries` | `number` | Max heal/generation retries per session (default 5) |
+| `maxRetries` | `number` | Max heal/generation retries per file (default 5) |
 | `skipFiles` | `string[]` | Filenames to exclude from analysis |
 | `skipDirs` | `string[]` | Directory names to exclude |
 | `skipPaths` | `string[]` | Path prefixes to exclude |
+| `lisaLlm` | `object` | Lisa LLM local tier config (see below) |
 
 All fields are **optional**. The agent auto-detects everything. This file is the escape hatch for unusual setups.
 
+### Lisa LLM — Local-First Tier (v2.10.0)
+
+Lisa LLM adds a local LLM tier (Ollama or any OpenAI-compatible server) that attempts fixes **before** calling cloud APIs. When the Memory Engine has a high-confidence proven fix pattern, the agent tries the local model first — **zero API cost**. Falls back to cloud on failure.
+
+**Enable via `.lisai.json`:**
+```json
+{
+  "lisaLlm": {
+    "enabled": true,
+    "provider": "ollama",
+    "model": "qwen2.5-coder:7b",
+    "baseUrl": "http://localhost:11434",
+    "confidenceThreshold": 0.8
+  }
+}
+```
+
+**Or via environment variables:**
+```bash
+LISA_LLM_ENABLED=true
+LISA_LLM_MODEL=qwen2.5-coder:7b
+LISA_LLM_URL=http://localhost:11434
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `enabled` | `false` | Opt-in. Set `true` or `LISA_LLM_ENABLED=true` |
+| `provider` | `"ollama"` | Any OpenAI-compatible server works (LM Studio, LocalAI, vLLM) |
+| `model` | `"qwen2.5-coder:7b"` | Swappable — `deepseek-coder-v3`, `codestral`, etc. |
+| `baseUrl` | `"http://localhost:11434"` | Ollama default. Override for other servers |
+| `confidenceThreshold` | `0.8` | Minimum pattern confidence to trigger local tier |
+
+**How it works:**
+1. Memory Engine returns proven patterns with confidence scores
+2. If `confidence >= threshold` and Lisa LLM is enabled → Tier 1 (local) attempt
+3. Local fix verified → **done** (zero API cost, logged as `resolvedBy: 'lisa-llm'`)
+4. Local fix fails → falls through to Tier 2 (cloud) — **doesn't burn a retry**
+5. No high-confidence patterns → skip local, go directly to cloud
+
+**Requirements:** [Ollama](https://ollama.com/) running locally with a code model pulled:
+```bash
+ollama pull qwen2.5-coder:7b
+```
+
+**Dashboard:** The project page shows a "Lisa LLM vs Cloud" breakdown card with resolution counts and success rate when Lisa LLM data exists.
+
+### `.env` File
+
+The agent loads `.env` from your project root (the directory where you run the command). You can put all config here:
+
+```env
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+LISA_CLAUDE_MODEL=claude-sonnet-4-6
+LISA_CONTROL_PLANE_URL=http://localhost:3088
+```
+
 ### Config Priority
 
 Settings are resolved in this order (highest wins):
 
 ```
-Shell env var  >  Control Plane  >  CLI flag  >  .lisai.json  >  built-in default
+Shell env var  >  .lisai.json  >  Control Plane  >  CLI flag  >  built-in default
 ```
 
+`.lisai.json` overrides Control Plane defaults for `maxRetries` and `provider`, so you can always fine-tune locally even when connected to the Dashboard.
+
 ## Control Plane Integration
 
 Connect the agent to the Lisa.ai Dashboard for remote configuration, telemetry, and the Memory Engine:
 
+```json
+// .lisai.json
+{
+  "projectId": "my-project-123",
+  "provider": "claude"
+}
+```
+
+```bash
+lisa-agent heal    # automatically uses projectId from .lisai.json
+```
+
+Or via CLI flag:
 ```bash
-lisa-agent heal --command "npm test" --project-id "my-project-123"
+lisa-agent heal --project-id "my-project-123"
 ```
 
 With a project ID, the agent will:
@@ -257,7 +389,8 @@ The Memory Engine stores proven fix patterns from previous heal runs. When the a
 - Patterns are keyed by normalized error shape + framework + project
 - Only patterns with confidence >= 50% are injected
 - Confidence = `successCount / totalAttempts`, updated after each heal attempt
-- Memory is project-scoped and stored on the Control Plane (requires `--project-id`)
+- Memory is project-scoped and stored on the Control Plane (requires `projectId`)
+- Supports hybrid vector + exact search for semantically similar error matching
 
 ## Auto-Detection
 
@@ -273,77 +406,61 @@ The agent **adapts to your project** — zero config required. If no `--command`
 
 ### Heal a broken Angular project
 ```bash
-export GOOGLE_GENERATIVE_AI_API_KEY="your-key"
-lisa-agent heal --command "npx ng test --no-watch --browsers=ChromeHeadless" --model gemini
+export ANTHROPIC_API_KEY="sk-ant-..."
+lisa-agent heal
 ```
 
-### Generate unit tests for a Node.js API
+### Generate unit tests for uncovered files
 ```bash
-export ANTHROPIC_API_KEY="your-key"
-lisa-agent unit --model claude
+lisa-agent unit
 ```
 
 ### Generate Playwright E2E tests
 ```bash
-export GOOGLE_GENERATIVE_AI_API_KEY="your-key"
-lisa-agent e2e --model gemini
-```
-
-### Generate integration tests
-```bash
-export OPENAI_API_KEY="your-key"
-lisa-agent integration --model openai
-```
-
-### Fix npm vulnerabilities with LLM guidance
-```bash
-lisa-agent audit --model gemini
+lisa-agent e2e
 ```
 
 ### Target specific files (skip discovery for large projects)
 ```bash
-lisa-agent heal --files src/app/todo.spec.ts,src/app/auth.spec.ts --model gemini
-lisa-agent unit --files src/services/auth.service.ts --model claude
-lisa-agent e2e --files e2e/login.spec.ts --model gemini
-lisa-agent integration --files src/services/user.service.ts --model openai
+lisa-agent heal --files src/app/todo.spec.ts,src/app/auth.spec.ts
+lisa-agent unit --files src/services/auth.service.ts
+lisa-agent e2e --files e2e/login.spec.ts
+lisa-agent integration --files src/services/user.service.ts
 ```
 
 ### GitHub Actions CI — auto-heal on every push
 ```bash
-# One-time setup: generate the workflow file
-lisa-agent init-ci --model gemini
+# One-time setup
+lisa-agent init-ci --model claude
 
-# Then add your API key as a GitHub secret:
-#   Repo > Settings > Secrets > Actions > GOOGLE_GENERATIVE_AI_API_KEY
+# Add your API key as a GitHub secret:
+#   Repo > Settings > Secrets > Actions > ANTHROPIC_API_KEY
 
 # That's it! On every push, Lisa.ai will:
 #   1. Run your tests
 #   2. Auto-heal any failures
-#   3. Open a PR with the fixes for review
+#   3. Open a PR with the fixes
 ```
 
-### Run heal in CI mode locally (test without pushing)
+### Full pipeline with Control Plane
 ```bash
-lisa-agent heal --ci --model gemini
-# Runs the full heal loop, then attempts to commit + open PR.
-# Without GITHUB_TOKEN set, PR creation is gracefully skipped.
-```
-
-### Full CI/CD pipeline with Control Plane
-```bash
-lisa-agent heal --command "npm test" --model gemini --project-id "prod-api"
-lisa-agent unit --model gemini --project-id "prod-api"
-lisa-agent e2e --model gemini --project-id "prod-api"
-lisa-agent integration --model gemini --project-id "prod-api"
-lisa-agent audit --model gemini --project-id "prod-api"
+lisa-agent heal --project-id "prod-api"
+lisa-agent unit --project-id "prod-api"
+lisa-agent e2e --project-id "prod-api"
+lisa-agent integration --project-id "prod-api"
+lisa-agent audit --project-id "prod-api"
 ```
 
 ## Requirements
 
 - Node.js 18+
-- At least one LLM API key (Gemini, Claude, or OpenAI)
+- At least one LLM API key (Claude, Gemini, or OpenAI)
 - A JavaScript/TypeScript project with a test suite
 
+## License
+
+ISC
+
 ---
 
-*Built by the Lisa.ai Platform team.*
+*Built by the Lisa.ai team.*