@trazum/cli 1.53.4 → 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/src/index.ts CHANGED
@@ -69,6 +69,8 @@ import {
69
69
  explainGateFailure,
70
70
  assignSources,
71
71
  fleetRollup,
72
+ rollUp,
73
+ heartbeats,
72
74
  labelCoverage,
73
75
  measuredUsage,
74
76
  gateMargin,
@@ -296,6 +298,7 @@ const VALUE_FLAGS = new Set([
296
298
  'max-usd',
297
299
  'max-growth-usd',
298
300
  'max-cache-loss-usd',
301
+ 'max-stale-hours',
299
302
  'max-day-usd',
300
303
  'max-session-usd',
301
304
  'csv-out',
@@ -593,6 +596,8 @@ const COMMAND_FLAGS: Record<string, string[]> = {
593
596
  rank: ['level', 'model', 'calls', 'output-tokens', 'batch', 'disable', 'prompt', 'markdown-out'],
594
597
  init: ['dry-run', 'yes', 'json', 'pricing', 'pricing-live'],
595
598
  conform: ['contract', 'json'],
599
+ rollup: ['json'],
600
+ pulse: ['json', 'max-stale-hours'],
596
601
  feedback: [],
597
602
  gateway: ['on-cannot-tell', 'port', 'socket', 'pricing', 'pricing-live'],
598
603
  ladder: ['pricing', 'pricing-live', 'since', 'until', 'label'],
@@ -2038,6 +2043,325 @@ async function commandConform(args: Args, t: CliMessages): Promise<void> {
2038
2043
  console.log();
2039
2044
  }
2040
2045
 
2046
+ /**
2047
+ * `trazum rollup <document...>` — several people's bills, one roll-up.
2048
+ *
2049
+ * The first command here that reads *documents* rather than logs. Everything
2050
+ * else assumes one operator with the files on disk; this assumes four people
2051
+ * who each already ran `trazum profile --json` where their traffic is, and one
2052
+ * of them wants the total.
2053
+ *
2054
+ * **A format and a merge, not a service.** There is no upload, no account and
2055
+ * no server: the documents arrive however the team already moves files, and
2056
+ * this reads them off the filesystem. That is the whole design — a tool whose
2057
+ * argument is that it reads your bill without uploading it cannot also be the
2058
+ * place everybody's bill is uploaded.
2059
+ *
2060
+ * A directory argument is expanded to the `.json` files directly inside it, so
2061
+ * a shared folder people drop a document into is a roll-up without anybody
2062
+ * writing a shell loop.
2063
+ *
2064
+ * The rendering leads with the total and then spends most of its lines on what
2065
+ * the merge could **not** do: the contributors' own gaps, the findings that do
2066
+ * not roll up, and the overlap between contributors that nothing here can see.
2067
+ * A roll-up is the document most likely to be pasted into a slide, and a total
2068
+ * with its caveats one screen away is a total that will be quoted alone.
2069
+ */
2070
+ async function commandRollup(args: Args, t: CliMessages): Promise<void> {
2071
+ if (args.positional.length === 0) throw new Error(t.rollup.noTargets());
2072
+
2073
+ /** Every document to merge, in the order the caller named them. */
2074
+ const inputs: { name: string; text: string }[] = [];
2075
+ /** What a failed filesystem call was refusing, when it said. */
2076
+ const codeOf = (error: unknown): string | undefined =>
2077
+ typeof error === 'object' && error !== null ? (error as { code?: string }).code : undefined;
2078
+
2079
+ for (const target of args.positional) {
2080
+ /**
2081
+ * Attempted, not checked first.
2082
+ *
2083
+ * The obvious shape is `stat` and then branch on `isDirectory()`, and it
2084
+ * is a check-then-act: between the answer and the read the path can become
2085
+ * something else, and CodeQL flagged exactly that on the pull request that
2086
+ * introduced this command. Reading the error code has no window between
2087
+ * the two operations, because there is only one operation — and it is the
2088
+ * same reasoning the gateway applies to a budget decision, which happens
2089
+ * before the upstream is opened rather than between two things.
2090
+ *
2091
+ * `ENOTDIR` is an answer — this is a file — and every other failure is a
2092
+ * failure.
2093
+ */
2094
+ const listing = await readdir(target, { withFileTypes: true }).catch((error: unknown) => {
2095
+ const code = codeOf(error);
2096
+ if (code === 'ENOTDIR') return null;
2097
+ if (code === 'ENOENT') throw new Error(t.rollup.noSuchTarget(target));
2098
+ throw error;
2099
+ });
2100
+
2101
+ if (listing !== null) {
2102
+ const found = listing
2103
+ .filter((child) => child.isFile() && child.name.endsWith('.json'))
2104
+ .map((child) => join(target, child.name))
2105
+ .sort((a, b) => a.localeCompare(b));
2106
+ // An empty directory is named rather than quietly contributing nothing:
2107
+ // a roll-up of a folder somebody spelled wrong would otherwise report a
2108
+ // total of zero and look like a team that spent nothing.
2109
+ if (found.length === 0) throw new Error(t.rollup.emptyDirectory(target));
2110
+ for (const file of found) inputs.push({ name: file, text: await readFile(file, 'utf8') });
2111
+ continue;
2112
+ }
2113
+
2114
+ const text = await readFile(target, 'utf8').catch((error: unknown) => {
2115
+ // Gone between the two calls, which is the race the shape above avoids
2116
+ // deciding on: the read is what says so, and it says so by name.
2117
+ if (codeOf(error) === 'ENOENT') throw new Error(t.rollup.noSuchTarget(target));
2118
+ throw error;
2119
+ });
2120
+ inputs.push({ name: target, text });
2121
+ }
2122
+
2123
+ const document = rollUp(inputs);
2124
+
2125
+ if (boolFlag(args, 'json')) {
2126
+ console.log(JSON.stringify(document, null, 2));
2127
+ // A rejected contribution is a machine missing from the total, so it gates
2128
+ // — the same reason `conform` exits 1 on a problem. Every other caveat is
2129
+ // a property of merging summaries and would gate on every honest roll-up.
2130
+ if (document.rejected.length > 0) process.exitCode = 1;
2131
+ return;
2132
+ }
2133
+
2134
+ const day = (ms: number): string => new Date(ms).toISOString().slice(0, 10);
2135
+
2136
+ console.log();
2137
+ console.log(
2138
+ c.bold(
2139
+ t.rollup.heading(document.contributors.length, formatUsd(document.total.totalUsd), document.total.calls),
2140
+ ),
2141
+ );
2142
+ console.log(
2143
+ ` ${c.dim(
2144
+ document.span === null
2145
+ ? t.rollup.noSpan()
2146
+ : t.rollup.span(day(document.span.fromMs), day(document.span.toMs)),
2147
+ )}`,
2148
+ );
2149
+ if (document.claimedSpan !== null) {
2150
+ console.log(
2151
+ ` ${c.dim(
2152
+ wrap(
2153
+ t.rollup.claimedSpan(
2154
+ day(document.claimedSpan.fromMs),
2155
+ day(document.claimedSpan.toMs - 1),
2156
+ document.claimedSpan.contributors,
2157
+ ),
2158
+ 72,
2159
+ ' ',
2160
+ ),
2161
+ )}`,
2162
+ );
2163
+ }
2164
+
2165
+ console.log();
2166
+ console.log(c.bold(t.rollup.contributorsHeading()));
2167
+ for (const contributor of document.contributors) {
2168
+ console.log(
2169
+ ` ${t.rollup.contributor(
2170
+ contributor.name,
2171
+ formatUsd(contributor.totalUsd),
2172
+ contributor.calls,
2173
+ contributor.spanDays === null ? null : Math.round(contributor.spanDays),
2174
+ )}${contributor.via === null ? '' : ` ${c.dim(t.rollup.via(contributor.via))}`}`,
2175
+ );
2176
+ /**
2177
+ * What this contributor asked for, before what it found.
2178
+ *
2179
+ * A span is not a period: a log whose latest record is the 5th may be a
2180
+ * log of a quiet week or a log that stopped being written on the 5th, and
2181
+ * only a claim tells those apart. Printed above the gaps because the
2182
+ * silence below is measured against it.
2183
+ */
2184
+ if (contributor.claimed !== null) {
2185
+ const { sinceMs, untilMs } = contributor.claimed;
2186
+ if (sinceMs !== null && untilMs !== null) {
2187
+ // The window is half-open, so the last claimed day is the one before
2188
+ // `until` — printed as the reader would say it, not as the filter
2189
+ // stores it.
2190
+ console.log(` ${c.dim(t.rollup.claimedRow(day(sinceMs), day(untilMs - 1)))}`);
2191
+ }
2192
+ if (contributor.undatedExcluded !== null && contributor.undatedExcluded > 0) {
2193
+ console.log(` ${c.yellow(wrap(t.rollup.undated(contributor.undatedExcluded), 70, ' '))}`);
2194
+ }
2195
+ }
2196
+ // Every gap under the contributor that has it, never summed into one
2197
+ // figure: "one of your four machines is 90% unpriced" is the finding, and
2198
+ // an average is what hides it.
2199
+ for (const gap of contributor.gaps) {
2200
+ console.log(` ${c.yellow(wrap(gap.detail, 70, ' '))}`);
2201
+ }
2202
+ // The silent stretches by name, under the gap that counted them: "eight
2203
+ // days recorded nothing" is a number, and which eight is the finding.
2204
+ if (contributor.silence !== null && contributor.silence.runs.length > 0) {
2205
+ const runs = contributor.silence.runs
2206
+ .map((run) => (run.from === run.to ? run.from : `${run.from} to ${run.to}`))
2207
+ .join(', ');
2208
+ console.log(` ${c.dim(wrap(t.rollup.silentRuns(runs), 68, ' '))}`);
2209
+ }
2210
+ }
2211
+
2212
+ if (document.rejected.length > 0) {
2213
+ console.log();
2214
+ console.log(c.bold(t.rollup.rejectedHeading()));
2215
+ for (const rejection of document.rejected) {
2216
+ // The roll-up it arrived through, when it came through one: a rejection
2217
+ // whose origin got lost is a machine nobody knows to go and fix.
2218
+ const line =
2219
+ rejection.via === null
2220
+ ? t.rollup.rejected(rejection.name, rejection.because)
2221
+ : t.rollup.rejectedVia(rejection.name, rejection.via, rejection.because);
2222
+ console.log(` ${c.red(wrap(line, 72, ' '))}`);
2223
+ }
2224
+ process.exitCode = 1;
2225
+ }
2226
+
2227
+ if (document.identicalContributions.groups.length > 0) {
2228
+ console.log();
2229
+ for (const group of document.identicalContributions.groups) {
2230
+ console.log(` ${c.yellow(wrap(t.rollup.identical(group.join(', ')), 72, ' '))}`);
2231
+ }
2232
+ console.log(` ${c.dim(t.rollup.identicalUsd(formatUsd(document.identicalContributions.usd)))}`);
2233
+ }
2234
+
2235
+ if (document.repeatedContributors.length > 0) {
2236
+ console.log();
2237
+ console.log(` ${c.yellow(wrap(t.rollup.repeated(document.repeatedContributors.join(', ')), 72, ' '))}`);
2238
+ }
2239
+
2240
+ if (document.byLabel.length > 0) {
2241
+ console.log();
2242
+ console.log(c.bold(t.rollup.byLabelHeading()));
2243
+ for (const row of document.byLabel.slice(0, 8)) {
2244
+ console.log(` ${t.rollup.labelRow(row.label, formatUsd(row.breakdown.totalUsd), row.breakdown.calls)}`);
2245
+ }
2246
+ }
2247
+
2248
+ if (document.notMerged.length > 0) {
2249
+ console.log();
2250
+ console.log(c.bold(t.rollup.notMergedHeading()));
2251
+ for (const finding of document.notMerged) {
2252
+ console.log(` ${wrap(t.rollup.notMerged(finding.finding, finding.because), 72, ' ')}`);
2253
+ if (finding.presentIn.length > 0) {
2254
+ console.log(` ${c.dim(t.rollup.presentIn(finding.presentIn.join(', ')))}`);
2255
+ }
2256
+ }
2257
+ }
2258
+
2259
+ if (document.cannotSay.length > 0) {
2260
+ console.log();
2261
+ console.log(c.bold(t.rollup.cannotSayHeading()));
2262
+ for (const caveat of document.cannotSay) {
2263
+ console.log(` ${c.dim(wrap(t.rollup.caveat(caveat), 72, ' '))}`);
2264
+ }
2265
+ }
2266
+ console.log();
2267
+ }
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
+
2041
2365
  /**
2042
2366
  * `trazum feedback` — where to say it, and what to say.
2043
2367
  *
@@ -4972,6 +5296,16 @@ async function commandHistory(
4972
5296
  return t.history.runCache(n(run.periods), run.sinceName, pct(run.from), pct(run.to));
4973
5297
  };
4974
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
+
4975
5309
  const lines = (md: boolean): string[] => {
4976
5310
  const out: string[] = [];
4977
5311
  const first = history.periods[0]!;
@@ -4989,7 +5323,8 @@ async function commandHistory(
4989
5323
  }
4990
5324
  if (history.runs.length > 0) out.push('');
4991
5325
  for (const run of history.runs) {
4992
- out.push(md ? `- ${runLine(run)}` : ` ! ${runLine(run)}`);
5326
+ const line = `${runLine(run)}${runHole(run)}`;
5327
+ out.push(md ? `- ${line}` : ` ! ${line}`);
4993
5328
  }
4994
5329
  if (history.repeatedPlanActions.length > 0) out.push('');
4995
5330
  for (const repeat of history.repeatedPlanActions) {
@@ -5004,6 +5339,34 @@ async function commandHistory(
5004
5339
  );
5005
5340
  out.push(md ? `- ${row}` : ` ! ${row}`);
5006
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
+ }
5007
5370
  for (const name of history.undatedReports) {
5008
5371
  out.push(md ? `- ${t.history.undated(name)}` : ` ${t.history.undated(name)}`);
5009
5372
  }
@@ -9343,6 +9706,7 @@ async function main(): Promise<void> {
9343
9706
  avgOutputTokens: DEFAULT_USAGE.avgOutputTokens,
9344
9707
  cacheHitRate: DEFAULT_USAGE.cacheHitRate,
9345
9708
  locales: LOCALES,
9709
+ contracts: CONTRACT_NAMES,
9346
9710
  },
9347
9711
  c.bold,
9348
9712
  ),
@@ -9487,6 +9851,12 @@ async function main(): Promise<void> {
9487
9851
  case 'conform':
9488
9852
  await commandConform(args, t);
9489
9853
  break;
9854
+ case 'rollup':
9855
+ await commandRollup(args, t);
9856
+ break;
9857
+ case 'pulse':
9858
+ await commandPulse(args, t);
9859
+ break;
9490
9860
  case 'init':
9491
9861
  await commandInit(args, config, pricing, t);
9492
9862
  break;