@shipfox/client-workflows 16.0.0 → 18.0.0

package/src/components/job-detail/json-code.tsx

@@ -0,0 +1,120 @@
+import {
+  CodeBlock,
+  CodeBlockBody,
+  CodeBlockContent,
+  CodeBlockCopyButton,
+  CodeBlockFilename,
+  CodeBlockFiles,
+  CodeBlockHeader,
+  CodeBlockItem,
+  CodeTabs,
+} from '@shipfox/react-ui/code-block';
+import {Text} from '@shipfox/react-ui/typography';
+import {useState} from 'react';
+
+export interface JsonCodeEntry {
+  filename: string;
+  label?: string | undefined;
+  value: unknown;
+}
+
+export function JsonCode({
+  title,
+  value,
+  emptyMessage,
+}: {
+  title?: string | undefined;
+  value: unknown;
+  emptyMessage?: string | undefined;
+}) {
+  const filename = title ?? 'value.json';
+
+  return (
+    <div className="flex min-w-0 flex-col gap-tight">
+      {title ? (
+        <Text size="xs" className="text-foreground-neutral-muted">
+          {title}
+        </Text>
+      ) : null}
+      {emptyMessage && isEmptyObject(value) ? (
+        <Text size="xs" className="text-foreground-neutral-muted">
+          {emptyMessage}
+        </Text>
+      ) : (
+        <JsonCodeBlock entries={[{filename, value}]} />
+      )}
+    </div>
+  );
+}
+
+export function JsonCodeTabs({entries}: {entries: readonly JsonCodeEntry[]}) {
+  const entryKeys = entries.map((entry) => entry.label ?? entry.filename);
+  const [activeKey, setActiveKey] = useState(entryKeys[0] ?? '');
+  const activeValue = entryKeys.includes(activeKey) ? activeKey : (entryKeys[0] ?? '');
+  const codes = Object.fromEntries(
+    entries.map((entry) => [entry.label ?? entry.filename, stringifyJson(entry.value)]),
+  );
+
+  return (
+    <CodeTabs
+      value={activeValue}
+      onValueChange={setActiveKey}
+      codes={codes}
+      lang="json"
+      syntaxHighlighting={false}
+      className="h-auto min-h-0 rounded-8 bg-background-contrast-base shadow-button-neutral"
+    />
+  );
+}
+
+function JsonCodeBlock({entries}: {entries: readonly JsonCodeEntry[]}) {
+  const data = entries.map((entry) => ({
+    filename: entry.filename,
+    language: 'json',
+    code: stringifyJson(entry.value),
+  }));
+
+  return (
+    <CodeBlock
+      data={data}
+      className="h-auto min-h-0 rounded-6 bg-background-contrast-base shadow-button-neutral"
+    >
+      <CodeBlockHeader className="bg-background-contrast-base p-tight">
+        <CodeBlockFiles>
+          {(item) => {
+            const entry = entries.find((candidate) => candidate.filename === item.filename);
+            return (
+              <CodeBlockFilename value={item.filename}>
+                {entry?.label ?? item.filename}
+              </CodeBlockFilename>
+            );
+          }}
+        </CodeBlockFiles>
+        <CodeBlockCopyButton />
+      </CodeBlockHeader>
+      <CodeBlockBody>
+        {(item) => (
+          <CodeBlockItem value={item.filename}>
+            <CodeBlockContent language="json" syntaxHighlighting={false}>
+              {item.code}
+            </CodeBlockContent>
+          </CodeBlockItem>
+        )}
+      </CodeBlockBody>
+    </CodeBlock>
+  );
+}
+
+function isEmptyObject(value: unknown): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 0
+  );
+}
+
+function stringifyJson(value: unknown): string {
+  const serialized = JSON.stringify(value, null, 2);
+  return serialized === undefined ? String(value) : serialized;
+}

package/src/components/job-detail/step-attempt-log-panel.test.tsx

@@ -203,6 +203,7 @@ describe('StepAttemptLogPanel', () => {
     renderPanel({attemptStatus: 'succeeded'});
 
     expect(await screen.findByText('hello')).toBeInTheDocument();
+    expect(screen.getByRole('log')).toHaveAttribute('aria-live', 'off');
   });
 
   test('renders a terminal closed empty stream as no output', async () => {

package/src/components/job-detail/step-attempt-log-panel.tsx

@@ -100,10 +100,15 @@ export function StepAttemptLogPanel({
   }
 
   return (
-    <div className="flex min-w-0 flex-col gap-8">
+    <div className="flex min-w-0 flex-col gap-inline">
       {staleError ? (
-        <Callout role="alert" type="warning" className="px-10 py-8">
-          <div className="flex min-w-0 flex-1 items-center justify-between gap-8">
+        <Callout
+          role="alert"
+          type="warning"
+          variant="secondary"
+          className="rounded-none border-b border-border-neutral-base px-0 py-row shadow-none"
+        >
+          <div className="flex min-w-0 flex-1 items-center justify-between gap-inline">
             <Text size="xs">Could not refresh logs.</Text>
             <Button
               type="button"
@@ -121,6 +126,7 @@ export function StepAttemptLogPanel({
         records={records}
         emptyState={query.data?.complete ? 'complete' : 'pending'}
         anchorToFailure={anchorToFailure}
+        ariaLive={attemptStatus === 'running' ? 'polite' : 'off'}
         className={surfaceClassName}
       />
     </div>
@@ -138,7 +144,7 @@ function StepLogsLoadingSurface({label, className}: {label: string; className: s
 function StepLogsWaitingSurface({startedAt, className}: {startedAt: string; className: string}) {
   return (
     <div role="status" aria-label="Waiting for logs" className={className}>
-      <Text size="xs" className="px-10 py-12 text-foreground-neutral-muted">
+      <Text size="xs" className="px-tight py-row text-foreground-neutral-muted">
         Waiting for output ·{' '}
         <span className="font-code tabular-nums" aria-hidden="true">
           <JobExecutionTimeText time={{state: 'live', fromIso: startedAt}} />
@@ -174,8 +180,13 @@ function isTerminalAttemptStatus(status: string): boolean {
 
 function StepLogsError({retrying, onRetry}: {retrying: boolean; onRetry: () => void}) {
   return (
-    <Callout role="alert" type="error" className="px-10 py-8">
-      <div className="flex min-w-0 flex-1 items-center justify-between gap-8">
+    <Callout
+      role="alert"
+      type="error"
+      variant="secondary"
+      className="rounded-none border-b border-border-neutral-base px-0 py-row shadow-none"
+    >
+      <div className="flex min-w-0 flex-1 items-center justify-between gap-inline">
         <Text size="xs">Could not load logs.</Text>
         <Button type="button" size="2xs" variant="secondary" isLoading={retrying} onClick={onRetry}>
           Retry

package/src/components/job-detail/step-troubleshooting.stories.tsx

@@ -0,0 +1,120 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {useState} from 'react';
+import {
+  workflowJob,
+  workflowJobExecutionDto,
+  workflowStepAttemptDto,
+  workflowStepDto,
+} from '#test/fixtures/workflow-run.js';
+import {buildStepListModel, type StepListEntryModel} from '../step-list/step-list-model.js';
+import {StepInspectorSheet} from './step-troubleshooting.js';
+
+const meta = {
+  title: 'Workflows/StepInspector',
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const FailedStep: Story = {
+  render: () => <FailedStepStory />,
+};
+
+function FailedStepStory() {
+  const [queryClient] = useState(
+    () => new QueryClient({defaultOptions: {queries: {staleTime: Number.POSITIVE_INFINITY}}}),
+  );
+  const entry = failedStepEntry();
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <main className="min-h-screen bg-background-neutral-base p-16">
+        <StepInspectorSheet
+          entry={entry}
+          open
+          onOpenChange={() => undefined}
+          workspaceSlug="acme"
+          projectSlug="platform"
+          workflowRunId="11111111-1111-4111-8111-111111111111"
+          runAttempt={1}
+          jobId="44444444-4444-4444-8444-000000000001"
+        />
+      </main>
+    </QueryClientProvider>
+  );
+}
+
+function failedStepEntry(): StepListEntryModel {
+  const jobId = '44444444-4444-4444-8444-000000000001';
+  const executionId = '77777777-7777-4777-8777-000000000001';
+  const stepId = '55555555-5555-4555-8555-000000000001';
+  const attemptId = '66666666-6666-4666-8666-000000000001';
+  const job = workflowJob({
+    id: jobId,
+    name: 'verification',
+    key: 'verification',
+    status: 'failed',
+    job_executions: [
+      workflowJobExecutionDto({
+        id: executionId,
+        job_id: jobId,
+        status: 'failed',
+        steps: [
+          workflowStepDto({
+            id: stepId,
+            job_execution_id: executionId,
+            name: 'Run verification suite',
+            key: 'run-verification',
+            status: 'failed',
+            status_reason: 'agent_invocation_failed',
+            config: {run: 'pnpm test --filter=@shipfox/client-workflows'},
+            evaluation_trace: [
+              {
+                expression: 'inputs["branch"]',
+                roots: ['inputs'],
+                fill_target: 'step-dispatch',
+                evaluated_at: '2026-06-21T12:04:00.000Z',
+                field: 'branch',
+                value: 'main',
+              },
+            ],
+            error: {
+              message: 'The verification agent returned a non-zero exit code.',
+              reason: 'agent_invocation_failed',
+              category: 'user',
+              exit_code: 1,
+            },
+            attempts: [
+              workflowStepAttemptDto({
+                id: attemptId,
+                step_id: stepId,
+                status: 'failed',
+                exit_code: 1,
+                output: {summary: 'Tests failed before the report was uploaded.'},
+                outputs: {failed_tests: 3},
+                error: {
+                  message: 'The verification agent returned a non-zero exit code.',
+                  reason: 'agent_invocation_failed',
+                  category: 'user',
+                  exit_code: 1,
+                },
+                finished_at: '2026-06-21T12:04:00.000Z',
+              }),
+            ],
+          }),
+        ],
+      }),
+    ],
+  });
+  const execution = job.jobExecutions[0];
+  if (!execution) throw new Error('Story fixture is missing a job execution.');
+
+  const entry = buildStepListModel({job, jobExecution: execution}).entries[0];
+  if (!entry) throw new Error('Story fixture is missing a step attempt.');
+
+  return entry;
+}

package/src/components/job-detail/step-troubleshooting.test.tsx

@@ -0,0 +1,337 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  Outlet,
+  RouterProvider,
+} from '@tanstack/react-router';
+import {act, render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {useState} from 'react';
+import {
+  workflowJob,
+  workflowJobExecutionDto,
+  workflowStepAttemptDto,
+  workflowStepDto,
+} from '#test/fixtures/workflow-run.js';
+import {buildStepListModel, type StepListEntryModel} from '../step-list/step-list-model.js';
+import {StepInspectorSheet} from './step-troubleshooting.js';
+
+const STEP_ID = '55555555-5555-4555-8555-555555555555';
+const ATTEMPT_ID = '66666666-6666-4666-8666-666666666666';
+const EXECUTION_ID = '77777777-7777-4777-8777-777777777777';
+const INSPECTOR_TRIGGER_NAME = 'Open inspector';
+
+describe('StepInspectorSheet', () => {
+  afterEach(() => {
+    configureApiClient({baseUrl: '', fetchImpl: undefined});
+  });
+
+  it('shows a loading state only after the inspector is opened', async () => {
+    const user = userEvent.setup();
+    configureApiClient({
+      fetchImpl: vi.fn(() => new Promise<Response>(() => undefined)),
+    });
+
+    await renderPanel();
+
+    expect(screen.queryByRole('status', {name: 'Loading troubleshooting details'})).toBeNull();
+    await user.click(screen.getByRole('button', {name: INSPECTOR_TRIGGER_NAME}));
+    expect(
+      await screen.findByRole('status', {name: 'Loading troubleshooting details'}),
+    ).toBeInTheDocument();
+  });
+
+  it('keeps failure detail out of the default log path', async () => {
+    const user = userEvent.setup();
+    configureApiClient({
+      fetchImpl: vi.fn(() => new Promise<Response>(() => undefined)),
+    });
+
+    await renderPanel();
+
+    expect(screen.queryByRole('alert')).toBeNull();
+    await user.click(screen.getByRole('button', {name: INSPECTOR_TRIGGER_NAME}));
+    expect(await screen.findByRole('alert')).toBeInTheDocument();
+  });
+
+  it('shows the evaluation count only after the lazy detail response arrives', async () => {
+    const user = userEvent.setup();
+    configureApiClient({
+      fetchImpl: vi.fn(async () =>
+        jsonResponse({
+          step_id: STEP_ID,
+          attempt: 1,
+          authored_config: {run: 'pnpm test'},
+          config: {run: 'pnpm test --filter=client'},
+          evaluation_trace: [
+            {
+              expression: 'inputs.message',
+              roots: ['inputs.message'],
+              fill_target: 'run',
+              evaluated_at: '2026-08-05T12:00:00.000Z',
+              field: 'run',
+              value: 'hello',
+            },
+          ],
+        }),
+      ),
+    });
+
+    await renderPanel();
+
+    expect(screen.queryByText('Evaluation')).toBeNull();
+    await user.click(screen.getByRole('button', {name: INSPECTOR_TRIGGER_NAME}));
+    expect((await screen.findAllByText('Evaluation')).length).toBeGreaterThan(0);
+  });
+
+  it('shows an actionable error and retries the detail request', async () => {
+    const user = userEvent.setup();
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse({code: 'server-error'}, {status: 500}))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          step_id: STEP_ID,
+          attempt: 1,
+          authored_config: {run: 'pnpm test'},
+          config: {run: 'pnpm test --filter=client'},
+          evaluation_trace: null,
+        }),
+      );
+    configureApiClient({fetchImpl});
+
+    await renderPanel();
+    await user.click(screen.getByRole('button', {name: INSPECTOR_TRIGGER_NAME}));
+
+    expect(await screen.findByText('Details unavailable')).toBeInTheDocument();
+    await user.click(screen.getByRole('button', {name: 'Retry'}));
+    expect(await screen.findByRole('region', {name: 'Inputs'})).toBeInTheDocument();
+    expect(screen.getByText('Resolved configuration')).toBeInTheDocument();
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps the annotation link available when the detail request fails', async () => {
+    const user = userEvent.setup();
+    configureApiClient({
+      fetchImpl: vi.fn(() => Promise.resolve(jsonResponse({code: 'server-error'}, {status: 500}))),
+    });
+
+    await renderPanel({annotationCount: 2});
+    await user.click(screen.getByRole('button', {name: INSPECTOR_TRIGGER_NAME}));
+
+    expect(await screen.findByText('Details unavailable')).toBeInTheDocument();
+    expect(screen.getByRole('link', {name: 'View 2 annotations'})).toBeInTheDocument();
+  });
+
+  it('does not replace an annotation link with an empty inspector state', async () => {
+    const user = userEvent.setup();
+    configureApiClient({
+      fetchImpl: vi.fn(async () =>
+        jsonResponse({
+          step_id: STEP_ID,
+          attempt: 1,
+          authored_config: null,
+          config: null,
+          evaluation_trace: null,
+        }),
+      ),
+    });
+
+    await renderPanel({annotationCount: 2, entry: emptyStepEntry()});
+    await user.click(screen.getByRole('button', {name: INSPECTOR_TRIGGER_NAME}));
+
+    expect(await screen.findByRole('link', {name: 'View 2 annotations'})).toBeInTheDocument();
+    expect(screen.queryByText('No additional troubleshooting details were recorded.')).toBeNull();
+  });
+
+  it('does not show current step configuration or evaluation for a historical attempt', async () => {
+    const user = userEvent.setup();
+    configureApiClient({
+      fetchImpl: vi.fn(async () =>
+        jsonResponse({
+          step_id: STEP_ID,
+          attempt: 1,
+          authored_config: null,
+          config: null,
+          evaluation_trace: null,
+        }),
+      ),
+    });
+
+    await renderPanel();
+    await user.click(screen.getByRole('button', {name: INSPECTOR_TRIGGER_NAME}));
+    expect(await screen.findByRole('region', {name: 'Outputs'})).toBeInTheDocument();
+
+    expect(screen.queryByText('Authored configuration')).toBeNull();
+    expect(screen.queryByText('Resolved configuration')).toBeNull();
+    expect(screen.queryByText('Evaluation')).toBeNull();
+  });
+});
+
+async function renderPanel({
+  annotationCount,
+  entry,
+}: {
+  annotationCount?: number;
+  entry?: StepListEntryModel;
+} = {}) {
+  const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+  const rootRoute = createRootRoute({component: Outlet});
+  const panelRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId',
+    component: () => (
+      <QueryClientProvider client={queryClient}>
+        <PanelHarness annotationCount={annotationCount} entry={entry} />
+      </QueryClientProvider>
+    ),
+  });
+  const router = createRouter({
+    history: createMemoryHistory({initialEntries: ['/w/acme/p/platform/runs/run-1']}),
+    routeTree: rootRoute.addChildren([panelRoute]),
+  });
+  await router.load();
+  let result: ReturnType<typeof render> | undefined;
+  await act(() => {
+    result = render(<RouterProvider router={router} />);
+  });
+  if (!result) throw new Error('Step inspector did not render.');
+  return result;
+}
+
+function PanelHarness({
+  annotationCount,
+  entry: providedEntry,
+}: {
+  annotationCount?: number | undefined;
+  entry?: StepListEntryModel | undefined;
+}) {
+  const [inspectorOpen, setInspectorOpen] = useState(false);
+  const entry = providedEntry ?? stepEntry();
+  return (
+    <>
+      <button type="button" onClick={() => setInspectorOpen(true)}>
+        Open inspector
+      </button>
+      <StepInspectorSheet
+        entry={entry}
+        open={inspectorOpen}
+        onOpenChange={setInspectorOpen}
+        workspaceSlug="acme"
+        projectSlug="platform"
+        workflowRunId="11111111-1111-4111-8111-111111111111"
+        runAttempt={1}
+        jobId="44444444-4444-4444-8444-444444444444"
+        annotationCount={annotationCount}
+      />
+    </>
+  );
+}
+
+function stepEntry(): StepListEntryModel {
+  const jobId = '44444444-4444-4444-8444-444444444444';
+  const job = workflowJob({
+    id: jobId,
+    name: 'verification',
+    key: 'verification',
+    status: 'failed',
+    job_executions: [
+      workflowJobExecutionDto({
+        id: EXECUTION_ID,
+        job_id: jobId,
+        status: 'failed',
+        steps: [
+          workflowStepDto({
+            id: STEP_ID,
+            job_execution_id: EXECUTION_ID,
+            name: 'Run verification',
+            status: 'failed',
+            config: {run: 'pnpm test'},
+            evaluation_trace: [
+              {
+                expression: 'inputs.message',
+                roots: ['inputs.message'],
+                fill_target: 'run',
+                evaluated_at: '2026-08-05T12:00:00.000Z',
+                field: 'run',
+                value: 'current attempt value',
+              },
+            ],
+            attempts: [
+              workflowStepAttemptDto({
+                id: ATTEMPT_ID,
+                step_id: STEP_ID,
+                status: 'failed',
+                output: {result: 'failed'},
+                finished_at: '2026-08-05T12:01:00.000Z',
+              }),
+            ],
+          }),
+        ],
+      }),
+    ],
+  });
+  const execution = job.jobExecutions[0];
+  if (!execution) throw new Error('Test fixture is missing an execution.');
+  const entry = buildStepListModel({job, jobExecution: execution}).entries[0];
+  if (!entry) throw new Error('Test fixture is missing a step attempt.');
+
+  return entry;
+}
+
+function emptyStepEntry(): StepListEntryModel {
+  const jobId = '44444444-4444-4444-8444-444444444444';
+  const job = workflowJob({
+    id: jobId,
+    name: 'verification',
+    key: 'verification',
+    status: 'succeeded',
+    job_executions: [
+      workflowJobExecutionDto({
+        id: EXECUTION_ID,
+        job_id: jobId,
+        status: 'succeeded',
+        steps: [
+          workflowStepDto({
+            id: STEP_ID,
+            job_execution_id: EXECUTION_ID,
+            name: 'Run verification',
+            status: 'succeeded',
+            config: {},
+            attempts: [
+              workflowStepAttemptDto({
+                id: ATTEMPT_ID,
+                step_id: STEP_ID,
+                status: 'succeeded',
+                output: null,
+                outputs: null,
+                response: null,
+                error: null,
+                exit_code: 0,
+                finished_at: '2026-08-05T12:01:00.000Z',
+              }),
+            ],
+          }),
+        ],
+      }),
+    ],
+  });
+  const execution = job.jobExecutions[0];
+  if (!execution) throw new Error('Test fixture is missing an execution.');
+  const entry = buildStepListModel({job, jobExecution: execution}).entries[0];
+  if (!entry) throw new Error('Test fixture is missing a step attempt.');
+
+  return entry;
+}
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {'content-type': 'application/json'},
+    ...init,
+  });
+}