@shipfox/api-workflows 10.2.0 → 12.0.0

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

@@ -1,5 +1,10 @@
 import {agentInterModuleContract} from '@shipfox/api-agent-dto/inter-module';
-import {DEFAULT_JOB_CHECKOUT, type WorkflowModel} from '@shipfox/api-definitions-dto';
+import {
+  DEFAULT_JOB_CHECKOUT,
+  type WorkflowFieldTemplate,
+  type WorkflowModel,
+} from '@shipfox/api-definitions-dto';
+import {parseWorkflowTemplate, planInterpolationField} from '@shipfox/expression';
 import {createInterModuleKnownError} from '@shipfox/inter-module';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
 import {AgentConfigUnresolvableError, InterpolationUnresolvableError} from '#core/errors.js';
@@ -30,6 +35,15 @@ function template(source: string): string {
   return `\${{ ${source} }}`;
 }
 
+function checkoutTemplate(
+  field: 'checkout.repository' | 'checkout.ref',
+  source: string,
+): WorkflowFieldTemplate {
+  const result = planInterpolationField({field, segments: parseWorkflowTemplate(source)});
+  if (!result.ok) throw new Error(`Expected valid checkout template for ${field}`);
+  return result.plan.field.segments;
+}
+
 function shellRef(name: string): string {
   return `\${${name}}`;
 }
@@ -58,6 +72,28 @@ function creationContext(
 }
 
 describe('materializeWorkflowModel', () => {
+  it('keeps literal job names in runtime jobs', async () => {
+    const model = workflowModel({
+      jobs: {
+        deploy: {
+          name: 'Deploy',
+          steps: [{run: 'echo deploy'}],
+        },
+        review: {
+          name: 'Review',
+          steps: [{run: 'echo review'}],
+        },
+      },
+    });
+
+    const rows = await materializeWorkflowModel({model});
+    const deploy = rows.find((job) => job.key === 'deploy');
+    const review = rows.find((job) => job.key === 'review');
+
+    expect(deploy).toMatchObject({key: 'deploy', name: 'Deploy'});
+    expect(review).toMatchObject({key: 'review', name: 'Review'});
+  });
+
   it('converts workflow model jobs and steps to runtime rows', async () => {
     const model = workflowModel({
       runner: 'ubuntu-latest',
@@ -96,7 +132,12 @@ describe('materializeWorkflowModel', () => {
       sourceLocation: null,
       status: 'pending',
       type: 'setup',
-      config: {},
+      config: {
+        checkout: {
+          permissions: {contents: 'read'},
+          persist_credentials: true,
+        },
+      },
       authoredConfig: null,
       position: 0,
     };
@@ -441,7 +482,12 @@ describe('materializeWorkflowModel', () => {
 
     const rows = await materializeWorkflowModel({model});
 
-    expect(rows[0]?.steps[0]?.config).toEqual({});
+    expect(rows[0]?.steps[0]?.config).toEqual({
+      checkout: {
+        permissions: {contents: 'read'},
+        persist_credentials: true,
+      },
+    });
     expect(rows[0]?.steps[1]?.config).toEqual({
       run: 'npm test',
       env: {
@@ -573,6 +619,163 @@ describe('materializeWorkflowModel', () => {
     });
   });
 
+  it('resolves working directories for run and agent steps', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          steps: [
+            {run: 'npm test', workingDirectory: 'packages/api'},
+            {prompt: 'Review the changes', workingDirectory: template('run.id')},
+          ],
+        },
+      },
+    });
+
+    const rows = await materializeWorkflowModel({model, context: creationContext()});
+
+    expect(rows[0]?.steps[1]?.config).toEqual({
+      run: 'npm test',
+      working_directory: 'packages/api',
+    });
+    expect(rows[0]?.steps[2]?.config).toMatchObject({
+      harness: 'pi',
+      prompt: 'Review the changes',
+      working_directory: 'run-1',
+    });
+  });
+
+  it('defers unresolved working directory templates until step dispatch', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          steps: [{run: 'npm test', workingDirectory: template('steps.previous.outputs.path')}],
+        },
+      },
+    });
+
+    const rows = await materializeWorkflowModel({model, context: creationContext()});
+
+    expect(rows[0]?.steps[1]?.config).toEqual({run: 'npm test'});
+    expect(rows[0]?.steps[1]?.configPlan?.working_directory).toEqual({
+      segments: [
+        {
+          kind: 'deferred',
+          expression: {
+            language: 'cel',
+            source: 'steps.previous.outputs.path',
+            check: 'syntax',
+          },
+          fillTarget: 'step-dispatch',
+          roots: ['steps'],
+        },
+      ],
+    });
+  });
+
+  it('defers checkout target templates until step dispatch', async () => {
+    const repository = template('steps.previous.outputs.repository');
+    const ref = template('steps.previous.outputs.ref');
+    const model = workflowModel({
+      jobs: {
+        build: {
+          steps: [
+            {
+              checkout: {
+                repository,
+                ref,
+                fetchDepth: 1,
+                permissions: {contents: 'read'},
+                persistCredentials: true,
+                templates: {
+                  repository: checkoutTemplate('checkout.repository', repository),
+                  ref: checkoutTemplate('checkout.ref', ref),
+                },
+              },
+            },
+          ],
+        },
+      },
+    });
+
+    const rows = await materializeWorkflowModel({model, context: creationContext()});
+
+    expect(rows[0]?.steps[1]?.config).toEqual({
+      checkout: {
+        fetch_depth: 1,
+        path: '.',
+        permissions: {contents: 'read'},
+        persist_credentials: true,
+      },
+    });
+    expect(rows[0]?.steps[1]?.authoredConfig).toEqual({
+      checkout: {
+        repository,
+        ref,
+        fetch_depth: 1,
+        permissions: {contents: 'read'},
+        persist_credentials: true,
+      },
+    });
+    expect(rows[0]?.steps[1]?.configPlan?.checkout).toEqual({
+      repository: {
+        segments: [
+          expect.objectContaining({
+            kind: 'deferred',
+            roots: ['steps'],
+            fillTarget: 'step-dispatch',
+          }),
+        ],
+      },
+      ref: {
+        segments: [
+          expect.objectContaining({
+            kind: 'deferred',
+            roots: ['steps'],
+            fillTarget: 'step-dispatch',
+          }),
+        ],
+      },
+    });
+  });
+
+  it('defers unresolved thinking templates until step dispatch', async () => {
+    const model = workflowModel({
+      jobs: {
+        build: {
+          steps: [
+            {
+              harness: 'pi',
+              prompt: 'Review the change.',
+              thinking: template('steps.previous.outputs.thinking'),
+            },
+          ],
+        },
+      },
+    });
+
+    const rows = await materializeWorkflowModel({model, context: creationContext()});
+
+    expect(rows[0]?.steps[1]?.config).toEqual({});
+    expect(rows[0]?.steps[1]?.configPlan?.agent).toMatchObject({
+      harness: 'pi',
+      prompt: {segments: [{kind: 'literal', value: 'Review the change.'}]},
+      thinking: {
+        segments: [
+          {
+            kind: 'deferred',
+            expression: {
+              language: 'cel',
+              source: 'steps.previous.outputs.thinking',
+              check: 'syntax',
+            },
+            fillTarget: 'step-dispatch',
+            roots: ['steps'],
+          },
+        ],
+      },
+    });
+  });
+
   it('merges env before resolving and only resolves the winning values', async () => {
     const model = workflowModel({
       env: {SHARED: template('event.missing'), WORKFLOW_ONLY: template('run.id')},
@@ -1084,7 +1287,12 @@ describe('materializeWorkflowModel', () => {
         sourceLocation: null,
         status: 'pending',
         type: 'setup',
-        config: {},
+        config: {
+          checkout: {
+            permissions: {contents: 'read'},
+            persist_credentials: true,
+          },
+        },
         authoredConfig: null,
         position: 0,
       },

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

@@ -1,4 +1,4 @@
-import type {WorkflowModel} from '@shipfox/api-definitions-dto';
+import {DEFAULT_JOB_CHECKOUT, type WorkflowModel} from '@shipfox/api-definitions-dto';
 import {canonicalizeLabels, findInvalidLabels, MAX_RUNNER_LABELS} from '@shipfox/runner-labels';
 import type {AgentDefaultsResolver} from '#core/agent-defaults.js';
 import type {
@@ -19,9 +19,9 @@ export interface MaterializedWorkflowJob {
   readonly mode: WorkflowModelJob['mode'];
   readonly success?: string;
   readonly executionTimeoutMs?: number;
-  readonly checkout: WorkflowModelJob['checkout'];
+  readonly checkout: Exclude<WorkflowModelJob['checkout'], false>;
   readonly listening?: WorkflowModelJob['listening'];
-  readonly name?: WorkflowModelJob['name'];
+  readonly name?: string;
   readonly outputs?: WorkflowModelJob['outputs'];
   readonly dependencies: readonly string[];
   readonly runner: readonly string[];
@@ -52,31 +52,36 @@ export async function materializeWorkflowModel(
   const jobsById = new Map(model.jobs.map((job) => [job.id, job]));
 
   return await Promise.all(
-    model.jobs.map(async (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'
-          ? []
-          : await materializeJobExecutionSteps({
-              model,
-              job,
-              context,
-              resolveAgentDefaults,
-              definitionId,
-              agentToolContext,
-              agentToolSnapshot,
-            }),
-    })),
+    model.jobs.map(async (job, position) => {
+      const name = job.name;
+      return {
+        key: job.key,
+        mode: job.mode,
+        ...(job.success === undefined ? {} : {success: job.success}),
+        ...(job.executionTimeoutMs === undefined
+          ? {}
+          : {executionTimeoutMs: job.executionTimeoutMs}),
+        checkout: job.checkout === false ? DEFAULT_JOB_CHECKOUT : job.checkout,
+        ...(job.listening === undefined ? {} : {listening: job.listening}),
+        ...(name === undefined ? {} : {name}),
+        ...(job.outputs === undefined ? {} : {outputs: job.outputs}),
+        dependencies: dependencySourceNames(job, jobsById),
+        runner: job.runner,
+        position,
+        steps:
+          job.mode === 'listening'
+            ? []
+            : await materializeJobExecutionSteps({
+                model,
+                job,
+                context,
+                resolveAgentDefaults,
+                definitionId,
+                agentToolContext,
+                agentToolSnapshot,
+              }),
+      };
+    }),
   );
 }
 

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

@@ -6,11 +6,11 @@ function template(source: string): string {
 }
 
 describe('resolveJobExecutionName', () => {
-  it('resolves an interpolated job name at execution creation', () => {
+  it('resolves an interpolated execution name at execution creation', () => {
     const [job] = workflowModel({
       jobs: {
         deploy: {
-          name: `Deploy ${template('inputs.environment')}`,
+          executionName: `Deploy ${template('inputs.environment')}`,
           steps: [{run: 'echo deploy'}],
         },
       },
@@ -20,18 +20,17 @@ describe('resolveJobExecutionName', () => {
     const result = resolveJobExecutionName({
       definitionId: 'definition-1',
       job,
-      fallbackName: 'deploy #1',
       context: {inputs: {environment: 'prod'}},
     });
 
     expect(result).toMatchObject({
-      value: 'Deploy prod',
+      nameOverride: 'Deploy prod',
       trace: [
         {
-          field: 'job.name',
+          field: 'job.execution_name',
           expression: 'inputs.environment',
           roots: ['inputs'],
-          fillTarget: 'run-creation',
+          fillTarget: 'execution-creation',
           evaluatedAt: 'execution-creation',
           value: 'prod',
         },
@@ -43,7 +42,7 @@ describe('resolveJobExecutionName', () => {
     const [job] = workflowModel({
       jobs: {
         deploy: {
-          name: template('inputs.environment'),
+          executionName: template('inputs.environment'),
           steps: [{run: 'echo deploy'}],
         },
       },
@@ -53,18 +52,17 @@ describe('resolveJobExecutionName', () => {
     const result = resolveJobExecutionName({
       definitionId: 'definition-1',
       job,
-      fallbackName: 'deploy #1',
       context: {inputs: {environment: ''}},
     });
 
     expect(result).toMatchObject({
-      value: 'deploy #1',
+      nameOverride: null,
       trace: [
         {
-          field: 'job.name',
+          field: 'job.execution_name',
           expression: 'inputs.environment',
           roots: ['inputs'],
-          fillTarget: 'run-creation',
+          fillTarget: 'execution-creation',
           evaluatedAt: 'execution-creation',
           value: '',
         },
@@ -72,10 +70,26 @@ describe('resolveJobExecutionName', () => {
     });
   });
 
-  it('falls back when the job has no name template', () => {
+  it('falls back to the static job name when no execution name template exists', () => {
+    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,
+      context: {},
+    });
+
+    expect(result).toEqual({nameOverride: null, trace: []});
+  });
+
+  it('falls back when execution-name evaluation fails', () => {
     const [job] = workflowModel({
       jobs: {
         deploy: {
+          executionName: template('inputs.environment.missing'),
           steps: [{run: 'echo deploy'}],
         },
       },
@@ -85,10 +99,18 @@ describe('resolveJobExecutionName', () => {
     const result = resolveJobExecutionName({
       definitionId: 'definition-1',
       job,
-      fallbackName: 'deploy #1',
-      context: {},
+      context: {inputs: null},
     });
 
-    expect(result).toEqual({value: 'deploy #1', trace: []});
+    expect(result).toMatchObject({
+      nameOverride: null,
+      trace: [
+        expect.objectContaining({
+          field: 'job.execution_name',
+          expression: 'inputs.environment.missing',
+          degraded: true,
+        }),
+      ],
+    });
   });
 });

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

@@ -1,50 +1,65 @@
 import type {WorkflowModel} from '@shipfox/api-definitions-dto';
 import {
   capTraceEntries,
+  evaluationTraceEntry,
   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;
+  readonly executionName?: WorkflowModel['jobs'][number]['executionName'] | undefined;
 }
 
 export interface ResolveJobExecutionNameParams {
   readonly definitionId: string;
   readonly job: WorkflowModelJobName;
-  readonly fallbackName: string;
   readonly context: WorkflowExpressionEvaluationContext;
 }
 
 export function resolveJobExecutionName(params: ResolveJobExecutionNameParams): {
-  readonly value: string;
+  /** The resolved override to persist. The static fallback is deliberately not persisted. */
+  readonly nameOverride: string | null;
   readonly trace: readonly PersistedEvaluationTraceEntry[];
 } {
-  if (params.job.name === undefined) return {value: params.fallbackName, trace: []};
+  if (params.job.executionName === undefined) return {nameOverride: null, trace: []};
 
   try {
     const resolved = resolveFieldAtSite({
-      field: {segments: params.job.name},
+      field: {segments: params.job.executionName},
       site: 'execution-creation',
       context: params.context,
-      failurePolicy: getWorkflowInterpolationFieldFailurePolicy('job.name'),
+      failurePolicy: getWorkflowInterpolationFieldFailurePolicy('job.execution_name'),
     });
     return {
-      value:
-        resolved.kind === 'frozen' && resolved.value !== '' ? resolved.value : params.fallbackName,
-      trace: capTraceEntries(resolved.trace.map((entry) => ({...entry, field: 'job.name'}))),
+      nameOverride: resolved.kind === 'frozen' && resolved.value !== '' ? resolved.value : null,
+      trace: capTraceEntries(
+        resolved.trace.map((entry) => ({...entry, field: 'job.execution_name'})),
+      ),
     };
   } catch (error) {
     if (error instanceof WorkflowTemplateResolutionError) {
-      throw new InterpolationUnresolvableError(params.definitionId, {
-        field: 'job.name',
-        source: error.source,
-        cause: error,
-      });
+      const failedSegment = params.job.executionName.find(
+        (segment) => segment.kind === 'deferred' && segment.expression.source === error.source,
+      );
+      const trace =
+        failedSegment?.kind === 'deferred'
+          ? [
+              {
+                ...evaluationTraceEntry({
+                  expression: failedSegment.expression.source,
+                  roots: failedSegment.roots,
+                  fillTarget: failedSegment.fillTarget,
+                  evaluatedAt: 'execution-creation',
+                  degraded: true,
+                }),
+                field: 'job.execution_name',
+              },
+            ]
+          : [];
+      return {nameOverride: null, trace: capTraceEntries(trace)};
     }
     throw error;
   }