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

package/LICENSE

@@ -1,36 +1,87 @@
-Cuneiform CLI - Proprietary Software License
+Cuneiform for Salesforce CLI — Proprietary Software License
 
-Copyright (c) 2025 PeerNova, Inc. All Rights Reserved.
+Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
 
 TERMS AND CONDITIONS
 
-1. GRANT OF LICENSE
-   This software is licensed, not sold. Subject to a valid Cuneiform
-   subscription agreement, PeerNova, Inc. grants you a limited, non-exclusive,
-   non-transferable license to use this software solely in connection
-   with Cuneiform products.
+1. PROPRIETARY SOFTWARE
+   This software and all associated documentation, source code, and materials
+   ("Software") are the proprietary and confidential property of PeerNova, Inc.
+   This Software is not open source. Access to the source code does not grant
+   any license beyond what is expressly stated herein.
 
-2. RESTRICTIONS
+2. GRANT OF LICENSE
+   Subject to a valid, executed Master Subscription Agreement ("MSA") between
+   you (or your organization) and PeerNova, Inc., PeerNova grants you a limited,
+   non-exclusive, non-transferable, non-sublicensable license to use this
+   Software solely in connection with Cuneiform for Salesforce products and
+   services as specified in your MSA.
+
+   If you do not have a separate written agreement with PeerNova, your use of
+   Cuneiform for Salesforce is governed by the terms available at:
+   https://peernova.com/legal-cfsf/msa/
+
+3. NO LICENSE WITHOUT AGREEMENT
+   If you are not a current PeerNova customer with an active MSA, you have no
+   right to use, copy, modify, or distribute this Software. If you have received
+   access to this Software without an active MSA, you must cease all use
+   immediately and contact PeerNova at sfsupport@peernova.com to arrange
+   proper licensing.
+
+4. RESTRICTIONS
    You may NOT:
-   - Modify, adapt, or create derivative works
-   - Reverse engineer, decompile, or disassemble
-   - Remove or alter proprietary notices
-   - Redistribute, sublicense, or transfer
-   - Use without a valid Cuneiform subscription
-
-3. NO WARRANTY
-   THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
-   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-
-4. LIMITATION OF LIABILITY
-   IN NO EVENT SHALL PEERNOVA, INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-   DEALINGS IN THE SOFTWARE.
-
-5. TERMINATION
-   This license terminates automatically if you violate any terms
-   or if your Cuneiform subscription expires or is terminated.
-
-For licensing inquiries: legal@peernova.com
+   - Modify, adapt, translate, or create derivative works of this Software
+   - Reverse engineer, decompile, disassemble, or otherwise attempt to derive
+     the source code (except to the extent expressly permitted by applicable law)
+   - Remove, alter, or obscure any proprietary notices, labels, or marks
+   - Redistribute, sublicense, rent, lease, lend, or transfer this Software
+     to any third party
+   - Use this Software for any purpose not expressly authorized by your MSA
+   - Use this Software to develop competing products or services
+
+5. CONFIDENTIALITY
+   This Software contains trade secrets and confidential information of
+   PeerNova, Inc. You agree to maintain the confidentiality of the Software
+   and not disclose it to any third party without PeerNova's prior written
+   consent, subject to the terms of your MSA.
+
+6. NO WARRANTY
+   THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. PEERNOVA, INC.
+   DOES NOT WARRANT THAT THE SOFTWARE WILL MEET YOUR REQUIREMENTS OR THAT
+   ITS OPERATION WILL BE UNINTERRUPTED OR ERROR-FREE.
+
+7. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL PEERNOVA, INC. BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS,
+   REVENUE, DATA, OR DATA USE, ARISING OUT OF OR IN CONNECTION WITH THIS
+   SOFTWARE, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, EVEN IF
+   PEERNOVA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. PEERNOVA'S
+   TOTAL LIABILITY SHALL NOT EXCEED THE AMOUNTS PAID BY YOU UNDER YOUR MSA
+   DURING THE TWELVE (12) MONTHS PRECEDING THE CLAIM.
+
+8. TERMINATION
+   This license terminates automatically if:
+   - You violate any term of this license or your MSA
+   - Your MSA expires or is terminated for any reason
+   - You fail to maintain an active Cuneiform for Salesforce subscription
+
+   Upon termination, you must cease all use of the Software and destroy all
+   copies in your possession.
+
+9. GOVERNING LAW
+   This license shall be governed by and construed in accordance with the
+   laws specified in your MSA. In the absence of an MSA, the laws of the
+   State of California, United States, shall apply.
+
+10. ENTIRE AGREEMENT
+    This license, together with your MSA, constitutes the entire agreement
+    between you and PeerNova, Inc. regarding the Software. In the event of
+    any conflict between this license and your MSA, the terms of the MSA
+    shall prevail.
+
+For licensing inquiries: sfsupport@peernova.com
+For legal questions: legal@peernova.com
+
+Master Subscription Agreement: https://peernova.com/legal-cfsf/msa/

package/README.md

@@ -1,203 +1,237 @@
-# @peernova/cuneiform-sf
+# Cuneiform for Salesforce CLI
 
-[![NPM](https://img.shields.io/npm/v/@peernova/cuneiform-sf.svg?label=@peernova/cuneiform-sf)](https://www.npmjs.com/package/@peernova/cuneiform-sf) [![Downloads/week](https://img.shields.io/npm/dw/@peernova/cuneiform-sf.svg)](https://npmjs.org/package/@peernova/cuneiform-sf) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/salesforcecli/@peernova/cuneiform-sf/main/LICENSE.txt)
+> **Know what your Salesforce data is actually doing — before you deploy Agentforce, plan a migration, or prioritize data quality.**
 
-## Using the template
+`@peernova/cuneiform-sf` is the Salesforce CLI plugin for [Cuneiform for Salesforce](https://peernova.com). It profiles objects, fields, and value usage patterns directly from your org — and turns what used to be six weeks of manual audit work into a single command.
 
-This repository provides a template for creating a plugin for the Salesforce CLI. To convert this template to a working plugin:
+Built for Salesforce Admins, Analysts, Architects, and SI consultants who need evidence — not assumptions.
 
-1. Please get in touch with the Platform CLI team. We want to help you develop your plugin.
-2. Generate your plugin:
+---
 
-   ```
-   sf plugins install dev
-   sf dev generate plugin
+## What does it do?
 
-   git init -b main
-   git add . && git commit -m "chore: initial commit"
-   ```
+Cuneiform answers three questions about your Salesforce data:
 
-3. Create your plugin's repo in the salesforcecli github org
-4. When you're ready, replace the contents of this README with the information you want.
+| Phase        | Question                               | Commands                                                                                             |
+| ------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Discover** | What's in this org?                    | `org details`, `object list`, `object describe`                                                      |
+| **Profile**  | What does the data actually look like? | `definition create`, `profile`                                                                       |
+| **Operate**  | How do we manage this over time?       | `definition export/import`, `definition purge`, `summary purge`, `summary stop`, `summary reprofile` |
 
-## Learn about `sf` plugins
+Common use cases:
 
-Salesforce CLI plugins are based on the [oclif plugin framework](<(https://oclif.io/docs/introduction.html)>). Read the [plugin developer guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_plugins.meta/sfdx_cli_plugins/cli_plugins_architecture_sf_cli.htm) to learn about Salesforce CLI plugin development.
+- **Before an Agentforce rollout** — identify which fields are empty, undescribed, or carry no signal before your agent starts reading them
+- **Before a migration** — understand record volume, field population rates, and data age distribution across objects
+- **Data quality prioritization** — find the dead weight: fields that have been empty since the org went live
 
-This repository contains a lot of additional scripts and tools to help with general Salesforce node development and enforce coding standards. You should familiarize yourself with some of the [node developer packages](#tooling) used by Salesforce.
+---
 
-Additionally, there are some additional tests that the Salesforce CLI will enforce if this plugin is ever bundled with the CLI. These test are included by default under the `posttest` script and it is required to keep these tests active in your plugin if you plan to have it bundled.
-
-### Tooling
-
-- [@salesforce/core](https://github.com/forcedotcom/sfdx-core)
-- [@salesforce/kit](https://github.com/forcedotcom/kit)
-- [@salesforce/sf-plugins-core](https://github.com/salesforcecli/sf-plugins-core)
-- [@salesforce/ts-types](https://github.com/forcedotcom/ts-types)
-- [@salesforce/ts-sinon](https://github.com/forcedotcom/ts-sinon)
-- [@salesforce/dev-config](https://github.com/forcedotcom/dev-config)
-- [@salesforce/dev-scripts](https://github.com/forcedotcom/dev-scripts)
-
-### Hooks
-
-For cross clouds commands, e.g. `sf env list`, we utilize [oclif hooks](https://oclif.io/docs/hooks) to get the relevant information from installed plugins.
-
-This plugin includes sample hooks in the [src/hooks directory](src/hooks). You'll just need to add the appropriate logic. You can also delete any of the hooks if they aren't required for your plugin.
-
-# Everything past here is only a suggestion as to what should be in your specific plugin's description
-
-This plugin is bundled with the [Salesforce CLI](https://developer.salesforce.com/tools/sfdxcli). For more information on the CLI, read the [getting started guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_intro.htm).
-
-We always recommend using the latest version of these commands bundled with the CLI, however, you can install a specific version or tag if needed.
-
-## Prerequisites
-
-### SFDMU (SFDX Data Move Utility)
+## Install
 
-This plugin requires the SFDMU plugin for data export/import operations. Install it before using the Cuneiform data migration commands:
+The plugin runs on top of the Salesforce CLI (`sf`). Install all three components:
 
 ```bash
+# 1. Install the Salesforce CLI
+npm install -g @salesforce/cli
+
+# 2. Install SFDMU (required dependency for definition export/import)
 sf plugins install sfdmu
+
+# 3. Install the Cuneiform plugin
+sf plugins install @peernova/cuneiform-sf
 ```
 
-Verify the installation:
+**Verify everything is working:**
 
 ```bash
-sf sfdmu --help
+sf --version
+sf plugins | grep sfdmu   # should show sfdmu 5.x.x
+sf cuneiform --help
 ```
 
-For more information about SFDMU, visit: https://help.sfdmu.com
-
-## Install
+> **Note:** SFDMU must be version 5.x.x or higher. If you see 4.x, run: `sf plugins install sfdmu@5.6.0`
 
-```bash
-sf plugins install @peernova/cuneiform-sf@x.y.z
-```
+---
 
-## Issues
+## Before You Run Any Command
 
-Please report any issues at https://github.com/forcedotcom/cli/issues
+Two one-time setup steps are required. Skipping them causes E4656 "access denied" on almost every command.
 
-## Contributing
+### Step 1 — Admin enables API Profiling (once per org)
 
-1. Please read our [Code of Conduct](CODE_OF_CONDUCT.md)
-2. Create a new issue before starting your project so that we can keep track of
-   what you are trying to add/fix. That way, we can also offer suggestions or
-   let you know if there is already an effort in progress.
-3. Fork this repository.
-4. [Build the plugin locally](#build)
-5. Create a _topic_ branch in your fork. Note, this step is recommended but technically not required if contributing using a fork.
-6. Edit the code in your fork.
-7. Write appropriate tests for your changes. Try to achieve at least 95% code coverage on any new code. No pull request will be accepted without unit tests.
-8. Sign CLA (see [CLA](#cla) below).
-9. Send us a pull request when you are done. We'll review your code, suggest any needed changes, and merge it in.
+A Salesforce Administrator must do this in the target org:
 
-### CLA
+1. **Setup → Cuneiform Settings**
+2. Enable both checkboxes:
+   - ✅ Enable API Profiling
+   - ✅ Allow CLI Profile Requests
+3. **Save**
 
-External contributors will be required to sign a Contributor's License
-Agreement. You can do so by going to https://cla.salesforce.com/sign-cla.
+> ⚠️ **Checkboxes not visible?** This happens when the Cuneiform package was upgraded from an older version — the Custom Metadata layout doesn't update automatically. The admin needs to go to Setup → Custom Metadata Types → Cuneiform Configuration Profile → edit the page layout manually to add the missing fields.
 
-### Build
+### Step 2 — Configure your CLI user (once per user)
 
-To build the plugin locally, make sure to have yarn installed and run the following commands:
+Each person who will run commands does this once on their own machine:
 
 ```bash
-# Clone the repository
-git clone git@github.com:salesforcecli/@peernova/cuneiform-sf
-
-# Install the dependencies and compile
-yarn && yarn build
+sf cuneiform user details --target-org myOrg --configure
 ```
 
-To use your plugin, run using the local `./bin/dev` or `./bin/dev.cmd` file.
+Verify it worked:
 
 ```bash
-# Run using local run file.
-./bin/dev hello world
+sf cuneiform user details --target-org myOrg
 ```
 
-There should be no differences when running via the Salesforce CLI or using the local run file. However, it can be useful to link the plugin to do some additional testing or run your commands from anywhere on your machine.
+Look for `READY` in the output. If you see NOT READY, it will tell you exactly what's missing.
 
-```bash
-# Link your plugin to the sf cli
-sf plugins link .
-# To verify
-sf plugins
-```
+---
 
-## Commands
+## Your First Profile in 5 Commands
 
-<!-- commands -->
+```bash
+# 1. Authenticate to your org
+sf org login web --alias myOrg
 
-- [`sf cuneiform about`](#sf-cuneiform-about)
-- [`sf hello world`](#sf-hello-world)
+# 2. Confirm everything is set up correctly
+sf cuneiform user details --target-org myOrg --configure
 
-## `sf cuneiform about`
+# 3. See what's in the org
+sf cuneiform object list --target-org myOrg --with-records
 
-Summary of a command.
+# 4. Create a profiling definition (start with metadata — it's the fastest)
+sf cuneiform definition create --target-org myOrg --objects Account --method metadata --no-prompt
 
+# 5. Run the profile and check progress
+sf cuneiform profile --target-org myOrg --keys PD-0001
+sf cuneiform profile request list --target-org myOrg
 ```
-USAGE
-  $ sf cuneiform about [--json] [--flags-dir <value>] [-n <value>]
 
-FLAGS
-  -n, --name=<value>  Description of a flag.
+Results appear in the app once profiling completes.
 
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
+---
 
-DESCRIPTION
-  Summary of a command.
+## Profiling Methods
 
-  More information about a command. Don't repeat the summary.
+Always start with `metadata`. It requires no record scanning and is enough for initial discovery.
 
-EXAMPLES
-  $ sf cuneiform about
+| Method        | What it answers                                 | Speed                   |
+| ------------- | ----------------------------------------------- | ----------------------- |
+| `metadata`    | What fields exist and how are they configured?  | Fast — **start here**   |
+| `historical`  | How does field population change over time?     | Medium                  |
+| `comparative` | How does this year compare to last year?        | Medium                  |
+| `recordtype`  | How does data differ by business process stage? | Medium                  |
+| `outcome`     | How does data differ between Won vs Lost?       | Medium                  |
+| `full`        | All of the above                                | Slow — only when needed |
 
-FLAG DESCRIPTIONS
-  -n, --name=<value>  Description of a flag.
-
-    More information about a flag. Don't repeat the summary.
-```
+---
 
-_See code: [src/commands/cuneiform/about.ts](https://github.com/PeerNova-Solutions/cuneiform-cli/blob/1.0.2/src/commands/cuneiform/about.ts)_
+## Compatibility
 
-## `sf hello world`
+Each CLI release requires a minimum version of the Cuneiform managed package in your target org. The package is identified by the `pnova` namespace — if you see `pnova__` prefixed objects or fields in your org, Cuneiform is installed.
 
-Say hello.
+Check compatibility (no authentication needed):
 
+```bash
+sf cuneiform compatibility check
 ```
-USAGE
-  $ sf hello world [--json] [--flags-dir <value>] [-n <value>]
 
-FLAGS
-  -n, --name=<value>  [default: World] The name of the person you'd like to say hello to.
+Check against a specific org:
+
+```bash
+sf cuneiform compatibility check --target-org myOrg
+```
 
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
+| State                       | Exit code | What to do                                     |
+| --------------------------- | --------- | ---------------------------------------------- |
+| `installed-match`           | 0         | Proceed normally.                              |
+| `installed-newer`           | 0         | Proceed, monitor for unexpected behavior.      |
+| `installed-version-unknown` | 0         | Proceed with caution. Common in scratch orgs.  |
+| `installed-older`           | 1         | Ask your Admin to upgrade the managed package. |
+| `not-installed`             | 1         | Ask your Admin to install the managed package. |
 
-DESCRIPTION
-  Say hello.
+> **CI/CD note:** The command exits non-zero when the package is outdated or missing — suitable as a pipeline gate before running profiling jobs.
 
-  Say hello either to the world or someone you know.
+---
 
-EXAMPLES
-  Say hello to the world:
+## MCP Server — Use with AI Assistants
 
-    $ sf hello world
+Cuneiform can expose its capabilities through the [Model Context Protocol](https://modelcontextprotocol.io), letting any MCP-aware AI assistant (Claude, Cursor, and others) answer questions about your org data in plain language — no command syntax required.
 
-  Say hello to someone you know:
+```bash
+sf cuneiform mcp serve --target-org myOrg
+```
 
-    $ sf hello world --name Astro
+Point your AI assistant at the running server and ask things like:
+
+- _"Which fields on Account are sparsely populated?"_
+- _"Which record types haven't been touched in 12 months?"_
+- _"What custom fields on Case have no description?"_
+
+The server uses the same engine as the CLI — anything profileable from the command line is available through your assistant.
+
+---
+
+## All Commands
+
+| Command                               | What it does                                               |
+| ------------------------------------- | ---------------------------------------------------------- |
+| `sf cuneiform compatibility check`    | Verify CLI ↔ managed package version compatibility         |
+| `sf cuneiform org details`            | Full org baseline: edition, features, clouds, API limits   |
+| `sf cuneiform user details`           | Check user readiness; configure required permissions       |
+| `sf cuneiform object list`            | List objects with record counts and namespace filters      |
+| `sf cuneiform object describe`        | Full object deep-dive: fields, record types, data age      |
+| `sf cuneiform definition create`      | Create profiling definitions                               |
+| `sf cuneiform definition list`        | List all definitions with status                           |
+| `sf cuneiform definition get`         | Retrieve definitions by key                                |
+| `sf cuneiform definition update`      | Update definition metadata                                 |
+| `sf cuneiform definition export`      | Export definitions to CSV (do this before sandbox refresh) |
+| `sf cuneiform definition import`      | Restore definitions from CSV                               |
+| `sf cuneiform definition purge`       | Delete definitions (purge summaries first)                 |
+| `sf cuneiform profile`                | Execute profiling — fire-and-forget                        |
+| `sf cuneiform profile request list`   | Track queued, in-progress, and completed requests          |
+| `sf cuneiform profile request cancel` | Cancel queued requests                                     |
+| `sf cuneiform profile request delete` | Remove canceled/rejected request records                   |
+| `sf cuneiform summary stop`           | Halt in-progress profiling (completed fields preserved)    |
+| `sf cuneiform summary reprofile`      | Re-execute failed or stopped profiling                     |
+| `sf cuneiform summary purge`          | Delete profiling results (use `--prune` to keep latest)    |
+| `sf cuneiform mcp serve`              | Start the MCP server for AI assistant integration          |
+
+Append `--help` to any command for the full flag reference. All commands support `--json` for structured output.
+
+---
+
+## Tips
+
+- Run `compatibility check` after every CLI update
+- Always run `user details --configure` first on a new org or user — most errors trace back to missing permissions
+- `definition create` is safe to re-run — existing definitions are skipped automatically
+- Export definitions before every sandbox refresh — they get wiped during refresh
+- Use `summary purge --prune`, not `--all` — prune keeps the latest result set
+- Use `--dry-run` on `definition create` to preview what would be created without writing anything
+
+---
+
+## Troubleshooting
+
+| Error                              | Cause                                                                 | Fix                                                                                                                   |
+| ---------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `--configure command failed`       | Admin checkboxes not enabled                                          | Ask admin to complete First-Time Setup, Step 1                                                                        |
+| Checkboxes not visible in Setup    | Package upgraded from older version; layout not updated automatically | Setup → Custom Metadata Types → Cuneiform Configuration Profile → edit page layout manually to add the missing fields |
+| `E4656 Access denied`              | First-Time Setup not completed                                        | `sf cuneiform user details --target-org myOrg --configure`                                                            |
+| `command not found: sf`            | Salesforce CLI not installed                                          | `npm install -g @salesforce/cli`                                                                                      |
+| `command not found: sf cuneiform`  | Plugin not installed                                                  | `sf plugins install @peernova/cuneiform-sf`                                                                           |
+| Compatibility exit code `1`        | Package outdated or not installed                                     | Ask your Salesforce Admin to install/upgrade the managed package                                                      |
+| `sfdmu version error`              | SFDMU is on 4.x                                                       | `sf plugins install sfdmu@5.6.0`                                                                                      |
+| `myOrg not found`                  | Alias doesn't match `sf org list`                                     | Use the alias shown by `sf org list`                                                                                  |
+| Profile stays in `Queued` > 30 min | API limit or workflow paused                                          | `sf cuneiform org details --target-org myOrg` — check API limits                                                      |
+
+---
 
-FLAG DESCRIPTIONS
-  -n, --name=<value>  The name of the person you'd like to say hello to.
+## Issues
 
-    This person can be anyone in the world!
-```
+Report bugs and request features at https://github.com/PeerNova-Solutions/salesforce-cli/issues
 
-_See code: [src/commands/hello/world.ts](https://github.com/PeerNova-Solutions/cuneiform-cli/blob/1.0.2/src/commands/hello/world.ts)_
+## License
 
-<!-- commandsstop -->
+Proprietary — Copyright © PeerNova, Inc. Available on [Salesforce AppExchange](https://appexchange.salesforce.com). AppExchange Security Review cleared.