@trazum/cli 1.66.0 → 1.67.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.66.0",
3
+ "version": "1.67.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.66.0"
40
+ "@trazum/core": "1.67.1"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/html.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { UNLABELLED, formatUsd, sharesOf } from '@trazum/core';
2
- import type { RollupDocument, UsageBreakdown } from '@trazum/core';
2
+ import type { PositionDocument, RollupDocument, UsageBreakdown } from '@trazum/core';
3
3
  import type { CliMessages } from './i18n/index.js';
4
4
  import type { ProfileMarkdownInput } from './markdown.js';
5
5
  import { dayOf, spanDays } from './time.js';
@@ -341,3 +341,79 @@ export function renderRollupHtml(document: RollupDocument, t: CliMessages): stri
341
341
  parts,
342
342
  );
343
343
  }
344
+
345
+ /**
346
+ * The position as one self-contained page — the third door the 1.64 arc's
347
+ * discipline applies to: the input is the position document itself, the one
348
+ * `--json` prints and `conform` checks, so the page cannot disagree with
349
+ * the data. Every sentence is the terminal's own, through the same message
350
+ * catalogue, which is what keeps the two surfaces saying the same thing in
351
+ * the same words. The caveat block — what could not be measured, what is
352
+ * deliberately unanswered, the records nobody can price — renders BEFORE
353
+ * the positions, because a forwarded page gets cropped from the bottom.
354
+ */
355
+ export function renderPositionHtml(document: PositionDocument, t: CliMessages): string {
356
+ const scopeName = (entry: { scope: string; label: string | null }): string =>
357
+ entry.scope === 'month'
358
+ ? t.position.scopeMonth()
359
+ : entry.scope === 'day'
360
+ ? t.position.scopeDay()
361
+ : t.position.scopeLabel(entry.label ?? '');
362
+
363
+ const parts: string[] = [];
364
+ parts.push(`<h1>${esc(t.position.heading(document.month.id))}</h1>`);
365
+ parts.push(`<p class="muted">${esc(t.position.source())}</p>`);
366
+
367
+ const caveats = [
368
+ ...document.unmeasured.map((entry) => t.position.unmeasured(scopeName(entry), t.position.why(entry.why))),
369
+ ...document.cannotSay,
370
+ ...(document.unpricedRecords > 0 ? [t.position.unpriced(document.unpricedRecords)] : []),
371
+ ];
372
+ if (caveats.length > 0) {
373
+ parts.push(
374
+ `<div class="caveats"><h2>${esc(t.position.cannotSayHeading())}</h2><ul>${caveats
375
+ .map((line) => `<li>${esc(line)}</li>`)
376
+ .join('')}</ul></div>`,
377
+ );
378
+ }
379
+
380
+ parts.push(
381
+ `<ul class="findings">${document.positions
382
+ .map((position) => {
383
+ const name = scopeName(position);
384
+ const sentence =
385
+ position.verdict === 'cannot-tell'
386
+ ? t.position.cannotTell(name)
387
+ : position.verdict === 'over'
388
+ ? t.position.over(
389
+ name,
390
+ formatUsd(position.measuredUsd),
391
+ formatUsd(position.limitUsd),
392
+ formatUsd(-position.remainingUsd),
393
+ )
394
+ : t.position.within(
395
+ name,
396
+ formatUsd(position.measuredUsd),
397
+ formatUsd(position.limitUsd),
398
+ formatUsd(position.remainingUsd),
399
+ position.daysMeasured,
400
+ position.daysElapsed,
401
+ );
402
+ const distance =
403
+ position.distance === null
404
+ ? ''
405
+ : `<div class="muted">${esc(
406
+ t.position.distance(
407
+ position.distance.daysAway.toFixed(1),
408
+ formatUsd(position.distance.usdPerDay),
409
+ position.distance.overDays,
410
+ ),
411
+ )}</div>`;
412
+ return `<li>${esc(sentence)}${distance}</li>`;
413
+ })
414
+ .join('')}</ul>`,
415
+ );
416
+
417
+ parts.push(`<footer>${esc(t.html.footer())}</footer>`);
418
+ return page(t.position.heading(document.month.id), t.locale, parts);
419
+ }
package/src/i18n/en.ts CHANGED
@@ -58,6 +58,7 @@ ${bold('USAGE')}
58
58
  trazum conform <file|-> [--contract <name>]
59
59
  trazum schema <contract>
60
60
  trazum rollup <document...|dir> [--json] [--html-out <file>]
61
+ trazum position <usage.jsonl>
61
62
  trazum pulse [--max-stale-hours <n>]
62
63
  trazum bench [--workload <id>] [--record <file>] [--against <file> --max-ratio <n>] [--json]
63
64
  trazum write [--answers <file>] [--json] [-o <file>]
@@ -135,6 +136,19 @@ ${bold('OPTIONS FOR write')}
135
136
  --calls <n> Calls per month, for the estimate.
136
137
  --avg-output <n> Average output tokens per call, for the estimate.
137
138
 
139
+ ${bold('OPTIONS FOR position')}
140
+ --html-out <file> The position as one self-contained page — the
141
+ same sentences the terminal prints, caveats
142
+ first, for the person who does not run CLIs.
143
+ --json The position document, contract-checked like
144
+ everything (\`--contract position\`).
145
+
146
+ Where the month stands against every configured ceiling, measured from the
147
+ named log alone with the denominator on every figure. The distance line is
148
+ division on the past, labelled as such, and absent under the seven-day
149
+ floor, on an over, and on a zero rate: never a forecast, and no field in
150
+ the document names a date.
151
+
138
152
  ${bold('OPTIONS FOR pulse')}
139
153
  --max-stale-hours <n> Exit 1 when something that runs here has not run
140
154
  in over n hours. Without it, the ages are
@@ -435,6 +449,13 @@ ${bold('OPTIONS FOR check')}
435
449
  --baseline Gate on the recorded cost baseline. On by default whenever
436
450
  the config declares one, so CI needs no argument; the useful
437
451
  spelling is --no-baseline, which skips it for one run.
452
+ --files-from <file|-> Check only the files listed, one path per line — the shape
453
+ git diff --name-only produces, so a pre-commit hook is one
454
+ pipe: git diff --cached --name-only | trazum check --files-from -
455
+ Non-prompt paths and deletions are dropped and counted out
456
+ loud; a list with nothing checkable passes. Budgets apply
457
+ per file as always; the baseline needs the whole repository
458
+ and is skipped, and says so.
438
459
 
439
460
  Built for CI: exits with code 1 when the prompt busts the budget, so a
440
461
  template that grows unchecked breaks the build instead of the bill.
@@ -1577,6 +1598,35 @@ ${bold('EXAMPLES')}
1577
1598
  },
1578
1599
  },
1579
1600
 
1601
+ position: {
1602
+ heading: (month) => `Where ${month} stands, measured`,
1603
+ scopeMonth: () => 'the month',
1604
+ scopeDay: () => 'today',
1605
+ scopeLabel: (label) => `"${label}"`,
1606
+ within: (scope, measured, limit, remaining, days, elapsed) =>
1607
+ `${scope}: ${measured} of ${limit} measured — ${remaining} left (${days} of ${elapsed} elapsed days measured)`,
1608
+ over: (scope, measured, limit, overBy) =>
1609
+ `${scope}: over — ${measured} measured against ${limit}, ${overBy} past the ceiling`,
1610
+ cannotTell: (scope) => `${scope}: cannot tell — nothing measured in this window`,
1611
+ distance: (days, rate, overDays) =>
1612
+ `at ${rate}/day over ${overDays} measured days, the ceiling is ${days} days away — division on the past, not a forecast`,
1613
+ unmeasuredHeading: () => 'Configured and not measurable from this log',
1614
+ unmeasured: (scope, why) => `${scope}: ${why}`,
1615
+ why: (reason) =>
1616
+ reason === 'no-clock'
1617
+ ? 'no record carries a timestamp, so no window can be measured'
1618
+ : reason === 'no-labels'
1619
+ ? 'no record carries a label, so per-label spend is unknowable here'
1620
+ : reason === 'nothing-recorded'
1621
+ ? 'the log is empty — nothing was recorded'
1622
+ : 'the log records labels and has never seen this one this month — possibly renamed, possibly idle, and neither is "under budget"',
1623
+ cannotSayHeading: () => 'What this deliberately does not answer',
1624
+ unpriced: (count) =>
1625
+ `${count} record(s) name a model the catalogue cannot price. They contribute nothing to any figure above — money nobody can see, said here rather than hidden.`,
1626
+ source: () =>
1627
+ 'Measured from this log alone, priced record by record. The store\'s provider-billed monthly standing is a different measurement — "trazum store" prints it — and the two are never merged into one figure.',
1628
+ noLog: () => 'position needs a usage log: trazum position usage.jsonl',
1629
+ },
1580
1630
  pulse: {
1581
1631
  heading: () => 'Did the things that are supposed to run, run?',
1582
1632
  kind: (kind) => {
@@ -2012,6 +2062,10 @@ ${bold('EXAMPLES')}
2012
2062
  noBudget: () => '(no budget)',
2013
2063
  walkTruncated: () =>
2014
2064
  'Stopped early: the directory is larger than the walk limit, so this is not the whole picture.',
2065
+ filesFromSummary: (checked, listed, dropped) =>
2066
+ `Checking ${checked} of ${listed} listed file(s) — ${dropped} dropped: not a prompt extension, ignored by config, or no longer on disk.`,
2067
+ filesFromNoBaseline: () =>
2068
+ 'The baseline gate is skipped under --files-from: it compares the whole repository against the committed record, and a partial list would read as removals. Budgets are checked per file as always; run "trazum check ." for the baseline.',
2015
2069
  exactCountsCost: (files) =>
2016
2070
  `Counting ${files} ${files === 1 ? 'file' : 'files'} through the API, one call each. This takes a moment.`,
2017
2071
  },
package/src/i18n/es.ts CHANGED
@@ -45,6 +45,7 @@ ${bold('USO')}
45
45
  trazum conform <fichero|-> [--contract <nombre>]
46
46
  trazum schema <contrato>
47
47
  trazum rollup <documento...|dir> [--json] [--html-out <fichero>]
48
+ trazum position <uso.jsonl>
48
49
  trazum pulse [--max-stale-hours <n>]
49
50
  trazum bench [--workload <id>] [--record <fichero>] [--against <fichero> --max-ratio <n>] [--json]
50
51
  trazum write [--answers <fichero>] [--json] [-o <fichero>]
@@ -124,6 +125,19 @@ ${bold('OPCIONES DE write')}
124
125
  --calls <n> Llamadas al mes, para la estimación.
125
126
  --avg-output <n> Tokens de salida por llamada, para la estimación.
126
127
 
128
+ ${bold('OPCIONES DE position')}
129
+ --html-out <fichero> La posición como una página autocontenida — las
130
+ mismas frases que imprime el terminal, caveats
131
+ primero, para quien no ejecuta CLIs.
132
+ --json El documento de posición, verificado por
133
+ contrato como todo (\`--contract position\`).
134
+
135
+ Dónde está el mes frente a cada techo configurado, medido solo desde el
136
+ log nombrado y con el denominador en cada cifra. La línea de distancia es
137
+ división sobre el pasado, etiquetada como tal, y ausente bajo el suelo de
138
+ siete días, con un techo superado o con tasa cero: nunca un pronóstico, y
139
+ ningún campo del documento nombra una fecha.
140
+
127
141
  ${bold('OPCIONES DE pulse')}
128
142
  --max-stale-hours <n> Sale con 1 cuando algo que corre aquí lleva más
129
143
  de n horas sin correr. Sin esto, se informan las
@@ -436,6 +450,15 @@ ${bold('OPCIONES DE check')}
436
450
  --baseline Aplica la línea base registrada. Activo por defecto siempre
437
451
  que el config declare una, así CI no necesita argumentos; la
438
452
  forma útil es --no-baseline, que la omite en una ejecución.
453
+ --files-from <fichero|-> Comprueba solo los ficheros listados, una ruta por línea —
454
+ la forma que produce git diff --name-only, así que un hook
455
+ de pre-commit es una tubería:
456
+ git diff --cached --name-only | trazum check --files-from -
457
+ Las rutas que no son prompts y las eliminaciones se
458
+ descartan y se cuentan en voz alta; una lista sin nada
459
+ comprobable pasa. Los presupuestos aplican por fichero como
460
+ siempre; el baseline necesita el repositorio entero y se
461
+ omite, diciéndolo.
439
462
 
440
463
  Pensado para CI: sale con código 1 si el prompt supera el presupuesto,
441
464
  así una plantilla que crece sin control rompe la build en vez de la factura.
@@ -1589,6 +1612,35 @@ ${bold('EJEMPLOS')}
1589
1612
  },
1590
1613
  },
1591
1614
 
1615
+ position: {
1616
+ heading: (month) => `Dónde está ${month}, medido`,
1617
+ scopeMonth: () => 'el mes',
1618
+ scopeDay: () => 'hoy',
1619
+ scopeLabel: (label) => `«${label}»`,
1620
+ within: (scope, measured, limit, remaining, days, elapsed) =>
1621
+ `${scope}: ${measured} de ${limit} medidos — quedan ${remaining} (${days} de ${elapsed} días transcurridos con medición)`,
1622
+ over: (scope, measured, limit, overBy) =>
1623
+ `${scope}: superado — ${measured} medidos contra ${limit}, ${overBy} por encima del techo`,
1624
+ cannotTell: (scope) => `${scope}: no se puede saber — nada medido en esta ventana`,
1625
+ distance: (days, rate, overDays) =>
1626
+ `a ${rate}/día sobre ${overDays} días medidos, el techo queda a ${days} días — división sobre el pasado, no un pronóstico`,
1627
+ unmeasuredHeading: () => 'Configurado y no medible desde este log',
1628
+ unmeasured: (scope, why) => `${scope}: ${why}`,
1629
+ why: (reason) =>
1630
+ reason === 'no-clock'
1631
+ ? 'ningún registro lleva marca de tiempo, así que no se puede medir ninguna ventana'
1632
+ : reason === 'no-labels'
1633
+ ? 'ningún registro lleva etiqueta, así que el gasto por etiqueta es incognoscible aquí'
1634
+ : reason === 'nothing-recorded'
1635
+ ? 'el log está vacío — no se registró nada'
1636
+ : 'el log registra etiquetas y no ha visto esta en todo el mes — quizá renombrada, quizá parada, y ninguna de las dos es «dentro del presupuesto»',
1637
+ cannotSayHeading: () => 'Lo que deliberadamente no responde',
1638
+ unpriced: (count) =>
1639
+ `${count} registro(s) nombran un modelo que el catálogo no puede tasar. No aportan nada a ninguna cifra de arriba — dinero que nadie ve, dicho aquí en vez de escondido.`,
1640
+ source: () =>
1641
+ 'Medido solo desde este log, registro a registro. La posición mensual facturada por el proveedor que guarda el almacén es otra medición — la imprime «trazum store» — y las dos nunca se funden en una cifra.',
1642
+ noLog: () => 'position necesita un log de uso: trazum position uso.jsonl',
1643
+ },
1592
1644
  pulse: {
1593
1645
  heading: () => '¿Corrieron las cosas que tienen que correr?',
1594
1646
  kind: (kind) => {
@@ -2023,6 +2075,10 @@ ${bold('EJEMPLOS')}
2023
2075
  noBudget: () => '(sin presupuesto)',
2024
2076
  walkTruncated: () =>
2025
2077
  'Se ha parado antes de tiempo: el directorio supera el límite de recorrido, así que esto no es el cuadro completo.',
2078
+ filesFromSummary: (checked, listed, dropped) =>
2079
+ `Comprobando ${checked} de ${listed} fichero(s) listados — ${dropped} descartados: sin extensión de prompt, ignorados por la config, o ya no están en disco.`,
2080
+ filesFromNoBaseline: () =>
2081
+ 'La puerta de baseline se omite con --files-from: compara el repositorio entero contra el registro comprometido, y una lista parcial se leería como eliminaciones. Los presupuestos se comprueban por fichero como siempre; ejecuta «trazum check .» para el baseline.',
2026
2082
  exactCountsCost: (files) =>
2027
2083
  `Contando ${files} ${files === 1 ? 'fichero' : 'ficheros'} con la API, una llamada por cada uno. Esto tarda un momento.`,
2028
2084
  },
package/src/i18n/types.ts CHANGED
@@ -518,6 +518,29 @@ export interface CliMessages {
518
518
  caveat(code: string): string;
519
519
  };
520
520
 
521
+ position: {
522
+ /** `Where 2026-08 stands, measured` — the month is data, not prose. */
523
+ heading(month: string): string;
524
+ scopeMonth(): string;
525
+ scopeDay(): string;
526
+ scopeLabel(label: string): string;
527
+ within(scope: string, measured: string, limit: string, remaining: string, days: number, elapsed: number): string;
528
+ over(scope: string, measured: string, limit: string, overBy: string): string;
529
+ cannotTell(scope: string): string;
530
+ /**
531
+ * Division on the past, said as such — never a forecast. Absent under
532
+ * the floor, so this line only ever renders with its denominator.
533
+ */
534
+ distance(days: string, rate: string, overDays: number): string;
535
+ unmeasuredHeading(): string;
536
+ unmeasured(scope: string, why: string): string;
537
+ why(reason: 'no-clock' | 'no-labels' | 'nothing-recorded' | 'label-unseen'): string;
538
+ cannotSayHeading(): string;
539
+ unpriced(count: number): string;
540
+ /** The source, named: this log alone, never merged with the store. */
541
+ source(): string;
542
+ noLog(): string;
543
+ };
521
544
  pulse: {
522
545
  heading(): string;
523
546
  kind(kind: string): string;
@@ -810,6 +833,10 @@ export interface CliMessages {
810
833
  noBudget(): string;
811
834
  walkTruncated(): string;
812
835
  exactCountsCost(files: number): string;
836
+ /** How many of the listed files are checkable, and how many were dropped. */
837
+ filesFromSummary(checked: number, listed: number, dropped: number): string;
838
+ /** The baseline is whole-repository; a partial list checks budgets only. */
839
+ filesFromNoBaseline(): string;
813
840
  };
814
841
 
815
842
  /**
package/src/index.ts CHANGED
@@ -92,6 +92,7 @@ import {
92
92
  listModels,
93
93
  LOCALES,
94
94
  MAX_BASELINE_BYTES,
95
+ matchGlob,
95
96
  MAX_INPUT_CHARS,
96
97
  moneyIsComparable,
97
98
  mostSpecificMatch,
@@ -110,6 +111,7 @@ import {
110
111
  parseUsageLine,
111
112
  plannedCalls,
112
113
  positionAt,
114
+ positionReport,
113
115
  PRICING_LAST_REVIEWED,
114
116
  profilePrompt,
115
117
  profileToCsv,
@@ -242,7 +244,7 @@ import {
242
244
  renderRankMarkdown,
243
245
  renderProfileMarkdown,
244
246
  } from './markdown.js';
245
- import { renderProfileHtml, renderRollupHtml } from './html.js';
247
+ import { renderPositionHtml, renderProfileHtml, renderRollupHtml } from './html.js';
246
248
  import type { CliMessages } from './i18n/index.js';
247
249
 
248
250
  // --------------------------------------------------------------------------
@@ -280,6 +282,7 @@ interface Args {
280
282
  const VALUE_FLAGS = new Set([
281
283
  'answers',
282
284
  'calls',
285
+ 'files-from',
283
286
  'log',
284
287
  'avg-output',
285
288
  'a',
@@ -644,7 +647,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
644
647
  'tokens-only', 'cost', 'prompt', 'suggest', 'apply-suggestions',
645
648
  'cache-suggestions', 'from-log', 'label', 'all-labels',
646
649
  ],
647
- check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
650
+ check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline', 'files-from'],
648
651
  baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
649
652
  profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'html-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', 'markdown-summary', 'by-source'],
650
653
  plan: ['json', 'out', 'markdown-out', 'min-usd', 'pricing', 'pricing-live'],
@@ -664,6 +667,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
664
667
  conform: ['contract', 'json'],
665
668
  schema: [],
666
669
  rollup: ['json', 'html-out'],
670
+ position: ['json', 'html-out', 'pricing', 'pricing-live'],
667
671
  pulse: ['json', 'max-stale-hours'],
668
672
  bench: ['workload', 'json', 'record', 'against', 'max-ratio'],
669
673
  write: ['answers', 'json', 'out', 'o', 'calls', 'avg-output'],
@@ -2545,6 +2549,130 @@ async function commandWrite(args: Args, t: CliMessages): Promise<void> {
2545
2549
  }
2546
2550
  }
2547
2551
 
2552
+ /**
2553
+ * `trazum position <usage.jsonl>` — where the month stands, measured.
2554
+ *
2555
+ * One answer where `profile`, `budgetPositions` and `watch` each held a
2556
+ * piece: every configured ceiling with its measurement, its window and its
2557
+ * denominators, from the named log alone. The distance line is division on
2558
+ * the past — `positionReport` withholds it under the floor, on an over and
2559
+ * on a zero rate, so if it prints, its denominator prints with it.
2560
+ */
2561
+ async function commandPosition(
2562
+ args: Args,
2563
+ config: TrazumConfig,
2564
+ pricing: PricingCatalogue,
2565
+ t: CliMessages,
2566
+ ): Promise<void> {
2567
+ const file = args.positional[0];
2568
+ if (file === undefined) throw new Error(t.position.noLog());
2569
+
2570
+ const text = await readUsageLog(file, t);
2571
+ const records = text
2572
+ .split('\n')
2573
+ .filter((line) => line.trim() !== '')
2574
+ .map((line) => parseUsageLine(line))
2575
+ .filter((record): record is NonNullable<ReturnType<typeof parseUsageLine>> => record !== null);
2576
+
2577
+ const document = positionReport(
2578
+ records,
2579
+ {
2580
+ ...(config.spend === undefined ? {} : { spend: config.spend }),
2581
+ ...(config.limits === undefined ? {} : { limits: config.limits }),
2582
+ },
2583
+ { catalogue: pricing },
2584
+ );
2585
+
2586
+ /**
2587
+ * The HTML door, written on both output paths — the 1.64 rule: the page a
2588
+ * person forwards must exist whether the run was for a human or a pipe.
2589
+ */
2590
+ const htmlOut = stringFlag(args, 'html-out');
2591
+ if (htmlOut !== undefined) {
2592
+ await writeFile(htmlOut, renderPositionHtml(document, t), 'utf8');
2593
+ if (!boolFlag(args, 'json')) console.error(c.dim(t.html.written(htmlOut)));
2594
+ }
2595
+
2596
+ if (boolFlag(args, 'json')) {
2597
+ console.log(JSON.stringify(document, null, 2));
2598
+ return;
2599
+ }
2600
+
2601
+ const scopeName = (position: { scope: string; label: string | null }): string =>
2602
+ position.scope === 'month'
2603
+ ? t.position.scopeMonth()
2604
+ : position.scope === 'day'
2605
+ ? t.position.scopeDay()
2606
+ : t.position.scopeLabel(position.label ?? '');
2607
+
2608
+ console.log();
2609
+ console.log(c.bold(t.position.heading(document.month.id)));
2610
+ for (const position of document.positions) {
2611
+ const name = scopeName(position);
2612
+ if (position.verdict === 'cannot-tell') {
2613
+ console.log(` ${c.yellow('?')} ${wrap(t.position.cannotTell(name), 72, ' ')}`);
2614
+ continue;
2615
+ }
2616
+ if (position.verdict === 'over') {
2617
+ console.log(
2618
+ ` ${c.red('✗')} ${wrap(
2619
+ t.position.over(name, formatUsd(position.measuredUsd), formatUsd(position.limitUsd), formatUsd(-position.remainingUsd)),
2620
+ 72,
2621
+ ' ',
2622
+ )}`,
2623
+ );
2624
+ continue;
2625
+ }
2626
+ console.log(
2627
+ ` ${c.green('✓')} ${wrap(
2628
+ t.position.within(
2629
+ name,
2630
+ formatUsd(position.measuredUsd),
2631
+ formatUsd(position.limitUsd),
2632
+ formatUsd(position.remainingUsd),
2633
+ position.daysMeasured,
2634
+ position.daysElapsed,
2635
+ ),
2636
+ 72,
2637
+ ' ',
2638
+ )}`,
2639
+ );
2640
+ if (position.distance !== null) {
2641
+ console.log(
2642
+ ` ${c.dim(wrap(
2643
+ t.position.distance(
2644
+ position.distance.daysAway.toFixed(1),
2645
+ formatUsd(position.distance.usdPerDay),
2646
+ position.distance.overDays,
2647
+ ),
2648
+ 70,
2649
+ ' ',
2650
+ ))}`,
2651
+ );
2652
+ }
2653
+ }
2654
+ if (document.unmeasured.length > 0) {
2655
+ console.log();
2656
+ console.log(` ${c.bold(t.position.unmeasuredHeading())}`);
2657
+ for (const entry of document.unmeasured) {
2658
+ console.log(` ${c.yellow(wrap(t.position.unmeasured(scopeName(entry), t.position.why(entry.why)), 70, ' '))}`);
2659
+ }
2660
+ }
2661
+ if (document.cannotSay.length > 0) {
2662
+ console.log();
2663
+ console.log(` ${c.bold(t.position.cannotSayHeading())}`);
2664
+ for (const line of document.cannotSay) {
2665
+ console.log(` ${c.dim(wrap(line, 70, ' '))}`);
2666
+ }
2667
+ }
2668
+ if (document.unpricedRecords > 0) {
2669
+ console.log();
2670
+ console.log(` ${c.yellow(wrap(t.position.unpriced(document.unpricedRecords), 72, ' '))}`);
2671
+ }
2672
+ console.log();
2673
+ console.log(` ${c.dim(wrap(t.position.source(), 74, ' '))}`);
2674
+ }
2675
+
2548
2676
  async function commandPulse(args: Args, t: CliMessages): Promise<void> {
2549
2677
  const root = process.cwd();
2550
2678
  const maxStaleHours = numberFlag(args, 'max-stale-hours', Number.NaN, t);
@@ -4958,6 +5086,25 @@ async function commandCheck(
4958
5086
  // A flag beats the config, as everywhere else. -1 means "not given".
4959
5087
  const flagBudget = numberFlag(args, 'max-tokens', -1, t);
4960
5088
 
5089
+ /**
5090
+ * `--files-from -` reads a file list from stdin — the shape
5091
+ * `git diff --name-only` already produces — so a pre-commit hook is one
5092
+ * pipe with no shell loop. Chapter three of the 1.67 arc, and the
5093
+ * refusals and budgets are the directory mode's own: only which files are
5094
+ * looked at changes, and what was dropped from the list is counted out
5095
+ * loud rather than silently.
5096
+ */
5097
+ const filesFrom = stringFlag(args, 'files-from');
5098
+ if (filesFrom !== undefined) {
5099
+ const listText = await readInput(filesFrom, t, maxInputFlag(args, t));
5100
+ const listed = listText
5101
+ .split('\n')
5102
+ .map((line) => line.trim())
5103
+ .filter((line) => line !== '');
5104
+ await checkDirectory('.', args, flagBudget, config, counter, level, t, locale, pricing, listed);
5105
+ return;
5106
+ }
5107
+
4961
5108
  const asDirectory = target !== undefined && target !== '-' ? await isDirectory(target) : false;
4962
5109
 
4963
5110
  if (asDirectory) {
@@ -9275,6 +9422,37 @@ interface PromptScan {
9275
9422
  * files the gate does not check. One walk, one answer, and the budget resolution
9276
9423
  * comes along for free so `check` still sees exactly what it always did.
9277
9424
  */
9425
+ /**
9426
+ * Filters an explicit file list to what the directory walk would have
9427
+ * accepted: the same extensions, the same ignore globs, and only files that
9428
+ * exist — a path listed by `git diff --name-only` may be a deletion. The
9429
+ * dropped count is returned so the caller can say it, because a hook that
9430
+ * silently skips half its input reads as having checked everything.
9431
+ */
9432
+ async function fromList(
9433
+ root: string,
9434
+ listed: readonly string[],
9435
+ config: TrazumConfig,
9436
+ ): Promise<{ checkable: string[]; dropped: number }> {
9437
+ const extensions = (config.extensions ?? [...DEFAULT_EXTENSIONS, ...SOURCE_EXTENSIONS]).map((ext) =>
9438
+ ext.toLowerCase(),
9439
+ );
9440
+ const ignore = config.ignore ?? [];
9441
+ const checkable: string[] = [];
9442
+ for (const raw of listed) {
9443
+ const relativePath = raw.replace(/^\.\//, '');
9444
+ if (!extensions.some((ext) => relativePath.toLowerCase().endsWith(ext))) continue;
9445
+ if (ignore.some((pattern) => matchGlob(pattern, relativePath) || matchGlob(pattern, `${relativePath}/`))) continue;
9446
+ try {
9447
+ if (!(await stat(join(root, relativePath))).isFile()) continue;
9448
+ } catch {
9449
+ continue; // listed and gone: a deletion in the diff, not an error
9450
+ }
9451
+ checkable.push(relativePath);
9452
+ }
9453
+ return { checkable, dropped: listed.length - checkable.length };
9454
+ }
9455
+
9278
9456
  async function scanPrompts(
9279
9457
  root: string,
9280
9458
  args: Args,
@@ -9285,13 +9463,16 @@ async function scanPrompts(
9285
9463
  t: CliMessages,
9286
9464
  locale: Locale,
9287
9465
  pricing: PricingCatalogue,
9466
+ only?: readonly string[],
9288
9467
  ): Promise<PromptScan> {
9289
9468
  // Source files are walked alongside prompt files rather than opted into.
9290
9469
  // Requiring config to discover a marker somebody just wrote is how `eval` came
9291
9470
  // to be fully implemented and completely undiscoverable; an unmarked source
9292
9471
  // file costs one `includes()` and is dropped.
9293
9472
  const extensions = config.extensions ?? [...DEFAULT_EXTENSIONS, ...SOURCE_EXTENSIONS];
9294
- const { files, truncated } = await walkPrompts(root, { extensions, ignore: config.ignore });
9473
+ const walked = only === undefined ? await walkPrompts(root, { extensions, ignore: config.ignore }) : null;
9474
+ const files = walked === null ? [...only!] : walked.files;
9475
+ const truncated = walked === null ? false : walked.truncated;
9295
9476
 
9296
9477
  if (files.length === 0) {
9297
9478
  throw new Error(t.errors.noPromptsFound(root, extensions.join(' ')));
@@ -9361,8 +9542,25 @@ async function checkDirectory(
9361
9542
  t: CliMessages,
9362
9543
  locale: Locale,
9363
9544
  pricing: PricingCatalogue,
9545
+ only?: readonly string[],
9364
9546
  ): Promise<void> {
9365
9547
  const n = (value: number): string => value.toLocaleString(t.numberLocale);
9548
+
9549
+ /**
9550
+ * An explicit list with nothing checkable is a pass, not an error: the
9551
+ * whole point of `--files-from` is a hook over `git diff --name-only`,
9552
+ * and a commit that touches no prompt files must go through — with the
9553
+ * drop counted out loud, never silently.
9554
+ */
9555
+ if (only !== undefined) {
9556
+ const { checkable, dropped } = await fromList(root, only, config);
9557
+ if (!boolFlag(args, 'json')) {
9558
+ console.log(c.dim(t.check.filesFromSummary(checkable.length, only.length, dropped)));
9559
+ }
9560
+ if (checkable.length === 0) return;
9561
+ only = checkable;
9562
+ }
9563
+
9366
9564
  const { verdicts, declined, truncated, extensions } = await scanPrompts(
9367
9565
  root,
9368
9566
  args,
@@ -9373,6 +9571,7 @@ async function checkDirectory(
9373
9571
  t,
9374
9572
  locale,
9375
9573
  pricing,
9574
+ only,
9376
9575
  );
9377
9576
 
9378
9577
  /**
@@ -9384,7 +9583,16 @@ async function checkDirectory(
9384
9583
  * asked for and could not run is not a pass: that is the whole reason
9385
9584
  * `parseBaseline` throws on everything.
9386
9585
  */
9387
- const wantsBaseline = config.baseline !== undefined && boolFlag(args, 'baseline', true);
9586
+ /**
9587
+ * The baseline is a whole-repository gate: it compares every measured file
9588
+ * against the committed record, and handing it two changed files would
9589
+ * report the other thirty-eight as removed. So `--files-from` checks
9590
+ * budgets only, and says so once rather than silently narrowing a gate.
9591
+ */
9592
+ const wantsBaseline = config.baseline !== undefined && boolFlag(args, 'baseline', true) && only === undefined;
9593
+ if (config.baseline !== undefined && only !== undefined && !boolFlag(args, 'json')) {
9594
+ console.log(c.dim(t.check.filesFromNoBaseline()));
9595
+ }
9388
9596
  let baselineOutcome: {
9389
9597
  comparison: BaselineComparison;
9390
9598
  breached: BaselineBreach[];
@@ -10729,6 +10937,9 @@ async function main(): Promise<void> {
10729
10937
  case 'rollup':
10730
10938
  await commandRollup(args, t);
10731
10939
  break;
10940
+ case 'position':
10941
+ await commandPosition(args, config, pricing, t);
10942
+ break;
10732
10943
  case 'pulse':
10733
10944
  await commandPulse(args, t);
10734
10945
  break;