@crediolabs/policy-builder-cli 0.1.16 → 0.1.18

package/README.md

@@ -1,132 +1,67 @@
 # @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. The on-chain interpreter the
+policies target is **unaudited**; see the
+[architecture document](https://github.com/untangledfinance/octogate/blob/main/docs/architecture.md).
 
 ## 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>

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.js

@@ -1,4 +1,4 @@
-// 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 { 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/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

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

@@ -1,5 +1,5 @@
 "use strict";
-// 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:
@@ -51,14 +51,7 @@ async function runSynthesizeCommand(argv, flags) {
     if (hasMandate) {
         const mandate = (0, output_ts_1.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 (0, run_1.runSynthesizePolicy)(args);
         if (explain)
             emitExplainBlock(res, flags);
@@ -87,10 +80,7 @@ async function runSynthesizeCommand(argv, flags) {
     const userResponses = {};
     if (pairs.responses) {
         const file = (0, output_ts_1.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 output_ts_1.CliError({
                 code: 'CLI_INVALID_JSON',
                 message: `synthesize: --responses ${pairs.responses} must be a JSON object`,
@@ -98,48 +88,43 @@ 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 (!(0, policy_synth_1.isStellarAddress)(r)) {
-                throw new output_ts_1.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 (!(0, policy_synth_1.isStellarAddress)(r)) {
+            throw new output_ts_1.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.
@@ -149,31 +134,32 @@ 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 output_ts_1.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 output_ts_1.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 output_ts_1.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 output_ts_1.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 output_ts_1.CliError({
@@ -230,6 +216,19 @@ async function runSynthesizeCommand(argv, flags) {
         emitExplainBlock(res, flags);
     return (0, output_ts_1.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
@@ -304,9 +303,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 output_ts_1.CliError({
             code: 'CLI_MISSING_ARG',
             message: `synthesize: ${flagName} "${raw}" must be a positive integer`,
@@ -314,16 +315,7 @@ function parsePositiveInt(raw, flagName) {
             retryable: false,
         });
     }
-    const n = Number(raw);
-    if (!Number.isInteger(n) || n <= 0) {
-        throw new output_ts_1.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-cjs/src/index.js

@@ -1,5 +1,5 @@
 "use strict";
-// 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.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeJsonFile = exports.readJsonFile = exports.formatToolResponse = exports.runSynthesizeCommand = exports.runRecordCommand = void 0;
 var record_ts_1 = require("./commands/record.js");

package/dist-cjs/src/output.js

@@ -1,5 +1,5 @@
 "use strict";
-// 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
@@ -119,20 +119,19 @@ function writeJsonFile(path, value) {
  *  Throws CliError so the router can map it to a process exit code + a
  *  structured JSON envelope under --json. */
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-builder-cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "license": "MIT",
   "description": "CLI wrapper around the OZ policy-synth core (record + synthesize) for solo-dev and CI workflows.",
   "type": "module",
@@ -12,12 +12,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/untangledfinance/oz-policy-builder.git",
-    "directory": "apps/policy-builder-cli"
+    "url": "https://github.com/untangledfinance/octogate.git",
+    "directory": "packages/policy-builder-cli"
   },
-  "homepage": "https://github.com/untangledfinance/oz-policy-builder#readme",
+  "homepage": "https://github.com/untangledfinance/octogate#readme",
   "bugs": {
-    "url": "https://github.com/untangledfinance/oz-policy-builder/issues"
+    "url": "https://github.com/untangledfinance/octogate/issues"
   },
   "keywords": [
     "stellar",
@@ -63,7 +63,7 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@crediolabs/policy-synth": "0.1.15",
+    "@crediolabs/policy-synth": "0.1.18",
     "@stellar/stellar-sdk": "14.4.0",
     "zod": "3.25.76"
   },

package/src/commands/record.ts

@@ -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/src/commands/synthesize.ts

@@ -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:
@@ -72,13 +72,7 @@ export async function runSynthesizeCommand(
   if (hasMandate) {
     const mandate = readJsonFile(pairs.mandate as string) as Record<string, unknown>
     const args: Record<string, unknown> = { source: 'mandate', mandate }
-    if (pairs['oz-config'] !== undefined) {
-      args.ozConfig = readOzConfigFile(pairs['oz-config'] as string)
-    }
-    if (pairs.confidence !== undefined) {
-      args.confidenceOverride = { threshold: parseConfidence(pairs.confidence as string) }
-    }
-    if (explain) args.explain = true
+    applySharedFlags(args, pairs, explain)
     const res = await runSynthesizePolicy(args)
     if (explain) emitExplainBlock(res, flags)
     return formatToolResponse(res, flags, 'synthesize(mandate)')
@@ -109,9 +103,7 @@ export async function runSynthesizeCommand(
   const userResponses: Record<string, unknown> = {}
   if (pairs.responses) {
     const file = readJsonFile(pairs.responses)
-    if (file !== null && typeof file === 'object' && !Array.isArray(file)) {
-      Object.assign(userResponses, file as Record<string, unknown>)
-    } 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`,
@@ -119,58 +111,42 @@ export async function runSynthesizeCommand(
         retryable: false,
       })
     }
+    Object.assign(userResponses, file as Record<string, unknown>)
   }
-  if (pairs['window-seconds'] !== undefined) {
-    userResponses.windowSeconds = parsePositiveInt(
-      pairs['window-seconds'] as string,
-      '--window-seconds'
-    )
-  }
-  if (pairs['valid-until'] !== undefined) {
-    userResponses.validUntilLedger = parsePositiveInt(
-      pairs['valid-until'] as string,
-      '--valid-until'
-    )
-  }
-  if (pairs['limit-amount'] !== undefined) {
-    userResponses.limitAmount = parseI128String(pairs['limit-amount'] as string, '--limit-amount')
-  }
-  if (pairs['invocation-limit'] !== undefined) {
-    userResponses.invocationLimit = parsePositiveInt(
-      pairs['invocation-limit'] as string,
-      '--invocation-limit'
-    )
+  // Per-field overrides. Each entry: argv flag name, userResponses key,
+  // and a parser that validates the raw string.
+  const userResponseFlags: Array<[string, string, (raw: string, flag: string) => unknown]> = [
+    ['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] as string, `--${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) {
-    args.userResponses = userResponses
   }
+  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'] as string)
-  }
-  if (pairs.confidence !== undefined) {
-    args.confidenceOverride = { threshold: parseConfidence(pairs.confidence as string) }
-  }
+  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,
@@ -181,34 +157,32 @@ export async function runSynthesizeCommand(
   // 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,
-    })
-  }
-  if (smartAccountRaw !== undefined) {
+  // --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,
+      })
+    }
+  } else {
     const smartAccount = smartAccountRaw.trim()
     if (smartAccount.length === 0) {
       throw new CliError({
@@ -271,6 +245,23 @@ export async function runSynthesizeCommand(
   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: Record<string, unknown>,
+  pairs: Record<string, string>,
+  explain: boolean
+): void {
+  if (pairs['oz-config'] !== undefined) {
+    args.ozConfig = readOzConfigFile(pairs['oz-config'] as string)
+  }
+  if (pairs.confidence !== undefined) {
+    args.confidenceOverride = { threshold: parseConfidence(pairs.confidence as string) }
+  }
+  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
@@ -366,9 +357,11 @@ function parseConfidence(raw: string): number {
 
 /** 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: string, flagName: string): number {
-  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`,
@@ -376,16 +369,7 @@ function parsePositiveInt(raw: string, flagName: string): number {
       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>`

package/src/index.ts

@@ -1,4 +1,4 @@
-// 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 { runRecordCommand } from './commands/record.ts'
 export { runSynthesizeCommand } from './commands/synthesize.ts'

package/src/output.ts

@@ -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
@@ -120,18 +120,16 @@ export function formatToolResponse<T>(
   flags: CliFlags,
   outLabel = 'result'
 ): T {
-  if (res.ok) {
-    const envelope = { ok: true as const, 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 as const, 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-specific error codes, distinct from the core's ErrorCode union. They