@shipfox/client-logs 0.2.0

package/src/core/log-tree.test.ts

@@ -0,0 +1,380 @@
+import type {LogRecord} from '@shipfox/api-logs-dto';
+import {buildLogTree, type GroupLogNode, type LogNode, stripTrailingNewline} from './log-tree.js';
+
+const out = (data: string, stream: 'stdout' | 'stderr' = 'stdout', ts = 0): LogRecord => ({
+  v: 1,
+  ts,
+  type: 'output',
+  stream,
+  data,
+});
+const gstart = (
+  groupId: string,
+  name: string,
+  parentGroupId: string | null = null,
+  ts = 0,
+): LogRecord => ({
+  v: 1,
+  ts,
+  type: 'group_start',
+  group_id: groupId,
+  parent_group_id: parentGroupId,
+  name,
+});
+const gend = (groupId: string, ts = 0): LogRecord => ({
+  v: 1,
+  ts,
+  type: 'group_end',
+  group_id: groupId,
+});
+const end = (totalBytes = 0, ts = 0): LogRecord => ({
+  v: 1,
+  ts,
+  type: 'end',
+  total_bytes: totalBytes,
+});
+const gap = (droppedBytes = 0, ts = 0): LogRecord => ({
+  v: 1,
+  ts,
+  type: 'gap',
+  dropped_bytes: droppedBytes,
+});
+const capped = (ts = 0): LogRecord => ({v: 1, ts, type: 'capped'});
+const runnerLost = (ts = 0): LogRecord => ({v: 1, ts, type: 'runner_lost'});
+const agentSession = (
+  row: Extract<LogRecord, {type: 'agent_session'}>['row'] = {
+    kind: 'raw',
+    timestamp: 0,
+    label: 'entry',
+    raw: 'entry',
+  },
+  ts = 0,
+): LogRecord => ({
+  v: 1,
+  ts,
+  type: 'agent_session',
+  row: {...row, timestamp: ts},
+});
+
+const asGroup = (node: LogNode | undefined): GroupLogNode => {
+  if (node?.kind !== 'group') throw new Error(`expected a group node, got ${node?.kind}`);
+  return node;
+};
+
+describe('buildLogTree', () => {
+  test('numbers flat output lines and counts them', () => {
+    const records = [out('a'), out('b'), out('c')];
+
+    const tree = buildLogTree(records);
+
+    expect(tree.nodes.map((n) => (n.kind === 'output' ? n.lineNumber : null))).toEqual([1, 2, 3]);
+    expect(tree.lineCount).toBe(3);
+    expect(tree.terminated).toBe(false);
+  });
+
+  test('reads originTs from the first record and null when empty', () => {
+    const withRecords = buildLogTree([out('a', 'stdout', 42)]);
+    const empty = buildLogTree([]);
+
+    expect(withRecords.originTs).toBe(42);
+    expect(empty.originTs).toBeNull();
+    expect(empty.nodes).toEqual([]);
+    expect(empty.lineCount).toBe(0);
+  });
+
+  test('anchors originTs on the first agent_session record', () => {
+    const tree = buildLogTree([agentSession(undefined, 5), out('a', 'stdout', 9)]);
+
+    expect(tree.originTs).toBe(5);
+  });
+
+  test('nests output inside a closed group', () => {
+    const records = [gstart('g1', 'Build'), out('compiling'), gend('g1', 9)];
+
+    const tree = buildLogTree(records);
+    const group = asGroup(tree.nodes[0]);
+
+    expect(tree.nodes).toHaveLength(1);
+    expect(group.record.name).toBe('Build');
+    expect(group.closed).toBe(true);
+    expect(group.endTs).toBe(9);
+    expect(group.children).toHaveLength(1);
+  });
+
+  test('builds a multi-level group tree', () => {
+    const records = [
+      gstart('g1', 'Build'),
+      gstart('g2', 'Compile', 'g1'),
+      out('cc'),
+      gend('g2'),
+      gend('g1'),
+    ];
+
+    const tree = buildLogTree(records);
+    const g1 = asGroup(tree.nodes[0]);
+    const g2 = asGroup(g1.children[0]);
+
+    expect(g1.record.group_id).toBe('g1');
+    expect(g2.record.group_id).toBe('g2');
+    expect(g2.children[0]?.kind).toBe('output');
+  });
+
+  test('precomputes the subtree output-line count per group', () => {
+    const records = [
+      gstart('g1', 'Build'),
+      out('a'),
+      gstart('g2', 'Compile', 'g1'),
+      out('b'),
+      out('c'),
+      gend('g2'),
+      gend('g1'),
+    ];
+
+    const g1 = asGroup(buildLogTree(records).nodes[0]);
+    const g2 = asGroup(g1.children[1]);
+
+    expect(g1.lineCount).toBe(3);
+    expect(g2.lineCount).toBe(2);
+  });
+
+  test('leaves a group open when its end never arrives', () => {
+    const records = [gstart('g1', 'Build'), out('still going')];
+
+    const tree = buildLogTree(records);
+    const group = asGroup(tree.nodes[0]);
+
+    expect(group.closed).toBe(false);
+    expect(group.endTs).toBeNull();
+  });
+
+  test('ignores an unbalanced group_end with no open group', () => {
+    const records = [out('a'), gend('ghost'), out('b')];
+
+    const tree = buildLogTree(records);
+
+    expect(tree.nodes.map((n) => n.kind)).toEqual(['output', 'output']);
+  });
+
+  test('closes the matching group_id when a group_start was dropped (C1)', () => {
+    const records = [gstart('g1', 'Build'), out('inside g1'), gend('g2'), gend('g1', 5)];
+
+    const tree = buildLogTree(records);
+    const g1 = asGroup(tree.nodes[0]);
+
+    expect(tree.nodes).toHaveLength(1);
+    expect(g1.closed).toBe(true);
+    expect(g1.endTs).toBe(5);
+    expect(g1.children.map((n) => n.kind)).toEqual(['output']);
+  });
+
+  test('orphaned inner groups close with their matched ancestor', () => {
+    const records = [gstart('g1', 'Build'), gstart('g2', 'Compile', 'g1'), out('x'), gend('g1', 7)];
+
+    const tree = buildLogTree(records);
+    const g1 = asGroup(tree.nodes[0]);
+    const g2 = asGroup(g1.children[0]);
+
+    expect(g1.closed).toBe(true);
+    expect(g1.endTs).toBe(7);
+    expect(g2.closed).toBe(true);
+    expect(g2.endTs).toBeNull();
+  });
+
+  test('a dropped root group_end does not nest or taint the next root group', () => {
+    // g1's group_end is dropped under backlog pressure (a gap stands in for it); g2 declares
+    // parent_group_id null, so it lands at root, not inside still-open g1. g1 is orphan-closed
+    // when g2 opens, so a runner_lost inside g2 must not bubble into the already-closed g1.
+    const records = [
+      gstart('g1', 'first'),
+      out('a'),
+      gap(64),
+      gstart('g2', 'second'),
+      runnerLost(),
+      gend('g2'),
+    ];
+
+    const tree = buildLogTree(records);
+    const g1 = asGroup(tree.nodes[0]);
+    const g2 = asGroup(tree.nodes[1]);
+
+    expect(tree.nodes).toHaveLength(2);
+    expect(g1.closed).toBe(true);
+    expect(g1.endTs).toBeNull();
+    expect(g1.lineCount).toBe(1);
+    expect(g1.hasError).toBe(false);
+    expect(g2.hasError).toBe(true);
+  });
+
+  test('a dropped inner group_end reparents the next sibling via parent_group_id', () => {
+    // g2's group_end is dropped; g3 declares parent g1, so it is a sibling of g2 under g1,
+    // not nested inside the still-open g2.
+    const records = [
+      gstart('g1', 'outer'),
+      gstart('g2', 'inner-a', 'g1'),
+      out('x'),
+      gstart('g3', 'inner-b', 'g1'),
+      out('y'),
+      gend('g3'),
+      gend('g1', 9),
+    ];
+
+    const tree = buildLogTree(records);
+    const g1 = asGroup(tree.nodes[0]);
+
+    expect(g1.children.map((n) => n.kind)).toEqual(['group', 'group']);
+    const g2 = asGroup(g1.children[0]);
+    const g3 = asGroup(g1.children[1]);
+    expect(g2.record.group_id).toBe('g2');
+    expect(g2.closed).toBe(true);
+    expect(g2.endTs).toBeNull();
+    expect(g3.record.group_id).toBe('g3');
+    expect(g3.closed).toBe(true);
+  });
+
+  test('places markers at the current nesting level', () => {
+    const records = [gstart('g1', 'Build'), gap(128), gend('g1'), end(2048)];
+
+    const tree = buildLogTree(records);
+    const g1 = asGroup(tree.nodes[0]);
+
+    expect(g1.children[0]?.kind).toBe('marker');
+    expect(tree.nodes[1]?.kind).toBe('marker');
+  });
+
+  test('assigns a unique seq across siblings that reuse a group_id or marker ts', () => {
+    // A concatenated multi-step/retry stream reuses g1 and can repeat a marker (type, ts);
+    // seq stays unique so the React keys in LogView never collide.
+    const records = [
+      gstart('g1', 'first'),
+      gend('g1'),
+      gstart('g1', 'second'),
+      gend('g1'),
+      gap(1, 5),
+      gap(2, 5),
+    ];
+
+    const seqs = buildLogTree(records).nodes.map((n) => n.seq);
+
+    expect(seqs).toEqual([0, 1, 2, 3]);
+  });
+
+  test('emits agent_session nodes without consuming a line number', () => {
+    const records = [out('a'), agentSession(), out('b')];
+
+    const tree = buildLogTree(records);
+
+    expect(tree.nodes.map((node) => node.kind)).toEqual(['output', 'session', 'output']);
+    expect(tree.nodes.flatMap((n) => (n.kind === 'output' ? [n.lineNumber] : []))).toEqual([1, 2]);
+  });
+
+  test('keeps stdout between a tool call and tool result in stream order', () => {
+    const toolCall = agentSession(
+      {kind: 'tool-call', timestamp: 1, id: 'call-1', name: 'edit_file', input: '{}'},
+      1,
+    );
+    const toolResult = agentSession(
+      {
+        kind: 'tool-result',
+        timestamp: 3,
+        toolCallId: 'call-1',
+        toolName: 'edit_file',
+        output: 'done',
+        isError: false,
+      },
+      3,
+    );
+
+    const tree = buildLogTree([toolCall, out('interleaved\n', 'stdout', 2), toolResult]);
+
+    expect(tree.nodes.map((node) => node.kind)).toEqual(['session', 'output', 'session']);
+  });
+
+  test.each([
+    ['end', [end()], true],
+    ['runner_lost', [runnerLost()], true],
+    ['capped', [capped()], false],
+    ['none', [out('a')], false],
+  ])('terminated is %s-driven', (_label, records, expected) => {
+    const tree = buildLogTree(records as LogRecord[]);
+
+    expect(tree.terminated).toBe(expected);
+  });
+
+  describe('hasError annotation', () => {
+    test('a runner_lost marker in a group sets hasError', () => {
+      const records = [gstart('g1', 'Run'), runnerLost(), gend('g1')];
+
+      const group = asGroup(buildLogTree(records).nodes[0]);
+
+      expect(group.hasError).toBe(true);
+    });
+
+    test('stderr does NOT set hasError (a channel, not a failure)', () => {
+      const records = [gstart('g1', 'Run'), out('boom', 'stderr'), gend('g1')];
+
+      const group = asGroup(buildLogTree(records).nodes[0]);
+
+      expect(group.hasError).toBe(false);
+    });
+
+    test('gap and capped are warnings, not errors', () => {
+      const records = [gstart('g1', 'Run'), gap(64), capped(), gend('g1')];
+
+      const group = asGroup(buildLogTree(records).nodes[0]);
+
+      expect(group.hasError).toBe(false);
+    });
+
+    test('a runner_lost bubbles up through nested ancestors', () => {
+      const records = [
+        gstart('g1', 'Build'),
+        gstart('g2', 'Compile', 'g1'),
+        runnerLost(),
+        gend('g2'),
+        gend('g1'),
+      ];
+
+      const g1 = asGroup(buildLogTree(records).nodes[0]);
+      const g2 = asGroup(g1.children[0]);
+
+      expect(g1.hasError).toBe(true);
+      expect(g2.hasError).toBe(true);
+    });
+
+    test('a closed sibling is not marked by a later runner_lost', () => {
+      const records = [
+        gstart('g1', 'first'),
+        out('ok'),
+        gend('g1'),
+        gstart('g2', 'second'),
+        runnerLost(),
+        gend('g2'),
+      ];
+
+      const tree = buildLogTree(records);
+      const g1 = asGroup(tree.nodes[0]);
+      const g2 = asGroup(tree.nodes[1]);
+
+      expect(g1.hasError).toBe(false);
+      expect(g2.hasError).toBe(true);
+    });
+  });
+});
+
+describe('stripTrailingNewline', () => {
+  test('removes a single trailing newline', () => {
+    expect(stripTrailingNewline('line\n')).toBe('line');
+  });
+
+  test('leaves a line without a trailing newline untouched', () => {
+    expect(stripTrailingNewline('line')).toBe('line');
+  });
+
+  test('removes only one of several trailing newlines', () => {
+    expect(stripTrailingNewline('line\n\n')).toBe('line\n');
+  });
+
+  test('strips a trailing CRLF, leaving no carriage return', () => {
+    expect(stripTrailingNewline('line\r\n')).toBe('line');
+  });
+});

package/src/core/log-tree.ts

@@ -0,0 +1,200 @@
+import type {LogRecord} from '@shipfox/api-logs-dto';
+
+/**
+ * Pure render transform for the step-log read stream. The runner emits a flat,
+ * ordered NDJSON record list; `group_start`/`group_end` form a tree that the
+ * reader reconstructs here before rendering. No React, no state — one function
+ * over the record array.
+ *
+ *   records[] ──▶ buildLogTree ──▶ { nodes (forest), terminated, originTs, lineCount }
+ *
+ * Group closing matches `group_id` (not a blind top-of-stack pop) so a stream that
+ * drops a `group_start` under backlog/gap pressure but still delivers its
+ * `group_end` does not mis-nest everything after it.
+ */
+
+export type OutputLogRecord = Extract<LogRecord, {type: 'output'}>;
+export type GroupStartLogRecord = Extract<LogRecord, {type: 'group_start'}>;
+export type EndLogRecord = Extract<LogRecord, {type: 'end'}>;
+export type GapLogRecord = Extract<LogRecord, {type: 'gap'}>;
+export type CappedLogRecord = Extract<LogRecord, {type: 'capped'}>;
+export type RunnerLostLogRecord = Extract<LogRecord, {type: 'runner_lost'}>;
+export type AgentSessionLogRecord = Extract<LogRecord, {type: 'agent_session'}>;
+export type MarkerLogRecord = EndLogRecord | GapLogRecord | CappedLogRecord | RunnerLostLogRecord;
+
+/**
+ * Stable, unique render key in creation order. A natural key is not enough: `group_id`
+ * and a marker's `(type, ts)` can both repeat among siblings once a consumer feeds a
+ * concatenated multi-step/retry stream (or two markers land in the same millisecond),
+ * and the append-only build order keeps `seq` stable across re-renders.
+ */
+export interface LogNodeBase {
+  seq: number;
+}
+
+export interface OutputLogNode extends LogNodeBase {
+  kind: 'output';
+  lineNumber: number;
+  record: OutputLogRecord;
+}
+
+export interface MarkerLogNode extends LogNodeBase {
+  kind: 'marker';
+  record: MarkerLogRecord;
+}
+
+export interface GroupLogNode extends LogNodeBase {
+  kind: 'group';
+  record: GroupStartLogRecord;
+  /** False when no matching `group_end` arrived (still streaming, or truncated). */
+  closed: boolean;
+  /** `group_end` timestamp when closed by its matching end, else null. */
+  endTs: number | null;
+  /** Precomputed: subtree contains a `runner_lost` (a genuine failure). `stderr` is a channel, not an error, so it never sets this. */
+  hasError: boolean;
+  /** Precomputed output-line count in the subtree, for the collapsed summary. */
+  lineCount: number;
+  children: LogNode[];
+}
+
+export interface SessionLogNode extends LogNodeBase {
+  kind: 'session';
+  record: AgentSessionLogRecord;
+}
+
+export type LogNode = OutputLogNode | MarkerLogNode | GroupLogNode | SessionLogNode;
+
+export interface LogTree {
+  nodes: LogNode[];
+  /** The stream is closed: the records contain an `end` or a `runner_lost`. */
+  terminated: boolean;
+  /** First record's timestamp; the baseline for relative timestamps. Null when empty. */
+  originTs: number | null;
+  /** Physical output lines (one per `output` record in v1); drives the end banner. */
+  lineCount: number;
+}
+
+const TRAILING_NEWLINE = /\r?\n$/;
+
+/** Strips a single trailing line ending (CRLF or LF) so a line-framed record renders without a blank continuation. */
+export function stripTrailingNewline(data: string): string {
+  return data.replace(TRAILING_NEWLINE, '');
+}
+
+export function assertNever(value: never): never {
+  throw new Error(`unexpected log record type: ${JSON.stringify(value)}`);
+}
+
+export function buildLogTree(records: readonly LogRecord[]): LogTree {
+  const nodes: LogNode[] = [];
+  const stack: GroupLogNode[] = [];
+  let seq = 0;
+  let lineNumber = 0;
+  let lineCount = 0;
+  let terminated = false;
+  let originTs: number | null = null;
+
+  const childrenOf = (): LogNode[] => stack[stack.length - 1]?.children ?? nodes;
+
+  // Bubble a failure signal (a runner_lost only) to every currently-open ancestor group
+  // in one pass, so `hasError` is read in O(1) at render time instead of re-walking subtrees.
+  const markOpenGroupsError = (): void => {
+    for (const frame of stack) frame.hasError = true;
+  };
+
+  for (const record of records) {
+    if (originTs === null) originTs = record.ts;
+    switch (record.type) {
+      case 'output': {
+        lineNumber += 1;
+        lineCount += 1;
+        for (const frame of stack) frame.lineCount += 1;
+        childrenOf().push({kind: 'output', seq: seq++, lineNumber, record});
+        break;
+      }
+      case 'group_start': {
+        // Reconcile the open stack to the declared parent before nesting. `parent_group_id`
+        // is the runner's stack top at emit time (null at the root), so any reader frame
+        // below that parent (or every open frame, when the parent is root) is a group whose
+        // own `group_end` was dropped under backlog pressure. Orphan-close those frames so a
+        // dropped end never mis-parents the groups that follow. A parent whose own start was
+        // dropped is not on the stack: it falls through to best-effort root placement.
+        const parentId = record.parent_group_id;
+        let parentIndex = -1;
+        if (parentId !== null) {
+          for (let i = stack.length - 1; i >= 0; i -= 1) {
+            if (stack[i]?.record.group_id === parentId) {
+              parentIndex = i;
+              break;
+            }
+          }
+        }
+        for (let i = stack.length - 1; i > parentIndex; i -= 1) {
+          const frame = stack[i];
+          if (frame) frame.closed = true;
+        }
+        stack.length = parentIndex + 1;
+
+        const group: GroupLogNode = {
+          kind: 'group',
+          seq: seq++,
+          record,
+          closed: false,
+          endTs: null,
+          hasError: false,
+          lineCount: 0,
+          children: [],
+        };
+        childrenOf().push(group);
+        stack.push(group);
+        break;
+      }
+      case 'group_end': {
+        // Close the matching open group_id; any inner frames orphaned by a dropped
+        // group_end close with it. An end with no matching open start is ignored.
+        let matchIndex = -1;
+        for (let i = stack.length - 1; i >= 0; i -= 1) {
+          if (stack[i]?.record.group_id === record.group_id) {
+            matchIndex = i;
+            break;
+          }
+        }
+        if (matchIndex !== -1) {
+          for (let i = stack.length - 1; i >= matchIndex; i -= 1) {
+            const frame = stack[i];
+            if (frame) frame.closed = true;
+          }
+          const matched = stack[matchIndex];
+          if (matched) matched.endTs = record.ts;
+          stack.length = matchIndex;
+        }
+        break;
+      }
+      case 'end':
+      case 'gap':
+      case 'capped': {
+        if (record.type === 'end') terminated = true;
+        childrenOf().push({kind: 'marker', seq: seq++, record});
+        break;
+      }
+      case 'runner_lost': {
+        terminated = true;
+        childrenOf().push({kind: 'marker', seq: seq++, record});
+        markOpenGroupsError();
+        break;
+      }
+      case 'agent_session':
+        childrenOf().push({kind: 'session', seq: seq++, record});
+        break;
+      default:
+        assertNever(record);
+    }
+  }
+
+  return {
+    nodes,
+    terminated,
+    originTs,
+    lineCount,
+  };
+}

package/src/env.d.ts

@@ -0,0 +1,7 @@
+interface ImportMetaEnv {
+  readonly DEV: boolean;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}