@trazum/cli 1.55.0 → 1.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
4
4
  import { dirname, join, resolve as resolvePath } from 'node:path';
5
5
  import { fileURLToPath } from 'node:url';
6
6
  import { gunzipSync } from 'node:zlib';
7
- import { CONTRACT_NAMES, 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, bandGoverns, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, BREAK_EVEN_BAND, allocate, annualRecord, replayCommitment, coversTheTerm, runExperiment, qualityGate, semanticPassCost, verifySemanticProposals, SEMANTIC_SYSTEM_PROMPT, ladderPosition, validateLadder, outcomeReport, rankPerOutcome, FAILURE_POLICIES, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, rollUp, 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';
7
+ import { CONTRACT_NAMES, 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, bandGoverns, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, BREAK_EVEN_BAND, allocate, annualRecord, replayCommitment, coversTheTerm, runExperiment, qualityGate, semanticPassCost, verifySemanticProposals, SEMANTIC_SYSTEM_PROMPT, ladderPosition, validateLadder, outcomeReport, rankPerOutcome, FAILURE_POLICIES, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, rollUp, heartbeats, 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';
8
8
  import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
9
9
  import { dayOf, formatGap, median, spanDays } from './time.js';
10
10
  // Everything that reads the filesystem, on its own entry point so the web
@@ -69,6 +69,7 @@ const VALUE_FLAGS = new Set([
69
69
  'max-usd',
70
70
  'max-growth-usd',
71
71
  'max-cache-loss-usd',
72
+ 'max-stale-hours',
72
73
  'max-day-usd',
73
74
  'max-session-usd',
74
75
  'csv-out',
@@ -326,6 +327,7 @@ const COMMAND_FLAGS = {
326
327
  init: ['dry-run', 'yes', 'json', 'pricing', 'pricing-live'],
327
328
  conform: ['contract', 'json'],
328
329
  rollup: ['json'],
330
+ pulse: ['json', 'max-stale-hours'],
329
331
  feedback: [],
330
332
  gateway: ['on-cannot-tell', 'port', 'socket', 'pricing', 'pricing-live'],
331
333
  ladder: ['pricing', 'pricing-live', 'since', 'until', 'label'],
@@ -1713,6 +1715,99 @@ async function commandRollup(args, t) {
1713
1715
  }
1714
1716
  console.log();
1715
1717
  }
1718
+ /**
1719
+ * `trazum pulse [--max-stale-hours <n>] [--json]` — did the things that are
1720
+ * supposed to run, run?
1721
+ *
1722
+ * `watch --once` is built for a scheduler: a cron entry is the whole daemon,
1723
+ * and its state file records each cycle precisely so a restart is honest about
1724
+ * the stretch it did not watch. That file is read by exactly one thing, and
1725
+ * that thing is the next cycle.
1726
+ *
1727
+ * **So nothing could tell you the watcher had stopped, because the thing that
1728
+ * would tell you was the thing that stopped.** A dead cron produces silence,
1729
+ * and a watcher with nothing to report produces silence too. This command is
1730
+ * the outside view: the age of the last watch cycle, the age of the last pull
1731
+ * into the store, and how far the stored measurements reach.
1732
+ *
1733
+ * **It is not a service and does not run itself.** Something has to notice,
1734
+ * and this product's answer is that the something is already in your CI: a
1735
+ * step that runs this with `--max-stale-hours` turns a dead cron into a red
1736
+ * build, on the schedule your CI already has, without Trazum holding anybody's
1737
+ * metrics. Where that answer runs out is written down in docs/ rather than
1738
+ * left to be discovered.
1739
+ *
1740
+ * Exits 1 only when a **run** that has happened before is past a **stated**
1741
+ * threshold. Never on a first run that never happened, and never on how far
1742
+ * the measurements reach — that is a provider reporting on its own schedule,
1743
+ * not a job that failed.
1744
+ */
1745
+ async function commandPulse(args, t) {
1746
+ const root = process.cwd();
1747
+ const maxStaleHours = numberFlag(args, 'max-stale-hours', Number.NaN, t);
1748
+ const state = await readWatchState(root);
1749
+ const { resolved } = await readStore(root);
1750
+ /**
1751
+ * The newest pull and the furthest reach, kept apart.
1752
+ *
1753
+ * One says a job ran; the other says how far its answers go. A store pulled
1754
+ * ten minutes ago whose newest record stops two days back is a healthy cron
1755
+ * in front of a provider that reports late, and a single figure would call
1756
+ * that either a failure or a success depending which half it took.
1757
+ */
1758
+ let storePulledMs = null;
1759
+ let storeCoveredToMs = null;
1760
+ for (const record of resolved.records) {
1761
+ if (storePulledMs === null || record.pulledAtMs > storePulledMs)
1762
+ storePulledMs = record.pulledAtMs;
1763
+ if (storeCoveredToMs === null || record.toMs > storeCoveredToMs)
1764
+ storeCoveredToMs = record.toMs;
1765
+ }
1766
+ const report = heartbeats({ watchCycleMs: state?.lastCycleMs ?? null, storePulledMs, storeCoveredToMs }, Number.isFinite(maxStaleHours)
1767
+ ? { nowMs: Date.now(), maxStaleHours }
1768
+ : { nowMs: Date.now() });
1769
+ if (boolFlag(args, 'json')) {
1770
+ console.log(JSON.stringify(report, null, 2));
1771
+ if (report.stale)
1772
+ process.exitCode = 1;
1773
+ return;
1774
+ }
1775
+ const when = (ms) => new Date(ms).toISOString().replace('T', ' ').slice(0, 16);
1776
+ console.log();
1777
+ console.log(c.bold(t.pulse.heading()));
1778
+ for (const heartbeat of report.beats) {
1779
+ const name = t.pulse.kind(heartbeat.kind);
1780
+ if (heartbeat.lastMs === null) {
1781
+ // Never run is not late. It is a thing nobody has started here, and a
1782
+ // line that shouted about it would be this tool nagging.
1783
+ console.log(` ${c.dim(t.pulse.neverRun(name))}`);
1784
+ continue;
1785
+ }
1786
+ const line = t.pulse.age(name, when(heartbeat.lastMs), heartbeat.ageHours ?? 0);
1787
+ if (heartbeat.verdict === 'stale')
1788
+ console.log(` ${c.red(`✗ ${line}`)}`);
1789
+ else if (heartbeat.verdict === 'within')
1790
+ console.log(` ${c.green(`✓ ${line}`)}`);
1791
+ else
1792
+ console.log(` ${line}`);
1793
+ }
1794
+ console.log();
1795
+ if (report.maxStaleHours === null) {
1796
+ // Nothing was judged, and the exit code says so silently. Said out loud,
1797
+ // because a screen of green ticks with no threshold behind them is the
1798
+ // shape somebody reads as "checked".
1799
+ console.log(` ${c.dim(wrap(t.pulse.noThreshold(), 74, ' '))}`);
1800
+ }
1801
+ else if (report.stale) {
1802
+ process.exitCode = 1;
1803
+ console.log(` ${c.red(wrap(t.pulse.stale(report.maxStaleHours), 74, ' '))}`);
1804
+ }
1805
+ else {
1806
+ console.log(` ${c.dim(wrap(t.pulse.within(report.maxStaleHours), 74, ' '))}`);
1807
+ }
1808
+ console.log(` ${c.dim(wrap(t.pulse.notAService(), 74, ' '))}`);
1809
+ console.log();
1810
+ }
1716
1811
  /**
1717
1812
  * `trazum feedback` — where to say it, and what to say.
1718
1813
  *
@@ -3967,6 +4062,14 @@ async function commandHistory(args, config, configDir, pricing, t) {
3967
4062
  }
3968
4063
  return t.history.runCache(n(run.periods), run.sinceName, pct(run.from), pct(run.to));
3969
4064
  };
4065
+ /**
4066
+ * The hole under a run, on the run's own line.
4067
+ *
4068
+ * A run is consecutive *reports*, and reads as consecutive *time* unless
4069
+ * told otherwise. A caveat one section away is a caveat that arrives after
4070
+ * the reader has already formed the sentence.
4071
+ */
4072
+ const runHole = (run) => run.unmeasuredDays > 0 ? t.history.runHole(run.unmeasuredDays) : '';
3970
4073
  const lines = (md) => {
3971
4074
  const out = [];
3972
4075
  const first = history.periods[0];
@@ -3980,7 +4083,8 @@ async function commandHistory(args, config, configDir, pricing, t) {
3980
4083
  if (history.runs.length > 0)
3981
4084
  out.push('');
3982
4085
  for (const run of history.runs) {
3983
- out.push(md ? `- ${runLine(run)}` : ` ! ${runLine(run)}`);
4086
+ const line = `${runLine(run)}${runHole(run)}`;
4087
+ out.push(md ? `- ${line}` : ` ! ${line}`);
3984
4088
  }
3985
4089
  if (history.repeatedPlanActions.length > 0)
3986
4090
  out.push('');
@@ -3989,6 +4093,28 @@ async function commandHistory(args, config, configDir, pricing, t) {
3989
4093
  const row = t.history.repeated(repeat.kind, name, repeat.model, n(repeat.appearances), repeat.firstPlanned?.slice(0, 10) ?? null, repeat.lastPlanned?.slice(0, 10) ?? null);
3990
4094
  out.push(md ? `- ${row}` : ` ! ${row}`);
3991
4095
  }
4096
+ /**
4097
+ * The holes in the timeline, before the per-file notes.
4098
+ *
4099
+ * A stretch nobody measured is a fact about the whole series rather than
4100
+ * about one file, and it is the finding this command could not make until
4101
+ * now: a scheduled run that stopped three weeks ago produces a series that
4102
+ * looks exactly like a shorter one.
4103
+ */
4104
+ if (history.unmeasured.length > 0) {
4105
+ out.push('');
4106
+ const total = history.unmeasured.reduce((sum, hole) => sum + hole.days, 0);
4107
+ const summary = t.history.unmeasuredTotal(total);
4108
+ out.push(md ? `- **${summary}**` : ` ! ${summary}`);
4109
+ for (const hole of history.unmeasured) {
4110
+ const row = t.history.unmeasured(hole.days, day(hole.fromMs), day(hole.toMs), hole.afterName, hole.beforeName);
4111
+ out.push(md ? `- ${row}` : ` ${row}`);
4112
+ }
4113
+ }
4114
+ for (const overlap of history.overlappingReports) {
4115
+ const row = t.history.overlap(overlap.a, overlap.b, overlap.days);
4116
+ out.push(md ? `- ${row}` : ` ! ${row}`);
4117
+ }
3992
4118
  for (const name of history.undatedReports) {
3993
4119
  out.push(md ? `- ${t.history.undated(name)}` : ` ${t.history.undated(name)}`);
3994
4120
  }
@@ -7734,6 +7860,9 @@ async function main() {
7734
7860
  case 'rollup':
7735
7861
  await commandRollup(args, t);
7736
7862
  break;
7863
+ case 'pulse':
7864
+ await commandPulse(args, t);
7865
+ break;
7737
7866
  case 'init':
7738
7867
  await commandInit(args, config, pricing, t);
7739
7868
  break;