@shipfox/api-workflows 2.0.0

package/src/presentation/dto/step.test.ts

@@ -0,0 +1,307 @@
+import type {Step, StepAttempt} from '#core/entities/step.js';
+import {fromStepErrorDto, toStepAttemptDto, toStepDto} from './step.js';
+
+function step(overrides: Partial<Step> & {type: string}): Step {
+  return {
+    id: '00000000-0000-0000-0000-000000000001',
+    jobExecutionId: '00000000-0000-0000-0000-0000000000bb',
+    key: null,
+    name: 'step',
+    sourceLocation: null,
+    status: 'failed',
+    statusReason: null,
+    evaluationTrace: null,
+    config: {},
+    condition: null,
+    configPlan: null,
+    authoredConfig: null,
+    error: null,
+    position: 0,
+    version: 1,
+    currentAttempt: 1,
+    createdAt: new Date('2026-01-01T00:00:00.000Z'),
+    updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+    ...overrides,
+  };
+}
+
+describe('fromStepErrorDto', () => {
+  it('persists the machine-readable reason in camelCase', () => {
+    const persisted = fromStepErrorDto({
+      message: 'mkdir denied',
+      reason: 'workspace_prep_failed',
+    });
+
+    expect(persisted).toEqual({message: 'mkdir denied', reason: 'workspace_prep_failed'});
+  });
+
+  it('persists the machine-readable agent config issue in camelCase', () => {
+    const persisted = fromStepErrorDto({
+      message: 'Missing credentials',
+      reason: 'agent_config_invalid',
+      agent_config_issue: 'provider_not_configured',
+    });
+
+    expect(persisted).toEqual({
+      message: 'Missing credentials',
+      reason: 'agent_config_invalid',
+      agentConfigIssue: 'provider_not_configured',
+    });
+  });
+
+  it('persists config error field and source diagnostics', () => {
+    const persisted = fromStepErrorDto({
+      message: 'Could not resolve env.VERSION',
+      reason: 'config_unresolvable',
+      field: 'env.VERSION',
+      source: 'steps.build.outputs.version',
+    });
+
+    expect(persisted).toEqual({
+      message: 'Could not resolve env.VERSION',
+      reason: 'config_unresolvable',
+      field: 'env.VERSION',
+      source: 'steps.build.outputs.version',
+    });
+  });
+
+  it('ignores a runner-supplied category (the server derives it on read)', () => {
+    const persisted = fromStepErrorDto({
+      message: 'mkdir denied',
+      reason: 'workspace_prep_failed',
+      category: 'setup',
+    });
+
+    expect(persisted).not.toHaveProperty('category');
+  });
+
+  it('returns null for a missing error', () => {
+    expect(fromStepErrorDto(undefined)).toBeNull();
+    expect(fromStepErrorDto(null)).toBeNull();
+  });
+});
+
+describe('toStepDto error category', () => {
+  it("derives category 'setup' for a setup step error and surfaces the reason", () => {
+    const dto = toStepDto(
+      step({type: 'setup', error: {message: 'mkdir denied', reason: 'workspace_prep_failed'}}),
+    );
+
+    expect(dto.error).toEqual({
+      message: 'mkdir denied',
+      reason: 'workspace_prep_failed',
+      category: 'setup',
+    });
+  });
+
+  it("derives category 'user' for a run step error", () => {
+    const dto = toStepDto(
+      step({type: 'run', error: {message: 'Command exited with code 1', exitCode: 1}}),
+    );
+
+    expect(dto.error).toEqual({
+      message: 'Command exited with code 1',
+      exit_code: 1,
+      category: 'user',
+    });
+  });
+
+  it("derives category 'user' for an agent config error and surfaces the reason", () => {
+    const dto = toStepDto(
+      step({
+        type: 'agent',
+        error: {
+          message: 'Unknown provider "foo" for agent step.',
+          reason: 'agent_config_invalid',
+          agentConfigIssue: 'provider_unsupported',
+        },
+      }),
+    );
+
+    expect(dto.error).toEqual({
+      message: 'Unknown provider "foo" for agent step.',
+      reason: 'agent_config_invalid',
+      agent_config_issue: 'provider_unsupported',
+      category: 'user',
+    });
+  });
+
+  it('surfaces config error field and source diagnostics', () => {
+    const dto = toStepDto(
+      step({
+        type: 'run',
+        error: {
+          message: 'Could not resolve env.VERSION',
+          reason: 'config_unresolvable',
+          field: 'env.VERSION',
+          source: 'steps.build.outputs.version',
+        },
+      }),
+    );
+
+    expect(dto.error).toEqual({
+      message: 'Could not resolve env.VERSION',
+      reason: 'config_unresolvable',
+      field: 'env.VERSION',
+      source: 'steps.build.outputs.version',
+      category: 'user',
+    });
+  });
+
+  it('renders no error (and no category) for a successful step', () => {
+    const dto = toStepDto(step({type: 'run', status: 'succeeded', error: null}));
+
+    expect(dto.error).toBeNull();
+  });
+
+  it('maps source locations to snake_case', () => {
+    const dto = toStepDto(
+      step({type: 'run', sourceLocation: {startLine: 5, endLine: 8}, error: null}),
+    );
+
+    expect(dto.source_location).toEqual({start_line: 5, end_line: 8});
+  });
+
+  it('maps missing source locations to null', () => {
+    const dto = toStepDto(step({type: 'setup', sourceLocation: null, error: null}));
+
+    expect(dto.source_location).toBeNull();
+  });
+});
+
+const baseAttempt: StepAttempt = {
+  id: '11111111-1111-4111-8111-111111111111',
+  stepId: '22222222-2222-4222-8222-222222222222',
+  attempt: 1,
+  executionOrder: 1,
+  status: 'failed',
+  config: null,
+  evaluationTrace: null,
+  output: null,
+  response: null,
+  error: null,
+  exitCode: 1,
+  gateResult: {passed: 'yes'},
+  restartFeedback: null,
+  logOutcome: null,
+  startedAt: new Date('2026-01-01T00:00:00.000Z'),
+  finishedAt: new Date('2026-01-01T00:01:00.000Z'),
+  createdAt: new Date('2026-01-01T00:00:00.000Z'),
+};
+
+describe('toStepAttemptDto', () => {
+  it('maps passed gate payloads to typed gate results', () => {
+    const attempt: StepAttempt = {
+      ...baseAttempt,
+      status: 'succeeded',
+      exitCode: 0,
+      gateResult: {passed: true, source: 'exit_code == 0', exit_code: 0},
+    };
+
+    const result = toStepAttemptDto(attempt);
+
+    expect(result.gate_result).toEqual({
+      kind: 'passed',
+      passed: true,
+      source: 'exit_code == 0',
+      exit_code: 0,
+    });
+  });
+
+  it('maps failed gate payloads to typed gate results', () => {
+    const attempt: StepAttempt = {
+      ...baseAttempt,
+      gateResult: {passed: false, source: 'exit_code == 0', exit_code: 1},
+    };
+
+    const result = toStepAttemptDto(attempt);
+
+    expect(result.gate_result).toEqual({
+      kind: 'failed',
+      passed: false,
+      source: 'exit_code == 0',
+      exit_code: 1,
+    });
+  });
+
+  it('maps uncheckable gate payloads before generic failed payloads', () => {
+    const attempt: StepAttempt = {
+      ...baseAttempt,
+      gateResult: {passed: false, uncheckable: true, reason: 'missing output', exit_code: null},
+    };
+
+    const result = toStepAttemptDto(attempt);
+
+    expect(result.gate_result).toEqual({
+      kind: 'uncheckable',
+      passed: false,
+      uncheckable: true,
+      reason: 'missing output',
+      exit_code: null,
+    });
+  });
+
+  it('maps missing gate payloads to an explicit none result', () => {
+    const attempt: StepAttempt = {...baseAttempt, gateResult: null};
+
+    const result = toStepAttemptDto(attempt);
+
+    expect(result.gate_result).toEqual({kind: 'none'});
+    expect(result.restart_feedback).toBeNull();
+  });
+
+  it('maps running attempts without gate payloads to not evaluated', () => {
+    const attempt: StepAttempt = {...baseAttempt, status: 'running', gateResult: null};
+
+    const result = toStepAttemptDto(attempt);
+
+    expect(result.gate_result).toEqual({kind: 'not_evaluated'});
+  });
+
+  it('maps gate expression failures to typed evaluation errors', () => {
+    const attempt: StepAttempt = {
+      ...baseAttempt,
+      gateResult: {
+        passed: false,
+        uncheckable: true,
+        reason: 'gate expression evaluation failed',
+        exit_code: 1,
+      },
+    };
+
+    const result = toStepAttemptDto(attempt);
+
+    expect(result.gate_result).toEqual({
+      kind: 'evaluation_error',
+      reason: 'gate expression evaluation failed',
+      exit_code: 1,
+    });
+  });
+
+  it('maps restart feedback', () => {
+    const attempt: StepAttempt = {
+      ...baseAttempt,
+      output: {summary: 'looks good'},
+      response: 'done',
+      restartFeedback: 'gate condition not met',
+    };
+
+    const result = toStepAttemptDto(attempt);
+
+    expect(result.output).toEqual({summary: 'looks good'});
+    expect(result.outputs).toEqual({summary: 'looks good'});
+    expect(result.response).toBe('done');
+    expect(result.restart_feedback).toBe('gate condition not met');
+  });
+
+  it('maps legacy gate payloads to an explicit unknown result', () => {
+    const attempt = baseAttempt;
+
+    const result = toStepAttemptDto(attempt);
+
+    expect(result.gate_result).toEqual({
+      kind: 'unknown',
+      data: {passed: 'yes'},
+    });
+  });
+});

package/src/presentation/dto/step.ts

@@ -0,0 +1,145 @@
+import {
+  agentConfigIssueSchema,
+  type StepAttemptDto,
+  type StepDto,
+  type StepErrorCategoryDto,
+  type StepErrorDto,
+  type StepGateResultDto,
+  stepErrorReasonSchema,
+} from '@shipfox/api-workflows-dto';
+import type {Step, StepAttempt} from '#core/entities/step.js';
+import {GATE_EVALUATION_ERROR_REASON} from '#core/step-transition/evaluate-gate.js';
+
+// Domain `error` is loosely typed (jsonb), so narrow it to the fixed runner
+// contract rather than trusting whatever shape the row happens to hold. `category`
+// is not stored on the row; the caller derives it from the step type and passes it
+// in (server-authoritative, never trusted from the runner).
+function toStepErrorDto(
+  error: Record<string, unknown> | null,
+  category: StepErrorCategoryDto,
+): StepErrorDto {
+  if (error === null) return null;
+  const message = typeof error.message === 'string' ? error.message : '';
+  const exitCode = error.exitCode;
+  const signal = typeof error.signal === 'string' ? error.signal : undefined;
+  const field = typeof error.field === 'string' ? error.field : undefined;
+  const source = typeof error.source === 'string' ? error.source : undefined;
+  const reason = stepErrorReasonSchema.safeParse(error.reason);
+  const agentConfigIssue = agentConfigIssueSchema.safeParse(error.agentConfigIssue);
+  return {
+    message,
+    ...(exitCode === null || typeof exitCode === 'number' ? {exit_code: exitCode} : {}),
+    ...(signal === undefined ? {} : {signal}),
+    ...(reason.success ? {reason: reason.data} : {}),
+    ...(field === undefined ? {} : {field}),
+    ...(source === undefined ? {} : {source}),
+    ...(agentConfigIssue.success ? {agent_config_issue: agentConfigIssue.data} : {}),
+    category,
+  };
+}
+
+// Inverse of toStepErrorDto: reported wire errors land on the domain row in
+// camelCase so the read path renders them back without a special case. `category`
+// is intentionally NOT persisted — the server derives it from the step type on
+// read, so a runner-supplied category is ignored here.
+export function fromStepErrorDto(error: StepErrorDto | undefined): Record<string, unknown> | null {
+  if (!error) return null;
+  return {
+    message: error.message,
+    ...(error.exit_code === null || typeof error.exit_code === 'number'
+      ? {exitCode: error.exit_code}
+      : {}),
+    ...(typeof error.signal === 'string' ? {signal: error.signal} : {}),
+    ...(error.reason === undefined ? {} : {reason: error.reason}),
+    ...(error.field === undefined ? {} : {field: error.field}),
+    ...(error.source === undefined ? {} : {source: error.source}),
+    ...(error.agent_config_issue === undefined ? {} : {agentConfigIssue: error.agent_config_issue}),
+  };
+}
+
+function isIntOrNull(value: unknown): value is number | null {
+  return value === null || (typeof value === 'number' && Number.isInteger(value));
+}
+
+function toStepGateResultDto(
+  gateResult: Record<string, unknown> | null,
+  status: string,
+): StepGateResultDto {
+  if (gateResult === null) {
+    return status === 'running' || status === 'pending' ? {kind: 'not_evaluated'} : {kind: 'none'};
+  }
+
+  const exitCode = gateResult.exit_code;
+  const passed = gateResult.passed;
+  const source = gateResult.source;
+  const reason = gateResult.reason;
+
+  if (passed === true && typeof source === 'string' && isIntOrNull(exitCode)) {
+    return {kind: 'passed', passed, source, exit_code: exitCode};
+  }
+
+  if (
+    passed === false &&
+    gateResult.uncheckable === true &&
+    typeof reason === 'string' &&
+    isIntOrNull(exitCode)
+  ) {
+    if (reason === GATE_EVALUATION_ERROR_REASON) {
+      return {kind: 'evaluation_error', reason, exit_code: exitCode};
+    }
+    return {kind: 'uncheckable', passed, uncheckable: true, reason, exit_code: exitCode};
+  }
+
+  if (passed === false && typeof source === 'string' && isIntOrNull(exitCode)) {
+    return {kind: 'failed', passed, source, exit_code: exitCode};
+  }
+
+  return {kind: 'unknown', data: gateResult};
+}
+
+export function toStepDto(step: Step): StepDto {
+  return {
+    id: step.id,
+    job_execution_id: step.jobExecutionId,
+    key: step.key,
+    name: step.name,
+    source_location: toStepSourceLocationDto(step.sourceLocation),
+    status: step.status,
+    type: step.type,
+    config: step.config,
+    error: toStepErrorDto(step.error, step.type === 'setup' ? 'setup' : 'user'),
+    position: step.position,
+    current_attempt: step.currentAttempt,
+    created_at: step.createdAt.toISOString(),
+    updated_at: step.updatedAt.toISOString(),
+  };
+}
+
+function toStepSourceLocationDto(
+  sourceLocation: Step['sourceLocation'],
+): StepDto['source_location'] {
+  if (sourceLocation === null) return null;
+  return {
+    start_line: sourceLocation.startLine,
+    end_line: sourceLocation.endLine,
+  };
+}
+
+export function toStepAttemptDto(attempt: StepAttempt): StepAttemptDto {
+  return {
+    id: attempt.id,
+    step_id: attempt.stepId,
+    attempt: attempt.attempt,
+    execution_order: attempt.executionOrder,
+    status: attempt.status,
+    exit_code: attempt.exitCode,
+    output: attempt.output,
+    outputs: attempt.output,
+    response: attempt.response,
+    error: attempt.error,
+    gate_result: toStepGateResultDto(attempt.gateResult, attempt.status),
+    restart_feedback: attempt.restartFeedback,
+    started_at: attempt.startedAt.toISOString(),
+    finished_at: attempt.finishedAt ? attempt.finishedAt.toISOString() : null,
+  };
+}

package/src/presentation/dto/workflow-run.ts

@@ -0,0 +1,38 @@
+import type {WorkflowRunAttemptDto, WorkflowRunDto} from '@shipfox/api-workflows-dto';
+import type {WorkflowRun} from '#core/entities/workflow-run.js';
+import type {WorkflowRunAttempt} from '#core/entities/workflow-run-attempt.js';
+
+export function toRunDto(run: WorkflowRun, latestAttempt = run.currentAttempt): WorkflowRunDto {
+  return {
+    id: run.id,
+    project_id: run.projectId,
+    definition_id: run.definitionId,
+    name: run.name,
+    status: run.status,
+    current_attempt: run.currentAttempt,
+    latest_attempt: latestAttempt,
+    trigger_provider: run.triggerProvider,
+    trigger_source: run.triggerSource,
+    trigger_event: run.triggerEvent,
+    trigger_payload: run.triggerPayload,
+    inputs: run.inputs,
+    source_snapshot: run.sourceSnapshot,
+    created_at: run.createdAt.toISOString(),
+    updated_at: run.updatedAt.toISOString(),
+    started_at: run.startedAt?.toISOString() ?? null,
+    finished_at: run.finishedAt?.toISOString() ?? null,
+  };
+}
+
+export function toRunAttemptDto(attempt: WorkflowRunAttempt): WorkflowRunAttemptDto {
+  return {
+    id: attempt.id,
+    workflow_run_id: attempt.workflowRunId,
+    attempt: attempt.attempt,
+    status: attempt.status,
+    created_at: attempt.createdAt.toISOString(),
+    started_at: attempt.startedAt?.toISOString() ?? null,
+    finished_at: attempt.finishedAt?.toISOString() ?? null,
+    rerun_mode: attempt.rerunMode,
+  };
+}

package/src/presentation/index.ts

@@ -0,0 +1,10 @@
+export {workflowRoutes as routes} from './routes/index.js';
+export {
+  onJobEventDelivered,
+  onJobStepsSettled,
+  onRunnerJobClaimed,
+  onRunnerJobLeaseExpired,
+  onRunnerJobQueued,
+  onWorkflowRunAttemptCreated,
+  onWorkflowRunCancelled,
+} from './subscribers/index.js';