@trazum/cli 1.63.0 → 1.64.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.63.0",
3
+ "version": "1.64.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.63.0"
40
+ "@trazum/core": "1.64.0"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/html.ts ADDED
@@ -0,0 +1,343 @@
1
+ import { UNLABELLED, formatUsd, sharesOf } from '@trazum/core';
2
+ import type { RollupDocument, UsageBreakdown } from '@trazum/core';
3
+ import type { CliMessages } from './i18n/index.js';
4
+ import type { ProfileMarkdownInput } from './markdown.js';
5
+ import { dayOf, spanDays } from './time.js';
6
+
7
+ /**
8
+ * HTML for the person who does not run CLIs.
9
+ *
10
+ * One self-contained file: inline CSS, no scripts, no external assets — a
11
+ * mail client, a wiki upload and a double-click all render it the same. It
12
+ * is a **projection of the document `--json` prints**, taking the exact same
13
+ * input object as the Markdown renderer: no second computation exists to
14
+ * disagree with the first, and the parity guard in the suite walks every
15
+ * figure here back to that document.
16
+ *
17
+ * The design rule this repository applies to its terminal output is applied
18
+ * here where a designer would be tempted to grey it out: **the caveats are
19
+ * furniture, not footnotes.** Unpriced models, skipped lines and the absent
20
+ * fields render inside a bordered block ahead of the detail tables, at the
21
+ * same visual weight as the totals they qualify — a forwarded report whose
22
+ * limits can be cropped out is a lie by omission wearing this tool's name.
23
+ *
24
+ * Escaping is not optional politeness: labels, model ids and file paths come
25
+ * from somebody's log, and a label is exactly where `<script>` would arrive.
26
+ * Everything interpolated goes through `esc()`, tested with hostile labels.
27
+ */
28
+
29
+ export function esc(value: string): string {
30
+ return value
31
+ .replaceAll('&', '&amp;')
32
+ .replaceAll('<', '&lt;')
33
+ .replaceAll('>', '&gt;')
34
+ .replaceAll('"', '&quot;')
35
+ .replaceAll("'", '&#39;');
36
+ }
37
+
38
+ /**
39
+ * A single committed look, print-first: explicit colours on everything, a
40
+ * caveat block that a printer and a dark-mode mail client both keep legible.
41
+ * No media-query theming — this file's job is to look the same everywhere,
42
+ * including on paper.
43
+ */
44
+ const STYLE = `
45
+ :root { color-scheme: light; }
46
+ body { margin: 0; padding: 2.5rem 1.25rem; background: #f7f6f3; color: #1f2328;
47
+ font: 16px/1.55 -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; }
48
+ main { max-width: 860px; margin: 0 auto; background: #ffffff; border: 1px solid #d9d5cc;
49
+ border-radius: 6px; padding: 2.25rem 2.5rem; }
50
+ h1 { font-size: 1.45rem; margin: 0 0 .25rem; }
51
+ h2 { font-size: 1.05rem; margin: 2rem 0 .5rem; border-bottom: 1px solid #e4e0d8; padding-bottom: .3rem; }
52
+ .headline { font-size: 1.8rem; font-weight: 700; margin: .75rem 0 .1rem; font-variant-numeric: tabular-nums; }
53
+ .muted { color: #59606a; }
54
+ .gate-fail { border: 2px solid #b42318; background: #fdf1f0; color: #7a1a12;
55
+ padding: .7rem 1rem; border-radius: 6px; margin: 1rem 0; font-weight: 600; }
56
+ .gate-pass { color: #365f37; margin: 1rem 0; }
57
+ .caveats { border: 2px solid #8a6d1a; background: #fbf6e9; border-radius: 6px;
58
+ padding: 1rem 1.25rem; margin: 1.5rem 0; }
59
+ .caveats h2 { margin: 0 0 .5rem; border: 0; padding: 0; font-size: 1.05rem; color: #6d5510; }
60
+ .caveats ul { margin: 0; padding-left: 1.2rem; }
61
+ .caveats li { margin: .3rem 0; }
62
+ table { border-collapse: collapse; width: 100%; margin: .5rem 0 1rem; font-variant-numeric: tabular-nums; }
63
+ th { text-align: left; font-weight: 600; border-bottom: 2px solid #d9d5cc; padding: .35rem .6rem .35rem 0; }
64
+ td { border-bottom: 1px solid #ece9e2; padding: .35rem .6rem .35rem 0; }
65
+ td.n, th.n { text-align: right; }
66
+ ul.findings { padding-left: 1.2rem; } ul.findings li { margin: .35rem 0; }
67
+ footer { margin-top: 2rem; padding-top: .75rem; border-top: 1px solid #e4e0d8;
68
+ font-size: .85rem; color: #59606a; }
69
+ @media print { body { background: #ffffff; padding: 0; } main { border: 0; padding: 0; } }
70
+ `;
71
+
72
+ interface Row {
73
+ name: string;
74
+ breakdown: UsageBreakdown;
75
+ }
76
+
77
+ function breakdownTable(rows: Row[], totalUsd: number, t: ProfileMarkdownInput['t'], nameHeading: string): string {
78
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
79
+ const body = rows
80
+ .map(({ name, breakdown: b }) => {
81
+ const share = totalUsd > 0 ? `${((b.totalUsd / totalUsd) * 100).toFixed(1)}%` : '—';
82
+ return `<tr><td>${esc(name)}</td><td class="n">${n(b.calls)}</td><td class="n">${n(b.inputTokens)}</td><td class="n">${n(b.cacheReadTokens)}</td><td class="n">${n(b.cacheWriteTokens)}</td><td class="n">${n(b.outputTokens)}</td><td class="n">${esc(formatUsd(b.totalUsd))}</td><td class="n">${share}</td></tr>`;
83
+ })
84
+ .join('\n');
85
+ return `<table><thead><tr><th>${esc(nameHeading)}</th><th class="n">${esc(t.html.colCalls())}</th><th class="n">${esc(t.html.colInput())}</th><th class="n">${esc(t.html.colCacheRead())}</th><th class="n">${esc(t.html.colCacheWrite())}</th><th class="n">${esc(t.html.colOutput())}</th><th class="n">USD</th><th class="n">%</th></tr></thead><tbody>\n${body}\n</tbody></table>`;
86
+ }
87
+
88
+ /** The profile as one self-contained page. Same input as the Markdown door. */
89
+ export function renderProfileHtml(input: ProfileMarkdownInput): string {
90
+ const { report, levers, cache, t, gates, window, stalePricing } = input;
91
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
92
+ const pct = (share: number): string => `${(share * 100).toFixed(1)}%`;
93
+ const showLabel = (label: string): string => (label === UNLABELLED ? t.profile.unlabelled() : label);
94
+ const shares = sharesOf(report.total);
95
+ const parts: string[] = [];
96
+
97
+ parts.push(`<h1>${esc(t.profile.heading())}</h1>`);
98
+ parts.push(
99
+ `<p class="headline">${esc(t.profile.spent(t.profile.calls(report.total.calls), formatUsd(report.total.totalUsd)))}</p>`,
100
+ );
101
+ if (report.span !== null) {
102
+ parts.push(
103
+ `<p class="muted">${esc(t.profile.spanLine(dayOf(report.span.fromMs), dayOf(report.span.toMs), spanDays(report.span.fromMs, report.span.toMs)))}</p>`,
104
+ );
105
+ }
106
+ if (window !== undefined) {
107
+ parts.push(`<p class="muted">${esc(t.profile.windowLine(window.since, window.until))}</p>`);
108
+ }
109
+
110
+ if (gates !== undefined && gates.lines.length > 0) {
111
+ const box = gates.failed ? 'gate-fail' : 'gate-pass';
112
+ parts.push(`<div class="${box}">${gates.lines.map((line) => esc(line)).join('<br>')}</div>`);
113
+ }
114
+
115
+ /**
116
+ * The caveats, ahead of every detail table. What this report cannot say is
117
+ * part of what it says, and it renders before the part a skimmer stops at.
118
+ */
119
+ const caveats: string[] = [];
120
+ if (report.unpricedModels.length > 0) {
121
+ caveats.push(esc(t.profile.unpriced(report.unpricedModels.join(', '), report.unpriced.calls)));
122
+ }
123
+ if (report.skippedLines.length > 0) {
124
+ const shown = report.skippedLines.slice(0, 5).join(', ');
125
+ caveats.push(
126
+ esc(t.profile.skipped(report.skippedLines.length, report.skippedLines.length > 5 ? `${shown}…` : shown)),
127
+ );
128
+ }
129
+ if (report.span === null) caveats.push(esc(t.html.noClock()));
130
+ if (!report.hasSessions) caveats.push(esc(t.html.noSessions()));
131
+ if (report.total.assumedWriteTtlCalls > 0) {
132
+ caveats.push(
133
+ esc(
134
+ t.profile.cacheTtlUnsettled(
135
+ report.total.assumedWriteTtlCalls,
136
+ formatUsd(-cache.deltaUsd),
137
+ formatUsd(cache.worstCaseDeltaUsd),
138
+ ),
139
+ ),
140
+ );
141
+ }
142
+ if (stalePricing !== undefined) {
143
+ caveats.push(esc(t.profile.pricesStale(stalePricing.date, stalePricing.days)));
144
+ }
145
+ if (caveats.length > 0) {
146
+ parts.push(
147
+ `<div class="caveats"><h2>${esc(t.html.caveatsHeading())}</h2><ul>${caveats
148
+ .map((caveat) => `<li>${caveat}</li>`)
149
+ .join('')}</ul></div>`,
150
+ );
151
+ }
152
+
153
+ parts.push(`<h2>${esc(t.html.byLabelHeading())}</h2>`);
154
+ parts.push(
155
+ breakdownTable(
156
+ report.byLabel.map((row) => ({ name: showLabel(row.label), breakdown: row.breakdown })),
157
+ report.total.totalUsd,
158
+ t,
159
+ t.html.colLabel(),
160
+ ),
161
+ );
162
+
163
+ parts.push(`<h2>${esc(t.html.byModelHeading())}</h2>`);
164
+ parts.push(
165
+ breakdownTable(
166
+ report.byModel.map((row) => ({ name: row.model, breakdown: row.breakdown })),
167
+ report.total.totalUsd,
168
+ t,
169
+ t.html.colModel(),
170
+ ),
171
+ );
172
+
173
+ // The findings, as the sentences the terminal already says — the copy is
174
+ // the product's, not this file's, so the two surfaces cannot drift apart.
175
+ const findings: string[] = [];
176
+ for (const lever of levers.slices.slice(0, 5)) {
177
+ findings.push(
178
+ esc(t.profile.leverSlice(showLabel(lever.label), lever.modelName, formatUsd(lever.combinedUsd), pct(lever.shareOfBill))),
179
+ );
180
+ }
181
+ if (report.total.cacheReadTokens + report.total.cacheWriteTokens > 0) {
182
+ if (cache.deltaUsd > 0) {
183
+ findings.push(
184
+ esc(t.profile.cacheLost(formatUsd(cache.deltaUsd), n(report.total.cacheWriteTokens), n(report.total.cacheReadTokens))),
185
+ );
186
+ } else {
187
+ findings.push(esc(t.profile.cachePaidOff(formatUsd(-cache.deltaUsd))));
188
+ }
189
+ }
190
+ if (findings.length > 0) {
191
+ parts.push(`<h2>${esc(t.html.findingsHeading())}</h2>`);
192
+ parts.push(`<ul class="findings">${findings.map((finding) => `<li>${finding}</li>`).join('')}</ul>`);
193
+ }
194
+
195
+ parts.push(
196
+ `<p class="muted">${esc(t.html.sharesLine(pct(shares.input), pct(shares.cacheRead), pct(shares.cacheWrite), pct(shares.output)))}</p>`,
197
+ );
198
+
199
+ parts.push(`<footer>${esc(t.html.footer())}</footer>`);
200
+
201
+ return page(t.profile.heading(), t.locale, parts);
202
+ }
203
+
204
+ /** The shared skeleton: both documents are the same file to a mail client. */
205
+ function page(title: string, locale: string, parts: string[]): string {
206
+ return [
207
+ '<!doctype html>',
208
+ `<html lang="${esc(locale)}">`,
209
+ '<head>',
210
+ '<meta charset="utf-8">',
211
+ '<meta name="viewport" content="width=device-width, initial-scale=1">',
212
+ `<title>${esc(title)}</title>`,
213
+ `<style>${STYLE}</style>`,
214
+ '</head>',
215
+ '<body>',
216
+ '<main>',
217
+ ...parts,
218
+ '</main>',
219
+ '</body>',
220
+ '</html>',
221
+ '',
222
+ ].join('\n');
223
+ }
224
+
225
+ /**
226
+ * The roll-up as one self-contained page — the team-facing document, for
227
+ * exactly the person who does not run CLIs.
228
+ *
229
+ * The same discipline as the profile door: the input is the roll-up document
230
+ * itself, the one `--json` prints and `conform` checks, so the page cannot
231
+ * disagree with the data. Two things this page refuses to soften, because
232
+ * they are the roll-up's whole honesty: **each contributor's gaps stay under
233
+ * that contributor** — summing them away is the averaging this command
234
+ * exists to refuse — and **the `cannotSay` caveats render in the caveat
235
+ * block**, overlap-invisible included, so the one thing no merge can measure
236
+ * cannot be cropped out of the forwarded copy.
237
+ */
238
+ export function renderRollupHtml(document: RollupDocument, t: CliMessages): string {
239
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
240
+ const parts: string[] = [];
241
+
242
+ parts.push(`<h1>${esc(t.rollup.heading(document.contributors.length, formatUsd(document.total.totalUsd), document.total.calls))}</h1>`);
243
+ parts.push(`<p class="headline">${esc(formatUsd(document.total.totalUsd))}</p>`);
244
+ if (document.span !== null) {
245
+ parts.push(`<p class="muted">${esc(t.rollup.span(dayOf(document.span.fromMs), dayOf(document.span.toMs)))}</p>`);
246
+ } else {
247
+ parts.push(`<p class="muted">${esc(t.rollup.noSpan())}</p>`);
248
+ }
249
+
250
+ // The caveat block, ahead of every table: what the merge cannot say, what
251
+ // was rejected by name, and which contributions arrived twice.
252
+ const caveats: string[] = [];
253
+ for (const code of document.cannotSay) caveats.push(esc(t.rollup.caveat(code)));
254
+ for (const rejection of document.rejected) {
255
+ caveats.push(
256
+ esc(
257
+ rejection.via === null
258
+ ? t.rollup.rejected(rejection.name, rejection.because)
259
+ : t.rollup.rejectedVia(rejection.name, rejection.via, rejection.because),
260
+ ),
261
+ );
262
+ }
263
+ if (document.repeatedContributors.length > 0) {
264
+ caveats.push(esc(t.rollup.repeated(document.repeatedContributors.join(', '))));
265
+ }
266
+ for (const group of document.identicalContributions.groups) {
267
+ caveats.push(esc(t.rollup.identical(group.join(', '))));
268
+ }
269
+ if (document.identicalContributions.usd > 0) {
270
+ caveats.push(esc(t.rollup.identicalUsd(formatUsd(document.identicalContributions.usd))));
271
+ }
272
+ if (document.unpricedModels.length > 0) {
273
+ caveats.push(esc(t.profile.unpriced(document.unpricedModels.join(', '), document.unpriced.calls)));
274
+ }
275
+ if (caveats.length > 0) {
276
+ parts.push(
277
+ `<div class="caveats"><h2>${esc(t.rollup.cannotSayHeading())}</h2><ul>${caveats
278
+ .map((caveat) => `<li>${caveat}</li>`)
279
+ .join('')}</ul></div>`,
280
+ );
281
+ }
282
+
283
+ // One contributor, one row — and that contributor's own gaps directly
284
+ // beneath its name, never pooled.
285
+ parts.push(`<h2>${esc(t.rollup.contributorsHeading())}</h2>`);
286
+ const contributorRows = document.contributors
287
+ .map((contributor) => {
288
+ const gapItems = contributor.gaps
289
+ .map((gap) => `<li>${esc(gap.detail)}${gap.usd !== null ? ` — ${esc(formatUsd(gap.usd))}` : ''}</li>`)
290
+ .join('');
291
+ const gaps = gapItems === '' ? '' : `<ul class="findings">${gapItems}</ul>`;
292
+ return `<tr><td>${esc(contributor.name)}</td><td class="n">${n(contributor.calls)}</td><td class="n">${esc(formatUsd(contributor.totalUsd))}</td><td class="n">${contributor.spanDays === null ? '—' : n(contributor.spanDays)}</td></tr>${
293
+ gaps === '' ? '' : `<tr><td colspan="4">${gaps}</td></tr>`
294
+ }`;
295
+ })
296
+ .join('\n');
297
+ parts.push(
298
+ `<table><thead><tr><th>${esc(t.html.colContributor())}</th><th class="n">${esc(t.html.colCalls())}</th><th class="n">USD</th><th class="n">${esc(t.html.colSpanDays())}</th></tr></thead><tbody>\n${contributorRows}\n</tbody></table>`,
299
+ );
300
+
301
+ parts.push(`<h2>${esc(t.rollup.byLabelHeading())}</h2>`);
302
+ parts.push(
303
+ breakdownTable(
304
+ document.byLabel.map((row) => ({
305
+ name: row.label === UNLABELLED ? t.profile.unlabelled() : row.label,
306
+ breakdown: row.breakdown,
307
+ })),
308
+ document.total.totalUsd,
309
+ t,
310
+ t.html.colLabel(),
311
+ ),
312
+ );
313
+ parts.push(`<h2>${esc(t.html.byModelHeading())}</h2>`);
314
+ parts.push(
315
+ breakdownTable(
316
+ document.byModel.map((row) => ({ name: row.model, breakdown: row.breakdown })),
317
+ document.total.totalUsd,
318
+ t,
319
+ t.html.colModel(),
320
+ ),
321
+ );
322
+
323
+ // Findings that did not merge are named with the contributors that have
324
+ // them — reported as prose, exactly as the terminal says it.
325
+ if (document.notMerged.length > 0) {
326
+ parts.push(`<h2>${esc(t.rollup.notMergedHeading())}</h2>`);
327
+ parts.push(
328
+ `<ul class="findings">${document.notMerged
329
+ .map(
330
+ (entry) =>
331
+ `<li>${esc(t.rollup.notMerged(entry.finding, entry.because))} ${esc(t.rollup.presentIn(entry.presentIn.join(', ')))}</li>`,
332
+ )
333
+ .join('')}</ul>`,
334
+ );
335
+ }
336
+
337
+ parts.push(`<footer>${esc(t.html.footer())}</footer>`);
338
+ return page(
339
+ t.rollup.heading(document.contributors.length, formatUsd(document.total.totalUsd), document.total.calls),
340
+ t.locale,
341
+ parts,
342
+ );
343
+ }
package/src/i18n/en.ts CHANGED
@@ -56,7 +56,7 @@ ${bold('USAGE')}
56
56
  trazum prune <file> --cases <file> --yes
57
57
  trazum where [file]
58
58
  trazum conform <file|-> [--contract <name>]
59
- trazum rollup <document...|dir> [--json]
59
+ trazum rollup <document...|dir> [--json] [--html-out <file>]
60
60
  trazum pulse [--max-stale-hours <n>]
61
61
  trazum bench [--workload <id>] [--record <file>] [--against <file> --max-ratio <n>] [--json]
62
62
  trazum write [--answers <file>] [--json] [-o <file>]
@@ -104,6 +104,11 @@ ${bold('OPTIONS FOR conform')}
104
104
 
105
105
  ${bold('OPTIONS FOR rollup')}
106
106
  --json The roll-up document as data. See docs/format.md.
107
+ --html-out <file> Also write the roll-up as one self-contained HTML
108
+ file — the team-facing report, for whoever pays
109
+ the bill. Each contributor's gaps stay under that
110
+ contributor, and what no merge can measure is in
111
+ the caveat block, impossible to crop.
107
112
 
108
113
  Several people's bills, one roll-up. Each contributor runs
109
114
  \`trazum profile --json\` where their traffic already is; this merges the
@@ -516,6 +521,10 @@ ${bold('OPTIONS FOR profile')}
516
521
  are named as impossible, not priced as cheap.
517
522
  --markdown-out <file> Also write the report as Markdown, for a CI job
518
523
  summary or a pull request comment.
524
+ --html-out <file> Also write the report as one self-contained HTML
525
+ file — the one to email to whoever pays the bill.
526
+ Same figures as --json, caveats rendered as
527
+ prominently as the totals they qualify.
519
528
  --csv-shape <shape> Which table --csv-out writes: slice (default),
520
529
  day, hour, or model-day (one row per day and
521
530
  model — charts the mix moving). One row shape
@@ -1576,6 +1585,29 @@ ${bold('EXAMPLES')}
1576
1585
  '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.',
1577
1586
  },
1578
1587
 
1588
+ html: {
1589
+ caveatsHeading: () => 'What this report cannot say',
1590
+ noClock: () => 'No record carried a timestamp, so days, rates and drift are not in this report — a total is still a total.',
1591
+ noSessions: () => 'No record carried a session, so conversation growth and per-conversation costs are not in this report.',
1592
+ byLabelHeading: () => 'By workload',
1593
+ byModelHeading: () => 'By model',
1594
+ findingsHeading: () => 'What would move this bill',
1595
+ colLabel: () => 'workload',
1596
+ colModel: () => 'model',
1597
+ colContributor: () => 'contributor',
1598
+ colSpanDays: () => 'days',
1599
+ colCalls: () => 'calls',
1600
+ colInput: () => 'input',
1601
+ colCacheRead: () => 'cache reads',
1602
+ colCacheWrite: () => 'cache writes',
1603
+ colOutput: () => 'output',
1604
+ sharesLine: (input, cacheRead, cacheWrite, output) =>
1605
+ `Where the money goes: ${input} plain input, ${cacheRead} cache reads, ${cacheWrite} cache writes, ${output} output.`,
1606
+ footer: () =>
1607
+ 'Generated by trazum from a usage log, offline. Every figure derives from that log and the pricing table the run named; nothing here was sent anywhere to be computed.',
1608
+ written: (path) => `HTML report written to ${path}.`,
1609
+ },
1610
+
1579
1611
  bench: {
1580
1612
  heading: () => 'This machine, measured',
1581
1613
  machine: (node, platform, cpuCount, cpuModel) =>
package/src/i18n/es.ts CHANGED
@@ -43,7 +43,7 @@ ${bold('USO')}
43
43
  trazum prune <fichero> --cases <fichero> --yes
44
44
  trazum where [fichero]
45
45
  trazum conform <fichero|-> [--contract <nombre>]
46
- trazum rollup <documento...|dir> [--json]
46
+ trazum rollup <documento...|dir> [--json] [--html-out <fichero>]
47
47
  trazum pulse [--max-stale-hours <n>]
48
48
  trazum bench [--workload <id>] [--record <fichero>] [--against <fichero> --max-ratio <n>] [--json]
49
49
  trazum write [--answers <fichero>] [--json] [-o <fichero>]
@@ -92,6 +92,12 @@ ${bold('OPCIONES DE conform')}
92
92
  ${bold('OPCIONES DE rollup')}
93
93
  --json El documento de agregación como datos. Ver
94
94
  docs/format.md.
95
+ --html-out <fichero> Escribe además el roll-up como un único HTML
96
+ autocontenido — el informe de equipo, para quien
97
+ paga la factura. Los huecos de cada contribuyente
98
+ se quedan bajo ese contribuyente, y lo que ninguna
99
+ fusión puede medir va en la caja de salvedades,
100
+ imposible de recortar.
95
101
 
96
102
  Las facturas de varias personas, una sola agregación. Cada contribuyente
97
103
  ejecuta \`trazum profile --json\` donde ya está su tráfico; esto fusiona los
@@ -523,6 +529,11 @@ ${bold('OPCIONES DE profile')}
523
529
  imposibles, no se cobran como baratas.
524
530
  --markdown-out <fichero> Escribe además el informe en Markdown, para el
525
531
  resumen de un job de CI o un comentario de PR.
532
+ --html-out <fichero> Escribe además el informe como un único HTML
533
+ autocontenido — el que se envía por correo a
534
+ quien paga la factura. Las mismas cifras que
535
+ --json, con las salvedades tan visibles como
536
+ los totales a los que acompañan.
526
537
  --csv-shape <forma> Qué tabla escribe --csv-out: slice (por defecto),
527
538
  day, hour o model-day (una fila por día y
528
539
  modelo — dibuja la mezcla moviéndose). Una sola
@@ -1586,6 +1597,29 @@ ${bold('EJEMPLOS')}
1586
1597
  '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ó.',
1587
1598
  },
1588
1599
 
1600
+ html: {
1601
+ caveatsHeading: () => 'Lo que este informe no puede decir',
1602
+ noClock: () => 'Ningún registro traía marca de tiempo, así que días, ritmos y deriva no están en este informe — un total sigue siendo un total.',
1603
+ noSessions: () => 'Ningún registro traía sesión, así que el crecimiento de conversación y los costes por conversación no están en este informe.',
1604
+ byLabelHeading: () => 'Por carga de trabajo',
1605
+ byModelHeading: () => 'Por modelo',
1606
+ findingsHeading: () => 'Qué movería esta factura',
1607
+ colLabel: () => 'carga',
1608
+ colModel: () => 'modelo',
1609
+ colContributor: () => 'contribuyente',
1610
+ colSpanDays: () => 'días',
1611
+ colCalls: () => 'llamadas',
1612
+ colInput: () => 'entrada',
1613
+ colCacheRead: () => 'lecturas de caché',
1614
+ colCacheWrite: () => 'escrituras de caché',
1615
+ colOutput: () => 'salida',
1616
+ sharesLine: (input, cacheRead, cacheWrite, output) =>
1617
+ `A dónde va el dinero: ${input} entrada normal, ${cacheRead} lecturas de caché, ${cacheWrite} escrituras de caché, ${output} salida.`,
1618
+ footer: () =>
1619
+ 'Generado por trazum a partir de un log de uso, sin conexión. Cada cifra deriva de ese log y de la tabla de precios que la ejecución nombró; nada de esto se envió a ninguna parte para calcularse.',
1620
+ written: (path) => `Informe HTML escrito en ${path}.`,
1621
+ },
1622
+
1589
1623
  bench: {
1590
1624
  heading: () => 'Esta máquina, medida',
1591
1625
  machine: (node, platform, cpuCount, cpuModel) =>
package/src/i18n/types.ts CHANGED
@@ -529,6 +529,28 @@ export interface CliMessages {
529
529
  notAService(): string;
530
530
  };
531
531
 
532
+ /** The HTML report: the one surface for a reader with an inbox, not a terminal. */
533
+ html: {
534
+ caveatsHeading(): string;
535
+ noClock(): string;
536
+ noSessions(): string;
537
+ byLabelHeading(): string;
538
+ byModelHeading(): string;
539
+ findingsHeading(): string;
540
+ colLabel(): string;
541
+ colModel(): string;
542
+ colContributor(): string;
543
+ colSpanDays(): string;
544
+ colCalls(): string;
545
+ colInput(): string;
546
+ colCacheRead(): string;
547
+ colCacheWrite(): string;
548
+ colOutput(): string;
549
+ sharesLine(input: string, cacheRead: string, cacheWrite: string, output: string): string;
550
+ footer(): string;
551
+ written(path: string): string;
552
+ };
553
+
532
554
  bench: {
533
555
  heading(): string;
534
556
  machine(node: string, platform: string, cpuCount: number, cpuModel: string | null): string;
package/src/index.ts CHANGED
@@ -238,6 +238,7 @@ import {
238
238
  renderRankMarkdown,
239
239
  renderProfileMarkdown,
240
240
  } from './markdown.js';
241
+ import { renderProfileHtml, renderRollupHtml } from './html.js';
241
242
  import type { CliMessages } from './i18n/index.js';
242
243
 
243
244
  // --------------------------------------------------------------------------
@@ -331,6 +332,7 @@ const VALUE_FLAGS = new Set([
331
332
  'locale',
332
333
  'config',
333
334
  'markdown-out',
335
+ 'html-out',
334
336
  'otlp-out',
335
337
  'pricing',
336
338
  'prompt',
@@ -617,7 +619,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
617
619
  ],
618
620
  check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
619
621
  baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
620
- 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'],
622
+ profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'html-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'],
621
623
  plan: ['json', 'out', 'markdown-out', 'min-usd', 'pricing', 'pricing-live'],
622
624
  verify: ['against', 'gate', 'json', 'markdown-out', 'pricing', 'pricing-live'],
623
625
  history: ['store', 'json', 'markdown-out'],
@@ -633,7 +635,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
633
635
  rank: ['level', 'model', 'calls', 'output-tokens', 'batch', 'disable', 'prompt', 'markdown-out'],
634
636
  init: ['dry-run', 'yes', 'json', 'pricing', 'pricing-live'],
635
637
  conform: ['contract', 'json'],
636
- rollup: ['json'],
638
+ rollup: ['json', 'html-out'],
637
639
  pulse: ['json', 'max-stale-hours'],
638
640
  bench: ['workload', 'json', 'record', 'against', 'max-ratio'],
639
641
  write: ['answers', 'json', 'out', 'o', 'calls', 'avg-output'],
@@ -2193,6 +2195,14 @@ async function commandRollup(args: Args, t: CliMessages): Promise<void> {
2193
2195
 
2194
2196
  const document = rollUp(inputs);
2195
2197
 
2198
+ // The HTML door, on both output paths — a side file that vanished under
2199
+ // --json is the fault the profile's --csv-out already taught this file.
2200
+ const htmlOut = stringFlag(args, 'html-out');
2201
+ if (htmlOut !== undefined) {
2202
+ await writeFile(htmlOut, renderRollupHtml(document, t), 'utf8');
2203
+ console.error(c.dim(t.html.written(htmlOut)));
2204
+ }
2205
+
2196
2206
  if (boolFlag(args, 'json')) {
2197
2207
  console.log(JSON.stringify(document, null, 2));
2198
2208
  // A rejected contribution is a machine missing from the total, so it gates
@@ -7329,11 +7339,26 @@ async function commandProfile(
7329
7339
  * comment. Written from the same message catalogue the terminal used, because
7330
7340
  * two renderings of one finding drift the moment they are worded twice.
7331
7341
  */
7332
- const markdownOut = stringFlag(args, 'markdown-out');
7333
- if (markdownOut !== undefined) {
7334
- await writeFile(
7335
- markdownOut,
7336
- renderProfileMarkdown({
7342
+ const markdownOut = stringFlag(args, 'markdown-out');
7343
+ const htmlOut = stringFlag(args, 'html-out');
7344
+ if (markdownOut !== undefined || htmlOut !== undefined) {
7345
+ /**
7346
+ * Derived here, not borrowed from the terminal path. Under `--json`
7347
+ * that path never runs, and the outer `levers` this block used to
7348
+ * reach for was an uninitialised binding — `profile --json
7349
+ * --markdown-out` crashed with a ReferenceError from 1.59 until the
7350
+ * HTML door's test drove both flags together and found it. The flag
7351
+ * did not silently do nothing; it loudly did nothing, and no test had
7352
+ * ever asked.
7353
+ */
7354
+ const levers = billLevers(report, { catalogue: pricing });
7355
+ const cache = cacheEconomics(report.total);
7356
+ /**
7357
+ * One input object for both doors, built once: the HTML file and the
7358
+ * Markdown file are two projections of the same figures, and building
7359
+ * the input twice is how two renderings of one bill start disagreeing.
7360
+ */
7361
+ const renderInput = ({
7337
7362
  report,
7338
7363
  levers,
7339
7364
  cache,
@@ -7375,10 +7400,15 @@ async function commandProfile(
7375
7400
  },
7376
7401
  }
7377
7402
  : {}),
7378
- }),
7379
- 'utf8',
7380
- );
7381
- notice(c.dim(t.report.wroteTo(markdownOut)));
7403
+ });
7404
+ if (markdownOut !== undefined) {
7405
+ await writeFile(markdownOut, renderProfileMarkdown(renderInput), 'utf8');
7406
+ notice(c.dim(t.report.wroteTo(markdownOut)));
7407
+ }
7408
+ if (htmlOut !== undefined) {
7409
+ await writeFile(htmlOut, renderProfileHtml(renderInput), 'utf8');
7410
+ notice(c.dim(t.html.written(htmlOut)));
7411
+ }
7382
7412
  }
7383
7413
 
7384
7414
  /**