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

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,118 @@
+# summary
+
+Update metadata attributes (name, category, time category, segment category, description) on an existing profiling definition.
+
+# description
+
+A profiling definition has two distinct surfaces: its metadata attributes (name, category, time category, segment category, description) and its field selection. This command edits the metadata attributes only — the field selection set at creation time is not mutable through this command.
+
+Supply one or more of the five attribute flags to update exactly those columns; untouched attributes are preserved.
+
+WHAT IT DOES:
+
+- Writes only the supplied attributes; untouched columns are preserved on the record
+- Validates the definition ID format (15 or 18 character Salesforce ID)
+- Enforces length constraints: name, category, time category, segment category max 255 chars; description max 8192 chars
+- Returns the list of attribute names that were written
+
+WHEN TO USE:
+
+- To rename a definition after a scope change or project rebranding
+- To reclassify definitions under a new category for cleaner reporting
+- To assign or update time and segment labels after profiling results are reviewed
+- To add or revise the description for team documentation purposes
+
+NATURAL LANGUAGE → FLAG MAPPING:
+"rename this definition" → --name "New Definition Name"
+"set the category to Revenue" → --category "Revenue"
+"tag this as Q1 2025" → --time-category "Q1 2025"
+"classify as Closed Won accounts" → --segment-category "Closed Won"
+"update the description" → --description "Detailed profiling of high-value accounts"
+
+COMMAND SEQUENCE: `definition get` (retrieve current metadata and definition ID) → `definition update` (update attributes) → `definition list` (confirm updated values)
+
+# 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.name.summary
+
+New definition name (max 255 characters). Replaces the current Prop_Name\_\_c value.
+
+# flags.category.summary
+
+New category label (max 255 characters). Replaces the current Prop_Category\_\_c value. Use to group definitions for reporting.
+
+# flags.time-category.summary
+
+New time category label (max 255 characters). Replaces the current Prop_TimeCategory\_\_c value. Examples: "Q1 2025", "Lifetime", "2024".
+
+# flags.segment-category.summary
+
+New segment category label (max 255 characters). Replaces the current Prop_SegmentCategory\_\_c value. Examples: "Closed Won", "PersonAccounts", "Open Cases".
+
+# flags.description.summary
+
+New description (max 8192 characters). Replaces the current Prop_Description\_\_c value. Supports HTML content.
+
+# flags.format.summary
+
+Output format: table (human-readable, default) or json (structured output for scripting).
+
+# examples
+
+- Rename a definition:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --name "Q1 2025 Revenue Analysis"
+
+- Update the category and time category together:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --category "Revenue" --time-category "Q1 2025"
+
+- Add a segment category to an existing definition:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --segment-category "Closed Won"
+
+- Update all five attributes at once:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --name "Full Profile" --category "Revenue" --time-category "2025" --segment-category "All" --description "Complete revenue profile"
+
+- Output update results as JSON for scripted pipelines:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --id a00000000000001AAA --name "Renamed" --json
+
+# errors.invalidDefinitionId
+
+Invalid definition ID format: %s. Expected a 15 or 18 character Salesforce ID.
+
+# errors.noAttributesProvided
+
+No attributes provided. Supply at least one of: --name, --category, --time-category, --segment-category, --description.
+
+# errors.nameTooLong
+
+--name value exceeds maximum length of 255 characters (received %s characters).
+
+# errors.categoryTooLong
+
+--category value exceeds maximum length of 255 characters (received %s characters).
+
+# errors.timeCategoryTooLong
+
+--time-category value exceeds maximum length of 255 characters (received %s characters).
+
+# errors.segmentCategoryTooLong
+
+--segment-category value exceeds maximum length of 255 characters (received %s characters).
+
+# errors.descriptionTooLong
+
+--description value exceeds maximum length of 8192 characters (received %s characters).
+
+# 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