@agentxjs/devtools 1.9.6-dev → 2.0.0

package/README.md

@@ -0,0 +1,284 @@
+# @agentxjs/devtools
+
+Development and testing tools for AgentX. Provides BDD utilities for Cucumber-based integration tests, plus VCR-style fixture recording/replay for deterministic LLM testing.
+
+## Overview
+
+`@agentxjs/devtools` has two parts:
+
+1. **BDD Utilities** (`@agentxjs/devtools/bdd`) -- Cucumber config, AI-powered UI testing, documentation testing, dev server management.
+2. **VCR Infrastructure** -- `MockDriver`, `RecordingDriver`, `createVcrCreateDriver` for recording and replaying LLM interactions in unit tests.
+
+## Quick Start: BDD Testing
+
+### 1. Set up Cucumber config
+
+```typescript
+// bdd/cucumber.js
+import { createCucumberConfig } from "@agentxjs/devtools/bdd";
+
+export default createCucumberConfig({
+  paths: ["bdd/journeys/**/*.feature"],
+  import: ["bdd/steps/**/*.ts"],
+});
+```
+
+### 2. Use agentUiTester for UI tests
+
+```typescript
+import { agentUiTester } from "@agentxjs/devtools/bdd";
+
+const result = agentUiTester(`
+  Navigate to http://localhost:3000
+  Verify redirect to /setup
+  Fill email "admin@example.com", password "admin123"
+  Click Setup
+  Verify logged in as admin
+`);
+
+assert.ok(result.passed, result.output);
+```
+
+### 3. Start a dev server in tests
+
+```typescript
+import { startDevServer, stopDevServer } from "@agentxjs/devtools/bdd";
+
+// In BeforeAll hook
+await startDevServer({ cwd: "/path/to/app", port: 3000 });
+
+// In AfterAll hook
+stopDevServer();
+```
+
+### 4. Use MockDriver for unit tests
+
+MockDriver replays recorded fixtures — no network calls, fully deterministic. Use it when you need to test code that interacts with a Driver without hitting a real LLM API.
+
+```typescript
+import { MockDriver } from "@agentxjs/devtools";
+import { SIMPLE_REPLY } from "@agentxjs/devtools/fixtures";
+
+// Create a mock driver from a built-in fixture
+const driver = new MockDriver({ fixture: SIMPLE_REPLY });
+await driver.initialize();
+
+for await (const event of driver.receive({ content: "Hello" })) {
+  if (event.type === "text_delta") {
+    process.stdout.write(event.data.text);
+  }
+}
+
+await driver.dispose();
+```
+
+Built-in fixtures: `SIMPLE_REPLY`, `LONG_REPLY`, `TOOL_CALL`, `ERROR`, `EMPTY`.
+
+To use your own recorded fixture:
+
+```typescript
+import { MockDriver, getFixture } from "@agentxjs/devtools";
+
+const fixture = getFixture("my-recorded-scenario"); // from fixtures directory
+const driver = new MockDriver({ fixture });
+```
+
+## Quick Start: VCR Recording
+
+Record real LLM interactions once, replay them in subsequent test runs:
+
+```typescript
+import { createDevtools } from "@agentxjs/devtools";
+
+const devtools = createDevtools({
+  fixturesDir: "./fixtures",
+  apiKey: process.env.ANTHROPIC_API_KEY, // only needed for recording
+});
+
+// Fixture exists  --> playback (MockDriver)
+// Fixture missing --> call real API, record, save, return MockDriver
+const driver = await devtools.driver("greeting-test", {
+  message: "Hello!",
+});
+
+await driver.initialize();
+for await (const event of driver.receive(userMessage)) {
+  if (event.type === "text_delta") {
+    process.stdout.write(event.data.text);
+  }
+}
+await driver.dispose();
+```
+
+### VCR with Server (Integration Tests)
+
+Use `createVcrCreateDriver` to wrap a real driver with VCR logic — ideal for BDD tests that run through the full server stack:
+
+```typescript
+import { createVcrCreateDriver } from "@agentxjs/devtools";
+
+const vcrCreateDriver = createVcrCreateDriver({
+  fixturesDir: "./fixtures",
+  getFixtureName: () => currentFixture,
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  createRealDriver: createMonoDriver,
+  onPlayback: (name) => console.log(`Playback: ${name}`),
+  onRecording: (name) => console.log(`Recording: ${name}`),
+});
+
+const server = await createServer({ platform, createDriver: vcrCreateDriver });
+```
+
+## API Reference
+
+### BDD API (`@agentxjs/devtools/bdd`)
+
+#### `createCucumberConfig(options: CucumberConfigOptions)`
+
+```typescript
+interface CucumberConfigOptions {
+  paths: string[]; // feature file paths
+  import: string[]; // step definition paths
+  tags?: string; // default: "not @pending and not @skip"
+  timeout?: number; // default: 30000 ms
+  format?: string[]; // default: ["progress"]
+}
+```
+
+#### `agentUiTester(prompt, options?): UiTestResult`
+
+Runs a UI test scenario using Claude CLI + agent-browser.
+
+```typescript
+interface UiTesterOptions {
+  model?: string; // default: "haiku"
+  baseUrl?: string;
+  timeout?: number; // default: 300000 (5 min)
+  headed?: boolean; // default: false
+}
+
+interface UiTestResult {
+  passed: boolean;
+  output: string;
+}
+```
+
+#### `agentDocTester(options, testerOptions?): DocTestResult`
+
+Evaluates documents against requirements using AgentX. Assesses completeness, logic, and readability.
+
+```typescript
+import { agentDocTester } from "@agentxjs/devtools/bdd";
+
+const result = await agentDocTester({
+  files: ["packages/core/README.md"],
+  requirements: `
+    The README should explain Container, Image, Session, Driver, Platform.
+    There should be a Quick Start example.
+  `,
+});
+
+assert.ok(result.passed, result.output);
+```
+
+```typescript
+interface DocTesterOptions {
+  provider?: string; // default: "anthropic"
+  model?: string; // default: "claude-haiku-4-5-20251001"
+  apiKey?: string; // reads from DEEPRACTICE_API_KEY or ANTHROPIC_API_KEY
+  baseUrl?: string; // reads from DEEPRACTICE_BASE_URL
+  timeout?: number; // default: 120000 (2 min)
+}
+```
+
+#### `startDevServer(options): Promise<void>`
+
+```typescript
+interface DevServerOptions {
+  cwd: string;
+  port: number;
+  command?: string; // default: "bun"
+  args?: string[]; // default: ["run", "dev"]
+  timeout?: number; // default: 30000
+  debug?: boolean; // default: !!process.env.DEBUG
+}
+```
+
+#### Path Utilities
+
+```typescript
+import { getFixturesPath, getTempPath, ensureDir, getMonorepoPath } from "@agentxjs/devtools/bdd";
+```
+
+### VCR API (main entry)
+
+#### `createDevtools(config: DevtoolsConfig): Devtools`
+
+```typescript
+interface DevtoolsConfig {
+  fixturesDir: string;
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+  systemPrompt?: string;
+  cwd?: string;
+  createDriver?: CreateDriver;
+}
+```
+
+| Method                                   | Description                                               |
+| ---------------------------------------- | --------------------------------------------------------- |
+| `driver(name, options): Promise<Driver>` | Get driver — playback if fixture exists, record otherwise |
+| `load(name): Promise<Fixture>`           | Load a fixture by name                                    |
+| `exists(name): boolean`                  | Check if fixture exists                                   |
+| `delete(name): Promise<void>`            | Delete a fixture                                          |
+
+#### `MockDriver`
+
+Replays events from a fixture. No network calls.
+
+```typescript
+import { MockDriver, createMockDriver } from "@agentxjs/devtools";
+
+const driver = new MockDriver({ fixture: myFixture });
+```
+
+#### `RecordingDriver`
+
+Wraps a real driver and records all events.
+
+```typescript
+import { createRecordingDriver } from "@agentxjs/devtools";
+
+const recorder = createRecordingDriver({ driver: realDriver, name: "my-scenario" });
+const fixture = recorder.getFixture(); // after recording
+```
+
+#### Built-in Fixtures
+
+```typescript
+import { SIMPLE_REPLY, TOOL_CALL, getFixture, listFixtures } from "@agentxjs/devtools/fixtures";
+
+listFixtures(); // ["simple-reply", "long-reply", "tool-call", "error", "empty"]
+```
+
+## Configuration
+
+### Package Exports
+
+| Import path                   | Contents                                                                                |
+| ----------------------------- | --------------------------------------------------------------------------------------- |
+| `@agentxjs/devtools`          | VCR: `Devtools`, `MockDriver`, `RecordingDriver`, fixtures                              |
+| `@agentxjs/devtools/mock`     | `MockDriver`, `createMockDriver`                                                        |
+| `@agentxjs/devtools/recorder` | `RecordingDriver`, `createRecordingDriver`                                              |
+| `@agentxjs/devtools/fixtures` | Built-in fixtures, `getFixture`, `listFixtures`                                         |
+| `@agentxjs/devtools/bdd`      | BDD: `createCucumberConfig`, `agentUiTester`, `agentDocTester`, `startDevServer`, paths |
+
+### Peer Dependencies (optional)
+
+| Package                   | When needed                                          |
+| ------------------------- | ---------------------------------------------------- |
+| `agentxjs`                | `agentDocTester` (uses AgentX SDK for AI evaluation) |
+| `@agentxjs/claude-driver` | Recording with claude-driver                         |
+| `@playwright/test`        | Browser-based BDD tests                              |
+| `@cucumber/cucumber`      | BDD test runner                                      |

package/dist/bdd/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bdd/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+// src/bdd/cli.ts
+import { spawn } from "child_process";
+import { resolve, dirname, relative } from "path";
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function loadEnvFile(filePath) {
+  if (!existsSync(filePath)) return;
+  const content = readFileSync(filePath, "utf-8");
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    let value = trimmed.slice(eqIndex + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (process.env[key] === void 0) {
+      process.env[key] = value;
+    }
+  }
+}
+function findMonorepoRoot(startDir) {
+  let dir = startDir;
+  while (true) {
+    const pkgPath = resolve(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (pkg.workspaces) return dir;
+      } catch {
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+var cwd = process.cwd();
+loadEnvFile(resolve(cwd, ".env"));
+loadEnvFile(resolve(cwd, ".env.local"));
+var monorepoRoot = findMonorepoRoot(cwd);
+if (monorepoRoot && monorepoRoot !== cwd) {
+  loadEnvFile(resolve(monorepoRoot, ".env"));
+  loadEnvFile(resolve(monorepoRoot, ".env.local"));
+}
+var args = process.argv.slice(2);
+var configPath = "bdd/cucumber.js";
+var configIndex = args.indexOf("--config");
+if (configIndex !== -1 && args[configIndex + 1]) {
+  configPath = args[configIndex + 1];
+  args.splice(configIndex, 2);
+}
+var fullConfigPath = resolve(cwd, configPath);
+if (!existsSync(fullConfigPath)) {
+  console.error(`Config not found: ${fullConfigPath}`);
+  console.error("Create bdd/cucumber.js or specify --config path");
+  process.exit(1);
+}
+var featurePaths = [];
+var flags = [];
+for (const arg of args) {
+  if (arg.startsWith("-")) {
+    flags.push(arg);
+  } else if (arg.endsWith(".feature") || arg.includes(".feature:")) {
+    featurePaths.push(arg);
+  } else {
+    flags.push(arg);
+  }
+}
+var cucumberPaths = [
+  resolve(cwd, "node_modules/.bin/cucumber-js"),
+  resolve(__dirname, "../../../.bin/cucumber-js"),
+  "cucumber-js"
+];
+var cucumberBin = cucumberPaths.find((p) => p === "cucumber-js" || existsSync(p)) || "cucumber-js";
+var rootNodeModules = resolve(cwd, "node_modules");
+var effectiveConfig = configPath;
+var tempConfigPath = null;
+if (featurePaths.length > 0) {
+  const configRelPath = relative(
+    dirname(resolve(cwd, "bdd/.tmp-cucumber.js")),
+    fullConfigPath
+  ).replace(/\\/g, "/");
+  const pathsJson = JSON.stringify(featurePaths);
+  const tempContent = [
+    `import config from "./${configRelPath}";`,
+    `export default { ...config.default ?? config, paths: ${pathsJson} };`,
+    ""
+  ].join("\n");
+  tempConfigPath = resolve(cwd, "bdd/.tmp-cucumber.js");
+  writeFileSync(tempConfigPath, tempContent);
+  effectiveConfig = "bdd/.tmp-cucumber.js";
+}
+var cucumberArgs = ["--config", effectiveConfig, ...flags];
+var child = spawn(cucumberBin, cucumberArgs, {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    NODE_OPTIONS: "--import tsx",
+    NODE_PATH: rootNodeModules
+  }
+});
+child.on("close", (code) => {
+  if (tempConfigPath && existsSync(tempConfigPath)) {
+    try {
+      unlinkSync(tempConfigPath);
+    } catch {
+    }
+  }
+  process.exit(code ?? 0);
+});
+//# sourceMappingURL=cli.js.map

package/dist/bdd/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bdd/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * BDD CLI wrapper for cucumber-js\n *\n * Usage:\n *   bdd                              # Run all tests\n *   bdd path/to/file.feature         # Run specific feature file\n *   bdd path/to/file.feature:10      # Run specific scenario by line\n *   bdd --tags @contributor           # Run specific tags\n *   bdd --tags \"@dev and not @slow\"   # Tag expression\n *   bdd --name \"token usage\"          # Filter by scenario name (regex)\n *   bdd --dry-run                     # Validate without executing\n *   bdd --config path                 # Custom config (default: bdd/cucumber.js)\n */\n\nimport { spawn } from \"node:child_process\";\nimport { resolve, dirname, relative } from \"node:path\";\nimport { existsSync, readFileSync, writeFileSync, unlinkSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\n// Load .env files (like dotenv but zero dependencies)\nfunction loadEnvFile(filePath: string) {\n  if (!existsSync(filePath)) return;\n  const content = readFileSync(filePath, \"utf-8\");\n  for (const line of content.split(\"\\n\")) {\n    const trimmed = line.trim();\n    if (!trimmed || trimmed.startsWith(\"#\")) continue;\n    const eqIndex = trimmed.indexOf(\"=\");\n    if (eqIndex === -1) continue;\n    const key = trimmed.slice(0, eqIndex).trim();\n    let value = trimmed.slice(eqIndex + 1).trim();\n    if (\n      (value.startsWith('\"') && value.endsWith('\"')) ||\n      (value.startsWith(\"'\") && value.endsWith(\"'\"))\n    ) {\n      value = value.slice(1, -1);\n    }\n    if (process.env[key] === undefined) {\n      process.env[key] = value;\n    }\n  }\n}\n\n// Find monorepo root by walking up to find the root package.json with workspaces\nfunction findMonorepoRoot(startDir: string): string | null {\n  let dir = startDir;\n  while (true) {\n    const pkgPath = resolve(dir, \"package.json\");\n    if (existsSync(pkgPath)) {\n      try {\n        const pkg = JSON.parse(readFileSync(pkgPath, \"utf-8\"));\n        if (pkg.workspaces) return dir;\n      } catch {\n        // ignore parse errors\n      }\n    }\n    const parent = dirname(dir);\n    if (parent === dir) return null;\n    dir = parent;\n  }\n}\n\nconst cwd = process.cwd();\n\n// Load .env files from cwd first, then monorepo root\nloadEnvFile(resolve(cwd, \".env\"));\nloadEnvFile(resolve(cwd, \".env.local\"));\n\nconst monorepoRoot = findMonorepoRoot(cwd);\nif (monorepoRoot && monorepoRoot !== cwd) {\n  loadEnvFile(resolve(monorepoRoot, \".env\"));\n  loadEnvFile(resolve(monorepoRoot, \".env.local\"));\n}\n\nconst args = process.argv.slice(2);\n\n// Extract --config\nlet configPath = \"bdd/cucumber.js\";\nconst configIndex = args.indexOf(\"--config\");\nif (configIndex !== -1 && args[configIndex + 1]) {\n  configPath = args[configIndex + 1];\n  args.splice(configIndex, 2);\n}\n\n// Check if config exists\nconst fullConfigPath = resolve(cwd, configPath);\nif (!existsSync(fullConfigPath)) {\n  console.error(`Config not found: ${fullConfigPath}`);\n  console.error(\"Create bdd/cucumber.js or specify --config path\");\n  process.exit(1);\n}\n\n// Separate positional args (feature files/lines) from flags\nconst featurePaths: string[] = [];\nconst flags: string[] = [];\n\nfor (const arg of args) {\n  if (arg.startsWith(\"-\")) {\n    flags.push(arg);\n  } else if (arg.endsWith(\".feature\") || arg.includes(\".feature:\")) {\n    featurePaths.push(arg);\n  } else {\n    // Could be a flag value (e.g. after --tags), keep as-is\n    flags.push(arg);\n  }\n}\n\n// Find cucumber-js binary\nconst cucumberPaths = [\n  resolve(cwd, \"node_modules/.bin/cucumber-js\"),\n  resolve(__dirname, \"../../../.bin/cucumber-js\"),\n  \"cucumber-js\",\n];\nconst cucumberBin =\n  cucumberPaths.find((p) => p === \"cucumber-js\" || existsSync(p)) || \"cucumber-js\";\n\nconst rootNodeModules = resolve(cwd, \"node_modules\");\n\n// When feature paths are specified, generate a temp config that overrides\n// the original config's `paths` — cucumber-js config.paths takes precedence\n// over positional args, so we must override it in the config itself.\nlet effectiveConfig = configPath;\nlet tempConfigPath: string | null = null;\n\nif (featurePaths.length > 0) {\n  const configRelPath = relative(\n    dirname(resolve(cwd, \"bdd/.tmp-cucumber.js\")),\n    fullConfigPath\n  ).replace(/\\\\/g, \"/\");\n  const pathsJson = JSON.stringify(featurePaths);\n  const tempContent = [\n    `import config from \"./${configRelPath}\";`,\n    `export default { ...config.default ?? config, paths: ${pathsJson} };`,\n    \"\",\n  ].join(\"\\n\");\n\n  tempConfigPath = resolve(cwd, \"bdd/.tmp-cucumber.js\");\n  writeFileSync(tempConfigPath, tempContent);\n  effectiveConfig = \"bdd/.tmp-cucumber.js\";\n}\n\n// Build cucumber args\nconst cucumberArgs = [\"--config\", effectiveConfig, ...flags];\n\nconst child = spawn(cucumberBin, cucumberArgs, {\n  stdio: \"inherit\",\n  env: {\n    ...process.env,\n    NODE_OPTIONS: \"--import tsx\",\n    NODE_PATH: rootNodeModules,\n  },\n});\n\nchild.on(\"close\", (code) => {\n  // Clean up temp config\n  if (tempConfigPath && existsSync(tempConfigPath)) {\n    try {\n      unlinkSync(tempConfigPath);\n    } catch {\n      // ignore cleanup errors\n    }\n  }\n  process.exit(code ?? 0);\n});\n"],"mappings":"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","names":[]}

package/dist/bdd/index.d.ts

@@ -0,0 +1,202 @@
+import { Browser, Page } from '@playwright/test';
+import { ChildProcess } from 'node:child_process';
+
+/**
+ * Shared Cucumber configuration for BDD tests
+ *
+ * Usage in project's cucumber.js:
+ *
+ * ```js
+ * import { createCucumberConfig } from "@agentxjs/devtools/bdd";
+ *
+ * export default createCucumberConfig({
+ *   paths: ["bdd/journeys/** /*.feature"],
+ *   import: ["bdd/steps/** /*.ts"],
+ * });
+ * ```
+ */
+interface CucumberConfigOptions {
+    /** Feature file paths */
+    paths: string[];
+    /** Step definition paths */
+    import: string[];
+    /** Tags to filter (default: exclude @pending and @skip) */
+    tags?: string;
+    /** Default timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Format output (default: progress) */
+    format?: string[];
+}
+declare function createCucumberConfig(options: CucumberConfigOptions): {
+    format: string[];
+    formatOptions: {
+        snippetInterface: string;
+    };
+    import: string[];
+    paths: string[];
+    tags: string;
+    worldParameters: {
+        defaultTimeout: number;
+    };
+};
+
+/**
+ * Playwright utilities for BDD testing
+ *
+ * Uses system Chrome to avoid downloading Chromium.
+ * Install: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 bun add -d @playwright/test
+ *
+ * Browser lifecycle:
+ * - Single browser instance for all tests
+ * - Single page (tab) reused across scenarios
+ * - resetPage() clears state between scenarios
+ */
+
+interface BrowserOptions {
+    headless?: boolean;
+    slowMo?: number;
+}
+/**
+ * Launch browser using system Chrome (singleton)
+ */
+declare function launchBrowser(options?: BrowserOptions): Promise<Browser>;
+/**
+ * Get or create a page (singleton, reused across scenarios)
+ */
+declare function getPage(): Promise<Page>;
+/**
+ * Reset page state between scenarios (without closing)
+ * Use this instead of closePage() for faster tests
+ */
+declare function resetPage(): Promise<void>;
+/**
+ * Close current page
+ * @deprecated Use resetPage() for faster tests. Only use closePage() if you need full isolation.
+ */
+declare function closePage(): Promise<void>;
+/**
+ * Close browser and cleanup
+ */
+declare function closeBrowser(): Promise<void>;
+/**
+ * Wait for a URL to be accessible
+ */
+declare function waitForUrl(url: string, timeout?: number): Promise<boolean>;
+
+/**
+ * Dev server utilities for BDD testing
+ *
+ * Start and stop dev servers during test runs.
+ */
+
+interface DevServerOptions {
+    /** Working directory */
+    cwd: string;
+    /** Command to run (default: "bun") */
+    command?: string;
+    /** Command arguments (default: ["run", "dev"]) */
+    args?: string[];
+    /** Port to wait for */
+    port: number;
+    /** Startup timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Show server output (default: false, or true if DEBUG env is set) */
+    debug?: boolean;
+}
+/**
+ * Start a dev server and wait for it to be ready
+ */
+declare function startDevServer(options: DevServerOptions): Promise<void>;
+/**
+ * Stop the dev server
+ */
+declare function stopDevServer(): void;
+/**
+ * Get the dev server process (for advanced use)
+ */
+declare function getDevServer(): ChildProcess | null;
+
+/**
+ * Monorepo root directory
+ */
+declare function getMonorepoPath(): string;
+/**
+ * Current package root directory
+ */
+declare function getPackagePath(): string;
+/**
+ * BDD directory for current package
+ */
+declare function getBddPath(): string;
+/**
+ * Fixtures directory for current package's BDD tests
+ */
+declare function getFixturesPath(subdir?: string): string;
+/**
+ * Get or create a temporary directory for tests
+ */
+declare function getTempPath(prefix?: string): string;
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+declare function ensureDir(path: string): string;
+/**
+ * Reset cached paths (useful for testing)
+ */
+declare function resetPaths(): void;
+declare const paths: {
+    monorepo: typeof getMonorepoPath;
+    package: typeof getPackagePath;
+    bdd: typeof getBddPath;
+    fixtures: typeof getFixturesPath;
+    temp: typeof getTempPath;
+    ensure: typeof ensureDir;
+    reset: typeof resetPaths;
+};
+
+interface UiTestResult {
+    passed: boolean;
+    output: string;
+}
+interface UiTesterOptions {
+    model?: string;
+    baseUrl?: string;
+    timeout?: number;
+    /** Show browser window (default: false) */
+    headed?: boolean;
+}
+/**
+ * Run a UI test scenario using Claude Code CLI + agent-browser.
+ *
+ * BDD scripts must run under Node.js (not Bun) to avoid claude CLI auth bug.
+ */
+declare function agentUiTester(prompt: string, options?: UiTesterOptions): UiTestResult;
+
+interface DocTestResult {
+    passed: boolean;
+    output: string;
+}
+interface DocTesterOptions {
+    /** LLM provider (default: "anthropic") */
+    provider?: string;
+    /** Model name */
+    model?: string;
+    /** API key (reads from env if not provided) */
+    apiKey?: string;
+    /** Base URL (reads from env if not provided) */
+    baseUrl?: string;
+    /** Timeout in ms */
+    timeout?: number;
+}
+/**
+ * Evaluate a document against requirements using AgentX.
+ *
+ * Uses agentxjs local mode — no subprocess, no CLI, no auth issues.
+ * Requires `agentxjs` as a peer dependency.
+ */
+declare function agentDocTester(options: {
+    files: string[];
+    requirements: string;
+}, testerOptions?: DocTesterOptions): Promise<DocTestResult>;
+
+export { type BrowserOptions, type CucumberConfigOptions, type DevServerOptions, type DocTestResult, type DocTesterOptions, type UiTestResult, type UiTesterOptions, agentDocTester, agentUiTester, closeBrowser, closePage, createCucumberConfig, ensureDir, getBddPath, getDevServer, getFixturesPath, getMonorepoPath, getPackagePath, getPage, getTempPath, launchBrowser, paths, resetPage, resetPaths, startDevServer, stopDevServer, waitForUrl };