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

package/lib/adapters/types.d.ts

@@ -0,0 +1,112 @@
+export type { QueryResult, DescribeSObjectResult, DescribeFieldResult, DescribeGlobalResult, DescribeGlobalSObjectResult, ExecuteAnonymousResult, PicklistEntry, ChildRelationship, RecordTypeInfo, IConnectionFacade, IToolingApi, ISObjectApi, ISObjectQueryBuilder, HttpRequest, } from './connection-facade.js';
+export type { ServiceResult, ServiceResultMetadata } from '../models/service-result.js';
+export { createSuccessResult, createFailureResult } from '../models/service-result.js';
+export { AdapterErrorCodes, mapSalesforceError, ErrorCodeDescriptions, type AdapterErrorCode } from './errors.js';
+/**
+ * Default cache TTL value (5 minutes in milliseconds).
+ *
+ * The 5-minute default balances freshness with performance:
+ * - Short enough to reflect metadata changes within a typical development session
+ * - Long enough to avoid redundant API calls during iterative operations
+ * - Configurable via `CUNEIFORM_CACHE_TTL` environment variable for different use cases
+ */
+export declare const DEFAULT_CACHE_TTL = 300000;
+/**
+ * Minimum API version required for adapter operations.
+ *
+ * This is set to API version 50.0 (Winter '21) which includes:
+ * - Enhanced Tooling API support for custom fields and validation rules
+ * - Improved SOQL query capabilities
+ * - ExecuteAnonymous improvements
+ */
+export declare const MINIMUM_API_VERSION = 50;
+/**
+ * Parses an API version string to a numeric value.
+ *
+ * @param version - Version string (e.g., "50.0", "v50.0", "50")
+ * @returns Numeric version or undefined if invalid
+ *
+ * @example
+ * ```typescript
+ * parseApiVersion('50.0');  // Returns 50.0
+ * parseApiVersion('v52.0'); // Returns 52.0
+ * parseApiVersion('invalid'); // Returns undefined
+ * ```
+ */
+export declare function parseApiVersion(version: string | undefined): number | undefined;
+/**
+ * Checks if an API version meets the minimum requirement.
+ *
+ * @param version - Version string or number to check
+ * @param minimum - Minimum required version (default: MINIMUM_API_VERSION)
+ * @returns true if version meets or exceeds minimum, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isApiVersionSupported('52.0');      // Returns true
+ * isApiVersionSupported('48.0');      // Returns false
+ * isApiVersionSupported('52.0', 55);  // Returns false
+ * ```
+ */
+export declare function isApiVersionSupported(version: string | number | undefined, minimum?: number): boolean;
+/**
+ * Asserts that an API version meets the minimum requirement.
+ *
+ * @param version - Version string or number to check
+ * @param operation - Operation name for error message
+ * @param minimum - Minimum required version (default: MINIMUM_API_VERSION)
+ * @throws Error if version is below minimum
+ *
+ * @example
+ * ```typescript
+ * assertApiVersion('52.0', 'queryCustomFields'); // No error
+ * assertApiVersion('48.0', 'queryCustomFields'); // Throws Error
+ * ```
+ */
+export declare function assertApiVersion(version: string | number | undefined, operation: string, minimum?: number): void;
+/**
+ * Logs a warning if the API version is below minimum.
+ *
+ * Unlike assertApiVersion, this doesn't throw an error but logs a warning
+ * to the provided logger. This is useful for adapters that should work
+ * with older API versions but may have degraded functionality.
+ *
+ * If no logger is provided, falls back to console.warn to ensure
+ * version warnings are always visible.
+ *
+ * @param version - Version string or number to check
+ * @param operation - Operation name for the warning message
+ * @param logger - Logger to use for the warning (falls back to console.warn)
+ * @param minimum - Minimum required version (default: MINIMUM_API_VERSION)
+ * @returns true if version is supported, false if warning was logged
+ *
+ * @example
+ * ```typescript
+ * warnApiVersion('48.0', 'RestApiAdapter', console); // Logs warning, returns false
+ * warnApiVersion('52.0', 'RestApiAdapter', console); // No warning, returns true
+ * warnApiVersion('48.0', 'RestApiAdapter');          // Logs to console.warn, returns false
+ * ```
+ */
+export declare function warnApiVersion(version: string | number | undefined, operation: string, logger?: Console, minimum?: number): boolean;
+/**
+ * Gets the cache TTL from config or environment.
+ *
+ * TTL priority (highest to lowest):
+ * 1. `configTtl` parameter (programmatic override)
+ * 2. `CUNEIFORM_CACHE_TTL` environment variable (in milliseconds)
+ * 3. `DEFAULT_CACHE_TTL` constant (300,000ms = 5 minutes)
+ *
+ * @param configTtl - Optional TTL from adapter config (in milliseconds)
+ * @returns TTL in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Use environment variable
+ * process.env.CUNEIFORM_CACHE_TTL = '60000'; // 1 minute
+ * const ttl = getCacheTtl(); // Returns 60000
+ *
+ * // Override with config
+ * const ttl = getCacheTtl(120000); // Returns 120000 (2 minutes)
+ * ```
+ */
+export declare function getCacheTtl(configTtl?: number): number;

package/lib/adapters/types.js

@@ -0,0 +1,169 @@
+/*
+ * 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 { SfError } from '@salesforce/core';
+export { createSuccessResult, createFailureResult } from '../models/service-result.js';
+// Re-export error codes
+export { AdapterErrorCodes, mapSalesforceError, ErrorCodeDescriptions } from './errors.js';
+/**
+ * Default cache TTL value (5 minutes in milliseconds).
+ *
+ * The 5-minute default balances freshness with performance:
+ * - Short enough to reflect metadata changes within a typical development session
+ * - Long enough to avoid redundant API calls during iterative operations
+ * - Configurable via `CUNEIFORM_CACHE_TTL` environment variable for different use cases
+ */
+export const DEFAULT_CACHE_TTL = 300_000;
+/**
+ * Minimum API version required for adapter operations.
+ *
+ * This is set to API version 50.0 (Winter '21) which includes:
+ * - Enhanced Tooling API support for custom fields and validation rules
+ * - Improved SOQL query capabilities
+ * - ExecuteAnonymous improvements
+ */
+export const MINIMUM_API_VERSION = 50.0;
+/**
+ * Parses an API version string to a numeric value.
+ *
+ * @param version - Version string (e.g., "50.0", "v50.0", "50")
+ * @returns Numeric version or undefined if invalid
+ *
+ * @example
+ * ```typescript
+ * parseApiVersion('50.0');  // Returns 50.0
+ * parseApiVersion('v52.0'); // Returns 52.0
+ * parseApiVersion('invalid'); // Returns undefined
+ * ```
+ */
+export function parseApiVersion(version) {
+    if (!version) {
+        return undefined;
+    }
+    // Remove leading 'v' if present
+    const cleanVersion = version.toLowerCase().startsWith('v') ? version.slice(1) : version;
+    const parsed = parseFloat(cleanVersion);
+    return isNaN(parsed) ? undefined : parsed;
+}
+/**
+ * Checks if an API version meets the minimum requirement.
+ *
+ * @param version - Version string or number to check
+ * @param minimum - Minimum required version (default: MINIMUM_API_VERSION)
+ * @returns true if version meets or exceeds minimum, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isApiVersionSupported('52.0');      // Returns true
+ * isApiVersionSupported('48.0');      // Returns false
+ * isApiVersionSupported('52.0', 55);  // Returns false
+ * ```
+ */
+export function isApiVersionSupported(version, minimum = MINIMUM_API_VERSION) {
+    const numericVersion = typeof version === 'number' ? version : parseApiVersion(version);
+    if (numericVersion === undefined) {
+        return false;
+    }
+    return numericVersion >= minimum;
+}
+/**
+ * Asserts that an API version meets the minimum requirement.
+ *
+ * @param version - Version string or number to check
+ * @param operation - Operation name for error message
+ * @param minimum - Minimum required version (default: MINIMUM_API_VERSION)
+ * @throws Error if version is below minimum
+ *
+ * @example
+ * ```typescript
+ * assertApiVersion('52.0', 'queryCustomFields'); // No error
+ * assertApiVersion('48.0', 'queryCustomFields'); // Throws Error
+ * ```
+ */
+export function assertApiVersion(version, operation, minimum = MINIMUM_API_VERSION) {
+    if (!isApiVersionSupported(version, minimum)) {
+        const versionStr = version ?? 'unknown';
+        throw new SfError(`API version ${versionStr} is below minimum required version ${minimum} for ${operation}. ` +
+            `Please upgrade to API version ${minimum} or higher.`, 'UnsupportedApiVersion');
+    }
+}
+/**
+ * Logs a warning if the API version is below minimum.
+ *
+ * Unlike assertApiVersion, this doesn't throw an error but logs a warning
+ * to the provided logger. This is useful for adapters that should work
+ * with older API versions but may have degraded functionality.
+ *
+ * If no logger is provided, falls back to console.warn to ensure
+ * version warnings are always visible.
+ *
+ * @param version - Version string or number to check
+ * @param operation - Operation name for the warning message
+ * @param logger - Logger to use for the warning (falls back to console.warn)
+ * @param minimum - Minimum required version (default: MINIMUM_API_VERSION)
+ * @returns true if version is supported, false if warning was logged
+ *
+ * @example
+ * ```typescript
+ * warnApiVersion('48.0', 'RestApiAdapter', console); // Logs warning, returns false
+ * warnApiVersion('52.0', 'RestApiAdapter', console); // No warning, returns true
+ * warnApiVersion('48.0', 'RestApiAdapter');          // Logs to console.warn, returns false
+ * ```
+ */
+export function warnApiVersion(version, operation, logger, minimum = MINIMUM_API_VERSION) {
+    if (!isApiVersionSupported(version, minimum)) {
+        const versionStr = version ?? 'unknown';
+        const message = `Warning: API version ${versionStr} is below recommended minimum ${minimum} for ${operation}. ` +
+            'Some features may not work as expected.';
+        // Use provided logger if available, otherwise fall back to console.warn
+        // to ensure version warnings are always visible
+        if (logger?.warn) {
+            logger.warn(message);
+        }
+        else {
+            // eslint-disable-next-line no-console -- Fallback when no logger provided
+            console.warn(message);
+        }
+        return false;
+    }
+    return true;
+}
+/**
+ * Gets the cache TTL from config or environment.
+ *
+ * TTL priority (highest to lowest):
+ * 1. `configTtl` parameter (programmatic override)
+ * 2. `CUNEIFORM_CACHE_TTL` environment variable (in milliseconds)
+ * 3. `DEFAULT_CACHE_TTL` constant (300,000ms = 5 minutes)
+ *
+ * @param configTtl - Optional TTL from adapter config (in milliseconds)
+ * @returns TTL in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Use environment variable
+ * process.env.CUNEIFORM_CACHE_TTL = '60000'; // 1 minute
+ * const ttl = getCacheTtl(); // Returns 60000
+ *
+ * // Override with config
+ * const ttl = getCacheTtl(120000); // Returns 120000 (2 minutes)
+ * ```
+ */
+export function getCacheTtl(configTtl) {
+    if (configTtl !== undefined) {
+        return configTtl;
+    }
+    const envTtl = process.env.CUNEIFORM_CACHE_TTL;
+    if (envTtl) {
+        const parsed = parseInt(envTtl, 10);
+        if (!isNaN(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return DEFAULT_CACHE_TTL;
+}
+//# sourceMappingURL=types.js.map

package/lib/adapters/types.js.map

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

package/lib/base/cuneiform-command.d.ts

@@ -0,0 +1,175 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { Messages, SfError } from '@salesforce/core';
+import type { Connection } from '@salesforce/core';
+import { type IConnectionFacade } 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';
+/**
+ * Connection context returned by {@link CuneiformCommand.initConnection}.
+ *
+ * Contains the connection facade and pre-built adapters that most commands need.
+ */
+export type ConnectionContext = {
+    /** The connection facade for the target org */
+    facade: IConnectionFacade;
+    /** SOQL query adapter wrapping the facade */
+    soqlAdapter: SoqlQueryAdapter;
+    /** REST API adapter wrapping the facade */
+    restAdapter: RestApiAdapter;
+    /** Tooling API adapter wrapping the facade */
+    toolingAdapter: ToolingApiAdapter;
+};
+/**
+ * Creates the standard adapter stack from a connection facade.
+ *
+ * Single source of truth for adapter instantiation. All commands, operations,
+ * and MCP tools should use this instead of constructing adapters inline.
+ *
+ * @param facade - The connection facade for the target org
+ * @returns Object containing all three adapter instances
+ */
+export declare function createAdapterStack(facade: IConnectionFacade): {
+    soqlAdapter: SoqlQueryAdapter;
+    restAdapter: RestApiAdapter;
+    toolingAdapter: ToolingApiAdapter;
+};
+/**
+ * Abstract base class for all Cuneiform CLI commands.
+ *
+ * Provides a shared access gate that validates the authenticated user has
+ * the required Cuneiform permission sets and that Global Profiling is enabled
+ * before allowing command execution.
+ *
+ * Subclasses call `this.enforceAccessGate(facade)` at the start of their
+ * `run()` method after obtaining the connection facade. Commands that should
+ * bypass the gate (e.g., `user details`, which IS the diagnostic tool) simply
+ * omit the `enforceAccessGate()` call.
+ *
+ * The `skipAccessGate` static property is used by the UX snapshot test
+ * harness to auto-stub the gate for non-access-gate test scenarios.
+ *
+ * @template T The command result type
+ *
+ * @example
+ * ```typescript
+ * export default class MyCommand extends CuneiformCommand<MyResult> {
+ *   public async run(): Promise<MyResult> {
+ *     const { flags } = await this.parse(MyCommand);
+ *     const { facade, soqlAdapter, restAdapter } = await this.initConnection(flags);
+ *
+ *     // Business logic follows — adapters and access gate already handled
+ *     const service = new MyService({ soqlAdapter, restAdapter });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class CuneiformCommand<T> extends SfCommand<T> {
+    /**
+     * Set to `true` in subclasses that should bypass the access gate.
+     * Example: `user details` is exempt because it IS the diagnostic tool.
+     */
+    protected static skipAccessGate: boolean;
+    /**
+     * Resolves an error code to an i18n message using a command-specific error code map.
+     *
+     * Looks up the error code in the provided map, retrieves the corresponding i18n
+     * message, and returns it. If the message contains a `%s` placeholder, interpolates
+     * the fallback string. Messages with `%d` placeholders return the fallback directly
+     * since numeric interpolation requires context the caller must provide.
+     *
+     * Returns the fallback directly when errorCode is undefined or not in the map.
+     *
+     * @param errorCodeMap - Command-specific mapping of error codes to message bundle keys
+     * @param errorCode - The error code from the operation result
+     * @param fallback - The pre-formatted message from the operation layer
+     * @param msgs - The command's Messages instance for i18n lookup
+     * @returns The resolved user-facing error message
+     */
+    protected static resolveErrorMessage(errorCodeMap: Record<string, string>, errorCode: string | undefined, fallback: string, msgs: Messages<string>): string;
+    /**
+     * Normalizes a multi-value string flag: splits on commas, trims whitespace, and
+     * deduplicates. Used by commands that accept comma-separated values in flags
+     * (e.g., `--request-ids`, `--definition-names`).
+     *
+     * @param raw - The raw flag value array from oclif flag parsing
+     * @param options - Optional configuration
+     * @param options.caseInsensitive - When true, deduplicates case-insensitively while preserving the casing of the first occurrence
+     * @returns Deduplicated array of trimmed values, or undefined if input is empty
+     */
+    protected static parseMultiValueFlag(raw: string[] | undefined, options?: {
+        caseInsensitive?: boolean;
+    }): string[] | undefined;
+    /**
+     * Resolves the user-facing error message for an access gate failure.
+     *
+     * Maps service error codes to message bundle keys for actionable
+     * error messages that guide the user toward resolution.
+     */
+    private static resolveAccessGateMessage;
+    /**
+     * Sanitizes JSON output by stripping stack traces and error causes.
+     *
+     * Prevents exposing Node.js stack traces and absolute filesystem paths
+     * in `--json` error output. Success JSON output is unaffected since it
+     * never contains `stack` or `cause` properties.
+     */
+    logJson(json: unknown): void;
+    /**
+     * Intercepts oclif parse errors to fix misleading "Try this" suggestions for
+     * boolean flags declared with `allowNo: true` (CLI-3379).
+     *
+     * When a user passes a value to a boolean flag (e.g., `--skip-empty false`),
+     * oclif rejects the value as an unexpected argument and upstream
+     * `SfCommandError.appendErrorSuggestions` produces a misleading suggestion
+     * like `--skip-empty "--skip-empty false"` — the result of two upstream bugs:
+     * (1) `k.input` is wrongly prepended to args; (2) the suggestion logic has no
+     * awareness of `--[no-]` boolean flags.
+     *
+     * This override pre-processes the raw parse-output token stream BEFORE
+     * delegating to `super.catch`. For each FlagToken→ArgToken pair where the
+     * flag is a boolean with `allowNo: true`, it always splices the ArgToken out
+     * of `error.parse.output.raw` (suppressing upstream's buggy suggestion), and
+     * — only when the arg is a recognized boolean literal (true/false/yes/no/1/0)
+     * — also pushes the corrected `--no-<flag>` or `--<flag>` onto `error.actions`.
+     *
+     * Unrecognized values (e.g., `--skip-empty bogus`) get the silent splice
+     * (no fabricated suggestion, no misleading upstream output). Non-boolean
+     * flags and booleans without `allowNo` are left untouched.
+     */
+    catch(error: Error | SfError): Promise<never>;
+    /**
+     * Enforces the Cuneiform profiling access gate.
+     *
+     * Validates that the authenticated user has:
+     * 1. Cuneiform for Salesforce installed in the org
+     * 2. Required permission sets assigned
+     * 3. Global Profiling enabled
+     *
+     * Throws an SfError with an actionable, user-friendly error message
+     * from the `cuneiform.access` message bundle if any check fails.
+     *
+     * @param facade - The connection facade for the target org
+     * @throws {SfError} If the user cannot use Cuneiform commands
+     */
+    enforceAccessGate(facade: IConnectionFacade): Promise<void>;
+    /**
+     * Initializes the connection facade and standard adapters for a command.
+     *
+     * Encapsulates the common 5-line boilerplate shared by 16 of 18 commands:
+     * get connection, create facade, enforce access gate, create adapters.
+     *
+     * Commands that bypass the access gate (e.g., `user details` with
+     * `skipAccessGate = true`) will skip the gate check automatically.
+     *
+     * @param flags - The parsed command flags containing target-org and api-version
+     * @returns Connection context with facade and pre-built adapters
+     * @throws {SfError} If the access gate check fails
+     */
+    protected initConnection(flags: {
+        'target-org': {
+            getConnection(apiVersion?: string): Connection;
+        };
+        'api-version'?: string;
+    }): Promise<ConnectionContext>;
+}