melusine 0.1.0

package/examples/order-fulfillment/README.md

@@ -0,0 +1,16 @@
+# Order Fulfillment Example
+
+This example shows nested decisions: stock, payment, and fulfillment speed.
+
+Files:
+
+- `journey.md` defines the Mermaid flow and setup args.
+- `catalog.js` exposes reusable order tasks and scorers.
+- `order-workflow.mjs` is the toy system under test.
+- `generated/order-fulfillment.test.mjs` is the generated wrapper.
+
+Run it:
+
+```sh
+node src/cli.js test examples/order-fulfillment/journey.md --catalog examples/order-fulfillment/catalog.js
+```

package/examples/order-fulfillment/catalog.js

@@ -0,0 +1,59 @@
+// @ts-check
+
+import { scorer, task } from 'melusine';
+import { OrderWorkflow } from './order-workflow.mjs';
+
+const expectedExpressEvents = 'reserved,paid,express';
+const expectedStandardEvents = 'reserved,paid,standard';
+
+export const catalog = {
+  start: task(({ args }) => new OrderWorkflow(args[0]), { as: 'order', requiredArgs: 1 }),
+
+  stock: scorer(({ context }) => context.order.hasStock()),
+
+  reserve: task(({ args, context }) => {
+    context.order.reserve(args[0]);
+  }, { requiredArgs: 1 }),
+
+  outOfStock: scorer(() => ({
+    pass: false,
+    message: 'expected stock for SKU-42',
+  })),
+
+  payment: scorer(({ context }) => context.order.isPaymentApproved()),
+
+  capture: task(({ context }) => {
+    context.order.capturePayment();
+  }),
+
+  paymentDeclined: scorer(() => ({
+    pass: false,
+    message: 'expected approved payment',
+  })),
+
+  expedite: scorer(({ context }) => context.order.needsExpedite()),
+
+  express: task(({ context }) => {
+    context.order.scheduleExpress();
+  }),
+
+  expressReady: scorer(({ context }) => ({
+    pass: context.order.fulfillment === 'express' && context.order.events.join(',') === expectedExpressEvents,
+    actual: { fulfillment: context.order.fulfillment, events: context.order.events.join(',') },
+    expected: { fulfillment: 'express', events: expectedExpressEvents },
+    message: 'express fulfillment should be ready',
+  })),
+
+  standard: task(({ context }) => {
+    context.order.scheduleStandard();
+  }),
+
+  standardReady: scorer(({ context }) => ({
+    pass: context.order.fulfillment === 'standard' && context.order.events.join(',') === expectedStandardEvents,
+    actual: { fulfillment: context.order.fulfillment, events: context.order.events.join(',') },
+    expected: { fulfillment: 'standard', events: expectedStandardEvents },
+    message: 'standard fulfillment should be ready',
+  })),
+};
+
+export default catalog;

package/examples/order-fulfillment/generated/order-fulfillment.test.mjs

@@ -0,0 +1,15 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { formatRunFailure, runText } from "melusine";
+import * as catalogModule from "../catalog.js";
+
+const catalog = (catalogModule.default ?? catalogModule.catalog);
+const journeyUrl = new URL("../journey.md", import.meta.url);
+
+test("journey: order-fulfillment-nested", async () => {
+  assert.ok(catalog && typeof catalog === 'object', 'catalog module did not export a catalog object');
+  const text = await readFile(journeyUrl, 'utf8');
+  const result = await runText(text, catalog);
+  assert.equal(result.ok, true, formatRunFailure(result));
+});

package/examples/order-fulfillment/journey.md

@@ -0,0 +1,32 @@
+---
+journey: order-fulfillment-nested
+nodes:
+  start:
+    args: [{ stock: 2, paymentApproved: true, expedited: false }]
+    as: order
+  reserve: { args: ["SKU-42"] }
+---
+
+# Order fulfillment journey
+
+```mermaid
+graph TD
+  start(["Order received"]) --> stock
+  stock{"Stock available?"}
+  stock -->|yes| reserve
+  stock -->|no| outOfStock
+  reserve["Reserve inventory"] --> payment
+  payment{"Payment approved?"}
+  payment -->|yes| capture
+  payment -->|no| paymentDeclined
+  capture["Capture payment"] --> expedite
+  expedite{"Expedite requested?"}
+  expedite -->|yes| express
+  expedite -->|no| standard
+  express["Schedule express fulfillment"] --> expressReady
+  standard["Schedule standard fulfillment"] --> standardReady
+  outOfStock(["Out of stock"])
+  paymentDeclined(["Payment declined"])
+  expressReady(["Express fulfillment ready"])
+  standardReady(["Standard fulfillment ready"])
+```

package/examples/order-fulfillment/order-workflow.mjs

@@ -0,0 +1,48 @@
+export class OrderWorkflow {
+  constructor({ stock, paymentApproved, expedited }) {
+    this.stock = stock;
+    this.paymentApproved = paymentApproved;
+    this.expedited = expedited;
+    this.reservedSku = null;
+    this.paid = false;
+    this.fulfillment = null;
+    this.events = [];
+  }
+
+  hasStock() {
+    return this.stock > 0;
+  }
+
+  reserve(sku) {
+    if (!this.hasStock()) throw new Error('out of stock');
+    this.stock -= 1;
+    this.reservedSku = sku;
+    this.events.push('reserved');
+  }
+
+  isPaymentApproved() {
+    return this.paymentApproved;
+  }
+
+  capturePayment() {
+    if (!this.paymentApproved) throw new Error('payment declined');
+    this.paid = true;
+    this.events.push('paid');
+  }
+
+  needsExpedite() {
+    return this.expedited;
+  }
+
+  scheduleExpress() {
+    if (!this.paid) throw new Error('payment required');
+    this.fulfillment = 'express';
+    this.events.push('express');
+  }
+
+  scheduleStandard() {
+    if (!this.paid) throw new Error('payment required');
+    this.fulfillment = 'standard';
+    this.events.push('standard');
+  }
+}

package/examples/vending/README.md

@@ -0,0 +1,16 @@
+# Vending Example
+
+This example shows a single decision scorer. The `enough` scorer selects the `yes` branch when the machine has enough credit.
+
+Files:
+
+- `journey.md` defines the Mermaid flow and item args.
+- `catalog.js` exposes reusable vending tasks and scorers.
+- `vending-machine.mjs` is the toy system under test.
+- `generated/vending.test.mjs` is the generated wrapper.
+
+Run it:
+
+```sh
+node src/cli.js test examples/vending/journey.md --catalog examples/vending/catalog.js
+```

package/examples/vending/catalog.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+import { scorer, task } from 'melusine';
+import { VendingMachine } from './vending-machine.mjs';
+
+export const catalog = {
+  start: task(() => new VendingMachine(), { as: 'machine' }),
+
+  insert: task(({ args, context }) => {
+    context.machine.insert(args[0]);
+  }, { requiredArgs: 1 }),
+
+  enough: scorer(({ context }) => context.machine.credit >= 125),
+
+  dispense: task(({ args, context }) => {
+    context.machine.dispense(args[0]);
+  }, { requiredArgs: 1 }),
+
+  gotCola: scorer(({ context }) => ({
+    pass: context.machine.lastDispensed === 'cola',
+    actual: context.machine.lastDispensed,
+    expected: 'cola',
+    message: 'machine should dispense cola',
+  })),
+
+  fail: scorer(() => ({
+    pass: false,
+    message: 'expected enough credit for cola',
+  })),
+};
+
+export default catalog;

package/examples/vending/generated/vending.test.mjs

@@ -0,0 +1,15 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { formatRunFailure, runText } from "melusine";
+import * as catalogModule from "../catalog.js";
+
+const catalog = (catalogModule.default ?? catalogModule.catalog);
+const journeyUrl = new URL("../journey.md", import.meta.url);
+
+test("journey: vending-purchase", async () => {
+  assert.ok(catalog && typeof catalog === 'object', 'catalog module did not export a catalog object');
+  const text = await readFile(journeyUrl, 'utf8');
+  const result = await runText(text, catalog);
+  assert.equal(result.ok, true, formatRunFailure(result));
+});

package/examples/vending/journey.md

@@ -0,0 +1,21 @@
+---
+journey: vending-purchase
+nodes:
+  start:    { as: machine }
+  insert:   { args: [150] }
+  dispense: { args: ["cola"] }
+---
+
+# Vending purchase journey
+
+```mermaid
+graph TD
+  start(["Customer approaches with $1.50"]) --> insert
+  insert["Insert coins"] --> enough
+  enough{"Enough credit for cola?"}
+  enough -->|yes| dispense
+  enough -->|no| fail
+  dispense["Dispense cola"] --> gotCola
+  gotCola(["Got cola"])
+  fail(["Insufficient credit"])
+```

package/examples/vending/vending-machine.mjs

@@ -0,0 +1,16 @@
+export class VendingMachine {
+  constructor() {
+    this.credit = 0;
+    this.lastDispensed = null;
+  }
+
+  insert(cents) {
+    this.credit += cents;
+  }
+
+  dispense(item) {
+    if (this.credit < 125) throw new Error('insufficient credit');
+    this.credit -= 125;
+    this.lastDispensed = item;
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "melusine",
+  "version": "0.1.0",
+  "description": "Compile Mermaid journey flowcharts into framework-agnostic test plans.",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "bin": {
+    "melusine": "./src/cli.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "examples",
+    "README.md",
+    "SPEC.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "generate:example": "npm run generate:examples",
+    "generate:examples": "node src/cli.js compile examples/onboarding/journey.md --catalog examples/onboarding/catalog.js --out examples/onboarding/generated/onboarding.test.mjs && node src/cli.js compile examples/vending/journey.md --catalog examples/vending/catalog.js --out examples/vending/generated/vending.test.mjs && node src/cli.js compile examples/order-fulfillment/journey.md --catalog examples/order-fulfillment/catalog.js --out examples/order-fulfillment/generated/order-fulfillment.test.mjs",
+    "test": "npm run build && node --test test/*.test.js"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  }
+}