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

package/lib/services/ObjectListCommandService.js

@@ -0,0 +1,904 @@
+/*
+ * 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';
+import { ServiceErrorCodes } from '../adapters/errors.js';
+import { CuneiformQueryBuilder } from '../adapters/soql/cuneiform-query-builder.js';
+import { categorizeNamespace } from './namespace-constants.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Service Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+/** Valid filter type values */
+const VALID_FILTER_TYPES = new Set(['all', 'standard', 'custom']);
+/** Valid classification values */
+const VALID_CLASSIFICATIONS = new Set(['customer', 'internal', 'all']);
+/** Valid sort field values */
+const VALID_SORT_FIELDS = new Set(['name', 'recordCount', 'label']);
+/**
+ * Orchestration service for the `sf cuneiform object list` command.
+ *
+ * Composes ObjectFilteringService for filtering and ContactPointService for
+ * contact point analysis. Computes summary statistics and namespace distribution.
+ *
+ * @design
+ * This is an orchestration service (not a domain service). It coordinates multiple
+ * services to fulfill command requirements, handles flag-specific logic, and
+ * transforms results into the command's expected output structure.
+ *
+ * @example
+ * ```typescript
+ * const service = new ObjectListCommandService({
+ *   objectFilteringService,
+ *   contactPointService,
+ *   restAdapter,
+ *   logger: console,
+ * });
+ *
+ * // List custom objects with contact point analysis
+ * const result = await service.listObjects({
+ *   filter: 'custom',
+ *   withRecords: true,
+ *   withContactPoints: true,
+ *   minRecords: 1000,
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Found ${result.data.summary.totalObjects} objects`);
+ *   console.log(`Standard: ${result.data.summary.standardObjects}`);
+ *   console.log(`Custom: ${result.data.summary.customObjects}`);
+ * }
+ * ```
+ */
+export class ObjectListCommandService {
+    objectFilteringService;
+    contactPointService;
+    restApiAdapter;
+    soqlAdapter;
+    logger;
+    constructor(config) {
+        this.objectFilteringService = config.objectFilteringService;
+        this.contactPointService = config.contactPointService;
+        this.restApiAdapter = config.restApiAdapter;
+        this.soqlAdapter = config.soqlAdapter;
+        this.logger = config.logger;
+    }
+    /**
+     * Groups objects by their namespace category.
+     *
+     * Uses categorizeNamespace() to classify each object's namespace,
+     * then groups into standard/industry/managed/custom buckets with
+     * human-readable labels.
+     *
+     * @param objects - Array of ObjectListItem to group
+     * @returns Array of NamespaceCategoryGroup, ordered: standard, industry, managed, custom.
+     * Empty categories are omitted.
+     */
+    static groupObjectsByNamespaceCategory(objects) {
+        const categoryLabels = {
+            standard: 'Standard Objects',
+            industry: 'Industry Cloud',
+            managed: 'Managed Packages',
+            custom: 'Custom Packages',
+        };
+        const displayOrder = ['standard', 'industry', 'managed', 'custom'];
+        // Group objects by category
+        const grouped = new Map();
+        for (const obj of objects) {
+            const category = categorizeNamespace(obj.namespace);
+            const existing = grouped.get(category);
+            if (existing) {
+                existing.push(obj);
+            }
+            else {
+                grouped.set(category, [obj]);
+            }
+        }
+        // Build results in display order, skipping empty categories
+        const results = [];
+        for (const category of displayOrder) {
+            const categoryObjects = grouped.get(category);
+            if (categoryObjects && categoryObjects.length > 0) {
+                results.push({
+                    category,
+                    label: categoryLabels[category],
+                    objects: categoryObjects,
+                    count: categoryObjects.length,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Sorts objects by the specified field.
+     *
+     * @param objects - Objects to sort
+     * @param sort - Sort field
+     * @returns Sorted array (new array, not mutated)
+     */
+    static sortObjects(objects, sort) {
+        const sorted = [...objects];
+        sorted.sort((a, b) => {
+            switch (sort) {
+                case 'name':
+                    return a.apiName.localeCompare(b.apiName);
+                case 'label':
+                    return a.label.localeCompare(b.label);
+                case 'recordCount': {
+                    // Sort by record count descending (highest first), then by label ascending for ties.
+                    // CLI-4214: an unknown count (undefined) sorts as the lowest value so it lands last.
+                    const countDiff = (b.recordCount ?? -1) - (a.recordCount ?? -1);
+                    if (countDiff !== 0)
+                        return countDiff;
+                    return a.label.localeCompare(b.label);
+                }
+            }
+        });
+        return sorted;
+    }
+    /**
+     * Determines whether any enrichment flag requiring describe calls is active.
+     */
+    static needsDescribeCalls(options) {
+        return (options.includeFieldCounts === true || options.includeReferences === true || options.withContactPoints === true);
+    }
+    /**
+     * Builds FilterOptions from command options.
+     *
+     * `excludeSystemObjects` is set unconditionally — system suffix types
+     * (`__Feed`, `__History`, `__Share`, `__mdt`, `__ChangeEvent`, `__e`) are never
+     * valid object list targets. The shared `NON_DATA_SUFFIX_PATTERN` filter lives
+     * in `ObjectFilteringService.applySystemObjectExclusion` (CLI-3374 mirrors the
+     * opt-in PR #292 applied to `definition create`).
+     */
+    static buildFilterOptions(options) {
+        const filterOptions = {
+            type: options.filter === 'all' ? undefined : options.filter,
+            classification: options.classification,
+            withRecords: options.withRecords,
+            withoutRecords: options.withoutRecords,
+            withOwner: options.withOwner,
+            hasRecordTypes: options.withRecordTypes,
+            excludeSystemObjects: true,
+        };
+        if (options.namespace !== undefined) {
+            filterOptions.namespace = options.namespace;
+        }
+        if (options.pattern !== undefined) {
+            filterOptions.nameFilter = {
+                value: options.pattern,
+                operator: options.pattern.includes('*') ? 'wildcard' : 'contains',
+            };
+        }
+        return filterOptions;
+    }
+    /**
+     * Validates command options and returns an error message if invalid.
+     *
+     * @param options - Options to validate
+     * @returns Error message if invalid, undefined if valid
+     */
+    static validateOptions(options) {
+        // Validate filter type
+        if (options.filter !== undefined && !VALID_FILTER_TYPES.has(options.filter)) {
+            return `Invalid filter type: "${options.filter}". Must be 'all', 'standard', or 'custom'.`;
+        }
+        // Validate sort field
+        if (options.sort !== undefined && !VALID_SORT_FIELDS.has(options.sort)) {
+            return `Invalid sort field: "${options.sort}". Must be 'name', 'recordCount', or 'label'.`;
+        }
+        // Validate mutually exclusive flags
+        if (options.withRecords && options.withoutRecords) {
+            return 'Cannot specify both --with-records and --without-records.';
+        }
+        // Validate classification
+        if (options.classification !== undefined && !VALID_CLASSIFICATIONS.has(options.classification)) {
+            return `Invalid classification: "${options.classification}". Must be 'customer', 'internal', or 'all'.`;
+        }
+        // Validate minRecords
+        if (options.minRecords !== undefined) {
+            if (!Number.isInteger(options.minRecords) || options.minRecords < 0) {
+                return `Invalid min-records value: ${options.minRecords}. Must be a non-negative integer.`;
+            }
+        }
+        // Validate limit
+        if (options.limit !== undefined) {
+            if (!Number.isInteger(options.limit) || options.limit < 1) {
+                return `Invalid limit value: ${options.limit}. Must be a positive integer.`;
+            }
+        }
+        return ObjectListCommandService.validateObjectFlagConflicts(options);
+    }
+    /**
+     * Validates that `--object` is not combined with mutually exclusive flags.
+     *
+     * @returns Error message if a conflict is detected, undefined if valid
+     */
+    static validateObjectFlagConflicts(options) {
+        if (options.object === undefined)
+            return undefined;
+        if (options.object.trim().length === 0) {
+            return 'Object name cannot be empty.';
+        }
+        if (options.filter !== undefined && options.filter !== 'all') {
+            return 'Cannot use --filter with --object. These flags are mutually exclusive.';
+        }
+        if (options.namespace !== undefined) {
+            return 'Cannot use --namespace with --object. These flags are mutually exclusive.';
+        }
+        if (options.pattern !== undefined) {
+            return 'Cannot use --pattern with --object. These flags are mutually exclusive.';
+        }
+        if (options.withoutRecords) {
+            return 'Cannot use --without-records with --object. These flags are mutually exclusive.';
+        }
+        if (options.minRecords !== undefined && options.minRecords > 0) {
+            return 'Cannot use --min-records with --object. These flags are mutually exclusive.';
+        }
+        return undefined;
+    }
+    /**
+     * Determines if an object is external (ends with __x).
+     *
+     * @param name - Object API name
+     * @returns True if external object
+     */
+    static isExternalObject(name) {
+        return name.endsWith('__x');
+    }
+    /**
+     * Determines if an object is a Big Object (ends with __b).
+     *
+     * @param name - Object API name
+     * @returns True if Big Object
+     */
+    static isBigObject(name) {
+        return name.endsWith('__b');
+    }
+    /**
+     * Determines if an object is a Custom Metadata Type (ends with __mdt).
+     *
+     * @param name - Object API name
+     * @returns True if Custom Metadata Type
+     */
+    static isCustomMetadataType(name) {
+        return name.endsWith('__mdt');
+    }
+    /**
+     * Determines if an object is a Platform Event (ends with __e).
+     *
+     * @param name - Object API name
+     * @returns True if Platform Event
+     */
+    static isPlatformEvent(name) {
+        return name.endsWith('__e');
+    }
+    /**
+     * Extracts namespace from an object API name.
+     *
+     * @param name - Object API name
+     * @returns Namespace prefix or null for unmanaged objects
+     */
+    static extractNamespace(name) {
+        const parts = name.split('__');
+        // Namespace pattern: ns__Object__c has 3+ parts
+        if (parts.length >= 3) {
+            return parts[0];
+        }
+        return null;
+    }
+    /**
+     * Computes namespace distribution from a list of objects.
+     *
+     * @param objects - Array of SObjectInfo
+     * @returns Array of namespace counts, sorted by count descending
+     */
+    static computeNamespaceCounts(objects) {
+        const counts = new Map();
+        for (const obj of objects) {
+            const ns = obj.namespace ?? null;
+            counts.set(ns, (counts.get(ns) ?? 0) + 1);
+        }
+        // Convert to array and sort by count descending, then by namespace
+        const result = [];
+        for (const [namespace, count] of counts) {
+            result.push({ namespace, count });
+        }
+        result.sort((a, b) => {
+            if (b.count !== a.count) {
+                return b.count - a.count;
+            }
+            // null namespace sorts last
+            if (a.namespace === null)
+                return 1;
+            if (b.namespace === null)
+                return -1;
+            return a.namespace.localeCompare(b.namespace);
+        });
+        return result;
+    }
+    /**
+     * Creates an empty ObjectListResult for error cases.
+     *
+     * @param options - Applied filter options
+     * @returns Empty result structure
+     */
+    static createEmptyResult(options) {
+        return {
+            summary: {
+                totalObjects: 0,
+                withRecords: 0,
+                withoutRecords: 0,
+                standardObjects: 0,
+                customObjects: 0,
+                externalObjects: 0,
+                withNamespace: 0,
+                withoutNamespace: 0,
+                namespaceCounts: [],
+                totalRecordCount: 0,
+            },
+            filters: options,
+            objects: [],
+        };
+    }
+    /**
+     * Transforms ContactPointAnalysis to ContactPointSummary.
+     *
+     * @param analysis - ContactPointAnalysis from ContactPointService
+     * @returns ContactPointSummary for ObjectListItem
+     */
+    static transformContactPointAnalysis(analysis) {
+        const emailFields = [];
+        const phoneFields = [];
+        const urlFields = [];
+        for (const field of analysis.contactPointFields) {
+            const fieldInfo = {
+                apiName: field.fieldName,
+                label: field.fieldLabel,
+                isStandard: !field.fieldName.endsWith('__c'),
+            };
+            switch (field.contactPointType) {
+                case 'email':
+                    emailFields.push(fieldInfo);
+                    break;
+                case 'phone':
+                    phoneFields.push(fieldInfo);
+                    break;
+                // URL fields are detected by fieldType 'url' or name patterns
+                // ContactPointService uses 'other' for URL-like fields
+                default:
+                    // Check if it might be a URL field by name
+                    if (field.fieldName.toLowerCase().includes('url') || field.fieldName.toLowerCase().includes('website')) {
+                        urlFields.push(fieldInfo);
+                    }
+            }
+        }
+        return {
+            emailFields,
+            phoneFields,
+            urlFields,
+            summary: {
+                emailCount: emailFields.length,
+                phoneCount: phoneFields.length,
+                urlCount: urlFields.length,
+                totalContactPoints: emailFields.length + phoneFields.length + urlFields.length,
+            },
+        };
+    }
+    /**
+     * Computes summary statistics from filtered objects.
+     *
+     * @param objects - Filtered SObjectInfo array
+     * @returns ObjectListSummary
+     */
+    static computeSummary(objects) {
+        let withRecords = 0;
+        let withoutRecords = 0;
+        let standardObjects = 0;
+        let customObjects = 0;
+        let externalObjects = 0;
+        let withNamespace = 0;
+        let withoutNamespace = 0;
+        let withOwnerCount = 0;
+        let withRecordTypesCount = 0;
+        let hasOwnerData = false;
+        let hasRecordTypesData = false;
+        let totalRecordCount = 0;
+        for (const obj of objects) {
+            // Record count categorization and accumulation
+            totalRecordCount += obj.recordCount ?? 0;
+            if (obj.recordCount !== undefined && obj.recordCount > 0) {
+                withRecords++;
+            }
+            else {
+                withoutRecords++;
+            }
+            // Object type categorization
+            if (obj.isCustom) {
+                customObjects++;
+            }
+            else {
+                standardObjects++;
+            }
+            // External object count
+            if (ObjectListCommandService.isExternalObject(obj.name)) {
+                externalObjects++;
+            }
+            // Namespace presence count
+            const ns = ObjectListCommandService.extractNamespace(obj.name);
+            if (ns) {
+                withNamespace++;
+            }
+            else {
+                withoutNamespace++;
+            }
+            // Owner field count (only meaningful when data is populated)
+            if (obj.hasOwner !== undefined) {
+                hasOwnerData = true;
+                if (obj.hasOwner)
+                    withOwnerCount++;
+            }
+            // Record types count (only meaningful when data is populated)
+            if (obj.hasRecordTypes !== undefined) {
+                hasRecordTypesData = true;
+                if (obj.hasRecordTypes)
+                    withRecordTypesCount++;
+            }
+        }
+        return {
+            totalObjects: objects.length,
+            withRecords,
+            withoutRecords,
+            standardObjects,
+            customObjects,
+            externalObjects,
+            withNamespace,
+            withoutNamespace,
+            withOwner: hasOwnerData ? withOwnerCount : undefined,
+            withRecordTypes: hasRecordTypesData ? withRecordTypesCount : undefined,
+            namespaceCounts: ObjectListCommandService.computeNamespaceCounts(objects),
+            totalRecordCount,
+        };
+    }
+    /**
+     * Computes enrichment aggregate totals from post-enrichment object items.
+     * Returns a partial summary with only the enrichment totals that are active.
+     */
+    static computeEnrichmentTotals(items, options) {
+        const totals = {};
+        if (options.includeFieldCounts) {
+            totals.totalFieldCount = items.reduce((sum, obj) => sum + (obj.totalFields ?? 0), 0);
+            totals.totalCustomFieldCount = items.reduce((sum, obj) => sum + (obj.customFields ?? 0), 0);
+        }
+        if (options.includeReferences) {
+            totals.totalReferenceCount = items.reduce((sum, obj) => sum + (obj.lookupFieldCount ?? 0), 0);
+        }
+        if (options.withContactPoints) {
+            totals.totalContactPoints = items.reduce((sum, obj) => sum + (obj.contactPoints?.summary.totalContactPoints ?? 0), 0);
+        }
+        if (options.withRecordTypes) {
+            totals.totalRecordTypeCount = items.reduce((sum, obj) => sum + (obj.recordTypeCount ?? 0), 0);
+        }
+        if (options.withBusinessProcess) {
+            totals.totalBusinessProcessCount = items.reduce((sum, obj) => sum + (obj.businessProcessCount ?? 0), 0);
+        }
+        return totals;
+    }
+    /**
+     * Normalizes a warnings array to `undefined` when empty (CLI-4214).
+     * Keeps the truncation disclosure on the result while avoiding empty arrays.
+     *
+     * @param warnings - Warnings from the filtering service result
+     * @returns The warnings array when non-empty, otherwise undefined
+     */
+    static normalizeWarnings(warnings) {
+        return warnings && warnings.length > 0 ? warnings : undefined;
+    }
+    /**
+     * Transforms SObjectInfo array to ObjectListItem array.
+     *
+     * @param objects - SObjectInfo array from filtering
+     * @returns ObjectListItem array
+     */
+    static transformToListItems(objects) {
+        const items = [];
+        for (const obj of objects) {
+            const item = {
+                apiName: obj.name,
+                label: obj.label,
+                keyPrefix: null, // Will be populated if available from describe
+                // CLI-4214: carry the count and its provenance verbatim. Do NOT coerce an
+                // undefined count to 0 — an unknown count must render as unknown, not zero.
+                recordCount: obj.recordCount,
+                recordCountProvenance: obj.recordCountProvenance,
+                isCustom: obj.isCustom,
+                isExternal: ObjectListCommandService.isExternalObject(obj.name),
+                namespace: ObjectListCommandService.extractNamespace(obj.name),
+                isCustomer: obj.isCustomer,
+                hasOwner: obj.hasOwner,
+                hasRecordTypes: obj.hasRecordTypes,
+            };
+            items.push(item);
+        }
+        return items;
+    }
+    /**
+     * Lists Salesforce objects with filtering, summary statistics, and optional contact point analysis.
+     *
+     * @param options - Command options mapping to CLI flags
+     * @returns ServiceResult containing ObjectListResult
+     */
+    async listObjects(options = {}) {
+        const startTime = Date.now();
+        const emptyResult = ObjectListCommandService.createEmptyResult(options);
+        // Validate options
+        const validationError = ObjectListCommandService.validateOptions(options);
+        if (validationError) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_LIST_QUERY_FAILED, validationError, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        try {
+            this.logger?.log('ObjectListCommandService: Starting object list operation');
+            // Single-object short-circuit: bypass ObjectFilteringService and REST delegation
+            if (options.object) {
+                return await this.listSingleObject(options.object, options, startTime);
+            }
+            // Build filter options and execute filtering
+            const filterOptions = ObjectListCommandService.buildFilterOptions(options);
+            const filterResult = await this.objectFilteringService.filter(filterOptions);
+            if (!filterResult.success) {
+                return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_LIST_FILTER_FAILED, filterResult.message ?? 'Filter operation failed', { metadata: { duration: Date.now() - startTime } });
+            }
+            let filteredObjects = filterResult.data;
+            // Exclude Big Objects by default (not queryable via standard SOQL)
+            filteredObjects = filteredObjects.filter((obj) => !ObjectListCommandService.isBigObject(obj.name));
+            // Exclude Custom Metadata Types by default (configuration metadata, not data objects)
+            filteredObjects = filteredObjects.filter((obj) => !ObjectListCommandService.isCustomMetadataType(obj.name));
+            // Exclude Platform Events by default (event bus objects, not queryable data objects)
+            filteredObjects = filteredObjects.filter((obj) => !ObjectListCommandService.isPlatformEvent(obj.name));
+            // Apply minRecords filter
+            if (options.minRecords !== undefined && options.minRecords > 0) {
+                filteredObjects = filteredObjects.filter((obj) => (obj.recordCount ?? 0) >= options.minRecords);
+            }
+            // Compute summary statistics (before limiting)
+            const summary = ObjectListCommandService.computeSummary(filteredObjects);
+            // Transform to ObjectListItem array
+            let objectItems = ObjectListCommandService.transformToListItems(filteredObjects);
+            // Sort before limiting — sort must happen on the full set, not a truncated page.
+            // CLI-3601: apply the recordCount-desc default at the service layer so programmatic
+            // callers get deterministic ordering even when options.sort is omitted. ObjectListService
+            // (the lower-level composition service used by the MCP `cuneiform_object_list` tool)
+            // applies the same default in its own `listObjects()` — see ObjectListService.ts § "Sort".
+            // The command-layer flag default ('recordCount') is preserved for help-text
+            // discoverability but is redundant w.r.t. this service-level guarantee.
+            const sortField = options.sort ?? 'recordCount';
+            objectItems = ObjectListCommandService.sortObjects(objectItems, sortField);
+            // Apply limit after sort
+            if (options.limit !== undefined && options.limit < objectItems.length) {
+                objectItems = objectItems.slice(0, options.limit);
+            }
+            // Apply enrichments (field counts, references, record types, contact points)
+            // Shared describe session: when multiple field-data enrichments are active,
+            // describe calls are made once and shared across all enrichments.
+            const hasEnrichments = options.includeFieldCounts === true ||
+                options.includeReferences === true ||
+                options.withContactPoints === true ||
+                options.withRecordTypes === true ||
+                options.withBusinessProcess === true;
+            if (hasEnrichments) {
+                objectItems = await this.applyEnrichments(objectItems, options);
+            }
+            // Compute enrichment aggregate totals from post-enrichment data
+            Object.assign(summary, ObjectListCommandService.computeEnrichmentTotals(objectItems, options));
+            // Build contact point analysis metadata (if requested)
+            let contactPointAnalysis;
+            if (options.withContactPoints) {
+                const minThreshold = options.minRecords ?? 0;
+                const analyzedCount = objectItems.filter((obj) => (obj.recordCount ?? -1) >= minThreshold).length;
+                contactPointAnalysis = {
+                    analyzedCount,
+                    minRecordsThreshold: minThreshold,
+                };
+            }
+            const result = {
+                summary,
+                filters: options,
+                objects: objectItems,
+                // CLI-4214: surface the filtering chain's reconciliation truncation disclosure.
+                warnings: ObjectListCommandService.normalizeWarnings(filterResult.warnings),
+                contactPointAnalysis,
+            };
+            const duration = Date.now() - startTime;
+            this.logger?.log(`ObjectListCommandService: Completed in ${duration}ms, found ${summary.totalObjects} objects`);
+            return createSuccessResult(result, {
+                message: `Found ${summary.totalObjects} objects matching filter criteria`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`ObjectListCommandService: Failed - ${errorMessage}`);
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_LIST_QUERY_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Single-object short-circuit for the `--object` flag.
+     *
+     * Bypasses ObjectFilteringService entirely. Uses describeGlobal to confirm
+     * the object exists, then getRecordCounts to fetch the real record count
+     * in one targeted call.
+     *
+     * @param objectName - API name of the target object (case-insensitive match)
+     * @param options - Full command options (enrichments still apply)
+     * @param startTime - Operation start timestamp for duration tracking
+     */
+    async listSingleObject(objectName, options, startTime) {
+        const emptyResult = ObjectListCommandService.createEmptyResult(options);
+        if (!this.restApiAdapter) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_LIST_QUERY_FAILED, '--object requires a REST API adapter; none was provided', { metadata: { duration: Date.now() - startTime } });
+        }
+        // Verify object exists via describeGlobal (case-insensitive name match)
+        const globalResult = await this.restApiAdapter.describeGlobal();
+        if (!globalResult.success) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_LIST_GLOBAL_DESCRIBE_FAILED, globalResult.message ?? 'Global describe failed', { metadata: { duration: Date.now() - startTime } });
+        }
+        const sobject = globalResult.data.sobjects.find((s) => s.name.toLowerCase() === objectName.toLowerCase());
+        if (!sobject) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_LIST_QUERY_FAILED, `Object "${objectName}" was not found in this org`, { metadata: { duration: Date.now() - startTime } });
+        }
+        // Fetch real record count directly — no filter chain needed.
+        // Fail loudly on count-fetch failure: returning recordCount: 0 silently would recreate the
+        // exact "default-50 trap" CLI-3041 was created to fix.
+        const countResult = await this.restApiAdapter.getRecordCounts([sobject.name]);
+        if (!countResult.success) {
+            return createFailureResult(emptyResult, ServiceErrorCodes.OBJECT_LIST_QUERY_FAILED, `Failed to fetch record count for "${sobject.name}": ${countResult.message ?? 'unknown error'}`, { metadata: { duration: Date.now() - startTime } });
+        }
+        const recordCount = countResult.data.get(sobject.name) ?? 0;
+        const info = {
+            name: sobject.name,
+            label: sobject.label,
+            isCustom: sobject.custom,
+            namespace: ObjectListCommandService.extractNamespace(sobject.name) ?? undefined,
+            recordCount,
+            // CLI-4214: the single-object path fetches an authoritative count via getRecordCounts.
+            recordCountProvenance: 'queried',
+        };
+        const summary = ObjectListCommandService.computeSummary([info]);
+        // Build ObjectListItem, enriching keyPrefix and labelPlural from global describe
+        const baseItem = ObjectListCommandService.transformToListItems([info])[0];
+        let objectItems = [
+            { ...baseItem, keyPrefix: sobject.keyPrefix, labelPlural: sobject.labelPlural },
+        ];
+        // Apply any requested enrichments (field counts, contact points, etc.)
+        const hasEnrichments = options.includeFieldCounts === true ||
+            options.includeReferences === true ||
+            options.withContactPoints === true ||
+            options.withRecordTypes === true ||
+            options.withBusinessProcess === true;
+        if (hasEnrichments) {
+            objectItems = await this.applyEnrichments(objectItems, options);
+        }
+        Object.assign(summary, ObjectListCommandService.computeEnrichmentTotals(objectItems, options));
+        let contactPointAnalysis;
+        if (options.withContactPoints) {
+            contactPointAnalysis = {
+                analyzedCount: objectItems.length,
+                minRecordsThreshold: options.minRecords ?? 0,
+            };
+        }
+        const result = {
+            summary,
+            filters: options,
+            objects: objectItems,
+            contactPointAnalysis,
+        };
+        const duration = Date.now() - startTime;
+        this.logger?.log(`ObjectListCommandService: Single-object lookup completed in ${duration}ms — ${sobject.name} (${recordCount} records)`);
+        return createSuccessResult(result, {
+            message: `Found ${sobject.name} with ${recordCount} records`,
+            metadata: { duration },
+        });
+    }
+    /**
+     * Fetches object describes for enrichment, shared across all field-data flags.
+     *
+     * @param objectNames - Object API names to describe
+     * @returns Map of object name to DescribeSObjectResult
+     */
+    async fetchObjectDescribes(objectNames) {
+        if (!this.restApiAdapter || objectNames.length === 0) {
+            return new Map();
+        }
+        this.logger?.log(`ObjectListCommandService: Fetching describes for ${objectNames.length} objects`);
+        const result = await this.restApiAdapter.describeObjects(objectNames);
+        if (result.success) {
+            return result.data;
+        }
+        this.logger?.log(`ObjectListCommandService: Describe fetch failed: ${result.message ?? 'unknown error'}`);
+        return new Map();
+    }
+    /**
+     * Fetches record type counts via aggregate SOQL.
+     *
+     * @returns Map of SobjectType to active record type count
+     */
+    async fetchRecordTypeCounts() {
+        if (!this.soqlAdapter) {
+            return new Map();
+        }
+        this.logger?.log('ObjectListCommandService: Fetching record type counts');
+        const soql = new CuneiformQueryBuilder()
+            .select(['SobjectType', 'COUNT(Id) cnt'])
+            .from('RecordType')
+            .where('IsActive', '=', true)
+            .groupBy(['SobjectType'])
+            .toSOQL();
+        const result = await this.soqlAdapter.query(soql);
+        const counts = new Map();
+        if (result.success) {
+            for (const record of result.data.records) {
+                counts.set(record.SobjectType, record.cnt);
+            }
+        }
+        else {
+            this.logger?.log(`ObjectListCommandService: Record type count query failed: ${result.message ?? 'unknown error'}`);
+        }
+        return counts;
+    }
+    /**
+     * Fetches active business process counts via aggregate SOQL.
+     *
+     * BusinessProcess records are linked to objects via the TableEnumOrId field,
+     * which maps to the SobjectType (e.g., 'Opportunity', 'Lead', 'Case', 'Solution').
+     *
+     * @returns Map of SobjectType to active business process count
+     */
+    async fetchBusinessProcessCounts() {
+        if (!this.soqlAdapter) {
+            return new Map();
+        }
+        this.logger?.log('ObjectListCommandService: Fetching business process counts');
+        const soql = new CuneiformQueryBuilder()
+            .select(['TableEnumOrId', 'COUNT(Id) cnt'])
+            .from('BusinessProcess')
+            .where('IsActive', '=', true)
+            .groupBy(['TableEnumOrId'])
+            .toSOQL();
+        const result = await this.soqlAdapter.query(soql);
+        const counts = new Map();
+        if (result.success) {
+            for (const record of result.data.records) {
+                counts.set(record.TableEnumOrId, record.cnt);
+            }
+        }
+        else {
+            this.logger?.log(`ObjectListCommandService: Business process count query failed: ${result.message ?? 'unknown error'}`);
+        }
+        return counts;
+    }
+    /**
+     * Applies enrichment data (field counts, references, record types, business processes, contact points) to object items.
+     *
+     * When multiple field-data enrichments are active, describe calls are shared (not duplicated).
+     *
+     * @param objectItems - Object items to enrich
+     * @param options - Command options determining which enrichments to apply
+     * @returns Enriched object items
+     */
+    async applyEnrichments(objectItems, options) {
+        const objectNames = objectItems.map((obj) => obj.apiName);
+        let enrichedItems = [...objectItems];
+        const progress = options.onProgress;
+        // Shared describe session: fetch once, use for all field-data enrichments
+        let describeMap;
+        if (ObjectListCommandService.needsDescribeCalls(options)) {
+            progress?.('Retrieving object metadata...');
+            describeMap = await this.fetchObjectDescribes(objectNames);
+        }
+        // Apply field count enrichment
+        if (options.includeFieldCounts && describeMap) {
+            progress?.('Extracting field counts...');
+            const dm = describeMap;
+            enrichedItems = enrichedItems.map((item) => {
+                const describe = dm.get(item.apiName);
+                if (describe) {
+                    return {
+                        ...item,
+                        totalFields: describe.fields.length,
+                        customFields: describe.fields.filter((f) => f.custom).length,
+                    };
+                }
+                return item;
+            });
+        }
+        // Apply reference field enrichment
+        if (options.includeReferences && describeMap) {
+            progress?.('Extracting reference fields...');
+            const dm = describeMap;
+            enrichedItems = enrichedItems.map((item) => {
+                const describe = dm.get(item.apiName);
+                if (describe) {
+                    return {
+                        ...item,
+                        lookupFieldCount: describe.fields.filter((f) => f.referenceTo && f.referenceTo.length > 0).length,
+                    };
+                }
+                return item;
+            });
+        }
+        // Apply record type count enrichment (independent SOQL, not from describe)
+        if (options.withRecordTypes) {
+            progress?.('Retrieving record type counts...');
+            const recordTypeCounts = await this.fetchRecordTypeCounts();
+            enrichedItems = enrichedItems.map((item) => ({
+                ...item,
+                recordTypeCount: recordTypeCounts.get(item.apiName) ?? 0,
+            }));
+        }
+        // Apply business process count enrichment (independent SOQL, not from describe)
+        if (options.withBusinessProcess) {
+            progress?.('Retrieving business process counts...');
+            const businessProcessCounts = await this.fetchBusinessProcessCounts();
+            enrichedItems = enrichedItems.map((item) => ({
+                ...item,
+                businessProcessCount: businessProcessCounts.get(item.apiName) ?? 0,
+            }));
+        }
+        // Apply contact point enrichment (uses shared describe if available)
+        if (options.withContactPoints) {
+            progress?.('Classifying contact points...');
+            const minThreshold = options.minRecords ?? 0;
+            const objectNamesToAnalyze = enrichedItems
+                .filter((obj) => (obj.recordCount ?? -1) >= minThreshold)
+                .map((obj) => obj.apiName);
+            this.logger?.log(`ObjectListCommandService: Analyzing contact points for ${objectNamesToAnalyze.length} objects (threshold: ${minThreshold})`);
+            const contactPointResults = await this.fetchContactPoints(objectNamesToAnalyze);
+            enrichedItems = enrichedItems.map((item) => {
+                const cp = contactPointResults.get(item.apiName);
+                return {
+                    ...item,
+                    contactPoints: contactPointResults.has(item.apiName) ? cp : undefined,
+                };
+            });
+        }
+        return enrichedItems;
+    }
+    /**
+     * Fetches contact point analysis for a list of object names.
+     *
+     * Uses parallel execution with per-promise catch to prevent one failure
+     * from blocking others. Returns a map of object name to contact point summary.
+     *
+     * @param objectNames - Object API names to analyze
+     * @returns Map of object name to ContactPointSummary (or null on failure)
+     */
+    async fetchContactPoints(objectNames) {
+        const resultsMap = new Map();
+        const fetchPromises = objectNames.map(async (objectName) => {
+            try {
+                const cpResult = await this.contactPointService.analyzeContactPoints(objectName);
+                if (cpResult.success) {
+                    resultsMap.set(objectName, ObjectListCommandService.transformContactPointAnalysis(cpResult.data));
+                }
+                else {
+                    resultsMap.set(objectName, null);
+                    this.logger?.log(`Contact point analysis failed for ${objectName}: ${cpResult.message ?? 'unknown error'}`);
+                }
+            }
+            catch (error) {
+                resultsMap.set(objectName, null);
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                this.logger?.log(`Contact point analysis error for ${objectName}: ${errorMessage}`);
+            }
+        });
+        await Promise.all(fetchPromises);
+        return resultsMap;
+    }
+}
+//# sourceMappingURL=ObjectListCommandService.js.map