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

package/lib/services/UserReadinessService.js

@@ -0,0 +1,831 @@
+/*
+ * 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 { CuneiformQueryBuilder } from '../adapters/soql/cuneiform-query-builder.js';
+import { createSuccessResult, createFailureResult } from '../models/service-result.js';
+import { ServiceErrorCodes } from '../adapters/errors.js';
+import { CUNEIFORM_NAMESPACE } from './namespace-constants.js';
+import { validateRequiredString } from './validation.js';
+/**
+ * Permission set names required for Cuneiform operations.
+ */
+export const REQUIRED_PERMISSION_SETS = [
+    'Cuneiform_for_CRM_PRO_Administrative_User',
+    'Cuneiform_for_CRM_Global_Profiling_Support',
+];
+/**
+ * Maps required permission set API names to their human-readable labels.
+ * Used for user-facing display across both details and configure commands.
+ */
+export const REQUIRED_PERMISSION_SET_LABELS = {
+    [REQUIRED_PERMISSION_SETS[0]]: 'Cuneiform for CRM PRO Administrative User',
+    [REQUIRED_PERMISSION_SETS[1]]: 'Cuneiform for CRM Global Profiling Support',
+};
+/**
+ * Org types that allow configure operations.
+ * Production is the only blocked type.
+ */
+export const CONFIGURE_ALLOWED_ORG_TYPES = ['Developer', 'Sandbox', 'Scratch', 'Trial'];
+/**
+ * Service for validating user readiness to use Cuneiform.
+ *
+ * Checks whether a user has the required permission sets and configuration
+ * profile to execute Cuneiform operations. Also detects if Cuneiform is
+ * installed in the org.
+ *
+ * @example
+ * ```typescript
+ * const service = new UserReadinessService({ soqlAdapter });
+ *
+ * const result = await service.checkReadiness(userId);
+ * if (result.success) {
+ *   if (result.data.isReady) {
+ *     console.log('User is ready to use Cuneiform');
+ *   } else {
+ *     console.log('Issues:', result.data.messages.join(', '));
+ *   }
+ * }
+ * ```
+ */
+export class UserReadinessService {
+    soqlAdapter;
+    logger;
+    restClient;
+    constructor(config) {
+        this.soqlAdapter = config.soqlAdapter;
+        this.logger = config.logger;
+        this.restClient = config.restClient;
+    }
+    /**
+     * Checks whether configure operations are allowed in the given org type.
+     *
+     * Only Production orgs are blocked. Developer, Sandbox, Scratch, and Trial
+     * orgs are all allowed to run configure operations.
+     *
+     * @param orgType - The classified org type
+     * @returns true if configure is allowed, false for Production
+     */
+    static isConfigureAllowed(orgType) {
+        return CONFIGURE_ALLOWED_ORG_TYPES.includes(orgType);
+    }
+    /**
+     * Creates an empty UserReadiness result for error cases.
+     */
+    static createEmptyReadiness(userId) {
+        return {
+            userId,
+            isReady: false,
+            isCuneiformInstalled: false,
+            permissionSets: {
+                hasAllRequired: false,
+                assignments: [],
+                missingRequired: [...REQUIRED_PERMISSION_SETS],
+            },
+            configProfile: { isConfigured: false },
+            messages: [],
+        };
+    }
+    /**
+     * Creates an empty UserInfo result for error cases.
+     */
+    static createEmptyUserInfo(userId) {
+        return {
+            id: userId,
+            username: '',
+            fullName: '',
+            email: '',
+            profileName: '',
+            roleName: null,
+            isActive: false,
+        };
+    }
+    /**
+     * Checks if an error message indicates Cuneiform namespace is not found.
+     *
+     * This typically means the Cuneiform for Salesforce package is not installed in the org.
+     * The Salesforce API returns "sObject type not supported" or similar when
+     * querying namespaced objects that don't exist.
+     */
+    static isCuneiformNamespaceNotFoundError(message) {
+        const lowerMessage = message.toLowerCase();
+        return (lowerMessage.includes('sobject type') &&
+            (lowerMessage.includes('not supported') || lowerMessage.includes('invalid')));
+    }
+    /**
+     * Maps the ISV REST API payload to the canonical UserReadiness shape.
+     *
+     * The Apex endpoint returns flat booleans and differently-named fields
+     * (e.g. `assigned` instead of `isAssigned`, `cuneiformInstalled` instead
+     * of `isCuneiformInstalled`).  This mapper bridges the wire format to
+     * the TypeScript domain type so downstream code (buildResult, display)
+     * works unchanged.
+     */
+    static mapRestPayloadToUserReadiness(userId, payload) {
+        const assignments = (payload.permissionSets ?? []).map((ps) => ({
+            name: ps.name,
+            label: ps.label,
+            isAssigned: ps.assigned,
+            isRequired: REQUIRED_PERMISSION_SETS.includes(ps.name),
+        }));
+        return {
+            userId,
+            // Normalize isReady: the ISV REST endpoint may return isReady=true when only
+            // permission sets are assigned but API-only profiling is not enabled at the org
+            // level. Override to false when apiOnlyProfilingEnabled is not explicitly true
+            // so the display layer stays consistent with validateProfilingAccess() gate 3.
+            isReady: payload.isReady,
+            isCuneiformInstalled: payload.cuneiformInstalled,
+            permissionSets: {
+                hasAllRequired: payload.allPermissionsAssigned,
+                assignments,
+                missingRequired: payload.missingPermissionSets ?? [],
+            },
+            configProfile: {
+                isConfigured: payload.hasConfigurationProfile,
+                profileLabel: payload.configurationProfileLabel,
+                profileDeveloperName: payload.configurationProfileDeveloperName,
+                apiOnlyProfilingEnabled: payload.apiOnlyProfilingEnabled,
+                selfRegistrationEnabled: payload.selfRegistrationEnabled,
+            },
+            messages: [],
+        };
+    }
+    /**
+     * Retrieves user identity information.
+     *
+     * Queries the User object with Profile and UserRole relationships to build
+     * a complete user identity record. Handles null UserRole gracefully since
+     * users may not have a role assigned.
+     *
+     * @param userId - The Salesforce user ID to query
+     * @returns ServiceResult containing UserInfo
+     *
+     * @example
+     * ```typescript
+     * const result = await service.getUserInfo(userId);
+     * if (result.success) {
+     *   console.log(`User: ${result.data.fullName} (${result.data.profileName})`);
+     *   if (result.data.roleName) {
+     *     console.log(`Role: ${result.data.roleName}`);
+     *   }
+     * }
+     * ```
+     */
+    async getUserInfo(userId) {
+        const startTime = Date.now();
+        const emptyResult = UserReadinessService.createEmptyUserInfo(userId);
+        // Validate userId
+        const validationError = validateRequiredString(userId, 'User ID');
+        if (validationError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_ID_REQUIRED, validationError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            this.logger?.log(`Querying user info for: ${userId}`);
+            const soql = new CuneiformQueryBuilder()
+                .select(['Id', 'Username', 'Name', 'Email', 'Profile.Name', 'UserRole.Name', 'IsActive'])
+                .from('User')
+                .where('Id', '=', userId)
+                .limit(1)
+                .toSOQL();
+            const result = await this.soqlAdapter.query(soql);
+            if (!result.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.USER_INFO_QUERY_FAILED, result.message ?? 'User query failed', {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            if (result.data.records.length === 0) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.USER_INFO_QUERY_FAILED, `User not found: ${userId}`, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            const record = result.data.records[0];
+            const userInfo = {
+                id: record.Id,
+                username: record.Username,
+                fullName: record.Name,
+                email: record.Email,
+                profileName: record.Profile.Name,
+                roleName: record.UserRole?.Name ?? null,
+                isActive: record.IsActive,
+            };
+            const duration = Date.now() - startTime;
+            this.logger?.log(`User info retrieved: ${userInfo.fullName}`);
+            return createSuccessResult(userInfo, {
+                message: `User: ${userInfo.fullName}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`User info query failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_INFO_QUERY_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Checks complete user readiness for Cuneiform operations.
+     *
+     * Validates:
+     * 1. Cuneiform is installed (by querying CMT)
+     * 2. User has required permission sets
+     * 3. Configuration profile is set up
+     *
+     * @param userId - The Salesforce user ID to check
+     * @returns ServiceResult containing UserReadiness
+     */
+    async checkReadiness(userId) {
+        const startTime = Date.now();
+        // Validate userId
+        const validationError = validateRequiredString(userId, 'User ID');
+        if (validationError) {
+            const emptyResult = UserReadinessService.createEmptyReadiness(userId);
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_ID_REQUIRED, validationError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // REST API path: delegate to server when restClient is available.
+        // Falls back to local SOQL if REST returns unexpected results.
+        const restFallbackResult = await this.tryRestReadiness(userId, startTime);
+        if (restFallbackResult) {
+            return restFallbackResult;
+        }
+        const messages = [];
+        try {
+            this.logger?.log(`Checking readiness for user: ${userId}`);
+            // Check permission sets and config profile in parallel
+            const [permissionResult, configResult] = await Promise.all([
+                this.hasRequiredPermissionSets(userId),
+                this.hasConfigProfile(),
+            ]);
+            // Determine if Cuneiform is installed
+            let isCuneiformInstalled = true;
+            if (!configResult.success && configResult.errorCode === ServiceErrorCodes.USER_CUNEIFORM_NAMESPACE_NOT_FOUND) {
+                isCuneiformInstalled = false;
+                messages.push('Cuneiform for Salesforce is not installed in this org');
+            }
+            // Build permission set status
+            let permissionSets;
+            if (!permissionResult.success) {
+                permissionSets = {
+                    hasAllRequired: false,
+                    assignments: [],
+                    missingRequired: [...REQUIRED_PERMISSION_SETS],
+                };
+                messages.push(`Permission check failed: ${permissionResult.message ?? 'Unknown error'}`);
+            }
+            else {
+                permissionSets = permissionResult.data;
+                if (!permissionSets.hasAllRequired) {
+                    messages.push(`Missing permission sets: ${permissionSets.missingRequired.join(', ')}`);
+                }
+            }
+            // Build config profile status
+            let configProfile;
+            if (!configResult.success) {
+                configProfile = { isConfigured: false };
+                if (configResult.errorCode !== ServiceErrorCodes.USER_CUNEIFORM_NAMESPACE_NOT_FOUND) {
+                    messages.push(`Config profile check failed: ${configResult.message ?? 'Unknown error'}`);
+                }
+            }
+            else {
+                configProfile = configResult.data;
+                if (!configProfile.isConfigured) {
+                    messages.push('No active configuration profile found');
+                }
+            }
+            // Determine overall readiness — mirrors the gate chain in validateProfilingAccess().
+            // configProfile.isConfigured alone is not enough: the org must also have API-only
+            // profiling explicitly enabled, or the user will hit E4659 on every other command.
+            const isReady = isCuneiformInstalled &&
+                permissionSets.hasAllRequired &&
+                configProfile.isConfigured &&
+                configProfile.apiOnlyProfilingEnabled === true;
+            if (isReady) {
+                messages.push('User is ready to use Cuneiform');
+            }
+            const result = {
+                userId,
+                isReady,
+                isCuneiformInstalled,
+                permissionSets,
+                configProfile,
+                messages,
+            };
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Readiness check complete: ${isReady ? 'READY' : 'NOT READY'}`);
+            return createSuccessResult(result, {
+                message: isReady ? 'User is ready' : 'User is not ready',
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Readiness check failed: ${errorMessage}`);
+            const emptyResult = UserReadinessService.createEmptyReadiness(userId);
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_READINESS_QUERY_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Checks if the user has required Cuneiform permission sets.
+     *
+     * @param userId - The Salesforce user ID to check
+     * @returns ServiceResult containing PermissionSetStatus
+     */
+    async hasRequiredPermissionSets(userId) {
+        const startTime = Date.now();
+        // Validate userId
+        const validationError = validateRequiredString(userId, 'User ID');
+        if (validationError) {
+            const emptyResult = {
+                hasAllRequired: false,
+                assignments: [],
+                missingRequired: [...REQUIRED_PERMISSION_SETS],
+            };
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_ID_REQUIRED, validationError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            this.logger?.log(`Checking permission sets for user: ${userId}`);
+            // Step 1: Check direct PermissionSetAssignment records
+            const directSoql = new CuneiformQueryBuilder()
+                .select([
+                'Id',
+                'PermissionSet.Id',
+                'PermissionSet.Name',
+                'PermissionSet.Label',
+                'PermissionSet.NamespacePrefix',
+            ])
+                .from('PermissionSetAssignment')
+                .where('AssigneeId', '=', userId)
+                .andWhereIn('PermissionSet.Name', [...REQUIRED_PERMISSION_SETS])
+                .andWhere('PermissionSet.NamespacePrefix', '=', CUNEIFORM_NAMESPACE)
+                .toSOQL();
+            const directResult = await this.soqlAdapter.query(directSoql);
+            if (!directResult.success) {
+                const emptyResult = {
+                    hasAllRequired: false,
+                    assignments: [],
+                    missingRequired: [...REQUIRED_PERMISSION_SETS],
+                };
+                return createFailureResult(emptyResult, ServiceErrorCodes.USER_PERMISSION_SET_CHECK_FAILED, directResult.message ?? 'Permission set query failed', {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            // Build map of assigned permission set names to their labels
+            const assignedLabels = new Map(directResult.data.records.map((r) => [r.PermissionSet.Name, r.PermissionSet.Label]));
+            // Step 2: If any required permission sets are still missing, check group-based access
+            const directMissing = REQUIRED_PERMISSION_SETS.filter((name) => !assignedLabels.has(name));
+            if (directMissing.length > 0) {
+                const groupLabels = await this.getGroupAssignedPermissionSets(userId, directMissing);
+                for (const [name, label] of groupLabels) {
+                    assignedLabels.set(name, label);
+                }
+            }
+            // Build final status from combined direct + group results
+            const assignments = REQUIRED_PERMISSION_SETS.map((name) => ({
+                name,
+                label: assignedLabels.get(name),
+                isAssigned: assignedLabels.has(name),
+                isRequired: true,
+            }));
+            const missingRequired = REQUIRED_PERMISSION_SETS.filter((name) => !assignedLabels.has(name));
+            const hasAllRequired = missingRequired.length === 0;
+            const status = {
+                hasAllRequired,
+                assignments,
+                missingRequired,
+            };
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Permission check: ${hasAllRequired ? 'all assigned' : `missing ${missingRequired.length}`}`);
+            return createSuccessResult(status, {
+                message: hasAllRequired
+                    ? 'All required permission sets assigned'
+                    : `Missing ${missingRequired.length} permission sets`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Permission set check failed: ${errorMessage}`);
+            const emptyResult = {
+                hasAllRequired: false,
+                assignments: [],
+                missingRequired: [...REQUIRED_PERMISSION_SETS],
+            };
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_PERMISSION_SET_CHECK_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Retrieves the ID of a permission set by name and namespace.
+     *
+     * Queries the PermissionSet object directly to find a permission set by
+     * its Name and NamespacePrefix. This method returns the permission set ID
+     * for use in permission set assignment operations.
+     *
+     * @param permissionSetName - The permission set API name (e.g., 'Cuneiform_for_CRM_Global_Profiling_Support')
+     * @param namespacePrefix - The namespace prefix (e.g., 'pnova')
+     * @returns ServiceResult containing the permission set ID or null if not found
+     *
+     * @example
+     * ```typescript
+     * const result = await service.getPermissionSetId(
+     *   'Cuneiform_for_CRM_Global_Profiling_Support',
+     *   'pnova'
+     * );
+     * if (result.success && result.data) {
+     *   console.log(`Permission Set ID: ${result.data}`);
+     * } else if (result.success && result.data === null) {
+     *   console.log('Permission set not found in org');
+     * }
+     * ```
+     */
+    async getPermissionSetId(permissionSetName, namespacePrefix) {
+        const startTime = Date.now();
+        const emptyResult = null;
+        // Validate permissionSetName
+        const nameError = validateRequiredString(permissionSetName, 'Permission set name');
+        if (nameError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_PERMISSION_SET_CHECK_FAILED, nameError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // Validate namespacePrefix
+        const namespaceError = validateRequiredString(namespacePrefix, 'Namespace prefix');
+        if (namespaceError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_PERMISSION_SET_CHECK_FAILED, namespaceError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            this.logger?.log(`Querying permission set: ${namespacePrefix}__${permissionSetName}`);
+            const soql = new CuneiformQueryBuilder()
+                .select(['Id'])
+                .from('PermissionSet')
+                .where('Name', '=', permissionSetName)
+                .andWhere('NamespacePrefix', '=', namespacePrefix)
+                .limit(1)
+                .toSOQL();
+            const result = await this.soqlAdapter.query(soql);
+            if (!result.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.USER_PERMISSION_SET_CHECK_FAILED, result.message ?? 'Permission set query failed', {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            // Permission set not found - return null (not an error)
+            if (result.data.records.length === 0) {
+                const duration = Date.now() - startTime;
+                this.logger?.log(`Permission set not found: ${namespacePrefix}__${permissionSetName}`);
+                return createSuccessResult(null, {
+                    message: `Permission set not found: ${namespacePrefix}__${permissionSetName}`,
+                    warnings: [`Permission set '${permissionSetName}' not found in namespace '${namespacePrefix}'`],
+                    metadata: { duration },
+                });
+            }
+            const permissionSetId = result.data.records[0].Id;
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Permission set found: ${permissionSetId}`);
+            return createSuccessResult(permissionSetId, {
+                message: `Permission set found: ${permissionSetId}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Permission set query failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_PERMISSION_SET_CHECK_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Checks if a configuration profile is configured.
+     *
+     * Queries the Cuneiform Active Configuration CMT to determine if a profile
+     * is set up. If the CMT doesn't exist, returns E4654 indicating Cuneiform
+     * is not installed.
+     *
+     * @returns ServiceResult containing ConfigProfileStatus
+     */
+    async hasConfigProfile() {
+        const startTime = Date.now();
+        try {
+            this.logger?.log('Checking configuration profile...');
+            const soql = new CuneiformQueryBuilder()
+                .select([
+                'Id',
+                'DeveloperName',
+                'pnova__Active_Configuration_Profile__r.DeveloperName',
+                'pnova__Active_Configuration_Profile__r.Label',
+                'pnova__Active_Configuration_Profile__r.pnova__Enable_API_Only_Profiling__c',
+                'pnova__Active_Configuration_Profile__r.pnova__Enable_API_Only_Profiling_Registration__c',
+            ])
+                .from('pnova__Active_Configuration__mdt')
+                .where('DeveloperName', '=', 'Active_Configuration')
+                .limit(1)
+                .toSOQL();
+            const result = await this.soqlAdapter.query(soql);
+            // Check for namespace not found error (Cuneiform not installed)
+            if (!result.success) {
+                if (UserReadinessService.isCuneiformNamespaceNotFoundError(result.message ?? '')) {
+                    return createFailureResult({ isConfigured: false }, ServiceErrorCodes.USER_CUNEIFORM_NAMESPACE_NOT_FOUND, 'Cuneiform namespace not found - package may not be installed', { metadata: { duration: Date.now() - startTime } });
+                }
+                return createFailureResult({ isConfigured: false }, ServiceErrorCodes.USER_CONFIG_PROFILE_CHECK_FAILED, result.message ?? 'Config profile query failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            // No config record found
+            if (result.data.records.length === 0) {
+                const duration = Date.now() - startTime;
+                return createSuccessResult({ isConfigured: false }, {
+                    message: 'No active configuration found',
+                    metadata: { duration },
+                });
+            }
+            const record = result.data.records[0];
+            const profile = record.pnova__Active_Configuration_Profile__r;
+            // Config record exists but no profile linked
+            if (!profile) {
+                const duration = Date.now() - startTime;
+                return createSuccessResult({ isConfigured: false }, {
+                    message: 'Configuration exists but no profile is linked',
+                    metadata: { duration },
+                });
+            }
+            const status = {
+                isConfigured: true,
+                profileDeveloperName: profile.DeveloperName,
+                profileLabel: profile.Label,
+                apiOnlyProfilingEnabled: profile.pnova__Enable_API_Only_Profiling__c,
+                selfRegistrationEnabled: profile.pnova__Enable_API_Only_Profiling_Registration__c,
+            };
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Config profile found: ${status.profileLabel ?? 'Unknown'}`);
+            return createSuccessResult(status, {
+                message: `Active profile: ${status.profileLabel ?? 'Unknown'}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Config profile check failed: ${errorMessage}`);
+            // Check for namespace not found in exception
+            if (UserReadinessService.isCuneiformNamespaceNotFoundError(errorMessage)) {
+                return createFailureResult({ isConfigured: false }, ServiceErrorCodes.USER_CUNEIFORM_NAMESPACE_NOT_FOUND, 'Cuneiform namespace not found - package may not be installed', { metadata: { duration: Date.now() - startTime } });
+            }
+            return createFailureResult({ isConfigured: false }, ServiceErrorCodes.USER_CONFIG_PROFILE_CHECK_FAILED, errorMessage, { metadata: { duration: Date.now() - startTime } });
+        }
+    }
+    /**
+     * Validates that the user has profiling access to use Cuneiform commands.
+     *
+     * Checks in order:
+     * 1. Cuneiform is installed in the org
+     * 2. Required permission sets are assigned
+     * 3. Global Profiling is enabled
+     *
+     * Returns success if all checks pass. Returns a specific error code for the
+     * first failing check, with a user-friendly message including remediation steps.
+     *
+     * @param userId - The Salesforce user ID to validate
+     * @returns ServiceResult<void> — success or failure with specific error code
+     */
+    async validateProfilingAccess(userId) {
+        const startTime = Date.now();
+        const readinessResult = await this.checkReadiness(userId);
+        if (!readinessResult.success) {
+            return createFailureResult(undefined, readinessResult.errorCode ?? ServiceErrorCodes.USER_READINESS_QUERY_FAILED, readinessResult.message ?? 'Readiness check failed', { metadata: { duration: Date.now() - startTime } });
+        }
+        const readiness = readinessResult.data;
+        // Gate 1: Cuneiform must be installed
+        if (!readiness.isCuneiformInstalled) {
+            return createFailureResult(undefined, ServiceErrorCodes.USER_CUNEIFORM_NAMESPACE_NOT_FOUND, 'Cuneiform for Salesforce is not installed in this org.', { metadata: { duration: Date.now() - startTime } });
+        }
+        // Gate 2: Required permission sets must be assigned
+        if (!readiness.permissionSets.hasAllRequired) {
+            const missingLabels = readiness.permissionSets.missingRequired.map((name) => REQUIRED_PERMISSION_SET_LABELS[name] ?? name);
+            return createFailureResult(undefined, ServiceErrorCodes.PROFILING_ACCESS_DENIED, "Cuneiform is installed, but you don't have profiling access. " +
+                `Missing permission sets: ${missingLabels.join(', ')}. ` +
+                'Run "sf cuneiform user details --target-org <org>" for a full readiness diagnostic.', { metadata: { duration: Date.now() - startTime } });
+        }
+        // Gate 3: Global Profiling must be explicitly enabled
+        // Checks both: (a) config profile must exist, and (b) apiOnlyProfilingEnabled must be exactly true.
+        // When apiOnlyProfilingEnabled is undefined (e.g., Salesforce field returns null), access is denied.
+        if (!readiness.configProfile.isConfigured || readiness.configProfile.apiOnlyProfilingEnabled !== true) {
+            return createFailureResult(undefined, ServiceErrorCodes.GLOBAL_PROFILING_NOT_ENABLED, 'Cuneiform is installed and your permission sets are assigned, but Global Profiling is not enabled. ' +
+                'Run "sf cuneiform user details --target-org <org> --configure" to enable it, ' +
+                'or ask your Salesforce administrator to enable API-Only Profiling in the Configuration Profile.', { metadata: { duration: Date.now() - startTime } });
+        }
+        // Gate 4: Self-registration must be enabled for CLI self-provisioning
+        // This gate only applies to the configure flow (checked by callers), but validateProfilingAccess
+        // does NOT enforce it — it validates read access only. The configure flow checks this gate separately.
+        // See UserConfigurationService.buildConfigurationActions() for the enforcement point.
+        return createSuccessResult(undefined, {
+            message: 'Profiling access validated',
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+    /**
+     * Checks the feature status via the ISV profiling status REST endpoint.
+     *
+     * Calls `GET /services/apexrest/pnova/v1/profiling/status` to determine whether
+     * API-Based Profiling is enabled for this organization. This is Gate 0 — if the
+     * feature is not enabled, all other gates are moot.
+     *
+     * Graceful degradation:
+     * - On 404 (endpoint not found): returns success with `featureEnabled: true`.
+     * Older ISV packages may not expose this endpoint; we don't block them.
+     * - On other errors: returns failure with `FEATURE_STATUS_CHECK_FAILED`.
+     *
+     * @param restAdapter - The REST API adapter for making the HTTP request
+     * @returns ServiceResult containing FeatureStatus
+     *
+     * @example
+     * ```typescript
+     * const result = await service.checkFeatureStatus(restAdapter);
+     * if (result.success && !result.data.featureEnabled) {
+     *   // Block command execution — feature is disabled
+     * }
+     * ```
+     */
+    async checkFeatureStatus(restAdapter) {
+        const startTime = Date.now();
+        const statusUrl = '/services/apexrest/pnova/v1/profiling/status';
+        try {
+            this.logger?.log('Checking feature status via REST endpoint');
+            const result = await restAdapter.request({
+                url: statusUrl,
+                method: 'GET',
+            });
+            if (result.success) {
+                const duration = Date.now() - startTime;
+                this.logger?.log(`Feature status: featureEnabled=${String(result.data.featureEnabled)}`);
+                return createSuccessResult(result.data, {
+                    message: `Feature status: ${result.data.featureEnabled ? 'enabled' : 'disabled'}`,
+                    metadata: { duration },
+                });
+            }
+            // Check for 404 — graceful degradation for older ISV packages
+            const errorMessage = result.message ?? '';
+            if (errorMessage.includes('404') || errorMessage.includes('Not Found') || errorMessage.includes('NOT_FOUND')) {
+                this.logger?.log('Feature status endpoint not found (404) — assuming enabled (older ISV package)');
+                const duration = Date.now() - startTime;
+                return createSuccessResult({
+                    featureEnabled: true,
+                    apiBasedProfilingEnabled: true,
+                    selfRegistrationEnabled: false,
+                    packageVersion: 'unknown',
+                }, {
+                    message: 'Feature status endpoint not available — assuming enabled (older ISV package)',
+                    warnings: ['Status endpoint not found; feature status assumed enabled for backward compatibility'],
+                    metadata: { duration },
+                });
+            }
+            // Other errors — return failure
+            const duration = Date.now() - startTime;
+            return createFailureResult({
+                featureEnabled: false,
+                apiBasedProfilingEnabled: false,
+                selfRegistrationEnabled: false,
+                packageVersion: 'unknown',
+            }, ServiceErrorCodes.FEATURE_STATUS_CHECK_FAILED, errorMessage || 'Feature status check failed', { metadata: { duration } });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Feature status check failed: ${errorMessage}`);
+            // Check for 404 in exception messages too
+            if (errorMessage.includes('404') || errorMessage.includes('Not Found') || errorMessage.includes('NOT_FOUND')) {
+                const duration = Date.now() - startTime;
+                return createSuccessResult({
+                    featureEnabled: true,
+                    apiBasedProfilingEnabled: true,
+                    selfRegistrationEnabled: false,
+                    packageVersion: 'unknown',
+                }, {
+                    message: 'Feature status endpoint not available — assuming enabled (older ISV package)',
+                    warnings: ['Status endpoint not found; feature status assumed enabled for backward compatibility'],
+                    metadata: { duration },
+                });
+            }
+            return createFailureResult({
+                featureEnabled: false,
+                apiBasedProfilingEnabled: false,
+                selfRegistrationEnabled: false,
+                packageVersion: 'unknown',
+            }, ServiceErrorCodes.FEATURE_STATUS_CHECK_FAILED, errorMessage, { metadata: { duration: Date.now() - startTime } });
+        }
+    }
+    /**
+     * Attempts REST delegation for user readiness.
+     * Returns the successful result, or null to signal fallback to the local SOQL path.
+     * Falls back when REST returns cuneiformInstalled=false (Apex endpoint bug on some orgs).
+     */
+    async tryRestReadiness(userId, startTime) {
+        if (!this.restClient) {
+            return null;
+        }
+        const restResult = await this.checkReadinessViaRest(userId, startTime);
+        if (restResult.success && restResult.data.isCuneiformInstalled) {
+            return restResult;
+        }
+        this.logger?.log('REST readiness returned not-installed or failed — falling back to local SOQL');
+        return null;
+    }
+    /**
+     * Delegates user readiness check to the ISV REST API.
+     *
+     * @param userId - The Salesforce user ID to check
+     * @param startTime - Timestamp for duration tracking
+     * @returns ServiceResult containing UserReadiness from REST endpoint
+     */
+    async checkReadinessViaRest(userId, startTime) {
+        this.logger?.log('Delegating user readiness to ISV REST API (user-readiness)');
+        const emptyResult = UserReadinessService.createEmptyReadiness(userId);
+        const restResult = await this.restClient.checkUserReadiness(userId);
+        if (!restResult.success) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_READINESS_QUERY_FAILED, restResult.message ?? 'REST user-readiness failed', {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const response = restResult.data;
+        if (!response.success) {
+            const errorMsg = response.errors?.length > 0 ? response.errors[0] : 'Server-side readiness check failed';
+            return createFailureResult(emptyResult, ServiceErrorCodes.USER_READINESS_QUERY_FAILED, errorMsg, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const mappedResult = response.result
+            ? UserReadinessService.mapRestPayloadToUserReadiness(userId, response.result)
+            : emptyResult;
+        return createSuccessResult(mappedResult, {
+            message: 'User readiness checked via REST API',
+            metadata: { duration: Date.now() - startTime, strategyUsed: 'rest-api' },
+        });
+    }
+    /**
+     * Checks for required permission sets accessible through PermissionSetGroup membership.
+     *
+     * Two-step query approach for precision:
+     * 1. Get the specific PermissionSetGroup IDs assigned to this user
+     * 2. Check if those specific groups contain any of the missing required permission sets
+     *
+     * Both queries are tightly filtered to avoid pulling excess records:
+     * - Group query: filtered by AssigneeId AND PermissionSetGroupId != null
+     * - Component query: filtered by specific group IDs, permission set names, AND namespace
+     *
+     * @param userId - The Salesforce user ID
+     * @param missingNames - Permission set names not found via direct assignment
+     * @returns Map of permission set names to labels found through group membership
+     */
+    async getGroupAssignedPermissionSets(userId, missingNames) {
+        const foundLabels = new Map();
+        try {
+            // Step 2a: Get the user's PermissionSetGroup assignments
+            // Precise filter: only this user, only rows that ARE group assignments
+            const groupSoql = new CuneiformQueryBuilder()
+                .select(['PermissionSetGroupId'])
+                .from('PermissionSetAssignment')
+                .where('AssigneeId', '=', userId)
+                .andWhereNull('PermissionSetGroupId', false)
+                .toSOQL();
+            const groupResult = await this.soqlAdapter.query(groupSoql);
+            if (!groupResult.success || groupResult.data.records.length === 0) {
+                return foundLabels;
+            }
+            const groupIds = groupResult.data.records.map((r) => r.PermissionSetGroupId);
+            this.logger?.log(`User belongs to ${groupIds.length} permission set group(s)`);
+            // Step 2b: Check if those groups contain any of the missing required permission sets
+            // Precise filter: only the user's groups, only the missing names, only our namespace
+            const componentSoql = new CuneiformQueryBuilder()
+                .select(['PermissionSet.Name', 'PermissionSet.Label'])
+                .from('PermissionSetGroupComponent')
+                .where('PermissionSet.NamespacePrefix', '=', CUNEIFORM_NAMESPACE)
+                .andWhereIn('PermissionSetGroupId', groupIds)
+                .andWhereIn('PermissionSet.Name', [...missingNames])
+                .toSOQL();
+            const componentResult = await this.soqlAdapter.query(componentSoql);
+            if (!componentResult.success) {
+                return foundLabels;
+            }
+            for (const record of componentResult.data.records) {
+                foundLabels.set(record.PermissionSet.Name, record.PermissionSet.Label);
+            }
+            this.logger?.log(`Found ${foundLabels.size} permission set(s) via group membership`);
+        }
+        catch (error) {
+            // Group check is supplementary — don't fail the entire permission check
+            this.logger?.log(`Group permission check failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return foundLabels;
+    }
+}
+//# sourceMappingURL=UserReadinessService.js.map