@trazum/cli 1.49.0 → 1.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.49.0",
+  "version": "1.50.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.49.0"
+    "@trazum/core": "1.50.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -54,6 +54,7 @@ ${bold('USAGE')}
   trazum blame <file> [options]
   trazum prune <file> --cases <file> --yes
   trazum where [file]
+  trazum conform <file|-> [--contract <name>]
   trazum models
   trazum rules
 
@@ -73,6 +74,20 @@ ${bold('OPTIONS FOR init')}
   measured figure and leaves the limit to you — a generated config full of
   guessed numbers is one nobody trusts.
 
+${bold('OPTIONS FOR conform')}
+  --contract <name>           Check against a named contract instead of
+                              detecting one: usage-log, profile, plan,
+                              verification, history, connected, cost-answer.
+  --json                      The report as data.
+
+  Answers two questions and keeps them apart. Does this document conform —
+  required fields, present and the right type, exits 1 when not. And what can a
+  valid document of this shape not answer, with the field that would unlock
+  each.
+
+  The second never gates. Choosing not to log sessions is a decision, not a
+  defect. See docs/format.md.
+
 ${bold('OPTIONS FOR prune')}
   --cases <file>              One input per line, or a JSON array. Required.
   --yes                       Actually spend the calls. Without it the estimate is
@@ -904,6 +919,23 @@ ${bold('EXAMPLES')}
       `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
   },
 
+  conform: {
+    noTarget: () =>
+      'Pass a file to check — a usage log, or any document Trazum emits. Use "-" to read from stdin.',
+    badContract: (given, known) => `"${given}" is not a contract. Known contracts: ${known}.`,
+    unrecognised: (path) => `${path} does not match any contract Trazum knows.`,
+    heading: (path, contract) => `${path} reads as a ${contract} document`,
+    headingLog: (path, contract, records) =>
+      `${path} reads as a ${contract}: ${records} ${records === 1 ? 'record' : 'records'}`,
+    conforms: () => 'It conforms. Every required field is present and the right type.',
+    problem: (at, kind, detail) => `${at}: ${detail} (${kind})`,
+    moreProblems: (count) => `…and ${count} more. Fix these first; they are often the same mistake.`,
+    unavailableHeading: () => 'What this cannot answer, and what would unlock it',
+    unavailable: (finding, because, unlockedBy) => `${finding} — ${because}. Add ${unlockedBy}.`,
+    unavailableNeverGates: () =>
+      'None of those failed anything. Choosing not to record a field is a decision, not a defect, and a gate that failed on it would be this tool telling you what to log.',
+  },
+
   where: {
     hostHeading: () => 'Running inside',
     subscription: (host) =>

package/src/i18n/es.ts

@@ -41,6 +41,7 @@ ${bold('USO')}
   trazum blame <fichero> [opciones]
   trazum prune <fichero> --cases <fichero> --yes
   trazum where [fichero]
+  trazum conform <fichero|-> [--contract <nombre>]
   trazum models
   trazum rules
 
@@ -60,6 +61,20 @@ ${bold('OPCIONES DE init')}
   cifra medida y te deja el límite a ti — una configuración generada llena de
   números adivinados no se la cree nadie.
 
+${bold('OPCIONES DE conform')}
+  --contract <nombre>         Comprueba contra un contrato concreto en vez de
+                              detectarlo: usage-log, profile, plan,
+                              verification, history, connected, cost-answer.
+  --json                      El informe como datos.
+
+  Responde dos preguntas y las mantiene separadas. ¿Cumple este documento —
+  campos obligatorios, presentes y del tipo correcto; sale con 1 si no. Y qué no
+  puede responder un documento válido de esta forma, con el campo que lo
+  desbloquearía.
+
+  La segunda nunca hace fallar nada. Decidir no registrar sesiones es una
+  decisión, no un defecto. Ver docs/format.md.
+
 ${bold('OPCIONES DE prune')}
   --cases <fichero>           Una entrada por línea, o un array JSON. Obligatorio.
   --yes                       Gasta las llamadas de verdad. Sin él se imprime la
@@ -937,6 +952,23 @@ ${bold('EJEMPLOS')}
       `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
   },
 
+  conform: {
+    noTarget: () =>
+      'Pasa un archivo para comprobar — un registro de consumo, o cualquier documento que emita Trazum. Usa "-" para leer de la entrada estándar.',
+    badContract: (given, known) => `"${given}" no es un contrato. Contratos conocidos: ${known}.`,
+    unrecognised: (path) => `${path} no encaja con ningún contrato que Trazum conozca.`,
+    heading: (path, contract) => `${path} se lee como un documento ${contract}`,
+    headingLog: (path, contract, records) =>
+      `${path} se lee como ${contract}: ${records} ${records === 1 ? 'registro' : 'registros'}`,
+    conforms: () => 'Cumple. Todos los campos obligatorios están y son del tipo correcto.',
+    problem: (at, kind, detail) => `${at}: ${detail} (${kind})`,
+    moreProblems: (count) => `…y ${count} más. Arregla estos primero; suelen ser el mismo error.`,
+    unavailableHeading: () => 'Lo que esto no puede responder, y qué lo desbloquearía',
+    unavailable: (finding, because, unlockedBy) => `${finding} — ${because}. Añade ${unlockedBy}.`,
+    unavailableNeverGates: () =>
+      'Nada de eso ha hecho fallar nada. Decidir no registrar un campo es una decisión, no un defecto, y una puerta que fallara por ello sería esta herramienta diciéndote qué registrar.',
+  },
+
   where: {
     hostHeading: () => 'Ejecutándose dentro de',
     subscription: (host) =>

package/src/i18n/types.ts

@@ -246,6 +246,26 @@ export interface CliMessages {
     existingUnparseable(path: string): string;
   };
 
+  /**
+   * The conformance check.
+   *
+   * Two halves, and the copy keeps them apart everywhere: problems gate, gaps
+   * do not. Choosing not to log sessions is a decision, not a defect.
+   */
+  conform: {
+    noTarget(): string;
+    badContract(given: string, known: string): string;
+    unrecognised(path: string): string;
+    heading(path: string, contract: string): string;
+    headingLog(path: string, contract: string, records: number): string;
+    conforms(): string;
+    problem(at: string, kind: string, detail: string): string;
+    moreProblems(count: number): string;
+    unavailableHeading(): string;
+    unavailable(finding: string, because: string, unlockedBy: string): string;
+    unavailableNeverGates(): string;
+  };
+
   where: {
     hostHeading(): string;
     subscription(host: string): string;

package/src/index.ts

@@ -36,6 +36,7 @@ import {
   countTokensAnthropic,
   DEFAULT_USAGE,
   budgetPositions,
+  conform,
   detectFromSource,
   matchLocale,
   parsePlanDocument,
@@ -129,6 +130,7 @@ import type {
 } from '@trazum/core';
 import type {
   BudgetReport,
+  ContractName,
   UsageProfileReport,
   WaiverUse,
   InitDecline,
@@ -228,6 +230,7 @@ interface Args {
 
 const VALUE_FLAGS = new Set([
   'against',
+  'contract',
   'from-log',
   'min-usd',
   'payload',
@@ -550,6 +553,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   models: [],
   rank: ['level', 'model', 'calls', 'output-tokens', 'batch', 'disable', 'prompt', 'markdown-out'],
   init: ['dry-run', 'yes', 'json', 'pricing', 'pricing-live'],
+  conform: ['contract', 'json'],
   where: [],
   rules: [],
   blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -1472,6 +1476,20 @@ const INIT_LOG_CANDIDATES = [
  * nobody has vouched for.
  */
 
+/** Problems listed before the rest are counted. A wall of them helps nobody. */
+const MAX_CONFORM_PROBLEMS = 20;
+
+/** The contracts `--contract` accepts, so a typo is refused with the list. */
+const CONTRACT_NAMES = [
+  'usage-log',
+  'profile',
+  'plan',
+  'verification',
+  'history',
+  'connected',
+  'cost-answer',
+];
+
 /** How many source files, and how large each may be. Both reported when they bite. */
 const INIT_MAX_SOURCE_FILES = 400;
 const INIT_MAX_SOURCE_BYTES = 256 * 1024;
@@ -1850,6 +1868,87 @@ async function commandInit(
   console.log();
 }
 
+/**
+ * `trazum conform <file>` — does this document conform, and what will it not
+ * be able to answer?
+ *
+ * The command that makes the five contracts something to build against rather
+ * than something to read about. An emitter — a logging wrapper somebody wrote
+ * this afternoon, a connector for a provider this repository has never heard
+ * of, a dashboard writing profile documents of its own — points this at what
+ * it produced and finds out before shipping.
+ *
+ * **The second half is the useful half.** "Valid" is a yes or no. "Here is
+ * what a valid document of this shape cannot tell you, and the field that
+ * would unlock each" is the answer somebody acts on: a usage log with no
+ * `session` is perfectly conformant and simply has no conversation growth in
+ * it, and an emitter that only ever hears "valid" ships it and never finds out
+ * why half the report is empty.
+ *
+ * Exits 1 on a problem, so it gates. It never exits 1 on an *unavailable
+ * finding*: choosing not to log sessions is a decision, not a defect, and a
+ * gate that failed on it would be this tool telling somebody what to record.
+ */
+async function commandConform(args: Args, t: CliMessages): Promise<void> {
+  const target = args.positional[0];
+  if (target === undefined) throw new Error(t.conform.noTarget());
+
+  const named = stringFlag(args, 'contract');
+  if (named !== undefined && !CONTRACT_NAMES.includes(named)) {
+    throw new Error(t.conform.badContract(named, CONTRACT_NAMES.join(', ')));
+  }
+
+  const text = target === '-' ? await readInput('-', t) : await readUsageLog(target, t);
+  const report = conform(text, named === undefined ? {} : { contract: named as ContractName });
+
+  if (boolFlag(args, 'json')) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.conforms) process.exitCode = 1;
+    return;
+  }
+
+  console.log();
+  if (report.contract === null) {
+    console.log(c.red(t.conform.unrecognised(target)));
+    console.log(`  ${c.dim(wrap(report.because ?? '', 74, '    '))}`);
+    console.log();
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(
+    c.bold(
+      report.records === null
+        ? t.conform.heading(target, report.contract)
+        : t.conform.headingLog(target, report.contract, report.records),
+    ),
+  );
+
+  if (report.problems.length === 0) {
+    console.log(`  ${c.green(t.conform.conforms())}`);
+  } else {
+    for (const problem of report.problems.slice(0, MAX_CONFORM_PROBLEMS)) {
+      console.log(`  ${c.red(t.conform.problem(problem.at, problem.kind, problem.detail))}`);
+    }
+    if (report.problems.length > MAX_CONFORM_PROBLEMS) {
+      console.log(`  ${c.dim(t.conform.moreProblems(report.problems.length - MAX_CONFORM_PROBLEMS))}`);
+    }
+    process.exitCode = 1;
+  }
+
+  if (report.unavailable.length > 0) {
+    console.log();
+    console.log(c.bold(t.conform.unavailableHeading()));
+    for (const gap of report.unavailable) {
+      console.log(`  ${c.dim(wrap(t.conform.unavailable(gap.finding, gap.because, gap.unlockedBy), 74, '    '))}`);
+    }
+    // Said out loud, because the exit code says it silently and somebody
+    // reading a red-and-yellow screen will assume both halves gated.
+    console.log(`  ${c.dim(wrap(t.conform.unavailableNeverGates(), 74, '    '))}`);
+  }
+  console.log();
+}
+
 function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const col = t.models.columns;
@@ -7843,6 +7942,9 @@ async function main(): Promise<void> {
     case 'models':
       commandModels(t, pricing);
       break;
+    case 'conform':
+      await commandConform(args, t);
+      break;
     case 'init':
       await commandInit(args, config, pricing, t);
       break;