@suluk/journeys 0.3.1 → 0.4.0

package/test/audit.test.ts

@@ -0,0 +1,90 @@
+import { test, expect, describe } from "bun:test";
+import { buildAudit } from "../src/cli";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * C043 — the unified `journeys audit`: harden SECURITY + harden READINESS + journeys COVERAGE, folded by letter via
+ * harden's combineGrades. Coverage is journeys-owned (needs the features); harden never depends on journeys.
+ */
+const docJson = JSON.stringify({
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["amountCents", "balance"],
+            properties: {
+              amountCents: { type: "integer" }, // no maximum → a SECURITY finding
+              balance: { type: "integer", "x-suluk-origin": "computed" }, // required+computed → a READINESS finding
+            },
+          },
+        },
+      },
+    },
+    "/health": { requests: { health: { method: "get", responses: { "200": { status: 200 } } } } },
+  },
+});
+const feature = "Feature: f\n  Scenario: charge it\n    When I charge\n    Then it succeeds\n";
+
+describe("buildAudit", () => {
+  test("doc-only: security + readiness dimensions, no coverage, combined of 2", () => {
+    const a = buildAudit(docJson);
+    expect(a.combined.grades).toHaveLength(2);
+    expect(a.coverage).toBeUndefined();
+    expect(a.readiness.findings.some((f) => f.rule === "computed-required")).toBe(true);
+    expect(a.security.findings.some((f) => f.rule === "number-maximum")).toBe(true);
+  });
+
+  test("with features: coverage dimension included (combined of 3), uncovered ops surfaced", () => {
+    const a = buildAudit(docJson, [feature]);
+    expect(a.combined.grades).toHaveLength(3);
+    expect(a.coverage).toBeDefined();
+    expect(a.coverage!.covered).toBe(1); // charge covered
+    expect(a.coverage!.uncovered).toContain("health"); // health is a gap → generate an outline
+  });
+
+  test("the combined worst is the lowest dimension (the safe gate value)", () => {
+    const a = buildAudit(docJson, [feature]);
+    const ORDER = ["F", "D", "C", "B", "A"];
+    const min = a.combined.grades.reduce((w, g) => (ORDER.indexOf(g) < ORDER.indexOf(w) ? g : w), "A");
+    expect(a.combined.worst).toBe(min);
+  });
+});
+
+describe("bin: `journeys audit` end-to-end", () => {
+  const bin = join(import.meta.dir, "..", "bin", "journeys.ts");
+
+  test("prints all three dimensions + a combined grade; --min gates", () => {
+    const dir = mkdtempSync(join(tmpdir(), "journeys-audit-"));
+    try {
+      const docPath = join(dir, "openapi.json");
+      const featDir = join(dir, "features");
+      mkdirSync(featDir);
+      writeFileSync(docPath, docJson);
+      writeFileSync(join(featDir, "billing.feature"), feature);
+
+      const run = Bun.spawnSync(["bun", bin, "audit", "--doc", docPath, "--features", featDir]);
+      expect(run.exitCode).toBe(0);
+      const out = run.stdout.toString();
+      expect(out).toContain("security");
+      expect(out).toContain("readiness");
+      expect(out).toContain("coverage");
+      expect(out).toContain("combined");
+      expect(out).toContain("uncovered");
+
+      // gate on an impossible-to-meet minimum → non-zero exit
+      const gated = Bun.spawnSync(["bun", bin, "audit", "--doc", docPath, "--features", featDir, "--min", "A"]);
+      expect(gated.exitCode).toBe(1);
+      expect(gated.stderr.toString()).toContain("below the required A");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/test/cli.test.ts

@@ -0,0 +1,78 @@
+import { test, expect, describe } from "bun:test";
+import { buildDemoFiles } from "../src/cli";
+import { mkdtempSync, rmSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * C042 CLI — `journeys demos` compiles `.feature` files into a Bruno/Postman demo collection on disk. buildDemoFiles is
+ * the pure core (no fs); the bin is thin IO around it. Both are exercised here (unit + an end-to-end spawn).
+ */
+const docJson = JSON.stringify({
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/subs": { requests: { createSubscription: { method: "post", contentSchema: { type: "object", required: ["plan"], properties: { plan: { type: "string" } } }, responses: { "200": { status: 200 } }, "x-suluk-access": { requires: "authenticated" } } } },
+    "/charge": { requests: { charge: { method: "post", contentSchema: { type: "object", required: ["amountCents", "subscriptionId"], properties: { amountCents: { type: "integer", minimum: 100 }, subscriptionId: { type: "string", "x-suluk-origin": "sourced", "x-suluk-from": { op: "createSubscription", select: "id" } } } }, responses: { "200": { status: 200 } }, "x-suluk-access": { requires: "authenticated" } } } },
+  },
+});
+const featureText = "Feature: billing demo\n  Scenario: subscribe then charge\n    When I create subscription\n    And I charge\n";
+
+describe("buildDemoFiles", () => {
+  test("format bruno → a Bruno file map (chaining preserved)", () => {
+    const r = buildDemoFiles(docJson, [featureText], { format: "bruno", baseUrl: "https://api.example.com" });
+    expect([r.scenarios, r.requests]).toEqual([1, 2]);
+    expect(r.files["bruno.json"]).toBeDefined();
+    expect(r.files["environments/prod.bru"]).toContain("https://api.example.com");
+    expect(r.files["subscribe-then-charge/2-charge.bru"]).toContain('"subscriptionId": "{{createSubscription_id}}"');
+  });
+
+  test("format postman → a single v2.1 collection json", () => {
+    const r = buildDemoFiles(docJson, [featureText], { format: "postman", name: "Billing" });
+    expect(Object.keys(r.files)).toEqual(["billing.postman_collection.json"]);
+    expect(JSON.parse(r.files["billing.postman_collection.json"]).info.schema).toContain("v2.1.0");
+  });
+
+  test("format both → bruno/ and postman/ prefixed, no collision", () => {
+    const r = buildDemoFiles(docJson, [featureText], { format: "both", name: "Billing" });
+    expect(r.files["bruno/bruno.json"]).toBeDefined();
+    expect(r.files["postman/billing.postman_collection.json"]).toBeDefined();
+  });
+
+  test("name defaults to the contract's info.title", () => {
+    const r = buildDemoFiles(docJson, [featureText], { format: "postman" });
+    expect(r.files["billing.postman_collection.json"]).toBeDefined();
+  });
+});
+
+describe("bin: `journeys demos` end-to-end on disk", () => {
+  test("writes the collection files to --out (real spawn)", () => {
+    const dir = mkdtempSync(join(tmpdir(), "journeys-cli-"));
+    try {
+      const docPath = join(dir, "openapi.json");
+      const featDir = join(dir, "features");
+      const outDir = join(dir, "out");
+      mkdirSync(featDir);
+      writeFileSync(docPath, docJson);
+      writeFileSync(join(featDir, "billing.feature"), featureText);
+
+      const bin = join(import.meta.dir, "..", "bin", "journeys.ts");
+      const proc = Bun.spawnSync(["bun", bin, "demos", "--doc", docPath, "--features", featDir, "--out", outDir, "--format", "bruno", "--base-url", "https://api.example.com"]);
+
+      expect(proc.exitCode).toBe(0);
+      expect(proc.stdout.toString()).toContain("1 scenario(s), 2 request(s)");
+      expect(existsSync(join(outDir, "bruno.json"))).toBe(true);
+      const charge = join(outDir, "subscribe-then-charge", "2-charge.bru");
+      expect(existsSync(charge)).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("missing required flags → non-zero exit + usage", () => {
+    const bin = join(import.meta.dir, "..", "bin", "journeys.ts");
+    const proc = Bun.spawnSync(["bun", bin, "demos", "--doc", "x.json"]);
+    expect(proc.exitCode).toBe(1);
+    expect(proc.stderr.toString()).toContain("required");
+  });
+});

package/test/demos.test.ts

@@ -0,0 +1,126 @@
+import { test, expect, describe } from "bun:test";
+import { generateVocabulary } from "../src/vocabulary";
+import { parseFeature } from "../src/gherkin";
+import { compileDemos, renderPostman, renderBruno } from "../src/demos";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C042 — compile a bound feature into a Bruno/Postman DEMO collection: ordered requests, body from the Examples row (or
+ * synthesized), sourced fields wired to request CHAINING (capture → {{var}}), auth + a {{baseUrl}} that a developer
+ * points at localhost first and the presenter switches to prod for the live call.
+ */
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/subs": {
+      requests: {
+        createSubscription: {
+          method: "post",
+          contentSchema: { type: "object", required: ["plan"], properties: { plan: { type: "string" } } },
+          responses: { ok: { status: 200 } },
+          "x-suluk-access": { requires: "authenticated" },
+        },
+      },
+    },
+    "/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["amountCents", "subscriptionId"],
+            properties: {
+              amountCents: { type: "integer", minimum: 100 },
+              subscriptionId: { type: "string", "x-suluk-origin": "sourced", "x-suluk-from": { op: "createSubscription", select: "id" } },
+            },
+          },
+          responses: { ok: { status: 200 } },
+          "x-suluk-access": { requires: "authenticated" },
+        },
+      },
+    },
+  },
+} as unknown as OpenAPIv4Document;
+
+const feature = parseFeature(
+  ["Feature: billing demo", "  Scenario: subscribe then charge", "    When I create subscription", "    And I charge"].join("\n"),
+);
+const demos = compileDemos(doc, generateVocabulary(doc), [feature]);
+
+describe("compileDemos — the IR", () => {
+  test("ordered requests per scenario, method + path from the contract", () => {
+    expect(demos).toHaveLength(1);
+    expect(demos[0].requests.map((r) => [r.method, r.path])).toEqual([
+      ["POST", "/subs"],
+      ["POST", "/charge"],
+    ]);
+  });
+
+  test("the body is synthesized when there's no Examples table; computed dropped", () => {
+    expect(demos[0].requests[0].body).toEqual({ plan: { kind: "literal", value: "plan" } });
+  });
+
+  test("a sourced field becomes a {{var}} reference, and the SOURCE request captures it", () => {
+    const charge = demos[0].requests[1];
+    expect(charge.body!.subscriptionId).toEqual({ kind: "var", name: "createSubscription_id" });
+    const create = demos[0].requests[0];
+    expect(create.captures).toEqual([{ var: "createSubscription_id", from: "id" }]);
+  });
+
+  test("auth is flagged from x-suluk-access", () => {
+    expect(demos[0].requests.every((r) => r.needsAuth)).toBe(true);
+  });
+});
+
+describe("renderPostman", () => {
+  const json = renderPostman(demos, { name: "Billing demo", baseUrl: "https://api.example.com" });
+  const collection = JSON.parse(json);
+
+  test("a v2.1 collection with baseUrl (local-first) + prodBaseUrl + token variables", () => {
+    expect(collection.info.schema).toContain("v2.1.0");
+    const vars = Object.fromEntries(collection.variable.map((v: any) => [v.key, v.value]));
+    expect(vars.baseUrl).toBe("http://localhost:8787"); // dev-first
+    expect(vars.prodBaseUrl).toBe("https://api.example.com");
+    expect(vars).toHaveProperty("token");
+  });
+
+  test("the charge request body references the chained var, and create captures it via a test script", () => {
+    const folder = collection.item[0];
+    const create = folder.item[0];
+    const charge = folder.item[1];
+    expect(charge.request.body.raw).toContain('"subscriptionId": "{{createSubscription_id}}"');
+    const createScript = create.event.find((e: any) => e.listen === "test").script.exec.join("\n");
+    expect(createScript).toContain('pm.collectionVariables.set("createSubscription_id", pm.response.json().id)');
+  });
+
+  test("auth'd requests carry a bearer header + a 2xx test", () => {
+    const create = collection.item[0].item[0];
+    expect(create.request.header).toContainEqual({ key: "Authorization", value: "Bearer {{token}}" });
+    expect(create.event[0].script.exec.join("\n")).toContain("below(300)");
+  });
+});
+
+describe("renderBruno", () => {
+  const files = renderBruno(demos, { name: "Billing demo", baseUrl: "https://api.example.com" });
+
+  test("emits a collection manifest + BOTH local and prod environments", () => {
+    expect(files["bruno.json"]).toContain('"name": "Billing demo"');
+    expect(files["environments/local.bru"]).toContain("baseUrl: http://localhost:8787");
+    expect(files["environments/prod.bru"]).toContain("baseUrl: https://api.example.com");
+  });
+
+  test("a .bru file per request, sequenced, with method/url/body", () => {
+    const create = files["subscribe-then-charge/1-createsubscription.bru"];
+    const charge = files["subscribe-then-charge/2-charge.bru"];
+    expect(create).toContain("post {\n  url: {{baseUrl}}/subs");
+    expect(create).toContain("auth: bearer");
+    expect(charge).toContain('"subscriptionId": "{{createSubscription_id}}"');
+  });
+
+  test("the source request captures the chained var via a post-response script", () => {
+    const create = files["subscribe-then-charge/1-createsubscription.bru"];
+    expect(create).toContain('bru.setVar("createSubscription_id", res.body.id);');
+    expect(create).toContain("res.status: lt 300");
+  });
+});

package/test/emit-outline.test.ts

@@ -0,0 +1,95 @@
+import { test, expect, describe } from "bun:test";
+import { generateVocabulary } from "../src/vocabulary";
+import { parseFeature } from "../src/gherkin";
+import { emitRunnableSuite } from "../src/emit";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C040-P1 (runnable half) — a Scenario Outline runs PER Examples row through the generated SDK client; an `input` cell
+ * is a coerced literal, a `sourced` cell <op.select> is RESOLVED from a prior step's captured response (chaining across
+ * a multi-step journey). Each bound When's result is captured under its op.name so a later sourced field reads it.
+ */
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/subs": {
+      requests: {
+        createSubscription: {
+          method: "post",
+          contentSchema: { type: "object", required: ["plan"], properties: { plan: { type: "string" } } },
+          responses: { ok: { status: 200 } },
+        },
+      },
+    },
+    "/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["amountCents", "subscriptionId"],
+            properties: {
+              amountCents: { type: "integer", minimum: 100 },
+              subscriptionId: { type: "string", "x-suluk-origin": "sourced", "x-suluk-from": { op: "createSubscription", select: "id" } },
+            },
+          },
+          responses: { ok: { status: 200 } },
+        },
+      },
+    },
+  },
+} as unknown as OpenAPIv4Document;
+
+const feature = parseFeature(
+  [
+    "Feature: billing journeys",
+    "  Scenario Outline: subscribe then charge",
+    "    When I create subscription",
+    "    And I charge",
+    "    Examples:",
+    "      | plan | amountCents | subscriptionId          |",
+    "      | pro  | 100         | <createSubscription.id> |",
+    "      | team | 250         | <createSubscription.id> |",
+  ].join("\n"),
+);
+
+describe("emitRunnableSuite — outline rows + sourced chaining", () => {
+  const suite = emitRunnableSuite(doc, generateVocabulary(doc), [feature]);
+
+  test("unrolls one test per Examples row", () => {
+    expect(suite).toContain('test("subscribe then charge — example 1"');
+    expect(suite).toContain('test("subscribe then charge — example 2"');
+  });
+
+  test("inlines the pick() helper + a per-row captured bag", () => {
+    expect(suite).toContain("const pick =");
+    expect(suite).toContain("const captured: Record<string, any> = {}");
+  });
+
+  test("builds each When op's body from the row, mapping columns to that op's fields by name", () => {
+    expect(suite).toContain('{ plan: "pro" }'); // createSubscription gets only its own field
+    expect(suite).toContain("amountCents: 100"); // input cell coerced to a number literal (its type)
+  });
+
+  test("a sourced cell resolves from the prior captured response (chaining), not a literal", () => {
+    expect(suite).toContain('subscriptionId: pick(captured, "createSubscription", "id")');
+  });
+
+  test("captures each bound When's result under its op.name for downstream chaining", () => {
+    expect(suite).toContain('captured["createSubscription"] = result1');
+    expect(suite).toContain('captured["charge"] = result2');
+  });
+
+  test("row 2 uses its own input value", () => {
+    expect(suite).toContain("amountCents: 250");
+  });
+
+  test("a plain (non-outline) scenario still emits a single test with a provide-input placeholder", () => {
+    const plain = parseFeature("Feature: f\n\n  Scenario: just charge\n    When I charge\n    Then it succeeds\n");
+    const out = emitRunnableSuite(doc, generateVocabulary(doc), [plain]);
+    expect(out).toContain('test("just charge"');
+    expect(out).toContain("/* provide input */");
+    expect(out).not.toContain("const captured");
+  });
+});

package/test/examples-wall.test.ts

@@ -0,0 +1,31 @@
+import { test, expect, describe } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * THE VALUE WALL (C040) — the mirror of the C039 hatch wall, one layer over. Examples are request/response VALUES, and
+ * `examples.ts` SYNTHESIZES them. The deterministic PROJECTOR CORE (the vocabulary projection + the binder + the parser
+ * + normalization) names only contract FACTS and must never reach the value-synthesis layer — otherwise a value could
+ * leak into a place the D1 wall keeps fact-only. Subpath/module naming is not compiler-enforced, so this asserts it over
+ * the source. It also pins `examples.ts` as SELF-CONTAINED (no journeys-internal, no external import) so it stays a
+ * one-file extraction if @suluk/reference / @suluk/sdk later want the resolver.
+ */
+const src = (rel: string) => readFileSync(join(import.meta.dir, "..", "src", rel), "utf8");
+
+// The pure projector core — produces contract-derived FACTS and the bind decision. It must not import the value layer.
+const PROJECTOR_CORE = ["vocabulary.ts", "bind.ts", "gherkin.ts", "normalize.ts"];
+const NO_EXAMPLES = /from\s+["']\.{1,2}\/examples["']/;
+
+describe("C040 value wall — the projector core never imports the example/value synthesis layer", () => {
+  for (const file of PROJECTOR_CORE) {
+    test(`src/${file}: does not import ./examples`, () => {
+      expect(NO_EXAMPLES.test(src(file))).toBe(false);
+    });
+  }
+
+  test("src/examples.ts is a pure re-export of the shared @suluk/examples leaf (no relative value-layer import)", () => {
+    const body = src("examples.ts");
+    expect(/export\s+\*\s+from\s+["']@suluk\/examples["']/.test(body)).toBe(true);
+    expect(/from\s+["']\.{1,2}\//.test(body)).toBe(false); // the impl lives in the leaf, not a journeys-relative file
+  });
+});

package/test/outline.test.ts

@@ -0,0 +1,105 @@
+import { test, expect, describe } from "bun:test";
+import { buildScenarioOutlines, renderScenarioOutlines } from "../src/outline";
+import { parseFeature } from "../src/gherkin";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C040-P1 — generate a Scenario Outline per op: columns = client-facing input fields (computed dropped), seed row from
+ * the C041 origin-aware resolver; a `sourced` column seeds as the wiring token `<op.select>`, not a value. Plus the
+ * gherkin parser now CAPTURES the Examples table (it used to drop it), so render→parse round-trips.
+ */
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "billing/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["amountCents", "subscriptionId"],
+            properties: {
+              amountCents: { type: "integer", minimum: 100 },
+              subscriptionId: { type: "string", "x-suluk-origin": "sourced", "x-suluk-from": { op: "createSubscription", select: "id" } },
+              total: { type: "number", "x-suluk-origin": "computed" },
+            },
+          },
+          responses: { ok: { status: 200 } },
+        },
+      },
+    },
+    health: { requests: { health: { method: "get", responses: { ok: { status: 200 } } } } },
+  },
+} as unknown as OpenAPIv4Document;
+
+describe("buildScenarioOutlines", () => {
+  const outlines = Object.fromEntries(buildScenarioOutlines(doc).map((o) => [o.op, o]));
+
+  test("columns are the client-facing inputs; a computed field is dropped", () => {
+    expect(outlines.charge.columns.map((c) => c.name)).toEqual(["amountCents", "subscriptionId"]);
+    expect(outlines.charge.columns.map((c) => c.origin)).toEqual(["input", "sourced"]);
+  });
+
+  test("an input cell seeds a synthesized value; a sourced cell seeds the <op.select> wiring token", () => {
+    const byName = Object.fromEntries(outlines.charge.columns.map((c) => [c.name, c.seed]));
+    expect(byName.amountCents).toBe("100"); // synthesized, honors minimum
+    expect(byName.subscriptionId).toBe("<createSubscription.id>"); // wired, not a value
+  });
+
+  test("the When phrase is the contract's bindable vocabulary phrase (columns carry the body, so the outline binds)", () => {
+    expect(outlines.charge.whenPhrase).toBe("I charge");
+  });
+
+  test("a body-less op has no columns (renders as a plain Scenario, not an Outline)", () => {
+    expect(outlines.health.columns).toEqual([]);
+    expect(outlines.health.whenPhrase).toBe("I health");
+  });
+});
+
+describe("renderScenarioOutlines → a .feature sidecar", () => {
+  const feature = renderScenarioOutlines(doc);
+
+  test("a column-bearing op becomes a Scenario Outline with an Examples table + the wiring token", () => {
+    expect(feature).toContain("Scenario Outline: charge");
+    expect(feature).toContain("Examples:");
+    expect(feature).toContain("amountCents");
+    expect(feature).toContain("<createSubscription.id>");
+  });
+
+  test("a body-less op becomes a plain Scenario (no Outline, no Examples)", () => {
+    expect(feature).toContain("Scenario: health");
+    expect(feature).not.toContain("Scenario Outline: health");
+  });
+});
+
+describe("parseFeature captures the Examples table (round-trip)", () => {
+  test("render → parse recovers the headers + the seed row", () => {
+    const feature = renderScenarioOutlines(doc, { only: ["charge"] });
+    const parsed = parseFeature(feature);
+    const charge = parsed.scenarios.find((s) => s.name === "charge")!;
+    expect(charge.examples?.headers).toEqual(["amountCents", "subscriptionId"]);
+    expect(charge.examples?.rows).toEqual([["100", "<createSubscription.id>"]]);
+  });
+
+  test("a plain Scenario has no examples block", () => {
+    const parsed = parseFeature("Feature: f\n\n  Scenario: s\n    When I do\n    Then it works\n");
+    expect(parsed.scenarios[0].examples).toBeUndefined();
+  });
+
+  test("a hand-authored Outline with multiple rows parses every row", () => {
+    const src = [
+      "Feature: f",
+      "  Scenario Outline: charge",
+      "    When I charge with amountCents=<amountCents>",
+      "    Then it succeeds",
+      "    Examples:",
+      "      | amountCents |",
+      "      | 100         |",
+      "      | 250         |",
+    ].join("\n");
+    const charge = parseFeature(src).scenarios[0];
+    expect(charge.examples?.headers).toEqual(["amountCents"]);
+    expect(charge.examples?.rows).toEqual([["100"], ["250"]]);
+  });
+});

package/test/promote-cli.test.ts

@@ -0,0 +1,85 @@
+import { test, expect, describe } from "bun:test";
+import { planPromotions, parseTargetSpec, miniDiff, type PromoteTargetSpec } from "../src/cli";
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * C040-P4 CLI — `journeys promote` lifts a tester's @public Examples row into the Zod source. planPromotions is the pure
+ * core (no fs); the bin is dry-run-by-default + --write (the reviewable safety model; a substrate operator runs
+ * mizan_check_action_safety before --write).
+ */
+const featureText = ["Feature: f", "  Scenario Outline: charge", "    When I charge", "    @public", "    Examples:", "      | amountCents | currency |", "      | 100         | usd      |"].join("\n");
+const source = `import { z } from "zod";\nexport const ChargeBody = z.object({ amountCents: z.number().int(), currency: z.string() });\n`;
+
+describe("parseTargetSpec", () => {
+  test('parses "<scenario>=<file>#<schemaVar>" (scenario may have spaces)', () => {
+    expect(parseTargetSpec("subscribe then charge=src/validation.ts#ChargeBody")).toEqual({ scenario: "subscribe then charge", file: "src/validation.ts", schemaVar: "ChargeBody" });
+  });
+  test("rejects a malformed spec", () => {
+    expect(parseTargetSpec("no-hash=file.ts")).toBeNull();
+    expect(parseTargetSpec("nodelimiters")).toBeNull();
+  });
+});
+
+describe("planPromotions", () => {
+  const targets = new Map<string, PromoteTargetSpec>([["charge", { file: "validation.ts", schemaVar: "ChargeBody" }]]);
+
+  test("applies the @public row to the target source (content-typed coercion)", () => {
+    const plan = planPromotions([featureText], targets, { "validation.ts": source });
+    expect(plan.rows[0]).toMatchObject({ scenario: "charge", schemaVar: "ChargeBody", status: "applied" });
+    const file = plan.files.find((f) => f.file === "validation.ts")!;
+    expect(file.changed).toBe(true);
+    expect(file.updated).toContain('examples: [{"amountCents":100,"currency":"usd"}]'); // 100 → number, usd → string
+    expect(file.updated).toContain("@suluk-public");
+  });
+
+  test("an unmapped scenario is reported as skipped, source unchanged", () => {
+    const plan = planPromotions([featureText], new Map(), { "validation.ts": source });
+    expect(plan.rows[0].status).toBe("skipped");
+    expect(plan.files.every((f) => !f.changed)).toBe(true);
+  });
+
+  test("never-clobber surfaces as a skipped row (hand-authored examples present)", () => {
+    const hand = `export const ChargeBody = z.object({ amountCents: z.number() }).meta({ examples: [{ amountCents: 1 }] });\n`;
+    const plan = planPromotions([featureText], targets, { "validation.ts": hand });
+    expect(plan.rows[0].status).toBe("skipped");
+    expect(plan.rows[0].reason).toMatch(/not clobbering/i);
+  });
+});
+
+describe("miniDiff", () => {
+  test("marks removed/added lines with context", () => {
+    const d = miniDiff("a\nb\nc\n", "a\nB\nc\n");
+    expect(d).toContain("- b");
+    expect(d).toContain("+ B");
+  });
+});
+
+describe("bin: `journeys promote` end-to-end on disk", () => {
+  test("dry run prints a diff but does NOT write; --write applies", () => {
+    const dir = mkdtempSync(join(tmpdir(), "journeys-promote-"));
+    try {
+      const featDir = join(dir, "features");
+      const src = join(dir, "validation.ts");
+      mkdirSync(featDir);
+      writeFileSync(join(featDir, "billing.feature"), featureText);
+      writeFileSync(src, source);
+      const bin = join(import.meta.dir, "..", "bin", "journeys.ts");
+      const target = `charge=${src}#ChargeBody`;
+
+      const dry = Bun.spawnSync(["bun", bin, "promote", "--features", featDir, "--target", target]);
+      expect(dry.exitCode).toBe(0);
+      expect(dry.stdout.toString()).toContain("@suluk-public");
+      expect(dry.stdout.toString()).toContain("dry run");
+      expect(readFileSync(src, "utf8")).toBe(source); // UNCHANGED on a dry run
+
+      const wrote = Bun.spawnSync(["bun", bin, "promote", "--features", featDir, "--target", target, "--write"]);
+      expect(wrote.exitCode).toBe(0);
+      expect(wrote.stdout.toString()).toContain("wrote 1 file");
+      expect(readFileSync(src, "utf8")).toContain("@suluk-public"); // applied on --write
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});