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

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

@@ -2,25 +2,7 @@
 
 [![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)
 
-## Using the template
-
-This repository provides a template for creating a plugin for the Salesforce CLI. To convert this template to a working plugin:
-
-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
-
-   git init -b main
-   git add . && git commit -m "chore: initial commit"
-   ```
-
-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.
-
-## Learn about `sf` plugins
+## About
 
 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.
 
@@ -44,11 +26,7 @@ For cross clouds commands, e.g. `sf env list`, we utilize [oclif hooks](https://
 
 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.
+This plugin extends the [Salesforce CLI](https://developer.salesforce.com/tools/sfdxcli) with enterprise data profiling and metadata governance capabilities.
 
 ## Prerequisites
 
@@ -74,6 +52,48 @@ For more information about SFDMU, visit: https://help.sfdmu.com
 sf plugins install @peernova/cuneiform-sf@x.y.z
 ```
 
+## Compatibility
+
+Each CLI release expects a minimum version of the **Cuneiform For Salesforce** managed package (namespace `pnova`) installed in your target org. The required version is published in the CLI's `package.json` under `cuneiform.requiredAppVersion`:
+
+```jsonc
+{
+  "name": "@peernova/cuneiform-sf",
+  "version": "1.0.4-beta.1",
+  "cuneiform": {
+    "requiredAppVersion": "4.12.0.17"
+  }
+}
+```
+
+### Check compatibility
+
+Print the required app version (no auth, no API calls):
+
+```bash
+sf cuneiform compatibility check
+```
+
+Verify a target org's installed version:
+
+```bash
+sf cuneiform compatibility check --target-org myOrg
+```
+
+The command exits non-zero when the installed version is older than required, or when Cuneiform For Salesforce is not installed at all — useful for CI gates that run profiling jobs after a fresh package install.
+
+| State                       | Exit code | 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 namespace but version not exposed (source-pushed scratch orgs, CLI-1569) — cannot verify |
+| `installed-older`           |     1     | Installed version is older than required — upgrade the org                                                      |
+| `not-installed`             |     1     | `pnova` package not installed in the org                                                                        |
+
+### Updating `requiredAppVersion`
+
+When releasing a new CLI version that depends on new app-side features, update `cuneiform.requiredAppVersion` in `package.json` alongside the CLI's own `version` bump. The release procedure should treat these as a paired change.
+
 ## Issues
 
 Please report any issues at https://github.com/forcedotcom/cli/issues
@@ -113,7 +133,7 @@ To use your plugin, run using the local `./bin/dev` or `./bin/dev.cmd` file.
 
 ```bash
 # Run using local run file.
-./bin/dev hello world
+./bin/dev.js cuneiform definition create --help
 ```
 
 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.
@@ -127,77 +147,21 @@ sf plugins
 
 ## Commands
 
-<!-- commands -->
-
-- [`sf cuneiform about`](#sf-cuneiform-about)
-- [`sf hello world`](#sf-hello-world)
-
-## `sf cuneiform about`
+| Command                          | Description                       |
+| -------------------------------- | --------------------------------- |
+| `sf cuneiform definition create` | Create profiling definition(s)    |
+| `sf cuneiform definition get`    | Retrieve profiling definitions    |
+| `sf cuneiform definition update` | Update definition field lists     |
+| `sf cuneiform definition purge`  | Delete unused definitions         |
+| `sf cuneiform definition export` | Export definitions (VCS-friendly) |
+| `sf cuneiform definition import` | Import definitions from export    |
+| `sf cuneiform profile`           | Execute profiling operations      |
 
-Summary of a command.
+For detailed usage, run any command with `--help`:
 
+```bash
+sf cuneiform definition create --help
+sf cuneiform profile --help
 ```
-USAGE
-  $ sf cuneiform about [--json] [--flags-dir <value>] [-n <value>]
-
-FLAGS
-  -n, --name=<value>  Description of a flag.
-
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
-
-DESCRIPTION
-  Summary of a command.
-
-  More information about a command. Don't repeat the summary.
-
-EXAMPLES
-  $ sf cuneiform about
-
-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)_
-
-## `sf hello world`
-
-Say hello.
-
-```
-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.
-
-  Say hello either to the world or someone you know.
-
-EXAMPLES
-  Say hello to the world:
-
-    $ sf hello world
-
-  Say hello to someone you know:
-
-    $ sf hello world --name Astro
-
-FLAG DESCRIPTIONS
-  -n, --name=<value>  The name of the person you'd like to say hello to.
-
-    This person can be anyone in the world!
-```
-
-_See code: [src/commands/hello/world.ts](https://github.com/PeerNova-Solutions/cuneiform-cli/blob/1.0.2/src/commands/hello/world.ts)_
 
-<!-- commandsstop -->
+# Test run for workflow verification

package/messages/compatibility.check.md

@@ -0,0 +1,71 @@
+# summary
+
+Verify the Cuneiform For Salesforce app version required by this CLI build, and (optionally) the version installed in a target org.
+
+# description
+
+Reports the Cuneiform For Salesforce managed-package version this CLI release was tested against. Without `--target-org`, the command is a local-only readout — no Salesforce API calls, no authentication required.
+
+When `--target-org` is supplied, the command queries the org for the installed Cuneiform For Salesforce package via the Tooling API and reports one of five states:
+
+- `installed-match` — installed version satisfies the requirement (exit 0)
+- `installed-newer` — installed version is newer than required (exit 0, advisory)
+- `installed-version-unknown` — Cuneiform is detected via namespace but the version is not exposed (typical for source-pushed scratch orgs — CLI-1569). Compatibility cannot be verified, but the package is present (exit 0, advisory)
+- `installed-older` — installed version is older than required (exit 1)
+- `not-installed` — Cuneiform For Salesforce is not installed in this org (exit 1)
+
+Use this command to:
+
+- Confirm a scratch org or sandbox is ready for CLI operations after a fresh package install
+- Diagnose CLI errors that look like data-shape mismatches but are version-compatibility issues
+- Pin CLI/app version pairs in CI before running profiling jobs
+
+# examples
+
+- Print the required app version (no auth, no API calls):
+
+  <%= config.bin %> <%= command.id %>
+
+- Verify the installed version in a target org:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg
+
+- Machine-readable output for CI:
+
+  <%= config.bin %> <%= command.id %> --target-org myOrg --json
+
+# flags.target-org.summary
+
+Target org username or alias. When supplied, the command queries the org's installed Cuneiform For Salesforce version and reports compatibility.
+
+# flags.api-version.summary
+
+API version to use when querying the target org. Defaults to the org's maximum supported version.
+
+# state.installed-match
+
+✓ Installed version matches the required version. Compatible.
+
+# state.installed-newer
+
+✓ Installed version is newer than required. Likely compatible — newer org-side features may not be exposed by this CLI build.
+
+# state.installed-version-unknown
+
+⚠ Cuneiform For Salesforce is present in this org (detected via namespace) but the package version is not exposed by the standard API. This is typical for source-pushed scratch orgs. Compatibility cannot be verified against the requirement — proceed at your own risk.
+
+# state.installed-older
+
+✗ Installed version is older than required. CLI commands that depend on newer app features will fail. Upgrade Cuneiform For Salesforce in this org to at least the required version.
+
+# state.not-installed
+
+✗ Cuneiform For Salesforce is not installed in this org. Install the managed package before running CLI commands.
+
+# errors.manifestInvalid
+
+This CLI build's `package.json` is missing the `cuneiform.requiredAppVersion` field. This is a build-time configuration error — please file an issue on the salesforce-cli repository.
+
+# errors.orgQueryFailed
+
+Failed to query the installed package version from the target org: %s

package/messages/cuneiform.access.md

@@ -0,0 +1,138 @@
+# error.profilingAccessDenied
+
+Cuneiform is installed, but you don't have profiling access.
+
+You're missing one or more required permission sets.
+
+Next steps:
+
+1. Run the diagnostic to see exactly what's missing:
+   sf cuneiform user details --target-org <your-org>
+
+2. Preview what the auto-configure would change:
+   sf cuneiform user details --target-org <your-org> --configure --dry-run
+
+3. Apply the changes automatically:
+   sf cuneiform user details --target-org <your-org> --configure
+
+If you don't have permission to self-configure, ask your Salesforce administrator to assign the required Cuneiform permission sets.
+
+# error.globalProfilingNotEnabled
+
+Cuneiform is installed, but Global Profiling is not enabled.
+
+API-Only Profiling must be enabled in the Configuration Profile before you can use the CLI.
+
+Next steps:
+
+1. Run the diagnostic to see your current readiness:
+   sf cuneiform user details --target-org <your-org>
+
+2. Preview what the auto-configure would change:
+   sf cuneiform user details --target-org <your-org> --configure --dry-run
+
+3. Apply the changes automatically:
+   sf cuneiform user details --target-org <your-org> --configure
+
+If you don't have permission to self-configure, ask your Salesforce administrator to enable API-Only Profiling in the Cuneiform Configuration Profile.
+
+# error.cuneiformNotInstalled
+
+Cuneiform for Salesforce is not installed in this org.
+
+The Cuneiform for Salesforce CLI is available exclusively to PeerNova customers with an active license. The managed package must be installed and activated before you can use the CLI.
+
+Next steps:
+
+1. If you are a PeerNova customer, contact your Salesforce administrator to install the package.
+
+2. If you need to obtain a license, request one at:
+   https://jira-peernova.atlassian.net/wiki/spaces/CFCPD/pages/4196499551
+
+3. To get Cuneiform for Salesforce:
+   https://jira-peernova.atlassian.net/wiki/spaces/CFCPD/pages/2624356353
+
+4. Once installed, verify your readiness:
+   sf cuneiform user details --target-org <your-org>
+
+For help: sfsupport@peernova.com
+
+# error.selfRegistrationNotEnabled
+
+Cuneiform is installed and API-Only Profiling is enabled, but CLI self-provisioning is not available.
+
+Your administrator has not enabled CLI self-provisioning for API-based profiling. This setting ensures your admin controls which users can configure their own API profiling access — you're one admin action away from full access.
+
+Next steps:
+
+1. Run the diagnostic to see your full readiness status:
+   sf cuneiform user details --target-org <your-org>
+
+2. Ask your Salesforce administrator to enable "Enable API Profiling Self-Registration"
+   in the Cuneiform Configuration Profile (Custom Metadata).
+
+3. Alternatively, your admin can assign the API-Based Profiling permission set to you
+   directly, bypassing self-provisioning.
+
+# error.featureNotEnabled
+
+API-Based Profiling is not enabled for this organization.
+
+The Cuneiform for Salesforce CLI is available exclusively to PeerNova customers with an active license. This feature must be enabled by PeerNova before you can use the CLI.
+
+Next steps:
+
+1. If you are a PeerNova customer, contact your PeerNova account team to enable
+   API-Based Profiling for your organization.
+
+2. If you need to obtain a license, request one at:
+   https://jira-peernova.atlassian.net/wiki/spaces/CFCPD/pages/4196499551
+
+3. To get Cuneiform for Salesforce:
+   https://jira-peernova.atlassian.net/wiki/spaces/CFCPD/pages/2624356353
+
+4. Once enabled, verify your readiness:
+   sf cuneiform user details --target-org <your-org>
+
+For help: sfsupport@peernova.com
+
+# error.environmentConfigureBlocked
+
+Configuration is not allowed in production environments.
+
+The configure and autoconfigure commands are restricted to non-production orgs to protect your production data. This org has been identified as a Production org.
+
+Next steps:
+
+1. Run the diagnostic to confirm your org type:
+   sf cuneiform user details --target-org <your-org>
+
+2. Use a sandbox, scratch org, or developer org to test configuration:
+   sf cuneiform user details --target-org <sandbox-org> --configure
+
+3. If you believe this org was misidentified, contact your Salesforce administrator to verify the org type.
+
+# error.connectionFailed
+
+Could not verify your Cuneiform access. The connection to your org failed before the access check could run.
+
+Detail: %s
+
+Next steps:
+
+1. Verify your org is authenticated:
+   sf org list --all
+
+2. Re-authenticate if needed:
+   sf org login web --alias <your-org>
+
+3. Once connected, verify your readiness:
+   sf cuneiform user details --target-org <your-org>
+
+If the problem persists, check your network connection and ensure the Salesforce instance is reachable.
+
+# error.accessCheckFailed
+
+Could not verify your Cuneiform access.
+
+%s