@peernova/cuneiform-sf 1.0.2 → 1.0.3-beta.0

package/lib/services/SFDMUService.js

@@ -0,0 +1,262 @@
+/*
+ * Copyright (c) 2026, PeerNova Inc. All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { SfError } from '@salesforce/core';
+import { SFDMUErrorCodes } from '../models/sfdmu-types.js';
+/** Default promisified execFile */
+const defaultExecFileAsync = promisify(execFile);
+/**
+ * Service for executing SFDMU (Salesforce Data Move Utility) operations.
+ *
+ * This service provides:
+ * - Runtime verification that SFDMU is installed
+ * - Secure shell execution using execFile (prevents command injection)
+ * - Cross-platform support (Windows/Unix)
+ * - Configurable timeout and buffer sizes
+ * - Result parsing for record counts and errors
+ *
+ * @example
+ * ```typescript
+ * const service = new SFDMUService();
+ * await service.verifyInstallation();
+ * const result = await service.runExport({
+ *   configPath: './export.json',
+ *   sourceOrg: 'myOrg'
+ * });
+ * ```
+ */
+export class SFDMUService {
+    /** Default timeout for SFDMU operations (5 minutes) */
+    static DEFAULT_TIMEOUT = 300_000;
+    /** Default max buffer size for stdout/stderr (10MB) */
+    static DEFAULT_MAX_BUFFER = 10 * 1024 * 1024;
+    /** The sf CLI binary name (platform-specific) */
+    sfBinary;
+    /** Logger instance */
+    logger;
+    /** Injected execFile function */
+    execFileAsync;
+    /**
+     * Creates a new SFDMUService instance.
+     *
+     * @param config - Optional configuration including logger and test dependencies
+     */
+    constructor(config) {
+        const platform = config?.platform ?? process.platform;
+        this.sfBinary = platform === 'win32' ? 'sf.cmd' : 'sf';
+        this.logger = config?.logger;
+        this.execFileAsync = config?.execFileAsync ?? defaultExecFileAsync;
+    }
+    /**
+     * Builds command line arguments for SFDMU execution.
+     *
+     * @param options - Operation options
+     * @param operation - The operation type
+     * @returns Array of command line arguments
+     */
+    static buildArgs(options, operation) {
+        const args = ['sfdmu:run', '--path', options.configPath];
+        // For export: source=org, target=csvfile (writes CSV files)
+        // For import: source=csvfile, target=org (reads CSV files)
+        if (operation === 'export' && options.sourceOrg) {
+            args.push('--sourceusername', options.sourceOrg);
+            args.push('--targetusername', 'csvfile');
+        }
+        else if (operation === 'import' && options.targetOrg) {
+            args.push('--sourceusername', 'csvfile');
+            args.push('--targetusername', options.targetOrg);
+        }
+        // Add API preference if specified
+        if (options.useBulkAPI === false) {
+            args.push('--apiversion', 'rest');
+        }
+        return args;
+    }
+    /**
+     * Parses record count from SFDMU stdout output.
+     *
+     * @param stdout - Standard output from SFDMU
+     * @returns Parsed record count or undefined if not found
+     */
+    static parseRecordCount(stdout) {
+        // SFDMU outputs record counts in various formats
+        // Examples: "Processed 100 records", "Total: 100 records"
+        const patterns = [/Processed\s+(\d+)\s+records?/i, /Total[:\s]+(\d+)\s+records?/i, /(\d+)\s+records?\s+processed/i];
+        for (const pattern of patterns) {
+            const match = stdout.match(pattern);
+            if (match?.[1]) {
+                return parseInt(match[1], 10);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Parses error messages from SFDMU stderr output.
+     *
+     * @param stderr - Standard error from SFDMU
+     * @returns Array of error messages
+     */
+    static parseErrors(stderr) {
+        if (!stderr.trim()) {
+            return [];
+        }
+        // Split stderr into lines and filter for error messages
+        return stderr
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && (line.toLowerCase().includes('error') || line.startsWith('Error:')));
+    }
+    /**
+     * Parses warning messages from SFDMU stderr output.
+     *
+     * @param stderr - Standard error from SFDMU
+     * @returns Array of warning messages
+     */
+    static parseWarnings(stderr) {
+        if (!stderr.trim()) {
+            return [];
+        }
+        // Split stderr into lines and filter for warnings
+        return stderr
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && line.toLowerCase().includes('warning'));
+    }
+    /**
+     * Returns the sf binary name being used (for testing/debugging).
+     */
+    getSfBinary() {
+        return this.sfBinary;
+    }
+    /**
+     * Verifies that SFDMU is installed and available.
+     *
+     * @throws SfError if SFDMU is not installed, with installation instructions
+     */
+    async verifyInstallation() {
+        try {
+            await this.execFileAsync(this.sfBinary, ['sfdmu', '--help'], {
+                timeout: 30_000, // 30 second timeout for help command
+                maxBuffer: 1024 * 1024, // 1MB buffer for help output
+            });
+            this.logger?.log('SFDMU installation verified');
+        }
+        catch (error) {
+            const execError = error;
+            // Check if this is a "command not found" type error
+            if (execError.code === 'ENOENT' || execError.message?.includes('not found')) {
+                throw new SfError('Salesforce CLI (sf) is not installed or not in PATH.', 'SFCLINotFound', [
+                    'Install Salesforce CLI: https://developer.salesforce.com/tools/salesforcecli',
+                    'Ensure sf is in your PATH',
+                ]);
+            }
+            // SFDMU plugin not installed (sf found but sfdmu command failed)
+            throw new SfError('SFDMU plugin is not installed.', SFDMUErrorCodes.NOT_INSTALLED, [
+                'Install SFDMU: sf plugins install sfdmu',
+                'Documentation: https://help.sfdmu.com',
+            ]);
+        }
+    }
+    /**
+     * Executes an SFDMU export operation.
+     *
+     * @param options - Export options including config path and source org
+     * @returns ServiceResult containing the execution result
+     */
+    async runExport(options) {
+        return this.executeOperation(options, 'export');
+    }
+    /**
+     * Executes an SFDMU import operation.
+     *
+     * @param options - Import options including config path and target org
+     * @returns ServiceResult containing the execution result
+     */
+    async runImport(options) {
+        return this.executeOperation(options, 'import');
+    }
+    /**
+     * Executes an SFDMU operation (export or import).
+     *
+     * @param options - Operation options
+     * @param operation - The operation type ('export' or 'import')
+     * @returns ServiceResult containing the execution result
+     */
+    async executeOperation(options, operation) {
+        const startTime = Date.now();
+        // Verify SFDMU is installed before attempting operation
+        await this.verifyInstallation();
+        // Build command arguments
+        const args = SFDMUService.buildArgs(options, operation);
+        const timeout = options.timeout ?? SFDMUService.DEFAULT_TIMEOUT;
+        const maxBuffer = options.maxBuffer ?? SFDMUService.DEFAULT_MAX_BUFFER;
+        this.logger?.log(`Executing SFDMU ${operation}: ${this.sfBinary} ${args.join(' ')}`);
+        try {
+            const { stdout, stderr } = await this.execFileAsync(this.sfBinary, args, {
+                timeout,
+                maxBuffer,
+            });
+            const duration = Date.now() - startTime;
+            const recordsProcessed = SFDMUService.parseRecordCount(stdout);
+            const warnings = SFDMUService.parseWarnings(stderr);
+            return {
+                success: true,
+                data: {
+                    exitCode: 0,
+                    stdout,
+                    stderr,
+                    recordsProcessed,
+                    errors: [],
+                },
+                message: `SFDMU ${operation} completed successfully`,
+                warnings: warnings.length > 0 ? warnings : undefined,
+                metadata: {
+                    duration,
+                },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const execError = error;
+            // Handle timeout
+            if (execError.killed && execError.signal === 'SIGTERM') {
+                return {
+                    success: false,
+                    data: {
+                        exitCode: -1,
+                        stdout: execError.stdout ?? '',
+                        stderr: execError.stderr ?? '',
+                        errors: [`Operation timed out after ${timeout}ms`],
+                    },
+                    errorCode: SFDMUErrorCodes.TIMEOUT,
+                    message: `SFDMU ${operation} timed out after ${timeout}ms`,
+                    metadata: {
+                        duration,
+                    },
+                };
+            }
+            // Handle execution failure
+            const exitCode = execError.code ?? 1;
+            const errors = SFDMUService.parseErrors(execError.stderr ?? '');
+            return {
+                success: false,
+                data: {
+                    exitCode: typeof exitCode === 'number' ? exitCode : 1,
+                    stdout: execError.stdout ?? '',
+                    stderr: execError.stderr ?? '',
+                    errors,
+                },
+                errorCode: SFDMUErrorCodes.EXECUTION_FAILED,
+                message: `SFDMU ${operation} failed with exit code ${exitCode}`,
+                metadata: {
+                    duration,
+                },
+            };
+        }
+    }
+}
+//# sourceMappingURL=SFDMUService.js.map

package/lib/services/SFDMUService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SFDMUService.js","sourceRoot":"","sources":["../../src/services/SFDMUService.ts"],"names":[],"mappings":"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"}

package/messages/definition.export.md

@@ -0,0 +1,41 @@
+# summary
+
+Export profiling definitions from a Salesforce org to SFDMU-compatible CSV files.
+
+# description
+
+Exports profiling definition records to CSV files in SFDMU-compatible format for backup, version control, or cross-org migration.
+
+The export creates a timestamped directory containing:
+
+- export.json: SFDMU configuration file
+- pnova**Profiling_Definition**c.csv: Definition records
+- export-metadata.json: Export statistics and metadata
+
+Use --exclude-ids for VCS-friendly output that excludes Salesforce IDs (Id, CreatedById, etc.), making the files suitable for version control.
+
+# flags.target-org.summary
+
+Salesforce org to export definitions from.
+
+# flags.output.summary
+
+Output directory path. Defaults to ./data/exports/definitions/{timestamp}.
+
+# flags.exclude-ids.summary
+
+Exclude Salesforce IDs for VCS-friendly output.
+
+# examples
+
+- Export all definitions to the default location:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Export to a specific directory:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --output ./backup/definitions
+
+- Export with VCS-friendly mode (excludes IDs):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --exclude-ids --output ./config/definitions

package/messages/definition.import.md

@@ -0,0 +1,48 @@
+# summary
+
+Import profiling definitions from SFDMU-compatible CSV files into a Salesforce org.
+
+# description
+
+Imports profiling definition records from CSV files exported by `sf cuneiform definition export` or manually created SFDMU-compatible files.
+
+The source directory must contain:
+
+- pnova**Profiling_Definition**c.csv: Definition records to import
+
+The import operation can be configured as:
+
+- Insert (default): Creates new records only. Fails if a record with the same Name exists.
+- Upsert: Creates new records or updates existing records matched by Name (external ID).
+
+Use --dry-run to validate the import without making changes to the org.
+
+# flags.target-org.summary
+
+Salesforce org to import definitions into.
+
+# flags.source.summary
+
+Source directory containing CSV files to import.
+
+# flags.operation.summary
+
+SFDMU operation type: Insert (create only) or Upsert (create/update).
+
+# flags.dry-run.summary
+
+Preview changes without making them (dry-run mode).
+
+# examples
+
+- Import definitions from a backup directory:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup/definitions
+
+- Import with upsert (update existing, insert new):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup --operation Upsert
+
+- Preview import without making changes:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup --dry-run