@trazum/cli 1.47.0 → 1.49.0

package/dist/index.js

@@ -2,7 +2,7 @@
 import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { join, resolve as resolvePath } from 'node:path';
 import { gunzipSync } from 'node:zlib';
-import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, detectFromSource, matchLocale, parsePlanDocument, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
+import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
 import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
 import { dayOf, formatGap, median, spanDays } from './time.js';
 // Everything that reads the filesystem, on its own entry point so the web
@@ -11,6 +11,7 @@ import { CONFIG_FILENAME, DEFAULT_EXTENSIONS, budgetFor, BUNDLED_CATALOGUE, SAFE
 import { contentAt, gitAvailable, namesByRevision, pathInRepository, repositoryRoot, revisionsFor, } from './git.js';
 import { fetchProviderUsage, findCredential } from './connect.js';
 import { STORE_DIR, appendRecords, readStore, rewriteStore } from './store-fs.js';
+import { WAIVER_LOG, appendWaiverUse, readWaiverLog } from './waiver-log.js';
 import { DEFAULT_PORT, buildServer, listen } from './serve.js';
 import { WATCH_STATE_VERSION, checkWebhook, postWebhook, readWatchState, writeWatchState, } from './watch-run.js';
 import { LOCALE_ENV_VARS, detectLocale, getCliMessages } from './i18n/index.js';
@@ -2081,36 +2082,36 @@ function parseWhen(args, flag, endOfDay, t, now) {
  */
 async function commandServe(args, config, pricing, t) {
     const root = process.cwd();
-    const limitUsd = config.spend?.maxUsd;
     const { resolved } = await readStore(root);
-    const measured = resolved.records.length > 0;
     /**
-     * The window the measurement covers, carried into every answer.
+     * The live budget, from `budgetPositions` — the same number `store` prints
+     * and the same one the MCP guard consults.
      *
-     * The position is read once at start, so a caller has to be able to see how
-     * old it is. A null window here would let a figure from last month read as
-     * current, which is the staleness this endpoint is otherwise honest about.
+     * **This used to read `spend.maxUsd` against the whole store**, which is a
+     * per-log gate compared against however much history the store happened to
+     * hold. A year of records against a monthly limit reported as a budget
+     * position, with a straight face and no way for a caller to tell. Same
+     * units, different denominators, and the two surfaces disagreed by exactly
+     * as much history as the machine had. `spend.monthlyUsd` is the key for a
+     * calendar month and nothing infers one key from the other: a repository
+     * with a per-log gate and no monthly budget has no monthly position, and
+     * this says so rather than picking a number that is the right shape.
      */
-    const window = measured
-        ? {
-            fromMs: Math.min(...resolved.records.map((record) => record.fromMs)),
-            toMs: Math.max(...resolved.records.map((record) => record.toMs)),
-        }
-        : null;
-    const report = bucketedProfile({
-        provider: 'store',
-        granularity: 'bucketed',
-        buckets: bucketsFromRecords(resolved.records),
-        window,
-        gaps: [],
-        unavailable: [],
-    }, { catalogue: pricing });
+    const budget = budgetPositions(resolved.records, config.spend, { catalogue: pricing });
+    const standing = budget.positions[0] ?? null;
+    const limitUsd = config.spend?.monthlyUsd;
+    const measured = standing !== null && standing.coverage !== 'none';
     const server = buildServer({
         catalogue: pricing,
         position: () => ({
-            consumedUsd: measured ? report.total.totalUsd : undefined,
+            // Nothing measured inside the period is `undefined`, never zero: the
+            // endpoint's `cannot-tell` exists for exactly this, and a $0 consumed
+            // would be the healthiest-looking budget a dead store can produce.
+            consumedUsd: measured ? standing.consumedUsd : undefined,
             limitUsd,
-            window: report.span,
+            // The period, not the store's span. A caller judging staleness needs to
+            // know which month the figure is about.
+            window: standing === null ? null : { fromMs: standing.period.fromMs, toMs: standing.period.toMs },
         }),
     });
     const socket = stringFlag(args, 'socket');
@@ -2122,7 +2123,10 @@ async function commandServe(args, config, pricing, t) {
     const where = await listen(server, socket !== undefined ? { socket } : { port });
     console.log(c.bold(t.serve.listening(where)));
     console.log(`  ${c.dim(wrap(t.serve.loopbackOnly(), 74, '    '))}`);
-    console.log(`  ${c.dim(wrap(measured ? t.serve.measuredFrom(formatUsd(report.total.totalUsd)) : t.serve.nothingMeasured(STORE_DIR), 74, '    '))}`);
+    console.log(`  ${c.dim(wrap(measured ? t.serve.measuredFrom(formatUsd(standing.consumedUsd)) : t.serve.nothingMeasured(STORE_DIR), 74, '    '))}`);
+    if (standing !== null && standing.coverage === 'partial') {
+        console.log(`  ${c.yellow(wrap(t.serve.partialCoverage(standing.measuredDays, standing.elapsedDays, standing.period.id), 74, '    '))}`);
+    }
     if (limitUsd === undefined) {
         console.log(`  ${c.dim(wrap(t.serve.noBudget(), 74, '    '))}`);
     }
@@ -2375,6 +2379,51 @@ async function commandStore(args, config, pricing, t) {
     }
     const keepDays = config.store?.keepDays;
     console.log(`  ${c.dim(wrap(keepDays === undefined ? t.store.noRetention() : t.store.retention(String(keepDays)), 74, '    '))}`);
+    /**
+     * The live budget, printed here because this is where the measurement lives.
+     *
+     * The same call `serve` makes and the same call the MCP guard makes, so the
+     * three cannot disagree about how much of the month is gone — which is the
+     * whole point of the number existing in one place.
+     */
+    renderBudget(budgetPositions(resolved.records, config.spend, { catalogue: pricing }), t, n);
+}
+/**
+ * One budget standing, rendered.
+ *
+ * Coverage before the money, deliberately. A reader who sees "$61 of $100"
+ * first has already formed a view by the time they reach "over three of
+ * nineteen elapsed days", and the second sentence has to undo the first.
+ */
+function renderBudget(report, t, n) {
+    const standing = report.positions[0];
+    if (standing === undefined) {
+        if (report.unmeasuredScopes.length > 0) {
+            console.log();
+            console.log(`  ${c.dim(wrap(t.store.budgetScopesUnmeasured(report.unmeasuredScopes.length), 74, '    '))}`);
+        }
+        return;
+    }
+    console.log();
+    console.log(c.bold(t.store.budgetHeading(standing.period.id)));
+    if (standing.coverage === 'none') {
+        // Nothing measured is never rendered as nothing spent. A dead store and a
+        // quiet month produce the same zero, and only one of them is good news.
+        console.log(`  ${c.red(wrap(t.store.budgetNothingMeasured(standing.elapsedDays), 74, '    '))}`);
+        return;
+    }
+    if (standing.coverage === 'partial') {
+        console.log(`  ${c.yellow(wrap(t.store.budgetPartial(standing.measuredDays, standing.elapsedDays, standing.unmeasuredDays.join(', ')), 74, '    '))}`);
+    }
+    const share = standing.burn.consumedShare;
+    console.log(`  ${t.store.budgetStanding(formatUsd(standing.consumedUsd), formatUsd(standing.limitUsd), share === null ? '—' : `${Math.round(share * 100)}%`, n(standing.measuredDays), n(standing.period.days))}`);
+    const line = t.store.budgetShape(standing.burn.shape, Math.round(standing.burn.elapsedShare * 100), standing.coverage);
+    console.log(`  ${standing.verdict === 'over' ? c.red(line) : c.dim(wrap(line, 74, '    '))}`);
+    // Only where there is a shape to disclaim. "That is a shape, not a forecast"
+    // under "nothing to compare against" is a disclaimer about nothing.
+    if (standing.burn.shape !== 'cannot-tell') {
+        console.log(`  ${c.dim(wrap(t.store.budgetNeverForecast(), 74, '    '))}`);
+    }
 }
 /**
  * `trazum connect <provider>` — the bill, read from the provider.
@@ -2518,7 +2567,7 @@ async function commandConnect(args, pricing, t) {
  * same action planned twice — and no series, however long, becomes a
  * forecast.
  */
-async function commandHistory(args, pricing, t) {
+async function commandHistory(args, config, pricing, t) {
     /**
      * `--store` builds the series from measured spend already on disk.
      *
@@ -2617,7 +2666,22 @@ async function commandHistory(args, pricing, t) {
     if (history.periods.length < 3) {
         throw new Error(t.history.needsThree(String(history.periods.length)));
     }
-    const stamped = { ...history, unrecognizedFiles: unrecognized };
+    /**
+     * The waiver record — closing the gap 1.40 named and could not fill.
+     *
+     * 1.40 wanted to say "this finding has been waived three times in a row" and
+     * refused to, because the only material available was the config as it
+     * stands, and a past reconstructed from a present is a guess wearing a
+     * record's clothes. The material exists now: since 1.48 a waiver that
+     * silences a gate writes down that it did, and this reads those lines back.
+     *
+     * Read from the working directory rather than from the reports directory:
+     * the waiver record belongs to the repository whose gates fired, and the
+     * stored reports may have come from anywhere.
+     */
+    const waivers = await readWaiverLog('.');
+    const waiverReport = waiverHistory(waivers.uses, config.waive ?? []);
+    const stamped = { ...history, unrecognizedFiles: unrecognized, waivers: waiverReport };
     const n = (value) => value.toLocaleString(t.numberLocale);
     const day = (ms) => new Date(ms).toISOString().slice(0, 10);
     const pct = (value) => `${(value * 100).toFixed(1)}%`;
@@ -2659,6 +2723,56 @@ async function commandHistory(args, pricing, t) {
         for (const name of unrecognized) {
             out.push(md ? `- ${t.history.unrecognized(name)}` : `  ${t.history.unrecognized(name)}`);
         }
+        /**
+         * The waiver record, printed only once something has been recorded.
+         *
+         * Silent on a repository that has never waived anything, rather than a
+         * heading over "0 uses" — an empty section teaches a reader to skip the
+         * section, and this is the one they should not learn to skip.
+         */
+        if (waivers.present) {
+            out.push('');
+            out.push(md ? `### ${t.history.waiverHeading()}` : t.history.waiverHeading());
+            if (waiverReport.totalUses === 0) {
+                out.push(md ? `- ${t.history.waiverNoneRecorded()}` : `  ${t.history.waiverNoneRecorded()}`);
+            }
+            else {
+                const since = t.history.waiverSince(waiverReport.since ?? '', waiverReport.totalUses);
+                out.push(md ? `- ${since}` : `  ${since}`);
+                out.push(md ? `- _${t.history.waiverStartsHere()}_` : `  ${t.history.waiverStartsHere()}`);
+                for (const habit of waiverReport.habits) {
+                    out.push('');
+                    const head = t.history.waiverHabit(habit.gate, habit.uses, habit.days, habit.firstDay, habit.lastDay);
+                    out.push(md ? `- **${head}**` : `  ${head}`);
+                    const rows = [t.history.waiverVerdict(habit.verdict)];
+                    // The reason as it stands *now* — never read backwards onto an
+                    // older use, which is the same mistake the record exists to avoid.
+                    const latest = habit.reasons[habit.reasons.length - 1];
+                    if (latest !== undefined)
+                        rows.push(t.history.waiverReasonNow(latest));
+                    if (habit.reasons.length > 1)
+                        rows.push(t.history.waiverReasonsChanged(habit.reasons.length));
+                    const firstExpiry = habit.expiries[0];
+                    const lastExpiry = habit.expiries[habit.expiries.length - 1];
+                    if (habit.expiries.length > 1 && firstExpiry !== undefined && lastExpiry !== undefined) {
+                        rows.push(t.history.waiverExpiriesMoved(firstExpiry, lastExpiry, habit.expiries.length - 1));
+                    }
+                    if (!habit.stillConfigured)
+                        rows.push(t.history.waiverNoLongerConfigured());
+                    for (const row of rows)
+                        out.push(md ? `  - ${row}` : `    ${row}`);
+                }
+            }
+            if (waiverReport.neverUsed.length > 0) {
+                out.push('');
+                const dead = t.history.waiverNeverUsed(waiverReport.neverUsed.join(', '));
+                out.push(md ? `- ${dead}` : `  ${dead}`);
+            }
+            if (waivers.unreadable.length > 0) {
+                const bad = t.history.waiverUnreadable(waivers.unreadable.length, WAIVER_LOG);
+                out.push(md ? `- ${bad}` : `  ${bad}`);
+            }
+        }
         if (fromStore) {
             out.push('');
             const note = t.history.storeNoLabels();
@@ -3332,7 +3446,16 @@ async function commandProfile(args, config, pricing, t) {
      * way, because a waived failure that vanished from the output would be a
      * finding deleted with extra steps.
      */
-    const waived = (gate) => {
+    /**
+     * Uses recorded this run, flushed after the gates have finished.
+     *
+     * Collected rather than written inline because `waived` is synchronous and
+     * called from seven places inside the gate pass. Writing from each of them
+     * would mean seven awaits threaded through the exit-code logic — the one
+     * part of this command where a mistake turns a red build green.
+     */
+    const waiverUses = [];
+    const waived = (gate, measuredUsd = null, limitUsd = null) => {
         const found = waiverFor(gate);
         if (found === null)
             return false;
@@ -3342,6 +3465,29 @@ async function commandProfile(args, config, pricing, t) {
         }
         const daysLeft = Math.max(0, Math.ceil((Date.parse(`${found.entry.until}T00:00:00Z`) + 86_400_000 - Date.now()) / 86_400_000));
         console.error(c.yellow(t.profile.waiveActive(gate, found.entry.reason, found.entry.until, String(daysLeft))));
+        /**
+         * Recorded **when it silences something**, never when it is configured.
+         *
+         * A waiver nobody's build has ever hit is not a habit — it is dead config
+         * — and the history reports the two apart. This is also the only honest
+         * way to build the record 1.40 refused to invent: it starts today and
+         * says so, rather than reconstructing a past from the present.
+         *
+         * The reason and the expiry are taken from the config **as it stands at
+         * this moment**, because that is the decision that was actually in force.
+         * Reading today's reason back onto last quarter's use is the same mistake
+         * one layer down.
+         */
+        waiverUses.push({
+            schemaVersion: 1,
+            day: waiverDay(new Date()),
+            gate,
+            reason: found.entry.reason,
+            until: found.entry.until,
+            commit: process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? null,
+            measuredUsd,
+            limitUsd,
+        });
         return true;
     };
     const applyGates = () => {
@@ -3391,7 +3537,7 @@ async function commandProfile(args, config, pricing, t) {
                 }
                 if (usd > limit) {
                     console.error(c.red(t.profile.labelBudgetFailed(label, formatUsd(usd), formatUsd(limit))));
-                    if (!waived(`byLabel:${label}`))
+                    if (!waived(`byLabel:${label}`, usd, limit))
                         process.exitCode = 1;
                 }
                 else {
@@ -3453,7 +3599,7 @@ async function commandProfile(args, config, pricing, t) {
                  * copy says so.
                  */
                 explainFailure(report.total.totalUsd - maxUsd);
-                if (!waived('maxUsd'))
+                if (!waived('maxUsd', report.total.totalUsd, maxUsd))
                     process.exitCode = 1;
             }
             else {
@@ -3488,7 +3634,7 @@ async function commandProfile(args, config, pricing, t) {
             }
             else if (againstDelta > maxGrowth) {
                 console.error(c.red(t.profile.maxGrowthUsdFailed(formatSignedUsd(againstDelta), formatUsd(maxGrowth))));
-                if (!waived('maxGrowthUsd'))
+                if (!waived('maxGrowthUsd', againstDelta, maxGrowth))
                     process.exitCode = 1;
             }
         }
@@ -3505,12 +3651,12 @@ async function commandProfile(args, config, pricing, t) {
             const gateCache = cacheEconomics(report.total);
             if (gateCache.deltaUsd > maxLoss) {
                 console.error(c.red(t.profile.maxCacheLossFailed(formatUsd(gateCache.deltaUsd), formatUsd(maxLoss))));
-                if (!waived('maxCacheLossUsd'))
+                if (!waived('maxCacheLossUsd', gateCache.deltaUsd, maxLoss))
                     process.exitCode = 1;
             }
             else if (gateCache.worstCaseDeltaUsd > maxLoss) {
                 console.error(c.red(t.profile.maxCacheLossWorstCase(report.total.assumedWriteTtlCalls, formatUsd(gateCache.worstCaseDeltaUsd), formatUsd(maxLoss))));
-                if (!waived('maxCacheLossUsd'))
+                if (!waived('maxCacheLossUsd', gateCache.worstCaseDeltaUsd, maxLoss))
                     process.exitCode = 1;
             }
             else {
@@ -3556,7 +3702,7 @@ async function commandProfile(args, config, pricing, t) {
                 if (worst.usd > maxDay) {
                     console.error(c.red(`${t.profile.maxDayFailed(worst.day, formatUsd(worst.usd), formatUsd(maxDay))}${suspect}`));
                     explainFailure(worst.usd - maxDay, { namesLargest: true });
-                    if (!waived('maxDayUsd'))
+                    if (!waived('maxDayUsd', worst.usd, maxDay))
                         process.exitCode = 1;
                 }
                 else {
@@ -3598,7 +3744,7 @@ async function commandProfile(args, config, pricing, t) {
             else if (report.sessionSpend.maxUsd > maxSession) {
                 console.error(c.red(t.profile.maxSessionFailed(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))));
                 explainFailure(report.sessionSpend.maxUsd - maxSession);
-                if (!waived('maxSessionUsd'))
+                if (!waived('maxSessionUsd', report.sessionSpend.maxUsd, maxSession))
                     process.exitCode = 1;
             }
             else {
@@ -3631,6 +3777,26 @@ async function commandProfile(args, config, pricing, t) {
             gateFailed = process.exitCode === 1;
         }
     };
+    /**
+     * Writes down every waiver that silenced something this run.
+     *
+     * **A failure here never fails the build.** The gate's job is the exit code;
+     * a read-only checkout or a full disk must not turn a passing build red on
+     * account of bookkeeping. The problem is reported and the gate's own verdict
+     * stands — which is also why this runs after `recordGates` rather than
+     * inside it: nothing about the exit code depends on the write.
+     */
+    const recordWaiverUses = async () => {
+        if (waiverUses.length === 0)
+            return;
+        for (const use of waiverUses) {
+            const failed = await appendWaiverUse('.', use);
+            if (failed !== null) {
+                console.error(c.dim(t.profile.waiveNotRecorded(WAIVER_LOG, failed)));
+                return;
+            }
+        }
+    };
     /**
      * The side files the caller asked for. Written on **both** output paths:
      * under --json the human rendering returns early, and the first version of
@@ -3779,6 +3945,7 @@ async function commandProfile(args, config, pricing, t) {
             ...(whatIf !== null ? { whatIf } : {}),
         }, null, 2));
         recordGates();
+        await recordWaiverUses();
         await writeSideFiles();
         return;
     }
@@ -4786,6 +4953,7 @@ async function commandProfile(args, config, pricing, t) {
     }
     reportProfileGaps(report, t, n, pricingStale);
     recordGates();
+    await recordWaiverUses();
     await writeSideFiles();
 }
 /**
@@ -6082,7 +6250,7 @@ async function main() {
             await commandVerify(args, pricing, t);
             break;
         case 'history':
-            await commandHistory(args, pricing, t);
+            await commandHistory(args, config, pricing, t);
             break;
         case 'connect':
             await commandConnect(args, pricing, t);