levante 0.1.0

package/scripts/trace/replay-with-trace.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Replay a Playwright codegen recording with tracing enabled.
+ * Captures a trace.zip with screenshots, DOM snapshots, and network activity.
+ *
+ * Usage:
+ *   node replay-with-trace.mjs <codegen-file.ts>
+ *
+ * The trace is saved alongside the codegen file as codegen-<timestamp>-trace.zip.
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { dirname, resolve, basename, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = process.env.E2E_AI_PROJECT_ROOT || resolve(__dirname, '..', '..');
+
+const codegenFile = process.argv[2];
+if (!codegenFile) {
+  console.error('Usage: node replay-with-trace.mjs <codegen-file.ts>');
+  process.exit(1);
+}
+
+const codegenPath = resolve(root, codegenFile);
+if (!existsSync(codegenPath)) {
+  console.error(`File not found: ${codegenFile}`);
+  process.exit(1);
+}
+
+const codegenDir = dirname(codegenPath);
+const codegenBase = basename(codegenFile, '.ts');
+const traceOutputDir = resolve(codegenDir, 'trace-results');
+const configPath = resolve(__dirname, 'replay.config.ts');
+const traceZipDest = resolve(codegenDir, `${codegenBase}-trace.zip`);
+
+// Ensure auth storage state exists for replay
+const storageStatePath = resolve(root, '.auth', 'codegen.json');
+if (!existsSync(storageStatePath)) {
+  console.error('No cached auth found \u2014 running auth setup...');
+  try {
+    execSync(`node "${resolve(__dirname, '..', 'auth', 'setup-auth.mjs')}"`, {
+      cwd: root,
+      stdio: 'inherit',
+      env: { ...process.env, E2E_AI_PROJECT_ROOT: root },
+    });
+  } catch {
+    console.error('Auth setup failed \u2014 replay will proceed without cached auth.');
+  }
+}
+
+console.error(`Replaying with trace: ${codegenFile}`);
+console.error(`Trace will be saved to: ${relative(root, traceZipDest)}`);
+
+let replayFailed = false;
+try {
+  execSync(
+    `npx playwright test "${codegenPath}" --config "${configPath}" --project chromium`,
+    {
+      cwd: root,
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        TRACE_OUTPUT_DIR: traceOutputDir,
+      },
+    },
+  );
+} catch {
+  replayFailed = true;
+  console.error('Replay finished with errors (trace may still be partial).');
+}
+
+if (existsSync(traceOutputDir)) {
+  const dirs = readdirSync(traceOutputDir, { withFileTypes: true }).filter((d) => d.isDirectory());
+
+  for (const dir of dirs) {
+    const traceZip = resolve(traceOutputDir, dir.name, 'trace.zip');
+    if (existsSync(traceZip)) {
+      renameSync(traceZip, traceZipDest);
+      break;
+    }
+  }
+
+  rmSync(traceOutputDir, { recursive: true, force: true });
+}
+
+if (existsSync(traceZipDest)) {
+  console.error(`\nTrace saved: ${relative(root, traceZipDest)}`);
+  console.error(`Open with:   npx playwright show-trace "${relative(root, traceZipDest)}"`);
+  process.exit(replayFailed ? 1 : 0);
+} else {
+  console.error('\nWarning: No trace file was captured.');
+  process.exit(1);
+}

package/scripts/trace/replay.config.ts

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Minimal Playwright config for replaying codegen recordings with tracing.
+ * Used by scripts/trace/replay-with-trace.mjs.
+ *
+ * Trace output dir is controlled via TRACE_OUTPUT_DIR env variable.
+ * Project root is controlled via E2E_AI_PROJECT_ROOT env variable.
+ * Reuses cached auth from .auth/codegen.json when available.
+ */
+const projectRoot = process.env.E2E_AI_PROJECT_ROOT || resolve(__dirname, '..', '..');
+const storageStatePath = resolve(projectRoot, '.auth', 'codegen.json');
+const storageState = existsSync(storageStatePath) ? storageStatePath : undefined;
+
+export default defineConfig({
+  testDir: projectRoot,
+  testMatch: '**/codegen-*.ts',
+  timeout: 120_000,
+  retries: 0,
+  workers: 1,
+  reporter: 'list',
+  outputDir: process.env.TRACE_OUTPUT_DIR || resolve(projectRoot, 'test-results-trace'),
+  use: {
+    trace: 'on',
+    screenshot: 'on',
+    actionTimeout: 30_000,
+    storageState,
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});

package/scripts/voice/merger.mjs

@@ -0,0 +1,119 @@
+/**
+ * Format seconds as MM:SS.
+ * @param {number} sec
+ * @returns {string}
+ */
+function formatTime(sec) {
+  const m = Math.floor(sec / 60);
+  const s = Math.floor(sec % 60);
+  return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+}
+
+/**
+ * Extract real action timestamps from // @t:<seconds>s comments injected during codegen.
+ * Returns an array of { lineIndex, elapsed } or null if no timestamps found.
+ *
+ * @param {string[]} lines
+ * @param {number[]} actionIndices - line indices of action lines
+ * @returns {number[] | null} elapsed seconds per action, or null
+ */
+function extractEmbeddedTimestamps(lines, actionIndices) {
+  const tsPattern = /^\s*\/\/\s*@t:([\d.]+)s\s*$/;
+  const timestamps = [];
+
+  for (const actionIdx of actionIndices) {
+    // Look at the line immediately before the action for a @t: comment
+    if (actionIdx > 0 && tsPattern.test(lines[actionIdx - 1])) {
+      const match = lines[actionIdx - 1].match(tsPattern);
+      timestamps.push(parseFloat(match[1]));
+    } else {
+      // Missing timestamp for this action — can't use embedded timestamps
+      return null;
+    }
+  }
+
+  return timestamps;
+}
+
+/**
+ * Merge codegen output with voice transcript segments.
+ *
+ * If the codegen contains // @t:<seconds>s comments (injected during recording),
+ * those real timestamps are used for alignment. Otherwise, action timestamps are
+ * distributed linearly across the session duration (fallback).
+ *
+ * @param {string} codegenContent - The original codegen .ts file content
+ * @param {Array<{ start: number, end: number, text: string }>} segments - Whisper transcript segments
+ * @param {number} durationSec - Total session duration in seconds (used only for linear fallback)
+ * @returns {string} Annotated codegen content
+ */
+export function merge(codegenContent, segments, durationSec) {
+  if (!segments || segments.length === 0) return codegenContent;
+
+  const lines = codegenContent.split('\n');
+  const actionPattern = /^\s*(await\s+page\.|await\s+expect\()/;
+  const tsCommentPattern = /^\s*\/\/\s*@t:[\d.]+s\s*$/;
+
+  // Find indices of action lines (skip @t: comment lines)
+  const actionIndices = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (actionPattern.test(lines[i])) {
+      actionIndices.push(i);
+    }
+  }
+
+  if (actionIndices.length === 0) return codegenContent;
+
+  // Try to use embedded timestamps, fall back to linear distribution
+  const embeddedTs = extractEmbeddedTimestamps(lines, actionIndices);
+  const actionTimestamps = embeddedTs
+    ? embeddedTs
+    : actionIndices.map((_, idx) => {
+        if (actionIndices.length === 1) return durationSec / 2;
+        return (idx / (actionIndices.length - 1)) * durationSec;
+      });
+
+  // For each segment, find the nearest action by timestamp
+  /** @type {Map<number, Array<{ start: number, end: number, text: string }>>} */
+  const insertions = new Map();
+
+  for (const seg of segments) {
+    const segMid = (seg.start + seg.end) / 2;
+    let bestIdx = 0;
+    let bestDist = Math.abs(actionTimestamps[0] - segMid);
+
+    for (let i = 1; i < actionTimestamps.length; i++) {
+      const dist = Math.abs(actionTimestamps[i] - segMid);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestIdx = i;
+      }
+    }
+
+    const actionLineIdx = actionIndices[bestIdx];
+    if (!insertions.has(actionLineIdx)) {
+      insertions.set(actionLineIdx, []);
+    }
+    insertions.get(actionLineIdx).push(seg);
+  }
+
+  // Build result: strip old @t: comments and insert voice comments before action lines
+  const result = [];
+  for (let i = 0; i < lines.length; i++) {
+    // Skip @t: timestamp comments — they're consumed, not preserved
+    if (tsCommentPattern.test(lines[i])) continue;
+
+    const segs = insertions.get(i);
+    if (segs) {
+      const indent = lines[i].match(/^(\s*)/)[1];
+      for (const seg of segs) {
+        result.push(
+          `${indent}// [Voice ${formatTime(seg.start)} - ${formatTime(seg.end)}] "${seg.text}"`,
+        );
+      }
+    }
+    result.push(lines[i]);
+  }
+
+  return result.join('\n');
+}

package/scripts/voice/recorder.mjs

@@ -0,0 +1,54 @@
+import { spawn, execSync } from 'node:child_process';
+
+/**
+ * Check that the `rec` command (from sox) is available.
+ * Throws a clear error if not installed.
+ */
+export function checkRecAvailable() {
+  try {
+    execSync('which rec', { stdio: 'ignore' });
+  } catch {
+    throw new Error(
+      'The "rec" command is not available.\n' +
+        'Install sox to enable voice recording:\n' +
+        '  brew install sox          # macOS\n' +
+        '  sudo apt install sox      # Debian/Ubuntu\n',
+    );
+  }
+}
+
+/**
+ * Start recording audio from the microphone to a WAV file.
+ * @param {string} wavPath - Absolute path to the output .wav file
+ * @returns {{ process: import('node:child_process').ChildProcess, startTime: number }}
+ */
+export function startRecording(wavPath) {
+  checkRecAvailable();
+
+  const recProcess = spawn('rec', ['-q', '-r', '16000', '-c', '1', '-b', '16', wavPath], {
+    stdio: 'ignore',
+  });
+
+  recProcess.on('error', (err) => {
+    console.error(`Recording process error: ${err.message}`);
+  });
+
+  return { process: recProcess, startTime: Date.now() };
+}
+
+/**
+ * Stop recording by sending SIGTERM and waiting for the process to close.
+ * @param {import('node:child_process').ChildProcess} recProcess
+ * @returns {Promise<void>}
+ */
+export function stopRecording(recProcess) {
+  return new Promise((resolve, reject) => {
+    if (!recProcess || recProcess.killed) {
+      resolve();
+      return;
+    }
+    recProcess.on('close', () => resolve());
+    recProcess.on('error', reject);
+    recProcess.kill('SIGTERM');
+  });
+}

package/scripts/voice/transcriber.mjs

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Transcribe a WAV file using OpenAI Whisper API.
+ * Returns an array of segments with start/end timestamps (seconds) and text.
+ *
+ * Requires OPENAI_API_KEY in the environment.
+ * If the key is missing, logs a warning and returns an empty array.
+ *
+ * @param {string} wavPath - Absolute path to the .wav file
+ * @returns {Promise<Array<{ start: number, end: number, text: string }>>}
+ */
+export async function transcribe(wavPath) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    console.error(
+      'Warning: OPENAI_API_KEY not set — skipping voice transcription.\n' +
+        'Set it in .env to enable automatic transcription.',
+    );
+    return [];
+  }
+
+  const fileBuffer = readFileSync(wavPath);
+  const blob = new Blob([fileBuffer], { type: 'audio/wav' });
+
+  const formData = new FormData();
+  formData.append('file', blob, 'recording.wav');
+  formData.append('model', 'whisper-1');
+  formData.append('response_format', 'verbose_json');
+  formData.append('timestamp_granularities[]', 'segment');
+
+  const response = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Whisper API error (${response.status}): ${errorText}`);
+  }
+
+  const result = await response.json();
+
+  return (result.segments || []).map((seg) => ({
+    start: seg.start,
+    end: seg.end,
+    text: seg.text.trim(),
+  }));
+}

package/templates/e2e-ai.context.example.md

@@ -0,0 +1,93 @@
+# Project Context for e2e-ai
+
+## Application
+
+- **Name**: My Application
+- **Description**: A web application for managing resources
+- **Tech Stack**: React, TypeScript, Material UI
+- **Base URL**: https://app.example.com
+
+## Test Infrastructure
+
+### Fixtures
+- `singleResourcePage` — Pre-authenticated page for single-resource user
+- `multiResourcePage` — Pre-authenticated page for multi-resource user
+
+### Helpers
+- `createStepCounter()` — Returns a `nextStep(label)` function for sequential step naming
+- `test` — Custom test object from `@config` with fixtures pre-registered
+
+### Auth Pattern
+- Login is handled by fixtures — test step 1 ("Log in") is a no-op
+- Storage state cached in `.auth/` directory
+
+## Feature Methods
+
+### useFeatures(page)
+Returns `{ appNav, settingsApp, dashboardApp }`
+
+- `appNav.navigateTo(section)` — Navigate to a named section
+- `appNav.waitForNavigation()` — Wait for navigation to complete
+- `dashboardApp.waitForDashboard()` — Wait for dashboard to load
+
+### useItemFeatures(page, appNav)
+Returns `{ itemList, itemCreation, itemDetail }`
+
+- `itemList.clickListButton()` — Switch to list view
+- `itemList.clickGridButton()` — Switch to grid view
+- `itemCreation.openCreateDialog()` — Open the create item modal
+- `itemDetail.waitForDetail()` — Wait for detail panel to load
+
+## Import Conventions
+
+```typescript
+import { createStepCounter, test } from '@config';
+import { useFeatures } from '@features';
+import { useItemFeatures } from '@features/items';
+import { expect } from 'playwright/test';
+```
+
+Path aliases (from tsconfig.json):
+- `@config` → `e2e/config`
+- `@features` → `e2e/features`
+- `@features/*` → `e2e/features/*`
+
+## Selector Conventions
+
+1. Prefer `getByRole`, `getByText`, `getByLabel` over CSS selectors
+2. Use `[id^="item-"]` pattern for dynamically generated IDs
+3. Use `data-testid` when semantic selectors are ambiguous
+4. Never rely on generated CSS class names (e.g., `.css-xxxxx`)
+
+## Test Structure Template
+
+```typescript
+import { createStepCounter, test } from '@config';
+import { useFeatures } from '@features';
+import { expect } from 'playwright/test';
+
+test.describe('ISSUE-KEY - Test title', () => {
+  test('Test title', async ({ singleResourcePage }) => {
+    const { appNav } = useFeatures(singleResourcePage);
+    const nextStep = createStepCounter();
+
+    await test.step(nextStep('Log in with valid credentials'), async () => {
+      // Expected: User is logged in and on the dashboard
+      // Login handled by singleResourcePage fixture
+    });
+
+    await test.step(nextStep('Navigate to Items section'), async () => {
+      // Expected: Items list is displayed
+      await appNav.navigateTo('Items');
+    });
+  });
+});
+```
+
+## Utility Patterns
+
+- `{ timeout: 10000 }` for visibility assertions
+- `{ timeout: 15000 }` for navigation waits
+- `{ timeout: 500 }` for short animation waits
+- Use `page.waitForLoadState('networkidle')` before asserting loaded data
+- Wrap data-dependent assertions in try/catch with `// TODO: data-dependent` comment