opencroc 1.8.3 → 1.8.4

package/README.md

@@ -1,417 +1,383 @@
-<p align="center">
-  <img src="assets/banner.png" alt="OpenCroc banner" width="820" />
-</p>
-
-<h1 align="center">OpenCroc</h1>
-
-<p align="center">
-  <strong>AI-native E2E testing framework that reads your source code, generates tests, and self-heals failures.</strong>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
-  <a href="https://github.com/opencroc/opencroc/actions/workflows/ci.yml"><img src="https://github.com/opencroc/opencroc/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
-  <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
-  <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
-</p>
-
-<p align="center">
-  <a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.ja.md">日本語</a>
-</p>
-
----
-
-## What is OpenCroc?
-
-OpenCroc is an **AI-native end-to-end testing framework** built on top of [Playwright](https://playwright.dev). Instead of writing test scripts by hand, OpenCroc **reads your backend source code** (models, controllers, DTOs) and automatically generates complete E2E test suites — including API chains, seed data, request bodies, and assertions.
-
-When tests fail, OpenCroc doesn't just report errors — it **traces the root cause** through the full request chain, **generates fix patches**, and **re-runs tests to verify the fix** — all autonomously.
-
-### Key Capabilities
-
-| Capability | Description |
-|---|---|
-| **Source-Aware Test Generation** | Parses Sequelize/TypeORM models, Express/NestJS controllers, and DTO decorators via [ts-morph](https://ts-morph.com) to understand your API surface |
-| **AI-Driven Configuration** | LLM generates request body templates, seed data, parameter mappings — validated by 3-layer verification (schema → semantic → dry-run) |
-| **Intelligent Chain Planning** | Builds API dependency DAGs, performs topological sorting, and plans test chains with greedy coverage optimization |
-| **Log-Driven Completion Detection** | Goes beyond `networkidle` — verifies request completion by matching backend execution logs (`api_exec end`) |
-| **Failure Chain Attribution** | Traces failures through the full call chain: network errors → slow APIs → backend logs → root cause |
-| **Controlled Self-Healing** | `backup → AI patch → dry-run → apply → re-run → verify → rollback` — with safety gates at every step |
-| **Impact Analysis** | BFS traversal of foreign key relations to map blast radius, auto-generates Mermaid diagrams |
-
-## Quick Start
-
-### Prerequisites
-
-- Node.js >= 18
-- A backend project with Express/NestJS + Sequelize/TypeORM
-
-### Installation
-
-```bash
-npm install opencroc --save-dev
-```
-
-### Initialize
-
-```bash
-npx opencroc init
-```
-
-This will:
-1. Scan your project structure
-2. Detect your ORM and framework
-3. Create `opencroc.config.ts` with sensible defaults
-4. Generate a sample test suite
-
-### Generate Tests
-
-```bash
-# Generate tests for a single module
-npx opencroc generate --module=knowledge-base
-
-# Generate tests for all detected modules
-npx opencroc generate --all
-
-# Dry-run (preview without writing files)
-npx opencroc generate --all --dry-run
-```
-
-### Run Tests
-
-```bash
-# Run all generated tests
-npx opencroc test
-
-# Run specific module
-npx opencroc test --module=knowledge-base
-
-# Run in headed browser mode
-npx opencroc test --headed
-
-# Override lifecycle hooks from CLI
-npx opencroc test --setup-hook="npm run e2e:setup" --auth-hook="node scripts/auth.js" --teardown-hook="npm run e2e:cleanup"
-```
-
-### Validate AI Configs
-
-```bash
-# Validate generated configurations
-npx opencroc validate --all
-
-# Compare AI-generated vs baseline results
-npx opencroc compare --baseline=report-a.json --current=report-b.json
-```
-
-### Launch OpenCroc Studio
-
-OpenCroc Studio is a **pixel-art croc office** with a real-time **knowledge graph** UI. It runs as a local web server and visualizes your project structure, agent status, and test results.
-
-```bash
-# Start Studio (opens browser at http://localhost:8765)
-npx opencroc serve
-
-# Custom port
-npx opencroc serve --port 3000
-
-# Don't auto-open browser
-npx opencroc serve --no-open
-
-# Specify host (e.g. for remote access)
-npx opencroc serve --host 0.0.0.0 --port 8765
-```
-
-Studio features:
-- **Knowledge Graph Canvas** — interactive graph of your project's models, controllers, and API relations (drag, zoom, hover)
-- **Pixel Croc Office** — 6 AI agents (Parser 🐊, Analyzer 🐊, Tester 🐊, Healer 🐊, Planner 🐊, Reporter 🐊) with live status animations
-- **Real-time WebSocket** — agent status and graph changes push to the browser instantly
-- **Module Sidebar** — browse discovered modules and agent states at a glance
-- **REST API** — `GET /api/project` (graph data), `GET /api/agents` (agent states), `POST /api/project/refresh` (re-scan)
-
-### Full Pipeline (One Command)
-
-```bash
-# Run everything: generate → execute → analyze → heal → report
-npx opencroc run
-
-# With options
-npx opencroc run --module=users --self-heal --report html,json
-```
-
-### CI/CD Integration
-
-```bash
-# Generate GitHub Actions workflow
-npx opencroc ci --platform github
-
-# Generate GitLab CI pipeline
-npx opencroc ci --platform gitlab --self-heal
-```
-
-### Dashboard & Reports
-
-```bash
-# Generate visual dashboard
-npx opencroc dashboard
-
-# Generate reports in multiple formats
-npx opencroc report --format html,json,markdown
-```
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│              OpenCroc Studio (localhost:8765)                │
-│    Pixel Croc Office  +  Knowledge Graph  +  WebSocket      │
-├─────────────────────────────────────────────────────────────┤
-│                     CLI / Orchestrator                       │
-├──────────┬──────────┬──────────┬──────────┬─────────────────┤
-│  Source   │  Chain   │  Test    │ Execution│   Self-Healing  │
-│  Parser   │ Planner  │Generator │  Engine  │     Engine      │
-│           │          │          │          │                 │
-│ ts-morph  │ DAG +    │ Template │Playwright│ AI Attribution  │
-│ Model     │ Topo     │ + AI     │ + Log    │ + Controlled    │
-│ Controller│ Sort +   │ Config   │ Driven   │ Fix + Verify    │
-│ DTO       │ Greedy   │ Merge    │ Assert   │ + Rollback      │
-├──────────┴──────────┴──────────┴──────────┴─────────────────┤
-│              Observation Bus (Network + Backend Logs)         │
-├──────────────────────────────────────────────────────────────┤
-│              Report Engine (HTML / JSON / Markdown)           │
-└──────────────────────────────────────────────────────────────┘
-```
-
-### 6-Stage Pipeline
-
-```
-Source Scan → ER Diagram → API Analysis → Chain Planning → Test Generation → Failure Analysis
-     │            │             │              │                │                  │
-  ts-morph    Mermaid      Dependency       Topological     Playwright +      Root Cause +
-  parsing     erDiagram    DAG builder      + greedy        AI body/seed      Impact map
-```
-
-## How It Works
-
-### 1. Source Parsing
-
-OpenCroc uses [ts-morph](https://ts-morph.com) to statically analyze your backend:
-
-- **Models**: Extracts table names, column types, indexes, and foreign keys from Sequelize `Model.init()` / TypeORM `@Entity()`
-- **Controllers**: Extracts routes, HTTP methods, path parameters from Express `router.get/post/put/delete`
-- **DTOs**: Extracts validation rules from `@IsString()`, `@IsNumber()`, `@IsOptional()` decorators
-
-### 2. AI Configuration Generation
-
-For each module, OpenCroc calls an LLM (OpenAI / ZhiPu / any OpenAI-compatible API) to generate:
-
-- **Request body templates** — field-accurate POST/PUT payloads
-- **Seed data** — `beforeAll` setup steps with correct API sequences
-- **Parameter mappings** — path parameter aliases (`/:id` → `categoryId`)
-- **ID aliases** — preventing ID conflicts across multi-resource chains
-
-Each config is validated through **3 layers**:
-1. **Schema validation** — JSON structure completeness
-2. **Semantic validation** — field values match source code metadata
-3. **Dry-run validation** — TypeScript compilation check
-
-Failed configs are **automatically fixed** (up to 3 rounds) before being written.
-
-### 3. Log-Driven Completion
-
-Instead of relying on fragile `networkidle` signals:
-
-```
-Frontend Request → Backend api_exec start log → Backend processing → api_exec end log
-                                                                          ↓
-                                              OpenCroc polls end logs to confirm completion
-```
-
-This catches cases where the frontend appears idle but the backend is still processing.
-
-### 4. Self-Healing Loop
-
-```
-Test Failure
-  → AI Attribution (LLM + heuristic fallback)
-  → Generate Fix Patch
-  → Dry-Run Validation
-  → Apply Patch (with backup)
-  → Re-run Failed Tests
-  → Verify Fix
-  → Commit or Rollback
-```
-
-## Real-World Validation
-
-OpenCroc has been validated against a **production-scale RBAC system** (multi-tenant enterprise permission management) with 100+ Sequelize models, 75+ Express controllers, and embedded associations:
-
-```
-$ npx tsx examples/rbac-system/smoke-test.ts
-
-Modules        : 5 (default, aigc, data-platform, integration, workflow)
-ER Diagrams    : 5
-  [default] 102 tables, 65 relations
-  [aigc] 6 tables, 0 relations
-  [data-platform] 4 tables, 0 relations
-  [integration] 14 tables, 0 relations
-  [workflow] 2 tables, 0 relations
-Chain Plans    : 5
-  [aigc] 78 chains, 150 steps
-Generated Files: 78
-Duration       : 1153ms
-```
-
-Key findings:
-- **102 tables** and **65 foreign key relations** correctly extracted from flat model layout
-- **Embedded associations** (`.belongsTo()` / `.hasMany()` inside model files) detected without dedicated association files
-- **78 test files** generated across 5 modules in just over 1 second
-- Handles both flat (`models/*.ts`) and nested (`models/module/*.ts`) directory structures
-
-## Configuration
-
-```typescript
-// opencroc.config.ts
-import { defineConfig } from 'opencroc';
-
-export default defineConfig({
-  // Backend source paths
-  backend: {
-    modelsDir: 'src/models',
-    controllersDir: 'src/controllers',
-    servicesDir: 'src/services',
-  },
-
-  // Target application
-  baseUrl: 'http://localhost:3000',
-  apiBaseUrl: 'http://localhost:3000/api',
-
-  // AI configuration
-  ai: {
-    provider: 'openai',        // 'openai' | 'zhipu' | 'custom'
-    apiKey: process.env.AI_API_KEY,
-    model: 'gpt-4o-mini',
-  },
-
-  // Test execution
-  execution: {
-    workers: 4,
-    timeout: 30_000,
-    retries: 1,
-  },
-
-  // Log-driven completion (requires backend instrumentation)
-  logCompletion: {
-    enabled: true,
-    endpoint: '/internal/test-logs',
-    pollIntervalMs: 500,
-    timeoutMs: 10_000,
-  },
-
-  // Self-healing
-  selfHealing: {
-    enabled: false,
-    fixScope: 'config-only',   // 'config-only' | 'config-and-source'
-    maxFixRounds: 3,
-    dryRunFirst: true,
-  },
-});
-```
-
-## Supported Tech Stacks
-
-| Layer | Supported | Planned |
-|---|---|---|
-| **ORM** | Sequelize, TypeORM, Prisma, Drizzle | — |
-| **Framework** | Express | NestJS, Fastify, Koa |
-| **Test Runner** | Playwright | — |
-| **LLM** | OpenAI, ZhiPu (GLM), Ollama (local) | Anthropic |
-| **Database** | MySQL, PostgreSQL | SQLite, MongoDB |
-
-## Comparison
-
-| Feature | OpenCroc | Playwright | Metersphere | auto-playwright |
-|---|---|---|---|---|
-| Source-aware generation | ✅ | ❌ | ❌ | ❌ |
-| AI config generation + validation | ✅ | ❌ | ❌ | ❌ |
-| Log-driven completion | ✅ | ❌ | ❌ | ❌ |
-| Failure chain attribution | ✅ | ❌ | Partial | ❌ |
-| Self-healing with rollback | ✅ | ❌ | ❌ | ❌ |
-| API dependency DAG | ✅ | ❌ | ❌ | ❌ |
-| Zero-config test generation | ✅ | Codegen only | Manual | NL→action |
-| Impact blast radius analysis | ✅ | ❌ | ❌ | ❌ |
-
-## Roadmap
-
-- [x] 6-stage source-to-test pipeline
-- [x] AI configuration generation with 3-layer validation
-- [x] Controlled self-healing loop
-- [x] Log-driven completion detection
-- [x] Failure chain attribution + impact analysis
-- [x] TypeORM / Prisma adapter
-- [x] Ollama local LLM support
-- [x] Real-world validation (102 tables, 65 relations, 78 generated tests)
-- [x] GitHub Actions / GitLab CI integration
-- [x] VS Code extension scaffold
-- [x] Plugin system
-- [x] HTML / JSON / Markdown report generation
-- [x] NestJS controller parser
-- [x] Visual dashboard (opencroc.com)
-- [x] Drizzle ORM adapter
-- [x] AI Config Suggester + Enhanced DTO-aware Suggester
-- [x] Auto-Fixer (4 strategies: interface-path, DTO field, seed dependency, param mapping)
-- [x] 3-layer config validation (schema → semantic → dry-run)
-- [x] DTO Parser (ts-morph interface + express-validator extraction)
-- [x] Baseline Comparator (Playwright report diff + regression detection)
-- [x] Module config preset loader
-- [x] LLM-enhanced chain planner
-- [x] Runtime infrastructure (Playwright config, auth setup, teardown, network monitor)
-- [x] Full orchestration pipeline
-- [x] Advanced reporters (checklist, workorder, token tracking)
-- [x] OpenCroc Studio — pixel croc office + knowledge graph UI (`opencroc serve`)
-
-## Release Snapshot
-
-- Current stable release: `1.3.0`
-- npm dist-tag `latest`: `1.3.0`
-- Roadmap status: M1 Studio delivered
-- Full-suite quality gate: 34 test files / 373 tests passing on Node.js 20.x & 22.x
-
-### Version Rhythm
-
-- `0.3.x`: plugin system, CI templates, reporters, VS Code scaffold, CI hardening
-- `0.4.x`: NestJS controller parser
-- `0.5.x`: Drizzle ORM adapter
-- `0.6.x`: visual dashboard + Windows Vitest stability hardening
-- `0.7.x – 0.9.x`: runtime infrastructure (Playwright generators, auth, log-driven detection, rules engine)
-- `1.0.0`: full orchestration pipeline
-- `1.1.0`: advanced self-healing (dialog loop, controlled fixer, auto-fix PR generation)
-- `1.2.0`: advanced reporters (checklist, workorder, token tracking) + Sprint 0-3 migration complete
-- `1.3.0`: OpenCroc Studio M1 — Fastify server, knowledge graph API, pixel croc office frontend
-
-### Release Verification
-
-```bash
-npm run lint
-npm run typecheck
-npm test
-npm view opencroc version dist-tags --json
-```
-
-## Documentation
-
-Visit **[opencroc.com](https://opencroc.com)** for full documentation, or browse:
-
-- [Architecture Guide](docs/architecture.md)
-- [Configuration Reference](docs/configuration.md)
-- [Backend Instrumentation Guide](docs/backend-instrumentation.md)
-- [AI Provider Setup](docs/ai-providers.md)
-- [Self-Healing Guide](docs/self-healing.md)
-- [Troubleshooting](docs/troubleshooting.md)
-
-## Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-## License
-
-[MIT](LICENSE) © 2026 OpenCroc Contributors
+<p align="center">
+  <img src="assets/banner.png" alt="OpenCroc banner" width="820" />
+</p>
+
+<h1 align="center">OpenCroc</h1>
+
+<p align="center">
+  <strong>AI-native E2E testing framework that reads source code, generates tests, and self-heals failures.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencroc"><img src="https://img.shields.io/npm/v/opencroc?color=green" alt="npm version" /></a>
+  <a href="https://github.com/opencroc/opencroc/actions/workflows/ci.yml"><img src="https://github.com/opencroc/opencroc/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
+  <a href="https://github.com/opencroc/opencroc/blob/main/LICENSE"><img src="https://img.shields.io/github/license/opencroc/opencroc" alt="MIT License" /></a>
+  <a href="https://opencroc.com"><img src="https://img.shields.io/badge/docs-opencroc.com-blue" alt="Documentation" /></a>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh-CN.md">Simplified Chinese</a> | <a href="README.ja.md">Japanese</a>
+</p>
+
+---
+
+## What is OpenCroc?
+
+OpenCroc is an AI-native end-to-end testing framework built on top of [Playwright](https://playwright.dev). Instead of writing test scripts by hand, OpenCroc reads backend source code, understands models, controllers, DTOs, and relations, then generates complete E2E suites with seed data, request bodies, API chains, and assertions.
+
+When tests fail, OpenCroc does more than report the error. It traces the failure across the request chain, attributes likely root causes, proposes fixes, and can re-run verification after controlled healing steps.
+
+## Key Capabilities
+
+| Capability | Description |
+| --- | --- |
+| Source-aware generation | Parses Sequelize, TypeORM, Prisma, and Drizzle structures to understand modules, models, routes, and DTOs |
+| AI-driven config generation | Produces request templates, seed plans, parameter mappings, and test scaffolds with validation gates |
+| Chain planning | Builds dependency DAGs and plans execution order for higher API coverage |
+| Log-driven completion | Uses backend execution signals instead of relying only on `networkidle` |
+| Failure attribution | Traces issues across frontend requests, backend logs, and dependency chains |
+| Controlled self-healing | Supports backup, patch, dry-run, re-run, verify, and rollback loops |
+| Visual Studio | Ships a local web UI for graph exploration, agent activity, and pixel-office monitoring |
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18 or newer
+- A backend project using Express or NestJS
+- One of the supported ORM or schema patterns
+
+### Installation
+
+```bash
+npm install opencroc --save-dev
+```
+
+### Initialize
+
+```bash
+npx opencroc init
+```
+
+This will:
+
+1. Scan your project structure
+2. Detect your framework and ORM patterns
+3. Create `opencroc.config.ts`
+4. Generate a starter output layout
+
+### Generate Tests
+
+```bash
+# Generate tests for a single module
+npx opencroc generate --module=knowledge-base
+
+# Generate tests for all detected modules
+npx opencroc generate --all
+
+# Preview without writing files
+npx opencroc generate --all --dry-run
+```
+
+### Run Tests
+
+```bash
+# Run all generated tests
+npx opencroc test
+
+# Run a single module
+npx opencroc test --module=knowledge-base
+
+# Run in headed mode
+npx opencroc test --headed
+
+# Override hooks from the CLI
+npx opencroc test --setup-hook="npm run e2e:setup" --auth-hook="node scripts/auth.js" --teardown-hook="npm run e2e:cleanup"
+```
+
+### Validate AI Configs
+
+```bash
+npx opencroc validate --all
+npx opencroc compare --baseline=report-a.json --current=report-b.json
+```
+
+## OpenCroc Studio
+
+OpenCroc Studio is the local visual workspace for OpenCroc. It combines a knowledge graph view, a pixel-office operations view, and a 3D office runtime into one web experience served by the CLI.
+
+### Launch Studio
+
+```bash
+# Start Studio and open the browser
+npx opencroc serve
+
+# Custom port
+npx opencroc serve --port 3000
+
+# Disable browser auto-open
+npx opencroc serve --no-open
+
+# Bind a public host
+npx opencroc serve --host 0.0.0.0 --port 8765
+```
+
+### Current Web Architecture
+
+- Fastify serves the local Studio application and API endpoints
+- The frontend is a single-entry Vite SPA
+- The main routes are `/`, `/studio`, and `/pixel`
+- The web source is organized under `src/web` with `app`, `pages`, `features`, `shared`, `styles`, and `public`
+- Legacy entry URLs such as `/index-studio.html` and `/index-v2-pixel.html` are redirected to SPA routes
+
+### Studio Features
+
+- Knowledge graph canvas for modules, APIs, and relations
+- Pixel-office dashboard for live agent activity
+- 3D office runtime view for immersive monitoring
+- Real-time updates over WebSocket
+- Sidebar navigation and route-based view switching
+- REST endpoints such as `GET /api/project`, `GET /api/agents`, and `POST /api/project/refresh`
+
+## Full Pipeline
+
+```bash
+# Run the full pipeline
+npx opencroc run
+
+# Run a module with self-healing and reports
+npx opencroc run --module=users --self-heal --report html,json
+```
+
+## CI/CD Integration
+
+```bash
+npx opencroc ci --platform github
+npx opencroc ci --platform gitlab --self-heal
+```
+
+## Dashboard and Reports
+
+```bash
+npx opencroc dashboard
+npx opencroc report --format html,json,markdown
+```
+
+## Architecture
+
+```text
++-------------------------------------------------------------------+
+| OpenCroc Studio                                                   |
+| Fastify server + single-entry Vite SPA + WebSocket updates        |
+| Routes: /, /studio, /pixel                                        |
++-------------------------------------------------------------------+
+| CLI / Orchestrator                                                |
++--------------+--------------+---------------+----------------------+
+| Source Parse | Chain Plan   | Test Generate | Execute / Observe    |
++--------------+--------------+---------------+----------------------+
+| Self-Heal    | Impact Map   | Reports       | Dashboard / Studio   |
++--------------+--------------+---------------+----------------------+
+```
+
+### 6-Stage Pipeline
+
+```text
+Source Scan -> ER Diagram -> API Analysis -> Chain Planning -> Test Generation -> Failure Analysis
+```
+
+## How It Works
+
+### 1. Source Parsing
+
+OpenCroc uses [ts-morph](https://ts-morph.com) and framework-aware parsers to analyze:
+
+- Models and relations
+- Controllers and routes
+- DTO fields and validation rules
+- Module boundaries and dependency surfaces
+
+### 2. AI Configuration Generation
+
+For each module, OpenCroc can generate:
+
+- Request body templates
+- Seed data plans
+- Parameter mappings
+- ID alias rules
+
+Each config passes through validation stages:
+
+1. Schema validation
+2. Semantic validation
+3. Dry-run validation
+
+### 3. Log-Driven Completion
+
+Instead of depending only on browser idle heuristics, OpenCroc can watch backend completion signals and correlate them with frontend actions.
+
+### 4. Self-Healing Loop
+
+```text
+Test Failure
+-> Attribution
+-> Proposed Fix
+-> Dry-Run Validation
+-> Apply Patch
+-> Re-run
+-> Verify
+-> Rollback if needed
+```
+
+## Real-World Validation
+
+OpenCroc has been exercised against a production-style RBAC system with more than 100 Sequelize models, dozens of controllers, and embedded associations.
+
+```bash
+$ npx tsx examples/rbac-system/smoke-test.ts
+
+Modules        : 5
+ER Diagrams    : 5
+Chain Plans    : 5
+Generated Files: 78
+Duration       : 1153ms
+```
+
+Key findings:
+
+- 102 tables and 65 foreign-key relations extracted from a flat model layout
+- Embedded associations detected without requiring dedicated association files
+- 78 generated test files across 5 modules
+- Support for both flat and nested directory layouts
+
+## Configuration
+
+```typescript
+import { defineConfig } from 'opencroc';
+
+export default defineConfig({
+  backend: {
+    modelsDir: 'src/models',
+    controllersDir: 'src/controllers',
+    servicesDir: 'src/services',
+  },
+
+  baseUrl: 'http://localhost:3000',
+  apiBaseUrl: 'http://localhost:3000/api',
+
+  ai: {
+    provider: 'openai',
+    apiKey: process.env.AI_API_KEY,
+    model: 'gpt-4o-mini',
+  },
+
+  execution: {
+    workers: 4,
+    timeout: 30_000,
+    retries: 1,
+  },
+
+  logCompletion: {
+    enabled: true,
+    endpoint: '/internal/test-logs',
+    pollIntervalMs: 500,
+    timeoutMs: 10_000,
+  },
+
+  selfHealing: {
+    enabled: false,
+    fixScope: 'config-only',
+    maxFixRounds: 3,
+    dryRunFirst: true,
+  },
+});
+```
+
+## Supported Tech Stacks
+
+| Layer | Supported | Planned |
+| --- | --- | --- |
+| ORM | Sequelize, TypeORM, Prisma, Drizzle | More adapters as needed |
+| Framework | Express | NestJS, Fastify, Koa |
+| Test Runner | Playwright | Additional runners |
+| LLM | OpenAI, ZhiPu, Ollama | Anthropic |
+| Database | MySQL, PostgreSQL | SQLite, MongoDB |
+
+## Comparison
+
+| Feature | OpenCroc | Playwright | Metersphere | auto-playwright |
+| --- | --- | --- | --- | --- |
+| Source-aware generation | Yes | No | No | No |
+| AI config generation and validation | Yes | No | No | No |
+| Log-driven completion | Yes | No | No | No |
+| Failure attribution | Yes | No | Partial | No |
+| Self-healing with rollback | Yes | No | No | No |
+| API dependency DAG | Yes | No | No | No |
+| Zero-config test generation | Yes | Limited | Manual | Prompt-driven |
+| Impact analysis | Yes | No | No | No |
+
+## Roadmap
+
+- [x] 6-stage source-to-test pipeline
+- [x] AI configuration generation with validation
+- [x] Controlled self-healing loop
+- [x] Log-driven completion detection
+- [x] Failure attribution and impact analysis
+- [x] Prisma and Drizzle adapters
+- [x] Ollama local LLM support
+- [x] CI integration
+- [x] VS Code extension scaffold
+- [x] Plugin system
+- [x] HTML, JSON, and Markdown reports
+- [x] Visual Studio dashboard
+- [x] Runtime infrastructure
+- [x] Full orchestration pipeline
+- [x] Advanced reporters
+- [x] OpenCroc Studio route-based web app
+
+## Release Snapshot
+
+- Product snapshot covered by this README: `1.8.3`
+- Studio architecture snapshot: Fastify + single-entry Vite SPA + route-based views
+- Main Studio routes: `/`, `/studio`, `/pixel`
+- Full-suite quality gate: 41 test files and 414 tests passing
+
+### Version Rhythm
+
+- `0.3.x`: plugin system, CI templates, reporters, VS Code scaffold
+- `0.4.x`: NestJS controller parser
+- `0.5.x`: Drizzle ORM adapter
+- `0.6.x`: visual dashboard and Windows Vitest stability work
+- `0.7.x - 0.9.x`: runtime infrastructure, auth, log-driven detection, rules engine
+- `1.0.0`: full orchestration pipeline
+- `1.1.0`: advanced self-healing
+- `1.2.0`: advanced reporters and migration work
+- `1.3.0`: OpenCroc Studio M1
+- `1.8.3`: Vite SPA routing, web architecture cleanup, package slimming
+
+### Release Verification
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm view opencroc version dist-tags --json
+```
+
+## Documentation
+
+Visit **[opencroc.com](https://opencroc.com)** for documentation, or browse:
+
+- [Architecture Guide](docs/architecture.md)
+- [Configuration Reference](docs/configuration.md)
+- [Backend Instrumentation Guide](docs/backend-instrumentation.md)
+- [AI Provider Setup](docs/ai-providers.md)
+- [Self-Healing Guide](docs/self-healing.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## Contributing
+
+We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](LICENSE) Copyright 2026 OpenCroc Contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencroc",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "description": "AI-native project intelligence platform — universal scanner, knowledge graph, risk analysis, multi-perspective reports, and E2E testing",
   "keywords": [
     "project-intelligence",