ticketlens 0.1.0

package/skills/jtb/scripts/lib/attention-scorer.mjs

@@ -0,0 +1,152 @@
+/**
+ * Pure scoring logic for ticket triage.
+ * No I/O — all functions take data and return results.
+ */
+
+const BOT_PATTERNS = [
+  /^automatic\s*bot$/i,
+  /^jira\s*(software|automation)?$/i,
+  /^svn\s*commit/i,
+  /^bitbucket/i,
+  /^github/i,
+  /^gitlab/i,
+  /^jenkins/i,
+  /^bamboo/i,
+  /\bbot\b/i,
+  /\bautomation\b/i,
+];
+
+export function isBot(authorName) {
+  if (!authorName) return false;
+  return BOT_PATTERNS.some(p => p.test(authorName));
+}
+
+const VCS_COMMIT_PATTERN = /\bsvn\s*commit\b|\bcommit\b.*\brevision\b|\bgit\s*commit\b/i;
+const VCS_AUTHOR_PATTERN = /\*Author:\*\s*(\S+)/i;
+
+/**
+ * Check if a bot comment is a VCS commit by the current user.
+ * Jira SVN/Git integrations post commits as bot users (e.g. "Automatic Bot")
+ * but the commit body contains the actual author.
+ */
+export function isBotCommitByUser(comment, currentUser) {
+  if (!comment?.body || !currentUser) return false;
+  if (!VCS_COMMIT_PATTERN.test(comment.body)) return false;
+  const match = comment.body.match(VCS_AUTHOR_PATTERN);
+  if (!match) return false;
+  const commitAuthor = match[1].toLowerCase();
+  return (
+    (currentUser.name && commitAuthor === currentUser.name.toLowerCase()) ||
+    (currentUser.displayName && commitAuthor === currentUser.displayName.toLowerCase())
+  );
+}
+
+export function isFromCurrentUser(comment, currentUser) {
+  if (!comment || !currentUser) return false;
+  // Cloud: match by accountId
+  if (currentUser.accountId && comment.authorAccountId) {
+    return comment.authorAccountId === currentUser.accountId;
+  }
+  // Server: match by name/username
+  if (currentUser.name && comment.authorName) {
+    return comment.authorName === currentUser.name;
+  }
+  // Fallback: displayName match
+  if (currentUser.displayName && comment.author) {
+    return comment.author === currentUser.displayName;
+  }
+  return false;
+}
+
+/**
+ * Get the effective "last comment" considering bot VCS commits.
+ * Walk backwards through all comments (including bots).
+ * - If the last comment is a bot VCS commit by the current user, treat as user's response.
+ * - If the last comment is any other bot, skip it.
+ * - If a human comment, use it directly.
+ */
+export function findLastEffectiveComment(comments, currentUser) {
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const c = comments[i];
+    if (!isBot(c.author)) return { comment: c, fromCurrentUser: isFromCurrentUser(c, currentUser) };
+    if (isBotCommitByUser(c, currentUser)) return { comment: c, fromCurrentUser: true };
+    // Other bot comment — skip and keep looking
+  }
+  return { comment: null, fromCurrentUser: false };
+}
+
+export function scoreAttention(ticket, currentUser, opts = {}) {
+  const { staleDays = 5, now = new Date() } = opts;
+
+  const { comment: lastComment, fromCurrentUser } = findLastEffectiveComment(
+    ticket.comments || [], currentUser
+  );
+
+  // Check needs-response: last effective comment is NOT from current user
+  if (lastComment && !fromCurrentUser) {
+    const commentDate = lastComment.created ? new Date(lastComment.created) : null;
+    const daysSinceComment = commentDate ? (now - commentDate) / (1000 * 60 * 60 * 24) : 0;
+
+    // If the unanswered comment is older than the stale threshold, treat as aging
+    // rather than urgent — the window to respond promptly has passed.
+    if (daysSinceComment >= staleDays) {
+      return {
+        ticketKey: ticket.key,
+        summary: ticket.summary,
+        status: ticket.status,
+        urgency: 'aging',
+        reason: `${lastComment.author} commented ${Math.floor(daysSinceComment)}d ago`,
+        lastComment,
+        daysSinceUpdate: Math.floor(daysSinceComment),
+      };
+    }
+
+    return {
+      ticketKey: ticket.key,
+      summary: ticket.summary,
+      status: ticket.status,
+      urgency: 'needs-response',
+      reason: `${lastComment.author} commented`,
+      lastComment,
+    };
+  }
+
+  // Check aging: no activity for >= staleDays
+  const updatedDate = ticket.updated ? new Date(ticket.updated) : null;
+  if (updatedDate) {
+    const daysSinceUpdate = (now - updatedDate) / (1000 * 60 * 60 * 24);
+    if (daysSinceUpdate >= staleDays) {
+      return {
+        ticketKey: ticket.key,
+        summary: ticket.summary,
+        status: ticket.status,
+        urgency: 'aging',
+        reason: `No activity for ${Math.floor(daysSinceUpdate)} days`,
+        lastComment,
+        daysSinceUpdate: Math.floor(daysSinceUpdate),
+      };
+    }
+  }
+
+  return {
+    ticketKey: ticket.key,
+    summary: ticket.summary,
+    status: ticket.status,
+    urgency: 'clear',
+    reason: 'Up to date',
+    lastComment,
+  };
+}
+
+const URGENCY_ORDER = { 'needs-response': 0, 'aging': 1, 'clear': 2 };
+
+export function sortByUrgency(scores) {
+  return [...scores].sort((a, b) => {
+    const orderDiff = URGENCY_ORDER[a.urgency] - URGENCY_ORDER[b.urgency];
+    if (orderDiff !== 0) return orderDiff;
+    // Within same urgency, sort by most recent activity (lastComment date or ticket updated)
+    const dateA = a.lastComment?.created ? new Date(a.lastComment.created) : new Date(0);
+    const dateB = b.lastComment?.created ? new Date(b.lastComment.created) : new Date(0);
+    return dateB - dateA; // most recent first
+  });
+}

package/skills/jtb/scripts/lib/banner.mjs

@@ -0,0 +1,201 @@
+/**
+ * Session banner for TicketLens CLI.
+ * Renders a colored header box with embedded spinner, and a footer for errors.
+ * Writes to stderr so stdout stays clean for piped output.
+ */
+
+import { createStyler } from './ansi.mjs';
+import { getVersion } from './config.mjs';
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+const visibleLength = (str) => str.replace(ANSI_RE, '').length;
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL = 80;
+
+
+function buildBox(lines, { s, borderColor = 'cyan' }) {
+  const maxVisible = lines.reduce((max, l) => Math.max(max, visibleLength(l)), 0);
+  const innerWidth = maxVisible + 2;
+
+  const padLine = (line) => {
+    const pad = innerWidth - visibleLength(line) - 1;
+    return ' ' + line + ' '.repeat(Math.max(0, pad));
+  };
+
+  const bc = s[borderColor] || s.cyan;
+  const top = bc('╭' + '─'.repeat(innerWidth) + '╮');
+  const bot = bc('╰' + '─'.repeat(innerWidth) + '╯');
+  const body = lines.map(l => bc('│') + padLine(l) + bc('│')).join('\n');
+
+  return { top, body, bot, innerWidth, bc };
+}
+
+export function createSession(conn, { stream = process.stderr } = {}) {
+  const isTTY = stream.isTTY;
+  const s = createStyler({ isTTY });
+  const version = getVersion();
+
+  const hostname = conn.baseUrl ? new URL(conn.baseUrl).hostname : 'unknown';
+  const profileLabel = conn.profileName || 'default';
+  const userLabel = conn.email || (conn.pat ? 'token auth' : 'unknown');
+
+  const jiraLabel = conn.profileName
+    ? conn.profileName.charAt(0).toUpperCase() + conn.profileName.slice(1) + ' Jira'
+    : hostname;
+
+  // Pre-build the info lines to calculate box width including status line.
+  const infoLines = [
+    `${s.bold(s.brand('◆ TicketLens'))} ${s.dim(`v${version}`)}`,
+    `  ${s.dim('Profile:')}  ${profileLabel}`,
+    `  ${s.dim('Server:')}   ${hostname}`,
+    `  ${s.dim('User:')}     ${userLabel}`,
+  ];
+  // Reserve width for the longest possible status message (failure is longer than success).
+  const allLines = [...infoLines, '', `● Connection to ${jiraLabel} failed.`];
+  const maxVisible = allLines.reduce((max, l) => Math.max(max, visibleLength(l)), 0);
+  const innerWidth = maxVisible + 2;
+
+  const bc = s.brand; // border color
+  let timer = null;
+  let boxOpen = false;
+
+  const padInner = (line) => {
+    const pad = innerWidth - visibleLength(line) - 1;
+    return ' ' + line + ' '.repeat(Math.max(0, pad));
+  };
+
+  const writeLine = (content) => {
+    stream.write(bc('│') + padInner(content) + bc('│'));
+  };
+
+  return {
+    /** Render a full pre-connection banner (non-TTY fallback). */
+    _plainBanner() {
+      stream.write(`[TicketLens v${version}]  profile: ${profileLabel}  server: ${hostname}\n`);
+    },
+
+    /** Start the header: renders full closed box with spinner on status line. */
+    spin(message) {
+      if (!isTTY) {
+        this._plainBanner();
+        return this;
+      }
+
+      const bot = bc('╰' + '─'.repeat(innerWidth) + '╯');
+
+      // Top border + info lines + separator
+      const top = bc('╭' + '─'.repeat(innerWidth) + '╮');
+      stream.write(top + '\n');
+      for (const line of infoLines) {
+        writeLine(line);
+        stream.write('\n');
+      }
+      // Blank separator line
+      writeLine('');
+      stream.write('\n');
+      boxOpen = true;
+
+      // Render initial spinner line + bottom border (box appears closed)
+      let frame = 0;
+      const writeSpinnerAndBorder = () => {
+        const content = `${s.brand(SPINNER_FRAMES[frame])} ${message}`;
+        writeLine(content);
+        stream.write('\n');
+        stream.write(bot);
+      };
+
+      stream.write('\x1b[?25l'); // hide cursor
+      writeSpinnerAndBorder();
+
+      timer = setInterval(() => {
+        frame = (frame + 1) % SPINNER_FRAMES.length;
+        // Clear bottom border line, move up, clear spinner line, redraw both
+        stream.write('\r\x1b[2K\x1b[A\r\x1b[2K');
+        writeSpinnerAndBorder();
+      }, SPINNER_INTERVAL);
+
+      return this;
+    },
+
+    /** Stop spinner, show green status, redraw final box. */
+    connected() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (!isTTY) return this;
+
+      const bot = bc('╰' + '─'.repeat(innerWidth) + '╯');
+      const status = `${s.green('●')} Connected to ${jiraLabel}.`;
+      // Clear bottom border line, move up, clear spinner line, redraw both
+      stream.write('\r\x1b[2K\x1b[A\r\x1b[2K');
+      writeLine(status);
+      stream.write('\n');
+      stream.write(bot + '\n');
+      stream.write('\x1b[?25h'); // restore cursor
+      boxOpen = false;
+      return this;
+    },
+
+    /** Stop spinner, show red status, redraw final box. */
+    failed() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (!isTTY) return this;
+
+      const bot = bc('╰' + '─'.repeat(innerWidth) + '╯');
+      const status = `${s.red('●')} Connection to ${jiraLabel} failed.`;
+      // Clear bottom border line, move up, clear spinner line, redraw both
+      stream.write('\r\x1b[2K\x1b[A\r\x1b[2K');
+      writeLine(status);
+      stream.write('\n');
+      stream.write(bot + '\n');
+      stream.write('\x1b[?25h'); // restore cursor
+      boxOpen = false;
+      return this;
+    },
+
+    /** Render a colored footer box for errors or info messages. */
+    footer(message, type = 'error', hint = null) {
+      if (!isTTY) {
+        stream.write(`${message}\n`);
+        if (hint) stream.write(`  ${hint}\n`);
+        return this;
+      }
+
+      const icon = type === 'error' ? s.red('✖') : s.brand('ℹ');
+      const colorFn = type === 'error' ? s.red : s.dim;
+      const contentLine = `${icon} ${message}`;
+      const lines = [contentLine];
+      if (hint) lines.push(`  ${s.dim(hint)}`);
+
+      const maxContent = lines.reduce((max, l) => Math.max(max, visibleLength(l)), 0);
+      const footerWidth = Math.max(maxContent + 2, innerWidth);
+
+      const padFooter = (line) => {
+        const pad = footerWidth - visibleLength(line) - 1;
+        return ' ' + line + ' '.repeat(Math.max(0, pad));
+      };
+
+      const top = colorFn('╭' + '─'.repeat(footerWidth) + '╮');
+      const body = lines.map(l => colorFn('│') + padFooter(l) + colorFn('│')).join('\n');
+      const bot = colorFn('╰' + '─'.repeat(footerWidth) + '╯');
+
+      stream.write(`${top}\n${body}\n${bot}\n`);
+      return this;
+    },
+
+    /** Expose for external use (e.g. scan spinner outside box). */
+    get styler() { return s; },
+    get label() { return jiraLabel; },
+  };
+}
+
+// Keep backward compat for tests — renderBanner delegates to createSession.
+export function renderBanner(conn, opts = {}) {
+  const session = createSession(conn, opts);
+  session._plainBanner();
+}

package/skills/jtb/scripts/lib/brief-assembler.mjs

@@ -0,0 +1,137 @@
+/**
+ * Assembles a normalized ticket into a structured markdown TicketBrief.
+ */
+
+import { formatTable } from './table-formatter.mjs';
+import { formatSize } from './attachment-downloader.mjs';
+import { timeAgo, truncate, stripCr } from './config.mjs';
+
+export function assembleBrief(ticket, codeRefs = null) {
+  const sections = [];
+  sections.push(`# ${ticket.key}: ${ticket.summary}`);
+
+  const meta = [`**Type:** ${ticket.type}`, `**Status:** ${ticket.status}`, `**Priority:** ${ticket.priority}`, `**Assignee:** ${ticket.assignee ?? 'Unassigned'}`, `**Reporter:** ${ticket.reporter ?? 'Unknown'}`];
+  if (ticket.created) meta.push(`**Created:** ${ticket.created.split('T')[0]}`);
+  if (ticket.updated) meta.push(`**Updated:** ${ticket.updated.split('T')[0]}`);
+  sections.push(meta.join(' | '));
+
+  if (ticket.description) {
+    sections.push(`## Description\n\n${stripCr(ticket.description)}`);
+  }
+
+  if (ticket.comments?.length > 0) {
+    const commentLines = ticket.comments.map(c => {
+      const date = c.created ? c.created.split('T')[0] : 'unknown';
+      return `### **${c.author}** (${date})\n\n${c.body.replace(/\r/g, '')}`;
+    });
+    sections.push(`## Comments\n\n${commentLines.join('\n\n---\n\n')}`);
+  }
+
+  if (ticket.linkedTicketDetails?.length > 0) {
+    const linkedSections = ticket.linkedTicketDetails.map(lt => {
+      const parts = [`### ${lt.key}: ${lt.summary}`, `**Type:** ${lt.type} | **Status:** ${lt.status}`];
+      if (lt.description) parts.push(stripCr(lt.description));
+      if (lt.comments?.length > 0) {
+        const cmts = lt.comments.map(c => {
+          const date = c.created ? c.created.split('T')[0] : 'unknown';
+          return `**${c.author}** (${date}): ${c.body.replace(/\r/g, '')}`;
+        });
+        parts.push(cmts.join('\n\n'));
+      }
+      return parts.join('\n\n');
+    });
+    sections.push(`## Linked Tickets\n\n${linkedSections.join('\n\n---\n\n')}`);
+  }
+
+  if (codeRefs) {
+    const categories = [
+      ['File Paths', codeRefs.filePaths],
+      ['Methods', codeRefs.methods],
+      ['Classes', codeRefs.classes],
+      ['Git SHAs', codeRefs.shas],
+      ['SVN Revisions', codeRefs.svnRevisions],
+      ['Branches', codeRefs.branches],
+      ['Namespaces', codeRefs.namespaces],
+    ];
+    const filled = categories
+      .filter(([, items]) => items?.length > 0)
+      .map(([label, items]) => `**${label}:** ${items.map(i => '`' + i + '`').join(', ')}`);
+    if (filled.length > 0) {
+      sections.push(`## Code References\n\n${filled.join('\n')}`);
+    }
+  }
+
+  if (ticket.attachments?.length > 0) {
+    const lines = ticket.attachments.map(a => {
+      const r = (ticket.localAttachments ?? []).find(x => x.filename === a.filename);
+      const sz = formatSize(a.size);
+      if (r?.localPath) {
+        const note = r.skipReason === 'cached' ? ', cached' : '';
+        return `- \`${r.localPath}\` _(${a.filename}, ${sz}${note})_`;
+      }
+      if (r?.skipReason === 'too-large') return `- ${a.filename} _(${sz} — exceeds 10 MB limit)_`;
+      if (r?.skipReason === 'limit')     return `- ${a.filename} _(${sz} — attachment limit reached)_`;
+      if (r?.skipReason === 'error')     return `- ${a.filename} _(${sz} — download failed: ${r.error})_`;
+      return `- ${a.filename} _(${sz})_`;
+    });
+    sections.push(`## Attachments\n\n${lines.join('\n')}`);
+  }
+
+  return sections.join('\n\n');
+}
+
+export function assembleTriageSummary(scoredTickets, opts = {}) {
+  const { staleDays = 5, baseUrl } = opts;
+  const browseUrl = baseUrl ? baseUrl.replace(/\/$/, '') + '/browse/' : null;
+  const actionable = scoredTickets.filter(t => t.urgency !== 'clear');
+
+  if (actionable.length === 0) {
+    return 'All clear — no tickets need your attention right now.';
+  }
+
+  const sections = [];
+  sections.push(`Tickets Needing Your Attention (${actionable.length} found)`);
+
+  const needsResponse = actionable.filter(t => t.urgency === 'needs-response');
+  const aging = actionable.filter(t => t.urgency === 'aging');
+  const allKeys = [];
+
+  if (needsResponse.length > 0) {
+    const tableRows = needsResponse.map((t, i) => {
+      allKeys.push(t.ticketKey);
+      const ago = t.lastComment ? timeAgo(t.lastComment.created) : '';
+      const commenter = t.lastComment?.author ?? 'Unknown';
+      const snippet = t.lastComment?.body ? truncate(t.lastComment.body, 60) : '';
+      return [String(i + 1), t.ticketKey, truncate(t.summary, 50), t.status, commenter, ago, snippet];
+    });
+    const table = formatTable(
+      ['#', 'Ticket', 'Summary', 'Status', 'From', 'When', 'Comment'],
+      tableRows,
+      { maxWidths: { 2: 50, 6: 60 } },
+    );
+    sections.push(`Needs Response (${needsResponse.length})\n\n${table}`);
+  }
+
+  if (aging.length > 0) {
+    const agingOffset = needsResponse.length;
+    const tableRows = aging.map((t, i) => {
+      allKeys.push(t.ticketKey);
+      const days = t.daysSinceUpdate ?? '?';
+      return [String(agingOffset + i + 1), t.ticketKey, truncate(t.summary, 50), t.status, `${days}d`];
+    });
+    const table = formatTable(
+      ['#', 'Ticket', 'Summary', 'Status', 'Stale'],
+      tableRows,
+      { maxWidths: { 2: 50 } },
+    );
+    sections.push(`Aging — no activity > ${staleDays} days (${aging.length})\n\n${table}`);
+  }
+
+  if (browseUrl && allKeys.length > 0) {
+    const links = allKeys.map((k, i) => `[${i + 1}] ${k}: ${browseUrl}${k}`);
+    sections.push(`Quick Links\n\n${links.join('\n')}`);
+  }
+
+  return sections.join('\n\n');
+}
+

package/skills/jtb/scripts/lib/brief-cache.mjs

@@ -0,0 +1,137 @@
+/**
+ * Brief data cache — stores full normalized ticket JSON so repeat fetches
+ * skip the Jira API call entirely.
+ *
+ * Path:   ~/.ticketlens/cache/PROFILE/TICKET-KEY/brief.json
+ * Format: { fetchedAt, depth, ticket }
+ * TTL:    4 hours (bypassed by --no-cache)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+export const BRIEF_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours (default)
+export const DEFAULT_BRIEF_TTL = '4h'; // human-readable default for display/config
+
+/**
+ * Returns the absolute path to the brief cache file for a given ticket + profile.
+ */
+export function briefCachePath(ticketKey, profileName, configDir = DEFAULT_CONFIG_DIR) {
+  const safeProfile = (profileName || '_default').replace(/[^a-zA-Z0-9_\-]/g, '_');
+  const safeKey = ticketKey.replace(/[^a-zA-Z0-9_\-]/g, '_');
+  return path.join(configDir, 'cache', safeProfile, safeKey, 'brief.json');
+}
+
+/**
+ * Reads a cached brief. Returns null on:
+ * - cache miss
+ * - expired TTL
+ * - cached depth is less than the requested depth
+ *
+ * @param {string} ticketKey
+ * @param {string|null} profileName
+ * @param {number} depth
+ * @param {string} [configDir]
+ * @param {number} [ttlMs] - override TTL in ms; defaults to BRIEF_TTL_MS (4h)
+ * Returns { ticket, fetchedAt, cachedDepth } on hit.
+ */
+export function readBriefCache(ticketKey, profileName, depth, configDir = DEFAULT_CONFIG_DIR, ttlMs = BRIEF_TTL_MS) {
+  const filePath = briefCachePath(ticketKey, profileName, configDir);
+  if (!fs.existsSync(filePath)) return null;
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  const age = Date.now() - new Date(data.fetchedAt).getTime();
+  if (age > ttlMs) {
+    try { fs.unlinkSync(filePath); } catch { /* non-fatal */ }
+    return null;
+  }
+
+  // Serve cache only if cached depth covers the requested depth
+  if ((data.depth ?? 0) < depth) return null;
+
+  return { ticket: data.ticket, fetchedAt: data.fetchedAt, cachedDepth: data.depth };
+}
+
+/**
+ * Writes a normalized ticket to the brief cache.
+ * Non-fatal — a write failure does not affect the output.
+ */
+export function writeBriefCache(ticketKey, profileName, depth, ticket, configDir = DEFAULT_CONFIG_DIR) {
+  const filePath = briefCachePath(ticketKey, profileName, configDir);
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify({ fetchedAt: new Date().toISOString(), depth, ticket }));
+  } catch {
+    // Non-fatal
+  }
+}
+
+/**
+ * Removes the brief cache file for a specific ticket + profile.
+ */
+export function clearBriefCache(ticketKey, profileName, configDir = DEFAULT_CONFIG_DIR) {
+  const filePath = briefCachePath(ticketKey, profileName, configDir);
+  try {
+    if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+  } catch { /* non-fatal */ }
+}
+
+/**
+ * Returns all brief cache entries across all profiles.
+ * Each entry: { profileName, ticketKey, filePath, size, mtimeMs, fetchedAt, depth }
+ */
+export function getBriefCacheEntries(configDir = DEFAULT_CONFIG_DIR) {
+  const cacheDir = path.join(configDir, 'cache');
+  if (!fs.existsSync(cacheDir)) return [];
+
+  const entries = [];
+  let profileDirs;
+  try {
+    profileDirs = fs.readdirSync(cacheDir).filter(d => {
+      try { return fs.statSync(path.join(cacheDir, d)).isDirectory(); } catch { return false; }
+    });
+  } catch { return []; }
+
+  for (const profileName of profileDirs) {
+    const profileDir = path.join(cacheDir, profileName);
+    let ticketDirs;
+    try { ticketDirs = fs.readdirSync(profileDir); } catch { continue; }
+
+    for (const ticketKey of ticketDirs) {
+      const briefFile = path.join(profileDir, ticketKey, 'brief.json');
+      if (!fs.existsSync(briefFile)) continue;
+      try {
+        const stat = fs.statSync(briefFile);
+        let fetchedAt = null;
+        let depth = null;
+        try {
+          const data = JSON.parse(fs.readFileSync(briefFile, 'utf8'));
+          fetchedAt = data.fetchedAt ?? null;
+          depth = data.depth ?? null;
+        } catch { /* use nulls */ }
+        entries.push({ profileName, ticketKey, filePath: briefFile, size: stat.size, mtimeMs: stat.mtimeMs, fetchedAt, depth });
+      } catch { /* deleted between readdir and stat */ }
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Human-readable age string from an ISO timestamp.
+ */
+export function briefCacheAge(fetchedAt) {
+  const ms = Date.now() - new Date(fetchedAt).getTime();
+  const mins = Math.floor(ms / 60000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}