@crediolabs/policy-builder-cli 0.1.17 → 0.2.0

package/README.md

@@ -1,132 +1,69 @@
 # @crediolabs/policy-builder-cli
 
-CLI for the OpenZeppelin Accounts Policy Builder. It records a Soroban
-transaction and synthesises the minimal policy that permits exactly that flow —
-the same core as the MCP server, for solo-dev and CI workflows. MIT-licensed.
+Command-line wrapper around
+[`@crediolabs/policy-synth`](https://www.npmjs.com/package/@crediolabs/policy-synth):
+record a Soroban transaction and synthesise the minimal policy that permits
+exactly that flow, from a shell or a CI job.
 
 ## Install
 
 ```sh
 npm install -g @crediolabs/policy-builder-cli
-# or run without installing:
-npx @crediolabs/policy-builder-cli --help
+# or run without installing
+bunx @crediolabs/policy-builder-cli record --network testnet --hash <tx>
 ```
 
+The binary is `policy-builder`.
+
 ## Commands
 
-```
-policy-builder record     --network <mainnet|testnet> --hash <tx> | --xdr <b64>
-                          [--json] [--quiet] [--out <path>]
-
-policy-builder synthesize --mandate <path.json>
-                          [--oz-config <path.json>] [--confidence <0..1>]
-                          [--json] [--quiet] [--out <path>]
-
-policy-builder synthesize --recorded-tx <path.json> --network <mainnet|testnet>
-                          [--responses <path.json>]
-                          [--oz-config <path.json>] [--confidence <0..1>]
-                          [--smart-account <C...>] [--install-nonce <n>]
-                          [--oracle-max-staleness <s>] [--oracle-max-deviation <bps>]
-                          [--window-seconds <n>] [--valid-until <ledger>]
-                          [--limit-amount <i128str>] [--invocation-limit <n>]
-                          [--json] [--quiet] [--out <path>]
-```
+### `record`
 
-Global flags:
-
-- `--json` — emit a machine-readable JSON envelope (`{ ok, data }` / `{ ok, error }`) on stdout.
-- `--quiet` — suppress progress / non-error output.
-- `--out <path>` — write the artefact to a file (JSON).
-- `--oz-config <path.json>` — JSON `OzAdapterConfig` (custom OZ instance
-  addresses for the network). Defaults to the core's mainnet placeholder.
-  Applies to both the `--mandate` and `--recorded-tx` synthesize paths.
-- `--confidence <0..1>` — recorder confidence gate threshold. The synth
-  rejects when `parseConfidence.overall < threshold`; it does not change the
-  recording's `parseConfidence.thresholdUsed` in the output. Must be a finite
-  number in `[0, 1]` (inclusive); out-of-range values are rejected with
-  `CLI_MISSING_ARG`.
-- `--smart-account <C...>` — opt into the interpreter adapter, so
-  constraints OZ built-ins cannot express (per-method scoping, invocation-count
-  windows, oracle bounds, exact hop paths) lower to a real predicate document
-  instead of warnings. Must be a Stellar contract strkey (56 chars, base32
-  alphabet `[2-7A-Z]`, matching `^C[2-7A-Z]{55}$`).
-- `--install-nonce <n>` — per-rule install nonce for the interpreter policy.
-  Requires `--smart-account`; the CLI rejects `--install-nonce` without
-  `--smart-account` so callers cannot silently drop the nonce.
-- `--oracle-max-staleness <s>` — interpreter oracle max staleness in seconds
-  (positive integer `<= 600`, tighten-only vs the wasm default). Requires
-  `--smart-account`; widen values are rejected by the core.
-- `--oracle-max-deviation <bps>` — interpreter oracle max deviation in basis
-  points (positive integer `<= 200`, tighten-only). Requires
-  `--smart-account`; widen values are rejected by the core.
-- `--window-seconds <n>` — per-field override of `userResponses.windowSeconds`.
-  Overrides the same field from `--responses` (CLI flag wins).
-- `--valid-until <ledger>` — per-field override of `userResponses.validUntilLedger`.
-  Overrides the same field from `--responses` (CLI flag wins).
-- `--limit-amount <i128str>` — per-field override of `userResponses.limitAmount`
-  (positive base-10 i128 string). Overrides the same field from `--responses`.
-- `--invocation-limit <n>` — per-field override of `userResponses.invocationLimit`.
-  Overrides the same field from `--responses` (CLI flag wins).
-
-**Precedence for per-field response flags:** `--responses <file>` provides the
-base `userResponses` object; any of the per-field flags above override the
-same-named field from the file (the CLI flag is the explicit caller intent,
-the file is the default bag). The two never merge - either-or on the same
-field.
-
-A `ToolError` exits non-zero (`1`), so CI scripts can gate on `$?`. Empty
-`--smart-account`, out-of-range `--confidence`, non-numeric `--window-seconds`,
-non-integer `--oracle-*`, and `--oracle-*` without `--smart-account` are all
-rejected with `CLI_MISSING_ARG` before the call reaches the core.
-
-## Examples
-
-Record an on-chain transaction and synthesise from the recording:
+Decode a transaction into a `RecordedTransaction`:
 
 ```sh
-policy-builder record --network mainnet --hash <tx-hash> --out recorded-tx.json
-policy-builder synthesize --recorded-tx recorded-tx.json --network mainnet --json
+policy-builder record --network mainnet --hash <transaction hash>
+policy-builder record --network testnet --xdr  <base64 envelope XDR>
 ```
 
-Synthesise with the interpreter opt-in (use when the policy needs constraints
-OZ built-ins cannot express — e.g. per-claim frequency caps on Blend):
+Exactly one of `--hash` (fetched over RPC) or `--xdr` (decoded locally) is
+required.
+
+### `synthesize`
+
+Produce a `ProposedPolicy` from a recording or from a mandate file (exactly
+one of the two):
 
 ```sh
-policy-builder synthesize \
-  --recorded-tx recorded-tx.json \
-  --network mainnet \
-  --responses responses.json \
-  --smart-account CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIT4C \
-  --install-nonce 1 \
-  --json
+policy-builder synthesize --network mainnet --recorded-tx recorded.json
+policy-builder synthesize --mandate mandate.json
 ```
 
-Synthesise deterministically from a mandate (`mandate.json`):
+`synthesize --recorded-tx` accepts either a bare `RecordedTransaction` or the
+artifact `record --out` writes, so `record --out tx.json` followed by
+`synthesize --recorded-tx tx.json` works end to end. Add `--explain` to
+include the human-readable review card and predicate tree in the output.
 
-```json
-{
-  "chain": "stellar",
-  "contract": "CTOKEN",
-  "method": "transfer",
-  "spendingLimit": { "token": "CTOKEN", "limit": "5000000", "windowSeconds": 2592000 }
-}
-```
+Both commands print a single JSON envelope to stdout: the result on success,
+a machine-readable error object (stable `code`, `severity`, `retryable`) on
+failure. That makes the output safe to pipe and to assert on in CI.
 
-```sh
-policy-builder synthesize --mandate mandate.json --json
-```
+## Beyond record and synthesize
 
-> Recording an XDR envelope (`--xdr`) instead of an on-chain `--hash` has no raw
-> events to cross-check, so the recorder fails closed at the default confidence
-> threshold. See [`@crediolabs/policy-synth`](https://www.npmjs.com/package/@crediolabs/policy-synth)
-> for the confidence-override details.
+Verification, simulation, install and revoke are part of the same core; drive
+them from
+[`@crediolabs/policy-builder-mcp`](https://www.npmjs.com/package/@crediolabs/policy-builder-mcp)
+or call `@crediolabs/policy-synth/run` directly. The CLI stays deliberately
+small: the two commands that fit a pipe.
 
-## Status
+## Security model
 
-The `record` and `synthesize` commands (both the mandate and recording
-front-ends) are implemented and test-covered. Install, on-chain verify, and
-simulate are later phases.
+The CLI holds no key material and signs nothing. See the
+[architecture document](https://github.com/untangledfinance/octogate/blob/main/docs/architecture.md)
+for what the on-chain interpreter does and does not enforce, and the
+[repository README](https://github.com/untangledfinance/octogate#readme) for
+the contracts' audit status.
 
 ## License
 
-MIT.
+MIT

package/dist/bin/policy-builder.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// apps/policy-builder-cli/bin/policy-builder.ts - subcommand router.
+// packages/policy-builder-cli/bin/policy-builder.ts - subcommand router.
 //
 // Usage:
 //   policy-builder record --network <mainnet|testnet> --hash <tx>
@@ -26,6 +26,7 @@
 // `command + subcommand-flags + global-flags` and dispatches to the matching
 // command body. Bad args -> CliError -> non-zero exit (JSON envelope under
 // --json).
+import { runMergeCommand } from "../src/commands/merge.js";
 import { runRecordCommand } from "../src/commands/record.js";
 import { runSynthesizeCommand } from "../src/commands/synthesize.js";
 import { emitCliError, parseFlags } from "../src/output.js";
@@ -47,6 +48,10 @@ async function main() {
                 await runSynthesizeCommand(subcommandArgs, flags);
                 return;
             }
+            case 'merge': {
+                await runMergeCommand(subcommandArgs, flags);
+                return;
+            }
             case 'help':
             case '--help':
             case '-h':
@@ -68,6 +73,10 @@ function printHelp() {
 
 Usage:
   policy-builder record     --network <mainnet|testnet> --hash <tx> | --xdr <b64>
+  policy-builder merge      --smart-account <C...> --source-account <G...>
+                            --rule-id <n> --predicate <b64> --step <detach|reinstall>
+                            [--network <mainnet|testnet>] [--rpc-url <url>]
+                            [--json] [--quiet] [--out <path>]
                             [--json] [--quiet] [--out <path>]
   policy-builder synthesize --mandate <path.json>
                             [--oz-config <path.json>] [--confidence <0..1>]

package/dist/src/commands/merge.d.ts

@@ -0,0 +1,2 @@
+import { type CliFlags } from '../output.ts';
+export declare function runMergeCommand(argv: ReadonlyArray<string>, flags: CliFlags): Promise<import("@crediolabs/policy-synth/run").MergePolicyResult>;

package/dist/src/commands/merge.js

@@ -0,0 +1,58 @@
+// packages/policy-builder-cli/src/commands/merge.ts
+//
+// `policy-builder merge` subcommand. The tightening remedy for a cross-rule
+// authority overlap.
+//
+// OpenZeppelin enforces only the policies of the context rule a signer NAMES,
+// so a signer in several rules picks which one applies and their authority is
+// the maximum over the matching rules. Adding a second, tighter rule therefore
+// restricts nothing. To actually tighten, the restriction has to become ONE
+// predicate: the conjunction of the installed one and the new one.
+//
+// Two transactions, in order, because `add_policy` refuses a policy already
+// attached to the rule:
+//
+//   policy-builder merge --step detach    ...  sign and submit, wait
+//   policy-builder merge --step reinstall ...  sign and submit
+//
+// The detach uninstalls the policy, which resets every counter on the rule and
+// leaves it unpoliced until the reinstall confirms. Both are reported as
+// warnings rather than left for the operator to discover afterwards.
+import { runMergePolicy } from '@crediolabs/policy-synth/run';
+import { CliError, formatToolResponse, parsePairs } from "../output.js";
+function missing(message) {
+    return new CliError({
+        code: 'CLI_MISSING_ARG',
+        message,
+        severity: 'error',
+        retryable: false,
+    });
+}
+function required(pairs, name) {
+    const value = pairs[name];
+    if (!value)
+        throw missing(`merge: --${name} is required`);
+    return value;
+}
+export async function runMergeCommand(argv, flags) {
+    const pairs = parsePairs(argv);
+    const step = required(pairs, 'step');
+    if (step !== 'detach' && step !== 'reinstall') {
+        throw missing("merge: --step must be 'detach' or 'reinstall'");
+    }
+    const ruleId = Number(required(pairs, 'rule-id'));
+    if (!Number.isInteger(ruleId) || ruleId < 0) {
+        throw missing('merge: --rule-id must be a non-negative integer');
+    }
+    const res = await runMergePolicy({
+        smartAccount: required(pairs, 'smart-account'),
+        sourceAccount: required(pairs, 'source-account'),
+        ruleId,
+        incomingPredicateBlobBase64: required(pairs, 'predicate'),
+        step,
+        ...(pairs.network ? { network: pairs.network } : {}),
+        ...(pairs['rpc-url'] ? { rpcUrl: pairs['rpc-url'] } : {}),
+        ...(pairs['allow-unpinned-rpc-url'] === 'true' ? { allowUnpinnedRpcUrl: true } : {}),
+    });
+    return formatToolResponse(res, flags);
+}

package/dist/src/commands/record.js

@@ -1,4 +1,4 @@
-// apps/policy-builder-cli/src/commands/record.ts
+// packages/policy-builder-cli/src/commands/record.ts
 //
 // `policy-builder record` subcommand. Thin wrapper around the core
 // `recordTransaction` - no business logic, just argv -> RecordInput + the

package/dist/src/commands/synthesize.js

@@ -1,4 +1,4 @@
-// apps/policy-builder-cli/src/commands/synthesize.ts
+// packages/policy-builder-cli/src/commands/synthesize.ts
 //
 // `policy-builder synthesize` subcommand. Dispatches to ONE of the two
 // front-ends (mandate / recording) based on which file flag is supplied:
@@ -48,14 +48,7 @@ export async function runSynthesizeCommand(argv, flags) {
     if (hasMandate) {
         const mandate = readJsonFile(pairs.mandate);
         const args = { source: 'mandate', mandate };
-        if (pairs['oz-config'] !== undefined) {
-            args.ozConfig = readOzConfigFile(pairs['oz-config']);
-        }
-        if (pairs.confidence !== undefined) {
-            args.confidenceOverride = { threshold: parseConfidence(pairs.confidence) };
-        }
-        if (explain)
-            args.explain = true;
+        applySharedFlags(args, pairs, explain);
         const res = await runSynthesizePolicy(args);
         if (explain)
             emitExplainBlock(res, flags);
@@ -84,10 +77,7 @@ export async function runSynthesizeCommand(argv, flags) {
     const userResponses = {};
     if (pairs.responses) {
         const file = readJsonFile(pairs.responses);
-        if (file !== null && typeof file === 'object' && !Array.isArray(file)) {
-            Object.assign(userResponses, file);
-        }
-        else {
+        if (file === null || typeof file !== 'object' || Array.isArray(file)) {
             throw new CliError({
                 code: 'CLI_INVALID_JSON',
                 message: `synthesize: --responses ${pairs.responses} must be a JSON object`,
@@ -95,48 +85,43 @@ export async function runSynthesizeCommand(argv, flags) {
                 retryable: false,
             });
         }
+        Object.assign(userResponses, file);
     }
-    if (pairs['window-seconds'] !== undefined) {
-        userResponses.windowSeconds = parsePositiveInt(pairs['window-seconds'], '--window-seconds');
-    }
-    if (pairs['valid-until'] !== undefined) {
-        userResponses.validUntilLedger = parsePositiveInt(pairs['valid-until'], '--valid-until');
-    }
-    if (pairs['limit-amount'] !== undefined) {
-        userResponses.limitAmount = parseI128String(pairs['limit-amount'], '--limit-amount');
-    }
-    if (pairs['invocation-limit'] !== undefined) {
-        userResponses.invocationLimit = parsePositiveInt(pairs['invocation-limit'], '--invocation-limit');
+    // Per-field overrides. Each entry: argv flag name, userResponses key,
+    // and a parser that validates the raw string.
+    const userResponseFlags = [
+        ['window-seconds', 'windowSeconds', parsePositiveInt],
+        ['valid-until', 'validUntilLedger', parsePositiveInt],
+        ['limit-amount', 'limitAmount', parseI128String],
+        ['invocation-limit', 'invocationLimit', parsePositiveInt],
+    ];
+    for (const [flag, key, parse] of userResponseFlags) {
+        if (pairs[flag] !== undefined) {
+            userResponses[key] = parse(pairs[flag], `--${flag}`);
+        }
     }
     // --recipient <C...|G...> is REPEATABLE (parsePairs collapses duplicate keys,
     // so it is collected straight from argv). Each value builds the swap-recipient
     // allowlist; supplying it REPLACES the default pin to the recorded recipient.
     const recipients = collectRepeated(argv, 'recipient');
-    if (recipients.length > 0) {
-        for (const r of recipients) {
-            // Same validator the run-layer schema applies (SDK StrKey underneath) - a
-            // swap recipient may be a G... wallet or a C... contract. Shared rather
-            // than re-inlined so the CLI and the schema cannot drift apart.
-            if (!isStellarAddress(r)) {
-                throw new CliError({
-                    code: 'CLI_MISSING_ARG',
-                    message: `synthesize: --recipient "${r}" is not a valid Stellar address (expected a G... wallet or C... contract)`,
-                    severity: 'error',
-                    retryable: false,
-                });
-            }
+    for (const r of recipients) {
+        // Same validator the run-layer schema applies (SDK StrKey underneath) - a
+        // swap recipient may be a G... wallet or a C... contract. Shared rather
+        // than re-inlined so the CLI and the schema cannot drift apart.
+        if (!isStellarAddress(r)) {
+            throw new CliError({
+                code: 'CLI_MISSING_ARG',
+                message: `synthesize: --recipient "${r}" is not a valid Stellar address (expected a G... wallet or C... contract)`,
+                severity: 'error',
+                retryable: false,
+            });
         }
-        userResponses.swapRecipientAllowlist = recipients;
     }
-    if (Object.keys(userResponses).length > 0) {
+    if (recipients.length > 0)
+        userResponses.swapRecipientAllowlist = recipients;
+    if (Object.keys(userResponses).length > 0)
         args.userResponses = userResponses;
-    }
-    if (pairs['oz-config'] !== undefined) {
-        args.ozConfig = readOzConfigFile(pairs['oz-config']);
-    }
-    if (pairs.confidence !== undefined) {
-        args.confidenceOverride = { threshold: parseConfidence(pairs.confidence) };
-    }
+    applySharedFlags(args, pairs, explain);
     // --smart-account <C...> opts into the interpreter adapter, so constraints OZ
     // cannot express (per-method scoping, invocation-count windows, oracle bounds,
     // exact hop paths) lower to a real predicate document instead of just warnings.
@@ -146,31 +131,32 @@ export async function runSynthesizeCommand(argv, flags) {
     // without `--smart-account` are rejected up front instead of being silently
     // dropped. The foot-gun: an empty value previously produced an "ok" envelope
     // with 0 policyDocuments, so callers thought the constraint had been enforced
-    // when in fact it had been silently skipped.
+    // when it had been silently skipped.
     const smartAccountRaw = pairs['smart-account'];
     const installNonceRaw = pairs['install-nonce'];
     const oracleStalenessRaw = pairs['oracle-max-staleness'];
     const oracleDeviationRaw = pairs['oracle-max-deviation'];
-    if (installNonceRaw !== undefined && smartAccountRaw === undefined) {
-        throw new CliError({
-            code: 'CLI_MISSING_ARG',
-            message: 'synthesize: --install-nonce requires --smart-account <C...> (interpreter opt-in)',
-            severity: 'error',
-            retryable: false,
-        });
-    }
-    // Oracle params are an interpreter-only knob; reject up front so they cannot
-    // be silently dropped when --smart-account is absent.
-    if ((oracleStalenessRaw !== undefined || oracleDeviationRaw !== undefined) &&
-        smartAccountRaw === undefined) {
-        throw new CliError({
-            code: 'CLI_MISSING_ARG',
-            message: 'synthesize: --oracle-max-staleness / --oracle-max-deviation require --smart-account <C...> (interpreter opt-in)',
-            severity: 'error',
-            retryable: false,
-        });
+    // --install-nonce and the oracle knobs are interpreter-only. Reject up
+    // front so they cannot be silently dropped when --smart-account is absent.
+    if (smartAccountRaw === undefined) {
+        if (installNonceRaw !== undefined) {
+            throw new CliError({
+                code: 'CLI_MISSING_ARG',
+                message: 'synthesize: --install-nonce requires --smart-account <C...> (interpreter opt-in)',
+                severity: 'error',
+                retryable: false,
+            });
+        }
+        if (oracleStalenessRaw !== undefined || oracleDeviationRaw !== undefined) {
+            throw new CliError({
+                code: 'CLI_MISSING_ARG',
+                message: 'synthesize: --oracle-max-staleness / --oracle-max-deviation require --smart-account <C...> (interpreter opt-in)',
+                severity: 'error',
+                retryable: false,
+            });
+        }
     }
-    if (smartAccountRaw !== undefined) {
+    else {
         const smartAccount = smartAccountRaw.trim();
         if (smartAccount.length === 0) {
             throw new CliError({
@@ -227,6 +213,19 @@ export async function runSynthesizeCommand(argv, flags) {
         emitExplainBlock(res, flags);
     return formatToolResponse(res, flags, 'synthesize(recording)');
 }
+/** Apply flags shared between the mandate and recording synthesize paths:
+ *  --oz-config, --confidence, --explain. Pulled out so adding a shared flag
+ *  adds one branch here rather than two copies in the command body. */
+function applySharedFlags(args, pairs, explain) {
+    if (pairs['oz-config'] !== undefined) {
+        args.ozConfig = readOzConfigFile(pairs['oz-config']);
+    }
+    if (pairs.confidence !== undefined) {
+        args.confidenceOverride = { threshold: parseConfidence(pairs.confidence) };
+    }
+    if (explain)
+        args.explain = true;
+}
 /** Augment the tool response envelope with the --explain fields and
  *  (in non-JSON mode) print the review card readably. The CLI is the
  *  single seam that places `review` + `predicateTree` on the wire
@@ -301,9 +300,11 @@ function parseConfidence(raw) {
 }
 /** Parse a strictly positive integer (windowSeconds, validUntilLedger,
  *  invocationLimit, oracleParams bounds). The core re-validates these with
- *  field-specific caps; the CLI just enforces "looks like an integer > 0". */
+ *  field-specific caps; the CLI just enforces "looks like an integer > 0".
+ *  The `^[0-9]+$` regex already pins the shape to a non-negative integer, so
+ *  the only thing left to check is "not zero". */
 function parsePositiveInt(raw, flagName) {
-    if (!POSITIVE_INT_RE.test(raw)) {
+    if (!POSITIVE_INT_RE.test(raw) || raw === '0') {
         throw new CliError({
             code: 'CLI_MISSING_ARG',
             message: `synthesize: ${flagName} "${raw}" must be a positive integer`,
@@ -311,16 +312,7 @@ function parsePositiveInt(raw, flagName) {
             retryable: false,
         });
     }
-    const n = Number(raw);
-    if (!Number.isInteger(n) || n <= 0) {
-        throw new CliError({
-            code: 'CLI_MISSING_ARG',
-            message: `synthesize: ${flagName} "${raw}" must be a positive integer`,
-            severity: 'error',
-            retryable: false,
-        });
-    }
-    return n;
+    return Number(raw);
 }
 /** Collect ALL values for a repeatable `--<name> <value>` / `--<name>=<value>`
  *  flag from argv, in order. Unlike `parsePairs` (which keeps only the last

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
+export { runMergeCommand } from './commands/merge.ts';
 export { runRecordCommand } from './commands/record.ts';
 export { runSynthesizeCommand } from './commands/synthesize.ts';
 export { formatToolResponse, readJsonFile, writeJsonFile } from './output.ts';

package/dist/src/index.js

@@ -1,4 +1,5 @@
-// apps/policy-builder-cli/src/index.ts - public re-exports for the CLI package.
+// packages/policy-builder-cli/src/index.ts - public re-exports for the CLI package.
+export { runMergeCommand } from "./commands/merge.js";
 export { runRecordCommand } from "./commands/record.js";
 export { runSynthesizeCommand } from "./commands/synthesize.js";
 export { formatToolResponse, readJsonFile, writeJsonFile } from "./output.js";

package/dist/src/output.js

@@ -1,4 +1,4 @@
-// apps/policy-builder-cli/src/output.ts
+// packages/policy-builder-cli/src/output.ts
 //
 // Output helpers for the CLI: formatToolResponse for the `--json` flag and
 // file I/O for `--out`. The CLI is intentionally tiny - no commander / yargs
@@ -110,20 +110,19 @@ export function writeJsonFile(path, value) {
  *  Throws CliError so the router can map it to a process exit code + a
  *  structured JSON envelope under --json. */
 export function formatToolResponse(res, flags, outLabel = 'result') {
-    if (res.ok) {
-        const envelope = { ok: true, data: res.data };
-        if (flags.out)
-            writeJsonFile(flags.out, envelope);
-        if (flags.json) {
-            // newline-terminated JSON so it pipes cleanly
-            process.stdout.write(`${JSON.stringify(envelope)}\n`);
-        }
-        else if (!flags.quiet) {
-            process.stdout.write(`${outLabel}: ok\n`);
-        }
-        return res.data;
+    if (!res.ok)
+        throw new CliError(res.error);
+    const envelope = { ok: true, data: res.data };
+    if (flags.out)
+        writeJsonFile(flags.out, envelope);
+    if (flags.json) {
+        // newline-terminated JSON so it pipes cleanly
+        process.stdout.write(`${JSON.stringify(envelope)}\n`);
+    }
+    else if (!flags.quiet) {
+        process.stdout.write(`${outLabel}: ok\n`);
     }
-    throw new CliError(res.error);
+    return res.data;
 }
 /** CLI-local error class wrapping a (core or CLI) ToolError so the router can
  *  map it to a non-zero exit. The error is preserved verbatim for --json. */

package/dist-cjs/src/commands/merge.d.ts

@@ -0,0 +1,2 @@
+import { type CliFlags } from '../output.ts';
+export declare function runMergeCommand(argv: ReadonlyArray<string>, flags: CliFlags): Promise<import("@crediolabs/policy-synth/run").MergePolicyResult>;

package/dist-cjs/src/commands/merge.js

@@ -0,0 +1,61 @@
+"use strict";
+// packages/policy-builder-cli/src/commands/merge.ts
+//
+// `policy-builder merge` subcommand. The tightening remedy for a cross-rule
+// authority overlap.
+//
+// OpenZeppelin enforces only the policies of the context rule a signer NAMES,
+// so a signer in several rules picks which one applies and their authority is
+// the maximum over the matching rules. Adding a second, tighter rule therefore
+// restricts nothing. To actually tighten, the restriction has to become ONE
+// predicate: the conjunction of the installed one and the new one.
+//
+// Two transactions, in order, because `add_policy` refuses a policy already
+// attached to the rule:
+//
+//   policy-builder merge --step detach    ...  sign and submit, wait
+//   policy-builder merge --step reinstall ...  sign and submit
+//
+// The detach uninstalls the policy, which resets every counter on the rule and
+// leaves it unpoliced until the reinstall confirms. Both are reported as
+// warnings rather than left for the operator to discover afterwards.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMergeCommand = runMergeCommand;
+const run_1 = require("@crediolabs/policy-synth/run");
+const output_ts_1 = require("../output.js");
+function missing(message) {
+    return new output_ts_1.CliError({
+        code: 'CLI_MISSING_ARG',
+        message,
+        severity: 'error',
+        retryable: false,
+    });
+}
+function required(pairs, name) {
+    const value = pairs[name];
+    if (!value)
+        throw missing(`merge: --${name} is required`);
+    return value;
+}
+async function runMergeCommand(argv, flags) {
+    const pairs = (0, output_ts_1.parsePairs)(argv);
+    const step = required(pairs, 'step');
+    if (step !== 'detach' && step !== 'reinstall') {
+        throw missing("merge: --step must be 'detach' or 'reinstall'");
+    }
+    const ruleId = Number(required(pairs, 'rule-id'));
+    if (!Number.isInteger(ruleId) || ruleId < 0) {
+        throw missing('merge: --rule-id must be a non-negative integer');
+    }
+    const res = await (0, run_1.runMergePolicy)({
+        smartAccount: required(pairs, 'smart-account'),
+        sourceAccount: required(pairs, 'source-account'),
+        ruleId,
+        incomingPredicateBlobBase64: required(pairs, 'predicate'),
+        step,
+        ...(pairs.network ? { network: pairs.network } : {}),
+        ...(pairs['rpc-url'] ? { rpcUrl: pairs['rpc-url'] } : {}),
+        ...(pairs['allow-unpinned-rpc-url'] === 'true' ? { allowUnpinnedRpcUrl: true } : {}),
+    });
+    return (0, output_ts_1.formatToolResponse)(res, flags);
+}

package/dist-cjs/src/commands/record.js

@@ -1,5 +1,5 @@
 "use strict";
-// apps/policy-builder-cli/src/commands/record.ts
+// packages/policy-builder-cli/src/commands/record.ts
 //
 // `policy-builder record` subcommand. Thin wrapper around the core
 // `recordTransaction` - no business logic, just argv -> RecordInput + the