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

package/lib/models/user-details-types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Shared types for the `sf cuneiform user details` command result.
+ *
+ * Extracted from the command file so that display formatters (utils layer)
+ * can consume these types without importing from the commands layer.
+ *
+ * @module models/user-details-types
+ */
+/**
+ * Org context information for JSON output.
+ */
+export type OrgContextResult = {
+    /** Organization name */
+    orgName: string;
+    /** 18-character Organization ID */
+    orgId: string;
+    /** Instance URL (e.g., https://acme.my.salesforce.com) */
+    instanceUrl: string;
+    /** Whether this is a sandbox org */
+    isSandbox: boolean;
+    /** Organization type (e.g., Developer Edition, Enterprise Edition) */
+    orgType: string;
+};
+/**
+ * User identity information for JSON output.
+ */
+export type UserIdentityResult = {
+    /** Salesforce User ID */
+    id: string;
+    /** User's login username */
+    username: string;
+    /** User's email address */
+    email: string;
+    /** Name of the user's assigned Profile */
+    profileName: string;
+    /** Name of the user's assigned Role (null if not assigned) */
+    roleName: string | null;
+};
+/**
+ * Prerequisites check result.
+ */
+export type PrerequisitesResult = {
+    /** Whether Cuneiform for Salesforce is installed in the org */
+    cuneiformInstalled: boolean;
+    /** Whether the Admin permission set is assigned */
+    adminAccessAssigned: boolean;
+    /** Whether all prerequisites passed */
+    allPassed: boolean;
+};
+/**
+ * Permission set assignment status for JSON output.
+ */
+export type PermissionSetAssignmentResult = {
+    /** Full API name with namespace (e.g., pnova__Cuneiform_for_CRM_PRO_Administrative_User) */
+    apiName: string;
+    /** Human-readable label (e.g., Cuneiform for CRM (Pro): Administrative User) */
+    label: string;
+    /** Whether the permission set is assigned */
+    isAssigned: boolean;
+    /** Whether this permission set is required for profiling */
+    isRequired: boolean;
+};
+/**
+ * Configuration profile status for JSON output.
+ */
+export type ConfigProfileResult = {
+    /** Whether a configuration profile is active */
+    isConfigured: boolean;
+    /** Label of the active profile (null if not configured) */
+    profileLabel: string | null;
+    /** Whether API-only profiling is enabled (null if not configured) */
+    apiOnlyProfilingEnabled: boolean | null;
+    /** Whether CLI self-provisioning is enabled (null if not configured) */
+    selfRegistrationEnabled: boolean | null;
+};
+/**
+ * Readiness assessment combining permission sets and config profile.
+ */
+export type ReadinessResult = {
+    /** Whether the user is ready to use Cuneiform */
+    isReady: boolean;
+    /** Permission set assignment statuses */
+    permissionSets: PermissionSetAssignmentResult[];
+    /** Configuration profile status */
+    configProfile: ConfigProfileResult;
+};
+/**
+ * Structured resolution guidance item with persona routing.
+ */
+export type ResolutionGuidanceItem = {
+    /** What the issue is */
+    issue: string;
+    /** Itemized detail lines (rendered as indented bullets) */
+    detail?: string[];
+    /** What action to take */
+    action: string;
+    /** Who should take the action */
+    persona: 'admin' | 'self';
+};
+/**
+ * Individual configuration action result.
+ */
+export type ConfigurationActionResult = {
+    /** Type of action */
+    type: 'assignPermissionSet' | 'enableApiOnlyProfiling' | 'unassignPermissionSet' | 'disableApiOnlyProfiling';
+    /** Target identifier (permission set name or profile name) */
+    target: string;
+    /** Human-readable label for the target */
+    targetLabel: string;
+    /** Action status */
+    status: 'applied' | 'skipped' | 'failed' | 'planned';
+    /** Status message */
+    message?: string;
+};
+/**
+ * Snapshot of the user's configuration state captured before --configure actions
+ * were planned or applied. Narrowed from the service-level ConfigurationState —
+ * userId and username are intentionally omitted because they are already exposed
+ * via UserDetailsResult.user. Surfaces the CLI-3418 readiness-threading contract
+ * into the JSON output so consumers can verify that the readiness display and
+ * configure previousState derive from a single readiness snapshot.
+ */
+export type ConfigurationPreviousState = {
+    /** Whether all required permission sets were assigned at snapshot time */
+    hasRequiredPermissionSets: boolean;
+    /** Names of missing permission sets at snapshot time (empty if all assigned) */
+    missingPermissionSets: string[];
+    /** Whether API-only profiling was enabled at snapshot time */
+    apiOnlyProfilingEnabled: boolean;
+    /** Active profile developer name at snapshot time (if configured) */
+    profileDeveloperName?: string;
+};
+/**
+ * Configuration result (only present when --configure is used).
+ */
+export type ConfigurationResult = {
+    /** Whether this was a dry-run (no changes applied) */
+    dryRun: boolean;
+    /**
+     * Configuration state before actions were planned or applied. Surfaces the
+     * CLI-3418 readiness-threading contract: this snapshot is built from the same
+     * readiness data that drives the readiness display, so consumers can verify
+     * agreement between the two surfaces.
+     */
+    previousState: ConfigurationPreviousState;
+    /** Actions taken or planned */
+    actions: ConfigurationActionResult[];
+    /** Summary statistics */
+    summary: {
+        /** Number of changes required */
+        changesRequired: number;
+        /** Number of changes successfully applied */
+        changesApplied: number;
+        /** Number of changes that failed */
+        changesFailed: number;
+    };
+    /** Deployment job ID for tracking (if API-only profiling was enabled) */
+    deploymentJobId?: string;
+};
+/**
+ * Contextual links for the user.
+ */
+export type LinksResult = {
+    /** URL to verification documentation */
+    documentation?: string;
+    /** URL to installation guide */
+    installationGuide?: string;
+};
+/**
+ * Unified command result type for JSON output.
+ * Used by both diagnostic (default) and configure (--configure) modes.
+ */
+export type UserDetailsResult = {
+    /** Org context information */
+    orgContext: OrgContextResult;
+    /** User identity information */
+    user: UserIdentityResult;
+    /** Prerequisites check result */
+    prerequisites: PrerequisitesResult;
+    /** Readiness assessment */
+    readiness: ReadinessResult;
+    /** Structured resolution guidance (empty if ready) */
+    resolutionGuidance: ResolutionGuidanceItem[];
+    /** Configuration result (only present when --configure is used) */
+    configuration?: ConfigurationResult;
+    /** Contextual links */
+    links: LinksResult;
+};

package/lib/models/user-details-types.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=user-details-types.js.map

package/lib/models/user-details-types.js.map

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

package/lib/models/year-range.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Represents a single comparative year entry within a year range.
+ *
+ * Each entry defines what "Set A" and "Set B" are for a comparative definition:
+ * - Bounded: year vs year-1 (e.g., 2026 vs 2025)
+ * - Unbounded: year vs all prior records (e.g., 2023 vs Prior)
+ */
+export type ComparativeYearEntry = {
+    /** The target year (Set A: records created in this year) */
+    readonly year: number;
+    /** When true, Set B is "all records before year" instead of "year - 1" */
+    readonly unbounded: boolean;
+};
+/**
+ * A resolved year range for comparative profiling definitions.
+ *
+ * Contains the ordered list of comparative year entries derived from user input
+ * (flags like --year, --depth, --from, --to, --use-prior).
+ *
+ * Default behavior:
+ * - comparative method: depth=1 (current year only)
+ * - full method: depth=3 (current year + 2 prior years)
+ * - --use-prior replaces the last entry with an unbounded comparison
+ */
+export type YearRange = {
+    /** Ordered list of comparative years (most recent first) */
+    readonly entries: readonly ComparativeYearEntry[];
+};
+/**
+ * Raw flag inputs for year range resolution.
+ * Mirrors the CLI flags before validation and resolution.
+ */
+export type YearRangeInput = {
+    /** Single year or comma-delimited years (e.g., 2026 or "2026,2025,2024") */
+    year?: number | number[];
+    /** Number of years to include (counting back from year) */
+    depth?: number;
+    /** Start year of explicit range (inclusive) */
+    from?: number;
+    /** End year of explicit range (inclusive) */
+    to?: number;
+    /** Replace last comparison with unbounded "vs Prior" */
+    usePrior?: boolean;
+    /** Profiling method — determines default depth */
+    method?: 'metadata' | 'historical' | 'comparative' | 'recordtype' | 'outcome' | 'full';
+};
+/**
+ * Resolves CLI flag inputs into a validated YearRange.
+ *
+ * Resolution priority:
+ * 1. --from/--to: explicit range (inclusive, most recent first)
+ * 2. --year (array): comma-delimited years
+ * 3. --year + --depth: single year with lookback depth
+ * 4. --year alone: single year with method-default depth
+ * 5. No flags: current year with method-default depth
+ *
+ * @param input - Raw flag inputs
+ * @returns Resolved YearRange
+ * @throws Error if inputs are invalid or conflicting
+ */
+export declare function resolveYearRange(input?: YearRangeInput): YearRange;
+/**
+ * Returns the default depth for a given profiling method.
+ *
+ * - comparative: 1 (current year only)
+ * - outcome: 1 (no year dimension — uses filterJson)
+ * - full: 3 (current year + 2 prior)
+ * - recordtype: 3 (same as full)
+ */
+export declare function getDefaultDepth(method: string): number;
+/**
+ * Formats a ComparativeYearEntry as a human-readable string.
+ *
+ * @example
+ * formatYearEntry({ year: 2026, unbounded: false }) // "2026 vs 2025"
+ * formatYearEntry({ year: 2023, unbounded: true })  // "2023 vs Prior"
+ */
+export declare function formatYearEntry(entry: ComparativeYearEntry): string;

package/lib/models/year-range.js

@@ -0,0 +1,153 @@
+/*
+ * 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.
+ */
+/** Maximum allowed depth to prevent excessive definition creation */
+const MAX_DEPTH = 10;
+/** Minimum valid year */
+const MIN_YEAR = 2000;
+/** Maximum valid year */
+const MAX_YEAR = 2050;
+/**
+ * Resolves CLI flag inputs into a validated YearRange.
+ *
+ * Resolution priority:
+ * 1. --from/--to: explicit range (inclusive, most recent first)
+ * 2. --year (array): comma-delimited years
+ * 3. --year + --depth: single year with lookback depth
+ * 4. --year alone: single year with method-default depth
+ * 5. No flags: current year with method-default depth
+ *
+ * @param input - Raw flag inputs
+ * @returns Resolved YearRange
+ * @throws Error if inputs are invalid or conflicting
+ */
+export function resolveYearRange(input = {}) {
+    const method = input.method ?? 'comparative';
+    // Metadata has no time dimension — skip year range resolution
+    if (method === 'metadata') {
+        return { entries: [] };
+    }
+    const currentYear = new Date().getFullYear();
+    // Resolution path 1: --from/--to explicit range
+    if (input.from !== undefined || input.to !== undefined) {
+        return resolveFromToRange(input, currentYear);
+    }
+    // Resolution path 2: --year as array (comma-delimited)
+    if (Array.isArray(input.year)) {
+        return resolveYearArray(input.year, input.usePrior);
+    }
+    // Resolution path 3/4/5: --year + --depth or defaults
+    const baseYear = input.year ?? currentYear;
+    const defaultDepth = getDefaultDepth(method);
+    const depth = input.depth ?? defaultDepth;
+    validateYear(baseYear);
+    validateDepth(depth);
+    const entries = [];
+    for (let i = 0; i < depth; i++) {
+        const year = baseYear - i;
+        const isLast = i === depth - 1;
+        entries.push({
+            year,
+            unbounded: isLast && (input.usePrior ?? false),
+        });
+    }
+    return { entries };
+}
+/**
+ * Returns the default depth for a given profiling method.
+ *
+ * - comparative: 1 (current year only)
+ * - outcome: 1 (no year dimension — uses filterJson)
+ * - full: 3 (current year + 2 prior)
+ * - recordtype: 3 (same as full)
+ */
+export function getDefaultDepth(method) {
+    switch (method) {
+        case 'comparative':
+        case 'outcome':
+            return 1;
+        case 'full':
+        case 'recordtype':
+            return 3;
+        default:
+            return 1;
+    }
+}
+/**
+ * Formats a ComparativeYearEntry as a human-readable string.
+ *
+ * @example
+ * formatYearEntry({ year: 2026, unbounded: false }) // "2026 vs 2025"
+ * formatYearEntry({ year: 2023, unbounded: true })  // "2023 vs Prior"
+ */
+export function formatYearEntry(entry) {
+    if (entry.unbounded) {
+        return `${entry.year} vs Prior`;
+    }
+    return `${entry.year} vs ${entry.year - 1}`;
+}
+// ── Internal helpers ──────────────────────────────────────────────────
+function resolveFromToRange(input, currentYear) {
+    const from = input.from ?? MIN_YEAR;
+    const to = input.to ?? currentYear;
+    validateYear(from);
+    validateYear(to);
+    if (from > to) {
+        throw new Error(`--from (${from}) cannot be greater than --to (${to})`);
+    }
+    const depth = to - from + 1;
+    if (depth > MAX_DEPTH) {
+        throw new Error(`Year range spans ${depth} years, exceeding maximum of ${MAX_DEPTH}`);
+    }
+    if (input.depth !== undefined) {
+        throw new Error('--depth cannot be combined with --from/--to');
+    }
+    const entries = [];
+    for (let year = to; year >= from; year--) {
+        const isLast = year === from;
+        entries.push({
+            year,
+            unbounded: isLast && (input.usePrior ?? false),
+        });
+    }
+    return { entries };
+}
+function resolveYearArray(years, usePrior) {
+    if (years.length === 0) {
+        throw new Error('--year requires at least one year value');
+    }
+    if (years.length > MAX_DEPTH) {
+        throw new Error(`--year specifies ${years.length} years, exceeding maximum of ${MAX_DEPTH}`);
+    }
+    for (const y of years) {
+        validateYear(y);
+    }
+    // Sort descending (most recent first)
+    const sorted = [...years].sort((a, b) => b - a);
+    const entries = sorted.map((year, i) => ({
+        year,
+        unbounded: i === sorted.length - 1 && (usePrior ?? false),
+    }));
+    return { entries };
+}
+function validateYear(year) {
+    if (!Number.isInteger(year)) {
+        throw new Error(`Year must be an integer, got ${year}`);
+    }
+    if (year < MIN_YEAR || year > MAX_YEAR) {
+        throw new Error(`Year ${year} is out of range (${MIN_YEAR}-${MAX_YEAR})`);
+    }
+}
+function validateDepth(depth) {
+    if (!Number.isInteger(depth) || depth < 1) {
+        throw new Error(`--depth must be a positive integer, got ${depth}`);
+    }
+    if (depth > MAX_DEPTH) {
+        throw new Error(`--depth ${depth} exceeds maximum of ${MAX_DEPTH}`);
+    }
+}
+//# sourceMappingURL=year-range.js.map

package/lib/models/year-range.js.map

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

package/lib/operations/CompatibilityCheckOperation.d.ts

@@ -0,0 +1,62 @@
+import { type ServiceResult } from '../models/service-result.js';
+import { CompatibilityService, type CompatibilityState } from '../services/CompatibilityService.js';
+import { type OrgInfoService } from '../services/OrgInfoService.js';
+/** Error codes specific to the compatibility-check operation. */
+export declare const CompatibilityErrorCodes: {
+    /** Manifest is missing required fields (re-raised from CompatibilityService). */
+    readonly MANIFEST_INVALID: "E4681";
+    /** Manifest CLI version field is missing. */
+    readonly CLI_VERSION_MISSING: "E4684";
+    /** Failed to query installed package version from the org. */
+    readonly ORG_PACKAGE_QUERY_FAILED: "E4683";
+};
+/**
+ * Result payload of the compatibility check.
+ *
+ * `installed` is present only when an org check was performed (caller passed an
+ * `OrgInfoService`). When absent, the result describes only the CLI's
+ * requirement (no Salesforce API call was made).
+ */
+export type CompatibilityResult = {
+    /** CLI plugin version (from `package.json` `version` field). */
+    cliVersion: string;
+    /** Display name of the Cuneiform For Salesforce managed package. */
+    appName: string;
+    /** Minimum-required app version (from `package.json` `cuneiform.requiredAppVersion`). */
+    requiredAppVersion: string;
+    /** Org-side details, present only when a target org was supplied. */
+    installed?: {
+        /** Installed version string, or `null` when the package is not installed. */
+        version: string | null;
+        /** Compatibility outcome relative to the required version. */
+        state: CompatibilityState;
+    };
+};
+/** Options for {@link CompatibilityCheckOperation.execute}. */
+export type CompatibilityCheckOptions = {
+    /**
+     * When provided, the operation queries the org for the installed Cuneiform
+     * For Salesforce package and includes installed-version detail in the result.
+     * When omitted, the result describes only the CLI's requirement.
+     */
+    orgInfoService?: OrgInfoService;
+};
+/**
+ * Orchestrates compatibility resolution between the running CLI and (optionally)
+ * the Cuneiform For Salesforce package installed in a target org.
+ *
+ * Always returns required and CLI versions. When an `OrgInfoService` is supplied
+ * via {@link execute}, also queries `getCuneiformPackageInfo()` and computes the
+ * comparison state via {@link CompatibilityService.compare}.
+ */
+export declare class CompatibilityCheckOperation {
+    private readonly compatibilityService;
+    constructor(compatibilityService: CompatibilityService);
+    /**
+     * Run the compatibility check.
+     *
+     * @param options - optionally supply an `OrgInfoService` to query the target org
+     * @returns ServiceResult describing the CLI requirement and (when org-checked) the installed state
+     */
+    execute(options?: CompatibilityCheckOptions): Promise<ServiceResult<CompatibilityResult>>;
+}

package/lib/operations/CompatibilityCheckOperation.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 { SfError } from '@salesforce/core';
+import { createSuccessResult, createFailureResult } from '../models/service-result.js';
+import { CompatibilityService } from '../services/CompatibilityService.js';
+/** Display name of the managed package. Stable — does not vary with version. */
+const APP_NAME = 'Cuneiform For Salesforce';
+/** Error codes specific to the compatibility-check operation. */
+export const CompatibilityErrorCodes = {
+    /** Manifest is missing required fields (re-raised from CompatibilityService). */
+    MANIFEST_INVALID: 'E4681',
+    /** Manifest CLI version field is missing. */
+    CLI_VERSION_MISSING: 'E4684',
+    /** Failed to query installed package version from the org. */
+    ORG_PACKAGE_QUERY_FAILED: 'E4683',
+};
+/**
+ * Orchestrates compatibility resolution between the running CLI and (optionally)
+ * the Cuneiform For Salesforce package installed in a target org.
+ *
+ * Always returns required and CLI versions. When an `OrgInfoService` is supplied
+ * via {@link execute}, also queries `getCuneiformPackageInfo()` and computes the
+ * comparison state via {@link CompatibilityService.compare}.
+ */
+export class CompatibilityCheckOperation {
+    compatibilityService;
+    constructor(compatibilityService) {
+        this.compatibilityService = compatibilityService;
+    }
+    /**
+     * Run the compatibility check.
+     *
+     * @param options - optionally supply an `OrgInfoService` to query the target org
+     * @returns ServiceResult describing the CLI requirement and (when org-checked) the installed state
+     */
+    async execute(options) {
+        const startTime = Date.now();
+        const fallbackResult = {
+            cliVersion: 'unknown',
+            appName: APP_NAME,
+            requiredAppVersion: 'unknown',
+        };
+        let cliVersion;
+        let requiredVersion;
+        try {
+            requiredVersion = this.compatibilityService.loadRequired().version;
+            cliVersion = this.compatibilityService.loadCliVersion();
+        }
+        catch (err) {
+            const errorCode = err instanceof SfError ? err.name : CompatibilityErrorCodes.MANIFEST_INVALID;
+            const errorMessage = err instanceof Error ? err.message : 'Unknown manifest error';
+            return createFailureResult(fallbackResult, errorCode, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const baseResult = {
+            cliVersion,
+            appName: APP_NAME,
+            requiredAppVersion: requiredVersion,
+        };
+        const orgInfoService = options?.orgInfoService;
+        if (!orgInfoService) {
+            return createSuccessResult(baseResult, {
+                message: `Required ${APP_NAME} app version: ${requiredVersion}`,
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const pkgResult = await orgInfoService.getCuneiformPackageInfo();
+        if (!pkgResult.success) {
+            return createFailureResult(baseResult, CompatibilityErrorCodes.ORG_PACKAGE_QUERY_FAILED, pkgResult.message ?? 'Failed to query installed Cuneiform package version', { metadata: { duration: Date.now() - startTime } });
+        }
+        // CLI-1569: source-pushed scratch orgs return installed=true with no version.
+        // Treat as "version-unknown" rather than misreporting as not-installed.
+        let installedVersion = null;
+        let state;
+        if (pkgResult.data.installed && typeof pkgResult.data.version === 'string') {
+            installedVersion = pkgResult.data.version;
+            state = CompatibilityService.compare(requiredVersion, installedVersion);
+        }
+        else if (pkgResult.data.installed) {
+            // Detected via namespace fallback, no version available.
+            state = 'installed-version-unknown';
+        }
+        else {
+            state = 'not-installed';
+        }
+        const result = {
+            ...baseResult,
+            installed: { version: installedVersion, state },
+        };
+        return createSuccessResult(result, {
+            message: `Compatibility: ${state}`,
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+}
+//# sourceMappingURL=CompatibilityCheckOperation.js.map

package/lib/operations/CompatibilityCheckOperation.js.map

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