@memberjunction/metadata-sync 2.55.0 → 2.56.0

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

@@ -1,246 +0,0 @@
-/**
- * @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[];
-    static flags: {
-        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>;
-        'no-validate': 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
-     * @param currentDepth - Current recursion depth for recursive entities
-     * @param ancestryPath - Set of IDs in current ancestry chain to prevent circular references
-     * @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.
-     * NEW: Supports automatic recursive patterns for self-referencing entities.
-     *
-     * @param parentRecord - Parent entity record
-     * @param relatedConfig - Configuration for related entities to pull
-     * @param syncEngine - Sync engine instance
-     * @param entityConfig - Entity configuration
-     * @param flags - Command flags
-     * @param currentDepth - Current recursion depth for recursive entities
-     * @param ancestryPath - Set of IDs in current ancestry chain to prevent circular references
-     * @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;
-}