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

package/messages/object.describe.md

@@ -0,0 +1,205 @@
+# 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 and expand the Relationships and Lookups tables to show all rows (no truncation). Use with `--field-type`, `--field-pattern`, and `--sort` to filter and organize the field 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
+
+- Full relationship listing — expand the Relationships and Lookups tables to show all rows (suppresses the "... (N more)" truncation):
+
+  <%= config.bin %> <%= command.id %> --object Case --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

package/messages/object.list.md

@@ -0,0 +1,463 @@
+# summary
+
+Enumerate Salesforce objects with record counts, type classifications, and namespace distribution — so you can identify which objects hold customer data and focus profiling on what matters.
+
+# description
+
+A typical Salesforce org contains 500 to 2,000 objects. Most are empty platform objects, managed package internals, or system metadata. Finding the objects that actually hold customer data — the ones worth profiling — requires navigating Object Manager, running SOQL counts, and cross-referencing namespace prefixes. This command transforms that exploration into a single call with filter flags and enrichment options.
+
+The default customer-facing classification filter focuses attention on objects most likely relevant for profiling scope decisions. Record counts distinguish populated objects from empty shells. Namespace distribution reveals how the org's data is partitioned across standard Salesforce, industry clouds, managed packages, and custom development.
+
+**Six output sections:**
+
+- **Org Identity** — org name, edition, instance URL
+- **Summary Statistics** — total objects, objects with records, standard/custom/external counts, namespace distribution
+- **Namespace Distribution** — objects grouped by standard, industry, managed, and custom categories
+- **Objects Table** — name, label, record count, type, namespace — plus optional enrichment columns
+- **Contact Points** — email, phone, and URL field details (when `--with-contact-points` is specified)
+- **Next Steps** — `object describe` for field-level deep dives, `definition create` for profiling scope
+
+NATURAL LANGUAGE → FLAG MAPPING:
+
+"Which objects have data?" → `--with-records`
+"What custom objects exist?" → `--filter custom`
+"What did CPQ add to this org?" → `--namespace SBQQ`
+"Which objects match a name?" → `--pattern Account*`
+"Which objects have meaningful volume?" → `--min-records 1000`
+"Which objects can be assigned to users?" → `--with-owner`
+"Which objects have record type segmentation?" → `--with-record-types`
+"Where are email, phone, and address fields?" → `--with-contact-points`
+"How complex is each object?" → `--with-fields`
+"Which objects reference other objects?" → `--with-references`
+
+**How this differs from `object describe`:** This command shows the broad inventory across many objects. Use `object describe` when you need the deep dive on a specific object's fields, record types, relationships, and data age.
+
+Read-only. Does not create, modify, or delete records or metadata. Results default to customer-facing classification, sorted by record count descending, paginated at 50 with a visible notice when more exist.
+
+COMMAND SEQUENCE: `org details` (understand the org landscape) → `object list` (identify objects of interest) → `object describe` (deep dive on specific objects) → `definition create` (define profiling scope)
+
+# flags.target-org.summary
+
+List objects from this Salesforce org. Specify the org alias or username when you have multiple authenticated orgs.
+
+# flags.object.summary
+
+Fetch a single object by API name — bypasses all filters and the limit cap, and always returns the real record count. Use this when you know the exact object you need (e.g., `--object Lead`). Mutually exclusive with --filter (non-default), --namespace, --pattern, --without-records, and --min-records.
+
+# flags.filter.summary
+
+Filter by object type: `standard`, `custom`, or `all`. Use `custom` to audit custom data model objects or `standard` to focus on platform objects. Defaults to `all`.
+
+# flags.namespace.summary
+
+Filter by namespace prefix (case-insensitive). Accepts a single namespace (`SBQQ`), a comma-separated list (`SBQQ,FinServ`), or the `all` sentinel to disable namespace filtering. Use an empty string for unmanaged objects only.
+
+# flags.pattern.summary
+
+Filter by API name pattern with wildcard support. Examples: `Account*` matches Account and AccountContactRelation; `*__c` matches custom objects.
+
+# flags.with-records.summary
+
+Show only objects that contain data (record count > 0). Filters out empty platform infrastructure and focuses on populated objects worth profiling.
+
+# flags.without-records.summary
+
+Show only empty objects (record count = 0). Identifies unused objects during org cleanup or newly provisioned objects awaiting data.
+
+# flags.with-owner.summary
+
+Show only objects with an OwnerId field — objects whose records can be assigned to users. Identifies ownership-trackable data for profiling scope.
+
+# flags.with-record-types.summary
+
+Show only objects with record types defined. Record types indicate segmented data entry or business processes — relevant for deciding whether to use record-type-based profiling.
+
+# flags.with-business-process.summary
+
+Add a business process count column showing lifecycle processes (Lead, Opportunity, Case, Solution). Identifies objects with stage-based workflows before profiling.
+
+# flags.with-fields.summary
+
+Add field count columns (total fields and custom fields) to gauge object complexity. Identifies objects with large field inventories before running `object describe`.
+
+# flags.with-references.summary
+
+Add a reference/lookup field count column. High reference counts indicate hub objects in the data model with dense relationship networks.
+
+# flags.classification.summary
+
+Object classification filter: `customer` (customer-facing objects most relevant to profiling, the default), `internal` (system/platform objects), or `all`. The customer-facing filter uses heuristics based on object type, namespace, and naming patterns.
+
+# flags.with-contact-points.summary
+
+Add contact point columns showing email, phone, and URL field counts per object. Discovers identity resolution candidates before a contact point analysis engagement.
+
+# flags.min-records.summary
+
+Minimum record count threshold. Show only objects with at least this many records (e.g., `--min-records 1000` to focus on high-volume objects).
+
+# flags.sort.summary
+
+Sort results by: `name` (alphabetical), `recordCount` (highest first, the default), or `label`.
+
+# flags.limit.summary
+
+Maximum objects to display (1-200, default: 50). A notice appears when results are truncated — increase to see more, or use --pattern / --object to bypass this cap entirely.
+
+# examples
+
+- Explore a new org — see customer-facing objects sorted by data volume (the default starting point):
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Custom object audit — inventory custom objects for a handoff document or data model review:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --filter custom
+
+- Namespace-focused scope — see how Financial Services Cloud objects are populated:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --namespace FinServ --with-fields --with-record-types
+
+- Multi-package scope — combine Financial Services Cloud and CPQ in one listing:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --namespace FinServ,SBQQ
+
+- Disable namespace filtering explicitly — list every namespace including unmanaged:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --namespace all
+
+- Profiling candidates — focus on high-volume objects worth profiling:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --with-records --min-records 1000 --sort recordCount
+
+- Contact point discovery — find objects with email, phone, or address fields before an analysis engagement:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --with-contact-points --with-records
+
+- Complexity assessment — add field and reference counts to identify hub objects in the data model:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --with-fields --with-references --with-records
+
+# output.title
+
+Cuneiform Object Listing for %s (%s)
+
+# 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.mutuallyExclusiveFlags
+
+Cannot specify both %s and %s. These flags are mutually exclusive.
+
+# errors.objectNotFound
+
+Object "%s" was not found in this org. Check the API name spelling and run without --object to browse available objects.
+
+# errors.noTargetOrg
+
+Could not determine target org username
+
+# errors.orgIdentityFailed
+
+Could not retrieve org identity
+
+# output.summary.header
+
+Summary
+
+# output.summary.totalObjects
+
+Total Objects
+
+# output.summary.withRecords
+
+With Records
+
+# output.summary.withoutRecords
+
+Without Records
+
+# output.summary.standard
+
+Standard
+
+# output.summary.custom
+
+Custom
+
+# output.summary.withRecordTypes
+
+With Record Types
+
+# output.summary.withOwner
+
+With Owner
+
+# output.summary.external
+
+External
+
+# output.summary.withNamespace
+
+With Namespace
+
+# output.summary.withoutNamespace
+
+Without Namespace
+
+# output.namespaceDistribution.header
+
+Namespace Distribution
+
+# output.namespaceDistribution.noNamespace
+
+No Namespace
+
+# output.namespaceDistribution.columns.prefix
+
+Prefix
+
+# output.namespaceDistribution.columns.label
+
+Label
+
+# output.namespaceDistribution.columns.count
+
+Count
+
+# output.objects.header
+
+Objects
+
+# output.objects.limitNotice
+
+Displaying the top %s objects. Use --limit to show more or less objects.
+
+# output.objects.totalLabel
+
+Total
+
+# output.objects.unknownRecordCount
+
+—
+
+# output.objects.approximateLegend
+
+~ = approximate count (from the org's record-count hint); run with --with-records for an exact count
+
+# output.objects.noNamespace
+
+No Namespace
+
+# output.objects.typeCustom
+
+Custom
+
+# output.objects.typeStandard
+
+Standard
+
+# output.objects.columns.prefix
+
+Prefix
+
+# output.objects.columns.objectLabel
+
+Object Label
+
+# output.objects.columns.records
+
+Records
+
+# output.objects.columns.recordTypes
+
+Rec. Types
+
+# output.objects.columns.businessProcess
+
+Processes
+
+# output.objects.columns.totalFields
+
+Fields
+
+# output.objects.columns.custom
+
+Custom
+
+# output.objects.columns.reference
+
+Reference
+
+# output.objects.columns.totalCPs
+
+Total CPs
+
+# output.objects.columns.email
+
+Email
+
+# output.objects.columns.phone
+
+Phone
+
+# output.objects.columns.url
+
+Url
+
+# output.contactPoints.header
+
+Contact Point Fields
+
+# output.contactPoints.email
+
+Email
+
+# output.contactPoints.phone
+
+Phone
+
+# output.contactPoints.url
+
+URL
+
+# output.filters.type
+
+Type: %s
+
+# output.filters.namespace
+
+Namespace: %s
+
+# output.filters.pattern
+
+Pattern: %s
+
+# output.filters.withRecords
+
+With records only
+
+# output.filters.withoutRecords
+
+Without records only
+
+# output.filters.withOwner
+
+With OwnerId field
+
+# output.filters.withRecordTypes
+
+With record types
+
+# output.filters.withBusinessProcess
+
+With business processes
+
+# output.filters.withFields
+
+With field counts
+
+# output.filters.withReferences
+
+With reference fields
+
+# output.filters.withContactPoints
+
+With contact points
+
+# output.filters.classification
+
+Classification: %s
+
+# output.filters.minRecords
+
+Min records: %s
+
+# spinner.listing
+
+Listing
+
+# spinner.objectsNoun
+
+objects
+
+# spinner.enriching
+
+Enriching objects
+
+# output.patternHeader
+
+Pattern
+
+# errors.listFailed
+
+Object list failed
+
+# errors.invalidNamespace
+
+%s
+
+# warnings.sortWithoutRecords
+
+Sorting by recordCount without --with-records: all record counts will be 0 and order will be arbitrary. Add --with-records to sort by actual data volume.
+
+# output.entityType
+
+objects
+
+# output.noResults.suggestion
+
+Try relaxing or removing the most restrictive filters
+
+# output.nextSteps.header
+
+Next steps:
+
+# output.nextSteps.describeLabel
+
+Describe %s
+
+# output.nextSteps.describeCommand
+
+sf cuneiform object describe %s --target-org %s
+
+# output.nextSteps.describeCommandNoOrg
+
+sf cuneiform object describe %s --help
+
+# output.nextSteps.definitionCreateLabel
+
+Create a profiling definition
+
+# output.nextSteps.definitionCreateCommand
+
+sf cuneiform definition create --help