@peernova/cuneiform-sf 1.0.3-beta.0 → 1.0.4-beta.9

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,163 @@
 # @peernova/cuneiform-sf
 
-[![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)
+[![NPM Version](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://www.npmjs.com/package/@peernova/cuneiform-sf)
+[![License](https://img.shields.io/badge/License-Proprietary-blue.svg)](https://github.com/PeerNova-Solutions/salesforce-cli/blob/development-ai/LICENSE)
 
-## Using the template
+> **Know what your Salesforce data is actually doing — before you deploy Agentforce, plan a migration, or prioritize data quality.**
 
-This repository provides a template for creating a plugin for the Salesforce CLI. To convert this template to a working plugin:
+`@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 gives you evidence for decisions that previously required weeks of manual analysis or specialist data-management expertise.
 
-1. Please get in touch with the Platform CLI team. We want to help you develop your plugin.
-2. Generate your plugin:
+## What is Cuneiform
 
-   ```
-   sf plugins install dev
-   sf dev generate plugin
+Cuneiform is built around a single discipline: **Know Your Customer's Data (KYCD)**. You can't deploy AI, migrate an org, or prioritize remediation if you don't know what's in there. The CLI surfaces that knowledge in three phases:
 
-   git init -b main
-   git add . && git commit -m "chore: initial commit"
-   ```
+| Phase        | Question it answers              | Commands                                                                         |
+| ------------ | -------------------------------- | -------------------------------------------------------------------------------- |
+| **Discover** | What's in this org?              | `cuneiform org details`, `cuneiform object list`, `cuneiform object describe`    |
+| **Profile**  | What does the data look like?    | `cuneiform definition create`, `cuneiform profile`                               |
+| **Operate**  | How do we manage this over time? | `cuneiform definition export/import`, `cuneiform summary`, `cuneiform mcp serve` |
 
-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.
+It's built for Salesforce Admins, Analysts, Architects, and SI consultants who need evidence — population rates, value distributions, usage patterns — not assumptions.
 
-## Learn about `sf` plugins
-
-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.
-
-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.
+## Install
 
-## Prerequisites
+The plugin runs on top of the Salesforce CLI (`sf`). Install both, plus the SFDMU peer dependency:
 
-### SFDMU (SFDX Data Move Utility)
+```bash
+# 1. Install the Salesforce CLI (if you don't have it)
+npm install -g @salesforce/cli
 
-This plugin requires the SFDMU plugin for data export/import operations. Install it before using the Cuneiform data migration commands:
+# 2. Install the Cuneiform plugin
+sf plugins install @peernova/cuneiform-sf
 
-```bash
+# 3. Install SFDMU (required peer dependency for definition import/export)
 sf plugins install sfdmu
 ```
 
-Verify the installation:
+Verify:
 
 ```bash
+sf cuneiform --help
 sf sfdmu --help
 ```
 
-For more information about SFDMU, visit: https://help.sfdmu.com
-
-## Install
+> **SFDMU** ([sfdmu.com](https://help.sfdmu.com)) powers the data-move operations used by `definition export` and `definition import`. It is a required peer dependency.
 
-```bash
-sf plugins install @peernova/cuneiform-sf@x.y.z
-```
-
-## Issues
-
-Please report any issues at https://github.com/forcedotcom/cli/issues
-
-## Contributing
+## Compatibility
 
-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.
+Each CLI release expects a minimum version of the **Cuneiform For Salesforce** managed package installed in your target org. This package is identified by the Salesforce namespace `pnova` — if you see `pnova__` prefixed objects or fields in your org, Cuneiform is installed. The required version is published in this package's `package.json` under `cuneiform.requiredAppVersion`:
 
-### CLA
-
-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.
-
-### Build
-
-To build the plugin locally, make sure to have yarn installed and run the following commands:
-
-```bash
-# Clone the repository
-git clone git@github.com:salesforcecli/@peernova/cuneiform-sf
-
-# Install the dependencies and compile
-yarn && yarn build
+```jsonc
+{
+  "name": "@peernova/cuneiform-sf",
+  "cuneiform": {
+    "requiredAppVersion": "4.12.0.17"
+  }
+}
 ```
 
-To use your plugin, run using the local `./bin/dev` or `./bin/dev.cmd` file.
+Check what this CLI build expects (no auth, no API calls):
 
 ```bash
-# Run using local run file.
-./bin/dev hello world
+sf cuneiform compatibility check
 ```
 
-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.
+Verify a specific org meets the minimum:
 
 ```bash
-# Link your plugin to the sf cli
-sf plugins link .
-# To verify
-sf plugins
+sf cuneiform compatibility check --target-org my-org
 ```
 
-## Commands
-
-<!-- commands -->
-
-- [`sf cuneiform about`](#sf-cuneiform-about)
-- [`sf hello world`](#sf-hello-world)
-
-## `sf cuneiform about`
-
-Summary of a command.
+The command exits non-zero when the installed version is older than required or the managed package is not installed — suitable for CI gates that run profiling after a fresh package install.
 
-```
-USAGE
-  $ sf cuneiform about [--json] [--flags-dir <value>] [-n <value>]
+| State                       | Exit | Meaning                                                                                                                  |
+| --------------------------- | :--: | ------------------------------------------------------------------------------------------------------------------------ |
+| `installed-match`           |  0   | Installed version equals required (Major.Minor.Patch.Build padded)                                                       |
+| `installed-newer`           |  0   | Installed version is newer than required                                                                                 |
+| `installed-version-unknown` |  0   | Cuneiform detected (via `pnova` namespace) but version not exposed (common in source-pushed scratch orgs) — can't verify |
+| `installed-older`           |  1   | Installed version is older than required — upgrade the org                                                               |
+| `not-installed`             |  1   | Cuneiform managed package not installed in the org                                                                       |
 
-FLAGS
-  -n, --name=<value>  Description of a flag.
+## Quickstart
 
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
+A first profile in five commands:
 
-DESCRIPTION
-  Summary of a command.
+```bash
+# 1. Authenticate to your target org
+sf org login web --alias my-org
 
-  More information about a command. Don't repeat the summary.
+# 2. Confirm the user has the permissions Cuneiform needs (configures them if not)
+sf cuneiform user details --target-org my-org
 
-EXAMPLES
-  $ sf cuneiform about
+# 3. See what's in the org
+sf cuneiform org details --target-org my-org
+sf cuneiform object list --target-org my-org
 
-FLAG DESCRIPTIONS
-  -n, --name=<value>  Description of a flag.
+# 4. Create a profiling definition for an object you care about (e.g. Account)
+sf cuneiform definition create --target-org my-org --sobject Account
 
-    More information about a flag. Don't repeat the summary.
+# 5. Run the profile and review results
+sf cuneiform profile --target-org my-org --definition-key <key-from-step-4>
+sf cuneiform summary reprofile --help
 ```
 
-_See code: [src/commands/cuneiform/about.ts](https://github.com/PeerNova-Solutions/cuneiform-cli/blob/1.0.2/src/commands/cuneiform/about.ts)_
+Append `--help` to any command for the full flag reference. All commands support `--json` for structured output in CI pipelines and scripts.
 
-## `sf hello world`
+## Commands
 
-Say hello.
+All commands are namespaced under the `cuneiform` topic.
+
+| Command                               | What it does                                                                |
+| ------------------------------------- | --------------------------------------------------------------------------- |
+| `sf cuneiform compatibility check`    | Verify CLI ↔ managed-package version compatibility                          |
+| `sf cuneiform definition create`      | Create profiling definition(s)                                              |
+| `sf cuneiform definition get`         | Retrieve profiling definition(s) by key                                     |
+| `sf cuneiform definition list`        | List all profiling definitions with status                                  |
+| `sf cuneiform definition update`      | Update definition metadata (name, category, description, …)                 |
+| `sf cuneiform definition purge`       | Delete unused definitions                                                   |
+| `sf cuneiform definition export`      | Export definitions to a VCS-friendly format                                 |
+| `sf cuneiform definition import`      | Import definitions from an exported bundle                                  |
+| `sf cuneiform object list`            | List objects with record counts, type distribution, and namespace filtering |
+| `sf cuneiform object describe`        | Retrieve comprehensive object metadata (fields, record types, dependencies) |
+| `sf cuneiform org details`            | Show org configuration, installation status, namespaces, and limits         |
+| `sf cuneiform profile`                | Execute profiling for one or more definitions                               |
+| `sf cuneiform profile request list`   | List profiling requests with status and progress                            |
+| `sf cuneiform profile request cancel` | Cancel in-progress profiling requests                                       |
+| `sf cuneiform profile request delete` | Delete terminal profiling requests                                          |
+| `sf cuneiform summary purge`          | Delete profiling summary records (with dry-run preview)                     |
+| `sf cuneiform summary stop`           | Stop in-progress profiling summaries                                        |
+| `sf cuneiform summary reprofile`      | Re-execute profiling for existing summaries                                 |
+| `sf cuneiform user details`           | Show user readiness; configure required permissions                         |
+
+## Discovery
+
+Before profiling, deploying Agentforce, or planning a migration, start by understanding what's actually in an object. `object describe` is the entry point — it answers _"what fields exist, how many are custom, and what's the shape of this object today?"_ — in seconds, with no SOQL and no Setup clicks.
 
+```bash
+sf cuneiform object describe --target-org my-org --object Case --with-fields
 ```
-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.
-
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
 
-DESCRIPTION
-  Say hello.
+You'll see the total field count, a custom-vs-standard breakdown, and per-field metadata (type, required, unique, referenced object for lookups). It's the natural first stop for an Agentforce readiness check, a data-quality assessment, or scoping a migration.
 
-  Say hello either to the world or someone you know.
+Narrow the view with follow-up flags as the question gets sharper:
 
-EXAMPLES
-  Say hello to the world:
+```bash
+# Just the lookup fields, sorted by referenced object
+sf cuneiform object describe --target-org my-org --object Case --with-fields --field-type lookup
 
-    $ sf hello world
+# Just the custom Agentforce-tagged fields
+sf cuneiform object describe --target-org my-org --object Case --with-fields --field-pattern '__c$'
+```
 
-  Say hello to someone you know:
+## Issues
 
-    $ sf hello world --name Astro
+Report bugs and request features at <https://github.com/PeerNova-Solutions/salesforce-cli/issues>.
 
-FLAG DESCRIPTIONS
-  -n, --name=<value>  The name of the person you'd like to say hello to.
+## Contributing
 
-    This person can be anyone in the world!
-```
+This is a PeerNova-published package. PeerNova engineers — see the in-repo `CONTRIBUTING.md` and `CLAUDE.md` for development conventions, branch model, and PR workflow. External contributors should open an issue before starting work so we can coordinate.
 
-_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 — see [LICENSE](./LICENSE). Copyright © PeerNova, Inc.