@shipfox/api-workflows 2.0.0

package/src/core/listener-execution-materialization.ts

@@ -0,0 +1,162 @@
+import {
+  type AgentDefaultsResolver,
+  catalogDefaultAgentResolver,
+} from '@shipfox/api-agent/core/resolve-agent-config';
+import type {WorkflowModel} from '@shipfox/api-definitions';
+import type {
+  AgentToolMaterializationContext,
+  AgentToolMaterializationSnapshot,
+} from './agent-tools.js';
+import type {Job} from './entities/job.js';
+import type {
+  JobExecution,
+  JobExecutionStatus,
+  WorkflowExecutionEvent,
+} from './entities/job-execution.js';
+import type {PersistedEvaluationTraceEntry} from './entities/step.js';
+import type {WorkflowRun} from './entities/workflow-run.js';
+import {
+  AgentConfigUnresolvableError,
+  AgentIntegrationMaterializationError,
+  InterpolationUnresolvableError,
+  InvalidJobRunnerLabelsError,
+} from './errors.js';
+import {
+  assembleExecutionCreationContext,
+  type MaterializedWorkflowStep,
+  materializeJobExecutionSteps,
+  materializeJobRunner,
+  resolveJobExecutionName,
+} from './step-config/index.js';
+
+export interface MaterializeListenerExecutionParams {
+  readonly model: WorkflowModel | null;
+  readonly run: Pick<
+    WorkflowRun,
+    | 'id'
+    | 'name'
+    | 'definitionId'
+    | 'projectId'
+    | 'workspaceId'
+    | 'createdAt'
+    | 'triggerPayload'
+    | 'inputs'
+  >;
+  readonly job: Pick<Job, 'id' | 'key'>;
+  readonly sequence: number;
+  readonly triggerEvents: readonly WorkflowExecutionEvent[];
+  readonly priorExecutions: readonly JobExecution[];
+  readonly resolveAgentDefaults?: AgentDefaultsResolver | undefined;
+  readonly agentToolContext?: AgentToolMaterializationContext | undefined;
+  readonly agentToolSnapshot?: AgentToolMaterializationSnapshot | null | undefined;
+}
+
+export interface MaterializedListenerExecution {
+  readonly name: string;
+  readonly runner: readonly string[];
+  readonly status: JobExecutionStatus;
+  readonly statusReason: 'unknown' | null;
+  readonly triggerEvents: readonly WorkflowExecutionEvent[];
+  readonly evaluationTrace: readonly PersistedEvaluationTraceEntry[] | null;
+  readonly steps: readonly MaterializedWorkflowStep[];
+}
+
+export function materializeListenerExecution(
+  params: MaterializeListenerExecutionParams,
+): MaterializedListenerExecution {
+  const fallbackName = `${params.job.key} #${params.sequence}`;
+  let executionName = fallbackName;
+  let evaluationTrace: readonly PersistedEvaluationTraceEntry[] = [];
+  let runner: readonly string[] = [];
+  let steps: readonly MaterializedWorkflowStep[] = [];
+  let status: JobExecutionStatus = 'pending';
+
+  try {
+    if (!params.model) throw new PermanentListenerMaterializationError('Run attempt has no model');
+    const modelJob = params.model.jobs.find((job) => job.key === params.job.key);
+    if (!modelJob) {
+      throw new PermanentListenerMaterializationError(
+        `Workflow model has no job key: ${params.job.key}`,
+      );
+    }
+
+    const resolvedName = resolveJobExecutionName({
+      definitionId: params.run.definitionId,
+      job: modelJob,
+      fallbackName,
+      context: listenerExecutionContext({...params, executionName, status}).values,
+    });
+    executionName = resolvedName.value;
+    evaluationTrace = resolvedName.trace;
+
+    const context = listenerExecutionContext({...params, executionName, status});
+    runner = materializeJobRunner({
+      job: modelJob,
+      context,
+      definitionId: params.run.definitionId,
+    });
+    steps = materializeJobExecutionSteps({
+      model: params.model,
+      job: modelJob,
+      context,
+      resolveAgentDefaults: params.resolveAgentDefaults ?? catalogDefaultAgentResolver,
+      definitionId: params.run.definitionId,
+      agentToolContext: params.agentToolContext,
+      agentToolSnapshot: params.agentToolSnapshot,
+    });
+  } catch (error) {
+    if (!isPermanentListenerMaterializationError(error)) throw error;
+    status = 'failed';
+    steps = [];
+    runner = [];
+  }
+
+  return {
+    name: executionName,
+    runner,
+    status,
+    statusReason: status === 'failed' ? 'unknown' : null,
+    triggerEvents: params.triggerEvents,
+    evaluationTrace: evaluationTrace.length === 0 ? null : evaluationTrace,
+    steps,
+  };
+}
+
+function listenerExecutionContext(
+  params: Pick<
+    MaterializeListenerExecutionParams,
+    'run' | 'job' | 'sequence' | 'triggerEvents' | 'priorExecutions'
+  > & {
+    readonly executionName: string;
+    readonly status: JobExecutionStatus;
+  },
+) {
+  return assembleExecutionCreationContext({
+    run: params.run,
+    triggerPayload: params.run.triggerPayload,
+    inputs: params.run.inputs,
+    jobId: params.job.id,
+    sequence: params.sequence,
+    executionName: params.executionName,
+    status: params.status,
+    triggerEvents: params.triggerEvents,
+    priorExecutions: params.priorExecutions,
+  });
+}
+
+class PermanentListenerMaterializationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PermanentListenerMaterializationError';
+  }
+}
+
+function isPermanentListenerMaterializationError(error: unknown): boolean {
+  return (
+    error instanceof PermanentListenerMaterializationError ||
+    error instanceof InterpolationUnresolvableError ||
+    error instanceof InvalidJobRunnerLabelsError ||
+    error instanceof AgentConfigUnresolvableError ||
+    error instanceof AgentIntegrationMaterializationError
+  );
+}

package/src/core/run-workflow.test.ts

@@ -0,0 +1,229 @@
+import type {WorkflowDefinition} from '@shipfox/api-definitions';
+import {workflowModel} from '#test/index.js';
+import type {TriggerPayload} from './entities/workflow-run.js';
+import {DefinitionNotFoundError, ProjectMismatchError} from './errors.js';
+import {runWorkflow} from './run-workflow.js';
+
+const mockCreateWorkspaceAgentDefaultsResolver = vi.hoisted(() => vi.fn());
+const mockWorkspaceAgentDefaultsResolver = vi.hoisted(() =>
+  vi.fn().mockReturnValue({
+    harness: 'pi',
+    provider: 'openai',
+    model: 'gpt-5.5-pro',
+    thinking: 'medium',
+  }),
+);
+
+vi.mock('@shipfox/api-definitions', () => ({
+  DEFAULT_JOB_CHECKOUT: {
+    permissions: {contents: 'read'},
+    persistCredentials: true,
+  },
+  getDefinitionById: vi.fn(),
+}));
+
+vi.mock('@shipfox/api-agent/core/resolve-agent-config', () => {
+  return {
+    catalogDefaultAgentResolver: vi.fn().mockReturnValue({
+      harness: 'pi',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'xhigh',
+    }),
+  };
+});
+
+vi.mock('@shipfox/api-agent/core/workspace-agent-defaults-resolver', () => {
+  return {
+    createWorkspaceAgentDefaultsResolver: mockCreateWorkspaceAgentDefaultsResolver,
+  };
+});
+
+import {getDefinitionById} from '@shipfox/api-definitions';
+
+const mockGetDefinitionById = vi.mocked(getDefinitionById);
+
+function buildDefinition(overrides?: Partial<WorkflowDefinition>): WorkflowDefinition {
+  const model = workflowModel();
+  const document = {
+    name: model.name,
+    jobs: {
+      build: {steps: [{run: 'echo hello'}]},
+    },
+  };
+  return {
+    id: crypto.randomUUID(),
+    projectId: crypto.randomUUID(),
+    configPath: '.shipfox/workflows/test.yml',
+    source: 'manual',
+    sha: null,
+    ref: null,
+    name: 'Test Workflow',
+    definition: document,
+    document,
+    model,
+    sourceSnapshot: null,
+    contentHash: null,
+    fetchedAt: new Date(),
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    deletedAt: null,
+    ...overrides,
+  };
+}
+
+function manualPayload(): TriggerPayload {
+  return {
+    source: 'manual',
+    event: 'fire',
+    subscriptionId: crypto.randomUUID(),
+    userId: crypto.randomUUID(),
+  };
+}
+
+describe('runWorkflow', () => {
+  let workspaceId: string;
+  let projectId: string;
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+    projectId = crypto.randomUUID();
+    mockCreateWorkspaceAgentDefaultsResolver.mockClear();
+    mockCreateWorkspaceAgentDefaultsResolver.mockResolvedValue(mockWorkspaceAgentDefaultsResolver);
+    mockWorkspaceAgentDefaultsResolver.mockClear();
+  });
+
+  test('creates a run from a valid definition with the provided manual trigger payload', async () => {
+    const definition = buildDefinition({projectId});
+    mockGetDefinitionById.mockResolvedValue(definition);
+    const triggerPayload = manualPayload();
+
+    const run = await runWorkflow({
+      workspaceId,
+      projectId,
+      definitionId: definition.id,
+      triggerPayload,
+    });
+
+    expect(run.id).toBeDefined();
+    expect(run.projectId).toBe(projectId);
+    expect(run.definitionId).toBe(definition.id);
+    expect(run.name).toBe(definition.name);
+    expect(run.status).toBe('pending');
+    expect(run.triggerProvider).toBeNull();
+    expect(run.triggerSource).toBe('manual');
+    expect(run.triggerEvent).toBe('fire');
+    expect(run.triggerPayload).toEqual(triggerPayload);
+    expect(mockCreateWorkspaceAgentDefaultsResolver).not.toHaveBeenCalled();
+  });
+
+  test('builds the workspace agent resolver only when the definition has an agent step', async () => {
+    const model = workflowModel({
+      jobs: {
+        fix: {steps: [{prompt: 'Fix the failing tests.'}]},
+      },
+    });
+    const definition = buildDefinition({projectId, model});
+    mockGetDefinitionById.mockResolvedValue(definition);
+
+    const run = await runWorkflow({
+      workspaceId,
+      projectId,
+      definitionId: definition.id,
+      triggerPayload: manualPayload(),
+    });
+
+    expect(run.id).toBeDefined();
+    expect(mockCreateWorkspaceAgentDefaultsResolver).toHaveBeenCalledWith(workspaceId);
+    expect(mockWorkspaceAgentDefaultsResolver).toHaveBeenCalledWith({
+      harness: undefined,
+      provider: undefined,
+      model: undefined,
+      thinking: undefined,
+    });
+  });
+
+  test('persists an integration trigger payload intact', async () => {
+    const definition = buildDefinition({projectId});
+    mockGetDefinitionById.mockResolvedValue(definition);
+    const triggerPayload: TriggerPayload = {
+      provider: 'github',
+      source: 'github_acme',
+      event: 'push',
+      deliveryId: crypto.randomUUID(),
+      data: {ref: 'main', headCommitSha: 'abc', externalRepositoryId: 'github:1'},
+    };
+
+    const run = await runWorkflow({
+      workspaceId,
+      projectId,
+      definitionId: definition.id,
+      triggerPayload,
+    });
+
+    expect(run.triggerProvider).toBe('github');
+    expect(run.triggerSource).toBe('github_acme');
+    expect(run.triggerEvent).toBe('push');
+    expect(run.triggerPayload).toEqual(triggerPayload);
+  });
+
+  test('creates the run with the definition source snapshot', async () => {
+    const sourceSnapshot = {content: 'name: Test Workflow\njobs: {}\n', format: 'yaml'} as const;
+    const definition = buildDefinition({projectId, sourceSnapshot});
+    mockGetDefinitionById.mockResolvedValue(definition);
+
+    const run = await runWorkflow({
+      workspaceId,
+      projectId,
+      definitionId: definition.id,
+      triggerPayload: manualPayload(),
+    });
+
+    expect(run.sourceSnapshot).toEqual(sourceSnapshot);
+  });
+
+  test('throws DefinitionNotFoundError for unknown definition', async () => {
+    mockGetDefinitionById.mockResolvedValue(undefined);
+
+    const unknownId = crypto.randomUUID();
+
+    await expect(
+      runWorkflow({
+        workspaceId,
+        projectId,
+        definitionId: unknownId,
+        triggerPayload: manualPayload(),
+      }),
+    ).rejects.toThrow(DefinitionNotFoundError);
+  });
+
+  test('throws ProjectMismatchError when definition.projectId does not match', async () => {
+    const otherProjectId = crypto.randomUUID();
+    const definition = buildDefinition({projectId: otherProjectId});
+    mockGetDefinitionById.mockResolvedValue(definition);
+
+    await expect(
+      runWorkflow({
+        workspaceId,
+        projectId,
+        definitionId: definition.id,
+        triggerPayload: manualPayload(),
+      }),
+    ).rejects.toThrow(ProjectMismatchError);
+  });
+
+  test('passes inputs through to the run', async () => {
+    const definition = buildDefinition({projectId});
+    mockGetDefinitionById.mockResolvedValue(definition);
+
+    const run = await runWorkflow({
+      workspaceId,
+      projectId,
+      definitionId: definition.id,
+      triggerPayload: manualPayload(),
+      inputs: {env: 'staging'},
+    });
+
+    expect(run.inputs).toEqual({env: 'staging'});
+  });
+});

package/src/core/run-workflow.ts

@@ -0,0 +1,41 @@
+import {catalogDefaultAgentResolver} from '@shipfox/api-agent/core/resolve-agent-config';
+import {createWorkspaceAgentDefaultsResolver} from '@shipfox/api-agent/core/workspace-agent-defaults-resolver';
+import {getDefinitionById} from '@shipfox/api-definitions';
+import {createWorkflowRun} from '#db/workflow-runs.js';
+import type {TriggerPayload, WorkflowRun} from './entities/workflow-run.js';
+import {DefinitionNotFoundError, ProjectMismatchError} from './errors.js';
+import {modelHasAgentStep} from './step-config/materialize-workflow-model.js';
+
+export interface RunWorkflowParams {
+  workspaceId: string;
+  projectId: string;
+  definitionId: string;
+  triggerPayload: TriggerPayload;
+  inputs?: Record<string, unknown> | undefined;
+  triggerIdempotencyKey?: string | undefined;
+}
+
+export async function runWorkflow(params: RunWorkflowParams): Promise<WorkflowRun> {
+  const definition = await getDefinitionById(params.definitionId);
+  if (!definition) throw new DefinitionNotFoundError(params.definitionId);
+
+  if (definition.projectId !== params.projectId) {
+    throw new ProjectMismatchError(definition.projectId, params.projectId);
+  }
+  const resolveAgentDefaults = modelHasAgentStep(definition.model)
+    ? await createWorkspaceAgentDefaultsResolver(params.workspaceId)
+    : catalogDefaultAgentResolver;
+
+  return createWorkflowRun({
+    workspaceId: params.workspaceId,
+    projectId: params.projectId,
+    definitionId: definition.id,
+    name: definition.name,
+    model: definition.model,
+    triggerPayload: params.triggerPayload,
+    inputs: params.inputs,
+    sourceSnapshot: definition.sourceSnapshot,
+    triggerIdempotencyKey: params.triggerIdempotencyKey,
+    resolveAgentDefaults,
+  });
+}

package/src/core/source-control.test.ts

@@ -0,0 +1,17 @@
+import type {IntegrationSourceControlService} from '@shipfox/api-integration-core';
+import {clearSourceControl, setSourceControl, sourceControl} from './source-control.js';
+
+describe('sourceControl', () => {
+  it('returns the configured service', () => {
+    const service = {} as IntegrationSourceControlService;
+    setSourceControl(service);
+
+    expect(sourceControl()).toBe(service);
+  });
+
+  it('throws when the source-control integration is not configured', () => {
+    clearSourceControl();
+
+    expect(() => sourceControl()).toThrow('source-control integration is not configured');
+  });
+});

package/src/core/source-control.ts

@@ -0,0 +1,22 @@
+import type {IntegrationSourceControlService} from '@shipfox/api-integration-core';
+
+// Boot-set holder for the integration source-control service, mirroring the db()
+// singleton. The composition root injects it once at startup; routes read it.
+// Workflows cannot construct the service itself (it needs the integration provider
+// registry and connection lookup that live in @shipfox/api-integration-core).
+let _sourceControl: IntegrationSourceControlService | undefined;
+
+export function setSourceControl(service: IntegrationSourceControlService): void {
+  _sourceControl = service;
+}
+
+export function clearSourceControl(): void {
+  _sourceControl = undefined;
+}
+
+export function sourceControl(): IntegrationSourceControlService {
+  if (!_sourceControl) {
+    throw new Error('workflows: source-control integration is not configured');
+  }
+  return _sourceControl;
+}