@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.8

package/lib/operations/OrgResetOperation.js

@@ -0,0 +1,209 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { createSuccessResult, createFailureResult } from '../models/service-result.js';
+/**
+ * Default name pattern for NUT-created definitions.
+ * Matches definitions created by NUT tests with the `[NUT-` prefix.
+ */
+export const DEFAULT_NUT_PATTERN = '[NUT-%';
+/**
+ * Error codes specific to org reset operations.
+ * Range: E4950-E4959.
+ */
+export const ResetErrorCodes = {
+    /** Query for definitions failed */
+    DEFINITION_QUERY_FAILED: 'E4950',
+    /** Definition deletion failed */
+    DEFINITION_DELETE_FAILED: 'E4951',
+    /** Request cancellation failed */
+    REQUEST_CANCEL_FAILED: 'E4952',
+    /** Request deletion failed */
+    REQUEST_DELETE_FAILED: 'E4953',
+    /** Operation failed unexpectedly */
+    OPERATION_FAILED: 'E4954',
+};
+/**
+ * Orchestrates a full org reset by purging NUT-created test data.
+ *
+ * The reset sequence is:
+ * 1. Query definitions matching the name pattern (default: `[NUT-%`)
+ * 2. Cancel any active profiling requests linked to those definitions
+ * 3. Delete cancelled/rejected profiling requests
+ * 4. Delete definitions that have no related summaries
+ *
+ * Follows the 4-layer architecture: Command → Operation → Service → API
+ */
+export class OrgResetOperation {
+    definitionService;
+    requestService;
+    logger;
+    constructor(definitionService, requestService, logger) {
+        this.definitionService = definitionService;
+        this.requestService = requestService;
+        this.logger = logger;
+    }
+    /**
+     * Creates an empty result structure.
+     */
+    static emptyResult(pattern, dryRun) {
+        return {
+            definitions: { deleted: 0, skipped: 0, failed: 0, total: 0 },
+            requests: { cancelled: 0, deleted: 0, failed: 0, total: 0 },
+            dryRun,
+            pattern,
+        };
+    }
+    /**
+     * Executes the org reset operation.
+     */
+    async execute(options) {
+        const startTime = Date.now();
+        const pattern = options.pattern ?? DEFAULT_NUT_PATTERN;
+        const dryRun = options.dryRun ?? false;
+        const emptyResult = OrgResetOperation.emptyResult(pattern, dryRun);
+        try {
+            this.logger?.log(`Starting org reset with pattern: ${pattern}`);
+            // Step 1: Query definitions matching pattern
+            options.onProgress?.({ step: 'query-definitions', message: `Querying definitions matching "${pattern}"...` });
+            const queryResult = await this.definitionService.getAllDefinitions({ namePattern: pattern });
+            if (!queryResult.success) {
+                this.logger?.log(`Definition query failed: ${queryResult.message}`);
+                return createFailureResult(emptyResult, ResetErrorCodes.DEFINITION_QUERY_FAILED, queryResult.message, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            const definitions = queryResult.data;
+            if (definitions.length === 0) {
+                this.logger?.log('No definitions found matching pattern — org is already clean');
+                return createSuccessResult(emptyResult, {
+                    message: 'Org is already clean — no test data found.',
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            options.onProgress?.({
+                step: 'query-definitions',
+                message: `Found ${definitions.length} definitions matching "${pattern}"`,
+                count: definitions.length,
+            });
+            // Categorize definitions
+            const deletable = definitions.filter((d) => !d.hasRelatedSummaries);
+            const blocked = definitions.filter((d) => d.hasRelatedSummaries);
+            // Step 2: Cancel active profiling requests for matched definitions
+            const requestResult = await this.handleRequests(definitions, dryRun, options);
+            // Step 3: Delete definitions (unless dry-run)
+            const definitionResult = await this.handleDefinitions(deletable, blocked, dryRun, options);
+            // Build final result
+            const result = {
+                definitions: definitionResult,
+                requests: requestResult,
+                dryRun,
+                pattern,
+            };
+            const summary = dryRun
+                ? `Dry-run: would delete ${deletable.length} definitions, skip ${blocked.length} (has summaries), ` +
+                    `cancel ${requestResult.cancelled} requests`
+                : `Reset complete: deleted ${definitionResult.deleted} definitions, ` +
+                    `cancelled ${requestResult.cancelled} requests, deleted ${requestResult.deleted} requests`;
+            this.logger?.log(summary);
+            return createSuccessResult(result, {
+                message: summary,
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Org reset failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ResetErrorCodes.OPERATION_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Handles profiling request cancellation and deletion for matched definitions.
+     */
+    async handleRequests(_definitions, dryRun, options) {
+        const result = { cancelled: 0, deleted: 0, failed: 0, total: 0 };
+        // Cancel active requests
+        options.onProgress?.({ step: 'cancel-requests', message: 'Cancelling active profiling requests...' });
+        const cancelResult = await this.requestService.cancelRequests({ all: true, dryRun });
+        if (cancelResult.success) {
+            result.cancelled = cancelResult.data.cancelled.length;
+            result.total += cancelResult.data.totalCancellable;
+        }
+        else {
+            // Not a fatal error — continue even if cancel finds nothing
+            this.logger?.log(`Request cancellation: ${cancelResult.message ?? 'no cancellable requests'}`);
+        }
+        // Delete cancelled/rejected requests
+        options.onProgress?.({ step: 'delete-requests', message: 'Deleting terminal profiling requests...' });
+        const deleteResult = await this.requestService.deleteRequests({ all: true, dryRun });
+        if (deleteResult.success) {
+            result.deleted = deleteResult.data.deleted.length;
+            result.total += deleteResult.data.totalDeletable;
+        }
+        else {
+            this.logger?.log(`Request deletion: ${deleteResult.message ?? 'no deletable requests'}`);
+        }
+        options.onProgress?.({
+            step: 'delete-requests',
+            message: `Requests: ${result.cancelled} cancelled, ${result.deleted} deleted`,
+            count: result.cancelled + result.deleted,
+        });
+        return result;
+    }
+    /**
+     * Handles definition deletion for deletable definitions.
+     */
+    async handleDefinitions(deletable, blocked, dryRun, options) {
+        const result = {
+            deleted: 0,
+            skipped: blocked.length,
+            failed: 0,
+            total: deletable.length + blocked.length,
+        };
+        if (deletable.length === 0) {
+            options.onProgress?.({
+                step: 'delete-definitions',
+                message: 'No deletable definitions (all blocked by summaries)',
+                count: 0,
+            });
+            return result;
+        }
+        if (dryRun) {
+            result.deleted = deletable.length;
+            options.onProgress?.({
+                step: 'delete-definitions',
+                message: `Dry-run: would delete ${deletable.length} definitions, skip ${blocked.length}`,
+                count: deletable.length,
+            });
+            return result;
+        }
+        options.onProgress?.({
+            step: 'delete-definitions',
+            message: `Deleting ${deletable.length} definitions...`,
+            count: deletable.length,
+        });
+        const idsToDelete = deletable.map((d) => d.id);
+        const deleteResult = await this.definitionService.deleteDefinitions(idsToDelete);
+        if (!deleteResult.success) {
+            this.logger?.log(`Definition deletion failed: ${deleteResult.message}`);
+            result.failed = deletable.length;
+            return result;
+        }
+        result.deleted = deleteResult.data.deleted;
+        result.failed = deleteResult.data.failed;
+        result.skipped += deleteResult.data.skipped;
+        options.onProgress?.({
+            step: 'delete-definitions',
+            message: `Definitions: ${result.deleted} deleted, ${result.skipped} skipped, ${result.failed} failed`,
+            count: result.deleted,
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=OrgResetOperation.js.map

package/lib/operations/OrgResetOperation.js.map

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

package/lib/operations/ProfileOperation.d.ts

@@ -0,0 +1,187 @@
+import { type ServiceResult } from '../models/service-result.js';
+import { ProfilingDefinitionService, type DefinitionType, type ProfilingStatus } from '../services/ProfilingDefinitionService.js';
+import { ProfilingExecutionService } from '../services/ProfilingExecutionService.js';
+/**
+ * Execution mode: single definition or bulk.
+ */
+export type ProfileMode = 'single' | 'bulk';
+/**
+ * Options for the profile execution operation.
+ */
+export type ProfileOptions = {
+    /** Target org username or alias */
+    targetOrg: string;
+    /** Profile by definition key(s) (e.g., PD-0001). Accepts multiple keys. */
+    keys?: string[];
+    /** Profile by Salesforce definition ID */
+    definitionId?: string;
+    /** Bulk profile by type */
+    type?: DefinitionType;
+    /** Filter by current status (e.g., "NOT PROFILED", "ERROR") */
+    status?: ProfilingStatus;
+    /** Object namespace filter */
+    namespace?: string;
+    /** Filter by definition category (e.g., "Baseline", "Record Types") */
+    category?: string;
+    /** Filter by time category (e.g., "Lifetime", "2026 vs 2025") */
+    timeCategory?: string;
+    /** Filter by segment category (e.g., "Historical", "Enterprise Sales") */
+    segmentCategory?: string;
+    /** Limit number of definitions processed */
+    limit?: number;
+    /** Skip definitions with zero records (default: true) */
+    skipEmpty?: boolean;
+    /** Parallel execution threads 1-10 (default: 5) */
+    parallel?: number;
+    /** Progress callback for bulk execution */
+    onProgress?: (message: string) => void;
+    logger?: Console;
+};
+/**
+ * Result of a single profiling execution.
+ */
+export type ProfileExecutionResult = {
+    /** Definition key (e.g., PD-0001) */
+    definitionKey: string;
+    /** Definition ID */
+    definitionId: string;
+    /** Object API name */
+    objectName: string;
+    /** Execution status */
+    status: 'success' | 'failed' | 'skipped';
+    /** Request ID (if execution started) */
+    requestId?: string;
+    /** Error message (if failed) */
+    errorMessage?: string;
+    /** Error code (if failed) */
+    errorCode?: string;
+    /** Skip reason (if skipped) */
+    skipReason?: string;
+    /** Resolution guidance (if failed) */
+    resolution?: string;
+    /** Duration in ms */
+    durationMs: number;
+};
+/**
+ * Result of profile execution operation.
+ */
+export type ProfileResult = {
+    /** Execution mode */
+    mode: ProfileMode;
+    /** Individual execution results */
+    executions: ProfileExecutionResult[];
+    /** Summary statistics */
+    summary: {
+        total: number;
+        successful: number;
+        failed: number;
+        skipped: number;
+    };
+};
+/**
+ * Error codes specific to profile operations.
+ */
+export declare const ProfileErrorCodes: {
+    /** No selection provided (key/id/type) */
+    readonly NO_SELECTION: "PROFILE_NO_SELECTION";
+    /** Multiple selection flags provided */
+    readonly INVALID_SELECTION: "PROFILE_INVALID_SELECTION";
+    /** Definition not found */
+    readonly DEFINITION_NOT_FOUND: "PROFILE_DEFINITION_NOT_FOUND";
+    /** Definition ID has invalid Salesforce ID format */
+    readonly INVALID_ID: "PROFILE_INVALID_ID";
+    /** Parallel out of range (1-10) */
+    readonly INVALID_PARALLEL: "PROFILE_INVALID_PARALLEL";
+    /** Query for definitions failed */
+    readonly QUERY_FAILED: "PROFILE_QUERY_FAILED";
+    /** No definitions found matching filters */
+    readonly NO_DEFINITIONS_FOUND: "PROFILE_NO_DEFINITIONS_FOUND";
+    /** Execution failed */
+    readonly EXECUTION_FAILED: "PROFILE_EXECUTION_FAILED";
+    /** Operation failed unexpectedly */
+    readonly OPERATION_FAILED: "PROFILE_OPERATION_FAILED";
+};
+/**
+ * Orchestrates profiling execution for single and bulk modes.
+ *
+ * Follows the 4-layer architecture: Command → Operation → Service → API
+ * This operation layer handles business logic orchestration:
+ * 1. Validates options (must have exactly one of key/id/type)
+ * 2. Routes to single or bulk execution
+ * 3. Transforms service results to spec-compliant ProfileResult format
+ * 4. Handles partial failures (return success if any succeeded)
+ *
+ * @example
+ * ```typescript
+ * const operation = new ProfileOperation(executionService, definitionService);
+ *
+ * // Single mode
+ * const result = await operation.execute({
+ *   targetOrg: 'myOrg',
+ *   key: 'PD-0001',
+ * });
+ *
+ * // Bulk mode
+ * const result = await operation.execute({
+ *   targetOrg: 'myOrg',
+ *   type: 'metadata',
+ *   parallel: 5,
+ *   onProgress: (msg) => console.log(msg),
+ * });
+ * ```
+ */
+export declare class ProfileOperation {
+    private readonly executionService;
+    private readonly definitionService;
+    private readonly logger?;
+    /**
+     * Creates a new ProfileOperation instance.
+     *
+     * @param executionService - Service for executing and monitoring profiling operations
+     * @param definitionService - Service for querying profiling definitions
+     * @param logger - Optional logger for debug output
+     */
+    constructor(executionService: ProfilingExecutionService, definitionService: ProfilingDefinitionService, logger?: Console | undefined);
+    /**
+     * Validates profile operation options.
+     *
+     * @param options - The profile options to validate
+     * @returns Error code if invalid, undefined if valid
+     */
+    private static validateOptions;
+    /**
+     * Creates an empty ProfileResult for failure cases.
+     *
+     * @param mode - The execution mode
+     * @returns Empty ProfileResult
+     */
+    private static createEmptyResult;
+    /**
+     * Executes the profile operation.
+     *
+     * @param options - Profile operation options
+     * @returns ServiceResult containing ProfileResult
+     */
+    execute(options: ProfileOptions): Promise<ServiceResult<ProfileResult>>;
+    /**
+     * Executes profiling for a single definition by key or ID.
+     *
+     * @param options - Profile operation options (key or definitionId must be set)
+     * @returns ServiceResult containing ProfileResult
+     */
+    private executeSingle;
+    /**
+     * Executes profiling for multiple keys by iterating and aggregating results.
+     *
+     * @param options - Profile operation options (keys must have 2+ entries)
+     * @returns ServiceResult containing aggregated ProfileResult
+     */
+    private executeMultipleKeys;
+    /**
+     * Executes profiling for multiple definitions matching type and filters.
+     *
+     * @param options - Profile operation options (type must be set)
+     * @returns ServiceResult containing ProfileResult
+     */
+    private executeBulk;
+}