@shipfox/api-server 13.0.0 → 14.0.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@shipfox/api-server",
   "license": "MIT",
   "private": false,
-  "version": "13.0.0",
+  "version": "14.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -24,28 +24,28 @@
   "dependencies": {
     "@shipfox/annotations": "12.3.0",
     "@shipfox/annotations-dto": "12.3.0",
-    "@shipfox/api-agent": "12.2.0",
-    "@shipfox/api-agent-dto": "12.2.0",
-    "@shipfox/api-auth": "12.2.0",
+    "@shipfox/api-agent": "14.0.0",
+    "@shipfox/api-agent-dto": "14.0.0",
+    "@shipfox/api-auth": "13.1.0",
     "@shipfox/api-auth-dto": "12.0.0",
-    "@shipfox/api-definitions": "12.3.0",
-    "@shipfox/api-definitions-dto": "12.3.0",
+    "@shipfox/api-definitions": "14.0.0",
+    "@shipfox/api-definitions-dto": "14.0.0",
     "@shipfox/api-dispatcher": "12.2.0",
-    "@shipfox/api-email-challenges": "1.1.8",
-    "@shipfox/api-integration-core": "13.0.0",
-    "@shipfox/api-integration-core-dto": "12.2.0",
-    "@shipfox/api-logs": "13.0.0",
-    "@shipfox/api-projects": "12.2.0",
-    "@shipfox/api-projects-dto": "12.2.0",
-    "@shipfox/api-runners": "13.0.0",
-    "@shipfox/api-runners-dto": "13.0.0",
-    "@shipfox/api-secrets": "12.2.0",
+    "@shipfox/api-email-challenges": "1.1.9",
+    "@shipfox/api-integration-core": "14.0.0",
+    "@shipfox/api-integration-core-dto": "14.0.0",
+    "@shipfox/api-logs": "14.0.0",
+    "@shipfox/api-projects": "14.0.0",
+    "@shipfox/api-projects-dto": "14.0.0",
+    "@shipfox/api-runners": "14.0.0",
+    "@shipfox/api-runners-dto": "14.0.0",
+    "@shipfox/api-secrets": "14.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-triggers": "13.0.0",
-    "@shipfox/api-workflows": "13.0.0",
-    "@shipfox/api-workflows-dto": "13.0.0",
+    "@shipfox/api-triggers": "14.0.0",
+    "@shipfox/api-workflows": "14.0.0",
+    "@shipfox/api-workflows-dto": "14.0.0",
     "@shipfox/api-workspaces-dto": "12.0.0",
-    "@shipfox/api-workspaces": "13.0.0",
+    "@shipfox/api-workspaces": "14.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-error-monitoring": "0.3.0",
     "@shipfox/node-fastify": "0.4.2",

package/src/index.ts

@@ -1,4 +1,5 @@
 export {
+  type DefaultAgentModuleFactory,
   type DefaultAuthModuleFactory,
   type DefaultModulesExtension,
   type DefaultModulesOptions,

package/src/modules.test.ts

@@ -14,7 +14,8 @@ import {
   type WorkspacesInterModuleClient,
   workspacesInterModuleContract,
 } from '@shipfox/api-workspaces-dto/inter-module';
-import {defineInterModulePresentation} from '@shipfox/inter-module';
+import {defineInterModuleContract, defineInterModulePresentation} from '@shipfox/inter-module';
+import type {DefaultAgentModuleFactory} from './modules.js';
 import {defaultModules} from './modules.js';
 
 const mocks = vi.hoisted(() => ({
@@ -35,6 +36,7 @@ const mocks = vi.hoisted(() => ({
   deleteSecrets: vi.fn(),
   getIntegrationConnectionById: vi.fn(),
   getSecret: vi.fn(),
+  getSecretsByNamespace: vi.fn(),
   getWorkspaceCreator: vi.fn(),
   getWorkspaceOperatingState: vi.fn(),
   listMembershipsForTokenClaims: vi.fn(),
@@ -109,6 +111,7 @@ describe('defaultModules', () => {
     mocks.deleteSecrets.mockReset();
     mocks.getIntegrationConnectionById.mockReset();
     mocks.getSecret.mockReset();
+    mocks.getSecretsByNamespace.mockReset();
     mocks.getWorkspaceCreator.mockReset();
     mocks.listMembershipsForTokenClaims.mockReset();
     mocks.setSecrets.mockReset();
@@ -123,6 +126,7 @@ describe('defaultModules', () => {
             getAgentToolsContext: vi.fn(),
             listSourceFiles: vi.fn(),
             resolveConnection: vi.fn(),
+            resolveSourceRef: vi.fn(),
             resolveSourceRepository: vi.fn(),
             resolveTriggerReference: vi.fn(),
           }),
@@ -151,6 +155,7 @@ describe('defaultModules', () => {
     });
     mocks.deleteSecrets.mockResolvedValue({deleted: 1});
     mocks.getSecret.mockResolvedValue({value: 'secret'});
+    mocks.getSecretsByNamespace.mockResolvedValue({values: {}});
     mocks.listMembershipsForTokenClaims.mockResolvedValue({memberships: []});
     mocks.getWorkspaceCreator.mockResolvedValue({creatorUserId: null});
     mocks.setSecrets.mockResolvedValue({});
@@ -185,7 +190,7 @@ describe('defaultModules', () => {
         defineInterModulePresentation(secretsInterModuleContract, {
           deleteSecrets: mocks.deleteSecrets,
           getSecret: mocks.getSecret,
-          getSecretsByNamespace: vi.fn(),
+          getSecretsByNamespace: mocks.getSecretsByNamespace,
           getVariablesByNamespace: vi.fn(),
           setSecrets: mocks.setSecrets,
         }),
@@ -193,6 +198,7 @@ describe('defaultModules', () => {
     });
     mocks.createAgentModule.mockReturnValue({
       name: 'agent',
+      database: {db: () => undefined as never, migrationsPath: 'test', databaseNamespace: 'agent'},
       interModulePresentations: [
         {
           contract: agentInterModuleContract,
@@ -222,7 +228,11 @@ describe('defaultModules', () => {
       interModulePresentations: [
         {
           contract: definitionsInterModuleContract,
-          handlers: {getDefinitionForWorkflowRun: vi.fn()},
+          handlers: {
+            getDefinitionForWorkflowRun: vi.fn(),
+            listDefinitionsAtRef: vi.fn(),
+            resolveDefinitionAtRef: vi.fn(),
+          },
         },
       ],
     });
@@ -314,6 +324,129 @@ describe('defaultModules', () => {
     expect(mocks.createAuthModule).toHaveBeenCalledWith({workspaces: expect.any(Object)});
   });
 
+  it('uses the default Agent module factory when none is supplied', async () => {
+    await defaultModules();
+
+    expect(mocks.createAgentModule).toHaveBeenCalledWith({secrets: expect.any(Object)});
+    expect(mocks.createAgentModule.mock.calls[0]?.[0].secrets).not.toHaveProperty('getSecret');
+  });
+
+  it('composes Agent with the shared Secrets client and registers the supplied module', async () => {
+    const customAgentModule = mocks.createAgentModule();
+    mocks.createAgentModule.mockClear();
+    const agentModule = vi.fn<DefaultAgentModuleFactory>(({secrets}) =>
+      mocks.createAgentModule({secrets}),
+    );
+
+    const modules = await defaultModules({agentModule});
+    const agentFactoryCall = agentModule.mock.calls[0];
+    expect(agentFactoryCall).toBeDefined();
+    if (!agentFactoryCall) throw new Error('Agent module factory was not called.');
+    const agentSecrets = agentFactoryCall[0].secrets;
+    const scope = {
+      workspaceId: crypto.randomUUID(),
+      projectId: null,
+      namespace: 'agent',
+    };
+    const secretValues = await agentSecrets.getSecretsByNamespace(scope);
+
+    expect(agentModule).toHaveBeenCalledWith({secrets: expect.any(Object)});
+    expect(secretValues).toEqual({values: {}});
+    expect(mocks.getSecretsByNamespace).toHaveBeenCalledWith(
+      scope,
+      expect.objectContaining({signal: expect.any(AbortSignal)}),
+    );
+    expect(agentSecrets).not.toHaveProperty('getSecret');
+    expect(agentSecrets).not.toHaveProperty('getVariablesByNamespace');
+    expect(mocks.createAgentModule).toHaveBeenCalledWith({secrets: agentSecrets});
+    expect(mocks.createAgentModule).toHaveBeenCalledTimes(1);
+    expect(modules.filter((module) => module.name === 'agent')).toEqual([customAgentModule]);
+    expect(
+      modules
+        .flatMap((module) =>
+          (module.interModulePresentations ?? []).map(({contract}) => contract.module),
+        )
+        .filter((module) => module === agentInterModuleContract.module),
+    ).toEqual([agentInterModuleContract.module]);
+    expect(modules.map((module) => module.name)).toEqual([
+      'email-challenges',
+      'auth',
+      'workspaces',
+      'secrets',
+      'agent',
+      'integrations',
+      'projects',
+      'definitions',
+      'workflows',
+      'annotations',
+      'runners',
+      'logs',
+      'triggers',
+      'dispatcher',
+    ]);
+  });
+
+  it('rejects a custom Agent module without the Agent database namespace', async () => {
+    const customAgentModule = {
+      ...mocks.createAgentModule(),
+      database: {
+        db: () => undefined as never,
+        migrationsPath: 'test',
+        databaseNamespace: 'custom_agent',
+      },
+    };
+
+    await expect(defaultModules({agentModule: () => customAgentModule})).rejects.toThrow(
+      'Custom agentModule must declare database namespace "agent"',
+    );
+  });
+
+  it('rejects a custom Agent module without the canonical Agent presentation', async () => {
+    const customAgentModule = {
+      ...mocks.createAgentModule(),
+      interModulePresentations: [],
+    };
+
+    await expect(defaultModules({agentModule: () => customAgentModule})).rejects.toThrow(
+      'Custom agentModule must present the canonical "agent" inter-module contract',
+    );
+  });
+
+  it('rejects a custom Agent module with a mismatched Agent contract', async () => {
+    const defaultAgentModule = mocks.createAgentModule();
+    const defaultPresentation = defaultAgentModule.interModulePresentations?.[0];
+    if (!defaultPresentation) throw new Error('Default Agent presentation is not configured.');
+    const mismatchedAgentContract = defineInterModuleContract({
+      module: agentInterModuleContract.module,
+      methods: Object.fromEntries(
+        Object.entries(agentInterModuleContract.methods).map(([method, contract]) => [
+          method,
+          {input: contract.input, output: contract.output, errors: contract.errors},
+        ]),
+      ),
+    });
+    const customAgentModule = {
+      ...defaultAgentModule,
+      interModulePresentations: [{...defaultPresentation, contract: mismatchedAgentContract}],
+    };
+
+    await expect(defaultModules({agentModule: () => customAgentModule})).rejects.toThrow(
+      'Custom agentModule must present the canonical "agent" inter-module contract',
+    );
+  });
+
+  it('rejects an extension that duplicates the Agent presentation', async () => {
+    const defaultAgentModule = mocks.createAgentModule();
+    const agentPresentation = defaultAgentModule.interModulePresentations?.[0];
+    if (!agentPresentation) throw new Error('Default Agent presentation is not configured.');
+
+    await expect(
+      defaultModules({
+        extension: () => [{name: 'duplicate-agent', interModulePresentations: [agentPresentation]}],
+      }),
+    ).rejects.toThrow('Module "agent" already has a registered presentation');
+  });
+
   it('composes Auth with the shared Workspaces client and registers the supplied module', async () => {
     const signupPolicy = {isSignupAllowed: vi.fn().mockResolvedValue({allowed: true})};
     const customAuthModule = mocks.createAuthModule();

package/src/modules.ts

@@ -20,7 +20,10 @@ import {projectsInterModuleContract} from '@shipfox/api-projects-dto/inter-modul
 import {createRunnersModule} from '@shipfox/api-runners';
 import {runnersInterModuleContract} from '@shipfox/api-runners-dto/inter-module';
 import {createSecretsModule} from '@shipfox/api-secrets';
-import {secretsInterModuleContract} from '@shipfox/api-secrets-dto/inter-module';
+import {
+  type SecretsInterModuleClient,
+  secretsInterModuleContract,
+} from '@shipfox/api-secrets-dto/inter-module';
 import {createTriggersModule} from '@shipfox/api-triggers';
 import {createWorkflowsModule} from '@shipfox/api-workflows';
 import {workflowsInterModuleContract} from '@shipfox/api-workflows-dto/inter-module';
@@ -41,6 +44,7 @@ import {logger} from '@shipfox/node-opentelemetry';
 export interface DefaultModulesOptions {
   webhookDeliverySource?: WebhookDeliverySource | undefined;
   authModule?: DefaultAuthModuleFactory | undefined;
+  agentModule?: DefaultAgentModuleFactory | undefined;
   runnersModule?: DefaultRunnersModuleFactory | undefined;
   extension?: DefaultModulesExtension | undefined;
 }
@@ -48,6 +52,17 @@ export interface DefaultModulesOptions {
 export type DefaultAuthModuleFactory = (options: {
   workspaces: WorkspacesInterModuleClient;
 }) => ShipfoxModule;
+
+/**
+ * Builds the Agent module in the standard composition slot. The default
+ * factory validates Agent configuration through `createAgentModule`; a custom
+ * factory owns equivalent validation when it does not delegate to that
+ * factory. Custom modules must preserve the `agent` database namespace and
+ * canonical Agent presentation required by the composed clients.
+ */
+export type DefaultAgentModuleFactory = (options: {
+  secrets: Pick<SecretsInterModuleClient, 'deleteSecrets' | 'getSecretsByNamespace' | 'setSecrets'>;
+}) => ShipfoxModule;
 export type DefaultRunnersModuleFactory = (options: {auth: AuthInterModuleClient}) => ShipfoxModule;
 export type DefaultModulesExtension = (options: {
   workspaces: WorkspacesInterModuleClient;
@@ -166,13 +181,17 @@ export async function defaultModules(
     integrations: integrationsClient,
   });
   const extensionModules = options.extension?.({workspaces: workspacesClient}) ?? [];
+  const agentModule = (options.agentModule ?? createAgentModule)({
+    secrets: createAgentSecretsClient(secretsClient),
+  });
+  if (options.agentModule) validateCustomAgentModule(agentModule);
 
   const modules = [
     emailChallengesModule,
     (options.authModule ?? createAuthModule)({workspaces: workspacesClient}),
     createWorkspacesModule({auth: authClient, projects: projectsClient, runners: runnersClient}),
     createSecretsModule(projectsClient),
-    createAgentModule({secrets: secretsClient}),
+    agentModule,
     integrations.module,
     projectsModule,
     definitionsModule,
@@ -201,3 +220,39 @@ export async function defaultModules(
   interModuleTransport.seal();
   return modules;
 }
+
+type AgentModuleSecretsClient = Pick<
+  SecretsInterModuleClient,
+  'deleteSecrets' | 'getSecretsByNamespace' | 'setSecrets'
+>;
+
+function createAgentSecretsClient(
+  secretsClient: SecretsInterModuleClient,
+): AgentModuleSecretsClient {
+  return {
+    deleteSecrets: (input, options) => secretsClient.deleteSecrets(input, options),
+    getSecretsByNamespace: (input, options) => secretsClient.getSecretsByNamespace(input, options),
+    setSecrets: (input, options) => secretsClient.setSecrets(input, options),
+  };
+}
+
+function validateCustomAgentModule(module: ShipfoxModule): void {
+  const databases = module.database
+    ? Array.isArray(module.database)
+      ? module.database
+      : [module.database]
+    : [];
+  if (
+    !databases.some(({databaseNamespace}) => databaseNamespace === agentInterModuleContract.module)
+  ) {
+    throw new Error(
+      'Custom agentModule must declare database namespace "agent" for the Agent module.',
+    );
+  }
+
+  if (
+    !module.interModulePresentations?.some(({contract}) => contract === agentInterModuleContract)
+  ) {
+    throw new Error('Custom agentModule must present the canonical "agent" inter-module contract.');
+  }
+}