@xera-ai/core 0.1.3 → 0.1.5

package/package.json

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

package/src/adapter/types.ts

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

package/src/artifact/hash.ts

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

package/src/artifact/meta.ts

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

package/src/artifact/paths.ts

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

package/src/artifact/status.ts

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

package/src/auth/encrypt.ts

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

package/src/auth/key.ts

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

package/src/auth/refresh.ts

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

package/src/auth/state.ts

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

package/src/bin-internal/exec.ts

@@ -0,0 +1,111 @@
+import { resolveArtifactPaths, generateRunId } from '../artifact/paths';
+import { acquireLock, releaseLock, isLockStale, readLock, forceUnlock } from '../lock/file-lock';
+import { NdjsonLogger } from '../logging/ndjson-logger';
+import { loadConfig } from '../config/load';
+import { readAuthState } from '../auth/state';
+import { needsRefresh } from '../auth/refresh';
+import { stagePlaywrightState, runAuthSetup, runPlaywright } from '@xera-ai/web';
+import { chromium } from '@playwright/test';
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export async function execCmd(argv: string[]): Promise<number> {
+  const ticket = argv[0];
+  if (!ticket) { console.error('[xera:exec] usage: exec <TICKET>'); return 1; }
+  const cwd = process.cwd();
+  const config = await loadConfig(cwd);
+  const paths = resolveArtifactPaths(cwd, ticket);
+  const runId = generateRunId();
+  const log = new NdjsonLogger(paths.logPath);
+
+  // Acquire lock
+  if (!acquireLock(paths.lockPath, runId)) {
+    if (isLockStale(paths.lockPath)) {
+      console.error(`[xera:exec] stale lock detected; force unlocking. Run \`xera-internal unlock ${ticket}\` to clear manually.`);
+      forceUnlock(paths.lockPath);
+      acquireLock(paths.lockPath, runId);
+    } else {
+      const existing = readLock(paths.lockPath);
+      console.error(`[xera:exec] another run in progress (PID ${existing?.pid} on ${existing?.hostname}, started ${existing?.started_at}). Wait or run \`xera-internal unlock ${ticket}\`.`);
+      return 1;
+    }
+  }
+
+  const t0 = Date.now();
+  try {
+    // Auth refresh per role declared in xera.config.ts
+    if (config.web.auth.strategy === 'storageState' && config.web.auth.setupScript) {
+      const browser = await chromium.launch();
+      try {
+        for (const [roleName, roleCreds] of Object.entries(config.web.auth.roles)) {
+          const entry = readAuthState(paths.authDir, roleName);
+          if (needsRefresh(entry, { ttl: config.web.auth.ttl, refreshBuffer: config.web.auth.refreshBuffer })) {
+            const email = process.env[roleCreds.envEmail];
+            const password = process.env[roleCreds.envPassword];
+            if (!email || !password) {
+              console.error(`[xera:exec] missing env ${roleCreds.envEmail} or ${roleCreds.envPassword} for role "${roleName}"`);
+              return 1;
+            }
+            await runAuthSetup({
+              role: roleName,
+              creds: { email, password },
+              setupScriptPath: join(cwd, config.web.auth.setupScript),
+              authDir: paths.authDir,
+              browser,
+            });
+            log.log({ step: 'auth-refresh', role: roleName });
+          }
+        }
+      } finally {
+        await browser.close();
+      }
+    }
+
+    // Stage Playwright storageState files for declared roles
+    const stagedRoles: Record<string, string> = {};
+    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);
+        }
+      }
+    }
+
+    // Generate per-run playwright.config.ts if not present at ticketDir
+    const cfgPath = join(paths.ticketDir, 'playwright.config.ts');
+    if (!existsSync(cfgPath)) {
+      writeFileSync(cfgPath, renderPlaywrightConfig({
+        baseUrl: config.web.baseUrl[config.web.defaultEnv]!,
+        storageStatePathPerRole: stagedRoles,
+      }));
+    }
+
+    const runDir = paths.runPath(runId).runDir;
+    mkdirSync(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}`);
+    // Exit 3 means "test failed" (expected vs infra error)
+    return r.outcome === 'PASS' ? 0 : 3;
+  } finally {
+    releaseLock(paths.lockPath);
+  }
+}
+
+function renderPlaywrightConfig(opts: { baseUrl: string; storageStatePathPerRole: Record<string, string> }): string {
+  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(',\n')}
+  ],
+});
+`;
+}

package/src/bin-internal/fetch.ts

@@ -0,0 +1,71 @@
+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}`, '');
+  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('\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;
+}