@objectstack/core 3.0.8 → 3.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/core",
-  "version": "3.0.8",
+  "version": "3.0.9",
   "license": "Apache-2.0",
   "description": "Microkernel Core for ObjectStack",
   "type": "module",
@@ -22,7 +22,7 @@
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "zod": "^4.3.6",
-    "@objectstack/spec": "3.0.8"
+    "@objectstack/spec": "3.0.9"
   },
   "peerDependencies": {
     "pino": "^8.0.0"

package/src/index.ts

@@ -31,6 +31,10 @@ export * from './health-monitor.js';
 export * from './hot-reload.js';
 export * from './dependency-resolver.js';
 
+// Export Phase 3 components - Package lifecycle management
+export * from './namespace-resolver.js';
+export * from './package-manager.js';
+
 // Re-export contracts from @objectstack/spec for backward compatibility
 export type { 
     Logger,

package/src/namespace-resolver.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { NamespaceResolver } from './namespace-resolver.js';
+import { createLogger } from './logger.js';
+
+describe('NamespaceResolver', () => {
+  let resolver: NamespaceResolver;
+
+  beforeEach(() => {
+    const logger = createLogger({ level: 'silent' });
+    resolver = new NamespaceResolver(logger);
+  });
+
+  describe('register', () => {
+    it('should register namespaces for a package', () => {
+      resolver.register('pkg-a', ['objects.task', 'views.task_list']);
+
+      const registry = resolver.getRegistry();
+      expect(registry.size).toBe(2);
+      expect(registry.get('objects.task')?.packageId).toBe('pkg-a');
+      expect(registry.get('views.task_list')?.packageId).toBe('pkg-a');
+    });
+
+    it('should overwrite namespace when same package re-registers', () => {
+      resolver.register('pkg-a', ['objects.task']);
+      resolver.register('pkg-a', ['objects.task']);
+
+      expect(resolver.getRegistry().size).toBe(1);
+      expect(resolver.getRegistry().get('objects.task')?.packageId).toBe('pkg-a');
+    });
+  });
+
+  describe('unregister', () => {
+    it('should remove all namespaces for a package', () => {
+      resolver.register('pkg-a', ['objects.task', 'views.task_list']);
+      resolver.register('pkg-b', ['objects.project']);
+
+      const removed = resolver.unregister('pkg-a');
+      expect(removed).toEqual(['objects.task', 'views.task_list']);
+      expect(resolver.getRegistry().size).toBe(1);
+      expect(resolver.getRegistry().has('objects.project')).toBe(true);
+    });
+
+    it('should return empty array for unknown package', () => {
+      const removed = resolver.unregister('unknown');
+      expect(removed).toEqual([]);
+    });
+  });
+
+  describe('checkAvailability', () => {
+    it('should report no conflicts for unused namespaces', () => {
+      const result = resolver.checkAvailability('pkg-a', ['objects.task']);
+      expect(result.available).toBe(true);
+      expect(result.conflicts).toHaveLength(0);
+    });
+
+    it('should detect conflict with another package', () => {
+      resolver.register('pkg-a', ['objects.task']);
+
+      const result = resolver.checkAvailability('pkg-b', ['objects.task']);
+      expect(result.available).toBe(false);
+      expect(result.conflicts).toHaveLength(1);
+      expect(result.conflicts[0].namespace).toBe('objects.task');
+      expect(result.conflicts[0].existingPackageId).toBe('pkg-a');
+      expect(result.conflicts[0].incomingPackageId).toBe('pkg-b');
+    });
+
+    it('should not conflict with own namespaces', () => {
+      resolver.register('pkg-a', ['objects.task']);
+
+      const result = resolver.checkAvailability('pkg-a', ['objects.task']);
+      expect(result.available).toBe(true);
+    });
+
+    it('should provide suggestions for conflicts', () => {
+      resolver.register('pkg-a', ['objects.task']);
+
+      const result = resolver.checkAvailability('@myorg/plugin-crm', ['objects.task']);
+      expect(result.available).toBe(false);
+      expect(result.suggestions['objects.task']).toBeDefined();
+      expect(result.suggestions['objects.task']).toContain('crm');
+    });
+  });
+
+  describe('extractNamespaces', () => {
+    it('should extract namespaces from object-style metadata', () => {
+      const config = {
+        objects: { task: {}, project: {} },
+        views: { task_list: {} },
+      };
+
+      const ns = resolver.extractNamespaces(config);
+      expect(ns).toContain('objects.task');
+      expect(ns).toContain('objects.project');
+      expect(ns).toContain('views.task_list');
+      expect(ns).toHaveLength(3);
+    });
+
+    it('should extract namespaces from array-style metadata', () => {
+      const config = {
+        objects: [{ name: 'task' }, { name: 'project' }],
+        flows: [{ name: 'approval_flow' }],
+      };
+
+      const ns = resolver.extractNamespaces(config);
+      expect(ns).toContain('objects.task');
+      expect(ns).toContain('objects.project');
+      expect(ns).toContain('flows.approval_flow');
+      expect(ns).toHaveLength(3);
+    });
+
+    it('should return empty array for empty config', () => {
+      const ns = resolver.extractNamespaces({});
+      expect(ns).toEqual([]);
+    });
+  });
+
+  describe('getPackageNamespaces', () => {
+    it('should return namespaces for a specific package', () => {
+      resolver.register('pkg-a', ['objects.task', 'views.task_list']);
+      resolver.register('pkg-b', ['objects.project']);
+
+      expect(resolver.getPackageNamespaces('pkg-a')).toEqual(['objects.task', 'views.task_list']);
+      expect(resolver.getPackageNamespaces('pkg-b')).toEqual(['objects.project']);
+    });
+
+    it('should return empty for unknown package', () => {
+      expect(resolver.getPackageNamespaces('unknown')).toEqual([]);
+    });
+  });
+});

package/src/namespace-resolver.ts

@@ -0,0 +1,188 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { ObjectLogger } from './logger.js';
+
+/**
+ * Namespace entry representing an object/view/flow etc. registered by a package.
+ */
+export interface NamespaceEntry {
+  /** The namespace path (e.g. "objects.project_task", "views.task_list") */
+  namespace: string;
+  /** The package that owns this namespace */
+  packageId: string;
+  /** When this entry was registered */
+  registeredAt: string;
+}
+
+/**
+ * Result of a namespace conflict check.
+ */
+export interface NamespaceConflict {
+  /** The conflicting namespace path */
+  namespace: string;
+  /** The package that currently owns this namespace */
+  existingPackageId: string;
+  /** The package attempting to register the same namespace */
+  incomingPackageId: string;
+  /** A suggested alternative name to avoid the conflict */
+  suggestion?: string;
+}
+
+/**
+ * Result of namespace availability check.
+ */
+export interface NamespaceCheckResult {
+  /** Whether all requested namespaces are available */
+  available: boolean;
+  /** List of conflicts detected */
+  conflicts: NamespaceConflict[];
+  /** Suggested alternatives for each conflict */
+  suggestions: Record<string, string>;
+}
+
+/**
+ * Namespace Resolver
+ *
+ * Manages namespace registration for installed packages and detects collisions
+ * during install-time. Each metadata item (object, view, flow, page, etc.)
+ * produces a namespace like `objects.<name>` or `views.<name>`.
+ *
+ * When a new package declares objects, views, or other metadata that would
+ * collide with an existing package's metadata, this resolver reports the
+ * conflicts and suggests prefixed alternatives.
+ */
+export class NamespaceResolver {
+  private logger: ObjectLogger;
+  private registry: Map<string, NamespaceEntry> = new Map();
+
+  constructor(logger: ObjectLogger) {
+    this.logger = logger.child({ component: 'NamespaceResolver' });
+  }
+
+  /**
+   * Register namespaces owned by a package.
+   */
+  register(packageId: string, namespaces: string[]): void {
+    const now = new Date().toISOString();
+    for (const ns of namespaces) {
+      if (this.registry.has(ns)) {
+        const existing = this.registry.get(ns)!;
+        if (existing.packageId !== packageId) {
+          this.logger.warn('Overwriting namespace entry', { namespace: ns, existing: existing.packageId, incoming: packageId });
+        }
+      }
+      this.registry.set(ns, { namespace: ns, packageId, registeredAt: now });
+      this.logger.debug('Namespace registered', { namespace: ns, packageId });
+    }
+  }
+
+  /**
+   * Unregister all namespaces belonging to a package.
+   */
+  unregister(packageId: string): string[] {
+    const removed: string[] = [];
+    for (const [ns, entry] of this.registry) {
+      if (entry.packageId === packageId) {
+        this.registry.delete(ns);
+        removed.push(ns);
+      }
+    }
+    this.logger.debug('Namespaces unregistered', { packageId, count: removed.length });
+    return removed;
+  }
+
+  /**
+   * Check whether a set of namespaces is available for a given package.
+   */
+  checkAvailability(packageId: string, namespaces: string[]): NamespaceCheckResult {
+    const conflicts: NamespaceConflict[] = [];
+    const suggestions: Record<string, string> = {};
+
+    for (const ns of namespaces) {
+      const existing = this.registry.get(ns);
+      if (existing && existing.packageId !== packageId) {
+        const suggestion = this.suggestAlternative(ns, packageId);
+        conflicts.push({
+          namespace: ns,
+          existingPackageId: existing.packageId,
+          incomingPackageId: packageId,
+          suggestion,
+        });
+        suggestions[ns] = suggestion;
+      }
+    }
+
+    return {
+      available: conflicts.length === 0,
+      conflicts,
+      suggestions,
+    };
+  }
+
+  /**
+   * Extract namespace strings from a package's metadata definition.
+   */
+  extractNamespaces(config: Record<string, unknown>): string[] {
+    const namespaces: string[] = [];
+    const categories = [
+      'objects', 'views', 'pages', 'flows', 'workflows',
+      'apps', 'dashboards', 'reports', 'actions', 'agents',
+    ];
+
+    for (const category of categories) {
+      const items = config[category];
+      if (Array.isArray(items)) {
+        for (const item of items) {
+          const name = (item as Record<string, unknown>)?.name;
+          if (typeof name === 'string') {
+            namespaces.push(`${category}.${name}`);
+          }
+        }
+      } else if (items && typeof items === 'object') {
+        for (const key of Object.keys(items as object)) {
+          namespaces.push(`${category}.${key}`);
+        }
+      }
+    }
+
+    return namespaces;
+  }
+
+  /**
+   * Get all registered entries.
+   */
+  getRegistry(): ReadonlyMap<string, NamespaceEntry> {
+    return this.registry;
+  }
+
+  /**
+   * Get all namespaces belonging to a specific package.
+   */
+  getPackageNamespaces(packageId: string): string[] {
+    const namespaces: string[] = [];
+    for (const [ns, entry] of this.registry) {
+      if (entry.packageId === packageId) {
+        namespaces.push(ns);
+      }
+    }
+    return namespaces;
+  }
+
+  /**
+   * Generate a prefixed alternative namespace to avoid conflicts.
+   */
+  private suggestAlternative(ns: string, packageId: string): string {
+    // Extract the short package name for prefixing
+    const shortName = packageId
+      .replace(/^@[^/]+\//, '')
+      .replace(/^plugin-/, '')
+      .replace(/-/g, '_');
+
+    const parts = ns.split('.');
+    if (parts.length >= 2) {
+      // e.g. "objects.task" → "objects.crm_task"
+      return `${parts[0]}.${shortName}_${parts.slice(1).join('.')}`;
+    }
+    return `${shortName}_${ns}`;
+  }
+}

package/src/package-manager.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PackageManager } from './package-manager.js';
+import { createLogger } from './logger.js';
+
+describe('PackageManager', () => {
+  let manager: PackageManager;
+
+  beforeEach(() => {
+    const logger = createLogger({ level: 'silent' });
+    manager = new PackageManager(logger, { platformVersion: '3.0.0' });
+  });
+
+  describe('install', () => {
+    it('should install a package successfully', async () => {
+      const result = await manager.install('pkg-a', '1.0.0', {
+        objects: { task: { label: 'Task' } },
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.packageId).toBe('pkg-a');
+      expect(result.version).toBe('1.0.0');
+      expect(manager.getPackage('pkg-a')).toBeDefined();
+      expect(manager.getPackage('pkg-a')?.status).toBe('installed');
+    });
+
+    it('should reject already installed package', async () => {
+      await manager.install('pkg-a', '1.0.0', {});
+      const result = await manager.install('pkg-a', '1.0.0', {});
+
+      expect(result.success).toBe(false);
+      expect(result.errorMessage).toContain('already installed');
+    });
+
+    it('should detect namespace conflicts', async () => {
+      await manager.install('pkg-a', '1.0.0', {
+        objects: { task: {} },
+      });
+
+      const result = await manager.install('pkg-b', '1.0.0', {
+        objects: { task: {} },
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.namespaceConflicts).toHaveLength(1);
+      expect(result.namespaceConflicts[0].namespace).toBe('objects.task');
+      expect(result.namespaceConflicts[0].existingPackageId).toBe('pkg-a');
+    });
+
+    it('should reject incompatible platform version', async () => {
+      const result = await manager.install('pkg-a', '1.0.0', {
+        engine: { objectstack: '>=4.0.0' },
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.errorMessage).toContain('platform');
+    });
+
+    it('should reject missing dependencies', async () => {
+      const result = await manager.install('pkg-a', '1.0.0', {
+        dependencies: { 'pkg-b': '^1.0.0' },
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.errorMessage).toContain('Missing dependencies');
+    });
+
+    it('should succeed when dependencies are installed', async () => {
+      await manager.install('pkg-b', '1.0.0', {});
+      const result = await manager.install('pkg-a', '1.0.0', {
+        dependencies: { 'pkg-b': '^1.0.0' },
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.installedDependencies).toContain('pkg-b');
+    });
+  });
+
+  describe('uninstall', () => {
+    it('should uninstall a package', async () => {
+      await manager.install('pkg-a', '1.0.0', {});
+      const result = await manager.uninstall('pkg-a');
+
+      expect(result.success).toBe(true);
+      expect(manager.getPackage('pkg-a')).toBeUndefined();
+    });
+
+    it('should prevent uninstalling if dependents exist', async () => {
+      await manager.install('pkg-a', '1.0.0', {});
+      await manager.install('pkg-b', '1.0.0', {
+        dependencies: { 'pkg-a': '^1.0.0' },
+      });
+
+      const result = await manager.uninstall('pkg-a');
+      expect(result.success).toBe(false);
+      expect(result.errorMessage).toContain('depended upon');
+    });
+
+    it('should reject uninstalling unknown package', async () => {
+      const result = await manager.uninstall('unknown');
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('upgrade', () => {
+    it('should upgrade a package and create snapshot', async () => {
+      await manager.install('pkg-a', '1.0.0', {
+        objects: { task: {} },
+      });
+
+      const result = await manager.upgrade('pkg-a', '2.0.0', {
+        objects: { task: {}, project: {} },
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.fromVersion).toBe('1.0.0');
+      expect(result.toVersion).toBe('2.0.0');
+      expect(result.snapshot.previousVersion).toBe('1.0.0');
+      expect(manager.getPackage('pkg-a')?.version).toBe('2.0.0');
+    });
+
+    it('should reject upgrade for uninstalled package', async () => {
+      const result = await manager.upgrade('unknown', '2.0.0', {});
+      expect(result.success).toBe(false);
+      expect(result.errorMessage).toContain('not installed');
+    });
+
+    it('should detect namespace conflicts during upgrade', async () => {
+      await manager.install('pkg-a', '1.0.0', { objects: { task: {} } });
+      await manager.install('pkg-b', '1.0.0', { objects: { project: {} } });
+
+      // pkg-a upgrade tries to add objects.project which is owned by pkg-b
+      const result = await manager.upgrade('pkg-a', '2.0.0', {
+        objects: { task: {}, project: {} },
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.errorMessage).toContain('Namespace conflicts');
+    });
+
+    it('should reject platform-incompatible upgrade', async () => {
+      await manager.install('pkg-a', '1.0.0', {});
+
+      const result = await manager.upgrade('pkg-a', '2.0.0', {
+        engine: { objectstack: '>=5.0.0' },
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.errorMessage).toContain('platform');
+    });
+  });
+
+  describe('rollback', () => {
+    it('should rollback to pre-upgrade state', async () => {
+      await manager.install('pkg-a', '1.0.0', {
+        objects: { task: {} },
+      });
+      await manager.upgrade('pkg-a', '2.0.0', {
+        objects: { task: {}, project: {} },
+      });
+
+      const result = await manager.rollback('pkg-a');
+      expect(result.success).toBe(true);
+      expect(result.restoredVersion).toBe('1.0.0');
+      expect(manager.getPackage('pkg-a')?.version).toBe('1.0.0');
+    });
+
+    it('should reject rollback without snapshot', async () => {
+      await manager.install('pkg-a', '1.0.0', {});
+      const result = await manager.rollback('pkg-a');
+
+      expect(result.success).toBe(false);
+      expect(result.errorMessage).toContain('No upgrade snapshot');
+    });
+  });
+
+  describe('listPackages', () => {
+    it('should list all installed packages', async () => {
+      await manager.install('pkg-a', '1.0.0', {});
+      await manager.install('pkg-b', '2.0.0', {});
+
+      const list = manager.listPackages();
+      expect(list).toHaveLength(2);
+      expect(list.map(p => p.packageId)).toContain('pkg-a');
+      expect(list.map(p => p.packageId)).toContain('pkg-b');
+    });
+  });
+
+  describe('checkNamespaces', () => {
+    it('should check namespace availability', async () => {
+      await manager.install('pkg-a', '1.0.0', {
+        objects: { task: {} },
+      });
+
+      const result = manager.checkNamespaces('pkg-b', {
+        objects: { task: {} },
+      });
+
+      expect(result.available).toBe(false);
+      expect(result.conflicts).toHaveLength(1);
+    });
+
+    it('should report available when no conflicts', () => {
+      const result = manager.checkNamespaces('pkg-a', {
+        objects: { task: {} },
+      });
+
+      expect(result.available).toBe(true);
+      expect(result.conflicts).toHaveLength(0);
+    });
+  });
+
+  describe('resolveDependencies', () => {
+    it('should resolve dependencies in topological order', () => {
+      const packages = new Map([
+        ['a', { dependencies: [] as string[] }],
+        ['b', { dependencies: ['a'] }],
+        ['c', { dependencies: ['a', 'b'] }],
+      ]);
+
+      const order = manager.resolveDependencies(packages);
+      expect(order.indexOf('a')).toBeLessThan(order.indexOf('b'));
+      expect(order.indexOf('b')).toBeLessThan(order.indexOf('c'));
+    });
+  });
+});