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

package/messages/definition.create.md

@@ -0,0 +1,511 @@
+# summary
+
+Build profiling definitions that translate scoping decisions — object selection, filtering, and profiling methodology — into executable configuration records across one or dozens of objects in a single command.
+
+# description
+
+Profiling definitions are the blueprint that tells Cuneiform what to analyze. Each definition specifies an object, a profiling method, and a time scope. This command translates your intent — expressed through flags for method selection, object filtering, and time windowing — into structured definition records in the target org.
+
+The command executes in two phases. Phase 1 discovers and validates objects, builds a preview table showing each object with its record count, profiling type, category, time category, and segment category, then prompts for confirmation. Phase 2 creates definitions sequentially, reporting progress via spinner updates. Output includes separate Created and Skipped tables, a summary box (Objects/Created/Skipped/Failed), and optional post-creation actions: trigger immediate profiling, open the first definition in Salesforce Lightning, or write session data to a local log directory.
+
+PREREQUISITES: Run `sf cuneiform user details --configure` to verify permissions. Objects must exist in the target org.
+
+CHOOSING A PROFILING METHOD (--method):
+
+- metadata — Catalogs field structure and configuration. No record scanning. Fast. No time dimension.
+- historical — Full record-level data profiling with year-based time windows. Captures how field population changes over time.
+- comparative — Year-over-year comparison: compares current-period records (SetA) against prior-period records (SetB). Requires --year or --date-literal.
+- recordtype — Per-record-type analysis across 6 time windows. Segments data by business process stage (e.g., New Business vs Renewal).
+- outcome — Boolean outcome comparison: Won vs Lost for Opportunity, Closed vs Open for Case, Converted vs Unconverted for Lead. Surfaces data quality gaps between business outcomes.
+- full — All five methods combined. Comprehensive first-time profiling of a new org. Default.
+
+SCOPING OBJECTS:
+
+- --objects Account,Contact — Profile specific named objects (comma-separated or repeated)
+- --filter custom — All custom objects; --filter standard — All standard objects
+- --with-records — Only objects that have at least one record (recommended for historical/comparative)
+- --min-records 100 — Only objects with 100+ records
+- --namespace SBQQ — Only objects from a specific managed package (e.g., SBQQ for CPQ, FinServ for FSC)
+- --pattern Account\* — Objects matching a wildcard pattern
+
+ROLLING TIME WINDOWS (use with --method comparative, historical, recordtype, or full):
+
+- --date-literal THIS_YEAR — Profile the current year's records
+- --date-literal THIS_QUARTER — Profile the current quarter
+- --date-literal THIS_MONTH — Profile the current month
+- --depth 3 — With a date literal, creates 3 cascading periods: this period, last period, and two periods ago
+- --depth 2 --date-literal THIS_QUARTER — Creates definitions for this quarter AND last quarter
+- --year 2026 — Use a specific year instead of a date literal; --depth controls how many prior years to include
+- --date-field LastModifiedDate — Use LastModifiedDate instead of CreatedDate for time filtering
+
+NATURAL LANGUAGE → FLAG MAPPING:
+
+- "compare X from 2025 vs 2026" → --method comparative --year 2026
+- "rolling quarterly analysis" → --method comparative --date-literal THIS_QUARTER --depth N
+- "year-over-year trends" → --method comparative
+- "by business stage / record type" → --method recordtype
+- "won vs lost / closed vs open" → --method outcome
+- "field-level stats only" → --method metadata
+- "objects with data" → --with-records
+- "FSC objects" → --namespace FinServ
+- "CPQ objects" → --namespace SBQQ
+- "last N months" → --date-literal LAST_MONTH --depth N
+- "this fiscal year" → --date-literal THIS_FISCAL_YEAR
+
+COMMAND SEQUENCE: `user details --configure` (verify permissions) → `object describe` (understand structure) → `definition create` (build definitions) → `profile` (execute profiling)
+
+SAFETY: Objects that already have definitions are skipped automatically (no duplicates). A confirmation prompt appears before creation. Use --dry-run to preview without creating.
+
+# flags.target-org.summary
+
+Salesforce org where definitions will be created. The command validates Cuneiform installation and permission sets before any API calls.
+
+# flags.objects.summary
+
+Salesforce object API names to create definitions for (e.g., --objects Account --objects Contact). Repeat the flag for multiple objects. When you know exactly which objects to profile, this is the most direct selection mode. Cannot be combined with --filter when targeting specific objects.
+
+# flags.pattern.summary
+
+Filter objects by API name pattern using wildcard matching (e.g., Account\_ matches Account and AccountTeamMember). Use plain text for substring matching (e.g., Account matches any object containing "Account"). Targets families of related objects by naming convention.
+
+# flags.filter.summary
+
+Filter objects by Salesforce object type: custom (objects with \_\_c suffix), standard (built-in objects like Account, Contact, Opportunity), or all (both). Defaults to all.
+
+# flags.namespace.summary
+
+Filter objects by managed package namespace prefix to scope profiling to a specific product installation (e.g., --namespace SBQQ for CPQ, --namespace FinServ for Financial Services Cloud, --namespace HealthCloudGA for Health Cloud). Pass an empty string ("") to target only unpackaged custom objects. Combines with --filter custom to isolate custom objects from a specific package.
+
+# flags.classification.summary
+
+Filter by object classification: customer (business-facing objects), internal (system objects), or all. Defaults to all.
+
+# flags.with-records.summary
+
+Include only objects that have at least one record. Avoids creating definitions for empty staging or archive objects. Recommended for historical and comparative profiling where empty objects produce no analytical value. Cannot be combined with --without-records.
+
+# flags.without-records.summary
+
+Include only objects that have zero records. Targets empty objects for data completeness analysis or unused schema identification. Cannot be combined with --with-records.
+
+# flags.with-record-types.summary
+
+Include only objects that have at least one active record type defined. Use with --method recordtype to ensure targeted objects have record types to segment by.
+
+# flags.category.summary
+
+Label assigned to every definition created in this run (e.g., --category "Phase 1" or --category "Sales Cloud"). Groups definitions by engagement phase or functional area for later filtering and management. Freeform text.
+
+# flags.min-records.summary
+
+Minimum record count an object must have to be included (e.g., --min-records 100 skips objects with fewer than 100 records). Filters out low-volume objects that would produce statistically insignificant profiling results. Defaults to 0 (include all).
+
+# flags.limit.summary
+
+Maximum number of objects to create definitions for (e.g., --limit 20 for a quick demo setup). Constrains scope in large orgs or matches a statement-of-work object count. Objects are selected in the order returned by the Salesforce DescribeGlobal API. When omitted, processes all matching objects.
+
+# flags.method.summary
+
+Profiling methodology that determines the analytical questions each definition can answer:
+metadata — Catalogs field structure and configuration. Fast, no record scanning, no time dimension.
+historical — Full record-level analysis with year-based time windows. Captures field population changes over time.
+comparative — Compares current-period records (SetA) vs prior-period records (SetB). Requires --year or --date-literal.
+recordtype — Per-record-type analysis across 6 time windows. Segments by business process stage (e.g., New Business vs Renewal for Opportunity).
+outcome — Boolean outcome comparison: Won vs Lost (Opportunity), Closed vs Open (Case), Converted vs Unconverted (Lead). Surfaces data quality gaps between business outcomes.
+full — All five methods combined. Comprehensive first-time profiling of a new org or client engagement. Default.
+Defaults to full.
+
+# flags.year.summary
+
+Anchor year for time-based profiling definitions (e.g., --year 2026). Used with --method comparative, historical, recordtype, or full. Accepts comma-separated years (--year 2026,2025,2024). When combined with --depth, sets the starting year and counts backward (e.g., --year 2026 --depth 3 creates definitions for 2026, 2025, and 2024). Defaults to the current year. Cannot be combined with --date-literal.
+
+# flags.depth.summary
+
+Number of cascading time periods to create, counting backward from the anchor year or date literal (e.g., --depth 3 with --year 2026 creates definitions for 2026, 2025, and 2024). Use with --date-literal to span periods (e.g., --date-literal THIS_QUARTER --depth 2 creates definitions for this quarter and last quarter). When no anchor year is specified, defaults to the current year. Defaults to 1 for comparative, 3 for full and recordtype. Maximum 10.
+
+# flags.from.summary
+
+Start year of an explicit range (inclusive). Use with --to for a custom year range (e.g., --from 2020 --to 2026). Cannot be combined with --depth.
+
+# flags.to.summary
+
+End year of an explicit range (inclusive). Use with --from for a custom year range (e.g., --from 2020 --to 2026). Defaults to the current year when --from is specified.
+
+# errors.yearRangeInvalid
+
+Invalid year range: %s
+
+# flags.recordtype.summary
+
+Filter to a specific record type name for record-type-specific profiling (e.g., --recordtype "New Business"). Used with --method recordtype or --method full. When omitted, all record types matching --record-type-status are included.
+
+# flags.record-type-status.summary
+
+Filter record types by activity status: active (default), all (active and inactive), or inactive (only inactive). Used with --method recordtype or --method full.
+
+# warnings.yearIgnored
+
+Year-related flags (--year, --depth, --from, --to) have no effect with --method metadata. Metadata profiling analyzes field structure only, with no time dimension. Ignoring.
+
+# flags.no-value-frequency.summary
+
+Skip common value frequency analysis during profiling. Reduces profiling time for objects where frequency distribution data is not needed.
+
+# flags.use-prior.summary
+
+Expand the comparison baseline (SetB) for comparative definitions to include all records created before the anchor year, rather than only the immediately prior year. Shows "current year vs everything before" instead of "current year vs last year" — useful for demonstrating data quality improvements across the full historical record. Cannot be combined with --date-literal.
+
+# flags.lifetime-primary.summary
+
+Lifetime-vs-X comparative variant: SetA is unfiltered (all records), SetB is the supplied secondary filter. Shows "all records ever vs records matching the filter" — useful for highlighting what fraction of the lifetime data falls within a recent window or specific year. Requires --method comparative AND one of (--date-literal, --year, --from/--to). Mutually exclusive with --use-prior, --depth, and non-comparative methods.
+
+# flags.date-literal.summary
+
+Rolling time window for time-scoped profiling — use instead of --year for calendar-relative periods. Combine with --depth to create cascading definitions across multiple periods (e.g., --date-literal THIS_QUARTER --depth 4 creates definitions for the last 4 quarters). Cannot be combined with --year, --from, --to, or --use-prior.
+
+Supported values:
+TODAY, YESTERDAY — Single-day windows
+THIS_WEEK, LAST_WEEK — Weekly windows
+THIS_MONTH, LAST_MONTH — Monthly windows (use with --depth for "last N months")
+THIS_QUARTER, LAST_QUARTER — Quarterly windows (use with --depth for "rolling quarters")
+THIS_FISCAL_QUARTER, LAST_FISCAL_QUARTER — Fiscal quarter windows
+THIS_YEAR, LAST_YEAR — Annual windows
+THIS_FISCAL_YEAR, LAST_FISCAL_YEAR — Fiscal year windows
+N_YEARS_AGO:2, N_YEARS_AGO:3 — Specific years in the past
+LAST_N_YEARS:2, LAST_N_YEARS:3 — Last N complete years
+
+# flags.date-field.summary
+
+Date field used to assign records to time windows when using --date-literal. Determines which records fall in "this year" vs "last year." Defaults to CreatedDate. Use LastModifiedDate to analyze records by when they were last updated rather than when they were created (e.g., --date-field LastModifiedDate to profile recently refreshed data).
+
+# errors.dateLiteralMutualExclusion
+
+Cannot combine --date-literal with --year, --from, --to, or --use-prior. Date literals replace year-based time scoping. Use --date-literal with --depth to cascade across multiple periods.
+
+# errors.lifetimePrimaryMethodRequired
+
+--lifetime-primary is only valid with --method comparative.
+
+# errors.lifetimePrimaryUsePriorMutualExclusion
+
+Cannot combine --lifetime-primary with --use-prior. Choose one variant: --lifetime-primary (lifetime vs filtered) or --use-prior (current year vs all prior).
+
+# errors.lifetimePrimaryDepthMutualExclusion
+
+Cannot combine --lifetime-primary with --depth. The lifetime-vs-X variant produces a single definition shape per object — no cascade.
+
+# errors.lifetimePrimaryRequiresSecondaryFilter
+
+--lifetime-primary requires a secondary filter: provide --date-literal, --year, or --from/--to.
+
+# flags.dry-run.summary
+
+Preview which definitions would be created without writing any records to the org. The preview table shows the same columns as the creation output: object name, record count, type, category, and time segment. Use before any scoped run to verify the object selection and methodology match your intent.
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt and create definitions immediately. Use for scripted execution and CI automation workflows.
+
+# prompt.showDetail
+
+Show detailed preview?
+
+# prompt.confirm
+
+Create %s Profiling Definitions?
+
+# output.cancelled
+
+Definition creation cancelled.
+
+# examples
+
+- Create definitions for a single object using all profiling methods:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account
+
+- Preview what would be created before committing (recommended before batch runs):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --filter custom --with-records --dry-run
+
+- Profile all custom objects with at least 100 records, tagged by engagement phase:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --filter custom --with-records --min-records 100 --category "Phase 1"
+
+- Isolate Financial Services Cloud objects by namespace:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --namespace FinServ --method metadata
+
+- Rolling quarterly trend analysis across the last 4 quarters:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Opportunity --method comparative --date-literal THIS_QUARTER --depth 4
+
+- Lifetime vs last 2 years — show what fraction of all records were created in the recent window:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account,Contact,Opportunity --method comparative --lifetime-primary --date-literal LAST_N_YEARS:2
+
+- Lifetime vs a specific year — compare all records ever against records created in 2024:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Opportunity --method comparative --lifetime-primary --year 2024
+
+- Won vs Lost opportunity analysis to surface data quality gaps between business outcomes:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Opportunity --objects Case --objects Lead --method outcome
+
+- Bulk run with shared, human-readable category labels across every created definition:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --filter custom --with-records --time-category "Q1 2026" --segment-category "Pilot Run"
+
+# flags.profiled.summary
+
+Only create definitions for objects that already have successful metadata profiling results. Builds on prior metadata analysis — run metadata profiling first, review the results, then create historical or comparative definitions for the objects worth deeper analysis. Cannot be combined with --method metadata.
+
+# errors.profiledWithMetadata
+
+Cannot use --profiled with --method metadata. The --profiled flag targets objects that already have metadata profiling results.
+
+# errors.noObjectsFound
+
+No objects found matching the specified filters.
+
+# errors.objectsNotFound
+
+None of the specified objects exist in the org: %s
+
+# errors.allObjectsSkipped
+
+All %d objects already have existing definitions.
+
+# errors.operationFailed
+
+Failed to create definitions: %s
+
+# errors.filterFailed
+
+Failed to filter objects: %s
+
+# flags.profile.summary
+
+Trigger profiling immediately after definitions are created — equivalent to running `sf cuneiform profile` as a follow-up. Useful for quick single-object setup. For batch runs, create definitions first, review them, then profile separately.
+
+# flags.open.summary
+
+Open the created definition in Salesforce Lightning after creation completes. When multiple definitions are created, opens the first one. Useful for verifying the definition record in the Profiling Definition Wizard.
+
+# flags.logs.summary
+
+Write session logs to the .cuneiform/logs/ directory for audit and troubleshooting.
+
+# errors.noProfiledObjects
+
+No objects have been profiled yet. Run profiling with --method metadata first.
+
+# errors.orgUnreachable
+
+Unable to connect to the target org.
+
+The org "%s" could not be reached. This usually means:
+
+1. The org alias or username is incorrect
+2. The org has expired or been deleted
+3. Your authentication has expired
+
+To resolve:
+
+- Verify the org exists: sf org list
+- Re-authenticate: sf org login web --alias <your-org>
+- Check org status: sf org display --target-org <your-org>
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# errors.mutuallyExclusiveRecordFlags
+
+Cannot use --with-records and --without-records together.
+
+# errors.minRecordsWithoutRecords
+
+Cannot use --min-records with --without-records. The --min-records flag requires record counts, which --without-records excludes.
+
+# errors.recordtypeMethodRequired
+
+--recordtype flag cannot be used with --method metadata. Use it with --method historical, comparative, recordtype, outcome, or full.
+
+# output.title
+
+Creating Cuneiform Profiling Definitions for %s (%s)
+
+# output.creating
+
+Creating %d Cuneiform Profiling Definitions
+
+# errors.objectsNotFoundDetail
+
+No Salesforce Objects were found matching the specified criteria.
+
+Please check the object name(s) and confirm they exist in your Salesforce org.
+
+# spinner.connecting
+
+Connecting
+
+# spinner.validatingObjects
+
+Validating Salesforce Objects
+
+# warnings.objectNotVerified
+
+We could not verify the Object %s; no Profiling Definitions will be created for this object.
+
+# output.failedSummary
+
+%s definitions failed:
+
+# output.profileDryRun
+
+[DRY RUN] Would start profiling for %s definitions.
+
+# output.profilingStarting
+
+Profiling created definitions...
+
+# output.profilingSuccess
+
+[PROFILING] %s — request %s
+
+# warnings.profilingFailed
+
+Failed to start profiling for %s: %s
+
+# output.openedMultiple
+
+Opened first definition. Use Salesforce to view all %s definitions.
+
+# output.openedSingle
+
+Opened definition in Salesforce.
+
+# output.sessionLog
+
+Session log: %s
+
+# output.creationSummary
+
+Creation Summary
+
+# output.summaryObjects
+
+Objects:
+
+# output.summaryMethod
+
+Method:
+
+# output.summaryToCreate
+
+To create:
+
+# output.summaryExisting
+
+Existing:
+
+# output.summaryPreview
+
+Preview:
+
+# output.summaryCreated
+
+Created:
+
+# output.summarySkipped
+
+Skipped:
+
+# output.summaryFailed
+
+Failed:
+
+# output.summaryHeader
+
+Summary
+
+# output.tablePrefix.preview
+
+Preview
+
+# output.tablePrefix.created
+
+Created
+
+# output.skippedExisting
+
+Skipped %s Existing Definitions
+
+# output.definitionsTitle
+
+Cuneiform Profiling Definitions
+
+# table.header.object
+
+object
+
+# table.header.records
+
+records
+
+# table.header.type
+
+type
+
+# table.header.category
+
+category
+
+# table.header.time
+
+time
+
+# table.header.segment
+
+segment
+
+# spinner.status.created
+
+created
+
+# spinner.status.skipped
+
+skipped
+
+# output.summaryToCreateSuffix
+
+%s definitions
+
+# output.summaryExistingSuffix
+
+%s definitions (skipped)
+
+# flags.name-prefix.summary
+
+Prefix prepended to each definition name (e.g., --name-prefix TC-01). Joined with the bullet separator character.
+
+# flags.name-suffix.summary
+
+Suffix appended to each definition name (e.g., --name-suffix "Run A"). Joined with the bullet separator character.
+
+# flags.time-category.summary
+
+Verbatim time category applied to every definition created in this run (e.g., --time-category "Q1 2026" or --time-category "Pilot Period"). Overrides all computed time category values regardless of method, year, or outcome configuration. Useful for grouping definitions across a bulk run with a single shared, human-readable time label.
+
+# flags.segment-category.summary
+
+Verbatim segment category applied to every definition created in this run (e.g., --segment-category "Pilot Run" or --segment-category "Phase 1 Cohort"). Overrides all computed segment category values regardless of method, record type, or outcome configuration. Useful for grouping definitions across a bulk run with a single shared, human-readable segment label.
+
+# flags.origin.summary
+
+Origin message appended to auto-generated definition descriptions. Defaults to "Created via the Cuneiform for Salesforce CLI." Pass an empty string to suppress the origin tag.
+
+# spinner.status.failed
+
+failed

package/messages/definition.export.md

@@ -0,0 +1,88 @@
+# summary
+
+Preserve profiling definitions as portable CSV files before sandbox refreshes, package upgrades, or cross-org migrations — so hours of scoping work are recoverable in seconds.
+
+# description
+
+Profiling definitions represent hours of scoping work — object selection, method assignment, category classification, field configuration. That configuration exists inside the Salesforce org and a sandbox refresh removes it. This command extracts all profiling definitions and writes them to a self-contained export directory for backup, migration, or version control.
+
+The export creates a timestamped directory containing three files:
+
+- `export.json` — SFDMU configuration file for round-trip compatibility with `definition import`
+- `pnova__Profiling_Definition__c.csv` — all definition records (fields covering identity, aggregation status, version tracking, profiling configuration, and formula fields)
+- `export-metadata.json` — source org, timestamp, record count, and file manifest
+
+This command exports OUT of the org. To bring definitions back IN, use `sf cuneiform definition import`.
+
+WHEN TO USE:
+
+- Before a sandbox refresh — preserve definitions so you can restore after the refresh wipes custom data
+- Before a package upgrade — capture the current configuration in case the upgrade affects profiling definitions
+- For cross-org migration — export from sandbox, review the CSV in a spreadsheet, import to production
+- For version control — commit definition exports to Git with `--exclude-ids` for clean diffs between versions
+
+The `--exclude-ids` flag strips Salesforce-generated IDs (Id, CreatedById, LastModifiedById) from the CSV output. This produces clean diffs between exports — org-specific IDs create false diffs in version control.
+
+Read-only. Does not modify definitions in the org. Fails if the output directory already exists, preventing accidental overwrites of previous exports.
+
+# flags.target-org.summary
+
+Export definitions from this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.output.summary
+
+Override the default timestamped output directory. Defaults to `./data/exports/definitions/{timestamp}`, creating a unique directory per export. Specify a custom path to organize exports within a project structure (e.g., `--output ./config/definitions`).
+
+# flags.exclude-ids.summary
+
+Strip Salesforce-generated IDs (Id, CreatedById, LastModifiedById) from the CSV output. Use this when committing exports to Git — org-specific IDs differ between environments and create false diffs. Keep IDs when exporting for same-org restore fidelity.
+
+# spinner.exporting
+
+Exporting definitions...
+
+# export.complete
+
+Exported %s definition(s) successfully.
+
+# output.directory
+
+Output directory: %s
+
+# table.header.file
+
+File
+
+# table.header.definition
+
+Definition
+
+# table.header.path
+
+Path
+
+# warnings.title
+
+Warnings
+
+# examples
+
+- Back up all definitions before a sandbox refresh:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Save to a specific directory within your project structure:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --output ./backup/definitions
+
+- Export for Git — strip org-specific IDs so diffs reflect only meaningful configuration changes:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --exclude-ids --output ./config/definitions
+
+- Export for cross-org migration — keep IDs for exact restore fidelity in the target org:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --output ./migration/source-org
+
+- Output as JSON for scripting, automation pipelines, or downstream tooling:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --json