@hexabot-ai/api 3.2.2-alpha.1 → 3.2.2-alpha.11

package/src/transfer/adapters/mcp-server-transfer.adapter.ts

@@ -0,0 +1,255 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { isDeepStrictEqual } from 'node:util';
+
+import {
+  type WorkflowExportBundle,
+  type WorkflowExportBundleMcpServer,
+  type WorkflowImportResourceResult,
+} from '@hexabot-ai/types';
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+} from '@nestjs/common';
+import { In } from 'typeorm';
+
+import { CredentialOrmEntity } from '@/user/entities/credential.entity';
+import { McpServerOrmEntity } from '@/workflow/entities/mcp-server.entity';
+import { McpServerService } from '@/workflow/services/mcp-server.service';
+import { McpServerTransport } from '@/workflow/types';
+
+import {
+  WorkflowTransferAdapter,
+  WorkflowTransferExportContext,
+  WorkflowTransferImportContext,
+  WorkflowTransferResourceAdapter,
+} from '../workflow-transfer-resource-adapter';
+import {
+  assertFoundAll,
+  buildPostCreateEvent,
+  buildResourceResult,
+  uniqueResourceIds,
+  type WorkflowTransferImportAdapterResult,
+} from '../workflow-transfer.types';
+
+type McpServerExportResources = {
+  credentialIds: string[];
+  mcpServers: WorkflowExportBundleMcpServer[];
+};
+
+@WorkflowTransferAdapter()
+@Injectable()
+export class McpServerTransferAdapter extends WorkflowTransferResourceAdapter {
+  override readonly kind = 'mcpServer';
+
+  override readonly resourceKeys = ['mcpServers'];
+
+  override readonly dependsOn = ['credential'];
+
+  constructor(private readonly mcpServerService: McpServerService) {
+    super();
+  }
+
+  override async buildExportResources(
+    ctx: WorkflowTransferExportContext,
+  ): Promise<Record<string, WorkflowExportBundleMcpServer[]>> {
+    const resources = await this.buildMcpServerExportResources(
+      ctx.getRefs(this.kind),
+    );
+    ctx.addResourceRefs('credential', resources.credentialIds);
+
+    return {
+      mcpServers: resources.mcpServers,
+    };
+  }
+
+  private async buildMcpServerExportResources(
+    ids: string[],
+  ): Promise<McpServerExportResources> {
+    const uniqueIds = uniqueResourceIds(ids);
+    if (uniqueIds.length === 0) {
+      return { credentialIds: [], mcpServers: [] };
+    }
+
+    const servers = await this.mcpServerService.findAndPopulate({
+      where: { id: In(uniqueIds) },
+    });
+    assertFoundAll(
+      'MCP server',
+      uniqueIds,
+      servers.map((server) => server.id),
+    );
+
+    return {
+      credentialIds: servers
+        .map((server) => server.credential?.id)
+        .filter((id): id is string => typeof id === 'string' && !!id),
+      mcpServers: servers.map((server) => ({
+        exportId: server.id,
+        name: server.name,
+        enabled: server.enabled,
+        transport: server.transport,
+        url: server.url ?? null,
+        command: server.command ?? null,
+        args: server.args ?? null,
+        cwd: server.cwd ?? null,
+        credentialExportId: server.credential?.id ?? null,
+      })),
+    };
+  }
+
+  override async importResources(
+    ctx: WorkflowTransferImportContext,
+  ): Promise<WorkflowTransferImportAdapterResult> {
+    const servers =
+      ctx.getResources<WorkflowExportBundle['resources']['mcpServers'][number]>(
+        'mcpServers',
+      );
+    const credentialIdMap = ctx.getIdMap('credential');
+    const placeholderCredentialExportIds =
+      this.getPlaceholderCredentialExportIds(ctx);
+    const idMap: Record<string, string> = {};
+    const resources: WorkflowImportResourceResult[] = [];
+    const warnings: string[] = [];
+    const postCreateEvents: WorkflowTransferImportAdapterResult['postCreateEvents'] =
+      [];
+
+    for (const server of servers) {
+      const credentialId = server.credentialExportId
+        ? credentialIdMap[server.credentialExportId]
+        : null;
+      const credential = credentialId
+        ? await ctx.manager.findOne(CredentialOrmEntity, {
+            where: { id: credentialId },
+          })
+        : null;
+      const importedCredential = server.credentialExportId
+        ? credentialId
+          ? credential
+          : null
+        : null;
+      const shouldDisable =
+        Boolean(server.credentialExportId) &&
+        placeholderCredentialExportIds.has(server.credentialExportId!);
+      const existing = await ctx.manager.findOne(McpServerOrmEntity, {
+        where: { name: server.name },
+        relations: ['credential'],
+      });
+
+      if (existing) {
+        if (!this.isEquivalentMcpServer(existing, server, importedCredential)) {
+          throw new ConflictException(
+            `MCP server "${server.name}" already exists with different configuration`,
+          );
+        }
+
+        idMap[server.exportId] = existing.id;
+        resources.push(
+          buildResourceResult({
+            kind: 'mcpServer',
+            exportId: server.exportId,
+            localId: existing.id,
+            name: server.name,
+            action: 'reused',
+          }),
+        );
+        continue;
+      }
+
+      if (server.credentialExportId && !credentialId) {
+        throw new BadRequestException(
+          `Workflow bundle is missing credential "${server.credentialExportId}" required by MCP server "${server.name}"`,
+        );
+      }
+
+      const payload = {
+        name: server.name,
+        enabled: shouldDisable ? false : server.enabled,
+        transport: server.transport,
+        url: server.url,
+        command: server.command,
+        args: server.args,
+        cwd: server.cwd,
+        credential:
+          credentialId && server.transport === McpServerTransport.http
+            ? { id: credentialId }
+            : null,
+      };
+      const created = await ctx.manager.save(
+        McpServerOrmEntity,
+        ctx.manager.create(McpServerOrmEntity, payload),
+      );
+
+      idMap[server.exportId] = created.id;
+      resources.push(
+        buildResourceResult({
+          kind: 'mcpServer',
+          exportId: server.exportId,
+          localId: created.id,
+          name: server.name,
+          action: 'created',
+        }),
+      );
+      postCreateEvents.push(
+        buildPostCreateEvent('mcpServer', created, payload),
+      );
+
+      if (shouldDisable) {
+        warnings.push(
+          `MCP server "${server.name}" was disabled because it depends on an imported placeholder credential.`,
+        );
+      }
+    }
+
+    return {
+      idMap,
+      resources,
+      warnings,
+      postCreateEvents,
+    };
+  }
+
+  private getPlaceholderCredentialExportIds(
+    ctx: WorkflowTransferImportContext,
+  ): Set<string> {
+    const placeholderExportIds =
+      ctx.getDependencyResult('credential')?.metadata?.placeholderExportIds;
+    if (placeholderExportIds instanceof Set) {
+      return placeholderExportIds as Set<string>;
+    }
+
+    return Array.isArray(placeholderExportIds)
+      ? new Set(
+          placeholderExportIds.filter(
+            (id): id is string => typeof id === 'string',
+          ),
+        )
+      : new Set<string>();
+  }
+
+  private isEquivalentMcpServer(
+    existing: McpServerOrmEntity,
+    imported: WorkflowExportBundleMcpServer,
+    importedCredential: CredentialOrmEntity | null,
+  ): boolean {
+    const existingCredentialName =
+      existing.credential && typeof existing.credential === 'object'
+        ? existing.credential.name
+        : null;
+    const importedCredentialName = importedCredential?.name ?? null;
+
+    return (
+      existing.transport === imported.transport &&
+      (existing.url ?? null) === (imported.url ?? null) &&
+      (existing.command ?? null) === (imported.command ?? null) &&
+      isDeepStrictEqual(existing.args ?? null, imported.args ?? null) &&
+      (existing.cwd ?? null) === (imported.cwd ?? null) &&
+      existingCredentialName === importedCredentialName
+    );
+  }
+}

package/src/transfer/adapters/memory-definition-transfer.adapter.ts

@@ -0,0 +1,167 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { isDeepStrictEqual } from 'node:util';
+
+import {
+  type WorkflowExportBundle,
+  type WorkflowExportBundleMemoryDefinition,
+  type WorkflowImportResourceResult,
+} from '@hexabot-ai/types';
+import { ConflictException, Injectable } from '@nestjs/common';
+import { In } from 'typeorm';
+
+import { MemoryDefinitionOrmEntity } from '@/workflow/entities/memory-definition.entity';
+import { MemoryDefinitionService } from '@/workflow/services/memory-definition.service';
+
+import {
+  WorkflowTransferAdapter,
+  WorkflowTransferExportContext,
+  WorkflowTransferImportContext,
+  WorkflowTransferResourceAdapter,
+} from '../workflow-transfer-resource-adapter';
+import {
+  assertFoundAll,
+  buildPostCreateEvent,
+  buildResourceResult,
+  uniqueResourceIds,
+  type WorkflowTransferImportAdapterResult,
+} from '../workflow-transfer.types';
+
+@WorkflowTransferAdapter()
+@Injectable()
+export class MemoryDefinitionTransferAdapter extends WorkflowTransferResourceAdapter {
+  override readonly kind = 'memoryDefinition';
+
+  override readonly resourceKeys = ['memoryDefinitions'];
+
+  constructor(
+    private readonly memoryDefinitionService: MemoryDefinitionService,
+  ) {
+    super();
+  }
+
+  override async buildExportResources(
+    ctx: WorkflowTransferExportContext,
+  ): Promise<Record<string, WorkflowExportBundleMemoryDefinition[]>> {
+    return {
+      memoryDefinitions: await this.buildMemoryDefinitionExportResources(
+        ctx.getRefs(this.kind),
+      ),
+    };
+  }
+
+  private async buildMemoryDefinitionExportResources(
+    ids: string[],
+  ): Promise<WorkflowExportBundleMemoryDefinition[]> {
+    const uniqueIds = uniqueResourceIds(ids);
+    if (uniqueIds.length === 0) {
+      return [];
+    }
+
+    const definitions = await this.memoryDefinitionService.find({
+      where: { id: In(uniqueIds) },
+    });
+    assertFoundAll(
+      'memory definition',
+      uniqueIds,
+      definitions.map((definition) => definition.id),
+    );
+
+    return definitions.map((definition) => ({
+      exportId: definition.id,
+      name: definition.name,
+      slug: definition.slug,
+      scope: definition.scope,
+      schema: definition.schema,
+      ttlSeconds: definition.ttlSeconds ?? null,
+    }));
+  }
+
+  override async importResources(
+    ctx: WorkflowTransferImportContext,
+  ): Promise<WorkflowTransferImportAdapterResult> {
+    const definitions =
+      ctx.getResources<
+        WorkflowExportBundle['resources']['memoryDefinitions'][number]
+      >('memoryDefinitions');
+    const idMap: Record<string, string> = {};
+    const resources: WorkflowImportResourceResult[] = [];
+    const postCreateEvents: WorkflowTransferImportAdapterResult['postCreateEvents'] =
+      [];
+
+    for (const definition of definitions) {
+      const existing = await ctx.manager.findOne(MemoryDefinitionOrmEntity, {
+        where: { slug: definition.slug },
+      });
+
+      if (existing) {
+        if (!this.isEquivalentMemoryDefinition(existing, definition)) {
+          throw new ConflictException(
+            `Memory definition "${definition.slug}" already exists with different configuration`,
+          );
+        }
+
+        idMap[definition.exportId] = existing.id;
+        resources.push(
+          buildResourceResult({
+            kind: 'memoryDefinition',
+            exportId: definition.exportId,
+            localId: existing.id,
+            name: definition.name,
+            action: 'reused',
+          }),
+        );
+        continue;
+      }
+
+      const payload = {
+        name: definition.name,
+        slug: definition.slug,
+        scope: definition.scope,
+        schema: definition.schema,
+        ttlSeconds: definition.ttlSeconds ?? null,
+      };
+      const created = await ctx.manager.save(
+        MemoryDefinitionOrmEntity,
+        ctx.manager.create(MemoryDefinitionOrmEntity, payload),
+      );
+
+      idMap[definition.exportId] = created.id;
+      resources.push(
+        buildResourceResult({
+          kind: 'memoryDefinition',
+          exportId: definition.exportId,
+          localId: created.id,
+          name: definition.name,
+          action: 'created',
+        }),
+      );
+      postCreateEvents.push(
+        buildPostCreateEvent('memoryDefinition', created, payload),
+      );
+    }
+
+    return {
+      idMap,
+      resources,
+      warnings: [],
+      postCreateEvents,
+    };
+  }
+
+  private isEquivalentMemoryDefinition(
+    existing: MemoryDefinitionOrmEntity,
+    imported: WorkflowExportBundle['resources']['memoryDefinitions'][number],
+  ): boolean {
+    return (
+      existing.name === imported.name &&
+      existing.scope === imported.scope &&
+      (existing.ttlSeconds ?? null) === (imported.ttlSeconds ?? null) &&
+      isDeepStrictEqual(existing.schema, imported.schema)
+    );
+  }
+}

package/src/transfer/index.ts

@@ -0,0 +1,19 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './workflow-transfer.module';
+
+export * from './workflow-transfer.controller';
+
+export * from './workflow-transfer-definition.service';
+
+export * from './workflow-transfer-resource-adapter';
+
+export * from './workflow-transfer-adapter.registry';
+
+export * from './workflow-transfer.types';
+
+export * from './workflow-transfer.service';

package/src/transfer/workflow-transfer-adapter.registry.ts

@@ -0,0 +1,250 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { WORKFLOW_TRANSFER_RESOURCE_KIND_PATTERN } from '@hexabot-ai/types';
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+
+import {
+  WORKFLOW_TRANSFER_ADAPTER_METADATA_KEY,
+  WorkflowTransferResourceAdapter,
+} from './workflow-transfer-resource-adapter';
+
+type DiscoveredProvider = {
+  instance?: unknown;
+  metatype?: unknown;
+  name?: string;
+};
+
+type VisitState = 'visiting' | 'visited';
+
+@Injectable()
+export class WorkflowTransferAdapterRegistry implements OnModuleInit {
+  private initialized = false;
+
+  private adaptersInDependencyOrder: WorkflowTransferResourceAdapter[] = [];
+
+  private adaptersByKind = new Map<string, WorkflowTransferResourceAdapter>();
+
+  private adaptersByResourceKey = new Map<
+    string,
+    WorkflowTransferResourceAdapter
+  >();
+
+  constructor(private readonly discoveryService: DiscoveryService) {}
+
+  onModuleInit(): void {
+    this.ensureInitialized();
+  }
+
+  listInDependencyOrder(): WorkflowTransferResourceAdapter[] {
+    this.ensureInitialized();
+
+    return [...this.adaptersInDependencyOrder];
+  }
+
+  listInReverseDependencyOrder(): WorkflowTransferResourceAdapter[] {
+    return [...this.listInDependencyOrder()].reverse();
+  }
+
+  get(kind: string): WorkflowTransferResourceAdapter | undefined {
+    this.ensureInitialized();
+
+    return this.adaptersByKind.get(kind);
+  }
+
+  getByResourceKey(key: string): WorkflowTransferResourceAdapter | undefined {
+    this.ensureInitialized();
+
+    return this.adaptersByResourceKey.get(key);
+  }
+
+  getResourceKeys(): string[] {
+    this.ensureInitialized();
+
+    return Array.from(this.adaptersByResourceKey.keys());
+  }
+
+  private ensureInitialized(): void {
+    if (this.initialized) {
+      return;
+    }
+
+    const adapters = this.discoverAdapters();
+    this.adaptersByKind = this.buildKindMap(adapters);
+    this.adaptersByResourceKey = this.buildResourceKeyMap(adapters);
+    this.assertDependenciesExist(adapters);
+    this.adaptersInDependencyOrder = this.sortInDependencyOrder(adapters);
+    this.initialized = true;
+  }
+
+  private discoverAdapters(): WorkflowTransferResourceAdapter[] {
+    return this.discoveryService
+      .getProviders()
+      .flatMap((provider: DiscoveredProvider) => {
+        if (!this.hasAdapterMetadata(provider)) {
+          return [];
+        }
+
+        if (!this.isAdapterInstance(provider.instance)) {
+          throw new Error(
+            `Workflow transfer adapter provider ${
+              provider.name ?? 'unknown'
+            } is missing a valid adapter instance`,
+          );
+        }
+
+        return [provider.instance];
+      });
+  }
+
+  private hasAdapterMetadata(provider: DiscoveredProvider): boolean {
+    const metatype =
+      typeof provider.metatype === 'function' ? provider.metatype : null;
+    const instanceConstructor =
+      provider.instance && typeof provider.instance === 'object'
+        ? provider.instance.constructor
+        : null;
+
+    return [metatype, instanceConstructor].some(
+      (target) =>
+        !!target &&
+        Reflect.getMetadata(WORKFLOW_TRANSFER_ADAPTER_METADATA_KEY, target) ===
+          true,
+    );
+  }
+
+  private isAdapterInstance(
+    value: unknown,
+  ): value is WorkflowTransferResourceAdapter {
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      'kind' in value &&
+      'resourceKeys' in value &&
+      'buildExportResources' in value &&
+      'importResources' in value
+    );
+  }
+
+  private buildKindMap(
+    adapters: WorkflowTransferResourceAdapter[],
+  ): Map<string, WorkflowTransferResourceAdapter> {
+    const adaptersByKind = new Map<string, WorkflowTransferResourceAdapter>();
+
+    for (const adapter of adapters) {
+      this.assertValidName(adapter.kind, 'kind');
+      if (adaptersByKind.has(adapter.kind)) {
+        throw new Error(
+          `Duplicate workflow transfer adapter kind "${adapter.kind}"`,
+        );
+      }
+
+      adaptersByKind.set(adapter.kind, adapter);
+    }
+
+    return adaptersByKind;
+  }
+
+  private buildResourceKeyMap(
+    adapters: WorkflowTransferResourceAdapter[],
+  ): Map<string, WorkflowTransferResourceAdapter> {
+    const adaptersByResourceKey = new Map<
+      string,
+      WorkflowTransferResourceAdapter
+    >();
+
+    for (const adapter of adapters) {
+      if (adapter.resourceKeys.length === 0) {
+        throw new Error(
+          `Workflow transfer adapter "${adapter.kind}" must declare at least one resource key`,
+        );
+      }
+
+      for (const resourceKey of adapter.resourceKeys) {
+        this.assertValidName(resourceKey, 'resource key');
+        if (adaptersByResourceKey.has(resourceKey)) {
+          throw new Error(
+            `Duplicate workflow transfer resource key "${resourceKey}"`,
+          );
+        }
+
+        adaptersByResourceKey.set(resourceKey, adapter);
+      }
+    }
+
+    return adaptersByResourceKey;
+  }
+
+  private assertDependenciesExist(
+    adapters: WorkflowTransferResourceAdapter[],
+  ): void {
+    for (const adapter of adapters) {
+      for (const dependency of adapter.dependsOn) {
+        this.assertValidName(dependency, 'dependency');
+        if (!this.adaptersByKind.has(dependency)) {
+          throw new Error(
+            `Workflow transfer adapter "${adapter.kind}" depends on unknown adapter "${dependency}"`,
+          );
+        }
+      }
+    }
+  }
+
+  private sortInDependencyOrder(
+    adapters: WorkflowTransferResourceAdapter[],
+  ): WorkflowTransferResourceAdapter[] {
+    const ordered: WorkflowTransferResourceAdapter[] = [];
+    const stateByKind = new Map<string, VisitState>();
+
+    for (const adapter of adapters) {
+      this.visitAdapter(adapter, [], stateByKind, ordered);
+    }
+
+    return ordered;
+  }
+
+  private visitAdapter(
+    adapter: WorkflowTransferResourceAdapter,
+    path: string[],
+    stateByKind: Map<string, VisitState>,
+    ordered: WorkflowTransferResourceAdapter[],
+  ): void {
+    const state = stateByKind.get(adapter.kind);
+    if (state === 'visited') {
+      return;
+    }
+
+    if (state === 'visiting') {
+      const cycleStart = path.indexOf(adapter.kind);
+      const cyclePath = [
+        ...(cycleStart >= 0 ? path.slice(cycleStart) : path),
+        adapter.kind,
+      ];
+      throw new Error(
+        `Workflow transfer adapter dependency cycle: ${cyclePath.join(' -> ')}`,
+      );
+    }
+
+    stateByKind.set(adapter.kind, 'visiting');
+    for (const dependency of adapter.dependsOn) {
+      this.visitAdapter(
+        this.adaptersByKind.get(dependency)!,
+        [...path, adapter.kind],
+        stateByKind,
+        ordered,
+      );
+    }
+    stateByKind.set(adapter.kind, 'visited');
+    ordered.push(adapter);
+  }
+
+  private assertValidName(value: string, label: string): void {
+    if (!WORKFLOW_TRANSFER_RESOURCE_KIND_PATTERN.test(value)) {
+      throw new Error(`Invalid workflow transfer adapter ${label} "${value}"`);
+    }
+  }
+}