@xera-ai/core 0.1.4 → 0.1.6

package/src/bin-internal/fetch.ts

@@ -0,0 +1,84 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadConfig } from '../config/load';
+import { resolveArtifactPaths } from '../artifact/paths';
+import { hashString } from '../artifact/hash';
+import { writeMeta, readMeta } from '../artifact/meta';
+import { createJiraClient } from '../jira/client';
+import type { JiraTicket } from '../jira/types';
+
+export interface FetchCmdOpts { cwd?: string; }
+
+export async function fetchCmd(argv: string[], opts: FetchCmdOpts = {}): Promise<number> {
+  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);
+
+  // Test injection: skip real Jira when XERA_TEST_JIRA env is set.
+  let t: JiraTicket;
+  if (process.env.XERA_TEST_JIRA) {
+    t = JSON.parse(process.env.XERA_TEST_JIRA) as JiraTicket;
+  } 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);
+  mkdirSync(dirname(paths.storyPath), { recursive: true });
+  writeFileSync(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 ?? {}),
+    // Re-stamp the just-fetched fields:
+    story_hash: hashString(story),
+    fetched_at: new Date().toISOString(),
+  });
+
+  console.log(`[xera:fetch] wrote ${paths.storyPath}`);
+  return 0;
+}
+
+function renderStory(t: JiraTicket): string {
+  const lines: string[] = [];
+  lines.push(`# ${t.key}: ${t.summary}`, '');
+
+  const story = t.story.trim();
+  // Avoid double "## Story" heading when Jira description already starts with it.
+  if (/^##\s+story\b/i.test(story)) {
+    lines.push(story, '');
+  } else {
+    lines.push('## Story', '', story, '');
+  }
+
+  if (t.acceptanceCriteria && 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})`), '');
+  }
+  return lines.join('\n');
+}

package/src/bin-internal/index.ts

@@ -0,0 +1,39 @@
+import { fetchCmd } from './fetch';
+import { validateFeatureCmd } from './validate-feature';
+import { typecheckCmd } from './typecheck';
+import { lintCmd } from './lint';
+import { execCmd } from './exec';
+import { normalizeCmd } from './normalize';
+import { reportCmd } from './report';
+import { postCmd } from './post';
+import { statusCmd } from './status-cmd';
+import { unlockCmd } from './unlock';
+import { promoteCmd } from './promote';
+
+const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
+  fetch: fetchCmd,
+  'validate-feature': validateFeatureCmd,
+  typecheck: typecheckCmd,
+  lint: lintCmd,
+  exec: execCmd,
+  normalize: normalizeCmd,
+  report: reportCmd,
+  post: postCmd,
+  status: statusCmd,
+  unlock: unlockCmd,
+  promote: promoteCmd,
+};
+
+export async function run(argv: string[]): Promise<number> {
+  const [cmd, ...rest] = argv;
+  if (!cmd || !COMMANDS[cmd]) {
+    console.error(`Usage: xera-internal <command> [args...]\nCommands: ${Object.keys(COMMANDS).join(', ')}`);
+    return 1;
+  }
+  try {
+    return await COMMANDS[cmd]!(rest);
+  } catch (err) {
+    console.error(`[xera:${cmd}] failed: ${(err as Error).message}`);
+    return 4;
+  }
+}

package/src/bin-internal/lint.ts

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

package/src/bin-internal/normalize.ts

@@ -0,0 +1,20 @@
+import { resolveArtifactPaths } from '../artifact/paths';
+import { normalizeRun } from '@xera-ai/web';
+import { readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export async function normalizeCmd(argv: string[]): Promise<number> {
+  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 = join(paths.runsDir, runId);
+  if (!existsSync(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;
+}

package/src/bin-internal/post.ts

@@ -0,0 +1,35 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveArtifactPaths } from '../artifact/paths';
+import { loadConfig } from '../config/load';
+import { readStatus, writeStatus } from '../artifact/status';
+import { createJiraClient } from '../jira/client';
+
+export async function postCmd(argv: string[]): Promise<number> {
+  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 = join(paths.ticketDir, 'jira-comment.draft.md');
+  if (!existsSync(draftPath)) { console.error(`[xera:post] no draft at ${draftPath}; run \`xera-internal report\` first.`); return 1; }
+  const body = readFileSync(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;
+}

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.');
+    },
+  };
+}