@shipfox/api-workflows 2.0.0

package/src/metrics/instance.ts

@@ -0,0 +1,160 @@
+import {instanceMetrics} from '@shipfox/node-opentelemetry';
+import type {JobStatus, ResolutionReason} from '#core/entities/job.js';
+import type {JobExecutionStatus} from '#core/entities/job-execution.js';
+import type {WorkflowRunStatus} from '#core/entities/workflow-run.js';
+import type {RuntimeCompletionStatus} from '#core/workflow-scheduling/runtime-dag.js';
+
+const meter = instanceMetrics.getMeter('workflows');
+
+const runCreatedCount = meter.createCounter<{provider: string}>('workflows_run_created', {
+  description: 'Workflow runs created by bounded trigger provider',
+});
+
+const runStatusChangedCount = meter.createCounter<{status: WorkflowRunStatus}>(
+  'workflows_run_status_changed',
+  {description: 'Workflow run status transitions by resulting status'},
+);
+
+const jobStatusChangedCount = meter.createCounter<{status: JobStatus}>(
+  'workflows_job_status_changed',
+  {description: 'Workflow job status transitions by resulting status'},
+);
+
+const jobExecutionStatusChangedCount = meter.createCounter<{status: JobExecutionStatus}>(
+  'workflows_job_execution_status_changed',
+  {description: 'Workflow job execution status transitions by resulting status'},
+);
+
+const jobExecutionQueuedCount = meter.createCounter<Record<string, never>>(
+  'workflows_job_execution_queued',
+  {
+    description: 'Workflow job executions first marked as queued from runner queue events',
+  },
+);
+
+const jobExecutionStartedCount = meter.createCounter<Record<string, never>>(
+  'workflows_job_execution_started',
+  {
+    description: 'Workflow job executions first marked as started from runner claim events',
+  },
+);
+
+const jobExecutionStepsSettledCount = meter.createCounter<{
+  status: Extract<RuntimeCompletionStatus, 'failed' | 'succeeded'>;
+}>('workflows_job_execution_steps_settled', {
+  description: 'Job execution steps-settled events enqueued by resulting completion status',
+});
+
+const jobExecutionTimedOutCount = meter.createCounter<Record<string, never>>(
+  'workflows_job_execution_timed_out',
+  {
+    description: 'Workflow job executions failed by the execution orchestration timeout path',
+  },
+);
+
+const jobExecutionLeaseExpiryResolvedCount = meter.createCounter<{status: RuntimeCompletionStatus}>(
+  'workflows_job_execution_lease_expiry_resolved',
+  {description: 'Runner lease-expiry resolutions by resulting runtime status'},
+);
+
+const stepRestartEnqueuedCount = meter.createCounter<Record<string, never>>(
+  'workflows_step_restart_enqueued',
+  {description: 'Durable step restart events enqueued after a restartable gate failure'},
+);
+
+const listenerEventsReceivedCount = meter.createCounter<{provider: string}>(
+  'workflows_listener_events_received',
+  {description: 'Listener integration events buffered by bounded trigger provider'},
+);
+
+const listenerExecutionsCount = meter.createCounter<{
+  outcome: 'succeeded' | 'failed' | 'cancelled';
+}>('workflows_listener_executions', {
+  description: 'Listener job execution firings by terminal outcome',
+});
+
+const listenerResolvedCount = meter.createCounter<{reason: ResolutionReason}>(
+  'workflows_listener_resolved',
+  {description: 'Listener resolutions by bounded reason'},
+);
+
+const agentToolWarningFailedCount = meter.createCounter<{
+  reason: 'budget' | 'lookup' | 'write';
+}>('workflows_agent_tool_warning_failed', {
+  description: 'Agent tool capability warning failures by bounded reason',
+});
+
+const listenerEventsCoalesced = meter.createHistogram<Record<string, never>>(
+  'workflows_listener_events_coalesced',
+  {
+    description: 'Listener firing batch sizes',
+    unit: '1',
+    advice: {explicitBucketBoundaries: [1, 2, 5, 10, 25, 50, 100, 250]},
+  },
+);
+
+export function recordWorkflowRunCreated(provider: string): void {
+  runCreatedCount.add(1, {provider});
+}
+
+export function recordWorkflowRunStatusChanged(status: WorkflowRunStatus): void {
+  runStatusChangedCount.add(1, {status});
+}
+
+export function recordWorkflowJobStatusChanged(status: JobStatus): void {
+  jobStatusChangedCount.add(1, {status});
+}
+
+export function recordWorkflowJobExecutionStatusChanged(status: JobExecutionStatus): void {
+  jobExecutionStatusChangedCount.add(1, {status});
+}
+
+export function recordWorkflowJobExecutionQueued(): void {
+  jobExecutionQueuedCount.add(1);
+}
+
+export function recordWorkflowJobExecutionStarted(): void {
+  jobExecutionStartedCount.add(1);
+}
+
+export function recordWorkflowJobExecutionStepsSettled(
+  status: Extract<RuntimeCompletionStatus, 'failed' | 'succeeded'>,
+): void {
+  jobExecutionStepsSettledCount.add(1, {status});
+}
+
+export function recordWorkflowJobExecutionTimedOut(): void {
+  jobExecutionTimedOutCount.add(1);
+}
+
+export function recordWorkflowJobExecutionLeaseExpiryResolved(
+  status: RuntimeCompletionStatus,
+): void {
+  jobExecutionLeaseExpiryResolvedCount.add(1, {status});
+}
+
+export function recordWorkflowStepRestartEnqueued(): void {
+  stepRestartEnqueuedCount.add(1);
+}
+
+export function recordListenerEventReceived(provider: string): void {
+  listenerEventsReceivedCount.add(1, {provider});
+}
+
+export function recordWorkflowListenerExecution(
+  outcome: 'succeeded' | 'failed' | 'cancelled',
+): void {
+  listenerExecutionsCount.add(1, {outcome});
+}
+
+export function recordWorkflowListenerResolved(reason: ResolutionReason): void {
+  listenerResolvedCount.add(1, {reason});
+}
+
+export function recordListenerEventsCoalesced(batchSize: number): void {
+  listenerEventsCoalesced.record(batchSize);
+}
+
+export function recordWorkflowAgentToolWarningFailed(reason: 'budget' | 'lookup' | 'write'): void {
+  agentToolWarningFailedCount.add(1, {reason});
+}

package/src/metrics/service.ts

@@ -0,0 +1,30 @@
+import {getServiceMetricsProvider} from '@shipfox/node-opentelemetry';
+import {countActiveListeners} from '#db/job-listeners.js';
+import {getWorkflowJobExecutionDepth} from '#db/workflow-runs.js';
+
+export function registerWorkflowsServiceMetrics(): void {
+  const meter = getServiceMetricsProvider().getMeter('workflows');
+
+  const runningRuns = meter.createObservableGauge('workflows_running_runs', {
+    description: 'Workflow runs currently marked running',
+  });
+  const runningJobExecutions = meter.createObservableGauge('workflows_running_job_executions', {
+    description: 'Workflow job executions currently marked running',
+  });
+  const activeListeners = meter.createObservableGauge('workflows_active_listeners', {
+    description: 'Workflow jobs currently marked as listening',
+  });
+
+  meter.addBatchObservableCallback(
+    async (observer) => {
+      const [depth, listenerCount] = await Promise.all([
+        getWorkflowJobExecutionDepth(),
+        countActiveListeners(),
+      ]);
+      observer.observe(runningRuns, depth.runningRuns);
+      observer.observe(runningJobExecutions, depth.runningJobExecutions);
+      observer.observe(activeListeners, listenerCount);
+    },
+    [runningRuns, runningJobExecutions, activeListeners],
+  );
+}

package/src/presentation/dto/checkout-token.test.ts

@@ -0,0 +1,107 @@
+import type {CheckoutSpec} from '@shipfox/api-integration-core';
+import {toCheckoutTokenDto} from './checkout-token.js';
+
+describe('toCheckoutTokenDto', () => {
+  it('maps credentials to basic auth with an ISO expiry', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: 'main',
+      gitAuthor: {
+        name: 'shipfox-test[bot]',
+        email: '1+shipfox-test[bot]@users.noreply.github.com',
+      },
+      credentials: {
+        username: 'x-access-token',
+        token: 'ghs-token',
+        expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+      },
+    };
+
+    const dto = toCheckoutTokenDto(spec, {persist: true});
+
+    expect(dto).toEqual({
+      repository_url: 'https://github.com/acme/repo.git',
+      ref: 'main',
+      git_author: {
+        name: 'shipfox-test[bot]',
+        email: '1+shipfox-test[bot]@users.noreply.github.com',
+      },
+      auth: {
+        kind: 'basic',
+        username: 'x-access-token',
+        token: 'ghs-token',
+        expires_at: '2026-06-10T12:00:00.000Z',
+        carry: 'header',
+        host: 'github.com',
+        persist: true,
+      },
+    });
+  });
+
+  it('maps persist false into credential auth', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: 'main',
+      credentials: {
+        username: 'x-access-token',
+        token: 'ghs-token',
+        expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+      },
+    };
+
+    const dto = toCheckoutTokenDto(spec, {persist: false});
+
+    expect(dto.auth).toMatchObject({carry: 'header', host: 'github.com', persist: false});
+  });
+
+  it('omits auth when the spec has no credentials', () => {
+    const spec: CheckoutSpec = {repositoryUrl: 'https://example.com/acme/repo.git', ref: 'trunk'};
+
+    const dto = toCheckoutTokenDto(spec, {persist: true});
+
+    expect(dto).toEqual({repository_url: 'https://example.com/acme/repo.git', ref: 'trunk'});
+    expect(dto.auth).toBeUndefined();
+  });
+
+  it('rejects a repository URL that embeds credentials', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'https://x-access-token:ghs-token@github.com/acme/repo.git',
+      ref: 'main',
+    };
+
+    expect(() => toCheckoutTokenDto(spec, {persist: true})).toThrow();
+  });
+
+  it('rejects an scp-like URL that embeds credentials', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'user:secret@github.com:acme/repo.git',
+      ref: 'main',
+    };
+
+    expect(() => toCheckoutTokenDto(spec, {persist: true})).toThrow();
+  });
+
+  it('accepts a credential-free scp-like URL', () => {
+    const spec: CheckoutSpec = {repositoryUrl: 'git@github.com:acme/repo.git', ref: 'main'};
+
+    const dto = toCheckoutTokenDto(spec, {persist: true});
+
+    expect(dto).toEqual({repository_url: 'git@github.com:acme/repo.git', ref: 'main'});
+  });
+
+  it('maps the host from an scp-like credentialed URL', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'git@github.com:acme/repo.git',
+      ref: 'main',
+      credentials: {
+        username: 'x-access-token',
+        token: 'ghs-token',
+        expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+      },
+    };
+
+    const dto = toCheckoutTokenDto(spec, {persist: true});
+
+    expect(dto.auth).toMatchObject({host: 'github.com'});
+  });
+});

package/src/presentation/dto/checkout-token.ts

@@ -0,0 +1,85 @@
+import type {CheckoutSpec} from '@shipfox/api-integration-core';
+import type {CheckoutTokenResponseDto} from '@shipfox/api-workflows-dto';
+
+const SCP_LIKE_HOST_RE = /^(?:[^@:/]+@)?([^:/]+):/;
+
+// Defense in depth: createCheckoutSpec's contract is that `repositoryUrl` never
+// embeds credentials (they live in `credentials` so redaction can mask them). A
+// provider bug that put a token in the URL would bypass redaction and leak it
+// into `git remote -v` and logs, so reject it before it reaches the runner.
+function assertNoEmbeddedCredentials(repositoryUrl: string): void {
+  // Run the scp-style check unconditionally: a genuine scp form
+  // (git@host:org/repo.git) fails URL parsing, but a `user:secret@host:path`
+  // string parses with a bogus `user:` scheme and *empty* URL userinfo, so the
+  // url.username check below would miss its embedded password.
+  assertNoScpCredentials(repositoryUrl);
+
+  let url: URL;
+  try {
+    url = new URL(repositoryUrl);
+  } catch {
+    return;
+  }
+  if (url.username || url.password) {
+    throw new Error('Checkout repository URL must not embed credentials');
+  }
+}
+
+// scp-like userinfo is everything before the first `@`, and that `@` precedes
+// the first `/`. A bare `git@host:path` user is fine; a `user:secret@host:path`
+// password embeds a credential, so reject any colon in the userinfo segment.
+function assertNoScpCredentials(repositoryUrl: string): void {
+  const atIndex = repositoryUrl.indexOf('@');
+  const slashIndex = repositoryUrl.indexOf('/');
+  if (atIndex === -1 || (slashIndex !== -1 && atIndex > slashIndex)) {
+    return;
+  }
+  if (repositoryUrl.slice(0, atIndex).includes(':')) {
+    throw new Error('Checkout repository URL must not embed credentials');
+  }
+}
+
+export function toCheckoutTokenDto(
+  spec: CheckoutSpec,
+  options: {persist: boolean},
+): CheckoutTokenResponseDto {
+  assertNoEmbeddedCredentials(spec.repositoryUrl);
+
+  // Every provider that returns credentials uses a username (GitHub:
+  // 'x-access-token'), so the response is always basic auth; a credential-free
+  // spec (debug) omits auth entirely.
+  return {
+    repository_url: spec.repositoryUrl,
+    ref: spec.ref,
+    ...(spec.gitAuthor
+      ? {git_author: {name: spec.gitAuthor.name, email: spec.gitAuthor.email}}
+      : {}),
+    ...(spec.credentials
+      ? {
+          auth: {
+            kind: 'basic' as const,
+            username: spec.credentials.username,
+            token: spec.credentials.token,
+            expires_at: spec.credentials.expiresAt.toISOString(),
+            carry: 'header' as const,
+            host: checkoutHost(spec.repositoryUrl),
+            persist: options.persist,
+          },
+        }
+      : {}),
+  };
+}
+
+function checkoutHost(repositoryUrl: string): string {
+  try {
+    const host = new URL(repositoryUrl).host;
+    if (host) return host;
+  } catch {
+    // Fall through to scp-like parsing.
+  }
+
+  const scpLike = SCP_LIKE_HOST_RE.exec(repositoryUrl);
+  if (scpLike?.[1]) return scpLike[1];
+
+  throw new Error('Checkout repository URL must include a host');
+}

package/src/presentation/dto/index.ts

@@ -0,0 +1,3 @@
+export {toJobDto, toJobExecutionDto} from './job.js';
+export {toStepAttemptDto, toStepDto} from './step.js';
+export {toRunAttemptDto, toRunDto} from './workflow-run.js';

package/src/presentation/dto/job.test.ts

@@ -0,0 +1,108 @@
+import type {Job} from '#core/entities/job.js';
+import type {JobExecution} from '#core/entities/job-execution.js';
+import {toJobDto, toJobExecutionDto} from './job.js';
+
+describe('toJobDto', () => {
+  it('maps job status reason to snake_case', () => {
+    const job = jobEntity({
+      status: 'skipped',
+      statusReason: 'dependency_not_completed',
+      outputs: {image_sha: 'abc123'},
+    });
+
+    const dto = toJobDto(job);
+
+    expect(dto.status).toBe('skipped');
+    expect(dto.status_reason).toBe('dependency_not_completed');
+    expect(dto.outputs).toEqual({image_sha: 'abc123'});
+  });
+});
+
+describe('toJobExecutionDto', () => {
+  it('maps listener trigger events', () => {
+    const jobExecution = jobExecutionEntity({
+      outputs: {verdict: 'approved'},
+      triggerEvents: [
+        {
+          source: 'github',
+          event: 'deployment_status',
+          delivery_id: 'delivery-1',
+          received_at: '2026-06-25T00:00:00.000Z',
+          data: {state: 'success'},
+        },
+      ],
+    });
+
+    const dto = toJobExecutionDto(jobExecution);
+
+    expect(dto.outputs).toEqual({verdict: 'approved'});
+    expect(dto.trigger_events).toEqual([
+      {
+        source: 'github',
+        event: 'deployment_status',
+        delivery_id: 'delivery-1',
+        received_at: '2026-06-25T00:00:00.000Z',
+        data: {state: 'success'},
+      },
+    ]);
+  });
+});
+
+function jobEntity(overrides: Partial<Job> = {}): Job {
+  return {
+    id: '11111111-1111-4111-8111-111111111111',
+    workflowRunAttemptId: '22222222-2222-4222-8222-222222222222',
+    key: 'deploy',
+    name: null,
+    mode: 'one_shot',
+    status: 'pending',
+    statusReason: null,
+    outputs: null,
+    carriedOver: false,
+    checkout: {
+      permissions: {contents: 'read'},
+      persistCredentials: true,
+    },
+    success: null,
+    executionTimeoutMs: null,
+    listeningTimeoutMs: null,
+    maxExecutions: null,
+    onResolve: null,
+    batchDebounceMs: null,
+    batchMaxSize: null,
+    batchMaxWaitMs: null,
+    listenerStatus: 'inactive',
+    resolutionReason: null,
+    listeningOn: null,
+    listeningUntil: null,
+    dependencies: [],
+    runner: null,
+    position: 0,
+    version: 1,
+    createdAt: new Date('2026-06-25T00:00:00.000Z'),
+    updatedAt: new Date('2026-06-25T00:00:01.000Z'),
+    ...overrides,
+  };
+}
+
+function jobExecutionEntity(overrides: Partial<JobExecution> = {}): JobExecution {
+  return {
+    id: '33333333-3333-4333-8333-333333333333',
+    jobId: '11111111-1111-4111-8111-111111111111',
+    sequence: 1,
+    name: 'deploy',
+    runner: null,
+    status: 'pending',
+    statusReason: null,
+    outputs: null,
+    triggerEvents: [],
+    version: 1,
+    createdAt: new Date('2026-06-25T00:00:00.000Z'),
+    updatedAt: new Date('2026-06-25T00:00:01.000Z'),
+    queuedAt: null,
+    startedAt: null,
+    finishedAt: null,
+    timedOutAt: null,
+    ...overrides,
+  };
+}

package/src/presentation/dto/job.ts

@@ -0,0 +1,64 @@
+import type {JobDto, JobExecutionDto} from '@shipfox/api-workflows-dto';
+import type {Job} from '#core/entities/job.js';
+import type {JobExecution} from '#core/entities/job-execution.js';
+
+export function toJobDto(job: Job): JobDto {
+  return {
+    id: job.id,
+    run_attempt_id: job.workflowRunAttemptId,
+    key: job.key,
+    name: job.name,
+    mode: job.mode,
+    status: job.status,
+    status_reason: job.statusReason,
+    carried_over: job.carriedOver,
+    listening:
+      job.listeningOn === null
+        ? null
+        : {
+            on: job.listeningOn,
+            until: job.listeningUntil,
+            timeout_ms: job.listeningTimeoutMs,
+            max_executions: job.maxExecutions,
+            batch:
+              job.batchDebounceMs === null &&
+              job.batchMaxSize === null &&
+              job.batchMaxWaitMs === null
+                ? null
+                : {
+                    ...(job.batchDebounceMs === null ? {} : {debounce_ms: job.batchDebounceMs}),
+                    ...(job.batchMaxSize === null ? {} : {max_size: job.batchMaxSize}),
+                    ...(job.batchMaxWaitMs === null ? {} : {max_wait_ms: job.batchMaxWaitMs}),
+                  },
+            on_resolve: job.onResolve ?? 'finish',
+            execution_timeout_ms: job.executionTimeoutMs ?? null,
+            name: job.name,
+          },
+    listener_status: job.listenerStatus,
+    resolution_reason: job.resolutionReason,
+    outputs: job.outputs,
+    dependencies: job.dependencies,
+    position: job.position,
+    created_at: job.createdAt.toISOString(),
+    updated_at: job.updatedAt.toISOString(),
+  };
+}
+
+export function toJobExecutionDto(jobExecution: JobExecution): JobExecutionDto {
+  return {
+    id: jobExecution.id,
+    job_id: jobExecution.jobId,
+    sequence: jobExecution.sequence,
+    name: jobExecution.name,
+    status: jobExecution.status,
+    status_reason: jobExecution.statusReason,
+    trigger_events: jobExecution.triggerEvents,
+    outputs: jobExecution.outputs,
+    queued_at: jobExecution.queuedAt?.toISOString() ?? null,
+    started_at: jobExecution.startedAt?.toISOString() ?? null,
+    finished_at: jobExecution.finishedAt?.toISOString() ?? null,
+    timed_out_at: jobExecution.timedOutAt?.toISOString() ?? null,
+    created_at: jobExecution.createdAt.toISOString(),
+    updated_at: jobExecution.updatedAt.toISOString(),
+  };
+}