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

package/lib/mcp/tools/user-tools.js

@@ -0,0 +1,167 @@
+/*
+ * 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 { UserConfigurationService } from '../../services/UserConfigurationService.js';
+import { OrgInfoService } from '../../services/OrgInfoService.js';
+import { UserReadinessService } from '../../services/UserReadinessService.js';
+import { McpErrorCodes } from '../errors.js';
+import { createMcpError, serviceResultToMcp, extractErrorMessage } from './tool-factory.js';
+/**
+ * Handler for cuneiform_user_details tool invocation.
+ *
+ * Returns user identity, readiness, and org context directly from service data.
+ * Builds the MCP response inline rather than delegating to the command layer.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- SDK requires params arg; UserDetailsInput is empty
+export async function handleUserDetails(adapters, params) {
+    try {
+        const { facade, soql: soqlAdapter } = adapters;
+        const userReadinessService = new UserReadinessService({ soqlAdapter });
+        const orgInfoService = new OrgInfoService({ connectionFacade: facade, soqlAdapter });
+        // Get current user ID from connection identity with validation
+        const identity = await facade.identity();
+        const userId = identity.user_id;
+        if (!userId) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, 'Session expired or identity unavailable. Re-authenticate with the target org.');
+        }
+        // Fetch org identity, user info, and readiness in parallel
+        const [orgIdentityResult, userInfoResult, readinessResult] = await Promise.all([
+            orgInfoService.getOrgIdentity(),
+            userReadinessService.getUserInfo(userId),
+            userReadinessService.checkReadiness(userId),
+        ]);
+        // Handle user info failure
+        if (!userInfoResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to get user info: ${userInfoResult.message ?? 'Unknown error'}`);
+        }
+        // Handle readiness check failure
+        if (!readinessResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to check readiness: ${readinessResult.message ?? 'Unknown error'}`);
+        }
+        // Build warnings for partial failures
+        const warnings = [];
+        if (!orgIdentityResult.success) {
+            warnings.push(`Org identity unavailable: ${orgIdentityResult.message ?? 'Unknown error'}`);
+        }
+        const orgIdentity = orgIdentityResult.success ? orgIdentityResult.data : undefined;
+        const userInfo = userInfoResult.data;
+        const readiness = readinessResult.data;
+        // Build MCP response directly from service data (no command-layer dependency)
+        const result = {
+            orgContext: {
+                orgName: orgIdentity?.organizationName ?? null,
+                orgId: orgIdentity?.organizationId ?? null,
+                instanceUrl: facade.instanceUrl ?? null,
+                isSandbox: orgIdentity?.isSandbox ?? null,
+            },
+            user: {
+                id: userInfo.id,
+                username: userInfo.username,
+                email: userInfo.email,
+                profileName: userInfo.profileName,
+                roleName: userInfo.roleName,
+            },
+            readiness: {
+                isReady: readiness.isReady,
+                isCuneiformInstalled: readiness.isCuneiformInstalled,
+                permissionSets: {
+                    hasAllRequired: readiness.permissionSets.hasAllRequired,
+                    missingRequired: readiness.permissionSets.missingRequired,
+                    assignments: readiness.permissionSets.assignments,
+                },
+                configProfile: {
+                    isConfigured: readiness.configProfile.isConfigured,
+                    profileLabel: readiness.configProfile.profileLabel ?? null,
+                    apiOnlyProfilingEnabled: readiness.configProfile.isConfigured
+                        ? readiness.configProfile.apiOnlyProfilingEnabled ?? null
+                        : null,
+                },
+            },
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+        return serviceResultToMcp({
+            success: true,
+            data: result,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        });
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to get user details: ${extractErrorMessage(error, 'handleUserDetails')}`);
+    }
+}
+/**
+ * Handler for cuneiform_user_configure tool invocation.
+ *
+ * Includes a prerequisite guard that checks Cuneiform installation
+ * before attempting configuration.
+ *
+ * @param adapters - Session-scoped MCP adapters
+ * @param params - Validated input from MCP SDK
+ * @returns MCP CallToolResult
+ */
+export async function handleUserConfigure(adapters, params) {
+    try {
+        const { facade, soql: soqlAdapter, rest: restAdapter } = adapters;
+        const userReadinessService = new UserReadinessService({ soqlAdapter });
+        // Get current user ID from connection identity with validation
+        const identity = await facade.identity();
+        const userId = identity.user_id;
+        if (!userId) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, 'Session expired or identity unavailable. Re-authenticate with the target org.');
+        }
+        // Prerequisite guard: check Cuneiform is installed before configuring
+        const readinessResult = await userReadinessService.checkReadiness(userId);
+        if (!readinessResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to check prerequisites: ${readinessResult.message ?? 'Unknown error'}`);
+        }
+        if (!readinessResult.data.isCuneiformInstalled) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, 'Cuneiform for Salesforce is not installed in this org. ' +
+                'Install the package from AppExchange before configuring user access. ' +
+                'See: https://peernova.link/cli/configure');
+        }
+        const userConfigService = new UserConfigurationService({
+            soqlAdapter,
+            restApiAdapter: restAdapter,
+            userReadinessService,
+        });
+        // Execute configuration (with dry-run by default)
+        const configResult = await userConfigService.configure(userId, {
+            dryRun: params.dryRun,
+        });
+        if (!configResult.success) {
+            return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Configuration failed: ${configResult.message ?? 'Unknown error'}`);
+        }
+        // Map to command-level result for consistent response shape
+        const result = {
+            dryRun: params.dryRun,
+            actions: configResult.data.actions.map((action) => ({
+                type: action.type,
+                target: action.target,
+                targetLabel: action.targetLabel ?? action.target,
+                status: params.dryRun ? 'planned' : action.status,
+                message: action.message,
+            })),
+            summary: {
+                changesRequired: configResult.data.summary.changesRequired,
+                changesApplied: configResult.data.summary.changesApplied,
+                changesFailed: configResult.data.summary.changesFailed,
+            },
+        };
+        return serviceResultToMcp({
+            success: true,
+            data: result,
+        });
+    }
+    catch (error) {
+        return createMcpError(McpErrorCodes.TOOL_INVOCATION_FAILED, `Failed to configure user: ${extractErrorMessage(error, 'handleUserConfigure')}`);
+    }
+}
+//# sourceMappingURL=user-tools.js.map

package/lib/mcp/tools/user-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-tools.js","sourceRoot":"","sources":["../../../src/mcp/tools/user-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE5F;;;;;;;;;GASG;AACH,mHAAmH;AACnH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAqB,EAAE,MAAwB;IACrF,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC;QAE/C,MAAM,oBAAoB,GAAG,IAAI,oBAAoB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QACvE,MAAM,cAAc,GAAG,IAAI,cAAc,CAAC,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QAErF,+DAA+D;QAC/D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,+EAA+E,CAChF,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,MAAM,CAAC,iBAAiB,EAAE,cAAc,EAAE,eAAe,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC7E,cAAc,CAAC,cAAc,EAAE;YAC/B,oBAAoB,CAAC,WAAW,CAAC,MAAM,CAAC;YACxC,oBAAoB,CAAC,cAAc,CAAC,MAAM,CAAC;SAC5C,CAAC,CAAC;QAEH,2BAA2B;QAC3B,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,4BAA4B,cAAc,CAAC,OAAO,IAAI,eAAe,EAAE,CACxE,CAAC;QACJ,CAAC;QAED,iCAAiC;QACjC,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;YAC7B,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,8BAA8B,eAAe,CAAC,OAAO,IAAI,eAAe,EAAE,CAC3E,CAAC;QACJ,CAAC;QAED,sCAAsC;QACtC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,6BAA6B,iBAAiB,CAAC,OAAO,IAAI,eAAe,EAAE,CAAC,CAAC;QAC7F,CAAC;QAED,MAAM,WAAW,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QACnF,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC;QACrC,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,CAAC;QAEvC,8EAA8E;QAC9E,MAAM,MAAM,GAAG;YACb,UAAU,EAAE;gBACV,OAAO,EAAE,WAAW,EAAE,gBAAgB,IAAI,IAAI;gBAC9C,KAAK,EAAE,WAAW,EAAE,cAAc,IAAI,IAAI;gBAC1C,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI;gBACvC,SAAS,EAAE,WAAW,EAAE,SAAS,IAAI,IAAI;aAC1C;YACD,IAAI,EAAE;gBACJ,EAAE,EAAE,QAAQ,CAAC,EAAE;gBACf,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;aAC5B;YACD,SAAS,EAAE;gBACT,OAAO,EAAE,SAAS,CAAC,OAAO;gBAC1B,oBAAoB,EAAE,SAAS,CAAC,oBAAoB;gBACpD,cAAc,EAAE;oBACd,cAAc,EAAE,SAAS,CAAC,cAAc,CAAC,cAAc;oBACvD,eAAe,EAAE,SAAS,CAAC,cAAc,CAAC,eAAe;oBACzD,WAAW,EAAE,SAAS,CAAC,cAAc,CAAC,WAAW;iBAClD;gBACD,aAAa,EAAE;oBACb,YAAY,EAAE,SAAS,CAAC,aAAa,CAAC,YAAY;oBAClD,YAAY,EAAE,SAAS,CAAC,aAAa,CAAC,YAAY,IAAI,IAAI;oBAC1D,uBAAuB,EAAE,SAAS,CAAC,aAAa,CAAC,YAAY;wBAC3D,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,uBAAuB,IAAI,IAAI;wBACzD,CAAC,CAAC,IAAI;iBACT;aACF;YACD,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SACrD,CAAC;QAEF,OAAO,kBAAkB,CAAC;YACxB,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SACrD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,+BAA+B,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,CAAC,EAAE,CACjF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAqB,EAAE,MAA0B;IACzF,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC;QAElE,MAAM,oBAAoB,GAAG,IAAI,oBAAoB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QAEvE,+DAA+D;QAC/D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,+EAA+E,CAChF,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,MAAM,eAAe,GAAG,MAAM,oBAAoB,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAC1E,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;YAC7B,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,kCAAkC,eAAe,CAAC,OAAO,IAAI,eAAe,EAAE,CAC/E,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAC/C,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,yDAAyD;gBACvD,uEAAuE;gBACvE,0CAA0C,CAC7C,CAAC;QACJ,CAAC;QAED,MAAM,iBAAiB,GAAG,IAAI,wBAAwB,CAAC;YACrD,WAAW;YACX,cAAc,EAAE,WAAW;YAC3B,oBAAoB;SACrB,CAAC,CAAC;QAEH,kDAAkD;QAClD,MAAM,YAAY,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,MAAM,EAAE;YAC7D,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;YAC1B,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,yBAAyB,YAAY,CAAC,OAAO,IAAI,eAAe,EAAE,CACnE,CAAC;QACJ,CAAC;QAED,4DAA4D;QAC5D,MAAM,MAAM,GAAG;YACb,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAClD,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,MAAM;gBAChD,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM;gBACjD,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC,CAAC;YACH,OAAO,EAAE;gBACP,eAAe,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe;gBAC1D,cAAc,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc;gBACxD,aAAa,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa;aACvD;SACF,CAAC;QAEF,OAAO,kBAAkB,CAAC;YACxB,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,MAAM;SACb,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,cAAc,CACnB,aAAa,CAAC,sBAAsB,EACpC,6BAA6B,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,CAAC,EAAE,CACjF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/lib/models/cascade-skip-accumulator.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared accumulator for cascade-mode skip tracking in `DefinitionCreateOperation`.
+ *
+ * When `--method full` orchestrates multiple input builders (record-type, outcome),
+ * per-object "skipping" warnings would be false: the object survives the run with
+ * other variants. The cascade caller allocates this accumulator and passes it down
+ * to the empty-result branches of each builder. Builders push the skipped object's
+ * name into the relevant bucket instead of pushing a per-object warning. The cascade
+ * caller then emits at most one aggregated summary warning after both builders run.
+ *
+ * Standalone callers (`--method recordtype`, `--method outcome`) pass nothing — per-object
+ * warning behavior is unchanged at line 910 (RT) and line 1021 (outcome) of their
+ * respective files.
+ *
+ * Presence/absence of the accumulator IS the caller-context signal — no enum needed.
+ *
+ * CLI-3611: `noOutcomeField` bucket removed. In `--method full`, outcome support is
+ * limited to Opportunity/Case/Lead by Salesforce platform design. Silently skipping
+ * objects without outcome fields is expected behavior — emitting a warning implies
+ * something went wrong, which is misleading.
+ */
+export type CascadeSkipAccumulator = {
+    /** Object names where `RecordTypeService` returned zero record types (empty-result branch). */
+    noRecordTypes: string[];
+};

package/lib/models/cascade-skip-accumulator.js

@@ -0,0 +1,9 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=cascade-skip-accumulator.js.map

package/lib/models/cascade-skip-accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade-skip-accumulator.js","sourceRoot":"","sources":["../../src/models/cascade-skip-accumulator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/lib/models/date-literal.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Date literal support for profiling definition creation.
+ *
+ * Replaces the year-range model with ISV-compatible date literal segmentation.
+ * Definitions become rolling windows that stay relevant without recreation.
+ *
+ * The 14 supported literals match the ISV DateLiteral.cls constants exactly.
+ * See docs/knowledge/salesforce/date-literals.md for full reference.
+ */
+import type { ExpressionLine } from '../services/DefinitionFieldGenerationService.js';
+/**
+ * The 52 date literals supported by the ISV DateLiteral.cls (after CLI-3419).
+ * These are the ONLY literals the CLI should generate — they correspond 1:1
+ * to the constants in the ISV product's DateLiteral class.
+ *
+ * Pre-CLI-3419 vocabulary was 14 entries (year-tier cap of 4 + 4 base
+ * non-year-tier + 2 span). CLI-3419 raises the cap to 10 across all
+ * non-span tiers, extending the cascade vocabulary to N_X_AGO:2..9 for
+ * day/week/month/quarter and N_YEARS_AGO:4..9 for year.
+ */
+export declare const SUPPORTED_DATE_LITERALS: readonly ["TODAY", "YESTERDAY", "N_DAYS_AGO:2", "N_DAYS_AGO:3", "N_DAYS_AGO:4", "N_DAYS_AGO:5", "N_DAYS_AGO:6", "N_DAYS_AGO:7", "N_DAYS_AGO:8", "N_DAYS_AGO:9", "THIS_WEEK", "LAST_WEEK", "N_WEEKS_AGO:2", "N_WEEKS_AGO:3", "N_WEEKS_AGO:4", "N_WEEKS_AGO:5", "N_WEEKS_AGO:6", "N_WEEKS_AGO:7", "N_WEEKS_AGO:8", "N_WEEKS_AGO:9", "THIS_MONTH", "LAST_MONTH", "N_MONTHS_AGO:2", "N_MONTHS_AGO:3", "N_MONTHS_AGO:4", "N_MONTHS_AGO:5", "N_MONTHS_AGO:6", "N_MONTHS_AGO:7", "N_MONTHS_AGO:8", "N_MONTHS_AGO:9", "THIS_QUARTER", "LAST_QUARTER", "N_QUARTERS_AGO:2", "N_QUARTERS_AGO:3", "N_QUARTERS_AGO:4", "N_QUARTERS_AGO:5", "N_QUARTERS_AGO:6", "N_QUARTERS_AGO:7", "N_QUARTERS_AGO:8", "N_QUARTERS_AGO:9", "THIS_YEAR", "LAST_YEAR", "N_YEARS_AGO:2", "N_YEARS_AGO:3", "N_YEARS_AGO:4", "N_YEARS_AGO:5", "N_YEARS_AGO:6", "N_YEARS_AGO:7", "N_YEARS_AGO:8", "N_YEARS_AGO:9", "LAST_N_YEARS:2", "LAST_N_YEARS:3"];
+/** Type representing any supported date literal value */
+export type SupportedDateLiteral = (typeof SUPPORTED_DATE_LITERALS)[number];
+/**
+ * Customer-facing labels for each date literal.
+ * Used in definition names, descriptions, and time category display.
+ *
+ * Word-form convention for N≥2 mirrors the existing year-tier labels
+ * ("Two Years Ago", "Three Years Ago") — see CLI-3419 Decision #3.
+ */
+export declare const DATE_LITERAL_LABELS: Record<SupportedDateLiteral, string>;
+/**
+ * Date literal tier classification.
+ *
+ * Each tier determines the maximum allowed depth for cascading. After
+ * CLI-3419, non-span tiers cascade across offsets 0..9 using the native
+ * SOQL N_X_AGO:n literals — definitions stay rolling:
+ * - year:    THIS_YEAR → LAST_YEAR → N_YEARS_AGO:2..9 (10 entries)
+ * - quarter: THIS_QUARTER → LAST_QUARTER → N_QUARTERS_AGO:2..9 (10 entries)
+ * - month:   THIS_MONTH → LAST_MONTH → N_MONTHS_AGO:2..9 (10 entries)
+ * - week:    THIS_WEEK → LAST_WEEK → N_WEEKS_AGO:2..9 (10 entries)
+ * - day:     TODAY → YESTERDAY → N_DAYS_AGO:2..9 (10 entries)
+ * - span:    depth 0 only (LAST_N_YEARS:2, LAST_N_YEARS:3 combine multiple years)
+ */
+export type DateLiteralTier = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'span';
+/** Maps each literal to its tier */
+export declare const LITERAL_TIERS: Record<SupportedDateLiteral, DateLiteralTier>;
+/**
+ * Maximum cascade depth per tier — interpreted as max absolute offset from
+ * the current period plus one (offsets 0..MAX-1 are valid).
+ *
+ * CLI-3419 raised the cap from 4 (year-tier only) to 10 across all non-span
+ * tiers. The cascade vocabulary now covers offsets 0..9 — labels "This X"
+ * through "Nine X Ago" — at every non-span tier. Span literals
+ * (LAST_N_YEARS:2/3) stay at depth 1 because they already aggregate multiple
+ * periods (AC4).
+ */
+export declare const TIER_MAX_DEPTH: Record<DateLiteralTier, number>;
+/**
+ * Depth cascade arrays per literal.
+ *
+ * Starting from a given literal at depth 0, each subsequent depth level
+ * adds the next literal in the cascade. Cascades always move backward in time.
+ *
+ * Cap interpretation (CLI-3419): cap=10 means max absolute offset is 9.
+ * Each base's cascade contains the literals from its own offset down to the
+ * tier max. E.g., LAST_QUARTER (offset 1) cascade has 9 entries
+ * (offsets 1..9); N_QUARTERS_AGO:9 cascade has 1 entry.
+ *
+ * Examples:
+ * - THIS_YEAR with depth 3 → [THIS_YEAR, LAST_YEAR, N_YEARS_AGO:2]
+ * - THIS_QUARTER with depth 4 → [THIS_QUARTER, LAST_QUARTER, N_QUARTERS_AGO:2, N_QUARTERS_AGO:3]
+ */
+export declare const LITERAL_CASCADES: Record<SupportedDateLiteral, readonly SupportedDateLiteral[]>;
+/**
+ * A single entry in a resolved date literal range.
+ * Analogous to ComparativeYearEntry in the year-range model.
+ */
+export type DateLiteralEntry = {
+    /** The date literal value (e.g., 'THIS_YEAR', 'LAST_QUARTER') */
+    readonly literal: SupportedDateLiteral;
+    /** Customer-facing label (e.g., 'This Year', 'Last Quarter') */
+    readonly label: string;
+};
+/**
+ * A resolved date literal range for profiling definitions.
+ * Analogous to YearRange in the year-range model.
+ *
+ * Contains the ordered list of date literal entries derived from user input
+ * (--date-literal flag + --depth flag).
+ */
+export type DateLiteralRange = {
+    /** Ordered list of date literal entries (most recent first) */
+    readonly entries: readonly DateLiteralEntry[];
+    /** The date field to filter on (default: CreatedDate) */
+    readonly dateField: string;
+};
+/**
+ * Raw flag inputs for date literal range resolution.
+ */
+export type DateLiteralInput = {
+    /** The base date literal (e.g., 'THIS_YEAR') */
+    dateLiteral: string;
+    /** Number of periods to cascade (counting back from base) */
+    depth?: number;
+    /** The date field to filter on (default: CreatedDate) */
+    dateField?: string;
+};
+/**
+ * Validates a date literal value against the ISV-supported set.
+ *
+ * @param value - The date literal string to validate
+ * @returns undefined if valid, error message string if invalid
+ */
+export declare function validateDateLiteral(value: string): string | undefined;
+/**
+ * Resolves CLI flag inputs into a validated DateLiteralRange.
+ *
+ * @param input - Raw flag inputs
+ * @returns Resolved DateLiteralRange
+ * @throws Error if inputs are invalid
+ */
+export declare function resolveDateLiteralRange(input: DateLiteralInput): DateLiteralRange;
+/**
+ * Returns the customer-facing label for a date literal.
+ *
+ * @param literal - A supported date literal value
+ * @returns The label string, or the raw literal if not found
+ */
+export declare function getDateLiteralLabel(literal: string): string;
+/**
+ * Customer-facing labels for known date-field API names.
+ * Used by humanizeDateField() to render filter labels and description text.
+ */
+export declare const DATE_FIELD_LABELS: Readonly<Record<string, string>>;
+/**
+ * Converts a date-field API name into a customer-facing label.
+ *
+ * Examples:
+ * - `humanizeDateField('CreatedDate')` returns `'Created Date'`
+ * - `humanizeDateField('LastModifiedDate')` returns `'Last Modified Date'`
+ * - `humanizeDateField('SomeCustomDate__c')` returns `'Some Custom Date'`
+ * - `humanizeDateField('')` returns `''`
+ *
+ * Known field names return their canonical label from DATE_FIELD_LABELS.
+ * Unknown PascalCase identifiers are split into space-separated words
+ * with custom-field `__c` suffix stripped. Falsy input is returned
+ * as-is so caller-side `label ? ... : dateField` truthy guards continue
+ * to work unchanged.
+ *
+ * @param dateField - The date-field API name (e.g., 'CreatedDate')
+ * @returns The customer-facing label
+ */
+export declare function humanizeDateField(dateField: string): string;
+/**
+ * Maps each date literal to its `$Constant.*` display value for the expression builder.
+ * These are the values that `fsc_expressionBuilder3` renders in the Value field.
+ *
+ * Naming mirrors the existing year-tier convention ($Constant.TwoYearsAgo,
+ * $Constant.ThreeYearsAgo) — CLI-3419 extends to all non-span tiers.
+ */
+export declare const DATE_LITERAL_CONSTANTS: Record<SupportedDateLiteral, string>;
+/**
+ * Builds an ISV-compatible filterJson string for date literal filtering.
+ *
+ * Produces the full expression builder JSON schema that `fsc_expressionBuilder3` expects,
+ * including all 12 required fields per expression line. The `parameter` field uses `$Constant.*`
+ * display values and `parameterValue` / `dateLiteral` use the SOQL literal.
+ *
+ * The outer envelope (hasFilters, setA) is required by ProfilingDefinitionApiService.resolveFilterClause()
+ * to enable WHERE clause filtering. setA.json must be an object (not a string) — the API
+ * does JSON.serialize() on it.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
+ * @param dateLiteral - The date literal value (e.g., 'THIS_YEAR', 'N_YEARS_AGO:2')
+ * @param objectName - The Salesforce object API name (e.g., 'Account', 'Lead'). Defaults to empty string for backward compatibility.
+ * @param objectLabel - The Salesforce object label (e.g., 'Account', 'Lead'). Defaults to objectName.
+ * @returns JSON string compatible with GlobalProfilingService.createProfilingDefinition()
+ */
+export declare function buildDateLiteralFilterJson(dateField: string, dateLiteral: string, objectName?: string, objectLabel?: string): string;
+/**
+ * Builds an ISV-compatible filterJson string for date-literal comparative definitions.
+ * Creates SetA (primary period) and SetB (prior period), both using SOQL date literals.
+ *
+ * Used when method='comparative' with a date literal that has a prior period in its cascade.
+ * The prior literal is derived from LITERAL_CASCADES[setALiteral][1] by the caller.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
+ * @param setALiteral - The primary (current) date literal for SetA
+ * @param setBLiteral - The prior period date literal for SetB
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters, setA, and setB
+ */
+export declare function buildComparativeDateLiteralFilterJson(dateField: string, setALiteral: SupportedDateLiteral, setBLiteral: SupportedDateLiteral, objectName?: string, objectLabel?: string): string;
+/**
+ * Formats a year boundary as an ISO 8601 UTC midnight string.
+ * Used for explicit date range expressions in year-based comparisons.
+ */
+export declare function yearBoundaryISO(year: number): string;
+/**
+ * Formats a year boundary as a human-readable display string (M/d/yyyy, h:mm a).
+ * Used for the `parameter` display value in expression builder JSON.
+ */
+export declare function yearBoundaryDisplay(year: number): string;
+/**
+ * Builds an ISV-compatible filterJson string for a single year (SetA only, no SetB).
+ * Used for historical definitions scoped to a specific year via --year flag.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
+ * @param year - The target year
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters and setA (no setB)
+ */
+export declare function buildHistoricalYearFilterJson(dateField: string, year: number, objectName?: string, objectLabel?: string): string;
+/**
+ * Builds an ISV-compatible filterJson string for year-based comparative definitions.
+ * Creates SetA (target year) and SetB (prior year or all prior years) using explicit
+ * date range expressions (>= start AND < end), not date literals.
+ *
+ * This approach supports arbitrary years with no lookback limitation.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
+ * @param year - The target year for SetA
+ * @param usePrior - When true, SetB is all records before the target year. When false, SetB is the prior year.
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters, setA, and setB
+ */
+export declare function buildComparativeYearFilterJson(dateField: string, year: number, usePrior: boolean, objectName?: string, objectLabel?: string): string;
+/**
+ * Builds an ISV-compatible filterJson string for the lifetime-vs-X comparative variant.
+ *
+ * SetA is unfiltered (empty expressions array — represents "all records / lifetime"); SetB carries the supplied
+ * secondary filter. This is the inverse of `buildComparativeYearFilterJson`, where SetA is the year-scoped set and
+ * SetB is the prior-year (or unbounded) set.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
+ * @param secondary - The secondary filter spec applied to SetB. Accepts `{ kind: 'year', year }` for a year-bounded SetB,
+ * or `{ kind: 'dateLiteral', literal }` for a SOQL date-literal SetB.
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label (defaults to objectName)
+ * @returns JSON string with hasFilters, setA (empty), and setB (filtered)
+ */
+export declare function buildLifetimeComparativeFilterJson(dateField: string, secondary: {
+    kind: 'year';
+    year: number;
+} | {
+    kind: 'dateLiteral';
+    literal: SupportedDateLiteral;
+}, objectName?: string, objectLabel?: string): string;
+/**
+ * Single expression-builder JSON line representing a `RecordTypeId = <rtId>` condition.
+ * Matches the 11-field schema (12 with optional `id`) that `fsc_expressionBuilder3` expects,
+ * used when scoping a profiling definition to a specific record type.
+ *
+ * @param rtId - The RecordType Salesforce ID (15 or 18 chars)
+ * @param objectName - The Salesforce object API name (e.g., 'Case')
+ * @param objectLabel - The Salesforce object label (defaults to objectName)
+ * @returns Expression line ready to embed in `setA.json.expressions` / `setB.json.expressions`
+ */
+export declare function buildRecordTypeFilterExpression(rtId: string, objectName?: string, objectLabel?: string): ExpressionLine;
+/**
+ * Composes a RecordTypeId scope filter into an existing ISV filterJson envelope so the server
+ * restricts profiling SOQL to a single record type. CLI-3834: `--method recordtype` was writing
+ * the RT name to `Prop_SegmentCategory__c` (label only) without populating the filter/RT-scope
+ * fields. This helper appends the RT condition to `setA` (and `setB` when present) preserving
+ * the source `logicType` (defaults to `'AND'` for the legacy canonical builders).
+ *
+ * When `filterJson` is `undefined`/`null` (Lifetime path), returns a fresh envelope with
+ * `setA.json.expressions = [rtExpression]` and `hasFilters: true`.
+ *
+ * @param filterJson - Existing filterJson string from a `buildXxxFilterJson` helper, or undefined
+ * @param rtId - The RecordType Salesforce ID
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label (defaults to objectName)
+ * @returns Updated filterJson string carrying the RT scope on every existing filter side
+ */
+export declare function composeRecordTypeFilter(filterJson: string | undefined, rtId: string, objectName?: string, objectLabel?: string): string;