@xera-ai/core 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,17 +17,22 @@
     }
   },
   "bin": {
-  "xera-internal": "./dist/bin/internal.js"
-},
-"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.5",
-  "@playwright/test": "1.48.0",
-  "fflate": "0.8.2"
-}
+    "xera-internal": "./dist/bin/internal.js"
+  },
+  "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": "4.4.3",
+    "@xera-ai/web": "^0.2.0",
+    "@playwright/test": "1.60.0",
+    "fflate": "0.8.3",
+    "yaml": "2.9.0"
+  }
 }

package/src/auth/refresh.ts

@@ -1,4 +1,5 @@
 import type { AuthStateEntry } from './state';
+
 export type { AuthStateEntry } from './state';
 
 const RE = /^(\d+)([hms])$/;

package/src/bin-internal/doctor.ts

@@ -1,6 +1,8 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { Stage } from '../eval/types';
+import { summarizeCost } from '../graph/cost';
+import { loadAllEvents } from '../graph/store';
 import { verifyPrompts } from './verify-prompts';
 
 export interface DoctorOpts {
@@ -124,6 +126,40 @@ export async function doctorCmd(_argv: string[], opts: DoctorOpts = {}): Promise
     ...checkPromptInjectionPreamble(repoRoot),
     ...checkRootScripts(repoRoot),
   ];
+  // Cost summary (past 7 days)
+  const cost = summarizeCost(repoRoot, 7);
+  if (cost.totalCalls > 0) {
+    console.log('');
+    console.log('LLM cost (past 7 days):');
+    console.log(`  Total calls: ${cost.totalCalls}`);
+    console.log(`  Estimated:   $${cost.totalUsd.toFixed(2)} USD`);
+    const top = Object.entries(cost.bySkill).sort((a, b) => b[1].usd - a[1].usd)[0];
+    if (top)
+      console.log(`  Top skill:   ${top[0]} (${top[1].calls} calls, $${top[1].usd.toFixed(2)})`);
+  }
+
+  // Backfill detection
+  const xeraDir = join(repoRoot, '.xera');
+  if (existsSync(xeraDir)) {
+    const ticketDirs = readdirSync(xeraDir, { withFileTypes: true }).filter(
+      (e) => e.isDirectory() && /^[A-Z]+-\d+$/.test(e.name),
+    );
+    if (ticketDirs.length > 0) {
+      const events = loadAllEvents(repoRoot);
+      const fetchedTickets = new Set(
+        events.filter((e) => e.type === 'ticket.fetched').map((e) => e.payload.ticketId),
+      );
+      const unbackfilled = ticketDirs.map((d) => d.name).filter((t) => !fetchedTickets.has(t));
+      if (unbackfilled.length > 0) {
+        console.log('');
+        console.log(`⚠ Graph: ${unbackfilled.length} ticket(s) not yet in graph.`);
+        console.log(`  These won't participate in v0.6.1+ features (TEST_OUTDATED, /xera-impact).`);
+        console.log(`  Run: bun run xera:graph-backfill`);
+        console.log(`  (Use --dry-run to preview.)`);
+      }
+    }
+  }
+
   if (results.length === 0) {
     console.log('[xera:doctor] ok');
     return 0;

package/src/bin-internal/eval-prepare.ts

@@ -2,8 +2,8 @@ import {
   copyFileSync,
   existsSync,
   mkdirSync,
-  readFileSync,
   readdirSync,
+  readFileSync,
   writeFileSync,
 } from 'node:fs';
 import { join } from 'node:path';

package/src/bin-internal/graph-backfill.ts

@@ -0,0 +1,43 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { recordScriptImpl } from './graph-record-script';
+
+async function backfillTicket(repoRoot: string, ticket: string, dryRun: boolean): Promise<number> {
+  // 1) Synthesize ticket.fetched from story.md (use story.md mtime)
+  const storyPath = join(repoRoot, '.xera', ticket, 'story.md');
+  if (!existsSync(storyPath)) return 0;
+
+  const { recordFetch } = await import('./graph-record');
+  // Re-use the same code path; in dry-run we don't actually call appendEvents.
+  // For simplicity in v0.6.0, dry-run lists ticket count and returns.
+  if (dryRun) {
+    console.log(`[backfill dry-run] would backfill ${ticket}`);
+    return 0;
+  }
+  // recordScriptImpl handles scenario/POM extraction.
+  await recordScriptImpl(repoRoot, ticket);
+  await recordFetch(repoRoot, ticket);
+  return 0;
+}
+
+export async function graphBackfillCmd(argv: string[]): Promise<number> {
+  const dryRun = argv.includes('--dry-run');
+  const repoRoot = process.cwd();
+  const xeraDir = join(repoRoot, '.xera');
+  if (!existsSync(xeraDir)) {
+    console.log('[backfill] no .xera/ directory');
+    return 0;
+  }
+  const tickets: string[] = [];
+  for (const entry of readdirSync(xeraDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === 'graph') continue;
+    if (entry.name.startsWith('.')) continue;
+    if (!/^[A-Z]+-\d+$/.test(entry.name)) continue;
+    tickets.push(entry.name);
+  }
+  console.log(`[backfill] found ${tickets.length} tickets`);
+  for (const t of tickets) await backfillTicket(repoRoot, t, dryRun);
+  console.log(`[backfill] done`);
+  return 0;
+}

package/src/bin-internal/graph-query.ts

@@ -0,0 +1,43 @@
+import { deriveSnapshot, loadAllEvents } from '../graph/store';
+import type { Snapshot } from '../graph/types';
+
+function filterByTicket(snap: Snapshot, ticket: string): Snapshot {
+  const out: Snapshot = {
+    ...snap,
+    tickets: snap.tickets[ticket] ? { [ticket]: snap.tickets[ticket]! } : {},
+    scenarios: Object.fromEntries(
+      Object.entries(snap.scenarios).filter(([, s]) => s.ticketId === ticket),
+    ),
+    poms: Object.fromEntries(Object.entries(snap.poms).filter(([, p]) => p.ticketId === ticket)),
+    edges: snap.edges.filter((e) => e.from === ticket || e.to === ticket),
+  };
+  return out;
+}
+
+function renderText(snap: Snapshot): string {
+  const out: string[] = [];
+  out.push(`Graph snapshot — ${snap.event_count} events`);
+  out.push(`Tickets: ${Object.keys(snap.tickets).length}`);
+  out.push(`Scenarios: ${Object.keys(snap.scenarios).length}`);
+  out.push(`POMs: ${Object.keys(snap.poms).length}`);
+  out.push(`Edges: ${snap.edges.length}`);
+  for (const t of Object.values(snap.tickets)) {
+    out.push(`  ${t.id} — ${t.summary}`);
+  }
+  return out.join('\n');
+}
+
+export async function graphQueryCmd(argv: string[]): Promise<number> {
+  let ticket: string | undefined;
+  let format: 'text' | 'json' = 'text';
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--ticket') ticket = argv[++i];
+    else if (argv[i] === '--format') format = argv[++i] as 'text' | 'json';
+  }
+  const repoRoot = process.cwd();
+  let snap = deriveSnapshot(loadAllEvents(repoRoot));
+  if (ticket) snap = filterByTicket(snap, ticket);
+  if (format === 'json') process.stdout.write(JSON.stringify(snap, null, 2));
+  else process.stdout.write(renderText(snap));
+  return 0;
+}

package/src/bin-internal/graph-record-script.ts

@@ -0,0 +1,191 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { appendEvents } from '../graph/store';
+import type {
+  EdgeDiscoveredPayload,
+  Event,
+  PomGeneratedPayload,
+  ScenarioGeneratedPayload,
+} from '../graph/types';
+import { SCHEMA_VERSION } from '../graph/types';
+import { ulid } from '../graph/ulid';
+
+const sha1 = (s: string) => createHash('sha1').update(s).digest('hex');
+const sId = (ticket: string, name: string) =>
+  sha1(`${ticket}:${name.trim().toLowerCase().replace(/\s+/g, ' ')}`);
+const pId = (file: string) => sha1(basename(file));
+const nowIso = () => new Date().toISOString();
+const mk = <T extends Event['type']>(
+  actor: string,
+  type: T,
+  payload: Extract<Event, { type: T }>['payload'],
+): Event =>
+  ({
+    event_id: ulid(),
+    schema_version: SCHEMA_VERSION,
+    ts: nowIso(),
+    actor,
+    type,
+    payload,
+  }) as Event;
+
+function parseFeature(
+  text: string,
+): Array<{ name: string; priority: 'p0' | 'p1' | 'p2'; gherkin: string }> {
+  const scenarios: Array<{ name: string; priority: 'p0' | 'p1' | 'p2'; gherkin: string }> = [];
+  const lines = text.split('\n');
+  let currentTagPriority: 'p0' | 'p1' | 'p2' = 'p1';
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i]!.trim();
+    if (line.startsWith('@')) {
+      const tag = line.slice(1).split(/\s+/)[0]!.toLowerCase();
+      if (tag === 'p0' || tag === 'p1' || tag === 'p2') currentTagPriority = tag;
+      i++;
+      continue;
+    }
+    if (line.startsWith('Scenario:') || line.startsWith('Scenario Outline:')) {
+      const name = line.replace(/^Scenario( Outline)?:\s*/, '');
+      const start = i;
+      i++;
+      while (
+        i < lines.length &&
+        !lines[i]!.trim().startsWith('Scenario') &&
+        !lines[i]!.trim().startsWith('@')
+      )
+        i++;
+      scenarios.push({
+        name,
+        priority: currentTagPriority,
+        gherkin: lines.slice(start, i).join('\n'),
+      });
+      currentTagPriority = 'p1';
+      continue;
+    }
+    i++;
+  }
+  return scenarios;
+}
+
+function listPomFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.ts'))
+    .map((f) => join(dir, f));
+}
+
+function extractRoute(pomContent: string): string {
+  const m = pomContent.match(/goto\s*\(\s*['"]([^'"]+)['"]/);
+  return m ? m[1]! : '';
+}
+
+function extractLocators(pomContent: string): string[] {
+  const out: string[] = [];
+  const re = /\b(getByRole|getByLabel|getByText|getByTestId|locator)\s*\(\s*([^)]+)\)/g;
+  let m = re.exec(pomContent);
+  while (m !== null) {
+    out.push(`${m[1]}(${m[2]})`);
+    m = re.exec(pomContent);
+  }
+  return out;
+}
+
+function extractPomUsage(specContent: string): string[] {
+  const names = new Set<string>();
+  const re = /new\s+([A-Z][A-Za-z0-9]*Page)\s*\(/g;
+  let m = re.exec(specContent);
+  while (m !== null) {
+    names.add(m[1]!);
+    m = re.exec(specContent);
+  }
+  return [...names];
+}
+
+export async function recordScriptImpl(repoRoot: string, ticket: string): Promise<number> {
+  const ticketDir = join(repoRoot, '.xera', ticket);
+  const featurePath = join(ticketDir, 'feature', `${ticket}.feature`);
+  const specPath = join(ticketDir, 'tests', `${ticket}.spec.ts`);
+  const pomDir = join(ticketDir, 'poms');
+
+  if (!existsSync(featurePath)) {
+    console.error(`[graph-record script] feature missing`);
+    return 1;
+  }
+
+  const featureText = readFileSync(featurePath, 'utf8');
+  const featureHash = sha1(featureText);
+  const scenarios = parseFeature(featureText);
+
+  const events: Event[] = [];
+  for (const s of scenarios) {
+    const id = sId(ticket, s.name);
+    const p: ScenarioGeneratedPayload = {
+      scenarioId: id,
+      ticketId: ticket,
+      name: s.name,
+      gherkin: s.gherkin,
+      priority: s.priority,
+      featureHash,
+      generatedAt: nowIso(),
+    };
+    events.push(mk('xera-script', 'scenario.generated', p));
+  }
+
+  const pomFiles = listPomFiles(pomDir);
+  const pomNameToId = new Map<string, string>();
+  for (const pomFile of pomFiles) {
+    const content = readFileSync(pomFile, 'utf8');
+    const id = pId(pomFile);
+    const className = content.match(/export\s+class\s+([A-Z][A-Za-z0-9]*Page)/)?.[1] ?? '';
+    pomNameToId.set(className, id);
+    const pg: PomGeneratedPayload = {
+      pomId: id,
+      ticketId: ticket,
+      filePath: pomFile.replace(`${repoRoot}/`, ''),
+      route: extractRoute(content),
+      locators: extractLocators(content),
+      scope: 'local',
+    };
+    events.push(mk('xera-script', 'pom.generated', pg));
+  }
+
+  if (existsSync(specPath)) {
+    const specContent = readFileSync(specPath, 'utf8');
+    const usedPoms = extractPomUsage(specContent);
+    for (const scenario of scenarios) {
+      const scId = sId(ticket, scenario.name);
+      for (const pomName of usedPoms) {
+        const pid = pomNameToId.get(pomName);
+        if (!pid) continue;
+        const ep: EdgeDiscoveredPayload = {
+          kind: 'uses',
+          from: scId,
+          to: pid,
+          source: 'xera-script',
+        };
+        events.push(mk('xera-script', 'edge.discovered', ep));
+      }
+    }
+  }
+
+  for (const [, id] of pomNameToId) {
+    const pom = events.find(
+      (e) => e.type === 'pom.generated' && (e.payload as PomGeneratedPayload).pomId === id,
+    );
+    if (!pom) continue;
+    const route = (pom.payload as PomGeneratedPayload).route;
+    if (!route) continue;
+    const slug =
+      route
+        .replace(/^\//, '')
+        .split('/')[0]!
+        .replace(/[^a-z0-9-]/gi, '-')
+        .toLowerCase() || 'root';
+    const ep: EdgeDiscoveredPayload = { kind: 'covers', from: id, to: slug, source: 'xera-script' };
+    events.push(mk('xera-script', 'edge.discovered', ep));
+  }
+
+  appendEvents(repoRoot, events, { skill: 'xera-script', ticketId: ticket });
+  return 0;
+}

package/src/bin-internal/graph-record.ts

@@ -0,0 +1,243 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { appendEvents } from '../graph/store';
+import type {
+  EdgeDiscoveredPayload,
+  Event,
+  PomPromotedPayload,
+  RunClassifiedPayload,
+  RunCompletedPayload,
+  TicketFetchedPayload,
+} from '../graph/types';
+import { SCHEMA_VERSION } from '../graph/types';
+import { ulid } from '../graph/ulid';
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+function sha1(s: string): string {
+  return createHash('sha1').update(s).digest('hex');
+}
+function scenarioId(ticket: string, name: string): string {
+  return sha1(`${ticket}:${name.trim().toLowerCase().replace(/\s+/g, ' ')}`);
+}
+function pomId(filePath: string): string {
+  return sha1(basename(filePath));
+}
+function makeEvent<T extends Event['type']>(
+  actor: string,
+  type: T,
+  payload: Extract<Event, { type: T }>['payload'],
+): Event {
+  return {
+    event_id: ulid(),
+    schema_version: SCHEMA_VERSION,
+    ts: nowIso(),
+    actor,
+    type,
+    payload,
+  } as Event;
+}
+
+interface StoryFrontmatter {
+  ticketId: string;
+  summary: string;
+  storyHash: string;
+  acceptanceCriteria?: string[];
+  linked_issues?: Array<{
+    ticketId: string;
+    relation: 'blocks' | 'duplicates' | 'relates' | 'supersedes';
+  }>;
+}
+
+function readStoryFrontmatter(repoRoot: string, ticket: string): StoryFrontmatter | null {
+  const path = join(repoRoot, '.xera', ticket, 'story.md');
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, 'utf8');
+  const m = raw.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  return parseYaml(m[1]!) as StoryFrontmatter;
+}
+
+function readGraphInput(repoRoot: string, ticket: string): { modifiesAreas: string[] } {
+  const path = join(repoRoot, '.xera', ticket, 'graph-input.json');
+  if (!existsSync(path)) return { modifiesAreas: [] };
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return { modifiesAreas: [] };
+  }
+}
+
+export async function recordFetch(repoRoot: string, ticket: string): Promise<number> {
+  const fm = readStoryFrontmatter(repoRoot, ticket);
+  if (!fm) {
+    console.error(`[graph-record fetch] story.md not found for ${ticket}`);
+    return 1;
+  }
+  const { modifiesAreas } = readGraphInput(repoRoot, ticket);
+  const events: Event[] = [];
+  const fetchedPayload: TicketFetchedPayload = {
+    ticketId: fm.ticketId,
+    summary: fm.summary,
+    ac: fm.acceptanceCriteria ?? [],
+    jiraLinks: fm.linked_issues ?? [],
+    storyHash: fm.storyHash,
+    modifiesAreas,
+  };
+  events.push(makeEvent('xera-fetch', 'ticket.fetched', fetchedPayload));
+  for (const link of fm.linked_issues ?? []) {
+    const p: EdgeDiscoveredPayload = {
+      kind: 'jira-linked',
+      from: fm.ticketId,
+      to: link.ticketId,
+      source: `jira:${link.relation}`,
+    };
+    events.push(makeEvent('xera-fetch', 'edge.discovered', p));
+  }
+  for (const area of modifiesAreas) {
+    const p: EdgeDiscoveredPayload = {
+      kind: 'modifies',
+      from: fm.ticketId,
+      to: area,
+      source: 'extract-areas',
+    };
+    events.push(makeEvent('xera-fetch', 'edge.discovered', p));
+  }
+  appendEvents(repoRoot, events, { skill: 'xera-fetch', ticketId: ticket });
+  return 0;
+}
+
+async function recordScript(repoRoot: string, ticket: string): Promise<number> {
+  const { recordScriptImpl } = await import('./graph-record-script');
+  return recordScriptImpl(repoRoot, ticket);
+}
+
+async function recordExec(repoRoot: string, ticket: string, runId: string): Promise<number> {
+  const reporterPath = join(repoRoot, '.xera', ticket, 'runs', runId, 'reporter.json');
+  if (!existsSync(reporterPath)) {
+    console.error(`[graph-record exec] reporter.json missing`);
+    return 1;
+  }
+  const data = JSON.parse(readFileSync(reporterPath, 'utf8')) as {
+    scenarios: Array<{ name: string; status: 'pass' | 'fail'; runtime: number; traceId?: string }>;
+  };
+  const events: Event[] = [];
+  for (const s of data.scenarios) {
+    const p: RunCompletedPayload = {
+      scenarioId: scenarioId(ticket, s.name),
+      ticketId: ticket,
+      runId,
+      status: s.status,
+      runtime: s.runtime,
+    };
+    if (s.traceId) p.traceId = s.traceId;
+    events.push(makeEvent('xera-exec', 'run.completed', p));
+  }
+  appendEvents(repoRoot, events, { skill: 'xera-exec', ticketId: ticket });
+  return 0;
+}
+
+async function recordClassify(repoRoot: string, ticket: string, runId: string): Promise<number> {
+  const classifyPath = join(repoRoot, '.xera', ticket, 'runs', runId, 'classifier-output.json');
+  if (!existsSync(classifyPath)) {
+    console.error(`[graph-record classify] classifier-output.json missing`);
+    return 1;
+  }
+  const data = JSON.parse(readFileSync(classifyPath, 'utf8')) as {
+    scenarios: Array<{ name: string; class: string; confidence: 'low' | 'medium' | 'high' }>;
+  };
+  const events: Event[] = [];
+  for (const s of data.scenarios) {
+    const p: RunClassifiedPayload = {
+      scenarioId: scenarioId(ticket, s.name),
+      runId,
+      classification: s.class as RunClassifiedPayload['classification'],
+      confidence: s.confidence,
+    };
+    events.push(makeEvent('xera-report', 'run.classified', p));
+  }
+  appendEvents(repoRoot, events, { skill: 'xera-report', ticketId: ticket });
+  return 0;
+}
+
+async function recordPromote(repoRoot: string, args: Map<string, string>): Promise<number> {
+  const from = args.get('--from');
+  const to = args.get('--to');
+  const pomIdArg = args.get('--pom-id');
+  if (!from || !to) {
+    console.error(`[graph-record promote] --from and --to required`);
+    return 1;
+  }
+  const id = pomIdArg ?? pomId(from);
+  const p: PomPromotedPayload = { pomId: id, fromPath: from, toPath: to };
+  const e = makeEvent('xera-promote', 'pom.promoted', p);
+  appendEvents(repoRoot, [e], { skill: 'xera-promote', ticketId: 'shared' });
+  return 0;
+}
+
+function parseFlags(args: string[]): Map<string, string> {
+  const m = new Map<string, string>();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i]!.startsWith('--')) {
+      m.set(args[i]!, args[i + 1] ?? '');
+      i++;
+    }
+  }
+  return m;
+}
+
+export async function graphRecordCmd(argv: string[]): Promise<number> {
+  const [action, ...rest] = argv;
+  if (!action) {
+    console.error(`Usage: xera-internal graph-record <fetch|script|exec|classify|promote> [args]`);
+    return 1;
+  }
+  const repoRoot = process.cwd();
+  switch (action) {
+    case 'fetch': {
+      const ticket = rest[0];
+      if (!ticket) {
+        console.error('ticket required');
+        return 1;
+      }
+      return recordFetch(repoRoot, ticket);
+    }
+    case 'script': {
+      const ticket = rest[0];
+      if (!ticket) {
+        console.error('ticket required');
+        return 1;
+      }
+      return recordScript(repoRoot, ticket);
+    }
+    case 'exec': {
+      const ticket = rest[0];
+      const flags = parseFlags(rest);
+      const runId = flags.get('--run-id');
+      if (!ticket || !runId) {
+        console.error('ticket + --run-id required');
+        return 1;
+      }
+      return recordExec(repoRoot, ticket, runId);
+    }
+    case 'classify': {
+      const ticket = rest[0];
+      const flags = parseFlags(rest);
+      const runId = flags.get('--run-id');
+      if (!ticket || !runId) {
+        console.error('ticket + --run-id required');
+        return 1;
+      }
+      return recordClassify(repoRoot, ticket, runId);
+    }
+    case 'promote': {
+      return recordPromote(repoRoot, parseFlags(rest));
+    }
+    default:
+      console.error(`Unknown action: ${action}`);
+      return 1;
+  }
+}

package/src/bin-internal/graph-snapshot.ts

@@ -0,0 +1,23 @@
+import { deriveSnapshot, isSnapshotStale, loadAllEvents, writeSnapshot } from '../graph/store';
+
+export async function graphSnapshotCmd(argv: string[]): Promise<number> {
+  const check = argv.includes('--check');
+  const noRebuild = argv.includes('--no-rebuild');
+  const repoRoot = process.cwd();
+  const stale = isSnapshotStale(repoRoot);
+  if (check) {
+    if (!stale) return 0;
+    if (noRebuild) {
+      console.error('[graph-snapshot] stale');
+      return 1;
+    }
+    // fall through to rebuild
+  }
+  const events = loadAllEvents(repoRoot);
+  const snap = deriveSnapshot(events);
+  writeSnapshot(repoRoot, snap);
+  if (check && stale) {
+    console.log(`[graph-snapshot] rebuilt (${events.length} events)`);
+  }
+  return 0;
+}

package/src/bin-internal/heal-prepare.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { scrubFreeText } from '@xera-ai/web';
 import { unzipSync } from 'fflate';

package/src/bin-internal/index.ts

@@ -4,6 +4,10 @@ import { evalPrepareCmd } from './eval-prepare';
 import { evalReportCmd } from './eval-report';
 import { execCmd } from './exec';
 import { fetchCmd } from './fetch';
+import { graphBackfillCmd } from './graph-backfill';
+import { graphQueryCmd } from './graph-query';
+import { graphRecordCmd } from './graph-record';
+import { graphSnapshotCmd } from './graph-snapshot';
 import { healPrepareCmd } from './heal-prepare';
 import { lintCmd } from './lint';
 import { normalizeCmd } from './normalize';
@@ -23,6 +27,10 @@ const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
   'eval-report': evalReportCmd,
   exec: execCmd,
   fetch: fetchCmd,
+  'graph-backfill': graphBackfillCmd,
+  'graph-query': graphQueryCmd,
+  'graph-record': graphRecordCmd,
+  'graph-snapshot': graphSnapshotCmd,
   'heal-prepare': healPrepareCmd,
   lint: lintCmd,
   normalize: normalizeCmd,