test(cli): publish report schemas and goldens

Author: grysz

.github/workflows/release.yml

@@ -66,7 +66,7 @@ jobs:
           }
 
           rm -rf "${package_dir}" dist
-          mkdir -p "${package_dir}/bin" "${package_dir}/packages" "${package_dir}/docs" dist
+          mkdir -p "${package_dir}/bin" "${package_dir}/packages" "${package_dir}/docs/schemas" "${package_dir}/goldens/cli" dist
 
           cp "target/release/${{ matrix.binary }}" "${binary_path}"
 
@@ -83,8 +83,11 @@ jobs:
             --tx-bytes 400
 
           cp docs/KERNEL_PACKAGE_SCHEMA.md "${package_dir}/docs/KERNEL_PACKAGE_SCHEMA.md"
+          cp docs/CLI_REPORT_SCHEMAS.md "${package_dir}/docs/CLI_REPORT_SCHEMAS.md"
+          cp docs/schemas/*.schema.json "${package_dir}/docs/schemas/"
           cp docs/PROJECT_STATUS.md "${package_dir}/docs/PROJECT_STATUS.md"
           cp docs/RUSTY_KASPA_UPSTREAM_WATCH.md "${package_dir}/docs/RUSTY_KASPA_UPSTREAM_WATCH.md"
+          cp tests/golden/cli/*.json "${package_dir}/goldens/cli/"
 
           cat > "${package_dir}/RELEASE_NOTES.md" <<EOF
           # KaspaScript ${version}
@@ -98,6 +101,7 @@ jobs:
           - kaspascript CLI for ${{ matrix.label }}
           - verified TN12 kernel packages for escrow.ks and vault.ks
           - Kernel Package v0 schema reference
+          - CLI report JSON Schemas and golden snapshots
           - project status and Rusty Kaspa upstream watch docs
           - smoke verification output
           - SHA-256 checksums
@@ -169,6 +173,7 @@ jobs:
           - \`kaspascript\` CLI binary
           - verified TN12 kernel packages for \`escrow.ks\` and \`vault.ks\`
           - Kernel Package v0 schema reference
+          - CLI report JSON Schemas and golden snapshots
           - project status and Rusty Kaspa upstream watch docs
           - smoke verification output
           - internal \`SHA256SUMS.txt\`

README.md

@@ -266,6 +266,11 @@ Every report-style command also supports `--json` for agents and CI:
 $ kaspascript doctor escrow.ks --target future-mainnet --json
 ```
 
+The report payloads are versioned contracts. JSON Schemas live in
+[`docs/schemas`](docs/schemas), and golden report snapshots live in
+[`tests/golden/cli`](tests/golden/cli). Start with
+[`docs/CLI_REPORT_SCHEMAS.md`](docs/CLI_REPORT_SCHEMAS.md).
+
 ```console
 $ kaspascript verify escrow.artifact.json
 backend: kaspa-txscript

cli/src/main.rs

@@ -149,19 +149,7 @@ fn kernel_check_command(args: &[String]) -> Result<()> {
 
     match options.format {
         OutputFormat::Json => {
-            let report = json!({
-                "schema_version": "kaspascript.cli.kernel.check.v0",
-                "contract": package.kernel.readiness.contract,
-                "target": package.package_target,
-                "artifact": &package.artifact,
-                "readiness": &package.kernel.readiness,
-                "capabilities": &package.kernel.capabilities,
-                "fee_estimate": &package.fee_estimate,
-                "next_commands": [
-                    format!("kaspascript kernel preview {path} --target {}", package.package_target),
-                    format!("kaspascript kernel package {path} --target {} --compute-grams {} --tx-bytes {}", package.package_target, package.fee_estimate.compute_grams, package.fee_estimate.transaction_bytes)
-                ]
-            });
+            let report = kernel_check_report(path, &package);
             println!("{}", serde_json::to_string_pretty(&report)?);
         }
         OutputFormat::Human => print_kernel_check_human(path, &package),
@@ -195,12 +183,7 @@ fn kernel_preview_command(args: &[String]) -> Result<()> {
 
     match options.format {
         OutputFormat::Json => {
-            let report = json!({
-                "schema_version": "kaspascript.cli.kernel.preview.v0",
-                "contract": package.kernel.readiness.contract,
-                "target": package.package_target,
-                "previews": previews,
-            });
+            let report = kernel_preview_report(&package, &previews);
             println!("{}", serde_json::to_string_pretty(&report)?);
         }
         OutputFormat::Human => print_kernel_preview_human(&package, &previews),
@@ -276,10 +259,7 @@ fn toccata_targets_command(args: &[String]) -> Result<()> {
     let targets = target_matrix();
     match format {
         OutputFormat::Json => {
-            let report = json!({
-                "schema_version": "kaspascript.cli.toccata.targets.v0",
-                "targets": targets,
-            });
+            let report = toccata_targets_report(targets);
             println!("{}", serde_json::to_string_pretty(&report)?);
         }
         OutputFormat::Human => print_target_matrix_human(&targets),
@@ -299,11 +279,7 @@ fn toccata_fee_command(args: &[String]) -> Result<()> {
 
     match options.format {
         OutputFormat::Json => {
-            let report = json!({
-                "schema_version": "kaspascript.cli.toccata.fee.v0",
-                "fee_estimate": estimate,
-                "formula": "max(compute_grams, tx_bytes * 2) * 100 sompi",
-            });
+            let report = toccata_fee_report(&estimate);
             println!("{}", serde_json::to_string_pretty(&report)?);
         }
         OutputFormat::Human => {
@@ -593,6 +569,49 @@ fn parse_u64_option(option: &str, value: &str) -> Result<u64> {
         .with_context(|| format!("{option} must be a non-negative integer"))
 }
 
+fn kernel_check_report(path: &str, package: &CompiledKernelPackage) -> Value {
+    json!({
+        "schema_version": "kaspascript.cli.kernel.check.v0",
+        "contract": package.kernel.readiness.contract,
+        "target": package.package_target,
+        "artifact": &package.artifact,
+        "readiness": &package.kernel.readiness,
+        "capabilities": &package.kernel.capabilities,
+        "fee_estimate": &package.fee_estimate,
+        "next_commands": [
+            format!("kaspascript kernel preview {path} --target {}", package.package_target),
+            format!("kaspascript kernel package {path} --target {} --compute-grams {} --tx-bytes {}", package.package_target, package.fee_estimate.compute_grams, package.fee_estimate.transaction_bytes)
+        ]
+    })
+}
+
+fn kernel_preview_report(
+    package: &CompiledKernelPackage,
+    previews: &[&kaspascript_kernel::WalletPreview],
+) -> Value {
+    json!({
+        "schema_version": "kaspascript.cli.kernel.preview.v0",
+        "contract": package.kernel.readiness.contract,
+        "target": package.package_target,
+        "previews": previews,
+    })
+}
+
+fn toccata_targets_report(targets: Vec<Value>) -> Value {
+    json!({
+        "schema_version": "kaspascript.cli.toccata.targets.v0",
+        "targets": targets,
+    })
+}
+
+fn toccata_fee_report(estimate: &kaspascript_kernel::FeeEstimate) -> Value {
+    json!({
+        "schema_version": "kaspascript.cli.toccata.fee.v0",
+        "fee_estimate": estimate,
+        "formula": "max(compute_grams, tx_bytes * 2) * 100 sompi",
+    })
+}
+
 fn toccata_status_report() -> Value {
     json!({
         "schema_version": "kaspascript.cli.toccata.status.v0",
@@ -1256,6 +1275,34 @@ mod tests {
         ),
     ];
 
+    const CLI_REPORT_SCHEMAS: &[(&str, &str, &str)] = &[
+        (
+            "kaspascript.cli.toccata.status.v0",
+            include_str!("../../docs/schemas/kaspascript.cli.toccata.status.v0.schema.json"),
+            include_str!("../../tests/golden/cli/toccata.status.json"),
+        ),
+        (
+            "kaspascript.cli.toccata.targets.v0",
+            include_str!("../../docs/schemas/kaspascript.cli.toccata.targets.v0.schema.json"),
+            include_str!("../../tests/golden/cli/toccata.targets.json"),
+        ),
+        (
+            "kaspascript.cli.toccata.fee.v0",
+            include_str!("../../docs/schemas/kaspascript.cli.toccata.fee.v0.schema.json"),
+            include_str!("../../tests/golden/cli/toccata.fee.json"),
+        ),
+        (
+            "kaspascript.cli.kernel.check.v0",
+            include_str!("../../docs/schemas/kaspascript.cli.kernel.check.v0.schema.json"),
+            include_str!("../../tests/golden/cli/kernel.check.escrow.verified-tn12.json"),
+        ),
+        (
+            "kaspascript.cli.kernel.preview.v0",
+            include_str!("../../docs/schemas/kaspascript.cli.kernel.preview.v0.schema.json"),
+            include_str!("../../tests/golden/cli/kernel.preview.escrow.release.verified-tn12.json"),
+        ),
+    ];
+
     #[test]
     fn kernel_package_command_writes_combined_artifact() {
         let dir =
@@ -1443,6 +1490,73 @@ mod tests {
         assert!(ToccataFeeOptions::parse(&["--tx-bytes".to_owned(), "400".to_owned()]).is_err());
     }
 
+    #[test]
+    fn cli_report_schema_files_are_valid_json() {
+        for (schema_version, schema, golden) in CLI_REPORT_SCHEMAS {
+            let schema_json: Value = serde_json::from_str(schema).expect("schema json");
+            let golden_json: Value = serde_json::from_str(golden).expect("golden json");
+
+            assert_eq!(
+                schema_json["properties"]["schema_version"]["const"],
+                Value::String((*schema_version).to_owned()),
+                "{schema_version}"
+            );
+            assert_eq!(
+                golden_json["schema_version"],
+                Value::String((*schema_version).to_owned()),
+                "{schema_version}"
+            );
+            assert_eq!(
+                schema_json["$schema"],
+                Value::String("https://json-schema.org/draft/2020-12/schema".to_owned()),
+                "{schema_version}"
+            );
+        }
+    }
+
+    #[test]
+    fn cli_report_golden_snapshots_match() {
+        assert_report_snapshot(
+            "toccata.status",
+            toccata_status_report(),
+            include_str!("../../tests/golden/cli/toccata.status.json"),
+        );
+
+        assert_report_snapshot(
+            "toccata.targets",
+            toccata_targets_report(target_matrix()),
+            include_str!("../../tests/golden/cli/toccata.targets.json"),
+        );
+
+        let fee = ToccataFeePolicy::default()
+            .estimate(1000, 400, "caller-provided Toccata fee estimate inputs")
+            .expect("fee estimate");
+        assert_report_snapshot(
+            "toccata.fee",
+            toccata_fee_report(&fee),
+            include_str!("../../tests/golden/cli/toccata.fee.json"),
+        );
+
+        let package = escrow_kernel_package();
+        assert_report_snapshot(
+            "kernel.check.escrow.verified-tn12",
+            kernel_check_report("tests/contracts/escrow.ks", &package),
+            include_str!("../../tests/golden/cli/kernel.check.escrow.verified-tn12.json"),
+        );
+
+        let previews = package
+            .kernel
+            .wallet_previews
+            .iter()
+            .filter(|preview| preview.transition == "release")
+            .collect::<Vec<_>>();
+        assert_report_snapshot(
+            "kernel.preview.escrow.release.verified-tn12",
+            kernel_preview_report(&package, &previews),
+            include_str!("../../tests/golden/cli/kernel.preview.escrow.release.verified-tn12.json"),
+        );
+    }
+
     #[test]
     fn kernel_package_golden_snapshots_match() {
         for (source_path, source, golden) in KERNEL_GOLDENS {
@@ -1496,4 +1610,24 @@ mod tests {
         );
         assert!(!blocked_package.kernel.readiness.ready);
     }
+
+    fn escrow_kernel_package() -> CompiledKernelPackage {
+        let options = KernelPackageOptions {
+            output: None,
+            compute_grams: 1000,
+            tx_bytes: Some(400),
+            target: Target::VerifiedTn12,
+        };
+        build_kernel_package(
+            "tests/contracts/escrow.ks",
+            include_str!("../../tests/contracts/escrow.ks"),
+            &options,
+        )
+        .expect("escrow package")
+    }
+
+    fn assert_report_snapshot(name: &str, actual: Value, golden: &str) {
+        let expected: Value = serde_json::from_str(golden).expect("golden json");
+        assert_eq!(actual, expected, "{name}");
+    }
 }

docs/CLI_REPORT_SCHEMAS.md

@@ -0,0 +1,41 @@
+# CLI Report Schemas
+
+KaspaScript publishes JSON Schema files and golden snapshots for the
+agent-facing CLI report payloads. These files are API contracts for agents, CI,
+wallets, SDKs, and indexers that consume `--json` output.
+
+The CLI report schemas are versioned independently from the kernel package
+schema. A report schema version must not change shape without a new
+`schema_version` value.
+
+## Schemas
+
+| CLI command | Schema version | Schema file | Golden snapshot |
+| --- | --- | --- | --- |
+| `kaspascript toccata status --json` | `kaspascript.cli.toccata.status.v0` | [`docs/schemas/kaspascript.cli.toccata.status.v0.schema.json`](schemas/kaspascript.cli.toccata.status.v0.schema.json) | [`tests/golden/cli/toccata.status.json`](../tests/golden/cli/toccata.status.json) |
+| `kaspascript toccata targets --json` | `kaspascript.cli.toccata.targets.v0` | [`docs/schemas/kaspascript.cli.toccata.targets.v0.schema.json`](schemas/kaspascript.cli.toccata.targets.v0.schema.json) | [`tests/golden/cli/toccata.targets.json`](../tests/golden/cli/toccata.targets.json) |
+| `kaspascript toccata fee --compute-grams 1000 --tx-bytes 400 --json` | `kaspascript.cli.toccata.fee.v0` | [`docs/schemas/kaspascript.cli.toccata.fee.v0.schema.json`](schemas/kaspascript.cli.toccata.fee.v0.schema.json) | [`tests/golden/cli/toccata.fee.json`](../tests/golden/cli/toccata.fee.json) |
+| `kaspascript kernel check tests/contracts/escrow.ks --target verified-tn12 --compute-grams 1000 --tx-bytes 400 --json` | `kaspascript.cli.kernel.check.v0` | [`docs/schemas/kaspascript.cli.kernel.check.v0.schema.json`](schemas/kaspascript.cli.kernel.check.v0.schema.json) | [`tests/golden/cli/kernel.check.escrow.verified-tn12.json`](../tests/golden/cli/kernel.check.escrow.verified-tn12.json) |
+| `kaspascript kernel preview tests/contracts/escrow.ks --target verified-tn12 --transition release --json` | `kaspascript.cli.kernel.preview.v0` | [`docs/schemas/kaspascript.cli.kernel.preview.v0.schema.json`](schemas/kaspascript.cli.kernel.preview.v0.schema.json) | [`tests/golden/cli/kernel.preview.escrow.release.verified-tn12.json`](../tests/golden/cli/kernel.preview.escrow.release.verified-tn12.json) |
+
+`kaspascript doctor <contract.ks> --json` is an alias for
+`kaspascript kernel check <contract.ks> --json` and uses
+`kaspascript.cli.kernel.check.v0`.
+
+## Compatibility Rules
+
+- `schema_version` is required in every report payload.
+- Existing required fields cannot be removed within the same schema version.
+- Existing field types cannot change within the same schema version.
+- New incompatible payload shapes must use a new schema version.
+- Golden snapshots are tested in CI against the report builders.
+- The report schemas are intentionally stricter at the top level than in nested
+  kernel-owned metadata, where `kaspascript.kernel.package.v0` is the deeper
+  contract.
+
+## Local Checks
+
+```bash
+cargo test -p kaspascript-cli cli_report_golden_snapshots_match
+cargo test -p kaspascript-cli cli_report_schema_files_are_valid_json
+```

docs/PROJECT_STATUS.md

@@ -32,6 +32,8 @@ CLI:
   [--transition <name>] [--json]`
 - `kaspascript toccata status|targets|fee [--json]`
 - `kaspascript doctor <contract.ks> --target <target> [--json]`
+- JSON Schemas in `docs/schemas` and golden report payloads in
+  `tests/golden/cli` for the agent-facing report surfaces.
 
 Kernel:
 
@@ -74,7 +76,6 @@ Testnet readiness:
 
 The current milestone is close to alpha complete. It needs:
 
-- JSON-schema publication for the agent-facing CLI report payloads.
 - CI running `cargo fmt --check`, `cargo clippy`, and workspace tests.
 
 ### Testnet Complete
@@ -143,3 +144,10 @@ cargo run -p kaspascript-cli -- doctor tests/contracts/escrow.ks \
   --target future-mainnet \
   --json
 ```
+
+Check the CLI report contracts:
+
+```bash
+cargo test -p kaspascript-cli cli_report_golden_snapshots_match
+cargo test -p kaspascript-cli cli_report_schema_files_are_valid_json
+```

docs/index.html

@@ -345,6 +345,12 @@ <h2 id="quickstart-title">Compile, inspect, verify, package.</h2>
   --compute-grams 1000 \
   --tx-bytes 400</code></pre>
         </div>
+        <p class="doc-link">
+          CLI report schemas:
+          <a href="https://github.com/gryszzz/Kaspa-Script/blob/main/docs/CLI_REPORT_SCHEMAS.md">
+            docs/CLI_REPORT_SCHEMAS.md
+          </a>
+        </p>
       </section>
 
       <section class="band" id="upstream" aria-labelledby="upstream-title">