@crediolabs/policy-builder-cli 0.3.1 → 0.5.0

package/dist/bin/policy-builder.js

@@ -4,6 +4,10 @@
 // Usage:
 //   policy-builder record --network <mainnet|testnet> --hash <tx>
 //                                 [--xdr <b64>] [--json] [--quiet] [--out <path>]
+//   policy-builder declare --network <mainnet|testnet> --fn <method>
+//                              [--token native|C...] [--max-amount <smallest-unit>]
+//                              [--to G...,G...] [--amount-arg N] [--to-arg N]
+//                              [--allow-zero-cap] [--json] [--quiet] [--out <path>]
 //   policy-builder synthesize --recorded-tx <path.json> --network <mainnet|testnet>
 //                              [--responses <path.json>]
 //                              [--confidence <0..1>]
@@ -21,6 +25,7 @@
 // `command + subcommand-flags + global-flags` and dispatches to the matching
 // command body. Bad args -> CliError -> non-zero exit (JSON envelope under
 // --json).
+import { runDeclareCommand } from "../src/commands/declare.js";
 import { runRecordCommand } from "../src/commands/record.js";
 import { runSynthesizeCommand } from "../src/commands/synthesize.js";
 import { emitCliError, parseFlags } from "../src/output.js";
@@ -37,6 +42,9 @@ async function main() {
             case 'record':
                 await runRecordCommand(subcommandArgs, flags);
                 return;
+            case 'declare':
+                await runDeclareCommand(subcommandArgs, flags);
+                return;
             case 'synthesize':
             case 'synth': {
                 await runSynthesizeCommand(subcommandArgs, flags);
@@ -64,6 +72,10 @@ function printHelp() {
 Usage:
   policy-builder record     --network <mainnet|testnet> --hash <tx> | --xdr <b64>
                             [--json] [--quiet] [--out <path>]
+  policy-builder declare    --network <mainnet|testnet> --fn <method>
+                            [--token native|C...] [--max-amount <smallest-unit>]
+                            [--to G...,G...] [--amount-arg N] [--to-arg N]
+                            [--allow-zero-cap] [--json] [--quiet] [--out <path>]
   policy-builder synthesize --recorded-tx <path.json> --network <mainnet|testnet>
                             [--responses <path.json>]
                             [--confidence <0..1>]

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

@@ -0,0 +1,9 @@
+import { type CliFlags } from '../output.ts';
+interface DeclareResult {
+    predicate: unknown;
+    encodedPredicate: string;
+    predicateHash: string;
+    warnings: string[];
+}
+export declare function runDeclareCommand(argv: ReadonlyArray<string>, flags: CliFlags): Promise<DeclareResult>;
+export {};

package/dist/src/commands/declare.js

@@ -0,0 +1,79 @@
+// packages/policy-builder-cli/src/commands/declare.ts
+//
+// `policy-builder declare` subcommand. The declarative counterpart to
+// `synthesize`: instead of inferring a predicate from a transaction that
+// happened, it takes the constraint stated outright.
+//
+// Thin wrapper around `runDeclarePolicy` - no business logic, just argv ->
+// DeclarePolicyInput + the canonical CLI envelope.
+//
+// `--token native` resolves to the network's native SAC, which is why this
+// command takes --network: the native SAC address differs per network, and
+// pinning the wrong one produces a policy that silently matches nothing.
+import { runDeclarePolicy } from '@crediolabs/policy-synth/run';
+import { Asset, Networks } from '@stellar/stellar-sdk';
+import { CliError, formatToolResponse, parsePairs } from "../output.js";
+function missing(message) {
+    return new CliError({ code: 'CLI_MISSING_ARG', message, severity: 'error', retryable: false });
+}
+export async function runDeclareCommand(argv, flags) {
+    const pairs = parsePairs(argv);
+    const network = pairs.network;
+    if (network !== 'mainnet' && network !== 'testnet') {
+        throw missing('declare: --network <mainnet|testnet> is required');
+    }
+    if (!pairs.fn) {
+        throw missing('declare: --fn <method> is required (the method the policy pins)');
+    }
+    const args = { fn: pairs.fn };
+    if (pairs.token) {
+        // `native` is resolved HERE rather than in the core: the core stays pure
+        // and network-agnostic, and resolving it needs the passphrase.
+        args.contract =
+            pairs.token === 'native'
+                ? Asset.native().contractId(network === 'mainnet' ? Networks.PUBLIC : Networks.TESTNET)
+                : pairs.token;
+    }
+    if (pairs['max-amount'] !== undefined)
+        args.maxAmount = pairs['max-amount'];
+    if (pairs['amount-arg'] !== undefined)
+        args.amountArgIndex = Number(pairs['amount-arg']);
+    if (pairs.to !== undefined) {
+        args.recipients = pairs.to
+            .split(',')
+            .map((a) => a.trim())
+            .filter(Boolean);
+    }
+    if (pairs['to-arg'] !== undefined)
+        args.recipientArgIndex = Number(pairs['to-arg']);
+    if (pairs['allow-zero-cap'] !== undefined)
+        args.allowZeroCap = true;
+    // Slippage floor: `--min-out-ratio 99/100 --in-arg 0 --out-arg 1`. All four
+    // parts are required together - a ratio with no argument positions cannot
+    // be lowered, and guessing them would bound the wrong values silently.
+    if (pairs['min-out-ratio'] !== undefined) {
+        const [num, den] = String(pairs['min-out-ratio']).split('/');
+        if (!num || !den) {
+            throw missing('declare: --min-out-ratio must be `num/den`, e.g. 99/100 for a 1% floor');
+        }
+        if (pairs['in-arg'] === undefined || pairs['out-arg'] === undefined) {
+            throw missing('declare: --min-out-ratio also needs --in-arg <i> and --out-arg <j>');
+        }
+        args.minOutputRatio = {
+            num,
+            den,
+            inputArgIndex: Number(pairs['in-arg']),
+            outputArgIndex: Number(pairs['out-arg']),
+        };
+    }
+    const res = runDeclarePolicy(args);
+    const data = formatToolResponse(res, flags, 'declare');
+    // Warnings go to stderr so `--json` stdout stays a clean envelope, but they
+    // are never silent: each one names an argument index that was GUESSED, and
+    // a bound on the wrong argument constrains nothing while looking correct.
+    if (!flags.quiet) {
+        for (const w of data.warnings)
+            process.stderr.write(`warning: ${w}\n`);
+    }
+    return data;
+}

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
+export { runDeclareCommand } from './commands/declare.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 @@
 // packages/policy-builder-cli/src/index.ts - public re-exports for the CLI package.
+export { runDeclareCommand } from "./commands/declare.js";
 export { runRecordCommand } from "./commands/record.js";
 export { runSynthesizeCommand } from "./commands/synthesize.js";
 export { formatToolResponse, readJsonFile, writeJsonFile } from "./output.js";

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

@@ -0,0 +1,9 @@
+import { type CliFlags } from '../output.ts';
+interface DeclareResult {
+    predicate: unknown;
+    encodedPredicate: string;
+    predicateHash: string;
+    warnings: string[];
+}
+export declare function runDeclareCommand(argv: ReadonlyArray<string>, flags: CliFlags): Promise<DeclareResult>;
+export {};

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

@@ -0,0 +1,82 @@
+"use strict";
+// packages/policy-builder-cli/src/commands/declare.ts
+//
+// `policy-builder declare` subcommand. The declarative counterpart to
+// `synthesize`: instead of inferring a predicate from a transaction that
+// happened, it takes the constraint stated outright.
+//
+// Thin wrapper around `runDeclarePolicy` - no business logic, just argv ->
+// DeclarePolicyInput + the canonical CLI envelope.
+//
+// `--token native` resolves to the network's native SAC, which is why this
+// command takes --network: the native SAC address differs per network, and
+// pinning the wrong one produces a policy that silently matches nothing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeclareCommand = runDeclareCommand;
+const run_1 = require("@crediolabs/policy-synth/run");
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+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 });
+}
+async function runDeclareCommand(argv, flags) {
+    const pairs = (0, output_ts_1.parsePairs)(argv);
+    const network = pairs.network;
+    if (network !== 'mainnet' && network !== 'testnet') {
+        throw missing('declare: --network <mainnet|testnet> is required');
+    }
+    if (!pairs.fn) {
+        throw missing('declare: --fn <method> is required (the method the policy pins)');
+    }
+    const args = { fn: pairs.fn };
+    if (pairs.token) {
+        // `native` is resolved HERE rather than in the core: the core stays pure
+        // and network-agnostic, and resolving it needs the passphrase.
+        args.contract =
+            pairs.token === 'native'
+                ? stellar_sdk_1.Asset.native().contractId(network === 'mainnet' ? stellar_sdk_1.Networks.PUBLIC : stellar_sdk_1.Networks.TESTNET)
+                : pairs.token;
+    }
+    if (pairs['max-amount'] !== undefined)
+        args.maxAmount = pairs['max-amount'];
+    if (pairs['amount-arg'] !== undefined)
+        args.amountArgIndex = Number(pairs['amount-arg']);
+    if (pairs.to !== undefined) {
+        args.recipients = pairs.to
+            .split(',')
+            .map((a) => a.trim())
+            .filter(Boolean);
+    }
+    if (pairs['to-arg'] !== undefined)
+        args.recipientArgIndex = Number(pairs['to-arg']);
+    if (pairs['allow-zero-cap'] !== undefined)
+        args.allowZeroCap = true;
+    // Slippage floor: `--min-out-ratio 99/100 --in-arg 0 --out-arg 1`. All four
+    // parts are required together - a ratio with no argument positions cannot
+    // be lowered, and guessing them would bound the wrong values silently.
+    if (pairs['min-out-ratio'] !== undefined) {
+        const [num, den] = String(pairs['min-out-ratio']).split('/');
+        if (!num || !den) {
+            throw missing('declare: --min-out-ratio must be `num/den`, e.g. 99/100 for a 1% floor');
+        }
+        if (pairs['in-arg'] === undefined || pairs['out-arg'] === undefined) {
+            throw missing('declare: --min-out-ratio also needs --in-arg <i> and --out-arg <j>');
+        }
+        args.minOutputRatio = {
+            num,
+            den,
+            inputArgIndex: Number(pairs['in-arg']),
+            outputArgIndex: Number(pairs['out-arg']),
+        };
+    }
+    const res = (0, run_1.runDeclarePolicy)(args);
+    const data = (0, output_ts_1.formatToolResponse)(res, flags, 'declare');
+    // Warnings go to stderr so `--json` stdout stays a clean envelope, but they
+    // are never silent: each one names an argument index that was GUESSED, and
+    // a bound on the wrong argument constrains nothing while looking correct.
+    if (!flags.quiet) {
+        for (const w of data.warnings)
+            process.stderr.write(`warning: ${w}\n`);
+    }
+    return data;
+}

package/dist-cjs/src/index.d.ts

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

package/dist-cjs/src/index.js

@@ -1,7 +1,9 @@
 "use strict";
 // 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;
+exports.writeJsonFile = exports.readJsonFile = exports.formatToolResponse = exports.runSynthesizeCommand = exports.runRecordCommand = exports.runDeclareCommand = void 0;
+var declare_ts_1 = require("./commands/declare.js");
+Object.defineProperty(exports, "runDeclareCommand", { enumerable: true, get: function () { return declare_ts_1.runDeclareCommand; } });
 var record_ts_1 = require("./commands/record.js");
 Object.defineProperty(exports, "runRecordCommand", { enumerable: true, get: function () { return record_ts_1.runRecordCommand; } });
 var synthesize_ts_1 = require("./commands/synthesize.js");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-builder-cli",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "CLI wrapper around the OZ policy-synth core (record + synthesize) for solo-dev and CI workflows.",
   "type": "module",
@@ -63,7 +63,7 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@crediolabs/policy-synth": "0.3.1",
+    "@crediolabs/policy-synth": "0.5.0",
     "@stellar/stellar-sdk": "14.4.0",
     "zod": "3.25.76"
   },

package/src/commands/declare.ts

@@ -0,0 +1,91 @@
+// packages/policy-builder-cli/src/commands/declare.ts
+//
+// `policy-builder declare` subcommand. The declarative counterpart to
+// `synthesize`: instead of inferring a predicate from a transaction that
+// happened, it takes the constraint stated outright.
+//
+// Thin wrapper around `runDeclarePolicy` - no business logic, just argv ->
+// DeclarePolicyInput + the canonical CLI envelope.
+//
+// `--token native` resolves to the network's native SAC, which is why this
+// command takes --network: the native SAC address differs per network, and
+// pinning the wrong one produces a policy that silently matches nothing.
+
+import { runDeclarePolicy } from '@crediolabs/policy-synth/run'
+import { Asset, Networks } from '@stellar/stellar-sdk'
+import { CliError, type CliFlags, formatToolResponse, parsePairs } from '../output.ts'
+
+interface DeclareResult {
+  predicate: unknown
+  encodedPredicate: string
+  predicateHash: string
+  warnings: string[]
+}
+
+function missing(message: string): CliError {
+  return new CliError({ code: 'CLI_MISSING_ARG', message, severity: 'error', retryable: false })
+}
+
+export async function runDeclareCommand(
+  argv: ReadonlyArray<string>,
+  flags: CliFlags
+): Promise<DeclareResult> {
+  const pairs = parsePairs(argv)
+  const network = pairs.network
+  if (network !== 'mainnet' && network !== 'testnet') {
+    throw missing('declare: --network <mainnet|testnet> is required')
+  }
+  if (!pairs.fn) {
+    throw missing('declare: --fn <method> is required (the method the policy pins)')
+  }
+
+  const args: Record<string, unknown> = { fn: pairs.fn }
+
+  if (pairs.token) {
+    // `native` is resolved HERE rather than in the core: the core stays pure
+    // and network-agnostic, and resolving it needs the passphrase.
+    args.contract =
+      pairs.token === 'native'
+        ? Asset.native().contractId(network === 'mainnet' ? Networks.PUBLIC : Networks.TESTNET)
+        : pairs.token
+  }
+  if (pairs['max-amount'] !== undefined) args.maxAmount = pairs['max-amount']
+  if (pairs['amount-arg'] !== undefined) args.amountArgIndex = Number(pairs['amount-arg'])
+  if (pairs.to !== undefined) {
+    args.recipients = (pairs.to as string)
+      .split(',')
+      .map((a) => a.trim())
+      .filter(Boolean)
+  }
+  if (pairs['to-arg'] !== undefined) args.recipientArgIndex = Number(pairs['to-arg'])
+  if (pairs['allow-zero-cap'] !== undefined) args.allowZeroCap = true
+  // Slippage floor: `--min-out-ratio 99/100 --in-arg 0 --out-arg 1`. All four
+  // parts are required together - a ratio with no argument positions cannot
+  // be lowered, and guessing them would bound the wrong values silently.
+  if (pairs['min-out-ratio'] !== undefined) {
+    const [num, den] = String(pairs['min-out-ratio']).split('/')
+    if (!num || !den) {
+      throw missing('declare: --min-out-ratio must be `num/den`, e.g. 99/100 for a 1% floor')
+    }
+    if (pairs['in-arg'] === undefined || pairs['out-arg'] === undefined) {
+      throw missing('declare: --min-out-ratio also needs --in-arg <i> and --out-arg <j>')
+    }
+    args.minOutputRatio = {
+      num,
+      den,
+      inputArgIndex: Number(pairs['in-arg']),
+      outputArgIndex: Number(pairs['out-arg']),
+    }
+  }
+
+  const res = runDeclarePolicy(args)
+  const data = formatToolResponse(res, flags, 'declare') as DeclareResult
+
+  // Warnings go to stderr so `--json` stdout stays a clean envelope, but they
+  // are never silent: each one names an argument index that was GUESSED, and
+  // a bound on the wrong argument constrains nothing while looking correct.
+  if (!flags.quiet) {
+    for (const w of data.warnings) process.stderr.write(`warning: ${w}\n`)
+  }
+  return data
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 // packages/policy-builder-cli/src/index.ts - public re-exports for the CLI package.
 
+export { runDeclareCommand } from './commands/declare.ts'
 export { runRecordCommand } from './commands/record.ts'
 export { runSynthesizeCommand } from './commands/synthesize.ts'
 export { formatToolResponse, readJsonFile, writeJsonFile } from './output.ts'