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

package/messages/org.details.md

@@ -0,0 +1,386 @@
+# summary
+
+Consolidate org configuration — products, features, capacity, and namespace composition — into a single view that replaces navigating six Setup pages.
+
+# description
+
+Salesforce spreads org configuration across Company Information, Installed Packages, Org Limits, Feature Settings, License Management, and more. Understanding what an org contains before profiling typically means navigating between these pages to build a mental model. This command consolidates that orientation into a single call that returns in seconds.
+
+**Structured sections, one command:**
+
+- **Identity** — org name, type (Production/Sandbox/Scratch/Developer/Trial), edition, instance URL, namespace
+- **Cuneiform** — installation status, package version, and license state
+- **Features** — enabled capabilities (Multi-Currency, Person Accounts, Einstein AI, Enhanced Notes, and others)
+- **Clouds** — Salesforce products detected by license queries and namespace prefix matching (Financial Services, CPQ, Health Cloud, and others found in the org)
+- **Namespaces** — installed packages with object counts and population rates per namespace
+- **Processes** — active business processes with record type associations
+- **Limits** — current API request quotas, data and file storage consumption, with capacity warnings at 95%
+- **Next Steps** — command suggestions tailored to the org's namespace composition and data
+
+James Morrison runs this first in every new org. Sarah Mitchell checks limits before profiling runs. Marcus Thompson uses the dynamic next steps to guide his exploration path.
+
+**When to run this command:**
+
+- Entering a new org for the first time and building a mental model of its product landscape
+- Checking API and storage capacity before submitting profiling requests
+- Verifying Cuneiform installation and license status in a new sandbox
+- Understanding which Salesforce products (Clouds, managed packages) are installed before scoping profiling
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"show me everything about this org" → no flags (all sections)
+"check my API limits" → --sections limits
+"is Cuneiform installed?" → --sections cuneiform
+"what Clouds are in this org?" → --sections clouds
+"show me all limits grouped" → --sections limits-all
+"how much storage is used?" → --sections limits-storage
+
+COMMAND SEQUENCE:
+`org details` → `object list` → `user details` → `definition create` → `profile`
+
+This is typically the first command run in any engagement. It precedes `object list` (exploring what objects have data) and `user details` (verifying profiling readiness). Read-only — consolidates existing data from multiple API endpoints into a single view.
+
+# flags.target-org.summary
+
+The Salesforce org to retrieve configuration details from. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.api-version.summary
+
+Override the Salesforce API version used for org configuration queries. Use this when troubleshooting version-specific behavior or testing against a specific API release.
+
+# flags.sections.summary
+
+Filter to specific sections instead of displaying the full eight-section report. Valid values: identity, cuneiform, features, clouds, namespaces, processes, limits. For limits granularity: limits-all (groups limits by category) or limits-api, limits-storage, limits-bulk, limits-apex, limits-streaming, limits-email (single category). Omit to display all sections.
+
+# examples
+
+- Engagement kickoff — see the full org picture (edition, products, features, capacity, namespace composition):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Pre-profiling capacity check — verify API and storage capacity before submitting profiling requests:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --sections limits
+
+- Cuneiform readiness — confirm installation and license status in a new sandbox:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --sections cuneiform
+
+- Product landscape — see which Salesforce Clouds are installed to scope profiling by product:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --sections clouds
+
+- Namespace composition — identify managed packages and their object counts for profiling scope:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --sections namespaces
+
+- Storage detail — check data and file storage consumption before a profiling run:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --sections limits-storage
+
+- JSON for automation — pipe structured output to assessment pipelines or SOW templates:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --json
+
+# info.fetching
+
+Fetching org details...
+
+# errors.identityFailed
+
+Failed to retrieve org identity information.
+
+# warnings.header
+
+Warnings
+
+# output.identity.header
+
+Org Identity
+
+# output.identity.orgId
+
+Org ID
+
+# output.identity.orgName
+
+Org Name
+
+# output.identity.orgType
+
+Org Type
+
+# output.identity.edition
+
+Edition
+
+# output.identity.namespace
+
+Namespace
+
+# output.identity.instanceUrl
+
+Instance URL
+
+# output.identity.username
+
+Username
+
+# output.cuneiform.header
+
+Cuneiform for Salesforce
+
+# output.cuneiform.status
+
+Status
+
+# output.cuneiform.installed
+
+Installed
+
+# output.cuneiform.notInstalled
+
+Not Installed
+
+# output.cuneiform.version
+
+Version
+
+# output.cuneiform.license
+
+License
+
+# output.features.header
+
+Org Features
+
+# output.features.multiCurrency
+
+Multi-Currency
+
+# output.features.enhancedNotes
+
+Enhanced Notes
+
+# output.features.stateCountryPicklists
+
+State/Country Picklists
+
+# output.features.territoryManagement
+
+Territory Management
+
+# output.features.personAccounts
+
+Person Accounts
+
+# output.features.digitalExperiences
+
+Digital Experiences
+
+# output.features.einsteinAI
+
+Einstein AI
+
+# output.clouds.header
+
+Detected Clouds
+
+# output.clouds.none
+
+No Salesforce Clouds detected
+
+# output.clouds.licenseSubheader
+
+Detected Clouds by License
+
+# output.clouds.namespaceSubheader
+
+Detected Clouds by Namespace
+
+# output.namespaces.header
+
+Installed Namespaces (Standard / Custom Objects)
+
+# output.limits.header
+
+API Limits
+
+# output.limits.dailyApiRequests
+
+Daily API Requests
+
+# output.limits.bulkApiRequests
+
+Bulk API Requests
+
+# output.limits.bulkV2QueryJobs
+
+Bulk V2 Query Jobs
+
+# output.limits.asyncApexExecutions
+
+Async Apex Executions
+
+# output.limits.streamingApiEvents
+
+Streaming API Events
+
+# output.cuneiform.licenseStatus
+
+Your Cuneiform license is %s.
+
+# output.cuneiform.licenseContactSupport
+
+Please contact support to reactivate your license at sfsupport@peernova.com.
+
+# output.cuneiform.licenseContactOrgDetails
+
+Include the org identity details from this command in your email.
+
+# output.cuneiform.installGuide
+
+To install Cuneiform for Salesforce, please visit: https://peernova.link/cli/configure
+
+# warnings.storageNearCapacity
+
+Your org is near its data storage limit.
+
+# warnings.storageProfilingImpact
+
+Cuneiform writes profiling results to custom objects in your org.
+
+# warnings.storageProfilingFailure
+
+Profiling may fail if storage capacity is exceeded.
+
+# table.clouds.cloud
+
+cloud
+
+# table.clouds.status
+
+status
+
+# table.clouds.usedLicenses
+
+used licenses
+
+# table.clouds.total
+
+total
+
+# table.cloudsDetail.cloud
+
+cloud
+
+# table.cloudsDetail.version
+
+version
+
+# table.cloudsDetail.namespace
+
+namespace
+
+# table.namespaces.namespace
+
+namespace
+
+# table.namespaces.product
+
+product
+
+# table.namespaces.objects
+
+objects
+
+# table.namespaces.populated
+
+populated
+
+# table.namespaces.empty
+
+empty
+
+# table.limits.limit
+
+limit
+
+# table.limits.used
+
+used
+
+# table.limits.max
+
+max
+
+# table.limits.percent
+
+percent
+
+# output.headerTitle
+
+Org Details
+
+# output.limits.dataStorageWithUnit
+
+Data Storage (MB)
+
+# output.limits.fileStorageWithUnit
+
+File Storage (MB)
+
+# output.unknownFallback
+
+Unknown
+
+# output.processes.header
+
+Business Processes
+
+# table.processes.name
+
+name
+
+# table.processes.object
+
+object
+
+# table.processes.active
+
+active
+
+# table.processes.recordTypes
+
+record types
+
+# output.nextSteps.header
+
+Next steps:
+
+# output.nextSteps.objectListWithRecords
+
+View objects with records
+
+# output.nextSteps.objectListCustom
+
+View custom objects
+
+# output.nextSteps.objectListStandard
+
+View standard objects
+
+# output.nextSteps.objectListNamespace
+
+View %s objects
+
+# output.nextSteps.objectListCustomerFacing
+
+View customer-facing objects with records
+
+# output.nextSteps.objectDescribe
+
+View specific object details
+
+# output.nextSteps.definitionCreate
+
+Create a profiling definition

package/messages/org.reset.md

@@ -0,0 +1,71 @@
+# summary
+
+Reset org by removing Cuneiform test data created by NUT tests.
+
+# description
+
+Purges all profiling definitions matching a name pattern (default: `[NUT-*]`), cancels active profiling requests, and deletes terminal requests. Use this command to restore a scratch org to a clean state after NUT test runs.
+
+The reset sequence is:
+
+1. Query definitions matching the name pattern
+2. Cancel any active profiling requests
+3. Delete cancelled/rejected profiling requests
+4. Delete definitions that have no related summaries
+
+Definitions with related summaries are skipped — use `sf cuneiform summary purge` first to remove them.
+
+# examples
+
+- Reset org by removing all NUT-created test data: `sf cuneiform org reset --target-org myOrg`
+- Preview what would be deleted without making changes: `sf cuneiform org reset --target-org myOrg --dry-run`
+- Reset with a custom pattern: `sf cuneiform org reset --target-org myOrg --pattern "Test%"`
+- Reset without confirmation prompt: `sf cuneiform org reset --target-org myOrg --no-prompt`
+
+# flags.pattern.summary
+
+SOQL LIKE pattern for definition names to purge.
+
+# flags.dry-run.summary
+
+Preview what would be deleted without making changes.
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt before deleting.
+
+# spinner.querying
+
+Querying definitions matching "%s"...
+
+# spinner.cancelling
+
+Cancelling active profiling requests...
+
+# spinner.deleting-requests
+
+Deleting terminal profiling requests...
+
+# spinner.deleting-definitions
+
+Deleting %d definitions...
+
+# info.already-clean
+
+Org is already clean — no test data found matching "%s".
+
+# info.dry-run-header
+
+Dry-run preview (no changes will be made):
+
+# info.summary
+
+Reset complete.
+
+# errors.queryFailed
+
+Failed to query definitions: %s
+
+# errors.operationFailed
+
+Org reset failed: %s

package/messages/profile.md

@@ -0,0 +1,231 @@
+# summary
+
+Execute profiling definitions against a Salesforce org to generate field-level, value-level, and KPI-level evidence about data population and usage patterns.
+
+# description
+
+Profiling is the moment where KYCD moves from planning to evidence. Before profiling, definitions are plans — field lists, filters, and scoping decisions. After profiling, they have results: field population rates, value distributions, null percentages, default detection, and usage patterns across every profiled object.
+
+The command operates as a fire-and-forget execution engine — it creates profiling requests in the processing queue and returns immediately. Results appear in the org as summaries complete, typically within minutes depending on object size and field count. Definitions are managed with the `definition` commands; results are reviewed through summaries.
+
+TWO MODES:
+
+**Single mode** — Profile one definition:
+
+- `--keys PD-0001` — profile by definition key
+- `--id a0Bxx000000001AAAA` — profile by Salesforce record ID
+
+Single mode displays definition key, object name, status, request ID, duration, and error details.
+
+**Bulk mode** — Profile multiple definitions with parallel execution:
+
+- `--method metadata` — profile all definitions of a method type (metadata, historical, or comparative)
+- Add filters: --status, --namespace, --category, --time-category, --segment-category, --limit
+- Control concurrency: --parallel (1-10 threads, default: 5)
+
+Bulk mode displays a configuration summary, a results table, a profiling summary (Successful/Failed/Skipped/Total), and resolution guidance for failures.
+
+Objects with zero records are automatically skipped (--skip-empty defaults to true), preventing wasted API calls. Failed definitions are reported with resolution guidance that provides actionable next steps.
+
+PREREQUISITE: Definitions must exist before profiling. Create them with `sf cuneiform definition create`.
+
+WHEN TO USE:
+
+- After creating definitions — turn scoping work into analytical evidence
+- To refresh profiling results — re-run profiling on existing definitions for updated data
+- For bulk assessment — sweep all metadata definitions in a single parallel command
+- To re-profile after errors — fix the underlying issue, then re-run the failed definitions
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"profile the Account definition" → --keys PD-0001
+"profile all metadata definitions" → --method metadata
+"profile everything that hasn't been profiled" → --method metadata --status "NOT PROFILED"
+"profile only FSC objects" → --method metadata --namespace FinServ
+"profile with less concurrency" → --method metadata --parallel 1
+
+COMMAND SEQUENCE:
+`definition create` or `definition update` → **`profile`** → `profile request list` → `definition get` (view results)
+
+# flags.target-org.summary
+
+Authenticate and execute profiling against this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.keys.summary
+
+Profile one or more definitions by key (e.g., --keys PD-0001). Find keys with `definition list`. Mutually exclusive with --id and --method.
+
+# flags.id.summary
+
+Profile a single definition by its Salesforce record ID (e.g., --id a0Bxx000000001AAAA). Use when you have the record ID from the Salesforce UI or API. Mutually exclusive with --keys and --method.
+
+# flags.method.summary
+
+Profile all definitions matching a method type: metadata (field-level analysis), historical (time-series trends), or comparative (segment comparison). Activates bulk mode with parallel execution. Mutually exclusive with --keys and --id.
+
+# flags.status.summary
+
+Filter definitions by profiling status before executing (e.g., --status "NOT PROFILED" for first-time profiling, --status "ERROR" to retry failures). Applies only in bulk mode with --method.
+
+# flags.namespace.summary
+
+Filter definitions by the namespace prefix of their target object (e.g., "FinServ" for Financial Services Cloud, "SBQQ" for CPQ). Profiles only definitions targeting objects from a specific managed package.
+
+# flags.category.summary
+
+Filter definitions by category label (e.g., "Baseline", "Phase 1"). Combine with --time-category and --segment-category to target definitions across all three category dimensions.
+
+# flags.time-category.summary
+
+Filter definitions by time category (e.g., "Lifetime", "2026 vs 2025", "This Year"). Combine with --category and --segment-category to target time-scoped definitions.
+
+# flags.segment-category.summary
+
+Filter definitions by segment category (e.g., "Historical", "Comparative", "Enterprise Sales", "Won vs Lost"). Combine with --category and --time-category to target specific comparison segments.
+
+# flags.limit.summary
+
+Cap the number of definitions processed in bulk mode (e.g., --limit 10 to profile a small batch for testing). Controls the maximum definitions per run.
+
+# flags.skip-empty.summary
+
+Automatically skip definitions targeting objects with zero records (default: true). Optimizes API usage by focusing execution on populated objects. Use --no-skip-empty to include all definitions regardless of record count.
+
+# flags.parallel.summary
+
+Set the number of parallel concurrent operations for bulk mode (1-10, default: 5). Lower values reduce API consumption; higher values increase throughput when the org has API capacity.
+
+# flags.format.summary
+
+Control the output format: table (default, human-readable with progress and summary boxes) or json (machine-readable for scripting and automation).
+
+# examples
+
+- Profile a single definition by key:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --keys PD-0001
+
+- Profile a single definition by Salesforce record ID:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a0Bxx000000001AAAA
+
+- Sweep all metadata definitions with parallel execution:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --method metadata
+
+- Profile only definitions that have never been profiled:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --method historical --status "NOT PROFILED"
+
+- Profile only Financial Services Cloud objects:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --method metadata --namespace FinServ
+
+- Maximize throughput with full parallelism:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --method comparative --parallel 10
+
+- Profile a small batch for testing:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --method metadata --limit 5
+
+- Minimize API impact with single-threaded execution:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --method metadata --parallel 1
+
+# display.definition
+
+Definition: %s (%s)
+
+# display.status
+
+Status: %s
+
+# display.requestId
+
+Request ID: %s
+
+# display.error
+
+Error: %s
+
+# display.resolution
+
+Resolution: %s
+
+# display.skipReason
+
+Skip reason: %s
+
+# display.processed
+
+Processed %s definition(s):
+
+# display.resolutionGuidance
+
+Resolution guidance for failures:
+
+# display.resolutionItem
+
+%s: %s
+
+# display.summaryTitle
+
+Summary
+
+# display.summarySuccessful
+
+Successful
+
+# display.summaryFailedLabel
+
+Failed
+
+# display.summarySkippedLabel
+
+Skipped
+
+# display.summaryTotalLabel
+
+Total
+
+# display.nextSteps
+
+Track profiling progress:
+
+sf cuneiform profile request list --target-org %s
+
+# spinner.connecting
+
+Connecting
+
+# errors.noSelection
+
+No selection provided. Specify --keys, --id, or --method flag.
+
+# errors.invalidSelection
+
+Invalid flag combination. Only one of --keys, --id, or --method allowed.
+
+# errors.invalidId
+
+Invalid Salesforce ID format: %s. Must be 15 or 18 alphanumeric characters.
+
+# errors.definitionNotFound
+
+Definition not found: %s
+
+# errors.invalidParallel
+
+Invalid --parallel value. Must be between 1 and 10.
+
+# errors.queryFailed
+
+Failed to query definitions: %s
+
+# errors.noDefinitionsFound
+
+No definitions found matching filters.
+
+# errors.executionFailed
+
+Profiling execution failed: %s