playwright-intelligence-engine 2.0.1 → 2.0.2

package/README.md

@@ -1,229 +1,229 @@
-# Playwright Intelligence Engine (`pw-intel`)
-
-> Fast, verification-first failure diagnosis, autonomous self-healing, and test generation for Microsoft Playwright suites.
-
-[![npm version](https://img.shields.io/npm/v/playwright-intelligence-engine.svg?style=flat-square)](https://www.npmjs.com/package/playwright-intelligence-engine)
-[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg?style=flat-square)](LICENSE)
-[![Node](https://img.shields.io/badge/Node->=20.0.0-green.svg?style=flat-square)](https://nodejs.org/)
-[![Playwright](https://img.shields.io/badge/Playwright->=1.30-orange.svg?style=flat-square)](https://playwright.dev/)
-
----
-
-## 1. Installation
-
-Run without installing via `npx`:
-```bash
-npx pw-intel --help
-```
-
-Or install in your project:
-```bash
-npm install --save-dev playwright-intelligence-engine
-```
-
-Or install globally:
-```bash
-npm install -g playwright-intelligence-engine
-```
-
-*(Both `pw-intel` and `playwright-intelligence-engine` commands are available).*
-
----
-
-## 2. Project Setup & LLM Configuration
-
-Initialize PIE in your Playwright repository:
-
-```bash
-npx pw-intel init
-```
-
-### Providing your LLM API Key (Optional)
-
-> **Note:** Failure diagnosis, trace analysis, and AST test repairs run **100% offline and locally** without an LLM key.
-> An API key is only needed if you want AI-assisted test generation (`pw-intel generate-agent`).
-
-You can configure an LLM key in any of three ways:
-
-#### Option A: During `init`
-```bash
-npx pw-intel init --api-key sk-your-openai-or-deepseek-key --model gpt-4o
-```
-*This automatically creates `.env` and adds it to your `.gitignore`.*
-
-#### Option B: Environment Variable
-```bash
-export OPENAI_API_KEY="sk-..."
-# or
-export PIE_LLM_API_KEY="sk-..."
-```
-
-#### Option C: In `.env`
-Create `.env` in your project root:
-```ini
-PIE_LLM_API_KEY=sk-...
-PIE_LLM_MODEL=gpt-4o
-PIE_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
-```
-
-Verify your setup at any time:
-```bash
-npx pw-intel doctor
-```
-
----
-
-## 3. How to Use
-
-### 🔍 A. Diagnose a Failing Test
-Ingest a Playwright trace archive (`trace.zip`) to find the exact root cause:
-
-```bash
-npx pw-intel diagnose ./test-results/trace.zip
-```
-
-**Output example:**
-```json
-{
-  "category": "LOCATOR_DRIFT",
-  "confidence": 0.94,
-  "action": "click",
-  "failingSelector": "#checkout-btn-v1",
-  "suggestedSelector": "button:has-text(\"Proceed to Checkout\")",
-  "targetFile": "e2e/pages/CartPage.ts",
-  "evidence": "Element ID changed dynamically; stable accessible role match found."
-}
-```
-
-If the failure was caused by a backend crash (HTTP 500) or expired authentication (HTTP 401), PIE flags it immediately and abstains from modifying locators.
-
----
-
-### 🔧 B. Autonomous Test Repair (Safe Worktrees)
-Repair a broken test or Page Object without risking your active Git branch:
-
-```bash
-# 1. Plan and test the repair in an isolated Git worktree:
-npx pw-intel autonomous-repair ./test-results/trace.zip --execute
-
-# 2. Check the cryptographic proposal:
-npx pw-intel approve <proposalId>
-
-# 3. Promote the verified fix atomically to your workspace:
-npx pw-intel promote --token <approvalToken>
-```
-
-**The Safety Guarantee:**
-- PIE **never** deletes or weakens your assertions (`expect(...)`).
-- PIE **never** alters test inputs or reorders user actions.
-- All repairs are executed and proven passing in a background worktree before promotion.
-
----
-
-### 🚀 C. Generate Tests from Requirements
-Generate complete Playwright test suites and Page Objects that conform to your repository's conventions:
-
-```bash
-npx pw-intel generate-agent ./requirements.json --mode brownfield --write --verify
-```
-
-**Arguments:**
-- `--mode brownfield`: Reuses existing fixtures, auth states, and Page Objects without generating duplicate login steps.
-- `--mode greenfield`: Scaffolds a new end-to-end testing architecture from scratch.
-- `--write`: Saves the generated files to disk.
-- `--verify`: Runs TypeScript typecheck and Playwright discovery to ensure generated code compiles.
-
----
-
-### 🧪 D. Reproduce a Spec with Live Instrumentation
-Rerun a flaky test with live DOM snapshots, network capture, and console logs:
-
-```bash
-npx pw-intel reproduce tests/checkout.spec.ts
-```
-
----
-
-### 📊 E. CI/CD Quality Gate & SARIF Reporting
-Convert Playwright test results into GitHub Actions annotations and SARIF security/flakiness reports:
-
-```bash
-npx pw-intel ci-report ./test-results/results.json --sarif-out ./pie-results.sarif
-```
-
----
-
-## 4. Cursor / Claude Code IDE Integration (MCP Server)
-
-PIE includes a built-in Model Context Protocol (MCP) server so AI coding assistants can diagnose traces and fix tests directly inside your IDE.
-
-### For Cursor / Windsurf
-Add to `.cursor/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "playwright-intelligence": {
-      "command": "npx",
-      "args": ["-y", "playwright-intelligence-engine", "mcp"]
-    }
-  }
-}
-```
-
-### For Claude Desktop / Claude Code
-Add to `claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "pw-intel": {
-      "command": "npx",
-      "args": ["-y", "playwright-intelligence-engine", "mcp"]
-    }
-  }
-}
-```
-
-**Available MCP Tools:**
-- `diagnose_trace`: Diagnoses Playwright traces and provides root causes.
-- `repair_page_object`: Stages isolated repairs with cryptographic approval tokens.
-- `generate_playwright_test`: Generates tests matching your repository's conventions.
-- `ingest_playwright_report`: Analyzes test run failures and flakiness.
-
----
-
-## 5. CLI Command Cheat Sheet
-
-| Command | Usage | Description |
-| :--- | :--- | :--- |
-| `init` | `pw-intel init [--api-key <k>]` | Initializes `.pie/config.json` & optional LLM credentials |
-| `doctor` | `pw-intel doctor` | Verifies Node, Git, Playwright & LLM readiness |
-| `diagnose` | `pw-intel diagnose <trace.zip>` | Ingests trace and outputs causal root cause |
-| `autonomous-repair` | `pw-intel autonomous-repair <trace.zip> --execute` | Verifies repair in an isolated Git worktree |
-| `approve` | `pw-intel approve <proposalId>` | Authorizes a verified repair proposal |
-| `promote` | `pw-intel promote --token <token>` | Applies authorized fix atomically to active code |
-| `generate-agent` | `pw-intel generate-agent <reqs.json> --write` | Generates tests matching project conventions |
-| `reproduce` | `pw-intel reproduce <spec.ts>` | Reruns spec with live DOM and network capture |
-| `ci-report` | `pw-intel ci-report <results.json>` | Generates CI annotations and SARIF report |
-| `mcp` | `pw-intel mcp` | Starts the Model Context Protocol stdio server |
-
----
-
-## 6. Detailed Documentation
-
-- [CLI Reference Guide](docs/CLI_REFERENCE.md)
-- [System Architecture](docs/ARCHITECTURE.md)
-- [Benchmark Methodology & Results](docs/BENCHMARK.md)
-- [Intent Invariants & Verification Guarantees](docs/INTENT_INVARIANTS.md)
-- [MCP Server Setup](docs/MCP_INTEGRATION.md)
-
----
-
-## Community & Contributing
-
-Contributions, feedback, and bug reports are warmly welcome! If Playwright Intelligence Engine saves you debugging time or helps stabilize your test suite, please consider giving it a ⭐ on [GitHub](https://github.com/lst2121/playwright-intelligence-engine).
-
----
-
-## License
-
-Apache-2.0. See [LICENSE](LICENSE) for details.
+# Playwright Intelligence Engine (`pw-intel`)
+
+> Fast, verification-first failure diagnosis, autonomous self-healing, and test generation for Microsoft Playwright suites.
+
+[![npm version](https://img.shields.io/npm/v/playwright-intelligence-engine.svg?style=flat-square)](https://www.npmjs.com/package/playwright-intelligence-engine)
+[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg?style=flat-square)](LICENSE)
+[![Node](https://img.shields.io/badge/Node->=20.0.0-green.svg?style=flat-square)](https://nodejs.org/)
+[![Playwright](https://img.shields.io/badge/Playwright->=1.30-orange.svg?style=flat-square)](https://playwright.dev/)
+
+---
+
+## 1. Installation
+
+Run without installing via `npx`:
+```bash
+npx pw-intel --help
+```
+
+Or install in your project:
+```bash
+npm install --save-dev playwright-intelligence-engine
+```
+
+Or install globally:
+```bash
+npm install -g playwright-intelligence-engine
+```
+
+*(Both `pw-intel` and `playwright-intelligence-engine` commands are available).*
+
+---
+
+## 2. Project Setup & LLM Configuration
+
+Initialize PIE in your Playwright repository:
+
+```bash
+npx pw-intel init
+```
+
+### Providing your LLM API Key (Optional)
+
+> **Note:** Failure diagnosis, trace analysis, and AST test repairs run **100% offline and locally** without an LLM key.
+> An API key is only needed if you want AI-assisted test generation (`pw-intel generate-agent`).
+
+You can configure an LLM key in any of three ways:
+
+#### Option A: During `init`
+```bash
+npx pw-intel init --api-key sk-your-openai-or-deepseek-key --model gpt-4o
+```
+*This automatically creates `.env` and adds it to your `.gitignore`.*
+
+#### Option B: Environment Variable
+```bash
+export OPENAI_API_KEY="sk-..."
+# or
+export PIE_LLM_API_KEY="sk-..."
+```
+
+#### Option C: In `.env`
+Create `.env` in your project root:
+```ini
+PIE_LLM_API_KEY=sk-...
+PIE_LLM_MODEL=gpt-4o
+PIE_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
+```
+
+Verify your setup at any time:
+```bash
+npx pw-intel doctor
+```
+
+---
+
+## 3. How to Use
+
+### 🔍 A. Diagnose a Failing Test
+Ingest a Playwright trace archive (`trace.zip`) to find the exact root cause:
+
+```bash
+npx pw-intel diagnose ./test-results/trace.zip
+```
+
+**Output example:**
+```json
+{
+  "category": "LOCATOR_DRIFT",
+  "confidence": 0.94,
+  "action": "click",
+  "failingSelector": "#checkout-btn-v1",
+  "suggestedSelector": "button:has-text(\"Proceed to Checkout\")",
+  "targetFile": "e2e/pages/CartPage.ts",
+  "evidence": "Element ID changed dynamically; stable accessible role match found."
+}
+```
+
+If the failure was caused by a backend crash (HTTP 500) or expired authentication (HTTP 401), PIE flags it immediately and abstains from modifying locators.
+
+---
+
+### 🔧 B. Autonomous Test Repair (Safe Worktrees)
+Repair a broken test or Page Object without risking your active Git branch:
+
+```bash
+# 1. Plan and test the repair in an isolated Git worktree:
+npx pw-intel autonomous-repair ./test-results/trace.zip --execute
+
+# 2. Check the cryptographic proposal:
+npx pw-intel approve <proposalId>
+
+# 3. Promote the verified fix atomically to your workspace:
+npx pw-intel promote --token <approvalToken>
+```
+
+**The Safety Guarantee:**
+- PIE **never** deletes or weakens your assertions (`expect(...)`).
+- PIE **never** alters test inputs or reorders user actions.
+- All repairs are executed and proven passing in a background worktree before promotion.
+
+---
+
+### 🚀 C. Generate Tests from Requirements
+Generate complete Playwright test suites and Page Objects that conform to your repository's conventions:
+
+```bash
+npx pw-intel generate-agent ./requirements.json --mode brownfield --write --verify
+```
+
+**Arguments:**
+- `--mode brownfield`: Reuses existing fixtures, auth states, and Page Objects without generating duplicate login steps.
+- `--mode greenfield`: Scaffolds a new end-to-end testing architecture from scratch.
+- `--write`: Saves the generated files to disk.
+- `--verify`: Runs TypeScript typecheck and Playwright discovery to ensure generated code compiles.
+
+---
+
+### 🧪 D. Reproduce a Spec with Live Instrumentation
+Rerun a flaky test with live DOM snapshots, network capture, and console logs:
+
+```bash
+npx pw-intel reproduce tests/checkout.spec.ts
+```
+
+---
+
+### 📊 E. CI/CD Quality Gate & SARIF Reporting
+Convert Playwright test results into GitHub Actions annotations and SARIF security/flakiness reports:
+
+```bash
+npx pw-intel ci-report ./test-results/results.json --sarif-out ./pie-results.sarif
+```
+
+---
+
+## 4. Cursor / Claude Code IDE Integration (MCP Server)
+
+PIE includes a built-in Model Context Protocol (MCP) server so AI coding assistants can diagnose traces and fix tests directly inside your IDE.
+
+### For Cursor / Windsurf
+Add to `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "playwright-intelligence": {
+      "command": "npx",
+      "args": ["-y", "playwright-intelligence-engine", "mcp"]
+    }
+  }
+}
+```
+
+### For Claude Desktop / Claude Code
+Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "pw-intel": {
+      "command": "npx",
+      "args": ["-y", "playwright-intelligence-engine", "mcp"]
+    }
+  }
+}
+```
+
+**Available MCP Tools:**
+- `diagnose_trace`: Diagnoses Playwright traces and provides root causes.
+- `repair_page_object`: Stages isolated repairs with cryptographic approval tokens.
+- `generate_playwright_test`: Generates tests matching your repository's conventions.
+- `ingest_playwright_report`: Analyzes test run failures and flakiness.
+
+---
+
+## 5. CLI Command Cheat Sheet
+
+| Command | Usage | Description |
+| :--- | :--- | :--- |
+| `init` | `pw-intel init [--api-key <k>]` | Initializes `.pie/config.json` & optional LLM credentials |
+| `doctor` | `pw-intel doctor` | Verifies Node, Git, Playwright & LLM readiness |
+| `diagnose` | `pw-intel diagnose <trace.zip>` | Ingests trace and outputs causal root cause |
+| `autonomous-repair` | `pw-intel autonomous-repair <trace.zip> --execute` | Verifies repair in an isolated Git worktree |
+| `approve` | `pw-intel approve <proposalId>` | Authorizes a verified repair proposal |
+| `promote` | `pw-intel promote --token <token>` | Applies authorized fix atomically to active code |
+| `generate-agent` | `pw-intel generate-agent <reqs.json> --write` | Generates tests matching project conventions |
+| `reproduce` | `pw-intel reproduce <spec.ts>` | Reruns spec with live DOM and network capture |
+| `ci-report` | `pw-intel ci-report <results.json>` | Generates CI annotations and SARIF report |
+| `mcp` | `pw-intel mcp` | Starts the Model Context Protocol stdio server |
+
+---
+
+## 6. Detailed Documentation
+
+- [CLI Reference Guide](docs/CLI_REFERENCE.md)
+- [System Architecture](docs/ARCHITECTURE.md)
+- [Benchmark Methodology & Results](docs/BENCHMARK.md)
+- [Intent Invariants & Verification Guarantees](docs/INTENT_INVARIANTS.md)
+- [MCP Server Setup](docs/MCP_INTEGRATION.md)
+
+---
+
+## Community & Contributing
+
+Contributions, feedback, and bug reports are warmly welcome! If Playwright Intelligence Engine saves you debugging time or helps stabilize your test suite, please consider giving it a ⭐ on [GitHub](https://github.com/lst2121/playwright-intelligence-engine).
+
+---
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) for details.

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAuCA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA4+B1D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAmFA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkgC1D"}

package/dist/core/version.d.ts

@@ -2,9 +2,9 @@
  * Product identity is kept in one place so the CLI, MCP server, and execution
  * proofs cannot silently advertise different versions.
  */
-export declare const PACKAGE_VERSION = "2.0.1";
-export declare const ENGINE_MILESTONE = "2.0.1";
-export declare const PROOF_VERSION = "2.0.1";
+export declare const PACKAGE_VERSION = "2.0.2";
+export declare const ENGINE_MILESTONE = "2.0.2";
+export declare const PROOF_VERSION = "2.0.2";
 export interface RuntimeProvenance {
     sourceRevision: string;
     workspaceDirty: boolean;

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/core/version.ts
 import { execFileSync } from "child_process";
-var PACKAGE_VERSION = "2.0.1";
-var ENGINE_MILESTONE = "2.0.1";
+var PACKAGE_VERSION = "2.0.2";
+var ENGINE_MILESTONE = "2.0.2";
 var PROOF_VERSION = ENGINE_MILESTONE;
 function getRuntimeProvenance(root = process.cwd()) {
   try {
@@ -358,8 +358,8 @@ var ArchiveReader = class _ArchiveReader {
       }
       const normalizedEntry = entryName.replace(/\\/g, "/");
       const targetFilePath = path.resolve(resolvedDest, normalizedEntry);
-      const relative2 = path.relative(resolvedDest, targetFilePath);
-      if (relative2.startsWith("..") || path.isAbsolute(relative2) || path.win32.isAbsolute(relative2) || path.posix.isAbsolute(relative2)) {
+      const relative3 = path.relative(resolvedDest, targetFilePath);
+      if (relative3.startsWith("..") || path.isAbsolute(relative3) || path.win32.isAbsolute(relative3) || path.posix.isAbsolute(relative3)) {
         throw new ZipSlipSecurityError(entry.entryName);
       }
       entryNames.push(entry.entryName);
@@ -2116,8 +2116,8 @@ async function inspectRepository(root) {
       }
     }
     if (!packageJson || !packagePath) throw new Error("No readable package.json found");
-    const relative2 = files.map((file) => path2.relative(absoluteRoot, file));
-    const configs = relative2.filter((file) => /(^|[\\/])playwright(?:\.[^.]*)?\.config\.(?:ts|js|mjs|cjs)$/i.test(file));
+    const relative3 = files.map((file) => path2.relative(absoluteRoot, file));
+    const configs = relative3.filter((file) => /(^|[\\/])playwright(?:\.[^.]*)?\.config\.(?:ts|js|mjs|cjs)$/i.test(file));
     const allDependencies = { ...packageJson.dependencies, ...packageJson.devDependencies };
     const hasPlaywright = Object.keys(allDependencies).some((name) => name === "@playwright/test" || name === "playwright");
     const packageRoot = path2.dirname(packagePath);
@@ -2132,10 +2132,10 @@ async function inspectRepository(root) {
       playwrightVersion: allDependencies["@playwright/test"] ?? allDependencies.playwright,
       hasPlaywrightConfig: configs.length > 0,
       playwrightConfigs: configs,
-      testFiles: relative2.filter((file) => /(?:^|[\\/])(?:tests?|e2e)(?:[\\/]).*\.(?:spec|test)\.(?:ts|tsx|js|jsx|mjs|cjs)$/i.test(file)).length,
-      pageObjectFiles: relative2.filter((file) => /(?:page|pages|pom|page-objects?)[\\/].*\.(?:ts|tsx|js|jsx)$/i.test(file)).length,
-      fixtureFiles: relative2.filter((file) => /fixture/i.test(file) && /\.(?:ts|tsx|js|jsx)$/.test(file)).length,
-      hasDocker: relative2.some((file) => /(?:^|[\\/])(?:docker-compose[^\\/]*|Dockerfile(?:\..*)?)$/i.test(file)),
+      testFiles: relative3.filter((file) => /(?:^|[\\/])(?:tests?|e2e)(?:[\\/]).*\.(?:spec|test)\.(?:ts|tsx|js|jsx|mjs|cjs)$/i.test(file)).length,
+      pageObjectFiles: relative3.filter((file) => /(?:page|pages|pom|page-objects?)[\\/].*\.(?:ts|tsx|js|jsx)$/i.test(file)).length,
+      fixtureFiles: relative3.filter((file) => /fixture/i.test(file) && /\.(?:ts|tsx|js|jsx)$/.test(file)).length,
+      hasDocker: relative3.some((file) => /(?:^|[\\/])(?:docker-compose[^\\/]*|Dockerfile(?:\..*)?)$/i.test(file)),
       hasLocalWebServerHint: Object.values(packageJson.scripts ?? {}).some((script) => /(?:next|vite|dev|start|serve)/i.test(script)),
       scripts: packageJson.scripts ?? {},
       status: hasPlaywright || configs.length > 0 ? "DISCOVERED" : "NOT_A_PLAYWRIGHT_REPOSITORY",
@@ -8008,8 +8008,8 @@ function assertWorkspacePath(root, target, label) {
   const resolved = path15.resolve(root, target);
   if (!fsSync2.existsSync(resolved)) throw new Error(`${label} not found: '${resolved}'`);
   const canonicalTarget = fsSync2.realpathSync(resolved);
-  const relative2 = path15.relative(canonicalRoot, canonicalTarget);
-  if (relative2.startsWith("..") || path15.isAbsolute(relative2)) throw new Error(`${label} escapes workspace root: '${target}'`);
+  const relative3 = path15.relative(canonicalRoot, canonicalTarget);
+  if (relative3.startsWith("..") || path15.isAbsolute(relative3)) throw new Error(`${label} escapes workspace root: '${target}'`);
   return canonicalTarget;
 }
 function resolveReadOnlyPath(root, target, label) {
@@ -8198,8 +8198,8 @@ var WorkspacePromoter = class _WorkspacePromoter {
     }
     const canonicalTarget = fs17.realpathSync(targetFilePath);
     const canonicalWorkspace = fs17.realpathSync(workspaceRoot);
-    const relative2 = path16.relative(canonicalWorkspace, canonicalTarget);
-    if (relative2.startsWith("..") || path16.isAbsolute(relative2)) {
+    const relative3 = path16.relative(canonicalWorkspace, canonicalTarget);
+    if (relative3.startsWith("..") || path16.isAbsolute(relative3)) {
       return {
         success: false,
         targetFilePath: canonicalTarget,
@@ -12765,8 +12765,8 @@ async function writeArchitecturePlan(root, plan) {
   const skipped = [];
   for (const file of plan.files) {
     const target = path21.resolve(projectRoot, file.relativePath);
-    const relative2 = path21.relative(projectRoot, target);
-    if (relative2.startsWith("..") || path21.isAbsolute(relative2)) throw new Error(`Architecture output path escapes project root: '${file.relativePath}'`);
+    const relative3 = path21.relative(projectRoot, target);
+    if (relative3.startsWith("..") || path21.isAbsolute(relative3)) throw new Error(`Architecture output path escapes project root: '${file.relativePath}'`);
     if (file.action === "SKIP_EXISTING") {
       skipped.push(file.relativePath);
       continue;
@@ -14726,8 +14726,8 @@ function assertWorkspacePath2(root, target, label) {
   const resolved = path25.resolve(root, target);
   if (!fsSync4.existsSync(resolved)) throw new Error(`${label} not found: '${resolved}'`);
   const canonicalTarget = fsSync4.realpathSync(resolved);
-  const relative2 = path25.relative(canonicalRoot, canonicalTarget);
-  if (relative2.startsWith("..") || path25.isAbsolute(relative2)) throw new Error(`${label} escapes workspace root: '${target}'`);
+  const relative3 = path25.relative(canonicalRoot, canonicalTarget);
+  if (relative3.startsWith("..") || path25.isAbsolute(relative3)) throw new Error(`${label} escapes workspace root: '${target}'`);
   return canonicalTarget;
 }
 function resolveReadOnlyPath2(root, target, label) {
@@ -19055,6 +19055,45 @@ ${generated.specCode}`
 import * as path31 from "path";
 import * as fs31 from "fs";
 import { spawn as spawn3, execSync } from "child_process";
+function findTraceArchives(targetPath) {
+  if (targetPath && !targetPath.startsWith("--")) {
+    const resolved = path31.resolve(targetPath);
+    if (fs31.existsSync(resolved)) {
+      if (fs31.statSync(resolved).isFile() && resolved.endsWith(".zip")) {
+        return [resolved];
+      }
+    }
+  }
+  const candidateDirs = [
+    targetPath && !targetPath.startsWith("--") && fs31.existsSync(targetPath) && fs31.statSync(targetPath).isDirectory() ? path31.resolve(targetPath) : null,
+    path31.resolve("test-results"),
+    path31.resolve("playwright-report"),
+    process.cwd()
+  ].filter(Boolean);
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const dir of candidateDirs) {
+    if (!fs31.existsSync(dir)) continue;
+    try {
+      const entries = fs31.readdirSync(dir, { recursive: true });
+      for (const entry of entries) {
+        const fullPath = path31.join(dir, String(entry));
+        if (fullPath.endsWith(".zip") && !seen.has(fullPath)) {
+          try {
+            const stat = fs31.statSync(fullPath);
+            if (stat.isFile()) {
+              seen.add(fullPath);
+              found.push({ filePath: fullPath, mtime: stat.mtimeMs });
+            }
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return found.sort((a, b) => b.mtime - a.mtime).map((f) => f.filePath);
+}
 async function runCli(argv) {
   const command = argv[2];
   if (!command || command === "--help" || command === "-h") {
@@ -19139,11 +19178,20 @@ async function runCli(argv) {
     }
   }
   if (command === "diagnose") {
-    const tracePath = argv[3];
-    if (!tracePath) {
-      console.error("Error: trace.zip path required. Usage: pw-intel diagnose <path-to-trace.zip> [--error-context <error-context.md>]");
+    const candidateArg = argv[3];
+    const traces = findTraceArchives(candidateArg);
+    if (traces.length === 0) {
+      console.error(
+        "Error: No trace.zip files found in test-results/ or current directory.\nPlease run your Playwright tests with tracing enabled: npx playwright test --trace on\nOr pass the path directly: pw-intel diagnose <path-to-trace.zip>"
+      );
       process.exit(1);
     }
+    const tracePath = traces[0];
+    if (traces.length > 1) {
+      console.log(`[pw-intel] Auto-discovered ${traces.length} trace files. Diagnosing most recent: ${path31.relative(process.cwd(), tracePath)}`);
+    } else if (!candidateArg || candidateArg.startsWith("--") || fs31.existsSync(candidateArg) && fs31.statSync(candidateArg).isDirectory()) {
+      console.log(`[pw-intel] Auto-discovered trace: ${path31.relative(process.cwd(), tracePath)}`);
+    }
     try {
       const { traceEntryName, networkEntryName, traceEntryNames, networkEntryNames } = ArchiveReader.findTraceFileEntries(tracePath);
       if (!traceEntryName) {
@@ -19243,11 +19291,20 @@ async function runCli(argv) {
     return;
   }
   if (command === "autonomous-repair") {
-    const tracePath = argv[3];
-    if (!tracePath) {
-      console.error("Error: trace.zip path required. Usage: pw-intel autonomous-repair <trace.zip> [--execute] [--test <spec>] [--pom <page-object>] [--class <Class>] [--member <member>]");
+    const candidateArg = argv[3];
+    const traces = findTraceArchives(candidateArg);
+    if (traces.length === 0) {
+      console.error(
+        "Error: No trace.zip files found in test-results/ or current directory.\nPlease run your Playwright tests with tracing enabled: npx playwright test --trace on\nOr pass the path directly: pw-intel autonomous-repair <trace.zip> [--execute]"
+      );
       process.exit(1);
     }
+    const tracePath = traces[0];
+    if (traces.length > 1) {
+      console.log(`[pw-intel] Auto-discovered ${traces.length} trace files. Repairing most recent: ${path31.relative(process.cwd(), tracePath)}`);
+    } else if (!candidateArg || candidateArg.startsWith("--") || fs31.existsSync(candidateArg) && fs31.statSync(candidateArg).isDirectory()) {
+      console.log(`[pw-intel] Auto-discovered trace: ${path31.relative(process.cwd(), tracePath)}`);
+    }
     try {
       const option = (name) => {
         const index = argv.indexOf(name);