@shipfox/api-workflows 12.1.0 → 12.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "12.1.0",
+  "version": "12.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -21,30 +21,32 @@
     "@temporalio/common": "1.18.1",
     "@temporalio/workflow": "1.18.1",
     "drizzle-orm": "^0.45.2",
+    "js-yaml": "^4.1.0",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "12.0.0",
+    "@shipfox/api-auth-context": "12.2.0",
     "@shipfox/api-auth-dto": "12.0.0",
-    "@shipfox/api-agent-dto": "12.0.0",
-    "@shipfox/annotations-dto": "12.0.0",
-    "@shipfox/api-definitions-dto": "12.0.0",
-    "@shipfox/api-projects-dto": "12.0.0",
-    "@shipfox/api-integration-core-dto": "12.0.0",
-    "@shipfox/api-runners-dto": "12.0.0",
+    "@shipfox/api-agent-dto": "12.2.0",
+    "@shipfox/annotations-dto": "12.3.0",
+    "@shipfox/api-definitions-dto": "12.3.0",
+    "@shipfox/api-projects-dto": "12.2.0",
+    "@shipfox/api-integration-core-dto": "12.2.0",
+    "@shipfox/api-runners-dto": "12.2.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "12.1.0",
+    "@shipfox/api-workflows-dto": "12.3.0",
     "@shipfox/api-workspaces-dto": "12.0.0",
+    "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
-    "@shipfox/expression": "2.0.0",
+    "@shipfox/expression": "2.2.0",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
-    "@shipfox/node-fastify": "0.4.1",
-    "@shipfox/node-module": "1.0.5",
-    "@shipfox/node-opentelemetry": "0.6.3",
+    "@shipfox/node-fastify": "0.4.2",
+    "@shipfox/node-module": "1.0.6",
+    "@shipfox/node-opentelemetry": "0.6.4",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.5.0",
-    "@shipfox/node-temporal": "0.4.4",
-    "@shipfox/runner-labels": "0.1.3",
-    "@shipfox/workflow-document": "3.0.0"
+    "@shipfox/node-temporal": "0.4.5",
+    "@shipfox/runner-labels": "0.2.0",
+    "@shipfox/workflow-document": "3.0.1"
   },
   "imports": {
     "#*": "./dist/*"

package/src/config.test.ts

@@ -0,0 +1,85 @@
+import {randomUUID} from 'node:crypto';
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {loadRunnerCatalog} from './config.js';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'api-workflows-'));
+});
+
+afterEach(() => {
+  rmSync(dir, {recursive: true, force: true});
+});
+
+function writeCatalog(contents: string): string {
+  const path = join(dir, `${randomUUID()}.yaml`);
+  writeFileSync(path, contents);
+  return path;
+}
+
+describe('loadRunnerCatalog', () => {
+  it('returns an empty catalog when no path is configured', () => {
+    expect(loadRunnerCatalog('')).toEqual({});
+  });
+
+  it.each(['', ' \n\t'])('treats an empty YAML document as empty', (contents) => {
+    expect(loadRunnerCatalog(writeCatalog(contents))).toEqual({});
+  });
+
+  it.each([
+    '# just a comment',
+    '---\n',
+    'null\n',
+    '~\n',
+  ])('rejects a null YAML document (%j)', (contents) => {
+    const path = writeCatalog(contents);
+
+    expect(() => loadRunnerCatalog(path)).toThrow(`Invalid runner catalog config at ${path}`);
+  });
+
+  it('loads and validates a YAML catalog', () => {
+    const path = writeCatalog(`
+ShipFox-4CPU:
+  - OS.Ubuntu-Latest
+  - CPU.4
+`);
+
+    expect(loadRunnerCatalog(path)).toEqual({
+      'shipfox-4cpu': ['cpu.4', 'os.ubuntu-latest'],
+    });
+  });
+
+  it('includes the file path when the catalog file is missing', () => {
+    const path = join(dir, 'missing.yaml');
+
+    expect(() => loadRunnerCatalog(path)).toThrow(`Cannot read runner catalog config at ${path}`);
+  });
+
+  it('includes the file path when YAML is malformed', () => {
+    const path = writeCatalog('runner: [unclosed');
+
+    expect(() => loadRunnerCatalog(path)).toThrow(`Cannot parse runner catalog config at ${path}`);
+  });
+
+  it.each([
+    ['bad name', 'label'],
+    ['name', 'not a label'],
+  ])('includes the file path when the catalog contains an invalid %s', (name, value) => {
+    const path = writeCatalog(`${name}:\n  - ${value}\n`);
+
+    expect(() => loadRunnerCatalog(path)).toThrow(`Invalid runner catalog config at ${path}`);
+  });
+
+  it('rejects oversized entries at startup', () => {
+    const path = writeCatalog(
+      `too-many:\n${Array.from({length: 21}, (_, index) => `  - label-${index}`).join('\n')}\n`,
+    );
+
+    expect(() => loadRunnerCatalog(path)).toThrow(
+      `Runner catalog entry "too-many" in ${path} has 21 labels`,
+    );
+  });
+});

package/src/config.ts

@@ -0,0 +1,71 @@
+import {readFileSync} from 'node:fs';
+import {createConfig, str} from '@shipfox/config';
+import {MAX_RUNNER_LABELS, parseRunnerCatalog, type RunnerCatalog} from '@shipfox/runner-labels';
+import yaml from 'js-yaml';
+
+export const config = createConfig({
+  RUNNER_CATALOG_PATH: str({
+    desc: 'Path to the YAML file that maps runner catalog names to complete label sets. Leave it empty to use every job runner value as a literal label. The file is loaded at startup; restart the API after changing it.',
+    default: '',
+  }),
+});
+
+/** Raised when the configured runner catalog cannot be read, parsed, or validated. */
+export class RunnerCatalogConfigError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'RunnerCatalogConfigError';
+  }
+}
+
+export function loadRunnerCatalog(filePath: string): RunnerCatalog {
+  if (filePath === '') return {};
+
+  let contents: string;
+  try {
+    contents = readFileSync(filePath, 'utf8');
+  } catch (error) {
+    throw new RunnerCatalogConfigError(
+      `Cannot read runner catalog config at ${filePath}: ${errorMessage(error)}`,
+      {cause: error},
+    );
+  }
+
+  if (contents.trim() === '') return {};
+
+  let raw: unknown;
+  try {
+    raw = yaml.load(contents);
+  } catch (error) {
+    throw new RunnerCatalogConfigError(
+      `Cannot parse runner catalog config at ${filePath}: ${errorMessage(error)}`,
+      {cause: error},
+    );
+  }
+
+  let catalog: RunnerCatalog;
+  try {
+    catalog = parseRunnerCatalog(raw);
+  } catch (error) {
+    throw new RunnerCatalogConfigError(
+      `Invalid runner catalog config at ${filePath}: ${errorMessage(error)}`,
+      {cause: error},
+    );
+  }
+
+  for (const [name, labels] of Object.entries(catalog)) {
+    if (labels.length > MAX_RUNNER_LABELS) {
+      throw new RunnerCatalogConfigError(
+        `Runner catalog entry "${name}" in ${filePath} has ${labels.length} labels; the maximum is ${MAX_RUNNER_LABELS}.`,
+      );
+    }
+  }
+
+  return catalog;
+}
+
+export const runnerCatalog = loadRunnerCatalog(config.RUNNER_CATALOG_PATH);
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/core/errors.ts

@@ -134,12 +134,54 @@ export class JobNotFoundError extends Error {
 }
 
 export class InvalidJobRunnerLabelsError extends Error {
-  constructor(readonly labels: readonly string[]) {
-    super(`Job runner labels are invalid: ${labels.join(', ')}`);
+  constructor(
+    readonly labels: readonly string[],
+    readonly requestedLabels: readonly string[] = labels,
+  ) {
+    const requestedSuffix =
+      requestedLabels.join(', ') === labels.join(', ')
+        ? ''
+        : ` (requested: ${requestedLabels.join(', ')})`;
+    super(`Job runner labels are invalid: ${labels.join(', ')}${requestedSuffix}`);
     this.name = 'InvalidJobRunnerLabelsError';
   }
 }
 
+export class JobOutputTooLargeError extends Error {
+  constructor(
+    readonly outputKey: string,
+    readonly limitBytes: number,
+    readonly scope: 'value' | 'total',
+  ) {
+    super(
+      scope === 'total'
+        ? `Job outputs exceed the ${limitBytes}-byte total limit (at "${outputKey}")`
+        : `Job output "${outputKey}" exceeds the ${limitBytes}-byte size limit`,
+    );
+    this.name = 'JobOutputTooLargeError';
+  }
+}
+
+export class JobOutputTooManyEntriesError extends Error {
+  constructor(
+    readonly entryCount: number,
+    readonly limitEntries: number,
+  ) {
+    super(`Job outputs cannot define more than ${limitEntries} entries (found ${entryCount})`);
+    this.name = 'JobOutputTooManyEntriesError';
+  }
+}
+
+export class JobOutputNotJsonSafeError extends Error {
+  constructor(
+    readonly outputKey: string,
+    readonly reason: string,
+  ) {
+    super(`Job output "${outputKey}" cannot be persisted as JSON: ${reason}`);
+    this.name = 'JobOutputNotJsonSafeError';
+  }
+}
+
 // The job named by a lease is terminal, so it must not exchange its lease for
 // fresh checkout credentials. Server state is the final gate, not the token.
 export class JobNotActiveError extends Error {

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

@@ -1139,6 +1139,7 @@ describe('step attempts', () => {
         projectId: expect.any(String),
         stepId,
         attempt: 1,
+        status: 'failed',
         logOutcome: 'abandoned',
       },
     ]);

package/src/core/step-config/assemble-run-context.test.ts

@@ -1,4 +1,8 @@
-import {getWorkflowPredicateContextRoots} from '@shipfox/expression';
+import {
+  createWorkflowExpression,
+  evaluateWorkflowExpression,
+  getWorkflowPredicateContextRoots,
+} from '@shipfox/expression';
 import type {JobExecution} from '#core/entities/job-execution.js';
 import type {Step, StepAttempt} from '#core/entities/step.js';
 import {
@@ -9,14 +13,94 @@ import {
   assembleGateContext,
   assembleJobActivationContext,
   assembleJobResolutionContext,
+  assembleJobsContext,
   assembleListenerSnapshotContext,
   assembleStepDispatchContext,
   assembleWorkflowRunContext,
+  listenerFilterOutputTypesForJobs,
   planListenerFilterSnapshots,
 } from './assemble-run-context.js';
 
 const date = new Date('2026-06-30T12:00:00.000Z');
 
+describe('assembleJobsContext', () => {
+  it.each([
+    {persistedValue: 42, expectedValue: 43n},
+    {persistedValue: '9007199254740993', expectedValue: 9007199254740994n},
+  ])('rehydrates persisted int outputs for CEL arithmetic', ({persistedValue, expectedValue}) => {
+    const context = assembleJobsContext([
+      {
+        job: {key: 'review', status: 'succeeded', outputs: {count: persistedValue}},
+        outputTypes: {count: 'int'},
+        executions: [],
+      },
+    ]);
+    const expression = createWorkflowExpression({
+      source: `jobs.review.outputs.count + 1 == ${expectedValue.toString()}`,
+      check: {mode: 'syntax'},
+    });
+
+    const result = evaluateWorkflowExpression(expression, context);
+
+    expect(result).toBe(true);
+  });
+
+  it('rehydrates persisted timestamp outputs for CEL comparison', () => {
+    const persistedValue = '2026-06-30T12:00:00.000Z';
+    const context = assembleJobsContext([
+      {
+        job: {key: 'review', status: 'succeeded', outputs: {createdAt: persistedValue}},
+        outputTypes: {createdAt: 'timestamp'},
+        executions: [],
+      },
+    ]);
+    const expression = createWorkflowExpression({
+      source: 'jobs.review.outputs.createdAt < timestamp("2026-07-01T00:00:00Z")',
+      check: {mode: 'syntax'},
+    });
+
+    const result = evaluateWorkflowExpression(expression, context);
+
+    expect(result).toBe(true);
+  });
+
+  it('rehydrates persisted execution int outputs for CEL arithmetic', () => {
+    const context = assembleJobsContext([
+      {
+        job: {key: 'review', status: 'succeeded', outputs: {}},
+        outputTypes: {count: 'int'},
+        executions: [jobExecution({outputs: {count: 42}})],
+      },
+    ]);
+    const expression = createWorkflowExpression({
+      source: 'jobs.review.executions[0].outputs.count + 1 == 43',
+      check: {mode: 'syntax'},
+    });
+
+    const result = evaluateWorkflowExpression(expression, context);
+
+    expect(result).toBe(true);
+  });
+
+  it('rehydrates persisted execution timestamp outputs for CEL comparison', () => {
+    const context = assembleJobsContext([
+      {
+        job: {key: 'review', status: 'succeeded', outputs: {}},
+        outputTypes: {createdAt: 'timestamp'},
+        executions: [jobExecution({outputs: {createdAt: '2026-06-30T12:00:00.000Z'}})],
+      },
+    ]);
+    const expression = createWorkflowExpression({
+      source: 'jobs.review.executions[0].outputs.createdAt < timestamp("2026-07-01T00:00:00Z")',
+      check: {mode: 'syntax'},
+    });
+
+    const result = evaluateWorkflowExpression(expression, context);
+
+    expect(result).toBe(true);
+  });
+});
+
 describe('assembleWorkflowRunContext', () => {
   const run = {
     id: 'run-1',
@@ -48,7 +132,7 @@ describe('assembleWorkflowRunContext', () => {
       },
       run: {
         id: 'run-1',
-        number: 1,
+        number: 1n,
         name: 'Build',
         project_id: 'proj-1',
         workspace_id: 'workspace-1',
@@ -224,16 +308,16 @@ describe('assembleExecutionCreationContext', () => {
         }),
         executions: [
           {
-            index: 0,
+            index: 0n,
             name: 'Build #1',
             status: 'failed',
             started_at: date,
             finished_at: date,
-            events: prior.triggerEvents,
+            events: prior.triggerEvents.map((event) => ({...event, received_at: date})),
             outputs: {},
           },
           {
-            index: 1,
+            index: 1n,
             name: 'Build #2',
             status: 'pending',
             started_at: null,
@@ -243,7 +327,7 @@ describe('assembleExecutionCreationContext', () => {
                 source: 'github',
                 event: 'deployment',
                 delivery_id: 'delivery-2',
-                received_at: '2026-06-30T12:01:00.000Z',
+                received_at: new Date('2026-06-30T12:01:00.000Z'),
                 project: null,
                 repository: null,
                 ref: null,
@@ -256,7 +340,7 @@ describe('assembleExecutionCreationContext', () => {
         ],
         job: {key: 'build', name: 'Build'},
         execution: {
-          index: 1,
+          index: 1n,
           name: 'Build #2',
           status: 'pending',
           started_at: null,
@@ -266,7 +350,7 @@ describe('assembleExecutionCreationContext', () => {
               source: 'github',
               event: 'deployment',
               delivery_id: 'delivery-2',
-              received_at: '2026-06-30T12:01:00.000Z',
+              received_at: new Date('2026-06-30T12:01:00.000Z'),
               project: null,
               repository: null,
               ref: null,
@@ -346,12 +430,15 @@ describe('assembleJobActivationContext', () => {
             outputs: {image: 'app:123'},
             executions: [
               {
-                index: 0,
+                index: 0n,
                 name: 'Build #1',
                 status: 'succeeded',
                 started_at: date,
                 finished_at: null,
-                events: buildExecution.triggerEvents,
+                events: buildExecution.triggerEvents.map((event) => ({
+                  ...event,
+                  received_at: date,
+                })),
                 outputs: {sha: 'abc123'},
               },
             ],
@@ -370,12 +457,15 @@ describe('assembleJobActivationContext', () => {
             outputs: {image: 'app:123'},
             executions: [
               {
-                index: 0,
+                index: 0n,
                 name: 'Build #1',
                 status: 'succeeded',
                 started_at: date,
                 finished_at: null,
-                events: buildExecution.triggerEvents,
+                events: buildExecution.triggerEvents.map((event) => ({
+                  ...event,
+                  received_at: date,
+                })),
                 outputs: {sha: 'abc123'},
               },
             ],
@@ -501,6 +591,59 @@ describe('listener filter snapshots', () => {
     expect(matcher?.filter_snapshot).toEqual({vars: {ENABLED: 'true'}});
   });
 
+  it('persists output types beside JSON-safe listener snapshots', () => {
+    const plan = planListenerFilterSnapshots({
+      on: [
+        {
+          source: 'github',
+          event: 'pull_request',
+          filter: 'jobs.build.outputs.details.count + 1 == 43',
+        },
+      ],
+      until: null,
+    });
+    const dependencyJobs = [
+      {
+        job: {
+          key: 'build',
+          status: 'succeeded' as const,
+          outputs: {details: {count: 42}},
+        },
+        outputTypes: {
+          details: {kind: 'object' as const, fields: {count: 'int' as const}},
+        },
+        executions: [],
+      },
+    ];
+    const context = assembleListenerSnapshotContext({
+      job: {key: 'await'},
+      run,
+      triggerPayload,
+      plan,
+      dependencyJobs,
+    });
+
+    const [matcher] = applyListenerFilterSnapshots(
+      plan.on,
+      context,
+      listenerFilterOutputTypesForJobs(dependencyJobs),
+    );
+
+    expect(matcher).toEqual({
+      source: 'github',
+      event: 'pull_request',
+      filter: 'jobs.build.outputs.details.count + 1 == 43',
+      filter_snapshot: {
+        jobs: {
+          build: expect.objectContaining({outputs: {details: {count: 42}}}),
+        },
+      },
+      filter_output_types: {
+        build: {details: {kind: 'object', fields: {count: 'int'}}},
+      },
+    });
+  });
+
   it('omits snapshots for event-only filters and malformed filters', () => {
     const plan = planListenerFilterSnapshots({
       on: [
@@ -606,6 +749,39 @@ describe('listener filter snapshots', () => {
       },
     });
   });
+
+  it('keeps snapshots JSON-serializable so they survive the outbox payload', () => {
+    const plan = planListenerFilterSnapshots({
+      on: [
+        {
+          source: 'github',
+          event: 'pull_request',
+          filter: 'jobs.build.executions[0].index == 0 && run.number == 1',
+        },
+      ],
+      until: null,
+    });
+    const context = assembleListenerSnapshotContext({
+      job: {key: 'await'},
+      run,
+      triggerPayload,
+      plan,
+      dependencyJobs: [
+        {
+          job: {key: 'build', status: 'succeeded', outputs: {}},
+          executions: [jobExecution({id: 'exec-build', jobId: 'job-build'})],
+        },
+      ],
+    });
+
+    const [matcher] = applyListenerFilterSnapshots(plan.on, context);
+    const jobs = matcher?.filter_snapshot?.jobs as Record<string, {executions: {index: unknown}[]}>;
+    const snapshotRun = matcher?.filter_snapshot?.run as {number: unknown};
+
+    expect(typeof jobs.build?.executions[0]?.index).toBe('number');
+    expect(typeof snapshotRun.number).toBe('number');
+    expect(() => JSON.stringify(matcher?.filter_snapshot)).not.toThrow();
+  });
 });
 
 describe('assembleStepDispatchContext', () => {
@@ -642,7 +818,7 @@ describe('assembleStepDispatchContext', () => {
       site: 'step-dispatch',
       values: {
         execution: {
-          index: 2,
+          index: 1n,
           name: 'Deploy',
           status: 'running',
           failed: false,
@@ -653,7 +829,7 @@ describe('assembleStepDispatchContext', () => {
               source: 'github',
               event: 'push',
               delivery_id: 'delivery-1',
-              received_at: '2026-06-30T12:00:00.000Z',
+              received_at: date,
               project: null,
               repository: null,
               ref: null,
@@ -980,7 +1156,7 @@ describe('assembleJobResolutionContext', () => {
         vars: {},
         executions: [
           {
-            index: 0,
+            index: 0n,
             name: 'First',
             status: 'failed',
             started_at: date,
@@ -990,7 +1166,7 @@ describe('assembleJobResolutionContext', () => {
                 source: 'github',
                 event: 'push',
                 delivery_id: 'delivery-1',
-                received_at: '2026-06-30T12:00:00.000Z',
+                received_at: date,
                 project: null,
                 repository: null,
                 ref: null,
@@ -1001,7 +1177,7 @@ describe('assembleJobResolutionContext', () => {
             outputs: {},
           },
           {
-            index: 1,
+            index: 1n,
             name: 'Second',
             status: 'succeeded',
             started_at: date,
@@ -1011,7 +1187,7 @@ describe('assembleJobResolutionContext', () => {
                 source: 'github',
                 event: 'push',
                 delivery_id: 'delivery-1',
-                received_at: '2026-06-30T12:00:00.000Z',
+                received_at: date,
                 project: null,
                 repository: null,
                 ref: null,
@@ -1069,15 +1245,51 @@ describe('assembleExecutionResolutionContext', () => {
     });
 
     expect(context.values.execution).toEqual({
-      index: 0,
+      index: 0n,
       name: 'Build #2',
       status: 'running',
       started_at: date,
       finished_at: null,
-      events: targetExecution.triggerEvents,
+      events: targetExecution.triggerEvents.map((event) => ({...event, received_at: date})),
       outputs: {sha: 'target'},
     });
   });
+
+  it('exposes execution indices and event timestamps as CEL-native values', () => {
+    const targetExecution = jobExecution({
+      id: 'exec-2',
+      sequence: 2,
+      outputs: {sha: 'target'},
+    });
+
+    const context = assembleExecutionResolutionContext({
+      run,
+      triggerPayload: {
+        source: 'manual',
+        event: 'fire',
+        subscriptionId: 'sub-1',
+        userId: 'user-1',
+      },
+      job: {key: 'build'},
+      jobExecution: targetExecution,
+      executions: [targetExecution],
+      steps: [],
+      attempts: [],
+    });
+
+    const expressions = [
+      'executions[0].index + 1 == 1',
+      'execution.index + 1 == 1',
+      'run.number + 1 == 2',
+      'executions[0].events[0].received_at < timestamp("2026-07-01T00:00:00Z")',
+    ];
+
+    for (const source of expressions) {
+      const expression = createWorkflowExpression({source, check: {mode: 'syntax'}});
+
+      expect(evaluateWorkflowExpression(expression, context.values)).toBe(true);
+    }
+  });
 });
 
 function step(overrides: Partial<Step> = {}): Step {