@trazum/cli 1.47.0 → 1.49.0

package/src/index.ts

@@ -35,9 +35,12 @@ import {
   computeSavings,
   countTokensAnthropic,
   DEFAULT_USAGE,
+  budgetPositions,
   detectFromSource,
   matchLocale,
   parsePlanDocument,
+  waiverDay,
+  waiverHistory,
   proposeInit,
   MIN_RATE_DAYS,
   parseConfig,
@@ -125,7 +128,9 @@ import type {
   UsageProfile,
 } from '@trazum/core';
 import type {
+  BudgetReport,
   UsageProfileReport,
+  WaiverUse,
   InitDecline,
   InitJustification,
   InitObservations,
@@ -168,6 +173,7 @@ import {
 import type { Revision } 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,
@@ -2743,41 +2749,39 @@ async function commandServe(
   t: CliMessages,
 ): Promise<void> {
   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 },
     }),
   });
 
@@ -2792,8 +2796,13 @@ async function commandServe(
   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, '    '))}`,
+    `  ${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, '    '))}`);
   }
@@ -3160,6 +3169,72 @@ async function commandStore(
   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: BudgetReport, t: CliMessages, n: (value: number) => string): void {
+  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, '    '))}`);
+  }
 }
 
 /**
@@ -3348,7 +3423,12 @@ async function commandConnect(
  * same action planned twice — and no series, however long, becomes a
  * forecast.
  */
-async function commandHistory(args: Args, pricing: PricingCatalogue, t: CliMessages): Promise<void> {
+async function commandHistory(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
   /**
    * `--store` builds the series from measured spend already on disk.
    *
@@ -3452,7 +3532,23 @@ async function commandHistory(args: Args, pricing: PricingCatalogue, t: CliMessa
     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: number): string => value.toLocaleString(t.numberLocale);
   const day = (ms: number): string => new Date(ms).toISOString().slice(0, 10);
   const pct = (value: number): string => `${(value * 100).toFixed(1)}%`;
@@ -3506,6 +3602,58 @@ async function commandHistory(args: Args, pricing: PricingCatalogue, t: CliMessa
     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();
@@ -4248,7 +4396,16 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
    * way, because a waived failure that vanished from the output would be a
    * finding deleted with extra steps.
    */
-  const waived = (gate: string): boolean => {
+  /**
+   * 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: WaiverUse[] = [];
+  const waived = (gate: string, measuredUsd: number | null = null, limitUsd: number | null = null): boolean => {
     const found = waiverFor(gate);
     if (found === null) return false;
     if (found.expired) {
@@ -4264,6 +4421,29 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
     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 = (): void => {
@@ -4312,7 +4492,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         }
         if (usd > limit) {
           console.error(c.red(t.profile.labelBudgetFailed(label, formatUsd(usd), formatUsd(limit))));
-          if (!waived(`byLabel:${label}`)) process.exitCode = 1;
+          if (!waived(`byLabel:${label}`, usd, limit)) process.exitCode = 1;
         } else {
           console.error(c.dim(t.profile.labelBudgetOk(label, formatUsd(usd), formatUsd(limit))));
         }
@@ -4385,7 +4565,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
          * copy says so.
          */
         explainFailure(report.total.totalUsd - maxUsd);
-        if (!waived('maxUsd')) process.exitCode = 1;
+        if (!waived('maxUsd', report.total.totalUsd, maxUsd)) process.exitCode = 1;
       } else {
         console.error(c.dim(t.profile.maxUsdOk(formatUsd(report.total.totalUsd), formatUsd(maxUsd))));
         explainMargin(report.total.totalUsd, maxUsd);
@@ -4425,7 +4605,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         process.exitCode = 1;
       } else if (againstDelta > maxGrowth) {
         console.error(c.red(t.profile.maxGrowthUsdFailed(formatSignedUsd(againstDelta), formatUsd(maxGrowth))));
-        if (!waived('maxGrowthUsd')) process.exitCode = 1;
+        if (!waived('maxGrowthUsd', againstDelta, maxGrowth)) process.exitCode = 1;
       }
     }
     /**
@@ -4443,7 +4623,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         console.error(
           c.red(t.profile.maxCacheLossFailed(formatUsd(gateCache.deltaUsd), formatUsd(maxLoss))),
         );
-        if (!waived('maxCacheLossUsd')) process.exitCode = 1;
+        if (!waived('maxCacheLossUsd', gateCache.deltaUsd, maxLoss)) process.exitCode = 1;
       } else if (gateCache.worstCaseDeltaUsd > maxLoss) {
         console.error(
           c.red(
@@ -4454,7 +4634,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
             ),
           ),
         );
-        if (!waived('maxCacheLossUsd')) process.exitCode = 1;
+        if (!waived('maxCacheLossUsd', gateCache.worstCaseDeltaUsd, maxLoss)) process.exitCode = 1;
       } else {
         console.error(
           c.dim(t.profile.maxCacheLossOk(formatUsd(Math.max(0, gateCache.worstCaseDeltaUsd)), formatUsd(maxLoss))),
@@ -4503,7 +4683,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
             c.red(`${t.profile.maxDayFailed(worst.day, formatUsd(worst.usd), formatUsd(maxDay))}${suspect}`),
           );
           explainFailure(worst.usd - maxDay, { namesLargest: true });
-          if (!waived('maxDayUsd')) process.exitCode = 1;
+          if (!waived('maxDayUsd', worst.usd, maxDay)) process.exitCode = 1;
         } else {
           console.error(c.dim(t.profile.maxDayOk(worst.day, formatUsd(worst.usd), formatUsd(maxDay))));
           explainMargin(worst.usd, maxDay);
@@ -4545,7 +4725,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
           c.red(t.profile.maxSessionFailed(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))),
         );
         explainFailure(report.sessionSpend.maxUsd - maxSession);
-        if (!waived('maxSessionUsd')) process.exitCode = 1;
+        if (!waived('maxSessionUsd', report.sessionSpend.maxUsd, maxSession)) process.exitCode = 1;
       } else {
         console.error(
           c.dim(t.profile.maxSessionOk(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))),
@@ -4579,6 +4759,26 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
     }
   };
 
+  /**
+   * 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 (): Promise<void> => {
+    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
@@ -4745,6 +4945,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
       ),
     );
     recordGates();
+    await recordWaiverUses();
     await writeSideFiles();
     return;
   }
@@ -5899,6 +6100,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
   reportProfileGaps(report, t, n, pricingStale);
 
   recordGates();
+  await recordWaiverUses();
 
   await writeSideFiles();
 }
@@ -7612,7 +7814,7 @@ async function main(): Promise<void> {
       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);

package/src/waiver-log.ts

@@ -0,0 +1,81 @@
+/**
+ * Where a waiver's uses are written down.
+ *
+ * The core decides what a use means and what a run of them adds up to; this
+ * decides where the bytes go — the same split every module here follows, so
+ * `@trazum/core` stays browser-safe and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, and never rewritten.** There is deliberately no prune, no
+ * compaction and no `--clear`: a record of decisions that the tool can erase
+ * is a record nobody can rely on, and the one thing a waiver history is for is
+ * being awkward six months later. Deleting the file is a thing a person does
+ * with `rm`, on purpose, having seen it.
+ *
+ * **A write that fails never fails the run.** The gate's job is the exit code.
+ * A read-only checkout, a full disk or a directory somebody's CI cannot create
+ * must not turn a passing build red on account of bookkeeping — the failure is
+ * reported and the gate's own verdict stands.
+ *
+ * **A line that will not parse is counted and skipped**, exactly as in the
+ * store. Losing the whole history because one line is broken would be the
+ * worst possible response; pretending the history is complete would be the
+ * second worst.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isWaiverUse } from '@trazum/core';
+import type { WaiverUse } from '@trazum/core';
+
+/** One file, not one per month: a waiver history is small and read whole. */
+export const WAIVER_LOG = '.trazum/waivers.jsonl';
+
+export interface WaiverReadResult {
+  uses: WaiverUse[];
+  /** 1-based positions of lines that would not parse. Named, never dropped quietly. */
+  unreadable: number[];
+  /** False when the file does not exist — "nothing recorded" is not "no file". */
+  present: boolean;
+}
+
+export async function readWaiverLog(root: string): Promise<WaiverReadResult> {
+  let raw: string;
+  try {
+    raw = await readFile(join(root, WAIVER_LOG), 'utf8');
+  } catch {
+    // Absent is the normal state of a repository that has never waived
+    // anything, and it is not an error.
+    return { uses: [], unreadable: [], present: false };
+  }
+
+  const uses: WaiverUse[] = [];
+  const unreadable: number[] = [];
+  raw.split('\n').forEach((line, index) => {
+    if (line.trim() === '') return;
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (isWaiverUse(parsed)) uses.push(parsed);
+      else unreadable.push(index + 1);
+    } catch {
+      unreadable.push(index + 1);
+    }
+  });
+  return { uses, unreadable, present: true };
+}
+
+/**
+ * Appends one use, and swallows any failure after reporting it.
+ *
+ * Returns the error message rather than throwing, so the caller can print it
+ * beside the gate's own output without the gate ever depending on the write.
+ */
+export async function appendWaiverUse(root: string, use: WaiverUse): Promise<string | null> {
+  const path = join(root, WAIVER_LOG);
+  try {
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, `${JSON.stringify(use)}\n`, { flag: 'a', mode: 0o600 });
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}