@trazum/cli 1.32.0 → 1.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.32.0"
+    "@trazum/core": "1.33.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -1150,6 +1150,28 @@ ${bold('EXAMPLES')}
       `--what-if does not know "${value}". Priced models: ${available}. Add it with --pricing if you have its rates.`,
     badGzip: (file, detail) =>
       `${file} is gzipped and would not decompress: ${detail}. Reading the rest and saying nothing would report a bill missing whatever that file held, so this stops instead. Check the file, or move it out of the directory.`,
+    dryRunHeading: () => 'What this log can answer — no bill was produced',
+    dryRunParsed: (parsed, skipped) =>
+      `${parsed} records parse; ${skipped} lines could not be read. A dry run prices nothing: the point is what the gates you are about to wire would stand on.`,
+    dryRunUnpriced: (models) =>
+      `Models the price table does not know: ${models}. Their tokens parse; their dollars need a --pricing overlay.`,
+    dryRunTotals: () => 'The bill itself: totals, per-model split, cache economics, the levers.',
+    dryRunLabels: (share) =>
+      `Per-workload findings and label budgets — "label" on ${share} of records.`,
+    dryRunClock: (share) =>
+      `The period, per-day and per-hour shape, --max-day-usd, --since/--until — a timestamp on ${share} of records.`,
+    dryRunSessions: (share) =>
+      `Conversation growth, per-conversation cost, --max-session-usd — a session on ${share} of records. Grouped by, never printed.`,
+    dryRunStopReason: (share) =>
+      `Truncated answers and their retry bill — a stop reason on ${share} of records.`,
+    dryRunCacheTtl: (ttl, writes) =>
+      `Settled cache verdicts — the "cache_creation" split on ${ttl} of ${writes} cache-writing records.`,
+    dryRunNoCacheTraffic: () =>
+      'Cache verdicts: nothing wrote to the cache in this log, so there is nothing to settle — not a missing field.',
+    dryRunFooter: () =>
+      'A ✗ is not a defect in the log; it is a finding this log cannot support yet. The README\'s recording recipe carries every field above.',
+    dryRunNoGates: () =>
+      '--dry-run produces no bill, so a gate beside it would exit green having judged nothing. Run the gates without --dry-run.',
     coverageHeading: () => 'What this log cannot answer yet',
     needsLabel: (seen) =>
       `"label" on ${seen} records: without it every workload is one row, so no per-workload spend, no drill-down, and the levers describe a mixture rather than a decision.`,

package/src/i18n/es.ts

@@ -1165,6 +1165,28 @@ ${bold('EJEMPLOS')}
       `--what-if no conoce "${value}". Modelos con precio: ${available}. Añádelo con --pricing si tienes sus tarifas.`,
     badGzip: (file, detail) =>
       `${file} está comprimido con gzip y no se ha podido descomprimir: ${detail}. Leer el resto y no decir nada daría una factura a la que le falta lo que hubiera en ese fichero, así que se para aquí. Revisa el fichero, o sácalo del directorio.`,
+    dryRunHeading: () => 'Qué puede responder este registro — no se ha producido factura',
+    dryRunParsed: (parsed, skipped) =>
+      `${parsed} registros se leen; ${skipped} líneas no se pudieron leer. Un dry run no valora nada: el punto es sobre qué se apoyarían los gates que vas a cablear.`,
+    dryRunUnpriced: (models) =>
+      `Modelos que la tabla de precios no conoce: ${models}. Sus tokens se leen; sus dólares necesitan un overlay --pricing.`,
+    dryRunTotals: () => 'La factura en sí: totales, desglose por modelo, economía de caché, las palancas.',
+    dryRunLabels: (share) =>
+      `Hallazgos por carga y presupuestos por etiqueta — "label" en el ${share} de los registros.`,
+    dryRunClock: (share) =>
+      `El periodo, la forma por día y por hora, --max-day-usd, --since/--until — marca de tiempo en el ${share} de los registros.`,
+    dryRunSessions: (share) =>
+      `Crecimiento de conversación, coste por conversación, --max-session-usd — sesión en el ${share} de los registros. Se agrupa por ella, nunca se imprime.`,
+    dryRunStopReason: (share) =>
+      `Respuestas truncadas y su factura de reintentos — razón de parada en el ${share} de los registros.`,
+    dryRunCacheTtl: (ttl, writes) =>
+      `Veredictos de caché resueltos — el desglose "cache_creation" en ${ttl} de ${writes} registros que escriben caché.`,
+    dryRunNoCacheTraffic: () =>
+      'Veredictos de caché: nada escribió en la caché en este registro, así que no hay nada que resolver — no es un campo ausente.',
+    dryRunFooter: () =>
+      'Una ✗ no es un defecto del registro; es un hallazgo que este registro aún no puede sostener. La receta de registro del README lleva todos los campos de arriba.',
+    dryRunNoGates: () =>
+      '--dry-run no produce factura, así que un gate a su lado saldría en verde sin haber juzgado nada. Corre los gates sin --dry-run.',
     coverageHeading: () => 'Lo que este registro todavía no puede responder',
     needsLabel: (seen) =>
       `"label" en ${seen} registros: sin él todas las cargas son una sola fila, así que no hay gasto por carga, ni zoom, y las palancas describen una mezcla en vez de una decisión.`,

package/src/i18n/types.ts

@@ -916,6 +916,23 @@ export interface CliMessages {
       * a skip: a total quietly missing a day is the failure this refuses.
       */
     badGzip(file: string, detail: string): string;
+    /**
+     * `--dry-run`: readiness per capability, no bill. The question somebody
+     * has before wiring CI, answered without making them read a report to
+     * discover a missing field.
+     */
+    dryRunHeading(): string;
+    dryRunParsed(parsed: string, skipped: string): string;
+    dryRunUnpriced(models: string): string;
+    dryRunTotals(): string;
+    dryRunLabels(share: string): string;
+    dryRunClock(share: string): string;
+    dryRunSessions(share: string): string;
+    dryRunStopReason(share: string): string;
+    dryRunCacheTtl(ttl: string, writes: string): string;
+    dryRunNoCacheTraffic(): string;
+    dryRunFooter(): string;
+    dryRunNoGates(): string;
     coverageHeading(): string;
     needsLabel(seen: string): string;
     needsSession(seen: string): string;

package/src/index.ts

@@ -440,7 +440,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   ],
   check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
   baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
-  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'],
+  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'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2146,6 +2146,52 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const pct = (share: number): string => `${(share * 100).toFixed(1)}%`;
 
+  /**
+   * `--dry-run`: what this log could and could not answer, and no bill.
+   *
+   * The question somebody has *before* wiring Trazum into CI is not "what did
+   * we spend" but "will this log support the gates I want" — and answering it
+   * with a full report makes them read a bill to find out a field is missing.
+   * This path states readiness per capability and produces no dollar figure
+   * at all, so nothing here can be mistaken for spend. It also refuses to
+   * coexist with the gates: a gate over a report that was never produced
+   * would exit green having judged nothing.
+   */
+  if (boolFlag(args, 'dry-run')) {
+    const gateFlags = ['max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd'];
+    if (gateFlags.some((flag) => typeof args.flags.get(flag) === 'string')) {
+      throw new Error(t.profile.dryRunNoGates());
+    }
+    const cov = report.fieldCoverage;
+    const parsed = cov.parsed;
+    console.log(c.bold(t.profile.dryRunHeading()));
+    console.log(`  ${wrap(t.profile.dryRunParsed(n(parsed), n(report.skippedLines.length)), 74, '  ')}`);
+    if (report.unpricedModels.length > 0) {
+      console.log(`  ${c.yellow('!')} ${wrap(t.profile.dryRunUnpriced(report.unpricedModels.join(', ')), 74, '    ')}`);
+    }
+    console.log();
+    const can = (ok: boolean, line: string): void => {
+      console.log(`  ${ok ? c.green('✓') : c.yellow('✗')} ${wrap(line, 74, '    ')}`);
+    };
+    const share = (count: number): string => (parsed > 0 ? pct(count / parsed) : '0%');
+    can(parsed > 0, t.profile.dryRunTotals());
+    can(cov.label > 0, t.profile.dryRunLabels(share(cov.label)));
+    can(cov.ts > 0, t.profile.dryRunClock(share(cov.ts)));
+    can(cov.session > 0, t.profile.dryRunSessions(share(cov.session)));
+    can(cov.stopReason > 0, t.profile.dryRunStopReason(share(cov.stopReason)));
+    // "No cache traffic" is not a missing field: the split can only exist on
+    // records that wrote, and a log that never wrote has nothing to record.
+    if (cov.cacheWrites > 0) {
+      can(cov.cacheTtl > 0, t.profile.dryRunCacheTtl(n(cov.cacheTtl), n(cov.cacheWrites)));
+    } else {
+      console.log(`  ${c.dim('·')} ${wrap(t.profile.dryRunNoCacheTraffic(), 74, '    ')}`);
+    }
+    console.log();
+    console.log(`  ${c.dim(wrap(t.profile.dryRunFooter(), 74, '  '))}`);
+    if (parsed === 0) process.exitCode = 1;
+    return;
+  }
+
   /**
    * The previous log, loaded before the output paths split so the growth gate
    * exists under `--json` too — a CI step reads the JSON and trusts the exit