@tekyzinc/gsd-t 3.29.11 → 4.0.12

package/bin/gsd-t-token-regenerate-log.cjs

@@ -1,129 +0,0 @@
-'use strict';
-/**
- * GSD-T Token Log Regenerator (M43 D3)
- *
- * Reads `.gsd-t/metrics/token-usage.jsonl` end-to-end and writes
- * `.gsd-t/token-log.md` deterministically. Per metrics-schema-contract v2
- * §Derived Artifact, `token-log.md` is a regenerated view post-v2.
- *
- * Sort (v2 §5): startedAt asc → session_id asc → turn_id asc.
- * Numeric turn_ids sort numerically; mixed/non-numeric falls back to lex.
- *
- * Idempotent and deterministic: running twice produces byte-identical output.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const capture = require('./gsd-t-token-capture.cjs');
-const { NEW_HEADER, NEW_SEP, _formatTokensCell } = capture;
-
-function _readJsonl(jsonlPath) {
-  if (!fs.existsSync(jsonlPath)) return [];
-  const text = fs.readFileSync(jsonlPath, 'utf8');
-  const rows = [];
-  for (const line of text.split('\n')) {
-    const s = line.trim();
-    if (!s) continue;
-    try { rows.push(JSON.parse(s)); }
-    catch (_) { /* skip malformed line */ }
-  }
-  return rows;
-}
-
-function _tokenCellFromRow(row) {
-  if (!row.hasUsage) return '—';
-  const u = {
-    input_tokens: row.inputTokens || 0,
-    output_tokens: row.outputTokens || 0,
-    cache_read_input_tokens: row.cacheReadInputTokens || 0,
-    cache_creation_input_tokens: row.cacheCreationInputTokens || 0,
-    total_cost_usd: (typeof row.costUSD === 'number') ? row.costUSD : undefined,
-  };
-  return _formatTokensCell(u);
-}
-
-function _cmpStart(a, b) {
-  const av = a.startedAt || '';
-  const bv = b.startedAt || '';
-  if (av < bv) return -1;
-  if (av > bv) return 1;
-  return 0;
-}
-
-function _cmpSession(a, b) {
-  const av = a.session_id == null ? '' : String(a.session_id);
-  const bv = b.session_id == null ? '' : String(b.session_id);
-  if (av < bv) return -1;
-  if (av > bv) return 1;
-  return 0;
-}
-
-function _cmpTurn(a, b) {
-  const av = a.turn_id == null ? '' : String(a.turn_id);
-  const bv = b.turn_id == null ? '' : String(b.turn_id);
-  const an = Number(av), bn = Number(bv);
-  if (av !== '' && bv !== '' && Number.isFinite(an) && Number.isFinite(bn)) {
-    return an - bn;
-  }
-  if (av < bv) return -1;
-  if (av > bv) return 1;
-  return 0;
-}
-
-function sortRows(rows) {
-  return rows.slice().sort((a, b) =>
-    _cmpStart(a, b) || _cmpSession(a, b) || _cmpTurn(a, b)
-  );
-}
-
-function _durationCell(row) {
-  const ms = Number(row.durationMs || 0);
-  return `${Math.max(0, Math.round(ms / 1000))}s`;
-}
-
-function _renderRow(row) {
-  const tokensCell = _tokenCellFromRow(row);
-  const notes  = (row.notes  == null || row.notes  === '') ? '-' : String(row.notes).replace(/\|/g, '\\|');
-  const domain = (row.domain == null || row.domain === '') ? '-' : String(row.domain);
-  const task   = (row.task   == null || row.task   === '') ? '-' : String(row.task);
-  const ctxPct = (row.ctxPct == null) ? 'N/A' : String(row.ctxPct);
-  return `| ${row.startedAt || ''} | ${row.endedAt || ''} | ${row.command || ''} | ${row.step || ''} | ${row.model || ''} | ${_durationCell(row)} | ${tokensCell} | ${notes} | ${domain} | ${task} | ${ctxPct} |`;
-}
-
-function renderMarkdown(rows) {
-  const sorted = sortRows(rows);
-  const lines = ['# GSD-T Token Log', '', NEW_HEADER, NEW_SEP];
-  for (const r of sorted) lines.push(_renderRow(r));
-  lines.push('');
-  return lines.join('\n');
-}
-
-/**
- * Regenerate token-log.md from token-usage.jsonl.
- * @param {object} [opts]
- * @param {string} [opts.projectDir='.']
- * @param {string} [opts.jsonlPath]     override input path
- * @param {string} [opts.tokenLogPath]  override output path
- * @returns {{ wrote: string, rowCount: number }}
- */
-function regenerateLog(opts = {}) {
-  const projectDir = opts.projectDir || '.';
-  const jsonlPath = opts.jsonlPath || path.join(projectDir, '.gsd-t', 'metrics', 'token-usage.jsonl');
-  const tokenLogPath = opts.tokenLogPath || path.join(projectDir, '.gsd-t', 'token-log.md');
-  const rows = _readJsonl(jsonlPath);
-  const markdown = renderMarkdown(rows);
-  const dir = path.dirname(tokenLogPath);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(tokenLogPath, markdown);
-  return { wrote: tokenLogPath, rowCount: rows.length };
-}
-
-module.exports = {
-  regenerateLog,
-  renderMarkdown,
-  sortRows,
-  _readJsonl,
-  _renderRow,
-  _tokenCellFromRow,
-};

package/bin/gsd-t-tool-attribution.cjs

@@ -1,377 +0,0 @@
-'use strict';
-/**
- * GSD-T Per-Tool Attribution Library (M43 D2)
- *
- * Joins per-turn usage rows (`.gsd-t/metrics/token-usage.jsonl`) with tool_call
- * events (`.gsd-t/events/YYYY-MM-DD.jsonl`) and attributes each turn's tokens
- * to the tools called during that turn via the output-byte ratio algorithm.
- *
- * Contract: `.gsd-t/contracts/tool-attribution-contract.md` v1.0.0.
- *
- * Zero external deps. `.cjs` for ESM/CJS compat.
- *
- * Exports:
- *   - joinTurnsAndEvents({ turnsPath, eventsGlob, since?, milestone? })
- *   - attributeTurn(turn)
- *   - aggregateByTool(rows)
- *   - aggregateByCommand(rows)
- *   - aggregateByDomain(rows)
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// ── JSONL helpers ────────────────────────────────────────────────────
-
-function _safeParse(line) {
-  const s = (line || '').trim();
-  if (!s || s[0] !== '{') return null;
-  try { return JSON.parse(s); } catch (_) { return null; }
-}
-
-function _readJsonl(p) {
-  if (!p || !fs.existsSync(p)) return [];
-  const text = fs.readFileSync(p, 'utf8');
-  const out = [];
-  for (const line of text.split('\n')) {
-    const j = _safeParse(line);
-    if (j) out.push(j);
-  }
-  return out;
-}
-
-// ── Event-glob resolution ────────────────────────────────────────────
-
-function _resolveEventFiles(eventsGlob, since) {
-  if (Array.isArray(eventsGlob)) return eventsGlob.filter((p) => p && fs.existsSync(p));
-  if (!eventsGlob) return [];
-  let stat;
-  try { stat = fs.statSync(eventsGlob); } catch (_) { return []; }
-  if (stat.isFile()) return [eventsGlob];
-  if (stat.isDirectory()) {
-    const entries = fs.readdirSync(eventsGlob).filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f));
-    const sinceDay = since && /^\d{4}-\d{2}-\d{2}$/.test(since) ? since : null;
-    const filtered = sinceDay ? entries.filter((f) => f.slice(0, 10) >= sinceDay) : entries;
-    return filtered.sort().map((f) => path.join(eventsGlob, f));
-  }
-  return [];
-}
-
-// ── Turn-row normalization ───────────────────────────────────────────
-
-function _normalizeTurn(row) {
-  const usage = {
-    input_tokens:   Number(row.inputTokens || 0),
-    output_tokens:  Number(row.outputTokens || 0),
-    cache_read:     Number(row.cacheReadInputTokens || 0),
-    cache_creation: Number(row.cacheCreationInputTokens || 0),
-    cost_usd: (typeof row.costUSD === 'number' && Number.isFinite(row.costUSD)) ? row.costUSD : null,
-  };
-  const hasUsage = !!row.hasUsage;
-  const anyTokens = usage.input_tokens > 0 || usage.output_tokens > 0 ||
-                    usage.cache_read > 0  || usage.cache_creation > 0;
-  if (!hasUsage && !anyTokens) return null;
-  return {
-    turn_id:    row.turn_id != null ? String(row.turn_id) : null,
-    session_id: row.session_id != null ? String(row.session_id) : null,
-    ts:         row.ts || row.startedAt || null,
-    startedAt:  row.startedAt || null,
-    command:    row.command || null,
-    domain:     row.domain || null,
-    milestone:  row.milestone || null,
-    usage,
-  };
-}
-
-// ── Turn-window matching ─────────────────────────────────────────────
-
-function _assignToolCallsToTurns(turnsBySession, eventsBySession) {
-  const assignments = new Map();
-  for (const [sid, turns] of turnsBySession.entries()) {
-    if (!turns.length) continue;
-    const events = eventsBySession.get(sid) || [];
-    events.sort((a, b) => (a._ms - b._ms));
-    let ti = 0;
-    for (const ev of events) {
-      while (ti + 1 < turns.length && turns[ti + 1]._ms <= ev._ms) ti += 1;
-      const currentTurn = turns[ti];
-      if (ti === 0 && currentTurn._ms > ev._ms) continue;
-      const key = `${sid} ${currentTurn.turn_id}`;
-      if (!assignments.has(key)) assignments.set(key, []);
-      assignments.get(key).push({
-        tool_name: ev.tool_name || null,
-        ts: ev.ts,
-        bytes: Number.isFinite(ev.bytes) ? Math.max(0, Number(ev.bytes)) : 0,
-      });
-    }
-  }
-  return assignments;
-}
-
-function _parseMs(s) {
-  if (!s) return NaN;
-  if (/\dT\d/.test(s)) return Date.parse(s);
-  if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(s)) return Date.parse(s.replace(' ', 'T') + ':00');
-  const p = Date.parse(s);
-  return Number.isFinite(p) ? p : NaN;
-}
-
-// ── Public API: joinTurnsAndEvents ───────────────────────────────────
-
-function joinTurnsAndEvents(opts) {
-  opts = opts || {};
-  const turnsPath = opts.turnsPath;
-  if (!turnsPath) throw new Error('joinTurnsAndEvents: turnsPath required');
-
-  const rawTurns = _readJsonl(turnsPath);
-  const turns = [];
-  for (const row of rawTurns) {
-    if (!row.session_id || !row.turn_id) continue;
-    const n = _normalizeTurn(row);
-    if (!n) continue;
-    if (opts.since) {
-      const day = String(n.startedAt || '').slice(0, 10);
-      if (day && day < opts.since) continue;
-    }
-    if (opts.milestone) {
-      if (!n.milestone || n.milestone !== opts.milestone) continue;
-    }
-    // Prefer ts (ISO UTC — exact write time of the row) over startedAt
-    // ('YYYY-MM-DD HH:MM' local minute-precision). Events carry ISO UTC, so
-    // ts → ts comparison is timezone-safe. startedAt remains the display
-    // field but isn't the join key.
-    n._ms = _parseMs(n.ts || n.startedAt);
-    turns.push(n);
-  }
-
-  // Dedup by (session_id, turn_id).
-  const seen = new Set();
-  const turnsDedup = [];
-  for (const t of turns) {
-    const k = `${t.session_id} ${t.turn_id}`;
-    if (seen.has(k)) continue;
-    seen.add(k);
-    turnsDedup.push(t);
-  }
-
-  const turnsBySession = new Map();
-  for (const t of turnsDedup) {
-    if (!turnsBySession.has(t.session_id)) turnsBySession.set(t.session_id, []);
-    turnsBySession.get(t.session_id).push(t);
-  }
-  for (const arr of turnsBySession.values()) {
-    arr.sort((a, b) => (a._ms || 0) - (b._ms || 0));
-  }
-
-  // Build a valid (session_id, turn_id) set so we can route events that carry
-  // a turn_id straight to their turn without timestamp-window matching.
-  const turnKeys = new Set();
-  for (const t of turnsDedup) turnKeys.add(`${t.session_id} ${t.turn_id}`);
-
-  const eventFiles = _resolveEventFiles(opts.eventsGlob, opts.since);
-  const eventsBySession = new Map();
-  // Direct assignments (M43 D2-fix): events that carry turn_id bypass the
-  // timestamp-window heuristic and map straight to (session_id, turn_id).
-  const directAssignments = new Map();
-  for (const f of eventFiles) {
-    const rows = _readJsonl(f);
-    for (const e of rows) {
-      if (e.event_type !== 'tool_call') continue;
-      const sid = e.agent_id;
-      if (!sid || !turnsBySession.has(sid)) continue;
-
-      const call = {
-        tool_name: e.reasoning || null,
-        ts: e.ts,
-        bytes: Number.isFinite(e.bytes) ? e.bytes :
-               Number.isFinite(e.result_bytes) ? e.result_bytes : 0,
-      };
-
-      // Prefer direct turn_id join when the event carries it and the turn
-      // exists in the dataset. Events written before this fix won't have
-      // turn_id — they fall through to the timestamp-window matcher below.
-      if (e.turn_id) {
-        const key = `${sid} ${e.turn_id}`;
-        if (turnKeys.has(key)) {
-          if (!directAssignments.has(key)) directAssignments.set(key, []);
-          directAssignments.get(key).push(call);
-          continue;
-        }
-        // turn_id set but no matching turn row — fall through so we still
-        // attribute this event via the window matcher (defensive, rare).
-      }
-
-      if (!eventsBySession.has(sid)) eventsBySession.set(sid, []);
-      eventsBySession.get(sid).push({ ...call, _ms: _parseMs(e.ts) });
-    }
-  }
-
-  const assignments = _assignToolCallsToTurns(turnsBySession, eventsBySession);
-  // Merge direct assignments on top of the window-matched ones. Direct wins
-  // (authoritative) — both shouldn't fire for the same event.
-  for (const [key, calls] of directAssignments.entries()) {
-    if (!assignments.has(key)) assignments.set(key, []);
-    for (const c of calls) assignments.get(key).push(c);
-  }
-
-  const out = [];
-  for (const [sid, arr] of turnsBySession.entries()) {
-    for (const t of arr) {
-      const key = `${sid} ${t.turn_id}`;
-      const calls = assignments.get(key) || [];
-      out.push({
-        turn_id:    t.turn_id,
-        session_id: t.session_id,
-        ts:         t.startedAt || t.ts,
-        command:    t.command,
-        domain:     t.domain,
-        milestone:  t.milestone,
-        usage:      t.usage,
-        tool_calls: calls,
-      });
-    }
-  }
-  return out;
-}
-
-// ── Public API: attributeTurn ────────────────────────────────────────
-
-function attributeTurn(turn) {
-  if (!turn || typeof turn !== 'object') {
-    throw new Error('attributeTurn: turn object required');
-  }
-  const calls = Array.isArray(turn.tool_calls) ? turn.tool_calls : [];
-  const usage = turn.usage || {};
-  const inT  = Number(usage.input_tokens || 0);
-  const outT = Number(usage.output_tokens || 0);
-  const crT  = Number(usage.cache_read || 0);
-  const ccT  = Number(usage.cache_creation || 0);
-  const cost = (typeof usage.cost_usd === 'number' && Number.isFinite(usage.cost_usd)) ? usage.cost_usd : null;
-
-  const base = {
-    turn_id:    turn.turn_id || null,
-    session_id: turn.session_id || null,
-    command:    turn.command || null,
-    domain:     turn.domain || null,
-    milestone:  turn.milestone || null,
-    attributions: [],
-  };
-
-  if (calls.length === 0) {
-    base.attributions.push(_mkAttr('no-tool', 0, 1.0, inT, outT, crT, ccT, cost, false));
-    return base;
-  }
-
-  let totalBytes = 0;
-  const calls2 = calls.map((c) => {
-    const b = Number.isFinite(c.bytes) ? Math.max(0, Number(c.bytes)) : 0;
-    totalBytes += b;
-    return { ...c, bytes: b };
-  });
-
-  if (totalBytes === 0) {
-    const share = 1 / calls2.length;
-    for (const c of calls2) {
-      base.attributions.push(_mkAttr(
-        c.tool_name || 'unknown',
-        c.bytes,
-        share,
-        share * inT, share * outT, share * crT, share * ccT,
-        cost == null ? null : share * cost,
-        !!c.missing_tool_result,
-      ));
-    }
-    return base;
-  }
-
-  for (const c of calls2) {
-    const share = c.bytes / totalBytes;
-    const missingTR = c.bytes === 0;
-    base.attributions.push(_mkAttr(
-      c.tool_name || 'unknown',
-      c.bytes,
-      share,
-      share * inT, share * outT, share * crT, share * ccT,
-      cost == null ? null : share * cost,
-      missingTR,
-    ));
-  }
-  return base;
-}
-
-function _mkAttr(name, bytes, share, inShare, outShare, crShare, ccShare, costShare, missing) {
-  return {
-    tool_name:             name,
-    bytes_attributed:      bytes,
-    share,
-    input_tokens_share:    inShare,
-    output_tokens_share:   outShare,
-    cache_read_share:      crShare,
-    cache_creation_share:  ccShare,
-    cost_usd_share:        costShare,
-    missing_tool_result:   !!missing,
-  };
-}
-
-// ── Public API: aggregators ──────────────────────────────────────────
-
-function _aggregateBy(keyFn, joinedRows) {
-  const rows = Array.isArray(joinedRows) ? joinedRows : [];
-  const acc = new Map();
-  for (const turn of rows) {
-    const attr = attributeTurn(turn);
-    for (const a of attr.attributions) {
-      const k = keyFn(attr, a);
-      if (k == null) continue;
-      if (!acc.has(k)) {
-        acc.set(k, {
-          key: k,
-          total_input: 0,
-          total_output: 0,
-          total_cache_read: 0,
-          total_cache_creation: 0,
-          total_cost_usd: 0,
-          turn_count: 0,
-          _turnIds: new Set(),
-        });
-      }
-      const a2 = acc.get(k);
-      a2.total_input          += Number(a.input_tokens_share || 0);
-      a2.total_output         += Number(a.output_tokens_share || 0);
-      a2.total_cache_read     += Number(a.cache_read_share || 0);
-      a2.total_cache_creation += Number(a.cache_creation_share || 0);
-      a2.total_cost_usd       += Number(a.cost_usd_share || 0);
-      a2._turnIds.add(`${attr.session_id} ${attr.turn_id}`);
-    }
-  }
-  const out = [];
-  for (const v of acc.values()) {
-    v.turn_count = v._turnIds.size;
-    delete v._turnIds;
-    out.push(v);
-  }
-  out.sort((a, b) => {
-    if (b.total_cost_usd !== a.total_cost_usd) return b.total_cost_usd - a.total_cost_usd;
-    if (b.total_output   !== a.total_output)   return b.total_output   - a.total_output;
-    if (a.key < b.key) return -1;
-    if (a.key > b.key) return 1;
-    return 0;
-  });
-  return out;
-}
-
-function aggregateByTool(joinedRows)    { return _aggregateBy((_attr, a) => a.tool_name || 'unknown', joinedRows); }
-function aggregateByCommand(joinedRows) { return _aggregateBy((attr) => attr.command || 'unknown', joinedRows); }
-function aggregateByDomain(joinedRows)  { return _aggregateBy((attr) => attr.domain || 'unknown', joinedRows); }
-
-module.exports = {
-  joinTurnsAndEvents,
-  attributeTurn,
-  aggregateByTool,
-  aggregateByCommand,
-  aggregateByDomain,
-  _readJsonl,
-  _normalizeTurn,
-  _resolveEventFiles,
-  _parseMs,
-};

package/bin/gsd-t-tool-cost.cjs

@@ -1,195 +0,0 @@
-'use strict';
-/**
- * GSD-T Tool-Cost CLI (M43 D2)
- *
- * `gsd-t tool-cost [--group-by tool|command|domain] [--since YYYY-MM-DD]
- *                   [--milestone Mxx] [--format table|json]`
- *
- * Consumer of `bin/gsd-t-tool-attribution.cjs`. Zero deps.
- *
- * Exit codes: 0 success, 2 arg parse error, 3 data access error.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const attribution = require('./gsd-t-tool-attribution.cjs');
-
-function _defaultTurnsPath(projectDir) {
-  return path.join(projectDir, '.gsd-t', 'metrics', 'token-usage.jsonl');
-}
-function _defaultEventsDir(projectDir) {
-  return path.join(projectDir, '.gsd-t', 'events');
-}
-
-function parseArgs(argv) {
-  const opts = {
-    groupBy: 'tool',
-    since: null,
-    milestone: null,
-    format: 'table',
-    projectDir: process.cwd(),
-    turnsPath: null,
-    eventsGlob: null,
-    help: false,
-  };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    const take = () => argv[++i];
-    if (a === '--group-by' || a === '-g') { opts.groupBy = take(); }
-    else if (a.startsWith('--group-by=')) { opts.groupBy = a.slice('--group-by='.length); }
-    else if (a === '--since') { opts.since = take(); }
-    else if (a.startsWith('--since=')) { opts.since = a.slice('--since='.length); }
-    else if (a === '--milestone') { opts.milestone = take(); }
-    else if (a.startsWith('--milestone=')) { opts.milestone = a.slice('--milestone='.length); }
-    else if (a === '--format' || a === '-f') { opts.format = take(); }
-    else if (a.startsWith('--format=')) { opts.format = a.slice('--format='.length); }
-    else if (a === '--project-dir') { opts.projectDir = take(); }
-    else if (a.startsWith('--project-dir=')) { opts.projectDir = a.slice('--project-dir='.length); }
-    else if (a === '--turns-path') { opts.turnsPath = take(); }
-    else if (a === '--events-glob') { opts.eventsGlob = take(); }
-    else if (a === '--help' || a === '-h') { opts.help = true; }
-    else {
-      const err = new Error(`tool-cost: unknown arg: ${a}`);
-      err.exitCode = 2;
-      throw err;
-    }
-  }
-  if (!['tool', 'command', 'domain'].includes(opts.groupBy)) {
-    const err = new Error(`tool-cost: --group-by must be tool|command|domain (got: ${opts.groupBy})`);
-    err.exitCode = 2;
-    throw err;
-  }
-  if (!['table', 'json'].includes(opts.format)) {
-    const err = new Error(`tool-cost: --format must be table|json (got: ${opts.format})`);
-    err.exitCode = 2;
-    throw err;
-  }
-  return opts;
-}
-
-function helpText() {
-  return [
-    'Usage: gsd-t tool-cost [options]',
-    '',
-    'Attribute per-turn tokens/cost across the tools used in each turn.',
-    '',
-    'Options:',
-    '  --group-by tool|command|domain   Aggregation key (default: tool)',
-    '  --since YYYY-MM-DD               Only include turns on or after this day',
-    '  --milestone Mxx                  Only include turns tagged with this milestone',
-    '  --format table|json              Output format (default: table)',
-    '  --project-dir PATH               Project root (default: cwd)',
-    '  --turns-path PATH                Override token-usage.jsonl path',
-    '  --events-glob PATH               Override events dir/file',
-    '  -h, --help                       Show this help',
-    '',
-  ].join('\n');
-}
-
-// ── Rendering ────────────────────────────────────────────────────────
-
-function _fmtMoney(n) {
-  if (n == null || !Number.isFinite(n)) return '-';
-  if (n === 0) return '$0.00';
-  if (Math.abs(n) < 0.01) return `$${n.toFixed(4)}`;
-  return `$${n.toFixed(2)}`;
-}
-
-function _fmtInt(n) {
-  if (!Number.isFinite(n)) return '0';
-  return String(Math.round(Number(n))).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
-}
-
-function renderTable(agg, opts) {
-  const top = agg.slice(0, 20);
-  const header = opts.groupBy === 'tool'    ? 'Tool' :
-                 opts.groupBy === 'command' ? 'Command' :
-                                               'Domain';
-  const lines = [];
-  lines.push(`═══ Tool Cost (group-by ${opts.groupBy}) ═══`);
-  if (opts.since)     lines.push(`Since: ${opts.since}`);
-  if (opts.milestone) lines.push(`Milestone: ${opts.milestone}`);
-  lines.push('');
-  if (top.length === 0) {
-    lines.push('  (no data)');
-    return lines.join('\n');
-  }
-  lines.push(`${header.padEnd(22)} ${'Turns'.padStart(6)} ${'Input'.padStart(12)} ${'Output'.padStart(10)} ${'CacheR'.padStart(12)} ${'CacheC'.padStart(10)} ${'Cost'.padStart(10)}`);
-  lines.push('─'.repeat(22 + 1 + 6 + 1 + 12 + 1 + 10 + 1 + 12 + 1 + 10 + 1 + 10));
-  for (const r of top) {
-    lines.push(
-      `${String(r.key).padEnd(22).slice(0, 22)} ` +
-      `${String(r.turn_count).padStart(6)} ` +
-      `${_fmtInt(r.total_input).padStart(12)} ` +
-      `${_fmtInt(r.total_output).padStart(10)} ` +
-      `${_fmtInt(r.total_cache_read).padStart(12)} ` +
-      `${_fmtInt(r.total_cache_creation).padStart(10)} ` +
-      `${_fmtMoney(r.total_cost_usd).padStart(10)}`
-    );
-  }
-  return lines.join('\n');
-}
-
-function renderJson(agg) {
-  // Newline-delimited JSON, one ranker row per line (contract §consumer).
-  return agg.map((r) => JSON.stringify(r)).join('\n');
-}
-
-// ── Main ─────────────────────────────────────────────────────────────
-
-function compute(opts) {
-  const projectDir = opts.projectDir || '.';
-  const turnsPath = opts.turnsPath || _defaultTurnsPath(projectDir);
-  const eventsGlob = opts.eventsGlob || _defaultEventsDir(projectDir);
-  if (!fs.existsSync(turnsPath)) {
-    // Empty-sink case per contract — not an error.
-    return [];
-  }
-  const joined = attribution.joinTurnsAndEvents({
-    turnsPath,
-    eventsGlob,
-    since: opts.since || undefined,
-    milestone: opts.milestone || undefined,
-  });
-  let agg;
-  if (opts.groupBy === 'command')     agg = attribution.aggregateByCommand(joined);
-  else if (opts.groupBy === 'domain') agg = attribution.aggregateByDomain(joined);
-  else                                agg = attribution.aggregateByTool(joined);
-  return agg;
-}
-
-function run(argv) {
-  let opts;
-  try { opts = parseArgs(argv); }
-  catch (e) {
-    process.stderr.write(String(e.message || e) + '\n');
-    return e.exitCode || 2;
-  }
-  if (opts.help) {
-    process.stdout.write(helpText());
-    return 0;
-  }
-  let agg;
-  try { agg = compute(opts); }
-  catch (e) {
-    process.stderr.write(`tool-cost: data access error: ${e.message || e}\n`);
-    return 3;
-  }
-  const out = (opts.format === 'json') ? renderJson(agg) : renderTable(agg, opts);
-  process.stdout.write(out + '\n');
-  return 0;
-}
-
-if (require.main === module) {
-  process.exit(run(process.argv.slice(2)));
-}
-
-module.exports = {
-  parseArgs,
-  helpText,
-  renderTable,
-  renderJson,
-  compute,
-  run,
-};