@trazum/cli 1.41.0 → 1.43.0

package/src/index.ts

@@ -19,6 +19,12 @@ import {
   CONNECTORS,
   normalizeAnthropicUsage,
   normalizeOpenAIUsage,
+  bucketsFromRecords,
+  evaluateWatch,
+  firedKey,
+  pruneRecords,
+  recordsFromBuckets,
+  storeInventory,
   storedReportFrom,
   verifyPlan,
   cacheEconomics,
@@ -141,6 +147,14 @@ import {
 } from './git.js';
 import type { Revision } from './git.js';
 import { fetchProviderUsage } from './connect.js';
+import { STORE_DIR, appendRecords, readStore, rewriteStore } from './store-fs.js';
+import {
+  WATCH_STATE_VERSION,
+  checkWebhook,
+  postWebhook,
+  readWatchState,
+  writeWatchState,
+} from './watch-run.js';
 import { detectLocale, getCliMessages } from './i18n/index.js';
 import {
   MAX_SUMMARY_CHARS,
@@ -190,6 +204,9 @@ const VALUE_FLAGS = new Set([
   'from-log',
   'min-usd',
   'payload',
+  'keep',
+  'interval',
+  'webhook',
   // `route` takes a path here, and the flag is deliberately not `--prompt`:
   // everywhere else in this tool `--prompt` names a marked prompt *inside* a
   // source file, and reusing it for a path would be a trap laid for the reader.
@@ -492,8 +509,10 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd', 'label', 'since', 'until', 'dry-run', 'markdown-summary', 'by-source'],
   plan: ['json', 'out', 'markdown-out', 'min-usd', 'pricing', 'pricing-live'],
   verify: ['against', 'gate', 'json', 'markdown-out', 'pricing', 'pricing-live'],
-  history: ['json', 'markdown-out'],
-  connect: ['since', 'until', 'payload', 'json', 'out', 'markdown-out', 'pricing', 'pricing-live', 'dry-run'],
+  history: ['store', 'json', 'markdown-out'],
+  connect: ['since', 'until', 'payload', 'store', 'json', 'out', 'markdown-out', 'pricing', 'pricing-live', 'dry-run'],
+  store: ['prune', 'keep', 'json', 'pricing', 'pricing-live', 'dry-run'],
+  watch: ['once', 'interval', 'since', 'payload', 'webhook', 'json', 'pricing', 'pricing-live'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2275,6 +2294,369 @@ function parseWhen(
   throw new Error(t.profile.badWhen(flag, value));
 }
 
+/**
+ * `trazum watch` — the afternoon it happened, said that afternoon.
+ *
+ * One cycle is the primitive: measure, keep, evaluate, emit, remember. The
+ * loop is that cycle in a timer, so a cron entry and a foreground watcher run
+ * exactly the same code and the tests exercise the thing that ships.
+ *
+ * Three transports, all boring on purpose: a non-zero exit code so cron mails
+ * it, a JSON event on stdout so any pipeline can read it, and a webhook for
+ * the operator who already has somewhere for alerts to go. No hosted service
+ * and no account.
+ */
+async function commandWatch(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const root = process.cwd();
+  const asJson = boolFlag(args, 'json');
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+  const day = (msValue: number): string => new Date(msValue).toISOString().slice(0, 10);
+
+  const thresholds = {
+    maxUsd: config.spend?.maxUsd,
+    maxDayUsd: config.spend?.maxDayUsd,
+    maxCacheLossUsd: config.spend?.maxCacheLossUsd,
+  };
+  if (
+    thresholds.maxUsd === undefined &&
+    thresholds.maxDayUsd === undefined &&
+    thresholds.maxCacheLossUsd === undefined
+  ) {
+    throw new Error(t.watch.noThresholds());
+  }
+
+  /**
+   * A webhook is a new outbound surface, so it is checked before anything is
+   * sent: credentials in a URL end up in logs and shell history, and an alert
+   * carrying spend figures over plain http across a network is a leak the
+   * operator did not ask for. Loopback is the exception, because pointing a
+   * watcher at your own alerting daemon is the ordinary case.
+   */
+  const webhookRaw = stringFlag(args, 'webhook');
+  let webhook: URL | null = null;
+  if (webhookRaw !== undefined) {
+    const checked = checkWebhook(webhookRaw);
+    if (!checked.ok) throw new Error(t.watch.badWebhook(checked.reason));
+    webhook = checked.url;
+  }
+
+  const intervalRaw = stringFlag(args, 'interval');
+  const once = boolFlag(args, 'once') || intervalRaw === undefined;
+  let intervalMs = 0;
+  if (!once) {
+    const match = /^(\d+)(m|h)$/.exec(intervalRaw!);
+    const amount = match === null ? NaN : Number(match[1]);
+    intervalMs = match?.[2] === 'h' ? amount * 3_600_000 : amount * 60_000;
+    // Usage APIs are rate limited, and a tight loop is a way to get somebody's
+    // key throttled by a tool that was supposed to save them money.
+    if (!Number.isFinite(intervalMs) || intervalMs < 5 * 60_000) {
+      throw new Error(t.watch.intervalTooTight());
+    }
+  }
+
+  const cycle = async (): Promise<number> => {
+    const state = await readWatchState(root);
+    const nowMs = Date.now();
+
+    /**
+     * Where the measurements come from: a saved payload when one is named
+     * (which is how this is tested and how an air-gapped run works), and the
+     * store otherwise. A cycle that found nothing to measure says so — a
+     * watcher over nothing is a green light nobody earned.
+     */
+    const payloadPath = stringFlag(args, 'payload');
+    let pull;
+    if (payloadPath !== undefined) {
+      pull = normalizeAnthropicUsage(JSON.parse(await readFile(payloadPath, 'utf8')));
+    } else {
+      const { resolved } = await readStore(root);
+      if (resolved.records.length === 0) throw new Error(t.watch.nothingToWatch(STORE_DIR));
+      pull = {
+        provider: 'store',
+        granularity: 'bucketed' as const,
+        buckets: bucketsFromRecords(resolved.records),
+        window: null,
+        gaps: [],
+        unavailable: [],
+      };
+    }
+
+    const report = bucketedProfile(pull, { catalogue: pricing });
+    const cache = bucketedCacheEconomics(report);
+    const result = evaluateWatch({
+      report,
+      thresholds,
+      cacheDeltaUsd: cache.verdict === 'no-cache' ? undefined : cache.deltaUsd,
+      nowMs,
+      lastCoveredToMs: state?.lastCoveredToMs ?? undefined,
+      alreadyFired: new Set(Object.keys(state?.fired ?? {})),
+    });
+
+    if (asJson) {
+      console.log(JSON.stringify({ schemaVersion: 1, firedAtMs: nowMs, ...result }, null, 2));
+    } else {
+      if (result.gap !== null) {
+        console.log(c.yellow(wrap(t.watch.gap(day(result.gap.fromMs), day(result.gap.toMs)), 76, '  ')));
+      }
+      for (const crossing of result.crossings) {
+        console.log(
+          c.red(
+            wrap(
+              t.watch.crossed(
+                crossing.gate,
+                formatUsd(crossing.measuredUsd),
+                formatUsd(crossing.limitUsd),
+                crossing.day,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      for (const abstention of result.abstentions) {
+        console.log(
+          c.dim(
+            wrap(
+              t.watch.notJudgeable(
+                abstention.gate,
+                abstention.reason,
+                abstention.detail === null
+                  ? null
+                  : `${Math.round((abstention.detail.coveredMs / abstention.detail.neededMs) * 100)}%`,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      for (const still of result.suppressed) {
+        console.log(
+          c.yellow(
+            wrap(
+              t.watch.stillOver(
+                still.gate,
+                formatUsd(still.measuredUsd),
+                formatUsd(still.limitUsd),
+                still.day,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      if (
+        result.crossings.length === 0 &&
+        result.suppressed.length === 0 &&
+        result.abstentions.length === 0
+      ) {
+        console.log(c.green(wrap(t.watch.allWithin(n(Object.keys(thresholds).filter((k) => thresholds[k as keyof typeof thresholds] !== undefined).length)), 76, '  ')));
+      }
+    }
+
+    if (webhook !== null && result.crossings.length > 0) {
+      const sent = await postWebhook(webhook, {
+        schemaVersion: 1,
+        firedAtMs: nowMs,
+        crossings: result.crossings,
+      });
+      if (!sent.ok) {
+        // Reported and swallowed: the exit code and the event already carried
+        // the crossing, and losing those because a receiver is down would make
+        // the quietest failure the loudest one.
+        console.error(c.yellow(t.watch.webhookFailed(sent.status === null ? sent.error ?? '' : String(sent.status))));
+      }
+    }
+
+    const fired = { ...(state?.fired ?? {}) };
+    for (const crossing of result.crossings) fired[firedKey(crossing.gate, crossing.day)] = nowMs;
+    await writeWatchState(root, {
+      v: WATCH_STATE_VERSION,
+      lastCycleMs: nowMs,
+      lastCoveredToMs: report.span?.toMs ?? state?.lastCoveredToMs ?? null,
+      fired,
+    });
+
+    return result.crossings.length + result.suppressed.length;
+  };
+
+  const crossed = await cycle();
+  // Still over is still a failure: only the alert was already sent.
+  if (crossed > 0) process.exitCode = 1;
+  if (once) return;
+
+  console.log(c.dim(t.watch.watching(String(Math.round(intervalMs / 60_000)))));
+  // The loop is the cycle in a timer and nothing more, so the primitive above
+  // is the only thing that ever needs testing.
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    await cycle();
+  }
+}
+
+/**
+ * `trazum store` — what is kept, and what a prune would take.
+ *
+ * The store is the one thing in this product that *deletes* something, so the
+ * errands around it are written to make that visible: the inventory says what
+ * is there and how far back, and `--prune` names what went with the span it
+ * covered. Retention with no policy written down is refused rather than
+ * defaulted — deleting measurements on a guess is not something anybody
+ * should receive by accident.
+ */
+async function commandStore(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const root = process.cwd();
+  const { resolved, unreadable, files } = await readStore(root);
+  const inventory = storeInventory(resolved);
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+  const day = (msValue: number): string => new Date(msValue).toISOString().slice(0, 10);
+
+  const priced = bucketedProfile(
+    {
+      provider: 'store',
+      granularity: 'bucketed',
+      buckets: bucketsFromRecords(resolved.records),
+      window: inventory.span,
+      gaps: [],
+      unavailable: [],
+    },
+    { catalogue: pricing },
+  );
+
+  if (boolFlag(args, 'prune')) {
+    const keepFlag = stringFlag(args, 'keep');
+    const keepDays = keepFlag !== undefined
+      ? Number(/^(\d+)d?$/.exec(keepFlag)?.[1] ?? NaN)
+      : config.store?.keepDays;
+    if (keepDays === undefined || !Number.isFinite(keepDays) || keepDays <= 0) {
+      throw new Error(t.store.pruneNeedsPolicy());
+    }
+    const cutoff = Date.now() - keepDays * 86_400_000;
+    const result = pruneRecords(resolved.records, cutoff);
+    const droppedUsd = bucketedProfile(
+      {
+        provider: 'store',
+        granularity: 'bucketed',
+        buckets: bucketsFromRecords(result.dropped),
+        window: null,
+        gaps: [],
+        unavailable: [],
+      },
+      { catalogue: pricing },
+    ).total.totalUsd;
+
+    if (boolFlag(args, 'dry-run')) {
+      console.log(
+        wrap(
+          t.store.pruneDryRun(
+            n(result.dropped.length),
+            String(keepDays),
+            result.droppedSpan === null
+              ? null
+              : `${day(result.droppedSpan.fromMs)} → ${day(result.droppedSpan.toMs)}`,
+            formatUsd(droppedUsd),
+          ),
+          76,
+          '  ',
+        ),
+      );
+      return;
+    }
+
+    // The prune also collapses the append log to what the store resolves to,
+    // which is the only moment a rewrite is safe: it is what the reader was
+    // already seeing.
+    await rewriteStore(root, result.kept);
+    console.log(
+      wrap(
+        t.store.pruned(
+          n(result.dropped.length),
+          String(keepDays),
+          result.droppedSpan === null
+            ? null
+            : `${day(result.droppedSpan.fromMs)} → ${day(result.droppedSpan.toMs)}`,
+          formatUsd(droppedUsd),
+          n(result.kept.length),
+        ),
+        76,
+        '  ',
+      ),
+    );
+    return;
+  }
+
+  if (boolFlag(args, 'json')) {
+    console.log(JSON.stringify({ ...inventory, totalUsd: priced.total.totalUsd, unreadable }, null, 2));
+    return;
+  }
+
+  /**
+   * Empty means *nothing at all* — not "nothing I could resolve".
+   *
+   * Records the store could not tell apart, lines it could not parse and
+   * records from a newer schema are all real measurements sitting on disk.
+   * Reporting an empty store over them would hide exactly what the reader
+   * needs to see, which is the failure this whole module is written against.
+   */
+  const nothingAtAll =
+    inventory.totalRecords === 0 &&
+    inventory.possiblyDouble === 0 &&
+    inventory.unknownVersion === 0 &&
+    unreadable.length === 0;
+  if (nothingAtAll) {
+    console.log(wrap(t.store.empty(STORE_DIR), 76, '  '));
+    return;
+  }
+
+  console.log(
+    c.bold(
+      t.store.heading(
+        n(inventory.totalRecords),
+        formatUsd(priced.total.totalUsd),
+        inventory.span === null ? '' : day(inventory.span.fromMs),
+        inventory.span === null ? '' : day(inventory.span.toMs),
+      ),
+    ),
+  );
+  for (const provider of inventory.providers) {
+    console.log(
+      `  ${t.store.providerRow(
+        provider.provider,
+        n(provider.records),
+        provider.span === null ? '' : `${day(provider.span.fromMs)} → ${day(provider.span.toMs)}`,
+        n(provider.models.length),
+      )}`,
+    );
+  }
+  console.log();
+  console.log(`  ${c.dim(wrap(t.store.holds(n(files.length)), 74, '    '))}`);
+  if (inventory.possiblyDouble > 0) {
+    console.log(`  ${c.yellow(wrap(t.store.possiblyDouble(n(inventory.possiblyDouble)), 74, '    '))}`);
+  }
+  if (inventory.unknownVersion > 0) {
+    console.log(`  ${c.yellow(wrap(t.store.unknownVersion(n(inventory.unknownVersion)), 74, '    '))}`);
+  }
+  for (const bad of unreadable) {
+    console.log(`  ${c.yellow(wrap(t.store.unreadable(bad.file, String(bad.line)), 74, '    '))}`);
+  }
+  const keepDays = config.store?.keepDays;
+  console.log(
+    `  ${c.dim(wrap(keepDays === undefined ? t.store.noRetention() : t.store.retention(String(keepDays)), 74, '    '))}`,
+  );
+}
+
 /**
  * `trazum connect <provider>` — the bill, read from the provider.
  *
@@ -2348,6 +2730,17 @@ async function commandConnect(
   const cache = bucketedCacheEconomics(report);
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
 
+  /**
+   * `--store` keeps what was pulled, so the next run does not download it
+   * again and `history` has a series without anybody curating a folder. Opt
+   * in rather than automatic: a command that starts writing to a hidden
+   * directory on its own is a command nobody trusts twice.
+   */
+  let stored = 0;
+  if (boolFlag(args, 'store')) {
+    stored = await appendRecords(process.cwd(), recordsFromBuckets(pull.provider, pull.buckets, Date.now()));
+  }
+
   const outPath = stringFlag(args, 'out');
   if (outPath !== undefined) {
     await writeFile(outPath, `${JSON.stringify({ ...report, pulledFrom: source.variable }, null, 2)}\n`);
@@ -2438,6 +2831,7 @@ async function commandConnect(
     else console.log(`  ${wrap(row, 74, '    ')}`);
   }
   if (outPath !== undefined) console.log(c.dim(t.connect.wrote(outPath)));
+  if (stored > 0) console.log(c.dim(t.store.appended(n(stored), STORE_DIR)));
 }
 
 /**
@@ -2449,40 +2843,103 @@ async function commandConnect(
  * same action planned twice — and no series, however long, becomes a
  * forecast.
  */
-async function commandHistory(args: Args, t: CliMessages): Promise<void> {
-  const path = args.positional[0];
-  if (path === undefined) throw new Error(t.history.noTarget());
-  const target = await stat(path).catch(() => null);
-  if (!target?.isDirectory()) throw new Error(t.history.noTarget());
-
-  const entries = await readdir(path, { withFileTypes: true });
-  const files = entries
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
-    .map((entry) => join(path, entry.name))
-    .sort((a, b) => a.localeCompare(b));
-
+async function commandHistory(args: Args, pricing: PricingCatalogue, t: CliMessages): Promise<void> {
+  /**
+   * `--store` builds the series from measured spend already on disk.
+   *
+   * Bucketed sources carry no label — a usage API groups by model and
+   * workspace, never by workload — so the label series is *absent and named*
+   * rather than empty and misread, the same discipline the connected report
+   * uses for the findings a sum cannot support. The model-share and
+   * cache-share series are exactly what a series exists for, and both work.
+   */
   const reports: StoredReport[] = [];
   const plans: (PlanDocument & { createdAt?: string })[] = [];
   const unrecognized: string[] = [];
-  for (const file of files) {
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(await readFile(file, 'utf8'));
-    } catch {
-      unrecognized.push(file);
-      continue;
-    }
-    const report = storedReportFrom(file, parsed);
-    if (report !== null) {
-      reports.push(report);
-      continue;
+  const fromStore = boolFlag(args, 'store');
+
+  if (fromStore) {
+    const { resolved } = await readStore(process.cwd());
+    if (resolved.records.length === 0) throw new Error(t.store.empty(STORE_DIR));
+
+    /**
+     * One period per UTC day of stored measurement, priced exactly as a fresh
+     * pull prices it.
+     *
+     * The label series is deliberately absent: a usage API groups by model
+     * and workspace, never by workload, so there is no label to carry.
+     * Rendering an empty label series would read as "no workload moved",
+     * which is a statement about traffic rather than about the source, and
+     * the footer says which it is.
+     */
+    const byDay = new Map<string, typeof resolved.records>();
+    for (const record of resolved.records) {
+      const key = new Date(record.fromMs).toISOString().slice(0, 10);
+      const list = byDay.get(key) ?? [];
+      list.push(record);
+      byDay.set(key, list);
+    }
+    for (const [dayKey, records] of [...byDay.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+      const day = bucketedProfile(
+        {
+          provider: 'store',
+          granularity: 'bucketed',
+          buckets: bucketsFromRecords(records),
+          window: {
+            fromMs: Math.min(...records.map((r) => r.fromMs)),
+            toMs: Math.max(...records.map((r) => r.toMs)),
+          },
+          gaps: [],
+          unavailable: [],
+        },
+        { catalogue: pricing },
+      );
+      const cacheTouched = day.total.cacheReadTokens + day.total.cacheWriteTokens;
+      reports.push({
+        name: dayKey,
+        span: day.span,
+        totalUsd: day.total.totalUsd,
+        calls: day.total.calls,
+        byLabel: new Map(),
+        byModel: new Map(day.byModel.map((slice) => [slice.model, slice.totalUsd])),
+        cacheReadShare:
+          day.total.inputTokens + cacheTouched > 0
+            ? day.total.cacheReadTokens / (day.total.inputTokens + cacheTouched)
+            : null,
+      });
     }
-    const maybePlan = parsed as PlanDocument & { createdAt?: string };
-    if (maybePlan?.schemaVersion === 1 && Array.isArray(maybePlan.actions)) {
-      plans.push(maybePlan);
-      continue;
+  } else {
+    const path = args.positional[0];
+    if (path === undefined) throw new Error(t.history.noTarget());
+    const target = await stat(path).catch(() => null);
+    if (!target?.isDirectory()) throw new Error(t.history.noTarget());
+
+    const entries = await readdir(path, { withFileTypes: true });
+    const files = entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+      .map((entry) => join(path, entry.name))
+      .sort((a, b) => a.localeCompare(b));
+
+    for (const file of files) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(await readFile(file, 'utf8'));
+      } catch {
+        unrecognized.push(file);
+        continue;
+      }
+      const report = storedReportFrom(file, parsed);
+      if (report !== null) {
+        reports.push(report);
+        continue;
+      }
+      const maybePlan = parsed as PlanDocument & { createdAt?: string };
+      if (maybePlan?.schemaVersion === 1 && Array.isArray(maybePlan.actions)) {
+        plans.push(maybePlan);
+        continue;
+      }
+      unrecognized.push(file);
     }
-    unrecognized.push(file);
   }
 
   const history = buildHistory(reports, plans);
@@ -2516,7 +2973,7 @@ async function commandHistory(args: Args, t: CliMessages): Promise<void> {
       const row = t.history.periodRow(
         period.name,
         formatUsd(period.totalUsd),
-        n(period.calls),
+        period.calls === null ? null : n(period.calls),
         ((period.toMs - period.fromMs) / 86_400_000).toFixed(1),
       );
       out.push(md ? `- ${row}` : `  ${row}`);
@@ -2544,6 +3001,11 @@ async function commandHistory(args: Args, t: CliMessages): Promise<void> {
     for (const name of unrecognized) {
       out.push(md ? `- ${t.history.unrecognized(name)}` : `  ${t.history.unrecognized(name)}`);
     }
+    if (fromStore) {
+      out.push('');
+      const note = t.history.storeNoLabels();
+      out.push(md ? `_${note}_` : `  ${note}`);
+    }
     out.push('');
     out.push(md ? `_${t.history.footer()}_` : `  ${t.history.footer()}`);
     return out;
@@ -6615,11 +7077,17 @@ async function main(): Promise<void> {
       await commandVerify(args, pricing, t);
       break;
     case 'history':
-      await commandHistory(args, t);
+      await commandHistory(args, pricing, t);
       break;
     case 'connect':
       await commandConnect(args, pricing, t);
       break;
+    case 'store':
+      await commandStore(args, config, pricing, t);
+      break;
+    case 'watch':
+      await commandWatch(args, config, pricing, t);
+      break;
     case 'route':
       await commandRoute(args, pricing, t);
       break;