@axiom-lattice/gateway 2.1.112 → 2.1.113

package/src/services/ExportImportService.ts

@@ -0,0 +1,296 @@
+/**
+ * Core orchestration service for tenant configuration export and import.
+ *
+ * @module @axiom-lattice/gateway/services/ExportImportService
+ */
+
+import { ExportableEntityRegistry, DependencyResolver, IdRemapper } from '@axiom-lattice/core';
+import type {
+  ExportBundle,
+  ExportableEntity,
+  ImportPreviewResult,
+  Resolution,
+  ImportApplyResult,
+  ImportEntityResult,
+} from '@axiom-lattice/core';
+import { randomUUID } from 'crypto';
+
+interface JobEntry {
+  bundle: ExportBundle;
+  tenantId: string;
+  createdAt: number;
+}
+
+/** Ephemeral in-memory job store (jobs expire after TTL). */
+const exportJobs = new Map<string, JobEntry>();
+
+/** TTL: 1 hour */
+const JOB_TTL_MS = 60 * 60 * 1000;
+
+function cleanExpiredJobs(): void {
+  const now = Date.now();
+  for (const [id, entry] of exportJobs) {
+    if (now - entry.createdAt > JOB_TTL_MS) {
+      exportJobs.delete(id);
+    }
+  }
+}
+
+export class ExportImportService {
+  private registry = ExportableEntityRegistry.getInstance();
+
+  /**
+   * Preview an export: check which types would be auto-included, which dependencies are missing.
+   */
+  async exportPreview(
+    tenantId: string,
+    selectedTypes: string[],
+  ): Promise<{ missingDependencies: string[]; cascadeAdditions: string[] }> {
+    const allDefs = this.registry.getAll();
+
+    const expanded = DependencyResolver.expandCascade(allDefs, selectedTypes);
+    const cascadeAdditions = expanded.filter((t) => !selectedTypes.includes(t));
+
+    const deps = DependencyResolver.computeDependencies(allDefs, expanded);
+    const registeredTypes = new Set(allDefs.map((d) => d.entityType));
+    const missingDependencies = deps.missing.filter((t) => registeredTypes.has(t));
+
+    return { missingDependencies, cascadeAdditions };
+  }
+
+  /**
+   * Generate a full ExportBundle for the given tenant and entity types.
+   * Stores the bundle in-memory and returns a jobId for download.
+   */
+  async export(
+    tenantId: string,
+    entityTypes: string[],
+    entityIds?: Record<string, string[]>,
+  ): Promise<{ jobId: string; bundle: ExportBundle }> {
+    const allDefs = this.registry.getAll();
+    const expanded = DependencyResolver.expandCascade(allDefs, entityTypes);
+    const finalTypes = [...new Set([...expanded, ...entityTypes])];
+
+    const dependencyOrder = DependencyResolver.resolveOrder(
+      finalTypes.map((t) => this.registry.get(t)),
+    );
+
+    const entities: Record<string, ExportableEntity[]> = {};
+    let exportCounter = 0;
+
+    for (const type of dependencyOrder) {
+      const def = this.registry.get(type);
+      let raw = await def.listForExport(tenantId);
+
+      if (entityIds && entityIds[type] && entityIds[type].length > 0) {
+        const idSet = new Set(entityIds[type]);
+        raw = raw.filter((e) => idSet.has(e.data.id as string));
+      }
+
+      entities[type] = raw.map((e) => ({
+        ...e,
+        _exportId: `exp-${type}-${String(++exportCounter).padStart(3, '0')}`,
+        data: this.sanitizeEntityData(e.data),
+      }));
+    }
+
+    // Build reverse map: raw entity ID → _exportId
+    const rawIdToExportId = new Map<string, string>();
+    for (const [, entityList] of Object.entries(entities)) {
+      for (const entity of entityList) {
+        const rawId = entity.data.id as string;
+        if (rawId) {
+          rawIdToExportId.set(rawId, entity._exportId);
+        }
+      }
+    }
+
+    // Rewrite reference fields to @type/exportId format
+    for (const [type, entityList] of Object.entries(entities)) {
+      const def = this.registry.get(type);
+      const refFields = def.referenceFields || {};
+      for (const entity of entityList) {
+        for (const [fieldName, refEntityType] of Object.entries(refFields)) {
+          const rawValue = entity.data[fieldName];
+          if (typeof rawValue === 'string' && rawValue) {
+            const exportId = rawIdToExportId.get(rawValue);
+            if (exportId) {
+              entity.data[fieldName] = `@${refEntityType}/${exportId}`;
+            }
+          }
+        }
+      }
+    }
+
+    const bundle: ExportBundle = {
+      version: 1,
+      exportedAt: new Date().toISOString(),
+      sourceTenantId: tenantId,
+      entities,
+      dependencyOrder,
+      _warning: 'This file contains plaintext secrets (passwords, API keys, tokens). Store it securely and delete after import.',
+    };
+
+    const jobId = randomUUID();
+    exportJobs.set(jobId, { bundle, tenantId, createdAt: Date.now() });
+
+    return { jobId, bundle };
+  }
+
+  /**
+   * Retrieve a previously generated export bundle by jobId with tenant validation.
+   */
+  getExportJob(jobId: string, tenantId: string): ExportBundle | undefined {
+    cleanExpiredJobs();
+    const entry = exportJobs.get(jobId);
+    if (!entry || entry.tenantId !== tenantId) return undefined;
+    return entry.bundle;
+  }
+
+  /**
+   * Preview import: validate bundle and detect conflicts.
+   */
+  async previewImport(
+    tenantId: string,
+    bundle: ExportBundle,
+  ): Promise<ImportPreviewResult> {
+    this.validateBundle(bundle);
+
+    const allConflicts: ImportPreviewResult['conflicts'] = [];
+    const allInsertions: ImportPreviewResult['insertions'] = [];
+    const allErrors: ImportPreviewResult['errors'] = [];
+
+    for (const [entityType, entities] of Object.entries(bundle.entities)) {
+      if (entities.length === 0) continue;
+
+      try {
+        const def = this.registry.get(entityType);
+        const result = await def.previewImport(tenantId, entities);
+
+        allConflicts.push(...result.conflicts);
+        allInsertions.push(...result.insertions);
+        allErrors.push(...result.errors);
+      } catch (err) {
+        for (const entity of entities) {
+          allErrors.push({
+            _exportId: entity._exportId,
+            entityType,
+            error: `Preview failed: ${(err as Error).message}`,
+          });
+        }
+      }
+    }
+
+    return { conflicts: allConflicts, insertions: allInsertions, errors: allErrors };
+  }
+
+  /**
+   * Apply import: create entities in dependency order with ID remapping.
+   */
+  async applyImport(
+    tenantId: string,
+    bundle: ExportBundle,
+    resolutions: Record<string, Resolution>,
+  ): Promise<ImportApplyResult> {
+    this.validateBundle(bundle);
+
+    const results: ImportEntityResult[] = [];
+    const idMap: Record<string, string> = {};
+    // Track skill old id → new id for agent graphDefinition implicit refs
+    const skillIdRemap: Record<string, string> = {};
+
+    for (const entityType of bundle.dependencyOrder) {
+      const entities = bundle.entities[entityType];
+      if (!entities || entities.length === 0) continue;
+
+      const def = this.registry.get(entityType);
+      const remapper = new IdRemapper(idMap);
+
+      for (const entity of entities) {
+        const resolution = resolutions[entity._exportId];
+
+        if (resolution?.action === 'skip') {
+          results.push({ _exportId: entity._exportId, entityType, status: 'skipped' });
+          continue;
+        }
+
+        try {
+          const remappedData = remapper.remapReferences(entity.data) as Record<string, unknown>;
+
+          // Remap implicit skill references in agent graphDefinition.skillIds
+          if (entityType === 'agent' && Object.keys(skillIdRemap).length > 0) {
+            const skillRemapper = new IdRemapper({});
+            remappedData.graphDefinition = skillRemapper.remapSkillIds(
+              (remappedData.graphDefinition as Record<string, unknown>) || {},
+              skillIdRemap,
+            );
+          }
+
+          if (resolution?.action === 'rename' && resolution.newId) {
+            remappedData.id = resolution.newId;
+          }
+
+          const entityWithRemappedData = { ...entity, data: remappedData };
+          const { newId } = await def.applyImport(
+            tenantId,
+            entityWithRemappedData,
+            resolution ?? { _exportId: entity._exportId, action: 'overwrite' },
+          );
+
+          if (newId) {
+            idMap[entity._exportId] = newId;
+            // Track skill ID renames for agent graphDefinition remapping
+            if (entityType === 'skill' && newId) {
+              const oldSkillId = remappedData.id as string;
+              if (oldSkillId !== newId) {
+                skillIdRemap[oldSkillId] = newId;
+              }
+            }
+            results.push({
+              _exportId: entity._exportId,
+              entityType,
+              status: resolution?.action === 'overwrite' ? 'updated' : 'created',
+              newId,
+            });
+          }
+        } catch (err) {
+          results.push({
+            _exportId: entity._exportId,
+            entityType,
+            status: 'failed',
+            error: (err as Error).message,
+          });
+        }
+      }
+    }
+
+    return { results, idMap };
+  }
+
+  /**
+   * List all registered exportable types (for frontend).
+   */
+  listExportableTypes() {
+    return this.registry.listTypes();
+  }
+
+  private validateBundle(bundle: ExportBundle): void {
+    if (bundle.version !== 1) {
+      throw new Error(`Unsupported bundle version: ${bundle.version}. Expected: 1`);
+    }
+    if (!bundle.entities || typeof bundle.entities !== 'object') {
+      throw new Error('Invalid bundle: missing entities');
+    }
+    if (!Array.isArray(bundle.dependencyOrder)) {
+      throw new Error('Invalid bundle: missing dependencyOrder');
+    }
+  }
+
+  private sanitizeEntityData(data: Record<string, unknown>): Record<string, unknown> {
+    const sanitized = { ...data };
+    delete sanitized.tenantId;
+    delete sanitized.createdAt;
+    delete sanitized.updatedAt;
+    return sanitized;
+  }
+}

package/src/services/__tests__/ExportImportService.test.ts

@@ -0,0 +1,130 @@
+import { ExportImportService } from '../ExportImportService';
+import { ExportableEntityRegistry } from '@axiom-lattice/core';
+import type { ExportableEntityDefinition, ExportableEntity } from '@axiom-lattice/core';
+
+function makeDef(
+  entityType: string,
+  entities: ExportableEntity[] = [],
+  dependsOn: string[] = [],
+): ExportableEntityDefinition {
+  return {
+    entityType,
+    label: entityType,
+    category: 'core',
+    dependsOn,
+    cascadeParents: [],
+    listForExport: jest.fn().mockResolvedValue(entities),
+    previewImport: jest.fn().mockResolvedValue({ conflicts: [], insertions: [], errors: [] }),
+    applyImport: jest.fn().mockResolvedValue({ newId: 'new-id' }),
+  };
+}
+
+describe('ExportImportService', () => {
+  beforeEach(() => {
+    (ExportableEntityRegistry as any).instance = undefined;
+    const registry = ExportableEntityRegistry.getInstance();
+    const s1 = { _exportId: '', data: { id: 's1', name: 'Skill 1' } };
+    const s2 = { _exportId: '', data: { id: 's2', name: 'Skill 2' } };
+    registry.register(makeDef('skill', [s1, s2]));
+    registry.register(makeDef('agent', [], ['skill']));
+    registry.register(makeDef('binding', [], ['agent']));
+  });
+
+  it('generates a valid ExportBundle', async () => {
+    const svc = new ExportImportService();
+    const { bundle } = await svc.export('tenant-1', ['skill']);
+
+    expect(bundle.version).toBe(1);
+    expect(bundle.sourceTenantId).toBe('tenant-1');
+    expect(bundle.entities.skill).toHaveLength(2);
+    expect(bundle.entities.skill[0]._exportId).toMatch(/^exp-skill-0/);
+    expect(bundle.entities.skill[0].data.id).toBe('s1');
+    expect(bundle.entities.skill[0].data).not.toHaveProperty('tenantId');
+    expect(bundle.entities.skill[0].data).not.toHaveProperty('createdAt');
+    expect(bundle.entities.skill[0].data).not.toHaveProperty('updatedAt');
+    expect(bundle.dependencyOrder).toEqual(['skill']);
+  });
+
+  it('filters entities by entityIds', async () => {
+    const svc = new ExportImportService();
+    const { bundle } = await svc.export('tenant-1', ['skill'], { skill: ['s1'] });
+    expect(bundle.entities.skill).toHaveLength(1);
+    expect(bundle.entities.skill[0].data.id).toBe('s1');
+  });
+
+  it('exportPreview detects missing dependencies', async () => {
+    const svc = new ExportImportService();
+    const result = await svc.exportPreview('tenant-1', ['agent']);
+    expect(result.missingDependencies).toContain('skill');
+    expect(result.cascadeAdditions).toEqual([]);
+  });
+
+  it('export includes transitive deps when explicitly requested', async () => {
+    const svc = new ExportImportService();
+    const { bundle } = await svc.export('tenant-1', ['skill', 'agent']);
+    expect(bundle.dependencyOrder).toContain('skill');
+    expect(bundle.dependencyOrder).toContain('agent');
+    expect(bundle.dependencyOrder.indexOf('skill')).toBeLessThan(bundle.dependencyOrder.indexOf('agent'));
+  });
+
+  it('previewImport returns insertions for new entities', async () => {
+    const svc = new ExportImportService();
+    const bundle = {
+      version: 1 as const,
+      exportedAt: new Date().toISOString(),
+      sourceTenantId: 't1',
+      entities: {
+        skill: [{ _exportId: 'exp-s-1', data: { id: 's1', name: 'Skill' } }],
+      },
+      dependencyOrder: ['skill'],
+    };
+
+    await svc.previewImport('tenant-2', bundle);
+    const registry = ExportableEntityRegistry.getInstance();
+    expect(registry.get('skill').previewImport).toHaveBeenCalled();
+  });
+
+  it('throws on invalid bundle version', async () => {
+    const svc = new ExportImportService();
+    await expect(
+      svc.previewImport('tenant-2', {
+        version: 99 as any,
+        entities: {},
+        dependencyOrder: [],
+        exportedAt: '',
+        sourceTenantId: '',
+      }),
+    ).rejects.toThrow(/version/);
+  });
+
+  it('throws on missing entities field', async () => {
+    const svc = new ExportImportService();
+    await expect(
+      svc.previewImport('tenant-2', {
+        version: 1,
+        exportedAt: '',
+        sourceTenantId: '',
+        dependencyOrder: [],
+      } as any),
+    ).rejects.toThrow(/entities/);
+  });
+
+  it('getExportJob returns undefined for unknown jobId', () => {
+    const svc = new ExportImportService();
+    expect(svc.getExportJob('nonexistent', 'tenant-1')).toBeUndefined();
+  });
+
+  it('getExportJob returns bundle after export', async () => {
+    const svc = new ExportImportService();
+    const { jobId, bundle } = await svc.export('tenant-1', ['skill']);
+    const retrieved = svc.getExportJob(jobId, 'tenant-1');
+    expect(retrieved).toEqual(bundle);
+  });
+
+  it('listExportableTypes returns registered types', () => {
+    const svc = new ExportImportService();
+    const types = svc.listExportableTypes();
+    expect(types).toHaveLength(3);
+    expect(types.map((t) => t.entityType)).toEqual(['skill', 'agent', 'binding']);
+  });
+});