@crediolabs/policy-builder-cli 0.1.11 → 0.1.12

package/dist/bin/policy-builder.js

@@ -6,7 +6,7 @@
 //                                 [--xdr <b64>] [--json] [--quiet] [--out <path>]
 //   policy-builder synthesize --mandate <path.json>
 //                              [--oz-config <path.json>] [--confidence <0..1>]
-//                              [--json] [--quiet] [--out <path>]
+//                              [--explain] [--json] [--quiet] [--out <path>]
 //   policy-builder synthesize --recorded-tx <path.json> --network <mainnet|testnet>
 //                              [--responses <path.json>]
 //                              [--oz-config <path.json>] [--confidence <0..1>]
@@ -15,7 +15,12 @@
 //                              [--window-seconds <n>] [--valid-until <ledger>]
 //                              [--limit-amount <i128str>] [--invocation-limit <n>]
 //                              [--recipient <C...|G...>]...
-//                              [--json] [--quiet] [--out <path>]
+//                              [--explain] [--json] [--quiet] [--out <path>]
+//
+// --explain (Phase 1) makes the synthesised policy human-readable: the
+// output gains `review` (the deterministic review-card summary) and
+// `predicateTree` (the in-memory interpreter predicate as JSON). Without
+// --explain the output is byte-identical to today.
 //
 // The router is hand-rolled (no commander / yargs dep). It splits argv into
 // `command + subcommand-flags + global-flags` and dispatches to the matching

package/dist/src/commands/synthesize.js

@@ -14,7 +14,13 @@
 // 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 { isStellarAddress } from '@crediolabs/policy-synth';
+//
+// --explain (Phase 1) makes the synthesised policy human-readable. The
+// orchestrator attaches the in-memory predicate tree + a SimulationResult
+// to the success envelope; the CLI builds the deterministic review card
+// from those inputs and emits it alongside the policy. Without --explain
+// the output is byte-identical to today.
+import { buildReviewCardSummary, isStellarAddress, } from '@crediolabs/policy-synth';
 import { runSynthesizePolicy } from '@crediolabs/policy-synth/run';
 import { CliError, formatToolResponse, parsePairs, readJsonFile } from "../output.js";
 // Positive-int flags and i128 amount strings share the same wire shape: a
@@ -33,6 +39,12 @@ export async function runSynthesizeCommand(argv, flags) {
             retryable: false,
         });
     }
+    // --explain is a STANDALONE flag (no value). Detect presence via
+    // `!== undefined` so `--explain` (no value) and a missing flag are
+    // distinguishable. The core defaults to ADDITIVE: with --explain the
+    // output gains `review` + `predicateTree` and remains unchanged
+    // otherwise.
+    const explain = pairs.explain !== undefined;
     if (hasMandate) {
         const mandate = readJsonFile(pairs.mandate);
         const args = { source: 'mandate', mandate };
@@ -42,7 +54,11 @@ export async function runSynthesizeCommand(argv, flags) {
         if (pairs.confidence !== undefined) {
             args.confidenceOverride = { threshold: parseConfidence(pairs.confidence) };
         }
+        if (explain)
+            args.explain = true;
         const res = await runSynthesizePolicy(args);
+        if (explain)
+            emitExplainBlock(res, flags);
         return formatToolResponse(res, flags, 'synthesize(mandate)');
     }
     // hasRecorded
@@ -200,9 +216,60 @@ export async function runSynthesizeCommand(argv, flags) {
         }
         args.interpreter = interpreter;
     }
+    if (explain)
+        args.explain = true;
     const res = await runSynthesizePolicy(args);
+    // formatToolResponse runs FIRST so the "ok" line + --out / --json writes
+    // happen with the additive fields already attached. emitExplainBlock
+    // mutates `res.data` in place to inject `review` + `predicateTree`, so
+    // the --out artefact and --json stdout both carry the same shape.
+    if (explain)
+        emitExplainBlock(res, flags);
     return formatToolResponse(res, flags, 'synthesize(recording)');
 }
+/** 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
+ *  envelope; the core stays downstream of `formatToolResponse` so the
+ *  byte-identical no-flag path is preserved. The envelope mutation is
+ *  done BEFORE `formatToolResponse` so the on-disk --out artefact and
+ *  the --json stdout both carry the same fields. */
+function emitExplainBlock(res, flags) {
+    if (!res.ok || !res.explain)
+        return;
+    const review = buildReviewCardSummary(
+    // The orchestrator's `predicateTree` is the exact in-memory AST
+    // (canonical JSON shape). The builder's input is typed as
+    // `PredicateNode | null`; the orchestrator's `null` is the truthful
+    // OZ-only / mandate value, so a null here is honest.
+    (res.explain.predicateTree ?? null), res.data?.policyRefs ?? [], res.data?.contextRule ?? {
+        contextRuleType: { kind: 'default' },
+        name: 'unknown',
+        validUntilLedger: null,
+        signers: [],
+        policies: [],
+    }, res.explain.simulation);
+    res.data.review =
+        review;
+    res.data.predicateTree = res.explain.predicateTree;
+    // In human mode (no --json), print the review card readably: the rule name,
+    // the expiry, then one line per constraint. Plain text; no colour, no box
+    // drawing. The "ok" line is printed by formatToolResponse; this block prints
+    // ONLY the review-card lines.
+    //
+    // `review.plainEnglish` is deliberately not printed here: it is the same
+    // constraint list joined into one sentence, so emitting both would state
+    // every constraint twice. It stays on the JSON envelope for callers that
+    // want a single-string summary.
+    if (!flags.json && !flags.quiet) {
+        process.stdout.write(`Review card: ${review.ruleName}\n`);
+        process.stdout.write(`  ${review.expiry}\n`);
+        process.stdout.write('  Constraints:\n');
+        for (const line of review.constraints) {
+            process.stdout.write(`    - ${line}\n`);
+        }
+    }
+}
 /** 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. */

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

@@ -15,6 +15,12 @@
 // 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.
+//
+// --explain (Phase 1) makes the synthesised policy human-readable. The
+// orchestrator attaches the in-memory predicate tree + a SimulationResult
+// to the success envelope; the CLI builds the deterministic review card
+// from those inputs and emits it alongside the policy. Without --explain
+// the output is byte-identical to today.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSynthesizeCommand = runSynthesizeCommand;
 const policy_synth_1 = require("@crediolabs/policy-synth");
@@ -36,6 +42,12 @@ async function runSynthesizeCommand(argv, flags) {
             retryable: false,
         });
     }
+    // --explain is a STANDALONE flag (no value). Detect presence via
+    // `!== undefined` so `--explain` (no value) and a missing flag are
+    // distinguishable. The core defaults to ADDITIVE: with --explain the
+    // output gains `review` + `predicateTree` and remains unchanged
+    // otherwise.
+    const explain = pairs.explain !== undefined;
     if (hasMandate) {
         const mandate = (0, output_ts_1.readJsonFile)(pairs.mandate);
         const args = { source: 'mandate', mandate };
@@ -45,7 +57,11 @@ async function runSynthesizeCommand(argv, flags) {
         if (pairs.confidence !== undefined) {
             args.confidenceOverride = { threshold: parseConfidence(pairs.confidence) };
         }
+        if (explain)
+            args.explain = true;
         const res = await (0, run_1.runSynthesizePolicy)(args);
+        if (explain)
+            emitExplainBlock(res, flags);
         return (0, output_ts_1.formatToolResponse)(res, flags, 'synthesize(mandate)');
     }
     // hasRecorded
@@ -203,9 +219,60 @@ async function runSynthesizeCommand(argv, flags) {
         }
         args.interpreter = interpreter;
     }
+    if (explain)
+        args.explain = true;
     const res = await (0, run_1.runSynthesizePolicy)(args);
+    // formatToolResponse runs FIRST so the "ok" line + --out / --json writes
+    // happen with the additive fields already attached. emitExplainBlock
+    // mutates `res.data` in place to inject `review` + `predicateTree`, so
+    // the --out artefact and --json stdout both carry the same shape.
+    if (explain)
+        emitExplainBlock(res, flags);
     return (0, output_ts_1.formatToolResponse)(res, flags, 'synthesize(recording)');
 }
+/** 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
+ *  envelope; the core stays downstream of `formatToolResponse` so the
+ *  byte-identical no-flag path is preserved. The envelope mutation is
+ *  done BEFORE `formatToolResponse` so the on-disk --out artefact and
+ *  the --json stdout both carry the same fields. */
+function emitExplainBlock(res, flags) {
+    if (!res.ok || !res.explain)
+        return;
+    const review = (0, policy_synth_1.buildReviewCardSummary)(
+    // The orchestrator's `predicateTree` is the exact in-memory AST
+    // (canonical JSON shape). The builder's input is typed as
+    // `PredicateNode | null`; the orchestrator's `null` is the truthful
+    // OZ-only / mandate value, so a null here is honest.
+    (res.explain.predicateTree ?? null), res.data?.policyRefs ?? [], res.data?.contextRule ?? {
+        contextRuleType: { kind: 'default' },
+        name: 'unknown',
+        validUntilLedger: null,
+        signers: [],
+        policies: [],
+    }, res.explain.simulation);
+    res.data.review =
+        review;
+    res.data.predicateTree = res.explain.predicateTree;
+    // In human mode (no --json), print the review card readably: the rule name,
+    // the expiry, then one line per constraint. Plain text; no colour, no box
+    // drawing. The "ok" line is printed by formatToolResponse; this block prints
+    // ONLY the review-card lines.
+    //
+    // `review.plainEnglish` is deliberately not printed here: it is the same
+    // constraint list joined into one sentence, so emitting both would state
+    // every constraint twice. It stays on the JSON envelope for callers that
+    // want a single-string summary.
+    if (!flags.json && !flags.quiet) {
+        process.stdout.write(`Review card: ${review.ruleName}\n`);
+        process.stdout.write(`  ${review.expiry}\n`);
+        process.stdout.write('  Constraints:\n');
+        for (const line of review.constraints) {
+            process.stdout.write(`    - ${line}\n`);
+        }
+    }
+}
 /** 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-builder-cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "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.1.9",
+    "@crediolabs/policy-synth": "0.1.10",
     "zod": "3.25.76"
   },
   "devDependencies": {

package/src/commands/synthesize.ts

@@ -14,11 +14,33 @@
 // 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.
+//
+// --explain (Phase 1) makes the synthesised policy human-readable. The
+// orchestrator attaches the in-memory predicate tree + a SimulationResult
+// to the success envelope; the CLI builds the deterministic review card
+// from those inputs and emits it alongside the policy. Without --explain
+// the output is byte-identical to today.
 
-import { isStellarAddress, type ProposedPolicy } from '@crediolabs/policy-synth'
+import {
+  buildReviewCardSummary,
+  isStellarAddress,
+  type ProposedPolicy,
+  type ReviewCardSummary,
+} from '@crediolabs/policy-synth'
 import { runSynthesizePolicy } from '@crediolabs/policy-synth/run'
 import { CliError, type CliFlags, formatToolResponse, parsePairs, readJsonFile } from '../output.ts'
 
+/** Local mirror of the synth core's `SimulationResult` shape. The verify
+ *  module is internal to the package, so the CLI keeps this minimal copy
+ *  instead of importing the deep path - the contract is small enough that
+ *  a structural type is cheaper than a new package export. */
+type SimulationResult = {
+  permit: { tx: 'permit' } | { tx: 'deny'; reason: string }
+  evaluatedCases: Array<{ dimension: string; outcome: 'permit' | 'deny'; reason: string }>
+  backend: 'interpreter-v1' | 'ts-model'
+  simulatorVersion: string
+}
+
 // 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.
@@ -40,6 +62,13 @@ export async function runSynthesizeCommand(
     })
   }
 
+  // --explain is a STANDALONE flag (no value). Detect presence via
+  // `!== undefined` so `--explain` (no value) and a missing flag are
+  // distinguishable. The core defaults to ADDITIVE: with --explain the
+  // output gains `review` + `predicateTree` and remains unchanged
+  // otherwise.
+  const explain = pairs.explain !== undefined
+
   if (hasMandate) {
     const mandate = readJsonFile(pairs.mandate as string) as Record<string, unknown>
     const args: Record<string, unknown> = { source: 'mandate', mandate }
@@ -49,7 +78,9 @@ export async function runSynthesizeCommand(
     if (pairs.confidence !== undefined) {
       args.confidenceOverride = { threshold: parseConfidence(pairs.confidence as string) }
     }
+    if (explain) args.explain = true
     const res = await runSynthesizePolicy(args)
+    if (explain) emitExplainBlock(res, flags)
     return formatToolResponse(res, flags, 'synthesize(mandate)')
   }
 
@@ -230,10 +261,78 @@ export async function runSynthesizeCommand(
     }
     args.interpreter = interpreter
   }
+  if (explain) args.explain = true
   const res = await runSynthesizePolicy(args)
+  // formatToolResponse runs FIRST so the "ok" line + --out / --json writes
+  // happen with the additive fields already attached. emitExplainBlock
+  // mutates `res.data` in place to inject `review` + `predicateTree`, so
+  // the --out artefact and --json stdout both carry the same shape.
+  if (explain) emitExplainBlock(res, flags)
   return formatToolResponse(res, flags, 'synthesize(recording)')
 }
 
+/** 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
+ *  envelope; the core stays downstream of `formatToolResponse` so the
+ *  byte-identical no-flag path is preserved. The envelope mutation is
+ *  done BEFORE `formatToolResponse` so the on-disk --out artefact and
+ *  the --json stdout both carry the same fields. */
+function emitExplainBlock(
+  res: {
+    ok: boolean
+    data?: ProposedPolicy
+    explain?: {
+      predicateTree: unknown
+      simulation: SimulationResult
+    }
+  },
+  flags: CliFlags
+): void {
+  if (!res.ok || !res.explain) return
+  const review = buildReviewCardSummary(
+    // The orchestrator's `predicateTree` is the exact in-memory AST
+    // (canonical JSON shape). The builder's input is typed as
+    // `PredicateNode | null`; the orchestrator's `null` is the truthful
+    // OZ-only / mandate value, so a null here is honest.
+    (res.explain.predicateTree ?? null) as never,
+    res.data?.policyRefs ?? [],
+    res.data?.contextRule ?? {
+      contextRuleType: { kind: 'default' as const },
+      name: 'unknown',
+      validUntilLedger: null,
+      signers: [],
+      policies: [],
+    },
+    res.explain.simulation
+  )
+  // Attach the two additive fields to the on-wire envelope. formatToolResponse
+  // reads from `res` and writes the JSON; we mutate the same object so the
+  // --json path + --out path see the same shape.
+  ;(res.data as ProposedPolicy & { review: ReviewCardSummary; predicateTree: unknown }).review =
+    review
+  ;(
+    res.data as ProposedPolicy & { review: ReviewCardSummary; predicateTree: unknown }
+  ).predicateTree = res.explain.predicateTree
+  // In human mode (no --json), print the review card readably: the rule name,
+  // the expiry, then one line per constraint. Plain text; no colour, no box
+  // drawing. The "ok" line is printed by formatToolResponse; this block prints
+  // ONLY the review-card lines.
+  //
+  // `review.plainEnglish` is deliberately not printed here: it is the same
+  // constraint list joined into one sentence, so emitting both would state
+  // every constraint twice. It stays on the JSON envelope for callers that
+  // want a single-string summary.
+  if (!flags.json && !flags.quiet) {
+    process.stdout.write(`Review card: ${review.ruleName}\n`)
+    process.stdout.write(`  ${review.expiry}\n`)
+    process.stdout.write('  Constraints:\n')
+    for (const line of review.constraints) {
+      process.stdout.write(`    - ${line}\n`)
+    }
+  }
+}
+
 /** 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. */