@jterrats/smart-deployment 1.0.3

package/lib/constants/agentforce-limits.js

@@ -0,0 +1,262 @@
+/**
+ * Agentforce AI Token Limits and Cost Management
+ *
+ * Most LLM providers have context window limits:
+ * - Claude Sonnet 3.5: 200K tokens
+ * - GPT-4 Turbo: 128K tokens
+ * - Einstein GPT: 32K tokens (Salesforce hosted)
+ *
+ * Token estimation: ~4 chars per token for code/JSON
+ */
+/**
+ * Maximum tokens per Agentforce request
+ * Conservative limit to account for prompt + response
+ */
+export const MAX_TOKENS_PER_REQUEST = 180_000; // Leave 20K for response
+/**
+ * Average tokens per Salesforce component (JSON format)
+ * Estimated from real org analysis
+ */
+export const AVG_TOKENS_PER_COMPONENT = {
+    /** Simple component (CustomLabel, Translation) */
+    SIMPLE: 50,
+    /** Standard component (ApexClass, CustomObject field) */
+    STANDARD: 200,
+    /** Complex component (Flow, Layout, Profile) */
+    COMPLEX: 500,
+    /** Very large (CustomObject with 100+ fields, Permission Set) */
+    VERY_LARGE: 1500,
+};
+/**
+ * Maximum components per AI analysis request
+ * Based on token limits and average component size
+ */
+export const MAX_COMPONENTS_PER_BATCH = {
+    /** Simple components only */
+    SIMPLE: Math.floor(MAX_TOKENS_PER_REQUEST / AVG_TOKENS_PER_COMPONENT.SIMPLE), // ~3600
+    /** Standard components */
+    STANDARD: Math.floor(MAX_TOKENS_PER_REQUEST / AVG_TOKENS_PER_COMPONENT.STANDARD), // ~900
+    /** Complex components */
+    COMPLEX: Math.floor(MAX_TOKENS_PER_REQUEST / AVG_TOKENS_PER_COMPONENT.COMPLEX), // ~360
+    /** Very large components */
+    VERY_LARGE: Math.floor(MAX_TOKENS_PER_REQUEST / AVG_TOKENS_PER_COMPONENT.VERY_LARGE), // ~120
+    /** Conservative default (mixed sizes) */
+    DEFAULT: 250,
+};
+/**
+ * Token limits by model (as of December 2024)
+ *
+ * 🆕 Gemini 1.5 Pro has massive 2M context window!
+ * This changes the game for large org analysis.
+ */
+export const MODEL_TOKEN_LIMITS = {
+    // Anthropic Claude (200K context)
+    'claude-3-5-sonnet': 200_000,
+    'claude-3-opus': 200_000,
+    // OpenAI GPT
+    'gpt-4o': 128_000, // Latest GPT-4 Omni
+    'gpt-4-turbo': 128_000,
+    'gpt-4': 8000, // Legacy
+    // Google Gemini (HUGE context windows!)
+    'gemini-1.5-pro': 2_000_000, // 2M tokens! 🚀
+    'gemini-1.5-flash': 1_000_000, // 1M tokens
+    'gemini-ultra': 1_000_000, // Future model
+    // Salesforce Einstein
+    'einstein-gpt': 32_000,
+};
+/**
+ * Cost per 1K tokens (approximate, as of December 2024)
+ * Updated with latest pricing
+ */
+export const COST_PER_1K_TOKENS = {
+    // Anthropic Claude 3.5
+    'claude-3-5-sonnet': {
+        input: 0.003, // $3 per 1M tokens
+        output: 0.015, // $15 per 1M tokens
+    },
+    'claude-3-opus': {
+        input: 0.015, // $15 per 1M tokens
+        output: 0.075, // $75 per 1M tokens
+    },
+    // OpenAI GPT-4
+    'gpt-4o': {
+        input: 0.005, // $5 per 1M tokens (cheaper than turbo!)
+        output: 0.015, // $15 per 1M tokens
+    },
+    'gpt-4-turbo': {
+        input: 0.01, // $10 per 1M tokens
+        output: 0.03, // $30 per 1M tokens
+    },
+    'gpt-4': {
+        input: 0.03, // $30 per 1M tokens (expensive legacy)
+        output: 0.06, // $60 per 1M tokens
+    },
+    // Google Gemini (VERY competitive pricing!)
+    'gemini-1.5-pro': {
+        input: 0.001_25, // $1.25 per 1M tokens (cheapest!)
+        output: 0.005, // $5 per 1M tokens
+    },
+    'gemini-1.5-flash': {
+        input: 0.000_075, // $0.075 per 1M tokens (ultra cheap!)
+        output: 0.0003, // $0.30 per 1M tokens
+    },
+    'gemini-ultra': {
+        input: 0.003, // Estimated (future model)
+        output: 0.01,
+    },
+    // Salesforce Einstein
+    'einstein-gpt': {
+        input: 0.02, // Estimated - Salesforce pricing
+        output: 0.06,
+    },
+};
+/**
+ * Estimates tokens for a given text
+ * Rule of thumb: ~4 characters per token for code/JSON
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Estimates cost for an AI analysis request
+ */
+export function estimateCost(inputTokens, outputTokens, model) {
+    const costs = COST_PER_1K_TOKENS[model];
+    const inputCost = (inputTokens / 1000) * costs.input;
+    const outputCost = (outputTokens / 1000) * costs.output;
+    return inputCost + outputCost;
+}
+/**
+ * Checks if a batch of components will exceed token limits
+ */
+export function willExceedTokenLimit(components, model, estimatedTokensPerComponent = AVG_TOKENS_PER_COMPONENT.STANDARD) {
+    const estimatedTokens = components.length * estimatedTokensPerComponent;
+    const maxAllowed = MODEL_TOKEN_LIMITS[model];
+    return {
+        exceeds: estimatedTokens > MAX_TOKENS_PER_REQUEST,
+        estimatedTokens,
+        maxAllowed,
+    };
+}
+/**
+ * Calculates optimal batch size for components
+ */
+export function calculateOptimalBatchSize(totalComponents, model, componentComplexity = 'STANDARD') {
+    const tokensPerComponent = AVG_TOKENS_PER_COMPONENT[componentComplexity];
+    const maxComponentsPerBatch = Math.floor(MAX_TOKENS_PER_REQUEST / tokensPerComponent);
+    const batchSize = Math.min(maxComponentsPerBatch, MAX_COMPONENTS_PER_BATCH.DEFAULT);
+    const totalBatches = Math.ceil(totalComponents / batchSize);
+    // Estimate cost (assuming 2K tokens output per batch)
+    const inputTokensPerBatch = batchSize * tokensPerComponent;
+    const outputTokensPerBatch = 2000;
+    const costPerBatch = estimateCost(inputTokensPerBatch, outputTokensPerBatch, model);
+    return {
+        batchSize,
+        totalBatches,
+        estimatedCostPerBatch: costPerBatch,
+        totalEstimatedCost: costPerBatch * totalBatches,
+    };
+}
+/**
+ * Batch strategy recommendations
+ */
+export const BATCH_STRATEGY = {
+    /**
+     * For small orgs (<500 components)
+     * Single batch analysis - faster, simpler
+     */
+    SINGLE_BATCH: 'single',
+    /**
+     * For medium orgs (500-2000 components)
+     * Multiple batches with dependency-aware grouping
+     */
+    MULTI_BATCH: 'multi',
+    /**
+     * For large orgs (>2000 components)
+     * Selective analysis - only complex/ambiguous components go through AI
+     * Use static analysis for obvious dependencies
+     */
+    SELECTIVE: 'selective',
+    /**
+     * For very large orgs (>5000 components)
+     * Hybrid approach - AI for critical path, heuristics for rest
+     */
+    HYBRID: 'hybrid',
+};
+/**
+ * Get recommended batch strategy based on org size
+ */
+export function getRecommendedBatchStrategy(totalComponents) {
+    if (totalComponents < 500)
+        return 'SINGLE_BATCH';
+    if (totalComponents < 2000)
+        return 'MULTI_BATCH';
+    if (totalComponents < 5000)
+        return 'SELECTIVE';
+    return 'HYBRID';
+}
+/**
+ * Get recommended model based on org size and budget
+ */
+export function getRecommendedModel(orgSize, budget) {
+    // For massive orgs (>10K components), Gemini is the only option
+    if (orgSize > 10_000) {
+        return budget === 'low' ? 'gemini-1.5-flash' : 'gemini-1.5-pro';
+    }
+    // For large orgs (5K-10K), prefer high context models
+    if (orgSize > 5000) {
+        if (budget === 'low')
+            return 'gemini-1.5-flash';
+        if (budget === 'medium')
+            return 'gemini-1.5-pro';
+        return 'claude-3-5-sonnet';
+    }
+    // For medium orgs (1K-5K), balance cost and quality
+    if (orgSize > 1000) {
+        if (budget === 'low')
+            return 'gemini-1.5-flash';
+        if (budget === 'medium')
+            return 'gpt-4o';
+        return 'claude-3-5-sonnet';
+    }
+    // For small orgs (<1K), any modern model works
+    if (budget === 'low')
+        return 'gemini-1.5-flash';
+    if (budget === 'medium')
+        return 'gpt-4o';
+    return 'claude-3-5-sonnet';
+}
+/**
+ * Compare models for a given workload
+ */
+export function compareModels(totalComponents, avgTokensPerComponent) {
+    const totalTokens = totalComponents * avgTokensPerComponent;
+    return Object.entries(MODEL_TOKEN_LIMITS).map(([model, limit]) => {
+        const canFit = totalTokens <= limit * 0.9; // 90% safety margin
+        const batchesNeeded = canFit ? 1 : Math.ceil(totalTokens / (limit * 0.9));
+        const costs = COST_PER_1K_TOKENS[model];
+        const inputCost = (totalTokens / 1000) * costs.input * batchesNeeded;
+        const outputCost = (2000 / 1000) * costs.output * batchesNeeded; // Assume 2K output per batch
+        let recommendation = '';
+        if (model.includes('gemini') && totalComponents > 5000) {
+            recommendation = '🚀 Best for large orgs';
+        }
+        else if (model.includes('claude') && totalComponents < 2000) {
+            recommendation = '⭐ Best quality';
+        }
+        else if (model.includes('gpt-4o')) {
+            recommendation = '⚖️ Balanced option';
+        }
+        else if (model === 'gemini-1.5-flash') {
+            recommendation = '💰 Most cost-effective';
+        }
+        return {
+            model: model,
+            canFitInSingleBatch: canFit,
+            batchesNeeded,
+            estimatedCost: inputCost + outputCost,
+            recommendation,
+        };
+    });
+}
+//# sourceMappingURL=agentforce-limits.js.map

package/lib/constants/agentforce-limits.js.map

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

package/lib/constants/api-version.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Salesforce API Version Requirements
+ *
+ * This plugin enforces a minimum API version to ensure:
+ * - Compatibility with modern Salesforce features
+ * - Avoidance of deprecated/retired API versions
+ * - Better governance and best practices
+ *
+ * @see https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/
+ */
+/**
+ * Minimum supported Salesforce API version.
+ *
+ * **Why 40.0?**
+ * - Released in Winter '17 (8+ years of stability)
+ * - API versions 21.0-30.0 are retiring in Summer '25 (June 2025)
+ * - API versions 31.0-39.0 are likely candidates for future retirement
+ * - Ensures compatibility with Lightning Experience and modern features
+ * - Forces orgs to modernize and follow best practices
+ *
+ * **What gets retired with older versions:**
+ * - Classic UI compatibility issues
+ * - Missing Lightning Web Components support
+ * - Older Flow versions
+ * - Deprecated Aura framework features
+ *
+ * @constant
+ */
+export declare const MIN_API_VERSION = 40;
+/**
+ * Recommended API version (latest stable).
+ * This should be updated with each Salesforce release.
+ *
+ * Current: Spring '25 = 61.0
+ *
+ * @constant
+ */
+export declare const RECOMMENDED_API_VERSION = 61;
+/**
+ * API versions that are officially deprecated (will be retired soon).
+ * These versions will trigger warnings.
+ *
+ * Source: https://help.salesforce.com/s/articleView?id=000389618&type=1
+ */
+export declare const DEPRECATED_API_VERSIONS: readonly [21, 22, 23, 24, 25, 26, 27, 28, 29, 30];
+/**
+ * Validate if an API version meets minimum requirements.
+ *
+ * @param version - API version to validate (e.g., "59.0" or 59.0)
+ * @returns Object with validation result and message
+ *
+ * @example
+ * ```typescript
+ * const result = validateApiVersion('40.0');
+ * if (!result.valid) {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export declare function validateApiVersion(version: string | number): {
+    valid: boolean;
+    level: 'error' | 'warning' | 'ok';
+    message: string;
+};
+/**
+ * Get a user-friendly message about API version requirements.
+ *
+ * @returns Information string about version requirements
+ */
+export declare function getApiVersionRequirements(): string;

package/lib/constants/api-version.js

@@ -0,0 +1,122 @@
+/**
+ * Salesforce API Version Requirements
+ *
+ * This plugin enforces a minimum API version to ensure:
+ * - Compatibility with modern Salesforce features
+ * - Avoidance of deprecated/retired API versions
+ * - Better governance and best practices
+ *
+ * @see https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/
+ */
+/**
+ * Minimum supported Salesforce API version.
+ *
+ * **Why 40.0?**
+ * - Released in Winter '17 (8+ years of stability)
+ * - API versions 21.0-30.0 are retiring in Summer '25 (June 2025)
+ * - API versions 31.0-39.0 are likely candidates for future retirement
+ * - Ensures compatibility with Lightning Experience and modern features
+ * - Forces orgs to modernize and follow best practices
+ *
+ * **What gets retired with older versions:**
+ * - Classic UI compatibility issues
+ * - Missing Lightning Web Components support
+ * - Older Flow versions
+ * - Deprecated Aura framework features
+ *
+ * @constant
+ */
+export const MIN_API_VERSION = 40.0;
+/**
+ * Recommended API version (latest stable).
+ * This should be updated with each Salesforce release.
+ *
+ * Current: Spring '25 = 61.0
+ *
+ * @constant
+ */
+export const RECOMMENDED_API_VERSION = 61.0;
+/**
+ * API versions that are officially deprecated (will be retired soon).
+ * These versions will trigger warnings.
+ *
+ * Source: https://help.salesforce.com/s/articleView?id=000389618&type=1
+ */
+export const DEPRECATED_API_VERSIONS = [21.0, 22.0, 23.0, 24.0, 25.0, 26.0, 27.0, 28.0, 29.0, 30.0];
+/**
+ * Validate if an API version meets minimum requirements.
+ *
+ * @param version - API version to validate (e.g., "59.0" or 59.0)
+ * @returns Object with validation result and message
+ *
+ * @example
+ * ```typescript
+ * const result = validateApiVersion('40.0');
+ * if (!result.valid) {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export function validateApiVersion(version) {
+    const numVersion = typeof version === 'string' ? parseFloat(version) : version;
+    if (isNaN(numVersion)) {
+        return {
+            valid: false,
+            level: 'error',
+            message: `Invalid API version format: "${version}". Expected format: "59.0" or 59.0`,
+        };
+    }
+    // Check if version is below minimum
+    if (numVersion < MIN_API_VERSION) {
+        return {
+            valid: false,
+            level: 'error',
+            message: `API version ${numVersion} is below the minimum supported version ${MIN_API_VERSION}. ` +
+                `Please update your sfdx-project.json to use API version ${RECOMMENDED_API_VERSION} or higher. ` +
+                'Older API versions lack support for modern features and may be retired soon.',
+        };
+    }
+    // Check if version is deprecated
+    if (DEPRECATED_API_VERSIONS.includes(numVersion)) {
+        return {
+            valid: true,
+            level: 'warning',
+            message: `API version ${numVersion} is officially deprecated and will be retired in Summer '25 (June 2025). ` +
+                `Please update to API version ${RECOMMENDED_API_VERSION} immediately to avoid disruption.`,
+        };
+    }
+    // Check if version is outdated (more than 4 releases old)
+    const versionsBehind = RECOMMENDED_API_VERSION - numVersion;
+    if (versionsBehind >= 4) {
+        return {
+            valid: true,
+            level: 'warning',
+            message: `API version ${numVersion} is ${Math.floor(versionsBehind)} versions behind the latest (${RECOMMENDED_API_VERSION}). ` +
+                'Consider upgrading to access new features and ensure long-term compatibility.',
+        };
+    }
+    return {
+        valid: true,
+        level: 'ok',
+        message: `API version ${numVersion} is valid and up to date.`,
+    };
+}
+/**
+ * Get a user-friendly message about API version requirements.
+ *
+ * @returns Information string about version requirements
+ */
+export function getApiVersionRequirements() {
+    return (`This plugin requires Salesforce API version ${MIN_API_VERSION} or higher.\n` +
+        `Recommended version: ${RECOMMENDED_API_VERSION}\n` +
+        '\n' +
+        'Why this requirement?\n' +
+        '- API versions below 40.0 lack modern feature support\n' +
+        '- API versions 21.0-30.0 are retiring in June 2025\n' +
+        '- Newer versions provide better error messages and performance\n' +
+        '- Ensures compatibility with Lightning Experience\n' +
+        '\n' +
+        'To update your API version, modify your sfdx-project.json:\n' +
+        `"sourceApiVersion": "${RECOMMENDED_API_VERSION}"`);
+}
+//# sourceMappingURL=api-version.js.map

package/lib/constants/api-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-version.js","sourceRoot":"","sources":["../../src/constants/api-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;AAE7G;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAwB;IAKzD,MAAM,UAAU,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAE/E,IAAI,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QACtB,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,OAAO;YACd,OAAO,EAAE,gCAAgC,OAAO,oCAAoC;SACrF,CAAC;IACJ,CAAC;IAED,oCAAoC;IACpC,IAAI,UAAU,GAAG,eAAe,EAAE,CAAC;QACjC,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,OAAO;YACd,OAAO,EACL,eAAe,UAAU,2CAA2C,eAAe,IAAI;gBACvF,2DAA2D,uBAAuB,cAAc;gBAChG,8EAA8E;SACjF,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,IAAI,uBAAuB,CAAC,QAAQ,CAAC,UAAmB,CAAC,EAAE,CAAC;QAC1D,OAAO;YACL,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,SAAS;YAChB,OAAO,EACL,eAAe,UAAU,2EAA2E;gBACpG,gCAAgC,uBAAuB,mCAAmC;SAC7F,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,MAAM,cAAc,GAAG,uBAAuB,GAAG,UAAU,CAAC;IAC5D,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,SAAS;YAChB,OAAO,EACL,eAAe,UAAU,OAAO,IAAI,CAAC,KAAK,CACxC,cAAc,CACf,gCAAgC,uBAAuB,KAAK;gBAC7D,+EAA+E;SAClF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,eAAe,UAAU,2BAA2B;KAC9D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB;IACvC,OAAO,CACL,+CAA+C,eAAe,eAAe;QAC7E,wBAAwB,uBAAuB,IAAI;QACnD,IAAI;QACJ,yBAAyB;QACzB,yDAAyD;QACzD,sDAAsD;QACtD,kEAAkE;QAClE,qDAAqD;QACrD,IAAI;QACJ,8DAA8D;QAC9D,wBAAwB,uBAAuB,GAAG,CACnD,CAAC;AACJ,CAAC"}

package/lib/constants/deployment-order.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Salesforce Metadata Deployment Order
+ *
+ * Defines recommended deployment order for CORE Salesforce metadata types.
+ *
+ * **Important**: Salesforce has 100+ metadata types and adds new ones each release.
+ * This file defines priorities for the MOST COMMON types (~78).
+ * For unlisted types, the plugin uses a fallback priority (99) via getDeploymentPriority().
+ *
+ * **Extensibility Strategy**:
+ * - Add new types here as needed (e.g., new Einstein features)
+ * - Unknown types automatically get priority 99 (deploy last, safe default)
+ * - Plugin works with ANY metadata type, even if not listed here
+ *
+ * Lower numbers = deploy first
+ * Higher numbers = deploy later
+ *
+ * @see https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_deploy.htm
+ * @see https://help.salesforce.com/s/articleView?id=000386798&type=1
+ */
+import type { MetadataType } from '../types/metadata.js';
+/**
+ * Deployment priority map for all Salesforce metadata types.
+ * Follows the principle: dependencies first, dependents later.
+ *
+ * Priority Groups:
+ * - 1-9: Core data model (objects, fields, record types)
+ * - 10-19: Code (Apex classes, pages, components)
+ * - 20-29: Automation (triggers, flows, process builders)
+ * - 30-39: UI & Experiences (layouts, pages, sites)
+ * - 40-49: Security & Access (profiles, permission sets, sharing)
+ * - 50-59: Integration & External (connected apps, named credentials)
+ * - 60-69: Content & Knowledge
+ * - 70-79: Analytics & Reporting
+ * - 80-89: Other metadata
+ * - 90-99: Post-deployment (translations, static resources)
+ */
+export declare const DEPLOYMENT_ORDER: Readonly<Record<MetadataType, number>>;
+/**
+ * Get deployment priority for a given metadata type.
+ *
+ * **Extensibility**: Returns 99 for unknown/new metadata types (safe fallback).
+ * This ensures the plugin works with future Salesforce metadata types without updates.
+ *
+ * @param metadataType - The Salesforce metadata type
+ * @returns Priority number (1-99), or 99 (lowest priority) if type is unknown
+ *
+ * @example
+ * ```typescript
+ * const priority = getDeploymentPriority('CustomObject'); // 6
+ * const priority2 = getDeploymentPriority('ApexClass'); // 31
+ * const unknown = getDeploymentPriority('UnknownNewType'); // 99 (safe fallback)
+ * ```
+ */
+export declare function getDeploymentPriority(metadataType: MetadataType): number;
+/**
+ * Sort metadata components by deployment priority.
+ *
+ * @param components - Array of metadata type names
+ * @returns Sorted array (lowest priority number first = deploy first)
+ *
+ * @example
+ * ```typescript
+ * const sorted = sortByDeploymentOrder(['ApexClass', 'CustomObject', 'Flow']);
+ * // Result: ['CustomObject', 'ApexClass', 'Flow']
+ * ```
+ */
+export declare function sortByDeploymentOrder(components: MetadataType[]): MetadataType[];