@shipfox/api-workflows 2.0.0

package/src/core/step-config/materialize-workflow-model.ts

@@ -0,0 +1,140 @@
+import type {AgentDefaultsResolver} from '@shipfox/api-agent/core/resolve-agent-config';
+import type {WorkflowModel} from '@shipfox/api-definitions';
+import {canonicalizeLabels, findInvalidLabels, MAX_RUNNER_LABELS} from '@shipfox/runner-labels';
+import type {
+  AgentToolMaterializationContext,
+  AgentToolMaterializationSnapshot,
+} from '#core/agent-tools.js';
+import {InvalidJobRunnerLabelsError} from '#core/errors.js';
+import {completeStepField} from './fields.js';
+import {
+  type MaterializedWorkflowStep,
+  materializeJobExecutionSteps,
+} from './materialize-job-execution-steps.js';
+import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
+
+type WorkflowModelJob = WorkflowModel['jobs'][number];
+export interface MaterializedWorkflowJob {
+  readonly key: string;
+  readonly mode: WorkflowModelJob['mode'];
+  readonly success?: string;
+  readonly executionTimeoutMs?: number;
+  readonly checkout: WorkflowModelJob['checkout'];
+  readonly listening?: WorkflowModelJob['listening'];
+  readonly name?: WorkflowModelJob['name'];
+  readonly outputs?: WorkflowModelJob['outputs'];
+  readonly dependencies: readonly string[];
+  readonly runner: readonly string[];
+  readonly position: number;
+  readonly steps: readonly MaterializedWorkflowStep[];
+}
+
+export interface MaterializeWorkflowModelParams {
+  readonly model: WorkflowModel;
+  readonly context?: WorkflowEvaluationContext | undefined;
+  readonly resolveAgentDefaults?: AgentDefaultsResolver | undefined;
+  readonly definitionId?: string | undefined;
+  readonly agentToolContext?: AgentToolMaterializationContext | undefined;
+  readonly agentToolSnapshot?: AgentToolMaterializationSnapshot | null | undefined;
+}
+
+export function materializeWorkflowModel(
+  params: MaterializeWorkflowModelParams,
+): readonly MaterializedWorkflowJob[] {
+  const {
+    model,
+    context = {site: 'run-creation', values: {}},
+    resolveAgentDefaults,
+    definitionId = model.name,
+    agentToolContext,
+    agentToolSnapshot,
+  } = params;
+  const jobsById = new Map(model.jobs.map((job) => [job.id, job]));
+
+  return model.jobs.map((job, position) => ({
+    key: job.key,
+    mode: job.mode,
+    ...(job.success === undefined ? {} : {success: job.success}),
+    ...(job.executionTimeoutMs === undefined ? {} : {executionTimeoutMs: job.executionTimeoutMs}),
+    checkout: job.checkout,
+    ...(job.listening === undefined ? {} : {listening: job.listening}),
+    ...(job.name === undefined ? {} : {name: job.name}),
+    ...(job.outputs === undefined ? {} : {outputs: job.outputs}),
+    dependencies: dependencySourceNames(job, jobsById),
+    runner: job.runner,
+    position,
+    steps:
+      job.mode === 'listening'
+        ? []
+        : materializeJobExecutionSteps({
+            model,
+            job,
+            context,
+            resolveAgentDefaults,
+            definitionId,
+            agentToolContext,
+            agentToolSnapshot,
+          }),
+  }));
+}
+
+export function materializeJobRunner(params: {
+  readonly job: WorkflowModelJob;
+  readonly context: WorkflowEvaluationContext;
+  readonly definitionId: string;
+}): readonly string[] {
+  const resolvedLabels = (params.job.runnerTemplates ?? []).map((template) =>
+    completeStepField({
+      field: 'job.runner',
+      errorField: 'job.runner',
+      template: {segments: template},
+      context: params.context,
+      definitionId: params.definitionId,
+    }),
+  );
+  const labels = canonicalizeLabels([...params.job.runner, ...resolvedLabels]);
+  const invalidLabels = findInvalidLabels(labels);
+  if (labels.length === 0 || labels.length > MAX_RUNNER_LABELS || invalidLabels.length > 0) {
+    throw new InvalidJobRunnerLabelsError(labels);
+  }
+  return labels;
+}
+
+export function materializeJobOutputs(params: {
+  readonly job: WorkflowModelJob;
+  readonly context: WorkflowEvaluationContext;
+  readonly definitionId: string;
+}): Record<string, string> | null {
+  const outputs = params.job.outputs;
+  if (outputs === undefined) return null;
+
+  return Object.fromEntries(
+    Object.entries(outputs).map(([key, template]) => [
+      key,
+      completeStepField({
+        field: 'job.outputs',
+        errorField: 'job.outputs',
+        template: {segments: template},
+        context: params.context,
+        definitionId: params.definitionId,
+      }),
+    ]),
+  );
+}
+
+export function modelHasAgentStep(model: WorkflowModel): boolean {
+  return model.jobs.some((job) => job.steps.some((step) => step.kind === 'agent'));
+}
+
+function dependencySourceNames(
+  job: WorkflowModelJob,
+  jobsById: ReadonlyMap<string, WorkflowModelJob>,
+): readonly string[] {
+  return job.dependencies.map((dependencyId) => {
+    const dependency = jobsById.get(dependencyId);
+    if (!dependency) {
+      throw new Error(`Unresolved workflow model dependency "${dependencyId}" for job "${job.id}"`);
+    }
+    return dependency.key;
+  });
+}

package/src/core/step-config/resolve-job-execution-name.test.ts

@@ -0,0 +1,94 @@
+import {workflowModel} from '#test/index.js';
+import {resolveJobExecutionName} from './resolve-job-execution-name.js';
+
+function template(source: string): string {
+  return `\${{ ${source} }}`;
+}
+
+describe('resolveJobExecutionName', () => {
+  it('resolves an interpolated job name at execution creation', () => {
+    const [job] = workflowModel({
+      jobs: {
+        deploy: {
+          name: `Deploy ${template('inputs.environment')}`,
+          steps: [{run: 'echo deploy'}],
+        },
+      },
+    }).jobs;
+    if (!job) throw new Error('Missing deploy job');
+
+    const result = resolveJobExecutionName({
+      definitionId: 'definition-1',
+      job,
+      fallbackName: 'deploy #1',
+      context: {inputs: {environment: 'prod'}},
+    });
+
+    expect(result).toMatchObject({
+      value: 'Deploy prod',
+      trace: [
+        {
+          field: 'job.name',
+          expression: 'inputs.environment',
+          roots: ['inputs'],
+          fillTarget: 'run-creation',
+          evaluatedAt: 'execution-creation',
+          value: 'prod',
+        },
+      ],
+    });
+  });
+
+  it('falls back when the name template resolves to an empty string', () => {
+    const [job] = workflowModel({
+      jobs: {
+        deploy: {
+          name: template('inputs.environment'),
+          steps: [{run: 'echo deploy'}],
+        },
+      },
+    }).jobs;
+    if (!job) throw new Error('Missing deploy job');
+
+    const result = resolveJobExecutionName({
+      definitionId: 'definition-1',
+      job,
+      fallbackName: 'deploy #1',
+      context: {inputs: {environment: ''}},
+    });
+
+    expect(result).toMatchObject({
+      value: 'deploy #1',
+      trace: [
+        {
+          field: 'job.name',
+          expression: 'inputs.environment',
+          roots: ['inputs'],
+          fillTarget: 'run-creation',
+          evaluatedAt: 'execution-creation',
+          value: '',
+        },
+      ],
+    });
+  });
+
+  it('falls back when the job has no name template', () => {
+    const [job] = workflowModel({
+      jobs: {
+        deploy: {
+          steps: [{run: 'echo deploy'}],
+        },
+      },
+    }).jobs;
+    if (!job) throw new Error('Missing deploy job');
+
+    const result = resolveJobExecutionName({
+      definitionId: 'definition-1',
+      job,
+      fallbackName: 'deploy #1',
+      context: {},
+    });
+
+    expect(result).toEqual({value: 'deploy #1', trace: []});
+  });
+});

package/src/core/step-config/resolve-job-execution-name.ts

@@ -0,0 +1,51 @@
+import type {WorkflowModel} from '@shipfox/api-definitions';
+import {
+  capTraceEntries,
+  getWorkflowInterpolationFieldFailurePolicy,
+  resolveFieldAtSite,
+  type WorkflowExpressionEvaluationContext,
+  WorkflowTemplateResolutionError,
+} from '@shipfox/expression';
+import type {PersistedEvaluationTraceEntry} from '#core/entities/step.js';
+import {InterpolationUnresolvableError} from '#core/errors.js';
+
+interface WorkflowModelJobName {
+  readonly name?: WorkflowModel['jobs'][number]['name'] | undefined;
+}
+
+export interface ResolveJobExecutionNameParams {
+  readonly definitionId: string;
+  readonly job: WorkflowModelJobName;
+  readonly fallbackName: string;
+  readonly context: WorkflowExpressionEvaluationContext;
+}
+
+export function resolveJobExecutionName(params: ResolveJobExecutionNameParams): {
+  readonly value: string;
+  readonly trace: readonly PersistedEvaluationTraceEntry[];
+} {
+  if (params.job.name === undefined) return {value: params.fallbackName, trace: []};
+
+  try {
+    const resolved = resolveFieldAtSite({
+      field: {segments: params.job.name},
+      site: 'execution-creation',
+      context: params.context,
+      failurePolicy: getWorkflowInterpolationFieldFailurePolicy('job.name'),
+    });
+    return {
+      value:
+        resolved.kind === 'frozen' && resolved.value !== '' ? resolved.value : params.fallbackName,
+      trace: capTraceEntries(resolved.trace.map((entry) => ({...entry, field: 'job.name'}))),
+    };
+  } catch (error) {
+    if (error instanceof WorkflowTemplateResolutionError) {
+      throw new InterpolationUnresolvableError(params.definitionId, {
+        field: 'job.name',
+        source: error.source,
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}

package/src/core/step-config/resolve-step-config.ts

@@ -0,0 +1,199 @@
+import type {AgentDefaultsResolver} from '@shipfox/api-agent/core/resolve-agent-config';
+import type {WorkflowEnvTemplates, WorkflowModel} from '@shipfox/api-definitions';
+import {
+  type AvailabilitySite,
+  capTraceEntries,
+  type EvaluationTraceLimitEntry,
+  type WorkflowExpressionEvaluationContext,
+} from '@shipfox/expression';
+import type {
+  AgentToolMaterializationContext,
+  AgentToolMaterializationSnapshot,
+} from '#core/agent-tools.js';
+import type {StepConfigDispatchPlan} from '#core/entities/step.js';
+import {resolveAgentStepConfig} from './agent.js';
+import {
+  freezeStepField,
+  type StepConfigField,
+  type WorkflowStepEvaluationTraceEntry,
+  type WorkflowStepTemplateDiagnostic,
+} from './fields.js';
+import {resolveRunStepConfig, type StepConfigMode} from './run.js';
+import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
+
+type WorkflowModelJob = WorkflowModel['jobs'][number];
+type WorkflowModelStep = WorkflowModelJob['steps'][number];
+type WorkflowModelRunStep = Extract<WorkflowModelStep, {kind: 'run'}>;
+type WorkflowModelAgentStep = Extract<WorkflowModelStep, {kind: 'agent'}>;
+
+export type {StepConfigField, WorkflowStepTemplateDiagnostic};
+
+export interface ResolvedStepConfig {
+  readonly config: Record<string, unknown>;
+  readonly configPlan: StepConfigDispatchPlan | null;
+  readonly authoredConfig: Record<string, unknown> | null;
+  readonly name?: string;
+  readonly diagnostics: readonly WorkflowStepTemplateDiagnostic[];
+  readonly trace: readonly (WorkflowStepEvaluationTraceEntry | EvaluationTraceLimitEntry)[];
+}
+
+export interface ResolveStepConfigParams {
+  readonly jobKey: string;
+  readonly step: WorkflowModelStep;
+  readonly workflowEnv: WorkflowModel['env'];
+  readonly workflowEnvTemplates: WorkflowEnvTemplates | undefined;
+  readonly jobEnv: WorkflowModelJob['env'];
+  readonly jobEnvTemplates: WorkflowEnvTemplates | undefined;
+  readonly context: WorkflowExpressionEvaluationContext;
+  readonly site: AvailabilitySite;
+  readonly resolveAgentDefaults: AgentDefaultsResolver;
+  readonly definitionId: string;
+  readonly agentToolContext?: AgentToolMaterializationContext | undefined;
+  readonly agentToolSnapshot?: AgentToolMaterializationSnapshot | null | undefined;
+}
+
+type BuildStepConfigParams = ResolveStepConfigParams & {readonly mode: StepConfigMode};
+
+interface BuiltStepConfig {
+  readonly config: Record<string, unknown>;
+  readonly configPlan: StepConfigDispatchPlan | null;
+  readonly diagnostics: readonly WorkflowStepTemplateDiagnostic[];
+  readonly trace: readonly WorkflowStepEvaluationTraceEntry[];
+  readonly hasTemplates: boolean;
+}
+
+export function resolveStepConfig(params: ResolveStepConfigParams): ResolvedStepConfig {
+  const context = evaluationContext(params);
+  const effective = buildStepConfig({...params, context, mode: 'effective'});
+  const authoredConfig = effective.hasTemplates
+    ? buildStepConfig({...params, context, mode: 'authored'}).config
+    : null;
+  const name = resolveStepName(params.step, context, params.definitionId);
+
+  return {
+    config: effective.config,
+    configPlan: effective.configPlan,
+    authoredConfig,
+    ...(name.value === undefined || name.value === '' ? {} : {name: name.value}),
+    diagnostics: [...effective.diagnostics, ...name.diagnostics],
+    trace: capTraceEntries([...effective.trace, ...name.trace]),
+  };
+}
+
+function buildStepConfig(
+  params: Omit<BuildStepConfigParams, 'context'> & {readonly context: WorkflowEvaluationContext},
+): BuiltStepConfig {
+  const gate = gateConfigForStep(params.step);
+  const outputs = outputsConfigForStep(params.step);
+  const runStep = runStepOrNull(params.step);
+  const isRunStep = runStep !== null;
+
+  if (isRunStep) {
+    const run = resolveRunStepConfig({...params, step: runStep});
+    return {
+      config: {...run.config, ...gate, ...outputs},
+      configPlan: run.configPlan,
+      diagnostics: run.diagnostics,
+      trace: run.trace,
+      hasTemplates: run.hasTemplates,
+    };
+  }
+
+  const agentStep = agentStepOrNull(params.step);
+  if (agentStep === null) throw new Error(`Unsupported workflow step kind: ${params.step.kind}`);
+
+  const agent = resolveAgentStepConfig({...params, step: agentStep});
+  return {
+    config: {...agent.config, ...gate, ...outputs},
+    configPlan: agent.configPlan,
+    diagnostics: agent.diagnostics,
+    trace: agent.trace,
+    hasTemplates: agent.hasTemplates,
+  };
+}
+
+function evaluationContext(params: {
+  readonly context: WorkflowExpressionEvaluationContext;
+  readonly site: AvailabilitySite;
+}): WorkflowEvaluationContext {
+  return {site: params.site, values: params.context};
+}
+
+function runStepOrNull(step: WorkflowModelStep): WorkflowModelRunStep | null {
+  const isRunStep = step.kind === 'run';
+  return isRunStep ? step : null;
+}
+
+function agentStepOrNull(step: WorkflowModelStep): WorkflowModelAgentStep | null {
+  const isAgentStep = step.kind === 'agent';
+  return isAgentStep ? step : null;
+}
+
+function gateConfigForStep(step: WorkflowModelStep): Record<string, unknown> {
+  const hasGate = step.gate !== undefined;
+  return hasGate ? {gate: stepGateConfig(step.gate)} : {};
+}
+
+function outputsConfigForStep(step: WorkflowModelStep): Record<string, unknown> {
+  const hasOutputs = step.outputs !== undefined;
+  return hasOutputs ? {outputs: step.outputs} : {};
+}
+
+function resolveStepName(
+  step: WorkflowModelStep,
+  context: WorkflowEvaluationContext,
+  definitionId: string,
+): {
+  readonly value: string | undefined;
+  readonly diagnostics: readonly WorkflowStepTemplateDiagnostic[];
+  readonly trace: readonly WorkflowStepEvaluationTraceEntry[];
+} {
+  const hasName = step.name !== undefined;
+  if (!hasName) return {value: undefined, diagnostics: [], trace: []};
+
+  const hasNameTemplate = step.templates?.name !== undefined;
+  if (!hasNameTemplate) return {value: step.name, diagnostics: [], trace: []};
+
+  const resolved = freezeStepField({
+    field: 'step.name',
+    template: {segments: step.templates.name},
+    context,
+    definitionId,
+    errorField: 'step.name',
+  });
+  return {
+    value: resolved.value,
+    diagnostics: resolved.diagnostics.map((diagnostic) => ({...diagnostic, field: 'step.name'})),
+    trace: resolved.trace.map((entry) => ({...entry, field: 'step.name'})),
+  };
+}
+
+function stepGateConfig(gate: NonNullable<WorkflowModelStep['gate']>): Record<string, unknown> {
+  const hasSuccess = gate.success !== undefined;
+  const hasOnFailure = gate.onFailure !== undefined;
+  const hasOnFailureFeedback = gate.onFailure?.feedback !== undefined;
+  const hasOnFailureFeedbackTemplate = gate.onFailure?.feedbackTemplate !== undefined;
+
+  return {
+    ...(hasSuccess
+      ? {
+          success: {
+            language: gate.success.language,
+            check: gate.success.check,
+            source: gate.success.source,
+          },
+        }
+      : {}),
+    ...(hasOnFailure
+      ? {
+          on_failure: {
+            restart_from: gate.onFailure.restartFrom,
+            ...(hasOnFailureFeedback ? {feedback: gate.onFailure.feedback} : {}),
+            ...(hasOnFailureFeedbackTemplate
+              ? {feedback_template: {segments: gate.onFailure.feedbackTemplate}}
+              : {}),
+          },
+        }
+      : {}),
+  };
+}