stack/packages/ledger/src/ledger.mjs

import { execFileSync } from 'node:child_process';
import { createReadStream } from 'node:fs';
import { readdir, lstat } from 'node:fs/promises';
import { createInterface } from 'node:readline';
import path from 'node:path';

const DAY = 86400000;
export const UNKNOWN = 'unknown';
export class SourceError extends Error {
  constructor(message, exitCode = 1) { super(message); this.exitCode = exitCode; }
}

export function dateRange(since, until = new Date().toISOString().slice(0, 10)) {
  const parse = value => {
    const ms = Date.parse(`${value}T00:00:00Z`);
    if (!/^\d{4}-\d{2}-\d{2}$/.test(value ?? '') || !Number.isFinite(ms) ||
        new Date(ms).toISOString().slice(0, 10) !== value) {
      throw new SourceError('Dates must be valid YYYY-MM-DD values');
    }
    return ms;
  };
  const start = parse(since), end = parse(until) + DAY;
  if (end <= start) throw new SourceError('--until must not precede --since');
  return { since, until, start, end };
}
const inRange = (value, range) => {
  const ms = typeof value === 'number' ? value : Date.parse(value);
  return Number.isFinite(ms) && ms >= range.start && ms < range.end;
};
export const issueNumbers = text => [...new Set(
  [...text.matchAll(/(?:^|[^\w])#([1-9]\d*)\b/g)].map(m => Number(m[1]))
)].filter(Number.isSafeInteger);

export function readCommits(root, range) {
  let output;
  try {
    // Filter ourselves: git --since can prune history at an out-of-order date.
    output = execFileSync('git', ['log', 'refactor', '--format=%H%x00%ct%x00%s'],
      { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
  } catch { throw new SourceError('Cannot read local refactor git log'); }
  return output.split('\n').filter(Boolean).flatMap(line => {
    const [hash, seconds, subject] = line.split('\0');
    const issues = issueNumbers(subject ?? '');
    return inRange(Number(seconds) * 1000, range) && issues.length ? [{ hash, issues }] : [];
  });
}

export function readIssues(root, range, tool = 'gitea-api.sh') {
  let output;
  try {
    // Updated-since includes closes in range. No until filter: later updates must
    // not hide a close in range. One page only, as required by the brief.
    output = execFileSync(tool, ['GET', `repos/mosaicstack/stack/issues?state=all&type=issues&since=${encodeURIComponent(new Date(range.start).toISOString())}&limit=50&page=1`],
      { cwd: root, encoding: 'utf8', timeout: 60000, maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
  } catch (error) {
    // Never echo an arbitrary API response or stderr that might contain secrets.
    const reason = error.status === 3 ? 'credentials missing, unreadable, or invalid' :
      error.code === 'ENOENT' ? 'gitea-api.sh unavailable' : 'credential or Gitea request failure';
    throw new SourceError(`Issues unavailable: ${reason}; use --no-issues for unknown issue metrics`, 2);
  }
  let issues;
  try { issues = JSON.parse(output); } catch { throw new SourceError('Issues unavailable: invalid Gitea JSON', 2); }
  if (!Array.isArray(issues) || issues.some(i => !i || !Number.isSafeInteger(i.number) || i.number < 1 ||
      typeof i.title !== 'string' || !Number.isFinite(Date.parse(i.created_at)) ||
      !(i.closed_at === null || Number.isFinite(Date.parse(i.closed_at))))) {
    throw new SourceError('Issues unavailable: invalid Gitea issue records', 2);
  }
  if (issues.length >= 50) throw new SourceError('Issues unavailable: full 50-row page may be incomplete; one-call limit forbids pagination. Narrow --since or use --no-issues', 2);
  if (new Set(issues.map(i => i.number)).size !== issues.length) throw new SourceError('Issues unavailable: duplicate issue numbers', 2);
  return issues.filter(i => !i.pull_request);
}

export function messageText(content) {
  if (typeof content === 'string') return content;
  if (Array.isArray(content)) return content.filter(c => c?.type === 'text' && typeof c.text === 'string').map(c => c.text).join('\n');
  return '';
}
export function messageKind(text) {
  const firstLine = text.split(/\r?\n/, 1)[0];
  // tmux preamble from agent-send.sh: [host:session -> host:session class=x]
  const tmux = firstLine.match(/^\[([^\s:\[\]]+):([^\s\[\]]+) -> ([^\s:\[\]]+):([^\s\[\]]+)(?: class=[a-z-]+)?\](?:\s|$)/);
  // T3 header (docs/guides/T3-AGENT-COMMS.md): [from: role (id) -> to: role (id) class=x]
  const t3 = firstLine.match(/^\[from: ([^\s()\[\]]+) \(([^()\[\]]+)\) -> to: ([^\s()\[\]]+) \(([^()\[\]]+)\)(?: class=[a-z-]+)?\](?:\s|$)/);
  const sender = tmux ? tmux[2] : t3 ? t3[1] : null;
  return sender === null ? 'human' : sender === 'control-board' ? 'board' : 'agent';
}
async function directories(dir, optional = false) {
  try {
    if (!(await lstat(dir)).isDirectory()) throw new SourceError('Session source must be a real directory');
    return await readdir(dir, { withFileTypes: true });
  } catch (error) {
    if (optional && error.code === 'ENOENT') return [];
    throw new SourceError(`Cannot read ledger directory: ${dir}`);
  }
}
export async function readSessions(root, range) {
  const rows = [];
  const mentions = new Map();
  // No symlink traversal, no fleet paths, no transcript content in the report.
  const agents = (await directories(path.join(root, 'agents'))).filter(e => e.isDirectory()).sort((a, b) => a.name.localeCompare(b.name));
  const state = path.join(root, '.pi', 'state');
  // Check every source ancestor, not only the leaf directory.
  if (!(await directories(path.join(root, '.pi'), true)).length) return { rows, mentions };
  await directories(state, true);
  for (const agent of agents) {
    const seatRoot = path.join(state, agent.name);
    await directories(seatRoot, true);
    const dir = path.join(seatRoot, 'sessions');
    const files = (await directories(dir, true)).filter(e => e.isFile() && e.name.endsWith('.jsonl'));
    const row = { seat: agent.name, board: 0, agent: 0, human: 0 };
    for (const file of files) {
      const input = createReadStream(path.join(dir, file.name));
      const lines = createInterface({ input, crlfDelay: Infinity });
      let lineNumber = 0;
      try {
        for await (const line of lines) {
          lineNumber++;
          if (!line.trim()) continue;
          let entry;
          try { entry = JSON.parse(line); }
          catch { throw new SourceError(`Malformed session JSON: ${agent.name}/${file.name}:${lineNumber}`); }
          if (entry?.type !== 'message' || entry.message?.role !== 'user') continue;
          const stamp = entry.timestamp ?? entry.message.timestamp;
          if (!Number.isFinite(typeof stamp === 'number' ? stamp : Date.parse(stamp))) {
            throw new SourceError(`Invalid user-message timestamp: ${agent.name}/${file.name}:${lineNumber}`);
          }
          if (!inRange(stamp, range)) continue;
          const text = messageText(entry.message.content);
          row[messageKind(text)]++;
          for (const number of issueNumbers(text)) {
            if (!mentions.has(number)) mentions.set(number, new Set());
            mentions.get(number).add(agent.name);
          }
        }
      } finally { lines.close(); input.destroy(); }
    }
    if (row.board + row.agent + row.human) rows.push(row);
  }
  return { rows, mentions };
}
const round = value => Math.round(value * 10) / 10;
function duration(issue) {
  if (!issue) return UNKNOWN;
  if (!issue.closed_at) return 'open';
  const hours = (Date.parse(issue.closed_at) - Date.parse(issue.created_at)) / 3600000;
  return hours >= 0 ? hours : UNKNOWN;
}
export function summarize(range, commits, issues, sessions) {
  const byNumber = new Map((issues ?? []).map(i => [i.number, i]));
  const counts = new Map();
  for (const commit of commits) for (const n of commit.issues) counts.set(n, (counts.get(n) ?? 0) + 1);
  const closed = (issues ?? []).filter(i => i.closed_at && inRange(i.closed_at, range));
  const touched = new Set([...counts.keys(), ...closed.map(i => i.number)]);
  const rows = [...touched].sort((a, b) => a - b).map(number => {
    const issue = byNumber.get(number), count = counts.get(number) ?? 0;
    const hours = duration(issue);
    return { issue: number, title: issue?.title ?? UNKNOWN, opened: issue?.created_at ?? UNKNOWN,
      hoursOpen: typeof hours === 'number' ? round(hours) : hours, commits: count,
      followUps: Math.max(0, count - 1), seats: [...(sessions.mentions.get(number) ?? [])].sort() };
  });
  const hours = closed.map(duration).sort((a, b) => a - b);
  const middle = Math.floor(hours.length / 2);
  const median = hours.includes(UNKNOWN) ? UNKNOWN : hours.length ?
    round(hours.length % 2 ? hours[middle] : (hours[middle - 1] + hours[middle]) / 2) : 0;
  const human = sessions.rows.reduce((sum, r) => sum + r.human, 0);
  return { since: range.since, until: range.until, timezone: 'UTC', issues: rows, seats: sessions.rows,
    totals: { issuesClosed: issues === null ? UNKNOWN : closed.length,
      medianHoursOpen: issues === null ? UNKNOWN : median, commits: commits.length,
      followUpsPerIssue: rows.length ? round(rows.reduce((sum, r) => sum + r.followUps, 0) / rows.length) : 0,
      humanMessagesPerClosedIssue: issues === null ? UNKNOWN : closed.length ? round(human / closed.length) : human ? UNKNOWN : 0 } };
}
const clean = value => String(value).replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
const decimal = value => typeof value === 'number' ? value.toFixed(1) : value;
export function totalsLine(t) {
  return `Totals: issues closed ${t.issuesClosed} | median hours open ${decimal(t.medianHoursOpen)} | commits ${t.commits} | follow-ups per issue ${decimal(t.followUpsPerIssue)} | human messages per closed issue ${decimal(t.humanMessagesPerClosedIssue)}`;
}
export function formatTable(report) {
  return [`Ledger ${report.since} through ${report.until} UTC`,
    'Issue | Title | Opened | Hours open | Commits | Follow-ups | Seats',
    ...report.issues.map(r => [`#${r.issue}`, clean(r.title).slice(0, 48), r.opened,
      decimal(r.hoursOpen), r.commits, r.followUps, r.seats.join(', ')].join(' | ')),
    '', 'Seat | Board | Agent | Human',
    ...report.seats.map(r => [clean(r.seat), r.board, r.agent, r.human].join(' | ')),
    '', totalsLine(report.totals)].join('\n');
}