@objectstack/metadata 3.3.0 → 4.0.0

package/src/objects/sys-metadata.object.ts

@@ -1,188 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-/**
- * sys_metadata — System Metadata Object
- *
- * Canonical ObjectStack object definition for the metadata persistence table.
- * Stores all platform-scope and user-scope metadata records (Objects, Views,
- * Flows, etc.) using the MetadataRecordSchema envelope.
- *
- * This is a system object (isSystem: true) — protected from deletion and
- * automatically provisioned by the DatabaseLoader on first use.
- *
- * @see MetadataRecordSchema in metadata-persistence.zod.ts
- */
-export const SysMetadataObject = ObjectSchema.create({
-  namespace: 'sys',
-  name: 'metadata',
-  label: 'System Metadata',
-  pluralLabel: 'System Metadata',
-  icon: 'settings',
-  isSystem: true,
-  description: 'Stores platform and user-scope metadata records (objects, views, flows, etc.)',
-
-  fields: {
-    /** Primary Key (UUID) */
-    id: Field.text({
-      label: 'ID',
-      required: true,
-      readonly: true,
-    }),
-
-    /** Machine name — unique identifier used in code references */
-    name: Field.text({
-      label: 'Name',
-      required: true,
-      searchable: true,
-      maxLength: 255,
-    }),
-
-    /** Metadata type (e.g. "object", "view", "flow") */
-    type: Field.text({
-      label: 'Metadata Type',
-      required: true,
-      searchable: true,
-      maxLength: 100,
-    }),
-
-    /** Namespace / module grouping (e.g. "crm", "core") */
-    namespace: Field.text({
-      label: 'Namespace',
-      required: false,
-      defaultValue: 'default',
-      maxLength: 100,
-    }),
-
-    /** Package that owns/delivered this metadata */
-    package_id: Field.text({
-      label: 'Package ID',
-      required: false,
-      maxLength: 255,
-    }),
-
-    /** Who manages this record: package, platform, or user */
-    managed_by: Field.select(['package', 'platform', 'user'], {
-      label: 'Managed By',
-      required: false,
-    }),
-
-    /** Scope: system (code), platform (admin DB), user (personal DB) */
-    scope: Field.select(['system', 'platform', 'user'], {
-      label: 'Scope',
-      required: true,
-      defaultValue: 'platform',
-    }),
-
-    /** JSON payload — the actual metadata configuration */
-    metadata: Field.textarea({
-      label: 'Metadata',
-      required: true,
-      description: 'JSON-serialized metadata payload',
-    }),
-
-    /** Parent metadata name for extension/override */
-    extends: Field.text({
-      label: 'Extends',
-      required: false,
-      maxLength: 255,
-    }),
-
-    /** Merge strategy when extending parent metadata */
-    strategy: Field.select(['merge', 'replace'], {
-      label: 'Strategy',
-      required: false,
-      defaultValue: 'merge',
-    }),
-
-    /** Owner user ID (for user-scope items) */
-    owner: Field.text({
-      label: 'Owner',
-      required: false,
-      maxLength: 255,
-    }),
-
-    /** Lifecycle state */
-    state: Field.select(['draft', 'active', 'archived', 'deprecated'], {
-      label: 'State',
-      required: false,
-      defaultValue: 'active',
-    }),
-
-    /** Tenant ID for multi-tenant isolation */
-    tenant_id: Field.text({
-      label: 'Tenant ID',
-      required: false,
-      maxLength: 255,
-    }),
-
-    /** Version number for optimistic concurrency */
-    version: Field.number({
-      label: 'Version',
-      required: false,
-      defaultValue: 1,
-    }),
-
-    /** Content checksum for change detection */
-    checksum: Field.text({
-      label: 'Checksum',
-      required: false,
-      maxLength: 64,
-    }),
-
-    /** Origin of this metadata record */
-    source: Field.select(['filesystem', 'database', 'api', 'migration'], {
-      label: 'Source',
-      required: false,
-    }),
-
-    /** Classification tags (JSON array) */
-    tags: Field.textarea({
-      label: 'Tags',
-      required: false,
-      description: 'JSON-serialized array of classification tags',
-    }),
-
-    /** Audit fields */
-    created_by: Field.text({
-      label: 'Created By',
-      required: false,
-      readonly: true,
-      maxLength: 255,
-    }),
-
-    created_at: Field.datetime({
-      label: 'Created At',
-      required: false,
-      readonly: true,
-    }),
-
-    updated_by: Field.text({
-      label: 'Updated By',
-      required: false,
-      maxLength: 255,
-    }),
-
-    updated_at: Field.datetime({
-      label: 'Updated At',
-      required: false,
-    }),
-  },
-
-  indexes: [
-    { fields: ['type', 'name'], unique: true },
-    { fields: ['type', 'scope'] },
-    { fields: ['tenant_id'] },
-    { fields: ['state'] },
-    { fields: ['namespace'] },
-  ],
-
-  enable: {
-    trackHistory: true,
-    searchable: false,
-    apiEnabled: true,
-    apiMethods: ['get', 'list', 'create', 'update', 'delete'],
-    trash: false,
-  },
-});

package/src/plugin.ts

@@ -1,102 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { Plugin, PluginContext } from '@objectstack/core';
-import { NodeMetadataManager } from './node-metadata-manager.js';
-import { DEFAULT_METADATA_TYPE_REGISTRY } from '@objectstack/spec/kernel';
-import type { MetadataPluginConfig } from '@objectstack/spec/kernel';
-import { SysMetadataObject } from './objects/sys-metadata.object.js';
-
-export interface MetadataPluginOptions {
-    rootDir?: string;
-    watch?: boolean;
-    config?: Partial<MetadataPluginConfig>;
-}
-
-export class MetadataPlugin implements Plugin {
-    name = 'com.objectstack.metadata';
-    type = 'standard';
-    version = '1.0.0';
-    
-    private manager: NodeMetadataManager;
-    private options: MetadataPluginOptions;
-
-    constructor(options: MetadataPluginOptions = {}) {
-        this.options = {
-            watch: true,
-            ...options
-        };
-
-        const rootDir = this.options.rootDir || process.cwd();
-
-        this.manager = new NodeMetadataManager({ 
-            rootDir,
-            watch: this.options.watch ?? true,
-            formats: ['yaml', 'json', 'typescript', 'javascript'] 
-        });
-
-        // Initialize with default type registry
-        this.manager.setTypeRegistry(DEFAULT_METADATA_TYPE_REGISTRY);
-    }
-
-    init = async (ctx: PluginContext) => {
-        ctx.logger.info('Initializing Metadata Manager', {
-            root: this.options.rootDir || process.cwd(),
-            watch: this.options.watch
-        });
-
-        // Register Metadata Manager as primary metadata service provider
-        // This takes precedence over ObjectQL's fallback metadata service
-        ctx.registerService('metadata', this.manager);
-
-        // Register metadata system objects so ObjectQLPlugin auto-discovers them
-        ctx.registerService('app.com.objectstack.metadata', {
-            id: 'com.objectstack.metadata',
-            name: 'Metadata',
-            version: '1.0.0',
-            type: 'plugin',
-            namespace: 'sys',
-            objects: [SysMetadataObject],
-        });
-
-        ctx.logger.info('MetadataPlugin providing metadata service (primary mode)', {
-            mode: 'file-system',
-            features: ['watch', 'persistence', 'multi-format', 'query', 'overlay', 'type-registry']
-        });
-    }
-
-    start = async (ctx: PluginContext) => {
-        ctx.logger.info('Loading metadata from file system...');
-        
-        // Use the type registry to discover metadata types (sorted by loadOrder)
-        const sortedTypes = [...DEFAULT_METADATA_TYPE_REGISTRY]
-            .sort((a, b) => a.loadOrder - b.loadOrder);
-
-        let totalLoaded = 0;
-        for (const entry of sortedTypes) {
-            try {
-                const items = await this.manager.loadMany(entry.type, {
-                    recursive: true
-                });
-
-                if (items.length > 0) {
-                    // Register loaded items in the in-memory registry
-                    for (const item of items) {
-                        const meta = item as any;
-                        if (meta?.name) {
-                            await this.manager.register(entry.type, meta.name, item);
-                        }
-                    }
-                    ctx.logger.info(`Loaded ${items.length} ${entry.type} from file system`);
-                    totalLoaded += items.length;
-                }
-            } catch (e: any) {
-                ctx.logger.debug(`No ${entry.type} metadata found`, { error: e.message });
-            }
-        }
-        
-        ctx.logger.info('Metadata loading complete', { 
-            totalItems: totalLoaded,
-            registeredTypes: sortedTypes.length,
-        });
-    }
-}

package/src/serializers/json-serializer.ts

@@ -1,73 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * JSON Metadata Serializer
- * 
- * Handles JSON format serialization and deserialization
- */
-
-import type { z } from 'zod';
-import type { MetadataFormat } from '@objectstack/spec/system';
-import type { MetadataSerializer, SerializeOptions } from './serializer-interface.js';
-
-export class JSONSerializer implements MetadataSerializer {
-  serialize<T>(item: T, options?: SerializeOptions): string {
-    const { prettify = true, indent = 2, sortKeys = false } = options || {};
-
-    if (sortKeys) {
-      // Sort keys recursively
-      const sorted = this.sortObjectKeys(item);
-      return prettify
-        ? JSON.stringify(sorted, null, indent)
-        : JSON.stringify(sorted);
-    }
-
-    return prettify
-      ? JSON.stringify(item, null, indent)
-      : JSON.stringify(item);
-  }
-
-  deserialize<T>(content: string, schema?: z.ZodSchema): T {
-    const parsed = JSON.parse(content);
-
-    if (schema) {
-      return schema.parse(parsed) as T;
-    }
-
-    return parsed as T;
-  }
-
-  getExtension(): string {
-    return '.json';
-  }
-
-  canHandle(format: MetadataFormat): boolean {
-    return format === 'json';
-  }
-
-  getFormat(): MetadataFormat {
-    return 'json';
-  }
-
-  /**
-   * Recursively sort object keys
-   */
-  private sortObjectKeys(obj: any): any {
-    if (obj === null || typeof obj !== 'object') {
-      return obj;
-    }
-
-    if (Array.isArray(obj)) {
-      return obj.map(item => this.sortObjectKeys(item));
-    }
-
-    const sorted: Record<string, any> = {};
-    const keys = Object.keys(obj).sort();
-
-    for (const key of keys) {
-      sorted[key] = this.sortObjectKeys(obj[key]);
-    }
-
-    return sorted;
-  }
-}

package/src/serializers/serializer-interface.ts

@@ -1,65 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Metadata Serializer Interface
- * 
- * Defines the contract for serializing/deserializing metadata
- */
-
-import type { z } from 'zod';
-import type { MetadataFormat } from '@objectstack/spec/system';
-
-/**
- * Serialization options
- */
-export interface SerializeOptions {
-  /** Prettify output (formatted with indentation) */
-  prettify?: boolean;
-  /** Indentation size (spaces) */
-  indent?: number;
-  /** Sort object keys alphabetically */
-  sortKeys?: boolean;
-  /** Include default values in output */
-  includeDefaults?: boolean;
-}
-
-/**
- * Abstract interface for metadata serializers
- * Implementations handle different formats (JSON, YAML, TypeScript, etc.)
- */
-export interface MetadataSerializer {
-  /**
-   * Serialize object to string
-   * @param item The item to serialize
-   * @param options Serialization options
-   * @returns Serialized string
-   */
-  serialize<T>(item: T, options?: SerializeOptions): string;
-
-  /**
-   * Deserialize string to object
-   * @param content The content to deserialize
-   * @param schema Optional Zod schema for validation
-   * @returns Deserialized object
-   */
-  deserialize<T>(content: string, schema?: z.ZodSchema): T;
-
-  /**
-   * Get file extension for this format
-   * @returns File extension (e.g., '.json', '.yaml')
-   */
-  getExtension(): string;
-
-  /**
-   * Check if this serializer can handle the format
-   * @param format The format to check
-   * @returns True if can handle
-   */
-  canHandle(format: MetadataFormat): boolean;
-
-  /**
-   * Get the format this serializer handles
-   * @returns The metadata format
-   */
-  getFormat(): MetadataFormat;
-}

package/src/serializers/serializers.test.ts

@@ -1,74 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { JSONSerializer } from '../serializers/json-serializer';
-import { YAMLSerializer } from '../serializers/yaml-serializer';
-import { TypeScriptSerializer } from '../serializers/typescript-serializer';
-
-describe('Serializers', () => {
-  describe('JSONSerializer', () => {
-    const serializer = new JSONSerializer();
-
-    it('should serialize to JSON', () => {
-      const data = { name: 'test', value: 42 };
-      const result = serializer.serialize(data);
-      expect(result).toContain('"name"');
-      expect(result).toContain('"test"');
-    });
-
-    it('should deserialize from JSON', () => {
-      const json = '{"name":"test","value":42}';
-      const result = serializer.deserialize(json);
-      expect(result).toEqual({ name: 'test', value: 42 });
-    });
-
-    it('should prettify JSON', () => {
-      const data = { name: 'test' };
-      const result = serializer.serialize(data, { prettify: true, indent: 2 });
-      expect(result).toContain('\n');
-      expect(result).toContain('  ');
-    });
-
-    it('should sort keys', () => {
-      const data = { zebra: 1, apple: 2, banana: 3 };
-      const result = serializer.serialize(data, { sortKeys: true });
-      const keys = Object.keys(JSON.parse(result));
-      expect(keys).toEqual(['apple', 'banana', 'zebra']);
-    });
-  });
-
-  describe('YAMLSerializer', () => {
-    const serializer = new YAMLSerializer();
-
-    it('should serialize to YAML', () => {
-      const data = { name: 'test', value: 42 };
-      const result = serializer.serialize(data);
-      expect(result).toContain('name: test');
-      expect(result).toContain('value: 42');
-    });
-
-    it('should deserialize from YAML', () => {
-      const yaml = 'name: test\nvalue: 42';
-      const result = serializer.deserialize(yaml);
-      expect(result).toEqual({ name: 'test', value: 42 });
-    });
-  });
-
-  describe('TypeScriptSerializer', () => {
-    const serializer = new TypeScriptSerializer('typescript');
-
-    it('should serialize to TypeScript module', () => {
-      const data = { name: 'test', value: 42 };
-      const result = serializer.serialize(data);
-      expect(result).toContain('import type');
-      expect(result).toContain('export const metadata');
-      expect(result).toContain('export default metadata');
-    });
-
-    it('should get correct extension', () => {
-      const ts = new TypeScriptSerializer('typescript');
-      expect(ts.getExtension()).toBe('.ts');
-
-      const js = new TypeScriptSerializer('javascript');
-      expect(js.getExtension()).toBe('.js');
-    });
-  });
-});

package/src/serializers/typescript-serializer.ts

@@ -1,127 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * TypeScript/JavaScript Metadata Serializer
- * 
- * Handles TypeScript/JavaScript module format serialization and deserialization
- */
-
-import type { z } from 'zod';
-import type { MetadataFormat } from '@objectstack/spec/system';
-import type { MetadataSerializer, SerializeOptions } from './serializer-interface.js';
-
-export class TypeScriptSerializer implements MetadataSerializer {
-  constructor(private format: 'typescript' | 'javascript' = 'typescript') {}
-
-  serialize<T>(item: T, options?: SerializeOptions): string {
-    const { prettify = true, indent = 2 } = options || {};
-
-    const jsonStr = JSON.stringify(item, null, prettify ? indent : 0);
-    
-    if (this.format === 'typescript') {
-      return `import type { ServiceObject } from '@objectstack/spec/data';\n\n` +
-        `export const metadata: ServiceObject = ${jsonStr};\n\n` +
-        `export default metadata;\n`;
-    } else {
-      return `export const metadata = ${jsonStr};\n\n` +
-        `export default metadata;\n`;
-    }
-  }
-
-  deserialize<T>(content: string, schema?: z.ZodSchema): T {
-    // For TypeScript/JavaScript files, we need to extract the exported object
-    // Note: This is a simplified parser that works with JSON-like object literals
-    // For complex TypeScript with nested objects, consider using a proper TypeScript parser
-    
-    // Try to find the object literal in various export patterns
-    // Pattern 1: export const metadata = {...};
-    let objectStart = content.indexOf('export const');
-    if (objectStart === -1) {
-      // Pattern 2: export default {...};
-      objectStart = content.indexOf('export default');
-    }
-    
-    if (objectStart === -1) {
-      throw new Error(
-        'Could not parse TypeScript/JavaScript module. ' +
-        'Expected export pattern: "export const metadata = {...};" or "export default {...};"'
-      );
-    }
-
-    // Find the first opening brace after the export statement
-    const braceStart = content.indexOf('{', objectStart);
-    if (braceStart === -1) {
-      throw new Error('Could not find object literal in export statement');
-    }
-
-    // Find the matching closing brace by counting braces
-    // Handle string literals to avoid counting braces inside strings
-    let braceCount = 0;
-    let braceEnd = -1;
-    let inString = false;
-    let stringChar = '';
-    
-    for (let i = braceStart; i < content.length; i++) {
-      const char = content[i];
-      const prevChar = i > 0 ? content[i - 1] : '';
-      
-      // Track string literals (simple handling of " and ')
-      if ((char === '"' || char === "'") && prevChar !== '\\') {
-        if (!inString) {
-          inString = true;
-          stringChar = char;
-        } else if (char === stringChar) {
-          inString = false;
-          stringChar = '';
-        }
-      }
-      
-      // Count braces only when not inside strings
-      if (!inString) {
-        if (char === '{') braceCount++;
-        if (char === '}') {
-          braceCount--;
-          if (braceCount === 0) {
-            braceEnd = i;
-            break;
-          }
-        }
-      }
-    }
-
-    if (braceEnd === -1) {
-      throw new Error('Could not find matching closing brace for object literal');
-    }
-
-    // Extract the object literal
-    const objectLiteral = content.substring(braceStart, braceEnd + 1);
-
-    try {
-      // Parse as JSON
-      const parsed = JSON.parse(objectLiteral);
-
-      if (schema) {
-        return schema.parse(parsed) as T;
-      }
-
-      return parsed as T;
-    } catch (error) {
-      throw new Error(
-        `Failed to parse object literal as JSON: ${error instanceof Error ? error.message : String(error)}. ` +
-        'Make sure the TypeScript/JavaScript object uses JSON-compatible syntax (no functions, comments, or trailing commas).'
-      );
-    }
-  }
-
-  getExtension(): string {
-    return this.format === 'typescript' ? '.ts' : '.js';
-  }
-
-  canHandle(format: MetadataFormat): boolean {
-    return format === 'typescript' || format === 'javascript';
-  }
-
-  getFormat(): MetadataFormat {
-    return this.format;
-  }
-}

package/src/serializers/yaml-serializer.ts

@@ -1,49 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * YAML Metadata Serializer
- * 
- * Handles YAML format serialization and deserialization
- */
-
-import * as yaml from 'js-yaml';
-import type { z } from 'zod';
-import type { MetadataFormat } from '@objectstack/spec/system';
-import type { MetadataSerializer, SerializeOptions } from './serializer-interface.js';
-
-export class YAMLSerializer implements MetadataSerializer {
-  serialize<T>(item: T, options?: SerializeOptions): string {
-    const { indent = 2, sortKeys = false } = options || {};
-
-    return yaml.dump(item, {
-      indent,
-      sortKeys,
-      lineWidth: -1, // Disable line wrapping
-      noRefs: true,  // Disable YAML references
-    });
-  }
-
-  deserialize<T>(content: string, schema?: z.ZodSchema): T {
-    // Use JSON_SCHEMA to prevent arbitrary code execution
-    // This restricts YAML to JSON-compatible types only
-    const parsed = yaml.load(content, { schema: yaml.JSON_SCHEMA });
-
-    if (schema) {
-      return schema.parse(parsed) as T;
-    }
-
-    return parsed as T;
-  }
-
-  getExtension(): string {
-    return '.yaml';
-  }
-
-  canHandle(format: MetadataFormat): boolean {
-    return format === 'yaml';
-  }
-
-  getFormat(): MetadataFormat {
-    return 'yaml';
-  }
-}

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"],
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  }
-}