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

package/messages/summary.reprofile.md

@@ -0,0 +1,150 @@
+# summary
+
+Re-submit failed or stopped profiling summaries for targeted recovery — only the failed and unprocessed fields are re-executed, preserving completed results.
+
+# description
+
+When a profiling run fails due to transient errors or is manually stopped, the resulting summary has gaps — some fields completed, others did not. Those gaps in the KYCD evidence persist until someone acts on them. This command re-submits those summaries for targeted recovery.
+
+Only failed and unprocessed fields are re-executed — previously completed fields are preserved. The existing summary record is reused. No definition recreation or reconfiguration is needed. This is a fire-and-forget operation: after submission, profiling re-executes asynchronously in the org. Use `sf cuneiform definition get` to check profiling status after submission.
+
+STOP + REPROFILE form a natural pair: use `sf cuneiform summary stop` to halt a summary and free resources, then reprofile later to complete the remaining fields. This is the standard recovery pattern for resource management and transient failure recovery.
+
+THREE SELECTION MODES (mutually exclusive):
+
+- **By ID** (`--ids`) — Reprofile specific summaries by Salesforce record ID
+- **All** (`--all`) — Reprofile all eligible (failed/stopped) summaries
+- **By object** (`--objects`) — Reprofile summaries for specific Salesforce objects
+
+Only summaries with failed or stopped (canceled) status are eligible. In-progress and completed summaries are excluded.
+
+WHEN TO USE:
+
+- After stopping summaries — complete the fields that were not yet processed when the stop signal was sent
+- After transient failures — governor limits, API timeouts, or infrastructure interruptions caused partial results
+- Bulk recovery — re-submit all failed summaries in one command after a service disruption
+- Object-targeted recovery — reprofile only the objects that failed while leaving successful ones untouched
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"reprofile everything that failed" → --all
+"reprofile just Account" → --objects Account
+"reprofile this specific summary" → --ids a0Bxx0000001234AAA
+"what would be reprofiled?" → --all --dry-run
+"reprofile without asking" → --all --no-prompt
+
+COMMAND SEQUENCE:
+`summary stop` or failed profiling run → **`summary reprofile`** → `profile request list` (verify re-profiling completed)
+
+# flags.target-org.summary
+
+Re-submit profiling summaries in this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.ids.summary
+
+Reprofile specific summaries by Salesforce record ID (comma-separated). Use for targeted recovery of individual summaries when the failure scope is narrow. Find summary IDs with `definition get`. Mutually exclusive with --all and --objects.
+
+# flags.all.summary
+
+Reprofile all eligible (failed or stopped) summaries across the org. Use for bulk recovery after infrastructure events, transient API failures, or governor limit spikes that affected multiple summaries. Mutually exclusive with --ids and --objects.
+
+# flags.objects.summary
+
+Reprofile summaries targeting specific Salesforce objects by API name (comma-separated). Use when only certain objects need recovery while others completed successfully. Mutually exclusive with --ids and --all.
+
+# flags.dry-run.summary
+
+Preview which summaries would be re-profiled, showing definition key, summary key, object, status, and planned action. Use to assess recovery scope and estimate the re-execution workload before committing.
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt and reprofile immediately. Use in automated recovery scripts or runbooks where interactive prompts are not available.
+
+# examples
+
+- Preview what would be reprofiled — assess recovery scope first:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --dry-run
+
+- Reprofile all failed and stopped summaries — bulk recovery:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all
+
+- Reprofile summaries for a specific object — targeted recovery:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account
+
+- Reprofile specific summaries by ID — surgical recovery:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --ids a0Bxx0000001234AAA,a0Bxx0000005678AAA
+
+- Reprofile summaries for multiple objects:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account,Contact
+
+- Reprofile immediately for automated recovery workflows:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --no-prompt
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# errors.noSelectionCriteria
+
+No selection criteria specified. Provide --ids, --all, or --objects to select summaries.
+
+# errors.mutuallyExclusive
+
+The flags --ids, --all, and --objects are mutually exclusive. Provide only one.
+
+# errors.noEligibleSummaries
+
+No failed or stopped profiling summaries found matching the specified criteria.
+
+# errors.queryFailed
+
+Failed to query summaries: %s
+
+# errors.reprofileFailed
+
+Failed to reprofile summaries: %s
+
+# prompt.confirm.singular
+
+Reprofile this summary?
+
+# prompt.confirm.plural
+
+Reprofile these %s summaries?
+
+# output.noEligible.message
+
+No failed or stopped summaries were found matching the specified criteria.
+
+# output.noEligible.guidance
+
+- Please check your filters and confirm that failed or stopped summaries exist in your Salesforce org.
+
+# output.cancelled
+
+Reprofile cancelled. No summaries were submitted.
+
+# output.dryRunBanner
+
+[DRY RUN] Would reprofile %s summary(ies). No changes made.
+
+# output.summary.submitted
+
+Submitted
+
+# output.summary.failed
+
+Failed
+
+# output.summary.total
+
+Total
+
+# output.summaryHeader
+
+Summary

package/messages/summary.stop.md

@@ -0,0 +1,157 @@
+# summary
+
+Send a stop signal to in-progress profiling summaries — halt execution to free org resources, preserving fields that already completed.
+
+# description
+
+Profiling runs in the background and consumes org resources — API calls, processing time, and storage writes. When a profiling run needs to yield — because of resource contention, a scheduling conflict, or a configuration issue — this command provides immediate control.
+
+The stop signal is sent and the command returns immediately (fire-and-forget). The backend handles the actual halting asynchronously. Fields that completed before the stop are preserved; unprocessed and in-progress fields are marked as failed. The summary status transitions to canceled.
+
+IMPORTANT: This command stops SUMMARIES, not requests. Summaries are the execution records created after a profiling request is processed. To prevent queued requests from being processed, use `sf cuneiform profile request cancel` instead.
+
+STOP vs CANCEL — these address different objects at different lifecycle stages:
+
+- **Cancel** prevents a Request from being processed. No Summary is created.
+- **Stop** halts an active Summary. Partially completed results are preserved.
+
+STOP + REPROFILE form a natural pair: stop a summary to release resources now, then use `sf cuneiform summary reprofile` later to re-execute only the failed and unprocessed fields. The existing summary is reused — no reconfiguration needed.
+
+THREE SELECTION MODES (mutually exclusive):
+
+- **By ID** (`--ids`) — Stop specific summaries by Salesforce record ID
+- **All** (`--all`) — Stop all in-progress summaries
+- **By object** (`--objects`) — Stop summaries for specific Salesforce objects
+
+Only summaries with in-progress profiling status are eligible. Completed, failed, and canceled summaries are excluded.
+
+WHEN TO USE:
+
+- Peak hours resource management — halt profiling to free API capacity, reprofile during off-hours
+- Long-running profiling on a large object — stop one object while others continue
+- Pre-maintenance window — stop active summaries before planned downtime
+- Definition adjustment — stop a run, fix the definition, then reprofile
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"stop everything" → --all
+"stop just Account profiling" → --objects Account
+"stop this specific summary" → --ids a0Bxx0000001234AAA
+"what would be stopped?" → --all --dry-run
+"stop without asking" → --all --no-prompt
+
+COMMAND SEQUENCE:
+`profile request list` (identify resource-consuming runs) → **`summary stop`** → `summary reprofile` (re-execute when conditions are appropriate)
+
+# flags.target-org.summary
+
+Stop profiling summaries in this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.ids.summary
+
+Stop specific profiling summaries by Salesforce record ID (comma-separated). Use for targeted halting when only some summaries need to stop. Find summary IDs with `definition get`. Mutually exclusive with --all and --objects.
+
+# flags.all.summary
+
+Stop all in-progress profiling summaries across the org. Use for peak hours resource management, pre-maintenance windows, or when the org needs its full API capacity immediately. Mutually exclusive with --ids and --objects.
+
+# flags.objects.summary
+
+Stop profiling for specific Salesforce objects by API name (comma-separated). Use when one object is consuming disproportionate resources while profiling on other objects should continue. Mutually exclusive with --ids and --all.
+
+# flags.dry-run.summary
+
+Preview which summaries would be stopped, showing definition key, summary key, object, status, and planned action. Use to verify scope before sending stop signals — especially important with --all.
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt and send stop signals immediately. Use in automated scripts, runbooks, or time-sensitive situations where interactive prompts are not practical.
+
+# examples
+
+- Preview what would be stopped — verify scope before committing:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --dry-run
+
+- Stop all in-progress summaries — free resources during peak hours:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all
+
+- Stop profiling for a specific object while others continue:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account
+
+- Stop specific summaries by ID — targeted precision:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --ids a0Bxx0000001234AAA,a0Bxx0000005678AAA
+
+- Stop profiling for multiple objects at once:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --objects Account,Contact
+
+- Stop immediately for automated runbooks:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --no-prompt
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# errors.noSelectionCriteria
+
+No selection criteria specified. Provide --ids, --all, or --objects to select summaries.
+
+# errors.mutuallyExclusive
+
+The flags --ids, --all, and --objects are mutually exclusive. Provide only one.
+
+# errors.noEligibleSummaries
+
+No in-progress profiling summaries found matching the specified criteria.
+
+# errors.queryFailed
+
+Failed to query summaries: %s
+
+# errors.stopFailed
+
+Failed to stop summaries: %s
+
+# prompt.confirm.singular
+
+Stop profiling for this summary?
+
+# prompt.confirm.plural
+
+Stop profiling for these %s summaries?
+
+# output.noEligible.message
+
+No in-progress summaries were found matching the specified criteria.
+
+# output.noEligible.guidance
+
+- Please check your filters and confirm that in-progress summaries exist in your Salesforce org.
+
+# output.cancelled
+
+Stop cancelled. No summaries were stopped.
+
+# output.dryRunBanner
+
+[DRY RUN] Would stop %s summary(ies). No changes made.
+
+# output.summary.stopped
+
+Stopped
+
+# output.summary.failed
+
+Failed
+
+# output.summary.total
+
+Total
+
+# output.summaryHeader
+
+Summary