Add comprehensive workflow examples and plugin patterns to package READMEs

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/metadata/README.md

@@ -196,6 +196,244 @@ 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');
+  
+  // Add version metadata
+  const versioned = objects.map(obj => ({
+    ...obj,
+    metadata: {
+      ...obj.metadata,
+      version: '2.0.0',
+      lastModified: new Date().toISOString(),
+      modifiedBy: execSync('git config user.name').toString().trim()
+    }
+  }));
+  
+  // Save versioned metadata
+  for (const obj of versioned) {
+    await manager.save('object', obj.name, obj, {
+      format: 'typescript',
+      prettify: true
+    });
+  }
+  
+  // Commit to version control
+  execSync('git add metadata/');
+  execSync('git commit -m "Version bump to 2.0.0"');
+}
+```
+
+### 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