@agentxjs/devtools 1.9.5-dev → 2.0.0

package/src/bdd/cli.ts

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

package/src/bdd/cucumber.config.ts

@@ -0,0 +1,40 @@
+/**
+ * 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"],
+ * });
+ * ```
+ */
+
+export 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[];
+}
+
+export function createCucumberConfig(options: CucumberConfigOptions) {
+  return {
+    format: options.format ?? ["progress"],
+    formatOptions: { snippetInterface: "async-await" },
+    import: options.import,
+    paths: options.paths,
+    tags: options.tags ?? "not @pending and not @skip",
+    worldParameters: {
+      defaultTimeout: options.timeout ?? 30000,
+    },
+  };
+}

package/src/bdd/dev-server.ts

@@ -0,0 +1,82 @@
+/**
+ * Dev server utilities for BDD testing
+ *
+ * Start and stop dev servers during test runs.
+ */
+
+import { spawn, ChildProcess } from "node:child_process";
+import { waitForUrl } from "./playwright";
+
+export 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;
+}
+
+let devServer: ChildProcess | null = null;
+
+/**
+ * Start a dev server and wait for it to be ready
+ */
+export async function startDevServer(options: DevServerOptions): Promise<void> {
+  if (devServer) return;
+
+  const {
+    cwd,
+    command = "bun",
+    args = ["run", "dev"],
+    port,
+    timeout = 30000,
+    debug = !!process.env.DEBUG,
+  } = options;
+
+  devServer = spawn(command, args, {
+    cwd,
+    stdio: "pipe",
+    detached: false,
+  });
+
+  if (debug) {
+    devServer.stdout?.on("data", (data) => {
+      console.log("[dev-server]", data.toString());
+    });
+
+    devServer.stderr?.on("data", (data) => {
+      console.error("[dev-server error]", data.toString());
+    });
+  }
+
+  const url = `http://localhost:${port}`;
+  const ready = await waitForUrl(url, timeout);
+
+  if (!ready) {
+    stopDevServer();
+    throw new Error(`Dev server failed to start on port ${port}`);
+  }
+}
+
+/**
+ * Stop the dev server
+ */
+export function stopDevServer(): void {
+  if (devServer) {
+    devServer.kill("SIGTERM");
+    devServer = null;
+  }
+}
+
+/**
+ * Get the dev server process (for advanced use)
+ */
+export function getDevServer(): ChildProcess | null {
+  return devServer;
+}

package/src/bdd/index.ts

@@ -0,0 +1,41 @@
+/**
+ * BDD utilities for testing AgentX projects
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createCucumberConfig,
+ *   launchBrowser,
+ *   startDevServer,
+ * } from "@agentxjs/devtools/bdd";
+ * ```
+ */
+
+export { createCucumberConfig, type CucumberConfigOptions } from "./cucumber.config";
+
+export {
+  launchBrowser,
+  getPage,
+  resetPage,
+  closePage,
+  closeBrowser,
+  waitForUrl,
+  type BrowserOptions,
+} from "./playwright";
+
+export { startDevServer, stopDevServer, getDevServer, type DevServerOptions } from "./dev-server";
+
+export {
+  paths,
+  getMonorepoPath,
+  getPackagePath,
+  getBddPath,
+  getFixturesPath,
+  getTempPath,
+  ensureDir,
+  resetPaths,
+} from "./paths";
+
+export { agentUiTester, type UiTestResult, type UiTesterOptions } from "./agent-ui-tester";
+
+export { agentDocTester, type DocTestResult, type DocTesterOptions } from "./agent-doc-tester";

package/src/bdd/paths.ts

@@ -0,0 +1,140 @@
+/**
+ * Unified path utilities for BDD testing
+ *
+ * Provides consistent path resolution across all packages.
+ */
+
+import { resolve, dirname } from "node:path";
+import { existsSync, mkdtempSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+// ============================================================================
+// Path Resolution
+// ============================================================================
+
+/**
+ * Find the monorepo root by looking for root package.json with workspaces
+ */
+export function findMonorepoRoot(startDir: string = process.cwd()): string {
+  let dir = startDir;
+  while (dir !== "/") {
+    const pkgPath = resolve(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = require(pkgPath);
+        if (pkg.workspaces || pkg.private === true) {
+          // Check if it looks like a monorepo root
+          const hasPackages = existsSync(resolve(dir, "packages"));
+          const hasApps = existsSync(resolve(dir, "apps"));
+          if (hasPackages || hasApps) {
+            return dir;
+          }
+        }
+      } catch {
+        // Ignore errors
+      }
+    }
+    dir = dirname(dir);
+  }
+  return startDir;
+}
+
+/**
+ * Get the current package root (where package.json is)
+ */
+export function getPackageRoot(startDir: string = process.cwd()): string {
+  let dir = startDir;
+  while (dir !== "/") {
+    if (existsSync(resolve(dir, "package.json"))) {
+      return dir;
+    }
+    dir = dirname(dir);
+  }
+  return startDir;
+}
+
+// ============================================================================
+// Standard Paths
+// ============================================================================
+
+let _monorepoRoot: string | null = null;
+let _packageRoot: string | null = null;
+let _tempDir: string | null = null;
+
+/**
+ * Monorepo root directory
+ */
+export function getMonorepoPath(): string {
+  if (!_monorepoRoot) {
+    _monorepoRoot = findMonorepoRoot();
+  }
+  return _monorepoRoot;
+}
+
+/**
+ * Current package root directory
+ */
+export function getPackagePath(): string {
+  if (!_packageRoot) {
+    _packageRoot = getPackageRoot();
+  }
+  return _packageRoot;
+}
+
+/**
+ * BDD directory for current package
+ */
+export function getBddPath(): string {
+  return resolve(getPackagePath(), "bdd");
+}
+
+/**
+ * Fixtures directory for current package's BDD tests
+ */
+export function getFixturesPath(subdir?: string): string {
+  const base = resolve(getBddPath(), "fixtures");
+  return subdir ? resolve(base, subdir) : base;
+}
+
+/**
+ * Get or create a temporary directory for tests
+ */
+export function getTempPath(prefix: string = "bdd-"): string {
+  if (!_tempDir) {
+    _tempDir = mkdtempSync(resolve(tmpdir(), prefix));
+  }
+  return _tempDir;
+}
+
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export function ensureDir(path: string): string {
+  if (!existsSync(path)) {
+    mkdirSync(path, { recursive: true });
+  }
+  return path;
+}
+
+/**
+ * Reset cached paths (useful for testing)
+ */
+export function resetPaths(): void {
+  _monorepoRoot = null;
+  _packageRoot = null;
+  _tempDir = null;
+}
+
+// ============================================================================
+// Convenience exports
+// ============================================================================
+
+export const paths = {
+  monorepo: getMonorepoPath,
+  package: getPackagePath,
+  bdd: getBddPath,
+  fixtures: getFixturesPath,
+  temp: getTempPath,
+  ensure: ensureDir,
+  reset: resetPaths,
+};

package/src/bdd/playwright.ts

@@ -0,0 +1,110 @@
+/**
+ * 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
+ */
+
+import { chromium, Browser, Page } from "@playwright/test";
+
+export interface BrowserOptions {
+  headless?: boolean;
+  slowMo?: number;
+}
+
+let browser: Browser | null = null;
+let page: Page | null = null;
+
+/**
+ * Launch browser using system Chrome (singleton)
+ */
+export async function launchBrowser(options: BrowserOptions = {}): Promise<Browser> {
+  if (browser) return browser;
+
+  const headless = options.headless ?? process.env.CI === "true";
+
+  browser = await chromium.launch({
+    channel: "chrome",
+    headless,
+    slowMo: options.slowMo,
+  });
+
+  return browser;
+}
+
+/**
+ * Get or create a page (singleton, reused across scenarios)
+ */
+export async function getPage(): Promise<Page> {
+  if (page && !page.isClosed()) return page;
+
+  const b = await launchBrowser();
+  page = await b.newPage();
+  return page;
+}
+
+/**
+ * Reset page state between scenarios (without closing)
+ * Use this instead of closePage() for faster tests
+ */
+export async function resetPage(): Promise<void> {
+  try {
+    if (page && !page.isClosed()) {
+      const context = page.context();
+      await context.clearCookies();
+      await page.goto("about:blank");
+    }
+  } catch {
+    // Browser may have crashed, will recreate on next getPage()
+    page = null;
+  }
+}
+
+/**
+ * Close current page
+ * @deprecated Use resetPage() for faster tests. Only use closePage() if you need full isolation.
+ */
+export async function closePage(): Promise<void> {
+  if (page) {
+    await page.close();
+    page = null;
+  }
+}
+
+/**
+ * Close browser and cleanup
+ */
+export async function closeBrowser(): Promise<void> {
+  if (page && !page.isClosed()) {
+    await page.close();
+    page = null;
+  }
+  if (browser) {
+    await browser.close();
+    browser = null;
+  }
+}
+
+/**
+ * Wait for a URL to be accessible
+ */
+export async function waitForUrl(url: string, timeout = 30000): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return true;
+      }
+    } catch {
+      // Not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}

package/src/env.ts

@@ -0,0 +1,97 @@
+/**
+ * Unified environment configuration for devtools
+ *
+ * Single source of truth for API credentials and model settings.
+ * Automatically loads .env / .env.local from monorepo root on import.
+ *
+ * All devtools modules (VCR, BDD, Devtools SDK) should use this
+ * instead of reading process.env directly.
+ *
+ * @example
+ * ```ts
+ * import { env } from "@agentxjs/devtools";
+ *
+ * const driver = createMonoDriver({
+ *   apiKey: env.apiKey!,
+ *   baseUrl: env.baseUrl,
+ *   model: env.model,
+ * });
+ * ```
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+
+// ============================================================================
+// Auto-load .env files from monorepo root
+// ============================================================================
+
+function loadEnvFile(filePath: string): void {
+  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] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+function findMonorepoRoot(): string | null {
+  let dir = process.cwd();
+  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;
+  }
+}
+
+// Load on import — cwd first, then monorepo root
+const cwd = process.cwd();
+loadEnvFile(resolve(cwd, ".env"));
+loadEnvFile(resolve(cwd, ".env.local"));
+
+const monorepoRoot = findMonorepoRoot();
+if (monorepoRoot && monorepoRoot !== cwd) {
+  loadEnvFile(resolve(monorepoRoot, ".env"));
+  loadEnvFile(resolve(monorepoRoot, ".env.local"));
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export const env = {
+  /** Deepractice API key */
+  get apiKey(): string | undefined {
+    return process.env.DEEPRACTICE_API_KEY;
+  },
+
+  /** Deepractice API base URL */
+  get baseUrl(): string | undefined {
+    return process.env.DEEPRACTICE_BASE_URL;
+  },
+
+  /** Model identifier */
+  get model(): string {
+    return process.env.DEEPRACTICE_MODEL || "claude-haiku-4-5-20251001";
+  },
+};

package/src/index.ts

@@ -8,9 +8,11 @@
  * ```typescript
  * import { createDevtools } from "@agentxjs/devtools";
  *
+ * import { env } from "@agentxjs/devtools";
+ *
  * const devtools = createDevtools({
  *   fixturesDir: "./fixtures",
- *   apiKey: process.env.DEEPRACTICE_API_KEY,
+ *   apiKey: env.apiKey,
  * });
  *
  * // Has fixture → playback (MockDriver)
@@ -58,6 +60,9 @@ export {
   type RecordingDriverOptions,
 } from "./recorder/RecordingDriver";
 
+// Environment
+export { env } from "./env";
+
 // Types
 export type { Fixture, FixtureEvent, MockDriverOptions } from "./types";