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

package/lib/operations/DefinitionListOperation.js

@@ -0,0 +1,108 @@
+/*
+ * 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.
+ */
+/**
+ * Error codes specific to list operations.
+ */
+export const ListErrorCodes = {
+    /** Service query failed (non-exception failure) */
+    LIST_FAILED: 'LIST_FAILED',
+    /** Operation failed unexpectedly (exception) */
+    OPERATION_FAILED: 'LIST_OPERATION_FAILED',
+};
+/**
+ * Orchestrates listing of profiling definitions.
+ *
+ * Follows the 4-layer architecture: Command -> Operation -> Service -> API
+ * This operation layer handles:
+ * 1. Accepts parsed command flags as ListOptions
+ * 2. Delegates to ProfilingDefinitionService.listDefinitions()
+ * 3. Returns ServiceResult<DefinitionListResult> with timing metadata
+ *
+ * @example
+ * ```typescript
+ * const operation = new DefinitionListOperation(definitionService);
+ * const result = await operation.execute({
+ *   filter: { status: 'active', objects: ['Account'] },
+ *   pagination: { limit: 10, offset: 0 },
+ *   sort: { field: 'name', direction: 'asc' }
+ * });
+ * ```
+ */
+export class DefinitionListOperation {
+    definitionService;
+    logger;
+    /**
+     * Creates a new DefinitionListOperation.
+     *
+     * @param definitionService - The ProfilingDefinitionService instance for querying definitions
+     * @param logger - Optional logger for debug output
+     */
+    constructor(definitionService, logger) {
+        this.definitionService = definitionService;
+        this.logger = logger;
+    }
+    /**
+     * Executes the definition list operation.
+     *
+     * Returns a ServiceResult with success=false and one of the following error codes on failure:
+     * - LIST_FAILED: When the underlying service query returns a failure result
+     * - OPERATION_FAILED: When an unexpected exception occurs
+     *
+     * @param options - List options (filter, pagination, sort)
+     * @returns ServiceResult containing DefinitionListResult or error details
+     */
+    async execute(options) {
+        const startTime = Date.now();
+        const emptyResult = {
+            definitions: [],
+            totalCount: 0,
+            summary: { activeCount: 0, inactiveCount: 0, profiledCount: 0, notProfiledCount: 0 },
+        };
+        try {
+            this.logger?.log('Starting definition list operation');
+            const listResult = await this.definitionService.listDefinitions({
+                filter: options.filter,
+                pagination: options.pagination,
+                sort: options.sort,
+            });
+            const duration = Date.now() - startTime;
+            if (!listResult.success) {
+                const errorMessage = listResult.message ?? 'Unknown error';
+                this.logger?.log(`Definition list failed: ${errorMessage}`);
+                return {
+                    success: false,
+                    data: emptyResult,
+                    errorCode: ListErrorCodes.LIST_FAILED,
+                    message: listResult.message ?? 'Definition list query failed',
+                    metadata: { duration },
+                };
+            }
+            const { definitions, totalCount, summary } = listResult.data;
+            this.logger?.log(`Definition list completed: ${String(definitions.length)} definitions found`);
+            return {
+                success: true,
+                data: { definitions, totalCount, summary },
+                message: `Found ${String(totalCount)} definitions`,
+                metadata: { duration },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Definition list failed: ${errorMessage}`);
+            return {
+                success: false,
+                data: emptyResult,
+                errorCode: ListErrorCodes.OPERATION_FAILED,
+                message: `Definition list failed: ${errorMessage}`,
+                metadata: { duration },
+            };
+        }
+    }
+}
+//# sourceMappingURL=DefinitionListOperation.js.map

package/lib/operations/DefinitionListOperation.js.map

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

package/lib/operations/DefinitionPurgeOperation.d.ts

@@ -0,0 +1,199 @@
+import { type ServiceResult } from '../models/service-result.js';
+import { ProfilingDefinitionService, type DefinitionType, type ProfilingStatus, type DeleteSkipReason, type DeleteFailure, type DeleteProgressEvent } from '../services/ProfilingDefinitionService.js';
+/**
+ * Options for the definition purge operation.
+ *
+ * Selection modes:
+ * - `keys` — delete specific definitions by key (exclusive, all other flags ignored)
+ * - `all` — fetch all definitions (optionally narrowed by filters)
+ * - Filters alone — fetch matching definitions via inclusive AND logic
+ *
+ * Filters that map to SOQL (server-side): objectNames, pattern, category, status, isActive, method (as type)
+ * Filters applied client-side after fetch: filter (standard/custom — derived from __c suffix), namespace (string-prefix on objectName)
+ */
+/** Canonical message returned when the user declines the purge confirmation prompt. */
+export declare const PURGE_CANCELLED_MESSAGE = "Purge cancelled by user.";
+export type PurgeOptions = {
+    /** Target org username or alias */
+    targetOrg: string;
+    /** Definition keys to delete (e.g., PD-0001) — exclusive mode, all other flags ignored */
+    keys?: string[];
+    /** Purge all definitions (can be combined with filter flags to narrow) */
+    all?: boolean;
+    /** Filter by target object API names (comma-delimited from CLI) */
+    objectNames?: string[];
+    /** Filter by object type: standard or custom (client-side) */
+    filter?: 'standard' | 'custom';
+    /** Filter by definition name pattern with SOQL LIKE (e.g., Account%) */
+    pattern?: string;
+    /** Filter by definition method/type: metadata, historical, or comparative (client-side) */
+    method?: DefinitionType;
+    /** Filter by category */
+    category?: string;
+    /** Filter by profiling status */
+    status?: ProfilingStatus;
+    /** Filter by object namespace prefix (client-side) */
+    namespace?: string;
+    /** Maximum number of definitions to process */
+    limit?: number;
+    /** Filter by active status */
+    isActive?: boolean;
+    /** Preview mode — categorize without deleting */
+    dryRun?: boolean;
+    /** Skip interactive confirmation prompt */
+    noPrompt?: boolean;
+    /** Progress callback for per-definition status updates */
+    onProgress?: (event: DeleteProgressEvent) => void;
+    /** Callback invoked after definitions are retrieved, reporting count and max label length */
+    onDefinitionsFound?: (count: number, maxLabelLength: number) => void;
+    /**
+     * Callback invoked after categorization but before deletion.
+     * Receives the categorized preview data and returns whether to proceed with deletion.
+     * If not provided or returns true, deletion proceeds. If returns false, operation aborts.
+     */
+    onPreviewReady?: (preview: PreviewData) => Promise<boolean>;
+    /** Optional logger for debug output */
+    logger?: Console;
+};
+/**
+ * Preview entry for a single definition in dry-run mode.
+ */
+export type PurgePreviewEntry = {
+    id: string;
+    key: string;
+    name: string;
+    objectName: string;
+    status: string;
+    action: 'delete' | 'skip';
+    reason?: string;
+};
+/**
+ * Dry-run preview summary.
+ */
+export type PurgePreview = {
+    deletable: number;
+    blockedBySummaries: number;
+    definitions: PurgePreviewEntry[];
+};
+/**
+ * Data passed to the onPreviewReady callback for user confirmation.
+ */
+export type PreviewData = {
+    /** Definitions eligible for deletion */
+    deletable: BlockedDefinition[];
+    /** Definitions blocked by related summaries */
+    blockedBySummaries: BlockedDefinition[];
+    /** Total definitions matched by filters */
+    total: number;
+};
+/**
+ * Blocked definition info for display.
+ */
+export type BlockedDefinition = {
+    id: string;
+    key: string;
+    name: string;
+    objectName: string;
+    objectLabel?: string;
+    category?: string;
+    timeCategory?: string;
+    segmentCategory?: string;
+    status: string;
+};
+/**
+ * Result of a definition purge operation.
+ */
+export type PurgeResult = {
+    /** Number of definitions successfully deleted */
+    deleted: number;
+    /** Number of definitions skipped (has summaries or other reasons) */
+    skipped: number;
+    /** Number of definitions that failed to delete */
+    failed: number;
+    /** Total number of definitions processed (including blocked) */
+    total: number;
+    /** Details about why each definition was skipped */
+    skipReasons: DeleteSkipReason[];
+    /** Details about each deletion failure */
+    failures: DeleteFailure[];
+    /** Definitions blocked by related summaries (pre-categorized) */
+    blockedBySummaries: BlockedDefinition[];
+    /** Whether this was a dry-run (no deletions performed) */
+    dryRun?: boolean;
+    /** Dry-run preview (only present when dryRun is true) */
+    preview?: PurgePreview;
+};
+/**
+ * Error codes specific to purge operations.
+ */
+export declare const PurgeErrorCodes: {
+    /** No selection criteria provided (no --all, --keys, or filters) */
+    readonly NO_SELECTION_CRITERIA: "PURGE_NO_SELECTION_CRITERIA";
+    /** Query for definitions failed */
+    readonly QUERY_FAILED: "PURGE_QUERY_FAILED";
+    /** No eligible definitions found */
+    readonly NO_ELIGIBLE_DEFINITIONS: "PURGE_NO_ELIGIBLE_DEFINITIONS";
+    /** Delete operation failed */
+    readonly DELETE_FAILED: "PURGE_DELETE_FAILED";
+    /** User cancelled the operation */
+    readonly USER_CANCELLED: "PURGE_USER_CANCELLED";
+    /** Operation failed unexpectedly */
+    readonly OPERATION_FAILED: "PURGE_OPERATION_FAILED";
+};
+/**
+ * Orchestrates purging of profiling definitions.
+ *
+ * Follows the 4-layer architecture: Command → Operation → Service → API
+ * This operation layer handles:
+ * 1. Validates selection mode (IDs, --all, or filters)
+ * 2. Fetches definitions using getAllDefinitions() with inclusive AND filters
+ * 3. Pre-categorizes into deletable vs blocked (by summaries)
+ * 4. Applies client-side filters (object type, method)
+ * 5. Optionally previews (dry-run) or executes deletion
+ * 6. Reports per-definition progress and statistics
+ */
+export declare class DefinitionPurgeOperation {
+    private readonly definitionService;
+    private readonly logger?;
+    constructor(definitionService: ProfilingDefinitionService, logger?: Console | undefined);
+    /**
+     * Checks if any filter flags are specified.
+     */
+    private static hasFilterFlags;
+    /**
+     * Builds GetDefinitionsOptions from purge options (server-side filters only).
+     */
+    private static buildQueryOptions;
+    /**
+     * Applies client-side filters that can't be expressed in SOQL.
+     */
+    private static applyClientFilters;
+    /**
+     * Categorizes definitions into deletable and blocked-by-summaries.
+     *
+     * Definitions can be deleted regardless of profiling status as long as
+     * they have no associated summaries.
+     */
+    private static categorize;
+    /**
+     * Maps a definition to a BlockedDefinition for display.
+     */
+    private static toBlockedDefinition;
+    /**
+     * Creates the empty result structure.
+     */
+    private static emptyResult;
+    /**
+     * Executes the definition purge operation.
+     */
+    execute(options: PurgeOptions): Promise<ServiceResult<PurgeResult>>;
+    /**
+     * Executes purge in key-list mode.
+     * Fetches all definitions, matches by key, ignores all other flags.
+     */
+    private executeKeyMode;
+    /**
+     * Executes purge in filter mode (--all or filter flags).
+     */
+    private executeFilterMode;
+}