feat(metadata): implement publishPackage, revertPackage, getPublished in MetadataManager with tests

Copilot · hotlong · Copilot · commit 1af324736fa7 · 2026-02-27T06:24:59.000Z
Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/metadata/src/metadata-manager.ts b/packages/metadata/src/metadata-manager.ts
@@ -15,6 +15,7 @@ import type {
   MetadataSaveResult,
   MetadataWatchEvent,
   MetadataFormat,
+  PackagePublishResult,
 } from '@objectstack/spec/system';
 import type {
   IMetadataService,
@@ -333,6 +334,155 @@ export class MetadataManager implements IMetadataService {
     }
   }
 
+  /**
+   * Publish an entire package:
+   * 1. Validate all draft items
+   * 2. Snapshot all items in the package (publishedDefinition = clone(metadata))
+   * 3. Increment version
+   * 4. Set all items state → active
+   */
+  async publishPackage(packageId: string, options?: {
+    changeNote?: string;
+    publishedBy?: string;
+    validate?: boolean;
+  }): Promise<PackagePublishResult> {
+    const now = new Date().toISOString();
+    const shouldValidate = options?.validate !== false;
+    const publishedBy = options?.publishedBy;
+
+    // Collect all items belonging to this package
+    const packageItems: Array<{ type: string; name: string; data: any }> = [];
+    for (const [type, typeStore] of this.registry) {
+      for (const [name, data] of typeStore) {
+        const meta = data as any;
+        if (meta?.packageId === packageId || meta?.package === packageId) {
+          packageItems.push({ type, name, data: meta });
+        }
+      }
+    }
+
+    if (packageItems.length === 0) {
+      return {
+        success: false,
+        packageId,
+        version: 0,
+        publishedAt: now,
+        itemsPublished: 0,
+        validationErrors: [{ type: '', name: '', message: `No metadata items found for package '${packageId}'` }],
+      };
+    }
+
+    // Validation pass
+    if (shouldValidate) {
+      const validationErrors: Array<{ type: string; name: string; message: string }> = [];
+      for (const item of packageItems) {
+        const result = await this.validate(item.type, item.data);
+        if (!result.valid && result.errors) {
+          for (const err of result.errors) {
+            validationErrors.push({
+              type: item.type,
+              name: item.name,
+              message: err.message,
+            });
+          }
+        }
+      }
+      if (validationErrors.length > 0) {
+        return {
+          success: false,
+          packageId,
+          version: 0,
+          publishedAt: now,
+          itemsPublished: 0,
+          validationErrors,
+        };
+      }
+    }
+
+    // Determine the next version by finding the max current version across items
+    let maxVersion = 0;
+    for (const item of packageItems) {
+      const v = typeof item.data.version === 'number' ? item.data.version : 0;
+      if (v > maxVersion) maxVersion = v;
+    }
+    const newVersion = maxVersion + 1;
+
+    // Snapshot and update all items
+    for (const item of packageItems) {
+      const updated = {
+        ...item.data,
+        publishedDefinition: JSON.parse(JSON.stringify(item.data.metadata ?? item.data)),
+        publishedAt: now,
+        publishedBy: publishedBy ?? item.data.publishedBy,
+        version: newVersion,
+        state: 'active',
+      };
+      await this.register(item.type, item.name, updated);
+    }
+
+    return {
+      success: true,
+      packageId,
+      version: newVersion,
+      publishedAt: now,
+      itemsPublished: packageItems.length,
+    };
+  }
+
+  /**
+   * Revert entire package to last published state.
+   * Restores all metadata definitions from their published snapshots.
+   */
+  async revertPackage(packageId: string): Promise<void> {
+    const packageItems: Array<{ type: string; name: string; data: any }> = [];
+    for (const [type, typeStore] of this.registry) {
+      for (const [name, data] of typeStore) {
+        const meta = data as any;
+        if (meta?.packageId === packageId || meta?.package === packageId) {
+          packageItems.push({ type, name, data: meta });
+        }
+      }
+    }
+
+    if (packageItems.length === 0) {
+      throw new Error(`No metadata items found for package '${packageId}'`);
+    }
+
+    // Check that at least one item has a published snapshot
+    const hasPublished = packageItems.some(item => item.data.publishedDefinition !== undefined);
+    if (!hasPublished) {
+      throw new Error(`Package '${packageId}' has never been published`);
+    }
+
+    for (const item of packageItems) {
+      if (item.data.publishedDefinition !== undefined) {
+        const reverted = {
+          ...item.data,
+          metadata: JSON.parse(JSON.stringify(item.data.publishedDefinition)),
+          state: 'active',
+        };
+        await this.register(item.type, item.name, reverted);
+      }
+    }
+  }
+
+  /**
+   * Get the published version of any metadata item (for runtime serving).
+   * Returns publishedDefinition if exists, else current definition.
+   */
+  async getPublished(type: string, name: string): Promise<unknown | undefined> {
+    const item = await this.get(type, name);
+    if (!item) return undefined;
+
+    const meta = item as any;
+    if (meta.publishedDefinition !== undefined) {
+      return meta.publishedDefinition;
+    }
+
+    // Fall back to current definition (metadata field or the item itself)
+    return meta.metadata ?? item;
+  }
+
   // ==========================================
   // Query / Search
   // ==========================================
diff --git a/packages/metadata/src/metadata-service.test.ts b/packages/metadata/src/metadata-service.test.ts
@@ -693,4 +693,201 @@ describe('MetadataManager — IMetadataService Contract', () => {
       return deps.then(result => expect(result).toHaveLength(1));
     });
   });
+
+  // ==========================================
+  // Package Publish / Revert / getPublished
+  // ==========================================
+
+  describe('publishPackage', () => {
+    it('should publish all items in a package', async () => {
+      await manager.register('object', 'opportunity', {
+        name: 'opportunity', label: 'Opportunity', packageId: 'com.acme.crm', state: 'draft',
+        metadata: { fields: ['name', 'amount'] },
+      });
+      await manager.register('view', 'opp_list', {
+        name: 'opp_list', label: 'Opp List', packageId: 'com.acme.crm', state: 'draft',
+        metadata: { columns: ['name', 'amount'] },
+      });
+
+      const result = await manager.publishPackage('com.acme.crm', { publishedBy: 'admin' });
+
+      expect(result.success).toBe(true);
+      expect(result.packageId).toBe('com.acme.crm');
+      expect(result.version).toBe(1);
+      expect(result.itemsPublished).toBe(2);
+      expect(result.publishedAt).toBeDefined();
+
+      // Verify items are now active with published snapshots
+      const obj = await manager.get('object', 'opportunity') as any;
+      expect(obj.state).toBe('active');
+      expect(obj.publishedDefinition).toBeDefined();
+      expect(obj.publishedBy).toBe('admin');
+      expect(obj.publishedAt).toBeDefined();
+
+      const view = await manager.get('view', 'opp_list') as any;
+      expect(view.state).toBe('active');
+      expect(view.publishedDefinition).toBeDefined();
+    });
+
+    it('should increment version on each publish', async () => {
+      await manager.register('object', 'account', {
+        name: 'account', packageId: 'crm', state: 'draft', version: 0,
+        metadata: { fields: ['name'] },
+      });
+
+      const first = await manager.publishPackage('crm');
+      expect(first.version).toBe(1);
+
+      const second = await manager.publishPackage('crm');
+      expect(second.version).toBe(2);
+    });
+
+    it('should fail for empty package', async () => {
+      const result = await manager.publishPackage('nonexistent');
+      expect(result.success).toBe(false);
+      expect(result.itemsPublished).toBe(0);
+      expect(result.validationErrors).toBeDefined();
+    });
+
+    it('should fail validation when items are invalid', async () => {
+      // Register an item without a name (will fail validate)
+      await manager.register('object', 'bad_item', {
+        packageId: 'com.acme.bad', state: 'draft',
+        metadata: {},
+      });
+
+      const result = await manager.publishPackage('com.acme.bad', { validate: true });
+      expect(result.success).toBe(false);
+      expect(result.validationErrors).toBeDefined();
+      expect(result.validationErrors!.length).toBeGreaterThan(0);
+    });
+
+    it('should skip validation when validate=false', async () => {
+      await manager.register('object', 'skip_val', {
+        packageId: 'com.acme.skip', state: 'draft',
+        metadata: {},
+      });
+
+      const result = await manager.publishPackage('com.acme.skip', { validate: false });
+      expect(result.success).toBe(true);
+      expect(result.itemsPublished).toBe(1);
+    });
+  });
+
+  describe('revertPackage', () => {
+    it('should revert to last published state', async () => {
+      // Register and publish
+      await manager.register('object', 'account', {
+        name: 'account', label: 'Account', packageId: 'crm',
+        metadata: { fields: ['name', 'email'] },
+      });
+      await manager.publishPackage('crm');
+
+      // Make edits after publish
+      const item = await manager.get('object', 'account') as any;
+      await manager.register('object', 'account', {
+        ...item,
+        metadata: { fields: ['name', 'email', 'phone'] },
+        state: 'draft',
+      });
+
+      // Verify edit was saved
+      const edited = await manager.get('object', 'account') as any;
+      expect(edited.metadata.fields).toContain('phone');
+
+      // Revert
+      await manager.revertPackage('crm');
+
+      // Verify reverted to published state
+      const reverted = await manager.get('object', 'account') as any;
+      expect(reverted.state).toBe('active');
+      expect(reverted.metadata).toEqual(reverted.publishedDefinition);
+    });
+
+    it('should throw for non-existent package', async () => {
+      await expect(manager.revertPackage('nonexistent')).rejects.toThrow('No metadata items found');
+    });
+
+    it('should throw for never-published package', async () => {
+      await manager.register('object', 'new_item', {
+        name: 'new_item', packageId: 'com.acme.new',
+      });
+
+      await expect(manager.revertPackage('com.acme.new')).rejects.toThrow('has never been published');
+    });
+  });
+
+  describe('getPublished', () => {
+    it('should return published definition when available', async () => {
+      await manager.register('object', 'account', {
+        name: 'account', label: 'Account', packageId: 'crm',
+        metadata: { fields: ['name'] },
+      });
+      await manager.publishPackage('crm');
+
+      // Edit after publish
+      const item = await manager.get('object', 'account') as any;
+      await manager.register('object', 'account', {
+        ...item,
+        metadata: { fields: ['name', 'email', 'phone'] },
+      });
+
+      // getPublished should return the published snapshot, not the edited version
+      const published = await manager.getPublished('object', 'account');
+      expect(published).toBeDefined();
+      // The published snapshot was taken from the original metadata
+      const pubAny = published as any;
+      expect(pubAny.fields).toBeDefined();
+    });
+
+    it('should return current definition when never published', async () => {
+      await manager.register('object', 'contact', {
+        name: 'contact', label: 'Contact',
+        metadata: { fields: ['first_name'] },
+      });
+
+      const published = await manager.getPublished('object', 'contact');
+      expect(published).toBeDefined();
+      // Falls back to metadata field
+      expect((published as any).fields).toEqual(['first_name']);
+    });
+
+    it('should return undefined for non-existent item', async () => {
+      const result = await manager.getPublished('object', 'nonexistent');
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('integration: edit → publish → edit → revert', () => {
+    it('should preserve published version through edit-revert cycle', async () => {
+      // Step 1: Initial setup
+      await manager.register('object', 'project', {
+        name: 'project', label: 'Project', packageId: 'pm',
+        metadata: { fields: ['name', 'status'] },
+      });
+
+      // Step 2: Publish v1
+      const v1 = await manager.publishPackage('pm', { publishedBy: 'admin' });
+      expect(v1.success).toBe(true);
+      expect(v1.version).toBe(1);
+
+      // Step 3: Edit after publish
+      const item = await manager.get('object', 'project') as any;
+      await manager.register('object', 'project', {
+        ...item,
+        metadata: { fields: ['name', 'status', 'priority'] },
+        state: 'draft',
+      });
+
+      // Step 4: End user sees published version
+      const endUserView = await manager.getPublished('object', 'project') as any;
+      expect(endUserView.fields).toEqual(['name', 'status']);
+
+      // Step 5: Revert discards draft changes
+      await manager.revertPackage('pm');
+      const reverted = await manager.get('object', 'project') as any;
+      expect(reverted.state).toBe('active');
+      expect(reverted.metadata.fields).toEqual(['name', 'status']);
+    });
+  });
 });
