@swarmdo/cli 1.29.0 → 1.30.0

package/dist/src/usage/limits.js

@@ -0,0 +1,134 @@
+/**
+ * limits.ts — forecast when a Claude Code usage window will hit its cap.
+ *
+ * Claude Code passes an official `rate_limits` payload to statusline scripts:
+ * for the rolling 5-hour and 7-day windows it reports `used_percentage` and
+ * `resets_at`. This is the projection layer on top — at the current burn rate,
+ * when will the window hit 100%, and does that land before the window resets?
+ * ("at this pace you hit the weekly cap Thu 14:00, 6h before it resets").
+ *
+ * Pure + deterministic: it takes a normalized window state + an injected `now`
+ * (the statusline shim maps the raw payload to WindowState — see #46), so the
+ * projection math is unit-tested with zero clock or wire-format coupling.
+ */
+/** Rolling-window durations Claude Code reports (5-hour + 7-day caps). */
+export const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
+export const SEVEN_DAY_MS = 7 * 24 * 60 * 60 * 1000;
+/** Coerce an epoch-seconds, epoch-ms, or ISO-string timestamp to epoch ms. */
+function toEpochMs(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v < 1e12 ? v * 1000 : v; // secs vs ms
+    if (typeof v === 'string') {
+        const t = Date.parse(v);
+        return Number.isNaN(t) ? null : t;
+    }
+    return null;
+}
+function pickWindow(obj, windowMs, label) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const o = obj;
+    const used = (o.used_percentage ?? o.usedPercentage);
+    const resetsAtMs = toEpochMs(o.resets_at ?? o.resetsAt);
+    if (typeof used !== 'number' || !Number.isFinite(used) || resetsAtMs === null)
+        return null;
+    return { label, state: { usedPercentage: Math.max(0, Math.min(100, used)), windowMs, resetsAtMs } };
+}
+/**
+ * Map Claude Code's statusline `rate_limits` payload to normalized windows.
+ * Tolerant of shape drift: accepts the payload bare or wrapped in `rate_limits`,
+ * snake_case or camelCase keys, and epoch-seconds / epoch-ms / ISO `resets_at`.
+ * Windows missing usage or a reset time are dropped. Pure.
+ */
+export function parseRateLimits(payload) {
+    const p = payload && typeof payload === 'object' ? payload : {};
+    const rl = (p.rate_limits ?? p.rateLimits ?? p);
+    const out = [];
+    const w5 = pickWindow(rl.five_hour ?? rl.fiveHour, FIVE_HOUR_MS, '5h');
+    const w7 = pickWindow(rl.seven_day ?? rl.sevenDay, SEVEN_DAY_MS, '7d');
+    if (w5)
+        out.push(w5);
+    if (w7)
+        out.push(w7);
+    return out;
+}
+/**
+ * Forecast a single window. Burn rate is `usedPercentage / elapsed`, where
+ * elapsed = now − windowStart and windowStart = resetsAt − windowMs. Pure.
+ */
+export function forecastWindow(w, nowMs, opts = {}) {
+    const warnPct = opts.warnPct ?? 80;
+    const used = w.usedPercentage;
+    const msToReset = Math.max(0, w.resetsAtMs - nowMs);
+    const windowStartMs = w.resetsAtMs - w.windowMs;
+    const elapsed = nowMs - windowStartMs;
+    let exhaustionMs = null;
+    if (used >= 100) {
+        // already exhausted — mark exhaustion as "now"
+        exhaustionMs = nowMs;
+    }
+    else if (used > 0 && elapsed > 0) {
+        const msTo100 = ((100 - used) * elapsed) / used; // (remaining%) / (used%/elapsed)
+        exhaustionMs = nowMs + msTo100;
+    }
+    const willExhaust = exhaustionMs !== null && exhaustionMs <= w.resetsAtMs;
+    const status = used >= 100 ? 'over' : (willExhaust || used >= warnPct) ? 'warn' : 'ok';
+    return { usedPercentage: used, resetsAtMs: w.resetsAtMs, msToReset, exhaustionMs, willExhaust, status };
+}
+/** Worst status across windows (over > warn > ok). Pure. */
+export function worstStatus(forecasts) {
+    const rank = { ok: 0, warn: 1, over: 2 };
+    return forecasts.reduce((acc, f) => (rank[f.status] > rank[acc] ? f.status : acc), 'ok');
+}
+/**
+ * The binding window — the one that constrains you first. A window projected to
+ * exhaust before reset outranks one that won't; among those that will, the
+ * earlier exhaustion wins; otherwise the higher used_percentage. null for [].
+ */
+export function bindingWindow(forecasts) {
+    if (forecasts.length === 0)
+        return null;
+    return [...forecasts].sort((a, b) => {
+        if (a.willExhaust !== b.willExhaust)
+            return a.willExhaust ? -1 : 1;
+        if (a.willExhaust && b.willExhaust)
+            return a.exhaustionMs - b.exhaustionMs;
+        return b.usedPercentage - a.usedPercentage;
+    })[0];
+}
+/** Compact human duration for a ms span, e.g. 9000000 → "2h30m", 90000 → "1m". */
+export function humanizeMs(ms) {
+    if (ms <= 0)
+        return '0m';
+    const totalMin = Math.floor(ms / 60_000);
+    const d = Math.floor(totalMin / 1440);
+    const h = Math.floor((totalMin % 1440) / 60);
+    const m = totalMin % 60;
+    if (d > 0)
+        return `${d}d${h > 0 ? `${h}h` : ''}`;
+    if (h > 0)
+        return `${h}h${m > 0 ? `${m}m` : ''}`;
+    return `${m}m`;
+}
+/** Ultra-compact one-line indicator for a statusline, e.g. "5h 72%⚠ · 7d 12%".
+ * `!` marks an over-cap window, `⚠` an at-risk one. Pure. */
+export function formatLimitSegment(forecasts) {
+    if (forecasts.length === 0)
+        return 'limits: n/a';
+    const mark = (s) => (s === 'over' ? '!' : s === 'warn' ? '⚠' : '');
+    return forecasts.map(({ label, f }) => `${label} ${Math.round(f.usedPercentage)}%${mark(f.status)}`).join(' · ');
+}
+/** One-line summary for a window, e.g. "5h window: 42% used, resets in 2h14m —
+ * on pace to hit the cap in ~1h20m (before reset)". `label` names the window. */
+export function formatForecast(label, f, nowMs) {
+    const head = `${label}: ${Math.round(f.usedPercentage)}% used, resets in ${humanizeMs(f.msToReset)}`;
+    if (f.status === 'over')
+        return `${head} — CAP REACHED`;
+    if (f.willExhaust && f.exhaustionMs !== null) {
+        const inMs = Math.max(0, f.exhaustionMs - nowMs);
+        const before = humanizeMs(f.resetsAtMs - f.exhaustionMs);
+        return `${head} — on pace to hit the cap in ~${humanizeMs(inMs)} (${before} before reset)`;
+    }
+    return `${head} — on pace to stay under the cap`;
+}
+//# sourceMappingURL=limits.js.map

package/dist/src/usage/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../../src/usage/limits.ts"],"names":[],"mappings":"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"}

package/dist/src/usage/reflect-html.d.ts

@@ -0,0 +1,23 @@
+/**
+ * reflect-html.ts — render a Reflection (see reflect.ts) into a self-contained,
+ * shareable HTML dashboard for `swarmdo usage reflect --html`.
+ *
+ * Pure + deterministic: it takes an already-computed Reflection and returns a
+ * complete HTML document string with all CSS inlined (no external requests, no
+ * clock — any timestamp is passed in), so it unit-tests without a browser or a
+ * network. Every user-controlled string (model ids, project paths) is HTML-
+ * escaped. See #47.
+ */
+import type { Reflection } from './reflect.js';
+/** HTML-escape a string for safe interpolation into text or attributes. */
+export declare function escapeHtml(s: string): string;
+/** Render the retrospective to a complete self-contained HTML document. Pure. */
+export declare function renderReflectionHtml(r: Reflection, opts?: {
+    generatedAt?: string;
+    delegation?: {
+        taskCalls: number;
+        toolCalls: number;
+        ratio: number;
+    };
+}): string;
+//# sourceMappingURL=reflect-html.d.ts.map

package/dist/src/usage/reflect-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect-html.d.ts","sourceRoot":"","sources":["../../../src/usage/reflect-html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAoCD,iFAAiF;AACjF,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,UAAU,EACb,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAO,GACxG,MAAM,CA+CR"}

package/dist/src/usage/reflect-html.js

@@ -0,0 +1,94 @@
+/**
+ * reflect-html.ts — render a Reflection (see reflect.ts) into a self-contained,
+ * shareable HTML dashboard for `swarmdo usage reflect --html`.
+ *
+ * Pure + deterministic: it takes an already-computed Reflection and returns a
+ * complete HTML document string with all CSS inlined (no external requests, no
+ * clock — any timestamp is passed in), so it unit-tests without a browser or a
+ * network. Every user-controlled string (model ids, project paths) is HTML-
+ * escaped. See #47.
+ */
+/** HTML-escape a string for safe interpolation into text or attributes. */
+export function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+const num = (n) => n.toLocaleString('en-US');
+const pct = (x) => `${Math.round(x * 100)}%`;
+/** A labelled proportional bar (width is % of the largest value in its group). */
+function bar(label, valueText, fillPct) {
+    const w = Math.max(0, Math.min(100, fillPct));
+    return `<div class="bar"><div class="bar-label" title="${escapeHtml(label)}">${escapeHtml(label)}</div>`
+        + `<div class="bar-track"><div class="bar-fill" style="width:${w.toFixed(1)}%"></div></div>`
+        + `<div class="bar-val">${escapeHtml(valueText)}</div></div>`;
+}
+function shareBars(rows) {
+    if (!rows.length)
+        return '<p class="empty">—</p>';
+    const max = Math.max(...rows.map((r) => r.costUsd), 0) || 1;
+    return rows.map((r) => bar(r.model, `${usd(r.costUsd)} · ${pct(r.pct)}`, (r.costUsd / max) * 100)).join('');
+}
+function hourBars(hist) {
+    if (!hist.some((v) => v > 0))
+        return '<p class="empty">—</p>';
+    const max = Math.max(...hist) || 1;
+    const cells = hist.map((v, h) => {
+        const hpct = (v / max) * 100;
+        return `<div class="hour" title="${String(h).padStart(2, '0')}:00 — ${usd(v)}">`
+            + `<div class="hour-bar" style="height:${hpct.toFixed(1)}%"></div>`
+            + `<div class="hour-tick">${h % 6 === 0 ? String(h).padStart(2, '0') : ''}</div></div>`;
+    }).join('');
+    return `<div class="hours">${cells}</div>`;
+}
+function stat(label, value) {
+    return `<div class="stat"><div class="stat-val">${escapeHtml(value)}</div><div class="stat-label">${escapeHtml(label)}</div></div>`;
+}
+/** Render the retrospective to a complete self-contained HTML document. Pure. */
+export function renderReflectionHtml(r, opts = {}) {
+    const arrow = r.trend.direction === 'up' ? '↑' : r.trend.direction === 'down' ? '↓' : '→';
+    const peak = r.peakHour ? `${String(r.peakHour.hour).padStart(2, '0')}:00` : '—';
+    const busiest = r.busiestDay ? `${r.busiestDay.day} (${usd(r.busiestDay.costUsd)})` : '—';
+    const gen = opts.generatedAt ? `<p class="gen">generated ${escapeHtml(opts.generatedAt)}</p>` : '';
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Claude Code Reflect — ${escapeHtml(r.period.from)}..${escapeHtml(r.period.to)}</title>
+<style>
+:root{--bg:#0f1117;--card:#181b24;--fg:#e6e8ee;--muted:#8b90a0;--accent:#7c9cff;--track:#262a36}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;padding:32px}
+.wrap{max-width:840px;margin:0 auto}
+h1{font-size:22px;margin:0 0 2px}.sub{color:var(--muted);margin:0 0 24px}.gen{color:var(--muted);font-size:12px;margin:24px 0 0}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin-bottom:28px}
+.stat{background:var(--card);border-radius:12px;padding:16px}
+.stat-val{font-size:22px;font-weight:600}.stat-label{color:var(--muted);font-size:12px;margin-top:4px}
+h2{font-size:14px;text-transform:uppercase;letter-spacing:.05em;color:var(--muted);margin:28px 0 12px}
+.bar{display:grid;grid-template-columns:minmax(0,1fr) 3fr minmax(0,auto);align-items:center;gap:10px;margin:6px 0}
+.bar-label{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:13px}
+.bar-track{background:var(--track);border-radius:6px;height:14px;overflow:hidden}
+.bar-fill{background:var(--accent);height:100%;border-radius:6px}
+.bar-val{font-size:12px;color:var(--muted);white-space:nowrap}
+.hours{display:flex;align-items:flex-end;gap:3px;height:90px}
+.hour{flex:1;display:flex;flex-direction:column;justify-content:flex-end;align-items:center;height:100%}
+.hour-bar{width:100%;background:var(--accent);border-radius:3px 3px 0 0;min-height:1px}
+.hour-tick{font-size:9px;color:var(--muted);margin-top:4px;height:12px}
+.empty{color:var(--muted)}
+</style></head><body><div class="wrap">
+<h1>Claude Code Reflect ${escapeHtml(arrow)}</h1>
+<p class="sub">${escapeHtml(r.period.from)} .. ${escapeHtml(r.period.to)} · ${r.period.spanDays} days · ${r.totals.activeDays} active</p>
+<div class="grid">
+${stat('Total spend', usd(r.totals.costUsd))}
+${stat('Total tokens', num(r.totals.totalTokens))}
+${stat('Avg / active day', usd(r.avgCostPerActiveDay))}
+${stat('Longest streak', `${r.longestStreak} day${r.longestStreak === 1 ? '' : 's'}`)}
+${stat('Peak hour', peak)}
+${stat('Cache read', pct(r.cacheReadPct))}
+${stat('Busiest day', busiest)}
+${stat('Trend', `${arrow} ${pct(r.trend.firstHalfCost > 0 ? (r.trend.secondHalfCost - r.trend.firstHalfCost) / r.trend.firstHalfCost : 0)}`)}
+${opts.delegation && opts.delegation.toolCalls > 0 ? stat('Delegation', pct(opts.delegation.ratio)) : ''}
+</div>
+<h2>Cost by hour of day</h2>${hourBars(r.hourHistogram)}
+<h2>Top models</h2>${shareBars(r.topModels)}
+<h2>Top projects</h2>${shareBars(r.topProjects)}
+${gen}
+</div></body></html>`;
+}
+//# sourceMappingURL=reflect-html.js.map

package/dist/src/usage/reflect-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect-html.js","sourceRoot":"","sources":["../../../src/usage/reflect-html.ts"],"names":[],"mappings":"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"}

package/dist/src/usage/reflect.d.ts

@@ -0,0 +1,105 @@
+/**
+ * reflect.ts — a "wrapped"-style retrospective over Claude Code usage.
+ *
+ * Anthropic's Reflect (2026-07-09) summarizes claude.ai *chats*; it doesn't
+ * touch Claude Code terminal work. swarmdo already parses the local transcripts
+ * for `usage daily/monthly/blocks/errors/cache`, so this is the retrospective
+ * layer on top: fold the existing per-day and per-(model,day) aggregation rows
+ * into headline stats — totals, the busiest day, the top models, the longest
+ * active-day streak, the cost trend, and cache efficiency.
+ *
+ * Pure + deterministic: it takes already-aggregated rows (no transcripts, no
+ * clock — the period bounds are passed in), so the whole thing is unit-tested
+ * without touching disk. The command layer in ../commands/usage.ts feeds it the
+ * rows the parser already produces. See #47.
+ */
+import type { DayRow, ModelRow } from './diff.js';
+export interface ModelShare {
+    model: string;
+    costUsd: number;
+    totalTokens: number;
+    /** share of total cost, 0..1 (0 when the period cost is 0) */
+    pct: number;
+}
+export interface ReflectionTotals {
+    costUsd: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    entries: number;
+    /** days in [from,to] with any token activity */
+    activeDays: number;
+}
+export interface Reflection {
+    period: {
+        from: string;
+        to: string; /** inclusive calendar span in days */
+        spanDays: number;
+    };
+    totals: ReflectionTotals;
+    /** highest-cost active day in the period, or null if the period is empty */
+    busiestDay: {
+        day: string;
+        costUsd: number;
+        totalTokens: number;
+    } | null;
+    /** models ranked by cost desc (capped to opts.topModels) */
+    topModels: ModelShare[];
+    /** projects ranked by cost desc (ModelShare.model holds the project path) */
+    topProjects: ModelShare[];
+    /** busiest local hour-of-day by cost (0..23), or null if no activity */
+    peakHour: {
+        hour: number;
+        value: number;
+    } | null;
+    /** cost per local hour-of-day, as supplied by the caller (length 24 when set) */
+    hourHistogram: number[];
+    /** longest run of consecutive active calendar days */
+    longestStreak: number;
+    /** cacheRead / (input + cacheWrite + cacheRead), 0..1 */
+    cacheReadPct: number;
+    /** total cost / active days (0 when no active days) */
+    avgCostPerActiveDay: number;
+    /** first-half vs second-half spend across the period */
+    trend: {
+        firstHalfCost: number;
+        secondHalfCost: number;
+        direction: 'up' | 'down' | 'flat';
+    };
+}
+export interface ReflectOptions {
+    /** how many models to keep in topModels (default 5) */
+    topModels?: number;
+    /** relative change below which the trend reads 'flat' (default 0.05 = 5%) */
+    flatThreshold?: number;
+}
+/** The calendar day after an ISO date (handles month/year rollover). Pure. */
+export declare function nextDay(iso: string): string;
+/**
+ * The ISO date `n` whole months before `iso`, clamping the day to the target
+ * month's length so "Mar 31 − 1 month" is Feb 28/29 (not a rolled-over Mar 3).
+ * Pure. Used to derive a `--period 1m|3m|…` window start from today.
+ */
+export declare function monthsBefore(iso: string, n: number): string;
+/** Inclusive whole-day span between two ISO dates (from <= to). Pure. */
+export declare function spanDays(from: string, to: string): number;
+/** Longest run of consecutive calendar days present in the set. Pure. */
+export declare function longestStreakOf(days: string[]): number;
+/** Render a numeric series as a Unicode block sparkline (one char per bucket).
+ * Zero buckets are blank; the rest scale ▁..█ against the max. Pure — used for
+ * the terminal cost-by-hour view (the HTML dashboard draws the same data). */
+export declare function hourSparkline(hist: number[]): string;
+/** Window + aggregate `{key, day, totals}` rows into cost-ranked shares. Pure.
+ * Reused for both models and projects (ModelShare.model carries whichever key). */
+export declare function rankShares(rows: ModelRow[], from: string, to: string, totalCost: number, topN: number): ModelShare[];
+/** Busiest bucket in a per-hour cost histogram (argmax; earliest hour wins ties),
+ * or null when every bucket is empty. Pure. */
+export declare function peakHourOf(hourHistogram: number[]): {
+    hour: number;
+    value: number;
+} | null;
+/** Fold pre-aggregated usage rows into a retrospective. Pure. */
+export declare function computeReflection(dayRows: DayRow[], modelRows: ModelRow[], from: string, to: string, opts?: ReflectOptions, projectRows?: ModelRow[], hourHistogram?: number[]): Reflection;
+//# sourceMappingURL=reflect.d.ts.map

package/dist/src/usage/reflect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect.d.ts","sourceRoot":"","sources":["../../../src/usage/reflect.ts"],"names":[],"mappings":"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"}

package/dist/src/usage/reflect.js

@@ -0,0 +1,165 @@
+/**
+ * reflect.ts — a "wrapped"-style retrospective over Claude Code usage.
+ *
+ * Anthropic's Reflect (2026-07-09) summarizes claude.ai *chats*; it doesn't
+ * touch Claude Code terminal work. swarmdo already parses the local transcripts
+ * for `usage daily/monthly/blocks/errors/cache`, so this is the retrospective
+ * layer on top: fold the existing per-day and per-(model,day) aggregation rows
+ * into headline stats — totals, the busiest day, the top models, the longest
+ * active-day streak, the cost trend, and cache efficiency.
+ *
+ * Pure + deterministic: it takes already-aggregated rows (no transcripts, no
+ * clock — the period bounds are passed in), so the whole thing is unit-tested
+ * without touching disk. The command layer in ../commands/usage.ts feeds it the
+ * rows the parser already produces. See #47.
+ */
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** The calendar day after an ISO date (handles month/year rollover). Pure. */
+export function nextDay(iso) {
+    const [y, m, d] = iso.split('-').map(Number);
+    const dt = new Date(y, m - 1, d + 1);
+    const yy = dt.getFullYear();
+    const mm = String(dt.getMonth() + 1).padStart(2, '0');
+    const dd = String(dt.getDate()).padStart(2, '0');
+    return `${yy}-${mm}-${dd}`;
+}
+/**
+ * The ISO date `n` whole months before `iso`, clamping the day to the target
+ * month's length so "Mar 31 − 1 month" is Feb 28/29 (not a rolled-over Mar 3).
+ * Pure. Used to derive a `--period 1m|3m|…` window start from today.
+ */
+export function monthsBefore(iso, n) {
+    const [y, m, d] = iso.split('-').map(Number);
+    const monthIndex = m - 1 - n; // may be negative — Date normalizes the year
+    const lastDay = new Date(y, monthIndex + 1, 0).getDate();
+    const dt = new Date(y, monthIndex, Math.min(d, lastDay));
+    const yy = dt.getFullYear();
+    const mm = String(dt.getMonth() + 1).padStart(2, '0');
+    const dd = String(dt.getDate()).padStart(2, '0');
+    return `${yy}-${mm}-${dd}`;
+}
+/** Inclusive whole-day span between two ISO dates (from <= to). Pure. */
+export function spanDays(from, to) {
+    const a = new Date(from + 'T00:00:00');
+    const b = new Date(to + 'T00:00:00');
+    return Math.floor((b.getTime() - a.getTime()) / 86_400_000) + 1;
+}
+/** Longest run of consecutive calendar days present in the set. Pure. */
+export function longestStreakOf(days) {
+    const uniq = [...new Set(days)].sort();
+    let best = 0;
+    let run = 0;
+    let prev = null;
+    for (const d of uniq) {
+        run = prev !== null && nextDay(prev) === d ? run + 1 : 1;
+        if (run > best)
+            best = run;
+        prev = d;
+    }
+    return best;
+}
+const within = (key, from, to) => key >= from && key <= to;
+const SPARK_BLOCKS = ' ▁▂▃▄▅▆▇█'; // index 0 = empty (zero), 1..8 = ▁..█ scaled to max
+/** Render a numeric series as a Unicode block sparkline (one char per bucket).
+ * Zero buckets are blank; the rest scale ▁..█ against the max. Pure — used for
+ * the terminal cost-by-hour view (the HTML dashboard draws the same data). */
+export function hourSparkline(hist) {
+    const max = Math.max(0, ...hist);
+    if (max <= 0)
+        return ' '.repeat(hist.length);
+    return hist.map((v) => SPARK_BLOCKS[v <= 0 ? 0 : Math.min(8, 1 + Math.floor((v / max) * 7))]).join('');
+}
+/** Window + aggregate `{key, day, totals}` rows into cost-ranked shares. Pure.
+ * Reused for both models and projects (ModelShare.model carries whichever key). */
+export function rankShares(rows, from, to, totalCost, topN) {
+    const per = new Map();
+    for (const r of rows) {
+        if (!within(r.day, from, to))
+            continue;
+        const slot = per.get(r.key) ?? { costUsd: 0, totalTokens: 0 };
+        slot.costUsd += r.totals.costUsd;
+        slot.totalTokens += r.totals.totalTokens;
+        per.set(r.key, slot);
+    }
+    return [...per.entries()]
+        .map(([key, v]) => ({ model: key, costUsd: v.costUsd, totalTokens: v.totalTokens, pct: totalCost > 0 ? v.costUsd / totalCost : 0 }))
+        .filter((m) => m.costUsd > 0 || m.totalTokens > 0)
+        .sort((a, b) => b.costUsd - a.costUsd || b.totalTokens - a.totalTokens || (a.model < b.model ? -1 : 1))
+        .slice(0, topN);
+}
+/** Busiest bucket in a per-hour cost histogram (argmax; earliest hour wins ties),
+ * or null when every bucket is empty. Pure. */
+export function peakHourOf(hourHistogram) {
+    let best = -1;
+    let bestVal = 0;
+    for (let h = 0; h < hourHistogram.length; h++) {
+        if (hourHistogram[h] > bestVal) {
+            bestVal = hourHistogram[h];
+            best = h;
+        }
+    }
+    return best < 0 ? null : { hour: best, value: bestVal };
+}
+/** Fold pre-aggregated usage rows into a retrospective. Pure. */
+export function computeReflection(dayRows, modelRows, from, to, opts = {}, projectRows = [], hourHistogram = []) {
+    if (!DATE.test(from) || !DATE.test(to))
+        throw new Error(`bad period bounds: ${from}..${to}`);
+    if (from > to)
+        throw new Error(`period "${from}..${to}" is reversed (from > to)`);
+    const topN = opts.topModels ?? 5;
+    const flat = opts.flatThreshold ?? 0.05;
+    const days = dayRows.filter((r) => within(r.key, from, to));
+    const totals = {
+        costUsd: 0, totalTokens: 0, inputTokens: 0, outputTokens: 0,
+        cacheReadTokens: 0, cacheWriteTokens: 0, entries: 0, activeDays: 0,
+    };
+    let busiestDay = null;
+    const activeDayKeys = [];
+    const mid = spanDays(from, to) / 2;
+    let firstHalfCost = 0;
+    let secondHalfCost = 0;
+    for (const r of days) {
+        const t = r.totals;
+        totals.costUsd += t.costUsd;
+        totals.totalTokens += t.totalTokens;
+        totals.inputTokens += t.inputTokens;
+        totals.outputTokens += t.outputTokens;
+        totals.cacheReadTokens += t.cacheReadTokens;
+        totals.cacheWriteTokens += t.cacheWriteTokens;
+        if (t.totalTokens > 0) {
+            totals.activeDays += 1;
+            activeDayKeys.push(r.key);
+        }
+        if (!busiestDay || t.costUsd > busiestDay.costUsd) {
+            busiestDay = { day: r.key, costUsd: t.costUsd, totalTokens: t.totalTokens };
+        }
+        // Trend: which half of the period does this day fall in?
+        if (spanDays(from, r.key) <= mid)
+            firstHalfCost += t.costUsd;
+        else
+            secondHalfCost += t.costUsd;
+    }
+    // A period with zero active days has no meaningful busiest day.
+    if (totals.activeDays === 0)
+        busiestDay = null;
+    // Cost-ranked shares over the same window, for both models and projects.
+    const topModels = rankShares(modelRows, from, to, totals.costUsd, topN);
+    const topProjects = rankShares(projectRows, from, to, totals.costUsd, topN);
+    const inputSide = totals.inputTokens + totals.cacheWriteTokens + totals.cacheReadTokens;
+    const relChange = firstHalfCost > 0 ? (secondHalfCost - firstHalfCost) / firstHalfCost : (secondHalfCost > 0 ? 1 : 0);
+    const direction = Math.abs(relChange) < flat ? 'flat' : relChange > 0 ? 'up' : 'down';
+    return {
+        period: { from, to, spanDays: spanDays(from, to) },
+        totals,
+        busiestDay,
+        topModels,
+        topProjects,
+        peakHour: peakHourOf(hourHistogram),
+        hourHistogram,
+        longestStreak: longestStreakOf(activeDayKeys),
+        cacheReadPct: inputSide > 0 ? totals.cacheReadTokens / inputSide : 0,
+        avgCostPerActiveDay: totals.activeDays > 0 ? totals.costUsd / totals.activeDays : 0,
+        trend: { firstHalfCost, secondHalfCost, direction },
+    };
+}
+//# sourceMappingURL=reflect.js.map

package/dist/src/usage/reflect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect.js","sourceRoot":"","sources":["../../../src/usage/reflect.ts"],"names":[],"mappings":"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"}

package/dist/src/usage/spend-forecast.d.ts

@@ -0,0 +1,28 @@
+/**
+ * spend-forecast.ts — project month-end Claude Code spend from month-to-date
+ * burn, for budgeting ("on pace for ~$420 this month").
+ *
+ * The quota forecaster (limits.ts) answers "will I hit the rolling cap"; this
+ * answers "what will the calendar month cost at the current daily average".
+ * Pure + deterministic: month-to-date total, the day-of-month, and the days in
+ * the month are passed in, so it's unit-tested without a clock.
+ */
+export interface SpendProjection {
+    monthToDateUsd: number;
+    dayOfMonth: number;
+    daysInMonth: number;
+    /** month-to-date / day-of-month */
+    dailyAverageUsd: number;
+    /** dailyAverage × daysInMonth — projected month-end total */
+    projectedUsd: number;
+    /** projectedUsd − monthToDateUsd — the remaining projected spend */
+    remainingUsd: number;
+}
+/** Days in the calendar month of an ISO `YYYY-MM` (or `YYYY-MM-DD`). Pure. */
+export declare function daysInMonthOf(iso: string): number;
+/**
+ * Project month-end spend at the current daily average. `dayOfMonth` is how many
+ * days (inclusive of today) have accrued the month-to-date total. Pure.
+ */
+export declare function projectMonthEnd(monthToDateUsd: number, dayOfMonth: number, daysInMonth: number): SpendProjection;
+//# sourceMappingURL=spend-forecast.d.ts.map

package/dist/src/usage/spend-forecast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-forecast.d.ts","sourceRoot":"","sources":["../../../src/usage/spend-forecast.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,eAAe,CAWhH"}

package/dist/src/usage/spend-forecast.js

@@ -0,0 +1,33 @@
+/**
+ * spend-forecast.ts — project month-end Claude Code spend from month-to-date
+ * burn, for budgeting ("on pace for ~$420 this month").
+ *
+ * The quota forecaster (limits.ts) answers "will I hit the rolling cap"; this
+ * answers "what will the calendar month cost at the current daily average".
+ * Pure + deterministic: month-to-date total, the day-of-month, and the days in
+ * the month are passed in, so it's unit-tested without a clock.
+ */
+/** Days in the calendar month of an ISO `YYYY-MM` (or `YYYY-MM-DD`). Pure. */
+export function daysInMonthOf(iso) {
+    const [y, m] = iso.split('-').map(Number);
+    if (!Number.isFinite(y) || !Number.isFinite(m) || m < 1 || m > 12)
+        return NaN;
+    return new Date(y, m, 0).getDate(); // day 0 of the next month = last day of this one
+}
+/**
+ * Project month-end spend at the current daily average. `dayOfMonth` is how many
+ * days (inclusive of today) have accrued the month-to-date total. Pure.
+ */
+export function projectMonthEnd(monthToDateUsd, dayOfMonth, daysInMonth) {
+    const dailyAverageUsd = dayOfMonth > 0 ? monthToDateUsd / dayOfMonth : 0;
+    const projectedUsd = dailyAverageUsd * daysInMonth;
+    return {
+        monthToDateUsd,
+        dayOfMonth,
+        daysInMonth,
+        dailyAverageUsd,
+        projectedUsd,
+        remainingUsd: Math.max(0, projectedUsd - monthToDateUsd),
+    };
+}
+//# sourceMappingURL=spend-forecast.js.map

package/dist/src/usage/spend-forecast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-forecast.js","sourceRoot":"","sources":["../../../src/usage/spend-forecast.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,GAAG,CAAC;IAC9E,OAAO,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,iDAAiD;AACvF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,cAAsB,EAAE,UAAkB,EAAE,WAAmB;IAC7F,MAAM,eAAe,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,MAAM,YAAY,GAAG,eAAe,GAAG,WAAW,CAAC;IACnD,OAAO;QACL,cAAc;QACd,UAAU;QACV,WAAW;QACX,eAAe;QACf,YAAY;QACZ,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,GAAG,cAAc,CAAC;KACzD,CAAC;AACJ,CAAC"}