levante 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "levante",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "levante": "./dist/cli.js",
+    "levante-mcp": "./dist/mcp.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/schema.d.ts",
+      "import": "./dist/config/schema.js"
+    }
+  },
+  "files": ["dist/", "agents/", "scripts/", "templates/"],
+  "scripts": {
+    "build": "bun build src/cli.ts src/index.ts src/config/schema.ts src/mcp.ts --outdir dist --target node --format esm --splitting",
+    "dev": "bun run src/cli.ts"
+  },
+  "dependencies": {
+    "@qai/types": "workspace:*",
+    "@inquirer/prompts": "^8.3.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "commander": "^13.1.0",
+    "dotenv": "^17.2.0",
+    "glob": "^13.0.6",
+    "ora": "^9.3.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.7.1",
+    "zod": "^4.0.5"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.14",
+    "typescript": "^5.8.3"
+  }
+}

package/scripts/auth/setup-auth.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * TEMPLATE: Authenticate a user and save the storage state for reuse by codegen and trace replay.
+ * Uses the Playwright API directly to perform a username/password login flow.
+ *
+ * This is a reference implementation — adapt the authenticate() function below to match
+ * your application's login flow (e.g., different form fields, OAuth redirects, SSO).
+ *
+ * Usage:
+ *   node scripts/auth/setup-auth.mjs                          # single resource (default)
+ *   node scripts/auth/setup-auth.mjs --multi                  # multi resource
+ *   node scripts/auth/setup-auth.mjs --output .auth/custom.json
+ *
+ * Credentials come from .env (USERNAME/PASSWORD or MULTI_RESOURCE_USERNAME/PASSWORD).
+ * Storage state is saved to .auth/codegen.json by default.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = process.env.E2E_AI_PROJECT_ROOT || resolve(__dirname, '..', '..');
+
+function loadEnv() {
+  const envPath = resolve(root, '.env');
+  if (!existsSync(envPath)) return;
+  const content = readFileSync(envPath, 'utf-8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed
+      .slice(eq + 1)
+      .trim()
+      .replace(/^["']|["']$/g, '');
+    if (!process.env[key]) process.env[key] = value;
+  }
+}
+
+loadEnv();
+
+const args = process.argv.slice(2);
+const isMulti = args.includes('--multi');
+const outputIdx = args.indexOf('--output');
+const customOutput = outputIdx !== -1 ? args[outputIdx + 1] : null;
+
+const username = isMulti
+  ? process.env.MULTI_RESOURCE_USERNAME
+  : process.env.SINGLE_RESOURCE_USERNAME;
+const password = isMulti
+  ? process.env.MULTI_RESOURCE_PASSWORD
+  : process.env.SINGLE_RESOURCE_PASSWORD;
+const baseUrl = process.env.BASE_URL;
+
+if (!username || !password) {
+  const prefix = isMulti ? 'MULTI_RESOURCE' : 'SINGLE_RESOURCE';
+  console.error(`Missing ${prefix}_USERNAME or ${prefix}_PASSWORD in .env`);
+  process.exit(1);
+}
+if (!baseUrl) {
+  console.error('Missing BASE_URL in .env');
+  process.exit(1);
+}
+
+const storageStatePath = customOutput
+  ? resolve(root, customOutput)
+  : resolve(root, '.auth', 'codegen.json');
+
+// Ensure .auth directory exists
+const authDir = dirname(storageStatePath);
+if (!existsSync(authDir)) {
+  mkdirSync(authDir, { recursive: true });
+}
+
+/**
+ * Authenticate and save storage state.
+ * Mirrors the login flow from e2e/config/auth.ts.
+ */
+async function authenticate() {
+  const { chromium } = await import('playwright');
+
+  console.error(`Authenticating as ${username}...`);
+
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+  try {
+    await page.goto(baseUrl);
+    await page.waitForEvent('load');
+
+    const usernameInput = page.getByRole('textbox', { name: 'username' });
+    await usernameInput.fill(username);
+    await usernameInput.press('Enter');
+
+    const passwordInput = page.getByRole('textbox', { name: 'password' });
+    await passwordInput.fill(password);
+    await passwordInput.press('Enter');
+
+    await page.waitForURL('**/dashboard**', { timeout: 30_000 });
+
+    await context.storageState({ path: storageStatePath });
+    console.error(`Storage state saved: ${storageStatePath}`);
+  } finally {
+    await browser.close();
+  }
+}
+
+// If the storage state already exists, skip authentication
+if (existsSync(storageStatePath)) {
+  console.error(`Storage state already exists: ${storageStatePath}`);
+  console.error('Reusing cached auth (delete the file to force re-authentication).');
+} else {
+  await authenticate();
+}

package/scripts/codegen-env.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+/**
+ * Run Playwright codegen against the app URL from your environment.
+ * Accepts an issue key so the recording is saved under <workingDir>/<KEY>/.
+ * Loads .env from the project root and passes BASE_URL to codegen.
+ *
+ * Environment variables (set by the CLI or directly):
+ *   E2E_AI_PROJECT_ROOT  - Absolute path to the project root
+ *   E2E_AI_WORKING_DIR   - Relative or absolute path to working directory (default: .qai/levante)
+ *   E2E_AI_KEY           - Issue key (e.g., PROJ-101, LIN-42, or any identifier)
+ *
+ * Usage:
+ *   node codegen-env.mjs PROJ-101
+ *   node codegen-env.mjs PROJ-101 --no-voice --no-trace
+ *   E2E_AI_KEY=PROJ-101 node codegen-env.mjs
+ */
+
+import { spawn, execSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'node:fs';
+import { dirname, resolve, relative, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Project root: prefer env var, then fall back to parent of scripts dir
+const root = process.env.E2E_AI_PROJECT_ROOT || resolve(__dirname, '..');
+
+function loadEnv() {
+  const envPath = resolve(root, '.env');
+  if (!existsSync(envPath)) return;
+  const content = readFileSync(envPath, 'utf-8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed
+      .slice(eq + 1)
+      .trim()
+      .replace(/^["']|["']$/g, '');
+    if (!process.env[key]) process.env[key] = value;
+  }
+}
+
+/** Normalize an issue key to PROJECT-NNNN (uppercase project) or return as-is. */
+function normalizeKey(key) {
+  const s = String(key || '').trim();
+  const match = s.match(/^([A-Za-z]+)-(\d+)$/i);
+  if (match) {
+    return `${match[1].toUpperCase()}-${match[2]}`;
+  }
+  return s || '';
+}
+
+/** Extract issue key from a URL (e.g. .../browse/PROJ-101) or plain string. */
+function extractKey(input) {
+  const s = String(input || '').trim();
+  const browseMatch = s.match(/\/browse\/([A-Za-z]+-\d+)/i);
+  if (browseMatch) return normalizeKey(browseMatch[1]);
+  if (s.includes('-') && /^[A-Za-z]+-\d+$/i.test(s)) return normalizeKey(s);
+  return normalizeKey(s);
+}
+
+// --- ANSI helpers ---
+function setTerminalTitle(title) {
+  process.stderr.write(`\x1b]0;${title}\x07`);
+}
+
+function printRecordingStatus(isRecording) {
+  if (isRecording) {
+    process.stderr.write('\x1b[97;41m \uD83C\uDFA4  Recording... \x1b[0m');
+    process.stderr.write('  Press \x1b[1mR\x1b[0m to pause\n');
+    setTerminalTitle('\uD83D\uDD34 Recording \u2014 codegen');
+  } else {
+    process.stderr.write('\x1b[97;43m \u23F8  Recording paused \x1b[0m');
+    process.stderr.write('  Press \x1b[1mR\x1b[0m to resume\n');
+    setTerminalTitle('\u23F8 Paused \u2014 codegen');
+  }
+}
+
+loadEnv();
+const baseUrl = process.env.BASE_URL;
+const url = baseUrl ? baseUrl.replace(/\/$/, '') : 'about:blank';
+
+// Parse CLI args
+const rawArgs = process.argv.slice(2);
+const voiceEnabled = !rawArgs.includes('--no-voice');
+const traceEnabled = !rawArgs.includes('--no-trace');
+const positionalArgs = rawArgs.filter((a) => !a.startsWith('--no-'));
+
+const keyInput = positionalArgs[0];
+const customOut = positionalArgs[1];
+const issueKey = extractKey(process.env.E2E_AI_KEY || keyInput);
+
+if (!issueKey) {
+  console.error('Usage: node codegen-env.mjs <ISSUE_KEY_or_URL> [output-path]');
+  console.error('Example: node codegen-env.mjs PROJ-101');
+  console.error('  Or set E2E_AI_KEY=PROJ-101 and run: node codegen-env.mjs');
+  process.exit(1);
+}
+
+// Resolve working directory from env or default
+const workingDirRel = process.env.E2E_AI_WORKING_DIR || '.qai/levante';
+const workingDirAbs = isAbsolute(workingDirRel) ? workingDirRel : resolve(root, workingDirRel);
+const issueDir = resolve(workingDirAbs, issueKey);
+if (!existsSync(issueDir)) {
+  mkdirSync(issueDir, { recursive: true });
+  console.error(`Created: ${relative(root, issueDir)}/`);
+}
+
+const now = new Date();
+const timestamp = [
+  now.getFullYear(),
+  String(now.getMonth() + 1).padStart(2, '0'),
+  String(now.getDate()).padStart(2, '0'),
+  '-',
+  String(now.getHours()).padStart(2, '0'),
+  String(now.getMinutes()).padStart(2, '0'),
+  String(now.getSeconds()).padStart(2, '0'),
+].join('');
+const defaultOut = resolve(issueDir, `codegen-${timestamp}.ts`);
+const outputPath = customOut ? resolve(root, customOut) : defaultOut;
+const outputRelative = relative(root, outputPath);
+
+console.error(`Issue key: ${issueKey}`);
+console.error(`Recording will be saved to: ${outputRelative}`);
+console.error(`Voice recording: ${voiceEnabled ? 'ENABLED' : 'disabled (--no-voice)'}`);
+console.error(`Trace replay:    ${traceEnabled ? 'ENABLED' : 'disabled (--no-trace)'}`);
+console.error('(When you close the Playwright Inspector, the file is written there.)\n');
+
+// --- Session timing (always track, used for action timestamps) ---
+const sessionStartTime = Date.now();
+
+// --- Action timestamp tracking via file polling ---
+const actionPattern = /^\s*(await\s+page\.|await\s+expect\()/;
+let prevActionCount = 0;
+const actionElapsedSec = []; // elapsed seconds for each action, in order
+let pollInterval = null;
+
+function startActionPolling() {
+  pollInterval = setInterval(() => {
+    if (!existsSync(outputPath)) return;
+    try {
+      const content = readFileSync(outputPath, 'utf-8');
+      const actionLines = content.split('\n').filter((l) => actionPattern.test(l));
+      const newCount = actionLines.length;
+      if (newCount > prevActionCount) {
+        const elapsed = (Date.now() - sessionStartTime) / 1000;
+        for (let i = prevActionCount; i < newCount; i++) {
+          actionElapsedSec.push(elapsed);
+        }
+        prevActionCount = newCount;
+      }
+    } catch {
+      // File might be mid-write — ignore
+    }
+  }, 500);
+}
+
+/** Inject // @t:<seconds>s comments above each action line in the codegen file. */
+function injectActionTimestamps(filePath) {
+  if (actionElapsedSec.length === 0) return;
+  const content = readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+  const result = [];
+  let idx = 0;
+  for (const line of lines) {
+    if (actionPattern.test(line) && idx < actionElapsedSec.length) {
+      const indent = line.match(/^(\s*)/)[1];
+      result.push(`${indent}// @t:${actionElapsedSec[idx].toFixed(1)}s`);
+      idx++;
+    }
+    result.push(line);
+  }
+  writeFileSync(filePath, result.join('\n'));
+}
+
+// --- Voice setup ---
+let recording = false;
+let currentRecProcess = null;
+let segmentIndex = 0;
+const segmentPaths = [];
+let recordingsDir = null;
+
+if (voiceEnabled) {
+  // Resolve scripts relative to this file's location
+  const { checkRecAvailable, startRecording } = await import(resolve(__dirname, 'voice', 'recorder.mjs'));
+  checkRecAvailable();
+
+  recordingsDir = resolve(issueDir, 'recordings');
+  if (!existsSync(recordingsDir)) {
+    mkdirSync(recordingsDir, { recursive: true });
+  }
+
+  const segPath = resolve(recordingsDir, `seg-${String(segmentIndex).padStart(3, '0')}.wav`);
+  segmentPaths.push(segPath);
+  const rec = startRecording(segPath);
+  currentRecProcess = rec.process;
+  recording = true;
+  segmentIndex++;
+
+  console.error(`Audio segments saved to: ${relative(root, recordingsDir)}/`);
+  printRecordingStatus(true);
+}
+
+// --- Auth setup: authenticate and cache storage state ---
+const authDir = resolve(root, '.auth');
+const storageStatePath = resolve(authDir, 'codegen.json');
+if (!existsSync(authDir)) {
+  mkdirSync(authDir, { recursive: true });
+}
+
+if (!existsSync(storageStatePath)) {
+  console.error('Authenticating to cache storage state...');
+  try {
+    execSync(`node "${resolve(__dirname, 'auth', 'setup-auth.mjs')}"`, {
+      cwd: root,
+      stdio: 'inherit',
+      env: { ...process.env, E2E_AI_PROJECT_ROOT: root },
+    });
+  } catch {
+    console.error('Auth setup failed \u2014 codegen will start without cached auth.');
+  }
+}
+
+// Spawn codegen with --load-storage (skip login) and --save-storage (update cache)
+const harPath = traceEnabled ? resolve(issueDir, `har-${timestamp}.har`) : null;
+const codegenArgs = ['playwright', 'codegen', '--output', outputPath];
+if (traceEnabled && harPath) {
+  codegenArgs.push('--save-har', harPath);
+}
+if (existsSync(storageStatePath)) {
+  codegenArgs.push('--load-storage', storageStatePath);
+  codegenArgs.push('--save-storage', storageStatePath);
+  console.error('Using cached auth \u2014 codegen will start already logged in.');
+}
+codegenArgs.push(url);
+
+const child = spawn('npx', codegenArgs, {
+  stdio: ['ignore', 'inherit', 'inherit'],
+  cwd: root,
+  shell: true,
+});
+
+// Start polling the output file for new actions to capture timestamps
+startActionPolling();
+
+// --- Keyboard listener for pause/resume ---
+if (voiceEnabled && process.stdin.isTTY) {
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding('utf-8');
+
+  process.stdin.on('data', async (key) => {
+    if (key === '\x03') {
+      child.kill('SIGTERM');
+      return;
+    }
+
+    if (key === 'r' || key === 'R') {
+      const { startRecording, stopRecording } = await import(resolve(__dirname, 'voice', 'recorder.mjs'));
+
+      if (recording) {
+        await stopRecording(currentRecProcess);
+        currentRecProcess = null;
+        recording = false;
+        printRecordingStatus(false);
+      } else {
+        const segPath = resolve(recordingsDir, `seg-${String(segmentIndex).padStart(3, '0')}.wav`);
+        segmentPaths.push(segPath);
+        const rec = startRecording(segPath);
+        currentRecProcess = rec.process;
+        recording = true;
+        segmentIndex++;
+        printRecordingStatus(true);
+      }
+    }
+  });
+}
+
+function cleanupTerminal() {
+  setTerminalTitle('');
+  if (process.stdin.isTTY && voiceEnabled) {
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+  }
+}
+
+child.on('exit', async (code) => {
+  cleanupTerminal();
+  if (pollInterval) clearInterval(pollInterval);
+
+  if (code === 0) {
+    console.error(`\nSaved: ${outputRelative}`);
+  }
+
+  // --- Inject action timestamps into codegen output ---
+  if (existsSync(outputPath) && actionElapsedSec.length > 0) {
+    injectActionTimestamps(outputPath);
+    console.error(`Injected ${actionElapsedSec.length} action timestamp(s) into: ${outputRelative}`);
+  }
+
+  // --- Voice post-processing: merge WAV segments only (transcription deferred to transcribe command) ---
+  if (voiceEnabled && segmentPaths.length > 0) {
+    try {
+      if (recording && currentRecProcess) {
+        const { stopRecording } = await import(resolve(__dirname, 'voice', 'recorder.mjs'));
+        await stopRecording(currentRecProcess);
+        currentRecProcess = null;
+        recording = false;
+      }
+
+      const existingSegments = segmentPaths.filter((p) => existsSync(p));
+
+      if (existingSegments.length === 0) {
+        console.error('No audio segments recorded.');
+      } else {
+        const mergedWavPath = resolve(recordingsDir, `voice-${timestamp}.wav`);
+
+        if (existingSegments.length === 1) {
+          renameSync(existingSegments[0], mergedWavPath);
+        } else {
+          console.error(`Merging ${existingSegments.length} audio segments...`);
+          const args = ['--combine', 'concatenate', ...existingSegments, mergedWavPath];
+          execSync(`sox ${args.map((a) => `"${a}"`).join(' ')}`, { stdio: 'ignore' });
+
+          for (const seg of existingSegments) {
+            try { unlinkSync(seg); } catch {}
+          }
+        }
+
+        console.error(`\nVoice recording summary:`);
+        console.error(`  Audio:   ${relative(root, mergedWavPath)}`);
+        console.error(`  Codegen: ${outputRelative}`);
+        console.error(`  (Run 'transcribe' to process voice → merge into codegen)`);
+      }
+    } catch (err) {
+      console.error(`\nVoice processing error: ${err.message}`);
+    }
+  }
+
+  // --- Trace: inject test.use({ trace: 'on' }) and run replay to generate trace ---
+  if (existsSync(outputPath)) {
+    const codegenSrc = readFileSync(outputPath, 'utf-8');
+    if (!codegenSrc.includes("test.use({ trace: 'on' })")) {
+      const injected = codegenSrc.replace(
+        /^(import\s.*from\s+['"]@playwright\/test['"];?\s*\n)/m,
+        "$1\ntest.use({ trace: 'on' });\n",
+      );
+      if (injected !== codegenSrc) {
+        writeFileSync(outputPath, injected);
+        console.error("Injected test.use({ trace: 'on' }) into codegen output.");
+      }
+    }
+
+    if (traceEnabled) {
+      console.error('\nStarting trace replay...');
+      try {
+        const replayScript = resolve(__dirname, 'trace', 'replay-with-trace.mjs');
+        execSync(`node "${replayScript}" "${outputRelative}"`, {
+          cwd: root,
+          stdio: 'inherit',
+          env: { ...process.env, E2E_AI_PROJECT_ROOT: root },
+        });
+      } catch {
+        console.error('Trace replay failed (codegen file is still saved).');
+      }
+    }
+  }
+
+  if (harPath && existsSync(harPath)) {
+    console.error(`HAR saved: ${relative(root, harPath)}`);
+  }
+
+  process.exit(code ?? 0);
+});

package/scripts/exporters/zephyr-json-to-import-xml.ts

@@ -0,0 +1,156 @@
+/**
+ * Convert a Zephyr-format test case JSON into an XML file suitable
+ * for import via Zephyr's "Import from File" wizard.
+ *
+ * Can be used both as a CLI script and as an importable module.
+ */
+
+export type ZephyrStep = { stepNumber: number; description: string; expectedResult: string };
+
+export type ZephyrTestCaseFile = {
+  title: string;
+  precondition?: string;
+  steps: ZephyrStep[];
+  issueKey?: string;
+  issueContext?: { project?: string; summary?: string; parent?: string; labels?: unknown[]; [key: string]: unknown };
+};
+
+/** Escape content for CDATA: split ]]> so it doesn't close the section. */
+function cdata(value: string): string {
+  const s = String(value ?? '');
+  return s.replace(/\]\]>/g, ']]]]><![CDATA[>');
+}
+
+function escapeXml(value: string): string {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Derive feature/area from parent epic or first label, otherwise "General".
+ */
+function getFeature(data: ZephyrTestCaseFile, titlePrefix?: string): string {
+  const parent = data.issueContext?.parent;
+  if (parent && typeof parent === 'string') {
+    const withoutKey = parent.replace(/^[A-Z][A-Z0-9]*-[0-9]+\s*/i, '').trim();
+    if (withoutKey) return withoutKey;
+  }
+  const labels = data.issueContext?.labels;
+  if (Array.isArray(labels) && labels.length > 0 && typeof labels[0] === 'string') {
+    return labels[0];
+  }
+  return 'General';
+}
+
+/**
+ * Format the full title with optional prefix.
+ * Default format: "<prefix> - <feature> - <test name>"
+ */
+export function formatExportTitle(data: ZephyrTestCaseFile, titlePrefix?: string): string {
+  const prefix = titlePrefix ?? 'UI Automation';
+  const feature = getFeature(data, titlePrefix);
+  const testName = (data.title ?? '').trim() || 'Untitled';
+  return `${prefix} - ${feature} - ${testName}`;
+}
+
+/**
+ * Convert a ZephyrTestCaseFile to Zephyr-compatible import XML.
+ */
+export function jsonToImportXml(data: ZephyrTestCaseFile, titlePrefix?: string): string {
+  const projectKey =
+    (data.issueContext?.project as string) || (data.issueKey?.split('-')[0]) || 'PROJECT';
+  const exportDate = new Date().toISOString().replace('T', ' ').replace(/\.[0-9]{3}Z$/, ' UTC');
+  const name = formatExportTitle(data, titlePrefix);
+  const precondition = data.precondition ?? '';
+  const steps = (data.steps ?? []).slice().sort((a, b) => a.stepNumber - b.stepNumber);
+
+  const stepLines = steps.map(
+    (step, i) =>
+      `                    <step index="${i}">
+                        <customFields/>
+                        <description><![CDATA[${cdata(step.description ?? '')}]]></description>
+                        <expectedResult><![CDATA[${cdata(step.expectedResult ?? '')}]]></expectedResult>
+                    </step>`
+  );
+
+  const testCaseAttrs = data.issueKey ? ` key="${escapeXml(data.issueKey)}"` : '';
+  const summary =
+    (data.issueContext?.summary as string) || data.title || '';
+  const issuesBlock = data.issueKey
+    ? `<issues>
+                <issue>
+                    <key>${escapeXml(data.issueKey)}</key>
+                    <summary><![CDATA[${cdata(summary)}]]></summary>
+                </issue>
+            </issues>`
+    : '<issues/>';
+
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<project>
+    <projectId>0</projectId>
+    <projectKey>${escapeXml(projectKey)}</projectKey>
+    <exportDate>${exportDate}</exportDate>
+    <testCases>
+        <testCase${testCaseAttrs}>
+            <attachments/>
+            <confluencePageLinks/>
+            <createdBy/>
+            <createdOn>${exportDate}</createdOn>
+            <customFields/>
+            <folder><![CDATA[]]></folder>
+            ${issuesBlock}
+            <labels/>
+            <name><![CDATA[${cdata(name)}]]></name>
+            <owner/>
+            <precondition><![CDATA[${cdata(precondition)}]]></precondition>
+            <priority><![CDATA[Normal]]></priority>
+            <status><![CDATA[Draft]]></status>
+            <parameters/>
+            <testDataWrapper/>
+            <testScript type="steps">
+                <steps>
+${stepLines.join('\n')}
+                </steps>
+            </testScript>
+        </testCase>
+    </testCases>
+</project>
+`;
+}
+
+// CLI entry point — only runs when this file is the direct entry point
+const isDirectRun = process.argv[1]?.includes('zephyr-json-to-import-xml');
+if (isDirectRun) {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+
+  const args = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  const outIdx = process.argv.indexOf('-o');
+  const outArg = outIdx >= 0 ? process.argv[outIdx + 1] : null;
+
+  const filePath = args[0];
+  if (!filePath) {
+    console.error('Usage: bun run zephyr-json-to-import-xml <test-case.json> [-o output.xml]');
+    process.exit(1);
+  }
+
+  const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+  if (!fs.existsSync(absPath)) {
+    console.error(`File not found: ${absPath}`);
+    process.exit(1);
+  }
+
+  const raw = JSON.parse(fs.readFileSync(absPath, 'utf-8')) as ZephyrTestCaseFile;
+  const xml = jsonToImportXml(raw);
+
+  const outPath = outArg
+    ? (path.isAbsolute(outArg) ? outArg : path.resolve(outArg))
+    : absPath.replace(/\.json$/i, '-import.xml');
+
+  fs.writeFileSync(outPath, xml, 'utf-8');
+  console.log(`Wrote ${outPath}`);
+}