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

package/lib/utils/formatting/availability-grid.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Pure rendering utilities for the data availability grid.
+ *
+ * Converts AvailabilityGrid data into both table-ready row objects (for this.table())
+ * and a structured JSON contract (for --json output and LLM consumption).
+ *
+ * Uses filled/empty circle metaphor:
+ * - \u25CF (●) = data exists
+ * - \u25CB (○) = no data
+ *
+ * @module utils/formatting/availability-grid
+ */
+import type { AvailabilityGrid } from '../../services/DataAvailabilityService.js';
+/** Filled circle: data exists in year */
+export declare const DATA_PRESENT = "\u25CF";
+/** Empty circle: no data in year */
+export declare const DATA_ABSENT = "\u25CB";
+/** Dash: not applicable or unknown */
+export declare const DATA_NA = "\u2014";
+/**
+ * A single row of the availability grid formatted for table display.
+ * Dynamic year columns are string-keyed (e.g., "y2026", "y2025").
+ */
+export type AvailabilityTableRow = {
+    /** Dynamic year columns: key = "y{year}", value = ● or ○ */
+    [yearKey: `y${number}`]: string;
+    /** Object API name */
+    object: string;
+    /** Oldest record year or "—" if no records */
+    oldest: string;
+};
+/**
+ * JSON contract for availability grid (LLM/MCP consumption).
+ */
+export type AvailabilityGridJson = {
+    /** Object API name */
+    objectName: string;
+    /** Oldest record year, or null if no records */
+    oldest: number | null;
+    /** Year-keyed availability flags */
+    years: Record<string, boolean>;
+};
+/**
+ * Builds table-ready row data from an AvailabilityGrid.
+ *
+ * Each row contains the object name, oldest year, and dynamic year columns
+ * with filled/empty circle symbols.
+ *
+ * @param grid - The availability grid from DataAvailabilityService
+ * @returns Array of row objects suitable for this.table()
+ */
+export declare function buildAvailabilityTableRows(grid: AvailabilityGrid): AvailabilityTableRow[];
+/**
+ * Builds column definitions for the availability grid table.
+ *
+ * Returns "Object", "Oldest", and one column per year in the grid.
+ *
+ * @param yearColumns - The year columns from the grid
+ * @returns Column definitions for this.table()
+ */
+export declare function buildAvailabilityColumns(yearColumns: readonly number[]): Array<{
+    key: string;
+    name: string;
+}>;
+/**
+ * Converts an AvailabilityGrid to the JSON contract structure.
+ *
+ * Each object becomes an entry with its oldest year and year-keyed boolean flags.
+ * This structure is designed for LLM/MCP consumption.
+ *
+ * @param grid - The availability grid from DataAvailabilityService
+ * @returns Array of JSON contract objects
+ */
+export declare function buildAvailabilityJson(grid: AvailabilityGrid): AvailabilityGridJson[];
+/**
+ * Generates a summary string for the availability grid.
+ *
+ * @param grid - The availability grid
+ * @returns Summary like "3 objects, 2 years, 1 gap"
+ */
+export declare function summarizeAvailabilityGrid(grid: AvailabilityGrid): string;

package/lib/utils/formatting/availability-grid.js

@@ -0,0 +1,94 @@
+/*
+ * 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.
+ */
+/** Filled circle: data exists in year */
+export const DATA_PRESENT = '\u25CF';
+/** Empty circle: no data in year */
+export const DATA_ABSENT = '\u25CB';
+/** Dash: not applicable or unknown */
+export const DATA_NA = '\u2014';
+/**
+ * Builds table-ready row data from an AvailabilityGrid.
+ *
+ * Each row contains the object name, oldest year, and dynamic year columns
+ * with filled/empty circle symbols.
+ *
+ * @param grid - The availability grid from DataAvailabilityService
+ * @returns Array of row objects suitable for this.table()
+ */
+export function buildAvailabilityTableRows(grid) {
+    return grid.rows.map((row) => {
+        const tableRow = {
+            object: row.objectApiName,
+            oldest: row.oldestYear !== null ? String(row.oldestYear) : DATA_NA,
+        };
+        for (const yearAvail of row.years) {
+            tableRow[`y${yearAvail.year}`] = yearAvail.hasData ? DATA_PRESENT : DATA_ABSENT;
+        }
+        return tableRow;
+    });
+}
+/**
+ * Builds column definitions for the availability grid table.
+ *
+ * Returns "Object", "Oldest", and one column per year in the grid.
+ *
+ * @param yearColumns - The year columns from the grid
+ * @returns Column definitions for this.table()
+ */
+export function buildAvailabilityColumns(yearColumns) {
+    const columns = [
+        { key: 'object', name: 'Object' },
+        { key: 'oldest', name: 'Oldest' },
+    ];
+    for (const year of yearColumns) {
+        columns.push({ key: `y${year}`, name: String(year) });
+    }
+    return columns;
+}
+/**
+ * Converts an AvailabilityGrid to the JSON contract structure.
+ *
+ * Each object becomes an entry with its oldest year and year-keyed boolean flags.
+ * This structure is designed for LLM/MCP consumption.
+ *
+ * @param grid - The availability grid from DataAvailabilityService
+ * @returns Array of JSON contract objects
+ */
+export function buildAvailabilityJson(grid) {
+    return grid.rows.map((row) => {
+        const years = {};
+        for (const yearAvail of row.years) {
+            years[String(yearAvail.year)] = yearAvail.hasData;
+        }
+        return {
+            objectName: row.objectApiName,
+            oldest: row.oldestYear,
+            years,
+        };
+    });
+}
+/**
+ * Generates a summary string for the availability grid.
+ *
+ * @param grid - The availability grid
+ * @returns Summary like "3 objects, 2 years, 1 gap"
+ */
+export function summarizeAvailabilityGrid(grid) {
+    const objectCount = grid.rows.length;
+    const yearCount = grid.yearColumns.length;
+    const gapCount = grid.rows.reduce((sum, row) => sum + row.years.filter((y) => !y.hasData).length, 0);
+    const parts = [
+        `${objectCount} object${objectCount !== 1 ? 's' : ''}`,
+        `${yearCount} year${yearCount !== 1 ? 's' : ''}`,
+    ];
+    if (gapCount > 0) {
+        parts.push(`${gapCount} gap${gapCount !== 1 ? 's' : ''}`);
+    }
+    return parts.join(', ');
+}
+//# sourceMappingURL=availability-grid.js.map

package/lib/utils/formatting/availability-grid.js.map

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

package/lib/utils/formatting/business-process-grid.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure rendering utilities for the business process grid.
+ *
+ * Converts business process data with record age distribution into table-ready
+ * row objects for makeTable() rendering. Reuses the record-age-grid columns
+ * and the filled/empty circle metaphor from availability-grid.ts.
+ *
+ * Designed for reuse across commands — any command that needs to display
+ * business processes with year-level record existence can use this component.
+ *
+ * @module utils/formatting/business-process-grid
+ */
+import type { RecordAgeDistribution, YearRecordAge } from '../../services/ObjectDescribeService.js';
+/**
+ * Business process entry for the grid display.
+ * Decoupled from service types so any command can construct this.
+ */
+export type BusinessProcessGridEntry = {
+    /** Process name */
+    name: string;
+    /** Whether the process is active */
+    isActive: boolean;
+    /** Number of record types using this process */
+    recordTypeCount: number;
+    /** Per-process record age distribution (optional — omit for processes without data) */
+    recordAgeDistribution?: RecordAgeDistribution;
+};
+/**
+ * Builds column definitions for the business process grid table.
+ *
+ * Returns: Process Name, Active, Record Types, then year columns + Oldest
+ * from the record age grid.
+ *
+ * @param years - The year entries (used to generate dynamic year columns)
+ * @returns Column definitions for makeTable()
+ */
+export declare function buildBusinessProcessColumns(years: readonly YearRecordAge[]): Array<{
+    key: string;
+    name: string;
+}>;
+/**
+ * Builds table-ready row data from business process entries.
+ *
+ * Each process becomes one row with its metadata columns and merged
+ * record age columns (year symbols + oldest date).
+ *
+ * @param processes - Array of business process entries with optional age data
+ * @param years - The year entries (used to fill em dashes for processes without data)
+ * @returns Array of row objects suitable for makeTable()
+ */
+export declare function buildBusinessProcessTableData(processes: readonly BusinessProcessGridEntry[], years?: readonly YearRecordAge[]): Array<Record<string, string>>;

package/lib/utils/formatting/business-process-grid.js

@@ -0,0 +1,58 @@
+/*
+ * 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 { buildRecordAgeColumns, buildRecordAgeTableData } from './record-age-grid.js';
+import { DATA_NA } from './availability-grid.js';
+/**
+ * Builds column definitions for the business process grid table.
+ *
+ * Returns: Process Name, Active, Record Types, then year columns + Oldest
+ * from the record age grid.
+ *
+ * @param years - The year entries (used to generate dynamic year columns)
+ * @returns Column definitions for makeTable()
+ */
+export function buildBusinessProcessColumns(years) {
+    const columns = [
+        { key: 'name', name: 'Process Name' },
+        { key: 'active', name: 'Active' },
+        { key: 'recordTypes', name: 'Record Types' },
+    ];
+    // Append year + oldest columns from the record-age-grid component
+    columns.push(...buildRecordAgeColumns(years));
+    return columns;
+}
+/**
+ * Builds table-ready row data from business process entries.
+ *
+ * Each process becomes one row with its metadata columns and merged
+ * record age columns (year symbols + oldest date).
+ *
+ * @param processes - Array of business process entries with optional age data
+ * @param years - The year entries (used to fill em dashes for processes without data)
+ * @returns Array of row objects suitable for makeTable()
+ */
+export function buildBusinessProcessTableData(processes, years = []) {
+    return processes.map((process) => {
+        const row = {
+            name: process.name,
+            active: process.isActive ? 'Yes' : 'No',
+            recordTypes: String(process.recordTypeCount),
+        };
+        if (process.recordAgeDistribution) {
+            // Merge year columns from record-age-grid
+            const ageRow = buildRecordAgeTableData(process.recordAgeDistribution)[0];
+            Object.assign(row, ageRow);
+        }
+        else if (years.length > 0) {
+            // Show em dash only in the oldest column for processes without data
+            row.oldest = DATA_NA;
+        }
+        return row;
+    });
+}
+//# sourceMappingURL=business-process-grid.js.map

package/lib/utils/formatting/business-process-grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"business-process-grid.js","sourceRoot":"","sources":["../../../src/utils/formatting/business-process-grid.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAiBjD;;;;;;;;GAQG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAA+B;IACzE,MAAM,OAAO,GAAyC;QACpD,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE;QACrC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;QACjC,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE;KAC7C,CAAC;IAEF,kEAAkE;IAClE,OAAO,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC;IAE9C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,6BAA6B,CAC3C,SAA8C,EAC9C,QAAkC,EAAE;IAEpC,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC/B,MAAM,GAAG,GAA2B;YAClC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;YACvC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC;SAC7C,CAAC;QAEF,IAAI,OAAO,CAAC,qBAAqB,EAAE,CAAC;YAClC,0CAA0C;YAC1C,MAAM,MAAM,GAAG,uBAAuB,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;YACzE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,oEAAoE;YACpE,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC;QACvB,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/utils/formatting/command-display.d.ts

@@ -0,0 +1,154 @@
+import type { StatusType } from './indicators.js';
+/**
+ * A key-value pair for display in a summary box.
+ */
+export type SummaryEntry = {
+    /** The label/key text. */
+    readonly key: string;
+    /** The value to display. */
+    readonly value: string;
+};
+/**
+ * Options for rendering a summary box.
+ */
+export type SummaryBoxOptions = {
+    /** The section title displayed in the header. */
+    readonly title: string;
+    /** Key-value entries to display in the box. */
+    readonly entries: readonly SummaryEntry[];
+    /** Width to pad keys to for column alignment. Default: 20. */
+    readonly keyWidth?: number;
+};
+/**
+ * Renders a summary box with a header, key-value entries, and a separator.
+ *
+ * Produces a structured block of output suitable for displaying command
+ * results, org details, or object metadata. Empty entries produce
+ * a header and separator with no key-value lines between them.
+ *
+ * @param options - The summary box configuration
+ * @returns A multi-line formatted string
+ *
+ * @example
+ * renderSummaryBox({ title: 'Org Details', entries: [{ key: 'Username', value: 'admin@example.com' }] })
+ */
+export declare function renderSummaryBox(options: SummaryBoxOptions): string;
+/**
+ * Logs a summary box to the console, line by line.
+ *
+ * Wraps {@link renderSummaryBox} with the common pattern of splitting
+ * the multi-line output and logging each line individually. Prepends
+ * a blank line for visual separation from preceding output.
+ *
+ * @param log - The logging function (typically `this.log.bind(this)`)
+ * @param options - The summary box configuration
+ *
+ * @example
+ * ```typescript
+ * displaySummaryBox(this.log.bind(this), {
+ *   title: 'Summary',
+ *   entries: [
+ *     { key: 'Deleted', value: '5' },
+ *     { key: 'Failed', value: '0' },
+ *   ],
+ * });
+ * ```
+ */
+export declare function displaySummaryBox(log: (msg: string) => void, options: SummaryBoxOptions): void;
+/**
+ * Options for rendering a completion message.
+ */
+export type CompletionMessageOptions = {
+    /** The status type for the message icon. */
+    readonly status: StatusType;
+    /** The primary message text. */
+    readonly message: string;
+    /** Optional detail lines displayed below the message. */
+    readonly details?: readonly string[];
+};
+/**
+ * Renders a completion message with a status symbol and optional detail lines.
+ *
+ * Used at the end of command execution to indicate success, failure, or
+ * warning outcomes with structured details.
+ *
+ * @param options - The completion message configuration
+ * @returns A formatted string with status symbol, message, and optional details
+ *
+ * @example
+ * renderCompletionMessage({ status: 'success', message: 'Exported 42 definitions' })
+ */
+export declare function renderCompletionMessage(options: CompletionMessageOptions): string;
+/**
+ * Options for rendering a warning block.
+ */
+export type WarningBlockOptions = {
+    /** The warning title text. */
+    readonly title: string;
+    /** Warning detail items displayed as a bullet list. */
+    readonly items: readonly string[];
+};
+/**
+ * Renders a warning block with a header and bullet list of items.
+ *
+ * Used to display non-fatal warnings that the user should be aware of
+ * but that don't prevent command completion.
+ *
+ * @param options - The warning block configuration
+ * @returns A formatted warning string, or an empty string if no items
+ *
+ * @example
+ * renderWarningBlock({ title: 'Warnings', items: ['3 objects have no record types'] })
+ */
+export declare function renderWarningBlock(options: WarningBlockOptions): string;
+/**
+ * Options for rendering a contextual header.
+ */
+export type ContextualHeaderOptions = {
+    /** The human-readable command title (e.g., "User Details", "Org Details"). */
+    readonly commandTitle: string;
+    /** The authenticated username. */
+    readonly username: string;
+    /** The org name (omitted from output if undefined or empty). */
+    readonly orgName?: string;
+};
+/**
+ * Renders a contextual header line for CLI command output.
+ *
+ * Produces a single line that frames the command output with context:
+ * "Cuneiform {commandTitle} for {username} ({orgName})"
+ *
+ * @param options - The contextual header configuration
+ * @returns A formatted header string
+ *
+ * @example
+ * renderContextualHeader({ commandTitle: 'User Details', username: 'admin@example.com', orgName: 'Acme Corp' })
+ */
+export declare function renderContextualHeader(options: ContextualHeaderOptions): string;
+/**
+ * Org context information for display at the top of command output.
+ */
+export type OrgContext = {
+    /** Organization name from the Organization sObject */
+    readonly orgName?: string;
+    /** 18-character Organization ID */
+    readonly orgId: string;
+    /** Instance URL (e.g., https://acme.my.salesforce.com) */
+    readonly instanceUrl: string;
+    /** Whether this is a sandbox org */
+    readonly isSandbox: boolean;
+};
+/**
+ * Renders an Org Context section as a summary box.
+ *
+ * Displays the connected org's name, ID, instance URL, and type
+ * (Production or Sandbox). This section should appear first in
+ * command output to establish which org the user is operating in.
+ *
+ * @param context - The org context data to render
+ * @returns A multi-line formatted string
+ *
+ * @example
+ * renderOrgContext({ orgName: 'Acme Corp', orgId: '00Dxx0000001gErEAI', instanceUrl: 'https://acme.my.salesforce.com' })
+ */
+export declare function renderOrgContext(context: OrgContext): string;

package/lib/utils/formatting/command-display.js

@@ -0,0 +1,154 @@
+/*
+ * 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.
+ */
+/**
+ * Higher-level display composition utilities for CLI command output.
+ *
+ * Composes Phase 0 primitives (sections, indicators) into reusable
+ * rendering functions for summary boxes, completion messages, and
+ * warning blocks used across multiple commands.
+ *
+ * All functions are pure (no side effects, no external state) and return
+ * formatted strings.
+ *
+ * @module utils/formatting/command-display
+ */
+import { sectionHeader, keyValue, bulletList } from './sections.js';
+import { statusSymbol } from './indicators.js';
+/**
+ * Renders a summary box with a header, key-value entries, and a separator.
+ *
+ * Produces a structured block of output suitable for displaying command
+ * results, org details, or object metadata. Empty entries produce
+ * a header and separator with no key-value lines between them.
+ *
+ * @param options - The summary box configuration
+ * @returns A multi-line formatted string
+ *
+ * @example
+ * renderSummaryBox({ title: 'Org Details', entries: [{ key: 'Username', value: 'admin@example.com' }] })
+ */
+export function renderSummaryBox(options) {
+    const maxKeyLength = options.entries.reduce((max, e) => Math.max(max, e.key.length), 0);
+    const autoKeyWidth = Math.max(20, maxKeyLength + 2);
+    const effectiveKeyWidth = options.keyWidth ?? autoKeyWidth;
+    const kvOptions = { keyWidth: effectiveKeyWidth };
+    const lines = [sectionHeader(options.title)];
+    for (const entry of options.entries) {
+        lines.push(keyValue(entry.key, entry.value, kvOptions));
+    }
+    return lines.join('\n');
+}
+/**
+ * Logs a summary box to the console, line by line.
+ *
+ * Wraps {@link renderSummaryBox} with the common pattern of splitting
+ * the multi-line output and logging each line individually. Prepends
+ * a blank line for visual separation from preceding output.
+ *
+ * @param log - The logging function (typically `this.log.bind(this)`)
+ * @param options - The summary box configuration
+ *
+ * @example
+ * ```typescript
+ * displaySummaryBox(this.log.bind(this), {
+ *   title: 'Summary',
+ *   entries: [
+ *     { key: 'Deleted', value: '5' },
+ *     { key: 'Failed', value: '0' },
+ *   ],
+ * });
+ * ```
+ */
+export function displaySummaryBox(log, options) {
+    log('');
+    for (const line of renderSummaryBox(options).split('\n')) {
+        log(line);
+    }
+}
+/**
+ * Renders a completion message with a status symbol and optional detail lines.
+ *
+ * Used at the end of command execution to indicate success, failure, or
+ * warning outcomes with structured details.
+ *
+ * @param options - The completion message configuration
+ * @returns A formatted string with status symbol, message, and optional details
+ *
+ * @example
+ * renderCompletionMessage({ status: 'success', message: 'Exported 42 definitions' })
+ */
+export function renderCompletionMessage(options) {
+    const lines = [`${statusSymbol(options.status)}  ${options.message}`];
+    if (options.details !== undefined && options.details.length > 0) {
+        lines.push(...bulletList([...options.details]));
+    }
+    return lines.join('\n');
+}
+/**
+ * Renders a warning block with a header and bullet list of items.
+ *
+ * Used to display non-fatal warnings that the user should be aware of
+ * but that don't prevent command completion.
+ *
+ * @param options - The warning block configuration
+ * @returns A formatted warning string, or an empty string if no items
+ *
+ * @example
+ * renderWarningBlock({ title: 'Warnings', items: ['3 objects have no record types'] })
+ */
+export function renderWarningBlock(options) {
+    if (options.items.length === 0) {
+        return '';
+    }
+    const lines = [`${statusSymbol('warning')}  ${options.title}`, ...bulletList([...options.items])];
+    return lines.join('\n');
+}
+/**
+ * Renders a contextual header line for CLI command output.
+ *
+ * Produces a single line that frames the command output with context:
+ * "Cuneiform {commandTitle} for {username} ({orgName})"
+ *
+ * @param options - The contextual header configuration
+ * @returns A formatted header string
+ *
+ * @example
+ * renderContextualHeader({ commandTitle: 'User Details', username: 'admin@example.com', orgName: 'Acme Corp' })
+ */
+export function renderContextualHeader(options) {
+    const base = `Cuneiform ${options.commandTitle} for ${options.username}`;
+    if (options.orgName) {
+        return `${base} (${options.orgName})`;
+    }
+    return base;
+}
+/**
+ * Renders an Org Context section as a summary box.
+ *
+ * Displays the connected org's name, ID, instance URL, and type
+ * (Production or Sandbox). This section should appear first in
+ * command output to establish which org the user is operating in.
+ *
+ * @param context - The org context data to render
+ * @returns A multi-line formatted string
+ *
+ * @example
+ * renderOrgContext({ orgName: 'Acme Corp', orgId: '00Dxx0000001gErEAI', instanceUrl: 'https://acme.my.salesforce.com' })
+ */
+export function renderOrgContext(context) {
+    return renderSummaryBox({
+        title: 'Org Context',
+        entries: [
+            { key: 'Org Name', value: context.orgName ?? '(unknown)' },
+            { key: 'Org ID', value: context.orgId },
+            { key: 'Instance URL', value: context.instanceUrl },
+            { key: 'Org Type', value: context.isSandbox ? 'Sandbox' : 'Production' },
+        ],
+    });
+}
+//# sourceMappingURL=command-display.js.map

package/lib/utils/formatting/command-display.js.map

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