@shipfox/api-definitions 2.0.0

package/src/core/validate-definition.test.ts

@@ -0,0 +1,152 @@
+import {validateDefinition} from './validate-definition.js';
+
+describe('validateDefinition', () => {
+  test('valid YAML returns { valid: true, definition }', () => {
+    const yaml = `
+name: Test
+runner: ubuntu-latest
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`;
+
+    const result = validateDefinition(yaml);
+
+    expect(result.valid).toBe(true);
+    if (result.valid) {
+      expect(result.definition.document.name).toBe('Test');
+      expect(result.definition.document.jobs.build?.steps).toHaveLength(1);
+      expect(result.definition.model.jobs[0]?.id).toBe('build');
+    }
+  });
+
+  test('invalid YAML syntax returns { valid: false, errors }', () => {
+    const result = validateDefinition('name: Bad\n  invalid:\nindentation');
+
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]?.message).toContain('Invalid workflow YAML syntax');
+    }
+  });
+
+  test('non-object YAML returns { valid: false, errors }', () => {
+    const stringResult = validateDefinition('just a string');
+    expect(stringResult.valid).toBe(false);
+
+    const nullResult = validateDefinition('');
+    expect(nullResult.valid).toBe(false);
+
+    const arrayResult = validateDefinition('- item1\n- item2');
+    expect(arrayResult.valid).toBe(false);
+  });
+
+  test('invalid document returns { valid: false, errors with details }', () => {
+    const yaml = `
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`;
+
+    const result = validateDefinition(yaml);
+
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.errors.length).toBeGreaterThan(0);
+      expect(result.errors[0]?.message).toBeDefined();
+    }
+  });
+
+  test('cyclic DAG returns { valid: false, errors with cycle info }', () => {
+    const yaml = `
+name: Cyclic
+runner: ubuntu-latest
+jobs:
+  a:
+    needs: b
+    steps:
+      - run: echo a
+  b:
+    needs: a
+    steps:
+      - run: echo b
+`;
+
+    const result = validateDefinition(yaml);
+
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.errors[0]?.message).toContain('Circular dependency');
+    }
+  });
+
+  test('runner-less YAML returns a validation path for the missing runner', () => {
+    const yaml = `
+name: Missing runner
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`;
+
+    const result = validateDefinition(yaml);
+
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.errors).toContainEqual(expect.objectContaining({path: 'jobs.build.runner'}));
+    }
+  });
+
+  test('default runner labels allow runner-less YAML', () => {
+    const yaml = `
+name: Default runner
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`;
+
+    const result = validateDefinition(yaml, {defaultRunnerLabels: ['ubuntu-latest']});
+
+    expect(result.valid).toBe(true);
+    if (result.valid) {
+      expect(result.definition.model.jobs[0]?.runner).toEqual(['ubuntu-latest']);
+    }
+  });
+
+  test('disabled Pi search tools return precise definition validation paths', () => {
+    const yaml = `
+name: Pi tools
+runner: ubuntu-latest
+jobs:
+  inspect:
+    steps:
+      - harness: pi
+        prompt: Fetch without search.
+        tools: [fetch_content, web_search, get_search_content]
+`;
+
+    const result = validateDefinition(yaml, {
+      harnessToolDeploymentConfig: {
+        pi: {enabledToolPackages: ['pi-web-access'], webSearchEnabled: false},
+        claude: {enabledToolPackages: []},
+      },
+    });
+
+    expect(result.valid).toBe(false);
+    if (!result.valid) {
+      expect(result.errors).toEqual([
+        expect.objectContaining({
+          path: 'jobs.inspect.steps.0.tools.1',
+          message: expect.stringContaining('web_search'),
+        }),
+        expect.objectContaining({
+          path: 'jobs.inspect.steps.0.tools.2',
+          message: expect.stringContaining('get_search_content'),
+        }),
+      ]);
+    }
+  });
+});

package/src/core/validate-definition.ts

@@ -0,0 +1,72 @@
+import type {HarnessToolDeploymentConfig} from '@shipfox/api-agent-dto';
+import {InvalidWorkflowDocumentError} from '@shipfox/workflow-document';
+import {definitionDefaultRunnerLabels, definitionHarnessToolDeploymentConfig} from '../config.js';
+import type {IntegrationValidationContext} from './entities/integration-context.js';
+import type {WorkflowDefinitionPayload} from './entities/workflow-definition.js';
+import {InvalidWorkflowModelError, normalizeWorkflowDocument} from './workflow-model/index.js';
+import {InvalidWorkflowYamlError, parseWorkflowYamlWithLocations} from './workflow-yaml/index.js';
+
+export type ValidationError = {message: string; path?: string | undefined};
+
+export type ValidationResult =
+  | {valid: true; definition: WorkflowDefinitionPayload}
+  | {valid: false; errors: ValidationError[]};
+
+export function validateDefinition(
+  yamlContent: string,
+  options: {
+    defaultRunnerLabels?: readonly string[];
+    harnessToolDeploymentConfig?: HarnessToolDeploymentConfig;
+    integrationValidationContext?: IntegrationValidationContext;
+  } = {},
+): ValidationResult {
+  try {
+    const {document, stepSourceLocations} = parseWorkflowYamlWithLocations(yamlContent);
+    const model = normalizeWorkflowDocument(document, {
+      defaultRunnerLabels: options.defaultRunnerLabels ?? definitionDefaultRunnerLabels,
+      harnessToolDeploymentConfig:
+        options.harnessToolDeploymentConfig ?? definitionHarnessToolDeploymentConfig,
+      integrationValidationContext: options.integrationValidationContext,
+      stepSourceLocations,
+    });
+    return {valid: true, definition: {document, model}};
+  } catch (error) {
+    return {valid: false, errors: validationErrorsFor(error)};
+  }
+}
+
+function validationErrorsFor(error: unknown): ValidationError[] {
+  if (error instanceof InvalidWorkflowYamlError) {
+    return [
+      validationError({
+        message: error.message,
+        path:
+          error.location === undefined
+            ? undefined
+            : `${error.location.line}:${error.location.column}`,
+      }),
+    ];
+  }
+
+  if (error instanceof InvalidWorkflowDocumentError) {
+    return error.validationError.issues.map((issue) =>
+      validationError({
+        message: issue.message,
+        path: issue.path.join('.') || undefined,
+      }),
+    );
+  }
+
+  if (error instanceof InvalidWorkflowModelError) {
+    return error.issues.map((issue) =>
+      validationError({message: issue.message, path: issue.path.join('.')}),
+    );
+  }
+
+  throw error;
+}
+
+function validationError(params: {message: string; path?: string | undefined}): ValidationError {
+  if (params.path === undefined) return {message: params.message};
+  return {message: params.message, path: params.path};
+}

package/src/core/workflow-model/README.md

@@ -0,0 +1,129 @@
+# Workflow Model
+
+Code that turns a checked workflow document into the model used by definitions.
+
+## What it does
+
+- **`WorkflowModel`**: Defines the stable workflow graph used after document
+  parsing.
+- **`normalizeWorkflowDocument(document)`**: Expands shorthand fields, assigns
+  stable ids, validates explicit providers, and builds graph edges.
+- **Step gates**: Parse run-step `gate.success` as a server-evaluated CEL
+  predicate against context roots available at step reporting, and check
+  `gate.on_failure.restart_from` against earlier named steps in the same job.
+- **`InvalidWorkflowModelError`**: Reports semantic workflow errors found during
+  normalization.
+
+Use this module after a workflow document has passed the shared document checks.
+It gives later code one shape for jobs, steps, runners, and graph edges. This is
+useful even when YAML is the only file format. YAML is for people to write. The
+model is for Shipfox code to use.
+
+This split keeps each step clear. The document package checks the public shape.
+This module decides what that shape means for jobs and run order. Later code can
+use the model without asking how the workflow was written.
+
+Think of this as the hand off from what a person wrote to what the system can
+run. A person may use short forms and names that are easy to read. The system
+needs one clear form. This module makes that form once, so the rest of the code
+does not have to guess.
+
+This is why the module is here. It gives the rest of the app a clear way to do
+its work. A test can set up one case, call one thing, and check what comes back.
+That keeps the next step easy to read.
+It is small.
+
+## Installation / Setup
+
+This code is part of `@shipfox/api-definitions`. It is not a standalone package.
+
+```json
+{
+  "dependencies": {
+    "@shipfox/api-agent-dto": "workspace:*",
+    "@shipfox/workflow-document": "workspace:*"
+  }
+}
+```
+
+## Usage
+
+```ts
+import {normalizeWorkflowDocument} from '#core/workflow-model/index.js';
+
+const model = normalizeWorkflowDocument({
+  name: 'simple build',
+  runner: 'ubuntu-latest',
+  jobs: {
+    build: {
+      steps: [{run: 'npm test'}],
+    },
+  },
+});
+
+console.log(model.jobs[0]?.steps[0]?.command.value);
+```
+
+## Behavior Notes
+
+The model does not own project ids, commit shas, refs, dates, database rows, or
+file paths. Those fields belong to `WorkflowDefinition`.
+
+Trigger filters stay as source strings in this module until event schemas define
+the expression context needed to type-check them.
+
+Event selectors use one document shape, `{source, event, with, filter}`, in
+three roles. Workflow `triggers` start a run. Job `listening.on` fires job
+executions. Job `listening.until` resolves the listening job.
+
+The persisted `workflow_document` keeps author-provided runner labels exactly as
+written. Canonical and defaulted labels live on `workflow_model.jobs[].runner`;
+downstream consumers should read the model, not `document.runner`.
+
+Run-step gate expressions are different. They are server-evaluated predicates,
+so this module parses them against the shared context registry, rejects
+runner-host roots, and checks that each root is available at step reporting. The
+accepted model stores a `WorkflowExpression` with `language: 'cel'`, the
+original source string, and the strongest check mode the referenced roots allow.
+
+Agent steps keep omitted `provider`, `model`, and `thinking` fields omitted in
+the definition model. Run materialization resolves runner-ready catalog defaults
+before execution. Explicit providers are checked against the shared provider
+catalog; explicit model ids are preserved because the shared seed catalog does
+not yet carry each provider's full model list.
+
+For now, run-step gates can use typed roots such as `step.exit_code`,
+`step.status`, open output fields such as `step.outputs.pass`, and other server
+roots that are available by step reporting. Guard optional output keys with
+`has(step.outputs.pass)` before reading them so missing keys fail as a normal
+false predicate instead of an uncheckable evaluation error.
+
+`on_failure.restart_from` must name an earlier step in the same job. The runtime
+host does not execute restart semantics yet. This module only records the
+accepted meaning in the model.
+
+If a rule needs project data or database state, put that rule in another layer.
+This module should stay pure and easy to test.
+
+If a rule can be checked from the document alone, it can live here. If a rule
+needs a project, a user, a commit, or a database row, it should live with that
+data.
+
+Run this step before saving a new definition. That way bad links, bad ids, and
+bad gate rules stop early, while the caller still knows which file field caused
+the problem.
+
+This also makes the next step simpler. The next step can read one clear shape
+instead of checking many short forms again.
+
+## Development
+
+```sh
+turbo check --filter=@shipfox/api-definitions
+turbo type --filter=@shipfox/api-definitions
+turbo test --filter=@shipfox/api-definitions
+```
+
+## License
+
+MIT

package/src/core/workflow-model/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_RUN_TIMEOUT_MS = 30 * 24 * 60 * 60 * 1000;

package/src/core/workflow-model/cron-trigger.test.ts

@@ -0,0 +1,29 @@
+import {isValidCronExpression, isValidTimezone} from './cron-trigger.js';
+
+describe('isValidCronExpression', () => {
+  it.each([['0 2 * * *'], ['*/15 9-17 * * 1-5'], ['0 2 * * MON']])('accepts %s', (expression) => {
+    const result = isValidCronExpression(expression);
+
+    expect(result).toBe(true);
+  });
+
+  it.each([['0 0 2 * * *'], ['@daily'], ['   '], ['not a cron']])('rejects %s', (expression) => {
+    const result = isValidCronExpression(expression);
+
+    expect(result).toBe(false);
+  });
+});
+
+describe('isValidTimezone', () => {
+  it.each(['UTC', 'Europe/Paris', 'US/Pacific'])('accepts %s', (timezone) => {
+    const result = isValidTimezone(timezone);
+
+    expect(result).toBe(true);
+  });
+
+  it('rejects an unknown timezone', () => {
+    const result = isValidTimezone('Not/A/Zone');
+
+    expect(result).toBe(false);
+  });
+});

package/src/core/workflow-model/cron-trigger.ts

@@ -0,0 +1,83 @@
+import {CronExpressionParser} from 'cron-parser';
+import type {WorkflowModelValidationIssue} from './invalid-workflow-model-error.js';
+import {issue} from './validation-issue.js';
+
+export const cronTriggerDefaultTimezone = 'UTC';
+const cronFieldSeparatorRegex = /\s+/;
+
+export function validateCronTrigger(params: {
+  readonly sourceKey: string;
+  readonly trigger: {
+    readonly event: string;
+  };
+  readonly config: {
+    readonly schedule?: string | undefined;
+    readonly timezone?: string | undefined;
+  };
+  readonly issues: WorkflowModelValidationIssue[];
+}): void {
+  const {sourceKey, trigger, config, issues} = params;
+
+  if (trigger.event !== 'tick') {
+    issues.push(
+      issue({
+        code: 'invalid-cron-event',
+        message: `A cron trigger must use event "tick"; found "${trigger.event}".`,
+        path: ['triggers', sourceKey, 'event'],
+        details: {event: trigger.event},
+      }),
+    );
+  }
+
+  if (config.schedule === undefined) {
+    issues.push(
+      issue({
+        code: 'missing-cron-schedule',
+        message: 'A cron trigger requires a schedule.',
+        path: ['triggers', sourceKey, 'config', 'schedule'],
+      }),
+    );
+  } else if (!isValidCronExpression(config.schedule)) {
+    issues.push(
+      issue({
+        code: 'invalid-cron-schedule',
+        message: 'Cron trigger schedule must be a valid 5-field cron expression.',
+        path: ['triggers', sourceKey, 'config', 'schedule'],
+        details: {schedule: config.schedule},
+      }),
+    );
+  }
+
+  if (config.timezone !== undefined && !isValidTimezone(config.timezone)) {
+    issues.push(
+      issue({
+        code: 'invalid-cron-timezone',
+        message: 'Cron trigger timezone must be a valid IANA time zone.',
+        path: ['triggers', sourceKey, 'config', 'timezone'],
+        details: {timezone: config.timezone},
+      }),
+    );
+  }
+}
+
+export function isValidCronExpression(expression: string): boolean {
+  const trimmedExpression = expression.trim();
+  if (trimmedExpression.length === 0) return false;
+  if (trimmedExpression.split(cronFieldSeparatorRegex).length !== 5) return false;
+
+  try {
+    CronExpressionParser.parse(trimmedExpression);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isValidTimezone(timezone: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', {timeZone: timezone});
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/core/workflow-model/index.ts

@@ -0,0 +1,9 @@
+export {DEFAULT_RUN_TIMEOUT_MS} from './constants.js';
+export {
+  InvalidWorkflowModelError,
+  invalidWorkflowModelErrorCode,
+  type WorkflowModelValidationIssue,
+  type WorkflowModelValidationIssueCode,
+  type WorkflowModelValidationIssuePathSegment,
+} from './invalid-workflow-model-error.js';
+export {normalizeWorkflowDocument} from './normalize-workflow-document.js';

package/src/core/workflow-model/invalid-workflow-model-error.ts

@@ -0,0 +1,71 @@
+export const invalidWorkflowModelErrorCode = 'invalid-workflow-model';
+
+export type WorkflowModelValidationIssueCode =
+  | 'context-unavailable-at-fill-site'
+  | 'context-unavailable-at-predicate-site'
+  | 'computed-context-key'
+  | 'duplicate-job-id'
+  | 'duplicate-step-id'
+  | 'duplicate-trigger-id'
+  | 'harness-provider-incompatible'
+  | 'harness-thinking-incompatible'
+  | 'harness-tool-incompatible'
+  | 'integration-connection-not-capable'
+  | 'integration-connection-not-found'
+  | 'integration-write-not-allowed'
+  | 'invalid-cron-event'
+  | 'invalid-cron-schedule'
+  | 'invalid-cron-timezone'
+  | 'invalid-provider'
+  | 'invalid-trigger-filter'
+  | 'invalid-interpolation-expression'
+  | 'invalid-interpolation-template'
+  | 'invalid-duration'
+  | 'invalid-listener-filter'
+  | 'invalid-job-if'
+  | 'invalid-job-output'
+  | 'invalid-job-success'
+  | 'invalid-output-schema'
+  | 'invalid-runner-label'
+  | 'invalid-step-gate-restart-from'
+  | 'invalid-step-gate-success'
+  | 'invalid-step-if'
+  | 'job-dependency-cycle'
+  | 'listening-job-missing-resolution-source'
+  | 'listening-timeout-exceeds-run-timeout'
+  | 'missing-harness-for-tools'
+  | 'missing-connection-for-integration'
+  | 'missing-job-needs-edge'
+  | 'missing-cron-schedule'
+  | 'missing-runner-label'
+  | 'multiple-manual-triggers'
+  | 'runner-context-not-bare'
+  | 'runner-context-in-field'
+  | 'runner-context-in-server-predicate'
+  | 'self-job-dependency'
+  | 'too-many-runner-labels'
+  | 'unknown-secret-store'
+  | 'unknown-interpolation-context'
+  | 'unknown-integration-method'
+  | 'unknown-integration-tool'
+  | 'unknown-job-dependency'
+  | 'untrusted-context-in-field'
+  | 'vars-context-in-server-predicate';
+
+export type WorkflowModelValidationIssuePathSegment = string | number;
+
+export interface WorkflowModelValidationIssue {
+  readonly code: WorkflowModelValidationIssueCode;
+  readonly message: string;
+  readonly path: readonly WorkflowModelValidationIssuePathSegment[];
+  readonly details?: Readonly<Record<string, unknown>>;
+}
+
+export class InvalidWorkflowModelError extends Error {
+  readonly code = invalidWorkflowModelErrorCode;
+
+  constructor(readonly issues: readonly WorkflowModelValidationIssue[]) {
+    super('Invalid workflow model');
+    this.name = 'InvalidWorkflowModelError';
+  }
+}

package/src/core/workflow-model/map-job-ids.ts

@@ -0,0 +1,33 @@
+import type {WorkflowDocument} from '@shipfox/workflow-document';
+import type {WorkflowModelValidationIssue} from './invalid-workflow-model-error.js';
+import {stableId} from './stable-id.js';
+import {issue} from './validation-issue.js';
+
+export function mapJobIds(
+  document: WorkflowDocument,
+  issues: WorkflowModelValidationIssue[],
+): ReadonlyMap<string, string> {
+  const jobIdBySourceName = new Map<string, string>();
+  const usedJobIds = new Map<string, string>();
+
+  for (const sourceKey of Object.keys(document.jobs)) {
+    const id = stableId(sourceKey);
+    const existingSourceKey = usedJobIds.get(id);
+    if (existingSourceKey !== undefined) {
+      issues.push(
+        issue({
+          code: 'duplicate-job-id',
+          message: `Job keys "${existingSourceKey}" and "${sourceKey}" resolve to the same stable id "${id}".`,
+          path: ['jobs', sourceKey],
+          details: {id, sourceKeys: [existingSourceKey, sourceKey]},
+        }),
+      );
+      continue;
+    }
+
+    usedJobIds.set(id, sourceKey);
+    jobIdBySourceName.set(sourceKey, id);
+  }
+
+  return jobIdBySourceName;
+}