@objectstack/metadata 3.0.11 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/metadata",
-  "version": "3.0.11",
+  "version": "3.1.0",
   "license": "Apache-2.0",
   "description": "Metadata loading, saving, and persistence for ObjectStack",
   "main": "src/index.ts",
@@ -29,9 +29,9 @@
     "js-yaml": "^4.1.0",
     "chokidar": "^5.0.0",
     "zod": "^4.3.6",
-    "@objectstack/core": "3.0.11",
-    "@objectstack/spec": "3.0.11",
-    "@objectstack/types": "3.0.11"
+    "@objectstack/core": "3.1.0",
+    "@objectstack/types": "3.1.0",
+    "@objectstack/spec": "3.1.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/metadata-manager.ts

@@ -15,6 +15,7 @@ import type {
   MetadataSaveResult,
   MetadataWatchEvent,
   MetadataFormat,
+  PackagePublishResult,
 } from '@objectstack/spec/system';
 import type {
   IMetadataService,
@@ -333,6 +334,187 @@ 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 }> = [];
+
+      // Schema validation
+      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,
+            });
+          }
+        }
+      }
+
+      // Dependency validation: referenced items must be in the same package or already published
+      const packageItemKeys = new Set(packageItems.map(i => `${i.type}:${i.name}`));
+      for (const item of packageItems) {
+        const deps = await this.getDependencies(item.type, item.name);
+        for (const dep of deps) {
+          const depKey = `${dep.targetType}:${dep.targetName}`;
+          // Skip if the dependency is within this package
+          if (packageItemKeys.has(depKey)) continue;
+          // Check if the dependency exists and has been published
+          const depItem = await this.get(dep.targetType, dep.targetName);
+          if (!depItem) {
+            validationErrors.push({
+              type: item.type,
+              name: item.name,
+              message: `Dependency '${dep.targetType}:${dep.targetName}' not found`,
+            });
+          } else {
+            const depMeta = depItem as any;
+            if (depMeta.publishedDefinition === undefined && depMeta.state !== 'active') {
+              validationErrors.push({
+                type: item.type,
+                name: item.name,
+                message: `Dependency '${dep.targetType}:${dep.targetName}' is not published`,
+              });
+            }
+          }
+        }
+      }
+
+      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: structuredClone(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: structuredClone(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
   // ==========================================

package/src/metadata-service.test.ts

@@ -693,4 +693,273 @@ 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);
+    });
+
+    it('should fail when dependency is not found or not published', async () => {
+      await manager.register('view', 'opp_list', {
+        name: 'opp_list', label: 'Opp List', packageId: 'com.acme.dep',
+        metadata: { columns: ['name'] },
+      });
+
+      // Register a dependency pointing to a non-existent item
+      manager.addDependency({
+        sourceType: 'view',
+        sourceName: 'opp_list',
+        targetType: 'object',
+        targetName: 'opportunity',
+        kind: 'reference',
+      });
+
+      const result = await manager.publishPackage('com.acme.dep', { validate: true });
+      expect(result.success).toBe(false);
+      expect(result.validationErrors).toBeDefined();
+      expect(result.validationErrors!.some(e => e.message.includes('opportunity'))).toBe(true);
+    });
+
+    it('should pass dependency check when target is in the same package', async () => {
+      await manager.register('object', 'project', {
+        name: 'project', label: 'Project', packageId: 'com.acme.same',
+        metadata: { fields: ['name'] },
+      });
+      await manager.register('view', 'project_list', {
+        name: 'project_list', label: 'Project List', packageId: 'com.acme.same',
+        metadata: { columns: ['name'] },
+      });
+
+      // Dependency within the same package
+      manager.addDependency({
+        sourceType: 'view',
+        sourceName: 'project_list',
+        targetType: 'object',
+        targetName: 'project',
+        kind: 'reference',
+      });
+
+      const result = await manager.publishPackage('com.acme.same', { validate: true });
+      expect(result.success).toBe(true);
+      expect(result.itemsPublished).toBe(2);
+    });
+
+    it('should pass dependency check when target is already published', async () => {
+      // Pre-existing published object (different package)
+      await manager.register('object', 'account', {
+        name: 'account', label: 'Account', packageId: 'com.acme.core',
+        publishedDefinition: { fields: ['name'] },
+        state: 'active',
+      });
+
+      // View in a different package references the published object
+      await manager.register('view', 'account_list', {
+        name: 'account_list', label: 'Account List', packageId: 'com.acme.views',
+        metadata: { columns: ['name'] },
+      });
+
+      manager.addDependency({
+        sourceType: 'view',
+        sourceName: 'account_list',
+        targetType: 'object',
+        targetName: 'account',
+        kind: 'reference',
+      });
+
+      const result = await manager.publishPackage('com.acme.views', { validate: true });
+      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']);
+    });
+  });
 });