@crediolabs/policy-builder-cli 0.1.6 → 0.1.8

package/src/commands/synthesize.ts

@@ -7,11 +7,23 @@
 //
 // The CLI mirrors the MCP tool's discriminated union: one subcommand, two
 // front-ends, mutually exclusive.
+//
+// Per-field response flags (--window-seconds, --valid-until, --limit-amount,
+// --invocation-limit) merge into `userResponses`. A flag overrides the same
+// field from --responses (CLI flags are explicit; the file is a default bag).
+// Oracle params (--oracle-max-staleness, --oracle-max-deviation) are part of
+// the interpreter opt-in and are rejected without --smart-account; tighten-only
+// bounds are validated by the core.
 
-import { runSynthesizePolicy } from '@crediolabs/policy-builder-mcp'
-import type { ProposedPolicy } from '@crediolabs/policy-synth'
+import { isStellarAddress, type ProposedPolicy } from '@crediolabs/policy-synth'
+import { runSynthesizePolicy } from '@crediolabs/policy-synth/run'
 import { CliError, type CliFlags, formatToolResponse, parsePairs, readJsonFile } from '../output.ts'
 
+// Positive-int flags and i128 amount strings share the same wire shape: a
+// base-10 unsigned decimal, no sign. The i128 stays a string at the boundary
+// because it is wider than Number.MAX_SAFE_INTEGER.
+const POSITIVE_INT_RE = /^[0-9]+$/
+
 export async function runSynthesizeCommand(
   argv: ReadonlyArray<string>,
   flags: CliFlags
@@ -30,7 +42,14 @@ export async function runSynthesizeCommand(
 
   if (hasMandate) {
     const mandate = readJsonFile(pairs.mandate as string) as Record<string, unknown>
-    const res = await runSynthesizePolicy({ source: 'mandate', mandate })
+    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) }
+    }
+    const res = await runSynthesizePolicy(args)
     return formatToolResponse(res, flags, 'synthesize(mandate)')
   }
 
@@ -53,20 +72,257 @@ export async function runSynthesizeCommand(
     })
   }
   const args: Record<string, unknown> = { source: 'recording', recordedTx, network }
+
+  // userResponses precedence: --responses file is the base; per-field flags
+  // override the same field. Only the override'd fields are merged in.
+  const userResponses: Record<string, unknown> = {}
   if (pairs.responses) {
-    args.userResponses = readJsonFile(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 {
+      throw new CliError({
+        code: 'CLI_INVALID_JSON',
+        message: `synthesize: --responses ${pairs.responses} must be a JSON object`,
+        severity: 'error',
+        retryable: false,
+      })
+    }
+  }
+  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'
+    )
   }
+  // --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,
+        })
+      }
+    }
+    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) }
+  }
+
   // --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.
   // The core validates the address and installNonce; a bad value surfaces there.
-  if (pairs['smart-account']) {
-    const interpreter: Record<string, unknown> = { smartAccountAddress: pairs['smart-account'] }
-    if (pairs['install-nonce']) {
-      interpreter.installNonce = Number(pairs['install-nonce'])
+  //
+  // Use `!== undefined` (not truthy) so `--smart-account ""` and `--install-nonce`
+  // 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.
+  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) {
+    const smartAccount = smartAccountRaw.trim()
+    if (smartAccount.length === 0) {
+      throw new CliError({
+        code: 'CLI_MISSING_ARG',
+        message:
+          'synthesize: --smart-account <C...> was passed empty; provide a 56-character contract strkey or omit the flag',
+        severity: 'error',
+        retryable: false,
+      })
+    }
+    if (!/^C[2-7A-Z]{55}$/.test(smartAccount)) {
+      throw new CliError({
+        code: 'CLI_MISSING_ARG',
+        message: `synthesize: --smart-account "${smartAccount}" is not a valid C... contract strkey (expected 56 chars starting with C)`,
+        severity: 'error',
+        retryable: false,
+      })
+    }
+    const interpreter: Record<string, unknown> = { smartAccountAddress: smartAccount }
+    if (installNonceRaw !== undefined) {
+      const nonce = Number(installNonceRaw)
+      if (!Number.isInteger(nonce) || nonce < 0) {
+        throw new CliError({
+          code: 'CLI_MISSING_ARG',
+          message: `synthesize: --install-nonce "${installNonceRaw}" is not a non-negative integer`,
+          severity: 'error',
+          retryable: false,
+        })
+      }
+      interpreter.installNonce = nonce
+    }
+    // Oracle params only attach when at least one bound was provided. The
+    // core validates tighten-only (maxStalenessSeconds <= 600,
+    // maxDeviationBps <= 200) - a too-loose value surfaces as SYNTHESIS_ERROR.
+    if (oracleStalenessRaw !== undefined || oracleDeviationRaw !== undefined) {
+      const oracleParams: Record<string, number> = {}
+      if (oracleStalenessRaw !== undefined) {
+        oracleParams.maxStalenessSeconds = parsePositiveInt(
+          oracleStalenessRaw,
+          '--oracle-max-staleness'
+        )
+      }
+      if (oracleDeviationRaw !== undefined) {
+        oracleParams.maxDeviationBps = parsePositiveInt(
+          oracleDeviationRaw,
+          '--oracle-max-deviation'
+        )
+      }
+      interpreter.oracleParams = oracleParams
     }
     args.interpreter = interpreter
   }
   const res = await runSynthesizePolicy(args)
   return formatToolResponse(res, flags, 'synthesize(recording)')
 }
+
+/** Read and validate an OzAdapterConfig JSON file. Throws CLI_FILE_NOT_FOUND /
+ *  CLI_INVALID_JSON for filesystem / parse failures; the core's strict schema
+ *  on `ozConfig` catches shape mismatches downstream. */
+function readOzConfigFile(path: string): Record<string, unknown> {
+  const value = readJsonFile(path)
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new CliError({
+      code: 'CLI_INVALID_JSON',
+      message: `synthesize: --oz-config ${path} must be a JSON object`,
+      severity: 'error',
+      retryable: false,
+    })
+  }
+  return value as Record<string, unknown>
+}
+
+/** Parse and validate `--confidence <n>` as a finite number in [0, 1]. A
+ *  threshold above 1 would disable the recorder gate; reject it up front. */
+function parseConfidence(raw: string): number {
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n < 0 || n > 1) {
+    throw new CliError({
+      code: 'CLI_MISSING_ARG',
+      message: `synthesize: --confidence "${raw}" must be a finite number within [0, 1]`,
+      severity: 'error',
+      retryable: false,
+    })
+  }
+  return n
+}
+
+/** 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". */
+function parsePositiveInt(raw: string, flagName: string): number {
+  if (!POSITIVE_INT_RE.test(raw)) {
+    throw new CliError({
+      code: 'CLI_MISSING_ARG',
+      message: `synthesize: ${flagName} "${raw}" must be a positive integer`,
+      severity: 'error',
+      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
+}
+
+/** Collect ALL values for a repeatable `--<name> <value>` / `--<name>=<value>`
+ *  flag from argv, in order. Unlike `parsePairs` (which keeps only the last
+ *  occurrence of a key), this preserves every occurrence so a flag like
+ *  `--recipient` can be supplied multiple times to build an allowlist. A
+ *  trailing `--<name>` with no value (or another flag next) is skipped. */
+function collectRepeated(argv: ReadonlyArray<string>, name: string): string[] {
+  const out: string[] = []
+  const eqPrefix = `--${name}=`
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === `--${name}`) {
+      const next = argv[i + 1]
+      if (next !== undefined && !next.startsWith('--')) {
+        out.push(next)
+        i++
+      }
+    } else if (a?.startsWith(eqPrefix)) {
+      out.push(a.slice(eqPrefix.length))
+    }
+  }
+  return out
+}
+
+/** Parse an i128 decimal string (positive, base 10). The synth gate, not the
+ *  CLI, decides what to do with negatives - real recordings carry positive
+ *  amounts on the wire for `limitAmount`. */
+function parseI128String(raw: string, flagName: string): string {
+  if (!POSITIVE_INT_RE.test(raw)) {
+    throw new CliError({
+      code: 'CLI_MISSING_ARG',
+      message: `synthesize: ${flagName} "${raw}" must be a positive decimal integer string (base-10 i128)`,
+      severity: 'error',
+      retryable: false,
+    })
+  }
+  return raw
+}

package/src/output.ts

@@ -37,7 +37,14 @@ export function parseFlags(argv: ReadonlyArray<string>): CliFlags {
 
 /** Resolve `--value <v>` style pairs after the subcommand name. Returns
  *  an object keyed by the option name (without `--`). Throws on missing
- *  value or duplicate keys. */
+ *  value or duplicate keys.
+ *
+ *  Note: an empty value (`--smart-account ""`) IS captured as an empty
+ *  string so the caller can distinguish "flag omitted" from "flag passed
+ *  empty" - a foot-gun: silently dropping empty values caused callers to
+ *  believe the interpreter adapter was engaged when it was not. The next
+ *  token is treated as a value iff it is present and does not start with
+ *  `--`; tokens starting with `--` are never consumed as values. */
 export function parsePairs(argv: ReadonlyArray<string>): Record<string, string> {
   const out: Record<string, string> = {}
   for (let i = 0; i < argv.length; i++) {
@@ -47,11 +54,21 @@ export function parsePairs(argv: ReadonlyArray<string>): Record<string, string>
       const key = a.slice(2, eq)
       const val = a.slice(eq + 1)
       if (key && val !== undefined) out[key] = val
-    } else if (a?.startsWith('--') && argv[i + 1] && !argv[i + 1]?.startsWith('--')) {
+    } else if (a?.startsWith('--')) {
       const key = a.slice(2)
-      const val = argv[i + 1] as string
-      out[key] = val
-      i++
+      if (!key) continue
+      const next = argv[i + 1]
+      // Only consume the next token if it is present AND does not look like
+      // another flag. Empty strings DO count as values so callers can
+      // distinguish "omitted" from "passed empty".
+      if (next !== undefined && !next.startsWith('--')) {
+        out[key] = next
+        i++
+      } else {
+        // Standalone flag (no value) - record as empty string so `!== undefined`
+        // checks upstream can detect presence.
+        out[key] = ''
+      }
     }
   }
   return out