@memberjunction/metadata-sync 2.52.0 → 2.53.0

package/dist/lib/provider-utils.js

@@ -131,9 +131,10 @@ exports.cleanupProvider = cleanupProvider;
  *
  * Retrieves the "System" user from MemberJunction's UserCache. This user is
  * typically used for CLI operations where no specific user context exists.
+ * The System user must have the Developer role to perform metadata sync operations.
  *
  * @returns The System UserInfo object
- * @throws Error if System user is not found in the cache
+ * @throws Error if System user is not found in the cache or doesn't have Developer role
  *
  * @example
  * ```typescript
@@ -146,6 +147,14 @@ function getSystemUser() {
     if (!sysUser) {
         throw new Error("System user not found in cache. Ensure the system user exists in the database.");
     }
+    // Check if the System user has the Developer role
+    const hasDeveloperRole = sysUser.UserRoles && sysUser.UserRoles.some(userRole => userRole.Role.trim().toLowerCase() === 'developer');
+    if (!hasDeveloperRole) {
+        throw new Error("System user does not have the 'Developer' role. " +
+            "The Developer role is required for metadata sync operations. " +
+            "Please ensure the System user is assigned the Developer role in the database:\n" +
+            "* Add a record to the __mj.UserRole table linking the System user to the Developer role");
+    }
     return sysUser;
 }
 exports.getSystemUser = getSystemUser;
@@ -179,6 +188,7 @@ exports.getDataProvider = getDataProvider;
  * @param dir - Base directory to search from
  * @param specificDir - Optional specific subdirectory name to check
  * @param directoryOrder - Optional array specifying the order directories should be processed
+ * @param ignoreDirectories - Optional array of directory patterns to ignore
  * @returns Array of absolute directory paths containing .mj-sync.json files, ordered according to directoryOrder
  *
  * @example
@@ -193,7 +203,7 @@ exports.getDataProvider = getDataProvider;
  * const dirs = findEntityDirectories(process.cwd(), undefined, ['prompts', 'agent-types']);
  * ```
  */
-function findEntityDirectories(dir, specificDir, directoryOrder) {
+function findEntityDirectories(dir, specificDir, directoryOrder, ignoreDirectories) {
     const results = [];
     // If specific directory is provided, check if it's an entity directory or root config directory
     if (specificDir) {
@@ -212,7 +222,12 @@ function findEntityDirectories(dir, specificDir, directoryOrder) {
                     // If this config has directoryOrder but no entity, treat it as a root config
                     // and look for entity directories in its subdirectories
                     if (config.directoryOrder) {
-                        return findEntityDirectories(targetDir, undefined, config.directoryOrder);
+                        // Merge ignore directories from parent with current config
+                        const mergedIgnoreDirectories = [
+                            ...(ignoreDirectories || []),
+                            ...(config.ignoreDirectories || [])
+                        ];
+                        return findEntityDirectories(targetDir, undefined, config.directoryOrder, mergedIgnoreDirectories);
                     }
                 }
                 catch (error) {
@@ -220,7 +235,7 @@ function findEntityDirectories(dir, specificDir, directoryOrder) {
                 }
             }
             // Fallback: look for entity subdirectories in the target directory
-            return findEntityDirectories(targetDir, undefined, directoryOrder);
+            return findEntityDirectories(targetDir, undefined, directoryOrder, ignoreDirectories);
         }
         return results;
     }
@@ -229,6 +244,13 @@ function findEntityDirectories(dir, specificDir, directoryOrder) {
     const foundDirectories = [];
     for (const entry of entries) {
         if (entry.isDirectory() && !entry.name.startsWith('.')) {
+            // Check if this directory should be ignored
+            if (ignoreDirectories && ignoreDirectories.some(pattern => {
+                // Simple pattern matching: exact name or ends with pattern
+                return entry.name === pattern || entry.name.endsWith(pattern);
+            })) {
+                continue;
+            }
             const subDir = path.join(dir, entry.name);
             const hasSyncConfig = fs.existsSync(path.join(subDir, '.mj-sync.json'));
             if (hasSyncConfig) {

package/dist/lib/provider-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-utils.js","sourceRoot":"","sources":["../../src/lib/provider-utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @fileoverview Database provider utilities for MetadataSync\n * @module provider-utils\n * \n * This module provides utilities for initializing and managing the database\n * connection, accessing system users, and finding entity directories. It handles\n * the mssql ConnectionPool lifecycle and MemberJunction provider initialization.\n */\n\nimport * as sql from 'mssql';\nimport { SQLServerDataProvider, SQLServerProviderConfigData, UserCache, setupSQLServerClient } from '@memberjunction/sqlserver-dataprovider';\nimport type { MJConfig } from '../config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { UserInfo } from '@memberjunction/core';\nimport { configManager } from './config-manager';\n\n/** Global ConnectionPool instance for connection lifecycle management */\nlet globalPool: sql.ConnectionPool | null = null;\n\n/** Global provider instance to ensure single initialization */\nlet globalProvider: SQLServerDataProvider | null = null;\n\n/** Promise to track ongoing initialization */\nlet initializationPromise: Promise<SQLServerDataProvider> | null = null;\n\n/**\n * Initialize a SQLServerDataProvider with the given configuration\n * \n * Creates and initializes a mssql ConnectionPool for SQL Server, then sets up\n * the MemberJunction SQLServerDataProvider. The connection is stored globally\n * for proper cleanup. Auto-detects Azure SQL databases for encryption settings.\n * \n * @param config - MemberJunction configuration with database connection details\n * @returns Promise resolving to initialized SQLServerDataProvider instance\n * @throws Error if database connection fails\n * \n * @example\n * ```typescript\n * const config = loadMJConfig();\n * const provider = await initializeProvider(config);\n * // Provider is ready for use\n * ```\n */\nexport async function initializeProvider(config: MJConfig): Promise<SQLServerDataProvider> {\n  // Return existing provider if already initialized\n  if (globalProvider) {\n    return globalProvider;\n  }\n  \n  // Return ongoing initialization if in progress\n  if (initializationPromise) {\n    return initializationPromise;\n  }\n  \n  // Start new initialization\n  initializationPromise = (async () => {\n    // Create mssql config\n    const poolConfig: sql.config = {\n      server: config.dbHost,\n      port: config.dbPort ? Number(config.dbPort) : 1433,\n      database: config.dbDatabase,\n      user: config.dbUsername,\n      password: config.dbPassword,\n      options: {\n        encrypt: config.dbEncrypt === 'Y' || config.dbEncrypt === 'true' || \n                 config.dbHost.includes('.database.windows.net'), // Auto-detect Azure SQL\n        trustServerCertificate: config.dbTrustServerCertificate === 'Y',\n        instanceName: config.dbInstanceName,\n        enableArithAbort: true\n      }\n    };\n    \n    // Create and connect pool\n    const pool = new sql.ConnectionPool(poolConfig);\n    await pool.connect();\n    \n    // Store for cleanup\n    globalPool = pool;\n    \n    // Create provider config\n    const providerConfig = new SQLServerProviderConfigData(\n      pool,\n      config.mjCoreSchema || '__mj' \n    );\n    \n    // Use setupSQLServerClient to properly initialize\n    globalProvider = await setupSQLServerClient(providerConfig);\n    return globalProvider;\n  })();\n  \n  return initializationPromise;\n}\n\n/**\n * Clean up the global database connection\n * \n * Closes the mssql ConnectionPool if it exists and is connected.\n * Should be called when the CLI command completes to ensure proper cleanup.\n * \n * @returns Promise that resolves when cleanup is complete\n * \n * @example\n * ```typescript\n * try {\n *   // Do work with database\n * } finally {\n *   await cleanupProvider();\n * }\n * ```\n */\nexport async function cleanupProvider(): Promise<void> {\n  if (globalPool && globalPool.connected) {\n    await globalPool.close();\n    globalPool = null;\n  }\n  globalProvider = null;\n  initializationPromise = null;\n}\n\n/**\n * Get the system user from the UserCache\n * \n * Retrieves the \"System\" user from MemberJunction's UserCache. This user is\n * typically used for CLI operations where no specific user context exists.\n * \n * @returns The System UserInfo object\n * @throws Error if System user is not found in the cache\n * \n * @example\n * ```typescript\n * const systemUser = getSystemUser();\n * const syncEngine = new SyncEngine(systemUser);\n * ```\n */\nexport function getSystemUser(): UserInfo {\n  const sysUser = UserCache.Instance.UserByName(\"System\", false);\n  if (!sysUser) {\n    throw new Error(\"System user not found in cache. Ensure the system user exists in the database.\");    \n  }\n  return sysUser;\n}\n\n/**\n * Get the current data provider instance\n * \n * Returns the global SQLServerDataProvider instance that was initialized by\n * initializeProvider. This allows access to data provider features like SQL logging.\n * \n * @returns The global SQLServerDataProvider instance or null if not initialized\n * \n * @example\n * ```typescript\n * const provider = getDataProvider();\n * if (provider?.CreateSqlLogger) {\n *   const logger = await provider.CreateSqlLogger('/path/to/log.sql');\n * }\n * ```\n */\nexport function getDataProvider(): SQLServerDataProvider | null {\n  return globalProvider;\n}\n\n/**\n * Find entity directories at the immediate level only\n * \n * Searches for directories containing .mj-sync.json files, which indicate\n * entity data directories. Only searches immediate subdirectories, not recursive.\n * If a specific directory is provided, only checks that directory.\n * \n * @param dir - Base directory to search from\n * @param specificDir - Optional specific subdirectory name to check\n * @param directoryOrder - Optional array specifying the order directories should be processed\n * @returns Array of absolute directory paths containing .mj-sync.json files, ordered according to directoryOrder\n * \n * @example\n * ```typescript\n * // Find all entity directories\n * const dirs = findEntityDirectories(process.cwd());\n * \n * // Check specific directory\n * const dirs = findEntityDirectories(process.cwd(), 'ai-prompts');\n * \n * // Find directories with custom ordering\n * const dirs = findEntityDirectories(process.cwd(), undefined, ['prompts', 'agent-types']);\n * ```\n */\nexport function findEntityDirectories(dir: string, specificDir?: string, directoryOrder?: string[]): string[] {\n  const results: string[] = [];\n  \n  // If specific directory is provided, check if it's an entity directory or root config directory\n  if (specificDir) {\n    const targetDir = path.isAbsolute(specificDir) ? specificDir : path.join(dir, specificDir);\n    if (fs.existsSync(targetDir)) {\n      const syncConfigPath = path.join(targetDir, '.mj-sync.json');\n      const hasSyncConfig = fs.existsSync(syncConfigPath);\n      \n      if (hasSyncConfig) {\n        try {\n          const config = JSON.parse(fs.readFileSync(syncConfigPath, 'utf8'));\n          \n          // If this config has an entity field, it's an entity directory\n          if (config.entity) {\n            results.push(targetDir);\n            return results;\n          }\n          \n          // If this config has directoryOrder but no entity, treat it as a root config\n          // and look for entity directories in its subdirectories\n          if (config.directoryOrder) {\n            return findEntityDirectories(targetDir, undefined, config.directoryOrder);\n          }\n        } catch (error) {\n          // If we can't parse the config, treat it as a regular directory\n        }\n      }\n      \n      // Fallback: look for entity subdirectories in the target directory\n      return findEntityDirectories(targetDir, undefined, directoryOrder);\n    }\n    return results;\n  }\n  \n  // Otherwise, find all immediate subdirectories with .mj-sync.json\n  const entries = fs.readdirSync(dir, { withFileTypes: true });\n  const foundDirectories: string[] = [];\n  \n  for (const entry of entries) {\n    if (entry.isDirectory() && !entry.name.startsWith('.')) {\n      const subDir = path.join(dir, entry.name);\n      const hasSyncConfig = fs.existsSync(path.join(subDir, '.mj-sync.json'));\n      \n      if (hasSyncConfig) {\n        foundDirectories.push(subDir);\n      }\n    }\n  }\n  \n  // If directoryOrder is specified, sort directories according to it\n  if (directoryOrder && directoryOrder.length > 0) {\n    const orderedDirs: string[] = [];\n    const unorderedDirs: string[] = [];\n    \n    // First, add directories in the specified order\n    for (const dirName of directoryOrder) {\n      const matchingDir = foundDirectories.find(fullPath => \n        path.basename(fullPath) === dirName\n      );\n      if (matchingDir) {\n        orderedDirs.push(matchingDir);\n      }\n    }\n    \n    // Then, add any remaining directories in alphabetical order\n    for (const foundDir of foundDirectories) {\n      const dirName = path.basename(foundDir);\n      if (!directoryOrder.includes(dirName)) {\n        unorderedDirs.push(foundDir);\n      }\n    }\n    \n    // Sort unordered directories alphabetically\n    unorderedDirs.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));\n    \n    return [...orderedDirs, ...unorderedDirs];\n  }\n  \n  // No ordering specified, return in alphabetical order (existing behavior)\n  return foundDirectories.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));\n}"]}
+{"version":3,"file":"provider-utils.js","sourceRoot":"","sources":["../../src/lib/provider-utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @fileoverview Database provider utilities for MetadataSync\n * @module provider-utils\n * \n * This module provides utilities for initializing and managing the database\n * connection, accessing system users, and finding entity directories. It handles\n * the mssql ConnectionPool lifecycle and MemberJunction provider initialization.\n */\n\nimport * as sql from 'mssql';\nimport { SQLServerDataProvider, SQLServerProviderConfigData, UserCache, setupSQLServerClient } from '@memberjunction/sqlserver-dataprovider';\nimport type { MJConfig } from '../config';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { UserInfo } from '@memberjunction/core';\n\n/** Global ConnectionPool instance for connection lifecycle management */\nlet globalPool: sql.ConnectionPool | null = null;\n\n/** Global provider instance to ensure single initialization */\nlet globalProvider: SQLServerDataProvider | null = null;\n\n/** Promise to track ongoing initialization */\nlet initializationPromise: Promise<SQLServerDataProvider> | null = null;\n\n/**\n * Initialize a SQLServerDataProvider with the given configuration\n * \n * Creates and initializes a mssql ConnectionPool for SQL Server, then sets up\n * the MemberJunction SQLServerDataProvider. The connection is stored globally\n * for proper cleanup. Auto-detects Azure SQL databases for encryption settings.\n * \n * @param config - MemberJunction configuration with database connection details\n * @returns Promise resolving to initialized SQLServerDataProvider instance\n * @throws Error if database connection fails\n * \n * @example\n * ```typescript\n * const config = loadMJConfig();\n * const provider = await initializeProvider(config);\n * // Provider is ready for use\n * ```\n */\nexport async function initializeProvider(config: MJConfig): Promise<SQLServerDataProvider> {\n  // Return existing provider if already initialized\n  if (globalProvider) {\n    return globalProvider;\n  }\n  \n  // Return ongoing initialization if in progress\n  if (initializationPromise) {\n    return initializationPromise;\n  }\n  \n  // Start new initialization\n  initializationPromise = (async () => {\n    // Create mssql config\n    const poolConfig: sql.config = {\n      server: config.dbHost,\n      port: config.dbPort ? Number(config.dbPort) : 1433,\n      database: config.dbDatabase,\n      user: config.dbUsername,\n      password: config.dbPassword,\n      options: {\n        encrypt: config.dbEncrypt === 'Y' || config.dbEncrypt === 'true' || \n                 config.dbHost.includes('.database.windows.net'), // Auto-detect Azure SQL\n        trustServerCertificate: config.dbTrustServerCertificate === 'Y',\n        instanceName: config.dbInstanceName,\n        enableArithAbort: true\n      }\n    };\n    \n    // Create and connect pool\n    const pool = new sql.ConnectionPool(poolConfig);\n    await pool.connect();\n    \n    // Store for cleanup\n    globalPool = pool;\n    \n    // Create provider config\n    const providerConfig = new SQLServerProviderConfigData(\n      pool,\n      config.mjCoreSchema || '__mj' \n    );\n    \n    // Use setupSQLServerClient to properly initialize\n    globalProvider = await setupSQLServerClient(providerConfig);\n    return globalProvider;\n  })();\n  \n  return initializationPromise;\n}\n\n/**\n * Clean up the global database connection\n * \n * Closes the mssql ConnectionPool if it exists and is connected.\n * Should be called when the CLI command completes to ensure proper cleanup.\n * \n * @returns Promise that resolves when cleanup is complete\n * \n * @example\n * ```typescript\n * try {\n *   // Do work with database\n * } finally {\n *   await cleanupProvider();\n * }\n * ```\n */\nexport async function cleanupProvider(): Promise<void> {\n  if (globalPool && globalPool.connected) {\n    await globalPool.close();\n    globalPool = null;\n  }\n  globalProvider = null;\n  initializationPromise = null;\n}\n\n/**\n * Get the system user from the UserCache\n * \n * Retrieves the \"System\" user from MemberJunction's UserCache. This user is\n * typically used for CLI operations where no specific user context exists.\n * The System user must have the Developer role to perform metadata sync operations.\n * \n * @returns The System UserInfo object\n * @throws Error if System user is not found in the cache or doesn't have Developer role\n * \n * @example\n * ```typescript\n * const systemUser = getSystemUser();\n * const syncEngine = new SyncEngine(systemUser);\n * ```\n */\nexport function getSystemUser(): UserInfo {\n  const sysUser = UserCache.Instance.UserByName(\"System\", false);\n  if (!sysUser) {\n    throw new Error(\"System user not found in cache. Ensure the system user exists in the database.\");    \n  }\n  \n  // Check if the System user has the Developer role\n  const hasDeveloperRole = sysUser.UserRoles && sysUser.UserRoles.some(\n    userRole => userRole.Role.trim().toLowerCase() === 'developer'\n  );\n  \n  if (!hasDeveloperRole) {\n    throw new Error(\n      \"System user does not have the 'Developer' role. \" +\n      \"The Developer role is required for metadata sync operations. \" +\n      \"Please ensure the System user is assigned the Developer role in the database:\\n\" +\n      \"* Add a record to the __mj.UserRole table linking the System user to the Developer role\"\n    );\n  }\n  \n  return sysUser;\n}\n\n/**\n * Get the current data provider instance\n * \n * Returns the global SQLServerDataProvider instance that was initialized by\n * initializeProvider. This allows access to data provider features like SQL logging.\n * \n * @returns The global SQLServerDataProvider instance or null if not initialized\n * \n * @example\n * ```typescript\n * const provider = getDataProvider();\n * if (provider?.CreateSqlLogger) {\n *   const logger = await provider.CreateSqlLogger('/path/to/log.sql');\n * }\n * ```\n */\nexport function getDataProvider(): SQLServerDataProvider | null {\n  return globalProvider;\n}\n\n/**\n * Find entity directories at the immediate level only\n * \n * Searches for directories containing .mj-sync.json files, which indicate\n * entity data directories. Only searches immediate subdirectories, not recursive.\n * If a specific directory is provided, only checks that directory.\n * \n * @param dir - Base directory to search from\n * @param specificDir - Optional specific subdirectory name to check\n * @param directoryOrder - Optional array specifying the order directories should be processed\n * @param ignoreDirectories - Optional array of directory patterns to ignore\n * @returns Array of absolute directory paths containing .mj-sync.json files, ordered according to directoryOrder\n * \n * @example\n * ```typescript\n * // Find all entity directories\n * const dirs = findEntityDirectories(process.cwd());\n * \n * // Check specific directory\n * const dirs = findEntityDirectories(process.cwd(), 'ai-prompts');\n * \n * // Find directories with custom ordering\n * const dirs = findEntityDirectories(process.cwd(), undefined, ['prompts', 'agent-types']);\n * ```\n */\nexport function findEntityDirectories(dir: string, specificDir?: string, directoryOrder?: string[], ignoreDirectories?: string[]): string[] {\n  const results: string[] = [];\n  \n  // If specific directory is provided, check if it's an entity directory or root config directory\n  if (specificDir) {\n    const targetDir = path.isAbsolute(specificDir) ? specificDir : path.join(dir, specificDir);\n    if (fs.existsSync(targetDir)) {\n      const syncConfigPath = path.join(targetDir, '.mj-sync.json');\n      const hasSyncConfig = fs.existsSync(syncConfigPath);\n      \n      if (hasSyncConfig) {\n        try {\n          const config = JSON.parse(fs.readFileSync(syncConfigPath, 'utf8'));\n          \n          // If this config has an entity field, it's an entity directory\n          if (config.entity) {\n            results.push(targetDir);\n            return results;\n          }\n          \n          // If this config has directoryOrder but no entity, treat it as a root config\n          // and look for entity directories in its subdirectories\n          if (config.directoryOrder) {\n            // Merge ignore directories from parent with current config\n            const mergedIgnoreDirectories = [\n              ...(ignoreDirectories || []),\n              ...(config.ignoreDirectories || [])\n            ];\n            return findEntityDirectories(targetDir, undefined, config.directoryOrder, mergedIgnoreDirectories);\n          }\n        } catch (error) {\n          // If we can't parse the config, treat it as a regular directory\n        }\n      }\n      \n      // Fallback: look for entity subdirectories in the target directory\n      return findEntityDirectories(targetDir, undefined, directoryOrder, ignoreDirectories);\n    }\n    return results;\n  }\n  \n  // Otherwise, find all immediate subdirectories with .mj-sync.json\n  const entries = fs.readdirSync(dir, { withFileTypes: true });\n  const foundDirectories: string[] = [];\n  \n  for (const entry of entries) {\n    if (entry.isDirectory() && !entry.name.startsWith('.')) {\n      // Check if this directory should be ignored\n      if (ignoreDirectories && ignoreDirectories.some(pattern => {\n        // Simple pattern matching: exact name or ends with pattern\n        return entry.name === pattern || entry.name.endsWith(pattern);\n      })) {\n        continue;\n      }\n      \n      const subDir = path.join(dir, entry.name);\n      const hasSyncConfig = fs.existsSync(path.join(subDir, '.mj-sync.json'));\n      \n      if (hasSyncConfig) {\n        foundDirectories.push(subDir);\n      }\n    }\n  }\n  \n  // If directoryOrder is specified, sort directories according to it\n  if (directoryOrder && directoryOrder.length > 0) {\n    const orderedDirs: string[] = [];\n    const unorderedDirs: string[] = [];\n    \n    // First, add directories in the specified order\n    for (const dirName of directoryOrder) {\n      const matchingDir = foundDirectories.find(fullPath => \n        path.basename(fullPath) === dirName\n      );\n      if (matchingDir) {\n        orderedDirs.push(matchingDir);\n      }\n    }\n    \n    // Then, add any remaining directories in alphabetical order\n    for (const foundDir of foundDirectories) {\n      const dirName = path.basename(foundDir);\n      if (!directoryOrder.includes(dirName)) {\n        unorderedDirs.push(foundDir);\n      }\n    }\n    \n    // Sort unordered directories alphabetically\n    unorderedDirs.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));\n    \n    return [...orderedDirs, ...unorderedDirs];\n  }\n  \n  // No ordering specified, return in alphabetical order (existing behavior)\n  return foundDirectories.sort((a, b) => path.basename(a).localeCompare(path.basename(b)));\n}"]}

package/dist/lib/sync-engine.d.ts

@@ -104,7 +104,10 @@ export declare class SyncEngine {
      * });
      * ```
      */
-    resolveLookup(entityName: string, fieldName: string, fieldValue: string, autoCreate?: boolean, createFields?: Record<string, any>): Promise<string>;
+    resolveLookup(entityName: string, lookupFields: Array<{
+        fieldName: string;
+        fieldValue: string;
+    }>, autoCreate?: boolean, createFields?: Record<string, any>): Promise<string>;
     /**
      * Build cascading defaults for a file path and process field values
      *

package/dist/lib/sync-engine.js

@@ -124,7 +124,7 @@ class SyncEngine {
         if (value.startsWith('@lookup:')) {
             const lookupStr = value.substring(8);
             // Parse lookup with optional create syntax
-            // Format: EntityName.FieldName=Value?create&OtherField=Value
+            // Format: EntityName.Field1=Value1&Field2=Value2?create&OtherField=Value
             const entityMatch = lookupStr.match(/^([^.]+)\./);
             if (!entityMatch) {
                 throw new Error(`Invalid lookup format: ${value}`);
@@ -134,12 +134,20 @@ class SyncEngine {
             // Check if this has ?create syntax
             const hasCreate = remaining.includes('?create');
             const lookupPart = hasCreate ? remaining.split('?')[0] : remaining;
-            // Parse the main lookup field
-            const fieldMatch = lookupPart.match(/^(.+?)=(.+)$/);
-            if (!fieldMatch) {
-                throw new Error(`Invalid lookup format: ${value}`);
+            // Parse all lookup fields (can be multiple with &)
+            const lookupFields = [];
+            const lookupPairs = lookupPart.split('&');
+            for (const pair of lookupPairs) {
+                const fieldMatch = pair.match(/^(.+?)=(.+)$/);
+                if (!fieldMatch) {
+                    throw new Error(`Invalid lookup field format: ${pair} in ${value}`);
+                }
+                const [, fieldName, fieldValue] = fieldMatch;
+                lookupFields.push({ fieldName: fieldName.trim(), fieldValue: fieldValue.trim() });
+            }
+            if (lookupFields.length === 0) {
+                throw new Error(`No lookup fields specified: ${value}`);
             }
-            const [, fieldName, fieldValue] = fieldMatch;
             // Parse additional fields for creation if ?create is present
             let createFields = {};
             if (hasCreate && remaining.includes('?create&')) {
@@ -152,7 +160,7 @@ class SyncEngine {
                     }
                 }
             }
-            return await this.resolveLookup(entityName, fieldName, fieldValue, hasCreate, createFields);
+            return await this.resolveLookup(entityName, lookupFields, hasCreate, createFields);
         }
         // Check for @env: reference
         if (value.startsWith('@env:')) {
@@ -188,18 +196,33 @@ class SyncEngine {
      * });
      * ```
      */
-    async resolveLookup(entityName, fieldName, fieldValue, autoCreate = false, createFields = {}) {
+    async resolveLookup(entityName, lookupFields, autoCreate = false, createFields = {}) {
         // Debug logging handled by caller if needed
         const rv = new core_1.RunView();
         const entityInfo = this.metadata.EntityByName(entityName);
         if (!entityInfo) {
             throw new Error(`Entity not found: ${entityName}`);
         }
-        const field = entityInfo.Fields.find(f => f.Name.trim().toLowerCase() === fieldName.trim().toLowerCase());
-        const quotes = field?.NeedsQuotes ? "'" : '';
+        // Build compound filter for all lookup fields
+        const filterParts = [];
+        for (const { fieldName, fieldValue } of lookupFields) {
+            const field = entityInfo.Fields.find(f => f.Name.trim().toLowerCase() === fieldName.trim().toLowerCase());
+            if (!field) {
+                throw new Error(`Field '${fieldName}' not found in entity '${entityName}'`);
+            }
+            // Handle null values properly
+            if (fieldValue.trim().toLowerCase() === 'null') {
+                filterParts.push(`${fieldName} IS NULL`);
+            }
+            else {
+                const quotes = field.NeedsQuotes ? "'" : '';
+                filterParts.push(`${fieldName} = ${quotes}${fieldValue.replace(/'/g, "''")}${quotes}`);
+            }
+        }
+        const extraFilter = filterParts.join(' AND ');
         const result = await rv.RunView({
             EntityName: entityName,
-            ExtraFilter: `${fieldName} = ${quotes}${fieldValue.replace(/'/g, "''")}${quotes}`,
+            ExtraFilter: extraFilter,
             MaxRows: 1
         }, this.contextUser);
         if (result.Success && result.Results.length > 0) {
@@ -226,9 +249,17 @@ class SyncEngine {
                     }
                 }
             }
-            // Set the lookup field
-            if (fieldName in newEntity) {
-                newEntity[fieldName] = fieldValue;
+            // Set all lookup fields
+            for (const { fieldName, fieldValue } of lookupFields) {
+                if (fieldName in newEntity) {
+                    // Handle null values properly
+                    if (fieldValue.toLowerCase() === 'null') {
+                        newEntity[fieldName] = null;
+                    }
+                    else {
+                        newEntity[fieldName] = fieldValue;
+                    }
+                }
             }
             // Set any additional fields provided
             for (const [key, value] of Object.entries(createFields)) {
@@ -237,7 +268,8 @@ class SyncEngine {
                 }
             }
             // Save the new record (new records are always dirty)
-            console.log(`📝 Auto-creating ${entityName} record where ${fieldName}='${fieldValue}'`);
+            const filterDesc = lookupFields.map(({ fieldName, fieldValue }) => `${fieldName}='${fieldValue}'`).join(' AND ');
+            console.log(`📝 Auto-creating ${entityName} record where ${filterDesc}`);
             const saved = await newEntity.Save();
             if (!saved) {
                 const message = newEntity.LatestResult?.Message;
@@ -254,7 +286,8 @@ class SyncEngine {
                 return newId;
             }
         }
-        throw new Error(`Lookup failed: No record found in '${entityName}' where ${fieldName}='${fieldValue}'`);
+        const filterDesc = lookupFields.map(({ fieldName, fieldValue }) => `${fieldName}='${fieldValue}'`).join(' AND ');
+        throw new Error(`Lookup failed: No record found in '${entityName}' where ${filterDesc}`);
     }
     /**
      * Build cascading defaults for a file path and process field values

package/dist/lib/sync-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-engine.js","sourceRoot":"","sources":["../../src/lib/sync-engine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @fileoverview Core synchronization engine for MemberJunction metadata\n * @module sync-engine\n * \n * This module provides the core functionality for synchronizing metadata between\n * the MemberJunction database and local file system representations. It handles\n * special reference types (@file, @url, @lookup, @env, @parent, @root, @template),\n * manages entity operations, and provides utilities for data transformation.\n */\n\nimport path from 'path';\nimport fs from 'fs-extra';\nimport crypto from 'crypto';\nimport axios from 'axios';\nimport { EntityInfo, Metadata, RunView, BaseEntity, CompositeKey, UserInfo } from '@memberjunction/core';\nimport { uuidv4 } from '@memberjunction/global';\nimport { EntityConfig, FolderConfig } from '../config';\n\n/**\n * Represents the structure of a metadata record with optional sync tracking\n */\nexport interface RecordData {\n  /** Primary key field(s) and their values */\n  primaryKey?: Record<string, any>;\n  /** Entity field names and their values */\n  fields: Record<string, any>;\n  /** Related entities organized by entity name */\n  relatedEntities?: Record<string, RecordData[]>;\n  /** Synchronization metadata for change tracking */\n  sync?: {\n    /** ISO timestamp of last modification */\n    lastModified: string;\n    /** SHA256 checksum of the fields object */\n    checksum: string;\n  };\n}\n\n/**\n * Core engine for synchronizing MemberJunction metadata between database and files\n * \n * @class SyncEngine\n * @example\n * ```typescript\n * const syncEngine = new SyncEngine(systemUser);\n * await syncEngine.initialize();\n * \n * // Process a field value with special references\n * const value = await syncEngine.processFieldValue('@lookup:Users.Email=admin@example.com', '/path/to/base');\n * ```\n */\nexport class SyncEngine {\n  private metadata: Metadata;\n  private contextUser: UserInfo;\n\n  /**\n   * Creates a new SyncEngine instance\n   * @param contextUser - The user context for database operations\n   */\n  constructor(contextUser: UserInfo) {\n    this.metadata = new Metadata();\n    this.contextUser = contextUser;\n  }\n  \n  /**\n   * Initializes the sync engine by refreshing metadata cache\n   * @returns Promise that resolves when initialization is complete\n   */\n  async initialize(): Promise<void> {\n    // Initialize metadata\n    await this.metadata.Refresh();\n  }\n  \n  /**\n   * Process special references in field values\n   * \n   * Handles the following reference types:\n   * - `@parent:fieldName` - References a field from the parent record\n   * - `@root:fieldName` - References a field from the root record\n   * - `@file:path` - Reads content from an external file\n   * - `@url:address` - Fetches content from a URL\n   * - `@lookup:Entity.Field=Value` - Looks up an entity ID by field value\n   * - `@env:VARIABLE` - Reads an environment variable\n   * \n   * @param value - The field value to process\n   * @param baseDir - Base directory for resolving relative file paths\n   * @param parentRecord - Optional parent entity for @parent references\n   * @param rootRecord - Optional root entity for @root references\n   * @returns The processed value with all references resolved\n   * @throws Error if a reference cannot be resolved\n   * \n   * @example\n   * ```typescript\n   * // File reference\n   * const content = await processFieldValue('@file:template.md', '/path/to/dir');\n   * \n   * // Lookup with auto-create\n   * const userId = await processFieldValue('@lookup:Users.Email=john@example.com?create', '/path');\n   * ```\n   */\n  async processFieldValue(value: any, baseDir: string, parentRecord?: BaseEntity | null, rootRecord?: BaseEntity | null): Promise<any> {\n    if (typeof value !== 'string') {\n      return value;\n    }\n    \n    // Check for @parent: reference\n    if (value.startsWith('@parent:')) {\n      if (!parentRecord) {\n        throw new Error(`@parent reference used but no parent record available: ${value}`);\n      }\n      const fieldName = value.substring(8);\n      return parentRecord.Get(fieldName);\n    }\n    \n    // Check for @root: reference\n    if (value.startsWith('@root:')) {\n      if (!rootRecord) {\n        throw new Error(`@root reference used but no root record available: ${value}`);\n      }\n      const fieldName = value.substring(6);\n      return rootRecord.Get(fieldName);\n    }\n    \n    // Check for @file: reference\n    if (value.startsWith('@file:')) {\n      const filePath = value.substring(6);\n      const fullPath = path.resolve(baseDir, filePath);\n      \n      if (await fs.pathExists(fullPath)) {\n        return await fs.readFile(fullPath, 'utf-8');\n      } else {\n        throw new Error(`File not found: ${fullPath}`);\n      }\n    }\n    \n    // Check for @url: reference\n    if (value.startsWith('@url:')) {\n      const url = value.substring(5);\n      \n      try {\n        const response = await axios.get(url);\n        return response.data;\n      } catch (error) {\n        throw new Error(`Failed to fetch URL: ${url} - ${error}`);\n      }\n    }\n    \n    // Check for @lookup: reference\n    if (value.startsWith('@lookup:')) {\n      const lookupStr = value.substring(8);\n      \n      // Parse lookup with optional create syntax\n      // Format: EntityName.FieldName=Value?create&OtherField=Value\n      const entityMatch = lookupStr.match(/^([^.]+)\\./);\n      if (!entityMatch) {\n        throw new Error(`Invalid lookup format: ${value}`);\n      }\n      \n      const entityName = entityMatch[1];\n      const remaining = lookupStr.substring(entityName.length + 1);\n      \n      // Check if this has ?create syntax\n      const hasCreate = remaining.includes('?create');\n      const lookupPart = hasCreate ? remaining.split('?')[0] : remaining;\n      \n      // Parse the main lookup field\n      const fieldMatch = lookupPart.match(/^(.+?)=(.+)$/);\n      if (!fieldMatch) {\n        throw new Error(`Invalid lookup format: ${value}`);\n      }\n      \n      const [, fieldName, fieldValue] = fieldMatch;\n      \n      // Parse additional fields for creation if ?create is present\n      let createFields: Record<string, any> = {};\n      if (hasCreate && remaining.includes('?create&')) {\n        const createPart = remaining.split('?create&')[1];\n        const pairs = createPart.split('&');\n        for (const pair of pairs) {\n          const [key, val] = pair.split('=');\n          if (key && val) {\n            createFields[key] = decodeURIComponent(val);\n          }\n        }\n      }\n      \n      return await this.resolveLookup(entityName, fieldName, fieldValue, hasCreate, createFields);\n    }\n    \n    // Check for @env: reference\n    if (value.startsWith('@env:')) {\n      const envVar = value.substring(5);\n      const envValue = process.env[envVar];\n      \n      if (envValue === undefined) {\n        throw new Error(`Environment variable not found: ${envVar}`);\n      }\n      \n      return envValue;\n    }\n    \n    return value;\n  }\n  \n  /**\n   * Resolve a lookup reference to an ID, optionally creating the record if it doesn't exist\n   * \n   * @param entityName - Name of the entity to search in\n   * @param fieldName - Field to match against\n   * @param fieldValue - Value to search for\n   * @param autoCreate - Whether to create the record if not found\n   * @param createFields - Additional fields to set when creating\n   * @returns The ID of the found or created record\n   * @throws Error if lookup fails and autoCreate is false\n   * \n   * @example\n   * ```typescript\n   * // Simple lookup\n   * const categoryId = await resolveLookup('Categories', 'Name', 'Technology');\n   * \n   * // Lookup with auto-create\n   * const tagId = await resolveLookup('Tags', 'Name', 'New Tag', true, {\n   *   Description: 'Auto-created tag',\n   *   Status: 'Active'\n   * });\n   * ```\n   */\n  async resolveLookup(\n    entityName: string, \n    fieldName: string, \n    fieldValue: string,\n    autoCreate: boolean = false,\n    createFields: Record<string, any> = {}\n  ): Promise<string> {\n    // Debug logging handled by caller if needed\n    \n    const rv = new RunView();\n    const entityInfo = this.metadata.EntityByName(entityName);\n    if (!entityInfo) {\n      throw new Error(`Entity not found: ${entityName}`);\n    }\n    \n    const field = entityInfo.Fields.find(f => f.Name.trim().toLowerCase() === fieldName.trim().toLowerCase());\n    const quotes = field?.NeedsQuotes ? \"'\" : '';\n    const result = await rv.RunView({\n      EntityName: entityName,\n      ExtraFilter: `${fieldName} = ${quotes}${fieldValue.replace(/'/g, \"''\")}${quotes}`,\n      MaxRows: 1\n    }, this.contextUser);\n    \n    if (result.Success && result.Results.length > 0) {\n      if (entityInfo.PrimaryKeys.length > 0) {\n        const pkeyField = entityInfo.PrimaryKeys[0].Name;\n        const id = result.Results[0][pkeyField];\n        return id;\n      }\n    }\n    \n    // If not found and auto-create is enabled, create the record\n    if (autoCreate) {\n      \n      const newEntity = await this.metadata.GetEntityObject(entityName, this.contextUser);\n      if (!newEntity) {\n        throw new Error(`Failed to create entity object for: ${entityName}`);\n      }\n      \n      newEntity.NewRecord();\n      \n      // Handle explicit ID setting for new records\n      if (entityInfo.PrimaryKeys.length > 0) {\n        for (const pk of entityInfo.PrimaryKeys) {\n          if (!pk.AutoIncrement && pk.Type.toLowerCase() === 'uniqueidentifier') {\n            // Generate UUID for this primary key and set it explicitly\n            const uuid = uuidv4();\n            (newEntity as any)[pk.Name] = uuid;\n          }\n        }\n      }\n      \n      // Set the lookup field\n      if (fieldName in newEntity) {\n        (newEntity as any)[fieldName] = fieldValue;\n      }\n      \n      // Set any additional fields provided\n      for (const [key, value] of Object.entries(createFields)) {\n        if (key in newEntity) {\n          (newEntity as any)[key] = value;\n        }\n      }\n      \n      // Save the new record (new records are always dirty)\n      console.log(`📝 Auto-creating ${entityName} record where ${fieldName}='${fieldValue}'`);\n      const saved = await newEntity.Save();\n      if (!saved) {\n        const message = newEntity.LatestResult?.Message;\n        if (message) {\n          throw new Error(`Failed to auto-create ${entityName}: ${message}`);\n        }\n        \n        const errors = newEntity.LatestResult?.Errors?.map(err => \n          typeof err === 'string' ? err : (err?.message || JSON.stringify(err))\n        )?.join(', ') || 'Unknown error';\n        throw new Error(`Failed to auto-create ${entityName}: ${errors}`);\n      }\n      \n      // Return the new ID\n      if (entityInfo.PrimaryKeys.length > 0) {\n        const pkeyField = entityInfo.PrimaryKeys[0].Name;\n        const newId = newEntity.Get(pkeyField);\n        return newId;\n      }\n    }\n    \n    throw new Error(`Lookup failed: No record found in '${entityName}' where ${fieldName}='${fieldValue}'`);\n  }\n  \n  /**\n   * Build cascading defaults for a file path and process field values\n   * \n   * Walks up the directory tree from the file location, collecting defaults from\n   * entity config and folder configs, with deeper folders overriding parent values.\n   * All default values are processed for special references.\n   * \n   * @param filePath - Path to the file being processed\n   * @param entityConfig - Entity configuration containing base defaults\n   * @returns Processed defaults with all references resolved\n   * @throws Error if any default value processing fails\n   */\n  async buildDefaults(filePath: string, entityConfig: EntityConfig): Promise<Record<string, any>> {\n    const parts = path.dirname(filePath).split(path.sep);\n    let defaults: Record<string, any> = { ...entityConfig.defaults };\n    \n    // Walk up the directory tree building defaults\n    let currentPath = '';\n    for (const part of parts) {\n      currentPath = path.join(currentPath, part);\n      const folderConfig = await this.loadFolderConfig(currentPath);\n      \n      if (folderConfig?.defaults) {\n        defaults = { ...defaults, ...folderConfig.defaults };\n      }\n    }\n    \n    // Process all default values (lookups, file references, etc.)\n    const processedDefaults: Record<string, any> = {};\n    const baseDir = path.dirname(filePath);\n    \n    for (const [field, value] of Object.entries(defaults)) {\n      try {\n        processedDefaults[field] = await this.processFieldValue(value, baseDir, null, null);\n      } catch (error) {\n        throw new Error(`Failed to process default for field '${field}': ${error}`);\n      }\n    }\n    \n    return processedDefaults;\n  }\n  \n  /**\n   * Load folder configuration from .mj-folder.json file\n   * \n   * @param dir - Directory to check for configuration\n   * @returns Folder configuration or null if not found/invalid\n   * @private\n   */\n  private async loadFolderConfig(dir: string): Promise<FolderConfig | null> {\n    const configPath = path.join(dir, '.mj-folder.json');\n    \n    if (await fs.pathExists(configPath)) {\n      try {\n        return await fs.readJson(configPath);\n      } catch (error) {\n        console.error(`Error loading folder config at ${configPath}:`, error);\n        return null;\n      }\n    }\n    \n    return null;\n  }\n  \n  /**\n   * Calculate SHA256 checksum for data\n   * \n   * Generates a deterministic hash of the provided data by converting it to\n   * formatted JSON and calculating a SHA256 digest. Used for change detection\n   * in sync operations.\n   * \n   * @param data - Any data structure to calculate checksum for\n   * @returns Hexadecimal string representation of the SHA256 hash\n   * \n   * @example\n   * ```typescript\n   * const checksum = syncEngine.calculateChecksum({\n   *   name: 'Test Record',\n   *   value: 42,\n   *   tags: ['a', 'b']\n   * });\n   * // Returns consistent hash for same data structure\n   * ```\n   */\n  calculateChecksum(data: any): string {\n    const hash = crypto.createHash('sha256');\n    hash.update(JSON.stringify(data, null, 2));\n    return hash.digest('hex');\n  }\n  \n  /**\n   * Get entity metadata information by name\n   * \n   * Retrieves the EntityInfo object containing schema metadata for the specified entity.\n   * Returns null if the entity is not found in the metadata cache.\n   * \n   * @param entityName - Name of the entity to look up\n   * @returns EntityInfo object with schema details or null if not found\n   * \n   * @example\n   * ```typescript\n   * const entityInfo = syncEngine.getEntityInfo('AI Prompts');\n   * if (entityInfo) {\n   *   console.log(`Primary keys: ${entityInfo.PrimaryKeys.map(pk => pk.Name).join(', ')}`);\n   * }\n   * ```\n   */\n  getEntityInfo(entityName: string): EntityInfo | null {\n    return this.metadata.EntityByName(entityName);\n  }\n  \n  /**\n   * Create a new entity object instance\n   * \n   * Uses the MemberJunction metadata system to properly instantiate an entity object.\n   * This ensures correct class registration and respects any custom entity subclasses.\n   * \n   * @param entityName - Name of the entity to create\n   * @returns Promise resolving to the new BaseEntity instance\n   * @throws Error if entity creation fails\n   * \n   * @example\n   * ```typescript\n   * const entity = await syncEngine.createEntityObject('AI Prompts');\n   * entity.NewRecord();\n   * entity.Set('Name', 'My Prompt');\n   * await entity.Save();\n   * ```\n   */\n  async createEntityObject(entityName: string): Promise<BaseEntity> {\n    const entity = await this.metadata.GetEntityObject(entityName, this.contextUser);\n    if (!entity) {\n      throw new Error(`Failed to create entity object for: ${entityName}`);\n    }\n    return entity;\n  }\n  \n  /**\n   * Load an entity record by primary key\n   * \n   * Retrieves an existing entity record from the database using its primary key values.\n   * Supports both single and composite primary keys. Returns null if the record is not found.\n   * \n   * @param entityName - Name of the entity to load\n   * @param primaryKey - Object containing primary key field names and values\n   * @returns Promise resolving to the loaded entity or null if not found\n   * @throws Error if entity metadata is not found\n   * \n   * @example\n   * ```typescript\n   * // Single primary key\n   * const entity = await syncEngine.loadEntity('Users', { ID: '123-456' });\n   * \n   * // Composite primary key\n   * const entity = await syncEngine.loadEntity('UserRoles', { \n   *   UserID: '123-456',\n   *   RoleID: '789-012'\n   * });\n   * ```\n   */\n  async loadEntity(entityName: string, primaryKey: Record<string, any>): Promise<BaseEntity | null> {\n    const entityInfo = this.getEntityInfo(entityName);\n    \n    if (!entityInfo) {\n      throw new Error(`Entity not found: ${entityName}`);\n    }\n    \n    // First, check if the record exists using RunView to avoid \"Error in BaseEntity.Load\" messages\n    // when records don't exist (which is a normal scenario during sync operations)\n    const rv = new RunView();\n    \n    // Build filter for primary key(s)\n    const filters: string[] = [];\n    for (const pk of entityInfo.PrimaryKeys) {\n      const value = primaryKey[pk.Name];\n      if (value === undefined || value === null) {\n        throw new Error(`Missing primary key value for ${pk.Name} in entity ${entityName}`);\n      }\n      \n      // Check if field needs quotes\n      const field = entityInfo.Fields.find(f => f.Name === pk.Name);\n      const quotes = field?.NeedsQuotes ? \"'\" : '';\n      const escapedValue = field?.NeedsQuotes && typeof value === 'string' ? value.replace(/'/g, \"''\") : value;\n      filters.push(`${pk.Name} = ${quotes}${escapedValue}${quotes}`);\n    }\n    \n    const result = await rv.RunView({\n      EntityName: entityName,\n      ExtraFilter: filters.join(' AND '),\n      MaxRows: 1\n    }, this.contextUser);\n    \n    // If no record found, return null without attempting to load\n    if (!result.Success || result.Results.length === 0) {\n      return null;\n    }\n    \n    // Record exists, now load it properly through the entity\n    const entity = await this.createEntityObject(entityName);\n    const compositeKey = new CompositeKey();\n    compositeKey.LoadFromSimpleObject(primaryKey);\n    const loaded = await entity.InnerLoad(compositeKey);\n    \n    return loaded ? entity : null;\n  }\n  \n  /**\n   * Process JSON object with template references\n   * \n   * Recursively processes JSON data structures to resolve `@template` references.\n   * Templates can be defined at any level and support:\n   * - Single template references: `\"@template:path/to/template.json\"`\n   * - Object with @template field: `{ \"@template\": \"file.json\", \"override\": \"value\" }`\n   * - Array of templates for merging: `{ \"@template\": [\"base.json\", \"overrides.json\"] }`\n   * - Nested template references within templates\n   * \n   * @param data - JSON data structure to process\n   * @param baseDir - Base directory for resolving relative template paths\n   * @returns Promise resolving to the processed data with all templates resolved\n   * @throws Error if template file is not found or contains invalid JSON\n   * \n   * @example\n   * ```typescript\n   * // Input data with template reference\n   * const data = {\n   *   \"@template\": \"defaults/ai-prompt.json\",\n   *   \"Name\": \"Custom Prompt\",\n   *   \"Prompt\": \"Override the template prompt\"\n   * };\n   * \n   * // Resolves template and merges with overrides\n   * const result = await syncEngine.processTemplates(data, '/path/to/dir');\n   * ```\n   */\n  async processTemplates(data: any, baseDir: string): Promise<any> {\n    // Handle arrays\n    if (Array.isArray(data)) {\n      const processedArray = [];\n      for (const item of data) {\n        processedArray.push(await this.processTemplates(item, baseDir));\n      }\n      return processedArray;\n    }\n    \n    // Handle objects\n    if (data && typeof data === 'object') {\n      // Check for @template reference\n      if (typeof data === 'string' && data.startsWith('@template:')) {\n        const templatePath = data.substring(10);\n        return await this.loadAndProcessTemplate(templatePath, baseDir);\n      }\n      \n      // Process object with possible @template field\n      const processed: any = {};\n      let templateData: any = {};\n      \n      // First, check if there's a @template field to process\n      if (data['@template']) {\n        const templates = Array.isArray(data['@template']) ? data['@template'] : [data['@template']];\n        \n        // Process templates in order, merging them\n        for (const templateRef of templates) {\n          const templateContent = await this.loadAndProcessTemplate(templateRef, baseDir);\n          templateData = this.deepMerge(templateData, templateContent);\n        }\n      }\n      \n      // Process all other fields\n      for (const [key, value] of Object.entries(data)) {\n        if (key === '@template') continue; // Skip the template field itself\n        \n        // Process the value recursively\n        processed[key] = await this.processTemplates(value, baseDir);\n      }\n      \n      // Merge template data with processed data (processed data takes precedence)\n      return this.deepMerge(templateData, processed);\n    }\n    \n    // Return primitive values as-is\n    return data;\n  }\n  \n  /**\n   * Load and process a template file\n   * \n   * Loads a JSON template file from the filesystem and recursively processes any\n   * nested template references within it. Template paths are resolved relative to\n   * the template file's directory, enabling template composition.\n   * \n   * @param templatePath - Path to the template file (relative or absolute)\n   * @param baseDir - Base directory for resolving relative paths\n   * @returns Promise resolving to the processed template content\n   * @throws Error if template file not found or contains invalid JSON\n   * @private\n   */\n  private async loadAndProcessTemplate(templatePath: string, baseDir: string): Promise<any> {\n    const fullPath = path.resolve(baseDir, templatePath);\n    \n    if (!await fs.pathExists(fullPath)) {\n      throw new Error(`Template file not found: ${fullPath}`);\n    }\n    \n    try {\n      const templateContent = await fs.readJson(fullPath);\n      \n      // Recursively process any nested templates\n      const templateDir = path.dirname(fullPath);\n      return await this.processTemplates(templateContent, templateDir);\n    } catch (error) {\n      throw new Error(`Failed to load template ${fullPath}: ${error}`);\n    }\n  }\n  \n  /**\n   * Deep merge two objects with target taking precedence\n   * \n   * Recursively merges two objects, with values from the target object overriding\n   * values from the source object. Arrays and primitive values are not merged but\n   * replaced entirely by the target value. Undefined values in target are skipped.\n   * \n   * @param source - Base object to merge from\n   * @param target - Object with values that override source\n   * @returns New object with merged values\n   * @private\n   * \n   * @example\n   * ```typescript\n   * const source = {\n   *   a: 1,\n   *   b: { x: 10, y: 20 },\n   *   c: [1, 2, 3]\n   * };\n   * const target = {\n   *   a: 2,\n   *   b: { y: 30, z: 40 },\n   *   d: 'new'\n   * };\n   * const result = deepMerge(source, target);\n   * // Result: { a: 2, b: { x: 10, y: 30, z: 40 }, c: [1, 2, 3], d: 'new' }\n   * ```\n   */\n  private deepMerge(source: any, target: any): any {\n    if (!source) return target;\n    if (!target) return source;\n    \n    // If target is not an object, it completely overrides source\n    if (typeof target !== 'object' || target === null || Array.isArray(target)) {\n      return target;\n    }\n    \n    // If source is not an object, target wins\n    if (typeof source !== 'object' || source === null || Array.isArray(source)) {\n      return target;\n    }\n    \n    // Both are objects, merge them\n    const result: any = { ...source };\n    \n    for (const [key, value] of Object.entries(target)) {\n      if (value === undefined) {\n        continue; // Skip undefined values\n      }\n      \n      if (typeof value === 'object' && value !== null && !Array.isArray(value) &&\n          typeof result[key] === 'object' && result[key] !== null && !Array.isArray(result[key])) {\n        // Both are objects, merge recursively\n        result[key] = this.deepMerge(result[key], value);\n      } else {\n        // Otherwise, target value wins\n        result[key] = value;\n      }\n    }\n    \n    return result;\n  }\n  \n}"]}
+{"version":3,"file":"sync-engine.js","sourceRoot":"","sources":["../../src/lib/sync-engine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @fileoverview Core synchronization engine for MemberJunction metadata\n * @module sync-engine\n * \n * This module provides the core functionality for synchronizing metadata between\n * the MemberJunction database and local file system representations. It handles\n * special reference types (@file, @url, @lookup, @env, @parent, @root, @template),\n * manages entity operations, and provides utilities for data transformation.\n */\n\nimport path from 'path';\nimport fs from 'fs-extra';\nimport crypto from 'crypto';\nimport axios from 'axios';\nimport { EntityInfo, Metadata, RunView, BaseEntity, CompositeKey, UserInfo } from '@memberjunction/core';\nimport { uuidv4 } from '@memberjunction/global';\nimport { EntityConfig, FolderConfig } from '../config';\n\n/**\n * Represents the structure of a metadata record with optional sync tracking\n */\nexport interface RecordData {\n  /** Primary key field(s) and their values */\n  primaryKey?: Record<string, any>;\n  /** Entity field names and their values */\n  fields: Record<string, any>;\n  /** Related entities organized by entity name */\n  relatedEntities?: Record<string, RecordData[]>;\n  /** Synchronization metadata for change tracking */\n  sync?: {\n    /** ISO timestamp of last modification */\n    lastModified: string;\n    /** SHA256 checksum of the fields object */\n    checksum: string;\n  };\n}\n\n/**\n * Core engine for synchronizing MemberJunction metadata between database and files\n * \n * @class SyncEngine\n * @example\n * ```typescript\n * const syncEngine = new SyncEngine(systemUser);\n * await syncEngine.initialize();\n * \n * // Process a field value with special references\n * const value = await syncEngine.processFieldValue('@lookup:Users.Email=admin@example.com', '/path/to/base');\n * ```\n */\nexport class SyncEngine {\n  private metadata: Metadata;\n  private contextUser: UserInfo;\n\n  /**\n   * Creates a new SyncEngine instance\n   * @param contextUser - The user context for database operations\n   */\n  constructor(contextUser: UserInfo) {\n    this.metadata = new Metadata();\n    this.contextUser = contextUser;\n  }\n  \n  /**\n   * Initializes the sync engine by refreshing metadata cache\n   * @returns Promise that resolves when initialization is complete\n   */\n  async initialize(): Promise<void> {\n    // Initialize metadata\n    await this.metadata.Refresh();\n  }\n  \n  /**\n   * Process special references in field values\n   * \n   * Handles the following reference types:\n   * - `@parent:fieldName` - References a field from the parent record\n   * - `@root:fieldName` - References a field from the root record\n   * - `@file:path` - Reads content from an external file\n   * - `@url:address` - Fetches content from a URL\n   * - `@lookup:Entity.Field=Value` - Looks up an entity ID by field value\n   * - `@env:VARIABLE` - Reads an environment variable\n   * \n   * @param value - The field value to process\n   * @param baseDir - Base directory for resolving relative file paths\n   * @param parentRecord - Optional parent entity for @parent references\n   * @param rootRecord - Optional root entity for @root references\n   * @returns The processed value with all references resolved\n   * @throws Error if a reference cannot be resolved\n   * \n   * @example\n   * ```typescript\n   * // File reference\n   * const content = await processFieldValue('@file:template.md', '/path/to/dir');\n   * \n   * // Lookup with auto-create\n   * const userId = await processFieldValue('@lookup:Users.Email=john@example.com?create', '/path');\n   * ```\n   */\n  async processFieldValue(value: any, baseDir: string, parentRecord?: BaseEntity | null, rootRecord?: BaseEntity | null): Promise<any> {\n    if (typeof value !== 'string') {\n      return value;\n    }\n    \n    // Check for @parent: reference\n    if (value.startsWith('@parent:')) {\n      if (!parentRecord) {\n        throw new Error(`@parent reference used but no parent record available: ${value}`);\n      }\n      const fieldName = value.substring(8);\n      return parentRecord.Get(fieldName);\n    }\n    \n    // Check for @root: reference\n    if (value.startsWith('@root:')) {\n      if (!rootRecord) {\n        throw new Error(`@root reference used but no root record available: ${value}`);\n      }\n      const fieldName = value.substring(6);\n      return rootRecord.Get(fieldName);\n    }\n    \n    // Check for @file: reference\n    if (value.startsWith('@file:')) {\n      const filePath = value.substring(6);\n      const fullPath = path.resolve(baseDir, filePath);\n      \n      if (await fs.pathExists(fullPath)) {\n        return await fs.readFile(fullPath, 'utf-8');\n      } else {\n        throw new Error(`File not found: ${fullPath}`);\n      }\n    }\n    \n    // Check for @url: reference\n    if (value.startsWith('@url:')) {\n      const url = value.substring(5);\n      \n      try {\n        const response = await axios.get(url);\n        return response.data;\n      } catch (error) {\n        throw new Error(`Failed to fetch URL: ${url} - ${error}`);\n      }\n    }\n    \n    // Check for @lookup: reference\n    if (value.startsWith('@lookup:')) {\n      const lookupStr = value.substring(8);\n      \n      // Parse lookup with optional create syntax\n      // Format: EntityName.Field1=Value1&Field2=Value2?create&OtherField=Value\n      const entityMatch = lookupStr.match(/^([^.]+)\\./);\n      if (!entityMatch) {\n        throw new Error(`Invalid lookup format: ${value}`);\n      }\n      \n      const entityName = entityMatch[1];\n      const remaining = lookupStr.substring(entityName.length + 1);\n      \n      // Check if this has ?create syntax\n      const hasCreate = remaining.includes('?create');\n      const lookupPart = hasCreate ? remaining.split('?')[0] : remaining;\n      \n      // Parse all lookup fields (can be multiple with &)\n      const lookupFields: Array<{fieldName: string, fieldValue: string}> = [];\n      const lookupPairs = lookupPart.split('&');\n      \n      for (const pair of lookupPairs) {\n        const fieldMatch = pair.match(/^(.+?)=(.+)$/);\n        if (!fieldMatch) {\n          throw new Error(`Invalid lookup field format: ${pair} in ${value}`);\n        }\n        const [, fieldName, fieldValue] = fieldMatch;\n        lookupFields.push({ fieldName: fieldName.trim(), fieldValue: fieldValue.trim() });\n      }\n      \n      if (lookupFields.length === 0) {\n        throw new Error(`No lookup fields specified: ${value}`);\n      }\n      \n      // Parse additional fields for creation if ?create is present\n      let createFields: Record<string, any> = {};\n      if (hasCreate && remaining.includes('?create&')) {\n        const createPart = remaining.split('?create&')[1];\n        const pairs = createPart.split('&');\n        for (const pair of pairs) {\n          const [key, val] = pair.split('=');\n          if (key && val) {\n            createFields[key] = decodeURIComponent(val);\n          }\n        }\n      }\n      \n      return await this.resolveLookup(entityName, lookupFields, hasCreate, createFields);\n    }\n    \n    // Check for @env: reference\n    if (value.startsWith('@env:')) {\n      const envVar = value.substring(5);\n      const envValue = process.env[envVar];\n      \n      if (envValue === undefined) {\n        throw new Error(`Environment variable not found: ${envVar}`);\n      }\n      \n      return envValue;\n    }\n    \n    return value;\n  }\n  \n  /**\n   * Resolve a lookup reference to an ID, optionally creating the record if it doesn't exist\n   * \n   * @param entityName - Name of the entity to search in\n   * @param fieldName - Field to match against\n   * @param fieldValue - Value to search for\n   * @param autoCreate - Whether to create the record if not found\n   * @param createFields - Additional fields to set when creating\n   * @returns The ID of the found or created record\n   * @throws Error if lookup fails and autoCreate is false\n   * \n   * @example\n   * ```typescript\n   * // Simple lookup\n   * const categoryId = await resolveLookup('Categories', 'Name', 'Technology');\n   * \n   * // Lookup with auto-create\n   * const tagId = await resolveLookup('Tags', 'Name', 'New Tag', true, {\n   *   Description: 'Auto-created tag',\n   *   Status: 'Active'\n   * });\n   * ```\n   */\n  async resolveLookup(\n    entityName: string, \n    lookupFields: Array<{fieldName: string, fieldValue: string}>,\n    autoCreate: boolean = false,\n    createFields: Record<string, any> = {}\n  ): Promise<string> {\n    // Debug logging handled by caller if needed\n    \n    const rv = new RunView();\n    const entityInfo = this.metadata.EntityByName(entityName);\n    if (!entityInfo) {\n      throw new Error(`Entity not found: ${entityName}`);\n    }\n    \n    // Build compound filter for all lookup fields\n    const filterParts: string[] = [];\n    for (const {fieldName, fieldValue} of lookupFields) {\n      const field = entityInfo.Fields.find(f => f.Name.trim().toLowerCase() === fieldName.trim().toLowerCase());\n      if (!field) {\n        throw new Error(`Field '${fieldName}' not found in entity '${entityName}'`);\n      }\n      \n      // Handle null values properly\n      if (fieldValue.trim().toLowerCase() === 'null') {\n        filterParts.push(`${fieldName} IS NULL`);\n      } else {\n        const quotes = field.NeedsQuotes ? \"'\" : '';\n        filterParts.push(`${fieldName} = ${quotes}${fieldValue.replace(/'/g, \"''\")}${quotes}`);\n      }\n    }\n    \n    const extraFilter = filterParts.join(' AND ');\n    const result = await rv.RunView({\n      EntityName: entityName,\n      ExtraFilter: extraFilter,\n      MaxRows: 1\n    }, this.contextUser);\n    \n    if (result.Success && result.Results.length > 0) {\n      if (entityInfo.PrimaryKeys.length > 0) {\n        const pkeyField = entityInfo.PrimaryKeys[0].Name;\n        const id = result.Results[0][pkeyField];\n        return id;\n      }\n    }\n    \n    // If not found and auto-create is enabled, create the record\n    if (autoCreate) {\n      \n      const newEntity = await this.metadata.GetEntityObject(entityName, this.contextUser);\n      if (!newEntity) {\n        throw new Error(`Failed to create entity object for: ${entityName}`);\n      }\n      \n      newEntity.NewRecord();\n      \n      // Handle explicit ID setting for new records\n      if (entityInfo.PrimaryKeys.length > 0) {\n        for (const pk of entityInfo.PrimaryKeys) {\n          if (!pk.AutoIncrement && pk.Type.toLowerCase() === 'uniqueidentifier') {\n            // Generate UUID for this primary key and set it explicitly\n            const uuid = uuidv4();\n            (newEntity as any)[pk.Name] = uuid;\n          }\n        }\n      }\n      \n      // Set all lookup fields\n      for (const {fieldName, fieldValue} of lookupFields) {\n        if (fieldName in newEntity) {\n          // Handle null values properly\n          if (fieldValue.toLowerCase() === 'null') {\n            (newEntity as any)[fieldName] = null;\n          } else {\n            (newEntity as any)[fieldName] = fieldValue;\n          }\n        }\n      }\n      \n      // Set any additional fields provided\n      for (const [key, value] of Object.entries(createFields)) {\n        if (key in newEntity) {\n          (newEntity as any)[key] = value;\n        }\n      }\n      \n      // Save the new record (new records are always dirty)\n      const filterDesc = lookupFields.map(({fieldName, fieldValue}) => `${fieldName}='${fieldValue}'`).join(' AND ');\n      console.log(`📝 Auto-creating ${entityName} record where ${filterDesc}`);\n      const saved = await newEntity.Save();\n      if (!saved) {\n        const message = newEntity.LatestResult?.Message;\n        if (message) {\n          throw new Error(`Failed to auto-create ${entityName}: ${message}`);\n        }\n        \n        const errors = newEntity.LatestResult?.Errors?.map(err => \n          typeof err === 'string' ? err : (err?.message || JSON.stringify(err))\n        )?.join(', ') || 'Unknown error';\n        throw new Error(`Failed to auto-create ${entityName}: ${errors}`);\n      }\n      \n      // Return the new ID\n      if (entityInfo.PrimaryKeys.length > 0) {\n        const pkeyField = entityInfo.PrimaryKeys[0].Name;\n        const newId = newEntity.Get(pkeyField);\n        return newId;\n      }\n    }\n    \n    const filterDesc = lookupFields.map(({fieldName, fieldValue}) => `${fieldName}='${fieldValue}'`).join(' AND ');\n    throw new Error(`Lookup failed: No record found in '${entityName}' where ${filterDesc}`);\n  }\n  \n  /**\n   * Build cascading defaults for a file path and process field values\n   * \n   * Walks up the directory tree from the file location, collecting defaults from\n   * entity config and folder configs, with deeper folders overriding parent values.\n   * All default values are processed for special references.\n   * \n   * @param filePath - Path to the file being processed\n   * @param entityConfig - Entity configuration containing base defaults\n   * @returns Processed defaults with all references resolved\n   * @throws Error if any default value processing fails\n   */\n  async buildDefaults(filePath: string, entityConfig: EntityConfig): Promise<Record<string, any>> {\n    const parts = path.dirname(filePath).split(path.sep);\n    let defaults: Record<string, any> = { ...entityConfig.defaults };\n    \n    // Walk up the directory tree building defaults\n    let currentPath = '';\n    for (const part of parts) {\n      currentPath = path.join(currentPath, part);\n      const folderConfig = await this.loadFolderConfig(currentPath);\n      \n      if (folderConfig?.defaults) {\n        defaults = { ...defaults, ...folderConfig.defaults };\n      }\n    }\n    \n    // Process all default values (lookups, file references, etc.)\n    const processedDefaults: Record<string, any> = {};\n    const baseDir = path.dirname(filePath);\n    \n    for (const [field, value] of Object.entries(defaults)) {\n      try {\n        processedDefaults[field] = await this.processFieldValue(value, baseDir, null, null);\n      } catch (error) {\n        throw new Error(`Failed to process default for field '${field}': ${error}`);\n      }\n    }\n    \n    return processedDefaults;\n  }\n  \n  /**\n   * Load folder configuration from .mj-folder.json file\n   * \n   * @param dir - Directory to check for configuration\n   * @returns Folder configuration or null if not found/invalid\n   * @private\n   */\n  private async loadFolderConfig(dir: string): Promise<FolderConfig | null> {\n    const configPath = path.join(dir, '.mj-folder.json');\n    \n    if (await fs.pathExists(configPath)) {\n      try {\n        return await fs.readJson(configPath);\n      } catch (error) {\n        console.error(`Error loading folder config at ${configPath}:`, error);\n        return null;\n      }\n    }\n    \n    return null;\n  }\n  \n  /**\n   * Calculate SHA256 checksum for data\n   * \n   * Generates a deterministic hash of the provided data by converting it to\n   * formatted JSON and calculating a SHA256 digest. Used for change detection\n   * in sync operations.\n   * \n   * @param data - Any data structure to calculate checksum for\n   * @returns Hexadecimal string representation of the SHA256 hash\n   * \n   * @example\n   * ```typescript\n   * const checksum = syncEngine.calculateChecksum({\n   *   name: 'Test Record',\n   *   value: 42,\n   *   tags: ['a', 'b']\n   * });\n   * // Returns consistent hash for same data structure\n   * ```\n   */\n  calculateChecksum(data: any): string {\n    const hash = crypto.createHash('sha256');\n    hash.update(JSON.stringify(data, null, 2));\n    return hash.digest('hex');\n  }\n  \n  /**\n   * Get entity metadata information by name\n   * \n   * Retrieves the EntityInfo object containing schema metadata for the specified entity.\n   * Returns null if the entity is not found in the metadata cache.\n   * \n   * @param entityName - Name of the entity to look up\n   * @returns EntityInfo object with schema details or null if not found\n   * \n   * @example\n   * ```typescript\n   * const entityInfo = syncEngine.getEntityInfo('AI Prompts');\n   * if (entityInfo) {\n   *   console.log(`Primary keys: ${entityInfo.PrimaryKeys.map(pk => pk.Name).join(', ')}`);\n   * }\n   * ```\n   */\n  getEntityInfo(entityName: string): EntityInfo | null {\n    return this.metadata.EntityByName(entityName);\n  }\n  \n  /**\n   * Create a new entity object instance\n   * \n   * Uses the MemberJunction metadata system to properly instantiate an entity object.\n   * This ensures correct class registration and respects any custom entity subclasses.\n   * \n   * @param entityName - Name of the entity to create\n   * @returns Promise resolving to the new BaseEntity instance\n   * @throws Error if entity creation fails\n   * \n   * @example\n   * ```typescript\n   * const entity = await syncEngine.createEntityObject('AI Prompts');\n   * entity.NewRecord();\n   * entity.Set('Name', 'My Prompt');\n   * await entity.Save();\n   * ```\n   */\n  async createEntityObject(entityName: string): Promise<BaseEntity> {\n    const entity = await this.metadata.GetEntityObject(entityName, this.contextUser);\n    if (!entity) {\n      throw new Error(`Failed to create entity object for: ${entityName}`);\n    }\n    return entity;\n  }\n  \n  /**\n   * Load an entity record by primary key\n   * \n   * Retrieves an existing entity record from the database using its primary key values.\n   * Supports both single and composite primary keys. Returns null if the record is not found.\n   * \n   * @param entityName - Name of the entity to load\n   * @param primaryKey - Object containing primary key field names and values\n   * @returns Promise resolving to the loaded entity or null if not found\n   * @throws Error if entity metadata is not found\n   * \n   * @example\n   * ```typescript\n   * // Single primary key\n   * const entity = await syncEngine.loadEntity('Users', { ID: '123-456' });\n   * \n   * // Composite primary key\n   * const entity = await syncEngine.loadEntity('UserRoles', { \n   *   UserID: '123-456',\n   *   RoleID: '789-012'\n   * });\n   * ```\n   */\n  async loadEntity(entityName: string, primaryKey: Record<string, any>): Promise<BaseEntity | null> {\n    const entityInfo = this.getEntityInfo(entityName);\n    \n    if (!entityInfo) {\n      throw new Error(`Entity not found: ${entityName}`);\n    }\n    \n    // First, check if the record exists using RunView to avoid \"Error in BaseEntity.Load\" messages\n    // when records don't exist (which is a normal scenario during sync operations)\n    const rv = new RunView();\n    \n    // Build filter for primary key(s)\n    const filters: string[] = [];\n    for (const pk of entityInfo.PrimaryKeys) {\n      const value = primaryKey[pk.Name];\n      if (value === undefined || value === null) {\n        throw new Error(`Missing primary key value for ${pk.Name} in entity ${entityName}`);\n      }\n      \n      // Check if field needs quotes\n      const field = entityInfo.Fields.find(f => f.Name === pk.Name);\n      const quotes = field?.NeedsQuotes ? \"'\" : '';\n      const escapedValue = field?.NeedsQuotes && typeof value === 'string' ? value.replace(/'/g, \"''\") : value;\n      filters.push(`${pk.Name} = ${quotes}${escapedValue}${quotes}`);\n    }\n    \n    const result = await rv.RunView({\n      EntityName: entityName,\n      ExtraFilter: filters.join(' AND '),\n      MaxRows: 1\n    }, this.contextUser);\n    \n    // If no record found, return null without attempting to load\n    if (!result.Success || result.Results.length === 0) {\n      return null;\n    }\n    \n    // Record exists, now load it properly through the entity\n    const entity = await this.createEntityObject(entityName);\n    const compositeKey = new CompositeKey();\n    compositeKey.LoadFromSimpleObject(primaryKey);\n    const loaded = await entity.InnerLoad(compositeKey);\n    \n    return loaded ? entity : null;\n  }\n  \n  /**\n   * Process JSON object with template references\n   * \n   * Recursively processes JSON data structures to resolve `@template` references.\n   * Templates can be defined at any level and support:\n   * - Single template references: `\"@template:path/to/template.json\"`\n   * - Object with @template field: `{ \"@template\": \"file.json\", \"override\": \"value\" }`\n   * - Array of templates for merging: `{ \"@template\": [\"base.json\", \"overrides.json\"] }`\n   * - Nested template references within templates\n   * \n   * @param data - JSON data structure to process\n   * @param baseDir - Base directory for resolving relative template paths\n   * @returns Promise resolving to the processed data with all templates resolved\n   * @throws Error if template file is not found or contains invalid JSON\n   * \n   * @example\n   * ```typescript\n   * // Input data with template reference\n   * const data = {\n   *   \"@template\": \"defaults/ai-prompt.json\",\n   *   \"Name\": \"Custom Prompt\",\n   *   \"Prompt\": \"Override the template prompt\"\n   * };\n   * \n   * // Resolves template and merges with overrides\n   * const result = await syncEngine.processTemplates(data, '/path/to/dir');\n   * ```\n   */\n  async processTemplates(data: any, baseDir: string): Promise<any> {\n    // Handle arrays\n    if (Array.isArray(data)) {\n      const processedArray = [];\n      for (const item of data) {\n        processedArray.push(await this.processTemplates(item, baseDir));\n      }\n      return processedArray;\n    }\n    \n    // Handle objects\n    if (data && typeof data === 'object') {\n      // Check for @template reference\n      if (typeof data === 'string' && data.startsWith('@template:')) {\n        const templatePath = data.substring(10);\n        return await this.loadAndProcessTemplate(templatePath, baseDir);\n      }\n      \n      // Process object with possible @template field\n      const processed: any = {};\n      let templateData: any = {};\n      \n      // First, check if there's a @template field to process\n      if (data['@template']) {\n        const templates = Array.isArray(data['@template']) ? data['@template'] : [data['@template']];\n        \n        // Process templates in order, merging them\n        for (const templateRef of templates) {\n          const templateContent = await this.loadAndProcessTemplate(templateRef, baseDir);\n          templateData = this.deepMerge(templateData, templateContent);\n        }\n      }\n      \n      // Process all other fields\n      for (const [key, value] of Object.entries(data)) {\n        if (key === '@template') continue; // Skip the template field itself\n        \n        // Process the value recursively\n        processed[key] = await this.processTemplates(value, baseDir);\n      }\n      \n      // Merge template data with processed data (processed data takes precedence)\n      return this.deepMerge(templateData, processed);\n    }\n    \n    // Return primitive values as-is\n    return data;\n  }\n  \n  /**\n   * Load and process a template file\n   * \n   * Loads a JSON template file from the filesystem and recursively processes any\n   * nested template references within it. Template paths are resolved relative to\n   * the template file's directory, enabling template composition.\n   * \n   * @param templatePath - Path to the template file (relative or absolute)\n   * @param baseDir - Base directory for resolving relative paths\n   * @returns Promise resolving to the processed template content\n   * @throws Error if template file not found or contains invalid JSON\n   * @private\n   */\n  private async loadAndProcessTemplate(templatePath: string, baseDir: string): Promise<any> {\n    const fullPath = path.resolve(baseDir, templatePath);\n    \n    if (!await fs.pathExists(fullPath)) {\n      throw new Error(`Template file not found: ${fullPath}`);\n    }\n    \n    try {\n      const templateContent = await fs.readJson(fullPath);\n      \n      // Recursively process any nested templates\n      const templateDir = path.dirname(fullPath);\n      return await this.processTemplates(templateContent, templateDir);\n    } catch (error) {\n      throw new Error(`Failed to load template ${fullPath}: ${error}`);\n    }\n  }\n  \n  /**\n   * Deep merge two objects with target taking precedence\n   * \n   * Recursively merges two objects, with values from the target object overriding\n   * values from the source object. Arrays and primitive values are not merged but\n   * replaced entirely by the target value. Undefined values in target are skipped.\n   * \n   * @param source - Base object to merge from\n   * @param target - Object with values that override source\n   * @returns New object with merged values\n   * @private\n   * \n   * @example\n   * ```typescript\n   * const source = {\n   *   a: 1,\n   *   b: { x: 10, y: 20 },\n   *   c: [1, 2, 3]\n   * };\n   * const target = {\n   *   a: 2,\n   *   b: { y: 30, z: 40 },\n   *   d: 'new'\n   * };\n   * const result = deepMerge(source, target);\n   * // Result: { a: 2, b: { x: 10, y: 30, z: 40 }, c: [1, 2, 3], d: 'new' }\n   * ```\n   */\n  private deepMerge(source: any, target: any): any {\n    if (!source) return target;\n    if (!target) return source;\n    \n    // If target is not an object, it completely overrides source\n    if (typeof target !== 'object' || target === null || Array.isArray(target)) {\n      return target;\n    }\n    \n    // If source is not an object, target wins\n    if (typeof source !== 'object' || source === null || Array.isArray(source)) {\n      return target;\n    }\n    \n    // Both are objects, merge them\n    const result: any = { ...source };\n    \n    for (const [key, value] of Object.entries(target)) {\n      if (value === undefined) {\n        continue; // Skip undefined values\n      }\n      \n      if (typeof value === 'object' && value !== null && !Array.isArray(value) &&\n          typeof result[key] === 'object' && result[key] !== null && !Array.isArray(result[key])) {\n        // Both are objects, merge recursively\n        result[key] = this.deepMerge(result[key], value);\n      } else {\n        // Otherwise, target value wins\n        result[key] = value;\n      }\n    }\n    \n    return result;\n  }\n  \n}"]}

package/dist/services/ValidationService.d.ts

@@ -6,6 +6,7 @@ export declare class ValidationService {
     private entityDependencies;
     private processedEntities;
     private options;
+    private userRoleCache;
     constructor(options?: Partial<ValidationOptions>);
     /**
      * Validates all metadata files in the specified directory
@@ -107,4 +108,12 @@ export declare class ValidationService {
      * Get validation result
      */
     private getResult;
+    /**
+     * Load user roles from the database into cache
+     */
+    private loadUserRoles;
+    /**
+     * Validate a UserID field value against allowed roles
+     */
+    private validateUserRole;
 }