@shipfox/client-workflows 14.0.1 → 16.0.0

package/src/routes/inputs.test.ts

@@ -3,8 +3,12 @@ import {
   applyWorkflowRunFilterPatch,
   clearWorkflowRunFilters,
   hasWorkflowRunFilters,
+  validateWorkflowJobSearch,
   validateWorkflowRunsSearch,
+  type WorkflowJobSearch,
   type WorkflowRunsSearch,
+  workflowJobRouteParams,
+  workflowJobSearchParams,
   workflowRouteParams,
   workflowRunListSearchParams,
   workflowRunSearchParams,
@@ -62,12 +66,58 @@ describe('validateWorkflowRunsSearch', () => {
     expect(validateWorkflowRunsSearch({after: '2026-02-28'})).toEqual({after: '2026-02-28'});
   });
 
-  test('keeps the run selection parameters the detail route owns', () => {
+  test('keeps legacy job selection on the run route', () => {
     expect(validateWorkflowRunsSearch({status: 'failed', runAttempt: '2', job: 'job-1'})).toEqual({
       status: ['failed'],
+      jobId: 'job-1',
       runAttempt: 2,
+    });
+  });
+});
+
+describe('the job detail URL contract', () => {
+  test('reads and writes job-scoped selection parameters', () => {
+    const search: WorkflowJobSearch = {
+      jobExecutionId: 'execution-1',
+      stepId: 'step-1',
+      stepAttemptId: 'attempt-2',
+      runAttempt: 3,
+    };
+    const query = stringifyAppSearch(workflowJobSearchParams(search));
+
+    expect(query).toBe(
+      '?jobExecution=execution-1&step=step-1&stepAttempt=attempt-2&runAttempt=%223%22',
+    );
+    expect(validateWorkflowJobSearch(parseAppSearch(query))).toEqual(search);
+  });
+
+  test('drops malformed job selection values', () => {
+    expect(
+      validateWorkflowJobSearch({
+        tab: 'annotations',
+        jobExecution: ['unexpected'],
+        step: '',
+        stepAttempt: 4,
+        runAttempt: '0',
+      }),
+    ).toEqual({});
+  });
+
+  test('requires all job route path parameters', () => {
+    expect(
+      workflowJobRouteParams({
+        workspaceSlug: 'workspace-1',
+        projectSlug: 'project-1',
+        workflowRunId: 'run-1',
+        jobId: 'job-1',
+      }),
+    ).toEqual({
+      workspaceSlug: 'workspace-1',
+      projectSlug: 'project-1',
+      workflowRunId: 'run-1',
       jobId: 'job-1',
     });
+    expect(() => workflowJobRouteParams({workspaceSlug: 'workspace-1'})).toThrow();
   });
 
   test('accepts known tabs and annotation severities while dropping unknown values', () => {
@@ -84,8 +134,8 @@ describe('validateWorkflowRunsSearch', () => {
     ['job execution', {jobExecutionId: 'execution-1'}],
     ['step', {stepId: 'step-1'}],
     ['step attempt', {stepAttemptId: 'attempt-1'}],
-  ])('defaults a legacy %s selection URL to Jobs', (_selection, search) => {
-    expect(workflowRunTab(search)).toBe('jobs');
+  ])('defaults a legacy %s selection URL to Summary', (_selection, search) => {
+    expect(workflowRunTab(search)).toBe('summary');
   });
 
   test('keeps an explicit Summary tab ahead of legacy selection inference', () => {
@@ -195,9 +245,9 @@ describe('applyWorkflowRunFilterPatch', () => {
   });
 
   test('leaves the run selection parameters alone', () => {
-    const next = applyWorkflowRunFilterPatch({runAttempt: 2, jobId: 'job-1'}, {search: 'deploy'});
+    const next = applyWorkflowRunFilterPatch({runAttempt: 2}, {search: 'deploy'});
 
-    expect(next).toEqual({runAttempt: 2, jobId: 'job-1', search: 'deploy'});
+    expect(next).toEqual({runAttempt: 2, search: 'deploy'});
   });
 });
 
@@ -232,7 +282,7 @@ describe('hasWorkflowRunFilters', () => {
   });
 
   test('does not count a run selection parameter as a filter', () => {
-    expect(hasWorkflowRunFilters({runAttempt: 2, jobId: 'job-1'})).toBe(false);
+    expect(hasWorkflowRunFilters({runAttempt: 2})).toBe(false);
   });
 });
 

package/src/routes/inputs.ts

@@ -1,3 +1,4 @@
+import {RUN_ANNOTATION_SEVERITIES, type RunAnnotationSeverity} from '#core/run-annotation.js';
 import type {WorkflowRunSelectionInput} from '#core/workflow-run-url-state.js';
 
 /**
@@ -12,9 +13,13 @@ export const WORKFLOW_RUN_TABS = ['summary', 'jobs', 'annotations', 'source'] as
 
 export type WorkflowRunTab = (typeof WORKFLOW_RUN_TABS)[number];
 
-export const WORKFLOW_RUN_ANNOTATION_SEVERITIES = ['error', 'warning', 'info', 'success'] as const;
+/**
+ * The `severity` parameter's vocabulary is the display severity set, not a second list: a URL
+ * that could name a severity the list cannot rank would be a filter with no matching rows.
+ */
+export const WORKFLOW_RUN_ANNOTATION_SEVERITIES = RUN_ANNOTATION_SEVERITIES;
 
-export type WorkflowRunAnnotationSeverity = (typeof WORKFLOW_RUN_ANNOTATION_SEVERITIES)[number];
+export type WorkflowRunAnnotationSeverity = RunAnnotationSeverity;
 
 export interface WorkflowRunsSearch extends WorkflowRunSelectionInput {
   search?: string;
@@ -31,6 +36,8 @@ export interface WorkflowRunsSearch extends WorkflowRunSelectionInput {
   severity?: WorkflowRunAnnotationSeverity;
 }
 
+export type WorkflowJobSearch = Omit<WorkflowRunSelectionInput, 'jobId'>;
+
 const STATUS_VALUES = new Set<string>(WORKFLOW_RUN_LIST_STATUSES);
 const TAB_VALUES = new Set<string>(WORKFLOW_RUN_TABS);
 const ANNOTATION_SEVERITY_VALUES = new Set<string>(WORKFLOW_RUN_ANNOTATION_SEVERITIES);
@@ -51,7 +58,6 @@ export function validateWorkflowRunsSearch(input: Record<string, unknown>): Work
   const event = repeatable(input.event);
   const after = calendarDate(input.after);
   const before = calendarDate(input.before);
-  const runAttempt = positiveInteger(input.runAttempt);
   const tabValue = string(input.tab);
   const tab = tabValue && TAB_VALUES.has(tabValue) ? (tabValue as WorkflowRunTab) : undefined;
   const annotation = string(input.annotation);
@@ -72,14 +78,16 @@ export function validateWorkflowRunsSearch(input: Record<string, unknown>): Work
     ...(tab ? {tab} : {}),
     ...(annotation ? {annotation} : {}),
     ...(severity ? {severity} : {}),
-    ...(string(input.job) ? {jobId: string(input.job)} : {}),
-    ...(string(input.jobExecution) ? {jobExecutionId: string(input.jobExecution)} : {}),
-    ...(string(input.step) ? {stepId: string(input.step)} : {}),
-    ...(string(input.stepAttempt) ? {stepAttemptId: string(input.stepAttempt)} : {}),
-    ...(runAttempt ? {runAttempt} : {}),
+    ...workflowSelectionFromSearch(input, true),
   };
 }
 
+/** Reads the job-detail query string without allowing a job id to leak back into URL state. */
+export function validateWorkflowJobSearch(input: Record<string, unknown>): WorkflowJobSearch {
+  const {jobId: _jobId, ...selection} = workflowSelectionFromSearch(input, false);
+  return selection;
+}
+
 /**
  * Writes the query string back.
  *
@@ -101,23 +109,19 @@ export function workflowRunSearchParams(
     ...(search.tab && search.tab !== 'summary' ? {tab: search.tab} : {}),
     ...(search.annotation ? {annotation: search.annotation} : {}),
     ...(search.severity ? {severity: search.severity} : {}),
-    ...(selection.jobId ? {job: selection.jobId} : {}),
-    ...(selection.jobExecutionId ? {jobExecution: selection.jobExecutionId} : {}),
-    ...(selection.stepId ? {step: selection.stepId} : {}),
-    ...(selection.stepAttemptId ? {stepAttempt: selection.stepAttemptId} : {}),
-    ...(selection.runAttempt ? {runAttempt: String(selection.runAttempt)} : {}),
+    ...workflowSelectionSearchParams(selection, true),
   };
 }
 
-/**
- * Resolves the detail surface for a URL. Explicit tabs win; legacy selection-only URLs belong
- * to Jobs so their selected detail remains visible instead of silently landing on Summary.
- */
+export function workflowJobSearchParams(selection: WorkflowJobSearch) {
+  return workflowSelectionSearchParams(selection, false);
+}
+
+/** Resolves the run-level surface. Removed Jobs-tab and selection-only URLs fall back to Summary. */
 export function workflowRunTab(
   search: Pick<WorkflowRunsSearch, 'tab' | 'jobId' | 'jobExecutionId' | 'stepId' | 'stepAttemptId'>,
 ): WorkflowRunTab {
-  if (search.tab) return search.tab;
-  if (search.jobId || search.jobExecutionId || search.stepId || search.stepAttemptId) return 'jobs';
+  if (search.tab === 'annotations' || search.tab === 'source') return search.tab;
   return 'summary';
 }
 
@@ -203,6 +207,54 @@ export function workflowRouteParams(input: Record<string, unknown>): {
   return workflowRunId ? {workspaceSlug, projectSlug, workflowRunId} : {workspaceSlug, projectSlug};
 }
 
+export function workflowJobRouteParams(input: Record<string, unknown>): {
+  workspaceSlug: string;
+  projectSlug: string;
+  workflowRunId: string;
+  jobId: string;
+} {
+  const workspaceSlug = string(input.workspaceSlug);
+  const projectSlug = string(input.projectSlug);
+  const workflowRunId = string(input.workflowRunId);
+  const jobId = string(input.jobId);
+  if (!workspaceSlug || !projectSlug || !workflowRunId || !jobId) {
+    throw new Error('Workflow job route is missing required path parameters.');
+  }
+  return {workspaceSlug, projectSlug, workflowRunId, jobId};
+}
+
+function workflowSelectionFromSearch(
+  input: Record<string, unknown>,
+  includeJobId: boolean,
+): WorkflowRunSelectionInput {
+  const jobId = includeJobId ? string(input.job) : undefined;
+  const jobExecutionId = string(input.jobExecution);
+  const stepId = string(input.step);
+  const stepAttemptId = string(input.stepAttempt);
+  const runAttempt = positiveInteger(input.runAttempt);
+
+  return {
+    ...(jobId ? {jobId} : {}),
+    ...(jobExecutionId ? {jobExecutionId} : {}),
+    ...(stepId ? {stepId} : {}),
+    ...(stepAttemptId ? {stepAttemptId} : {}),
+    ...(runAttempt ? {runAttempt} : {}),
+  };
+}
+
+function workflowSelectionSearchParams(
+  selection: WorkflowRunSelectionInput,
+  includeJobId: boolean,
+) {
+  return {
+    ...(includeJobId && selection.jobId ? {job: selection.jobId} : {}),
+    ...(selection.jobExecutionId ? {jobExecution: selection.jobExecutionId} : {}),
+    ...(selection.stepId ? {step: selection.stepId} : {}),
+    ...(selection.stepAttemptId ? {stepAttempt: selection.stepAttemptId} : {}),
+    ...(selection.runAttempt ? {runAttempt: String(selection.runAttempt)} : {}),
+  };
+}
+
 function setOrDelete<TKey extends keyof WorkflowRunsSearch>(
   target: WorkflowRunsSearch,
   key: TKey,

package/src/routes/job-detail.tsx

@@ -0,0 +1,29 @@
+import {defineRoute, useRouteParams, useRouteSearch} from '@shipfox/client-shell/runtime';
+import {WorkflowJobDetailPage} from '#pages/workflow-job-detail-page.js';
+import {validateWorkflowJobSearch, workflowJobRouteParams} from './inputs.js';
+import {ProjectRoute} from './project-route.js';
+
+export default defineRoute({
+  staticData: {layout: 'full-bleed'},
+  validateSearch: validateWorkflowJobSearch,
+  component: () => {
+    const {workspaceSlug, projectSlug, workflowRunId, jobId} =
+      useRouteParams(workflowJobRouteParams);
+    const search = useRouteSearch(validateWorkflowJobSearch);
+
+    return (
+      <ProjectRoute>
+        {(project) => (
+          <WorkflowJobDetailPage
+            projectId={project.id}
+            workspaceSlug={workspaceSlug}
+            projectSlug={projectSlug}
+            workflowRunId={workflowRunId}
+            jobId={jobId}
+            search={search}
+          />
+        )}
+      </ProjectRoute>
+    );
+  },
+});

package/test/pages.tsx

@@ -20,7 +20,7 @@ import {
 import {type RenderResult, render} from '@testing-library/react';
 import {createStore, Provider as JotaiProvider} from 'jotai';
 import type {ReactElement} from 'react';
-import {validateWorkflowRunsSearch} from '#routes/inputs.js';
+import {validateWorkflowJobSearch, validateWorkflowRunsSearch} from '#routes/inputs.js';
 
 // The workflow run page navigates with the router (run rows are links and the page redirects
 // to the first run), so the harness mounts the page under a memory router whose route tree
@@ -39,6 +39,10 @@ const authState: AuthState = {
   workspaces: [{id: PROJECT_TEST_WID, name: 'Acme', slug: PROJECT_TEST_WSLUG, membershipId: 'm-1'}],
 };
 
+type TestPageSearch =
+  | ReturnType<typeof validateWorkflowRunsSearch>
+  | ReturnType<typeof validateWorkflowJobSearch>;
+
 export function jsonResponse(body: unknown, init: ResponseInit = {}) {
   return new Response(JSON.stringify(body), {
     status: 200,
@@ -51,7 +55,8 @@ function createTestRouter(
   path: string,
   renderPage: (params: {
     workflowRunId?: string | undefined;
-    search: ReturnType<typeof validateWorkflowRunsSearch>;
+    jobId?: string | undefined;
+    search: TestPageSearch;
   }) => ReactElement,
 ) {
   const rootRoute = createRootRoute({component: Outlet});
@@ -75,6 +80,21 @@ function createTestRouter(
       });
     },
   });
+  const jobDetailRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId/jobs/$jobId',
+    component: function JobDetailRoute() {
+      const {workflowRunId, jobId} = useParams({strict: false}) as {
+        workflowRunId?: string;
+        jobId?: string;
+      };
+      return renderPage({
+        workflowRunId,
+        jobId,
+        search: validateWorkflowJobSearch(useSearch({strict: false}) as Record<string, unknown>),
+      });
+    },
+  });
   const workflowsRoute = createRoute({
     getParentRoute: () => rootRoute,
     path: '/w/$workspaceSlug/p/$projectSlug/workflows',
@@ -95,6 +115,7 @@ function createTestRouter(
     routeTree: rootRoute.addChildren([
       runsRoute,
       runDetailRoute,
+      jobDetailRoute,
       workflowsRoute,
       modelProviderSettingsRoute,
     ]),
@@ -105,7 +126,8 @@ export function renderProjectPage(
   path: string,
   renderPage: (params: {
     workflowRunId?: string | undefined;
-    search: ReturnType<typeof validateWorkflowRunsSearch>;
+    jobId?: string | undefined;
+    search: TestPageSearch;
   }) => ReactElement,
 ): RenderResult & {
   queryClient: QueryClient;

package/test/render.tsx

@@ -22,6 +22,11 @@ function createComponentRouter(element: ReactElement) {
     path: '/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId',
     component: () => null,
   });
+  const jobDetailRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId/jobs/$jobId',
+    component: () => null,
+  });
   // The unfiltered empty state links here.
   const workflowsRoute = createRoute({
     getParentRoute: () => rootRoute,
@@ -31,7 +36,7 @@ function createComponentRouter(element: ReactElement) {
 
   return createRouter({
     history: createMemoryHistory({initialEntries: ['/']}),
-    routeTree: rootRoute.addChildren([indexRoute, runDetailRoute, workflowsRoute]),
+    routeTree: rootRoute.addChildren([indexRoute, runDetailRoute, jobDetailRoute, workflowsRoute]),
   });
 }