@shipfox/api-workflows 10.2.0 → 12.0.0

package/drizzle/meta/_journal.json

@@ -12,8 +12,8 @@
     {
       "idx": 1,
       "version": "7",
-      "when": 1783439600000,
-      "tag": "0001_agent_tool_materialization",
+      "when": 1785771111717,
+      "tag": "0001_windy_sunfire",
       "breakpoints": true
     }
   ]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "10.2.0",
+  "version": "12.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -22,29 +22,29 @@
     "@temporalio/workflow": "1.18.1",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "10.2.0",
-    "@shipfox/api-auth-dto": "10.2.0",
-    "@shipfox/api-agent-dto": "10.0.0",
-    "@shipfox/annotations-dto": "9.0.2",
-    "@shipfox/api-definitions-dto": "10.0.0",
-    "@shipfox/api-projects-dto": "10.1.0",
-    "@shipfox/api-integration-core-dto": "9.0.2",
-    "@shipfox/api-runners-dto": "10.2.0",
-    "@shipfox/api-secrets-dto": "9.0.2",
-    "@shipfox/api-workflows-dto": "10.0.0",
-    "@shipfox/api-workspaces-dto": "10.2.0",
-    "@shipfox/inter-module": "0.2.2",
-    "@shipfox/expression": "1.2.0",
-    "@shipfox/node-drizzle": "0.3.4",
+    "@shipfox/api-auth-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-agent-dto": "12.0.0",
+    "@shipfox/api-auth-context": "12.0.0",
+    "@shipfox/api-integration-core-dto": "12.0.0",
+    "@shipfox/api-runners-dto": "12.0.0",
+    "@shipfox/api-workflows-dto": "12.0.0",
+    "@shipfox/api-workspaces-dto": "12.0.0",
+    "@shipfox/api-secrets-dto": "12.0.0",
+    "@shipfox/inter-module": "0.2.3",
+    "@shipfox/expression": "2.0.0",
+    "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
-    "@shipfox/node-fastify": "0.4.0",
-    "@shipfox/node-module": "1.0.4",
-    "@shipfox/node-opentelemetry": "0.6.3",
+    "@shipfox/node-fastify": "0.4.1",
+    "@shipfox/node-module": "1.0.5",
     "@shipfox/node-outbox": "0.2.6",
-    "@shipfox/node-postgres": "0.4.4",
+    "@shipfox/node-opentelemetry": "0.6.3",
+    "@shipfox/node-postgres": "0.5.0",
     "@shipfox/node-temporal": "0.4.4",
-    "@shipfox/runner-labels": "0.1.3",
-    "@shipfox/workflow-document": "2.1.3"
+    "@shipfox/workflow-document": "3.0.0",
+    "@shipfox/runner-labels": "0.1.3"
   },
   "imports": {
     "#*": "./dist/*"

package/src/core/agent-defaults.ts

@@ -6,7 +6,8 @@ export interface AgentDefaultsInput {
   readonly harness?: Harness | undefined;
   readonly provider?: ModelProviderRef | undefined;
   readonly model?: string | undefined;
-  readonly thinking?: AgentThinking | undefined;
+  /** A resolved template can carry any string. The agent module validates it. */
+  readonly thinking?: string | undefined;
 }
 
 export interface ResolvedAgentDefaults {

package/src/core/checkout.test.ts

@@ -1,125 +1,436 @@
 import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
 import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
-import * as workflowRuns from '#db/workflow-runs.js';
-import {jobFactory} from '#test/factories/job.js';
 import {projectFactory} from '#test/factories/project.js';
-import {createJobCheckoutSpec, resolveCheckoutIntent} from './checkout.js';
-import {
-  CheckoutIntentUnresolvedError,
-  JobNotFoundError,
-  WorkflowRunNotFoundError,
-} from './errors.js';
+import {createStepCheckoutSpec} from './checkout.js';
+import type {Step} from './entities/step.js';
+import type {WorkflowRunTriggerReference} from './entities/workflow-run.js';
+import {CheckoutConfigInvalidError, CheckoutIntentUnresolvedError} from './errors.js';
 
 const getProjectById = vi.fn();
-const projects = {getProjectById} as Pick<ProjectsModuleClient, 'getProjectById'>;
+const resolveCheckoutTarget = vi.fn();
+const projects = {
+  getProjectById,
+  resolveCheckoutTarget,
+} as Pick<ProjectsModuleClient, 'getProjectById' | 'resolveCheckoutTarget'>;
 
-describe('resolveCheckoutIntent', () => {
-  it('resolves connection + repo from the project, using the project workspace', async () => {
+const resolveConnection = vi.fn();
+const createCheckoutSpec = vi.fn();
+const integrations = {
+  resolveConnection,
+  createCheckoutSpec,
+} as Pick<IntegrationsModuleClient, 'createCheckoutSpec' | 'resolveConnection'>;
+
+describe('createStepCheckoutSpec', () => {
+  beforeEach(() => {
+    getProjectById.mockReset();
+    resolveCheckoutTarget.mockReset();
+    resolveConnection.mockReset();
+    createCheckoutSpec.mockReset();
+  });
+
+  it('resolves the default project target and setup-step defaults', async () => {
     const project = projectFactory.build();
+    const step = checkoutStep({
+      permissions: {contents: 'read'},
+      persist_credentials: true,
+    });
     getProjectById.mockResolvedValue({project});
-    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: 'main',
+    });
 
-    const intent = await resolveCheckoutIntent(job.id, projects as ProjectsModuleClient);
+    const result = await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
 
-    expect(intent).toEqual({
+    expect(result).toEqual({
+      spec: {
+        repositoryUrl: 'https://github.com/acme/repo.git',
+        ref: 'main',
+      },
+      fetchDepth: 1,
+      persistCredentials: true,
+    });
+    expect(resolveCheckoutTarget).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      defaults: {connectionId: project.sourceConnectionId, owner: 'acme'},
+      target: {project: project.id},
+    });
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
       workspaceId: project.workspaceId,
       connectionId: project.sourceConnectionId,
       externalRepositoryId: project.sourceExternalRepositoryId,
-      persistCredentials: true,
       permissions: {contents: 'read'},
     });
   });
 
-  it('throws JobNotFoundError for an unknown job', async () => {
-    const act = resolveCheckoutIntent(crypto.randomUUID(), projects as ProjectsModuleClient);
+  it('passes an explicit frozen target, ref, permissions, and fetch depth', async () => {
+    const project = projectFactory.build();
+    const targetProjectId = crypto.randomUUID();
+    const step = checkoutStep({
+      project: targetProjectId,
+      ref: 'refs/pull/412/head',
+      fetch_depth: 0,
+      permissions: {contents: 'write'},
+      persist_credentials: false,
+    });
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: targetProjectId,
+      connectionId: crypto.randomUUID(),
+      externalRepositoryId: 'github:412',
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: 'refs/pull/412/head',
+    });
+
+    const result = await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference: triggerReferenceFor(project.id),
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
 
-    await expect(act).rejects.toBeInstanceOf(JobNotFoundError);
+    expect(result.fetchDepth).toBe(0);
+    expect(result.persistCredentials).toBe(false);
+    expect(resolveCheckoutTarget).toHaveBeenCalledWith(
+      expect.objectContaining({target: {project: targetProjectId}}),
+    );
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: expect.any(String),
+      externalRepositoryId: 'github:412',
+      ref: 'refs/pull/412/head',
+      permissions: {contents: 'write'},
+    });
   });
 
-  it('resolves the checkout target while the parent job projection is still pending', async () => {
+  it('defaults the ref to the trigger commit for the triggered repository', async () => {
     const project = projectFactory.build();
+    const triggerReference = triggerReferenceFor(project.id);
+    const step = checkoutStep({permissions: {contents: 'read'}});
     getProjectById.mockResolvedValue({project});
-    const job = await jobFactory.create(
-      {},
-      {transient: {projectId: project.id, status: 'pending'}},
-    );
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: triggerReference.commit,
+    });
 
-    const intent = await resolveCheckoutIntent(job.id, projects as ProjectsModuleClient);
+    await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
 
-    expect(intent.connectionId).toBe(project.sourceConnectionId);
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: triggerReference.commit,
+      permissions: {contents: 'read'},
+    });
   });
 
-  it('throws WorkflowRunNotFoundError when the run is missing', async () => {
+  it('preserves an explicit ref when the trigger targets the same project', async () => {
     const project = projectFactory.build();
+    const explicitRef = 'refs/pull/412/head';
+    const step = checkoutStep({ref: explicitRef, permissions: {contents: 'read'}});
     getProjectById.mockResolvedValue({project});
-    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
-    vi.spyOn(workflowRuns, 'getWorkflowRunByAttemptId').mockResolvedValue(undefined);
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: explicitRef,
+    });
 
-    const act = resolveCheckoutIntent(job.id, projects as ProjectsModuleClient);
+    await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference: triggerReferenceFor(project.id),
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
 
-    await expect(act).rejects.toBeInstanceOf(WorkflowRunNotFoundError);
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      ref: explicitRef,
+      permissions: {contents: 'read'},
+    });
   });
 
-  it('throws CheckoutIntentUnresolvedError when the project is missing', async () => {
+  it('uses the provider default when the matching trigger reference has no commit', async () => {
     const project = projectFactory.build();
-    getProjectById.mockResolvedValue({project: null});
-    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
+    const triggerReference = {...triggerReferenceFor(project.id), commit: null};
+    const step = checkoutStep({permissions: {contents: 'read'}});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: 'main',
+    });
 
-    const act = resolveCheckoutIntent(job.id, projects as ProjectsModuleClient);
+    await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
 
-    await expect(act).rejects.toBeInstanceOf(CheckoutIntentUnresolvedError);
+    expect(createCheckoutSpec).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+      permissions: {contents: 'read'},
+    });
   });
-});
 
-describe('createJobCheckoutSpec', () => {
-  it('passes the resolved intent without a ref to the service', async () => {
+  it('keeps the provider default ref for a cross-repository target', async () => {
     const project = projectFactory.build();
+    const targetProjectId = crypto.randomUUID();
+    const step = checkoutStep({project: targetProjectId});
     getProjectById.mockResolvedValue({project});
-    const job = await jobFactory.create({}, {transient: {projectId: project.id}});
-    const spec = {repositoryUrl: 'https://github.com/acme/repo.git', ref: 'main'};
-    const createCheckoutSpec = vi.fn().mockResolvedValue(spec);
-    const integrations = {createCheckoutSpec} as Pick<
-      IntegrationsModuleClient,
-      'createCheckoutSpec'
-    >;
-
-    const result = await createJobCheckoutSpec({
-      jobId: job.id,
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: targetProjectId,
+      connectionId: crypto.randomUUID(),
+      externalRepositoryId: 'github:412',
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/target.git',
+      ref: 'main',
+    });
+
+    await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      triggerReference: triggerReferenceFor(project.id),
       integrations: integrations as IntegrationsModuleClient,
       projects: projects as ProjectsModuleClient,
     });
 
-    expect(result).toEqual({spec, persistCredentials: true});
     expect(createCheckoutSpec).toHaveBeenCalledWith({
       workspaceId: project.workspaceId,
+      connectionId: expect.any(String),
+      externalRepositoryId: 'github:412',
+      permissions: {contents: 'read'},
+    });
+  });
+
+  it('resolves a repository target using the frozen project owner as the default', async () => {
+    const project = projectFactory.build();
+    const step = checkoutStep({repository: 'repo', persist_credentials: true});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
       connectionId: project.sourceConnectionId,
       externalRepositoryId: project.sourceExternalRepositoryId,
-      permissions: {contents: 'read'},
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: 'main',
+    });
+
+    await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(resolveCheckoutTarget).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      defaults: {connectionId: project.sourceConnectionId, owner: 'acme'},
+      target: {repository: 'repo'},
     });
   });
 
-  it('passes requested write contents permission to the service', async () => {
+  it('resolves an explicit connection slug before resolving a repository target', async () => {
     const project = projectFactory.build();
+    const connectionId = crypto.randomUUID();
+    const step = checkoutStep({connection: 'github', repository: 'acme/repo'});
     getProjectById.mockResolvedValue({project});
-    const job = await jobFactory.create(
-      {},
-      {transient: {projectId: project.id, checkout: {permissions: {contents: 'write'}}}},
-    );
-    const spec = {repositoryUrl: 'https://github.com/acme/repo.git', ref: 'main'};
-    const createCheckoutSpec = vi.fn().mockResolvedValue(spec);
-    const integrations = {createCheckoutSpec} as Pick<
-      IntegrationsModuleClient,
-      'createCheckoutSpec'
-    >;
-
-    await createJobCheckoutSpec({
-      jobId: job.id,
+    resolveConnection.mockResolvedValue({id: connectionId, provider: 'github', slug: 'github'});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: 'main',
+    });
+
+    await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
       integrations: integrations as IntegrationsModuleClient,
       projects: projects as ProjectsModuleClient,
     });
 
-    expect(createCheckoutSpec).toHaveBeenCalledWith(
-      expect.objectContaining({permissions: {contents: 'write'}}),
-    );
+    expect(resolveConnection).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      slug: 'github',
+    });
+    expect(resolveCheckoutTarget).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      defaults: {connectionId: project.sourceConnectionId, owner: 'acme'},
+      target: {connection: connectionId, repository: 'acme/repo'},
+    });
+  });
+
+  it.each([
+    {repository: 'octocat/repo', owner: 'octocat'},
+    {repository: 'repo', owner: 'unknown'},
+  ])('derives the repository owner fallback for $repository', async ({repository, owner}) => {
+    const project = projectFactory.build({sourceRepositoryOwner: null});
+    const step = checkoutStep({repository});
+    getProjectById.mockResolvedValue({project});
+    resolveCheckoutTarget.mockResolvedValue({
+      projectId: project.id,
+      connectionId: project.sourceConnectionId,
+      externalRepositoryId: project.sourceExternalRepositoryId,
+    });
+    createCheckoutSpec.mockResolvedValue({
+      repositoryUrl: 'https://github.com/acme/repo.git',
+      ref: 'main',
+    });
+
+    await createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    expect(resolveCheckoutTarget).toHaveBeenCalledWith({
+      workspaceId: project.workspaceId,
+      defaults: {connectionId: project.sourceConnectionId, owner},
+      target: {repository},
+    });
+  });
+
+  it.each([
+    {project: crypto.randomUUID(), connection: 'github'},
+    {project: crypto.randomUUID(), repository: 'acme/repo'},
+    {connection: 'github'},
+  ])('rejects invalid checkout target shape: %j', async (checkout) => {
+    const act = createStepCheckoutSpec({
+      step: checkoutStep(checkout),
+      workspaceId: crypto.randomUUID(),
+      projectId: crypto.randomUUID(),
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    await expect(act).rejects.toBeInstanceOf(CheckoutConfigInvalidError);
+    expect(getProjectById).not.toHaveBeenCalled();
+    expect(resolveCheckoutTarget).not.toHaveBeenCalled();
+    expect(createCheckoutSpec).not.toHaveBeenCalled();
+  });
+
+  it('throws when the run project is missing', async () => {
+    const projectId = crypto.randomUUID();
+    getProjectById.mockResolvedValue({project: null});
+
+    const act = createStepCheckoutSpec({
+      step: checkoutStep({}),
+      workspaceId: crypto.randomUUID(),
+      projectId,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    await expect(act).rejects.toBeInstanceOf(CheckoutIntentUnresolvedError);
+    expect(resolveCheckoutTarget).not.toHaveBeenCalled();
+    expect(createCheckoutSpec).not.toHaveBeenCalled();
+  });
+
+  it('identifies a missing explicit connection in the unresolved error', async () => {
+    const project = projectFactory.build();
+    const step = checkoutStep({connection: 'missing', repository: 'acme/repo'});
+    getProjectById.mockResolvedValue({project});
+    resolveConnection.mockResolvedValue(null);
+
+    const act = createStepCheckoutSpec({
+      step,
+      workspaceId: project.workspaceId,
+      projectId: project.id,
+      integrations: integrations as IntegrationsModuleClient,
+      projects: projects as ProjectsModuleClient,
+    });
+
+    await expect(act).rejects.toThrow('Checkout intent unresolved: connection missing not found');
+    expect(resolveCheckoutTarget).not.toHaveBeenCalled();
+    expect(createCheckoutSpec).not.toHaveBeenCalled();
   });
 });
+
+function checkoutStep(checkout: Record<string, unknown>): Step {
+  const now = new Date();
+  return {
+    id: crypto.randomUUID(),
+    jobExecutionId: crypto.randomUUID(),
+    key: null,
+    name: 'Checkout',
+    sourceLocation: null,
+    status: 'running',
+    statusReason: null,
+    evaluationTrace: null,
+    type: 'checkout',
+    config: {checkout},
+    condition: null,
+    configPlan: null,
+    authoredConfig: null,
+    error: null,
+    position: 1,
+    version: 1,
+    currentAttempt: 1,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function triggerReferenceFor(projectId: string): WorkflowRunTriggerReference {
+  return {
+    project: {id: projectId},
+    repository: 'acme/repo',
+    ref: 'refs/heads/feature/checkout',
+    commit: 'a'.repeat(40),
+    actor: null,
+  };
+}