@memberjunction/metadata-sync 2.46.0 → 2.47.0

package/dist/lib/provider-utils.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * @fileoverview Database provider utilities for MetadataSync
+ * @module provider-utils
+ *
+ * This module provides utilities for initializing and managing the database
+ * connection, accessing system users, and finding entity directories. It handles
+ * the TypeORM DataSource lifecycle and MemberJunction provider initialization.
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -28,12 +36,26 @@ const typeorm_1 = require("typeorm");
 const sqlserver_dataprovider_1 = require("@memberjunction/sqlserver-dataprovider");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+/** Global DataSource instance for connection lifecycle management */
+let globalDataSource = null;
 /**
  * Initialize a SQLServerDataProvider with the given configuration
- * @param config MemberJunction configuration with database connection details
- * @returns Initialized SQLServerDataProvider instance
+ *
+ * Creates and initializes a TypeORM DataSource for SQL Server, then sets up
+ * the MemberJunction SQLServerDataProvider. The connection is stored globally
+ * for proper cleanup. Auto-detects Azure SQL databases for encryption settings.
+ *
+ * @param config - MemberJunction configuration with database connection details
+ * @returns Promise resolving to initialized SQLServerDataProvider instance
+ * @throws Error if database connection fails
+ *
+ * @example
+ * ```typescript
+ * const config = loadMJConfig();
+ * const provider = await initializeProvider(config);
+ * // Provider is ready for use
+ * ```
  */
-let globalDataSource = null;
 async function initializeProvider(config) {
     // Create TypeORM DataSource
     const dataSource = new typeorm_1.DataSource({
@@ -46,7 +68,8 @@ async function initializeProvider(config) {
         synchronize: false,
         logging: false,
         options: {
-            encrypt: config.dbTrustServerCertificate !== 'Y' ? false : true,
+            encrypt: config.dbEncrypt === 'Y' || config.dbEncrypt === 'true' ||
+                config.dbHost.includes('.database.windows.net'), // Auto-detect Azure SQL
             trustServerCertificate: config.dbTrustServerCertificate === 'Y',
             instanceName: config.dbInstanceName
         }
@@ -62,6 +85,23 @@ async function initializeProvider(config) {
     return await (0, sqlserver_dataprovider_1.setupSQLServerClient)(providerConfig);
 }
 exports.initializeProvider = initializeProvider;
+/**
+ * Clean up the global database connection
+ *
+ * Destroys the TypeORM DataSource if it exists and is initialized.
+ * Should be called when the CLI command completes to ensure proper cleanup.
+ *
+ * @returns Promise that resolves when cleanup is complete
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // Do work with database
+ * } finally {
+ *   await cleanupProvider();
+ * }
+ * ```
+ */
 async function cleanupProvider() {
     if (globalDataSource && globalDataSource.isInitialized) {
         await globalDataSource.destroy();
@@ -69,6 +109,21 @@ async function cleanupProvider() {
     }
 }
 exports.cleanupProvider = cleanupProvider;
+/**
+ * Get the system user from the UserCache
+ *
+ * Retrieves the "System" user from MemberJunction's UserCache. This user is
+ * typically used for CLI operations where no specific user context exists.
+ *
+ * @returns The System UserInfo object
+ * @throws Error if System user is not found in the cache
+ *
+ * @example
+ * ```typescript
+ * const systemUser = getSystemUser();
+ * const syncEngine = new SyncEngine(systemUser);
+ * ```
+ */
 function getSystemUser() {
     const sysUser = sqlserver_dataprovider_1.UserCache.Instance.UserByName("System", false);
     if (!sysUser) {
@@ -78,38 +133,48 @@ function getSystemUser() {
 }
 exports.getSystemUser = getSystemUser;
 /**
- * Recursively find all entity directories with .mj-sync.json files
- * @param dir Directory to search
- * @param specificDir Optional specific directory to limit search to
- * @returns Array of directory paths containing .mj-sync.json files
+ * Find entity directories at the immediate level only
+ *
+ * Searches for directories containing .mj-sync.json files, which indicate
+ * entity data directories. Only searches immediate subdirectories, not recursive.
+ * If a specific directory is provided, only checks that directory.
+ *
+ * @param dir - Base directory to search from
+ * @param specificDir - Optional specific subdirectory name to check
+ * @returns Array of absolute directory paths containing .mj-sync.json files
+ *
+ * @example
+ * ```typescript
+ * // Find all entity directories
+ * const dirs = findEntityDirectories(process.cwd());
+ *
+ * // Check specific directory
+ * const dirs = findEntityDirectories(process.cwd(), 'ai-prompts');
+ * ```
  */
 function findEntityDirectories(dir, specificDir) {
     const results = [];
-    function search(currentDir) {
-        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
-        // Check if this directory has .mj-sync.json (and it's not the root)
-        const hasSyncConfig = entries.some(e => e.name === '.mj-sync.json');
-        const isRoot = currentDir === dir;
-        if (hasSyncConfig && !isRoot) {
-            results.push(currentDir);
-        }
-        // Recursively search subdirectories
-        for (const entry of entries) {
-            if (entry.isDirectory() && !entry.name.startsWith('.')) {
-                search(path.join(currentDir, entry.name));
-            }
-        }
-    }
-    // If specific directory is provided, only search within it
+    // If specific directory is provided, check if it's an entity directory
     if (specificDir) {
-        // Handle both absolute and relative paths
         const targetDir = path.isAbsolute(specificDir) ? specificDir : path.join(dir, specificDir);
         if (fs.existsSync(targetDir)) {
-            search(targetDir);
+            const hasSyncConfig = fs.existsSync(path.join(targetDir, '.mj-sync.json'));
+            if (hasSyncConfig) {
+                results.push(targetDir);
+            }
         }
+        return results;
     }
-    else {
-        search(dir);
+    // Otherwise, find all immediate subdirectories with .mj-sync.json
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+            const subDir = path.join(dir, entry.name);
+            const hasSyncConfig = fs.existsSync(path.join(subDir, '.mj-sync.json'));
+            if (hasSyncConfig) {
+                results.push(subDir);
+            }
+        }
     }
     return results;
 }

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":["import { DataSource } from 'typeorm';\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/**\n * Initialize a SQLServerDataProvider with the given configuration\n * @param config MemberJunction configuration with database connection details\n * @returns Initialized SQLServerDataProvider instance\n */\nlet globalDataSource: DataSource | null = null;\n\nexport async function initializeProvider(config: MJConfig): Promise<SQLServerDataProvider> {\n  // Create TypeORM DataSource\n  const dataSource = new DataSource({\n    type: 'mssql',\n    host: config.dbHost,\n    port: config.dbPort ? Number(config.dbPort) : 1433,\n    database: config.dbDatabase,\n    username: config.dbUsername,\n    password: config.dbPassword,\n    synchronize: false,\n    logging: false,\n    options: {\n      encrypt: config.dbTrustServerCertificate !== 'Y' ? false : true,\n      trustServerCertificate: config.dbTrustServerCertificate === 'Y',\n      instanceName: config.dbInstanceName\n    }\n  });\n  \n  // Initialize the data source\n  await dataSource.initialize();\n  \n  // Store for cleanup\n  globalDataSource = dataSource;\n  \n  // Create provider config\n  const providerConfig = new SQLServerProviderConfigData(\n    dataSource,\n    'system@sync.cli', // Default user for CLI\n    config.mjCoreSchema || '__mj',\n    0\n  );\n  \n  // Use setupSQLServerClient to properly initialize\n  return await setupSQLServerClient(providerConfig);\n}\n\nexport async function cleanupProvider(): Promise<void> {\n  if (globalDataSource && globalDataSource.isInitialized) {\n    await globalDataSource.destroy();\n    globalDataSource = null;\n  }\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 * Recursively find all entity directories with .mj-sync.json files\n * @param dir Directory to search\n * @param specificDir Optional specific directory to limit search to\n * @returns Array of directory paths containing .mj-sync.json files\n */\nexport function findEntityDirectories(dir: string, specificDir?: string): string[] {\n  const results: string[] = [];\n  \n  function search(currentDir: string) {\n    const entries = fs.readdirSync(currentDir, { withFileTypes: true });\n    \n    // Check if this directory has .mj-sync.json (and it's not the root)\n    const hasSyncConfig = entries.some(e => e.name === '.mj-sync.json');\n    const isRoot = currentDir === dir;\n    \n    if (hasSyncConfig && !isRoot) {\n      results.push(currentDir);\n    }\n    \n    // Recursively search subdirectories\n    for (const entry of entries) {\n      if (entry.isDirectory() && !entry.name.startsWith('.')) {\n        search(path.join(currentDir, entry.name));\n      }\n    }\n  }\n  \n  // If specific directory is provided, only search within it\n  if (specificDir) {\n    // Handle both absolute and relative paths\n    const targetDir = path.isAbsolute(specificDir) ? specificDir : path.join(dir, specificDir);\n    if (fs.existsSync(targetDir)) {\n      search(targetDir);\n    }\n  } else {\n    search(dir);\n  }\n  \n  return results;\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 TypeORM DataSource lifecycle and MemberJunction provider initialization.\n */\n\nimport { DataSource } from 'typeorm';\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 DataSource instance for connection lifecycle management */\nlet globalDataSource: DataSource | null = null;\n\n/**\n * Initialize a SQLServerDataProvider with the given configuration\n * \n * Creates and initializes a TypeORM DataSource 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  // Create TypeORM DataSource\n  const dataSource = new DataSource({\n    type: 'mssql',\n    host: config.dbHost,\n    port: config.dbPort ? Number(config.dbPort) : 1433,\n    database: config.dbDatabase,\n    username: config.dbUsername,\n    password: config.dbPassword,\n    synchronize: false,\n    logging: false,\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    }\n  });\n  \n  // Initialize the data source\n  await dataSource.initialize();\n  \n  // Store for cleanup\n  globalDataSource = dataSource;\n  \n  // Create provider config\n  const providerConfig = new SQLServerProviderConfigData(\n    dataSource,\n    'system@sync.cli', // Default user for CLI\n    config.mjCoreSchema || '__mj',\n    0\n  );\n  \n  // Use setupSQLServerClient to properly initialize\n  return await setupSQLServerClient(providerConfig);\n}\n\n/**\n * Clean up the global database connection\n * \n * Destroys the TypeORM DataSource if it exists and is initialized.\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 (globalDataSource && globalDataSource.isInitialized) {\n    await globalDataSource.destroy();\n    globalDataSource = null;\n  }\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 * 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 * @returns Array of absolute directory paths containing .mj-sync.json files\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 */\nexport function findEntityDirectories(dir: string, specificDir?: string): string[] {\n  const results: string[] = [];\n  \n  // If specific directory is provided, check if it's an entity directory\n  if (specificDir) {\n    const targetDir = path.isAbsolute(specificDir) ? specificDir : path.join(dir, specificDir);\n    if (fs.existsSync(targetDir)) {\n      const hasSyncConfig = fs.existsSync(path.join(targetDir, '.mj-sync.json'));\n      if (hasSyncConfig) {\n        results.push(targetDir);\n      }\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  \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        results.push(subDir);\n      }\n    }\n  }\n  \n  return results;\n}"]}

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

@@ -1,49 +1,283 @@
+/**
+ * @fileoverview Core synchronization engine for MemberJunction metadata
+ * @module sync-engine
+ *
+ * This module provides the core functionality for synchronizing metadata between
+ * the MemberJunction database and local file system representations. It handles
+ * special reference types (@file, @url, @lookup, @env, @parent, @root, @template),
+ * manages entity operations, and provides utilities for data transformation.
+ */
 import { EntityInfo, BaseEntity, UserInfo } from '@memberjunction/core';
 import { EntityConfig } from '../config';
+/**
+ * Represents the structure of a metadata record with optional sync tracking
+ */
 export interface RecordData {
+    /** Primary key field(s) and their values */
     primaryKey?: Record<string, any>;
+    /** Entity field names and their values */
     fields: Record<string, any>;
+    /** Related entities organized by entity name */
     relatedEntities?: Record<string, RecordData[]>;
+    /** Synchronization metadata for change tracking */
     sync?: {
+        /** ISO timestamp of last modification */
         lastModified: string;
+        /** SHA256 checksum of the fields object */
         checksum: string;
     };
 }
+/**
+ * Core engine for synchronizing MemberJunction metadata between database and files
+ *
+ * @class SyncEngine
+ * @example
+ * ```typescript
+ * const syncEngine = new SyncEngine(systemUser);
+ * await syncEngine.initialize();
+ *
+ * // Process a field value with special references
+ * const value = await syncEngine.processFieldValue('@lookup:Users.Email=admin@example.com', '/path/to/base');
+ * ```
+ */
 export declare class SyncEngine {
     private metadata;
     private contextUser;
+    /**
+     * Creates a new SyncEngine instance
+     * @param contextUser - The user context for database operations
+     */
     constructor(contextUser: UserInfo);
+    /**
+     * Initializes the sync engine by refreshing metadata cache
+     * @returns Promise that resolves when initialization is complete
+     */
     initialize(): Promise<void>;
     /**
      * Process special references in field values
+     *
+     * Handles the following reference types:
+     * - `@parent:fieldName` - References a field from the parent record
+     * - `@root:fieldName` - References a field from the root record
+     * - `@file:path` - Reads content from an external file
+     * - `@url:address` - Fetches content from a URL
+     * - `@lookup:Entity.Field=Value` - Looks up an entity ID by field value
+     * - `@env:VARIABLE` - Reads an environment variable
+     *
+     * @param value - The field value to process
+     * @param baseDir - Base directory for resolving relative file paths
+     * @param parentRecord - Optional parent entity for @parent references
+     * @param rootRecord - Optional root entity for @root references
+     * @returns The processed value with all references resolved
+     * @throws Error if a reference cannot be resolved
+     *
+     * @example
+     * ```typescript
+     * // File reference
+     * const content = await processFieldValue('@file:template.md', '/path/to/dir');
+     *
+     * // Lookup with auto-create
+     * const userId = await processFieldValue('@lookup:Users.Email=john@example.com?create', '/path');
+     * ```
      */
     processFieldValue(value: any, baseDir: string, parentRecord?: BaseEntity | null, rootRecord?: BaseEntity | null): Promise<any>;
     /**
      * Resolve a lookup reference to an ID, optionally creating the record if it doesn't exist
+     *
+     * @param entityName - Name of the entity to search in
+     * @param fieldName - Field to match against
+     * @param fieldValue - Value to search for
+     * @param autoCreate - Whether to create the record if not found
+     * @param createFields - Additional fields to set when creating
+     * @returns The ID of the found or created record
+     * @throws Error if lookup fails and autoCreate is false
+     *
+     * @example
+     * ```typescript
+     * // Simple lookup
+     * const categoryId = await resolveLookup('Categories', 'Name', 'Technology');
+     *
+     * // Lookup with auto-create
+     * const tagId = await resolveLookup('Tags', 'Name', 'New Tag', true, {
+     *   Description: 'Auto-created tag',
+     *   Status: 'Active'
+     * });
+     * ```
      */
     resolveLookup(entityName: string, fieldName: string, fieldValue: string, autoCreate?: boolean, createFields?: Record<string, any>): Promise<string>;
     /**
      * Build cascading defaults for a file path and process field values
+     *
+     * Walks up the directory tree from the file location, collecting defaults from
+     * entity config and folder configs, with deeper folders overriding parent values.
+     * All default values are processed for special references.
+     *
+     * @param filePath - Path to the file being processed
+     * @param entityConfig - Entity configuration containing base defaults
+     * @returns Processed defaults with all references resolved
+     * @throws Error if any default value processing fails
      */
     buildDefaults(filePath: string, entityConfig: EntityConfig): Promise<Record<string, any>>;
     /**
-     * Load folder configuration
+     * Load folder configuration from .mj-folder.json file
+     *
+     * @param dir - Directory to check for configuration
+     * @returns Folder configuration or null if not found/invalid
+     * @private
      */
     private loadFolderConfig;
     /**
-     * Calculate checksum for data
+     * Calculate SHA256 checksum for data
+     *
+     * Generates a deterministic hash of the provided data by converting it to
+     * formatted JSON and calculating a SHA256 digest. Used for change detection
+     * in sync operations.
+     *
+     * @param data - Any data structure to calculate checksum for
+     * @returns Hexadecimal string representation of the SHA256 hash
+     *
+     * @example
+     * ```typescript
+     * const checksum = syncEngine.calculateChecksum({
+     *   name: 'Test Record',
+     *   value: 42,
+     *   tags: ['a', 'b']
+     * });
+     * // Returns consistent hash for same data structure
+     * ```
      */
     calculateChecksum(data: any): string;
     /**
-     * Get entity info by name
+     * Get entity metadata information by name
+     *
+     * Retrieves the EntityInfo object containing schema metadata for the specified entity.
+     * Returns null if the entity is not found in the metadata cache.
+     *
+     * @param entityName - Name of the entity to look up
+     * @returns EntityInfo object with schema details or null if not found
+     *
+     * @example
+     * ```typescript
+     * const entityInfo = syncEngine.getEntityInfo('AI Prompts');
+     * if (entityInfo) {
+     *   console.log(`Primary keys: ${entityInfo.PrimaryKeys.map(pk => pk.Name).join(', ')}`);
+     * }
+     * ```
      */
     getEntityInfo(entityName: string): EntityInfo | null;
     /**
-     * Create a new entity object
+     * Create a new entity object instance
+     *
+     * Uses the MemberJunction metadata system to properly instantiate an entity object.
+     * This ensures correct class registration and respects any custom entity subclasses.
+     *
+     * @param entityName - Name of the entity to create
+     * @returns Promise resolving to the new BaseEntity instance
+     * @throws Error if entity creation fails
+     *
+     * @example
+     * ```typescript
+     * const entity = await syncEngine.createEntityObject('AI Prompts');
+     * entity.NewRecord();
+     * entity.Set('Name', 'My Prompt');
+     * await entity.Save();
+     * ```
      */
     createEntityObject(entityName: string): Promise<BaseEntity>;
     /**
-     * Load an entity by primary key
+     * Load an entity record by primary key
+     *
+     * Retrieves an existing entity record from the database using its primary key values.
+     * Supports both single and composite primary keys. Returns null if the record is not found.
+     *
+     * @param entityName - Name of the entity to load
+     * @param primaryKey - Object containing primary key field names and values
+     * @returns Promise resolving to the loaded entity or null if not found
+     * @throws Error if entity metadata is not found
+     *
+     * @example
+     * ```typescript
+     * // Single primary key
+     * const entity = await syncEngine.loadEntity('Users', { ID: '123-456' });
+     *
+     * // Composite primary key
+     * const entity = await syncEngine.loadEntity('UserRoles', {
+     *   UserID: '123-456',
+     *   RoleID: '789-012'
+     * });
+     * ```
      */
     loadEntity(entityName: string, primaryKey: Record<string, any>): Promise<BaseEntity | null>;
+    /**
+     * Process JSON object with template references
+     *
+     * Recursively processes JSON data structures to resolve `@template` references.
+     * Templates can be defined at any level and support:
+     * - Single template references: `"@template:path/to/template.json"`
+     * - Object with @template field: `{ "@template": "file.json", "override": "value" }`
+     * - Array of templates for merging: `{ "@template": ["base.json", "overrides.json"] }`
+     * - Nested template references within templates
+     *
+     * @param data - JSON data structure to process
+     * @param baseDir - Base directory for resolving relative template paths
+     * @returns Promise resolving to the processed data with all templates resolved
+     * @throws Error if template file is not found or contains invalid JSON
+     *
+     * @example
+     * ```typescript
+     * // Input data with template reference
+     * const data = {
+     *   "@template": "defaults/ai-prompt.json",
+     *   "Name": "Custom Prompt",
+     *   "Prompt": "Override the template prompt"
+     * };
+     *
+     * // Resolves template and merges with overrides
+     * const result = await syncEngine.processTemplates(data, '/path/to/dir');
+     * ```
+     */
+    processTemplates(data: any, baseDir: string): Promise<any>;
+    /**
+     * Load and process a template file
+     *
+     * Loads a JSON template file from the filesystem and recursively processes any
+     * nested template references within it. Template paths are resolved relative to
+     * the template file's directory, enabling template composition.
+     *
+     * @param templatePath - Path to the template file (relative or absolute)
+     * @param baseDir - Base directory for resolving relative paths
+     * @returns Promise resolving to the processed template content
+     * @throws Error if template file not found or contains invalid JSON
+     * @private
+     */
+    private loadAndProcessTemplate;
+    /**
+     * Deep merge two objects with target taking precedence
+     *
+     * Recursively merges two objects, with values from the target object overriding
+     * values from the source object. Arrays and primitive values are not merged but
+     * replaced entirely by the target value. Undefined values in target are skipped.
+     *
+     * @param source - Base object to merge from
+     * @param target - Object with values that override source
+     * @returns New object with merged values
+     * @private
+     *
+     * @example
+     * ```typescript
+     * const source = {
+     *   a: 1,
+     *   b: { x: 10, y: 20 },
+     *   c: [1, 2, 3]
+     * };
+     * const target = {
+     *   a: 2,
+     *   b: { y: 30, z: 40 },
+     *   d: 'new'
+     * };
+     * const result = deepMerge(source, target);
+     * // Result: { a: 2, b: { x: 10, y: 30, z: 40 }, c: [1, 2, 3], d: 'new' }
+     * ```
+     */
+    private deepMerge;
 }