@memberjunction/metadata-sync 2.46.0 → 2.48.0

package/dist/commands/pull/index.d.ts

@@ -1,4 +1,34 @@
+/**
+ * @fileoverview Pull command implementation for MetadataSync
+ * @module commands/pull
+ *
+ * This module implements the pull command which retrieves metadata records from
+ * the MemberJunction database and saves them as local JSON files. It supports:
+ * - Filtering records with SQL expressions
+ * - Pulling related entities with foreign key relationships
+ * - Externalizing large text fields to separate files
+ * - Creating multi-record JSON files
+ * - Recursive directory search for entity configurations
+ */
 import { Command } from '@oclif/core';
+/**
+ * Pull metadata records from database to local files
+ *
+ * @class Pull
+ * @extends Command
+ *
+ * @example
+ * ```bash
+ * # Pull all records for an entity
+ * mj-sync pull --entity="AI Prompts"
+ *
+ * # Pull with filter
+ * mj-sync pull --entity="AI Prompts" --filter="CategoryID='123'"
+ *
+ * # Pull to multi-record file
+ * mj-sync pull --entity="AI Prompts" --multi-file="all-prompts.json"
+ * ```
+ */
 export default class Pull extends Command {
     static description: string;
     static examples: string[];
@@ -6,13 +36,203 @@ export default class Pull extends Command {
         entity: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
         filter: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'multi-file': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /**
+     * Find directories containing configuration for the specified entity
+     *
+     * Recursively searches the current working directory for .mj-sync.json files
+     * that specify the given entity name. Returns all matching directories to
+     * allow user selection when multiple locations exist.
+     *
+     * @param entityName - Name of the entity to search for
+     * @returns Promise resolving to array of directory paths
+     * @private
+     */
     private findEntityDirectories;
+    /**
+     * Process a single record and save to file
+     *
+     * Converts a database record into the file format and writes it to disk.
+     * This is a wrapper around processRecordData that handles file writing.
+     *
+     * @param record - Raw database record
+     * @param primaryKey - Primary key fields and values
+     * @param targetDir - Directory to save the file
+     * @param entityConfig - Entity configuration with pull settings
+     * @param syncEngine - Sync engine instance
+     * @returns Promise that resolves when file is written
+     * @private
+     */
     private processRecord;
+    /**
+     * Process record data for storage
+     *
+     * Transforms a raw database record into the RecordData format used for file storage.
+     * Handles field externalization, related entity pulling, and checksum calculation.
+     *
+     * @param record - Raw database record
+     * @param primaryKey - Primary key fields and values
+     * @param targetDir - Directory where files will be saved
+     * @param entityConfig - Entity configuration with defaults and settings
+     * @param syncEngine - Sync engine for checksum calculation
+     * @param flags - Command flags
+     * @param isNewRecord - Whether this is a new record
+     * @param existingRecordData - Existing record data to preserve field selection
+     * @returns Promise resolving to formatted RecordData
+     * @private
+     */
+    private processRecordData;
+    /**
+     * Convert a foreign key value to a @lookup reference
+     *
+     * Looks up the related record and creates a @lookup string that can be
+     * resolved during push operations.
+     *
+     * @param foreignKeyValue - The foreign key value (ID)
+     * @param targetEntity - Name of the target entity
+     * @param targetField - Field in target entity to use for lookup
+     * @param syncEngine - Sync engine instance
+     * @returns @lookup string or null if lookup fails
+     * @private
+     */
+    private convertToLookup;
+    /**
+     * Determine if a field should be saved to an external file
+     *
+     * Checks if a field is configured for externalization or contains substantial
+     * text content that would be better stored in a separate file.
+     *
+     * @param fieldName - Name of the field to check
+     * @param fieldValue - Value of the field
+     * @param entityConfig - Entity configuration with externalization settings
+     * @returns Promise resolving to true if field should be externalized
+     * @private
+     */
     private shouldExternalizeField;
+    /**
+     * Create an external file for a field value
+     *
+     * Saves large text content to a separate file and returns the filename.
+     * Automatically determines appropriate file extension based on field name
+     * and content type (e.g., .md for prompts, .html for templates).
+     * Uses the entity's name field for the filename if available.
+     *
+     * @param targetDir - Directory to save the file
+     * @param record - Full record to extract name field from
+     * @param primaryKey - Primary key for filename generation fallback
+     * @param fieldName - Name of the field being externalized
+     * @param content - Content to write to the file
+     * @param entityConfig - Entity configuration
+     * @returns Promise resolving to the created filename
+     * @private
+     */
     private createExternalFile;
+    /**
+     * Build a filename from primary key values
+     *
+     * Creates a safe filename based on the entity's primary key values.
+     * Handles GUIDs by using first 8 characters, sanitizes special characters,
+     * and creates composite names for multi-field keys.
+     * Files are prefixed with a dot to follow the metadata file convention.
+     *
+     * @param primaryKey - Primary key fields and values
+     * @param entityConfig - Entity configuration (for future extension)
+     * @returns Filename with .json extension
+     * @private
+     */
     private buildFileName;
+    /**
+     * Pull related entities for a parent record
+     *
+     * Retrieves child records that have foreign key relationships to the parent.
+     * Converts foreign key values to @parent references and supports nested
+     * related entities for deep object graphs.
+     *
+     * @param parentRecord - Parent entity record
+     * @param relatedConfig - Configuration for related entities to pull
+     * @param syncEngine - Sync engine instance
+     * @returns Promise resolving to map of entity names to related records
+     * @private
+     */
     private pullRelatedEntities;
+    /**
+     * Find which field in the parent record contains a specific value
+     *
+     * Used to convert foreign key references to @parent references by finding
+     * the parent field that contains the foreign key value. Typically finds
+     * the primary key field but can match any field.
+     *
+     * @param parentRecord - Parent record to search
+     * @param value - Value to search for
+     * @returns Field name containing the value, or null if not found
+     * @private
+     */
     private findParentField;
+    /**
+     * Find existing files in a directory matching a pattern
+     *
+     * Searches for files that match the configured file pattern, used to identify
+     * which records already exist locally for smart update functionality.
+     *
+     * @param dir - Directory to search in
+     * @param pattern - Glob pattern to match files (e.g., "*.json")
+     * @returns Promise resolving to array of file paths
+     * @private
+     */
+    private findExistingFiles;
+    /**
+     * Load existing records from files and build a lookup map
+     *
+     * Reads all existing files and creates a map from primary key to file location,
+     * enabling efficient lookup during the update process.
+     *
+     * @param files - Array of file paths to load
+     * @param entityInfo - Entity metadata for primary key information
+     * @returns Map from primary key string to file info
+     * @private
+     */
+    private loadExistingRecords;
+    /**
+     * Create a string lookup key from primary key values
+     *
+     * Generates a consistent string representation of primary key values
+     * for use in maps and comparisons.
+     *
+     * @param primaryKey - Primary key field names and values
+     * @returns String representation of the primary key
+     * @private
+     */
+    private createPrimaryKeyLookup;
+    /**
+     * Merge two record data objects based on configured strategy
+     *
+     * Combines existing and new record data according to the merge strategy:
+     * - 'overwrite': Replace all fields with new values
+     * - 'merge': Combine fields, with new values taking precedence
+     * - 'skip': Keep existing record unchanged
+     *
+     * @param existing - Existing record data
+     * @param newData - New record data from database
+     * @param strategy - Merge strategy to apply
+     * @param preserveFields - Field names that should never be overwritten
+     * @returns Merged record data
+     * @private
+     */
+    private mergeRecords;
+    /**
+     * Create a backup of a file before updating
+     *
+     * Creates a timestamped backup copy of the file in a backup directory
+     * with the original filename, timestamp suffix, and .backup extension.
+     * The backup directory defaults to .backups but can be configured.
+     *
+     * @param filePath - Path to the file to backup
+     * @param backupDirName - Name of the backup directory (optional)
+     * @returns Promise that resolves when backup is created
+     * @private
+     */
+    private createBackup;
 }