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

package/messages/profile.request.cancel.md

@@ -0,0 +1,143 @@
+# summary
+
+Transition queued profiling requests to Canceled status before they begin processing — prevent incorrect or unnecessary requests from generating summaries.
+
+# description
+
+When profiling is triggered, the system creates a request record that tracks execution. Requests begin in a Queued state, waiting for the backend to process them. This command transitions queued requests to Canceled status before processing begins — preventing them from generating summaries that would need to be identified and cleaned up later.
+
+IMPORTANT: Cancel applies to QUEUED requests only. Once a request has been processed and its summary is actively executing, the request is complete. To halt an in-progress summary, use `sf cuneiform summary stop` instead.
+
+TWO SELECTION MODES (mutually exclusive):
+
+- **Broad** (`--all`) — Cancel all cancellable requests (Queued status)
+- **Targeted** (`--request-ids`) — Cancel specific requests by Salesforce record ID
+
+SAFETY: Completed, rejected, and already-canceled requests are automatically excluded. Use --dry-run to preview what would be canceled before committing. A confirmation prompt shows the count before proceeding — use --no-prompt to skip for scripted use.
+
+Cancellation transitions status only — it does not delete records. Canceled requests remain visible in `profile request list` until permanently removed with `profile request delete`.
+
+CANCEL vs STOP — these address different objects at different lifecycle stages:
+
+- **Cancel** prevents a Request from being processed. No Summary is created.
+- **Stop** halts an active Summary that is already executing. Preserves completed fields.
+
+By the time a Summary exists, its originating Request is already complete. These operations do not overlap.
+
+WHEN TO USE:
+
+- Wrong definition submitted — cancel the queued request before it generates incorrect results
+- Pre-maintenance window — clear the queue before planned downtime
+- Configuration issue discovered — pause processing until the issue is resolved
+- Selective cleanup in shared orgs — cancel specific requests by ID while preserving valid requests
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"cancel everything in the queue" → --all
+"cancel just this one request" → --request-ids a0Xxx0000001AAA
+"what would be canceled?" → --all --dry-run
+"cancel without asking" → --all --no-prompt
+
+COMMAND SEQUENCE:
+`profile` or `profile request list` → **`profile request cancel`** → `profile request delete` (remove artifacts) or re-submit with corrected parameters
+
+# flags.target-org.summary
+
+Cancel profiling requests in this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.all.summary
+
+Cancel all queued requests in a single operation. Use for pre-maintenance windows, configuration corrections, or full queue pauses when processing should be deferred. Mutually exclusive with --request-ids.
+
+# flags.request-ids.summary
+
+Cancel specific profiling requests by Salesforce record ID (comma-separated). Use for targeted cancellation when only some queued requests are problematic — preserving valid requests in shared environments. Find request IDs with `profile request list`. Mutually exclusive with --all.
+
+# flags.dry-run.summary
+
+Preview which requests would be canceled, showing the same request details as a real cancellation. Use first in production orgs or shared environments to verify scope before committing — particularly important when other users have valid requests in the queue.
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt and cancel immediately. Use in scripts or automation where interactive prompts are not available. JSON mode also skips the prompt.
+
+# examples
+
+- Preview what would be canceled — verify scope before committing:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --dry-run
+
+- Cancel all queued requests — clear the processing queue before maintenance:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all
+
+- Cancel specific requests by ID — targeted cancellation in shared orgs:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --request-ids a0Xxx0000001AAA,a0Xxx0000002BBB
+
+- Cancel immediately for scripted workflows:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --no-prompt
+
+- Cancel specific requests as JSON output for automation:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --request-ids a0Xxx0000001AAA --json
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# errors.mutuallyExclusive
+
+The --all and --request-ids flags are mutually exclusive. Provide one or the other.
+
+# errors.noSelection
+
+You must provide either --all or --request-ids to specify which requests to cancel.
+
+# errors.cancelFailed
+
+Failed to cancel profiling requests: %s
+
+# errors.noCancellable
+
+No cancellable requests found matching the specified criteria.
+
+# errors.partialFailure
+
+Some requests could not be canceled. %s of %s succeeded.
+
+# errors.invalidIds
+
+Invalid request ID format: %s
+
+# prompt.confirm.singular
+
+Cancel this profiling request?
+
+# prompt.confirm.plural
+
+Cancel these %s profiling requests?
+
+# output.dryRunTitle
+
+Dry Run — Requests That Would Be Canceled
+
+# output.cancelled
+
+Successfully canceled %s profiling request(s).
+
+# output.noCancellable
+
+No cancellable requests found.
+
+# output.dryRunSummary
+
+%s request(s) would be canceled.
+
+# output.userCancelled
+
+Cancellation aborted by user.
+
+# output.failedHeader
+
+Failed to Cancel

package/messages/profile.request.delete.md

@@ -0,0 +1,139 @@
+# summary
+
+Permanently remove canceled and rejected profiling requests — cleaning up terminal request artifacts that never produced a summary.
+
+# description
+
+Every profiling run begins with a request record that tracks who initiated profiling, which definition was targeted, and the execution outcome. Canceled and rejected requests are terminal — they never produced a summary and serve no ongoing purpose. This command permanently removes them.
+
+ELIGIBLE STATUSES: Only Canceled and Rejected requests can be deleted. The eligibility filter is enforced at the query level — Queued and Completed requests are structurally excluded.
+
+PROTECTED STATUSES: Completed requests maintain the profiling user context reference needed for reprofiling. They are cascade-deleted automatically when their summary is purged via `summary purge`. Queued requests must be canceled first with `profile request cancel` before they become eligible for deletion.
+
+TWO SELECTION MODES (mutually exclusive):
+
+- **Broad** (`--all`) — Delete all deletable requests (Canceled and Rejected)
+- **Targeted** (`--request-ids`) — Delete specific requests by Salesforce record ID
+
+LIFECYCLE CONTEXT: Delete removes terminal, summary-less requests:
+
+1. `profile request cancel` — transition queued requests to Canceled status
+2. `profile request delete` — permanently remove Canceled and Rejected requests
+3. `summary purge` — cascade-deletes Completed requests automatically
+
+WHEN TO USE:
+
+- Post-cancellation cleanup — remove canceled request artifacts after resolving the issue
+- Engagement close-out — clean up the request history before org handoff
+- Periodic housekeeping — remove old canceled and rejected requests to keep the request list focused
+- CI pipeline reset — automate scratch org cleanup between test runs
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"delete all processed requests" → --all
+"delete just this one request" → --request-ids a0Xxx0000001AAA
+"what would be deleted?" → --all --dry-run
+"delete without asking" → --all --no-prompt
+
+COMMAND SEQUENCE: `profile request cancel` (cancel queued requests) → `profile request delete` (remove canceled/rejected) → `summary purge` (remove summaries, cascade-delete completed requests) → `definition purge` (remove definitions)
+
+# flags.target-org.summary
+
+Salesforce org containing the profiling requests to delete. The command validates Cuneiform installation before executing.
+
+# flags.all.summary
+
+Delete all deletable requests (Canceled and Rejected status). Targets request artifacts that never produced summaries. Completed requests are excluded — they are cascade-deleted when their summary is purged. Mutually exclusive with --request-ids.
+
+# flags.request-ids.summary
+
+Specific profiling request IDs to delete (e.g., --request-ids a0Xxx0000001AAA,a0Xxx0000002BBB). Targets individual canceled or rejected requests. Look up request IDs with `profile request list`. Mutually exclusive with --all.
+
+# flags.dry-run.summary
+
+Preview what would be deleted without making changes. Shows the same request details and counts as a real deletion. Use this first — deletion is permanent and cannot be undone.
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt and delete immediately. Use for scripted cleanup in CI pipelines and automation workflows. The irreversibility warning is bypassed — the caller accepts permanent deletion programmatically.
+
+# examples
+
+- Preview what would be deleted (deletion is permanent — always preview first):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --dry-run
+
+- Delete all canceled and rejected requests after resolving the underlying issues:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all
+
+- Delete specific requests by ID for targeted cleanup:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --request-ids a0Xxx0000001AAA,a0Xxx0000002BBB
+
+- Scripted scratch org reset in CI pipelines:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --no-prompt
+
+- Capture deletion results as JSON for engagement close-out documentation:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --json
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# errors.mutuallyExclusive
+
+The --all and --request-ids flags are mutually exclusive. Provide one or the other.
+
+# errors.noSelection
+
+You must provide either --all or --request-ids to specify which requests to delete.
+
+# errors.deleteFailed
+
+Failed to delete profiling requests: %s
+
+# errors.noDeletable
+
+No deletable requests found matching the specified criteria.
+
+# errors.partialFailure
+
+Some requests could not be deleted. %s of %s succeeded.
+
+# errors.invalidIds
+
+Invalid request ID format: %s
+
+# prompt.confirm.singular
+
+Permanently delete this profiling request? This action cannot be undone.
+
+# prompt.confirm.plural
+
+Permanently delete these %s profiling requests? This action cannot be undone.
+
+# output.dryRunTitle
+
+Dry Run — Requests That Would Be Deleted
+
+# output.deleted
+
+Successfully deleted %s profiling request(s).
+
+# output.noDeletable
+
+No deletable requests found.
+
+# output.dryRunSummary
+
+%s request(s) would be deleted.
+
+# output.userCancelled
+
+Deletion aborted by user.
+
+# output.failedHeader
+
+Failed to Delete

package/messages/profile.request.list.md

@@ -0,0 +1,89 @@
+# summary
+
+Retrieve profiling request execution records — see which requests are queued, completed, rejected, or canceled across the org.
+
+# description
+
+Profiling requests are the execution records of the KYCD journey — each one tracks who submitted profiling, against which definition, and the outcome. This command retrieves those records and displays them as a six-column table: request name, status, target object, parent definition name, submitted by (user), and created date.
+
+The command is read-only. For cancelling queued requests, use `profile request cancel`. For deleting terminal requests, use `profile request delete`.
+
+LIFECYCLE CONTEXT: Profiling requests are created when `sf cuneiform profile` runs. Each request starts as Queued and ends in one of three terminal states: Completed (summary created and executing independently), Rejected (validation failed or capacity exceeded), or Canceled (user stopped it before processing). There are exactly 4 request statuses.
+
+WHEN TO USE:
+
+- After submitting profiling — "Did my requests complete? Are they still queued?"
+- To triage rejections — filter by Rejected status to isolate problematic requests
+- For multi-user coordination — the submitted-by column shows who triggered each request
+- To check queue depth — see how many requests are waiting to be processed
+
+RELATED COMMANDS:
+
+- `sf cuneiform profile` — creates the requests this command lists
+- `sf cuneiform profile request cancel` — cancel queued requests that should not be processed
+- `sf cuneiform profile request delete` — permanently remove processed requests
+- `sf cuneiform definition get` — check profiling results at the definition level
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"show me all requests" → (no flags, lists all)
+"what's still queued?" → --status Queued
+"were any rejected?" → --status Rejected
+"show canceled requests" → --status Canceled
+"show more results" → --limit 100
+
+COMMAND SEQUENCE:
+`profile` → **`profile request list`** → `profile request cancel` or `summary stop` (when intervention is needed)
+
+# flags.target-org.summary
+
+Retrieve profiling requests from this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.status.summary
+
+Filter by request lifecycle status: Queued (waiting to be processed), Completed (summary created and executing), Rejected (validation failed or capacity exceeded), or Canceled (stopped before processing). There are exactly 4 valid values. Use --status Rejected for triage or --status Queued to check queue depth.
+
+# flags.limit.summary
+
+Control how many requests are displayed per page (default: 25, max: 200). Increase for large profiling runs where 25 results may not show the full picture.
+
+# examples
+
+- List all profiling requests — monitor progress after submitting profiling:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Triage rejected requests — isolate requests that need attention:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --status Rejected
+
+- Check queue depth — see how many requests are waiting for processing:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --status Queued
+
+- Confirm completed requests — verify which requests produced summaries:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --status Completed
+
+- View more results in a large profiling run:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --limit 100
+
+- Produce machine-readable output for scripting or dashboards:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --json
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# errors.queryFailed
+
+Failed to list profiling requests: %s
+
+# output.title
+
+Profiling Requests
+
+# output.noRequests
+
+No profiling requests found.

package/messages/summary.purge.md

@@ -0,0 +1,218 @@
+# summary
+
+Delete profiling summaries and their child records — use --prune to preserve the latest summary per definition while removing older results.
+
+# description
+
+Every profiling run creates a summary — a result record containing Field Results, Value Results, and KPI Results. Over repeated profiling cycles, summaries accumulate. An org with 20 definitions profiled weekly generates over 1,000 summaries per year. The current profiling posture is the latest summary per definition; older summaries are historical artifacts.
+
+This command deletes summaries and their child records from a Salesforce org. The `--prune` flag implements the standard housekeeping pattern: keep the latest summary per definition while removing older results. This is how Marcus Thompson closes engagement phases and how David Chen configures automated weekly cleanup.
+
+**Cleanup dependency order** — summary purge must happen BEFORE definition purge:
+
+1. `sf cuneiform profile request cancel` — cancel queued requests
+2. `sf cuneiform profile request delete` — remove canceled and rejected requests
+3. `sf cuneiform summary purge` — remove summaries (cascade-deletes completed requests; resets definition status to NOT PROFILED when all summaries are removed)
+4. `sf cuneiform definition purge` — remove definitions (requires zero summaries)
+
+THREE SELECTION MODES:
+
+- **By ID** (`--ids`) — Delete specific summaries by Salesforce record ID. Exclusive mode — filter flags are ignored.
+- **By filter** (`--objects`, `--category`, `--is-active`) — Delete summaries matching filters. Summaries are resolved through their parent definitions: the command queries definitions first, then targets their associated summaries.
+- **All** (`--all`) — Delete all eligible summaries. Can be combined with filter flags to narrow scope.
+
+ELIGIBILITY: Only summaries with a terminal profiling status (SUCCESS, COMPLETE w/ FAILURES, FAILED, CANCELED) can be deleted. In-progress summaries are automatically excluded and reported with a reason.
+
+SAFETY: Use --dry-run to preview the scope before deleting. The confirmation prompt shows affected summaries before proceeding. Cascade delete automatically removes child Field Results, Value Results, KPI Results, and related profiling requests (original and reprofile). Definition status resets to NOT PROFILED when all summaries for a definition are removed.
+
+**When to run this command:**
+
+- Post-sprint cleanup — prune intermediate results after iterative profiling cycles
+- Pre-sandbox-refresh storage reduction — free storage before the refresh window
+- Object-targeted cleanup after data model changes — remove stale summaries for redesigned objects
+- Before definition purge — clear summaries as a prerequisite for definition deletion
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"clean up old summaries, keep latest" → --all --prune
+"delete all summaries" → --all
+"delete Account summaries" → --objects Account
+"delete this specific summary" → --ids a0Bxx0000001234AAA
+"what would be deleted?" → --all --dry-run
+"clean up old summaries without asking" → --all --prune --no-prompt
+
+COMMAND SEQUENCE:
+`profile request cancel` → `profile request delete` → `summary purge` → `definition purge`
+
+# flags.target-org.summary
+
+The Salesforce org to purge summaries from. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.all.summary
+
+Target all eligible summaries for deletion. Can be combined with filter flags (--objects, --category, --is-active) to narrow scope. Combine with --prune to preserve the latest summary per definition while removing older results.
+
+# flags.ids.summary
+
+Specific summary record IDs to delete (comma-separated Salesforce record IDs). Exclusive mode — filter flags are ignored when --ids is specified. Use for surgical removal of individual summaries.
+
+# flags.objects.summary
+
+Filter by target object API name (matches the definition's profiled object). Scopes purge to summaries for specific objects (e.g., --objects Account removes only Account-related summaries).
+
+# flags.category.summary
+
+Filter by definition category label (e.g., "Phase 1", "Baseline"). Scopes purge to summaries from a completed engagement phase or functional area.
+
+# flags.is-active.summary
+
+Filter by definition active status. Targets summaries belonging to active or inactive definitions.
+
+# flags.limit.summary
+
+Maximum number of summaries to process per invocation (default: 50). Controls batch size in large cleanup operations. Ignored when --all is specified.
+
+# flags.prune.summary
+
+Preserve the latest summary for each definition and delete only older summaries. This is the standard housekeeping pattern — current profiling evidence is retained while historical results are removed. Combine with --all for org-wide pruning, or with filter flags to prune specific scopes.
+
+# flags.dry-run.summary
+
+Preview what would be deleted, applied to nothing. Shows the same categorization (eligible, skipped by status, preserved by prune) as a real purge. Run this first to verify scope before committing.
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt and delete immediately. Use in scripts and automation pipelines. The prompt normally shows which summaries (and their child records) will be permanently deleted.
+
+# flags.format.summary
+
+Output format: table (default, human-readable) or json (machine-readable for scripting and automation dashboards).
+
+# examples
+
+- Preview what would be deleted — start here to verify scope:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --dry-run
+
+- Standard housekeeping — keep the latest summary per definition, remove older results:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --prune
+
+- Object-targeted cleanup — remove Account summaries after a data model redesign:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account
+
+- Complete cleanup — delete all terminal-state summaries:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all
+
+- Surgical removal — delete specific summaries by record ID:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --ids a0Bxx0000001234AAA,a0Bxx0000005678AAA
+
+- Automated weekly prune — for CI pipelines and scheduled jobs:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --prune --no-prompt --format json
+
+# errors.noSelectionCriteria
+
+No selection criteria specified. Provide --all, --ids, or filter flags (--objects, --category, --is-active).
+
+# errors.mutuallyExclusive
+
+The --ids flag is mutually exclusive with filter flags (--objects, --category, --is-active, --all).
+
+# errors.noEligibleSummaries
+
+No summaries found matching the specified criteria.
+
+# errors.queryFailed
+
+Failed to query summaries: %s
+
+# errors.deleteFailed
+
+Failed to delete summaries: %s
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# output.pruneMode
+
+Prune mode: preserving latest summary per definition.
+
+# prompt.confirm.singular
+
+Delete this Profiling Summary (and its child Field Results, Value Results, and KPI Results)
+
+# prompt.confirm.plural
+
+Delete these %s Profiling Summaries (and their child Field Results, Value Results, and KPI Results)
+
+# output.noDeletable
+
+Purge cancelled — there are no Profiling Summaries that can be deleted.
+
+# output.cancelled
+
+Purge cancelled. No summaries were deleted.
+
+# skippedByStatus.header.singular
+
+Could not delete this Profiling Summary — it has a non-terminal status.
+
+# skippedByStatus.header.plural
+
+Could not delete these Profiling Summaries — they have non-terminal statuses.
+
+# skippedByPrune.header.singular
+
+Preserved this Profiling Summary — it is the latest for its definition.
+
+# skippedByPrune.header.plural
+
+Preserved these Profiling Summaries — they are the latest for their definitions.
+
+# output.noEligible.message
+
+No summaries were found matching the specified criteria.
+
+# output.noEligible.guidance
+
+- Please check your filters and confirm that summaries exist in your Salesforce org.
+
+# output.summary.deleted
+
+Deleted
+
+# output.summary.skipped
+
+Skipped
+
+# output.summary.failed
+
+Failed
+
+# output.summary.total
+
+Total
+
+# output.summaryHeader
+
+Summary
+
+# spinner.status.deleted
+
+deleted
+
+# spinner.status.skipped
+
+skipped
+
+# spinner.status.failed
+
+failed
+
+# warnings.limitIgnoredWithAll
+
+--limit is ignored when --all is specified. All eligible records will be processed.