@xera-ai/core 0.1.0

package/dist/bin/internal.js

@@ -0,0 +1,1013 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/bin-internal/fetch.ts
+import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
+import { dirname as dirname2 } from "path";
+
+// src/config/load.ts
+import { existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+// src/config/schema.ts
+import { z } from "zod";
+var AuthRoleSchema = z.object({
+  envEmail: z.string().min(1),
+  envPassword: z.string().min(1)
+});
+var AuthSchema = z.object({
+  strategy: z.enum(["storageState", "apiToken", "none"]).default("none"),
+  ttl: z.string().default("8h"),
+  refreshBuffer: z.string().default("30m"),
+  setupScript: z.string().optional(),
+  roles: z.record(z.string(), AuthRoleSchema).default({})
+});
+var WebSchema = z.object({
+  baseUrl: z.record(z.string(), z.string().url()).refine((m) => Object.keys(m).length > 0, {
+    message: "baseUrl must have at least one environment"
+  }),
+  defaultEnv: z.string(),
+  auth: AuthSchema.default({}),
+  testData: z.object({
+    users: z.record(z.string(), z.object({ fromAuth: z.string() })).default({})
+  }).default({ users: {} })
+}).refine((w) => w.baseUrl[w.defaultEnv] !== undefined, {
+  message: "defaultEnv must exist in baseUrl map",
+  path: ["defaultEnv"]
+});
+var JiraSchema = z.object({
+  baseUrl: z.string().url(),
+  projectKeys: z.array(z.string().min(1)).min(1),
+  fields: z.object({
+    story: z.string().min(1),
+    acceptanceCriteria: z.string().optional(),
+    attachments: z.string().default("attachment")
+  })
+});
+var AISchema = z.object({
+  livePageSnapshot: z.boolean().default(true),
+  confidenceThreshold: z.enum(["low", "medium", "high"]).default("medium"),
+  maxRetries: z.object({
+    typecheck: z.number().int().min(0).max(5).default(2),
+    lint: z.number().int().min(0).max(5).default(2),
+    validateFeature: z.number().int().min(0).max(5).default(2)
+  }).default({})
+}).default({});
+var ReportingSchema = z.object({
+  language: z.enum(["en", "vi"]).default("en"),
+  postToJira: z.boolean().default(true),
+  transition: z.object({
+    onPass: z.string().nullable().default(null),
+    onFail: z.string().nullable().default(null)
+  }).default({}),
+  artifactLinks: z.enum(["git", "local"]).default("git")
+}).default({});
+var XeraConfigSchema = z.object({
+  jira: JiraSchema,
+  web: WebSchema,
+  ai: AISchema,
+  reporting: ReportingSchema,
+  adapters: z.array(z.string().min(1)).min(1).default(["web"])
+});
+
+// src/config/load.ts
+async function loadConfig(cwd) {
+  const path = join(cwd, "xera.config.ts");
+  if (!existsSync(path)) {
+    throw new Error(`xera.config.ts not found in ${cwd}`);
+  }
+  const mod = await import(pathToFileURL(path).href);
+  const raw = mod.default ?? mod;
+  return XeraConfigSchema.parse(raw);
+}
+
+// src/artifact/paths.ts
+import { join as join2 } from "path";
+var TICKET_RE = /^[A-Z][A-Z0-9_]*-\d+$|^SAMPLE-\d+$/;
+function resolveArtifactPaths(repoRoot, ticket) {
+  if (!TICKET_RE.test(ticket)) {
+    throw new Error(`Invalid ticket key: "${ticket}" (expected e.g. JIRA-123 or SAMPLE-001)`);
+  }
+  const ticketDir = join2(repoRoot, ".xera", ticket);
+  return {
+    ticketDir,
+    storyPath: join2(ticketDir, "story.md"),
+    featurePath: join2(ticketDir, "test.feature"),
+    specPath: join2(ticketDir, "spec.ts"),
+    pageObjectsDir: join2(ticketDir, "page-objects"),
+    runsDir: join2(ticketDir, "runs"),
+    metaPath: join2(ticketDir, "meta.json"),
+    statusPath: join2(ticketDir, "status.json"),
+    logPath: join2(ticketDir, "xera.log"),
+    lockPath: join2(ticketDir, ".lock"),
+    authDir: join2(repoRoot, ".xera", ".auth"),
+    runPath: (runId) => {
+      const runDir = join2(ticketDir, "runs", runId);
+      return {
+        runDir,
+        reportJsonPath: join2(runDir, "report.json"),
+        tracePath: join2(runDir, "trace.zip"),
+        normalizedPath: join2(runDir, "normalized.json"),
+        screenshotsDir: join2(runDir, "screenshots"),
+        videoDir: join2(runDir, "videos")
+      };
+    }
+  };
+}
+function generateRunId(now = new Date) {
+  return now.toISOString().replace(/[:.]/g, "-").replace("Z", "");
+}
+
+// src/artifact/hash.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, readFileSync } from "fs";
+function hashString(s) {
+  return `sha256:${createHash("sha256").update(s).digest("hex")}`;
+}
+function hashFile(path) {
+  return hashString(readFileSync(path, "utf8"));
+}
+function hashFileIfExists(path) {
+  if (!existsSync2(path))
+    return null;
+  return hashFile(path);
+}
+
+// src/artifact/meta.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import { z as z2 } from "zod";
+var MetaJsonSchema = z2.object({
+  ticket: z2.string(),
+  adapter: z2.string(),
+  xera_version: z2.string(),
+  prompts_version: z2.string(),
+  fetched_at: z2.string().optional(),
+  story_hash: z2.string().optional(),
+  feature_generated_at: z2.string().optional(),
+  feature_generated_from_story_hash: z2.string().optional(),
+  feature_hash: z2.string().optional(),
+  script_generated_at: z2.string().optional(),
+  script_generated_from_feature_hash: z2.string().optional(),
+  script_warnings: z2.array(z2.string()).optional()
+});
+function readMeta(path) {
+  if (!existsSync3(path))
+    return null;
+  return MetaJsonSchema.parse(JSON.parse(readFileSync2(path, "utf8")));
+}
+function writeMeta(path, meta) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(meta, null, 2));
+}
+function updateMeta(path, patch) {
+  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;
+}
+
+// src/jira/mcp-backend.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+var MCP_ENV = "XERA_MCP_JIRA";
+async function createMcpBackend(_baseUrl) {
+  if (process.env[MCP_ENV] !== "1")
+    return null;
+  const tmpDir = join3(tmpdir(), "xera-mcp");
+  mkdirSync2(tmpDir, { recursive: true });
+  return {
+    backend: "mcp",
+    async fetchTicket(key, _fields) {
+      const cachePath = join3(tmpDir, `${key}.json`);
+      if (!existsSync4(cachePath)) {
+        throw new Error(`MCP-mode fetch requires the skill to first call mcp__atlassian__getJiraIssue and write ${cachePath}. ` + `If you are running this directly, unset ${MCP_ENV} to use REST.`);
+      }
+      const parsed = JSON.parse(readFileSync3(cachePath, "utf8"));
+      return parsed;
+    },
+    async postComment(key, body) {
+      const outPath = join3(tmpDir, `${key}.comment.json`);
+      writeFileSync2(outPath, JSON.stringify({ key, body }));
+      return { id: "mcp-pending" };
+    },
+    async transitionStatus(key, statusName) {
+      const outPath = join3(tmpDir, `${key}.transition.json`);
+      writeFileSync2(outPath, JSON.stringify({ key, statusName }));
+    },
+    async listFields(_sampleKey) {
+      throw new Error("listFields is REST-only; init flow uses REST for field discovery.");
+    }
+  };
+}
+
+// src/jira/rest-backend.ts
+function createRestBackend(baseUrl, creds) {
+  const authHeader = `Basic ${Buffer.from(`${creds.email}:${creds.apiToken}`).toString("base64")}`;
+  const base = baseUrl.replace(/\/$/, "");
+  async function req(path, init) {
+    const r = await fetch(`${base}${path}`, {
+      ...init,
+      headers: {
+        Authorization: authHeader,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...init?.headers ?? {}
+      }
+    });
+    if (!r.ok && r.status !== 201) {
+      throw new Error(`Jira REST ${init?.method ?? "GET"} ${path} failed: ${r.status} ${await r.text()}`);
+    }
+    return r;
+  }
+  return {
+    backend: "rest",
+    async fetchTicket(key, fields) {
+      const want = ["summary", fields.story];
+      if (fields.acceptanceCriteria)
+        want.push(fields.acceptanceCriteria);
+      want.push("attachment");
+      const r = await req(`/rest/api/3/issue/${encodeURIComponent(key)}?fields=${want.join(",")}`);
+      const json = await r.json();
+      const f = json.fields;
+      const attachments = Array.isArray(f.attachment) ? f.attachment.map((a) => ({ filename: a.filename, url: a.content })) : [];
+      const ticket = {
+        key: json.key,
+        summary: String(f.summary ?? ""),
+        story: String(f[fields.story] ?? ""),
+        attachments,
+        raw: f
+      };
+      if (fields.acceptanceCriteria) {
+        ticket.acceptanceCriteria = String(f[fields.acceptanceCriteria] ?? "");
+      }
+      return ticket;
+    },
+    async postComment(key, body) {
+      const r = await req(`/rest/api/3/issue/${encodeURIComponent(key)}/comment`, {
+        method: "POST",
+        body: JSON.stringify({
+          body: { type: "doc", version: 1, content: [{ type: "paragraph", content: [{ type: "text", text: body }] }] }
+        })
+      });
+      const json = await r.json();
+      return { id: json.id };
+    },
+    async transitionStatus(key, statusName) {
+      const tr = await req(`/rest/api/3/issue/${encodeURIComponent(key)}/transitions`);
+      const json = await tr.json();
+      const t = json.transitions.find((x) => x.name === statusName);
+      if (!t)
+        throw new Error(`No transition named "${statusName}" available for ${key}`);
+      await req(`/rest/api/3/issue/${encodeURIComponent(key)}/transitions`, {
+        method: "POST",
+        body: JSON.stringify({ transition: { id: t.id } })
+      });
+    },
+    async listFields(sampleKey) {
+      const r = await req(`/rest/api/3/issue/${encodeURIComponent(sampleKey)}?fields=*all`);
+      const json = await r.json();
+      return Object.entries(json.fields).map(([id, value]) => ({
+        id,
+        name: id,
+        hasContent: value !== null && value !== undefined && value !== ""
+      }));
+    }
+  };
+}
+
+// src/jira/client.ts
+async function createJiraClient(opts) {
+  if (opts.preferMcp !== false) {
+    const mcp = await createMcpBackend(opts.baseUrl);
+    if (mcp)
+      return mcp;
+  }
+  if (!opts.rest) {
+    throw new Error("Atlassian MCP not connected and no REST credentials provided (JIRA_EMAIL + JIRA_API_TOKEN).");
+  }
+  return createRestBackend(opts.baseUrl, opts.rest);
+}
+
+// src/bin-internal/fetch.ts
+async function fetchCmd(argv, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const ticket = argv[0];
+  if (!ticket) {
+    console.error("[xera:fetch] usage: xera-internal fetch <TICKET>");
+    return 1;
+  }
+  const config = await loadConfig(cwd);
+  const paths = resolveArtifactPaths(cwd, ticket);
+  let t;
+  if (process.env.XERA_TEST_JIRA) {
+    t = JSON.parse(process.env.XERA_TEST_JIRA);
+  } else {
+    const client = await createJiraClient({
+      baseUrl: config.jira.baseUrl,
+      preferMcp: true,
+      ...process.env.JIRA_EMAIL && process.env.JIRA_API_TOKEN ? { rest: { email: process.env.JIRA_EMAIL, apiToken: process.env.JIRA_API_TOKEN } } : {}
+    });
+    const fieldMap = config.jira.fields.acceptanceCriteria !== undefined ? { story: config.jira.fields.story, acceptanceCriteria: config.jira.fields.acceptanceCriteria } : { story: config.jira.fields.story };
+    t = await client.fetchTicket(ticket, fieldMap);
+  }
+  const story = renderStory(t);
+  mkdirSync3(dirname2(paths.storyPath), { recursive: true });
+  writeFileSync3(paths.storyPath, story);
+  const existing = readMeta(paths.metaPath);
+  writeMeta(paths.metaPath, {
+    ticket,
+    adapter: "web",
+    xera_version: "0.1.0",
+    prompts_version: "1.0.0",
+    ...existing ?? {},
+    story_hash: hashString(story),
+    fetched_at: new Date().toISOString()
+  });
+  console.log(`[xera:fetch] wrote ${paths.storyPath}`);
+  return 0;
+}
+function renderStory(t) {
+  const lines = [];
+  lines.push(`# ${t.key}: ${t.summary}`, "");
+  lines.push(`## Story`, "", t.story.trim(), "");
+  if (t.acceptanceCriteria && t.acceptanceCriteria.trim()) {
+    lines.push(`## Acceptance Criteria`, "", t.acceptanceCriteria.trim(), "");
+  }
+  if (t.attachments.length > 0) {
+    lines.push(`## Attachments`, "", ...t.attachments.map((a) => `- [${a.filename}](${a.url})`), "");
+  }
+  return lines.join(`
+`);
+}
+
+// src/bin-internal/validate-feature.ts
+import { readFileSync as readFileSync4, existsSync as existsSync5 } from "fs";
+import { validateGherkin } from "@xera-ai/web";
+async function validateFeatureCmd(argv) {
+  const ticket = argv[0];
+  if (!ticket) {
+    console.error("[xera:validate-feature] usage: validate-feature <TICKET>");
+    return 1;
+  }
+  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  if (!existsSync5(paths.featurePath)) {
+    console.error(`[xera:validate-feature] missing ${paths.featurePath}`);
+    return 1;
+  }
+  const r = validateGherkin(readFileSync4(paths.featurePath, "utf8"));
+  if (r.ok) {
+    console.log("[xera:validate-feature] ok");
+    return 0;
+  }
+  for (const e of r.errors)
+    console.error(`[xera:validate-feature] line ${e.line}: ${e.message}`);
+  return 2;
+}
+
+// src/bin-internal/typecheck.ts
+import { typecheckTicket } from "@xera-ai/web";
+async function typecheckCmd(argv) {
+  const ticket = argv[0];
+  if (!ticket) {
+    console.error("[xera:typecheck] usage: typecheck <TICKET>");
+    return 1;
+  }
+  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  const r = await typecheckTicket(paths.ticketDir);
+  if (r.ok) {
+    console.log("[xera:typecheck] ok");
+    return 0;
+  }
+  for (const e of r.errors)
+    console.error(`[xera:typecheck] ${e}`);
+  return 2;
+}
+
+// src/bin-internal/lint.ts
+import { lintTicket } from "@xera-ai/web";
+async function lintCmd(argv) {
+  const ticket = argv[0];
+  if (!ticket) {
+    console.error("[xera:lint] usage: lint <TICKET>");
+    return 1;
+  }
+  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  const r = await lintTicket(paths.ticketDir);
+  if (r.ok) {
+    console.log("[xera:lint] ok");
+    return 0;
+  }
+  for (const w of r.warnings)
+    console.error(`[xera:lint] ${w.file}:${w.line} [${w.rule}] ${w.message}`);
+  return 2;
+}
+
+// src/lock/file-lock.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync4, unlinkSync, mkdirSync as mkdirSync4 } from "fs";
+import { dirname as dirname3 } from "path";
+import { hostname } from "os";
+function acquireLock(path, runId) {
+  if (existsSync6(path))
+    return false;
+  mkdirSync4(dirname3(path), { recursive: true });
+  const data = {
+    pid: process.pid,
+    hostname: hostname(),
+    started_at: new Date().toISOString(),
+    run_id: runId
+  };
+  try {
+    writeFileSync4(path, JSON.stringify(data), { flag: "wx" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function releaseLock(path) {
+  if (existsSync6(path))
+    unlinkSync(path);
+}
+function readLock(path) {
+  if (!existsSync6(path))
+    return null;
+  return JSON.parse(readFileSync5(path, "utf8"));
+}
+function isLockStale(path) {
+  const lock = readLock(path);
+  if (!lock)
+    return true;
+  if (lock.hostname !== hostname()) {
+    return false;
+  }
+  try {
+    process.kill(lock.pid, 0);
+    return false;
+  } catch {
+    return true;
+  }
+}
+function forceUnlock(path) {
+  releaseLock(path);
+}
+
+// src/logging/ndjson-logger.ts
+import { appendFileSync, mkdirSync as mkdirSync5, existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
+import { dirname as dirname4 } from "path";
+
+class NdjsonLogger {
+  path;
+  constructor(path) {
+    this.path = path;
+    mkdirSync5(dirname4(path), { recursive: true });
+  }
+  log(payload) {
+    const entry = { ts: new Date().toISOString(), ...payload };
+    appendFileSync(this.path, `${JSON.stringify(entry)}
+`);
+  }
+  static readAll(path) {
+    if (!existsSync7(path))
+      return [];
+    const txt = readFileSync6(path, "utf8").trim();
+    if (!txt)
+      return [];
+    return txt.split(`
+`).map((line) => JSON.parse(line));
+  }
+}
+
+// src/auth/state.ts
+import { existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync5, mkdirSync as mkdirSync6 } from "fs";
+import { join as join4 } from "path";
+import { z as z3 } from "zod";
+
+// src/auth/encrypt.ts
+import { randomBytes, createCipheriv, createDecipheriv } from "crypto";
+var ALGO = "aes-256-gcm";
+var KEY_LEN = 32;
+var IV_LEN = 12;
+var TAG_LEN = 16;
+var VERSION = "v1";
+function generateKey() {
+  return randomBytes(KEY_LEN).toString("hex");
+}
+function keyToBuf(key) {
+  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;
+}
+function encrypt(plaintext, keyHex) {
+  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")}`;
+}
+function decrypt(ciphertext, keyHex) {
+  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");
+}
+
+// src/auth/key.ts
+var AUTH_KEY_ENV = "XERA_AUTH_KEY";
+function resolveAuthKey() {
+  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\` \u2014 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;
+}
+
+// src/auth/state.ts
+var AuthStateEntrySchema = z3.object({
+  role: z3.string(),
+  strategy: z3.enum(["storageState", "apiToken"]),
+  created_at: z3.string(),
+  expires_at: z3.string(),
+  payload: z3.record(z3.string(), z3.unknown())
+});
+function pathFor(authDir, role) {
+  return join4(authDir, `${role}.json`);
+}
+function writeAuthState(authDir, entry) {
+  mkdirSync6(authDir, { recursive: true });
+  const ct = encrypt(JSON.stringify(entry), resolveAuthKey());
+  writeFileSync5(pathFor(authDir, entry.role), ct);
+}
+function readAuthState(authDir, role) {
+  const p = pathFor(authDir, role);
+  if (!existsSync8(p))
+    return null;
+  const txt = readFileSync7(p, "utf8");
+  const plain = decrypt(txt, resolveAuthKey());
+  return AuthStateEntrySchema.parse(JSON.parse(plain));
+}
+
+// src/auth/refresh.ts
+var RE = /^(\d+)([hms])$/;
+function parseDuration(d) {
+  const m = RE.exec(d);
+  if (!m)
+    throw new Error(`Bad duration "${d}" \u2014 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;
+}
+function needsRefresh(entry, policy, now = new Date) {
+  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;
+}
+
+// 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 { join as join5 } from "path";
+async function execCmd(argv) {
+  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);
+  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 {
+    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: join5(cwd, config.web.auth.setupScript),
+              authDir: paths.authDir,
+              browser
+            });
+            log.log({ step: "auth-refresh", role: roleName });
+          }
+        }
+      } finally {
+        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);
+        }
+      }
+    }
+    const cfgPath = join5(paths.ticketDir, "playwright.config.ts");
+    if (!existsSync9(cfgPath)) {
+      writeFileSync6(cfgPath, renderPlaywrightConfig({
+        baseUrl: config.web.baseUrl[config.web.defaultEnv],
+        storageStatePathPerRole: stagedRoles
+      }));
+    }
+    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 });
+    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;
+  } finally {
+    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";
+import { readdirSync, existsSync as existsSync10 } from "fs";
+import { join as join6 } from "path";
+async function normalizeCmd(argv) {
+  const ticket = argv[0];
+  if (!ticket) {
+    console.error("[xera:normalize] usage: normalize <TICKET> [--run=<runId>]");
+    return 1;
+  }
+  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  const runArg = argv.find((a) => a.startsWith("--run="));
+  const runId = runArg ? runArg.split("=")[1] : readdirSync(paths.runsDir).filter((n) => !n.startsWith(".")).sort().pop();
+  if (!runId) {
+    console.error("[xera:normalize] no run found");
+    return 1;
+  }
+  const runDir = join6(paths.runsDir, runId);
+  if (!existsSync10(runDir)) {
+    console.error(`[xera:normalize] runs/${runId} missing`);
+    return 1;
+  }
+  const r = await normalizeRun({ runId, runDir });
+  console.log(`[xera:normalize] wrote normalized.json (scrubbed_fields_count=${r.scrubbed_fields_count})`);
+  return 0;
+}
+
+// src/bin-internal/report.ts
+import { readFileSync as readFileSync9, writeFileSync as writeFileSync8 } from "fs";
+import { join as join7 } from "path";
+
+// src/classifier/aggregate.ts
+var CLASS_PRIORITY = [
+  "REAL_BUG",
+  "TEST_BUG",
+  "SELECTOR_DRIFT",
+  "FLAKY",
+  "PASS"
+];
+var CONF_RANK = { low: 1, medium: 2, high: 3 };
+function aggregateScenarios(scenarios) {
+  if (scenarios.length === 0) {
+    return { overall: "PASS", overallConfidence: "low", scenarios: [] };
+  }
+  if (scenarios.every((s) => s.outcome === "PASS")) {
+    return { overall: "PASS", overallConfidence: "high", scenarios };
+  }
+  let chosen = "PASS";
+  for (const cls of CLASS_PRIORITY) {
+    if (scenarios.some((s) => s.class === cls)) {
+      chosen = cls;
+      break;
+    }
+  }
+  const matching = scenarios.filter((s) => s.class === chosen);
+  const minConf = matching.reduce((acc, s) => CONF_RANK[s.confidence] < CONF_RANK[acc] ? s.confidence : acc, "high");
+  return { overall: chosen, overallConfidence: minConf, scenarios };
+}
+
+// src/reporter/status-writer.ts
+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 { dirname as dirname5 } from "path";
+import { z as z4 } from "zod";
+var ClassificationEnum = z4.enum(["PASS", "REAL_BUG", "SELECTOR_DRIFT", "FLAKY", "TEST_BUG"]);
+var ResultEnum = z4.enum(["PASS", "FAIL"]);
+var ConfidenceEnum = z4.enum(["low", "medium", "high"]);
+var HistoryEntrySchema = z4.object({
+  ts: z4.string(),
+  result: ResultEnum,
+  class: ClassificationEnum
+});
+var StatusJsonSchema = z4.object({
+  ticket: z4.string(),
+  lastRun: z4.string(),
+  result: ResultEnum,
+  classification: ClassificationEnum,
+  confidence: ConfidenceEnum,
+  scenarios: z4.object({
+    total: z4.number().int().nonnegative(),
+    passed: z4.number().int().nonnegative(),
+    failed: z4.number().int().nonnegative(),
+    skipped: z4.number().int().nonnegative()
+  }),
+  history: z4.array(HistoryEntrySchema).default([]),
+  last_jira_comment_id: z4.string().optional()
+});
+var HISTORY_CAP = 20;
+function readStatus(path) {
+  if (!existsSync11(path))
+    return null;
+  return StatusJsonSchema.parse(JSON.parse(readFileSync8(path, "utf8")));
+}
+function writeStatus(path, status) {
+  mkdirSync8(dirname5(path), { recursive: true });
+  writeFileSync7(path, JSON.stringify(status, null, 2));
+}
+function appendHistory(path, entry) {
+  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;
+}
+
+// src/reporter/status-writer.ts
+function writeStatusFromClassification(path, input) {
+  const result = input.classification.overall === "PASS" ? "PASS" : "FAIL";
+  const entry = { ts: input.runTs, result, class: input.classification.overall };
+  if (!existsSync12(path)) {
+    writeStatus(path, {
+      ticket: input.ticket,
+      lastRun: input.runTs,
+      result,
+      classification: input.classification.overall,
+      confidence: input.classification.overallConfidence,
+      scenarios: input.scenarioCounts,
+      history: [entry]
+    });
+    return;
+  }
+  const cur = readStatus(path);
+  writeStatus(path, {
+    ...cur,
+    lastRun: input.runTs,
+    result,
+    classification: input.classification.overall,
+    confidence: input.classification.overallConfidence,
+    scenarios: input.scenarioCounts
+  });
+  appendHistory(path, entry);
+}
+
+// src/reporter/jira-comment.ts
+function buildJiraComment(input) {
+  const passed = input.scenarios.filter((s) => s.outcome === "PASS").length;
+  const total = input.scenarios.length;
+  const icon = input.overall === "PASS" ? "\uD83D\uDFE2" : "\uD83D\uDD34";
+  const header = `## ${icon} xera test ${input.overall === "PASS" ? "PASSED" : "FAILED"} \u2014 ${input.ticket} (run ${input.runId})`;
+  const meta = `**Classification:** ${input.overall} (confidence: ${input.overallConfidence})
+**Scenarios:** ${passed} / ${total} passed`;
+  const failingBlocks = input.scenarios.filter((s) => s.outcome === "FAIL").map((s) => `### Scenario: ${s.name}
+- **Classification:** ${s.class} (confidence: ${s.confidence})
+- **Diagnosis:** ${s.rationale}`).join(`
+
+`);
+  const reproduce = `### Reproduce locally
+
+\`\`\`
+bunx xera-internal exec ${input.ticket} --replay=${input.runId}
+\`\`\``;
+  const next = input.overall === "PASS" ? "" : `### Suggested next action
+- Review the failing scenarios above.
+- Re-run after changes: open Claude Code and run \`/xera-run ${input.ticket}\`.
+
+`;
+  const footer = `---
+xera v${input.xeraVersion} \u2022 prompts v${input.promptsVersion}`;
+  return [header, "", meta, "", failingBlocks, "", next, reproduce, "", footer].filter(Boolean).join(`
+`);
+}
+
+// src/bin-internal/report.ts
+async function reportCmd(argv) {
+  const ticket = argv[0];
+  const inputArg = argv.find((a) => a.startsWith("--input="));
+  if (!ticket || !inputArg) {
+    console.error("[xera:report] usage: report <TICKET> --input=<classifier-output.json>");
+    return 1;
+  }
+  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  const input = JSON.parse(readFileSync9(inputArg.slice("--input=".length), "utf8"));
+  const aggregated = aggregateScenarios(input.scenarios);
+  const ts = new Date().toISOString();
+  writeStatusFromClassification(paths.statusPath, {
+    ticket,
+    runTs: ts,
+    classification: aggregated,
+    scenarioCounts: input.scenarioCounts
+  });
+  const md = buildJiraComment({
+    ticket,
+    runId: input.runId,
+    overall: aggregated.overall,
+    overallConfidence: aggregated.overallConfidence,
+    scenarios: aggregated.scenarios,
+    xeraVersion: "0.1.0",
+    promptsVersion: "1.0.0"
+  });
+  const draftPath = join7(paths.ticketDir, "jira-comment.draft.md");
+  writeFileSync8(draftPath, md);
+  console.log(`[xera:report] wrote status.json and ${draftPath}`);
+  return 0;
+}
+
+// src/bin-internal/post.ts
+import { readFileSync as readFileSync10, existsSync as existsSync13 } from "fs";
+import { join as join8 } from "path";
+async function postCmd(argv) {
+  const ticket = argv[0];
+  if (!ticket) {
+    console.error("[xera:post] usage: post <TICKET>");
+    return 1;
+  }
+  const cwd = process.cwd();
+  const config = await loadConfig(cwd);
+  if (!config.reporting.postToJira) {
+    console.log("[xera:post] postToJira disabled in config; skipping");
+    return 0;
+  }
+  const paths = resolveArtifactPaths(cwd, ticket);
+  const draftPath = join8(paths.ticketDir, "jira-comment.draft.md");
+  if (!existsSync13(draftPath)) {
+    console.error(`[xera:post] no draft at ${draftPath}; run \`xera-internal report\` first.`);
+    return 1;
+  }
+  const body = readFileSync10(draftPath, "utf8");
+  const client = await createJiraClient({
+    baseUrl: config.jira.baseUrl,
+    preferMcp: true,
+    ...process.env.JIRA_EMAIL && process.env.JIRA_API_TOKEN ? { rest: { email: process.env.JIRA_EMAIL, apiToken: process.env.JIRA_API_TOKEN } } : {}
+  });
+  const r = await client.postComment(ticket, body);
+  console.log(`[xera:post] posted comment id=${r.id}`);
+  const s = readStatus(paths.statusPath);
+  if (s)
+    writeStatus(paths.statusPath, { ...s, last_jira_comment_id: r.id });
+  return 0;
+}
+
+// src/bin-internal/status-cmd.ts
+async function statusCmd(argv) {
+  const ticket = argv[0];
+  if (!ticket) {
+    console.error("[xera:status] usage: status <TICKET>");
+    return 1;
+  }
+  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  const s = readStatus(paths.statusPath);
+  if (!s) {
+    console.log(`[xera:status] no status yet for ${ticket}`);
+    return 0;
+  }
+  console.log(`${ticket}: ${s.result} (${s.classification}, conf=${s.confidence}) \u2014 ${s.scenarios.passed}/${s.scenarios.total} passed, last run ${s.lastRun}`);
+  for (const h of s.history.slice(0, 5))
+    console.log(`  ${h.ts}  ${h.result}  ${h.class}`);
+  return 0;
+}
+
+// src/bin-internal/unlock.ts
+async function unlockCmd(argv) {
+  const ticket = argv[0];
+  if (!ticket) {
+    console.error("[xera:unlock] usage: unlock <TICKET> [--force]");
+    return 1;
+  }
+  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  const lock = readLock(paths.lockPath);
+  if (!lock) {
+    console.log(`[xera:unlock] no lock for ${ticket}`);
+    return 0;
+  }
+  const force = argv.includes("--force");
+  if (!force && !isLockStale(paths.lockPath)) {
+    console.error(`[xera:unlock] lock is held by PID ${lock.pid} on ${lock.hostname} (active). Pass --force to override.`);
+    return 1;
+  }
+  forceUnlock(paths.lockPath);
+  console.log(`[xera:unlock] released`);
+  return 0;
+}
+
+// src/bin-internal/promote.ts
+import { promotePom } from "@xera-ai/web";
+async function promoteCmd(argv) {
+  const [ticket, className] = argv;
+  if (!ticket || !className) {
+    console.error("[xera:promote] usage: promote <TICKET> <PomClassName>");
+    return 1;
+  }
+  await promotePom({ repoRoot: process.cwd(), ticket, className });
+  console.log(`[xera:promote] moved ${className} \u2192 shared/page-objects/`);
+  return 0;
+}
+
+// src/bin-internal/index.ts
+var COMMANDS = {
+  fetch: fetchCmd,
+  "validate-feature": validateFeatureCmd,
+  typecheck: typecheckCmd,
+  lint: lintCmd,
+  exec: execCmd,
+  normalize: normalizeCmd,
+  report: reportCmd,
+  post: postCmd,
+  status: statusCmd,
+  unlock: unlockCmd,
+  promote: promoteCmd
+};
+async function run(argv) {
+  const [cmd, ...rest] = argv;
+  if (!cmd || !COMMANDS[cmd]) {
+    console.error(`Usage: xera-internal <command> [args...]
+Commands: ${Object.keys(COMMANDS).join(", ")}`);
+    return 1;
+  }
+  try {
+    return await COMMANDS[cmd](rest);
+  } catch (err) {
+    console.error(`[xera:${cmd}] failed: ${err.message}`);
+    return 4;
+  }
+}
+
+// bin/internal.ts
+var code = await run(process.argv.slice(2));
+process.exit(code);