@tokamak-private-dapps/private-state-cli 2.4.1 → 2.4.3

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 2.4.3 - 2026-06-01
+
+- Added pre-submit transaction dry-runs for every transaction-sending CLI command.
+- Added post-proof local prechecks before dry-run for proof-backed commands.
+- Improved dry-run and submit failure messages with decoded revert details when available.
+- Standardized CLI `--json` output so final success and failure results are JSON objects on stdout.
+- Changed progress, warning, and informational events to emit JSON Lines on stderr in `--json` mode.
+- Added structured JSON command-reference output for `help commands --json` and `--help --json`.
+
+## 2.4.2 - 2026-05-30
+
+- Changed channel workspace recovery guidance so CLI help, guide output, agent instructions, and documentation direct
+  users to registered workspace mirrors before explicit RPC genesis rebuilds.
+
 ## 2.4.1 - 2026-05-30
 
 - Classified `UnexpectedCurrentRootVector()` submit reverts as stale channel-root failures with recovery hints that

package/README.md

@@ -170,7 +170,8 @@ A common note-use flow after channel policy review is:
 `channel join` pays any join toll directly from the L1 wallet; `account deposit-bridge` funds later channel liquidity and does not pay the join toll.
 
 Use `private-state-cli help commands` for the full command list and required options. `private-state-cli --help`
-continues to print the same command list for shell compatibility.
+continues to print the same command list for shell compatibility. Add `--json` to either form to print the command
+reference as structured JSON on stdout.
 
 ### Action-impact acknowledgement
 
@@ -199,7 +200,14 @@ unless the user explicitly understands the compliance implications. Prefer a sel
 
 Workspace recovery commands use saved recovery indexes by default. If the local channel workspace is missing,
 corrupted, or does not contain a usable index, `channel recover-workspace` stops with an explicit error instead of
-silently replaying logs from channel genesis. Use `channel recover-workspace --source rpc --from-genesis` only when
+silently replaying logs from channel genesis. When the channel has a registered workspace mirror, recover from the
+mirror first:
+
+```bash
+private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source mirror
+```
+
+Use `channel recover-workspace --source rpc --from-genesis` only when no compatible workspace mirror is available and
 you intentionally want to rebuild channel workspace state from the channel creation block:
 
 ```bash
@@ -226,9 +234,9 @@ existing history, while `--from-genesis` overwrites it with one full genesis-to-
 by replaying from the channel's genesis block because no prior recovery index can exist for a new channel.
 
 `channel join` refreshes stale channel workspace state through the saved recovery index before submitting the
-registration transaction. For a channel that was created elsewhere, run `channel recover-workspace --source rpc --from-genesis`
-once before joining, or recover from a registered workspace mirror; later joins and wallet commands resume from the
-saved index instead of silently replaying from genesis.
+registration transaction. For a channel that was created elsewhere, recover from a registered workspace mirror first.
+Use `channel recover-workspace --source rpc --from-genesis` only when no compatible mirror is available; later joins
+and wallet commands resume from the saved index instead of silently replaying from genesis.
 
 Wallet commands that need channel state, including `wallet recover-workspace`, `wallet get-meta`,
 `wallet get-channel-fund`, and `wallet get-notes`, refresh stale local channel workspaces through saved recovery
@@ -517,6 +525,15 @@ LLM agents that guide users through this CLI should read [`agents.md`](agents.md
 commands. That file contains the agent-specific operating rules, including secret-handling boundaries, onboarding
 sequence, acknowledgement handling, recovery behavior, and error-response policy.
 
+When `--json` is used, the CLI follows one output contract for all commands:
+
+- the final success result is one JSON object on stdout
+- command failures are one JSON object on stdout with `ok: false`
+- progress, warning, and informational events are JSON Lines on stderr
+- human-readable mode remains the default when `--json` is omitted
+
+Agents should parse stdout for the final result and may stream stderr JSONL events to explain progress to the user.
+
 ## Artifacts
 
 Proof-backed and channel-mutating commands require full installed bridge, DApp, and Groth16 artifacts. Run

package/agents.md

@@ -37,16 +37,20 @@ activity or as a bridge-wide disclosure rule for every DApp.
     `private-state-cli set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or with explicit
     `--log-requests-per-second` and `--block-range-cap` values when the provider is not built in.
   - A workspace recovery index is the saved block pointer and state-root hash that lets the CLI resume log scanning
-    without replaying the channel from its creation block. If it is missing, explain `--from-genesis` before using it
-    because genesis replay can take much longer.
+    without replaying the channel from its creation block. If it is missing, check whether the channel has a registered
+    workspace mirror before explaining or using `--from-genesis`, because genesis replay can take much longer.
 - Before guiding a user to run `channel recover-workspace --source rpc --from-genesis`, explain that RPC genesis
-  recovery can be very slow because it scans channel logs from the creation block. If a channel workspace mirror is
-  available, try mirror-based recovery first, and use RPC genesis replay only when mirror recovery is unavailable or
-  unsuitable.
+  recovery can be very slow because it scans channel logs from the creation block. Run or suggest
+  `channel get-meta --channel-name <CHANNEL> --network <NETWORK>` first; if `workspaceMirror` is set, try
+  `channel recover-workspace --channel-name <CHANNEL> --network <NETWORK> --source mirror`. Use RPC genesis replay only
+  when no compatible workspace mirror is available.
 - When the user asks about gas use, transaction fees, transaction cost, or USD cost for private-state CLI commands, run
   `private-state-cli help transaction-fees --network <NETWORK> --json` and answer from the returned `rows`. If the
   network is unclear, ask which network to use. Do not tell the user to ask the developer unless the command fails after
   following the CLI's printed corrective guidance.
+- Prefer `--json` when running commands on behalf of a user. In JSON mode, parse stdout as the final success or failure
+  result. Failures use `ok: false` on stdout. Progress, warning, and informational events are emitted as JSON Lines on
+  stderr; stream or summarize those events for the human user instead of treating them as fatal by default.
 - When `channel recover-workspace` or `wallet recover-workspace` is unexpectedly slow, first inspect the RPC provider
   configured by `set rpc`. Explain that recovery speed is dominated by `eth_getLogs` block range cap and log request
   rate. Suggest re-running `set rpc` with a provider that supports a larger block range cap, such as Ankr or Chainnodes

package/commands/index.mjs

@@ -1,8 +1,8 @@
 import {
   assertHelpCommandsArgs,
   assertVersionArgs,
+  cliOutput,
   configureOutput,
-  formatCliErrorForDisplay,
   parseArgs,
   printHelp,
   printVersion,
@@ -52,11 +52,7 @@ export async function runPrivateStateCli(argv) {
     }
     await command(args);
   } catch (error) {
-    console.error(formatCliErrorForDisplay(error, args));
+    cliOutput.error(error, args);
     process.exitCode = 1;
   }
 }
-
-export function privateStateCliDispatchTable() {
-  return COMMANDS;
-}

package/lib/private-state-cli-command-registry.mjs

@@ -210,7 +210,7 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
   fromGenesis: {
     label: "Scan From Genesis",
     type: "checkbox",
-    hint: "Requires --source rpc. Ignore the local recovery index and replay channel logs from genesis.",
+    hint: "Requires --source rpc. Use only when no compatible workspace mirror is available and a full genesis replay is intentional.",
     option: "--from-genesis",
     optional: true,
   },
@@ -233,7 +233,7 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     type: "select",
     options: ["rpc", "mirror"],
     valueLabel: "<rpc|mirror>",
-    hint: "Optional. Defaults to rpc. mirror validates the channel leader's checkpoint manifest and downloads only the needed checkpoint or delta bundle before RPC delta replay.",
+    hint: "Use mirror first when a channel workspace mirror is registered. If omitted, the CLI uses rpc and resumes from the local recovery index when available.",
     option: "--source",
     optional: true,
   },
@@ -313,8 +313,11 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     id: "help-commands",
     display: "help commands",
     description: "Show the private-state CLI command reference.",
-    fields: [],
-    usage: "no options",
+    fields: ["json"],
+    usage: "optional --json",
+    help: [
+      "Use --json to emit the full command reference as structured JSON on stdout.",
+    ],
   },
   {
     id: "help-update",
@@ -429,12 +432,13 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     optionalFields: ["source", "fromGenesis", "outputRaw", "publishWorkspaceMirror", "leaderAccount", "output", "force"],
     usage: "--channel-name, --network, optional --source, optional --from-genesis, optional --output-raw, optional --publish-workspace-mirror with --leader-account and --output, optional --force",
     help: [
-      "By default, --source rpc resumes RPC log scanning from the workspace recovery index when available",
+      "When a channel workspace mirror is registered, try --source mirror before an explicit RPC genesis rebuild",
       "--source mirror validates the channel leader's registered checkpoint manifest, downloads only the needed checkpoint or delta bundle, and then replays RPC logs to latest",
+      "If --source is omitted, the CLI uses rpc and resumes RPC log scanning from the workspace recovery index when available",
       "RPC recovery writes a usable channel workspace checkpoint after each RPC log chunk, so interrupted runs can resume from the last completed chunk",
       "Mirror recovery uses a matching delta bundle when available; otherwise a newer verified full checkpoint replaces the local checkpoint before RPC catch-up",
       "Fails instead of falling back to genesis when no usable recovery index exists",
-      "Use --source rpc --from-genesis to ignore the recovery index and replay logs from channel genesis",
+      "Use --source rpc --from-genesis only when no compatible workspace mirror is available and you intentionally want to replay logs from channel genesis",
       "--output-raw with --source rpc appends raw JSON-RPC request and response history to method-specific JSON files under the channel workspace rpcCallHistory directory; eth_getLogs is split by event",
       "--from-genesis moves the existing local channel workspace to workspace-rebuild-backups before writing the current-format workspace; local secrets are preserved",
       "--publish-workspace-mirror writes manifest.json, checkpoint.zip, and any needed delta bundle after recovery",
@@ -524,7 +528,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 7,200-block pre-command budget",
-      "Fails instead of replaying from genesis; run channel recover-workspace --source rpc --from-genesis when a genesis rebuild is required",
+      "Fails instead of replaying from genesis; recover from a registered workspace mirror first, and use channel recover-workspace --source rpc --from-genesis only when no compatible mirror is available",
       "--wallet-secret-path is read once for channel-bound L2 spending-key derivation and is not stored in the wallet workspace",
       "Pays any join toll directly from the L1 wallet, not from bridge-deposited balance",
       "Prints the immutable policy snapshot before first registration",