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

package/messages/definition.get.md

@@ -0,0 +1,147 @@
+# summary
+
+Resolve profiling definition keys to their full configuration — see what each definition targets, which method it uses, and what state it is in.
+
+# description
+
+Definition keys like PD-0001 appear throughout the Cuneiform workflow — in profiling logs, summary reports, error messages, and colleague questions. When a key surfaces in any context, the next step is resolving what that definition targets, what method it uses, and what state it is in. This command retrieves profiling definitions by key and presents them in a nine-column table: key, name, target object, profiling type, category, time category, segment category, profiling status, and last profiled date.
+
+Multiple keys are fetched in parallel, so looking up 5 definitions is as fast as looking up 1. The output includes an Org Identity header, a definitions table with section header and count, JSON flag guidance with a copy-paste command, and contextual next steps. Keys that do not match any definition produce warnings (not errors), supporting partial success when retrieving batches.
+
+**When to use vs related commands:**
+
+- `definition list` — "Show me all definitions" (browse, filter, overview of many)
+- `definition get` — "Show me PD-0001" (targeted lookup of specific definitions by key)
+- `definition export` — "Back up definitions for migration" (portable CSV export, not inspection)
+
+**File export:** Use `--output-dir` to save each definition as a separate JSON file for audit artifacts, project documentation, or version control.
+
+Read-only. Does not create, modify, or execute definitions. The access gate validates Cuneiform installation and permissions before queries execute.
+
+NATURAL LANGUAGE → FLAG MAPPING:
+
+"get definition PD-0001" → --keys PD-0001
+"get details for Account Standard" → --keys Account_Standard
+"show me multiple definitions" → --keys PD-0001 --keys PD-0002
+"export definitions to files" → --keys PD-0001 --output-dir ./definitions
+"show definition as JSON" → --keys PD-0001 --json
+
+COMMAND SEQUENCE: `definition list` (find keys) → `definition get` (inspect by key) → `profile` (execute profiling) or `definition update` (refine configuration)
+
+# flags.target-org.summary
+
+Retrieve definitions from this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.keys.summary
+
+One or more definition keys to retrieve (e.g., `--keys PD-0001`). Repeat the flag for multiple keys: `--keys PD-0001 --keys PD-0002`. Keys are fetched in parallel for efficient batch lookup.
+
+# flags.output-dir.summary
+
+Save each definition as a separate JSON file in this directory (e.g., `PD-0001.json`). The directory is created if it does not exist. Use this for audit artifacts, project documentation, or version control snapshots.
+
+# flags.file-names.summary
+
+Override default key-based file names with custom names (must match `--keys` count). Use when you want descriptive names for exported files (e.g., `--file-names account-standard.json`).
+
+# flags.format.summary
+
+Display format: `table` (nine-column summary, default) or `json` (complete definition record with all fields).
+
+# examples
+
+- Resolve a definition key from a profiling log or error message:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --keys PD-0001
+
+- Verify multiple definitions before executing profiling (fetched in parallel):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --keys PD-0001 --keys PD-0002 --keys PD-0003
+
+- Export definitions as JSON files for audit artifacts or project documentation:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --keys PD-0001 --keys PD-0002 --output-dir ./definitions
+
+- Export with descriptive file names for engagement deliverables:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --keys PD-0001 --output-dir ./definitions --file-names account-standard.json
+
+- View the complete definition record in JSON format:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --keys PD-0001 --json
+
+# errors.keyCountMismatch
+
+The number of file names (%d) must match the number of keys (%d).
+
+# errors.definitionNotFound
+
+Definition not found: %s
+
+# errors.exportFailed
+
+Failed to export definition %s: %s
+
+# output.headerTitle
+
+Definition Get
+
+# output.identity.header
+
+Org Identity
+
+# output.identity.orgName
+
+Org Name
+
+# output.identity.orgId
+
+Org ID
+
+# output.identity.instanceUrl
+
+Instance URL
+
+# output.identity.orgType
+
+Org Type
+
+# output.identity.edition
+
+Edition
+
+# output.identity.namespace
+
+Namespace
+
+# output.identity.username
+
+Username
+
+# output.definitions.header
+
+Definitions
+
+# output.jsonGuidance
+
+For a full export of definition data, use the JSON flag:
+
+# output.nextSteps.header
+
+Next steps:
+
+# output.nextSteps.profile
+
+Execute profiling for this definition
+
+# output.nextSteps.profileMultiple
+
+Execute profiling for these definitions
+
+# output.nextSteps.definitionList
+
+View all definitions in this org
+
+# warnings.title
+
+Warnings

package/messages/definition.import.md

@@ -0,0 +1,65 @@
+# summary
+
+Restore or migrate profiling definitions into a Salesforce org from portable CSV files, with simulation to validate the result before any records are written.
+
+# description
+
+Profiling definitions capture the scoping decisions that tell Cuneiform what to analyze. When those decisions need to move between environments — sandbox to production, old scratch org to new, or restored after a refresh — this command imports them from CSV files produced by `definition export`.
+
+The command reads a source directory containing `pnova__Profiling_Definition__c.csv`, generates a temporary import configuration, and executes the import. Partial failures are surfaced explicitly — if some definitions fail validation while others import successfully, the output identifies which objects failed and why.
+
+OPERATION MODES:
+
+- **Insert** (default) — Creates new records only. Fails on duplicate Name. Use for clean restores into empty orgs.
+- **Upsert** — Creates new records OR updates existing records matched by the Name external ID. Use when some definitions may already exist in the target org (e.g., incremental deployment to production).
+
+WHEN TO USE:
+
+- After a sandbox refresh — restore definitions from backup in under a minute
+- For production deployment — import validated definitions from sandbox with simulation as the approval artifact
+- For template provisioning — import a standard definition set into each new engagement org
+- To test safely — simulate first with --simulation to validate the entire pipeline before committing
+
+COMMAND SEQUENCE: `definition export` (save definitions to files) → `definition import --simulation` (validate against target) → `definition import` (execute) → `profile` (run profiling with restored definitions)
+
+# flags.target-org.summary
+
+Salesforce org to import definitions into. The command validates Cuneiform installation before executing the import.
+
+# flags.source.summary
+
+Directory containing the CSV files to import. Point this at a previous `definition export` output directory or any directory with a `pnova__Profiling_Definition__c.csv` file (e.g., --source ./backup/definitions).
+
+# flags.operation.summary
+
+How to handle existing definitions: Insert (default) creates new records and fails on duplicate Names; Upsert creates new records and updates existing records matched by Name. Use Insert for clean restores into empty orgs. Use Upsert when some definitions may already exist from earlier iterations.
+
+# flags.simulation.summary
+
+Validate the import without modifying data. Runs the full import pipeline — parsing, validation, duplicate checking — but skips all writes. Use before production imports to verify the operation would succeed. The simulation output serves as a change approval artifact.
+
+# examples
+
+- Restore definitions after a sandbox refresh:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup/definitions
+
+- Validate the import before committing (simulation runs the full pipeline without writing):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup/definitions --simulation
+
+- Deploy validated definitions to production with Upsert to handle mixed scenarios:
+
+  <%= config.bin %> <%= command.id %> --target-org prodOrg --source ./release/definitions --operation Upsert
+
+- Provision a new engagement org from a standard definition template:
+
+  <%= config.bin %> <%= command.id %> --target-org newClientOrg --source ./templates/standard-definitions
+
+- Output as JSON for scripted verification in CI pipelines:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --source ./backup/definitions --json
+
+# warnings.title
+
+Warnings

package/messages/definition.list.md

@@ -0,0 +1,264 @@
+# summary
+
+Inventory profiling definitions across a Salesforce org — see what has been defined, what method each uses, and where profiling stands — so you know where to focus next.
+
+# description
+
+The profiling definition inventory is the foundation of any data profiling workflow. Before you can decide what to profile, you need to see what has already been defined, which objects are in scope, and which definitions are active, complete, or stuck. This command retrieves all profiling definitions from a Salesforce org and presents them as a paginated, filterable table with seven columns: definition key, name, target object, profiling method, category, profiling status, and last profiled date.
+
+An Org Identity summary box provides org context, and a Summary box shows aggregate counts: total definitions, active, inactive, profiled, and not profiled. Active filters display above the table so you always know which narrowing is in effect. Contextual next steps suggest `definition get`, `definition create`, and `profile` commands with the target org pre-populated.
+
+**When to use vs related commands:**
+
+- `definition list` — "Show me everything" / "What definitions exist?" / "Which definitions need profiling?" (browse and filter across many)
+- `definition get` — "Show me PD-0001" / "Verify this definition before profiling" (targeted lookup by key)
+
+FILTERING — six dimensions narrow results to precisely targeted subsets:
+
+--objects Account — Only definitions targeting the Account object
+--status active — Only active definitions (vs inactive or all)
+--method metadata — Only metadata-type definitions (vs historical or comparative)
+--category "Phase 1" — Only definitions in a specific category
+--namespace FinServ — Only definitions for Financial Services Cloud objects
+--pattern Account% — Definitions whose name matches a SOQL LIKE pattern
+
+NATURAL LANGUAGE → FLAG MAPPING:
+
+"show all definitions" → (no filter flags)
+"definitions for Account" → --objects Account
+"which definitions are active" → --status active
+"metadata definitions only" → --method metadata
+"definitions not yet profiled" → --sort lastProfiledDate
+"only FSC definitions" → --namespace FinServ
+
+COMMAND SEQUENCE: `definition create` (build definitions) → `definition list` (review inventory) → `definition get` / `profile` / `definition purge` (act on specific definitions)
+
+# flags.target-org.summary
+
+Retrieve definitions from this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.objects.summary
+
+Narrow the inventory to definitions targeting specific objects (comma-separated). For example, `--objects Account,Contact` shows only definitions for Account and Contact.
+
+# flags.status.summary
+
+Filter by activity status: `active` (currently usable for profiling), `inactive` (disabled), or `all` (both). Defaults to `all`, which gives the broadest view for discovery.
+
+# flags.method.summary
+
+Filter by profiling method: `metadata`, `historical`, or `comparative`. Use this when reviewing definitions of a single analysis type (e.g., `--method historical` to see only historical definitions).
+
+# flags.pattern.summary
+
+Filter definitions by name pattern using SOQL LIKE wildcards. Use `%` for multi-character and `_` for single-character wildcards (e.g., `Account%` matches all definitions whose name starts with "Account").
+
+# flags.category.summary
+
+Filter by the category label assigned during definition creation (e.g., "Phase 1", "Sales Cloud"). Use this to view definitions grouped by engagement phase or functional area.
+
+# flags.namespace.summary
+
+Filter by the namespace prefix of the target object (e.g., `FinServ` for Financial Services Cloud, `SBQQ` for CPQ). Use this to isolate definitions belonging to a specific managed package.
+
+# flags.limit.summary
+
+Maximum definitions per page (default: 25, max: 200). Use with `--offset` to paginate through large inventories.
+
+# flags.offset.summary
+
+Skip this many definitions before returning results. Use with `--limit` for pagination (e.g., `--limit 25 --offset 25` returns the second page).
+
+# flags.sort.summary
+
+Sort results by: `key` (definition key), `name` (definition name, the default), `objectName` (target object), or `lastProfiledDate` (most recently profiled first).
+
+# examples
+
+- Inventory all definitions in the org — see the full picture before deciding what to profile next:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Focus on a specific object — show only definitions targeting Account:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account
+
+- Find active definitions ready for profiling:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --status active
+
+- Isolate Financial Services Cloud definitions by namespace:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --namespace FinServ
+
+- Page through a large definition inventory (page 3 of 25-per-page):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --limit 25 --offset 50
+
+- Export the inventory as JSON for engagement reports or scripting:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --json
+
+# errors.queryFailed
+
+Failed to query profiling definitions: %s
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# output.title
+
+Cuneiform Profiling Definitions for %s (%s)
+
+# output.identity.header
+
+Org Identity
+
+# output.identity.orgName
+
+Org Name
+
+# output.identity.orgId
+
+Org ID
+
+# output.identity.instanceUrl
+
+Instance URL
+
+# output.identity.orgType
+
+Org Type
+
+# output.identity.edition
+
+Edition
+
+# output.identity.namespace
+
+Namespace
+
+# output.identity.username
+
+Username
+
+# output.definitions.header
+
+Definitions
+
+# output.summary.header
+
+Summary
+
+# output.summary.totalDefinitions
+
+Total Definitions
+
+# output.summary.active
+
+Active
+
+# output.summary.inactive
+
+Inactive
+
+# output.summary.profiled
+
+Profiled
+
+# output.summary.notProfiled
+
+Not Profiled
+
+# output.noResults.suggestion
+
+Try relaxing or removing the most restrictive filters.
+
+# output.limitNotice
+
+Displaying %s of %s definitions. Use --limit and --offset for pagination.
+
+# output.filters.status
+
+Status: %s
+
+# output.filters.method
+
+Method: %s
+
+# output.filters.objects
+
+Objects: %s
+
+# output.filters.pattern
+
+Pattern: %s
+
+# output.filters.category
+
+Category: %s
+
+# output.filters.namespace
+
+Namespace: %s
+
+# table.header.key
+
+Key
+
+# table.header.name
+
+Name
+
+# table.header.object
+
+Object
+
+# table.header.method
+
+Method
+
+# table.header.category
+
+Category
+
+# table.header.status
+
+Status
+
+# table.header.lastProfiled
+
+Last Profiled
+
+# output.entityType
+
+definitions
+
+# output.nextSteps.header
+
+Next steps:
+
+# output.nextSteps.getLabel
+
+Get definition details
+
+# output.nextSteps.getCommand
+
+sf cuneiform definition get --target-org %s --keys %s
+
+# output.nextSteps.createLabel
+
+Create a profiling definition
+
+# output.nextSteps.createCommand
+
+sf cuneiform definition create --help
+
+# output.nextSteps.profileLabel
+
+Execute profiling for a definition
+
+# output.nextSteps.profileCommand
+
+sf cuneiform profile --target-org %s --keys %s