@objectstack/metadata 0.9.2 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @objectstack/metadata
 
+## 1.0.1
+
+### Patch Changes
+
+- @objectstack/spec@1.0.1
+- @objectstack/core@1.0.1
+- @objectstack/types@1.0.1
+
+## 1.0.0
+
+### Major Changes
+
+- Major version release for ObjectStack Protocol v1.0.
+  - Stabilized Protocol Definitions
+  - Enhanced Runtime Plugin Support
+  - Fixed Type Compliance across Monorepo
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@1.0.0
+  - @objectstack/core@1.0.0
+  - @objectstack/types@1.0.0
+
 ## 0.9.2
 
 ### Patch Changes

package/README.md

@@ -1,458 +1,13 @@
 # @objectstack/metadata
 
-Metadata loading, saving, and persistence for ObjectStack.
+The **Model Definition** layer. It provides classes and utilities for parsing and validating ObjectStack metadata schemas.
 
-## Overview
+## Features
 
-The `@objectstack/metadata` package provides a unified interface for managing metadata across the ObjectStack ecosystem. It handles:
+- **Schema Loading**: Load metadata from JSON/YAML or TypeScript files.
+- **Reference Resolution**: Resolves cross-object references and inheritance.
+- **Validation**: Strict validation against the Zod schemas in `@objectstack/spec`.
 
-- **Metadata Serialization/Deserialization** - Support for JSON, YAML, TypeScript, and JavaScript formats
-- **File System Operations** - Load, save, and watch metadata files
-- **Validation** - Integration with Zod schemas from `@objectstack/spec`
-- **Caching** - ETag-based caching for performance optimization
-- **File Watching** - Development mode with automatic reload on file changes
+## Usage
 
-## 🤖 AI Development Context
-
-**Role**: Metadata IO & Persistence
-**Usage**:
-- Use `MetadataManager` to read/write `.object.ts`, `.view.yaml` files.
-- Handles format loading (TS, JSON, YAML).
-
-## Installation
-
-```bash
-pnpm add @objectstack/metadata
-```
-
-## Quick Start
-
-```typescript
-import { MetadataManager } from '@objectstack/metadata';
-import type { ServiceObject } from '@objectstack/spec/data';
-
-// Create manager
-const manager = new MetadataManager({
-  rootDir: './metadata',
-  formats: ['typescript', 'json', 'yaml'],
-  cache: { enabled: true, ttl: 3600 },
-  watch: process.env.NODE_ENV === 'development',
-});
-
-// Load metadata
-const customer = await manager.load<ServiceObject>('object', 'customer');
-
-// Save metadata
-await manager.save('object', 'project', projectObject, {
-  format: 'typescript',
-  prettify: true,
-});
-
-// Load multiple items
-const objects = await manager.loadMany<ServiceObject>('object', {
-  patterns: ['**/*.object.ts', '**/*.object.json'],
-});
-
-// Watch for changes
-manager.watch('object', (event) => {
-  console.log(`Object ${event.type}:`, event.name);
-});
-```
-
-## API
-
-### MetadataManager
-
-Main class for metadata operations.
-
-#### Constructor
-
-```typescript
-new MetadataManager(config: MetadataManagerConfig)
-```
-
-**Config options:**
-- `rootDir` - Root directory for metadata files
-- `formats` - Enabled serialization formats (default: `['typescript', 'json', 'yaml']`)
-- `cache` - Cache configuration with `enabled` and `ttl` options
-- `watch` - Enable file watching (default: `false`)
-- `watchOptions` - File watcher options (`ignored`, `persistent`, `ignoreInitial`)
-
-#### Methods
-
-**load<T>(type: string, name: string, options?: MetadataLoadOptions): Promise<T | null>**
-
-Load a single metadata item.
-
-```typescript
-const customer = await manager.load<ServiceObject>('object', 'customer');
-```
-
-**loadMany<T>(type: string, options?: MetadataLoadOptions): Promise<T[]>**
-
-Load multiple metadata items matching patterns.
-
-```typescript
-const objects = await manager.loadMany<ServiceObject>('object', {
-  patterns: ['**/*.object.ts'],
-  limit: 100,
-});
-```
-
-**save<T>(type: string, name: string, data: T, options?: MetadataSaveOptions): Promise<MetadataSaveResult>**
-
-Save metadata to disk.
-
-```typescript
-await manager.save('object', 'customer', customerObject, {
-  format: 'typescript',
-  prettify: true,
-  backup: true,
-});
-```
-
-**exists(type: string, name: string): Promise<boolean>**
-
-Check if metadata item exists.
-
-```typescript
-const exists = await manager.exists('object', 'customer');
-```
-
-**list(type: string): Promise<string[]>**
-
-List all items of a type.
-
-```typescript
-const objectNames = await manager.list('object');
-```
-
-**watch(type: string, callback: WatchCallback): void**
-
-Watch for metadata changes.
-
-```typescript
-manager.watch('object', (event) => {
-  if (event.type === 'added') {
-    console.log('New object:', event.name);
-  }
-});
-```
-
-**stopWatching(): Promise<void>**
-
-Stop all file watching.
-
-## Serialization Formats
-
-### JSON
-
-```json
-{
-  "name": "customer",
-  "label": "Customer",
-  "fields": {
-    "name": { "type": "text", "label": "Name" }
-  }
-}
-```
-
-### YAML
-
-```yaml
-name: customer
-label: Customer
-fields:
-  name:
-    type: text
-    label: Name
-```
-
-### TypeScript
-
-```typescript
-import type { ServiceObject } from '@objectstack/spec/data';
-
-export const metadata: ServiceObject = {
-  name: 'customer',
-  label: 'Customer',
-  fields: {
-    name: { type: 'text', label: 'Name' },
-  },
-};
-
-export default metadata;
-```
-
-## Architecture
-
-The metadata package is designed as a Layer 3 package in the ObjectStack architecture:
-
-```
-@objectstack/metadata (Layer 3)
-├── Dependencies:
-│   ├── @objectstack/spec (validation)
-│   ├── @objectstack/core (logging, DI)
-│   ├── @objectstack/types (shared types)
-│   ├── glob (file pattern matching)
-│   ├── js-yaml (YAML support)
-│   └── chokidar (file watching)
-└── Used By:
-    ├── @objectstack/cli (code generation)
-    ├── @objectstack/runtime (manifest loading)
-    └── @objectstack/objectql (registry persistence)
-```
-
-## Common Workflows
-
-### Development Workflow with File Watching
-
-```typescript
-import { MetadataManager } from '@objectstack/metadata';
-
-const manager = new MetadataManager({
-  rootDir: './metadata',
-  watch: true, // Enable file watching
-  cache: { enabled: true, ttl: 3600 }
-});
-
-// Watch for changes and reload
-manager.watch('object', async (event) => {
-  if (event.type === 'modified' || event.type === 'added') {
-    console.log(`Reloading object: ${event.name}`);
-    const updated = await manager.load('object', event.name);
-    
-    // Notify the system to reload
-    await objectQL.reloadObject(event.name, updated);
-  }
-});
-
-// Hot module replacement for development
-console.log('Watching metadata files for changes...');
-```
-
-### Metadata Migration Workflow
-
-```typescript
-import { MetadataManager } from '@objectstack/metadata';
-
-async function migrateMetadata() {
-  const manager = new MetadataManager({
-    rootDir: './metadata'
-  });
-  
-  // 1. Load all existing objects
-  const objects = await manager.loadMany('object');
-  
-  // 2. Transform metadata (e.g., rename field)
-  const transformed = objects.map(obj => ({
-    ...obj,
-    fields: Object.entries(obj.fields).reduce((acc, [key, field]) => {
-      // Rename 'description' to 'notes'
-      const newKey = key === 'description' ? 'notes' : key;
-      acc[newKey] = field;
-      return acc;
-    }, {})
-  }));
-  
-  // 3. Save with backup
-  for (const obj of transformed) {
-    await manager.save('object', obj.name, obj, {
-      format: 'typescript',
-      backup: true, // Create .bak file
-      prettify: true
-    });
-  }
-  
-  console.log(`Migrated ${objects.length} objects`);
-}
-```
-
-### Multi-Format Support Workflow
-
-```typescript
-import { MetadataManager } from '@objectstack/metadata';
-
-const manager = new MetadataManager({
-  rootDir: './metadata',
-  formats: ['typescript', 'json', 'yaml']
-});
-
-// Load from any format - manager auto-detects
-const customer = await manager.load('object', 'customer');
-// Tries: customer.object.ts, customer.object.json, customer.object.yaml
-
-// Save in preferred format
-await manager.save('object', 'customer', customer, {
-  format: 'typescript' // Convert to TypeScript
-});
-
-// Generate documentation from metadata
-const allObjects = await manager.loadMany('object');
-const docs = allObjects.map(obj => `
-## ${obj.label}
-
-**Name:** ${obj.name}
-
-**Fields:**
-${Object.entries(obj.fields).map(([name, field]) => 
-  `- **${field.label}** (\`${name}\`): ${field.type}`
-).join('\n')}
-`).join('\n\n');
-
-fs.writeFileSync('docs/objects.md', docs);
-```
-
-### Validation and Testing Workflow
-
-```typescript
-import { MetadataManager } from '@objectstack/metadata';
-import { ObjectSchema } from '@objectstack/spec/data';
-
-async function validateAllMetadata() {
-  const manager = new MetadataManager({
-    rootDir: './metadata'
-  });
-  
-  const objects = await manager.loadMany('object');
-  const errors = [];
-  
-  for (const obj of objects) {
-    const result = ObjectSchema.safeParse(obj);
-    
-    if (!result.success) {
-      errors.push({
-        name: obj.name,
-        issues: result.error.issues
-      });
-    }
-  }
-  
-  if (errors.length > 0) {
-    console.error('Validation errors found:');
-    errors.forEach(({ name, issues }) => {
-      console.error(`\n${name}:`);
-      issues.forEach(issue => {
-        console.error(`  - ${issue.path.join('.')}: ${issue.message}`);
-      });
-    });
-    process.exit(1);
-  }
-  
-  console.log(`✅ All ${objects.length} objects validated successfully`);
-}
-```
-
-### Metadata Versioning Workflow
-
-```typescript
-import { MetadataManager } from '@objectstack/metadata';
-import { execSync } from 'child_process';
-
-async function versionMetadata() {
-  const manager = new MetadataManager({
-    rootDir: './metadata'
-  });
-  
-  const objects = await manager.loadMany('object');
-  
-  // Get git user name safely
-  let modifiedBy = 'unknown';
-  try {
-    modifiedBy = execSync('git config user.name', { encoding: 'utf-8' }).trim();
-  } catch (error) {
-    console.warn('Could not get git user name, using "unknown"');
-  }
-  
-  // Add version metadata
-  const versioned = objects.map(obj => ({
-    ...obj,
-    metadata: {
-      ...obj.metadata,
-      version: '2.0.0',
-      lastModified: new Date().toISOString(),
-      modifiedBy
-    }
-  }));
-  
-  // Save versioned metadata
-  for (const obj of versioned) {
-    await manager.save('object', obj.name, obj, {
-      format: 'typescript',
-      prettify: true
-    });
-  }
-  
-  // Commit to version control (if git is available)
-  try {
-    execSync('git add metadata/', { stdio: 'inherit' });
-    execSync('git commit -m "Version bump to 2.0.0"', { stdio: 'inherit' });
-  } catch (error) {
-    console.warn('Git commit failed, changes are staged but not committed');
-  }
-}
-```
-
-### Import/Export Workflow
-
-```typescript
-import { MetadataManager } from '@objectstack/metadata';
-
-async function exportToJSON() {
-  const manager = new MetadataManager({
-    rootDir: './metadata'
-  });
-  
-  // Load all metadata
-  const [objects, views, apps] = await Promise.all([
-    manager.loadMany('object'),
-    manager.loadMany('view'),
-    manager.loadMany('app')
-  ]);
-  
-  // Create unified export
-  const exportData = {
-    version: '1.0.0',
-    exported: new Date().toISOString(),
-    objects,
-    views,
-    apps
-  };
-  
-  // Save as single JSON file
-  fs.writeFileSync(
-    'export/metadata-export.json',
-    JSON.stringify(exportData, null, 2)
-  );
-  
-  console.log('Export complete!');
-}
-
-async function importFromJSON(filePath: string) {
-  const manager = new MetadataManager({
-    rootDir: './metadata'
-  });
-  
-  const importData = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-  
-  // Import objects
-  for (const obj of importData.objects) {
-    await manager.save('object', obj.name, obj, {
-      format: 'typescript'
-    });
-  }
-  
-  // Import views
-  for (const view of importData.views) {
-    await manager.save('view', view.name, view, {
-      format: 'typescript'
-    });
-  }
-  
-  console.log('Import complete!');
-}
-```
-
-## License
-
-MIT
+Internal package used by `@objectstack/runtime` to process configuration.

package/dist/index.d.ts

@@ -3,10 +3,11 @@
  *
  * Metadata loading, saving, and persistence for ObjectStack
  */
-export { MetadataManager, type WatchCallback } from './metadata-manager.js';
+export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from './metadata-manager.js';
 export { MetadataPlugin } from './plugin.js';
 export { type MetadataLoader } from './loaders/loader-interface.js';
-export { FilesystemLoader } from './loaders/filesystem-loader.js';
+export { MemoryLoader } from './loaders/memory-loader.js';
+export { RemoteLoader } from './loaders/remote-loader.js';
 export { type MetadataSerializer, type SerializeOptions } from './serializers/serializer-interface.js';
 export { JSONSerializer } from './serializers/json-serializer.js';
 export { YAMLSerializer } from './serializers/yaml-serializer.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG5E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AACvG,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAG9E,YAAY,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAGzG,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AACvG,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAG9E,YAAY,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -7,7 +7,8 @@
 export { MetadataManager } from './metadata-manager.js';
 // Plugin
 export { MetadataPlugin } from './plugin.js';
-export { FilesystemLoader } from './loaders/filesystem-loader.js';
+export { MemoryLoader } from './loaders/memory-loader.js';
+export { RemoteLoader } from './loaders/remote-loader.js';
 export { JSONSerializer } from './serializers/json-serializer.js';
 export { YAMLSerializer } from './serializers/yaml-serializer.js';
 export * as Migration from './migration/index.js';

package/dist/loaders/filesystem-loader.d.ts

@@ -3,7 +3,7 @@
  *
  * Loads metadata from the filesystem using glob patterns
  */
-import type { MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataLoaderContract, MetadataFormat } from '@objectstack/spec/system';
+import type { MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataLoaderContract, MetadataFormat, MetadataSaveOptions, MetadataSaveResult } from '@objectstack/spec/system';
 import type { Logger } from '@objectstack/core';
 import type { MetadataLoader } from './loader-interface.js';
 import type { MetadataSerializer } from '../serializers/serializer-interface.js';
@@ -19,6 +19,7 @@ export declare class FilesystemLoader implements MetadataLoader {
     exists(type: string, name: string): Promise<boolean>;
     stat(type: string, name: string): Promise<MetadataStats | null>;
     list(type: string): Promise<string[]>;
+    save(type: string, name: string, data: any, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
     /**
      * Find file for a given type and name
      */

package/dist/loaders/filesystem-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filesystem-loader.d.ts","sourceRoot":"","sources":["../../src/loaders/filesystem-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAEjF,qBAAa,gBAAiB,YAAW,cAAc;IAYnD,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,MAAM,CAAC;IAbjB,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAMvC;IAEF,OAAO,CAAC,KAAK,CAAqE;gBAGxE,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAC,EACpD,MAAM,CAAC,EAAE,MAAM,YAAA;IAGnB,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA8FxB,QAAQ,CAAC,CAAC,GAAG,GAAG,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC;IAwDT,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKpD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA+B/D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAwB3C;;OAEG;YACW,QAAQ;IAkBtB;;OAEG;IACH,OAAO,CAAC,YAAY;IAkBpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAIrB"}
+{"version":3,"file":"filesystem-loader.d.ts","sourceRoot":"","sources":["../../src/loaders/filesystem-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAEjF,qBAAa,gBAAiB,YAAW,cAAc;IAmBnD,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,MAAM,CAAC;IApBjB,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAavC;IAEF,OAAO,CAAC,KAAK,CAAqE;gBAGxE,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAC,EACpD,MAAM,CAAC,EAAE,MAAM,YAAA;IAGnB,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA8FxB,QAAQ,CAAC,CAAC,GAAG,GAAG,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC;IAwDT,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKpD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA+B/D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAwBrC,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,GAAG,EACT,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA0F9B;;OAEG;YACW,QAAQ;IAkBtB;;OAEG;IACH,OAAO,CAAC,YAAY;IAkBpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAIrB"}

package/dist/loaders/filesystem-loader.js

@@ -14,6 +14,13 @@ export class FilesystemLoader {
         this.logger = logger;
         this.contract = {
             name: 'filesystem',
+            protocol: 'file',
+            capabilities: {
+                read: true,
+                write: true,
+                watch: true,
+                list: true,
+            },
             supportedFormats: ['json', 'yaml', 'typescript', 'javascript'],
             supportsWatch: true,
             supportsWrite: true,
@@ -82,7 +89,7 @@ export class FilesystemLoader {
             if (useCache) {
                 this.cache.set(cacheKey, {
                     data,
-                    etag: stats.etag,
+                    etag: stats.etag || '',
                     timestamp: Date.now(),
                 });
             }
@@ -205,6 +212,81 @@ export class FilesystemLoader {
             return [];
         }
     }
+    async save(type, name, data, options) {
+        const startTime = Date.now();
+        const { format = 'typescript', prettify = true, indent = 2, sortKeys = false, backup = false, overwrite = true, atomic = true, path: customPath, } = options || {};
+        try {
+            // Get serializer
+            const serializer = this.getSerializer(format);
+            if (!serializer) {
+                throw new Error(`No serializer found for format: ${format}`);
+            }
+            // Determine file path
+            const typeDir = path.join(this.rootDir, type);
+            const fileName = `${name}${serializer.getExtension()}`;
+            const filePath = customPath || path.join(typeDir, fileName);
+            // Check if file exists
+            if (!overwrite) {
+                try {
+                    await fs.access(filePath);
+                    throw new Error(`File already exists: ${filePath}`);
+                }
+                catch (error) {
+                    // File doesn't exist, continue
+                    if (error.code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+            }
+            // Create directory if it doesn't exist
+            await fs.mkdir(path.dirname(filePath), { recursive: true });
+            // Create backup if requested
+            let backupPath;
+            if (backup) {
+                try {
+                    await fs.access(filePath);
+                    backupPath = `${filePath}.bak`;
+                    await fs.copyFile(filePath, backupPath);
+                }
+                catch {
+                    // File doesn't exist, no backup needed
+                }
+            }
+            // Serialize data
+            const content = serializer.serialize(data, {
+                prettify,
+                indent,
+                sortKeys,
+            });
+            // Write to disk (atomic or direct)
+            if (atomic) {
+                const tempPath = `${filePath}.tmp`;
+                await fs.writeFile(tempPath, content, 'utf-8');
+                await fs.rename(tempPath, filePath);
+            }
+            else {
+                await fs.writeFile(filePath, content, 'utf-8');
+            }
+            // Update cache logic if needed (e.g., invalidate or update)
+            // For now, we rely on the watcher to pick up changes
+            return {
+                success: true,
+                path: filePath,
+                // format, // Not in schema
+                size: Buffer.byteLength(content, 'utf-8'),
+                backupPath,
+                saveTime: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            this.logger?.error('Failed to save metadata', undefined, {
+                type,
+                name,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
     /**
      * Find file for a given type and name
      */

package/dist/loaders/loader-interface.d.ts

@@ -3,7 +3,7 @@
  *
  * Defines the contract for loading metadata from various sources
  */
-import type { MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataLoaderContract } from '@objectstack/spec/system';
+import type { MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataLoaderContract, MetadataSaveOptions, MetadataSaveResult } from '@objectstack/spec/system';
 /**
  * Abstract interface for metadata loaders
  * Implementations can load from filesystem, HTTP, S3, databases, etc.
@@ -48,5 +48,13 @@ export interface MetadataLoader {
      * @returns Array of item names
      */
     list(type: string): Promise<string[]>;
+    /**
+     * Save metadata item
+     * @param type The metadata type
+     * @param name The item name
+     * @param data The data to save
+     * @param options Save options
+     */
+    save?(type: string, name: string, data: any, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
 }
 //# sourceMappingURL=loader-interface.d.ts.map

package/dist/loaders/loader-interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader-interface.d.ts","sourceRoot":"","sources":["../../src/loaders/loader-interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAE1C;;;;;;OAMG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,GAAG,GAAG,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEhB;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErD;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAEhE;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvC"}
+{"version":3,"file":"loader-interface.d.ts","sourceRoot":"","sources":["../../src/loaders/loader-interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAE1C;;;;;;OAMG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,GAAG,GAAG,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEhB;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErD;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAEhE;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEtC;;;;;;OAMG;IACH,IAAI,CAAC,CACH,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,GAAG,EACT,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChC"}