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

package/messages/user.details.md

@@ -0,0 +1,501 @@
+# summary
+
+Check whether the authenticated user is configured for profiling and resolve gaps — two configuration touchpoints verified and fixed in one command.
+
+# description
+
+Remote profiling requires two configuration touchpoints spread across two Salesforce Setup pages: a permission set assignment and a Custom Metadata Type setting on your Configuration Profile. Missing either one produces a generic access error. This command checks both in one step and tells you exactly what is missing and who can fix it.
+
+**Three modes:**
+
+- **Diagnostic (default)** — Answer "Am I set up to profile?" Shows Cuneiform installation status, permission set assignments, Configuration Profile enablement, and resolution guidance for any gaps. Read-only — safe to run even when permissions are incomplete.
+- **Configure (`--configure`)** — Answer "Set me up so I can profile." Assigns the required permission set via REST API and enables API-Based Profiling via Metadata API deployment in a single step. Idempotent — running it when already configured produces "no changes needed." Blocked in production orgs.
+- **Preview (`--configure --dry-run`)** — Answer "What would configure change?" Shows exactly what would be assigned or enabled, applied to nothing. Use this in regulated environments where changes require documented approval before execution.
+
+**Resolution guidance routes by persona:** When gaps exist, the output distinguishes between steps you can take yourself (self-service via `--configure`) and steps that require a Salesforce administrator.
+
+Sarah Mitchell uses this to onboard users for profiling. Marcus Thompson runs it on day one of every engagement — if access is missing, `--configure` resolves it in 15 seconds. Andre Robitaille uses `--configure` as the "hello world" of every workshop, turning NOT READY into READY as the first moment of participant success.
+
+**When to run this command:**
+
+- First time in a new org or after a sandbox refresh — confirm your user is configured before profiling
+- After getting an access error from any Cuneiform command — diagnose the exact gap
+- When onboarding workshop participants — each person runs `--configure` on their own account
+- Before a client-facing profiling session — verify readiness to prevent access failures mid-demo
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"am I set up to profile?" → no flags (diagnostic mode)
+"set me up for profiling" → --configure
+"what would configure change?" → --configure --dry-run
+"undo my configuration" → --unconfigure
+
+COMMAND SEQUENCE:
+`org details` → `user details` → `definition create` → `profile`
+
+The scope is the authenticated user's profiling readiness: permission set assignment and API-Based Profiling enablement. It typically follows `org details` (confirming Cuneiform is installed) and precedes `definition create` (building profiling definitions).
+
+# flags.target-org.summary
+
+The Salesforce org to check for profiling readiness. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.configure.summary
+
+Resolve configuration gaps in one step. Assigns the required permission set via REST API and enables API-Based Profiling via Metadata API deployment. Idempotent — safe to run when already configured. Blocked in production orgs (Developer Edition, sandbox, scratch, and trial only).
+
+# flags.api-version.summary
+
+Override the Salesforce API version for readiness checks. Use this when troubleshooting version-specific behavior or testing against a specific API release.
+
+# flags.dry-run.summary
+
+Preview what --configure would change, applied to nothing. Shows which permission set would be assigned and which Configuration Profile settings would be enabled. Use this in regulated environments to document changes for approval before execution. Implies --configure.
+
+# examples
+
+- First-time readiness check — confirm your user is configured before profiling:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Resolve all gaps at once — configure both touchpoints (permission set + API-Based Profiling) automatically:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --configure
+
+- Change management preview — document what would change before applying:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --configure --dry-run
+
+- Workshop onboarding — each participant configures their own account:
+
+  <%= config.bin %> <%= command.id %> --target-org workshopOrg --configure
+
+- Troubleshooting output — attach structured JSON to a support ticket when diagnosing access errors:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --json
+
+- Environment cleanup — reverse a previous configure when decommissioning a sandbox:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --unconfigure
+
+# prerequisites.header
+
+Prerequisites
+
+# prerequisites.cuneiformInstalled
+
+Cuneiform for Salesforce is installed
+
+# prerequisites.cuneiformNotInstalled
+
+Cuneiform for Salesforce is not installed
+
+# prerequisites.cuneiformInstallUrl
+
+Installation guide: https://peernova.link/cli/configure
+
+# prerequisites.adminAccess
+
+Administrative User (Pro Permission Set) access verified
+
+# prerequisites.adminNoAccess
+
+Administrative User (Pro Permission Set) not assigned
+
+# prerequisites.adminRemediation
+
+Contact your Salesforce administrator to grant access to Cuneiform.
+
+# links.verificationDocsUrl
+
+Verification documentation: https://peernova.link/cli/validate-cuneiform
+
+# links.installationGuideUrl
+
+https://peernova.link/cli/configure
+
+# info.userReady
+
+This user is ready for remote profiling via Cuneiform for Salesforce.
+
+# info.userConfigured
+
+This user is now ready for remote profiling via Cuneiform for Salesforce.
+
+# info.userConfigureIncomplete
+
+Configuration is incomplete — please review the warnings above for details.
+
+# info.userConfigureIncompleteAction
+
+You may need to contact your Salesforce administrator to resolve these issues.
+
+# info.nextSteps
+
+Next steps:
+
+# info.nextStepsOrgDetails
+
+sf cuneiform org details --target-org %s
+
+# info.nextStepsOrgDetailsLabel
+
+Explore your org configuration
+
+# info.nextStepsObjectList
+
+sf cuneiform object list --target-org %s --with-records
+
+# info.nextStepsObjectListLabel
+
+View available objects that are populated with records
+
+# info.nextStepsObjectDescribe
+
+sf cuneiform object describe --help
+
+# info.nextStepsObjectDescribeLabel
+
+View specific object details
+
+# info.nextStepsDefinitionCreate
+
+sf cuneiform definition create --help
+
+# info.nextStepsDefinitionCreateLabel
+
+Create a profiling definition
+
+# info.nextStepsPreviewLabel
+
+Preview what auto-configure would change
+
+# info.nextStepsPreview
+
+sf cuneiform user details --configure --dry-run --target-org %s
+
+# info.nextStepsConfigureLabel
+
+Automatically configure this user for remote profiling
+
+# info.nextStepsConfigure
+
+sf cuneiform user details --configure --target-org %s
+
+# info.nextStepsContactAdmin
+
+Contact your Salesforce administrator to assign the required Cuneiform permission sets.
+
+# info.nextStepsRetryLabel
+
+Retry the configuration
+
+# info.nextStepsReconfigureLabel
+
+Reconfigure this user for remote profiling
+
+# info.fetchingOrgData
+
+Fetching org data
+
+# info.configureStart
+
+Configuring user for remote profiling (this may take 10–30 seconds)...
+
+# info.dryRunStart
+
+Checking configuration status (dry-run mode)...
+
+# info.plannedActions
+
+Planned Actions (Dry-Run)
+
+# info.completedActions
+
+Configuration Actions
+
+# info.dryRunSummary
+
+Dry-run complete: %s would be applied.
+
+# info.configurationComplete
+
+Configuration complete: %s applied.
+
+# info.alreadyConfiguredSummary
+
+Already configured — no changes needed.
+
+# info.alreadyUnconfiguredSummary
+
+Already unconfigured — no changes needed.
+
+# info.userWouldBeReady
+
+This user would be ready for remote profiling via Cuneiform for Salesforce after applying these changes.
+
+# guidance.cuneiformNotInstalled
+
+Cuneiform for Salesforce is not installed in this org.
+
+# guidance.cuneiformNotInstalledAction
+
+Contact your Salesforce administrator to install the Cuneiform for Salesforce managed package.
+
+# guidance.missingPermissionSet
+
+Missing Permission Set: %s.
+
+# guidance.missingPermissionSetAction
+
+Navigate to Setup > Users > Permission Set Assignments to assign this permission set.
+
+# guidance.missingPermissionSets
+
+Missing Permission Sets:
+
+# guidance.missingPermissionSetsAction
+
+Navigate to Setup > Users > Permission Set Assignments to assign these permission sets.
+
+# guidance.apiOnlyProfilingDisabled
+
+API-Based Profiling is not enabled on the Configuration Profile.
+
+# guidance.apiOnlyProfilingDisabledAction
+
+Navigate to Setup > Custom Metadata Types > Cuneiform Configuration Profile to enable API-Based Profiling.
+
+# guidance.selfRegistrationDisabled
+
+CLI Self-Provisioning is not enabled on the Configuration Profile.
+
+# guidance.selfRegistrationDisabledAction
+
+Ask your Salesforce administrator to enable "Enable API Profiling Self-Registration" in the Cuneiform Configuration Profile (Custom Metadata), or request they assign the API-Based Profiling permission set to you directly.
+
+# guidance.noConfigProfile
+
+No active Configuration Profile found.
+
+# guidance.noConfigProfileAction
+
+This may indicate an access issue — contact your Salesforce administrator. See: https://peernova.link/cli/configure
+
+# output.headerTitle
+
+User Details
+
+# output.userIdentity.title
+
+User Identity
+
+# output.userIdentity.id
+
+ID
+
+# output.userIdentity.username
+
+Username
+
+# output.userIdentity.email
+
+Email
+
+# output.userIdentity.profile
+
+Profile
+
+# output.userIdentity.role
+
+Role
+
+# output.userIdentity.noRole
+
+(none)
+
+# output.readiness.header
+
+Cuneiform Readiness
+
+# output.readiness.status
+
+Status
+
+# output.readiness.notInstalled
+
+NOT INSTALLED
+
+# output.readiness.detail
+
+Detail
+
+# output.readiness.ready
+
+READY
+
+# output.readiness.notReady
+
+NOT READY
+
+# output.readiness.permissionSets
+
+Permission Sets:
+
+# output.readiness.configProfile
+
+Configuration Profile (%s):
+
+# output.readiness.unknown
+
+Unknown
+
+# output.readiness.globalProfiling
+
+API-Based Profiling Enabled
+
+# output.readiness.selfRegistration
+
+CLI Self-Provisioning Enabled
+
+# output.readiness.noActiveProfile
+
+No active configuration profile
+
+# output.readiness.warnings
+
+Warnings
+
+# output.guidance.header
+
+Resolution Guidance
+
+# output.action.wouldAssign
+
+Would Assign Permission Set: %s
+
+# output.action.assign
+
+Assigned Permission Set: %s
+
+# output.action.alreadyAssigned
+
+Permission Set %s Already Assigned
+
+# output.action.alreadyEnabled
+
+API-Based Profiling already enabled on the Configuration Profile
+
+# output.action.wouldEnable
+
+Would enable API-Based Profiling on the Configuration Profile
+
+# output.action.enable
+
+Enabled API-Based Profiling on the Configuration Profile
+
+# output.jobIdSuffix
+
+(Job ID: %s)
+
+# errors.userInfoFailed
+
+Failed to retrieve user information
+
+# errors.readinessFailed
+
+Failed to check user readiness
+
+# errors.configurationFailed
+
+User configuration failed. Check the error details and try again.
+
+# errors.cuneiformNotInstalled
+
+Cuneiform for Salesforce is not installed in this org. Install the Cuneiform for Salesforce package before running this command.
+
+# flags.unconfigure.summary
+
+Reverse a previous --configure by removing the permission set assignment and disabling API-Based Profiling on the Configuration Profile. Use this when decommissioning an environment or cleaning up access after testing.
+
+# info.userUnconfigured
+
+This user is no longer configured for remote profiling via Cuneiform for Salesforce.
+
+# info.unconfigureStart
+
+Removing remote profiling configuration (this may take 10–30 seconds)...
+
+# info.unconfigureComplete
+
+Configuration removed: %s applied.
+
+# output.action.wouldUnassign
+
+Would Unassign Permission Set: %s
+
+# output.action.unassign
+
+Unassigned Permission Set: %s
+
+# output.action.alreadyUnassigned
+
+Permission Set %s Already Unassigned
+
+# output.action.wouldDisable
+
+Would disable API-Based Profiling on the Configuration Profile
+
+# output.action.disable
+
+Disabled API-Based Profiling on the Configuration Profile
+
+# output.action.alreadyDisabled
+
+API-Based Profiling already disabled on the Configuration Profile
+
+# errors.orgConnectionFailed
+
+Could not connect to the Salesforce org "%s".
+
+The org may be expired, deleted, or your authentication session may have ended.
+
+What to try:
+
+1. Verify the org exists and is not expired:
+
+   sf org list
+
+2. Check the org connection details:
+
+   sf org display --target-org %s
+
+3. Re-authenticate if your session has ended:
+
+   sf org login web
+
+4. Specify a different org:
+
+   sf cuneiform user details --target-org <username>
+
+If these steps don't resolve the issue, re-run with --json and contact your Salesforce administrator with the output.
+
+# errors.orgApiFailed
+
+Could not retrieve data from the Salesforce org "%s".
+
+The connection was established, but an API error occurred — this may indicate insufficient permissions or a temporary service issue.
+
+What to try:
+
+1. Verify the org is accessible:
+
+   sf org display --target-org %s
+
+2. Check your user permissions:
+
+   sf org open --target-org %s --path /lightning/setup/PermSets/home
+
+3. Retry the command in case of a transient issue.
+
+4. Contact your Salesforce administrator if the problem persists.
+
+If these steps don't resolve the issue, re-run with --json and contact your Salesforce administrator with the output.