@trazum/cli 1.61.2 → 1.62.1

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.61.2",
3
+ "version": "1.62.1",
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.61.2"
40
+ "@trazum/core": "1.62.1"
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
@@ -1545,6 +1569,35 @@ ${bold('EXAMPLES')}
1545
1569
  '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
1570
  },
1547
1571
 
1572
+ bench: {
1573
+ heading: () => 'This machine, measured',
1574
+ machine: (node, platform, cpuCount, cpuModel) =>
1575
+ `node ${node} on ${platform}, ${plural(cpuCount, 'CPU')}${cpuModel === null ? '' : ` (${cpuModel})`}`,
1576
+ colWorkload: () => 'workload',
1577
+ colWall: () => 'wall ms',
1578
+ colRatio: () => 'ratio',
1579
+ colPeakRss: () => 'peak RSS',
1580
+ note: () =>
1581
+ '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.',
1582
+ unknownWorkload: (id, known) => `Unknown workload "${id}". Known: ${known}.`,
1583
+ recorded: (path) => `Baseline written to ${path}. Commit it; --against reads it.`,
1584
+ needsMaxRatio: () =>
1585
+ '--against needs --max-ratio <n>. How much regression is too much is a policy, and this tool does not write yours.',
1586
+ maxRatioNeedsAgainst: () => '--max-ratio judges against a baseline; pass --against <file> too.',
1587
+ badMaxRatio: (raw) =>
1588
+ `--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.`,
1589
+ recordAndAgainst: () =>
1590
+ '--record and --against together would gate a run against the baseline it is writing. Record, commit, then gate.',
1591
+ unreadableBaseline: (path) => `Could not read a baseline from ${path}. Re-record it with --record.`,
1592
+ badBaseline: (path, version) =>
1593
+ `${path} is not a baseline this version knows (schemaVersion: ${version}). Re-record it with --record rather than letting a misread number gate the build.`,
1594
+ notInBaseline: (id, path) =>
1595
+ `${path} records no ratio for "${id}", and silently passing an unrecorded workload would read as coverage. Re-record with --record.`,
1596
+ gateOver: (id, ratio, allowed) =>
1597
+ `✗ ${id}: ratio ${ratio} is past the allowed ${allowed} (baseline × --max-ratio).`,
1598
+ gateWithin: (factor) => `Every measured workload is within ${factor}× its recorded ratio.`,
1599
+ },
1600
+
1548
1601
  where: {
1549
1602
  hostHeading: () => 'Running inside',
1550
1603
  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
@@ -1555,6 +1579,35 @@ ${bold('EJEMPLOS')}
1555
1579
  '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
1580
  },
1557
1581
 
1582
+ bench: {
1583
+ heading: () => 'Esta máquina, medida',
1584
+ machine: (node, platform, cpuCount, cpuModel) =>
1585
+ `node ${node} en ${platform}, ${plural(cpuCount, 'CPU')}${cpuModel === null ? '' : ` (${cpuModel})`}`,
1586
+ colWorkload: () => 'carga',
1587
+ colWall: () => 'ms de pared',
1588
+ colRatio: () => 'ratio',
1589
+ colPeakRss: () => 'RSS pico',
1590
+ note: () =>
1591
+ '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.',
1592
+ unknownWorkload: (id, known) => `Carga desconocida "${id}". Conocidas: ${known}.`,
1593
+ recorded: (path) => `Baseline escrito en ${path}. Commitéalo; --against lo lee.`,
1594
+ needsMaxRatio: () =>
1595
+ '--against necesita --max-ratio <n>. Cuánta regresión es demasiada es una política, y esta herramienta no escribe la tuya.',
1596
+ maxRatioNeedsAgainst: () => '--max-ratio juzga contra un baseline; pasa también --against <fichero>.',
1597
+ badMaxRatio: (raw) =>
1598
+ `--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.`,
1599
+ recordAndAgainst: () =>
1600
+ '--record y --against juntos evaluarían una pasada contra el baseline que ella misma escribe. Graba, commitea, y luego evalúa.',
1601
+ unreadableBaseline: (path) => `No se pudo leer un baseline de ${path}. Vuelve a grabarlo con --record.`,
1602
+ badBaseline: (path, version) =>
1603
+ `${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.`,
1604
+ notInBaseline: (id, path) =>
1605
+ `${path} no graba ratio para "${id}", y aprobar en silencio una carga sin grabar se leería como cobertura. Vuelve a grabar con --record.`,
1606
+ gateOver: (id, ratio, allowed) =>
1607
+ `✗ ${id}: el ratio ${ratio} supera el permitido ${allowed} (baseline × --max-ratio).`,
1608
+ gateWithin: (factor) => `Cada carga medida está dentro de ${factor}× su ratio grabado.`,
1609
+ },
1610
+
1558
1611
  where: {
1559
1612
  hostHeading: () => 'Ejecutándose dentro de',
1560
1613
  subscription: (host) =>
package/src/i18n/types.ts CHANGED
@@ -526,6 +526,27 @@ export interface CliMessages {
526
526
  notAService(): string;
527
527
  };
528
528
 
529
+ bench: {
530
+ heading(): string;
531
+ machine(node: string, platform: string, cpuCount: number, cpuModel: string | null): string;
532
+ colWorkload(): string;
533
+ colWall(): string;
534
+ colRatio(): string;
535
+ colPeakRss(): string;
536
+ note(): string;
537
+ unknownWorkload(id: string, known: string): string;
538
+ recorded(path: string): string;
539
+ needsMaxRatio(): string;
540
+ maxRatioNeedsAgainst(): string;
541
+ badMaxRatio(raw: string): string;
542
+ recordAndAgainst(): string;
543
+ unreadableBaseline(path: string): string;
544
+ badBaseline(path: string, version: string): string;
545
+ notInBaseline(id: string, path: string): string;
546
+ gateOver(id: string, ratio: string, allowed: string): string;
547
+ gateWithin(factor: string): string;
548
+ };
549
+
529
550
  where: {
530
551
  hostHeading(): string;
531
552
  subscription(host: string): string;