@trazum/cli 1.62.0 → 1.63.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.62.0",
3
+ "version": "1.63.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.62.0"
40
+ "@trazum/core": "1.63.0"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/git.ts CHANGED
@@ -4,9 +4,10 @@ import { isAbsolute, relative, resolve, sep } from 'node:path';
4
4
  /**
5
5
  * The only place in this repository that runs another program.
6
6
  *
7
- * `trazum blame` needs a file's history, and the history lives in git. Nothing
8
- * else here has ever shelled out, so this module is written as if it were the
9
- * whole attack surface — because it is.
7
+ * `trazum blame` needs a file's history, and the history lives in git;
8
+ * `trazum bench` needs a fresh process per workload, because a memory peak is
9
+ * a fact about a process. Nothing else here has ever shelled out, so this
10
+ * module is written as if it were the whole attack surface — because it is.
10
11
  *
11
12
  * The rules, and why each one is here rather than in a comment on the call site:
12
13
  *
@@ -187,6 +188,37 @@ export function pathInRepository(root: string, target: string): string | null {
187
188
  return rel.split(sep).join('/');
188
189
  }
189
190
 
191
+ /**
192
+ * Two minutes: a bench child runs a workload in seconds, and a machine where
193
+ * it takes longer than this deserves a loud failure, not a silent wait.
194
+ */
195
+ const SELF_TIMEOUT_MS = 120_000;
196
+
197
+ /**
198
+ * Runs this same CLI in a child process and returns its stdout.
199
+ *
200
+ * The bench's isolation seam, kept in this module so the invariant the
201
+ * security suite asserts — child_process appears in exactly one file — stays
202
+ * whole. The same rules as the git spawn, and one more: **every argument is
203
+ * the caller's own.** The bench passes a script path derived from its own
204
+ * module URL, workload ids from a const list, and a locale its catalogue
205
+ * produced; nothing typed by a user reaches this argv.
206
+ */
207
+ export function runSelf(scriptPath: string, args: readonly string[]): string {
208
+ const result = spawnSync(process.execPath, [scriptPath, ...args], {
209
+ // Stated rather than left to the default, same as the git spawn above.
210
+ shell: false,
211
+ encoding: 'utf8',
212
+ timeout: SELF_TIMEOUT_MS,
213
+ maxBuffer: MAX_BUFFER,
214
+ });
215
+ if (result.error !== undefined) throw result.error;
216
+ if (result.status !== 0) {
217
+ throw new Error(result.stderr.trim() || `child exited with status ${result.status}`);
218
+ }
219
+ return result.stdout;
220
+ }
221
+
190
222
  /**
191
223
  * Commits that touched `repoPath`, newest first.
192
224
  *
package/src/i18n/en.ts CHANGED
@@ -58,6 +58,7 @@ ${bold('USAGE')}
58
58
  trazum conform <file|-> [--contract <name>]
59
59
  trazum rollup <document...|dir> [--json]
60
60
  trazum pulse [--max-stale-hours <n>]
61
+ trazum bench [--workload <id>] [--record <file>] [--against <file> --max-ratio <n>] [--json]
61
62
  trazum write [--answers <file>] [--json] [-o <file>]
62
63
  trazum models
63
64
  trazum rules [--measure <dir>] [--level <safe|aggressive>]
@@ -147,6 +148,29 @@ ${bold('OPTIONS FOR pulse')}
147
148
  late against — and never on how far the measurements reach, which is a
148
149
  provider reporting on its own schedule rather than a job that failed.
149
150
 
151
+ ${bold('OPTIONS FOR bench')}
152
+ --workload <id> Run one standard workload instead of all of them.
153
+ An unknown id is refused with the known ones named.
154
+ --record <file> Also write the measured ratios as a baseline, to
155
+ commit. The file --against reads.
156
+ --against <file> Judge this run's ratios against a recorded
157
+ baseline. Exits 1 when any measured workload is
158
+ past its recorded ratio times --max-ratio.
159
+ --max-ratio <n> The stated factor, at least 1. Required with
160
+ --against: how much regression is too much is a
161
+ policy, and this tool does not write yours.
162
+ --json The measurements as data. The shape never changes
163
+ with the gate flags — a verdict is the exit code
164
+ and sentences on stderr, the way check gates.
165
+
166
+ Measures this machine: the standard workloads, one shot each, wall time and
167
+ peak RSS. The wall clock is for a person with a change in hand; the gate
168
+ holds the ratio of workload to an in-process calibration loop, because a CI
169
+ runner lies about wall time to both by the same amount and the lie cancels
170
+ out. Each workload runs in its own child process, so a peak is that
171
+ workload's own; the inputs are generated, deterministic and never written to
172
+ your project.
173
+
150
174
  ${bold('OPTIONS FOR rules')}
151
175
  --measure <dir> Measure what each rule actually recovers over the
152
176
  prompts in that directory, instead of listing what
@@ -381,6 +405,10 @@ ${bold('OPTIONS FOR optimize')}
381
405
  --diff Show the line-by-line diff.
382
406
  --json Dump the full report as JSON.
383
407
  --locale <${d.locales.join('|')}> Language of the report. Default: the system language.
408
+ --max-input <chars> Raise (or lower) the prompt-input ceiling, per run.
409
+ Above it a prompt door refuses with the size and
410
+ the limit named rather than grinding. Logs and
411
+ documents are never held to it.
384
412
  -o, --out <file> Write the optimised prompt to a file.
385
413
  -h, --help This help.
386
414
  --clear-suggestion-cache Empty the --cache-suggestions cache and say how much
@@ -857,6 +885,9 @@ ${bold('EXAMPLES')}
857
885
  optionNeedsValue: (name) => `Option --${name} needs a value.`,
858
886
  mustBeNonNegative: (name, raw) =>
859
887
  `--${name} must be a non-negative number (received: "${raw}").`,
888
+ inputTooLarge: (source, size, limit) =>
889
+ `${source} is ${count(size)} characters, past the ${count(limit)}-character ceiling for a prompt. Raise it deliberately with --max-input <chars> if this input really is one.`,
890
+ badMaxInput: (raw) => `--max-input must be a positive number of characters (received: "${raw}").`,
860
891
  fractionFlag: (name, raw) =>
861
892
  `--${name} is a fraction between 0 and 1 (received: ${raw}). The config refuses the same value the same way.`,
862
893
  badLevel: (received) => `--level must be "safe" or "aggressive" (received: "${received}").`,
@@ -1545,6 +1576,35 @@ ${bold('EXAMPLES')}
1545
1576
  '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.',
1546
1577
  },
1547
1578
 
1579
+ bench: {
1580
+ heading: () => 'This machine, measured',
1581
+ machine: (node, platform, cpuCount, cpuModel) =>
1582
+ `node ${node} on ${platform}, ${plural(cpuCount, 'CPU')}${cpuModel === null ? '' : ` (${cpuModel})`}`,
1583
+ colWorkload: () => 'workload',
1584
+ colWall: () => 'wall ms',
1585
+ colRatio: () => 'ratio',
1586
+ colPeakRss: () => 'peak RSS',
1587
+ note: () =>
1588
+ 'One shot each, this machine, today. The wall clock is for a person reading two tables side by side; the ratio — workload over an in-process calibration loop — is the number a gate can hold, because the machine cancels out of it. Record one with --record, hold a build to it with --against and a stated --max-ratio.',
1589
+ unknownWorkload: (id, known) => `Unknown workload "${id}". Known: ${known}.`,
1590
+ recorded: (path) => `Baseline written to ${path}. Commit it; --against reads it.`,
1591
+ needsMaxRatio: () =>
1592
+ '--against needs --max-ratio <n>. How much regression is too much is a policy, and this tool does not write yours.',
1593
+ maxRatioNeedsAgainst: () => '--max-ratio judges against a baseline; pass --against <file> too.',
1594
+ badMaxRatio: (raw) =>
1595
+ `--max-ratio must be a finite number of at least 1 (received: ${raw}). It multiplies the recorded ratio; below 1 it would demand the code got faster.`,
1596
+ recordAndAgainst: () =>
1597
+ '--record and --against together would gate a run against the baseline it is writing. Record, commit, then gate.',
1598
+ unreadableBaseline: (path) => `Could not read a baseline from ${path}. Re-record it with --record.`,
1599
+ badBaseline: (path, version) =>
1600
+ `${path} is not a baseline this version knows (schemaVersion: ${version}). Re-record it with --record rather than letting a misread number gate the build.`,
1601
+ notInBaseline: (id, path) =>
1602
+ `${path} records no ratio for "${id}", and silently passing an unrecorded workload would read as coverage. Re-record with --record.`,
1603
+ gateOver: (id, ratio, allowed) =>
1604
+ `✗ ${id}: ratio ${ratio} is past the allowed ${allowed} (baseline × --max-ratio).`,
1605
+ gateWithin: (factor) => `Every measured workload is within ${factor}× its recorded ratio.`,
1606
+ },
1607
+
1548
1608
  where: {
1549
1609
  hostHeading: () => 'Running inside',
1550
1610
  subscription: (host) =>
package/src/i18n/es.ts CHANGED
@@ -45,6 +45,7 @@ ${bold('USO')}
45
45
  trazum conform <fichero|-> [--contract <nombre>]
46
46
  trazum rollup <documento...|dir> [--json]
47
47
  trazum pulse [--max-stale-hours <n>]
48
+ trazum bench [--workload <id>] [--record <fichero>] [--against <fichero> --max-ratio <n>] [--json]
48
49
  trazum write [--answers <fichero>] [--json] [-o <fichero>]
49
50
  trazum models
50
51
  trazum rules [--measure <dir>] [--level <safe|aggressive>]
@@ -135,6 +136,29 @@ ${bold('OPCIONES DE pulse')}
135
136
  contra la que ir tarde — ni por hasta dónde llegan las mediciones, que es un
136
137
  proveedor informando a su ritmo y no un trabajo que falló.
137
138
 
139
+ ${bold('OPCIONES DE bench')}
140
+ --workload <id> Ejecuta una sola carga estándar en vez de todas.
141
+ Un id desconocido se rechaza nombrando los conocidos.
142
+ --record <fichero> Escribe además los ratios medidos como baseline,
143
+ para commitear. El fichero que --against lee.
144
+ --against <fichero> Juzga los ratios de esta pasada contra un baseline
145
+ grabado. Sale con 1 cuando alguna carga medida
146
+ supera su ratio grabado por --max-ratio.
147
+ --max-ratio <n> El factor declarado, al menos 1. Obligatorio con
148
+ --against: cuánta regresión es demasiada es una
149
+ política, y esta herramienta no escribe la tuya.
150
+ --json Las mediciones como datos. La forma no cambia con
151
+ los flags del gate — el veredicto es el código de
152
+ salida y frases en stderr, como hace check.
153
+
154
+ Mide esta máquina: las cargas estándar, una pasada cada una, tiempo de pared y
155
+ RSS pico. El reloj de pared es para una persona con un cambio entre manos; el
156
+ gate sostiene el ratio entre la carga y un bucle de calibración en el mismo
157
+ proceso, porque un runner de CI miente sobre el tiempo a ambos por igual y la
158
+ mentira se cancela. Cada carga corre en su propio proceso hijo, así que cada
159
+ pico es solo suyo; las entradas se generan, son deterministas y nunca se
160
+ escriben en tu proyecto.
161
+
138
162
  ${bold('OPCIONES DE rules')}
139
163
  --measure <dir> Mide lo que recupera realmente cada regla sobre
140
164
  los prompts de ese directorio, en vez de listar
@@ -380,6 +404,10 @@ ${bold('OPCIONES DE optimize')}
380
404
  --diff Muestra el diff línea a línea.
381
405
  --json Vuelca el informe completo en JSON.
382
406
  --locale <${d.locales.join('|')}> Idioma del informe. Por defecto: el del sistema.
407
+ --max-input <caracteres> Sube (o baja) el techo de entrada de prompts, por
408
+ ejecución. Por encima, una puerta de prompt rechaza
409
+ nombrando el tamaño y el límite en vez de arrastrarse.
410
+ Los logs y documentos nunca se sujetan a él.
383
411
  -o, --out <fichero> Escribe el prompt optimizado a un fichero.
384
412
  -h, --help Esta ayuda.
385
413
  --clear-suggestion-cache Vacía la caché de --cache-suggestions y dice cuánto
@@ -883,6 +911,9 @@ ${bold('EJEMPLOS')}
883
911
  optionNeedsValue: (name) => `La opción --${name} necesita un valor.`,
884
912
  mustBeNonNegative: (name, raw) =>
885
913
  `--${name} debe ser un número no negativo (recibido: "${raw}").`,
914
+ inputTooLarge: (source, size, limit) =>
915
+ `${source} tiene ${count(size)} caracteres, por encima del techo de ${count(limit)} para un prompt. Súbelo deliberadamente con --max-input <caracteres> si esta entrada de verdad lo es.`,
916
+ badMaxInput: (raw) => `--max-input debe ser un número positivo de caracteres (recibido: "${raw}").`,
886
917
  fractionFlag: (name, raw) =>
887
918
  `--${name} es una fracción entre 0 y 1 (recibido: ${raw}). La configuración rechaza el mismo valor de la misma forma.`,
888
919
  badLevel: (received) => `--level debe ser "safe" o "aggressive" (recibido: "${received}").`,
@@ -1555,6 +1586,35 @@ ${bold('EJEMPLOS')}
1555
1586
  '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ó.',
1556
1587
  },
1557
1588
 
1589
+ bench: {
1590
+ heading: () => 'Esta máquina, medida',
1591
+ machine: (node, platform, cpuCount, cpuModel) =>
1592
+ `node ${node} en ${platform}, ${plural(cpuCount, 'CPU')}${cpuModel === null ? '' : ` (${cpuModel})`}`,
1593
+ colWorkload: () => 'carga',
1594
+ colWall: () => 'ms de pared',
1595
+ colRatio: () => 'ratio',
1596
+ colPeakRss: () => 'RSS pico',
1597
+ note: () =>
1598
+ 'Una pasada cada una, esta máquina, hoy. El reloj de pared es para una persona leyendo dos tablas lado a lado; el ratio — carga entre un bucle de calibración en el mismo proceso — es el número que un gate puede sostener, porque la máquina se cancela en él. Graba uno con --record y sujeta una build con --against y un --max-ratio declarado.',
1599
+ unknownWorkload: (id, known) => `Carga desconocida "${id}". Conocidas: ${known}.`,
1600
+ recorded: (path) => `Baseline escrito en ${path}. Commitéalo; --against lo lee.`,
1601
+ needsMaxRatio: () =>
1602
+ '--against necesita --max-ratio <n>. Cuánta regresión es demasiada es una política, y esta herramienta no escribe la tuya.',
1603
+ maxRatioNeedsAgainst: () => '--max-ratio juzga contra un baseline; pasa también --against <fichero>.',
1604
+ badMaxRatio: (raw) =>
1605
+ `--max-ratio debe ser un número finito de al menos 1 (recibido: ${raw}). Multiplica el ratio grabado; por debajo de 1 exigiría que el código se hubiera vuelto más rápido.`,
1606
+ recordAndAgainst: () =>
1607
+ '--record y --against juntos evaluarían una pasada contra el baseline que ella misma escribe. Graba, commitea, y luego evalúa.',
1608
+ unreadableBaseline: (path) => `No se pudo leer un baseline de ${path}. Vuelve a grabarlo con --record.`,
1609
+ badBaseline: (path, version) =>
1610
+ `${path} no es un baseline que esta versión conozca (schemaVersion: ${version}). Vuelve a grabarlo con --record antes que dejar que un número mal leído bloquee la build.`,
1611
+ notInBaseline: (id, path) =>
1612
+ `${path} no graba ratio para "${id}", y aprobar en silencio una carga sin grabar se leería como cobertura. Vuelve a grabar con --record.`,
1613
+ gateOver: (id, ratio, allowed) =>
1614
+ `✗ ${id}: el ratio ${ratio} supera el permitido ${allowed} (baseline × --max-ratio).`,
1615
+ gateWithin: (factor) => `Cada carga medida está dentro de ${factor}× su ratio grabado.`,
1616
+ },
1617
+
1558
1618
  where: {
1559
1619
  hostHeading: () => 'Ejecutándose dentro de',
1560
1620
  subscription: (host) =>
package/src/i18n/types.ts CHANGED
@@ -84,6 +84,9 @@ export interface CliMessages {
84
84
  livePricingFailed: (url: string, detail: string) => string;
85
85
  optionNeedsValue(name: string): string;
86
86
  mustBeNonNegative(name: string, raw: string): string;
87
+ /** The refusal ceiling: an input past the limit is named, never ground through. */
88
+ inputTooLarge(source: string, size: number, limit: number): string;
89
+ badMaxInput(raw: string): string;
87
90
  /** A flag that is a fraction of a whole: over 1 is refused, like the config. */
88
91
  fractionFlag(name: string, raw: string): string;
89
92
  badLevel(received: string): string;
@@ -526,6 +529,27 @@ export interface CliMessages {
526
529
  notAService(): string;
527
530
  };
528
531
 
532
+ bench: {
533
+ heading(): string;
534
+ machine(node: string, platform: string, cpuCount: number, cpuModel: string | null): string;
535
+ colWorkload(): string;
536
+ colWall(): string;
537
+ colRatio(): string;
538
+ colPeakRss(): string;
539
+ note(): string;
540
+ unknownWorkload(id: string, known: string): string;
541
+ recorded(path: string): string;
542
+ needsMaxRatio(): string;
543
+ maxRatioNeedsAgainst(): string;
544
+ badMaxRatio(raw: string): string;
545
+ recordAndAgainst(): string;
546
+ unreadableBaseline(path: string): string;
547
+ badBaseline(path: string, version: string): string;
548
+ notInBaseline(id: string, path: string): string;
549
+ gateOver(id: string, ratio: string, allowed: string): string;
550
+ gateWithin(factor: string): string;
551
+ };
552
+
529
553
  where: {
530
554
  hostHeading(): string;
531
555
  subscription(host: string): string;