@shipfox/client-logs 0.2.0

package/src/components/system-markers.tsx

@@ -0,0 +1,148 @@
+import {Icon, type IconName} from '@shipfox/react-ui/icon';
+import {LogContent, LogRow} from '@shipfox/react-ui/log';
+import {cn, formatBytes, formatDuration} from '@shipfox/react-ui/utils';
+import type {
+  CappedLogRecord,
+  EndLogRecord,
+  GapLogRecord,
+  RunnerLostLogRecord,
+} from '#core/log-tree.js';
+
+type MarkerTone = 'default' | 'warning' | 'error';
+
+const toneText: Record<MarkerTone, string> = {
+  default: 'text-foreground-neutral-muted',
+  warning: 'text-orange-600 dark:text-orange-400',
+  error: 'text-red-600 dark:text-red-400',
+};
+
+interface LogMarkerRowProps {
+  icon: IconName;
+  tone: MarkerTone;
+  timestamp?: Date | null;
+  /** Plain-language clause after the label: what it means / what to do. */
+  detail?: string;
+  /** Right-aligned `font-code` figures (bytes, line count, duration). */
+  meta?: string;
+  terminalFailure?: boolean;
+  children: string;
+}
+
+/**
+ * Shared timeline-marker row: a non-numbered line with a leading icon, a bold label, an
+ * optional plain-language detail clause, a dashed divider, and optional right-aligned
+ * monospace figures. The detail explains the consequence to the operator (the label
+ * names the event, the icon/tone carry severity), so the copy reads helpfully rather
+ * than mechanically.
+ */
+function LogMarkerRow({
+  icon,
+  tone,
+  timestamp = null,
+  detail,
+  meta,
+  terminalFailure = false,
+  children,
+}: LogMarkerRowProps) {
+  return (
+    <LogRow
+      lineNumber={null}
+      timestamp={timestamp}
+      tone={tone}
+      data-log-terminal-failure={terminalFailure ? 'true' : undefined}
+    >
+      <LogContent className={cn('block', toneText[tone])}>
+        <span className="inline-flex w-full items-center gap-8">
+          <Icon name={icon} className="size-14 flex-none" aria-hidden="true" />
+          {/* Label, detail, and figures share one text cluster joined by a literal
+              " · ". Flex `gap` is visual only and would copy with no separator, so the
+              separators are real inline text. The dashed rule trails after the text
+              (an aria-hidden flex filler) and contributes nothing to a selection. */}
+          <span className="min-w-0">
+            <span className="font-medium">{children}</span>
+            {detail != null && (
+              <>
+                {' · '}
+                <span className="font-normal opacity-80">{detail}</span>
+              </>
+            )}
+            {meta != null && (
+              <>
+                {' · '}
+                <span className="font-code tabular-nums opacity-80">{meta}</span>
+              </>
+            )}
+          </span>
+          <span
+            aria-hidden="true"
+            className="h-px flex-1 border-t border-dashed border-current opacity-30"
+          />
+        </span>
+      </LogContent>
+    </LogRow>
+  );
+}
+
+export interface EndMarkerProps {
+  record: EndLogRecord;
+  lineCount: number;
+  durationMs?: number | null;
+}
+
+/** Clean end of the log: line count + output bytes (+ overall duration). `total_bytes` is payload bytes. */
+export function EndMarker({record, lineCount, durationMs = null}: EndMarkerProps) {
+  const meta = [
+    `${lineCount} ${lineCount === 1 ? 'line' : 'lines'}`,
+    formatBytes(record.total_bytes),
+    ...(durationMs != null ? [formatDuration(durationMs)] : []),
+  ].join(' · ');
+
+  return (
+    <LogMarkerRow icon="flagLine" tone="default" timestamp={new Date(record.ts)} meta={meta}>
+      End of log
+    </LogMarkerRow>
+  );
+}
+
+/** The runner's local backlog shed bytes before upload, so some output never arrived. A warning. */
+export function GapMarker({record}: {record: GapLogRecord}) {
+  return (
+    <LogMarkerRow
+      icon="errorWarningLine"
+      tone="warning"
+      timestamp={new Date(record.ts)}
+      detail={`the runner fell behind and dropped ${formatBytes(record.dropped_bytes)}`}
+    >
+      Output missing
+    </LogMarkerRow>
+  );
+}
+
+/** The job hit its shared log size limit; logging stopped but the step kept running. A warning. */
+export function CappedMarker({record}: {record: CappedLogRecord}) {
+  return (
+    <LogMarkerRow
+      icon="forbidLine"
+      tone="warning"
+      timestamp={new Date(record.ts)}
+      detail="later output isn't shown; the step kept running"
+    >
+      Log size limit reached
+    </LogMarkerRow>
+  );
+}
+
+/** The runner disappeared and the stream was force-closed. A terminal failure (status taxonomy §9). */
+export function RunnerLostMarker({record}: {record: RunnerLostLogRecord}) {
+  return (
+    <LogMarkerRow
+      icon="closeCircleLine"
+      tone="error"
+      timestamp={new Date(record.ts)}
+      detail="the log ends here and may be incomplete"
+      terminalFailure
+    >
+      Runner disconnected
+    </LogMarkerRow>
+  );
+}

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

@@ -0,0 +1,219 @@
+import type {LogRecord, ReadLogsResponseDto} from '@shipfox/api-logs-dto';
+import {
+  mergeLogRead,
+  parseLogNdjson,
+  STEP_LOG_DRAIN_REFETCH_MS,
+  STEP_LOG_LIVE_REFETCH_MS,
+  type StepLogSnapshot,
+  stepLogRefetchInterval,
+} from './log-read.js';
+
+const output = (data: string, ts = 1): LogRecord => ({
+  v: 1,
+  ts,
+  type: 'output',
+  stream: 'stdout',
+  data,
+});
+
+const line = (record: LogRecord): string => `${JSON.stringify(record)}\n`;
+const inline = (params: {
+  ndjson: string;
+  nextCursor?: number;
+  hasMore?: boolean;
+  state?: 'open' | 'closed';
+  truncated?: boolean;
+}): Extract<ReadLogsResponseDto, {mode: 'inline'}> => ({
+  mode: 'inline',
+  ndjson: params.ndjson,
+  next_cursor: params.nextCursor ?? 1,
+  has_more: params.hasMore ?? false,
+  state: params.state ?? 'open',
+  truncated: params.truncated ?? false,
+});
+
+const presigned = (
+  params: Partial<Extract<ReadLogsResponseDto, {mode: 'presigned'}>> = {},
+): Extract<ReadLogsResponseDto, {mode: 'presigned'}> => ({
+  mode: 'presigned',
+  url: params.url ?? 'https://storage.example.test/logs/object?sig=1',
+  state: params.state ?? 'closed',
+  expires_at: params.expires_at ?? '2026-06-23T10:00:00.000Z',
+  total_bytes: params.total_bytes ?? 128,
+  truncated: params.truncated ?? false,
+});
+
+describe('parseLogNdjson', () => {
+  test('returns an empty record list for an empty body', () => {
+    const records = parseLogNdjson('');
+
+    expect(records).toEqual([]);
+  });
+
+  test('parses multiple record lines', () => {
+    const first = output('first\n', 1);
+    const second = output('second\n', 2);
+
+    const records = parseLogNdjson(line(first) + line(second));
+
+    expect(records).toEqual([first, second]);
+  });
+
+  test('throws when a line is not a valid log record', () => {
+    const parse = () => parseLogNdjson('{"v":1,"ts":1,"type":"nope"}\n');
+
+    expect(parse).toThrow();
+  });
+
+  test('splits records on CRLF line breaks', () => {
+    const first = output('first\n', 1);
+    const second = output('second\n', 2);
+
+    const records = parseLogNdjson(`${JSON.stringify(first)}\r\n${JSON.stringify(second)}\r\n`);
+
+    expect(records).toEqual([first, second]);
+  });
+
+  test('skips blank lines between records', () => {
+    const record = output('only\n', 1);
+
+    const records = parseLogNdjson(`\n${line(record)}\n`);
+
+    expect(records).toEqual([record]);
+  });
+});
+
+describe('mergeLogRead', () => {
+  test('appends inline records and advances the cursor', () => {
+    const previous: StepLogSnapshot = {
+      records: [output('old\n', 1)],
+      nextCursor: 3,
+      source: 'inline',
+      state: 'open',
+      complete: false,
+      hasMore: false,
+      truncated: false,
+      totalBytes: null,
+      expiresAt: null,
+    };
+    const response = inline({ndjson: line(output('new\n', 2)), nextCursor: 4, hasMore: true});
+
+    const snapshot = mergeLogRead(previous, {mode: 'inline', response});
+
+    expect(snapshot.records).toEqual([output('old\n', 1), output('new\n', 2)]);
+    expect(snapshot.nextCursor).toBe(4);
+    expect(snapshot.hasMore).toBe(true);
+    expect(snapshot.complete).toBe(false);
+  });
+
+  test('preserves records on an empty open inline page', () => {
+    const previous: StepLogSnapshot = {
+      records: [output('old\n', 1)],
+      nextCursor: 3,
+      source: 'inline',
+      state: 'open',
+      complete: false,
+      hasMore: false,
+      truncated: false,
+      totalBytes: null,
+      expiresAt: null,
+    };
+    const response = inline({ndjson: '', nextCursor: 3, state: 'open'});
+
+    const snapshot = mergeLogRead(previous, {mode: 'inline', response});
+
+    expect(snapshot.records).toEqual(previous.records);
+    expect(snapshot.nextCursor).toBe(3);
+    expect(snapshot.state).toBe('open');
+    expect(snapshot.complete).toBe(false);
+  });
+
+  test('marks a closed drained inline stream complete', () => {
+    const response = inline({ndjson: line(output('done\n')), state: 'closed', hasMore: false});
+
+    const snapshot = mergeLogRead(undefined, {mode: 'inline', response});
+
+    expect(snapshot.records).toEqual([output('done\n')]);
+    expect(snapshot.state).toBe('closed');
+    expect(snapshot.complete).toBe(true);
+    expect(snapshot.hasMore).toBe(false);
+  });
+
+  test('replaces partial inline records with the compacted object records', () => {
+    const previous: StepLogSnapshot = {
+      records: [output('partial\n', 1)],
+      nextCursor: 2,
+      source: 'inline',
+      state: 'closed',
+      complete: false,
+      hasMore: true,
+      truncated: false,
+      totalBytes: null,
+      expiresAt: null,
+    };
+    const response = presigned({
+      expires_at: '2026-06-23T10:00:00.000Z',
+      total_bytes: 256,
+      truncated: true,
+    });
+
+    const snapshot = mergeLogRead(previous, {
+      mode: 'presigned',
+      response,
+      ndjson: line(output('full\n', 2)),
+    });
+
+    expect(snapshot.records).toEqual([output('full\n', 2)]);
+    expect(snapshot.source).toBe('presigned');
+    expect(snapshot.state).toBe('compacted');
+    expect(snapshot.complete).toBe(true);
+    expect(snapshot.totalBytes).toBe(256);
+    expect(snapshot.expiresAt).toBe('2026-06-23T10:00:00.000Z');
+    expect(snapshot.truncated).toBe(true);
+  });
+});
+
+describe('stepLogRefetchInterval', () => {
+  const snapshot = (overrides: Partial<StepLogSnapshot>): StepLogSnapshot => ({
+    records: [],
+    nextCursor: 0,
+    source: 'inline',
+    state: 'open',
+    complete: false,
+    hasMore: false,
+    truncated: false,
+    totalBytes: null,
+    expiresAt: null,
+    ...overrides,
+  });
+
+  test('does not poll before the first snapshot', () => {
+    const interval = stepLogRefetchInterval(undefined);
+
+    expect(interval).toBe(false);
+  });
+
+  test('polls quickly while draining buffered inline pages', () => {
+    const interval = stepLogRefetchInterval(snapshot({hasMore: true}));
+
+    expect(interval).toBe(STEP_LOG_DRAIN_REFETCH_MS);
+  });
+
+  test('polls at live-tail cadence for an open drained stream', () => {
+    const interval = stepLogRefetchInterval(snapshot({state: 'open', hasMore: false}));
+
+    expect(interval).toBe(STEP_LOG_LIVE_REFETCH_MS);
+  });
+
+  test('stops polling once the stream is complete', () => {
+    const interval = stepLogRefetchInterval(snapshot({state: 'closed', complete: true}));
+
+    expect(interval).toBe(false);
+  });
+
+  test('stops polling after a fetch errors out instead of re-polling the dead cursor', () => {
+    const interval = stepLogRefetchInterval(snapshot({hasMore: true}), true);
+
+    expect(interval).toBe(false);
+  });
+});

package/src/core/log-read.ts

@@ -0,0 +1,79 @@
+import {type LogRecord, parseLogRecordLine, type ReadLogsResponseDto} from '@shipfox/api-logs-dto';
+
+export const STEP_LOG_DRAIN_REFETCH_MS = 250;
+export const STEP_LOG_LIVE_REFETCH_MS = 2_000;
+
+const NDJSON_LINE_BREAK = /\r?\n/;
+
+type InlineReadLogsResponse = Extract<ReadLogsResponseDto, {mode: 'inline'}>;
+type PresignedReadLogsResponse = Extract<ReadLogsResponseDto, {mode: 'presigned'}>;
+
+export interface StepLogSnapshot {
+  records: LogRecord[];
+  nextCursor: number;
+  source: 'inline' | 'presigned';
+  state: 'open' | 'closed' | 'compacted';
+  complete: boolean;
+  hasMore: boolean;
+  truncated: boolean;
+  totalBytes: number | null;
+  expiresAt: string | null;
+}
+
+export type ResolvedStepLogRead =
+  | {mode: 'inline'; response: InlineReadLogsResponse}
+  | {mode: 'presigned'; response: PresignedReadLogsResponse; ndjson: string};
+
+export function parseLogNdjson(ndjson: string): LogRecord[] {
+  return ndjson
+    .split(NDJSON_LINE_BREAK)
+    .filter((line) => line.length > 0)
+    .map(parseLogRecordLine);
+}
+
+export function mergeLogRead(
+  previous: StepLogSnapshot | undefined,
+  read: ResolvedStepLogRead,
+): StepLogSnapshot {
+  if (read.mode === 'presigned') {
+    return {
+      records: parseLogNdjson(read.ndjson),
+      nextCursor: 0,
+      source: 'presigned',
+      state: 'compacted',
+      complete: true,
+      hasMore: false,
+      truncated: read.response.truncated,
+      totalBytes: read.response.total_bytes,
+      expiresAt: read.response.expires_at,
+    };
+  }
+
+  const records = parseLogNdjson(read.response.ndjson);
+  const complete = read.response.state === 'closed' && !read.response.has_more;
+
+  return {
+    records: [...(previous?.records ?? []), ...records],
+    nextCursor: read.response.next_cursor,
+    source: 'inline',
+    state: read.response.state,
+    complete,
+    hasMore: read.response.has_more,
+    truncated: read.response.truncated,
+    totalBytes: null,
+    expiresAt: null,
+  };
+}
+
+export function stepLogRefetchInterval(
+  snapshot: StepLogSnapshot | undefined,
+  lastFetchErrored = false,
+): number | false {
+  // A persistent failure (deleted step, 5xx, an unparseable record line) never advances
+  // the cursor, so without this guard the interval re-polls the same dead cursor forever.
+  // Stop once a fetch errors out (React Query's own retry absorbs transient blips first);
+  // refetchOnWindowFocus/Reconnect (gated on !complete) resume it.
+  if (lastFetchErrored) return false;
+  if (!snapshot || snapshot.complete) return false;
+  return snapshot.hasMore ? STEP_LOG_DRAIN_REFETCH_MS : STEP_LOG_LIVE_REFETCH_MS;
+}