@shipfox/api-integration-core 13.0.0 → 14.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-core",
   "license": "MIT",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -24,19 +24,19 @@
     "ajv": "^8.20.0",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-agent-dto": "12.2.0",
+    "@shipfox/api-agent-dto": "14.0.0",
     "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-workflows-dto": "13.0.0",
-    "@shipfox/api-integration-core-dto": "12.2.0",
-    "@shipfox/api-integration-spi": "1.1.1",
+    "@shipfox/api-workflows-dto": "14.0.0",
+    "@shipfox/api-integration-core-dto": "14.0.0",
+    "@shipfox/api-integration-spi": "2.0.0",
     "@shipfox/api-workspaces-dto": "12.0.0",
-    "@shipfox/api-integration-gitea": "12.5.0",
-    "@shipfox/api-integration-github": "12.7.0",
-    "@shipfox/api-integration-jira": "12.5.0",
-    "@shipfox/api-integration-linear": "12.5.0",
-    "@shipfox/api-integration-sentry": "12.5.0",
-    "@shipfox/api-integration-slack": "12.5.0",
-    "@shipfox/api-integration-webhook": "12.5.0",
+    "@shipfox/api-integration-gitea": "14.0.0",
+    "@shipfox/api-integration-github": "14.0.0",
+    "@shipfox/api-integration-jira": "14.0.0",
+    "@shipfox/api-integration-linear": "14.0.0",
+    "@shipfox/api-integration-sentry": "14.0.0",
+    "@shipfox/api-integration-slack": "14.0.0",
+    "@shipfox/api-integration-webhook": "14.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
     "@shipfox/node-drizzle": "0.3.5",

package/src/core/agent-tool-selection.test.ts

@@ -110,6 +110,10 @@ function sourceProvider(provider: string) {
           throw new Error('not used');
         },
         resolveTriggerReference: () => null,
+        resolveRef: async () => {
+          await Promise.resolve();
+          throw new Error('not used');
+        },
       },
     },
   };

package/src/core/event-catalogs.test.ts

@@ -0,0 +1,16 @@
+import {createIntegrationProviderRegistry} from '#core/providers/registry.js';
+import {buildFixedEventProviders} from './event-catalogs.js';
+
+describe('buildFixedEventProviders', () => {
+  it('omits fixed providers that are not registered', () => {
+    expect(buildFixedEventProviders(createIntegrationProviderRegistry([]))).toEqual([]);
+  });
+
+  it('keeps a registered fixed provider in the context metadata', () => {
+    expect(
+      buildFixedEventProviders(
+        createIntegrationProviderRegistry([{provider: 'webhook', displayName: 'Webhook'}]),
+      ),
+    ).toEqual(['webhook']);
+  });
+});

package/src/core/event-catalogs.ts

@@ -0,0 +1,34 @@
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+
+/**
+ * Providers whose single event name is minted by Shipfox. An explicit event on
+ * one of these providers is provably wrong unless it is that one name; every
+ * other provider's event names are provider-minted and never treated as a
+ * closed set. `manual` and `cron` are registered built-in trigger sources;
+ * sync classifies them by literal, before slug resolution.
+ */
+export const FIXED_EVENT_PROVIDERS = ['webhook'] as const;
+
+export interface ProviderEventCatalog {
+  provider: string;
+  events: string[];
+}
+
+/** Keeps fixed-provider metadata aligned with the enabled provider registry. */
+export function buildFixedEventProviders(
+  registry: IntegrationProviderRegistry,
+): Array<(typeof FIXED_EVENT_PROVIDERS)[number]> {
+  const registeredProviders = new Set(registry.list().map(({provider}) => provider));
+  return FIXED_EVENT_PROVIDERS.filter((provider) => registeredProviders.has(provider));
+}
+
+/** Collects the event names each registered provider documents. */
+export function buildProviderEventCatalogs(
+  registry: IntegrationProviderRegistry,
+): ProviderEventCatalog[] {
+  return registry.list().flatMap((provider) => {
+    const catalog = provider.eventCatalog;
+    if (catalog === undefined) return [];
+    return [{provider: provider.provider, events: catalog.events.map((event) => event.name)}];
+  });
+}

package/src/core/providers/registry.test.ts

@@ -23,6 +23,10 @@ function sourceControlAdapter() {
       throw new Error('not used');
     },
     resolveTriggerReference: () => null,
+    resolveRef: async () => {
+      await Promise.resolve();
+      throw new Error('not used');
+    },
   };
 }
 

package/src/core/providers/registry.ts

@@ -83,8 +83,14 @@ function normalizeProvider(provider: IntegrationProvider): RegisteredIntegration
   return {
     ...provider,
     adapters,
-    capabilities: Object.entries(adapters)
-      .filter(([, adapter]) => Boolean(adapter))
-      .map(([capability]) => capability as IntegrationCapability),
+    capabilities: getIntegrationProviderCapabilities(adapters),
   };
 }
+
+export function getIntegrationProviderCapabilities(
+  adapters: IntegrationProvider['adapters'],
+): IntegrationCapability[] {
+  return Object.entries(adapters ?? {})
+    .filter(([, adapter]) => Boolean(adapter))
+    .map(([capability]) => capability as IntegrationCapability);
+}

package/src/core/providers/source-control.ts

@@ -12,6 +12,8 @@ export type {
   RepositoryPage,
   RepositorySnapshot,
   RepositoryVisibility,
+  ResolvedRef,
+  ResolveRefInput,
   ResolveRepositoryInput,
   SourceControlProvider,
   TriggerReference,

package/src/core/secret-cleanup.test.ts

@@ -119,6 +119,7 @@ async function createCleanupConnection(
     externalAccountId: overrides.externalAccountId ?? crypto.randomUUID(),
     slug: `${overrides.provider ?? 'slack'}_${crypto.randomUUID()}`,
     displayName: overrides.provider ?? 'Slack',
+    capabilities: overrides.provider === 'gitea' ? ['source_control'] : ['agent_tools'],
   });
   await enqueueIntegrationSecretCleanup({connection});
   return connection;

package/src/core/source-control-service.test.ts

@@ -52,6 +52,10 @@ describe('integration source-control service', () => {
         await Promise.resolve();
         return {path: '.shipfox/workflows/ci.yml', ref: 'main', content: 'name: CI'};
       },
+      resolveRef: async (input) => {
+        await Promise.resolve();
+        return {ref: input.ref, commit: 'a'.repeat(40)};
+      },
       resolveTriggerReference: () => null,
       createCheckoutSpec: async (input) => {
         await Promise.resolve();
@@ -116,6 +120,50 @@ describe('integration source-control service', () => {
     expect(resolveTriggerReference).toHaveBeenCalledWith({ref: 'refs/heads/main'});
   });
 
+  it('resolves a ref to a pinned commit through an active source-control connection', async () => {
+    const service = createService();
+
+    const result = await service.resolveSourceRef({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+      ref: 'refs/heads/main',
+    });
+
+    expect(result).toEqual({ref: 'refs/heads/main', commit: 'a'.repeat(40)});
+  });
+
+  it('surfaces provider ref failures', async () => {
+    const service = createService({
+      resolveRef: async () => {
+        await Promise.resolve();
+        throw new IntegrationProviderError('ref-not-found', 'Ref not found');
+      },
+    });
+
+    const result = service.resolveSourceRef({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+      ref: 'refs/heads/missing',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'ref-not-found'});
+  });
+
+  it('rejects source ref resolution for a connection in another workspace', async () => {
+    const service = createService();
+
+    const result = service.resolveSourceRef({
+      workspaceId: crypto.randomUUID(),
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+      ref: 'refs/heads/main',
+    });
+
+    await expect(result).rejects.toThrow('requested workspace');
+  });
+
   it('rejects a missing connection', async () => {
     const service = createService();
 

package/src/core/source-control-service.ts

@@ -13,6 +13,7 @@ import type {
   FileSnapshot,
   RepositoryPage,
   RepositorySnapshot,
+  ResolvedRef,
   TriggerReference,
 } from './providers/source-control.js';
 
@@ -21,6 +22,7 @@ export interface IntegrationSourceControlService {
   listRepositories(input: ListSourceRepositoriesInput): Promise<RepositoryPage>;
   resolveRepository(input: ResolveSourceRepositoryInput): Promise<ResolvedSourceRepository>;
   resolveTriggerReference(input: ResolveTriggerReferenceInput): Promise<TriggerReference | null>;
+  resolveSourceRef(input: ResolveSourceRefInput): Promise<ResolvedRef>;
   listFiles(input: ListSourceFilesInput): Promise<FilePage>;
   fetchFile(input: FetchSourceFileInput): Promise<FileSnapshot>;
   createCheckoutSpec(input: CreateSourceCheckoutSpecInput): Promise<CheckoutSpec>;
@@ -45,6 +47,10 @@ export interface ResolveTriggerReferenceInput {
   payload: unknown;
 }
 
+export interface ResolveSourceRefInput extends ResolveSourceRepositoryInput {
+  ref: string;
+}
+
 export interface ListSourceFilesInput extends ResolveSourceRepositoryInput {
   ref: string;
   prefix: string;
@@ -129,6 +135,16 @@ export function createSourceControlIntegrationService({
       return sourceControl?.resolveTriggerReference(payload) ?? null;
     },
 
+    async resolveSourceRef({workspaceId, connectionId, externalRepositoryId, ref}) {
+      const connection = await getConnection(connectionId);
+      if (connection.workspaceId !== workspaceId) {
+        throw new IntegrationConnectionWorkspaceMismatchError(connectionId);
+      }
+      const sourceControl = registry.getAdapter(connection.provider, 'source_control');
+
+      return await sourceControl.resolveRef({connection, externalRepositoryId, ref});
+    },
+
     async listFiles({workspaceId, connectionId, externalRepositoryId, ref, prefix, limit, cursor}) {
       const connection = await getConnection(connectionId);
       if (connection.workspaceId !== workspaceId) {

package/src/db/connections.test.ts

@@ -40,6 +40,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
 
     const second = await upsertIntegrationConnection({
@@ -48,6 +49,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'gitea-owner',
       slug: 'debug_renamed',
       displayName: 'Renamed Debug',
+      capabilities: ['source_control'],
     });
 
     expect(second.id).toBe(first.id);
@@ -64,6 +66,7 @@ describe('integration connection queries', () => {
       slug: 'linear_acme',
       displayName: 'Linear Acme',
       lifecycleStatus: 'disabled',
+      capabilities: ['agent_tools'],
     });
 
     expect(await connectionEvents(connection.id)).toHaveLength(0);
@@ -75,6 +78,7 @@ describe('integration connection queries', () => {
       slug: 'linear_acme',
       displayName: 'Linear Acme',
       lifecycleStatus: 'active',
+      capabilities: ['agent_tools'],
     });
 
     expect(await connectionEvents(connection.id)).toHaveLength(1);
@@ -87,6 +91,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'debug-1',
       slug: 'debug_1',
       displayName: 'Debug One',
+      capabilities: ['source_control'],
     });
     await upsertIntegrationConnection({
       workspaceId,
@@ -94,6 +99,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'debug-2',
       slug: 'debug_2',
       displayName: 'Debug Two',
+      capabilities: ['source_control'],
     });
 
     const result = await listIntegrationConnections({workspaceId});
@@ -108,6 +114,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'debug-1',
       slug: 'github_main',
       displayName: 'GitHub',
+      capabilities: ['source_control', 'agent_tools'],
     });
 
     await expect(
@@ -125,6 +132,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'debug-1',
       slug: 'gitea_owner',
       displayName: 'Debug One',
+      capabilities: ['source_control'],
     });
     await upsertIntegrationConnection({
       workspaceId,
@@ -132,6 +140,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'debug-2',
       slug: 'debug_2',
       displayName: 'Debug Two',
+      capabilities: ['source_control', 'agent_tools'],
     });
 
     const result = await resolveUniqueConnectionSlug({
@@ -144,6 +153,83 @@ describe('integration connection queries', () => {
     expect(result).toBe('debug');
   });
 
+  it.each([
+    'github',
+    'gitea',
+    'sentry',
+    'slack',
+    'jira',
+    'linear',
+    'webhook',
+  ] as const)('refuses the reserved source slugs for provider %s', async (provider) => {
+    // Sync classifies a trigger source by literal: `manual` and `cron` are
+    // built-in sources, never connection slugs, so every provider must refuse
+    // to allocate them.
+    for (const baseSlug of ['manual', 'cron'] as const) {
+      await expect(
+        resolveUniqueConnectionSlug({
+          workspaceId,
+          provider,
+          externalAccountId: 'external-account',
+          baseSlug,
+        }),
+      ).rejects.toBeInstanceOf(ConnectionSlugConflictError);
+    }
+  });
+
+  it('still allocates provider-prefixed slugs derived from reserved words', async () => {
+    const result = await resolveUniqueConnectionSlug({
+      workspaceId,
+      provider: 'github',
+      externalAccountId: 'external-account',
+      baseSlug: 'github_manual',
+    });
+
+    expect(result).toBe('github_manual');
+  });
+
+  it.each([
+    'manual_',
+    'MANUAL',
+    'cron-',
+  ] as const)('refuses slugs that normalize to a reserved source slug: %s', async (baseSlug) => {
+    await expect(
+      resolveUniqueConnectionSlug({
+        workspaceId,
+        provider: 'github',
+        externalAccountId: `normalized-${baseSlug}`,
+        baseSlug,
+      }),
+    ).rejects.toBeInstanceOf(ConnectionSlugConflictError);
+  });
+
+  it.each([
+    'manual',
+    'cron',
+  ] as const)('refuses direct writes for reserved slug %s', async (slug) => {
+    await expect(
+      createIntegrationConnection({
+        workspaceId,
+        provider: 'github',
+        externalAccountId: `create-${slug}`,
+        slug,
+        displayName: 'GitHub',
+        capabilities: ['source_control'],
+      }),
+    ).rejects.toBeInstanceOf(ConnectionSlugConflictError);
+
+    await expect(
+      upsertIntegrationConnection({
+        workspaceId,
+        provider: 'gitea',
+        externalAccountId: `upsert-${slug}`,
+        slug,
+        displayName: 'Gitea',
+        capabilities: ['source_control'],
+      }),
+    ).rejects.toBeInstanceOf(ConnectionSlugConflictError);
+  });
+
   it('keeps the existing slug when resolving a reconnect', async () => {
     await upsertIntegrationConnection({
       workspaceId,
@@ -151,6 +237,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'install-uuid',
       slug: 'sentry_prod',
       displayName: 'Sentry',
+      capabilities: [],
     });
 
     const result = await resolveUniqueConnectionSlug({
@@ -170,6 +257,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'stripe',
       slug: 'stripe',
       displayName: 'Stripe',
+      capabilities: [],
     });
 
     const result = createIntegrationConnection({
@@ -178,6 +266,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'stripe',
       slug: 'stripe_renamed',
       displayName: 'Renamed Stripe',
+      capabilities: [],
     });
 
     await expect(result).rejects.toBeInstanceOf(IntegrationConnectionAlreadyExistsError);
@@ -195,6 +284,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'stripe',
       slug: 'stripe',
       displayName: 'Stripe',
+      capabilities: [],
     });
 
     const result = createIntegrationConnection({
@@ -203,6 +293,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'stripe-prod',
       slug: 'stripe',
       displayName: 'Stripe prod',
+      capabilities: [],
     });
 
     await expect(result).rejects.toBeInstanceOf(ConnectionSlugConflictError);
@@ -215,6 +306,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
     await upsertIntegrationConnection({
       workspaceId,
@@ -222,6 +314,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'team-1',
       slug: 'github_team_1',
       displayName: 'GitHub',
+      capabilities: ['source_control', 'agent_tools'],
     });
     await upsertIntegrationConnection({
       workspaceId,
@@ -230,6 +323,7 @@ describe('integration connection queries', () => {
       slug: 'github_installation_1',
       displayName: 'GitHub',
       lifecycleStatus: 'disabled',
+      capabilities: ['source_control', 'agent_tools'],
     });
 
     const result = await listIntegrationConnections({workspaceId});
@@ -249,6 +343,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
     const debugB = await upsertIntegrationConnection({
       workspaceId: otherWorkspaceId,
@@ -256,6 +351,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'gitea-owner',
       slug: 'gitea_owner',
       displayName: 'Gitea',
+      capabilities: ['source_control'],
     });
     const github = await upsertIntegrationConnection({
       workspaceId,
@@ -263,6 +359,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'gh-1',
       slug: 'github_gh_1',
       displayName: 'GitHub',
+      capabilities: ['source_control', 'agent_tools'],
     });
 
     const result = await listIntegrationConnectionsByProvider({provider: 'gitea'});
@@ -280,11 +377,13 @@ describe('integration connection queries', () => {
       externalAccountId: 'install-uuid',
       slug: 'sentry_install_uuid',
       displayName: 'Sentry acme',
+      capabilities: [],
     });
 
     const updated = await updateIntegrationConnectionLifecycleStatus({
       id: connection.id,
       lifecycleStatus: 'disabled',
+      capabilities: [],
     });
 
     expect(updated?.lifecycleStatus).toBe('disabled');
@@ -301,6 +400,7 @@ describe('integration connection queries', () => {
       slug: 'linear_acme',
       displayName: 'Linear Acme',
       lifecycleStatus: 'disabled',
+      capabilities: ['agent_tools'],
     });
 
     expect(await connectionEvents(connection.id)).toHaveLength(0);
@@ -308,6 +408,7 @@ describe('integration connection queries', () => {
     await updateIntegrationConnectionLifecycleStatus({
       id: connection.id,
       lifecycleStatus: 'active',
+      capabilities: ['agent_tools'],
     });
 
     const events = await connectionEvents(connection.id);
@@ -317,6 +418,7 @@ describe('integration connection queries', () => {
       workspaceId,
       connectionId: connection.id,
       slug: 'linear_acme',
+      capabilities: ['agent_tools'],
     });
   });
 
@@ -327,11 +429,13 @@ describe('integration connection queries', () => {
       externalAccountId: 'linear-acme',
       slug: 'linear_acme',
       displayName: 'Linear Acme',
+      capabilities: ['agent_tools'],
     });
 
     await updateIntegrationConnectionLifecycleStatus({
       id: connection.id,
       lifecycleStatus: 'active',
+      capabilities: ['agent_tools'],
     });
 
     expect(await connectionEvents(connection.id)).toHaveLength(1);
@@ -341,6 +445,7 @@ describe('integration connection queries', () => {
     const result = await updateIntegrationConnectionLifecycleStatus({
       id: crypto.randomUUID(),
       lifecycleStatus: 'disabled',
+      capabilities: [],
     });
 
     expect(result).toBeUndefined();
@@ -353,6 +458,7 @@ describe('integration connection queries', () => {
       externalAccountId: 'stripe',
       slug: 'stripe',
       displayName: 'Stripe',
+      capabilities: [],
     });
 
     const deleted = await deleteIntegrationConnection({id: connection.id});
@@ -372,6 +478,7 @@ describe('integration connection queries', () => {
           externalAccountId: '123',
           slug: 'github_123',
           displayName: 'GitHub shipfox',
+          capabilities: ['source_control', 'agent_tools'],
         },
         {tx},
       );
@@ -401,4 +508,64 @@ describe('integration connection queries', () => {
       );
     expect(events).toHaveLength(0);
   });
+
+  it('publishes source-control and tool capabilities for a GitHub connection', async () => {
+    const connection = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'github',
+      externalAccountId: 'gh-capabilities',
+      slug: 'github_capabilities',
+      displayName: 'GitHub',
+      capabilities: ['source_control', 'agent_tools'],
+    });
+
+    const [event] = await connectionEvents(connection.id);
+    expect(event?.payload).toEqual({
+      provider: 'github',
+      workspaceId,
+      connectionId: connection.id,
+      slug: 'github_capabilities',
+      capabilities: ['source_control', 'agent_tools'],
+    });
+  });
+
+  it('publishes agent-tool capabilities for a Linear connection', async () => {
+    const connection = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'linear',
+      externalAccountId: 'linear-capabilities',
+      slug: 'linear_capabilities',
+      displayName: 'Linear',
+      capabilities: ['agent_tools'],
+    });
+
+    const [event] = await connectionEvents(connection.id);
+    expect(event?.payload).toEqual({
+      provider: 'linear',
+      workspaceId,
+      connectionId: connection.id,
+      slug: 'linear_capabilities',
+      capabilities: ['agent_tools'],
+    });
+  });
+
+  it('publishes an empty capabilities array for a webhook connection', async () => {
+    const connection = await createIntegrationConnection({
+      workspaceId,
+      provider: 'webhook',
+      externalAccountId: 'stripe-capabilities',
+      slug: 'stripe_capabilities',
+      displayName: 'Stripe',
+      capabilities: [],
+    });
+
+    const [event] = await connectionEvents(connection.id);
+    expect(event?.payload).toEqual({
+      provider: 'webhook',
+      workspaceId,
+      connectionId: connection.id,
+      slug: 'stripe_capabilities',
+      capabilities: [],
+    });
+  });
 });