@xera-ai/core 0.1.7 → 0.4.0

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

@@ -3,11 +3,19 @@ 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; }
+  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}`);
+  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

@@ -1,12 +1,18 @@
-import { resolveArtifactPaths } from '../artifact/paths';
 import { typecheckTicket } from '@xera-ai/web';
+import { resolveArtifactPaths } from '../artifact/paths';
 
 export async function typecheckCmd(argv: string[]): Promise<number> {
   const ticket = argv[0];
-  if (!ticket) { console.error('[xera:typecheck] usage: typecheck <TICKET>'); return 1; }
+  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; }
+  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

@@ -1,15 +1,23 @@
 import { resolveArtifactPaths } from '../artifact/paths';
-import { isLockStale, readLock, forceUnlock } from '../lock/file-lock';
+import { forceUnlock, isLockStale, readLock } 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; }
+  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; }
+  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.`);
+    console.error(
+      `[xera:unlock] lock is held by PID ${lock.pid} on ${lock.hostname} (active). Pass --force to override.`,
+    );
     return 1;
   }
   forceUnlock(paths.lockPath);

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

@@ -1,14 +1,23 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { resolveArtifactPaths } from '../artifact/paths';
+import { existsSync, readFileSync } from 'node:fs';
 import { validateGherkin } from '@xera-ai/web';
+import { resolveArtifactPaths } from '../artifact/paths';
 
 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; }
+  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; }
+  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; }
+  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/bin-internal/verify-prompts.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface CheckResult {
+  ok: boolean;
+  message: string;
+}
+
+const IN_SCOPE_PROMPTS = [
+  'feature-from-story.md',
+  'script-from-feature.md',
+  'heal-locator.md',
+  'extract-areas.md',
+] as const;
+
+const REQUIRED_SECTION_HEADING = '## Handling untrusted input';
+
+const REQUIRED_KEYWORDS = ['UNTRUSTED', 'injection-follow', '<XR_'] as const;
+
+export function verifyPrompts(repoRoot: string): CheckResult[] {
+  const promptsDir = join(repoRoot, 'packages/prompts');
+  const results: CheckResult[] = [];
+  for (const filename of IN_SCOPE_PROMPTS) {
+    const path = join(promptsDir, filename);
+    if (!existsSync(path)) {
+      results.push({
+        ok: false,
+        message: `${filename}: file missing at packages/prompts/${filename}`,
+      });
+      continue;
+    }
+    const text = readFileSync(path, 'utf8');
+    if (!text.includes(REQUIRED_SECTION_HEADING)) {
+      results.push({
+        ok: false,
+        message: `${filename}: missing required section "${REQUIRED_SECTION_HEADING}"`,
+      });
+      continue;
+    }
+    for (const keyword of REQUIRED_KEYWORDS) {
+      if (!text.includes(keyword)) {
+        results.push({
+          ok: false,
+          message: `${filename}: missing required keyword "${keyword}" (expected in "${REQUIRED_SECTION_HEADING}" section)`,
+        });
+      }
+    }
+  }
+  return results;
+}
+
+export async function verifyPromptsCmd(_argv: string[]): Promise<number> {
+  const results = verifyPrompts(process.cwd());
+  if (results.length === 0) {
+    console.log('[xera:verify-prompts] ok');
+    return 0;
+  }
+  for (const r of results) console.error(`[xera:verify-prompts] ${r.message}`);
+  return 1;
+}

package/src/classifier/aggregate.ts

@@ -1,7 +1,11 @@
-import type { ClassifyOutput, ScenarioClassification, Confidence } from './types';
+import type { ClassifyOutput, Confidence, ScenarioClassification } from './types';
 
 const CLASS_PRIORITY: Array<ClassifyOutput['overall']> = [
-  'REAL_BUG', 'TEST_BUG', 'SELECTOR_DRIFT', 'FLAKY', 'PASS',
+  'REAL_BUG',
+  'TEST_BUG',
+  'SELECTOR_DRIFT',
+  'FLAKY',
+  'PASS',
 ];
 
 const CONF_RANK: Record<Confidence, number> = { low: 1, medium: 2, high: 3 };
@@ -10,16 +14,19 @@ export function aggregateScenarios(scenarios: ScenarioClassification[]): Classif
   if (scenarios.length === 0) {
     return { overall: 'PASS', overallConfidence: 'low', scenarios: [] };
   }
-  if (scenarios.every(s => s.outcome === 'PASS')) {
+  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; }
+    if (scenarios.some((s) => s.class === cls)) {
+      chosen = cls;
+      break;
+    }
   }
-  const matching = scenarios.filter(s => s.class === chosen);
+  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,
+    (acc, s) => (CONF_RANK[s.confidence] < CONF_RANK[acc] ? s.confidence : acc),
     'high',
   );
   return { overall: chosen, overallConfidence: minConf, scenarios };

package/src/config/define.ts

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

package/src/config/load.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { XeraConfigSchema, type XeraConfig } from './schema';
+import { type XeraConfig, XeraConfigSchema } from './schema';
 
 export async function loadConfig(cwd: string): Promise<XeraConfig> {
   const path = join(cwd, 'xera.config.ts');

package/src/config/schema.ts

@@ -13,21 +13,23 @@ const AuthSchema = z.object({
   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 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.prefault({}),
+    testData: z
+      .object({
+        users: z.record(z.string(), z.object({ fromAuth: z.string() })).default({}),
+      })
+      .prefault({}),
+  })
+  .refine((w) => w.baseUrl[w.defaultEnv] !== undefined, {
+    message: 'defaultEnv must exist in baseUrl map',
+    path: ['defaultEnv'],
+  });
 
 const JiraSchema = z.object({
   baseUrl: z.string().url(),
@@ -39,29 +41,33 @@ const JiraSchema = z.object({
   }),
 });
 
-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 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),
+      })
+      .prefault({}),
+  })
+  .prefault({});
 
-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({});
+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),
+      })
+      .prefault({}),
+    artifactLinks: z.enum(['git', 'local']).default('git'),
+  })
+  .prefault({});
 
 export const XeraConfigSchema = z.object({
   jira: JiraSchema,

package/src/eval/paths.ts

@@ -0,0 +1,32 @@
+import { join } from 'node:path';
+
+export interface EvalPaths {
+  root: string;
+  manifest: string;
+  lock: string;
+  deterministicScores: string;
+  judgeScores: string;
+  report: string;
+  summary: string;
+  inputsDir: string;
+  actualDir: string;
+  ticketInputsDir(ticket: string): string;
+  ticketActualDir(ticket: string): string;
+}
+
+export function resolveEvalPaths(cwd: string, runId: string): EvalPaths {
+  const root = join(cwd, '.xera', 'eval', runId);
+  return {
+    root,
+    manifest: join(root, 'manifest.json'),
+    lock: join(root, '.lock'),
+    deterministicScores: join(root, 'deterministic-scores.json'),
+    judgeScores: join(root, 'judge-scores.json'),
+    report: join(root, 'report.md'),
+    summary: join(root, 'summary.json'),
+    inputsDir: join(root, 'inputs'),
+    actualDir: join(root, 'actual'),
+    ticketInputsDir: (ticket: string) => join(root, 'inputs', ticket),
+    ticketActualDir: (ticket: string) => join(root, 'actual', ticket),
+  };
+}

package/src/eval/run-id.ts

@@ -0,0 +1,30 @@
+import { execSync } from 'node:child_process';
+
+export interface RunIdOpts {
+  getGitSha?: () => string | null;
+  now?: () => Date;
+}
+
+function defaultGetGitSha(): string | null {
+  try {
+    return execSync('git rev-parse HEAD', { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+  } catch {
+    return null;
+  }
+}
+
+function pad(n: number): string {
+  return n.toString().padStart(2, '0');
+}
+
+export function generateRunId(opts: RunIdOpts = {}): string {
+  const getGitSha = opts.getGitSha ?? defaultGetGitSha;
+  const now = (opts.now ?? (() => new Date()))();
+  const date = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}`;
+  const time = `${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}`;
+  const sha = getGitSha();
+  const short = sha ? sha.slice(0, 7) : 'nogit';
+  return `${date}-${time}-${short}`;
+}

package/src/eval/types.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+
+export const STAGES = ['feature-from-story', 'script-from-feature', 'diagnose-failure'] as const;
+export const StageSchema = z.enum(STAGES);
+export type Stage = z.infer<typeof StageSchema>;
+
+export const VerdictSchema = z.enum(['PASS', 'FAIL', 'NA']);
+export type Verdict = z.infer<typeof VerdictSchema>;
+
+export const PromptVersionsSchema = z.object({
+  'feature-from-story': z.string(),
+  'script-from-feature': z.string(),
+  'diagnose-failure': z.string(),
+  'eval-rubric': z.string(),
+});
+export type PromptVersions = z.infer<typeof PromptVersionsSchema>;
+
+export const ManifestSchema = z.object({
+  run_id: z.string(),
+  started_at: z.string(),
+  git_sha: z.string(),
+  tickets: z.array(z.string()).min(1),
+  stages: z.array(StageSchema).min(1),
+  ticket_stages: z.record(z.string(), z.array(StageSchema).min(1)),
+  prompt_versions: PromptVersionsSchema,
+  flags: z.object({
+    force: z.boolean(),
+    only_prompt: StageSchema.nullable(),
+    only_ticket: z.string().nullable(),
+    judge_only: z.boolean(),
+  }),
+});
+export type Manifest = z.infer<typeof ManifestSchema>;
+
+export const DimensionSchema = z.object({
+  name: z.string(),
+  verdict: VerdictSchema,
+  notes: z.string(),
+});
+export type Dimension = z.infer<typeof DimensionSchema>;
+
+export const JudgmentSchema = z.object({
+  stage: StageSchema,
+  ticket: z.string(),
+  dimensions: z.array(DimensionSchema).min(1),
+});
+export type Judgment = z.infer<typeof JudgmentSchema>;
+
+export const JudgeScoresSchema = z.object({
+  run_id: z.string(),
+  judgments: z.array(JudgmentSchema),
+});
+export type JudgeScores = z.infer<typeof JudgeScoresSchema>;
+
+export const DeterministicEntrySchema = z.object({
+  ticket: z.string(),
+  stage: StageSchema,
+  passed: z.boolean(),
+  checks: z.array(z.string()),
+  error: z.string().optional(),
+});
+export type DeterministicEntry = z.infer<typeof DeterministicEntrySchema>;
+
+export const DeterministicScoresSchema = z.object({
+  run_id: z.string(),
+  entries: z.array(DeterministicEntrySchema),
+});
+export type DeterministicScores = z.infer<typeof DeterministicScoresSchema>;
+
+export const ResultSchema = z.object({
+  ticket: z.string(),
+  stage: StageSchema,
+  deterministic: z.object({
+    passed: z.boolean(),
+    checks: z.array(z.string()),
+    error: z.string().optional(),
+  }),
+  judge: z
+    .object({
+      passed: z.boolean(),
+      dimensions: z.array(DimensionSchema),
+      score: z.number().min(0).max(1),
+    })
+    .nullable(),
+  skipped: z.boolean().optional(),
+});
+export type Result = z.infer<typeof ResultSchema>;
+
+export const SummarySchema = z.object({
+  run_id: z.string(),
+  git_sha: z.string(),
+  prompt_versions: PromptVersionsSchema,
+  results: z.array(ResultSchema),
+  overall: z.object({
+    passed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+    score: z.number().min(0).max(1),
+  }),
+});
+export type Summary = z.infer<typeof SummarySchema>;

package/src/graph/cost.ts

@@ -0,0 +1,59 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { graphPaths } from './paths';
+
+export interface LlmCallLog {
+  ts?: string;
+  skill: string;
+  prompt: string;
+  tokensIn: number;
+  tokensOut: number;
+  model: string;
+  costUsd: number;
+}
+
+export function logLlmCall(repoRoot: string, call: LlmCallLog): void {
+  const paths = graphPaths(repoRoot);
+  mkdirSync(dirname(paths.costLog), { recursive: true });
+  const record = {
+    ts: call.ts ?? new Date().toISOString(),
+    skill: call.skill,
+    prompt: call.prompt,
+    tokens_in: call.tokensIn,
+    tokens_out: call.tokensOut,
+    model: call.model,
+    cost_estimate_usd: call.costUsd,
+  };
+  appendFileSync(paths.costLog, `${JSON.stringify(record)}\n`);
+}
+
+export interface CostSummary {
+  totalCalls: number;
+  totalUsd: number;
+  bySkill: Record<string, { calls: number; usd: number }>;
+  windowDays: number;
+}
+
+export function summarizeCost(repoRoot: string, daysBack: number): CostSummary {
+  const paths = graphPaths(repoRoot);
+  const result: CostSummary = { totalCalls: 0, totalUsd: 0, bySkill: {}, windowDays: daysBack };
+  if (!existsSync(paths.costLog)) return result;
+  const cutoff = Date.now() - daysBack * 86400 * 1000;
+  for (const line of readFileSync(paths.costLog, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    let row: { ts: string; skill: string; cost_estimate_usd: number };
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (Date.parse(row.ts) < cutoff) continue;
+    result.totalCalls++;
+    result.totalUsd += row.cost_estimate_usd;
+    if (!result.bySkill[row.skill]) result.bySkill[row.skill] = { calls: 0, usd: 0 };
+    const s = result.bySkill[row.skill]!;
+    s.calls++;
+    s.usd += row.cost_estimate_usd;
+  }
+  return result;
+}

package/src/graph/index.ts

@@ -0,0 +1,15 @@
+export type { CostSummary, LlmCallLog } from './cost';
+export { logLlmCall, summarizeCost } from './cost';
+export { currentYyyyMm, graphPaths } from './paths';
+export { EventSchema, safeParseEvent } from './schema';
+export {
+  appendEvents,
+  computeEventsHash,
+  deriveSnapshot,
+  isSnapshotStale,
+  loadAllEvents,
+  loadSnapshot,
+  writeSnapshot,
+} from './store';
+export * from './types';
+export { ulid } from './ulid';

package/src/graph/paths.ts

@@ -0,0 +1,27 @@
+import { join } from 'node:path';
+
+export interface GraphPaths {
+  eventsDir: string;
+  snapshotFile: string;
+  costLog: string;
+  eventsMonthDir(yyyyMm: string): string;
+  eventFile(ulid: string, skill: string, ticketId: string, yyyyMm: string): string;
+}
+
+export function graphPaths(repoRoot: string): GraphPaths {
+  const eventsDir = join(repoRoot, '.xera/graph/events');
+  return {
+    eventsDir,
+    snapshotFile: join(repoRoot, '.xera/graph/snapshot.json'),
+    costLog: join(repoRoot, '.xera/cost-log.jsonl'),
+    eventsMonthDir: (yyyyMm) => join(eventsDir, yyyyMm),
+    eventFile: (ulid, skill, ticketId, yyyyMm) =>
+      join(eventsDir, yyyyMm, `${ulid}-${skill}-${ticketId}.jsonl`),
+  };
+}
+
+export function currentYyyyMm(now: Date = new Date()): string {
+  const y = now.getUTCFullYear();
+  const m = String(now.getUTCMonth() + 1).padStart(2, '0');
+  return `${y}-${m}`;
+}