@xera-ai/web 0.1.4 → 0.1.6

package/dist/generator/typecheck.d.ts

@@ -2,4 +2,9 @@ export interface TypecheckResult {
     ok: boolean;
     errors: string[];
 }
+/**
+ * Type-check the ticket's TypeScript files using the project's root tsconfig.
+ * Errors are filtered to those whose path contains the ticket directory, so the
+ * skill sees only the locally relevant ones.
+ */
 export declare function typecheckTicket(ticketDir: string): Promise<TypecheckResult>;

package/dist/index.js

@@ -357,18 +357,45 @@ function validateGherkin(content) {
 }
 // src/generator/typecheck.ts
 import { spawnSync } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { dirname, join as join5 } from "path";
+function findNearestTsconfig(start) {
+  let dir = start;
+  while (true) {
+    const candidate = join5(dir, "tsconfig.json");
+    if (existsSync2(candidate))
+      return candidate;
+    const parent = dirname(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
 async function typecheckTicket(ticketDir) {
-  const proc = spawnSync("npx", ["tsc", "--noEmit", "--project", ticketDir], { encoding: "utf8" });
+  const tsconfig = findNearestTsconfig(ticketDir);
+  if (!tsconfig) {
+    return {
+      ok: false,
+      errors: [
+        `No tsconfig.json found walking up from ${ticketDir}. Run \`xera init\` to scaffold one at the project root.`
+      ]
+    };
+  }
+  const proc = spawnSync("npx", ["tsc", "--noEmit", "-p", tsconfig], { encoding: "utf8" });
   if (proc.status === 0)
     return { ok: true, errors: [] };
-  const out = (proc.stdout || "") + (proc.stderr || "");
-  const errors = out.split(`
+  const out = `${proc.stdout ?? ""}${proc.stderr ?? ""}`;
+  const allErrors = out.split(`
 `).filter((line) => /error TS\d+/.test(line));
-  return { ok: false, errors };
+  const ticketErrors = allErrors.filter((line) => line.includes(ticketDir));
+  return {
+    ok: false,
+    errors: ticketErrors.length > 0 ? ticketErrors : allErrors
+  };
 }
 // src/generator/lint.ts
-import { readFileSync as readFileSync3, existsSync as existsSync2, readdirSync } from "fs";
-import { join as join5 } from "path";
+import { readFileSync as readFileSync3, existsSync as existsSync3, readdirSync } from "fs";
+import { join as join6 } from "path";
 
 // src/generator/selector-rules.ts
 var AUTO_CLASS_RE = /\.(?:Mui|css|ant|chakra|MuiButton)[A-Za-z]*-[A-Za-z0-9_]*-[A-Za-z0-9_]{3,}/;
@@ -401,11 +428,11 @@ function lintSelectors(source) {
 
 // src/generator/lint.ts
 function listTsFiles(dir) {
-  if (!existsSync2(dir))
+  if (!existsSync3(dir))
     return [];
   const out = [];
   for (const name of readdirSync(dir, { withFileTypes: true })) {
-    const full = join5(dir, name.name);
+    const full = join6(dir, name.name);
     if (name.isDirectory())
       out.push(...listTsFiles(full));
     else if (name.name.endsWith(".ts"))
@@ -425,18 +452,18 @@ async function lintTicket(ticketDir) {
   return { ok: warnings.length === 0, warnings };
 }
 // src/generator/pom-scan.ts
-import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "fs";
+import { join as join7 } from "path";
 var CLASS_RE = /export\s+class\s+([A-Z][A-Za-z0-9_]*)/g;
 function scanSharedPoms(repoRoot) {
-  const dir = join6(repoRoot, "shared", "page-objects");
-  if (!existsSync3(dir))
+  const dir = join7(repoRoot, "shared", "page-objects");
+  if (!existsSync4(dir))
     return [];
   const found = [];
   for (const entry of readdirSync2(dir, { withFileTypes: true })) {
     if (!entry.isFile() || !entry.name.endsWith(".ts"))
       continue;
-    const path = join6(dir, entry.name);
+    const path = join7(dir, entry.name);
     const src = readFileSync4(path, "utf8");
     for (const m of src.matchAll(CLASS_RE)) {
       found.push({ className: m[1], absolutePath: path });
@@ -445,23 +472,23 @@ function scanSharedPoms(repoRoot) {
   return found;
 }
 // src/generator/promote.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync3, renameSync } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync3, renameSync } from "fs";
+import { join as join8 } from "path";
 async function promotePom(input) {
-  const fromDir = join7(input.repoRoot, ".xera", input.ticket, "page-objects");
-  const toDir = join7(input.repoRoot, "shared", "page-objects");
+  const fromDir = join8(input.repoRoot, ".xera", input.ticket, "page-objects");
+  const toDir = join8(input.repoRoot, "shared", "page-objects");
   const file = `${input.className}.ts`;
-  const fromPath = join7(fromDir, file);
-  const toPath = join7(toDir, file);
-  if (!existsSync4(fromPath)) {
+  const fromPath = join8(fromDir, file);
+  const toPath = join8(toDir, file);
+  if (!existsSync5(fromPath)) {
     throw new Error(`POM ${file} not found at ${fromPath}`);
   }
-  if (existsSync4(toPath)) {
+  if (existsSync5(toPath)) {
     throw new Error(`POM ${file} already exists at ${toPath}. Reconcile manually before promoting.`);
   }
   renameSync(fromPath, toPath);
-  const specPath = join7(input.repoRoot, ".xera", input.ticket, "spec.ts");
-  if (existsSync4(specPath)) {
+  const specPath = join8(input.repoRoot, ".xera", input.ticket, "spec.ts");
+  if (existsSync5(specPath)) {
     const src = readFileSync5(specPath, "utf8");
     const updated = src.replace(new RegExp(`from\\s+['"]\\./page-objects/${input.className}['"]`, "g"), `from '../../shared/page-objects/${input.className}'`);
     writeFileSync3(specPath, updated);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/web",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
+  "files": ["dist", "src"],
   "scripts": {
     "build": "bun build ./src/index.ts --outdir ./dist --target bun --external @playwright/test --external @xera-ai/core --external @cucumber/gherkin --external @cucumber/messages --external fflate",
     "typecheck": "tsc --noEmit"
@@ -20,7 +20,7 @@
     "@cucumber/gherkin": "30.0.4",
     "@cucumber/messages": "27.0.2",
     "@playwright/test": "1.48.0",
-    "@xera-ai/core": "^0.1.4",
+    "@xera-ai/core": "^0.1.5",
     "fflate": "0.8.2"
   }
 }

package/src/adapter.ts

@@ -0,0 +1,46 @@
+import { runPlaywright } from './executor';
+import { normalizeRun } from './trace-normalizer/normalize';
+import type { TestAdapter, GenerateInput, GenerateResult, ExecuteInput, RunResult, DoctorReport } from '@xera-ai/core/adapter';
+import { join } from 'node:path';
+
+export const WebAdapter: TestAdapter = {
+  id: 'web',
+
+  async generate(_input: GenerateInput): Promise<GenerateResult> {
+    // Generation itself is LLM-driven via skills + prompts; the adapter
+    // exposes helpers (validateGherkin, typecheckTicket, lintTicket) that
+    // the skills call via `bun run xera:*`. No direct artifact writing here.
+    return { artifacts: [], warnings: [] };
+  },
+
+  async execute(input: ExecuteInput): Promise<RunResult> {
+    const runDir = join(input.ticketDir, 'runs', input.runId);
+    const specPath = join(input.ticketDir, 'spec.ts');
+    const configPath = join(input.ticketDir, 'playwright.config.ts');
+    const pwResult = await runPlaywright({ specPath, configPath, outputDir: runDir });
+    const normalized = await normalizeRun({ runId: input.runId, runDir });
+    return {
+      runId: input.runId,
+      outcome: normalized.outcome,
+      scenarios: normalized.scenarios.map(s => {
+        const out: RunResult['scenarios'][number] = { name: s.name, outcome: s.outcome };
+        if (s.failure !== undefined) out.failure = s.failure;
+        return out;
+      }),
+      artifactsDir: runDir,
+      rawReportPath: pwResult.rawReportPath,
+      normalizedReportPath: join(runDir, 'normalized.json'),
+    };
+  },
+
+  async doctor(): Promise<DoctorReport> {
+    const checks: DoctorReport['checks'] = [];
+    try {
+      await import('@playwright/test');
+      checks.push({ name: '@playwright/test installed', ok: true });
+    } catch {
+      checks.push({ name: '@playwright/test installed', ok: false, message: 'Run `bun add -D @playwright/test`.' });
+    }
+    return { ok: checks.every(c => c.ok), checks };
+  },
+};

package/src/auth-setup/define.ts

@@ -0,0 +1,25 @@
+import type { Page } from '@playwright/test';
+
+export interface AuthRoleCreds {
+  email: string;
+  password: string;
+}
+
+export interface AuthSetupResult {
+  /** Optional explicit expiry hint, ms since epoch. */
+  expiresAt?: number;
+}
+
+export type AuthSetupFn = (
+  page: Page,
+  role: string,
+  creds: AuthRoleCreds,
+) => Promise<AuthSetupResult | void>;
+
+/**
+ * Helper to type-narrow the user's auth setup function. Users import this in
+ * `shared/auth-setup.ts`.
+ */
+export function defineAuthSetup(fn: AuthSetupFn): AuthSetupFn {
+  return fn;
+}

package/src/auth-setup/playwright-state.ts

@@ -0,0 +1,13 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readAuthState } from '@xera-ai/core';
+
+export function stagePlaywrightState(authDir: string, role: string): string {
+  const entry = readAuthState(authDir, role);
+  if (!entry) throw new Error(`No auth state for role "${role}" in ${authDir}`);
+  const cacheDir = join(authDir, '.cache');
+  mkdirSync(cacheDir, { recursive: true });
+  const stagedPath = join(cacheDir, `${role}.json`);
+  writeFileSync(stagedPath, JSON.stringify(entry.payload));
+  return stagedPath;
+}

package/src/auth-setup/runner.ts

@@ -0,0 +1,40 @@
+import type { Browser } from '@playwright/test';
+import { pathToFileURL } from 'node:url';
+import { writeAuthState } from '@xera-ai/core';
+import type { AuthRoleCreds } from './define';
+
+export interface RunAuthSetupInput {
+  role: string;
+  creds: AuthRoleCreds;
+  setupScriptPath: string;
+  authDir: string;
+  browser: Browser;
+  now?: Date;
+}
+
+export async function runAuthSetup(input: RunAuthSetupInput): Promise<void> {
+  const mod = await import(pathToFileURL(input.setupScriptPath).href);
+  const fn = mod.default;
+  if (typeof fn !== 'function') {
+    throw new Error(
+      `Auth setup script at ${input.setupScriptPath} must default-export a function (see defineAuthSetup).`,
+    );
+  }
+  const context = await input.browser.newContext();
+  try {
+    const page = await context.newPage();
+    const result = (await fn(page, input.role, input.creds)) ?? {};
+    const storageState = await context.storageState();
+    const now = input.now ?? new Date();
+    const expiresAtMs = result.expiresAt ?? now.getTime() + 8 * 3600 * 1000;
+    writeAuthState(input.authDir, {
+      role: input.role,
+      strategy: 'storageState',
+      created_at: now.toISOString(),
+      expires_at: new Date(expiresAtMs).toISOString(),
+      payload: storageState as unknown as Record<string, unknown>,
+    });
+  } finally {
+    await context.close();
+  }
+}

package/src/executor/index.ts

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+import { buildPlaywrightArgs } from './playwright-args';
+
+export interface SpawnResult {
+  exitCode: number;
+}
+export type SpawnFn = (cmd: string, args: string[], env: NodeJS.ProcessEnv) => Promise<SpawnResult>;
+
+export interface RunPlaywrightInput {
+  specPath: string;
+  configPath: string;
+  outputDir: string;
+  env?: NodeJS.ProcessEnv;
+  spawn?: SpawnFn;
+}
+
+export interface RunPlaywrightResult {
+  outcome: 'PASS' | 'FAIL';
+  rawReportPath: string;
+  exitCode: number;
+}
+
+const defaultSpawn: SpawnFn = async (cmd, args, env) => {
+  const proc = Bun.spawn([cmd, ...args], { env, stdout: 'inherit', stderr: 'inherit' });
+  const exitCode = await proc.exited;
+  return { exitCode };
+};
+
+export async function runPlaywright(input: RunPlaywrightInput): Promise<RunPlaywrightResult> {
+  const args = buildPlaywrightArgs({
+    specPath: input.specPath,
+    configPath: input.configPath,
+    outputDir: input.outputDir,
+  });
+  const spawn = input.spawn ?? defaultSpawn;
+  const { exitCode } = await spawn('npx', ['playwright', ...args], { ...process.env, ...input.env });
+  return {
+    outcome: exitCode === 0 ? 'PASS' : 'FAIL',
+    rawReportPath: join(input.outputDir, 'report.json'),
+    exitCode,
+  };
+}

package/src/executor/playwright-args.ts

@@ -0,0 +1,16 @@
+export interface PlaywrightArgsInput {
+  specPath: string;
+  outputDir: string;
+  configPath: string;
+}
+
+export function buildPlaywrightArgs(input: PlaywrightArgsInput): string[] {
+  return [
+    'test',
+    input.specPath,
+    `--config=${input.configPath}`,
+    '--reporter=json',
+    `--output=${input.outputDir}`,
+    '--trace=on',
+  ];
+}

package/src/generator/gherkin-validate.ts

@@ -0,0 +1,28 @@
+import { AstBuilder, GherkinClassicTokenMatcher, Parser } from '@cucumber/gherkin';
+import { IdGenerator } from '@cucumber/messages';
+
+export interface GherkinValidateResult {
+  ok: boolean;
+  errors: Array<{ line: number; message: string }>;
+}
+
+export function validateGherkin(content: string): GherkinValidateResult {
+  if (!content.trim()) {
+    return { ok: false, errors: [{ line: 0, message: 'Empty feature file' }] };
+  }
+  try {
+    const parser = new Parser(new AstBuilder(IdGenerator.uuid()), new GherkinClassicTokenMatcher());
+    parser.parse(content);
+    return { ok: true, errors: [] };
+  } catch (e: any) {
+    const errors: Array<{ line: number; message: string }> = [];
+    if (e?.errors && Array.isArray(e.errors)) {
+      for (const inner of e.errors) {
+        errors.push({ line: inner?.location?.line ?? 0, message: String(inner?.message ?? inner) });
+      }
+    } else {
+      errors.push({ line: 0, message: String(e?.message ?? e) });
+    }
+    return { ok: false, errors };
+  }
+}

package/src/generator/lint.ts

@@ -0,0 +1,30 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { lintSelectors, type SelectorWarning } from './selector-rules';
+
+export interface LintResult {
+  ok: boolean;
+  warnings: Array<SelectorWarning & { file: string }>;
+}
+
+function listTsFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const name of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, name.name);
+    if (name.isDirectory()) out.push(...listTsFiles(full));
+    else if (name.name.endsWith('.ts')) out.push(full);
+  }
+  return out;
+}
+
+export async function lintTicket(ticketDir: string): Promise<LintResult> {
+  const files = listTsFiles(ticketDir);
+  const warnings: LintResult['warnings'] = [];
+  for (const f of files) {
+    const src = readFileSync(f, 'utf8');
+    const r = lintSelectors(src);
+    for (const w of r.warnings) warnings.push({ ...w, file: f });
+  }
+  return { ok: warnings.length === 0, warnings };
+}

package/src/generator/pom-scan.ts

@@ -0,0 +1,24 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CLASS_RE = /export\s+class\s+([A-Z][A-Za-z0-9_]*)/g;
+
+export interface SharedPom {
+  className: string;
+  absolutePath: string;
+}
+
+export function scanSharedPoms(repoRoot: string): SharedPom[] {
+  const dir = join(repoRoot, 'shared', 'page-objects');
+  if (!existsSync(dir)) return [];
+  const found: SharedPom[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;
+    const path = join(dir, entry.name);
+    const src = readFileSync(path, 'utf8');
+    for (const m of src.matchAll(CLASS_RE)) {
+      found.push({ className: m[1]!, absolutePath: path });
+    }
+  }
+  return found;
+}

package/src/generator/promote.ts

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface PromoteInput {
+  repoRoot: string;
+  ticket: string;
+  className: string;
+}
+
+export async function promotePom(input: PromoteInput): Promise<void> {
+  const fromDir = join(input.repoRoot, '.xera', input.ticket, 'page-objects');
+  const toDir = join(input.repoRoot, 'shared', 'page-objects');
+  const file = `${input.className}.ts`;
+  const fromPath = join(fromDir, file);
+  const toPath = join(toDir, file);
+
+  if (!existsSync(fromPath)) {
+    throw new Error(`POM ${file} not found at ${fromPath}`);
+  }
+  if (existsSync(toPath)) {
+    throw new Error(`POM ${file} already exists at ${toPath}. Reconcile manually before promoting.`);
+  }
+
+  renameSync(fromPath, toPath);
+
+  const specPath = join(input.repoRoot, '.xera', input.ticket, 'spec.ts');
+  if (existsSync(specPath)) {
+    const src = readFileSync(specPath, 'utf8');
+    const updated = src.replace(
+      new RegExp(`from\\s+['"]\\./page-objects/${input.className}['"]`, 'g'),
+      `from '../../shared/page-objects/${input.className}'`,
+    );
+    writeFileSync(specPath, updated);
+  }
+}

package/src/generator/selector-rules.ts

@@ -0,0 +1,34 @@
+export interface SelectorWarning {
+  rule: 'no-auto-classname' | 'prefer-role-over-css' | 'no-xpath';
+  line: number;
+  text: string;
+  message: string;
+}
+
+const AUTO_CLASS_RE = /\.(?:Mui|css|ant|chakra|MuiButton)[A-Za-z]*-[A-Za-z0-9_]*-[A-Za-z0-9_]{3,}/;
+const LOCATOR_CSS_RE = /\.locator\(\s*['"`]([^'"`]+)['"`]/;
+const XPATH_RE = /\.locator\(\s*['"`](xpath=|\/\/)/;
+const ALLOW_CSS_RE = /xera-allow-css:/;
+
+export function lintSelectors(source: string): { warnings: SelectorWarning[] } {
+  const warnings: SelectorWarning[] = [];
+  const lines = source.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const text = lines[i]!;
+    const prev = lines[i - 1] ?? '';
+    if (XPATH_RE.test(text)) {
+      warnings.push({ rule: 'no-xpath', line: i + 1, text, message: 'XPath selectors are forbidden in v0.1.' });
+      continue;
+    }
+    const cssMatch = LOCATOR_CSS_RE.exec(text);
+    if (cssMatch) {
+      const sel = cssMatch[1]!;
+      if (AUTO_CLASS_RE.test(sel)) {
+        warnings.push({ rule: 'no-auto-classname', line: i + 1, text, message: `Auto-generated class name "${sel}" — refactor to role/label/test-id.` });
+      } else if (!ALLOW_CSS_RE.test(prev)) {
+        warnings.push({ rule: 'prefer-role-over-css', line: i + 1, text, message: `Prefer getByRole/getByLabel over CSS "${sel}". If unavoidable, add "// xera-allow-css: <reason>" on the previous line.` });
+      }
+    }
+  }
+  return { warnings };
+}

package/src/generator/typecheck.ts

@@ -0,0 +1,54 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export interface TypecheckResult {
+  ok: boolean;
+  errors: string[];
+}
+
+/**
+ * Walks up from `start` looking for the first `tsconfig.json`. Returns null if
+ * none is found before reaching the filesystem root.
+ */
+function findNearestTsconfig(start: string): string | null {
+  let dir = start;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = join(dir, 'tsconfig.json');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Type-check the ticket's TypeScript files using the project's root tsconfig.
+ * Errors are filtered to those whose path contains the ticket directory, so the
+ * skill sees only the locally relevant ones.
+ */
+export async function typecheckTicket(ticketDir: string): Promise<TypecheckResult> {
+  const tsconfig = findNearestTsconfig(ticketDir);
+  if (!tsconfig) {
+    return {
+      ok: false,
+      errors: [
+        `No tsconfig.json found walking up from ${ticketDir}. Run \`xera init\` to scaffold one at the project root.`,
+      ],
+    };
+  }
+
+  const proc = spawnSync('npx', ['tsc', '--noEmit', '-p', tsconfig], { encoding: 'utf8' });
+  if (proc.status === 0) return { ok: true, errors: [] };
+
+  const out = `${proc.stdout ?? ''}${proc.stderr ?? ''}`;
+  const allErrors = out.split('\n').filter((line) => /error TS\d+/.test(line));
+  // Keep errors that originate inside the ticket dir; if none match, fall back
+  // to all errors so callers don't see "ok" for a broken root.
+  const ticketErrors = allErrors.filter((line) => line.includes(ticketDir));
+  return {
+    ok: false,
+    errors: ticketErrors.length > 0 ? ticketErrors : allErrors,
+  };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from './adapter';
+export * from './auth-setup/define';
+export * from './auth-setup/runner';
+export * from './auth-setup/playwright-state';
+export * from './executor';
+export * from './executor/playwright-args';
+export * from './trace-normalizer/normalize';
+export * from './trace-normalizer/parse';
+export * from './trace-normalizer/scrub';
+export * from './trace-normalizer/scrub-rules';
+export * from './trace-normalizer/unzip';
+export * from './generator/gherkin-validate';
+export * from './generator/typecheck';
+export * from './generator/lint';
+export * from './generator/selector-rules';
+export * from './generator/pom-scan';
+export * from './generator/promote';

package/src/trace-normalizer/normalize.ts

@@ -0,0 +1,62 @@
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parsePlaywrightReport } from './parse';
+import { scrub, type NormalizedNetworkEntry, type NormalizedRun } from './scrub';
+import { unzipTrace } from './unzip';
+
+export interface NormalizeRunInput {
+  runId: string;
+  runDir: string;
+}
+
+interface TraceNetworkEntry {
+  type: 'request';
+  method: string;
+  url: string;
+  status: number;
+  requestHeaders?: Record<string, string>;
+  responseHeaders?: Record<string, string>;
+  requestBody?: unknown;
+  responseBody?: unknown;
+}
+
+interface TraceConsoleEntry { type: 'console'; text: string; }
+
+export async function normalizeRun(input: NormalizeRunInput): Promise<NormalizedRun> {
+  const reportPath = join(input.runDir, 'report.json');
+  const report = JSON.parse(readFileSync(reportPath, 'utf8'));
+  let normalized = parsePlaywrightReport(report, input.runId);
+
+  // Enrich with trace.zip if present
+  const tracePath = join(input.runDir, 'trace.zip');
+  if (existsSync(tracePath)) {
+    const { files } = unzipTrace(tracePath);
+    const networkFile = Object.entries(files).find(([k]) => k.endsWith('.network'))?.[1];
+    const traceFile = Object.entries(files).find(([k]) => k.endsWith('.trace'))?.[1];
+    const network: TraceNetworkEntry[] = networkFile
+      ? networkFile.trim().split('\n').filter(Boolean).map(l => JSON.parse(l)).filter((e: any) => e.type === 'request')
+      : [];
+    const consoleEvents: TraceConsoleEntry[] = traceFile
+      ? traceFile.trim().split('\n').filter(Boolean).map(l => JSON.parse(l)).filter((e: any) => e.type === 'console')
+      : [];
+
+    // Attach to each failing scenario (all entries — v0.1 doesn't yet correlate by step time)
+    for (const sc of normalized.scenarios) {
+      if (sc.outcome !== 'FAIL') continue;
+      sc.failure = sc.failure ?? {};
+      sc.failure.networkAtFailure = network.map(n => {
+        const entry: NormalizedNetworkEntry = { method: n.method, url: n.url, status: n.status };
+        if (n.requestHeaders !== undefined) entry.requestHeaders = n.requestHeaders;
+        if (n.responseHeaders !== undefined) entry.responseHeaders = n.responseHeaders;
+        if (n.requestBody !== undefined) entry.requestBody = n.requestBody;
+        if (n.responseBody !== undefined) entry.responseBody = n.responseBody;
+        return entry;
+      });
+      sc.failure.consoleAtFailure = consoleEvents.map(c => c.text);
+    }
+  }
+
+  normalized = scrub(normalized);
+  writeFileSync(join(input.runDir, 'normalized.json'), JSON.stringify(normalized, null, 2));
+  return normalized;
+}

package/src/trace-normalizer/parse.ts

@@ -0,0 +1,41 @@
+import type { NormalizedRun, NormalizedScenario } from './scrub';
+
+interface PWAttachment { name: string; path?: string; contentType?: string; }
+interface PWResult { status: string; duration: number; error?: { message?: string; stack?: string }; attachments?: PWAttachment[]; }
+interface PWTest { results: PWResult[]; }
+interface PWSpec { title: string; ok: boolean; tests: PWTest[]; }
+interface PWSuite { title: string; specs?: PWSpec[]; suites?: PWSuite[]; }
+interface PWReport { stats: { unexpected: number }; suites: PWSuite[]; }
+
+function* flatSpecs(suites: PWSuite[]): Generator<PWSpec> {
+  for (const s of suites) {
+    for (const sp of s.specs ?? []) yield sp;
+    if (s.suites) yield* flatSpecs(s.suites);
+  }
+}
+
+export function parsePlaywrightReport(report: PWReport, runId: string): NormalizedRun {
+  const scenarios: NormalizedScenario[] = [];
+  for (const spec of flatSpecs(report.suites)) {
+    const lastResult = spec.tests[0]?.results[0];
+    const outcome: 'PASS' | 'FAIL' | 'SKIPPED' =
+      !lastResult ? 'SKIPPED' :
+      lastResult.status === 'passed' ? 'PASS' :
+      lastResult.status === 'skipped' ? 'SKIPPED' : 'FAIL';
+    const sc: NormalizedScenario = { name: spec.title, outcome };
+    if (outcome === 'FAIL' && lastResult) {
+      const screenshot = lastResult.attachments?.find(a => a.name === 'screenshot')?.path;
+      const failure: NormalizedScenario['failure'] = {};
+      if (lastResult.error?.message !== undefined) failure!.errorMessage = lastResult.error.message;
+      if (screenshot !== undefined) failure!.screenshotPath = screenshot;
+      sc.failure = failure;
+    }
+    scenarios.push(sc);
+  }
+  return {
+    runId,
+    outcome: report.stats.unexpected === 0 ? 'PASS' : 'FAIL',
+    scenarios,
+    scrubbed_fields_count: 0,
+  };
+}

package/src/trace-normalizer/scrub-rules.ts

@@ -0,0 +1,60 @@
+export const SENSITIVE_HEADERS: readonly string[] = [
+  'authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'x-auth-token',
+  'x-csrf-token',
+  'proxy-authorization',
+];
+
+export const SENSITIVE_BODY_KEYS: readonly RegExp[] = [
+  /password/i,
+  /passwd/i,
+  /token/i,
+  /secret/i,
+  /api[-_]?key/i,
+  /access[-_]?key/i,
+  /private[-_]?key/i,
+  /authorization/i,
+  /credit[-_]?card/i,
+  /card[-_]?number/i,
+  /cvv/i,
+];
+
+export const JWT_RE = /\beyJ[A-Za-z0-9_-]{7,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{5,}\b/;
+export const CREDIT_CARD_RE = /\b(?:\d{4}[-\s]?){3}\d{4}\b/;
+
+const JWT_RE_G = new RegExp(JWT_RE.source, 'g');
+const CREDIT_CARD_RE_G = new RegExp(CREDIT_CARD_RE.source, 'g');
+
+const REDACTED = '[REDACTED]';
+
+export function scrubHeaders(headers: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    out[k] = SENSITIVE_HEADERS.includes(k.toLowerCase()) ? REDACTED : v;
+  }
+  return out;
+}
+
+export function scrubBodyJson(body: unknown): unknown {
+  if (Array.isArray(body)) return body.map(scrubBodyJson);
+  if (body && typeof body === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(body)) {
+      if (SENSITIVE_BODY_KEYS.some(re => re.test(k))) {
+        out[k] = REDACTED;
+      } else {
+        out[k] = scrubBodyJson(v);
+      }
+    }
+    return out;
+  }
+  if (typeof body === 'string') return scrubFreeText(body);
+  return body;
+}
+
+export function scrubFreeText(s: string): string {
+  return s.replace(JWT_RE_G, REDACTED).replace(CREDIT_CARD_RE_G, REDACTED);
+}

package/src/trace-normalizer/scrub.ts

@@ -0,0 +1,91 @@
+import { scrubHeaders, scrubBodyJson, scrubFreeText } from './scrub-rules';
+
+export interface NormalizedNetworkEntry {
+  method: string;
+  url: string;
+  status: number;
+  requestHeaders?: Record<string, string>;
+  requestBody?: unknown;
+  responseHeaders?: Record<string, string>;
+  responseBody?: unknown;
+}
+
+export interface NormalizedScenario {
+  name: string;
+  outcome: 'PASS' | 'FAIL' | 'SKIPPED';
+  failure?: {
+    step?: string;
+    errorMessage?: string;
+    domSnapshotAtFailure?: string;
+    networkAtFailure?: NormalizedNetworkEntry[];
+    consoleAtFailure?: string[];
+    screenshotPath?: string;
+  };
+}
+
+export interface NormalizedRun {
+  runId: string;
+  outcome: 'PASS' | 'FAIL';
+  scenarios: NormalizedScenario[];
+  scrubbed_fields_count: number;
+}
+
+function countScrubbed(before: unknown, after: unknown): number {
+  if (typeof before === 'string' && typeof after === 'string') return before !== after ? 1 : 0;
+  if (Array.isArray(before) && Array.isArray(after)) {
+    return before.reduce((acc, b, i) => acc + countScrubbed(b, after[i]), 0);
+  }
+  if (before && after && typeof before === 'object' && typeof after === 'object') {
+    let n = 0;
+    for (const k of Object.keys(before as Record<string, unknown>)) {
+      n += countScrubbed((before as Record<string, unknown>)[k], (after as Record<string, unknown>)[k]);
+    }
+    return n;
+  }
+  return 0;
+}
+
+export function scrub(run: NormalizedRun): NormalizedRun {
+  const out: NormalizedRun = { ...run, scrubbed_fields_count: 0, scenarios: [] };
+  let totalScrubs = 0;
+  for (const sc of run.scenarios) {
+    const newSc: NormalizedScenario = { ...sc };
+    if (sc.failure) {
+      const f = sc.failure;
+      const newF = { ...f };
+      if (f.errorMessage) {
+        newF.errorMessage = scrubFreeText(f.errorMessage);
+        totalScrubs += countScrubbed(f.errorMessage, newF.errorMessage);
+      }
+      if (f.consoleAtFailure) {
+        newF.consoleAtFailure = f.consoleAtFailure.map(scrubFreeText);
+        totalScrubs += f.consoleAtFailure.reduce(
+          (acc, b, i) => acc + countScrubbed(b, newF.consoleAtFailure![i]),
+          0,
+        );
+      }
+      if (f.networkAtFailure) {
+        newF.networkAtFailure = f.networkAtFailure.map(n => {
+          const reqHeaders = n.requestHeaders ? scrubHeaders(n.requestHeaders) : undefined;
+          const resHeaders = n.responseHeaders ? scrubHeaders(n.responseHeaders) : undefined;
+          const reqBody = n.requestBody !== undefined ? scrubBodyJson(n.requestBody) : undefined;
+          const resBody = n.responseBody !== undefined ? scrubBodyJson(n.responseBody) : undefined;
+          totalScrubs += countScrubbed(n.requestHeaders ?? {}, reqHeaders ?? {});
+          totalScrubs += countScrubbed(n.responseHeaders ?? {}, resHeaders ?? {});
+          totalScrubs += countScrubbed(n.requestBody ?? {}, reqBody ?? {});
+          totalScrubs += countScrubbed(n.responseBody ?? {}, resBody ?? {});
+          const out: NormalizedNetworkEntry = { method: n.method, url: n.url, status: n.status };
+          if (reqHeaders !== undefined) out.requestHeaders = reqHeaders;
+          if (resHeaders !== undefined) out.responseHeaders = resHeaders;
+          if (reqBody !== undefined) out.requestBody = reqBody;
+          if (resBody !== undefined) out.responseBody = resBody;
+          return out;
+        });
+      }
+      newSc.failure = newF;
+    }
+    out.scenarios.push(newSc);
+  }
+  out.scrubbed_fields_count = totalScrubs;
+  return out;
+}

package/src/trace-normalizer/unzip.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { unzipSync } from 'fflate';
+
+export interface TraceEntries {
+  /** Filename → text contents */
+  files: Record<string, string>;
+}
+
+export function unzipTrace(tracePath: string): TraceEntries {
+  const buf = readFileSync(tracePath);
+  const entries = unzipSync(buf);
+  const files: Record<string, string> = {};
+  for (const [name, data] of Object.entries(entries)) {
+    if (name.endsWith('/')) continue;
+    if (name.endsWith('.network') || name.endsWith('.trace') || name.endsWith('.txt') || name.endsWith('.json')) {
+      files[name] = new TextDecoder().decode(data);
+    }
+  }
+  return { files };
+}