@shipfox/client-workflows 16.0.0 → 17.0.0

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,
+  });
+}