@objectstack/metadata 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @objectstack/metadata
 
+## 0.9.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@0.9.2
+  - @objectstack/core@0.9.2
+  - @objectstack/types@0.9.2
+
+## 0.9.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements. All packages updated with unified versioning.
+- Updated dependencies
+  - @objectstack/spec@0.9.1
+  - @objectstack/core@0.9.1
+  - @objectstack/types@0.9.1
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -12,6 +12,13 @@ The `@objectstack/metadata` package provides a unified interface for managing me
 - **Caching** - ETag-based caching for performance optimization
 - **File Watching** - Development mode with automatic reload on file changes
 
+## 🤖 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
@@ -196,6 +203,256 @@ The metadata package is designed as a Layer 3 package in the ObjectStack archite
     └── @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/metadata",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Metadata loading, saving, and persistence for ObjectStack",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -16,9 +16,9 @@
     "js-yaml": "^4.1.0",
     "chokidar": "^3.5.3",
     "zod": "^4.3.6",
-    "@objectstack/core": "0.9.0",
-    "@objectstack/spec": "0.9.0",
-    "@objectstack/types": "0.9.0"
+    "@objectstack/core": "0.9.2",
+    "@objectstack/spec": "0.9.2",
+    "@objectstack/types": "0.9.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",