@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trazum/cli",
3
- "version": "1.55.0",
3
+ "version": "1.56.0",
4
4
  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
5
5
  "license": "MIT",
6
6
  "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
37
37
  "prepublishOnly": "npm run build && npm test"
38
38
  },
39
39
  "dependencies": {
40
- "@trazum/core": "1.55.0"
40
+ "@trazum/core": "1.56.0"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/i18n/en.ts CHANGED
@@ -57,6 +57,7 @@ ${bold('USAGE')}
57
57
  trazum where [file]
58
58
  trazum conform <file|-> [--contract <name>]
59
59
  trazum rollup <document...|dir> [--json]
60
+ trazum pulse [--max-stale-hours <n>]
60
61
  trazum models
61
62
  trazum rules
62
63
  trazum gateway <provider> --on-cannot-tell <fail-open|fail-closed>
@@ -116,6 +117,25 @@ ${bold('OPTIONS FOR rollup')}
116
117
 
117
118
  Exits 1 when a contribution was handed over and could not be merged.
118
119
 
120
+ ${bold('OPTIONS FOR pulse')}
121
+ --max-stale-hours <n> Exit 1 when something that runs here has not run
122
+ in over n hours. Without it, the ages are
123
+ reported and nothing is judged.
124
+ --json The report as data.
125
+
126
+ Did the things that are supposed to run, run? \`watch --once\` is built for a
127
+ scheduler, and its state file is read by exactly one thing — the next cycle.
128
+ So nothing could tell you the watcher had stopped, because the thing that
129
+ would tell you was the thing that stopped.
130
+
131
+ It runs nothing and hosts nothing. Something has to notice, and the something
132
+ is your CI: a step running this on the schedule you already have turns a dead
133
+ cron into a red build, without Trazum holding anybody's metrics.
134
+
135
+ Never gates on a first run that never happened — that has no cadence to be
136
+ late against — and never on how far the measurements reach, which is a
137
+ provider reporting on its own schedule rather than a job that failed.
138
+
119
139
  ${bold('OPTIONS FOR feedback')}
120
140
  (none)
121
141
 
@@ -1461,6 +1481,31 @@ ${bold('EXAMPLES')}
1461
1481
  },
1462
1482
  },
1463
1483
 
1484
+ pulse: {
1485
+ heading: () => 'Did the things that are supposed to run, run?',
1486
+ kind: (kind) => {
1487
+ switch (kind) {
1488
+ case 'watch-cycle':
1489
+ return 'last watch cycle';
1490
+ case 'store-pull':
1491
+ return 'last pull into the store';
1492
+ case 'store-coverage':
1493
+ return 'measurements reach up to';
1494
+ default:
1495
+ return kind;
1496
+ }
1497
+ },
1498
+ neverRun: (name) => `${name}: never here. Not late — there is no cadence to be late against.`,
1499
+ age: (name, when, hours) => `${name}: ${when}Z, ${plural(hours, 'hour')} ago`,
1500
+ noThreshold: () =>
1501
+ 'Nothing was judged. Pass --max-stale-hours <n> to make a run that stopped a failing exit code; how stale is too stale is a policy, and this tool does not write yours.',
1502
+ within: (hours) => `Everything that has run here ran within ${plural(hours, 'hour')}.`,
1503
+ stale: (hours) =>
1504
+ `Something that runs here has not run in over ${plural(hours, 'hour')}. Silence from a scheduled job and silence from a job with nothing to report look identical; this is which.`,
1505
+ notAService: () =>
1506
+ 'This command runs nothing and hosts nothing. Something has to notice, and the something is your CI: a step that runs this on the schedule you already have turns a dead cron into a red build, without Trazum holding anybody\'s metrics. How far the measurements reach is reported and never judged — that is a provider reporting on its own schedule, not a job that failed.',
1507
+ },
1508
+
1464
1509
  where: {
1465
1510
  hostHeading: () => 'Running inside',
1466
1511
  subscription: (host) =>
@@ -2430,6 +2475,13 @@ ${bold('EXAMPLES')}
2430
2475
  },
2431
2476
  storeNoLabels: () =>
2432
2477
  'This series comes from the store, and a usage API groups by model and workspace rather than by workload — so there is no label series here at all. Absent, not empty: nothing above says a workload did or did not move.',
2478
+ unmeasured: (days, from, to, after, before) =>
2479
+ `Nothing covers ${from} to ${to} — ${plural(days, 'day')} between ${after} and ${before}.`,
2480
+ unmeasuredTotal: (days) =>
2481
+ `${plural(days, 'day')} of this stretch are covered by no report. A series with a hole in it and a shorter series read identically; this is which.`,
2482
+ overlap: (a, b, days) =>
2483
+ `${a} and ${b} both cover ${plural(days, 'day')}. Named, never merged — which is the better measurement is not knowable from here, and adding both totals counts those days twice.`,
2484
+ runHole: (days) => ` — ${plural(days, 'day')} of this run are covered by no report`,
2433
2485
  undated: (name) => `${name} carries no span, so it is on no timeline above — named, never silently absorbed.`,
2434
2486
  unrecognized: (name) => `${name} is neither a stored report nor a saved plan, so it is in no series above.`,
2435
2487
  footer: () =>
package/src/i18n/es.ts CHANGED
@@ -44,6 +44,7 @@ ${bold('USO')}
44
44
  trazum where [fichero]
45
45
  trazum conform <fichero|-> [--contract <nombre>]
46
46
  trazum rollup <documento...|dir> [--json]
47
+ trazum pulse [--max-stale-hours <n>]
47
48
  trazum models
48
49
  trazum rules
49
50
  trazum gateway <provider> --on-cannot-tell <fail-open|fail-closed>
@@ -104,6 +105,25 @@ ${bold('OPCIONES DE rollup')}
104
105
 
105
106
  Sale con 1 cuando una contribución se entregó y no se pudo agregar.
106
107
 
108
+ ${bold('OPCIONES DE pulse')}
109
+ --max-stale-hours <n> Sale con 1 cuando algo que corre aquí lleva más
110
+ de n horas sin correr. Sin esto, se informan las
111
+ edades y no se juzga nada.
112
+ --json El informe como datos.
113
+
114
+ ¿Corrieron las cosas que tienen que correr? \`watch --once\` está hecho para un
115
+ planificador, y su fichero de estado lo lee exactamente una cosa: el siguiente
116
+ ciclo. Así que nada podía decirte que el vigilante se había parado, porque lo
117
+ que te lo diría era lo que se había parado.
118
+
119
+ No ejecuta nada y no aloja nada. Algo tiene que darse cuenta, y ese algo es tu
120
+ CI: un paso que ejecute esto con el horario que ya tienes convierte un cron
121
+ muerto en una build roja, sin que Trazum guarde las métricas de nadie.
122
+
123
+ Nunca falla por una primera ejecución que nunca ocurrió — no hay cadencia
124
+ contra la que ir tarde — ni por hasta dónde llegan las mediciones, que es un
125
+ proveedor informando a su ritmo y no un trabajo que falló.
126
+
107
127
  ${bold('OPCIONES DE feedback')}
108
128
  (ninguna)
109
129
 
@@ -1468,6 +1488,32 @@ ${bold('EJEMPLOS')}
1468
1488
  },
1469
1489
  },
1470
1490
 
1491
+ pulse: {
1492
+ heading: () => '¿Corrieron las cosas que tienen que correr?',
1493
+ kind: (kind) => {
1494
+ switch (kind) {
1495
+ case 'watch-cycle':
1496
+ return 'último ciclo de watch';
1497
+ case 'store-pull':
1498
+ return 'última descarga al almacén';
1499
+ case 'store-coverage':
1500
+ return 'las mediciones llegan hasta';
1501
+ default:
1502
+ return kind;
1503
+ }
1504
+ },
1505
+ neverRun: (name) =>
1506
+ `${name}: nunca aquí. No va tarde — no hay cadencia contra la que ir tarde.`,
1507
+ age: (name, when, hours) => `${name}: ${when}Z, hace ${plural(hours, 'hora')}`,
1508
+ noThreshold: () =>
1509
+ 'No se juzgó nada. Pasa --max-stale-hours <n> para que algo que dejó de correr sea un código de salida en rojo; cuánto es demasiado es una política, y esta herramienta no escribe la tuya.',
1510
+ within: (hours) => `Todo lo que corre aquí corrió dentro de ${plural(hours, 'hora')}.`,
1511
+ stale: (hours) =>
1512
+ `Algo que corre aquí lleva más de ${plural(hours, 'hora')} sin correr. El silencio de un trabajo programado y el de un trabajo sin nada que decir son iguales; esto dice cuál es.`,
1513
+ notAService: () =>
1514
+ 'Este comando no ejecuta nada y no aloja nada. Algo tiene que darse cuenta, y ese algo es tu CI: un paso que ejecute esto con el horario que ya tienes convierte un cron muerto en una build roja, sin que Trazum guarde las métricas de nadie. Hasta dónde llegan las mediciones se informa y nunca se juzga — eso es un proveedor informando a su ritmo, no un trabajo que falló.',
1515
+ },
1516
+
1471
1517
  where: {
1472
1518
  hostHeading: () => 'Ejecutándose dentro de',
1473
1519
  subscription: (host) =>
@@ -2434,6 +2480,13 @@ ${bold('EJEMPLOS')}
2434
2480
  },
2435
2481
  storeNoLabels: () =>
2436
2482
  'Esta serie viene del almacén, y una API de uso agrupa por modelo y workspace, no por carga de trabajo — así que aquí no hay serie por label en absoluto. Ausente, no vacía: nada de lo de arriba dice que una carga se moviera o dejara de moverse.',
2483
+ unmeasured: (days, from, to, after, before) =>
2484
+ `Nada cubre del ${from} al ${to} — ${plural(days, 'día')} entre ${after} y ${before}.`,
2485
+ unmeasuredTotal: (days) =>
2486
+ `${plural(days, 'día')} de este tramo no los cubre ningún informe. Una serie con un agujero y una serie más corta se leen igual; esto dice cuál es.`,
2487
+ overlap: (a, b, days) =>
2488
+ `${a} y ${b} cubren ambos ${plural(days, 'día')}. Nombrado, nunca fusionado — cuál es la mejor medición no se sabe desde aquí, y sumar los dos totales cuenta esos días dos veces.`,
2489
+ runHole: (days) => ` — ${plural(days, 'día')} de esta racha no los cubre ningún informe`,
2437
2490
  undated: (name) => `${name} no lleva período, así que no está en ninguna línea de tiempo de arriba — nombrado, nunca absorbido en silencio.`,
2438
2491
  unrecognized: (name) => `${name} no es ni un informe guardado ni un plan guardado, así que no está en ninguna serie de arriba.`,
2439
2492
  footer: () =>
package/src/i18n/types.ts CHANGED
@@ -461,6 +461,17 @@ export interface CliMessages {
461
461
  caveat(code: string): string;
462
462
  };
463
463
 
464
+ pulse: {
465
+ heading(): string;
466
+ kind(kind: string): string;
467
+ neverRun(name: string): string;
468
+ age(name: string, when: string, hours: number): string;
469
+ noThreshold(): string;
470
+ within(hours: number): string;
471
+ stale(hours: number): string;
472
+ notAService(): string;
473
+ };
474
+
464
475
  where: {
465
476
  hostHeading(): string;
466
477
  subscription(host: string): string;
@@ -1509,6 +1520,10 @@ export interface CliMessages {
1509
1520
  /** A store source carries no labels, so the label series is absent, not empty. */
1510
1521
  storeNoLabels(): string;
1511
1522
  undated(name: string): string;
1523
+ unmeasured(days: number, from: string, to: string, after: string, before: string): string;
1524
+ unmeasuredTotal(days: number): string;
1525
+ overlap(a: string, b: string, days: number): string;
1526
+ runHole(days: number): string;
1512
1527
  unrecognized(name: string): string;
1513
1528
  footer(): string;
1514
1529
  /** The waiver record — what this team has been living with, and for how long. */
package/src/index.ts CHANGED
@@ -70,6 +70,7 @@ import {
70
70
  assignSources,
71
71
  fleetRollup,
72
72
  rollUp,
73
+ heartbeats,
73
74
  labelCoverage,
74
75
  measuredUsage,
75
76
  gateMargin,
@@ -297,6 +298,7 @@ const VALUE_FLAGS = new Set([
297
298
  'max-usd',
298
299
  'max-growth-usd',
299
300
  'max-cache-loss-usd',
301
+ 'max-stale-hours',
300
302
  'max-day-usd',
301
303
  'max-session-usd',
302
304
  'csv-out',
@@ -595,6 +597,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
595
597
  init: ['dry-run', 'yes', 'json', 'pricing', 'pricing-live'],
596
598
  conform: ['contract', 'json'],
597
599
  rollup: ['json'],
600
+ pulse: ['json', 'max-stale-hours'],
598
601
  feedback: [],
599
602
  gateway: ['on-cannot-tell', 'port', 'socket', 'pricing', 'pricing-live'],
600
603
  ladder: ['pricing', 'pricing-live', 'since', 'until', 'label'],
@@ -2263,6 +2266,102 @@ async function commandRollup(args: Args, t: CliMessages): Promise<void> {
2263
2266
  console.log();
2264
2267
  }
2265
2268
 
2269
+ /**
2270
+ * `trazum pulse [--max-stale-hours <n>] [--json]` — did the things that are
2271
+ * supposed to run, run?
2272
+ *
2273
+ * `watch --once` is built for a scheduler: a cron entry is the whole daemon,
2274
+ * and its state file records each cycle precisely so a restart is honest about
2275
+ * the stretch it did not watch. That file is read by exactly one thing, and
2276
+ * that thing is the next cycle.
2277
+ *
2278
+ * **So nothing could tell you the watcher had stopped, because the thing that
2279
+ * would tell you was the thing that stopped.** A dead cron produces silence,
2280
+ * and a watcher with nothing to report produces silence too. This command is
2281
+ * the outside view: the age of the last watch cycle, the age of the last pull
2282
+ * into the store, and how far the stored measurements reach.
2283
+ *
2284
+ * **It is not a service and does not run itself.** Something has to notice,
2285
+ * and this product's answer is that the something is already in your CI: a
2286
+ * step that runs this with `--max-stale-hours` turns a dead cron into a red
2287
+ * build, on the schedule your CI already has, without Trazum holding anybody's
2288
+ * metrics. Where that answer runs out is written down in docs/ rather than
2289
+ * left to be discovered.
2290
+ *
2291
+ * Exits 1 only when a **run** that has happened before is past a **stated**
2292
+ * threshold. Never on a first run that never happened, and never on how far
2293
+ * the measurements reach — that is a provider reporting on its own schedule,
2294
+ * not a job that failed.
2295
+ */
2296
+ async function commandPulse(args: Args, t: CliMessages): Promise<void> {
2297
+ const root = process.cwd();
2298
+ const maxStaleHours = numberFlag(args, 'max-stale-hours', Number.NaN, t);
2299
+
2300
+ const state = await readWatchState(root);
2301
+ const { resolved } = await readStore(root);
2302
+
2303
+ /**
2304
+ * The newest pull and the furthest reach, kept apart.
2305
+ *
2306
+ * One says a job ran; the other says how far its answers go. A store pulled
2307
+ * ten minutes ago whose newest record stops two days back is a healthy cron
2308
+ * in front of a provider that reports late, and a single figure would call
2309
+ * that either a failure or a success depending which half it took.
2310
+ */
2311
+ let storePulledMs: number | null = null;
2312
+ let storeCoveredToMs: number | null = null;
2313
+ for (const record of resolved.records) {
2314
+ if (storePulledMs === null || record.pulledAtMs > storePulledMs) storePulledMs = record.pulledAtMs;
2315
+ if (storeCoveredToMs === null || record.toMs > storeCoveredToMs) storeCoveredToMs = record.toMs;
2316
+ }
2317
+
2318
+ const report = heartbeats(
2319
+ { watchCycleMs: state?.lastCycleMs ?? null, storePulledMs, storeCoveredToMs },
2320
+ Number.isFinite(maxStaleHours)
2321
+ ? { nowMs: Date.now(), maxStaleHours }
2322
+ : { nowMs: Date.now() },
2323
+ );
2324
+
2325
+ if (boolFlag(args, 'json')) {
2326
+ console.log(JSON.stringify(report, null, 2));
2327
+ if (report.stale) process.exitCode = 1;
2328
+ return;
2329
+ }
2330
+
2331
+ const when = (ms: number): string => new Date(ms).toISOString().replace('T', ' ').slice(0, 16);
2332
+
2333
+ console.log();
2334
+ console.log(c.bold(t.pulse.heading()));
2335
+ for (const heartbeat of report.beats) {
2336
+ const name = t.pulse.kind(heartbeat.kind);
2337
+ if (heartbeat.lastMs === null) {
2338
+ // Never run is not late. It is a thing nobody has started here, and a
2339
+ // line that shouted about it would be this tool nagging.
2340
+ console.log(` ${c.dim(t.pulse.neverRun(name))}`);
2341
+ continue;
2342
+ }
2343
+ const line = t.pulse.age(name, when(heartbeat.lastMs), heartbeat.ageHours ?? 0);
2344
+ if (heartbeat.verdict === 'stale') console.log(` ${c.red(`✗ ${line}`)}`);
2345
+ else if (heartbeat.verdict === 'within') console.log(` ${c.green(`✓ ${line}`)}`);
2346
+ else console.log(` ${line}`);
2347
+ }
2348
+
2349
+ console.log();
2350
+ if (report.maxStaleHours === null) {
2351
+ // Nothing was judged, and the exit code says so silently. Said out loud,
2352
+ // because a screen of green ticks with no threshold behind them is the
2353
+ // shape somebody reads as "checked".
2354
+ console.log(` ${c.dim(wrap(t.pulse.noThreshold(), 74, ' '))}`);
2355
+ } else if (report.stale) {
2356
+ process.exitCode = 1;
2357
+ console.log(` ${c.red(wrap(t.pulse.stale(report.maxStaleHours), 74, ' '))}`);
2358
+ } else {
2359
+ console.log(` ${c.dim(wrap(t.pulse.within(report.maxStaleHours), 74, ' '))}`);
2360
+ }
2361
+ console.log(` ${c.dim(wrap(t.pulse.notAService(), 74, ' '))}`);
2362
+ console.log();
2363
+ }
2364
+
2266
2365
  /**
2267
2366
  * `trazum feedback` — where to say it, and what to say.
2268
2367
  *
@@ -5197,6 +5296,16 @@ async function commandHistory(
5197
5296
  return t.history.runCache(n(run.periods), run.sinceName, pct(run.from), pct(run.to));
5198
5297
  };
5199
5298
 
5299
+ /**
5300
+ * The hole under a run, on the run's own line.
5301
+ *
5302
+ * A run is consecutive *reports*, and reads as consecutive *time* unless
5303
+ * told otherwise. A caveat one section away is a caveat that arrives after
5304
+ * the reader has already formed the sentence.
5305
+ */
5306
+ const runHole = (run: HistoryRun): string =>
5307
+ run.unmeasuredDays > 0 ? t.history.runHole(run.unmeasuredDays) : '';
5308
+
5200
5309
  const lines = (md: boolean): string[] => {
5201
5310
  const out: string[] = [];
5202
5311
  const first = history.periods[0]!;
@@ -5214,7 +5323,8 @@ async function commandHistory(
5214
5323
  }
5215
5324
  if (history.runs.length > 0) out.push('');
5216
5325
  for (const run of history.runs) {
5217
- out.push(md ? `- ${runLine(run)}` : ` ! ${runLine(run)}`);
5326
+ const line = `${runLine(run)}${runHole(run)}`;
5327
+ out.push(md ? `- ${line}` : ` ! ${line}`);
5218
5328
  }
5219
5329
  if (history.repeatedPlanActions.length > 0) out.push('');
5220
5330
  for (const repeat of history.repeatedPlanActions) {
@@ -5229,6 +5339,34 @@ async function commandHistory(
5229
5339
  );
5230
5340
  out.push(md ? `- ${row}` : ` ! ${row}`);
5231
5341
  }
5342
+ /**
5343
+ * The holes in the timeline, before the per-file notes.
5344
+ *
5345
+ * A stretch nobody measured is a fact about the whole series rather than
5346
+ * about one file, and it is the finding this command could not make until
5347
+ * now: a scheduled run that stopped three weeks ago produces a series that
5348
+ * looks exactly like a shorter one.
5349
+ */
5350
+ if (history.unmeasured.length > 0) {
5351
+ out.push('');
5352
+ const total = history.unmeasured.reduce((sum, hole) => sum + hole.days, 0);
5353
+ const summary = t.history.unmeasuredTotal(total);
5354
+ out.push(md ? `- **${summary}**` : ` ! ${summary}`);
5355
+ for (const hole of history.unmeasured) {
5356
+ const row = t.history.unmeasured(
5357
+ hole.days,
5358
+ day(hole.fromMs),
5359
+ day(hole.toMs),
5360
+ hole.afterName,
5361
+ hole.beforeName,
5362
+ );
5363
+ out.push(md ? `- ${row}` : ` ${row}`);
5364
+ }
5365
+ }
5366
+ for (const overlap of history.overlappingReports) {
5367
+ const row = t.history.overlap(overlap.a, overlap.b, overlap.days);
5368
+ out.push(md ? `- ${row}` : ` ! ${row}`);
5369
+ }
5232
5370
  for (const name of history.undatedReports) {
5233
5371
  out.push(md ? `- ${t.history.undated(name)}` : ` ${t.history.undated(name)}`);
5234
5372
  }
@@ -9716,6 +9854,9 @@ async function main(): Promise<void> {
9716
9854
  case 'rollup':
9717
9855
  await commandRollup(args, t);
9718
9856
  break;
9857
+ case 'pulse':
9858
+ await commandPulse(args, t);
9859
+ break;
9719
9860
  case 'init':
9720
9861
  await commandInit(args, config, pricing, t);
9721
9862
  break;