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

package/lib/models/object-describe-types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Shared types for the `sf cuneiform object describe` command result.
+ *
+ * Extracted from the command file so that display formatters (utils layer)
+ * can consume these types without importing from the commands layer.
+ *
+ * @module models/object-describe-types
+ */
+import type { FieldTypeCount, NamespaceCount, RecordAgeDistribution } from '../services/ObjectDescribeService.js';
+/**
+ * Field information for JSON output.
+ */
+export type FieldInfo = {
+    /** Field API name */
+    apiName: string;
+    /** Field label */
+    label: string;
+    /** Field type */
+    type: string;
+    /** Maximum length for text fields */
+    length?: number;
+    /** Whether this is a custom field */
+    isCustom: boolean;
+    /** Whether this is a formula field */
+    isFormula: boolean;
+    /** Whether this field is required */
+    isRequired: boolean;
+    /** Namespace prefix (null if standard/unmanaged) */
+    namespace: string | null;
+    /** Reference to object(s) for lookup fields */
+    referenceTo: string[] | null;
+};
+/**
+ * Object summary for JSON output.
+ */
+export type ObjectSummary = {
+    /** Object API name */
+    apiName: string;
+    /** Object label */
+    label: string;
+    /** Object plural label */
+    labelPlural: string;
+    /** Whether this is a custom object */
+    isCustom: boolean;
+    /** Namespace prefix */
+    namespace: string | null;
+    /** Record count (null if query failed) */
+    recordCount: number | null;
+    /** Whether the object is queryable */
+    queryable: boolean;
+    /** Whether the object can be profiled */
+    profileable: boolean;
+    /** Whether PersonAccount is enabled (only for Account) */
+    personAccountEnabled?: boolean;
+};
+/**
+ * Field summary for JSON output.
+ */
+export type FieldSummary = {
+    /** Total fields */
+    total: number;
+    /** Standard fields */
+    standard: number;
+    /** Custom fields */
+    custom: number;
+    /** Formula fields */
+    formula: number;
+    /** Lookup fields */
+    lookup: number;
+};
+/**
+ * Relationship info for JSON output.
+ */
+export type RelationshipInfo = {
+    /** Count of objects that reference this object */
+    referencedByCount: number;
+    /** Objects that reference this object */
+    referencedBy: Array<{
+        objectName: string;
+        fieldName: string;
+        relationshipName: string | null;
+    }>;
+    /** Lookup fields on this object */
+    lookupFields: Array<{
+        fieldName: string;
+        targetObject: string;
+    }>;
+};
+/**
+ * Profiling status for JSON output.
+ */
+export type ProfilingStatusInfo = {
+    /** Number of profiling definitions */
+    definitionCount: number;
+    /** Number of profiling summaries */
+    summaryCount?: number;
+    /** Definition details */
+    definitions: Array<{
+        name: string;
+        latestSummaryDate?: string;
+        latestStatus?: string;
+    }>;
+};
+/**
+ * Single object result for JSON output.
+ */
+export type ObjectResult = {
+    /** Object summary */
+    summary: ObjectSummary;
+    /** Record types */
+    recordTypes: Array<{
+        id: string;
+        name: string;
+        developerName: string;
+        isActive: boolean;
+        isDefault: boolean;
+        isPersonType?: boolean;
+        recordAgeDistribution?: RecordAgeDistribution;
+    }>;
+    /** Field summary */
+    fieldSummary: FieldSummary;
+    /** Field type distribution */
+    fieldTypeDistribution: FieldTypeCount[];
+    /** Namespace breakdown */
+    namespaces: NamespaceCount[];
+    /** Relationships */
+    relationships: RelationshipInfo;
+    /** Record age distribution */
+    recordAgeDistribution: RecordAgeDistribution | null;
+    /** Business processes with per-process record age distribution */
+    businessProcesses: Array<{
+        id: string;
+        name: string;
+        isActive: boolean;
+        recordTypeCount: number;
+        recordTypeIds: string[];
+        recordAgeDistribution?: RecordAgeDistribution;
+    }>;
+    /** Profiling status */
+    profilingStatus: ProfilingStatusInfo;
+    /** Detailed fields (only with --with-fields) */
+    fields: FieldInfo[] | null;
+};
+/**
+ * Aggregate totals across all described objects.
+ */
+export type ObjectDescribeTotals = {
+    /** Number of objects described */
+    objectsDescribed: number;
+    /** Total fields across all objects */
+    totalFields: number;
+    /** Total standard fields across all objects */
+    totalStandardFields: number;
+    /** Total custom fields across all objects */
+    totalCustomFields: number;
+    /** Total formula fields across all objects */
+    totalFormulaFields: number;
+    /** Total lookup fields across all objects */
+    totalLookupFields: number;
+    /** Total active record types across all objects */
+    totalRecordTypes: number;
+    /** Total records across all objects (null if any object count unavailable) */
+    totalRecords: number | null;
+};
+/**
+ * Command result type for JSON output.
+ */
+export type ObjectDescribeCommandResult = {
+    /** Array of object results */
+    objects: ObjectResult[];
+    /** Aggregate totals across all objects */
+    totals: ObjectDescribeTotals;
+};

package/lib/models/object-describe-types.js

@@ -0,0 +1,9 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=object-describe-types.js.map

package/lib/models/object-describe-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-describe-types.js","sourceRoot":"","sources":["../../src/models/object-describe-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/lib/models/profile-request-types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Model types for profiling request management.
+ *
+ * Represents `pnova__Profiling_Request__c` records used by the
+ * ProfileRequestService to list and cancel queued profiling requests.
+ *
+ * @module models/profile-request-types
+ */
+/**
+ * Status values for a profiling request record.
+ *
+ * The ISV `Prop_RequestStatus__c` restricted picklist has exactly 4 values.
+ * Source: Profiling_Request__c/fields/Prop_RequestStatus__c.field-meta.xml
+ */
+export type ProfileRequestStatus = 'Queued' | 'Canceled' | 'Completed' | 'Rejected';
+/**
+ * Statuses that are eligible for cancellation.
+ *
+ * Only Queued requests can be cancelled. All other statuses are terminal.
+ */
+export declare const CANCELLABLE_STATUSES: ProfileRequestStatus[];
+/**
+ * Statuses that are eligible for deletion.
+ *
+ * Only Canceled and Rejected requests can be deleted — these never produced
+ * a summary. Completed requests are protected because reprofiling resolves
+ * the profiling user from the most recently completed request. Completed
+ * requests are cascade-deleted when their summary is purged.
+ */
+export declare const DELETABLE_STATUSES: ProfileRequestStatus[];
+/**
+ * Represents a Salesforce profiling request record (pnova__Profiling_Request__c).
+ */
+export type IProfileRequest = {
+    /** Salesforce record ID */
+    id: string;
+    /** Request name/identifier */
+    name: string;
+    /** Current status: Queued, Canceled, Completed, Rejected */
+    status: ProfileRequestStatus;
+    /** Associated profiling definition ID */
+    definitionId: string;
+    /** Associated definition name */
+    definitionName: string;
+    /** Object API name being profiled */
+    objectName: string;
+    /** When the request was created (ISO 8601) */
+    createdDate: string;
+    /** When the request was last modified (ISO 8601) */
+    lastModifiedDate: string;
+    /** User who submitted the request */
+    submittedBy: string;
+};
+/**
+ * Options for listing profiling requests.
+ */
+export type ProfileRequestListOptions = {
+    /** Filter by status */
+    status?: ProfileRequestStatus | ProfileRequestStatus[];
+    /** Pagination limit (default 25, max 200) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+};
+/**
+ * Options for cancelling profiling requests.
+ */
+export type ProfileRequestCancelOptions = {
+    /** Cancel all cancellable requests */
+    all?: boolean;
+    /** Cancel specific request IDs */
+    requestIds?: string[];
+    /** Dry run -- return what would be canceled without acting */
+    dryRun?: boolean;
+};
+/**
+ * Result of a cancel operation.
+ */
+export type ProfileRequestCancelResult = {
+    /** Requests that were canceled (or would be in dry-run) */
+    cancelled: IProfileRequest[];
+    /** Requests that failed to cancel */
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+    /** Whether this was a dry run */
+    dryRun: boolean;
+    /** Total count of cancellable requests found */
+    totalCancellable: number;
+};
+/**
+ * Options for deleting profiling requests.
+ */
+export type ProfileRequestDeleteOptions = {
+    /** Delete all deletable (Canceled and Rejected) requests */
+    all?: boolean;
+    /** Delete specific request IDs */
+    requestIds?: string[];
+    /** Dry run -- return what would be deleted without acting */
+    dryRun?: boolean;
+};
+/**
+ * Result of a delete operation.
+ */
+export type ProfileRequestDeleteResult = {
+    /** Requests that were deleted (or would be in dry-run) */
+    deleted: IProfileRequest[];
+    /** Requests that failed to delete */
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+    /** Whether this was a dry run */
+    dryRun: boolean;
+    /** Total count of deletable requests found */
+    totalDeletable: number;
+};

package/lib/models/profile-request-types.js

@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+/**
+ * Statuses that are eligible for cancellation.
+ *
+ * Only Queued requests can be cancelled. All other statuses are terminal.
+ */
+export const CANCELLABLE_STATUSES = ['Queued'];
+/**
+ * Statuses that are eligible for deletion.
+ *
+ * Only Canceled and Rejected requests can be deleted — these never produced
+ * a summary. Completed requests are protected because reprofiling resolves
+ * the profiling user from the most recently completed request. Completed
+ * requests are cascade-deleted when their summary is purged.
+ */
+export const DELETABLE_STATUSES = ['Canceled', 'Rejected'];
+//# sourceMappingURL=profile-request-types.js.map

package/lib/models/profile-request-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-request-types.js","sourceRoot":"","sources":["../../src/models/profile-request-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmBH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA2B,CAAC,QAAQ,CAAC,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC"}

package/lib/models/profiling-execution-types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared types for profiling execution and bulk execution.
+ *
+ * These types were extracted from ProfilingExecutionService during the
+ * CLI-1415 decomposition to allow BulkExecutionService to use them
+ * without circular dependencies. ProfilingExecutionService re-exports
+ * all types for backward compatibility — no consumer imports change.
+ *
+ * @module models/profiling-execution-types
+ */
+import type { ProfilingDefinition } from '../services/ProfilingDefinitionService.js';
+import type { ServiceResult } from './service-result.js';
+import { type ProfilingRequestStatus, TERMINAL_STATUSES } from './status-types.js';
+export { type ProfilingRequestStatus, TERMINAL_STATUSES };
+/**
+ * Profiling status information.
+ */
+export type ProfilingStatus = {
+    /** The profiling request ID */
+    requestId: string;
+    /** Current status */
+    status: ProfilingRequestStatus;
+    /** The associated definition ID */
+    definitionId: string;
+    /** Error message if status is Rejected */
+    errorMessage?: string;
+    /** When the request was created (ISO 8601) */
+    createdDate?: string;
+    /** When the request was last modified (ISO 8601) */
+    lastModifiedDate?: string;
+};
+/**
+ * Profiling result after completion.
+ */
+export type ProfilingResult = {
+    /** The profiling request ID */
+    requestId: string;
+    /** Final status */
+    status: ProfilingRequestStatus;
+    /** The associated definition ID */
+    definitionId: string;
+    /** Whether profiling completed successfully */
+    success: boolean;
+    /** Error message if profiling failed */
+    errorMessage?: string;
+    /** When the request started (ISO 8601) */
+    startedAt?: string;
+    /** When the request completed (ISO 8601) */
+    completedAt?: string;
+    /** Total duration in milliseconds */
+    durationMs?: number;
+};
+/**
+ * Options for the execute() method.
+ */
+export type ExecuteOptions = {
+    /** Skip definition existence validation. Use when the caller has already verified the definition exists. */
+    skipValidation?: boolean;
+};
+/**
+ * Callback interface for profiling operations used by BulkExecutionService.
+ * Decouples bulk orchestration from single-execution mechanics.
+ */
+export type IProfilingExecutor = {
+    /** Triggers a single profiling execution and returns the request ID */
+    execute(definitionId: string): Promise<ServiceResult<string>>;
+    /** Gets the current status for a profiling request */
+    getStatus(requestId: string): Promise<ServiceResult<ProfilingStatus>>;
+};
+/**
+ * Options for bulk execution of profiling definitions.
+ */
+export type BulkExecutionOptions = {
+    /** Number of parallel threads (1-10, default 5) */
+    parallel?: number;
+    /** Skip definitions with no records to profile (default true) */
+    skipEmpty?: boolean;
+    /** Polling interval for status checks in milliseconds (default 5000ms) */
+    pollInterval?: number;
+    /** Wait for profiling to complete (default true). Set to false for enqueue-only mode. */
+    waitForCompletion?: boolean;
+};
+import { type DefinitionExecutionStatus } from './status-types.js';
+export { type DefinitionExecutionStatus };
+/**
+ * Reason why a definition was skipped.
+ */
+export type SkipReason = 'empty' | 'in_progress' | 'error';
+/**
+ * Result of executing a single definition in bulk execution.
+ */
+export type DefinitionExecutionResult = {
+    /** The profiling definition */
+    definition: ProfilingDefinition;
+    /** Execution status */
+    status: DefinitionExecutionStatus;
+    /** The profiling request ID (if execution started) */
+    requestId?: string;
+    /** Profiling result (if completed) */
+    result?: ProfilingResult;
+    /** Error message (if failed) */
+    errorMessage?: string;
+    /** Error code (if failed) */
+    errorCode?: string;
+    /** Skip reason (if skipped) */
+    skipReason?: SkipReason;
+    /** User-friendly resolution guidance (if failed) */
+    resolution?: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+};
+/**
+ * Summary of bulk execution results.
+ */
+export type BulkExecutionSummary = {
+    /** Total number of definitions processed */
+    total: number;
+    /** Number of successfully completed definitions */
+    successful: number;
+    /** Number of failed definitions */
+    failed: number;
+    /** Number of skipped definitions */
+    skipped: number;
+};
+/**
+ * Complete result of bulk execution.
+ */
+export type BulkExecutionResult = {
+    /** Summary statistics */
+    summary: BulkExecutionSummary;
+    /** Results for each definition */
+    definitions: DefinitionExecutionResult[];
+};
+/**
+ * Progress update during bulk execution.
+ */
+export type BulkProgressUpdate = {
+    /** Current definition being processed */
+    current: ProfilingDefinition;
+    /** Current status of the definition */
+    status: DefinitionExecutionStatus;
+    /** Index of current definition (0-based) */
+    index: number;
+    /** Total number of definitions */
+    total: number;
+    /** Running summary of results so far */
+    summary: BulkExecutionSummary;
+    /** Optional message describing current activity */
+    message?: string;
+};
+/**
+ * Callback function for progress updates during bulk execution.
+ */
+export type ProgressCallback = (update: BulkProgressUpdate) => void;

package/lib/models/profiling-execution-types.js

@@ -0,0 +1,14 @@
+/*
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Single execution types
+// ---------------------------------------------------------------------------
+// Imported from centralized status registry and re-exported for backward compatibility
+import { TERMINAL_STATUSES } from './status-types.js';
+export { TERMINAL_STATUSES };
+//# sourceMappingURL=profiling-execution-types.js.map

package/lib/models/profiling-execution-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling-execution-types.js","sourceRoot":"","sources":["../../src/models/profiling-execution-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoBH,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,uFAAuF;AACvF,OAAO,EAA+B,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAA+B,iBAAiB,EAAE,CAAC"}

package/lib/models/service-result.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Metadata associated with a service result.
+ * Contains operational details that may be useful for debugging or logging.
+ */
+export type ServiceResultMetadata = {
+    /** Additional context-specific metadata */
+    [key: string]: unknown;
+    /** Time taken for the operation in milliseconds */
+    duration?: number;
+    /** Strategy used (if multiple available) */
+    strategyUsed?: string;
+    /** Whether a fallback was used */
+    fallbackUsed?: boolean;
+    /** Original Salesforce error code if mapped from SF error */
+    sfErrorCode?: string;
+    /** Number of Salesforce API calls made during this operation */
+    apiCallCount?: number;
+};
+/**
+ * Generic service result wrapper following CLAUDE.md ServiceResult pattern.
+ * All service and adapter methods should return this type for consistent handling.
+ *
+ * @template T The type of the data payload
+ *
+ * @example
+ * ```typescript
+ * // Success result
+ * const success: ServiceResult<User[]> = {
+ *   success: true,
+ *   data: users,
+ *   message: 'Found 10 users',
+ *   metadata: { duration: 150 }
+ * };
+ *
+ * // Failure result
+ * const failure: ServiceResult<User[]> = {
+ *   success: false,
+ *   data: [],
+ *   errorCode: 'E3102',
+ *   message: 'Invalid SOQL query syntax'
+ * };
+ * ```
+ */
+export type ServiceResult<T> = {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** The operation result data */
+    data: T;
+    /** Error code for categorizing failures (see error code ranges in CLAUDE.md) */
+    errorCode?: string;
+    /** Human-readable message (error or success) */
+    message?: string;
+    /** Non-fatal warnings encountered during execution */
+    warnings?: string[];
+    /** Additional metadata about the operation */
+    metadata?: ServiceResultMetadata;
+};
+/**
+ * Creates a successful service result.
+ *
+ * @template T The type of the data payload
+ * @param data - The result data
+ * @param options - Optional message, warnings, and metadata
+ * @returns A successful ServiceResult
+ *
+ * @example
+ * ```typescript
+ * return createSuccessResult(records, {
+ *   message: `Found ${records.length} records`,
+ *   metadata: { duration: Date.now() - startTime }
+ * });
+ * ```
+ */
+export declare function createSuccessResult<T>(data: T, options?: {
+    message?: string;
+    warnings?: string[];
+    metadata?: ServiceResultMetadata;
+}): ServiceResult<T>;
+/**
+ * Creates a failed service result.
+ *
+ * @template T The type of the data payload
+ * @param data - The default/empty data for failed result
+ * @param errorCode - The error code categorizing the failure
+ * @param message - Human-readable error message (optional — omit to test nullish coalescing fallback)
+ * @param options - Optional metadata
+ * @returns A failed ServiceResult
+ *
+ * @example
+ * ```typescript
+ * return createFailureResult([], 'E3102', 'Invalid SOQL query syntax', {
+ *   metadata: { sfErrorCode: 'INVALID_QUERY' }
+ * });
+ * ```
+ */
+export declare function createFailureResult<T>(data: T, errorCode: string, message?: string, options?: {
+    metadata?: ServiceResultMetadata;
+}): ServiceResult<T>;
+/**
+ * Creates a failed service result without data.
+ *
+ * Use when a failure occurs before any data is available (e.g., namespace guard
+ * blocks a request, or validation fails before query execution). Avoids the
+ * `undefined as unknown as T` cast pattern.
+ *
+ * @template T The type of the data payload (inferred from calling context)
+ * @param errorCode - The error code categorizing the failure
+ * @param message - Human-readable error message
+ * @param options - Optional metadata
+ * @returns A failed ServiceResult with data set to undefined
+ */
+export declare function createEmptyFailureResult<T>(errorCode: string, message?: string, options?: {
+    metadata?: ServiceResultMetadata;
+}): ServiceResult<T>;