@xera-ai/core 0.1.4 → 0.1.6

package/dist/bin/internal.js

@@ -335,12 +335,22 @@ async function fetchCmd(argv, opts = {}) {
 function renderStory(t) {
   const lines = [];
   lines.push(`# ${t.key}: ${t.summary}`, "");
-  lines.push(`## Story`, "", t.story.trim(), "");
+  const story = t.story.trim();
+  if (/^##\s+story\b/i.test(story)) {
+    lines.push(story, "");
+  } else {
+    lines.push("## Story", "", story, "");
+  }
   if (t.acceptanceCriteria && t.acceptanceCriteria.trim()) {
-    lines.push(`## Acceptance Criteria`, "", t.acceptanceCriteria.trim(), "");
+    const ac = t.acceptanceCriteria.trim();
+    if (/^##\s+acceptance\s+criteria\b/i.test(ac)) {
+      lines.push(ac, "");
+    } else {
+      lines.push("## Acceptance Criteria", "", ac, "");
+    }
   }
   if (t.attachments.length > 0) {
-    lines.push(`## Attachments`, "", ...t.attachments.map((a) => `- [${a.filename}](${a.url})`), "");
+    lines.push("## Attachments", "", ...t.attachments.map((a) => `- [${a.filename}](${a.url})`), "");
   }
   return lines.join(`
 `);
@@ -597,7 +607,7 @@ function needsRefresh(entry, policy, now = new Date) {
 // src/bin-internal/exec.ts
 import { stagePlaywrightState, runAuthSetup, runPlaywright } from "@xera-ai/web";
 import { chromium } from "@playwright/test";
-import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync7, existsSync as existsSync9 } from "fs";
+import { mkdirSync as mkdirSync7, existsSync as existsSync9 } from "fs";
 import { join as join5 } from "path";
 async function execCmd(argv) {
   const ticket = argv[0];
@@ -649,25 +659,29 @@ async function execCmd(argv) {
         await browser.close();
       }
     }
-    const stagedRoles = {};
     if (config.web.auth.strategy === "storageState") {
       for (const roleName of Object.keys(config.web.auth.roles)) {
         if (readAuthState(paths.authDir, roleName)) {
-          stagedRoles[roleName] = stagePlaywrightState(paths.authDir, roleName);
+          stagePlaywrightState(paths.authDir, roleName);
         }
       }
     }
-    const cfgPath = join5(paths.ticketDir, "playwright.config.ts");
+    const cfgPath = join5(cwd, "playwright.config.ts");
     if (!existsSync9(cfgPath)) {
-      writeFileSync6(cfgPath, renderPlaywrightConfig({
-        baseUrl: config.web.baseUrl[config.web.defaultEnv],
-        storageStatePathPerRole: stagedRoles
-      }));
+      console.error(`[xera:exec] missing ${cfgPath}. Run \`xera init\` to scaffold it, then re-run.`);
+      return 1;
     }
     const runDir = paths.runPath(runId).runDir;
     mkdirSync7(runDir, { recursive: true });
-    log.log({ step: "exec.start", runId });
-    const r = await runPlaywright({ specPath: paths.specPath, configPath: cfgPath, outputDir: runDir });
+    const envName = process.env.XERA_ENV ?? config.web.defaultEnv;
+    const baseURL = config.web.baseUrl[envName] ?? config.web.baseUrl[config.web.defaultEnv];
+    log.log({ step: "exec.start", runId, env: envName, baseURL });
+    const r = await runPlaywright({
+      specPath: paths.specPath,
+      configPath: cfgPath,
+      outputDir: runDir,
+      env: { XERA_BASE_URL: baseURL, XERA_ENV: envName }
+    });
     log.log({ step: "exec.done", runId, exit: r.exitCode, ms: Date.now() - t0 });
     console.log(`[xera:exec] runId=${runId} outcome=${r.outcome}`);
     return r.outcome === "PASS" ? 0 : 3;
@@ -675,20 +689,6 @@ async function execCmd(argv) {
     releaseLock(paths.lockPath);
   }
 }
-function renderPlaywrightConfig(opts) {
-  const projects = Object.entries(opts.storageStatePathPerRole).map(([role, path]) => `    { name: '${role}', use: { ...devices['Desktop Chromium'], storageState: '${path}' } }`);
-  if (projects.length === 0)
-    projects.push(`    { name: 'default', use: { ...devices['Desktop Chromium'] } }`);
-  return `import { defineConfig, devices } from '@playwright/test';
-export default defineConfig({
-  use: { baseURL: '${opts.baseUrl}', trace: 'on' },
-  projects: [
-${projects.join(`,
-`)}
-  ],
-});
-`;
-}
 
 // src/bin-internal/normalize.ts
 import { normalizeRun } from "@xera-ai/web";
@@ -718,7 +718,7 @@ async function normalizeCmd(argv) {
 }
 
 // src/bin-internal/report.ts
-import { readFileSync as readFileSync9, writeFileSync as writeFileSync8 } from "fs";
+import { readFileSync as readFileSync9, writeFileSync as writeFileSync7 } from "fs";
 import { join as join7 } from "path";
 
 // src/classifier/aggregate.ts
@@ -753,7 +753,7 @@ function aggregateScenarios(scenarios) {
 import { existsSync as existsSync12 } from "fs";
 
 // src/artifact/status.ts
-import { existsSync as existsSync11, readFileSync as readFileSync8, writeFileSync as writeFileSync7, mkdirSync as mkdirSync8 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync8, writeFileSync as writeFileSync6, mkdirSync as mkdirSync8 } from "fs";
 import { dirname as dirname5 } from "path";
 import { z as z4 } from "zod";
 var ClassificationEnum = z4.enum(["PASS", "REAL_BUG", "SELECTOR_DRIFT", "FLAKY", "TEST_BUG"]);
@@ -787,7 +787,7 @@ function readStatus(path) {
 }
 function writeStatus(path, status) {
   mkdirSync8(dirname5(path), { recursive: true });
-  writeFileSync7(path, JSON.stringify(status, null, 2));
+  writeFileSync6(path, JSON.stringify(status, null, 2));
 }
 function appendHistory(path, entry) {
   const s = readStatus(path);
@@ -884,7 +884,7 @@ async function reportCmd(argv) {
     promptsVersion: "1.0.0"
   });
   const draftPath = join7(paths.ticketDir, "jira-comment.draft.md");
-  writeFileSync8(draftPath, md);
+  writeFileSync7(draftPath, md);
   console.log(`[xera:report] wrote status.json and ${draftPath}`);
   return 0;
 }

package/dist/bin-internal/exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/bin-internal/exec.ts"],"names":[],"mappings":"AAWA,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoF7D"}
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/bin-internal/exec.ts"],"names":[],"mappings":"AAWA,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8F7D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/core",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,14 +19,14 @@
   "bin": {
   "xera-internal": "./dist/bin/internal.js"
 },
-"files": ["dist", "bin"],
+"files": ["dist", "src", "bin"],
 "scripts": {
   "build": "bun build ./src/index.ts ./bin/internal.ts --outdir ./dist --target bun --external @playwright/test --external @xera-ai/web --external zod",
   "typecheck": "tsc --noEmit"
 },
 "dependencies": {
   "zod": "3.23.8",
-  "@xera-ai/web": "^0.1.4",
+  "@xera-ai/web": "^0.1.5",
   "@playwright/test": "1.48.0"
 }
 }

package/src/adapter/types.ts

@@ -0,0 +1,62 @@
+import type { XeraConfig } from '../config/schema';
+import type { Classification } from '../artifact/status';
+
+export interface GenerateInput {
+  ticketDir: string;
+  feature: string;
+  story: string;
+  config: XeraConfig;
+}
+
+export interface GenerateResult {
+  artifacts: string[];
+  warnings: string[];
+}
+
+export interface ExecuteInput {
+  ticketDir: string;
+  config: XeraConfig;
+  runId: string;
+  env: string;
+}
+
+export interface ScenarioResult {
+  name: string;
+  outcome: 'PASS' | 'FAIL' | 'SKIPPED';
+  failure?: {
+    step?: string;
+    errorMessage?: string;
+    domSnapshotAtFailure?: string;
+    networkAtFailure?: Array<{ method: string; url: string; status: number }>;
+    consoleAtFailure?: string[];
+    screenshotPath?: string;
+  };
+}
+
+export interface RunResult {
+  runId: string;
+  outcome: 'PASS' | 'FAIL';
+  scenarios: ScenarioResult[];
+  artifactsDir: string;
+  rawReportPath: string;
+  normalizedReportPath: string;
+}
+
+export interface ClassifyContext {
+  history: Array<{ ts: string; result: 'PASS' | 'FAIL'; class: Classification }>;
+  storyHashChanged: boolean;
+  specHashChanged: boolean;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  checks: Array<{ name: string; ok: boolean; message?: string }>;
+}
+
+export interface TestAdapter {
+  readonly id: string;
+  generate(input: GenerateInput): Promise<GenerateResult>;
+  execute(input: ExecuteInput): Promise<RunResult>;
+  classify?(run: RunResult, ctx: ClassifyContext): Partial<{ class: Classification; rationale: string }>;
+  doctor(): Promise<DoctorReport>;
+}

package/src/artifact/hash.ts

@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+
+export function hashString(s: string): string {
+  return `sha256:${createHash('sha256').update(s).digest('hex')}`;
+}
+
+export function hashFile(path: string): string {
+  return hashString(readFileSync(path, 'utf8'));
+}
+
+export function hashFileIfExists(path: string): string | null {
+  if (!existsSync(path)) return null;
+  return hashFile(path);
+}

package/src/artifact/meta.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+
+export const MetaJsonSchema = z.object({
+  ticket: z.string(),
+  adapter: z.string(),
+  xera_version: z.string(),
+  prompts_version: z.string(),
+  fetched_at: z.string().optional(),
+  story_hash: z.string().optional(),
+  feature_generated_at: z.string().optional(),
+  feature_generated_from_story_hash: z.string().optional(),
+  feature_hash: z.string().optional(),
+  script_generated_at: z.string().optional(),
+  script_generated_from_feature_hash: z.string().optional(),
+  script_warnings: z.array(z.string()).optional(),
+});
+
+export type MetaJson = z.infer<typeof MetaJsonSchema>;
+
+export function readMeta(path: string): MetaJson | null {
+  if (!existsSync(path)) return null;
+  return MetaJsonSchema.parse(JSON.parse(readFileSync(path, 'utf8')));
+}
+
+export function writeMeta(path: string, meta: MetaJson): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(meta, null, 2));
+}
+
+export function updateMeta(path: string, patch: Partial<MetaJson>): MetaJson {
+  const existing = readMeta(path);
+  if (!existing) {
+    throw new Error(`meta.json not found at ${path}; cannot update`);
+  }
+  const next = { ...existing, ...patch };
+  writeMeta(path, next);
+  return next;
+}

package/src/artifact/paths.ts

@@ -0,0 +1,62 @@
+import { join } from 'node:path';
+
+const TICKET_RE = /^[A-Z][A-Z0-9_]*-\d+$|^SAMPLE-\d+$/;
+
+export interface RunPaths {
+  runDir: string;
+  reportJsonPath: string;
+  tracePath: string;
+  normalizedPath: string;
+  screenshotsDir: string;
+  videoDir: string;
+}
+
+export interface ArtifactPaths {
+  ticketDir: string;
+  storyPath: string;
+  featurePath: string;
+  specPath: string;
+  pageObjectsDir: string;
+  runsDir: string;
+  metaPath: string;
+  statusPath: string;
+  logPath: string;
+  lockPath: string;
+  authDir: string;
+  runPath: (runId: string) => RunPaths;
+}
+
+export function resolveArtifactPaths(repoRoot: string, ticket: string): ArtifactPaths {
+  if (!TICKET_RE.test(ticket)) {
+    throw new Error(`Invalid ticket key: "${ticket}" (expected e.g. JIRA-123 or SAMPLE-001)`);
+  }
+  const ticketDir = join(repoRoot, '.xera', ticket);
+  return {
+    ticketDir,
+    storyPath: join(ticketDir, 'story.md'),
+    featurePath: join(ticketDir, 'test.feature'),
+    specPath: join(ticketDir, 'spec.ts'),
+    pageObjectsDir: join(ticketDir, 'page-objects'),
+    runsDir: join(ticketDir, 'runs'),
+    metaPath: join(ticketDir, 'meta.json'),
+    statusPath: join(ticketDir, 'status.json'),
+    logPath: join(ticketDir, 'xera.log'),
+    lockPath: join(ticketDir, '.lock'),
+    authDir: join(repoRoot, '.xera', '.auth'),
+    runPath: (runId: string) => {
+      const runDir = join(ticketDir, 'runs', runId);
+      return {
+        runDir,
+        reportJsonPath: join(runDir, 'report.json'),
+        tracePath: join(runDir, 'trace.zip'),
+        normalizedPath: join(runDir, 'normalized.json'),
+        screenshotsDir: join(runDir, 'screenshots'),
+        videoDir: join(runDir, 'videos'),
+      };
+    },
+  };
+}
+
+export function generateRunId(now: Date = new Date()): string {
+  return now.toISOString().replace(/[:.]/g, '-').replace('Z', '');
+}

package/src/artifact/status.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+
+const ClassificationEnum = z.enum(['PASS', 'REAL_BUG', 'SELECTOR_DRIFT', 'FLAKY', 'TEST_BUG']);
+const ResultEnum = z.enum(['PASS', 'FAIL']);
+const ConfidenceEnum = z.enum(['low', 'medium', 'high']);
+
+export const HistoryEntrySchema = z.object({
+  ts: z.string(),
+  result: ResultEnum,
+  class: ClassificationEnum,
+});
+
+export const StatusJsonSchema = z.object({
+  ticket: z.string(),
+  lastRun: z.string(),
+  result: ResultEnum,
+  classification: ClassificationEnum,
+  confidence: ConfidenceEnum,
+  scenarios: z.object({
+    total: z.number().int().nonnegative(),
+    passed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+  }),
+  history: z.array(HistoryEntrySchema).default([]),
+  last_jira_comment_id: z.string().optional(),
+});
+
+export type StatusJson = z.infer<typeof StatusJsonSchema>;
+export type HistoryEntry = z.infer<typeof HistoryEntrySchema>;
+export type Classification = z.infer<typeof ClassificationEnum>;
+
+const HISTORY_CAP = 20;
+
+export function readStatus(path: string): StatusJson | null {
+  if (!existsSync(path)) return null;
+  return StatusJsonSchema.parse(JSON.parse(readFileSync(path, 'utf8')));
+}
+
+export function writeStatus(path: string, status: StatusJson): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(status, null, 2));
+}
+
+export function appendHistory(path: string, entry: HistoryEntry): StatusJson {
+  const s = readStatus(path);
+  if (!s) {
+    throw new Error(`status.json not found at ${path}`);
+  }
+  s.history = [entry, ...s.history].slice(0, HISTORY_CAP);
+  writeStatus(path, s);
+  return s;
+}

package/src/auth/encrypt.ts

@@ -0,0 +1,40 @@
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+
+const ALGO = 'aes-256-gcm';
+const KEY_LEN = 32; // bytes (256 bits)
+const IV_LEN = 12;  // recommended for GCM
+const TAG_LEN = 16;
+const VERSION = 'v1';
+
+export function generateKey(): string {
+  return randomBytes(KEY_LEN).toString('hex');
+}
+
+function keyToBuf(key: string): Buffer {
+  const buf = Buffer.from(key, 'hex');
+  if (buf.length !== KEY_LEN) throw new Error(`Key must be ${KEY_LEN} bytes (got ${buf.length})`);
+  return buf;
+}
+
+export function encrypt(plaintext: string, keyHex: string): string {
+  const key = keyToBuf(keyHex);
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return `${VERSION}:${iv.toString('base64')}:${tag.toString('base64')}:${ct.toString('base64')}`;
+}
+
+export function decrypt(ciphertext: string, keyHex: string): string {
+  const [version, ivB64, tagB64, ctB64] = ciphertext.split(':');
+  if (version !== VERSION) throw new Error(`Unsupported ciphertext version: ${version}`);
+  if (!ivB64 || !tagB64 || !ctB64) throw new Error('Malformed ciphertext');
+  const key = keyToBuf(keyHex);
+  const iv = Buffer.from(ivB64, 'base64');
+  const tag = Buffer.from(tagB64, 'base64');
+  const ct = Buffer.from(ctB64, 'base64');
+  if (tag.length !== TAG_LEN) throw new Error('Bad auth tag length');
+  const decipher = createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+}

package/src/auth/key.ts

@@ -0,0 +1,15 @@
+export const AUTH_KEY_ENV = 'XERA_AUTH_KEY';
+
+export function resolveAuthKey(): string {
+  const key = process.env[AUTH_KEY_ENV];
+  if (!key) {
+    throw new Error(
+      `${AUTH_KEY_ENV} not set. It is auto-generated by \`xera init\` and saved to .env. ` +
+        `If you deleted .env, regenerate it by running \`xera init --update\` — note that any cached auth state will be invalidated.`,
+    );
+  }
+  if (!/^[0-9a-f]{64}$/i.test(key)) {
+    throw new Error(`${AUTH_KEY_ENV} must be a 64-character hex string (32 bytes).`);
+  }
+  return key;
+}

package/src/auth/refresh.ts

@@ -0,0 +1,31 @@
+import type { AuthStateEntry } from './state';
+export type { AuthStateEntry } from './state';
+
+const RE = /^(\d+)([hms])$/;
+
+export function parseDuration(d: string): number {
+  const m = RE.exec(d);
+  if (!m) throw new Error(`Bad duration "${d}" — expected e.g. "8h", "30m", "45s"`);
+  const n = Number(m[1]);
+  const unit = m[2]!;
+  if (unit === 'h') return n * 3600 * 1000;
+  if (unit === 'm') return n * 60 * 1000;
+  return n * 1000;
+}
+
+export interface RefreshPolicy { ttl: string; refreshBuffer: string; }
+
+export function needsRefresh(
+  entry: AuthStateEntry | null,
+  policy: RefreshPolicy,
+  now: Date = new Date(),
+): boolean {
+  if (!entry) return true;
+  const ttlMs = parseDuration(policy.ttl);
+  const bufMs = parseDuration(policy.refreshBuffer);
+  const createdAt = new Date(entry.created_at).getTime();
+  if (now.getTime() - createdAt > ttlMs) return true;
+  const expiresAt = new Date(entry.expires_at).getTime();
+  if (expiresAt - now.getTime() < bufMs) return true;
+  return false;
+}

package/src/auth/state.ts

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { encrypt, decrypt } from './encrypt';
+import { resolveAuthKey } from './key';
+
+export const AuthStateEntrySchema = z.object({
+  role: z.string(),
+  strategy: z.enum(['storageState', 'apiToken']),
+  created_at: z.string(),
+  expires_at: z.string(),
+  payload: z.record(z.string(), z.unknown()),
+});
+export type AuthStateEntry = z.infer<typeof AuthStateEntrySchema>;
+
+function pathFor(authDir: string, role: string): string {
+  return join(authDir, `${role}.json`);
+}
+
+export function writeAuthState(authDir: string, entry: AuthStateEntry): void {
+  mkdirSync(authDir, { recursive: true });
+  const ct = encrypt(JSON.stringify(entry), resolveAuthKey());
+  writeFileSync(pathFor(authDir, entry.role), ct);
+}
+
+export function readAuthState(authDir: string, role: string): AuthStateEntry | null {
+  const p = pathFor(authDir, role);
+  if (!existsSync(p)) return null;
+  const txt = readFileSync(p, 'utf8');
+  const plain = decrypt(txt, resolveAuthKey());
+  return AuthStateEntrySchema.parse(JSON.parse(plain));
+}

package/src/bin-internal/exec.ts

@@ -0,0 +1,107 @@
+import { resolveArtifactPaths, generateRunId } from '../artifact/paths';
+import { acquireLock, releaseLock, isLockStale, readLock, forceUnlock } from '../lock/file-lock';
+import { NdjsonLogger } from '../logging/ndjson-logger';
+import { loadConfig } from '../config/load';
+import { readAuthState } from '../auth/state';
+import { needsRefresh } from '../auth/refresh';
+import { stagePlaywrightState, runAuthSetup, runPlaywright } from '@xera-ai/web';
+import { chromium } from '@playwright/test';
+import { mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export async function execCmd(argv: string[]): Promise<number> {
+  const ticket = argv[0];
+  if (!ticket) { console.error('[xera:exec] usage: exec <TICKET>'); return 1; }
+  const cwd = process.cwd();
+  const config = await loadConfig(cwd);
+  const paths = resolveArtifactPaths(cwd, ticket);
+  const runId = generateRunId();
+  const log = new NdjsonLogger(paths.logPath);
+
+  // Acquire lock
+  if (!acquireLock(paths.lockPath, runId)) {
+    if (isLockStale(paths.lockPath)) {
+      console.error(`[xera:exec] stale lock detected; force unlocking. Run \`xera-internal unlock ${ticket}\` to clear manually.`);
+      forceUnlock(paths.lockPath);
+      acquireLock(paths.lockPath, runId);
+    } else {
+      const existing = readLock(paths.lockPath);
+      console.error(`[xera:exec] another run in progress (PID ${existing?.pid} on ${existing?.hostname}, started ${existing?.started_at}). Wait or run \`xera-internal unlock ${ticket}\`.`);
+      return 1;
+    }
+  }
+
+  const t0 = Date.now();
+  try {
+    // Auth refresh per role declared in xera.config.ts
+    if (config.web.auth.strategy === 'storageState' && config.web.auth.setupScript) {
+      const browser = await chromium.launch();
+      try {
+        for (const [roleName, roleCreds] of Object.entries(config.web.auth.roles)) {
+          const entry = readAuthState(paths.authDir, roleName);
+          if (needsRefresh(entry, { ttl: config.web.auth.ttl, refreshBuffer: config.web.auth.refreshBuffer })) {
+            const email = process.env[roleCreds.envEmail];
+            const password = process.env[roleCreds.envPassword];
+            if (!email || !password) {
+              console.error(`[xera:exec] missing env ${roleCreds.envEmail} or ${roleCreds.envPassword} for role "${roleName}"`);
+              return 1;
+            }
+            await runAuthSetup({
+              role: roleName,
+              creds: { email, password },
+              setupScriptPath: join(cwd, config.web.auth.setupScript),
+              authDir: paths.authDir,
+              browser,
+            });
+            log.log({ step: 'auth-refresh', role: roleName });
+          }
+        }
+      } finally {
+        await browser.close();
+      }
+    }
+
+    // Stage Playwright storageState files at predictable paths
+    // (.xera/.auth/.cache/<role>.json) — generated spec.ts references these
+    // via test.use({ storageState }) when an authenticated session is needed.
+    if (config.web.auth.strategy === 'storageState') {
+      for (const roleName of Object.keys(config.web.auth.roles)) {
+        if (readAuthState(paths.authDir, roleName)) {
+          stagePlaywrightState(paths.authDir, roleName);
+        }
+      }
+    }
+
+    // Use the root playwright.config.ts (generated by `xera init`). We never
+    // emit a per-ticket config — that path duplicates the root and bit-rots.
+    const cfgPath = join(cwd, 'playwright.config.ts');
+    if (!existsSync(cfgPath)) {
+      console.error(
+        `[xera:exec] missing ${cfgPath}. Run \`xera init\` to scaffold it, then re-run.`,
+      );
+      return 1;
+    }
+
+    const runDir = paths.runPath(runId).runDir;
+    mkdirSync(runDir, { recursive: true });
+
+    const envName = process.env.XERA_ENV ?? config.web.defaultEnv;
+    const baseURL = config.web.baseUrl[envName] ?? config.web.baseUrl[config.web.defaultEnv]!;
+
+    log.log({ step: 'exec.start', runId, env: envName, baseURL });
+    const r = await runPlaywright({
+      specPath: paths.specPath,
+      configPath: cfgPath,
+      outputDir: runDir,
+      env: { XERA_BASE_URL: baseURL, XERA_ENV: envName },
+    });
+    log.log({ step: 'exec.done', runId, exit: r.exitCode, ms: Date.now() - t0 });
+
+    console.log(`[xera:exec] runId=${runId} outcome=${r.outcome}`);
+    // Exit 3 means "test failed" (expected vs infra error)
+    return r.outcome === 'PASS' ? 0 : 3;
+  } finally {
+    releaseLock(paths.lockPath);
+  }
+}
+