@trazum/cli 1.80.0 → 1.81.0

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/src/i18n/es.ts CHANGED
@@ -1737,6 +1737,13 @@ ${bold('EJEMPLOS')}
1737
1737
  labelled: () => 'Etiquetado por carpeta de proyecto. Usa --no-label-from-project para dejarlo sin etiqueta, o --label <nombre> para poner una.',
1738
1738
  skipped: (other, unparseable, withoutUsage) => `Omitidas: ${other} línea(s) no-assistant (el resto del negocio del transcript), ${unparseable} imparseables, ${withoutUsage} línea(s) assistant sin usage.`,
1739
1739
  written: (file) => `Escrito ${file}.`,
1740
+ stateNeedsFile: () =>
1741
+ '--state lee un transcript, no una carpeta: el estado ata un desplazamiento del transcript a una longitud del fichero de salida, y varios transcripts escribiendo en una sola salida no tienen una longitud así. Apúntalo al fichero .jsonl.',
1742
+ stateNeedsOut: () => '--state necesita --out: sin fichero de salida no hay nada contra lo que reanudar.',
1743
+ resumed: (skipped, offset) =>
1744
+ skipped === 0
1745
+ ? `Transcript leído entero; punto de reanudación anotado en el byte ${offset}.`
1746
+ : `Reanudado en el byte ${skipped}, así que ${skipped} byte(s) no se releyeron. Siguiente punto de reanudación: byte ${offset}.`,
1740
1747
  },
1741
1748
 
1742
1749
  position: {
package/src/i18n/types.ts CHANGED
@@ -589,6 +589,12 @@ export interface CliMessages {
589
589
  labelled(): string;
590
590
  skipped(other: number, unparseable: number, withoutUsage: number): string;
591
591
  written(file: string): string;
592
+ /** `--state` was pointed at a folder, which it cannot resume. */
593
+ stateNeedsFile(): string;
594
+ /** `--state` with nowhere to append: the records were going to stdout. */
595
+ stateNeedsOut(): string;
596
+ /** How much of the transcript was skipped, and where the next run starts. */
597
+ resumed(skipped: number, offset: number): string;
592
598
  };
593
599
 
594
600
  position: {
package/src/index.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  #!/usr/bin/env node
2
+ import { createHash } from 'node:crypto';
2
3
  import { readdirSync, readFileSync } from 'node:fs';
3
4
  import { mkdir, mkdtemp, open, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
4
5
  import { cpus, tmpdir } from 'node:os';
@@ -352,6 +353,7 @@ const VALUE_FLAGS = new Set([
352
353
  'gpu-usd-hour',
353
354
  'tokens-per-second',
354
355
  'utilization',
356
+ 'state',
355
357
  ]);
356
358
 
357
359
  function parseArgs(argv: string[], t: CliMessages): Args {
@@ -674,7 +676,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
674
676
  schema: [],
675
677
  rollup: ['json', 'html-out'],
676
678
  position: ['json', 'html-out', 'pricing', 'pricing-live'],
677
- 'from-claude-code': ['label', 'label-from-project', 'out', 'o'],
679
+ 'from-claude-code': ['label', 'label-from-project', 'out', 'o', 'state'],
678
680
  'from-otel': ['label-from-service', 'out', 'o'],
679
681
  switch: ['to', 'migration-usd', 'cases'],
680
682
  ownrate: ['gpu-usd-hour', 'tokens-per-second', 'utilization'],
@@ -2600,6 +2602,122 @@ function projectLabelFor(file: string): string | undefined {
2600
2602
  return trimmed !== '' ? trimmed : folder;
2601
2603
  }
2602
2604
 
2605
+
2606
+ /**
2607
+ * `--state`: read the part of a transcript that is new since last time.
2608
+ *
2609
+ * A Claude Code transcript is append-only and can be enormous — the largest on
2610
+ * one real machine is 212 MB, and re-reading it to price the last thirty
2611
+ * seconds takes six and a half seconds. That is the whole cost of the status
2612
+ * line in `plugin/statusline`, and it is paid on every turn for a file whose
2613
+ * first two hundred megabytes cannot have changed.
2614
+ *
2615
+ * The state file ties three numbers together, and it is the third that makes
2616
+ * this exact rather than approximately right:
2617
+ *
2618
+ * - `offset`: where to start reading the transcript.
2619
+ * - `out`: how long the output file was when everything before `offset` had
2620
+ * been written. The tail after that is the last call as it looked last time,
2621
+ * and it is dropped and re-derived, because the converter's rule is that a
2622
+ * call arrives as several lines and the last one stands.
2623
+ * - `digest`: what the bytes just before `offset` were. A transcript that was
2624
+ * truncated, rotated or replaced would otherwise be resumed into the middle
2625
+ * of a different file, and the output would be a bill assembled from two
2626
+ * unrelated sessions. On a mismatch the whole thing is re-read, which is
2627
+ * slow and correct.
2628
+ */
2629
+ interface TranscriptState {
2630
+ schemaVersion: 1;
2631
+ files: Record<string, { offset: number; out: number; digest: string }>;
2632
+ }
2633
+
2634
+ /** How much of the run-up to `offset` is fingerprinted. */
2635
+ const STATE_DIGEST_BYTES = 4096;
2636
+
2637
+ const digestOf = (bytes: Buffer): string => createHash('sha256').update(bytes).digest('hex');
2638
+
2639
+ const readState = async (path: string): Promise<TranscriptState> => {
2640
+ try {
2641
+ const parsed: unknown = JSON.parse(await readFile(path, 'utf8'));
2642
+ if (
2643
+ typeof parsed === 'object' &&
2644
+ parsed !== null &&
2645
+ (parsed as TranscriptState).schemaVersion === 1 &&
2646
+ typeof (parsed as TranscriptState).files === 'object'
2647
+ ) {
2648
+ return parsed as TranscriptState;
2649
+ }
2650
+ } catch {
2651
+ // A missing, unreadable or unrecognised state file is a cold start, not an
2652
+ // error: the answer it produces is the same one, computed the slow way.
2653
+ }
2654
+ return { schemaVersion: 1, files: {} };
2655
+ };
2656
+
2657
+ /**
2658
+ * The byte offset of a line index within a chunk, counted in bytes rather than
2659
+ * characters.
2660
+ *
2661
+ * `String.prototype.split` counts UTF-16 code units and a transcript is UTF-8
2662
+ * with prompts in it, so a character index used as a byte offset would land
2663
+ * mid-sequence on the first accented character and corrupt every resume after
2664
+ * it. The newlines are found in the Buffer.
2665
+ */
2666
+ const byteOffsetOfLine = (chunk: Buffer, line: number): number => {
2667
+ if (line <= 0) return 0;
2668
+ let seen = 0;
2669
+ for (let i = 0; i < chunk.length; i += 1) {
2670
+ if (chunk[i] !== 0x0a) continue;
2671
+ seen += 1;
2672
+ if (seen === line) return i + 1;
2673
+ }
2674
+ return chunk.length;
2675
+ };
2676
+
2677
+ /** What a resumable read decided, so the caller can report it honestly. */
2678
+ interface ResumedRead {
2679
+ text: string;
2680
+ /** Bytes skipped because a previous run had already settled them. */
2681
+ skipped: number;
2682
+ /** Where the output must be truncated to before appending. */
2683
+ truncateOutTo: number;
2684
+ /** Records the previous run had settled, and this one must not re-emit. */
2685
+ chunkStart: number;
2686
+ }
2687
+
2688
+ const resumableRead = async (
2689
+ file: string,
2690
+ state: TranscriptState,
2691
+ ): Promise<{ chunk: Buffer; read: ResumedRead }> => {
2692
+ const key = resolvePath(file);
2693
+ const entry = state.files[key];
2694
+ const handle = await open(key, 'r');
2695
+ try {
2696
+ const { size } = await handle.stat();
2697
+ let start = 0;
2698
+ let truncateOutTo = 0;
2699
+
2700
+ if (entry !== undefined && entry.offset > 0 && entry.offset <= size) {
2701
+ const runUp = Math.min(STATE_DIGEST_BYTES, entry.offset);
2702
+ const before = Buffer.alloc(runUp);
2703
+ await handle.read(before, 0, runUp, entry.offset - runUp);
2704
+ if (digestOf(before) === entry.digest) {
2705
+ start = entry.offset;
2706
+ truncateOutTo = entry.out;
2707
+ }
2708
+ }
2709
+
2710
+ const chunk = Buffer.alloc(size - start);
2711
+ if (chunk.length > 0) await handle.read(chunk, 0, chunk.length, start);
2712
+ return {
2713
+ chunk,
2714
+ read: { text: chunk.toString('utf8'), skipped: start, truncateOutTo, chunkStart: start },
2715
+ };
2716
+ } finally {
2717
+ await handle.close();
2718
+ }
2719
+ };
2720
+
2603
2721
  async function commandFromClaudeCode(args: Args, t: CliMessages): Promise<void> {
2604
2722
  const target = args.positional[0];
2605
2723
  if (target === undefined) throw new Error(t.fromClaudeCode.noPath());
@@ -2639,6 +2757,28 @@ async function commandFromClaudeCode(args: Args, t: CliMessages): Promise<void>
2639
2757
  * says so.
2640
2758
  */
2641
2759
  const labelFromProject = boolFlag(args, 'label-from-project', info.isDirectory());
2760
+ /**
2761
+ * `--state` is for one transcript, deliberately.
2762
+ *
2763
+ * The state ties a transcript offset to a length of the output file, and
2764
+ * with several transcripts appending to one output there is no single length
2765
+ * that means "everything settled": the second file's records sit after the
2766
+ * first file's unsettled tail. A directory is re-read in full, which is what
2767
+ * it was doing before and is the right cost for a walk that is not a status
2768
+ * line refreshing every turn.
2769
+ */
2770
+ const statePath = stringFlag(args, 'state');
2771
+ if (statePath !== undefined && info.isDirectory()) throw new Error(t.fromClaudeCode.stateNeedsFile());
2772
+ if (statePath !== undefined && stringFlag(args, 'out') === undefined && stringFlag(args, 'o') === undefined) {
2773
+ throw new Error(t.fromClaudeCode.stateNeedsOut());
2774
+ }
2775
+ const state = statePath !== undefined ? await readState(statePath) : undefined;
2776
+ let resumed: ResumedRead | undefined;
2777
+ let chunk: Buffer | undefined;
2778
+ let resumeLine = 0;
2779
+ let settledRecords = 0;
2780
+ let settledOutBytes = 0;
2781
+
2642
2782
  const lines: string[] = [];
2643
2783
  let records = 0;
2644
2784
  let collapsed = 0;
@@ -2650,7 +2790,15 @@ async function commandFromClaudeCode(args: Args, t: CliMessages): Promise<void>
2650
2790
  let disagreements = 0;
2651
2791
  let synthetic = 0;
2652
2792
  for (const file of files) {
2653
- const text = await readFile(file, 'utf8');
2793
+ let text: string;
2794
+ if (state !== undefined) {
2795
+ const read = await resumableRead(file, state);
2796
+ chunk = read.chunk;
2797
+ resumed = read.read;
2798
+ text = read.read.text;
2799
+ } else {
2800
+ text = await readFile(file, 'utf8');
2801
+ }
2654
2802
  const projectLabel = labelFromProject ? projectLabelFor(file) : undefined;
2655
2803
  const conversion = claudeCodeRecords(text, {
2656
2804
  ...(label !== undefined
@@ -2660,6 +2808,8 @@ async function commandFromClaudeCode(args: Args, t: CliMessages): Promise<void>
2660
2808
  : {}),
2661
2809
  });
2662
2810
  for (const record of conversion.records) lines.push(JSON.stringify(record));
2811
+ resumeLine = conversion.resume.line;
2812
+ settledRecords = conversion.resume.records;
2663
2813
  records += conversion.records.length;
2664
2814
  collapsed += conversion.collapsed;
2665
2815
  noRequestId += conversion.noRequestId;
@@ -2673,12 +2823,57 @@ async function commandFromClaudeCode(args: Args, t: CliMessages): Promise<void>
2673
2823
 
2674
2824
  const out = stringFlag(args, 'out') ?? stringFlag(args, 'o');
2675
2825
  if (out !== undefined) {
2676
- await writeFile(out, lines.join('\n') + (lines.length > 0 ? '\n' : ''), 'utf8');
2826
+ if (statePath !== undefined) {
2827
+ /**
2828
+ * Append rather than rewrite, and drop the tail first.
2829
+ *
2830
+ * The tail is the last call as the previous run recorded it, and this
2831
+ * run has just re-derived it from its own first line. Truncating is what
2832
+ * makes the two runs add up to exactly one reading of the transcript
2833
+ * rather than one and a bit.
2834
+ */
2835
+ const handle = await open(out, resumed!.truncateOutTo > 0 ? 'r+' : 'w');
2836
+ try {
2837
+ await handle.truncate(resumed!.truncateOutTo);
2838
+ const body = lines.join('\n') + (lines.length > 0 ? '\n' : '');
2839
+ if (body !== '') await handle.write(body, resumed!.truncateOutTo, 'utf8');
2840
+ settledOutBytes =
2841
+ resumed!.truncateOutTo +
2842
+ lines
2843
+ .slice(0, settledRecords)
2844
+ .reduce((sum, line) => sum + Buffer.byteLength(line + '\n', 'utf8'), 0);
2845
+ } finally {
2846
+ await handle.close();
2847
+ }
2848
+ } else {
2849
+ await writeFile(out, lines.join('\n') + (lines.length > 0 ? '\n' : ''), 'utf8');
2850
+ }
2677
2851
  console.error(t.fromClaudeCode.written(out));
2678
2852
  } else {
2679
2853
  for (const line of lines) console.log(line);
2680
2854
  }
2681
2855
 
2856
+ if (statePath !== undefined) {
2857
+ const key = resolvePath(files[0]!);
2858
+ const nextOffset = resumed!.chunkStart + byteOffsetOfLine(chunk!, resumeLine);
2859
+ const runUp = Math.min(STATE_DIGEST_BYTES, nextOffset);
2860
+ const before = Buffer.alloc(runUp);
2861
+ if (runUp > 0) {
2862
+ const handle = await open(key, 'r');
2863
+ try {
2864
+ await handle.read(before, 0, runUp, nextOffset - runUp);
2865
+ } finally {
2866
+ await handle.close();
2867
+ }
2868
+ }
2869
+ const next: TranscriptState = {
2870
+ schemaVersion: 1,
2871
+ files: { [key]: { offset: nextOffset, out: settledOutBytes, digest: digestOf(before) } },
2872
+ };
2873
+ await writeFile(statePath, JSON.stringify(next, null, 2) + '\n', 'utf8');
2874
+ console.error(t.fromClaudeCode.resumed(resumed!.skipped, nextOffset));
2875
+ }
2876
+
2682
2877
  console.error(t.fromClaudeCode.summary(files.length, records));
2683
2878
  if (collapsed > 0) console.error(t.fromClaudeCode.collapsed(collapsed));
2684
2879
  if (streamed > 0) console.error(t.fromClaudeCode.streamed(streamed));