atris 3.30.0 → 3.30.2

package/lib/chat-log-scan.js

@@ -0,0 +1,377 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SCHEMA = 'atris.chat_scan.v1';
+const PROMPT_LINE = /^(?:max|pro|fast|code-fast)\s*›\s*(.+)$/i;
+const ERROR_LINE = /\b(error|failed|failure|timeout|HTTP \d{3}|ECONNREFUSED|ENOTFOUND|aborted|blocked)\b/i;
+const USER_BAIL = /\b(interrupted|Not completed yet|tool budget ended|max turns forcing final)\b/i;
+
+function compact(text, max = 160) {
+  const one = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!one) return '';
+  return one.length <= max ? one : `${one.slice(0, max - 3)}...`;
+}
+
+function safeRead(filePath, maxBytes = 2_000_000) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function listRecentFiles(dir, { pattern, limit = 40, maxAgeMs = 14 * 86400000 } = {}) {
+  if (!dir || !fs.existsSync(dir)) return [];
+  const cutoff = Date.now() - maxAgeMs;
+  const out = [];
+  const walk = (current) => {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (pattern && !pattern.test(entry.name)) continue;
+      let mtime = 0;
+      try {
+        mtime = fs.statSync(full).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (mtime < cutoff) continue;
+      out.push({ path: full, mtimeMs: mtime });
+    }
+  };
+  walk(dir);
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out.slice(0, limit);
+}
+
+function cursorTranscriptRoots(cwd = process.cwd()) {
+  const base = path.join(os.homedir(), '.cursor', 'projects');
+  if (!fs.existsSync(base)) return [];
+  const slug = cwd.replace(/^\/+/, '').split(path.sep).join('-');
+  const exact = path.join(base, slug, 'agent-transcripts');
+  const roots = [];
+  if (fs.existsSync(exact)) roots.push(exact);
+  const extra = process.env.ATRIS_CHAT_SCAN_CURSOR_ROOT;
+  if (extra && fs.existsSync(extra)) roots.push(extra);
+  return roots;
+}
+
+function axLogDirs(cwd = process.cwd()) {
+  const dirs = [];
+  const local = path.join(cwd, 'atris', 'runs');
+  const home = path.join(os.homedir(), '.atris', 'runs');
+  if (fs.existsSync(local)) dirs.push(local);
+  if (fs.existsSync(home) && home !== local) dirs.push(home);
+  return dirs;
+}
+
+function parseWorkedDuration(label) {
+  const text = String(label || '').trim().toLowerCase();
+  if (!text) return 0;
+  let seconds = 0;
+  for (const match of text.matchAll(/(\d+(?:\.\d+)?)\s*(ms|m|s)\b/g)) {
+    const value = Number(match[1]);
+    if (!Number.isFinite(value)) continue;
+    if (match[2] === 'ms') seconds += value / 1000;
+    if (match[2] === 's') seconds += value;
+    if (match[2] === 'm') seconds += value * 60;
+  }
+  return seconds;
+}
+
+function extractUserQuery(text) {
+  const raw = String(text || '');
+  const tagged = raw.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/i);
+  if (tagged) return compact(tagged[1], 240);
+  return compact(raw, 240);
+}
+
+function parseCursorTranscript(filePath, text) {
+  const lines = text.split(/\r?\n/).filter(Boolean);
+  const userTurns = [];
+  const assistantSummaries = [];
+  let toolCalls = 0;
+  let errors = 0;
+
+  for (const line of lines) {
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const role = row.role;
+    const parts = row.message?.content || [];
+    if (role === 'user') {
+      for (const part of parts) {
+        if (part.type === 'text' && part.text) {
+          const q = extractUserQuery(part.text);
+          if (q) userTurns.push(q);
+        }
+      }
+    }
+    if (role === 'assistant') {
+      let turnTools = 0;
+      let turnText = '';
+      for (const part of parts) {
+        if (part.type === 'tool_use') turnTools += 1;
+        if (part.type === 'text' && part.text && !part.text.includes('[REDACTED]')) {
+          turnText += part.text;
+        }
+      }
+      toolCalls += turnTools;
+      if (turnText.trim()) assistantSummaries.push(compact(turnText, 280));
+      if (ERROR_LINE.test(turnText) || USER_BAIL.test(turnText)) errors += 1;
+    }
+  }
+
+  const lastUser = userTurns[userTurns.length - 1] || null;
+  const lastAssistant = assistantSummaries[assistantSummaries.length - 1] || null;
+  return {
+    source: 'cursor',
+    path: filePath,
+    user_turns: userTurns.length,
+    assistant_turns: assistantSummaries.length,
+    tool_calls: toolCalls,
+    last_user: lastUser,
+    last_assistant: lastAssistant,
+    sample_users: userTurns.slice(-3),
+  };
+}
+
+function parseAxLog(filePath, text) {
+  const lines = text.split(/\r?\n/);
+  const userTurns = [];
+  const findings = [];
+  let mode = null;
+  let cwd = null;
+  let startedAt = null;
+  let finishedAt = null;
+  let exitCode = null;
+  let lastWorkedSec = null;
+  let toolCalls = 0;
+  let interrupted = false;
+
+  for (const line of lines) {
+    if (line.startsWith('mode: ')) mode = line.slice(6).trim();
+    if (line.startsWith('cwd: ')) cwd = line.slice(5).trim();
+    if (line.startsWith('started_at: ')) startedAt = line.slice(12).trim();
+    if (line.startsWith('finished_at: ')) finishedAt = line.slice(13).trim();
+    if (line.startsWith('exit_code: ')) exitCode = Number(line.slice(11).trim());
+    const prompt = line.match(PROMPT_LINE);
+    if (prompt) userTurns.push(compact(prompt[1], 240));
+    if (/^●\s/.test(line)) toolCalls += 1;
+    if (/·\s*Interrupted/i.test(line)) interrupted = true;
+    const worked = line.match(/^— Worked for ([^-]+?) —/);
+    if (worked) lastWorkedSec = worked[1];
+    if (ERROR_LINE.test(line) || /^x\s/.test(line.trim())) {
+      findings.push(compact(line, 180));
+    }
+    if (USER_BAIL.test(line)) findings.push(compact(line, 180));
+  }
+
+  return {
+    source: 'ax',
+    path: filePath,
+    mode,
+    cwd,
+    started_at: startedAt,
+    finished_at: finishedAt,
+    exit_code: Number.isFinite(exitCode) ? exitCode : null,
+    user_turns: userTurns.length,
+    tool_calls: toolCalls,
+    interrupted,
+    last_worked: lastWorkedSec,
+    last_user: userTurns[userTurns.length - 1] || null,
+    sample_users: userTurns.slice(-3),
+    log_findings: [...new Set(findings)].slice(0, 8),
+  };
+}
+
+function buildFindings(sessions) {
+  const findings = [];
+  for (const session of sessions) {
+    if (session.interrupted) {
+      findings.push({
+        severity: 'medium',
+        code: 'interrupted_turn',
+        title: 'User interrupted an in-flight turn',
+        source: session.source,
+        path: session.path,
+        evidence: session.last_user || session.last_assistant || '',
+      });
+    }
+    if (session.exit_code && session.exit_code !== 0) {
+      findings.push({
+        severity: 'high',
+        code: 'nonzero_exit',
+        title: `Chat session exited with code ${session.exit_code}`,
+        source: session.source,
+        path: session.path,
+        evidence: session.last_user || '',
+      });
+    }
+    for (const line of session.log_findings || []) {
+      findings.push({
+        severity: 'medium',
+        code: 'log_error_pattern',
+        title: 'Error-like line in chat log',
+        source: session.source,
+        path: session.path,
+        evidence: line,
+      });
+    }
+    if (session.source === 'ax' && session.last_worked) {
+      const seconds = parseWorkedDuration(session.last_worked);
+      const incomplete = (session.log_findings || []).some((l) => /Not completed yet|tool budget|Blocked:|max turns forcing/i.test(l));
+      if (seconds >= 45 && incomplete) {
+        findings.push({
+          severity: 'high',
+          code: 'slow_incomplete_turn',
+          title: `Long turn (${session.last_worked}) ended incomplete`,
+          source: session.source,
+          path: session.path,
+          evidence: session.last_user || '',
+        });
+      }
+    }
+    if (session.user_turns >= 2 && session.sample_users?.length >= 2) {
+      const a = session.sample_users[session.sample_users.length - 2].toLowerCase();
+      const b = session.sample_users[session.sample_users.length - 1].toLowerCase();
+      if (a && b && (a.includes(b.slice(0, 24)) || b.includes(a.slice(0, 24)))) {
+        findings.push({
+          severity: 'low',
+          code: 'repeat_user_ask',
+          title: 'User may have repeated a similar ask',
+          source: session.source,
+          path: session.path,
+          evidence: `${a} -> ${b}`,
+        });
+      }
+    }
+  }
+  findings.sort((x, y) => {
+    const rank = { high: 3, medium: 2, low: 1 };
+    return (rank[y.severity] || 0) - (rank[x.severity] || 0);
+  });
+  return findings.slice(0, 20);
+}
+
+function scanChatLogs(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const limit = Number(options.limit) || 12;
+  const maxAgeHours = Number(options.hours) || 720;
+  const maxAgeMs = maxAgeHours * 3600000;
+  const sessions = [];
+
+  for (const dir of axLogDirs(cwd)) {
+    for (const file of listRecentFiles(dir, { pattern: /^ax-.*\.log$/, limit, maxAgeMs })) {
+      const text = safeRead(file.path);
+      if (!text) continue;
+      sessions.push(parseAxLog(file.path, text));
+    }
+  }
+
+  for (const root of cursorTranscriptRoots(cwd)) {
+    for (const file of listRecentFiles(root, { pattern: /\.jsonl$/, limit, maxAgeMs })) {
+      const text = safeRead(file.path);
+      if (!text) continue;
+      const parsed = parseCursorTranscript(file.path, text);
+      if (parsed.user_turns > 0 || parsed.assistant_turns > 0) sessions.push(parsed);
+    }
+  }
+
+  sessions.sort((a, b) => {
+    const ta = fs.statSync(a.path).mtimeMs;
+    const tb = fs.statSync(b.path).mtimeMs;
+    return tb - ta;
+  });
+
+  const findings = buildFindings(sessions);
+  const report = {
+    schema: SCHEMA,
+    scanned_at: new Date().toISOString(),
+    cwd,
+    window_hours: maxAgeHours,
+    sources: {
+      ax_dirs: axLogDirs(cwd),
+      cursor_roots: cursorTranscriptRoots(cwd),
+    },
+    summary: {
+      sessions: sessions.length,
+      ax_sessions: sessions.filter((s) => s.source === 'ax').length,
+      cursor_sessions: sessions.filter((s) => s.source === 'cursor').length,
+      findings: findings.length,
+      high_findings: findings.filter((f) => f.severity === 'high').length,
+    },
+    sessions: sessions.slice(0, limit).map((s) => ({
+      ...s,
+      path: s.path,
+      rel_path: s.path.startsWith(cwd) ? path.relative(cwd, s.path) : s.path,
+    })),
+    findings,
+    next_command: findings.length
+      ? 'atris member wake auto-improver --execute --confirm-autonomy-policy'
+      : 'atris chat scan --hours 168',
+  };
+  return report;
+}
+
+function writeLatestScan(root, report) {
+  const stateDir = path.join(root, '.atris', 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  const latestPath = path.join(stateDir, 'chat_scan.latest.json');
+  fs.writeFileSync(latestPath, `${JSON.stringify(report, null, 2)}\n`);
+  return latestPath;
+}
+
+function readLatestScan(root) {
+  const latestPath = path.join(root, '.atris', 'state', 'chat_scan.latest.json');
+  try {
+    if (!fs.existsSync(latestPath)) return null;
+    return JSON.parse(fs.readFileSync(latestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function ensureChatScan(root, options = {}) {
+  const maxAgeMs = Number(options.maxAgeMs ?? 3600000);
+  const existing = readLatestScan(root);
+  if (existing && existing.scanned_at && !options.force) {
+    const age = Date.now() - new Date(existing.scanned_at).getTime();
+    if (Number.isFinite(age) && age >= 0 && age <= maxAgeMs) {
+      return existing;
+    }
+  }
+  const report = scanChatLogs({ cwd: root, hours: options.hours, limit: options.limit });
+  if (options.write !== false) writeLatestScan(root, report);
+  return report;
+}
+
+function topChatFindings(report, limit = 3) {
+  return (report && Array.isArray(report.findings) ? report.findings : []).slice(0, limit);
+}
+
+module.exports = {
+  SCHEMA,
+  scanChatLogs,
+  writeLatestScan,
+  readLatestScan,
+  ensureChatScan,
+  topChatFindings,
+  cursorTranscriptRoots,
+  axLogDirs,
+};

package/lib/context-gatherer.js

@@ -117,11 +117,14 @@ function shouldGatherContext({
   wipCount = 0,
   backlogCount = 0,
   inboxCount = 0,
+  completedTasksCount = 0,
 } = {}) {
   if (hasContextProfile(root)) return false;
   if (String(userInput || '').trim()) return true;
   if (mapStatus !== 'ready') return true;
-  if (liveMissionsCount > 0 || wipCount > 0 || backlogCount > 0 || inboxCount > 0) return false;
+  // Any signal that the workspace has been used (pending work OR completed
+  // history) means it is not a fresh project to onboard.
+  if (liveMissionsCount > 0 || wipCount > 0 || backlogCount > 0 || inboxCount > 0 || completedTasksCount > 0) return false;
   return true;
 }
 
@@ -137,6 +140,35 @@ function renderPrompt({ projectName = 'this workspace' } = {}) {
   ].join('\n');
 }
 
+function normalizeQuestionText(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^\w\s']/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// True when the input is a question ABOUT Atris itself ("what is atris?",
+// "what can you do?") rather than a task request. bin/atris.js uses this to
+// show the product overview instead of routing the words into plan/do.
+// A clear task verb always wins, so "build a website" is never a meta-question.
+function isAtrisMetaQuestion(value) {
+  const text = normalizeQuestionText(value);
+  if (!text) return false;
+
+  const taskVerb = /\b(add|audit|build|change|create|debug|deploy|edit|fix|implement|make|patch|refactor|remove|review|run|ship|test|update|write)\b/;
+  if (taskVerb.test(text)) return false;
+
+  return [
+    /^(what'?s|what is|what are|who is|who are)\s+(atris|you|this)\b/,
+    /^what\s+atris\s+is\b/,
+    /^(what|how)\s+(does|do|can)\s+(atris|you|this)\b/,
+    /^(explain|describe|define)\s+(atris|this)\b/,
+    /^tell me\s+(about|what)\s+(atris|this)\b/,
+    /^why\s+atris\b/,
+  ].some((pattern) => pattern.test(text));
+}
+
 module.exports = {
   PROFILE_REL_PATH,
   profilePath,
@@ -149,4 +181,6 @@ module.exports = {
   renderPrompt,
   starterTaskTitle,
   inferDomain,
+  normalizeQuestionText,
+  isAtrisMetaQuestion,
 };

package/lib/deck-compose.js

@@ -0,0 +1,145 @@
+// Compose a deck spec from a prose/markdown analysis (e.g. a transcript summary
+// the cloud returns for a YouTube video). Pure and deterministic: text in,
+// lint-clean spec out. The network fetch lives in the CLI; this just turns
+// structured text into layout SECTIONS and runs them through the layout planner
+// so the result picks narrative archetypes and stays under template fatigue.
+
+const { planLayout } = require('./deck-layout');
+
+function stripNoise(md) {
+  return String(md == null ? '' : md)
+    .replace(/```[\s\S]*?```/g, '')   // fenced code
+    .replace(/`([^`]+)`/g, '$1')      // inline code
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '') // images
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // links -> text
+    .replace(/\r\n?/g, '\n');
+}
+
+// Tokenize markdown-ish text into headings, bullet lists, quotes, paragraphs.
+function parseBlocks(md) {
+  const lines = stripNoise(md).split('\n');
+  const blocks = [];
+  let para = [];
+  let bullets = [];
+  const flushPara = () => { if (para.length) { blocks.push({ kind: 'p', text: para.join(' ').trim() }); para = []; } };
+  const flushBullets = () => { if (bullets.length) { blocks.push({ kind: 'ul', items: bullets.slice() }); bullets = []; } };
+  for (const raw of lines) {
+    const line = raw.replace(/\s+$/, '');
+    const h = line.match(/^(#{1,4})\s+(.+?)\s*#*$/);
+    const bul = line.match(/^\s*[-*•]\s+(.+)/) || line.match(/^\s*\d+[.)]\s+(.+)/);
+    const quote = line.match(/^\s*>\s*(.+)/);
+    if (h) { flushPara(); flushBullets(); blocks.push({ kind: 'h', level: h[1].length, text: h[2].trim() }); }
+    else if (bul) { flushPara(); bullets.push(bul[1].trim()); }
+    else if (quote) { flushPara(); flushBullets(); blocks.push({ kind: 'quote', text: quote[1].trim() }); }
+    else if (line.trim() === '') { flushPara(); flushBullets(); }
+    else { flushBullets(); para.push(line.trim()); }
+  }
+  flushPara();
+  flushBullets();
+  return blocks;
+}
+
+// "Term: detail" or bold "**Term** detail" -> { text, sub }; else a plain string.
+function toItem(line) {
+  const bold = line.match(/^\*\*(.+?)\*\*[:\s,-]+(.+)/);
+  if (bold && bold[1].length <= 48) return { text: bold[1].trim(), sub: bold[2].trim() };
+  const colon = line.match(/^([^:]{2,48}):\s+(.+)/);
+  if (colon) return { text: colon[1].trim(), sub: colon[2].trim() };
+  return line.replace(/\*\*/g, '');
+}
+
+// A quote may carry an attribution: `"..." - Name` or `... (Name)`.
+function splitQuote(text) {
+  const dash = text.match(/^["“]?(.+?)["”]?\s+[-–—]\s+(.+)$/);
+  if (dash) return { text: dash[1].trim(), author: dash[2].trim() };
+  const paren = text.match(/^["“]?(.+?)["”]?\s+\(([^)]+)\)\s*$/);
+  if (paren) return { text: paren[1].trim(), author: paren[2].trim() };
+  return { text: text.replace(/^["“]|["”]$/g, '').trim() };
+}
+
+function classify(heading, content) {
+  const ul = content.find((b) => b.kind === 'ul');
+  const quote = content.find((b) => b.kind === 'quote');
+  const paras = content.filter((b) => b.kind === 'p').map((b) => b.text);
+
+  if (ul) {
+    const lead = paras[0];
+    return {
+      kind: 'points',
+      heading: heading || undefined,
+      items: ul.items.map(toItem),
+      ...(lead && lead.length <= 120 ? { sub: lead } : {}),
+    };
+  }
+  if (quote) {
+    const q = splitQuote(quote.text);
+    return { kind: 'quote', quote: q };
+  }
+  const body = paras.join(' ').trim();
+  if (!body) return { kind: 'statement', text: heading || 'Untitled' };
+  if (body.length > 180 || paras.length > 1) {
+    return { kind: 'prose', heading: heading || undefined, paragraphs: paras.slice(0, 3) };
+  }
+  // short single paragraph: the heading is the claim, the paragraph the support
+  if (heading) return { kind: 'statement', text: heading, sub: body };
+  return { kind: 'statement', text: body };
+}
+
+// Group tokenized blocks into sections (one per heading; leading content forms
+// an untitled section), then classify each into a layout section.
+function blocksToSections(blocks) {
+  const groups = [];
+  let current = null;
+  for (const b of blocks) {
+    if (b.kind === 'h') { if (current) groups.push(current); current = { heading: b.text, content: [] }; }
+    else { if (!current) current = { heading: null, content: [] }; current.content.push(b); }
+  }
+  if (current) groups.push(current);
+  return groups.map((g) => ({ raw: g, section: classify(g.heading, g.content) }));
+}
+
+function composeSpec(text, opts = {}) {
+  const blocks = parseBlocks(text);
+  const grouped = blocksToSections(blocks);
+  let sections = grouped.map((g) => g.section);
+
+  // Cover: build a cover slide. Fold the first section into it ONLY when that
+  // section is a thin title/lead (a short statement or a cover) so we never
+  // destroy a deck that opens with bullets, a quote, or multi-paragraph prose.
+  const h1 = blocks.find((b) => b.kind === 'h' && b.level === 1);
+  const firstPara = blocks.find((b) => b.kind === 'p');
+  const first = sections[0];
+  const docTitle = opts.title || (h1 && h1.text) || (first && (first.heading || first.text)) || 'Untitled';
+  const coverSub = opts.subtitle
+    || (first && first.sub)
+    || (firstPara && firstPara.text !== docTitle ? firstPara.text : undefined);
+  const cover = { kind: 'cover', headline: docTitle, sub: coverSub };
+  const fold = first && (first.kind === 'statement' || first.kind === 'cover');
+  if (!sections.length) sections = [cover];
+  else if (fold) sections = [cover, ...sections.slice(1)];
+  else sections = [cover, ...sections];
+
+  // Close: synthesize a closing slide so every deck lands a takeaway.
+  sections.push({
+    kind: 'close',
+    text: opts.tagline || docTitle,
+    ...(opts.url || opts.footer ? { footer: [opts.footer, opts.url].filter(Boolean).join(' · ') } : {}),
+  });
+
+  const style = opts.style || 'narrative';
+  const slides = planLayout(sections, { style });
+  return {
+    theme: opts.theme || 'ink',
+    brand: opts.brand || { name: opts.brandName || docTitle, accent: '.' },
+    slides,
+  };
+}
+
+module.exports = {
+  parseBlocks,
+  blocksToSections,
+  classify,
+  toItem,
+  splitQuote,
+  composeSpec,
+};

package/lib/deck-history.js

@@ -0,0 +1,64 @@
+// Deck build history — every build appends one line to a JSONL ledger so an
+// operator can answer "which presentation did this spec become, and when?".
+// Rebuilds reuse the same presentation id under --update; this ledger is how
+// you track iterations of a spec over time.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const DEFAULT_HISTORY_PATH = path.join(os.homedir(), '.atris', 'deck-history.jsonl');
+
+// Short, stable content hash of a spec — same spec -> same hash, so you can
+// tell a no-op rebuild from a real change.
+function specHash(spec) {
+  return crypto.createHash('sha256').update(JSON.stringify(spec || {})).digest('hex').slice(0, 12);
+}
+
+function recordBuild({ spec, specPath = null, presentationId, url = null, mode = 'create', at = null }, historyPath = DEFAULT_HISTORY_PATH) {
+  const entry = {
+    at: at || new Date().toISOString(),
+    presentationId: presentationId || null,
+    url: url || (presentationId ? `https://docs.google.com/presentation/d/${presentationId}/edit` : null),
+    specPath: specPath || null,
+    specHash: specHash(spec),
+    theme: (spec && spec.theme) || null,
+    slideCount: (spec && spec.slides ? spec.slides.length : 0),
+    mode,
+  };
+  fs.mkdirSync(path.dirname(historyPath), { recursive: true });
+  fs.appendFileSync(historyPath, `${JSON.stringify(entry)}\n`);
+  return entry;
+}
+
+function readHistory(historyPath = DEFAULT_HISTORY_PATH) {
+  if (!fs.existsSync(historyPath)) return [];
+  return fs
+    .readFileSync(historyPath, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+}
+
+// Filter the ledger by a spec path (exact or basename suffix), a 12-char hash,
+// or a presentation id. No filter returns the whole ledger.
+function historyFor(query, historyPath = DEFAULT_HISTORY_PATH) {
+  const all = readHistory(historyPath);
+  if (!query) return all;
+  return all.filter((e) => (
+    e.specPath === query
+    || (e.specPath && e.specPath.endsWith(query))
+    || e.specHash === query
+    || e.presentationId === query
+  ));
+}
+
+module.exports = {
+  DEFAULT_HISTORY_PATH,
+  specHash,
+  recordBuild,
+  readHistory,
+  historyFor,
+};