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

package/lib/debug/debug-logger.js

@@ -0,0 +1,133 @@
+/*
+ * 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.
+ */
+/**
+ * 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 class DebugLogger {
+    static enabled = false;
+    /**
+     * Enable or disable debug logging globally.
+     *
+     * @param debug - Whether to enable debug logging
+     */
+    static setEnabled(debug) {
+        DebugLogger.enabled = debug;
+    }
+    /**
+     * Check if debug logging is currently enabled.
+     *
+     * @returns True if debug logging is enabled
+     */
+    static isEnabled() {
+        return DebugLogger.enabled;
+    }
+    /**
+     * 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, context, phase, details) {
+        if (!DebugLogger.enabled) {
+            return;
+        }
+        // eslint-disable-next-line no-console
+        console.error(`[DEBUG] [${layer}] ${context}: ${phase} → ${details}`);
+    }
+    /**
+     * Log timing information for an operation.
+     *
+     * @param layer - The architectural layer
+     * @param context - The context identifier
+     * @param durationMs - Duration in milliseconds
+     */
+    static logTiming(layer, context, durationMs) {
+        if (!DebugLogger.enabled) {
+            return;
+        }
+        // eslint-disable-next-line no-console
+        console.error(`[DEBUG] [${layer}] ${context}: timing → ${durationMs}ms`);
+    }
+    /**
+     * 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, context, success, durationMs, sizeBytes) {
+        if (!DebugLogger.enabled) {
+            return;
+        }
+        const sizeSuffix = sizeBytes !== undefined ? ` size=${DebugLogger.formatSize(sizeBytes)}` : '';
+        // eslint-disable-next-line no-console
+        console.error(`[DEBUG] [${layer}] ${context}: result → success=${success} duration=${durationMs}ms${sizeSuffix}`);
+    }
+    /**
+     * Format bytes as human-readable size (B, KB, MB).
+     *
+     * @param bytes - Size in bytes
+     * @returns Human-readable size string
+     */
+    static formatSize(bytes) {
+        if (bytes === 0) {
+            return '0B';
+        }
+        if (bytes < 1024) {
+            return `${bytes}B`;
+        }
+        if (bytes < 1_048_576) {
+            return `${(bytes / 1024).toFixed(1)}KB`;
+        }
+        return `${(bytes / 1_048_576).toFixed(1)}MB`;
+    }
+    /**
+     * 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, maxLen) {
+        if (maxLen <= 0) {
+            return '';
+        }
+        if (str.length <= maxLen) {
+            return str;
+        }
+        if (maxLen <= 3) {
+            return '...';
+        }
+        return str.slice(0, maxLen - 3) + '...';
+    }
+}
+//# sourceMappingURL=debug-logger.js.map

package/lib/debug/debug-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-logger.js","sourceRoot":"","sources":["../../src/debug/debug-logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;OAIG;IACI,MAAM,CAAC,UAAU,CAAC,KAAc;QACrC,WAAW,CAAC,OAAO,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,SAAS;QACrB,OAAO,WAAW,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED;;;;;;;;;OASG;IACI,MAAM,CAAC,GAAG,CAAC,KAAiB,EAAE,OAAe,EAAE,KAAa,EAAE,OAAe;QAClF,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YACzB,OAAO;QACT,CAAC;QACD,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,YAAY,KAAK,KAAK,OAAO,KAAK,KAAK,MAAM,OAAO,EAAE,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,SAAS,CAAC,KAAiB,EAAE,OAAe,EAAE,UAAkB;QAC5E,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YACzB,OAAO;QACT,CAAC;QACD,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,YAAY,KAAK,KAAK,OAAO,cAAc,UAAU,IAAI,CAAC,CAAC;IAC3E,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM,CAAC,SAAS,CACrB,KAAiB,EACjB,OAAe,EACf,OAAgB,EAChB,UAAkB,EAClB,SAAkB;QAElB,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YACzB,OAAO;QACT,CAAC;QACD,MAAM,UAAU,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/F,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,YAAY,KAAK,KAAK,OAAO,sBAAsB,OAAO,aAAa,UAAU,KAAK,UAAU,EAAE,CAAC,CAAC;IACpH,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,UAAU,CAAC,KAAa;QACpC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,KAAK,GAAG,IAAI,EAAE,CAAC;YACjB,OAAO,GAAG,KAAK,GAAG,CAAC;QACrB,CAAC;QACD,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,OAAO,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1C,CAAC;QACD,OAAO,GAAG,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,QAAQ,CAAC,GAAW,EAAE,MAAc;QAChD,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;YAChB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;YACzB,OAAO,GAAG,CAAC;QACb,CAAC;QACD,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;YAChB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;IAC1C,CAAC"}

package/lib/debug/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Debug infrastructure for infrastructure-level logging.
+ *
+ * This module provides unified debug logging that works across all layers
+ * (Adapter, Service, MCP, CLI) without requiring changes to individual
+ * services, adapters, or handlers.
+ *
+ * @module debug
+ */
+export { DebugLogger, type DebugLayer } from './debug-logger.js';
+export { withServiceDebugLogging } from './service-debug-proxy.js';
+export { withCommandDebugLogging, executeWithDebugLogging, type DebugWrappableCommand, type CommandDebugResult, } from './command-debug-proxy.js';

package/lib/debug/index.js

@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Debug infrastructure for infrastructure-level logging.
+ *
+ * This module provides unified debug logging that works across all layers
+ * (Adapter, Service, MCP, CLI) without requiring changes to individual
+ * services, adapters, or handlers.
+ *
+ * @module debug
+ */
+export { DebugLogger } from './debug-logger.js';
+export { withServiceDebugLogging } from './service-debug-proxy.js';
+export { withCommandDebugLogging, executeWithDebugLogging, } from './command-debug-proxy.js';
+//# sourceMappingURL=index.js.map

package/lib/debug/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/debug/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAmB,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EACL,uBAAuB,EACvB,uBAAuB,GAGxB,MAAM,0BAA0B,CAAC"}

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

@@ -0,0 +1,30 @@
+/**
+ * Wraps a service with debug logging for all method calls.
+ *
+ * When debug is enabled, creates a Proxy that intercepts all method calls and:
+ * - Logs method entry with arguments
+ * - Logs method exit with success status and timing
+ * - Logs errors when methods throw
+ *
+ * When debug is disabled (default), returns the original service unchanged
+ * with zero overhead.
+ *
+ * @template T - The service type (must be an object)
+ * @param service - The service instance to wrap
+ * @param serviceName - Name used in log output (e.g., 'OrgInfoService')
+ * @param debug - Whether to enable debug logging (default: false)
+ * @returns The service, wrapped with logging if debug=true
+ *
+ * @example
+ * ```typescript
+ * // Without logging (production)
+ * const service = withServiceDebugLogging(new OrgInfoService(conn), 'OrgInfoService');
+ *
+ * // With logging (debug mode)
+ * const service = withServiceDebugLogging(new OrgInfoService(conn), 'OrgInfoService', true);
+ * // Calls will log:
+ * // [DEBUG] [SERVICE] OrgInfoService.getOrgIdentity: called → []
+ * // [DEBUG] [SERVICE] OrgInfoService.getOrgIdentity: result → success=true duration=150ms
+ * ```
+ */
+export declare function withServiceDebugLogging<T extends object>(service: T, serviceName: string, debug?: boolean): T;

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

@@ -0,0 +1,102 @@
+/*
+ * 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';
+/**
+ * Type guard to check if a value looks like a ServiceResult.
+ * ServiceResult has { success: boolean, data: T } at minimum.
+ */
+function isServiceResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'success' in value &&
+        typeof value.success === 'boolean');
+}
+/**
+ * Wraps a service with debug logging for all method calls.
+ *
+ * When debug is enabled, creates a Proxy that intercepts all method calls and:
+ * - Logs method entry with arguments
+ * - Logs method exit with success status and timing
+ * - Logs errors when methods throw
+ *
+ * When debug is disabled (default), returns the original service unchanged
+ * with zero overhead.
+ *
+ * @template T - The service type (must be an object)
+ * @param service - The service instance to wrap
+ * @param serviceName - Name used in log output (e.g., 'OrgInfoService')
+ * @param debug - Whether to enable debug logging (default: false)
+ * @returns The service, wrapped with logging if debug=true
+ *
+ * @example
+ * ```typescript
+ * // Without logging (production)
+ * const service = withServiceDebugLogging(new OrgInfoService(conn), 'OrgInfoService');
+ *
+ * // With logging (debug mode)
+ * const service = withServiceDebugLogging(new OrgInfoService(conn), 'OrgInfoService', true);
+ * // Calls will log:
+ * // [DEBUG] [SERVICE] OrgInfoService.getOrgIdentity: called → []
+ * // [DEBUG] [SERVICE] OrgInfoService.getOrgIdentity: result → success=true duration=150ms
+ * ```
+ */
+export function withServiceDebugLogging(service, serviceName, debug) {
+    // Early return for zero overhead when debug is disabled
+    if (!debug) {
+        return service;
+    }
+    // Enable debug logger
+    DebugLogger.setEnabled(true);
+    return new Proxy(service, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            // Only wrap functions
+            if (typeof value !== 'function') {
+                return value;
+            }
+            // Return a wrapped function that logs
+            return (...args) => {
+                const methodName = String(prop);
+                const context = `${serviceName}.${methodName}`;
+                // Log method entry
+                DebugLogger.log('SERVICE', context, 'called', JSON.stringify(args));
+                const start = Date.now();
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- Proxy applies to unknown method signatures
+                    const result = value.apply(target, args);
+                    // Handle async methods (returns Promise)
+                    if (result instanceof Promise) {
+                        return result
+                            .then((resolvedValue) => {
+                            const duration = Date.now() - start;
+                            const success = isServiceResult(resolvedValue) ? resolvedValue.success : true;
+                            DebugLogger.log('SERVICE', context, 'result', `success=${success} duration=${duration}ms`);
+                            return resolvedValue;
+                        })
+                            .catch((error) => {
+                            const errorMessage = error instanceof Error ? error.message : String(error);
+                            DebugLogger.log('SERVICE', context, 'error', errorMessage);
+                            throw error;
+                        });
+                    }
+                    // Handle sync methods
+                    const duration = Date.now() - start;
+                    const success = isServiceResult(result) ? result.success : true;
+                    DebugLogger.log('SERVICE', context, 'result', `success=${success} duration=${duration}ms`);
+                    return result;
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    DebugLogger.log('SERVICE', context, 'error', errorMessage);
+                    throw error;
+                }
+            };
+        },
+    });
+}
+//# sourceMappingURL=service-debug-proxy.js.map

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

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

package/lib/hooks/prerun.d.ts

@@ -0,0 +1,25 @@
+import { Hook } from '@oclif/core';
+/**
+ * Prerun hook that enables debug logging when --debug flag is present.
+ *
+ * This hook runs after command resolution but before run() execution. Since
+ * oclif has already instantiated the command and will execute the original
+ * run() method, we enable the DebugLogger globally so that SERVICE and
+ * ADAPTER layers produce debug output.
+ *
+ * Architecture:
+ * - Checks for --debug flag in argv
+ * - Enables DebugLogger globally
+ * - SERVICE and ADAPTER layers check DebugLogger.isEnabled()
+ * - Zero overhead when --debug flag is not present
+ *
+ * Note: CLI-layer command logging (flags, timing) would require a base command
+ * class or command-level changes. This implementation focuses on enabling
+ * SERVICE → ADAPTER debug output which is the primary use case.
+ *
+ * @see src/debug/debug-logger.ts
+ * @see src/debug/service-debug-proxy.ts
+ * @see src/adapters/connection-facade.ts (createDebugConnectionFacade)
+ */
+declare const hook: Hook.Prerun;
+export default hook;

package/lib/hooks/prerun.js

@@ -0,0 +1,47 @@
+/*
+ * 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/debug-logger.js';
+/**
+ * Prerun hook that enables debug logging when --debug flag is present.
+ *
+ * This hook runs after command resolution but before run() execution. Since
+ * oclif has already instantiated the command and will execute the original
+ * run() method, we enable the DebugLogger globally so that SERVICE and
+ * ADAPTER layers produce debug output.
+ *
+ * Architecture:
+ * - Checks for --debug flag in argv
+ * - Enables DebugLogger globally
+ * - SERVICE and ADAPTER layers check DebugLogger.isEnabled()
+ * - Zero overhead when --debug flag is not present
+ *
+ * Note: CLI-layer command logging (flags, timing) would require a base command
+ * class or command-level changes. This implementation focuses on enabling
+ * SERVICE → ADAPTER debug output which is the primary use case.
+ *
+ * @see src/debug/debug-logger.ts
+ * @see src/debug/service-debug-proxy.ts
+ * @see src/adapters/connection-facade.ts (createDebugConnectionFacade)
+ */
+// eslint-disable-next-line @typescript-eslint/require-await -- Hook.Prerun type requires async
+const hook = async function (options) {
+    // Check if --debug flag is present in argv
+    const debugEnabled = options.argv?.includes('--debug') ?? false;
+    if (!debugEnabled) {
+        // No debug flag - return early (zero overhead)
+        return;
+    }
+    // Enable debug logger globally
+    DebugLogger.setEnabled(true);
+    // Get command name for logging
+    const commandName = options.Command.id ?? 'unknown';
+    // Log that debug mode is enabled
+    DebugLogger.log('CLI', commandName, 'debug', 'enabled via --debug flag');
+};
+export default hook;
+//# sourceMappingURL=prerun.js.map

package/lib/hooks/prerun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prerun.js","sourceRoot":"","sources":["../../src/hooks/prerun.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,+FAA+F;AAC/F,MAAM,IAAI,GAAgB,KAAK,WAAW,OAAO;IAC/C,2CAA2C;IAC3C,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC;IAEhE,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,+CAA+C;QAC/C,OAAO;IACT,CAAC;IAED,+BAA+B;IAC/B,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAE7B,+BAA+B;IAC/B,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,SAAS,CAAC;IAEpD,iCAAiC;IACjC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,0BAA0B,CAAC,CAAC;AAC3E,CAAC,CAAC;AAEF,eAAe,IAAI,CAAC"}

package/lib/mcp/config/mcp-config.d.ts

@@ -0,0 +1,55 @@
+import type { Connection } from '@salesforce/core';
+import { type IConnectionFacade } from '../../adapters/connection-facade.js';
+import { type ISoqlQueryAdapter } from '../../adapters/soql/soql-query-adapter.js';
+import { type IRestApiAdapter } from '../../adapters/rest/rest-api-adapter.js';
+import { type IToolingApiAdapter } from '../../adapters/tooling/tooling-api-adapter.js';
+/**
+ * Session-scoped adapter set shared across MCP tool invocations.
+ *
+ * Constructed once in `createMcpServer()` and closed over by all tool handlers.
+ * This allows LRU caches (e.g., RestApiAdapter's describe cache) to persist
+ * across paginated calls within a single MCP session.
+ */
+export type McpAdapters = {
+    /** Raw Salesforce connection (for handlers that need direct access, e.g., SFDMUService) */
+    readonly connection: Connection;
+    /** Shared connection facade (for services that need identity, instanceUrl, etc.) */
+    readonly facade: IConnectionFacade;
+    readonly soql: ISoqlQueryAdapter;
+    readonly rest: IRestApiAdapter;
+    readonly tooling: IToolingApiAdapter;
+};
+/**
+ * MCP Server configuration.
+ */
+export type McpServerConfig = {
+    /** Server name for identification */
+    readonly name: string;
+    /** Server version (matches plugin version) */
+    readonly version: string;
+    /** Target org connection string */
+    readonly targetOrg: string;
+    /** Optional API version override */
+    readonly apiVersion?: string;
+    /** Enable debug logging */
+    readonly debug?: boolean;
+};
+/**
+ * Creates default MCP server configuration.
+ *
+ * @param targetOrg - Target Salesforce org alias or username
+ * @param apiVersion - Optional API version override
+ * @param debug - Enable debug logging
+ * @returns MCP server configuration
+ */
+export declare function createMcpConfig(targetOrg: string, apiVersion?: string, debug?: boolean): McpServerConfig;
+/**
+ * Creates the MCP adapter stack from a Salesforce connection.
+ *
+ * Single source of truth for MCP adapter instantiation. Used by both
+ * `createMcpServer()` (session-scoped) and `invokeTool()` (per-call).
+ *
+ * @param connection - Raw Salesforce connection
+ * @returns MCP adapter set with connection, facade, and all three adapters
+ */
+export declare function createMcpAdapters(connection: Connection): McpAdapters;

package/lib/mcp/config/mcp-config.js

@@ -0,0 +1,51 @@
+/*
+ * 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 { createRequire } from 'node:module';
+import { createConnectionFacade } from '../../adapters/connection-facade.js';
+import { SoqlQueryAdapter } from '../../adapters/soql/soql-query-adapter.js';
+import { RestApiAdapter } from '../../adapters/rest/rest-api-adapter.js';
+import { ToolingApiAdapter } from '../../adapters/tooling/tooling-api-adapter.js';
+const require = createRequire(import.meta.url);
+const { version: PLUGIN_VERSION } = require('../../../package.json');
+/**
+ * Creates default MCP server configuration.
+ *
+ * @param targetOrg - Target Salesforce org alias or username
+ * @param apiVersion - Optional API version override
+ * @param debug - Enable debug logging
+ * @returns MCP server configuration
+ */
+export function createMcpConfig(targetOrg, apiVersion, debug) {
+    return {
+        name: 'cuneiform',
+        version: PLUGIN_VERSION,
+        targetOrg,
+        apiVersion,
+        debug: debug ?? false,
+    };
+}
+/**
+ * Creates the MCP adapter stack from a Salesforce connection.
+ *
+ * Single source of truth for MCP adapter instantiation. Used by both
+ * `createMcpServer()` (session-scoped) and `invokeTool()` (per-call).
+ *
+ * @param connection - Raw Salesforce connection
+ * @returns MCP adapter set with connection, facade, and all three adapters
+ */
+export function createMcpAdapters(connection) {
+    const facade = createConnectionFacade(connection);
+    return {
+        connection,
+        facade,
+        soql: new SoqlQueryAdapter(facade),
+        rest: new RestApiAdapter(facade),
+        tooling: new ToolingApiAdapter(facade),
+    };
+}
+//# sourceMappingURL=mcp-config.js.map

package/lib/mcp/config/mcp-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-config.js","sourceRoot":"","sources":["../../../src/mcp/config/mcp-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,sBAAsB,EAA0B,MAAM,qCAAqC,CAAC;AACrG,OAAO,EAAE,gBAAgB,EAA0B,MAAM,2CAA2C,CAAC;AACrG,OAAO,EAAE,cAAc,EAAwB,MAAM,yCAAyC,CAAC;AAC/F,OAAO,EAAE,iBAAiB,EAA2B,MAAM,+CAA+C,CAAC;AAE3G,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAwB,CAAC;AAuC5F;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,UAAmB,EAAE,KAAe;IACrF,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;QACvB,SAAS;QACT,UAAU;QACV,KAAK,EAAE,KAAK,IAAI,KAAK;KACtB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAsB;IACtD,MAAM,MAAM,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;IAClD,OAAO;QACL,UAAU;QACV,MAAM;QACN,IAAI,EAAE,IAAI,gBAAgB,CAAC,MAAM,CAAC;QAClC,IAAI,EAAE,IAAI,cAAc,CAAC,MAAM,CAAC;QAChC,OAAO,EAAE,IAAI,iBAAiB,CAAC,MAAM,CAAC;KACvC,CAAC;AACJ,CAAC"}

package/lib/mcp/config/pagination.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pagination infrastructure for MCP tool responses.
+ *
+ * Provides cursor-based pagination with server-side page size clamping
+ * to keep responses within LLM context budgets (~5 KB per response).
+ */
+/**
+ * Page size defaults and maximums for each paginated resource type.
+ */
+export declare const PAGE_SIZE_DEFAULTS: {
+    readonly OBJECT_LIST: {
+        readonly default: 25;
+        readonly max: 50;
+    };
+    readonly FIELD_LIST: {
+        readonly default: 25;
+        readonly max: 50;
+    };
+    readonly RELATIONSHIP_LIST: {
+        readonly default: 10;
+        readonly max: 25;
+    };
+    readonly NAMESPACE_LIST: {
+        readonly default: 10;
+        readonly max: 25;
+    };
+    readonly RECORD_TYPE_LIST: {
+        readonly default: 10;
+        readonly max: 25;
+    };
+};
+/**
+ * Metadata included in every paginated response envelope.
+ */
+export type PaginationMetadata = {
+    /** Number of items returned in this page */
+    readonly returned: number;
+    /** Total number of items across all pages */
+    readonly total: number;
+    /** Whether more items are available */
+    readonly hasMore: boolean;
+    /** Opaque cursor to pass for the next page (undefined on last page) */
+    readonly nextCursor?: string;
+    /** Items per page used for this response */
+    readonly pageSize: number;
+    /** Human-readable pagination status message */
+    readonly message: string;
+};
+/**
+ * Encodes a numeric offset into an opaque base64 cursor string.
+ *
+ * @param offset - The zero-based offset to encode
+ * @returns Opaque cursor string
+ */
+export declare function encodeCursor(offset: number): string;
+/**
+ * Decodes an opaque cursor string back to a numeric offset.
+ *
+ * Returns 0 for undefined or empty cursors (start from beginning).
+ * Throws for malformed cursors to prevent silent pagination loops.
+ *
+ * @param cursor - Opaque cursor string from a previous response
+ * @returns The decoded offset, or 0 if cursor is undefined/empty
+ * @throws Error if the cursor is present but malformed
+ */
+export declare function decodeCursor(cursor: string | undefined): number;
+/**
+ * Clamps a requested page size to within [1, max], defaulting if undefined.
+ *
+ * @param requested - The page size requested by the client (may be undefined)
+ * @param defaultSize - Default page size when not specified
+ * @param maxSize - Maximum allowed page size
+ * @returns Clamped page size
+ */
+export declare function clampPageSize(requested: number | undefined, defaultSize: number, maxSize: number): number;
+/**
+ * Input parameters for creating pagination metadata.
+ */
+type PaginationMetadataInput = {
+    /** Current offset (start of this page) */
+    readonly offset: number;
+    /** Page size used for this response */
+    readonly pageSize: number;
+    /** Total number of items across all pages */
+    readonly totalItems: number;
+    /** Actual number of items returned in this page */
+    readonly returnedItems: number;
+};
+/**
+ * Creates pagination metadata for a response envelope.
+ *
+ * @param input - Pagination parameters
+ * @returns Pagination metadata with cursor and status message
+ */
+export declare function createPaginationMetadata(input: PaginationMetadataInput): PaginationMetadata;
+export {};