@xera-ai/core 0.1.3 → 0.1.5

package/src/bin-internal/promote.ts

@@ -0,0 +1,12 @@
+import { promotePom } from '@xera-ai/web';
+
+export async function promoteCmd(argv: string[]): Promise<number> {
+  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} → shared/page-objects/`);
+  return 0;
+}

package/src/bin-internal/report.ts

@@ -0,0 +1,47 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveArtifactPaths } from '../artifact/paths';
+import { aggregateScenarios } from '../classifier/aggregate';
+import { writeStatusFromClassification } from '../reporter/status-writer';
+import { buildJiraComment } from '../reporter/jira-comment';
+import type { ScenarioClassification } from '../classifier/types';
+
+interface ReportInput {
+  scenarios: ScenarioClassification[];
+  scenarioCounts: { total: number; passed: number; failed: number; skipped: number };
+  runId: string;
+}
+
+export async function reportCmd(argv: string[]): Promise<number> {
+  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(readFileSync(inputArg.slice('--input='.length), 'utf8')) as ReportInput;
+
+  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 = join(paths.ticketDir, 'jira-comment.draft.md');
+  writeFileSync(draftPath, md);
+  console.log(`[xera:report] wrote status.json and ${draftPath}`);
+  return 0;
+}

package/src/bin-internal/status-cmd.ts

@@ -0,0 +1,13 @@
+import { resolveArtifactPaths } from '../artifact/paths';
+import { readStatus } from '../artifact/status';
+
+export async function statusCmd(argv: string[]): Promise<number> {
+  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}) — ${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;
+}

package/src/bin-internal/typecheck.ts

@@ -0,0 +1,12 @@
+import { resolveArtifactPaths } from '../artifact/paths';
+import { typecheckTicket } from '@xera-ai/web';
+
+export async function typecheckCmd(argv: string[]): Promise<number> {
+  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;
+}

package/src/bin-internal/unlock.ts

@@ -0,0 +1,18 @@
+import { resolveArtifactPaths } from '../artifact/paths';
+import { isLockStale, readLock, forceUnlock } from '../lock/file-lock';
+
+export async function unlockCmd(argv: string[]): Promise<number> {
+  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;
+}

package/src/bin-internal/validate-feature.ts

@@ -0,0 +1,14 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolveArtifactPaths } from '../artifact/paths';
+import { validateGherkin } from '@xera-ai/web';
+
+export async function validateFeatureCmd(argv: string[]): Promise<number> {
+  const ticket = argv[0];
+  if (!ticket) { console.error('[xera:validate-feature] usage: validate-feature <TICKET>'); return 1; }
+  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  if (!existsSync(paths.featurePath)) { console.error(`[xera:validate-feature] missing ${paths.featurePath}`); return 1; }
+  const r = validateGherkin(readFileSync(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;
+}

package/src/classifier/aggregate.ts

@@ -0,0 +1,26 @@
+import type { ClassifyOutput, ScenarioClassification, Confidence } from './types';
+
+const CLASS_PRIORITY: Array<ClassifyOutput['overall']> = [
+  'REAL_BUG', 'TEST_BUG', 'SELECTOR_DRIFT', 'FLAKY', 'PASS',
+];
+
+const CONF_RANK: Record<Confidence, number> = { low: 1, medium: 2, high: 3 };
+
+export function aggregateScenarios(scenarios: ScenarioClassification[]): ClassifyOutput {
+  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: ClassifyOutput['overall'] = '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<Confidence>(
+    (acc, s) => CONF_RANK[s.confidence] < CONF_RANK[acc] ? s.confidence : acc,
+    'high',
+  );
+  return { overall: chosen, overallConfidence: minConf, scenarios };
+}

package/src/classifier/history.ts

@@ -0,0 +1,27 @@
+import type { Classification } from '../artifact/status';
+
+export interface HistorySummary {
+  firstRun: boolean;
+  consecutiveFails: number;
+  lastResult: 'PASS' | 'FAIL' | null;
+  lastClass: Classification | null;
+}
+
+export function summarizeHistory(
+  history: Array<{ ts: string; result: 'PASS' | 'FAIL'; class: Classification }>,
+): HistorySummary {
+  if (history.length === 0) {
+    return { firstRun: true, consecutiveFails: 0, lastResult: null, lastClass: null };
+  }
+  let consecutiveFails = 0;
+  for (const entry of history) {
+    if (entry.result === 'FAIL') consecutiveFails++;
+    else break;
+  }
+  return {
+    firstRun: false,
+    consecutiveFails,
+    lastResult: history[0]!.result,
+    lastClass: history[0]!.class,
+  };
+}

package/src/classifier/types.ts

@@ -0,0 +1,25 @@
+import type { Classification } from '../artifact/status';
+
+export type { Classification };
+export type Confidence = 'low' | 'medium' | 'high';
+
+export interface ScenarioClassification {
+  name: string;
+  outcome: 'PASS' | 'FAIL' | 'SKIPPED';
+  class: Classification;
+  confidence: Confidence;
+  rationale: string;
+}
+
+export interface ClassifyOutput {
+  overall: Classification;
+  overallConfidence: Confidence;
+  scenarios: ScenarioClassification[];
+}
+
+export interface ClassifyContextInput {
+  history: Array<{ ts: string; result: 'PASS' | 'FAIL'; class: Classification }>;
+  storyHashChanged: boolean;
+  specHashChanged: boolean;
+  firstRun: boolean;
+}

package/src/config/define.ts

@@ -0,0 +1,2 @@
+import type { XeraConfig } from './schema';
+export function defineConfig(config: XeraConfig): XeraConfig { return config; }

package/src/config/load.ts

@@ -0,0 +1,14 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { XeraConfigSchema, type XeraConfig } from './schema';
+
+export async function loadConfig(cwd: string): Promise<XeraConfig> {
+  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);
+}

package/src/config/schema.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+
+const AuthRoleSchema = z.object({
+  envEmail: z.string().min(1),
+  envPassword: z.string().min(1),
+});
+
+const 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({}),
+});
+
+const 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'],
+});
+
+const 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'),
+  }),
+});
+
+const 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({});
+
+const 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({});
+
+export const XeraConfigSchema = z.object({
+  jira: JiraSchema,
+  web: WebSchema,
+  ai: AISchema,
+  reporting: ReportingSchema,
+  adapters: z.array(z.string().min(1)).min(1).default(['web']),
+});
+
+export type XeraConfig = z.infer<typeof XeraConfigSchema>;

package/src/index.ts

@@ -0,0 +1,19 @@
+export const VERSION = '0.1.0';
+export type * from './adapter/types';
+export * from './config/schema';
+export * from './config/define';
+export * from './config/load';
+export * from './artifact/paths';
+export * from './artifact/hash';
+export * from './artifact/meta';
+export * from './artifact/status';
+export * from './logging/ndjson-logger';
+export * from './lock/file-lock';
+export * from './jira/types';
+export * from './jira/client';
+export * from './jira/fields';
+export * from './jira/retry';
+export * from './auth/encrypt';
+export * from './auth/key';
+export * from './auth/state';
+export * from './auth/refresh';

package/src/jira/client.ts

@@ -0,0 +1,20 @@
+import type { JiraClient } from './types';
+import { createMcpBackend } from './mcp-backend';
+import { createRestBackend } from './rest-backend';
+
+export interface CreateJiraClientOptions {
+  baseUrl: string;
+  preferMcp?: boolean;
+  rest?: { email: string; apiToken: string };
+}
+
+export async function createJiraClient(opts: CreateJiraClientOptions): Promise<JiraClient> {
+  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);
+}

package/src/jira/fields.ts

@@ -0,0 +1,21 @@
+const PREFERRED_STORY_IDS = ['description', 'story'];
+
+export interface JiraFieldInfo {
+  id: string;
+  name: string;
+  hasContent: boolean;
+}
+
+export function rankStoryCandidates(fields: JiraFieldInfo[]): JiraFieldInfo[] {
+  return fields
+    .filter(f => f.hasContent)
+    .filter(f => !['attachment', 'comment', 'created', 'updated', 'reporter', 'creator'].includes(f.id))
+    .sort((a, b) => {
+      const ai = PREFERRED_STORY_IDS.indexOf(a.id);
+      const bi = PREFERRED_STORY_IDS.indexOf(b.id);
+      if (ai >= 0 && bi >= 0) return ai - bi;
+      if (ai >= 0) return -1;
+      if (bi >= 0) return 1;
+      return a.id.localeCompare(b.id);
+    });
+}

package/src/jira/mcp-backend.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { JiraClient, JiraTicket } from './types';
+
+const MCP_ENV = 'XERA_MCP_JIRA';
+
+export async function createMcpBackend(_baseUrl: string): Promise<JiraClient | null> {
+  if (process.env[MCP_ENV] !== '1') return null;
+  const tmpDir = join(tmpdir(), 'xera-mcp');
+  mkdirSync(tmpDir, { recursive: true });
+
+  return {
+    backend: 'mcp',
+    async fetchTicket(key, _fields): Promise<JiraTicket> {
+      const cachePath = join(tmpDir, `${key}.json`);
+      if (!existsSync(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(readFileSync(cachePath, 'utf8')) as JiraTicket;
+      return parsed;
+    },
+    async postComment(key, body) {
+      const outPath = join(tmpDir, `${key}.comment.json`);
+      writeFileSync(outPath, JSON.stringify({ key, body }));
+      // The skill will read this file and call mcp__atlassian__addCommentToJiraIssue.
+      return { id: 'mcp-pending' };
+    },
+    async transitionStatus(key, statusName) {
+      const outPath = join(tmpDir, `${key}.transition.json`);
+      writeFileSync(outPath, JSON.stringify({ key, statusName }));
+    },
+    async listFields(_sampleKey) {
+      throw new Error('listFields is REST-only; init flow uses REST for field discovery.');
+    },
+  };
+}

package/src/jira/rest-backend.ts

@@ -0,0 +1,79 @@
+import type { JiraClient, JiraFieldMap, JiraTicket } from './types';
+
+interface RestCreds { email: string; apiToken: string; }
+
+export function createRestBackend(baseUrl: string, creds: RestCreds): JiraClient {
+  const authHeader = `Basic ${Buffer.from(`${creds.email}:${creds.apiToken}`).toString('base64')}`;
+  const base = baseUrl.replace(/\/$/, '');
+
+  async function req(path: string, init?: RequestInit): Promise<Response> {
+    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): Promise<JiraTicket> {
+      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()) as { key: string; fields: Record<string, unknown> };
+      const f = json.fields;
+      const attachments = Array.isArray(f.attachment)
+        ? (f.attachment as Array<{ filename: string; content: string }>).map(a => ({ filename: a.filename, url: a.content }))
+        : [];
+      const ticket: JiraTicket = {
+        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()) as { id: string };
+      return { id: json.id };
+    },
+    async transitionStatus(key, statusName) {
+      const tr = await req(`/rest/api/3/issue/${encodeURIComponent(key)}/transitions`);
+      const json = (await tr.json()) as { transitions: Array<{ id: string; name: string }> };
+      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()) as { fields: Record<string, unknown> };
+      return Object.entries(json.fields).map(([id, value]) => ({
+        id,
+        name: id,
+        hasContent: value !== null && value !== undefined && value !== '',
+      }));
+    },
+  };
+}

package/src/jira/retry.ts

@@ -0,0 +1,24 @@
+export interface RetryOptions {
+  maxAttempts: number;
+  baseMs: number;
+  factor: number;
+  shouldRetry?: (err: unknown) => boolean;
+}
+
+export async function withRetry<T>(fn: () => Promise<T>, opts: RetryOptions): Promise<T> {
+  let attempt = 0;
+  let lastErr: unknown;
+  while (attempt < opts.maxAttempts) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (opts.shouldRetry && !opts.shouldRetry(err)) throw err;
+      attempt++;
+      if (attempt >= opts.maxAttempts) break;
+      const delay = opts.baseMs * Math.pow(opts.factor, attempt - 1);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw lastErr;
+}

package/src/jira/types.ts

@@ -0,0 +1,21 @@
+export interface JiraTicket {
+  key: string;
+  summary: string;
+  story: string;
+  acceptanceCriteria?: string;
+  attachments: Array<{ filename: string; url: string }>;
+  raw: Record<string, unknown>;
+}
+
+export interface JiraFieldMap {
+  story: string;
+  acceptanceCriteria?: string;
+}
+
+export interface JiraClient {
+  readonly backend: 'mcp' | 'rest';
+  fetchTicket(key: string, fields: JiraFieldMap): Promise<JiraTicket>;
+  postComment(key: string, body: string): Promise<{ id: string }>;
+  transitionStatus(key: string, statusName: string): Promise<void>;
+  listFields(sampleKey: string): Promise<Array<{ id: string; name: string; hasContent: boolean }>>;
+}

package/src/lock/file-lock.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { hostname } from 'node:os';
+
+export interface LockData {
+  pid: number;
+  hostname: string;
+  started_at: string;
+  run_id: string;
+}
+
+export function acquireLock(path: string, runId: string): boolean {
+  if (existsSync(path)) return false;
+  mkdirSync(dirname(path), { recursive: true });
+  const data: LockData = {
+    pid: process.pid,
+    hostname: hostname(),
+    started_at: new Date().toISOString(),
+    run_id: runId,
+  };
+  // Use 'wx' flag for atomic-ish create-only.
+  try {
+    writeFileSync(path, JSON.stringify(data), { flag: 'wx' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function releaseLock(path: string): void {
+  if (existsSync(path)) unlinkSync(path);
+}
+
+export function readLock(path: string): LockData | null {
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8')) as LockData;
+}
+
+export function isLockStale(path: string): boolean {
+  const lock = readLock(path);
+  if (!lock) return true;
+  if (lock.hostname !== hostname()) {
+    // Cannot verify a remote PID; treat as not stale.
+    return false;
+  }
+  try {
+    // Signal 0 = "check if process exists". Throws if not.
+    process.kill(lock.pid, 0);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+export function forceUnlock(path: string): void {
+  releaseLock(path);
+}

package/src/logging/ndjson-logger.ts

@@ -0,0 +1,25 @@
+import { appendFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface LogEntry {
+  ts: string;
+  [key: string]: unknown;
+}
+
+export class NdjsonLogger {
+  constructor(private readonly path: string) {
+    mkdirSync(dirname(path), { recursive: true });
+  }
+
+  log(payload: Record<string, unknown>): void {
+    const entry: LogEntry = { ts: new Date().toISOString(), ...payload };
+    appendFileSync(this.path, `${JSON.stringify(entry)}\n`);
+  }
+
+  static readAll(path: string): LogEntry[] {
+    if (!existsSync(path)) return [];
+    const txt = readFileSync(path, 'utf8').trim();
+    if (!txt) return [];
+    return txt.split('\n').map(line => JSON.parse(line) as LogEntry);
+  }
+}

package/src/reporter/jira-comment.ts

@@ -0,0 +1,31 @@
+import type { ClassifyOutput } from '../classifier/types';
+
+export interface JiraCommentInput extends ClassifyOutput {
+  ticket: string;
+  runId: string;
+  xeraVersion: string;
+  promptsVersion: string;
+}
+
+export function buildJiraComment(input: JiraCommentInput): string {
+  const passed = input.scenarios.filter(s => s.outcome === 'PASS').length;
+  const total = input.scenarios.length;
+  const icon = input.overall === 'PASS' ? '🟢' : '🔴';
+  const header = `## ${icon} xera test ${input.overall === 'PASS' ? 'PASSED' : 'FAILED'} — ${input.ticket} (run ${input.runId})`;
+  const meta = `**Classification:** ${input.overall} (confidence: ${input.overallConfidence})\n**Scenarios:** ${passed} / ${total} passed`;
+
+  const failingBlocks = input.scenarios
+    .filter(s => s.outcome === 'FAIL')
+    .map(s => `### Scenario: ${s.name}\n- **Classification:** ${s.class} (confidence: ${s.confidence})\n- **Diagnosis:** ${s.rationale}`)
+    .join('\n\n');
+
+  const reproduce = `### Reproduce locally\n\n\`\`\`\nbunx xera-internal exec ${input.ticket} --replay=${input.runId}\n\`\`\``;
+
+  const next = input.overall === 'PASS'
+    ? ''
+    : `### Suggested next action\n- Review the failing scenarios above.\n- Re-run after changes: open Claude Code and run \`/xera-run ${input.ticket}\`.\n\n`;
+
+  const footer = `---\nxera v${input.xeraVersion} • prompts v${input.promptsVersion}`;
+
+  return [header, '', meta, '', failingBlocks, '', next, reproduce, '', footer].filter(Boolean).join('\n');
+}