@shipfox/api-definitions 2.0.0

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@shipfox/api-definitions",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/definitions"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@temporalio/activity": "^1.16.1",
+    "@temporalio/common": "^1.16.1",
+    "@temporalio/workflow": "^1.16.1",
+    "cron-parser": "^5.6.1",
+    "drizzle-orm": "^0.45.2",
+    "js-yaml": "^4.1.0",
+    "yaml": "^2.8.3",
+    "zod": "^4.4.3",
+    "@shipfox/api-agent-dto": "2.0.0",
+    "@shipfox/api-auth-context": "2.0.0",
+    "@shipfox/api-definitions-dto": "2.0.0",
+    "@shipfox/api-integration-core": "2.0.0",
+    "@shipfox/api-integration-core-dto": "2.0.0",
+    "@shipfox/api-projects": "2.0.0",
+    "@shipfox/api-projects-dto": "2.0.0",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/api-secrets-dto": "2.0.0",
+    "@shipfox/node-module": "0.2.0",
+    "@shipfox/expression": "1.1.1",
+    "@shipfox/node-fastify": "0.2.1",
+    "@shipfox/node-opentelemetry": "0.5.0",
+    "@shipfox/node-outbox": "0.2.1",
+    "@shipfox/node-postgres": "0.4.1",
+    "@shipfox/node-drizzle": "0.2.1",
+    "@shipfox/runner-labels": "0.1.0",
+    "@shipfox/workflow-document": "2.0.1",
+    "@shipfox/node-temporal": "0.2.0"
+  },
+  "devDependencies": {
+    "@temporalio/client": "^1.16.1",
+    "@temporalio/testing": "^1.16.1",
+    "@temporalio/worker": "^1.16.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/pg": "^8.15.5",
+    "drizzle-kit": "^0.31.10",
+    "fastify": "^5.3.3",
+    "fastify-type-provider-zod": "^6.0.0",
+    "fishery": "^2.2.2",
+    "@shipfox/regex": "0.2.1",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/ts-config": "1.3.8"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,23 @@
+import {parseDefinitionDefaultRunnerLabels} from './config.js';
+
+const defaultRunnerLabelEnvPattern = /DEFINITION_DEFAULT_RUNNER_LABEL/;
+
+describe('parseDefinitionDefaultRunnerLabels', () => {
+  it('canonicalizes comma-delimited default runner labels', () => {
+    const labels = parseDefinitionDefaultRunnerLabels(' Ubuntu-Latest,node-22,ubuntu-latest ');
+
+    expect(labels).toEqual(['node-22', 'ubuntu-latest']);
+  });
+
+  it('rejects invalid configured runner labels with the env var name', () => {
+    expect(() => parseDefinitionDefaultRunnerLabels('has space')).toThrow(
+      defaultRunnerLabelEnvPattern,
+    );
+  });
+
+  it('rejects too many configured runner labels with the env var name', () => {
+    const value = Array.from({length: 21}, (_, index) => `label-${index}`).join(',');
+
+    expect(() => parseDefinitionDefaultRunnerLabels(value)).toThrow(defaultRunnerLabelEnvPattern);
+  });
+});

package/src/config.ts

@@ -0,0 +1,50 @@
+import {
+  buildHarnessToolDeploymentConfig,
+  type HarnessToolDeploymentConfig,
+} from '@shipfox/api-agent-dto';
+import {bool, createConfig, str} from '@shipfox/config';
+import {findInvalidLabels, MAX_RUNNER_LABELS, parseLabelList} from '@shipfox/runner-labels';
+
+export const config = createConfig({
+  DEFINITION_DEFAULT_RUNNER_LABEL: str({
+    desc: 'Default runner label(s) applied to workflow jobs that do not declare a "runner" at the job or workflow level. Set it to a comma-separated list, for example ubuntu-latest or ubuntu-latest,node-22. Leave it empty to require every workflow job to declare runner labels explicitly; with no value set, a job without a runner fails definition validation.',
+    default: '',
+  }),
+  AGENT_PI_ENABLED_TOOL_PACKAGES: str({
+    desc: 'Comma-separated optional Pi tool packages enabled for this deployment. Defaults to pi-web-access so Pi web access is available. Set it to an empty value to enable only Pi built-in tools. Accepted values: pi-web-access.',
+    default: 'pi-web-access',
+  }),
+  AGENT_PI_WEB_SEARCH_ENABLED: bool({
+    desc: 'Enables Pi web search tools when pi-web-access is enabled. Set it to false to disable web_search and get_search_content while keeping fetch_content available.',
+    default: true,
+  }),
+});
+
+export function parseDefinitionDefaultRunnerLabels(value: string): readonly string[] {
+  const labels = parseLabelList(value);
+  const invalid = findInvalidLabels(labels);
+
+  if (invalid.length > 0) {
+    throw new Error(
+      `DEFINITION_DEFAULT_RUNNER_LABEL contains invalid runner label(s): ${invalid.join(', ')}`,
+    );
+  }
+
+  if (labels.length > MAX_RUNNER_LABELS) {
+    throw new Error(
+      `DEFINITION_DEFAULT_RUNNER_LABEL contains ${labels.length} runner labels; the maximum is ${MAX_RUNNER_LABELS}`,
+    );
+  }
+
+  return labels;
+}
+
+export const definitionDefaultRunnerLabels = parseDefinitionDefaultRunnerLabels(
+  config.DEFINITION_DEFAULT_RUNNER_LABEL,
+);
+
+export const definitionHarnessToolDeploymentConfig: HarnessToolDeploymentConfig =
+  buildHarnessToolDeploymentConfig({
+    piEnabledToolPackages: config.AGENT_PI_ENABLED_TOOL_PACKAGES,
+    piWebSearchEnabled: config.AGENT_PI_WEB_SEARCH_ENABLED,
+  });

package/src/core/entities/index.ts

@@ -0,0 +1,4 @@
+export * from './integration-context.js';
+export * from './sync-state.js';
+export * from './workflow-definition.js';
+export * from './workflow-model.js';

package/src/core/entities/integration-context.ts

@@ -0,0 +1,21 @@
+import type {
+  AgentToolSelectionCatalog,
+  IntegrationCapability,
+  IntegrationProviderKind,
+} from '@shipfox/api-integration-core-dto';
+
+export interface IntegrationValidationContext {
+  readonly agentToolSelectionCatalogs: ReadonlyMap<
+    IntegrationProviderKind,
+    AgentToolSelectionCatalog
+  >;
+  readonly workspaceConnectionSnapshot: ReadonlyMap<
+    string,
+    {
+      readonly id: string;
+      readonly provider: IntegrationProviderKind;
+      readonly capabilities: readonly IntegrationCapability[];
+    }
+  >;
+  readonly defaultConnectionSlug?: string | undefined;
+}

package/src/core/entities/sync-state.ts

@@ -0,0 +1,40 @@
+export type DefinitionSyncStatus = 'pending' | 'syncing' | 'succeeded' | 'failed';
+
+export const DEFINITION_SYNC_ERROR_CODES = [
+  'no-workflow-files',
+  'invalid-definition',
+  'provider-repository-not-found',
+  'provider-file-not-found',
+  'provider-access-denied',
+  'provider-rate-limited',
+  'provider-timeout',
+  'provider-unavailable',
+  'provider-malformed-response',
+  'content-too-large',
+  'too-many-files',
+  'connection-unavailable',
+  'unknown',
+] as const;
+
+export type DefinitionSyncErrorCode = (typeof DEFINITION_SYNC_ERROR_CODES)[number];
+
+export function isDefinitionSyncErrorCode(value: unknown): value is DefinitionSyncErrorCode {
+  return (
+    typeof value === 'string' && (DEFINITION_SYNC_ERROR_CODES as readonly string[]).includes(value)
+  );
+}
+
+export interface DefinitionSyncState {
+  id: string;
+  projectId: string;
+  sourceConnectionId: string;
+  sourceExternalRepositoryId: string;
+  ref: string;
+  status: DefinitionSyncStatus;
+  lastErrorCode: DefinitionSyncErrorCode | null;
+  lastErrorMessage: string | null;
+  startedAt: Date | null;
+  finishedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}

package/src/core/entities/workflow-definition.ts

@@ -0,0 +1,38 @@
+import type {WorkflowDocument} from '@shipfox/workflow-document';
+import type {WorkflowModel} from './workflow-model.js';
+
+export type WorkflowSpec = WorkflowDocument;
+
+export interface WorkflowSourceSnapshot {
+  content: string;
+  format: 'yaml';
+}
+
+export interface WorkflowDefinitionPayload {
+  document: WorkflowDocument;
+  model: WorkflowModel;
+  sourceSnapshot?: WorkflowSourceSnapshot | null;
+}
+
+export interface WorkflowDefinition {
+  id: string;
+  projectId: string;
+  configPath: string | null;
+  source: 'manual' | 'vcs';
+  sha: string | null;
+  ref: string | null;
+  name: string;
+  /**
+   * Compatibility alias for packages that still consume the authoring document
+   * before they migrate to `document`/`model`.
+   */
+  definition: WorkflowSpec;
+  document: WorkflowDocument;
+  model: WorkflowModel;
+  sourceSnapshot: WorkflowSourceSnapshot | null;
+  contentHash: string | null;
+  fetchedAt: Date;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt: Date | null;
+}

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

@@ -0,0 +1,162 @@
+import type {
+  ExpressionType,
+  OutputDeclarations,
+  ResolvedFieldSegment,
+  WorkflowExpression,
+} from '@shipfox/expression';
+import type {AgentThinking, Harness} from '@shipfox/workflow-document';
+
+export type WorkflowFieldTemplate = readonly ResolvedFieldSegment[];
+export type WorkflowEnvTemplates = Readonly<Record<string, WorkflowFieldTemplate>>;
+export type WorkflowOutputTemplates = Readonly<Record<string, WorkflowFieldTemplate>>;
+
+export interface WorkflowModel {
+  readonly kind: 'workflow';
+  readonly name: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly templates?: {
+    readonly env?: WorkflowEnvTemplates;
+  };
+  readonly triggers: readonly WorkflowModelTrigger[];
+  readonly jobs: readonly WorkflowModelJob[];
+  readonly dependencies: readonly WorkflowModelDependency[];
+}
+
+export interface WorkflowModelTrigger {
+  readonly id: string;
+  readonly key: string;
+  readonly source: string;
+  readonly event: string;
+  readonly inputs?: Readonly<Record<string, unknown>>;
+  readonly filter?: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+}
+
+export interface WorkflowModelJob {
+  readonly id: string;
+  readonly key: string;
+  readonly mode: WorkflowModelJobMode;
+  readonly runner: readonly string[];
+  readonly runnerTemplates?: readonly WorkflowFieldTemplate[];
+  readonly checkout: WorkflowModelJobCheckout;
+  readonly if?: WorkflowExpression;
+  readonly success?: string;
+  readonly outputs?: WorkflowOutputTemplates;
+  readonly outputTypes?: Readonly<Record<string, ExpressionType>>;
+  readonly executionTimeoutMs?: number;
+  readonly listening?: WorkflowModelJobListening;
+  readonly name?: WorkflowFieldTemplate;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly templates?: {
+    readonly env?: WorkflowEnvTemplates;
+  };
+  readonly dependencies: readonly string[];
+  readonly steps: readonly WorkflowModelStep[];
+}
+
+export type WorkflowModelJobMode = 'one_shot' | 'listening';
+
+export interface WorkflowModelJobListening {
+  readonly on: readonly WorkflowModelListeningTrigger[];
+  readonly until?: readonly WorkflowModelListeningTrigger[];
+  readonly timeoutMs?: number;
+  readonly maxExecutions?: number;
+  readonly batch?: WorkflowModelListeningBatch;
+  readonly onResolve: 'finish' | 'cancel';
+}
+
+export interface WorkflowModelListeningTrigger {
+  readonly source: string;
+  readonly event: string;
+  readonly inputs?: Readonly<Record<string, unknown>>;
+  readonly filter?: string;
+}
+
+export interface WorkflowModelListeningBatch {
+  readonly debounceMs?: number;
+  readonly maxSize?: number;
+  readonly maxWaitMs?: number;
+}
+
+export interface WorkflowModelJobCheckout {
+  readonly permissions: {readonly contents: 'read' | 'write'};
+  readonly persistCredentials: boolean;
+}
+
+export type WorkflowModelStep = WorkflowModelRunStep | WorkflowModelAgentStep;
+
+interface WorkflowModelStepBase {
+  readonly id: string;
+  readonly key?: string;
+  readonly if?: WorkflowExpression;
+  readonly name?: string;
+  readonly outputs?: OutputDeclarations;
+  readonly gate?: WorkflowModelStepGate;
+  readonly sourceLocation?: WorkflowSourceLocation;
+}
+
+export interface WorkflowModelRunStep extends WorkflowModelStepBase {
+  readonly kind: 'run';
+  readonly command: WorkflowModelRunCommand;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly templates?: {
+    readonly command?: WorkflowFieldTemplate;
+    readonly name?: WorkflowFieldTemplate;
+    readonly env?: WorkflowEnvTemplates;
+  };
+}
+
+export interface WorkflowModelAgentStep extends WorkflowModelStepBase {
+  readonly kind: 'agent';
+  readonly harness?: Harness;
+  readonly model?: string;
+  readonly provider?: string;
+  readonly thinking?: AgentThinking;
+  readonly tools?: readonly string[];
+  readonly integrations?: readonly WorkflowModelStepIntegration[];
+  readonly prompt: string;
+  readonly templates?: {
+    readonly prompt?: WorkflowFieldTemplate;
+    readonly model?: WorkflowFieldTemplate;
+    readonly provider?: WorkflowFieldTemplate;
+    readonly name?: WorkflowFieldTemplate;
+  };
+}
+
+export interface WorkflowModelStepIntegration {
+  readonly connection?: string;
+  readonly include: readonly string[];
+  readonly exclude?: readonly string[];
+  readonly allowWrite: boolean;
+}
+
+export interface WorkflowSourceLocation {
+  readonly startLine: number;
+  readonly endLine: number;
+}
+
+export type WorkflowStepSourceLocationMap = ReadonlyMap<
+  string,
+  ReadonlyMap<number, WorkflowSourceLocation>
+>;
+
+export interface WorkflowModelRunCommand {
+  readonly kind: 'shell';
+  readonly value: string;
+}
+
+export interface WorkflowModelStepGate {
+  readonly success?: WorkflowExpression;
+  readonly onFailure?: WorkflowModelStepFailureAction;
+}
+
+export interface WorkflowModelStepFailureAction {
+  readonly restartFrom: string;
+  readonly feedback?: string;
+  readonly feedbackTemplate?: WorkflowFieldTemplate;
+}
+
+export interface WorkflowModelDependency {
+  readonly from: string;
+  readonly to: string;
+}

package/src/core/errors.ts

@@ -0,0 +1,21 @@
+import type {DefinitionSyncErrorCode} from './entities/sync-state.js';
+
+export class DefinitionParseError extends Error {
+  constructor(
+    message: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = 'DefinitionParseError';
+  }
+}
+
+export class DefinitionSyncPermanentError extends Error {
+  constructor(
+    public readonly code: DefinitionSyncErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'DefinitionSyncPermanentError';
+  }
+}

package/src/core/has-agent-step-integrations.ts

@@ -0,0 +1,7 @@
+import type {WorkflowDocument} from '@shipfox/workflow-document';
+
+export function hasAgentStepIntegrations(document: WorkflowDocument): boolean {
+  return Object.values(document.jobs).some((job) =>
+    job.steps.some((step) => step.integrations !== undefined),
+  );
+}

package/src/core/index.ts

@@ -0,0 +1,23 @@
+export type * from './entities/index.js';
+export {DefinitionParseError, DefinitionSyncPermanentError} from './errors.js';
+export {parseDefinition} from './parse-definition.js';
+export {
+  classifySyncFailure,
+  type DiscoverWorkflowFilesParams,
+  discoverWorkflowFiles,
+  type FetchAndParseWorkflowsParams,
+  FILE_FETCH_CONCURRENCY,
+  fetchAndParseWorkflows,
+  MAX_WORKFLOW_FILES,
+  type ParsedWorkflow,
+  type ResolvedSyncSource,
+  resolveSyncSource,
+  type SyncFailureClassification,
+  type SyncSourceContext,
+  UNRESOLVED_SYNC_REF,
+  WORKFLOW_PREFIX,
+} from './sync-definitions.js';
+export {DEFAULT_RUN_TIMEOUT_MS} from './workflow-model/constants.js';
+export {normalizeWorkflowDocument} from './workflow-model/index.js';
+export {DEFAULT_JOB_CHECKOUT} from './workflow-model/normalize-job-checkout.js';
+export {DEFAULT_JOB_SUCCESS} from './workflow-model/normalize-job-success.js';

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

@@ -0,0 +1,200 @@
+import {readFileSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {DefinitionParseError} from './errors.js';
+import {parseDefinition} from './parse-definition.js';
+
+const fixturesDir = resolve(dirname(fileURLToPath(import.meta.url)), '../../test/fixtures');
+
+function readFixture(name: string): string {
+  return readFileSync(resolve(fixturesDir, name), 'utf-8');
+}
+
+describe('parseDefinition', () => {
+  test('valid simple workflow returns document and model', () => {
+    const yaml = readFixture('valid-simple.yml');
+
+    const definition = parseDefinition(yaml);
+
+    expect(definition.document.name).toBe('Simple build');
+    expect(definition.document.triggers?.on_push?.source).toBe('github_acme');
+    expect(definition.document.triggers?.on_push?.event).toBe('push');
+    expect(definition.document.triggers?.on_demand?.source).toBe('manual');
+    expect(definition.document.triggers?.on_demand?.event).toBe('fire');
+    expect(definition.document.jobs.build?.steps).toHaveLength(2);
+    expect(definition.document.jobs.build?.steps?.[0]?.run).toBe('npm install');
+    const firstStep = definition.model.jobs.find((job) => job.id === 'build')?.steps[0];
+    expect(firstStep).toMatchObject({kind: 'run', command: {kind: 'shell', value: 'npm install'}});
+  });
+
+  test('valid DAG workflow parses successfully', () => {
+    const yaml = readFixture('valid-dag.yml');
+
+    const definition = parseDefinition(yaml);
+
+    expect(definition.document.name).toBe('Multi-job pipeline');
+    expect(Object.keys(definition.document.jobs)).toHaveLength(4);
+    expect(definition.model.dependencies).toEqual([
+      {from: 'build', to: 'test-unit'},
+      {from: 'build', to: 'test-integration'},
+      {from: 'test-unit', to: 'deploy'},
+      {from: 'test-integration', to: 'deploy'},
+    ]);
+  });
+
+  test('valid listening job workflow parses successfully', () => {
+    const yaml = readFixture('valid-listening-job.yml');
+
+    const definition = parseDefinition(yaml);
+
+    expect(definition.model.jobs[0]).toMatchObject({
+      id: 'review',
+      key: 'review',
+      mode: 'listening',
+      listening: {
+        on: [{source: 'github', event: 'pull_request_review'}],
+        until: [{source: 'github', event: 'pull_request'}],
+        timeoutMs: 30 * 24 * 60 * 60 * 1000,
+        maxExecutions: 3,
+        batch: {debounceMs: 5000, maxSize: 10, maxWaitMs: 60 * 60 * 1000},
+        onResolve: 'cancel',
+      },
+    });
+    expect(definition.model.jobs[0]?.name).toBeDefined();
+  });
+
+  test('attaches source line locations to workflow model steps', () => {
+    const yaml = `name: Source locations
+runner: ubuntu-latest
+jobs:
+  build:
+    steps:
+      - name: Install
+        run: pnpm install
+      # comments between authored steps are not part of either step range
+      - run: |
+          pnpm test
+          pnpm build
+        gate:
+          success: step.exit_code == 0
+  deploy:
+    needs: build
+    steps:
+      - name: Deploy
+        run: ./deploy.sh
+`;
+
+    const definition = parseDefinition(yaml);
+
+    const build = definition.model.jobs.find((job) => job.id === 'build');
+    const deploy = definition.model.jobs.find((job) => job.id === 'deploy');
+    expect(build?.steps.map((step) => step.sourceLocation)).toEqual([
+      {startLine: 6, endLine: 7},
+      {startLine: 9, endLine: 13},
+    ]);
+    expect(deploy?.steps.map((step) => step.sourceLocation)).toEqual([
+      {startLine: 17, endLine: 18},
+    ]);
+  });
+
+  test('ends source line locations on the final content line of block scalar steps', () => {
+    const yaml = `name: Block scalar
+runner: ubuntu-latest
+jobs:
+  build:
+    steps:
+      - run: |
+          echo one
+          echo two
+`;
+
+    const definition = parseDefinition(yaml);
+
+    expect(definition.model.jobs[0]?.steps[0]?.sourceLocation).toEqual({
+      startLine: 6,
+      endLine: 8,
+    });
+  });
+
+  test('accepts default runner labels through parse options', () => {
+    const yaml = `name: Default runner
+jobs:
+  build:
+    steps:
+      - run: echo hello
+`;
+
+    const definition = parseDefinition(yaml, {defaultRunnerLabels: ['ubuntu-latest']});
+
+    expect(definition.model.jobs[0]?.runner).toEqual(['ubuntu-latest']);
+  });
+
+  test('invalid YAML syntax throws DefinitionParseError', () => {
+    const yaml = readFixture('invalid-yaml-syntax.yml');
+
+    expect(() => parseDefinition(yaml)).toThrow(DefinitionParseError);
+  });
+
+  test('YAML that parses to a string throws DefinitionParseError', () => {
+    expect(() => parseDefinition('just a string')).toThrow(DefinitionParseError);
+  });
+
+  test('YAML that parses to null throws DefinitionParseError', () => {
+    expect(() => parseDefinition('')).toThrow(DefinitionParseError);
+  });
+
+  test('YAML that parses to an array throws DefinitionParseError', () => {
+    expect(() => parseDefinition('- item1\n- item2')).toThrow(DefinitionParseError);
+  });
+
+  test('valid YAML with invalid document throws DefinitionParseError with details', () => {
+    const yaml = readFixture('invalid-missing-name.yml');
+
+    try {
+      parseDefinition(yaml);
+      expect.fail('Expected DefinitionParseError');
+    } catch (error) {
+      expect(error).toBeInstanceOf(DefinitionParseError);
+      expect((error as DefinitionParseError).details).toBeDefined();
+      expect(Array.isArray((error as DefinitionParseError).details)).toBe(true);
+    }
+  });
+
+  test('valid document with cyclic job dependencies throws DefinitionParseError', () => {
+    const yaml = readFixture('invalid-cycle.yml');
+
+    expect(() => parseDefinition(yaml)).toThrow(DefinitionParseError);
+  });
+
+  test('manual trigger requires an explicit event', () => {
+    const yaml = `name: Manual only
+runner: ubuntu-latest
+triggers:
+  on_demand:
+    source: manual
+jobs:
+  run:
+    steps:
+      - run: echo hello
+`;
+
+    expect(() => parseDefinition(yaml)).toThrow(DefinitionParseError);
+  });
+
+  test('declaring more than one manual trigger throws DefinitionParseError', () => {
+    const yaml = `name: Multi manual
+runner: ubuntu-latest
+triggers:
+  deploy:
+    source: manual
+  rollback:
+    source: manual
+jobs:
+  run:
+    steps:
+      - run: echo hello
+`;
+
+    expect(() => parseDefinition(yaml)).toThrow(DefinitionParseError);
+  });
+});