@suluk/journeys 0.3.0 → 0.4.0

package/test/hatch-auth.test.ts

@@ -0,0 +1,53 @@
+import { test, expect, describe } from "bun:test";
+import { localD1 } from "../src/hatch/backends";
+import { stateHatch } from "../src/hatch/state";
+import { signInAs } from "../src/hatch/auth";
+import type { TestUser } from "../src/hatch/types";
+
+/**
+ * Durable package witness for the AUTH HATCH contract (C039) — the orchestration + the FAIL-CLOSED guarantee, proven
+ * without any real Better Auth (the consumer supplies mintSession/verify; here they are stubs). The end-to-end mint
+ * against toolfactory's real Better Auth is witnessed separately by toolfactory's local self-test
+ * (scripts/journeys-hatch-selftest.ts). This pins the property that matters most: signInAs NEVER returns a session the
+ * app rejected — it can never manufacture a false green — and teardown is test-user-scoped.
+ */
+async function fixture() {
+  const d1 = await localD1(":memory:");
+  await d1.run("CREATE TABLE user (id TEXT PRIMARY KEY, email TEXT)");
+  await d1.run("CREATE TABLE session (id TEXT PRIMARY KEY, userId TEXT, token TEXT)");
+  const state = stateHatch(d1, { write: true, scope: { value: "testuser_1" } });
+  return { d1, state };
+}
+const ensureUser = async (state: Awaited<ReturnType<typeof fixture>>["state"], user: TestUser) => {
+  await state.d1.seed("user", "id", [{ email: user.email }], { kind: "auth", because: "OAuth-only; no API seeds a verified user", userPathChecked: true });
+  return "testuser_1"; // seed forced user.id = the scope value
+};
+const mintSession = async (userId: string) => ({ cookie: `better-auth.session_token=${userId}.sig` });
+
+describe("auth hatch — signInAs (fail-closed, never a false green)", () => {
+  test("returns the session + seeds the user when the app ACCEPTS the minted cookie", async () => {
+    const { state } = await fixture();
+    const s = await signInAs({ state, user: { email: "bdd@example.test" }, ensureUser, mintSession, verify: async () => true });
+    expect(s.userId).toBe("testuser_1");
+    expect(s.cookie).toBe("better-auth.session_token=testuser_1.sig");
+    expect(await state.d1.get("SELECT id FROM user WHERE id = ?", ["testuser_1"])).toEqual({ id: "testuser_1" });
+  });
+
+  test("THROWS when the app REJECTS the minted session — fails closed, never returns an unverified credential", async () => {
+    const { state } = await fixture();
+    await expect(
+      signInAs({ state, user: { email: "bdd@example.test" }, ensureUser, mintSession, verify: async () => false }),
+    ).rejects.toThrow(/REJECTED|fails closed/);
+  });
+
+  test("teardown scoped-deletes only the test user's user + session rows", async () => {
+    const { d1, state } = await fixture();
+    await d1.run("INSERT INTO session (id, userId, token) VALUES (?,?,?)", ["s1", "testuser_1", "t"]);
+    await d1.run("INSERT INTO user (id, email) VALUES (?,?)", ["real_1", "real@customer.com"]); // a co-resident real user
+    const s = await signInAs({ state, user: { email: "bdd@example.test" }, ensureUser, mintSession, verify: async () => true });
+    await s.teardown(); // default targets: session.userId + user.id
+    expect(await state.d1.select("SELECT id FROM user WHERE id = ?", ["testuser_1"])).toEqual([]);
+    expect(await state.d1.select("SELECT id FROM session WHERE userId = ?", ["testuser_1"])).toEqual([]);
+    expect(await state.d1.select("SELECT id FROM user WHERE id = ?", ["real_1"])).toEqual([{ id: "real_1" }]); // untouched
+  });
+});

package/test/hatch-runscope.test.ts

@@ -0,0 +1,28 @@
+import { test, expect, describe } from "bun:test";
+import { tmpdir } from "node:os";
+import { runScope } from "../src/hatch/runscope";
+
+/**
+ * runScope is the parallel-safety primitive (C039): every call yields a UNIQUE test-user identity + an isolated temp DB
+ * path, so parallel worktrees / CI shards running the same BDD suite never clash.
+ */
+describe("runScope — unique-per-call, isolated, parallel-safe", () => {
+  test("each call is globally unique (id, scopeId, email, d1Path)", () => {
+    const a = runScope();
+    const b = runScope();
+    expect(a.runId).not.toBe(b.runId);
+    expect(a.scopeId).not.toBe(b.scopeId);
+    expect(a.email).not.toBe(b.email);
+    expect(a.d1Path).not.toBe(b.d1Path);
+    // 50 calls → 50 distinct ids
+    expect(new Set(Array.from({ length: 50 }, () => runScope().runId)).size).toBe(50);
+  });
+
+  test("the DB path is in the OS temp dir (outside any worktree/repo) and the scope ties everything to one test user", () => {
+    const s = runScope({ prefix: "tf-bdd" });
+    expect(s.d1Path.startsWith(tmpdir())).toBe(true);
+    expect(s.d1Path).toContain("tf-bdd-");
+    expect(s.scopeId).toBe(`testuser_${s.runId}`);
+    expect(s.email).toContain(s.runId);
+  });
+});

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 });
+    }
+  });
+});

package/test/promote.test.ts

@@ -0,0 +1,129 @@
+import { test, expect, describe } from "bun:test";
+import { parseFeature } from "../src/gherkin";
+import {
+  extractPublicRows,
+  buildExampleObject,
+  promoteExampleIntoZod,
+  promoteFeatureExamples,
+} from "../src/promote";
+import type { JsonSchema } from "@suluk/examples";
+
+/**
+ * C040-P4 — promote a tester's @public Examples row into the Zod source as .meta({ examples }). The source-write is
+ * MARKED, IDEMPOTENT, and NEVER CLOBBERS a hand-authored example.
+ */
+
+describe("extractPublicRows — a @public Examples block's first row", () => {
+  const feature = parseFeature(
+    [
+      "Feature: f",
+      "  Scenario Outline: charge",
+      "    When I charge",
+      "    @public",
+      "    Examples:",
+      "      | amountCents | currency |",
+      "      | 100         | usd      |",
+      "      | 250         | eur      |",
+      "  Scenario Outline: private",
+      "    When I charge",
+      "    Examples:",
+      "      | amountCents |",
+      "      | 999         |",
+    ].join("\n"),
+  );
+
+  test("only the @public-tagged block is returned, first row only", () => {
+    const rows = extractPublicRows([feature]);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].scenario).toBe("charge");
+    expect(rows[0].headers).toEqual(["amountCents", "currency"]);
+    expect(rows[0].row).toEqual(["100", "usd"]);
+  });
+});
+
+describe("buildExampleObject — typed coercion, wiring tokens skipped", () => {
+  const body: JsonSchema = {
+    type: "object",
+    properties: { amountCents: { type: "integer" }, currency: { type: "string" }, live: { type: "boolean" } },
+  };
+  test("coerces cells by the field type", () => {
+    expect(buildExampleObject(["amountCents", "currency", "live"], ["100", "usd", "true"], body)).toEqual({
+      amountCents: 100,
+      currency: "usd",
+      live: true,
+    });
+  });
+  test("a sourced wiring token <op.select> is not a concrete public value — skipped", () => {
+    expect(buildExampleObject(["amountCents", "subId"], ["100", "<createSubscription.id>"], body)).toEqual({ amountCents: 100 });
+  });
+});
+
+describe("promoteExampleIntoZod — marked, idempotent, never-clobber", () => {
+  const base = `import { z } from "zod";\nexport const ChargeBody = z.object({ amountCents: z.number().int() });\n`;
+
+  test("appends a marked .meta({ examples }) to a schema with no meta", () => {
+    const r = promoteExampleIntoZod(base, "ChargeBody", { amountCents: 100 }, "charge");
+    expect(r.changed).toBe(true);
+    expect(r.source).toContain("@suluk-public: charge");
+    expect(r.source).toContain('examples: [{"amountCents":100}]');
+    expect(r.source).toContain("z.object({ amountCents: z.number().int() }).meta(");
+  });
+
+  test("is idempotent — re-promoting REPLACES the marked block (single .meta), no double-append", () => {
+    const once = promoteExampleIntoZod(base, "ChargeBody", { amountCents: 100 }, "charge").source;
+    const twice = promoteExampleIntoZod(once, "ChargeBody", { amountCents: 250 }, "charge").source;
+    expect(twice.match(/@suluk-public/g)).toHaveLength(1);
+    expect(twice).toContain('examples: [{"amountCents":250}]');
+    expect(twice).not.toContain('examples: [{"amountCents":100}]');
+  });
+
+  test("REFUSES to clobber a hand-authored top-level .meta({ examples })", () => {
+    const hand = `export const ChargeBody = z.object({ amountCents: z.number() }).meta({ examples: [{ amountCents: 1 }] });\n`;
+    const r = promoteExampleIntoZod(hand, "ChargeBody", { amountCents: 100 }, "charge");
+    expect(r.changed).toBe(false);
+    expect(r.reason).toMatch(/not clobbering/i);
+    expect(r.source).toBe(hand);
+  });
+
+  test("appends safely after a non-example .meta (description) — preserved", () => {
+    const desc = `export const ChargeBody = z.object({ amountCents: z.number() }).meta({ description: "a charge" });\n`;
+    const r = promoteExampleIntoZod(desc, "ChargeBody", { amountCents: 100 }, "charge");
+    expect(r.changed).toBe(true);
+    expect(r.source).toContain('description: "a charge"');
+    expect(r.source).toContain("@suluk-public: charge");
+  });
+
+  test("a PROPERTY-level .meta is not mistaken for the top-level example meta", () => {
+    const prop = `export const ChargeBody = z.object({ amountCents: z.number().meta({ description: "cents" }) });\n`;
+    const r = promoteExampleIntoZod(prop, "ChargeBody", { amountCents: 100 }, "charge");
+    expect(r.changed).toBe(true);
+    // the property meta is untouched; a NEW top-level meta is appended
+    expect(r.source).toContain('z.number().meta({ description: "cents" })');
+    expect(r.source).toContain(") }).meta(/* @suluk-public");
+  });
+
+  test("a missing schema var is reported, not edited", () => {
+    const r = promoteExampleIntoZod(base, "NopeBody", { x: 1 }, "x");
+    expect(r.changed).toBe(false);
+    expect(r.reason).toMatch(/not found/);
+  });
+});
+
+describe("promoteFeatureExamples — orchestrated over a feature, target injected", () => {
+  const source = `export const ChargeBody = z.object({ amountCents: z.number().int() });\n`;
+  const feature = parseFeature(
+    ["Feature: f", "  Scenario Outline: charge", "    When I charge", "    @public", "    Examples:", "      | amountCents |", "      | 100         |"].join("\n"),
+  );
+
+  test("applies the public row to the resolved schema var", () => {
+    const r = promoteFeatureExamples(source, [feature], (sc) => (sc === "charge" ? { schemaVar: "ChargeBody", bodySchema: { type: "object", properties: { amountCents: { type: "integer" } } } } : null));
+    expect(r.applied).toEqual([{ scenario: "charge", schemaVar: "ChargeBody", reason: expect.stringContaining("promoted") }]);
+    expect(r.source).toContain('examples: [{"amountCents":100}]');
+  });
+
+  test("an unresolved scenario is skipped, not applied", () => {
+    const r = promoteFeatureExamples(source, [feature], () => null);
+    expect(r.applied).toHaveLength(0);
+    expect(r.skipped[0].reason).toMatch(/no target/);
+  });
+});