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

package/lib/utils/formatting/object-list-display.js

@@ -0,0 +1,718 @@
+/*
+ * 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.
+ */
+/**
+ * Display formatting functions for the `sf cuneiform object list` command.
+ *
+ * Extracted from the command class to keep the command as a thin orchestration
+ * shell. All functions are pure (no `this` references) and accept a `log`
+ * callback for output. Functions compose primitives from the shared formatting
+ * barrel (`utils/formatting/index.ts`).
+ *
+ * @module utils/formatting/object-list-display
+ */
+import { makeTable } from '@oclif/table';
+import { Messages } from '@salesforce/core';
+import { ObjectListCommandService } from '../../services/ObjectListCommandService.js';
+import { OrgInfoService } from '../../services/OrgInfoService.js';
+import { formatNumber, formatNamespace, formatEmptyState, renderSummaryBox, sectionHeader, sectionHeaderWithCount, logSectionGap, } from './index.js';
+/**
+ * Default border style for all tables rendered by this module.
+ */
+const TABLE_BORDER_STYLE = 'headers-only';
+/**
+ * Lazily loads messages for the object.list command.
+ * Using a getter to avoid module-level side effects.
+ */
+function getMessages() {
+    return Messages.loadMessages('@peernova/cuneiform-sf', 'object.list');
+}
+/**
+ * Renders the record-count cell for an object, disclosing count provenance (CLI-4214).
+ *
+ * - `undefined` recordCount → the unknown-count placeholder (em dash). NEVER 0.
+ * - `recordCountProvenance === 'limits'` → APPROXIMATE: prefixed with `~`.
+ * - otherwise (authoritative `'queried'` or a count with no provenance) → plain number.
+ *
+ * @param obj - The object list item
+ * @returns The display string for the record count (unpadded)
+ */
+export function formatRecordCount(obj) {
+    const msgs = getMessages();
+    if (obj.recordCount === undefined) {
+        return msgs.getMessage('output.objects.unknownRecordCount');
+    }
+    const rendered = formatNumber(obj.recordCount);
+    return obj.recordCountProvenance === 'limits' ? `~${rendered}` : rendered;
+}
+/**
+ * Computes per-category contact point totals across all objects.
+ *
+ * @param objects - The object list items to aggregate
+ * @returns Totals for email, phone, and URL contact point fields
+ */
+export function computeCpCategoryTotals(objects) {
+    let email = 0;
+    let phone = 0;
+    let url = 0;
+    for (const obj of objects) {
+        const cp = obj.contactPoints?.summary;
+        if (cp) {
+            email += cp.emailCount ?? 0;
+            phone += cp.phoneCount ?? 0;
+            url += cp.urlCount ?? 0;
+        }
+    }
+    return { email, phone, url };
+}
+/**
+ * Displays the complete object list results in table format.
+ *
+ * Orchestrates all display sub-sections: org identity, active filters,
+ * summary box, namespace distribution, object table, and next steps.
+ *
+ * @param log - The logging function (typically `this.log.bind(this)`)
+ * @param data - The ObjectListResult from the service
+ * @param orgIdentity - The org identity data (optional)
+ * @param instanceUrl - The org instance URL (optional)
+ * @param username - The target org username for Next Steps commands
+ */
+export function displayResults(log, data, orgIdentity, instanceUrl, username) {
+    const msgs = getMessages();
+    const { summary } = data;
+    // Sort objects at render time (presentation concern, not service concern)
+    const sortField = data.filters.sort ?? 'recordCount';
+    const objects = ObjectListCommandService.sortObjects(data.objects, sortField);
+    // Display contextual title and Org Identity section (non-fatal if absent)
+    if (orgIdentity?.organizationId) {
+        const orgName = orgIdentity.organizationName ?? '(unknown)';
+        const orgType = OrgInfoService.classifyOrgType(orgIdentity.isSandbox ?? false, orgIdentity.organizationType);
+        log('');
+        log(msgs.getMessage('output.title', [orgName, orgType]));
+        logSectionGap(log);
+        log(renderSummaryBox({
+            title: msgs.getMessage('output.identity.header'),
+            entries: [
+                { key: msgs.getMessage('output.identity.orgName'), value: orgName },
+                { key: msgs.getMessage('output.identity.orgId'), value: orgIdentity.organizationId },
+                { key: msgs.getMessage('output.identity.instanceUrl'), value: instanceUrl ?? '' },
+                { key: msgs.getMessage('output.identity.orgType'), value: orgType },
+                { key: msgs.getMessage('output.identity.edition'), value: orgIdentity.organizationType ?? 'Unknown' },
+                { key: msgs.getMessage('output.identity.namespace'), value: orgIdentity.namespacePrefix ?? 'None' },
+                { key: msgs.getMessage('output.identity.username'), value: username ?? orgIdentity.username },
+            ],
+        }));
+    }
+    // Display Pattern block (active filters) between Org Identity and Summary
+    const activeFilters = getActiveFilters(data.filters);
+    if (activeFilters.length > 0) {
+        logSectionGap(log);
+        log(sectionHeader(msgs.getMessage('output.patternHeader')));
+        for (const filter of activeFilters) {
+            log(`  • ${filter}`);
+        }
+    }
+    // Display summary section
+    const summaryEntries = [
+        { key: msgs.getMessage('output.summary.totalObjects'), value: formatNumber(summary.totalObjects) },
+        { key: msgs.getMessage('output.summary.withRecords'), value: formatNumber(summary.withRecords) },
+        { key: msgs.getMessage('output.summary.withoutRecords'), value: formatNumber(summary.withoutRecords) },
+        { key: msgs.getMessage('output.summary.standard'), value: formatNumber(summary.standardObjects) },
+        { key: msgs.getMessage('output.summary.custom'), value: formatNumber(summary.customObjects) },
+    ];
+    if (summary.withRecordTypes !== undefined) {
+        summaryEntries.push({
+            key: msgs.getMessage('output.summary.withRecordTypes'),
+            value: formatNumber(summary.withRecordTypes),
+        });
+    }
+    if (summary.withOwner !== undefined) {
+        summaryEntries.push({
+            key: msgs.getMessage('output.summary.withOwner'),
+            value: formatNumber(summary.withOwner),
+        });
+    }
+    if (summary.externalObjects > 0) {
+        summaryEntries.push({
+            key: msgs.getMessage('output.summary.external'),
+            value: formatNumber(summary.externalObjects),
+        });
+    }
+    summaryEntries.push({
+        key: msgs.getMessage('output.summary.withNamespace'),
+        value: formatNumber(summary.withNamespace),
+    });
+    summaryEntries.push({
+        key: msgs.getMessage('output.summary.withoutNamespace'),
+        value: formatNumber(summary.withoutNamespace),
+    });
+    logSectionGap(log);
+    log(renderSummaryBox({ title: msgs.getMessage('output.summary.header'), entries: summaryEntries }));
+    // Display namespace distribution if any namespaced objects exist
+    const hasNamespacedObjects = summary.namespaceCounts.some((ns) => ns.namespace !== null);
+    if (hasNamespacedObjects) {
+        logSectionGap(log);
+        displayNamespaceDistribution(log, summary.namespaceCounts);
+    }
+    // Display object table with count in header
+    logSectionGap(log);
+    const displayedCount = formatNumber(objects.length);
+    const totalCount = formatNumber(summary.totalObjects);
+    const countLabel = objects.length < summary.totalObjects ? `${displayedCount} of ${totalCount}` : `${displayedCount}`;
+    log(sectionHeader(`${msgs.getMessage('output.objects.header')} (${countLabel})`));
+    displayObjectsTable(log, data, objects);
+    // Display Next Steps
+    logSectionGap(log);
+    displayNextSteps(log, objects, username);
+}
+/**
+ * Displays the namespace distribution table.
+ *
+ * @param log - The logging function
+ * @param namespaceCounts - The namespace counts from the summary
+ */
+export function displayNamespaceDistribution(log, namespaceCounts) {
+    const msgs = getMessages();
+    const nsHeader = msgs.getMessage('output.namespaceDistribution.header');
+    log(sectionHeaderWithCount(nsHeader, namespaceCounts.length));
+    const noNamespaceLabel = msgs.getMessage('output.namespaceDistribution.noNamespace');
+    const totalLabel = msgs.getMessage('output.objects.totalLabel');
+    const nsTotal = namespaceCounts.reduce((sum, ns) => sum + ns.count, 0);
+    const nsTotalWidth = Math.max(msgs.getMessage('output.namespaceDistribution.columns.count').length, formatNumber(nsTotal).length, ...namespaceCounts.map((ns) => formatNumber(ns.count).length));
+    const nsData = namespaceCounts.map((ns) => ({
+        prefix: ns.namespace ?? '—',
+        label: formatNamespace(ns.namespace, { standardLabel: noNamespaceLabel }),
+        count: formatNumber(ns.count).padStart(nsTotalWidth),
+    }));
+    nsData.push({ prefix: '', label: '', count: '─'.repeat(nsTotalWidth) });
+    nsData.push({ prefix: '', label: totalLabel, count: formatNumber(nsTotal).padStart(nsTotalWidth) });
+    log(makeTable({
+        data: nsData,
+        columns: [
+            { key: 'prefix', name: msgs.getMessage('output.namespaceDistribution.columns.prefix') },
+            { key: 'label', name: msgs.getMessage('output.namespaceDistribution.columns.label') },
+            {
+                key: 'count',
+                name: msgs.getMessage('output.namespaceDistribution.columns.count'),
+                horizontalAlignment: 'right',
+            },
+        ],
+        borderStyle: TABLE_BORDER_STYLE,
+    }).trimEnd());
+}
+/**
+ * Displays the objects table with enrichment columns, or empty state if no objects match.
+ *
+ * @param log - The logging function
+ * @param data - The full ObjectListResult (for filters and summary)
+ * @param objects - The sorted objects to display
+ */
+export function displayObjectsTable(log, data, objects) {
+    const msgs = getMessages();
+    if (objects.length === 0) {
+        // Order active filters by selectivity (most restrictive first)
+        const selectiveFilters = getSelectiveFilters(data.filters);
+        const suggestions = selectiveFilters.length > 0 ? [msgs.getMessage('output.noResults.suggestion')] : [];
+        const emptyLines = formatEmptyState({
+            entityType: msgs.getMessage('output.entityType'),
+            appliedFilters: selectiveFilters,
+            suggestions,
+        });
+        for (const line of emptyLines) {
+            log(`  ${line}`);
+        }
+        return;
+    }
+    // Determine active enrichment flags for conditional columns
+    const enrichmentFlags = {
+        withFields: data.filters.includeFieldCounts ?? false,
+        withRecordTypes: data.filters.withRecordTypes ?? false,
+        withBusinessProcess: data.filters.withBusinessProcess ?? false,
+        withReferences: data.filters.includeReferences ?? false,
+        withContactPoints: data.filters.withContactPoints ?? false,
+    };
+    const { summary } = data;
+    // Pre-compute CP category totals (needed for both width calculation and total row rendering)
+    const cpTotals = enrichmentFlags.withContactPoints
+        ? computeCpCategoryTotals(objects)
+        : { email: 0, phone: 0, url: 0 };
+    // Pre-compute numeric column widths for right-alignment (includes total values to prevent alignment drift)
+    const colWidths = computeColWidths(objects, enrichmentFlags, summary, cpTotals);
+    // Build table data with consistent structure
+    const tableData = objects.map((obj) => formatObjectRow(obj, colWidths, enrichmentFlags));
+    // Append separator + total rows (injected as data rows for guaranteed alignment)
+    const { separatorRow, totalRow } = buildTotalRows(summary, colWidths, enrichmentFlags, cpTotals);
+    tableData.push(separatorRow);
+    tableData.push(totalRow);
+    log(makeTable({
+        data: tableData,
+        columns: getTableColumns(enrichmentFlags),
+        borderStyle: TABLE_BORDER_STYLE,
+    }).trimEnd());
+    // CLI-4214: when any row carries an approximate (limits-derived) count, print a legend
+    // explaining the `~` indicator so the approximation is never silently presented as exact.
+    if (objects.some((obj) => obj.recordCountProvenance === 'limits')) {
+        log('');
+        log(`  ${msgs.getMessage('output.objects.approximateLegend')}`);
+    }
+    // Display limit notice when results are truncated
+    if (data.filters.limit && objects.length >= data.filters.limit) {
+        log('');
+        log(`  • ${msgs.getMessage('output.objects.limitNotice', [formatNumber(objects.length)])}`);
+    }
+    // Display contact point field details below the main table
+    if (enrichmentFlags.withContactPoints) {
+        displayContactPointDetails(log, objects);
+    }
+}
+/**
+ * Displays contact point field details (email, phone, URL field names) for each object
+ * that has at least one contact point field, rendered as a sub-section after the main table.
+ *
+ * @param log - The logging function
+ * @param objects - The objects to display contact points for
+ */
+export function displayContactPointDetails(log, objects) {
+    const msgs = getMessages();
+    const objectsWithCPs = objects.filter((obj) => obj.contactPoints && obj.contactPoints.summary.totalContactPoints > 0);
+    if (objectsWithCPs.length === 0) {
+        return;
+    }
+    log('');
+    const cpHeader = msgs.getMessage('output.contactPoints.header');
+    log(sectionHeaderWithCount(cpHeader, objectsWithCPs.length));
+    for (const obj of objectsWithCPs) {
+        const cp = obj.contactPoints;
+        log('');
+        log(`  ${obj.label}`);
+        if (cp.emailFields.length > 0) {
+            log(`    ${msgs.getMessage('output.contactPoints.email')}   ${cp.emailFields.map((f) => f.label).join(', ')}`);
+        }
+        if (cp.phoneFields.length > 0) {
+            log(`    ${msgs.getMessage('output.contactPoints.phone')}   ${cp.phoneFields.map((f) => f.label).join(', ')}`);
+        }
+        if (cp.urlFields.length > 0) {
+            log(`    ${msgs.getMessage('output.contactPoints.url')}     ${cp.urlFields.map((f) => f.label).join(', ')}`);
+        }
+    }
+}
+/**
+ * Builds separator and total rows for the objects table.
+ *
+ * @param summary - The object list summary with aggregate counts
+ * @param colWidths - Pre-computed column widths
+ * @param enrichmentFlags - Active enrichment flags
+ * @param cpTotals - Contact point category totals
+ * @returns Separator and total row data
+ */
+export function buildTotalRows(summary, colWidths, enrichmentFlags, cpTotals) {
+    const msgs = getMessages();
+    const totalLabel = msgs.getMessage('output.objects.totalLabel');
+    const separatorRow = {
+        prefix: '',
+        objectLabel: '',
+        type: '',
+        records: '─'.repeat(colWidths.records),
+    };
+    const totalRow = {
+        prefix: '',
+        objectLabel: totalLabel,
+        type: '',
+        records: formatNumber(summary.totalRecordCount).padStart(colWidths.records),
+    };
+    if (enrichmentFlags.withRecordTypes) {
+        separatorRow.recordTypes = '─'.repeat(colWidths.recordTypes);
+        totalRow.recordTypes = formatNumber(summary.totalRecordTypeCount ?? 0).padStart(colWidths.recordTypes);
+    }
+    if (enrichmentFlags.withBusinessProcess) {
+        separatorRow.businessProcess = '─'.repeat(colWidths.businessProcess);
+        totalRow.businessProcess = formatNumber(summary.totalBusinessProcessCount ?? 0).padStart(colWidths.businessProcess);
+    }
+    if (enrichmentFlags.withFields) {
+        separatorRow.totalFields = '─'.repeat(colWidths.totalFields);
+        separatorRow.custom = '─'.repeat(colWidths.custom);
+        totalRow.totalFields = formatNumber(summary.totalFieldCount ?? 0).padStart(colWidths.totalFields);
+        totalRow.custom = formatNumber(summary.totalCustomFieldCount ?? 0).padStart(colWidths.custom);
+    }
+    if (enrichmentFlags.withReferences) {
+        separatorRow.reference = '─'.repeat(colWidths.reference);
+        totalRow.reference = formatNumber(summary.totalReferenceCount ?? 0).padStart(colWidths.reference);
+    }
+    if (enrichmentFlags.withContactPoints) {
+        separatorRow.cpTotal = '─'.repeat(colWidths.cpTotal);
+        separatorRow.cpEmail = '─'.repeat(colWidths.cpEmail);
+        separatorRow.cpPhone = '─'.repeat(colWidths.cpPhone);
+        separatorRow.cpUrl = '─'.repeat(colWidths.cpUrl);
+        totalRow.cpTotal = String(summary.totalContactPoints ?? 0).padStart(colWidths.cpTotal);
+        totalRow.cpEmail = String(cpTotals.email).padStart(colWidths.cpEmail);
+        totalRow.cpPhone = String(cpTotals.phone).padStart(colWidths.cpPhone);
+        totalRow.cpUrl = String(cpTotals.url).padStart(colWidths.cpUrl);
+    }
+    return { separatorRow, totalRow };
+}
+/**
+ * Pre-computes column widths for right-alignment of numeric columns.
+ * Includes summary totals in the max width calculation to prevent
+ * alignment drift when a total value is wider than any data value.
+ *
+ * @param objects - The objects to compute widths for
+ * @param enrichmentFlags - Active enrichment flags
+ * @param summary - The summary with aggregate totals
+ * @param cpTotals - Contact point category totals
+ * @returns Pre-computed column widths
+ */
+export function computeColWidths(objects, enrichmentFlags, summary, cpTotals) {
+    const msgs = getMessages();
+    // Include summary totals in max width calculation to prevent alignment drift
+    // when the total value is wider than any individual data value
+    return {
+        records: Math.max(msgs.getMessage('output.objects.columns.records').length, formatNumber(summary.totalRecordCount).length, 
+        // CLI-4214: width must account for the `~` prefix on approximate counts and the
+        // em-dash placeholder on unknown counts — both produced by formatRecordCount.
+        ...objects.map((obj) => formatRecordCount(obj).length)),
+        recordTypes: enrichmentFlags.withRecordTypes
+            ? Math.max(msgs.getMessage('output.objects.columns.recordTypes').length, formatNumber(summary.totalRecordTypeCount ?? 0).length, ...objects.map((obj) => (obj.recordTypeCount !== undefined ? formatNumber(obj.recordTypeCount).length : 1)))
+            : 0,
+        businessProcess: enrichmentFlags.withBusinessProcess
+            ? Math.max(msgs.getMessage('output.objects.columns.businessProcess').length, formatNumber(summary.totalBusinessProcessCount ?? 0).length, ...objects.map((obj) => obj.businessProcessCount !== undefined ? formatNumber(obj.businessProcessCount).length : 1))
+            : 0,
+        totalFields: enrichmentFlags.withFields
+            ? Math.max(msgs.getMessage('output.objects.columns.totalFields').length, formatNumber(summary.totalFieldCount ?? 0).length, ...objects.map((obj) => (obj.totalFields !== undefined ? formatNumber(obj.totalFields).length : 1)))
+            : 0,
+        custom: enrichmentFlags.withFields
+            ? Math.max(msgs.getMessage('output.objects.columns.custom').length, formatNumber(summary.totalCustomFieldCount ?? 0).length, ...objects.map((obj) => (obj.customFields !== undefined ? formatNumber(obj.customFields).length : 1)))
+            : 0,
+        reference: enrichmentFlags.withReferences
+            ? Math.max(msgs.getMessage('output.objects.columns.reference').length, formatNumber(summary.totalReferenceCount ?? 0).length, ...objects.map((obj) => (obj.lookupFieldCount !== undefined ? formatNumber(obj.lookupFieldCount).length : 1)))
+            : 0,
+        cpTotal: enrichmentFlags.withContactPoints
+            ? Math.max(msgs.getMessage('output.objects.columns.totalCPs').length, String(summary.totalContactPoints ?? 0).length, ...objects.map((obj) => String(obj.contactPoints?.summary.totalContactPoints ?? 0).length))
+            : 0,
+        cpEmail: enrichmentFlags.withContactPoints
+            ? Math.max(msgs.getMessage('output.objects.columns.email').length, String(cpTotals.email).length, ...objects.map((obj) => String(obj.contactPoints?.summary.emailCount ?? 0).length))
+            : 0,
+        cpPhone: enrichmentFlags.withContactPoints
+            ? Math.max(msgs.getMessage('output.objects.columns.phone').length, String(cpTotals.phone).length, ...objects.map((obj) => String(obj.contactPoints?.summary.phoneCount ?? 0).length))
+            : 0,
+        cpUrl: enrichmentFlags.withContactPoints
+            ? Math.max(msgs.getMessage('output.objects.columns.url').length, String(cpTotals.url).length, ...objects.map((obj) => String(obj.contactPoints?.summary.urlCount ?? 0).length))
+            : 0,
+    };
+}
+/**
+ * Formats a single object row for the table display, including optional enrichment columns.
+ *
+ * @param obj - The object list item to format
+ * @param colWidths - Pre-computed column widths for right-alignment
+ * @param enrichmentFlags - Active enrichment flags for conditional columns
+ * @returns A record of column key to formatted string value
+ */
+export function formatObjectRow(obj, colWidths, enrichmentFlags) {
+    const msgs = getMessages();
+    const row = {
+        prefix: obj.namespace ?? msgs.getMessage('output.objects.noNamespace'),
+        objectLabel: obj.label,
+        type: obj.isCustom ? msgs.getMessage('output.objects.typeCustom') : msgs.getMessage('output.objects.typeStandard'),
+        // CLI-4214: disclose count provenance — approximate counts carry a leading `~`,
+        // unknown counts render as an em dash (never 0).
+        records: formatRecordCount(obj).padStart(colWidths.records),
+    };
+    // Enrichment columns — right-aligned via padStart, ordered per spec
+    if (enrichmentFlags?.withRecordTypes) {
+        row.recordTypes = (obj.recordTypeCount !== undefined ? formatNumber(obj.recordTypeCount) : '—').padStart(colWidths.recordTypes);
+    }
+    if (enrichmentFlags?.withBusinessProcess) {
+        row.businessProcess = (obj.businessProcessCount !== undefined ? formatNumber(obj.businessProcessCount) : '—').padStart(colWidths.businessProcess);
+    }
+    if (enrichmentFlags?.withFields) {
+        row.totalFields = (obj.totalFields !== undefined ? formatNumber(obj.totalFields) : '—').padStart(colWidths.totalFields);
+        row.custom = (obj.customFields !== undefined ? formatNumber(obj.customFields) : '—').padStart(colWidths.custom);
+    }
+    if (enrichmentFlags?.withReferences) {
+        row.reference = (obj.lookupFieldCount !== undefined ? formatNumber(obj.lookupFieldCount) : '—').padStart(colWidths.reference);
+    }
+    if (enrichmentFlags?.withContactPoints) {
+        const cp = obj.contactPoints?.summary;
+        row.cpTotal = String(cp?.totalContactPoints ?? 0).padStart(colWidths.cpTotal);
+        row.cpEmail = String(cp?.emailCount ?? 0).padStart(colWidths.cpEmail);
+        row.cpPhone = String(cp?.phoneCount ?? 0).padStart(colWidths.cpPhone);
+        row.cpUrl = String(cp?.urlCount ?? 0).padStart(colWidths.cpUrl);
+    }
+    return row;
+}
+/**
+ * Gets table column definitions, including optional enrichment columns.
+ * Numeric columns use horizontalAlignment: 'right' for consistent rendering.
+ *
+ * @param enrichmentFlags - Active enrichment flags for conditional columns
+ * @returns Array of column definitions for makeTable
+ */
+export function getTableColumns(enrichmentFlags) {
+    const msgs = getMessages();
+    const columns = [
+        { key: 'prefix', name: msgs.getMessage('output.objects.columns.prefix') },
+        { key: 'objectLabel', name: msgs.getMessage('output.objects.columns.objectLabel') },
+        { key: 'records', name: msgs.getMessage('output.objects.columns.records'), horizontalAlignment: 'right' },
+    ];
+    // Enrichment columns: Record Types, Business Processes, Total Fields, Custom, Reference, Total CPs, Email, Phone, Url
+    if (enrichmentFlags?.withRecordTypes) {
+        columns.push({
+            key: 'recordTypes',
+            name: msgs.getMessage('output.objects.columns.recordTypes'),
+            horizontalAlignment: 'right',
+        });
+    }
+    if (enrichmentFlags?.withBusinessProcess) {
+        columns.push({
+            key: 'businessProcess',
+            name: msgs.getMessage('output.objects.columns.businessProcess'),
+            horizontalAlignment: 'right',
+        });
+    }
+    if (enrichmentFlags?.withFields) {
+        columns.push({
+            key: 'totalFields',
+            name: msgs.getMessage('output.objects.columns.totalFields'),
+            horizontalAlignment: 'right',
+        });
+        columns.push({
+            key: 'custom',
+            name: msgs.getMessage('output.objects.columns.custom'),
+            horizontalAlignment: 'right',
+        });
+    }
+    if (enrichmentFlags?.withReferences) {
+        columns.push({
+            key: 'reference',
+            name: msgs.getMessage('output.objects.columns.reference'),
+            horizontalAlignment: 'right',
+        });
+    }
+    if (enrichmentFlags?.withContactPoints) {
+        columns.push({
+            key: 'cpTotal',
+            name: msgs.getMessage('output.objects.columns.totalCPs'),
+            horizontalAlignment: 'right',
+        });
+        columns.push({
+            key: 'cpEmail',
+            name: msgs.getMessage('output.objects.columns.email'),
+            horizontalAlignment: 'right',
+        });
+        columns.push({
+            key: 'cpPhone',
+            name: msgs.getMessage('output.objects.columns.phone'),
+            horizontalAlignment: 'right',
+        });
+        columns.push({
+            key: 'cpUrl',
+            name: msgs.getMessage('output.objects.columns.url'),
+            horizontalAlignment: 'right',
+        });
+    }
+    return columns;
+}
+/**
+ * Renders a NamespaceFilter as a human-readable string for display.
+ *
+ * @param filter - The typed NamespaceFilter value
+ * @returns Display label (e.g. "all", "(unmanaged)", "FinServ", "FinServ, SBQQ")
+ */
+function formatNamespaceFilter(filter) {
+    if (filter.kind === 'all')
+        return 'all';
+    if (filter.kind === 'unmanaged')
+        return '(unmanaged)';
+    return filter.namespaces.join(', ');
+}
+/**
+ * Builds a list of human-readable descriptions for active filters.
+ *
+ * @param filters - The applied filter options from the service result
+ * @returns Array of filter description strings (empty if no filters active)
+ */
+export function getActiveFilters(filters) {
+    const msgs = getMessages();
+    const active = [];
+    if (filters.filter && filters.filter !== 'all') {
+        active.push(msgs.getMessage('output.filters.type', [`${filters.filter.charAt(0).toUpperCase()}${filters.filter.slice(1)}`]));
+    }
+    if (filters.namespace) {
+        active.push(msgs.getMessage('output.filters.namespace', [formatNamespaceFilter(filters.namespace)]));
+    }
+    if (filters.pattern) {
+        active.push(msgs.getMessage('output.filters.pattern', [filters.pattern]));
+    }
+    if (filters.withRecords) {
+        active.push(msgs.getMessage('output.filters.withRecords'));
+    }
+    if (filters.withoutRecords) {
+        active.push(msgs.getMessage('output.filters.withoutRecords'));
+    }
+    if (filters.withOwner) {
+        active.push(msgs.getMessage('output.filters.withOwner'));
+    }
+    if (filters.withRecordTypes) {
+        active.push(msgs.getMessage('output.filters.withRecordTypes'));
+    }
+    if (filters.withBusinessProcess) {
+        active.push(msgs.getMessage('output.filters.withBusinessProcess'));
+    }
+    if (filters.includeFieldCounts) {
+        active.push(msgs.getMessage('output.filters.withFields'));
+    }
+    if (filters.includeReferences) {
+        active.push(msgs.getMessage('output.filters.withReferences'));
+    }
+    if (filters.withContactPoints) {
+        active.push(msgs.getMessage('output.filters.withContactPoints'));
+    }
+    if (filters.classification && filters.classification !== 'all') {
+        active.push(msgs.getMessage('output.filters.classification', [
+            `${filters.classification.charAt(0).toUpperCase()}${filters.classification.slice(1)}`,
+        ]));
+    }
+    if (filters.minRecords && filters.minRecords > 0) {
+        active.push(msgs.getMessage('output.filters.minRecords', [formatNumber(filters.minRecords)]));
+    }
+    return active;
+}
+/**
+ * Returns active filters ordered by selectivity (most restrictive first).
+ * Used in empty state display to help users identify which filter to relax.
+ *
+ * @param filters - The applied filter options from the service result
+ * @returns Array of filter flag strings ordered by selectivity
+ */
+export function getSelectiveFilters(filters) {
+    const selective = [];
+    // Most restrictive first
+    if (filters.pattern)
+        selective.push(`--pattern ${filters.pattern}`);
+    if (filters.namespace)
+        selective.push(`--namespace ${formatNamespaceFilter(filters.namespace)}`);
+    if (filters.withRecordTypes)
+        selective.push('--with-record-types');
+    if (filters.withOwner)
+        selective.push('--with-owner');
+    if (filters.includeFieldCounts)
+        selective.push('--with-fields');
+    if (filters.includeReferences)
+        selective.push('--with-references');
+    if (filters.withContactPoints)
+        selective.push('--with-contact-points');
+    if (filters.classification && filters.classification !== 'all')
+        selective.push(`--classification ${filters.classification}`);
+    if (filters.minRecords && filters.minRecords > 0)
+        selective.push(`--min-records ${formatNumber(filters.minRecords)}`);
+    if (filters.withRecords)
+        selective.push('--with-records');
+    if (filters.withoutRecords)
+        selective.push('--without-records');
+    if (filters.filter && filters.filter !== 'all')
+        selective.push(`--filter ${filters.filter}`);
+    return selective;
+}
+/**
+ * Builds the command result for JSON output.
+ *
+ * @param data - The ObjectListResult from the service
+ * @param flags - The parsed command flags
+ * @param orgIdentity - The org identity data (optional)
+ * @param instanceUrl - The org instance URL (optional)
+ * @param metadata - Service metadata with duration
+ * @returns ObjectListCommandResult for JSON output
+ */
+export function buildCommandResult(data, flags, orgIdentity, instanceUrl, metadata) {
+    return {
+        success: true,
+        orgIdentity: orgIdentity
+            ? {
+                orgId: orgIdentity.organizationId,
+                orgName: orgIdentity.organizationName ?? '(unknown)',
+                orgType: orgIdentity.organizationType ?? '(unknown)',
+                isSandbox: orgIdentity.isSandbox ?? false,
+                instanceUrl: instanceUrl ?? '',
+                username: orgIdentity.username,
+                namespacePrefix: orgIdentity.namespacePrefix,
+            }
+            : undefined,
+        summary: data.summary,
+        filters: {
+            object: flags.object,
+            filter: flags.filter,
+            namespace: flags.namespace,
+            pattern: flags.pattern,
+            withRecords: flags['with-records'] || undefined,
+            withoutRecords: flags['without-records'] || undefined,
+            withOwner: flags['with-owner'] || undefined,
+            withRecordTypes: flags['with-record-types'] || undefined,
+            withBusinessProcess: flags['with-business-process'] || undefined,
+            includeFieldCounts: flags['with-fields'] || undefined,
+            includeReferences: flags['with-references'] || undefined,
+            withContactPoints: flags['with-contact-points'] || undefined,
+            classification: flags.classification,
+            minRecords: flags['min-records'],
+            sort: flags.sort,
+            limit: flags.limit,
+        },
+        objects: data.objects,
+        // CLI-4214: relay the record-count reconciliation truncation disclosure in JSON output.
+        warnings: data.warnings && data.warnings.length > 0 ? data.warnings : undefined,
+        metadata: metadata?.duration !== undefined ? { duration: metadata.duration } : undefined,
+    };
+}
+/**
+ * Displays contextual next steps based on the objects in the result.
+ * Suggests object describe commands for meaningful objects and
+ * always ends with the definition create command.
+ *
+ * @param log - The logging function
+ * @param objects - The object list items
+ * @param username - The target org username for command examples
+ */
+export function displayNextSteps(log, objects, username) {
+    const msgs = getMessages();
+    log(msgs.getMessage('output.nextSteps.header'));
+    log('');
+    // Pick meaningful objects for describe suggestions:
+    // 1. Highest record count object (most populated = most interesting)
+    // 2. First custom namespaced object (shows namespace-aware usage)
+    const suggestions = [];
+    // Find highest record count object
+    const sorted = [...objects]
+        .filter((o) => (o.recordCount ?? 0) > 0)
+        .sort((a, b) => (b.recordCount ?? 0) - (a.recordCount ?? 0));
+    if (sorted.length > 0) {
+        suggestions.push({ label: sorted[0].label, apiName: sorted[0].apiName });
+    }
+    // Find first custom namespaced object (different from the first suggestion)
+    const namespacedCustom = objects.find((o) => o.namespace && o.isCustom && (!suggestions[0] || o.apiName !== suggestions[0].apiName));
+    if (namespacedCustom) {
+        suggestions.push({ label: namespacedCustom.label, apiName: namespacedCustom.apiName });
+    }
+    // If we still have no second suggestion, pick a different standard object
+    if (suggestions.length < 2 && sorted.length > 1) {
+        suggestions.push({ label: sorted[1].label, apiName: sorted[1].apiName });
+    }
+    // Render object describe suggestions (2-space label, 4-space command)
+    for (const suggestion of suggestions) {
+        log(`  ${msgs.getMessage('output.nextSteps.describeLabel', [suggestion.label])}`);
+        if (username) {
+            log(`    ${msgs.getMessage('output.nextSteps.describeCommand', [suggestion.apiName, username])}`);
+        }
+        else {
+            log(`    ${msgs.getMessage('output.nextSteps.describeCommandNoOrg', [suggestion.apiName])}`);
+        }
+        log('');
+    }
+    // Static: definition create (always present, matches user-details/org-details)
+    log(`  ${msgs.getMessage('output.nextSteps.definitionCreateLabel')}`);
+    log(`    ${msgs.getMessage('output.nextSteps.definitionCreateCommand')}`);
+    log('');
+}
+//# sourceMappingURL=object-list-display.js.map