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

package/lib/constants/namespace-constants.js

@@ -0,0 +1,211 @@
+/*
+ * 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.
+ */
+/**
+ * Mapping of Salesforce namespace prefixes to product names.
+ *
+ * This map enables identification of installed Salesforce products by their
+ * namespace prefix. Managed packages use namespace prefixes on custom objects
+ * (e.g., `SBQQ__Quote__c` indicates Salesforce CPQ is installed).
+ *
+ * @see docs/knowledge/salesforce/namespaces.md for comprehensive documentation
+ *
+ * @example
+ * ```typescript
+ * const namespace = 'SBQQ__';
+ * const product = NAMESPACE_PRODUCT_MAP[namespace];
+ * console.log(product); // 'Salesforce CPQ'
+ * ```
+ */
+/* eslint-disable camelcase -- Salesforce namespace prefixes use underscores */
+export const NAMESPACE_PRODUCT_MAP = {
+    // Industry Clouds (Managed Packages)
+    HealthCloudGA__: 'Health Cloud',
+    FinServ__: 'Financial Services Cloud',
+    industriespersonalizedfinance: 'FSC Personalized Finance',
+    CGCloud__: 'Consumer Goods Cloud',
+    vlocity_cmt__: 'Vlocity CMT (Communications/Media/Energy)',
+    vlocity_ins__: 'Vlocity Insurance',
+    omnistudio: 'OmniStudio',
+    // Salesforce Add-on Products
+    SBQQ__: 'Salesforce CPQ',
+    FSL__: 'Field Service',
+    et4ae5__: 'Marketing Cloud Connect',
+    pi__: 'Pardot (legacy)',
+    b2bma: 'Pardot B2B Marketing',
+    maps__: 'Salesforce Maps',
+    blng__: 'Salesforce Billing',
+    ccrz: 'B2B Commerce (CloudCraze)',
+    wkcc__: 'Work.com',
+    // Nonprofit Ecosystem
+    npsp__: 'Nonprofit Success Pack',
+    npe01__: 'NPSP Contacts & Organizations',
+    npo02__: 'NPSP Households',
+    npe03__: 'NPSP Recurring Donations',
+    npe4__: 'NPSP Relationships',
+    npe5__: 'NPSP Affiliations',
+    hed__: 'Education Data Architecture',
+    pmdm__: 'Program Management Module',
+    sfdobase__: 'SFDO Base',
+    scm__: 'Nonprofit Case Management',
+    outfunds__: 'Outbound Funds Module',
+    GW_Volunteers__: 'Volunteers for Salesforce',
+    // Data Cloud / CDP
+    ssot__: 'Data Cloud SSOT',
+    // Salesforce Labs
+    agf__: 'Agile Accelerator',
+    dlrs: 'DLRS (Rollup Summaries)',
+    MPM4_BASE: 'Milestones PM+',
+    LABSMPM: 'Milestones PM',
+    // Cuneiform
+    // Both forms supported: 'pnova' (identifier) and 'pnova__' (object/field references)
+    pnova: 'Cuneiform for CRM',
+    pnova__: 'Cuneiform for CRM',
+};
+/**
+ * Namespace-to-cloud name mapping for package-based cloud detection.
+ * Keys are namespace prefixes without trailing underscores.
+ */
+export const CLOUD_NAMESPACE_MAP = {
+    FinServ: 'Financial Services Cloud',
+    HealthCloudGA: 'Health Cloud',
+    CGCloud: 'Consumer Goods Cloud',
+    vlocity_cmt: 'Communications/Media/Energy Cloud',
+    vlocity_ins: 'Insurance Cloud',
+    omnistudio: 'OmniStudio',
+};
+/* eslint-enable camelcase */
+/**
+ * The namespace prefix used by Cuneiform for CRM.
+ */
+export const CUNEIFORM_NAMESPACE = 'pnova';
+/**
+ * The namespace prefix with trailing underscores (for object/field references).
+ */
+export const CUNEIFORM_NAMESPACE_PREFIX = 'pnova__';
+/**
+ * Gets the product name for a given namespace prefix.
+ *
+ * @param namespace - The namespace prefix (with or without trailing underscores)
+ * @returns The product name or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * getProductName('SBQQ__');    // 'Salesforce CPQ'
+ * getProductName('SBQQ');      // 'Salesforce CPQ' (normalizes input)
+ * getProductName('Unknown__'); // undefined
+ * ```
+ */
+export function getProductName(namespace) {
+    // Try exact match first
+    if (NAMESPACE_PRODUCT_MAP[namespace]) {
+        return NAMESPACE_PRODUCT_MAP[namespace];
+    }
+    // Try with trailing underscores if not present
+    const withUnderscores = namespace.endsWith('__') ? namespace : `${namespace}__`;
+    if (NAMESPACE_PRODUCT_MAP[withUnderscores]) {
+        return NAMESPACE_PRODUCT_MAP[withUnderscores];
+    }
+    // Try without trailing underscores
+    const withoutUnderscores = namespace.replace(/__$/, '');
+    return NAMESPACE_PRODUCT_MAP[withoutUnderscores];
+}
+/**
+ * Checks if a namespace belongs to Cuneiform.
+ *
+ * @param namespace - The namespace to check
+ * @returns True if the namespace is Cuneiform's namespace
+ */
+export function isCuneiformNamespace(namespace) {
+    const normalized = namespace.replace(/__$/, '');
+    return normalized === CUNEIFORM_NAMESPACE;
+}
+/**
+ * Extracts unique namespaces from a list of object API names.
+ *
+ * @param objectNames - Array of Salesforce object API names
+ * @returns Array of unique namespace prefixes found
+ *
+ * @example
+ * ```typescript
+ * extractNamespaces(['SBQQ__Quote__c', 'Account', 'npsp__Donation__c']);
+ * // Returns: ['SBQQ__', 'npsp__']
+ * ```
+ */
+export function extractNamespaces(objectNames) {
+    const namespaces = new Set();
+    for (const name of objectNames) {
+        // Custom objects with namespaces follow pattern: Namespace__ObjectName__c
+        // Standard objects and unmanaged custom objects don't have namespace prefix
+        // The negative lookahead (?!c$|mdt$|e$|b$|x$|r$) ensures we don't match
+        // standard suffixes (__c, __mdt, __e, __b, __x, __r) as namespaces
+        const match = name.match(/^([A-Za-z0-9]+__)(?!c$|mdt$|e$|b$|x$|r$)/);
+        if (match) {
+            namespaces.add(match[1]);
+        }
+    }
+    return Array.from(namespaces).sort();
+}
+/**
+ * Industry Cloud namespace identifiers (without trailing underscores).
+ *
+ * These are a subset of NAMESPACE_PRODUCT_MAP that represent Salesforce
+ * Industry Cloud products rather than add-on managed packages.
+ */
+const INDUSTRY_NAMESPACES = new Set([
+    'HealthCloudGA',
+    'FinServ',
+    'industriespersonalizedfinance',
+    'CGCloud',
+    'vlocity_cmt',
+    'vlocity_ins',
+    'omnistudio',
+]);
+/**
+ * Normalizes a namespace prefix by removing trailing underscores.
+ *
+ * @param namespace - The namespace to normalize
+ * @returns The namespace without trailing underscores
+ */
+function normalizeNamespace(namespace) {
+    return namespace.replace(/__$/, '');
+}
+/**
+ * Categorizes a Salesforce namespace prefix into one of four categories:
+ * standard, industry, managed, or custom.
+ *
+ * @param namespace - The namespace prefix (with or without trailing underscores).
+ * Null, undefined, or empty string indicates a standard (platform-native) object.
+ * @returns The category classification for the namespace
+ *
+ * @example
+ * ```typescript
+ * categorizeNamespace(null);              // 'standard'
+ * categorizeNamespace('');                // 'standard'
+ * categorizeNamespace('FinServ__');       // 'industry'
+ * categorizeNamespace('SBQQ__');         // 'managed'
+ * categorizeNamespace('MyCustomPkg__');  // 'custom'
+ * ```
+ */
+export function categorizeNamespace(namespace) {
+    // Null, undefined, or empty/whitespace-only → standard (platform-native)
+    if (namespace == null || namespace.trim() === '') {
+        return 'standard';
+    }
+    const normalized = normalizeNamespace(namespace.trim());
+    // Check industry namespaces first (subset of known namespaces)
+    if (INDUSTRY_NAMESPACES.has(normalized)) {
+        return 'industry';
+    }
+    // Check if it's a known namespace in the product map (either form)
+    if (NAMESPACE_PRODUCT_MAP[normalized] ?? NAMESPACE_PRODUCT_MAP[`${normalized}__`]) {
+        return 'managed';
+    }
+    // Unknown namespace → custom
+    return 'custom';
+}
+//# sourceMappingURL=namespace-constants.js.map

package/lib/constants/namespace-constants.js.map

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

package/lib/debug/command-debug-proxy.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Parsed flags from a command's parse() call.
+ * The exact structure depends on the command's flag definitions.
+ */
+type ParsedFlags = Record<string, unknown>;
+/**
+ * Minimal interface for commands that can be wrapped with debug logging.
+ *
+ * This interface represents the essential shape of an SfCommand that the
+ * debug proxy needs to intercept. Commands must have a run() method that
+ * returns a Promise.
+ *
+ * @template T - The result type returned by the command's run() method
+ */
+export type DebugWrappableCommand<T> = {
+    /** Executes the command and returns a result */
+    run(): Promise<T>;
+};
+/**
+ * Result of wrapping a command with debug logging.
+ *
+ * Contains the wrapped command and a cleanup function that should be
+ * called after command execution completes (success or failure).
+ *
+ * @template T - The result type returned by the command's run() method
+ */
+export type CommandDebugResult<T> = {
+    /** The command instance, wrapped with debug logging if debug=true */
+    command: DebugWrappableCommand<T>;
+    /** Cleanup function to restore debug state after execution */
+    cleanup: () => void;
+};
+/**
+ * Wraps a command's run() method with debug logging for CLI layer visibility.
+ *
+ * When debug is enabled, creates a Proxy that intercepts the run() method and:
+ * - Logs command start with flags: `[DEBUG] [CLI] commandName: flags → {...}`
+ * - Logs command completion with timing: `[DEBUG] [CLI] commandName: complete → duration=Xms`
+ * - Logs errors: `[DEBUG] [CLI] commandName: error → message`
+ *
+ * When debug is disabled (default), returns the original command unchanged
+ * with zero overhead.
+ *
+ * @template T - The result type returned by the command's run() method
+ * @param command - The command instance to wrap
+ * @param commandName - Name used in log output (e.g., 'cuneiform:org:details')
+ * @param debug - Whether to enable debug logging (default: false)
+ * @param flags - Optional parsed flags to log at command start
+ * @returns Object containing the wrapped command and cleanup function
+ *
+ * @example
+ * ```typescript
+ * // In a hook or command infrastructure
+ * const { command: wrapped, cleanup } = withCommandDebugLogging(
+ *   commandInstance,
+ *   'cuneiform:org:details',
+ *   flags.debug,
+ *   flags
+ * );
+ *
+ * try {
+ *   const result = await wrapped.run();
+ *   return result;
+ * } finally {
+ *   cleanup();
+ * }
+ *
+ * // Output when debug=true:
+ * // [DEBUG] [CLI] cuneiform:org:details: flags → {"target-org":"myOrg","verbose":true}
+ * // [DEBUG] [CLI] cuneiform:org:details: complete → duration=150ms
+ * ```
+ */
+export declare function withCommandDebugLogging<T>(command: DebugWrappableCommand<T>, commandName: string, debug?: boolean, flags?: ParsedFlags): CommandDebugResult<T>;
+/**
+ * Convenience function to execute a command with debug logging.
+ *
+ * This is a higher-level wrapper that handles the full lifecycle:
+ * 1. Wraps the command with debug logging
+ * 2. Executes the command
+ * 3. Cleans up debug state
+ *
+ * @template T - The result type returned by the command's run() method
+ * @param command - The command instance to execute
+ * @param commandName - Name used in log output
+ * @param debug - Whether to enable debug logging
+ * @param flags - Optional parsed flags to log
+ * @returns Promise resolving to the command result
+ *
+ * @example
+ * ```typescript
+ * // Instead of managing wrap/cleanup manually:
+ * const result = await executeWithDebugLogging(
+ *   commandInstance,
+ *   'cuneiform:org:details',
+ *   flags.debug,
+ *   flags
+ * );
+ * ```
+ */
+export declare function executeWithDebugLogging<T>(command: DebugWrappableCommand<T>, commandName: string, debug?: boolean, flags?: ParsedFlags): Promise<T>;
+export {};

package/lib/debug/command-debug-proxy.js

@@ -0,0 +1,171 @@
+/*
+ * 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 { DebugLogger } from './debug-logger.js';
+/**
+ * Wraps a command's run() method with debug logging for CLI layer visibility.
+ *
+ * When debug is enabled, creates a Proxy that intercepts the run() method and:
+ * - Logs command start with flags: `[DEBUG] [CLI] commandName: flags → {...}`
+ * - Logs command completion with timing: `[DEBUG] [CLI] commandName: complete → duration=Xms`
+ * - Logs errors: `[DEBUG] [CLI] commandName: error → message`
+ *
+ * When debug is disabled (default), returns the original command unchanged
+ * with zero overhead.
+ *
+ * @template T - The result type returned by the command's run() method
+ * @param command - The command instance to wrap
+ * @param commandName - Name used in log output (e.g., 'cuneiform:org:details')
+ * @param debug - Whether to enable debug logging (default: false)
+ * @param flags - Optional parsed flags to log at command start
+ * @returns Object containing the wrapped command and cleanup function
+ *
+ * @example
+ * ```typescript
+ * // In a hook or command infrastructure
+ * const { command: wrapped, cleanup } = withCommandDebugLogging(
+ *   commandInstance,
+ *   'cuneiform:org:details',
+ *   flags.debug,
+ *   flags
+ * );
+ *
+ * try {
+ *   const result = await wrapped.run();
+ *   return result;
+ * } finally {
+ *   cleanup();
+ * }
+ *
+ * // Output when debug=true:
+ * // [DEBUG] [CLI] cuneiform:org:details: flags → {"target-org":"myOrg","verbose":true}
+ * // [DEBUG] [CLI] cuneiform:org:details: complete → duration=150ms
+ * ```
+ */
+export function withCommandDebugLogging(command, commandName, debug, flags) {
+    // Early return for zero overhead when debug is disabled
+    if (!debug) {
+        return {
+            command,
+            cleanup: () => {
+                /* no-op */
+            },
+        };
+    }
+    // Enable debug logger
+    DebugLogger.setEnabled(true);
+    // Log command start with flags
+    if (flags) {
+        const sanitizedFlags = sanitizeFlags(flags);
+        DebugLogger.log('CLI', commandName, 'flags', JSON.stringify(sanitizedFlags));
+    }
+    const start = Date.now();
+    const wrappedCommand = new Proxy(command, {
+        get(target, prop, receiver) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- Reflect.get returns unknown at runtime
+            const value = Reflect.get(target, prop, receiver);
+            // Only wrap the run() method
+            if (prop === 'run' && typeof value === 'function') {
+                return async () => {
+                    try {
+                        // The run method is typed as () => Promise<T> from DebugWrappableCommand
+                        const runFn = value;
+                        const result = await runFn.call(target);
+                        const duration = Date.now() - start;
+                        DebugLogger.log('CLI', commandName, 'complete', `duration=${duration}ms`);
+                        return result;
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        DebugLogger.log('CLI', commandName, 'error', errorMessage);
+                        throw error;
+                    }
+                };
+            }
+            return value;
+        },
+    });
+    return {
+        command: wrappedCommand,
+        cleanup: () => {
+            // Reset debug logger if needed
+            // Note: We don't disable here because other layers may still be logging
+        },
+    };
+}
+/**
+ * Sanitizes flags for logging by removing sensitive values.
+ *
+ * Removes or redacts:
+ * - access tokens
+ * - passwords
+ * - connection objects (replaced with type indicator)
+ *
+ * @param flags - The raw parsed flags
+ * @returns Sanitized flags safe for logging
+ */
+function sanitizeFlags(flags) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(flags)) {
+        // Skip sensitive keys
+        if (key.toLowerCase().includes('token') || key.toLowerCase().includes('password')) {
+            sanitized[key] = '[REDACTED]';
+            continue;
+        }
+        // Handle connection/org objects (don't log entire object)
+        if (value && typeof value === 'object') {
+            // Check for Salesforce Org objects
+            if ('getConnection' in value || 'getUsername' in value) {
+                sanitized[key] = '[Org]';
+                continue;
+            }
+            // Check for Connection objects
+            if ('accessToken' in value || 'instanceUrl' in value) {
+                sanitized[key] = '[Connection]';
+                continue;
+            }
+        }
+        sanitized[key] = value;
+    }
+    return sanitized;
+}
+/**
+ * Convenience function to execute a command with debug logging.
+ *
+ * This is a higher-level wrapper that handles the full lifecycle:
+ * 1. Wraps the command with debug logging
+ * 2. Executes the command
+ * 3. Cleans up debug state
+ *
+ * @template T - The result type returned by the command's run() method
+ * @param command - The command instance to execute
+ * @param commandName - Name used in log output
+ * @param debug - Whether to enable debug logging
+ * @param flags - Optional parsed flags to log
+ * @returns Promise resolving to the command result
+ *
+ * @example
+ * ```typescript
+ * // Instead of managing wrap/cleanup manually:
+ * const result = await executeWithDebugLogging(
+ *   commandInstance,
+ *   'cuneiform:org:details',
+ *   flags.debug,
+ *   flags
+ * );
+ * ```
+ */
+export async function executeWithDebugLogging(command, commandName, debug, flags) {
+    const { command: wrapped, cleanup } = withCommandDebugLogging(command, commandName, debug, flags);
+    try {
+        return await wrapped.run();
+    }
+    finally {
+        cleanup();
+    }
+}
+//# sourceMappingURL=command-debug-proxy.js.map

package/lib/debug/command-debug-proxy.js.map

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

package/lib/debug/debug-logger.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Debug logging layer identifiers.
+ * Each layer represents a distinct architectural boundary in the application.
+ */
+export type DebugLayer = 'ADAPTER' | 'SERVICE' | 'MCP' | 'CLI';
+/**
+ * Unified debug logging utility for infrastructure-level logging.
+ *
+ * Provides consistent debug output across all layers (Adapter, Service, MCP, CLI)
+ * with zero overhead when disabled. All output goes to stderr to preserve
+ * stdout for JSON-RPC communication and command output.
+ *
+ * @example
+ * ```typescript
+ * // Enable debug logging
+ * DebugLogger.setEnabled(true);
+ *
+ * // Log at different layers
+ * DebugLogger.log('MCP', 'cuneiform_org_details', 'params', '{ verbose: true }');
+ * DebugLogger.log('SERVICE', 'OrgInfoService.getOrgIdentity', 'called', '');
+ * DebugLogger.log('ADAPTER', 'SOQL', 'query', 'SELECT Id FROM Account');
+ * DebugLogger.logResult('MCP', 'cuneiform_org_details', true, 1234, 4300);
+ * ```
+ *
+ * Output format: `[DEBUG] [LAYER] context: phase → details`
+ */
+export declare class DebugLogger {
+    private static enabled;
+    /**
+     * Enable or disable debug logging globally.
+     *
+     * @param debug - Whether to enable debug logging
+     */
+    static setEnabled(debug: boolean): void;
+    /**
+     * Check if debug logging is currently enabled.
+     *
+     * @returns True if debug logging is enabled
+     */
+    static isEnabled(): boolean;
+    /**
+     * Log a debug message with consistent formatting.
+     *
+     * Output format: `[DEBUG] [LAYER] context: phase → details`
+     *
+     * @param layer - The architectural layer (ADAPTER, SERVICE, MCP, CLI)
+     * @param context - The context identifier (tool name, service name, etc.)
+     * @param phase - The phase of operation (params, called, result, etc.)
+     * @param details - Additional details to log
+     */
+    static log(layer: DebugLayer, context: string, phase: string, details: string): void;
+    /**
+     * Log timing information for an operation.
+     *
+     * @param layer - The architectural layer
+     * @param context - The context identifier
+     * @param durationMs - Duration in milliseconds
+     */
+    static logTiming(layer: DebugLayer, context: string, durationMs: number): void;
+    /**
+     * Log a result with success status, duration, and optional response size.
+     *
+     * @param layer - The architectural layer
+     * @param context - The context identifier
+     * @param success - Whether the operation succeeded
+     * @param durationMs - Duration in milliseconds
+     * @param sizeBytes - Response size in bytes (omitted when debug is off and serialization is skipped)
+     */
+    static logResult(layer: DebugLayer, context: string, success: boolean, durationMs: number, sizeBytes?: number): void;
+    /**
+     * Format bytes as human-readable size (B, KB, MB).
+     *
+     * @param bytes - Size in bytes
+     * @returns Human-readable size string
+     */
+    static formatSize(bytes: number): string;
+    /**
+     * Truncate a string to a maximum length, adding ellipsis if truncated.
+     *
+     * @param str - The string to truncate
+     * @param maxLen - Maximum length (including ellipsis)
+     * @returns Truncated string
+     */
+    static truncate(str: string, maxLen: number): string;
+}