@trazum/cli 1.51.1 → 1.51.2

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.51.1",
3
+ "version": "1.51.2",
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.51.1"
40
+ "@trazum/core": "1.51.2"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
@@ -31,9 +31,10 @@
31
31
  * aggregates since 1.42 and standing in the path changes nothing about that.
32
32
  */
33
33
 
34
+ import { once } from 'node:events';
34
35
  import { createServer } from 'node:http';
35
36
  import type { IncomingMessage, Server, ServerResponse } from 'node:http';
36
- import { estimateTokens, gatewayDecision, usageFromResponse } from '@trazum/core';
37
+ import { estimateTokens, gatewayDecision, streamingUsageReader, usageFromResponse } from '@trazum/core';
37
38
  import type { GatewayDecision, GatewayPolicy, GatewayStanding, PricingCatalogue } from '@trazum/core';
38
39
 
39
40
  /** Compiled in. See the module note. */
@@ -300,33 +301,89 @@ export function buildGateway(context: GatewayContext): Server {
300
301
  return;
301
302
  }
302
303
 
303
- const text = await upstreamResponse.text();
304
+ const back: Record<string, string> = {};
305
+ upstreamResponse.headers.forEach((value, name) => {
306
+ if (!HOP_BY_HOP.has(name.toLowerCase())) back[name] = value;
307
+ });
304
308
 
305
- // Measured at the moment of the call, from the provider's own counts —
306
- // the reason this beats a connector, which reports the runaway after it
307
- // ran. Counts only reach `record`; the body is dropped here.
308
- let measured: unknown;
309
- try {
310
- measured = JSON.parse(text);
311
- } catch {
312
- measured = null;
313
- }
314
- const usage = usageFromResponse(context.provider, measured);
315
- if (usage !== null) {
309
+ /** Counts only ever reach `record`; the body is never kept, either way. */
310
+ const recordUsage = (usage: ReturnType<typeof usageFromResponse>): void => {
311
+ if (usage === null) return;
316
312
  context.record({
317
313
  model: decision.kind === 'substitute' ? decision.to.id : described.model,
318
314
  label: described.label,
319
315
  substituted: decision.kind === 'substitute',
320
316
  ...usage,
321
317
  });
318
+ };
319
+
320
+ /**
321
+ * A streamed answer is relayed as it arrives.
322
+ *
323
+ * Until 1.52 this method read `await upstreamResponse.text()` for every
324
+ * response, which for `"stream": true` — nearly all production traffic —
325
+ * held the entire answer and then delivered it at once. Time to first
326
+ * token became the total generation time. This page argues that reading a
327
+ * budget file per request would put Trazum's latency between the caller
328
+ * and their provider; buffering a stream was a far larger version of that
329
+ * in the same file.
330
+ *
331
+ * The provider decides, not the request: a body asking to stream can
332
+ * still come back whole, and `content-type` is what actually arrived.
333
+ */
334
+ const streaming = (upstreamResponse.headers.get('content-type') ?? '').includes(
335
+ 'text/event-stream',
336
+ );
337
+
338
+ if (!streaming || upstreamResponse.body === null) {
339
+ const text = await upstreamResponse.text();
340
+ let measured: unknown;
341
+ try {
342
+ measured = JSON.parse(text);
343
+ } catch {
344
+ measured = null;
345
+ }
346
+ recordUsage(usageFromResponse(context.provider, measured));
347
+ response.writeHead(upstreamResponse.status, back);
348
+ response.end(text);
349
+ return;
322
350
  }
323
351
 
324
- const back: Record<string, string> = {};
325
- upstreamResponse.headers.forEach((value, name) => {
326
- if (!HOP_BY_HOP.has(name.toLowerCase())) back[name] = value;
327
- });
328
352
  response.writeHead(upstreamResponse.status, back);
329
- response.end(text);
353
+
354
+ const reader = streamingUsageReader(context.provider);
355
+ const decoder = new TextDecoder();
356
+ try {
357
+ for await (const chunk of upstreamResponse.body as AsyncIterable<Uint8Array>) {
358
+ // Counted on the way past, then forwarded unchanged. The bytes the
359
+ // caller receives are the bytes the provider sent.
360
+ reader.push(decoder.decode(chunk, { stream: true }));
361
+ if (!response.write(chunk)) {
362
+ await once(response, 'drain');
363
+ }
364
+ }
365
+ reader.push(decoder.decode());
366
+ } catch (error) {
367
+ /**
368
+ * The stream broke partway. The head is already sent, so there is no
369
+ * status left to change and no refusal to render — destroying the
370
+ * socket is the only way to tell the caller the answer is incomplete
371
+ * rather than short.
372
+ *
373
+ * The money is spent and unmeasured: the provider generated whatever it
374
+ * generated, and the counts ride the event this stream never reached.
375
+ * Recorded as a broken stream rather than as the partial counts, which
376
+ * would be a measurement of the part that arrived and read as the cost.
377
+ */
378
+ context.note(
379
+ `stream broke before its usage event: ${error instanceof Error ? error.message : String(error)} — this call is unmeasured`,
380
+ );
381
+ response.destroy();
382
+ return;
383
+ }
384
+
385
+ recordUsage(reader.done());
386
+ response.end();
330
387
  })();
331
388
  });
332
389
  }
package/src/i18n/en.ts CHANGED
@@ -175,7 +175,7 @@ ${bold('OPTIONS FOR commitment')}
175
175
 
176
176
  ${bold('OPTIONS FOR report')}
177
177
  --year <yyyy> Required. Which year to assemble.
178
- --json Also emit the record as JSON.
178
+ --json The record as data.
179
179
 
180
180
  Everything comes from the store and the plans you already keep — nothing is
181
181
  computed that cannot be checked against a document that already exists.
@@ -1304,9 +1304,24 @@ ${bold('EXAMPLES')}
1304
1304
  'Pass a file to check — a usage log, or any document Trazum emits. Use "-" to read from stdin.',
1305
1305
  badContract: (given, known) => `"${given}" is not a contract. Known contracts: ${known}.`,
1306
1306
  unrecognised: (path) => `${path} does not match any contract Trazum knows.`,
1307
- heading: (path, contract) => `${path} reads as a ${contract} document`,
1307
+ /**
1308
+ * The article follows the name's **sound**, not its first letter.
1309
+ *
1310
+ * Every contract that existed when this line was written began with a
1311
+ * consonant letter, so a bare `a` was right every time it ran; then
1312
+ * `outcome-report` and `annual-record` became reachable by name and it
1313
+ * started saying "a outcome-report".
1314
+ *
1315
+ * `u` is excluded on purpose and the first attempt got it wrong: a
1316
+ * letter-only rule turned "a usage-log" into "an usage-log", because
1317
+ * `usage` opens on /juː/. Bounded to the closed set of contract names, all
1318
+ * of which begin `a`, `c`, `h`, `o`, `p`, `u` or `v`, and `contract-article`
1319
+ * in the test suite fails if a new one arrives that this rule cannot judge.
1320
+ */
1321
+ heading: (path, contract) =>
1322
+ `${path} reads as ${/^[aeio]/.test(contract) ? 'an' : 'a'} ${contract} document`,
1308
1323
  headingLog: (path, contract, records) =>
1309
- `${path} reads as a ${contract}: ${records} ${records === 1 ? 'record' : 'records'}`,
1324
+ `${path} reads as ${/^[aeio]/.test(contract) ? 'an' : 'a'} ${contract}: ${records} ${records === 1 ? 'record' : 'records'}`,
1310
1325
  conforms: () => 'It conforms. Every required field is present and the right type.',
1311
1326
  problem: (at, kind, detail) => `${at}: ${detail} (${kind})`,
1312
1327
  moreProblems: (count) => `…and ${count} more. Fix these first; they are often the same mistake.`,
package/src/i18n/es.ts CHANGED
@@ -166,7 +166,7 @@ ${bold('OPCIONES DE commitment')}
166
166
 
167
167
  ${bold('OPCIONES DE report')}
168
168
  --year <yyyy> Obligatorio. Qué año montar.
169
- --json Emite también el registro como JSON.
169
+ --json El registro como datos.
170
170
 
171
171
  Todo sale del almacén y de los planes que ya guardas — no se calcula nada
172
172
  que no se pueda comprobar contra un documento que ya existe. Los meses sin
package/src/index.ts CHANGED
@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
6
6
  import { gunzipSync } from 'node:zlib';
7
7
 
8
8
  import {
9
+ CONTRACT_NAMES,
9
10
  applyRewrites,
10
11
  BASELINE_FILENAME,
11
12
  BASELINE_VERSION,
@@ -1563,16 +1564,15 @@ const FEEDBACK_REPO = 'https://github.com/Davmunrey/Trazum';
1563
1564
  /** Problems listed before the rest are counted. A wall of them helps nobody. */
1564
1565
  const MAX_CONFORM_PROBLEMS = 20;
1565
1566
 
1566
- /** The contracts `--contract` accepts, so a typo is refused with the list. */
1567
- const CONTRACT_NAMES = [
1568
- 'usage-log',
1569
- 'profile',
1570
- 'plan',
1571
- 'verification',
1572
- 'history',
1573
- 'connected',
1574
- 'cost-answer',
1575
- ];
1567
+ /**
1568
+ * The contracts `--contract` accepts, so a typo is refused with the list.
1569
+ *
1570
+ * Imported, never retyped. This was a hand-written copy of the union in
1571
+ * `conform.ts` and it stopped at `cost-answer`: `outcome-report` (1.50.4) and
1572
+ * `annual-record` (1.51.0) had rules, had cross-rules, and were refused by name
1573
+ * with "is not a contract" — the list telling the caller they had made a typo
1574
+ * when the list was the thing that was wrong.
1575
+ */
1576
1576
 
1577
1577
  /** How many source files, and how large each may be. Both reported when they bite. */
1578
1578
  const INIT_MAX_SOURCE_FILES = 400;
@@ -1978,12 +1978,16 @@ async function commandConform(args: Args, t: CliMessages): Promise<void> {
1978
1978
  if (target === undefined) throw new Error(t.conform.noTarget());
1979
1979
 
1980
1980
  const named = stringFlag(args, 'contract');
1981
- if (named !== undefined && !CONTRACT_NAMES.includes(named)) {
1981
+ // Widened for the membership test only: the array is `as const` so the union
1982
+ // is derived from it, and narrowing back is what `isContract` does below.
1983
+ const isContract = (value: string): value is ContractName =>
1984
+ (CONTRACT_NAMES as readonly string[]).includes(value);
1985
+ if (named !== undefined && !isContract(named)) {
1982
1986
  throw new Error(t.conform.badContract(named, CONTRACT_NAMES.join(', ')));
1983
1987
  }
1984
1988
 
1985
1989
  const text = target === '-' ? await readInput('-', t) : await readUsageLog(target, t);
1986
- const report = conform(text, named === undefined ? {} : { contract: named as ContractName });
1990
+ const report = conform(text, named === undefined ? {} : { contract: named });
1987
1991
 
1988
1992
  if (boolFlag(args, 'json')) {
1989
1993
  console.log(JSON.stringify(report, null, 2));
@@ -3113,6 +3117,21 @@ async function commandReport(
3113
3117
  .sort((a, b) => a.month.localeCompare(b.month));
3114
3118
 
3115
3119
  const record = annualRecord(year, periods);
3120
+
3121
+ /**
3122
+ * `--json` is the document *instead of* the report, not after it.
3123
+ *
3124
+ * It used to print the human report and then append the JSON, and the help
3125
+ * said "Also emit". That made the one command emitting the `annual-record`
3126
+ * contract the one command whose output no machine can read: `| jq` and
3127
+ * `| trazum conform -` both fail on the prose in front. Every other `--json`
3128
+ * in this CLI returns here rather than adding to what was printed.
3129
+ */
3130
+ if (boolFlag(args, 'json')) {
3131
+ console.log(JSON.stringify(record, null, 2));
3132
+ return;
3133
+ }
3134
+
3116
3135
  const n = (value: number): string => value.toLocaleString(t.numberLocale);
3117
3136
 
3118
3137
  console.log();
@@ -3170,10 +3189,6 @@ async function commandReport(
3170
3189
  console.log();
3171
3190
  console.log(` ${c.dim(wrap(t.annual.noNewData(), 74, ' '))}`);
3172
3191
  console.log();
3173
-
3174
- if (boolFlag(args, 'json')) {
3175
- console.log(JSON.stringify(record, null, 2));
3176
- }
3177
3192
  }
3178
3193
 
3179
3194
  function commandModels(t: CliMessages, pricing: PricingCatalogue): void {