@suluk/journeys 0.3.1 → 0.4.0

package/bin/journeys.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+/**
+ * @suluk/journeys CLI.
+ *   demos    — compile `.feature` files into a Bruno/Postman demo collection (live-prod / dev-local).
+ *   promote  — lift a tester's `@public` Examples row into the Zod source as `.meta({ examples })` (C040-P4).
+ *   audit    — the unified contract grade: harden security + readiness + BDD coverage (C043), with a CI gate.
+ *
+ * `--features` may be repeated and may name a directory (all `*.feature` under it) or a single file.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { buildDemoFiles, planPromotions, parseTargetSpec, miniDiff, buildAudit, type DemoFormat, type PromoteTargetSpec } from "../src/cli";
+
+const GRADES = ["F", "D", "C", "B", "A"];
+
+const DEMOS_USAGE = `journeys demos --doc <openapi.json> --features <dir-or-file>... --out <dir>
+               [--format bruno|postman|both] [--name <name>] [--base-url <prodURL>] [--local-base-url <localURL>]`;
+const PROMOTE_USAGE = `journeys promote --features <dir-or-file>... --target "<scenario>=<file>#<schemaVar>"... [--write] [--because <reason>]
+               (dry-run by default — prints a diff; pass --write to apply. Review the diff; a substrate operator
+                runs mizan_check_action_safety before --write.)`;
+const AUDIT_USAGE = `journeys audit --doc <openapi.json> [--features <dir-or-file>...] [--min A|B|C|D|F]
+               (security + readiness from @suluk/harden; BDD coverage when --features is given; --min gates on the worst.)`;
+const USAGE = `${DEMOS_USAGE}\n\n  ${PROMOTE_USAGE}\n\n  ${AUDIT_USAGE}`;
+
+function parseFlags(args: string[]): { cmd?: string; flags: Record<string, string[]> } {
+  const flags: Record<string, string[]> = {};
+  let cmd: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      const key = eq >= 0 ? a.slice(2, eq) : a.slice(2);
+      const val = eq >= 0 ? a.slice(eq + 1) : args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true";
+      (flags[key] ??= []).push(val);
+    } else if (!cmd) {
+      cmd = a;
+    }
+  }
+  return { cmd, flags };
+}
+
+const one = (flags: Record<string, string[]>, key: string): string | undefined => flags[key]?.[0];
+
+async function loadFeatureTexts(paths: string[]): Promise<string[]> {
+  const texts: string[] = [];
+  for (const p of paths) {
+    let st;
+    try {
+      st = statSync(p);
+    } catch {
+      throw new Error(`--features path not found: ${p}`);
+    }
+    if (st.isDirectory()) {
+      const glob = new Bun.Glob("**/*.feature");
+      let found = 0;
+      for await (const f of glob.scan({ cwd: p, absolute: true })) {
+        texts.push(await Bun.file(f).text());
+        found++;
+      }
+      if (!found) throw new Error(`no *.feature files under ${p}`);
+    } else {
+      texts.push(await Bun.file(p).text());
+    }
+  }
+  return texts;
+}
+
+async function demosCommand(flags: Record<string, string[]>): Promise<number> {
+  const docPath = one(flags, "doc");
+  const featurePaths = flags.features ?? [];
+  const out = one(flags, "out");
+  const format = (one(flags, "format") ?? "both") as DemoFormat;
+  if (!docPath || !featurePaths.length || !out) {
+    console.error("error: --doc, --features and --out are required.\n\n" + DEMOS_USAGE);
+    return 1;
+  }
+  if (!["bruno", "postman", "both"].includes(format)) {
+    console.error(`error: --format must be bruno|postman|both (got ${format}).`);
+    return 1;
+  }
+  const docText = await Bun.file(docPath).text();
+  const featureTexts = await loadFeatureTexts(featurePaths);
+  const result = buildDemoFiles(docText, featureTexts, {
+    format,
+    name: one(flags, "name"),
+    baseUrl: one(flags, "base-url"),
+    localBaseUrl: one(flags, "local-base-url"),
+  });
+  if (!result.scenarios) {
+    console.error("warning: no scenarios bound a When-operation — nothing to emit. Check the .feature steps against the contract's vocabulary.");
+    return 1;
+  }
+  for (const [rel, content] of Object.entries(result.files)) await Bun.write(join(out, rel), content);
+  console.log(`✓ ${result.scenarios} scenario(s), ${result.requests} request(s) → ${Object.keys(result.files).length} file(s) in ${out}/`);
+  return 0;
+}
+
+async function promoteCommand(flags: Record<string, string[]>): Promise<number> {
+  const featurePaths = flags.features ?? [];
+  const targetSpecs = flags.target ?? [];
+  if (!featurePaths.length || !targetSpecs.length) {
+    console.error("error: --features and at least one --target are required.\n\n" + PROMOTE_USAGE);
+    return 1;
+  }
+  const targets = new Map<string, PromoteTargetSpec>();
+  for (const spec of targetSpecs) {
+    const t = parseTargetSpec(spec);
+    if (!t) {
+      console.error(`error: bad --target ${JSON.stringify(spec)} — expected "<scenario>=<file>#<schemaVar>".`);
+      return 1;
+    }
+    targets.set(t.scenario, { file: t.file, schemaVar: t.schemaVar });
+  }
+  const featureTexts = await loadFeatureTexts(featurePaths);
+  const sources: Record<string, string> = {};
+  for (const t of targets.values()) if (!(t.file in sources)) sources[t.file] = await Bun.file(t.file).text();
+
+  const plan = planPromotions(featureTexts, targets, sources, { because: one(flags, "because") });
+  for (const row of plan.rows) {
+    const where = row.schemaVar ? ` → ${row.schemaVar} (${row.file})` : "";
+    console.log(`${row.status === "applied" ? "✓" : "–"} ${row.scenario}${where}: ${row.reason}`);
+  }
+  const changed = plan.files.filter((f) => f.changed);
+  for (const f of changed) {
+    console.log(`\n--- ${f.file} ---`);
+    console.log(miniDiff(f.original, f.updated));
+  }
+  if (!changed.length) {
+    console.log("\nNothing to promote.");
+    return 0;
+  }
+  if ("write" in flags) {
+    for (const f of changed) await Bun.write(f.file, f.updated);
+    console.log(`\n✓ wrote ${changed.length} file(s).`);
+  } else {
+    console.log(`\n(dry run — pass --write to apply. Review the diff above; a substrate operator runs mizan_check_action_safety before --write.)`);
+  }
+  return 0;
+}
+
+async function auditCommand(flags: Record<string, string[]>): Promise<number> {
+  const docPath = one(flags, "doc");
+  const featurePaths = flags.features ?? [];
+  const min = one(flags, "min");
+  if (!docPath) {
+    console.error("error: --doc is required.\n\n" + AUDIT_USAGE);
+    return 1;
+  }
+  if (min && !GRADES.includes(min)) {
+    console.error(`error: --min must be A|B|C|D|F (got ${min}).`);
+    return 1;
+  }
+  const docText = await Bun.file(docPath).text();
+  const featureTexts = featurePaths.length ? await loadFeatureTexts(featurePaths) : [];
+  const a = buildAudit(docText, featureTexts);
+
+  const dim = (label: string, d: { grade: string; score: number; findings: { severity: string; rule: string; path: string; message: string }[] }) => {
+    console.log(`\n${label}: ${d.grade} (${d.score}/100)`);
+    for (const f of d.findings.slice(0, 8)) console.log(`  [${f.severity}] ${f.rule}  ${f.path}: ${f.message}`);
+    if (d.findings.length > 8) console.log(`  …and ${d.findings.length - 8} more`);
+  };
+  dim("security ", a.security);
+  dim("readiness", a.readiness);
+  if (a.coverage) {
+    console.log(`\ncoverage : ${a.coverage.grade} (${a.coverage.covered}/${a.coverage.total} ops covered)`);
+    if (a.coverage.uncovered.length) console.log(`  uncovered (generate outlines): ${a.coverage.uncovered.join(", ")}`);
+  } else {
+    console.log(`\ncoverage : (skipped — pass --features to grade BDD coverage)`);
+  }
+  console.log(`\n= combined: worst ${a.combined.worst}, average ${a.combined.average}  [${a.combined.grades.join(" · ")}]`);
+
+  if (min) {
+    if (GRADES.indexOf(a.combined.worst) < GRADES.indexOf(min)) {
+      console.error(`\n✗ combined grade ${a.combined.worst} is below the required ${min}.`);
+      return 1;
+    }
+    console.log(`✓ meets the required ${min}.`);
+  }
+  return 0;
+}
+
+const { cmd, flags } = parseFlags(process.argv.slice(2));
+try {
+  if (cmd === "demos") {
+    process.exit(await demosCommand(flags));
+  } else if (cmd === "promote") {
+    process.exit(await promoteCommand(flags));
+  } else if (cmd === "audit") {
+    process.exit(await auditCommand(flags));
+  } else {
+    console.log(`@suluk/journeys CLI\n\nUsage:\n  ${USAGE}`);
+    process.exit(cmd ? 1 : 0);
+  }
+} catch (e) {
+  console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/journeys",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Intuitive, runnable BDD over a v4 'Suluk' contract. Projects a deterministic Gherkin step VOCABULARY from the contract (Given from x-suluk-access, When from each operation, Then from declared statuses + x-suluk-store + x-suluk-cost), binds authored .feature stories EXACT-or-UNBOUND with outcome steps resolved relative to the scenario's When-subject, and emits a BIDIRECTIONAL tri-state gap report (PARAPHRASE / NEEDS-DEV-GLUE / NEEDS-CONTRACT) + contract->authored coverage holes. A pure function of the document. CANDIDATE tooling.",
   "publishConfig": {
     "access": "public"
@@ -19,10 +19,15 @@
     ".": "./src/index.ts",
     "./hatch": "./src/hatch/index.ts"
   },
+  "bin": {
+    "journeys": "bin/journeys.ts"
+  },
   "dependencies": {
     "@suluk/cloudflare": "^0.2.0",
     "@suluk/core": "^0.1.13",
-    "@suluk/sdk": "^0.2.2"
+    "@suluk/examples": "^0.1.0",
+    "@suluk/harden": "^0.2.0",
+    "@suluk/sdk": "^0.3.0"
   },
   "devDependencies": {
     "@types/bun": "latest"

package/src/cli.ts

@@ -0,0 +1,186 @@
+/**
+ * CLI core (C042) — the PURE, filesystem-free heart of `journeys demos`: a v4 contract + `.feature` texts → the demo
+ * collection file map (Bruno and/or Postman). The bin (`bin/journeys.ts`) does only argv parsing + file IO around this,
+ * so the interesting logic stays unit-testable without touching disk.
+ */
+import { parseDocument, type OpenAPIv4Document } from "@suluk/core";
+import { auditDocument, auditReadiness, combineGrades, type Grade, type Finding } from "@suluk/harden";
+import { generateVocabulary } from "./vocabulary";
+import { parseFeature } from "./gherkin";
+import { bindFeatures } from "./bind";
+import { compileDemos, renderBruno, renderPostman } from "./demos";
+import { extractPublicRows, buildExampleObject, promoteExampleIntoZod } from "./promote";
+import { coverageGrade, type CoverageGrade } from "./coverage";
+
+export type DemoFormat = "bruno" | "postman" | "both";
+
+export interface BuildDemoFilesOptions {
+  /** which collection(s) to emit (default "both"). */
+  format?: DemoFormat;
+  /** collection name (default the contract's info.title). */
+  name?: string;
+  /** the PROD base URL (the live-call target). */
+  baseUrl?: string;
+  /** the LOCAL base URL a developer rehearses against first. */
+  localBaseUrl?: string;
+}
+
+export interface DemoFilesResult {
+  /** relative path → file content. When format is "both", Bruno files are under `bruno/`, Postman under `postman/`. */
+  files: Record<string, string>;
+  scenarios: number;
+  requests: number;
+}
+
+const slug = (s: string) => s.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "demo";
+
+/** Pure: a v4 document text + `.feature` texts → the demo collection file map. No filesystem. */
+export function buildDemoFiles(docText: string, featureTexts: string[], opts: BuildDemoFilesOptions = {}): DemoFilesResult {
+  const doc = parseDocument(docText) as OpenAPIv4Document;
+  const vocab = generateVocabulary(doc);
+  const features = featureTexts.map((t) => parseFeature(t));
+  const demos = compileDemos(doc, vocab, features);
+
+  const name = opts.name ?? doc.info?.title ?? "Demo";
+  const render = { name, baseUrl: opts.baseUrl, localBaseUrl: opts.localBaseUrl };
+  const format = opts.format ?? "both";
+
+  const files: Record<string, string> = {};
+  if (format === "bruno" || format === "both") {
+    const prefix = format === "both" ? "bruno/" : "";
+    for (const [p, c] of Object.entries(renderBruno(demos, render))) files[prefix + p] = c;
+  }
+  if (format === "postman" || format === "both") {
+    const prefix = format === "both" ? "postman/" : "";
+    files[`${prefix}${slug(name)}.postman_collection.json`] = renderPostman(demos, render);
+  }
+  return { files, scenarios: demos.length, requests: demos.reduce((n, d) => n + d.requests.length, 0) };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// `journeys promote` core — plan @public → Zod source edits (filesystem-free; the bin reads/writes around it).
+// ---------------------------------------------------------------------------------------------------------------------
+
+/** A `--target "<scenario>=<file>#<schemaVar>"` mapping. */
+export interface PromoteTargetSpec {
+  file: string;
+  schemaVar: string;
+}
+
+/** Parse `"<scenario>=<file>#<schemaVar>"`. The scenario may contain spaces/`=` only before the FIRST `=`. */
+export function parseTargetSpec(spec: string): { scenario: string; file: string; schemaVar: string } | null {
+  const eq = spec.indexOf("=");
+  const hash = spec.lastIndexOf("#");
+  if (eq < 0 || hash < eq) return null;
+  return { scenario: spec.slice(0, eq).trim(), file: spec.slice(eq + 1, hash).trim(), schemaVar: spec.slice(hash + 1).trim() };
+}
+
+export interface PromotionRow {
+  scenario: string;
+  file?: string;
+  schemaVar?: string;
+  status: "applied" | "skipped";
+  reason: string;
+}
+export interface PromotionFileResult {
+  file: string;
+  original: string;
+  updated: string;
+  changed: boolean;
+}
+export interface PromotionPlan {
+  files: PromotionFileResult[];
+  rows: PromotionRow[];
+}
+
+/**
+ * Plan the promotions for every `@public` Examples row: build the public example (content-typed) and apply
+ * `promoteExampleIntoZod` to the target's (pre-read) source — accumulating multiple rows per file. Pure: returns the
+ * before/after source per file (the bin diffs + writes). The never-clobber refusals surface as skipped rows.
+ */
+export function planPromotions(featureTexts: string[], targets: Map<string, PromoteTargetSpec>, sources: Record<string, string>, opts: { because?: string } = {}): PromotionPlan {
+  const features = featureTexts.map((t) => parseFeature(t));
+  const working: Record<string, string> = { ...sources };
+  const rows: PromotionRow[] = [];
+  for (const pub of extractPublicRows(features)) {
+    const target = targets.get(pub.scenario);
+    if (!target) {
+      rows.push({ scenario: pub.scenario, status: "skipped", reason: "no --target maps this scenario" });
+      continue;
+    }
+    if (!(target.file in working)) {
+      rows.push({ scenario: pub.scenario, file: target.file, schemaVar: target.schemaVar, status: "skipped", reason: `source file not loaded: ${target.file}` });
+      continue;
+    }
+    const example = buildExampleObject(pub.headers, pub.row);
+    const provenance = opts.because ? `${opts.because} (${pub.scenario})` : `promoted from ${pub.scenario}`;
+    const r = promoteExampleIntoZod(working[target.file], target.schemaVar, example, provenance);
+    if (r.changed) working[target.file] = r.source;
+    rows.push({ scenario: pub.scenario, file: target.file, schemaVar: target.schemaVar, status: r.changed ? "applied" : "skipped", reason: r.reason });
+  }
+  const files = Object.keys(sources).map((f) => ({ file: f, original: sources[f], updated: working[f], changed: working[f] !== sources[f] }));
+  return { files, rows };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// `journeys audit` core — the UNIFIED contract grade (C043): harden security + harden readiness + journeys coverage,
+// folded by letter via harden's combineGrades (the established harden+agents seam; harden never deps journeys).
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface DimensionAudit {
+  grade: Grade;
+  score: number;
+  findings: Finding[];
+}
+export interface AuditResult {
+  /** schema input-hardening (security) — `@suluk/harden` auditDocument. */
+  security: DimensionAudit;
+  /** schema-fact readiness (computed-required / missing-example) — `@suluk/harden` auditReadiness. */
+  readiness: DimensionAudit;
+  /** BDD contract coverage — present only when `.feature` files were given. */
+  coverage?: CoverageGrade;
+  /** the combined grade (worst is the safe value to gate on). */
+  combined: { worst: Grade; average: Grade; grades: Grade[] };
+}
+
+/** Run all readiness dimensions over a contract (+ optional `.feature` texts) and fold them into one grade. Pure. */
+export function buildAudit(docText: string, featureTexts: string[] = []): AuditResult {
+  const doc = parseDocument(docText) as OpenAPIv4Document;
+  const sec = auditDocument(doc);
+  const rd = auditReadiness(doc);
+  const grades: Grade[] = [sec.grade, rd.grade];
+
+  let coverage: CoverageGrade | undefined;
+  if (featureTexts.length) {
+    const report = bindFeatures(generateVocabulary(doc), featureTexts.map((t) => parseFeature(t)));
+    coverage = coverageGrade(report);
+    grades.push(coverage.grade);
+  }
+
+  return {
+    security: { grade: sec.grade, score: sec.score, findings: sec.findings },
+    readiness: { grade: rd.grade, score: rd.score, findings: rd.findings },
+    coverage,
+    combined: combineGrades(grades),
+  };
+}
+
+/** A minimal context diff (the edit is localized to one schema statement). Lines: `  ` ctx, `- ` removed, `+ ` added. */
+export function miniDiff(oldText: string, newText: string, ctx = 2): string {
+  const a = oldText.split("\n");
+  const b = newText.split("\n");
+  let s = 0;
+  while (s < a.length && s < b.length && a[s] === b[s]) s++;
+  let ea = a.length;
+  let eb = b.length;
+  while (ea > s && eb > s && a[ea - 1] === b[eb - 1]) {
+    ea--;
+    eb--;
+  }
+  const out: string[] = [];
+  for (let i = Math.max(0, s - ctx); i < s; i++) out.push(`  ${a[i]}`);
+  for (let i = s; i < ea; i++) out.push(`- ${a[i]}`);
+  for (let i = s; i < eb; i++) out.push(`+ ${b[i]}`);
+  for (let i = ea; i < Math.min(a.length, ea + ctx); i++) out.push(`  ${a[i]}`);
+  return out.join("\n");
+}

package/src/coverage.ts

@@ -0,0 +1,24 @@
+/**
+ * BDD coverage as a graded dimension (C043). `bindFeatures` already computes which contract operations a `.feature`
+ * suite covers; this turns that into a letter (using @suluk/harden's `grade`) so it folds into harden's `combineGrades`
+ * alongside the security + readiness grades — the journeys-owned dimension of the unified contract grade. It lives in
+ * journeys (not harden) because coverage needs the `.feature` files, and harden must not depend on journeys (cycle).
+ */
+import { grade, type Grade } from "@suluk/harden";
+import type { GapReport } from "./bind";
+
+export interface CoverageGrade {
+  grade: Grade;
+  score: number;
+  covered: number;
+  total: number;
+  /** uncovered operation names — the "gaps"; generate a Scenario Outline for each (renderScenarioOutlines). */
+  uncovered: string[];
+}
+
+/** Grade a gap report's contract→authored coverage (covered/total) and surface the uncovered ops. */
+export function coverageGrade(report: GapReport): CoverageGrade {
+  const { covered, total, holes } = report.coverage;
+  const score = total === 0 ? 100 : Math.round((covered / total) * 100);
+  return { grade: grade(score), score, covered, total, uncovered: holes.map((h) => h.name) };
+}

package/src/demos.ts

@@ -0,0 +1,239 @@
+/**
+ * Demo collections (C042): a bound feature set → a Bruno OR Postman collection a tester clicks through to showcase a
+ * feature START-TO-END on a LIVE (production) environment during a call.
+ *
+ * Same binding as the runnable emitter (C038/C040), a DIFFERENT lowering: each bound `When` becomes a raw HTTP request
+ * (method + `{{baseUrl}}`-prefixed path + auth header + JSON body) rather than a typed `client.<acc>()` call. The body is
+ * built from the scenario's first Examples row when present, else SYNTHESIZED from the schema (origin-aware) — so a demo
+ * is concrete without a table. A `sourced` field becomes request CHAINING: the SOURCE request captures the field into a
+ * collection variable (Postman `pm.collectionVariables.set` / Bruno `bru.setVar`) and the consumer references it via
+ * `{{var}}` — the live-call equivalent of `resolveSourced`. `baseUrl` + `token` are collection variables the presenter
+ * sets to point at prod. Pure (collection text out); a downstream consumer of the contract, never read by the matcher.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { resolveOps, type OpInfo } from "@suluk/sdk";
+import { describeInputs, synthesize, type JsonSchema } from "@suluk/examples";
+import { bindFeatures, type BindOptions } from "./bind";
+import type { Feature } from "./gherkin";
+import type { Vocabulary } from "./vocabulary";
+
+/** A request value: a concrete literal, or a `{{var}}` reference to a captured upstream response field. */
+export type DemoValue = { kind: "literal"; value: unknown } | { kind: "var"; name: string };
+/** Capture `res.<from>` of this request into the collection variable `var` (for downstream chaining). */
+export interface DemoCapture {
+  var: string;
+  from: string;
+}
+export interface DemoRequest {
+  /** the human label (the op name). */
+  label: string;
+  /** the op's by-name handle name (for chaining resolution). */
+  name: string;
+  method: string;
+  /** path with `{param}` substituted to a row value or a `{{param}}` variable; prefixed with `{{baseUrl}}` at render. */
+  path: string;
+  needsAuth: boolean;
+  body?: Record<string, DemoValue>;
+  captures: DemoCapture[];
+}
+export interface DemoScenario {
+  name: string;
+  requests: DemoRequest[];
+}
+
+const SOURCED_CELL = /^<([A-Za-z_][\w]*)\.(.+)>$/;
+const varName = (op: string, select: string) => `${op}_${select.replace(/[^A-Za-z0-9]+/g, "_")}`.replace(/_+$/, "");
+
+function coerce(cell: string, fieldSchema?: JsonSchema): unknown {
+  const t = fieldSchema && typeof fieldSchema === "object" ? fieldSchema.type : undefined;
+  const type = Array.isArray(t) ? t[0] : t;
+  if ((type === "integer" || type === "number") && cell.trim() !== "" && Number.isFinite(Number(cell))) return Number(cell);
+  if (type === "boolean" && (cell === "true" || cell === "false")) return cell === "true";
+  return cell;
+}
+
+interface Ref {
+  op: string;
+  select: string;
+  var: string;
+}
+
+/** Build the JSON body for a request from the Examples row (when present) else from the schema (synthesized). */
+function buildBody(op: OpInfo, cells: Record<string, string> | null): { body?: Record<string, DemoValue>; refs: Ref[] } {
+  const bodyRaw = op.bodyRaw as JsonSchema | undefined;
+  if (!bodyRaw || typeof bodyRaw !== "object") return { refs: [] };
+  const props = (bodyRaw.properties ?? {}) as Record<string, JsonSchema>;
+  const descs = describeInputs(bodyRaw);
+  if (!descs.length) return { refs: [] };
+  const body: Record<string, DemoValue> = {};
+  const refs: Ref[] = [];
+  for (const d of descs) {
+    if (d.origin === "computed") continue; // a client never sends a server-computed field
+    const cell = cells?.[d.name];
+    const token = cell ? SOURCED_CELL.exec(cell.trim()) : null;
+    if (token) {
+      const v = varName(token[1], token[2]);
+      body[d.name] = { kind: "var", name: v };
+      refs.push({ op: token[1], select: token[2], var: v });
+    } else if (cell !== undefined && cell !== "") {
+      body[d.name] = { kind: "literal", value: coerce(cell, props[d.name]) };
+    } else if (d.origin === "sourced" && d.source) {
+      const v = varName(d.source.op, d.source.select ?? "id");
+      body[d.name] = { kind: "var", name: v };
+      refs.push({ op: d.source.op, select: d.source.select ?? "id", var: v });
+    } else {
+      body[d.name] = { kind: "literal", value: synthesize(props[d.name], d.name, { direction: "request" }) };
+    }
+  }
+  return { body, refs };
+}
+
+function substitutePath(uri: string, cells: Record<string, string> | null): string {
+  const path = uri.replace(/^\/?/, "/");
+  return path.replace(/\{\+?([^}?&]+)\}/g, (_, p) => {
+    const cell = cells?.[p];
+    return cell && cell !== "" && !SOURCED_CELL.test(cell) ? cell : `{{${p}}}`;
+  });
+}
+
+export interface CompileDemoOptions extends BindOptions {}
+
+/** Compile a bound feature set into the demo IR: ordered requests per scenario, with sourced fields wired to captures. */
+export function compileDemos(doc: OpenAPIv4Document, vocab: Vocabulary, features: Feature[], opts: CompileDemoOptions = {}): DemoScenario[] {
+  const report = bindFeatures(vocab, features, opts);
+  const sourceScenarios = features.flatMap((f) => f.scenarios);
+  const { ops } = resolveOps(doc);
+  const opByHandle = new Map<string, OpInfo>(ops.map((op) => [`${op.name}@${op.uri}`, op]));
+
+  const demos: DemoScenario[] = [];
+  for (let i = 0; i < report.scenarios.length; i++) {
+    const sc = report.scenarios[i];
+    const ex = sourceScenarios[i]?.examples;
+    const cells = ex && ex.headers.length && ex.rows.length ? Object.fromEntries(ex.headers.map((h, ci) => [h, ex.rows[0][ci] ?? ""])) : null;
+
+    const requests: DemoRequest[] = [];
+    const refsPerReq: Ref[][] = [];
+    for (const r of sc.results) {
+      if (r.state !== "BOUND" || r.step.kind !== "when") continue;
+      const op = opByHandle.get(r.handle);
+      if (!op) continue;
+      const { body, refs } = buildBody(op, cells);
+      requests.push({
+        label: op.name,
+        name: op.name,
+        method: op.method.toUpperCase(),
+        path: substitutePath(op.uri, cells),
+        needsAuth: op.requires !== "anyone",
+        ...(body && Object.keys(body).length ? { body } : {}),
+        captures: [],
+      });
+      refsPerReq.push(refs);
+    }
+
+    // resolve chaining: each ref consumed by request `c` is captured by the latest prior request whose op produced it.
+    for (let c = 0; c < requests.length; c++) {
+      for (const ref of refsPerReq[c]) {
+        for (let s = c - 1; s >= 0; s--) {
+          if (requests[s].name === ref.op) {
+            if (!requests[s].captures.some((cap) => cap.var === ref.var)) requests[s].captures.push({ var: ref.var, from: ref.select });
+            break;
+          }
+        }
+      }
+    }
+
+    if (requests.length) demos.push({ name: sc.scenario, requests });
+  }
+  return demos;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Renderers
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface RenderOptions {
+  /** collection name (default the doc/feature title or "Demo"). */
+  name?: string;
+  /** the PROD base URL — the live-call target the tester switches to. */
+  baseUrl?: string;
+  /** the LOCAL base URL a developer tests against FIRST (the same collection, just a different `baseUrl`). Default a
+   *  Cloudflare Workers `wrangler dev` port. */
+  localBaseUrl?: string;
+}
+
+const DEFAULT_LOCAL = "http://localhost:8787";
+
+const slug = (s: string) => s.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() || "step";
+
+/** Render a JSON body where `{{var}}` refs are quoted strings (live-call chaining) and literals are JSON. */
+function renderBodyJson(body: Record<string, DemoValue>): string {
+  const lines = Object.entries(body).map(([k, v]) => `  ${JSON.stringify(k)}: ${v.kind === "var" ? JSON.stringify(`{{${v.name}}}`) : JSON.stringify(v.value)}`);
+  return `{\n${lines.join(",\n")}\n}`;
+}
+
+/** Render the demos as a Postman Collection v2.1.0 (a single JSON string). */
+export function renderPostman(demos: DemoScenario[], opts: RenderOptions = {}): string {
+  const local = opts.localBaseUrl ?? DEFAULT_LOCAL;
+  const collection = {
+    // `baseUrl` defaults to LOCAL so a fresh import runs against a dev server first; switch it to `{{prodBaseUrl}}` (or
+    // a Postman environment) for the live production demo. Same collection, both environments.
+    info: { name: opts.name ?? "Demo", schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" },
+    variable: [
+      { key: "baseUrl", value: local },
+      { key: "localBaseUrl", value: local },
+      { key: "prodBaseUrl", value: opts.baseUrl ?? "" },
+      { key: "token", value: "" },
+    ],
+    item: demos.map((sc) => ({
+      name: sc.name,
+      item: sc.requests.map((req) => {
+        const header = [
+          ...(req.body ? [{ key: "Content-Type", value: "application/json" }] : []),
+          ...(req.needsAuth ? [{ key: "Authorization", value: "Bearer {{token}}" }] : []),
+        ];
+        const scripts: string[] = [`pm.test("2xx", () => pm.expect(pm.response.code).to.be.below(300));`];
+        for (const cap of req.captures) scripts.push(`pm.collectionVariables.set(${JSON.stringify(cap.var)}, pm.response.json().${cap.from});`);
+        return {
+          name: req.label,
+          event: scripts.length ? [{ listen: "test", script: { type: "text/javascript", exec: scripts } }] : [],
+          request: {
+            method: req.method,
+            header,
+            url: { raw: `{{baseUrl}}${req.path}`, host: ["{{baseUrl}}"], path: req.path.split("/").filter(Boolean) },
+            ...(req.body ? { body: { mode: "raw", raw: renderBodyJson(req.body), options: { raw: { language: "json" } } } } : {}),
+          },
+        };
+      }),
+    })),
+  };
+  return JSON.stringify(collection, null, 2);
+}
+
+/** Render the demos as a Bruno collection — a map of relative file path → `.bru`/json content the consumer writes. */
+export function renderBruno(demos: DemoScenario[], opts: RenderOptions = {}): Record<string, string> {
+  const name = opts.name ?? "Demo";
+  const local = opts.localBaseUrl ?? DEFAULT_LOCAL;
+  // TWO environments, ONE collection: a developer runs `local` first, the presenter switches to `prod` for the live call.
+  const files: Record<string, string> = {
+    "bruno.json": JSON.stringify({ version: "1", name, type: "collection", ignore: ["node_modules", ".git"] }, null, 2),
+    "environments/local.bru": `vars {\n  baseUrl: ${local}\n  token: \n}\n`,
+    "environments/prod.bru": `vars {\n  baseUrl: ${opts.baseUrl ?? ""}\n  token: \n}\n`,
+  };
+  for (const sc of demos) {
+    const folder = slug(sc.name);
+    sc.requests.forEach((req, i) => {
+      const seq = i + 1;
+      const blocks: string[] = [
+        `meta {\n  name: ${req.label}\n  type: http\n  seq: ${seq}\n}`,
+        `${req.method.toLowerCase()} {\n  url: {{baseUrl}}${req.path}\n${req.body ? "  body: json\n" : ""}${req.needsAuth ? "  auth: bearer\n" : ""}}`,
+      ];
+      if (req.body) blocks.push(`headers {\n  Content-Type: application/json\n}`);
+      if (req.needsAuth) blocks.push(`auth:bearer {\n  token: {{token}}\n}`);
+      if (req.body) blocks.push(`body:json {\n${renderBodyJson(req.body).split("\n").map((l) => "  " + l).join("\n")}\n}`);
+      blocks.push(`assert {\n  res.status: lt 300\n}`);
+      if (req.captures.length) blocks.push(`script:post-response {\n${req.captures.map((c) => `  bru.setVar(${JSON.stringify(c.var)}, res.body.${c.from});`).join("\n")}\n}`);
+      files[`${folder}/${seq}-${slug(req.label)}.bru`] = blocks.join("\n\n") + "\n";
+    });
+  }
+  return files;
+}