@shipfox/client-logs 3.0.1 → 5.0.0

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

@@ -1,4 +1,4 @@
-import type {LogRecord} from '@shipfox/api-logs-dto';
+import type {LogRecord} from './log-model.js';
 import {buildLogTree, type GroupLogNode, type LogNode, stripTrailingNewline} from './log-tree.js';
 
 const out = (data: string, stream: 'stdout' | 'stderr' = 'stdout', ts = 0): LogRecord => ({
@@ -17,27 +17,27 @@ const gstart = (
   v: 1,
   ts,
   type: 'group_start',
-  group_id: groupId,
-  parent_group_id: parentGroupId,
+  groupId,
+  parentGroupId,
   name,
 });
 const gend = (groupId: string, ts = 0): LogRecord => ({
   v: 1,
   ts,
   type: 'group_end',
-  group_id: groupId,
+  groupId,
 });
 const end = (totalBytes = 0, ts = 0): LogRecord => ({
   v: 1,
   ts,
   type: 'end',
-  total_bytes: totalBytes,
+  totalBytes,
 });
 const gap = (droppedBytes = 0, ts = 0): LogRecord => ({
   v: 1,
   ts,
   type: 'gap',
-  dropped_bytes: droppedBytes,
+  droppedBytes,
 });
 const capped = (ts = 0): LogRecord => ({v: 1, ts, type: 'capped'});
 const runnerLost = (ts = 0): LogRecord => ({v: 1, ts, type: 'runner_lost'});
@@ -114,8 +114,8 @@ describe('buildLogTree', () => {
     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(g1.record.groupId).toBe('g1');
+    expect(g2.record.groupId).toBe('g2');
     expect(g2.children[0]?.kind).toBe('output');
   });
 
@@ -224,10 +224,10 @@ describe('buildLogTree', () => {
     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.record.groupId).toBe('g2');
     expect(g2.closed).toBe(true);
     expect(g2.endTs).toBeNull();
-    expect(g3.record.group_id).toBe('g3');
+    expect(g3.record.groupId).toBe('g3');
     expect(g3.closed).toBe(true);
   });
 

package/src/core/log-tree.ts

@@ -1,4 +1,4 @@
-import type {LogRecord} from '@shipfox/api-logs-dto';
+import type {LogRecord} from './log-model.js';
 
 /**
  * Pure render transform for the step-log read stream. The runner emits a flat,
@@ -119,11 +119,11 @@ export function buildLogTree(records: readonly LogRecord[]): LogTree {
         // 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;
+        const parentId = record.parentGroupId;
         let parentIndex = -1;
         if (parentId !== null) {
           for (let i = stack.length - 1; i >= 0; i -= 1) {
-            if (stack[i]?.record.group_id === parentId) {
+            if (stack[i]?.record.groupId === parentId) {
               parentIndex = i;
               break;
             }
@@ -154,7 +154,7 @@ export function buildLogTree(records: readonly LogRecord[]): LogTree {
         // 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) {
+          if (stack[i]?.record.groupId === record.groupId) {
             matchIndex = i;
             break;
           }

package/src/hooks/api/log-mapper.test.ts

@@ -0,0 +1,56 @@
+import {parseLogNdjson, toLogRead} from './log-mapper.js';
+
+const outputLine = (data: string, ts = 1): string =>
+  `${JSON.stringify({v: 1, ts, type: 'output', stream: 'stdout', data})}\n`;
+
+describe('parseLogNdjson', () => {
+  test('validates and maps records to package-owned camel-case fields', () => {
+    const records = parseLogNdjson(
+      `${JSON.stringify({
+        v: 1,
+        ts: 1,
+        type: 'group_start',
+        group_id: 'build',
+        parent_group_id: null,
+        name: 'Build',
+      })}\r\n${outputLine('done\n', 2)}`,
+    );
+
+    expect(records).toEqual([
+      {
+        v: 1,
+        ts: 1,
+        type: 'group_start',
+        groupId: 'build',
+        parentGroupId: null,
+        name: 'Build',
+      },
+      {v: 1, ts: 2, type: 'output', stream: 'stdout', data: 'done\n'},
+    ]);
+  });
+
+  test('rejects an invalid external record before a snapshot can be merged', () => {
+    expect(() => parseLogNdjson('{"v":1,"ts":1,"type":"nope"}\n')).toThrow();
+  });
+});
+
+describe('toLogRead', () => {
+  test('maps response envelopes to camel-case domain fields', () => {
+    expect(
+      toLogRead({
+        mode: 'presigned',
+        url: 'https://storage.example.test/logs/object?sig=1',
+        state: 'closed',
+        expires_at: '2026-06-23T10:00:00.000Z',
+        total_bytes: 128,
+        truncated: false,
+      }),
+    ).toEqual({
+      mode: 'presigned',
+      url: 'https://storage.example.test/logs/object?sig=1',
+      expiresAt: '2026-06-23T10:00:00.000Z',
+      totalBytes: 128,
+      truncated: false,
+    });
+  });
+});

package/src/hooks/api/log-mapper.ts

@@ -0,0 +1,75 @@
+import {
+  type LogRecord as LogRecordDto,
+  parseLogRecordLine,
+  type ReadLogsResponseDto,
+} from '@shipfox/api-logs-dto';
+import type {InlineLogRead, LogRecord, PresignedLogRead, SessionViewRow} from '#core/log-model.js';
+
+const NDJSON_LINE_BREAK = /\r?\n/;
+
+export function toLogRead(response: ReadLogsResponseDto): InlineLogRead | PresignedLogRead {
+  if (response.mode === 'presigned') {
+    return {
+      mode: 'presigned',
+      url: response.url,
+      expiresAt: response.expires_at,
+      totalBytes: response.total_bytes,
+      truncated: response.truncated,
+    };
+  }
+
+  return {
+    mode: 'inline',
+    ndjson: response.ndjson,
+    nextCursor: response.next_cursor,
+    hasMore: response.has_more,
+    state: response.state,
+    truncated: response.truncated,
+  };
+}
+
+/**
+ * The compacted object is fetched from a presigned external URL, so every line is
+ * validated at this boundary before it can enter the package-owned query snapshot.
+ */
+export function parseLogNdjson(ndjson: string): LogRecord[] {
+  return ndjson
+    .split(NDJSON_LINE_BREAK)
+    .filter((line) => line.length > 0)
+    .map((line) => toLogRecord(parseLogRecordLine(line)));
+}
+
+export function toLogRecord(record: LogRecordDto): LogRecord {
+  const base: {v: 1; ts: number} = {v: record.v, ts: record.ts};
+  switch (record.type) {
+    case 'output':
+      return {...base, type: record.type, stream: record.stream, data: record.data};
+    case 'group_start':
+      return {
+        ...base,
+        type: record.type,
+        groupId: record.group_id,
+        parentGroupId: record.parent_group_id,
+        name: record.name,
+      };
+    case 'group_end':
+      return {...base, type: record.type, groupId: record.group_id};
+    case 'end':
+      return {...base, type: record.type, totalBytes: record.total_bytes};
+    case 'gap':
+      return {...base, type: record.type, droppedBytes: record.dropped_bytes};
+    case 'agent_session':
+      return {...base, type: record.type, row: toSessionViewRow(record.row)};
+    case 'capped':
+    case 'runner_lost':
+      return {...base, type: record.type};
+  }
+}
+
+function toSessionViewRow(
+  row: Extract<LogRecordDto, {type: 'agent_session'}>['row'],
+): SessionViewRow {
+  return row.kind === 'message' || row.kind === 'lifecycle'
+    ? {...row, meta: row.meta.map((meta) => ({...meta}))}
+    : {...row};
+}

package/src/hooks/api/step-logs.test.ts

@@ -45,7 +45,14 @@ describe('readStepAttemptLogsPage', () => {
     });
 
     const url = new URL(requestFrom(fetchImpl).url);
-    expect(result).toEqual(body);
+    expect(result).toEqual({
+      mode: 'inline',
+      ndjson: '',
+      nextCursor: 8,
+      hasMore: false,
+      state: 'open',
+      truncated: false,
+    });
     expect(url.pathname).toBe('/steps/11111111-1111-4111-8111-111111111111/attempts/2/logs');
     expect(url.searchParams.get('cursor')).toBe('7');
     expect(requestFrom(fetchImpl).method).toBe('GET');
@@ -63,4 +70,17 @@ describe('readStepAttemptLogsPage', () => {
 
     await expect(result).rejects.toMatchObject({code: 'not-found', status: 404});
   });
+
+  test('rejects an invalid response envelope before it can advance a cached cursor', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({mode: 'inline', next_cursor: 8}));
+    configureApiClient({fetchImpl});
+
+    const result = readStepAttemptLogsPage({
+      stepId: '11111111-1111-4111-8111-111111111111',
+      attempt: 1,
+      cursor: 7,
+    });
+
+    await expect(result).rejects.toMatchObject({code: 'invalid-response'});
+  });
 });

package/src/hooks/api/step-logs.ts

@@ -1,5 +1,5 @@
-import type {ReadLogsResponseDto} from '@shipfox/api-logs-dto';
-import {ApiError, apiRequest} from '@shipfox/client-api';
+import {readLogsResponseSchema} from '@shipfox/api-logs-dto';
+import {ApiError, checkedApiRequest} from '@shipfox/client-api';
 import {useQuery, useQueryClient} from '@tanstack/react-query';
 import {useRef} from 'react';
 import {
@@ -8,6 +8,7 @@ import {
   type StepLogSnapshot,
   stepLogRefetchInterval,
 } from '#core/log-read.js';
+import {parseLogNdjson, toLogRead} from './log-mapper.js';
 
 export const stepLogsQueryKeys = {
   all: ['step-logs'] as const,
@@ -27,12 +28,14 @@ export async function readStepAttemptLogsPage({
   attempt,
   cursor,
   signal,
-}: ReadStepAttemptLogsPageParams): Promise<ReadLogsResponseDto> {
+}: ReadStepAttemptLogsPageParams) {
   const params = new URLSearchParams({cursor: String(cursor)});
-  return await apiRequest<ReadLogsResponseDto>(
+  const response = await checkedApiRequest(
+    readLogsResponseSchema,
     `/steps/${encodeURIComponent(stepId)}/attempts/${attempt}/logs?${params.toString()}`,
     {signal},
   );
+  return toLogRead(response);
 }
 
 class StepLogObjectFetchError extends Error {
@@ -63,6 +66,12 @@ export interface UseStepAttemptLogsQueryOptions {
   initialErrorRetryDelayMs?: number;
 }
 
+/**
+ * Narrow React Query wrapper for step logs. Its query function can read the prior
+ * snapshot imperatively, but bounded missing-stream retries need a ref that resets
+ * when the step, attempt, or retry budget changes. Keep that lifecycle state here
+ * rather than exporting query options that could accidentally share it between views.
+ */
 export function useStepAttemptLogsQuery(
   stepId: string | undefined,
   attempt: number | undefined,
@@ -93,7 +102,7 @@ export function useStepAttemptLogsQuery(
     enabled,
     queryFn: async ({signal}) => {
       const previous = queryClient.getQueryData<StepLogSnapshot>(queryKey);
-      let response: ReadLogsResponseDto;
+      let response: Awaited<ReturnType<typeof readStepAttemptLogsPage>>;
       try {
         response = await readStepAttemptLogsPage({
           stepId: stepId ?? '',
@@ -121,10 +130,18 @@ export function useStepAttemptLogsQuery(
 
       if (response.mode === 'presigned') {
         const ndjson = await readPresignedLogObject(response.url, signal);
-        return mergeLogRead(previous, {mode: 'presigned', response, ndjson});
+        return mergeLogRead(previous, {
+          mode: 'presigned',
+          response,
+          records: parseLogNdjson(ndjson),
+        });
       }
 
-      return mergeLogRead(previous, {mode: 'inline', response});
+      return mergeLogRead(previous, {
+        mode: 'inline',
+        response,
+        records: parseLogNdjson(response.ndjson),
+      });
     },
     retry: (failureCount, error) => {
       if (initialErrorRetryCount <= 0) return false;

package/src/index.ts

@@ -1,3 +1,10 @@
+export type {
+  LogRecord,
+  LogSource,
+  LogState,
+  SessionViewRow,
+  SessionViewRowMeta,
+} from '#core/log-model.js';
 export type {StepLogSnapshot} from '#core/log-read.js';
 export {
   buildLogTree,