@shipfox/client-workflows 15.0.0 → 17.0.0

package/src/components/workflow-run-view/workflow-run-view.tsx

@@ -10,11 +10,18 @@ import {
   SelectValue,
 } from '@shipfox/react-ui/select';
 import {toast} from '@shipfox/react-ui/toast';
+import {Text} from '@shipfox/react-ui/typography';
 import {useNavigate} from '@tanstack/react-router';
-import {type ReactNode, useEffect} from 'react';
-import type {Job, WorkflowRunRerunMode} from '#core/workflow-run.js';
-import type {RunAnnotationSummary} from '#core/workflow-run-tabs.js';
+import {type ReactNode, useEffect, useMemo} from 'react';
+import {buildRunAnnotationList, type RunAnnotationSummary} from '#core/run-annotation.js';
+import {
+  type EvaluationTraceEntry,
+  isWorkflowRunTerminal,
+  type Job,
+  type WorkflowRunRerunMode,
+} from '#core/workflow-run.js';
 import {withoutWorkflowRunSelectionSearch} from '#core/workflow-run-url-state.js';
+import {useRunAnnotationsQuery} from '#hooks/api/run-annotations.js';
 import {
   useCancelWorkflowRunMutation,
   useRerunWorkflowRunMutation,
@@ -30,7 +37,11 @@ import {
 import {JobGraph} from '../job-graph/index.js';
 import type {JobGraphSelectionSource} from '../job-graph/types.js';
 import {WorkflowRunSummary} from '../workflow-run-summary/index.js';
-import {RunAnnotationSummaryLine, RunAnnotationsEmpty} from '../workflow-run-tabs/index.js';
+import {
+  type DerivedRunAnnotation,
+  RunAnnotationList,
+  RunAnnotationSummaryLine,
+} from '../workflow-run-tabs/index.js';
 import {WorkflowSourceContent} from '../workflow-source-panel/index.js';
 import {RunWorkspaceNav} from './run-workspace-nav.js';
 import {resolveWorkflowRunSelection} from './workflow-run-selection.js';
@@ -51,7 +62,6 @@ export interface WorkflowRunViewProps {
   runAttempt?: number | undefined;
   selection?: WorkflowRunsSearch | undefined;
   tab?: WorkflowRunTab | undefined;
-  annotationSummary?: RunAnnotationSummary | undefined;
   activeJobId?: string | undefined;
   jobSearch?: WorkflowJobSearch | undefined;
   jobContent?: ReactNode | undefined;
@@ -69,7 +79,6 @@ export function WorkflowRunView({
   runAttempt,
   selection,
   tab,
-  annotationSummary,
   activeJobId,
   jobSearch,
   jobContent,
@@ -79,6 +88,22 @@ export function WorkflowRunView({
     runAttempt: selection?.runAttempt ?? runAttempt,
   });
   const rerunMutation = useRerunWorkflowRunMutation(projectId);
+  // Annotations are read on their own cadence rather than hydrated into the run, so the two
+  // modules stay decoupled. The key is shared, so the job page's count chip costs no extra fetch.
+  //
+  // Polling is scoped to the surface that renders bodies. The read has no counts-only mode, so
+  // every poll transfers whole Markdown bodies; doing that every four seconds behind Summary,
+  // Source, and the job log spends megabytes to keep one rail number warm. Off that surface the
+  // counts still refresh on navigation and on window focus.
+  const annotationsQuery = useRunAnnotationsQuery({
+    workflowRunId,
+    runAttempt: runQuery.data?.runAttempt.attempt,
+    live:
+      runWorkspaceSection(tab) === 'annotations' &&
+      !activeJobId &&
+      Boolean(runQuery.data) &&
+      !isWorkflowRunTerminal(runQuery.data?.runAttempt.status ?? 'pending'),
+  });
 
   return (
     <RelativeTimeProvider>
@@ -87,11 +112,11 @@ export function WorkflowRunView({
           workspaceSlug={workspaceSlug}
           projectSlug={projectSlug}
           query={runQuery}
+          annotations={annotationsQuery}
           rerunMutation={rerunMutation}
           runAttempt={runAttempt}
           selection={selection}
           tab={tab}
-          annotationSummary={annotationSummary}
           activeJobId={activeJobId}
           jobSearch={jobSearch}
           jobContent={jobContent}
@@ -105,11 +130,11 @@ function RunViewContent({
   workspaceSlug,
   projectSlug,
   query,
+  annotations,
   rerunMutation,
   runAttempt,
   selection,
   tab,
-  annotationSummary,
   activeJobId,
   jobSearch,
   jobContent,
@@ -117,17 +142,18 @@ function RunViewContent({
   workspaceSlug: string | undefined;
   projectSlug: string | undefined;
   query: ReturnType<typeof useWorkflowRunAttemptQuery>;
+  annotations: ReturnType<typeof useRunAnnotationsQuery>;
   rerunMutation: ReturnType<typeof useRerunWorkflowRunMutation>;
   runAttempt: number | undefined;
   selection: WorkflowRunsSearch | undefined;
   tab: WorkflowRunTab | undefined;
-  annotationSummary: RunAnnotationSummary | undefined;
   activeJobId: string | undefined;
   jobSearch: WorkflowJobSearch | undefined;
   jobContent: ReactNode | undefined;
 }) {
   const navigate = useNavigate();
   const runData = query.data;
+  const annotationSummary = annotations.summary;
   const activeSection = runWorkspaceSection(tab);
   const cancelMutation = useCancelWorkflowRunMutation(runData);
   const sourceSnapshot = runData?.sourceSnapshot ?? null;
@@ -228,6 +254,24 @@ function RunViewContent({
     });
   }
 
+  function clearAnnotationFilters() {
+    if (!runData || !workspaceSlug || !projectSlug) return;
+    const nextSearch: WorkflowRunsSearch = {...selection, tab: 'annotations'};
+    delete nextSearch.jobId;
+    delete nextSearch.jobExecutionId;
+    delete nextSearch.stepId;
+    delete nextSearch.stepAttemptId;
+    delete nextSearch.severity;
+    delete nextSearch.annotation;
+
+    void navigate({
+      to: '/w/$workspaceSlug/p/$projectSlug/runs/$workflowRunId',
+      params: {workspaceSlug, projectSlug, workflowRunId: runData.id},
+      search: workflowRunSearchParams(nextSearch, nextSearch) as never,
+      replace: true,
+    });
+  }
+
   function cancelRun() {
     cancelMutation.mutate(undefined, {
       onError: (error) => toast.error(cancelErrorMessage(error)),
@@ -291,6 +335,7 @@ function RunViewContent({
             <RunSectionContent
               section={activeSection}
               run={runData}
+              annotations={annotations}
               annotationSummary={annotationSummary}
               workspaceSlug={workspaceSlug}
               projectSlug={projectSlug}
@@ -298,11 +343,12 @@ function RunViewContent({
               selectedJobId={selection?.jobId}
               onSelectGraphJob={selectGraphJob}
               onSelectAnnotationJob={selectAnnotationJob}
+              onClearAnnotationFilters={clearAnnotationFilters}
               sourceSnapshot={sourceSnapshot}
               highlightedLineRange={highlightedLineRange}
             />
           ) : (
-            <div className="min-h-0 flex-1 overflow-auto p-24">{loadingOrError}</div>
+            <div className="min-h-0 flex-1 overflow-auto p-panel">{loadingOrError}</div>
           )}
         </div>
       </div>
@@ -313,6 +359,7 @@ function RunViewContent({
 function RunSectionContent({
   section,
   run,
+  annotations,
   annotationSummary,
   workspaceSlug,
   projectSlug,
@@ -320,11 +367,13 @@ function RunSectionContent({
   selectedJobId,
   onSelectGraphJob,
   onSelectAnnotationJob,
+  onClearAnnotationFilters,
   sourceSnapshot,
   highlightedLineRange,
 }: {
   section: RunWorkspaceSection;
   run: NonNullable<ReturnType<typeof useWorkflowRunAttemptQuery>['data']>;
+  annotations: ReturnType<typeof useRunAnnotationsQuery>;
   annotationSummary: RunAnnotationSummary | undefined;
   workspaceSlug: string | undefined;
   projectSlug: string | undefined;
@@ -332,6 +381,7 @@ function RunSectionContent({
   selectedJobId: string | undefined;
   onSelectGraphJob: (jobId: string | undefined, source?: JobGraphSelectionSource) => void;
   onSelectAnnotationJob: (jobId: string | undefined) => void;
+  onClearAnnotationFilters: () => void;
   sourceSnapshot: NonNullable<
     ReturnType<typeof useWorkflowRunAttemptQuery>['data']
   >['sourceSnapshot'];
@@ -341,8 +391,14 @@ function RunSectionContent({
 }) {
   if (section === 'summary') {
     return (
-      <section aria-label="All jobs summary" className="min-h-0 flex-1 overflow-auto pb-24 pt-16">
-        <div className="mx-auto flex w-full max-w-[1120px] flex-col gap-16 px-24">
+      <section
+        aria-label="All jobs summary"
+        className="min-h-0 flex-1 overflow-auto pb-panel pt-[16px]"
+      >
+        <div className="mx-auto flex w-full max-w-[1120px] flex-col gap-group px-frame">
+          <Text as="h2" className="sr-only">
+            All jobs summary
+          </Text>
           <JobGraph
             run={run}
             selectedJobId={selectedJobId}
@@ -355,33 +411,30 @@ function RunSectionContent({
   }
 
   if (section === 'annotations') {
-    const selectedJob = run.jobs.find((job) => job.id === selectedJobId);
     return (
-      <section aria-label="Run annotations" className="min-h-0 flex-1 overflow-auto pb-24 pt-16">
-        <div className="mx-auto flex w-full max-w-[1120px] flex-col gap-16 px-24">
-          <div className="flex flex-wrap items-center justify-between gap-8">
-            <RunAnnotationSummaryLine
-              summary={annotationSummary}
-              workspaceSlug={workspaceSlug}
-              projectSlug={projectSlug}
-              workflowRunId={run.id}
-              search={selection}
-            />
-            <AnnotationJobFilter
-              jobs={run.jobs}
-              selectedJobId={selectedJob?.id}
-              onSelect={onSelectAnnotationJob}
-            />
-          </div>
-          <RunAnnotationsEmpty jobName={selectedJob?.displayName} />
-        </div>
-      </section>
+      <RunAnnotationsSection
+        run={run}
+        annotations={annotations}
+        annotationSummary={annotationSummary}
+        workspaceSlug={workspaceSlug}
+        projectSlug={projectSlug}
+        selection={selection}
+        selectedJobId={selectedJobId}
+        onSelectAnnotationJob={onSelectAnnotationJob}
+        onClearAnnotationFilters={onClearAnnotationFilters}
+      />
     );
   }
 
   return (
-    <section aria-label="Workflow source" className="min-h-0 flex-1 overflow-auto pb-24 pt-16">
-      <div className="mx-auto flex min-h-full w-full max-w-[1120px] px-24">
+    <section
+      aria-label="Workflow source"
+      className="min-h-0 flex-1 overflow-auto pb-panel pt-[16px]"
+    >
+      <div className="mx-auto flex min-h-full w-full max-w-[1120px] flex-col px-frame">
+        <Text as="h2" className="sr-only">
+          Workflow source
+        </Text>
         {sourceSnapshot ? (
           <WorkflowSourceContent
             source={sourceSnapshot}
@@ -405,6 +458,171 @@ function RunSectionContent({
   );
 }
 
+function RunAnnotationsSection({
+  run,
+  annotations,
+  annotationSummary,
+  workspaceSlug,
+  projectSlug,
+  selection,
+  selectedJobId,
+  onSelectAnnotationJob,
+  onClearAnnotationFilters,
+}: {
+  run: NonNullable<ReturnType<typeof useWorkflowRunAttemptQuery>['data']>;
+  annotations: ReturnType<typeof useRunAnnotationsQuery>;
+  annotationSummary: RunAnnotationSummary | undefined;
+  workspaceSlug: string | undefined;
+  projectSlug: string | undefined;
+  selection: WorkflowRunsSearch | undefined;
+  selectedJobId: string | undefined;
+  onSelectAnnotationJob: (jobId: string | undefined) => void;
+  onClearAnnotationFilters: () => void;
+}) {
+  const selectedJob = run.jobs.find((job) => job.id === selectedJobId);
+  const severity = selection?.severity;
+  const records = annotations.annotations;
+
+  const entries = useMemo(
+    () =>
+      records
+        ? buildRunAnnotationList({
+            annotations: records,
+            jobs: run.jobs,
+            severity,
+            jobId: selectedJob?.id,
+          })
+        : undefined,
+    [records, run.jobs, selectedJob?.id, severity],
+  );
+  const derivedAnnotations = useMemo<readonly DerivedRunAnnotation[] | undefined>(() => {
+    if (!records) return undefined;
+    const jobsWithAnnotations = new Set(records.map((annotation) => annotation.jobId));
+
+    return run.jobs
+      .filter((job) => {
+        const style = job.status === 'failed' ? 'error' : 'warning';
+        return (
+          (!selectedJob || selectedJob.id === job.id) &&
+          !jobsWithAnnotations.has(job.id) &&
+          (job.status === 'failed' || job.status === 'skipped') &&
+          job.jobExecutions.length === 0 &&
+          matchesDerivedAnnotationFilters(style, selection)
+        );
+      })
+      .map((job) => ({
+        id: `derived-${job.id}`,
+        style: job.status === 'failed' ? 'error' : 'warning',
+        body: derivedJobAnnotation(job),
+      }));
+  }, [records, run.jobs, selectedJob, selection]);
+  const hasSynthesizedJobAnnotations = run.jobs.some(
+    (job) =>
+      (job.status === 'failed' || job.status === 'skipped') && job.jobExecutions.length === 0,
+  );
+
+  return (
+    <section
+      aria-label="Run annotations"
+      className="min-h-0 flex-1 overflow-auto pb-panel pt-[16px]"
+    >
+      <div className="mx-auto flex w-full max-w-[1120px] flex-col gap-group px-frame">
+        <Text as="h2" className="sr-only">
+          Annotations
+        </Text>
+        <div className="flex flex-wrap items-center justify-between gap-inline">
+          <RunAnnotationSummaryLine
+            summary={annotationSummary}
+            workspaceSlug={workspaceSlug}
+            projectSlug={projectSlug}
+            workflowRunId={run.id}
+            search={selection}
+          />
+          <AnnotationJobFilter
+            jobs={run.jobs}
+            selectedJobId={selectedJob?.id}
+            onSelect={onSelectAnnotationJob}
+          />
+        </div>
+        <RunAnnotationList
+          // Remounting on a filter or run-attempt change resets the render window, so the next
+          // list never inherits a "show more" position from different data.
+          key={`${run.id}:${run.runAttempt.attempt}:${severity ?? 'all'}:${selectedJob?.id ?? 'all'}`}
+          query={annotations.query}
+          entries={entries}
+          derivedAnnotations={derivedAnnotations}
+          workspaceSlug={workspaceSlug}
+          projectSlug={projectSlug}
+          workflowRunId={run.id}
+          runAttempt={run.runAttempt.attempt}
+          // A run with no annotations at all offers no filter to clear, whatever the URL says.
+          filtered={Boolean(
+            (severity || selectedJob || selection?.annotation) &&
+              ((annotationSummary?.total ?? 0) > 0 || hasSynthesizedJobAnnotations),
+          )}
+          filteredJobName={selectedJob?.displayName}
+          filteredSeverity={severity}
+          onClearFilters={onClearAnnotationFilters}
+          selectedAnnotationId={selection?.annotation}
+        />
+      </div>
+    </section>
+  );
+}
+
+function matchesDerivedAnnotationFilters(
+  style: 'warning' | 'error',
+  selection: WorkflowRunsSearch | undefined,
+): boolean {
+  if (selection?.severity && style !== selection.severity) return false;
+  // A selected annotation is a deep-link to a real annotation record. Synthetic diagnostics
+  // have no id or context, so they must not remain visible behind that selection.
+  return !selection?.annotation;
+}
+
+function derivedJobAnnotation(job: Job): string {
+  const reason = job.statusReason ? `Reason: \`${job.statusReason}\`` : null;
+  const traceSummary = formatConditionEvaluation(job.evaluationTrace);
+  const details = [reason, traceSummary].filter(Boolean).join('\n');
+
+  if (job.status === 'skipped') {
+    return [
+      `**${job.displayName}** was skipped before an execution was created.`,
+      '',
+      'Review its dependencies or condition before re-running.',
+      details,
+    ]
+      .filter(Boolean)
+      .join('\n');
+  }
+  return [
+    `**${job.displayName}** failed before an execution was created.`,
+    '',
+    'Check runner availability and workflow configuration before re-running.',
+    details,
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+function formatConditionEvaluation(
+  trace: readonly EvaluationTraceEntry[] | null | undefined,
+): string | null {
+  if (!trace?.length) return null;
+
+  return [
+    'Condition evaluation:',
+    ...trace.map((entry) => {
+      if ('dropped' in entry) {
+        return `- ${entry.dropped} additional evaluation${entry.dropped === 1 ? '' : 's'} not recorded`;
+      }
+      const value =
+        entry.value === undefined || entry.value === '' ? '(empty)' : `\`${entry.value}\``;
+      return `- \`${entry.field}\` evaluated \`${entry.expression}\` to ${value}${entry.degraded ? ' (degraded)' : ''}`;
+    }),
+  ].join('\n');
+}
+
 const ALL_ANNOTATION_JOBS = 'all-jobs';
 
 function AnnotationJobFilter({
@@ -448,11 +666,11 @@ function RunWorkspaceNavSkeleton() {
   return (
     <aside
       aria-label="Loading run navigation"
-      className="hidden w-240 shrink-0 border-r border-border-neutral-base bg-background-neutral-background p-12 min-[768px]:block"
+      className="hidden w-240 shrink-0 border-r border-border-neutral-base bg-background-neutral-background p-panel-compact min-[768px]:block"
     >
-      <div className="flex flex-col gap-16">
+      <div className="flex flex-col gap-group">
         <div className="h-32 rounded-4 bg-background-components-subtle" />
-        <div className="flex flex-col gap-6">
+        <div className="flex flex-col gap-inline">
           <div className="h-16 w-64 rounded-4 bg-background-components-subtle" />
           <div className="h-32 rounded-4 bg-background-components-subtle" />
           <div className="h-32 rounded-4 bg-background-components-subtle" />

package/src/core/entities/job-execution.ts

@@ -1,5 +1,6 @@
 import {type Duration, intervalToDuration} from 'date-fns';
 import type {Step} from './step.js';
+import type {EvaluationTraceEntry} from './step-attempt.js';
 
 export type JobExecutionStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled';
 export type JobExecutionDisplayStatus = JobExecutionStatus;
@@ -28,11 +29,14 @@ interface JobExecutionFields {
   name: string;
   status: JobExecutionStatus;
   statusReason: string | null;
+  runner: string[] | null;
+  outputs: Record<string, unknown> | null;
   triggerEvents: WorkflowExecutionEvent[];
   queuedAt: string | null;
   startedAt: string | null;
   finishedAt: string | null;
   timedOutAt: string | null;
+  evaluationTrace: EvaluationTraceEntry[] | null;
   createdAt: string;
   updatedAt: string;
   steps: Step[];
@@ -45,11 +49,14 @@ export class JobExecution {
   name!: string;
   status!: JobExecutionStatus;
   statusReason!: string | null;
+  runner!: string[] | null;
+  outputs!: Record<string, unknown> | null;
   triggerEvents!: WorkflowExecutionEvent[];
   queuedAt!: string | null;
   startedAt!: string | null;
   finishedAt!: string | null;
   timedOutAt!: string | null;
+  evaluationTrace!: EvaluationTraceEntry[] | null;
   createdAt!: string;
   updatedAt!: string;
   steps!: Step[];

package/src/core/entities/job.ts

@@ -3,6 +3,7 @@ import {
   type JobExecution,
   type JobExecutionDisplayDuration,
 } from './job-execution.js';
+import type {EvaluationTraceEntry} from './step-attempt.js';
 
 export type JobStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'skipped';
 export type JobDisplayStatus = JobStatus | 'listening';
@@ -75,6 +76,10 @@ interface JobFields {
   status: JobStatus;
   statusReason: JobStatusReason | null;
   carriedOver: boolean;
+  outputs: Record<string, unknown> | null;
+  success: string | null;
+  runner: string[] | null;
+  evaluationTrace: EvaluationTraceEntry[] | null;
   listening: JobListening | null;
   listenerStatus: ListenerStatus;
   resolutionReason: ResolutionReason | null;
@@ -94,6 +99,10 @@ export class Job {
   status!: JobStatus;
   statusReason!: JobStatusReason | null;
   carriedOver!: boolean;
+  outputs!: Record<string, unknown> | null;
+  success!: string | null;
+  runner!: string[] | null;
+  evaluationTrace!: EvaluationTraceEntry[] | null;
   listening!: JobListening | null;
   listenerStatus!: ListenerStatus;
   resolutionReason!: ResolutionReason | null;

package/src/core/entities/step-attempt.ts

@@ -13,6 +13,27 @@ export type StepAttemptDisplayDuration =
   | {state: 'fixed'; elapsed: Duration}
   | {state: 'live'; fromIso: string};
 
+export interface EvaluationTraceValueEntry {
+  expression: string;
+  roots: string[];
+  fillTarget: string;
+  evaluatedAt: string;
+  field: string;
+  value?: string;
+  truncated?: boolean;
+  exprTruncated?: boolean;
+  reference?: boolean;
+  degraded?: boolean;
+  envKey?: string;
+}
+
+export interface EvaluationTraceLimitEntry {
+  truncated: true;
+  dropped: number;
+}
+
+export type EvaluationTraceEntry = EvaluationTraceValueEntry | EvaluationTraceLimitEntry;
+
 interface StepAttemptFields {
   id: string;
   stepId: string;
@@ -22,6 +43,8 @@ interface StepAttemptFields {
   status: string;
   exitCode: number | null;
   output: Record<string, unknown> | null;
+  outputs: Record<string, unknown> | null;
+  response: string | null;
   error: Record<string, unknown> | null;
   gateResult: StepGateResult;
   restartFeedback: string | null;
@@ -38,6 +61,8 @@ export class StepAttempt {
   status!: string;
   exitCode!: number | null;
   output!: Record<string, unknown> | null;
+  outputs!: Record<string, unknown> | null;
+  response!: string | null;
   error!: Record<string, unknown> | null;
   gateResult!: StepGateResult;
   restartFeedback!: string | null;
@@ -53,6 +78,14 @@ export class StepAttempt {
   }
 }
 
+export interface StepAttemptDetail {
+  stepId: string;
+  attempt: number;
+  authoredConfig: Record<string, unknown> | null;
+  config: Record<string, unknown> | null;
+  evaluationTrace: EvaluationTraceEntry[] | null;
+}
+
 export function stepAttemptDisplayDurationFromTimestamps({
   startedAt,
   finishedAt,

package/src/core/entities/step.ts

@@ -1,4 +1,4 @@
-import type {StepAttempt} from './step-attempt.js';
+import type {EvaluationTraceEntry, StepAttempt} from './step-attempt.js';
 
 export type StepErrorReason =
   | 'checkout_failed'
@@ -71,8 +71,10 @@ export interface Step {
   name: string;
   sourceLocation: StepSourceLocation | null;
   status: string;
+  statusReason: string | null;
   type: string;
   config: Record<string, unknown>;
+  evaluationTrace: EvaluationTraceEntry[] | null;
   agentConfig: AgentStepConfig | null;
   error: StepError | null;
   position: number;