@trazum/cli 1.45.0 → 1.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.45.0",
+  "version": "1.47.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.45.0"
+    "@trazum/core": "1.47.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -33,6 +33,7 @@ export const en: CliMessages = {
   help: (d, bold) => `${bold('trazum')} — cut the cost of your prompts without losing what they ask for.
 
 ${bold('USAGE')}
+  trazum init [dir] [--dry-run | --yes]
   trazum optimize <file|-> [options]
   trazum check <file|dir|-> --max-tokens <n> [options]
   trazum baseline [dir] [options]
@@ -56,6 +57,22 @@ ${bold('USAGE')}
   trazum models
   trazum rules
 
+${bold('OPTIONS FOR init')}
+  --dry-run                   Print the config it would write and write nothing.
+  --yes                       Replace a trazum.config.json that is already there.
+                              Without it an existing config is left alone.
+  --json                      The proposal as data, including every key it
+                              declined and why. Writes nothing.
+
+  The first five minutes: finds your prompts, reads your code for which provider
+  it calls, finds a usage log or a credential for one, and writes a config out of
+  what it can actually justify. Then it prints the single most valuable thing it
+  found, arithmetic first.
+
+  It never invents a threshold. A budget is a policy, so init hands you the
+  measured figure and leaves the limit to you — a generated config full of
+  guessed numbers is one nobody trusts.
+
 ${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
@@ -809,6 +826,84 @@ ${bold('EXAMPLES')}
     wroteTo: (path) => `Optimised prompt written to ${path}`,
   },
 
+  init: {
+    heading: () => 'What is here',
+    host: (name) => `Running inside ${name}.`,
+    prompts: (count) =>
+      `${count} prompt ${count === 1 ? 'file' : 'files'} found.`,
+    noPrompts: () =>
+      'No prompt files found. Directory mode reads .txt, .md, .prompt and .tmpl by default — set "extensions" if yours are named otherwise.',
+    sourcesTruncated: (cap) =>
+      `Stopped after ${cap} source files, so a provider named further down was not seen.`,
+    usageFound: (kind, where) =>
+      kind === 'connector-credential'
+        ? `Usage can be pulled: a credential is in ${where}. Run trazum connect.`
+        : kind === 'store'
+          ? `A local store of past measurements is in ${where}.`
+          : `Usage log found: ${where}.`,
+    noUsage: () =>
+      'No usage found. Point trazum at a log (trazum profile <log.jsonl>) or pull one (trazum connect anthropic) — every money figure in this tool comes from one.',
+    usageUnreadable: (where, because) =>
+      `${where} is there and could not be read: ${because}. That is a different problem from having no usage, and it is the one to fix first.`,
+
+    configHeading: () => 'What the config would say',
+    nothingJustified: () =>
+      'Nothing. Every key below needs evidence this run did not find, and a guessed config is worse than none.',
+    whyLocale: (locale) => `your environment asks for ${locale}`,
+    whyExtensions: (extensions, files) => `${files} prompt files use ${extensions}`,
+    whyModelMeasured: (model, sharePct) => `${sharePct}% of the measured bill went to ${model}`,
+    whyModelSource: (model, file, line) => `${file}:${line} names ${model}`,
+    whyCalls: (perMonth, calls, days) =>
+      `${calls} calls over ${days} days, stated as ${perMonth} a month`,
+    whyOutput: (average, outputTokens, calls) =>
+      `${outputTokens} output tokens over ${calls} calls averages ${average}`,
+    whyCache: (rate, cacheReadTokens, inputTokens) =>
+      `${cacheReadTokens} cached against ${inputTokens} fresh input is a hit rate of ${rate}`,
+
+    noModelEvidence: () => 'nothing measured or written in the source names one model',
+    modelConflict: (files) => `these files name more than one provider: ${files}`,
+    modelProviderOnly: (provider, file) =>
+      `${file} names ${provider} and no model — a provider default would read as your decision six weeks from now`,
+    nothingMeasured: () => 'nothing has been measured yet',
+    windowTooShort: (days, minimum) =>
+      `${days} days measured; ${minimum} are needed before that is a monthly rate rather than a forecast`,
+    undatedCalls: (undated, calls) =>
+      `${undated} of ${calls} calls carry no timestamp, so they cannot be placed inside the window a rate would divide by`,
+    cacheNotRecorded: () =>
+      'this log has no cache columns at all, which is not the same as a hit rate of zero',
+    batchOnlyYouKnow: () =>
+      'whether the work can wait for a batch window is a product decision, and no log records it',
+    labelsUnprovable: (labels) =>
+      `${labels} ${labels === 1 ? 'label' : 'labels'} in the log, and nothing here proves which prompt file sends which`,
+    budgetIsPolicy: () => 'a budget is a policy, and there is no measured figure to write one against yet',
+    budgetIsPolicyMeasured: (usd, days) =>
+      `a budget is a policy, so it is yours to set — the measured figure is $${usd} over ${days} days`,
+
+    findingHeading: () => 'The most valuable thing found',
+    noFinding: (why) =>
+      why === 'nothing-measured'
+        ? 'Nothing, because nothing has been measured. Every figure this tool prints as money comes from a usage log.'
+        : why === 'nothing-could-be-priced'
+          ? 'Nothing: the log was read, and no model in it is in the price catalogue. Run trazum models to see what is priced.'
+          : 'Nothing worth a line: no single slice of this bill can be moved by more than one per cent of it.',
+    findingCalls: (calls, label, model, days) =>
+      `${calls} calls labelled "${label}" went to ${model} over ${days} days.`,
+    findingSpent: (usd) => `They cost $${usd}.`,
+    findingRoute: (model) => `The same work fits ${model}, which is cheaper per token.`,
+    findingBatch: () => 'The Batch API halves both halves of the bill, for work that can wait.',
+    findingTotal: (usd, days) => `Together: $${usd} over the same ${days} days.`,
+    findingNext: () => 'trazum plan <your log> ranks every action, not just this one.',
+
+    wouldOverwrite: (keys) => `This replaces keys you already set: ${keys}. Pass --yes to write anyway.`,
+    nothingToWrite: () => 'No config written: nothing above could be justified from what is here.',
+    wouldWrite: (path) => `Would write ${path}:`,
+    wrote: (path) => `Written to ${path}.`,
+    existingRefused: (path) =>
+      `${path} already exists and was left alone. Pass --dry-run to see what would go in it, or --yes to replace it.`,
+    existingUnparseable: (path) =>
+      `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
+  },
+
   where: {
     hostHeading: () => 'Running inside',
     subscription: (host) =>
@@ -1719,8 +1814,18 @@ ${bold('EXAMPLES')}
       'Point this at a saved plan and a newer log: trazum verify plan.json --against usage.jsonl. It says, per action, whether the change arrived, did not arrive, or cannot be told — and never fewer than those three.',
     needsAgainst: () =>
       '--against <newer.jsonl|dir> is required. A plan can only be verified against a log that came after it; without one there is nothing to hold the prediction to.',
-    badPlan: (path) =>
-      `${path} is not a plan document this tool can verify — expected the JSON that "trazum plan -o" writes (schemaVersion 1, with an actions array).`,
+    badPlan: (path, why) =>
+      `${path} is not a plan document this tool can verify: ${why}. Expected the JSON that "trazum plan -o" writes.`,
+    planRefusal: (why) =>
+      why.kind === 'not-json'
+        ? 'it is not valid JSON'
+        : why.kind === 'not-an-object'
+          ? 'the top level is not a JSON object'
+          : why.kind === 'wrong-schema-version'
+            ? `schemaVersion is ${JSON.stringify(why.found)} rather than 1`
+            : why.kind === 'actions-not-a-list'
+              ? 'there is no actions array'
+              : `action ${why.index + 1} is malformed (${why.because})`,
     heading: (actions, planDate) =>
       planDate === null
         ? `Did it work? ${actions} actions from an undated plan, against this log`

package/src/i18n/es.ts

@@ -20,6 +20,7 @@ export const es: CliMessages = {
   help: (d, bold) => `${bold('trazum')} — reduce el coste de tus prompts sin perder lo que piden.
 
 ${bold('USO')}
+  trazum init [dir] [--dry-run | --yes]
   trazum optimize <fichero|-> [opciones]
   trazum check <fichero|dir|-> --max-tokens <n> [opciones]
   trazum baseline [dir] [opciones]
@@ -43,6 +44,22 @@ ${bold('USO')}
   trazum models
   trazum rules
 
+${bold('OPCIONES DE init')}
+  --dry-run                   Imprime la configuración que escribiría y no escribe nada.
+  --yes                       Reemplaza un trazum.config.json que ya exista. Sin
+                              esto, una configuración existente se deja intacta.
+  --json                      La propuesta como datos, incluida cada clave que
+                              descartó y por qué. No escribe nada.
+
+  Los primeros cinco minutos: encuentra tus prompts, lee tu código para saber a
+  qué proveedor llama, busca un registro de consumo o una credencial para uno, y
+  escribe una configuración con lo que puede justificar de verdad. Después imprime
+  lo más valioso que encontró, con la aritmética delante.
+
+  Nunca se inventa un umbral. Un presupuesto es una política, así que init te da la
+  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 prune')}
   --cases <fichero>           Una entrada por línea, o un array JSON. Obligatorio.
   --yes                       Gasta las llamadas de verdad. Sin él se imprime la
@@ -842,6 +859,84 @@ ${bold('EJEMPLOS')}
     wroteTo: (path) => `Prompt optimizado escrito en ${path}`,
   },
 
+  init: {
+    heading: () => 'Lo que hay aquí',
+    host: (name) => `Ejecutándose dentro de ${name}.`,
+    prompts: (count) =>
+      `${count} ${count === 1 ? 'archivo de prompt encontrado' : 'archivos de prompt encontrados'}.`,
+    noPrompts: () =>
+      'No se encontraron prompts. El modo directorio lee .txt, .md, .prompt y .tmpl por defecto — define "extensions" si los tuyos se llaman de otra forma.',
+    sourcesTruncated: (cap) =>
+      `Se paró tras ${cap} archivos de código, así que un proveedor nombrado más abajo no se vio.`,
+    usageFound: (kind, where) =>
+      kind === 'connector-credential'
+        ? `El consumo se puede descargar: hay una credencial en ${where}. Ejecuta trazum connect.`
+        : kind === 'store'
+          ? `Hay un almacén local de mediciones pasadas en ${where}.`
+          : `Registro de consumo encontrado: ${where}.`,
+    noUsage: () =>
+      'No se encontró consumo. Apunta trazum a un registro (trazum profile <log.jsonl>) o descárgalo (trazum connect anthropic) — toda cifra en dinero de esta herramienta sale de uno.',
+    usageUnreadable: (where, because) =>
+      `${where} está ahí y no se pudo leer: ${because}. Ese es un problema distinto de no tener consumo, y es el primero que hay que arreglar.`,
+
+    configHeading: () => 'Lo que diría la configuración',
+    nothingJustified: () =>
+      'Nada. Cada clave de abajo necesita pruebas que esta ejecución no encontró, y una configuración adivinada es peor que ninguna.',
+    whyLocale: (locale) => `tu entorno pide ${locale}`,
+    whyExtensions: (extensions, files) => `${files} prompts usan ${extensions}`,
+    whyModelMeasured: (model, sharePct) => `el ${sharePct}% de la factura medida fue a ${model}`,
+    whyModelSource: (model, file, line) => `${file}:${line} nombra ${model}`,
+    whyCalls: (perMonth, calls, days) =>
+      `${calls} llamadas en ${days} días, expresadas como ${perMonth} al mes`,
+    whyOutput: (average, outputTokens, calls) =>
+      `${outputTokens} tokens de salida en ${calls} llamadas dan una media de ${average}`,
+    whyCache: (rate, cacheReadTokens, inputTokens) =>
+      `${cacheReadTokens} en caché frente a ${inputTokens} de entrada nueva dan una tasa de ${rate}`,
+
+    noModelEvidence: () => 'nada medido ni escrito en el código nombra un único modelo',
+    modelConflict: (files) => `estos archivos nombran más de un proveedor: ${files}`,
+    modelProviderOnly: (provider, file) =>
+      `${file} nombra ${provider} y ningún modelo — el modelo por defecto del proveedor se leería como decisión tuya dentro de seis semanas`,
+    nothingMeasured: () => 'todavía no se ha medido nada',
+    windowTooShort: (days, minimum) =>
+      `${days} días medidos; hacen falta ${minimum} antes de que eso sea un ritmo mensual y no un pronóstico`,
+    undatedCalls: (undated, calls) =>
+      `${undated} de ${calls} llamadas no llevan fecha, así que no se pueden situar dentro de la ventana por la que dividiría un ritmo`,
+    cacheNotRecorded: () =>
+      'este registro no tiene columnas de caché en absoluto, que no es lo mismo que una tasa de cero',
+    batchOnlyYouKnow: () =>
+      'si el trabajo puede esperar a una ventana de lote es una decisión de producto, y ningún registro la anota',
+    labelsUnprovable: (labels) =>
+      `${labels} ${labels === 1 ? 'etiqueta' : 'etiquetas'} en el registro, y nada aquí demuestra qué prompt envía cuál`,
+    budgetIsPolicy: () => 'un presupuesto es una política, y todavía no hay cifra medida contra la que escribir una',
+    budgetIsPolicyMeasured: (usd, days) =>
+      `un presupuesto es una política, así que es tuyo — la cifra medida es $${usd} en ${days} días`,
+
+    findingHeading: () => 'Lo más valioso encontrado',
+    noFinding: (why) =>
+      why === 'nothing-measured'
+        ? 'Nada, porque no se ha medido nada. Toda cifra que esta herramienta imprime como dinero sale de un registro de consumo.'
+        : why === 'nothing-could-be-priced'
+          ? 'Nada: el registro se leyó y ningún modelo suyo está en el catálogo de precios. Ejecuta trazum models para ver cuáles lo están.'
+          : 'Nada que merezca una línea: ninguna porción de esta factura se puede mover más de un uno por ciento del total.',
+    findingCalls: (calls, label, model, days) =>
+      `${calls} llamadas con la etiqueta "${label}" fueron a ${model} en ${days} días.`,
+    findingSpent: (usd) => `Costaron $${usd}.`,
+    findingRoute: (model) => `El mismo trabajo cabe en ${model}, más barato por token.`,
+    findingBatch: () => 'La API de lotes reduce a la mitad ambas mitades de la factura, para trabajo que puede esperar.',
+    findingTotal: (usd, days) => `Juntas: $${usd} en esos mismos ${days} días.`,
+    findingNext: () => 'trazum plan <tu registro> ordena todas las acciones, no solo esta.',
+
+    wouldOverwrite: (keys) => `Esto reemplaza claves que ya tenías: ${keys}. Pasa --yes para escribir igualmente.`,
+    nothingToWrite: () => 'No se escribió configuración: nada de lo anterior se pudo justificar con lo que hay aquí.',
+    wouldWrite: (path) => `Escribiría ${path}:`,
+    wrote: (path) => `Escrito en ${path}.`,
+    existingRefused: (path) =>
+      `${path} ya existe y se dejó intacto. Pasa --dry-run para ver qué iría dentro, o --yes para reemplazarlo.`,
+    existingUnparseable: (path) =>
+      `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
+  },
+
   where: {
     hostHeading: () => 'Ejecutándose dentro de',
     subscription: (host) =>
@@ -1749,8 +1844,18 @@ ${bold('EJEMPLOS')}
       'Apunta esto a un plan guardado y a un registro posterior: trazum verify plan.json --against usage.jsonl. Dice, por acción, si el cambio llegó, no llegó o no se puede saber — y nunca menos de esos tres.',
     needsAgainst: () =>
       '--against <nuevo.jsonl|dir> es obligatorio. Un plan solo puede verificarse contra un registro posterior; sin uno no hay nada a lo que someter la predicción.',
-    badPlan: (path) =>
-      `${path} no es un documento de plan que esta herramienta pueda verificar — se esperaba el JSON que escribe "trazum plan -o" (schemaVersion 1, con un array actions).`,
+    badPlan: (path, why) =>
+      `${path} no es un documento de plan que esta herramienta pueda verificar: ${why}. Se esperaba el JSON que escribe "trazum plan -o".`,
+    planRefusal: (why) =>
+      why.kind === 'not-json'
+        ? 'no es JSON válido'
+        : why.kind === 'not-an-object'
+          ? 'el nivel superior no es un objeto JSON'
+          : why.kind === 'wrong-schema-version'
+            ? `schemaVersion es ${JSON.stringify(why.found)} en vez de 1`
+            : why.kind === 'actions-not-a-list'
+              ? 'no hay un array actions'
+              : `la acción ${why.index + 1} está mal formada (${why.because})`,
     heading: (actions, planDate) =>
       planDate === null
         ? `¿Funcionó? ${actions} acciones de un plan sin fecha, contra este registro`

package/src/i18n/types.ts

@@ -189,6 +189,63 @@ export interface CliMessages {
     wroteTo(path: string): string;
   };
 
+  /**
+   * The first run.
+   *
+   * Every string here is either something that was *found* or something that
+   * was *declined with what would settle it*. There is deliberately no
+   * congratulation copy and no next-steps list: a first run that celebrates
+   * itself before showing a number is the shape people have learned to skip.
+   */
+  init: {
+    heading(): string;
+    host(name: string): string;
+    prompts(count: number): string;
+    noPrompts(): string;
+    sourcesTruncated(cap: number): string;
+    usageFound(kind: string, where: string): string;
+    noUsage(): string;
+    usageUnreadable(where: string, because: string): string;
+
+    configHeading(): string;
+    nothingJustified(): string;
+    whyLocale(locale: string): string;
+    whyExtensions(extensions: string, files: number): string;
+    whyModelMeasured(model: string, sharePct: number): string;
+    whyModelSource(model: string, file: string, line: number): string;
+    whyCalls(perMonth: number, calls: number, days: number): string;
+    whyOutput(average: number, outputTokens: number, calls: number): string;
+    whyCache(rate: number, cacheReadTokens: number, inputTokens: number): string;
+
+    noModelEvidence(): string;
+    modelConflict(files: string): string;
+    modelProviderOnly(provider: string, file: string): string;
+    nothingMeasured(): string;
+    windowTooShort(days: number, minimum: number): string;
+    undatedCalls(undated: number, calls: number): string;
+    cacheNotRecorded(): string;
+    batchOnlyYouKnow(): string;
+    labelsUnprovable(labels: number): string;
+    budgetIsPolicy(): string;
+    budgetIsPolicyMeasured(usd: string, days: number): string;
+
+    findingHeading(): string;
+    noFinding(why: string): string;
+    findingCalls(calls: string, label: string, model: string, days: number): string;
+    findingSpent(usd: string): string;
+    findingRoute(model: string): string;
+    findingBatch(): string;
+    findingTotal(usd: string, days: number): string;
+    findingNext(): string;
+
+    wouldOverwrite(keys: string): string;
+    nothingToWrite(): string;
+    wouldWrite(path: string): string;
+    wrote(path: string): string;
+    existingRefused(path: string): string;
+    existingUnparseable(path: string): string;
+  };
+
   where: {
     hostHeading(): string;
     subscription(host: string): string;
@@ -1212,7 +1269,22 @@ export interface CliMessages {
     noTarget(): string;
     needsAgainst(): string;
     /** Not a plan document: wrong shape, wrong version, or not JSON at all. */
-    badPlan(path: string): string;
+    /**
+     * `why` is the typed reason from `parsePlanDocument`, rendered so the
+     * refusal names what is wrong rather than only that something is. A file
+     * that is valid JSON and not a plan and a plan with one bad action are
+     * different problems with different fixes.
+     */
+    badPlan(path: string, why: string): string;
+    /** The typed refusal from `parsePlanDocument`, in one clause. */
+    planRefusal(
+      why:
+        | { kind: 'not-json' }
+        | { kind: 'not-an-object' }
+        | { kind: 'wrong-schema-version'; found: unknown }
+        | { kind: 'actions-not-a-list' }
+        | { kind: 'action-malformed'; index: number; because: string },
+    ): string;
     heading(actions: string, planDate: string | null): string;
     counts(arrived: string, notArrived: string, cannotTell: string): string;
     /** Two price lists are two measurements; every dollar line inherits this. */