@trazum/cli 1.41.0 → 1.43.0

package/src/i18n/es.ts

@@ -30,6 +30,8 @@ ${bold('USO')}
   trazum verify <plan.json> --against <nuevo.jsonl|dir> [opciones]
   trazum history <dir-de-informes-guardados> [opciones]
   trazum connect <anthropic|openai> [opciones]
+  trazum store [--prune] [opciones]
+  trazum watch [--once | --interval 15m] [opciones]
   trazum diff <antes> <después> [opciones]
   trazum diff --all <dir> <dir> [opciones]
   trazum rank <dir> [opciones]
@@ -327,6 +329,57 @@ ${bold('OPCIONES DE plan')}
   consejo haciéndose pasar por aritmética. El ahorro proyectado y el dinero ya
   gastado son totales separados en todas partes.
 
+${bold('OPCIONES DE watch')}
+  --once                      Una vuelta: medir, guardar, evaluar, emitir,
+                              recordar. Lo que ejecuta una entrada de cron. Es
+                              lo que se hace por defecto.
+  --interval <n>m|h           Se queda en primer plano y repite. Mínimo cinco
+                              minutos: las APIs de uso están limitadas por
+                              tasa, y un bucle apretado es una forma de que te
+                              estrangulen tu propia clave.
+  --webhook <url>             Envía los cruces por POST. Solo https, salvo en
+                              loopback; una URL con credenciales se rechaza,
+                              porque las URLs acaban en logs e historiales.
+  --payload <fichero>         Evalúa un payload de uso que ya tengas, en vez
+                              del almacén.
+  --json                      La vuelta como datos: cruces, abstenciones, hueco.
+
+  Evalúa los gates de gasto de tu configuración — maxUsd, maxDayUsd,
+  maxCacheLossUsd — contra lo que se ha medido, y te lo dice la tarde en que
+  pasa en vez de tres semanas después. Sale con 1 cuando algo cruzó, así que
+  cron te lo manda y CI falla.
+
+  Una alerta salta por un cruce medido y nunca por una proyección: "has
+  gastado $412 de un presupuesto de $400" es un hecho y "vas a excederte" es un
+  pronóstico, que esta herramienta no hace a ninguna escala de ventana. Un día
+  que todavía se está midiendo se reporta como aún no juzgable en vez de
+  aprobarse — pero un día que ya se pasó del presupuesto salta a cualquier
+  hora, porque no se pasa menos a medianoche.
+
+  Un reinicio no vuelve a avisar de un cruce ya reportado, y nombra el tramo
+  que no estuvo vigilando, porque un vigilante que se reanuda en silencio
+  insinúa una cobertura que no tuvo.
+
+${bold('OPCIONES DE store')}
+  --prune                     Borra las mediciones más antiguas que la política
+                              de retención y compacta el log a lo que el
+                              almacén ya resuelve. Dice qué se fue.
+  --keep <n>d                 Retención para esta ejecución, si la config no
+                              tiene ninguna.
+  --dry-run                   Con --prune: dice qué se iría y no borra nada.
+  --json                      El inventario como datos.
+
+  Dice qué guarda el almacén local: cuántas mediciones, sobre qué período, por
+  proveedor, y qué se llevaría una poda. El almacén guarda agregados y campos
+  de facturación — nunca texto de prompt, nunca texto de respuesta, nunca una
+  credencial — así que es un fichero que un equipo puede respaldar sin una
+  revisión de privacidad.
+
+  La poda es la única operación de aquí que destruye algo, así que se niega a
+  correr sin política de retención: pon "store": {"keepDays": 90} en la config
+  o pasa --keep. Borrar mediciones con una política que nadie escribió no es un
+  valor por defecto que nadie deba recibir por accidente.
+
 ${bold('OPCIONES DE connect')}
   --since <cuándo>            La ventana que se descarga. Un día UTC, una marca
   --until <cuándo>            ISO, una ventana relativa (7d, 24h) o "now". Por
@@ -337,6 +390,9 @@ ${bold('OPCIONES DE connect')}
   --payload <fichero>         Tasa un payload de uso que ya tengas, en vez de
                               descargar uno. Sin credencial y sin red — la misma
                               aritmética sobre la misma forma.
+  --store                     Guarda lo descargado en el almacén local, para que
+                              la próxima vez no haya que bajarlo otra vez y
+                              "trazum history --store" tenga una serie.
   -o, --out <fichero>         Guarda el informe tasado como JSON.
   --markdown-out <fichero>    Lo escribe además como Markdown, para CI.
   --json                      El informe como datos.
@@ -358,6 +414,12 @@ ${bold('OPCIONES DE connect')}
   que describe en silencio menos tráfico del que pediste.
 
 ${bold('OPCIONES DE history')}
+  --store                     Construye la serie desde el almacén local en vez
+                              de un directorio de informes guardados. Las
+                              fuentes agregadas no llevan label, así que la
+                              serie por label está ausente y se dice — las de
+                              cuota de modelo y de caché son para lo que existe
+                              una serie, y funcionan enteras.
   --markdown-out <fichero>    Escribe además la serie como Markdown, para un
                               resumen de CI o un comentario de pull request.
   --json                      La historia como datos.
@@ -1501,6 +1563,80 @@ ${bold('EJEMPLOS')}
       `Plan escrito en ${path}, con fecha. Guárdalo: una predicción que nadie apuntó es una predicción que no se le puede exigir a nadie.`,
   },
 
+  watch: {
+    noThresholds: () =>
+      'Vigilar necesita algo que vigilar. Define spend.maxUsd, spend.maxDayUsd o spend.maxCacheLossUsd en trazum.config.json — un vigilante sin umbral es una luz verde que nadie se ha ganado.',
+    nothingToWatch: (dir) =>
+      `Todavía no se ha medido nada: el almacén de ${dir} está vacío. Llénalo primero con "trazum connect <proveedor> --store" — vigilar la nada reportaría que todo está bien.`,
+    intervalTooTight: () =>
+      '--interval tiene que ser de al menos 5m. Las APIs de uso están limitadas por tasa, y un bucle apretado es una forma de que una herramienta que existe para ahorrarte dinero acabe estrangulando tu propia clave.',
+    badWebhook: (reason) =>
+      reason === 'credentials-in-url'
+        ? 'Esa URL de webhook lleva credenciales. Las URLs acaban en logs, historiales de shell y mensajes de error, así que se rechaza — pon el secreto en una cabecera que tu receptor compruebe, o en el propio receptor.'
+        : reason === 'insecure-scheme'
+          ? 'Un webhook tiene que ser https, salvo en loopback. Una alerta lleva tus cifras de gasto, y mandarlas en claro por una red es una fuga que no pediste.'
+          : 'Ese webhook no es una URL que esta herramienta pueda parsear.',
+    crossed: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'El gasto total'
+          : gate === 'maxDayUsd'
+            ? `El gasto del ${day}`
+            : 'El dinero perdido con la caché';
+      return `CRUZADO — ${what} es ${measured} contra un límite de ${limit}. Medido, no proyectado.`;
+    },
+    stillOver: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'El gasto total'
+          : gate === 'maxDayUsd'
+            ? `El gasto del ${day}`
+            : 'El dinero perdido con la caché';
+      return `SIGUE POR ENCIMA — ${what} es ${measured} contra un límite de ${limit}, y ya se avisó. Callado no es limpio.`;
+    },
+    notJudgeable: (gate, reason, covered) =>
+      reason === 'window-too-short'
+        ? `${gate} todavía no se puede juzgar: este período está medido al ${covered ?? 'parcialmente'}, y un umbral sobre parte de un día es un umbral sobre otra cosa. No es un aprobado — se juzgará cuando el día esté completo.`
+        : `${gate} no se puede juzgar en esta fuente, que no sirve aquello sobre lo que está escrito el gate. No es un aprobado: un gate saltado en silencio se lee exactamente igual que un gate que lleva tiempo pasando.`,
+    gap: (from, to) =>
+      `Nada estuvo vigilando entre ${from} y ${to}. Lo que cruzara en ese tramo no se vio, y esta línea existe para que un vigilante reanudado no insinúe una cobertura que no tuvo.`,
+    allWithin: (gates) => `Dentro de todos los umbrales: ${gates} gates evaluados contra gasto medido.`,
+    webhookFailed: (status) =>
+      `El webhook no se entregó (${status}). El cruce sigue en el código de salida y en la salida de arriba — que un receptor esté caído no puede ser el fallo más silencioso de la sala.`,
+    watching: (minutes) => `Vigilando cada ${minutes} minutos. Ctrl-C lo para.`,
+  },
+
+  store: {
+    appended: (count, dir) => `Guardadas ${count} mediciones en ${dir}.`,
+    empty: (dir) =>
+      `El almacén de ${dir} está vacío. Llénalo con "trazum connect <proveedor> --store" — eso es un estado, no un error.`,
+    heading: (records, usd, from, to) =>
+      `El almacén: ${records} mediciones · ${usd} · ${from} → ${to}`,
+    providerRow: (provider, records, span, models) =>
+      `${provider}  ${records} mediciones · ${span} · ${models} modelos`,
+    holds: (files) =>
+      `Guardado en ${files} ficheros: recuentos de tokens, dólares facturados y los identificadores de workspace y clave de la propia cuenta. Nunca texto de prompt, nunca texto de respuesta, nunca una credencial — esto es un fichero que puedes respaldar sin una revisión de privacidad.`,
+    possiblyDouble: (count) =>
+      `${count} registros no se pudieron distinguir de otro — una ventana de longitud cero, o un registro que no nombra modelo. Se guardan enteros en vez de fundirse, así que un total construido sobre ellos puede contar el mismo gasto dos veces. Decirlo es mejor que un número más pequeño que nadie puede comprobar.`,
+    unknownVersion: (count) =>
+      `${count} registros vienen de un esquema más nuevo del que esta versión conoce, así que se conservan y quedan fuera de las cifras de arriba en vez de adivinarse. Actualiza para leerlos.`,
+    unreadable: (file, line) =>
+      `${file} línea ${line} no se pudo parsear, así que no está en las cifras de arriba. El resto del fichero sí se leyó — una línea rota no puede costar un mes.`,
+    retention: (days) => `Retención: ${days} días, de "store.keepDays". Ejecuta "trazum store --prune" para aplicarla.`,
+    noRetention: () =>
+      'No hay política de retención configurada, así que nunca se borra nada por su cuenta. Pon "store": {"keepDays": 90} cuando quieras una.',
+    pruneNeedsPolicy: () =>
+      'Podar necesita una política de retención: pon "store": {"keepDays": 90} en trazum.config.json, o pasa --keep 90d para esta ejecución. Borrar mediciones con una política que nadie escribió no es un valor por defecto que debas recibir por accidente.',
+    pruneDryRun: (count, days, span, usd) =>
+      span === null
+        ? `Nada es más antiguo que ${days} días, así que una poda no borraría nada.`
+        : `Una poda borraría ${count} mediciones de más de ${days} días, que cubren ${span} y ${usd} de gasto medido. No se borró nada — esto era --dry-run.`,
+    pruned: (count, days, span, usd, kept) =>
+      span === null
+        ? `Nada era más antiguo que ${days} días. ${kept} mediciones conservadas, y el log compactado.`
+        : `Borradas ${count} mediciones de más de ${days} días, que cubren ${span} y ${usd} de gasto medido. ${kept} conservadas, y el log compactado a lo que el almacén ya resolvía.`,
+  },
+
   connect: {
     noTarget: (providers) =>
       `Nombra un proveedor del que leer tu factura: trazum connect anthropic. Disponibles: ${providers}. La credencial sale del entorno y nunca se guarda — añade --dry-run para ver exactamente qué se llamaría y de qué variable saldría.`,
@@ -1538,7 +1674,8 @@ ${bold('EJEMPLOS')}
     needsThree: (count) =>
       `Una serie necesita al menos tres informes con fecha, y este directorio tiene ${count}. Dos informes son una comparación, y "trazum profile --against" ya la hace mejor.`,
     heading: (periods, from, to) => `La larga distancia: ${periods} períodos, ${from} → ${to}`,
-    periodRow: (name, usd, calls, days) => `${name}  ${usd} · ${calls} llamadas · ${days} días`,
+    periodRow: (name, usd, calls, days) =>
+      calls === null ? `${name}  ${usd} · ${days} días` : `${name}  ${usd} · ${calls} llamadas · ${days} días`,
     runLabel: (label, periods, sinceName, from, to) =>
       `${label} lleva ${periods} períodos consecutivos subiendo desde ${sinceName}: ${from} → ${to}. Una forma, no un pronóstico.`,
     runModel: (model, periods, sinceName, from, to) =>
@@ -1559,6 +1696,8 @@ ${bold('EJEMPLOS')}
       const span = first !== null && last !== null ? ` (${first} → ${last})` : '';
       return `${what} se ha planificado ${appearances} veces${span} y sigue en el plan más reciente — una decisión que nadie está revisando.`;
     },
+    storeNoLabels: () =>
+      'Esta serie viene del almacén, y una API de uso agrupa por modelo y workspace, no por carga de trabajo — así que aquí no hay serie por label en absoluto. Ausente, no vacía: nada de lo de arriba dice que una carga se moviera o dejara de moverse.',
     undated: (name) => `${name} no lleva período, así que no está en ninguna línea de tiempo de arriba — nombrado, nunca absorbido en silencio.`,
     unrecognized: (name) => `${name} no es ni un informe guardado ni un plan guardado, así que no está en ninguna serie de arriba.`,
     footer: () =>

package/src/i18n/types.ts

@@ -1,4 +1,4 @@
-import type { CannotTellReason, EvalVerdict, Locale, PlanActionKind, PlanAssumption, RuleLevel, VerifyOutcome } from '@trazum/core';
+import type { CannotTellReason, EvalVerdict, Locale, NotJudgeable, PlanActionKind, PlanAssumption, RuleLevel, VerifyOutcome, WatchGate } from '@trazum/core';
 
 /**
  * The CLI's own message catalogue.
@@ -1072,6 +1072,59 @@ export interface CliMessages {
     wrote(path: string): string;
   };
 
+  /**
+   * `trazum watch` — the gates, evaluated as the money moves.
+   *
+   * The copy here carries the rule that makes an alert at 3am trustworthy: a
+   * crossing is measured, never projected, and a period too short to judge is
+   * said to be rather than passed.
+   */
+  watch: {
+    /** Watching with no threshold configured is a green light nobody earned. */
+    noThresholds(): string;
+    nothingToWatch(dir: string): string;
+    intervalTooTight(): string;
+    badWebhook(reason: 'invalid-url' | 'credentials-in-url' | 'insecure-scheme'): string;
+    /** A measured crossing. `day` names the afternoon when the gate is a day gate. */
+    crossed(gate: WatchGate, measured: string, limit: string, day: string | null): string;
+    /** Still over the limit, and already reported — quiet, but not clean. */
+    stillOver(gate: WatchGate, measured: string, limit: string, day: string | null): string;
+    /** Neither a pass nor a failure: this cannot be judged yet, and why. */
+    notJudgeable(gate: WatchGate, reason: NotJudgeable, covered: string | null): string;
+    /** The stretch nobody was watching, named rather than implied away. */
+    gap(from: string, to: string): string;
+    allWithin(gates: string): string;
+    webhookFailed(status: string): string;
+    watching(minutes: string): string;
+  };
+
+  /**
+   * `trazum store` — the measurements kept on disk.
+   *
+   * The one part of this product that deletes something, so its copy is
+   * written to make that visible: what is held, what a prune would take, and
+   * a refusal when no retention policy exists to prune against.
+   */
+  store: {
+    /** Records appended by a pull that asked to keep them. */
+    appended(count: string, dir: string): string;
+    empty(dir: string): string;
+    heading(records: string, usd: string, from: string, to: string): string;
+    providerRow(provider: string, records: string, span: string, models: string): string;
+    /** What the store holds — and what it never holds. */
+    holds(files: string): string;
+    /** Records the store could not tell apart, kept whole rather than merged. */
+    possiblyDouble(count: string): string;
+    unknownVersion(count: string): string;
+    unreadable(file: string, line: string): string;
+    retention(days: string): string;
+    noRetention(): string;
+    /** Deleting on a policy nobody wrote down is refused, never defaulted. */
+    pruneNeedsPolicy(): string;
+    pruneDryRun(count: string, days: string, span: string | null, usd: string): string;
+    pruned(count: string, days: string, span: string | null, usd: string, kept: string): string;
+  };
+
   /**
    * `trazum connect` — the bill, read from the provider.
    *
@@ -1115,12 +1168,15 @@ export interface CliMessages {
     /** Under three dated reports there is no series — only the comparison --against already does. */
     needsThree(count: string): string;
     heading(periods: string, from: string, to: string): string;
-    periodRow(name: string, usd: string, calls: string, days: string): string;
+    /** `calls` is null on a source that serves no request count. */
+    periodRow(name: string, usd: string, calls: string | null, days: string): string;
     runLabel(label: string, periods: string, sinceName: string, from: string, to: string): string;
     runModel(model: string, periods: string, sinceName: string, from: string, to: string): string;
     runCache(periods: string, sinceName: string, from: string, to: string): string;
     /** The same action in plan after plan: a decision nobody is executing. */
     repeated(kind: PlanActionKind, label: string, model: string, appearances: string, first: string | null, last: string | null): string;
+    /** A store source carries no labels, so the label series is absent, not empty. */
+    storeNoLabels(): string;
     undated(name: string): string;
     unrecognized(name: string): string;
     footer(): string;