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

package/messages/definition.purge.md

@@ -0,0 +1,318 @@
+# summary
+
+Delete profiling definitions that no longer represent current analysis intent — keeping the definition inventory focused on actively profiled objects.
+
+# description
+
+Profiling definitions accumulate over iterative scoping cycles: test definitions, exploration definitions, definitions for objects the team decided not to profile. This command removes them, leaving the inventory focused on current business intent.
+
+Three selection modes: by specific definition key (`--keys`), by composable AND filters (object, pattern, method, category, status, namespace), or all definitions (`--all`). Before deletion, the command pre-categorizes every matched definition into two groups: deletable (no summaries) and blocked by summaries (must run `summary purge` first). A paginated preview table shows this categorization with a can-delete indicator per definition.
+
+IMPORTANT: Definitions with existing summaries must have their summaries purged first. The full cleanup dependency order:
+
+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)
+4. `sf cuneiform definition purge` — remove definitions (requires zero summaries)
+
+THREE SELECTION MODES:
+
+- **By key** (`--keys PD-0001,PD-0003`) — Delete specific definitions. Exclusive mode — all filter flags are ignored.
+- **By filter** (`--objects Account --method metadata`) — Delete definitions matching ALL specified filters (AND logic). Combine --objects, --filter, --pattern, --method, --category, --status, and --namespace.
+- **All** (`--all`) — Delete all eligible definitions. Can be combined with filters to narrow scope.
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"delete the Account definition" → --keys PD-0001 (look up the key with `definition list`)
+"remove all unused definitions" → --all --status "NOT PROFILED"
+"clean up custom object definitions" → --all --filter custom
+"delete metadata-only definitions" → --all --method metadata
+"remove FSC definitions" → --all --namespace FinServ
+"what would be deleted?" → --all --dry-run
+
+COMMAND SEQUENCE: `summary purge` (remove summaries from blocked definitions) → `definition purge --dry-run` (preview) → `definition purge` (execute)
+
+# flags.target-org.summary
+
+Salesforce org to purge definitions from. The command validates Cuneiform installation and permissions before any deletions.
+
+# flags.all.summary
+
+Target all definitions for deletion. Combine with filter flags (--objects, --method, --status, etc.) to narrow scope. Definitions blocked by summaries are reported but not deleted — run `summary purge` for those first.
+
+# flags.keys.summary
+
+Delete specific definitions by key (e.g., --keys PD-0001,PD-0003). Exclusive mode — when --keys is specified, all other filter flags are ignored. Look up definition keys with `definition list`.
+
+# flags.objects.summary
+
+Filter definitions by target object API names (e.g., --objects Account,Contact). Limits deletion to definitions targeting the specified objects.
+
+# flags.filter.summary
+
+Filter definitions by object type: standard or custom. Targets definitions for one category of objects (e.g., --filter custom to clean up custom object definitions after scoping).
+
+# flags.pattern.summary
+
+Filter definitions by name pattern using SOQL LIKE wildcards (e.g., --pattern Account% matches definitions whose name starts with "Account"). Use % for multi-character wildcard and \_ for single-character wildcard.
+
+# flags.method.summary
+
+Filter definitions by profiling method: metadata, historical, or comparative (e.g., --method metadata to remove metadata-only definitions). Targets definitions of a specific analysis type.
+
+# flags.category.summary
+
+Filter definitions by category label (e.g., --category "Phase 1"). Removes definitions from a completed engagement phase or functional area.
+
+# flags.status.summary
+
+Filter definitions by profiling status: "NOT PROFILED", "IN PROGRESS", "COMPLETE", "COMPLETE w/ FAILURES", or "ERROR". Use --status "NOT PROFILED" to target definitions that were created but never executed.
+
+# flags.namespace.summary
+
+Filter definitions by the namespace prefix of their target object (e.g., --namespace FinServ for Financial Services Cloud, --namespace SBQQ for CPQ). Removes definitions for a managed package that is no longer in profiling scope.
+
+# flags.limit.summary
+
+Maximum number of definitions to process per batch (default: 50). Controls batch size for large deletion operations.
+
+# flags.dry-run.summary
+
+Preview what would be deleted without making changes. Shows the same two-category classification (deletable and blocked by summaries) as a real run. Use this first to verify scope and share the preview with stakeholders before committing.
+
+# flags.format.summary
+
+Output format: table (default, human-readable) or json (structured output for scripted pipelines).
+
+# examples
+
+- Preview what would be deleted and what is blocked by summaries:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --dry-run
+
+- Delete specific definitions by key (exclusive mode ignores all filters):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --keys PD-0001,PD-0003
+
+- Remove definitions that were never profiled after exploration:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --status "NOT PROFILED"
+
+- Clean up Financial Services Cloud definitions no longer in profiling scope:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --namespace FinServ
+
+- Remove metadata-only definitions after upgrading to comparative analysis:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --method metadata
+
+- Scripted scratch org reset with JSON output for CI verification:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --all --no-prompt --format json
+
+# errors.noSelectionCriteria
+
+No selection criteria specified. Provide --all, --keys, or filter flags.
+
+# errors.noEligibleDefinitions
+
+No definitions found matching the specified criteria.
+
+# errors.queryFailed
+
+Failed to query definitions: %s
+
+# errors.deleteFailed
+
+Failed to delete definitions: %s
+
+# errors.noTargetOrg
+
+Could not determine target org username.
+
+# blockedBySummaries.header
+
+Blocked by summaries — run `sf cuneiform summary purge` first:
+
+# queued.header
+
+Queued — these definitions have related requests in queue and cannot be deleted yet:
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt and delete immediately. Use for scripted execution in CI pipelines and automation workflows.
+
+# prompt.confirm.singular
+
+Delete this Profiling Definition
+
+# prompt.confirm.plural
+
+Delete these %s Profiling Definitions
+
+# output.noDeletable
+
+Purge cancelled — there are no Profiling Definitions that can be deleted.
+
+# output.cancelled
+
+Purge cancelled. No definitions were deleted.
+
+# spinner.connecting
+
+Connecting
+
+# spinner.retrievingDefinitions
+
+Retrieving Definitions
+
+# spinner.deletingDefinitions
+
+Deleting Definitions
+
+# spinner.status.deleted
+
+deleted
+
+# spinner.status.skipped
+
+skipped
+
+# spinner.status.failed
+
+failed
+
+# spinner.status.queued
+
+queued
+
+# output.initializing
+
+Initializing Profiling Definition Purging %s...
+
+# output.initializing.dryRunMode
+
+(dry run)
+
+# output.definitionsFound.singular
+
+%s definition found
+
+# output.definitionsFound.plural
+
+%s definitions found
+
+# output.noEligible.message
+
+No definitions were found matching the specified criteria.
+
+# output.noEligible.guidance
+
+- Please check your filters and confirm that definitions exist in your Salesforce org.
+
+# output.summaryHeader
+
+Summary
+
+# output.summary.deleted
+
+Deleted:
+
+# output.summary.skipped
+
+Skipped:
+
+# output.summary.failed
+
+Failed:
+
+# output.summary.queued
+
+Queued:
+
+# output.summary.total
+
+Total:
+
+# reason.hasSummaries
+
+Has Summaries
+
+# reason.notFound
+
+Not Found
+
+# reason.lookupFailed
+
+Lookup Failed
+
+# reason.queuedKeyword
+
+has related requests in queue
+
+# table.header.key
+
+Key
+
+# table.header.object
+
+Object
+
+# table.header.category
+
+Category
+
+# table.header.timeCategory
+
+Time Category
+
+# table.header.segmentCategory
+
+Segment Category
+
+# table.header.status
+
+Status
+
+# table.header.deleted
+
+Deleted?
+
+# table.header.canDelete
+
+Can Delete?
+
+# preview.summary
+
+%s to delete, %s blocked by summaries
+
+# dryRun.banner.singular
+
+[DRY RUN] Would delete %s definition. %s blocked by summaries.
+
+# dryRun.banner.plural
+
+[DRY RUN] Would delete %s definitions. %s blocked by summaries.
+
+# table.column.key
+
+KEY
+
+# table.column.name
+
+NAME
+
+# table.column.object
+
+OBJECT
+
+# table.column.status
+
+STATUS
+
+# table.column.action
+
+ACTION
+
+# warnings.limitIgnoredWithAll
+
+--limit is ignored when --all is specified. All eligible records will be processed.

package/messages/definition.update.md

@@ -0,0 +1,80 @@
+# summary
+
+Replace the field list on an existing profiling definition — preserving the definition's key, name, method, category, and profiling history while updating which fields get analyzed.
+
+# description
+
+A profiling definition specifies which fields on a Salesforce object will be analyzed during a profiling run. When a definition is first created, its field list captures a point-in-time snapshot of the object's schema. Schemas evolve — fields are added, deprecated, or reclassified — and the profiling scope needs to evolve with them.
+
+This command replaces the field list on an existing definition. It takes a Salesforce record ID and one or more field API names, then writes the new selection to the definition record via the API. The definition's key, name, object binding, method, category, and profiling history are all preserved — only the field selection changes.
+
+This is a full replacement operation — the new field list replaces the existing one entirely. Include all fields you want profiled, not just additions.
+
+WHAT IT DOES:
+
+- Replaces the definition's selected fields with the specified field API names
+- Deduplicates field names (duplicates are removed, order is preserved)
+- Validates the definition ID format (15 or 18 character Salesforce ID)
+- Returns the updated field count
+- Preserves definition identity: key, name, object, method, category, and profiling history remain intact
+
+WHEN TO USE:
+
+- After deploying new custom fields to a Salesforce object
+- To narrow profiling scope to analytically significant fields after reviewing initial results
+- To expand profiling scope when managed package upgrades add fields
+- When synchronizing definition field lists with current object metadata in CI scripts
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"update the field list for Account definition" → --id <definition-id> --fields Name --fields Email --fields Phone
+"change which fields are profiled" → --id <definition-id> --fields <field1> --fields <field2>
+"sync definition fields with metadata" → --id <definition-id> --fields <all-current-fields>
+"narrow profiling to 10 fields" → --id <definition-id> --fields <field1> ... --fields <field10>
+
+COMMAND SEQUENCE: `definition get` (retrieve current fields and definition ID) → `definition update` (replace field list) → `profile` (re-run profiling with updated scope)
+
+# flags.target-org.summary
+
+Salesforce org containing the definition to update. The command validates permissions before writing.
+
+# flags.id.summary
+
+Salesforce record ID (15 or 18 character) of the profiling definition to update. Retrieve definition IDs with `sf cuneiform definition get` or `sf cuneiform definition list`.
+
+# flags.fields.summary
+
+Field API names to set on the definition. Replaces the existing field list entirely — include all fields you want profiled, not just additions. Repeat the flag for each field (e.g., --fields Name --fields Email --fields Phone). Cross-object fields use dot notation (e.g., Account.Name). Duplicates are automatically removed while preserving order.
+
+# flags.format.summary
+
+Output format: table (human-readable, default) or json (structured output for scripting).
+
+# examples
+
+- Replace the field list on a definition after deploying new custom fields:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --fields Name --fields Email --fields Phone
+
+- Narrow profiling scope to analytically significant fields:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --fields Amount --fields StageName --fields CloseDate --fields Probability
+
+- Include cross-object lookup fields using dot notation:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --fields Name --fields Email --fields Phone --fields Account.Name
+
+- Output update results as JSON for scripted bulk field refresh:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --fields Name --fields Email --json
+
+# errors.invalidDefinitionId
+
+Invalid definition ID format: %s. Expected a 15 or 18 character Salesforce ID.
+
+# errors.noFieldsProvided
+
+No fields provided. Use --fields to specify one or more field API names.
+
+# errors.updateFailed
+
+Failed to update definition %s: %s

package/messages/mcp.serve.md

@@ -0,0 +1,66 @@
+# summary
+
+Start the MCP server to expose 18 Cuneiform tools to AI assistants — enabling natural language org discovery, definition management, and profiling through Claude Desktop, Cursor, or any MCP client.
+
+# description
+
+Starts the Cuneiform MCP (Model Context Protocol) server, exposing Cuneiform CLI capabilities as tools for AI assistants. Once running, an LLM client can query your org, list objects, describe fields, manage definitions, and execute profiling through natural language — using the same permissions as your CLI session.
+
+The server registers tools across categories covering org and metadata discovery, user management, definition lifecycle, definition import/export, analysis, and profiling execution. A system prompt provides LLMs with an incremental exploration workflow for the KYCD journey.
+
+David Chen wires this into Claude Desktop and Cursor workflows — the registered tools give him a well-defined API contract. Marcus Thompson uses it to accelerate org exploration through conversational queries. Andre Robitaille demonstrates MCP integration during workshops, where attendees experience Cuneiform through natural dialogue.
+
+TRANSPORT: The server uses stdio (stdin/stdout) with JSON-RPC 2.0 protocol. Logging goes to stderr (enable with --debug). The stdio transport ensures the server runs locally alongside the Salesforce CLI — same machine, same authenticated session.
+
+This command blocks until the MCP client disconnects. It is designed to be launched by an MCP client (Claude Desktop, Cursor, etc.). The access gate validates Cuneiform permissions at startup — the same gate used by all Cuneiform commands. On access gate failure, the command exits with an error describing the missing permission and how to resolve it via `user details --configure`.
+
+**When to run this command:**
+
+- AI-guided org discovery — let Claude explore a new client org through natural language
+- Hands-free definition creation — describe what you want and let the AI translate to tool calls
+- Training demonstrations — show Cuneiform capabilities through interactive AI conversation
+- Automated workflows — integrate Cuneiform tools into AI agent pipelines
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"start the MCP server" → --target-org myOrg
+"troubleshoot MCP tool calls" → --target-org myOrg --debug
+"pin a specific API version" → --target-org myOrg --api-version 59.0
+
+CONFIGURATION: Add the server to your AI tool's settings. For Claude Desktop, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cuneiform": {
+      "command": "sf",
+      "args": ["cuneiform", "mcp", "serve", "--target-org", "myOrg"]
+    }
+  }
+}
+```
+
+# examples
+
+- Start the MCP server for an org — the standard launch configuration:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Start with debug logging — see tool invocations and parameters on stderr:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --debug
+
+- Pin a specific API version — for consistent behavior across environments:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --api-version 59.0
+
+# flags.target-org.summary
+
+The Salesforce org to connect the MCP server to. The server inherits this org's authentication for all 18 tool invocations. Specify the org alias or username.
+
+# flags.api-version.summary
+
+Override the API version used for Salesforce API requests made through MCP tools. Use when troubleshooting version-specific behavior or testing against a specific API release.
+
+# flags.debug.summary
+
+Enable debug logging to stderr. Shows tool invocations, parameters, and response metadata for troubleshooting MCP communication. stdout remains reserved for MCP protocol traffic.

package/messages/object.describe.md

@@ -0,0 +1,201 @@
+# summary
+
+Retrieve comprehensive object metadata — fields, record types, data age distribution, relationships, and profiling status — to make informed decisions about what and how to profile.
+
+# description
+
+Understanding an object before profiling it is the difference between a targeted assessment and a fishing expedition. Salesforce scatters object metadata across Object Manager, Schema Builder, and Setup. This command consolidates everything into structured sections from a single call:
+
+- **Object Summary** — record count, field totals, type
+- **Record Age Distribution** — year-by-year grid showing when records were created (Cuneiform-exclusive), revealing whether data is actively growing, historical, or stagnant
+- **Record Types** — name, developer name, active status, default flag
+- **Business Processes** — active processes with record type associations and per-process record age grids
+- **Field Summary** — total, standard, custom, formula, lookup counts
+- **Field Type Distribution** — type counts with percentages
+- **Namespace Breakdown** — fields grouped by namespace prefix showing which managed packages contribute fields
+- **External References** — other objects that reference this one via lookups or master-detail
+- **Outbound Lookups** — this object's lookup fields and their target objects
+- **Profiling Status** — existing definitions, summary counts, last profiled date
+- **Field Listing** (opt-in via `--with-fields`) — individual field detail with filtering and sorting
+
+The record age distribution and per-business-process age grids directly inform the choice between metadata, historical, and comparative profiling methods. The profiling status section shows whether definitions already exist, preventing duplicate work.
+
+NATURAL LANGUAGE → FLAG MAPPING:
+
+"Show me the fields" → `--with-fields`
+"Just the lookup fields" → `--with-fields --field-type lookup`
+"Just custom fields" → `--with-fields --field-pattern "*__c"`
+"Sort fields by type" → `--with-fields --sort type`
+"Compare multiple objects" → `--object Account,Contact,Opportunity`
+
+For multiple objects (comma-separated), describes run in parallel with aggregate totals across all objects. Big Objects (**b) and External Objects (**x) are not supported — they lack standard SOQL support.
+
+Read-only. Does not modify objects, fields, or metadata. The access gate validates Cuneiform installation and permissions before queries execute.
+
+COMMAND SEQUENCE: `object list` (identify objects of interest) → `object describe` (deep dive on specific objects) → `definition create` (define profiling scope based on what you learned)
+
+# flags.target-org.summary
+
+Describe objects from this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.object.summary
+
+Object API name(s), comma-separated. Use one name for a complete deep dive or multiple for side-by-side comparison with aggregate totals (e.g., `Account,Contact,Opportunity`).
+
+# flags.with-fields.summary
+
+Include a detailed field listing showing individual fields with API name, label, type, custom flag, and namespace. Use with `--field-type`, `--field-pattern`, and `--sort` to filter and organize the listing.
+
+# flags.field-type.summary
+
+Filter the field listing to a specific type (requires `--with-fields`). Valid types: text, picklist, lookup, number, date, formula, checkbox, id, address. Use `lookup` to map the object's relationship network.
+
+# flags.field-pattern.summary
+
+Filter the field listing by API name pattern with wildcard support (requires `--with-fields`). Examples: `*__c` for custom fields, `pnova__*` for Cuneiform namespace fields.
+
+# flags.sort.summary
+
+Sort the field listing by: `name` (alphabetical, the default), `type` (grouped by field type), or `label`. Requires `--with-fields`.
+
+# examples
+
+- Assess an object before building profiling definitions — see all 11 metadata sections:
+
+  <%= config.bin %> <%= command.id %> --object Account --target-org myOrg
+
+- Compare multiple objects in parallel with aggregate totals for profiling scope decisions:
+
+  <%= config.bin %> <%= command.id %> --object Account,Contact,Opportunity --target-org myOrg
+
+- Full field inventory — add detailed field listings to see every field on the object:
+
+  <%= config.bin %> <%= command.id %> --object Account --with-fields --target-org myOrg
+
+- Relationship mapping — isolate lookup fields to understand the object's position in the data model:
+
+  <%= config.bin %> <%= command.id %> --object Account --with-fields --field-type lookup --sort type --target-org myOrg
+
+- Custom field audit — filter to custom fields for a managed package or customization review:
+
+  <%= config.bin %> <%= command.id %> --object Account --with-fields --field-pattern "\*\_\_c" --target-org myOrg
+
+- JSON for automation — pipe structured metadata to assessment pipelines or architecture documentation:
+
+  <%= config.bin %> <%= command.id %> --object Account --json --target-org myOrg
+
+# 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
+
+# errors.orgIdentityFailed
+
+Could not retrieve org identity information. Continuing without org context.
+
+# output.table.recordTypes.name
+
+Name
+
+# output.table.recordTypes.developerName
+
+Developer Name
+
+# output.table.recordTypes.active
+
+Active
+
+# output.table.recordTypes.default
+
+Default
+
+# output.table.fieldTypes.type
+
+Type
+
+# output.table.fieldTypes.count
+
+Count
+
+# output.table.fieldTypes.percent
+
+Percent
+
+# output.table.namespaces.namespace
+
+Namespace
+
+# output.table.namespaces.fieldCount
+
+Field Count
+
+# output.table.fields.apiName
+
+API Name
+
+# output.table.fields.label
+
+Label
+
+# output.table.fields.type
+
+Type
+
+# output.table.fields.custom
+
+Custom
+
+# output.table.fields.namespace
+
+Namespace
+
+# output.table.relationships.relatedObject
+
+Related Object
+
+# output.table.relationships.field
+
+Field
+
+# output.table.lookups.lookupField
+
+Lookup Field
+
+# output.table.lookups.targetObject
+
+Target Object
+
+# output.table.profilingStatus.name
+
+Definition
+
+# output.table.profilingStatus.lastProfiled
+
+Last Profiled