@eventmodelers/cli 1.0.150 → 1.0.152

package/stacks/modeling-kit/templates/.claude/skills/prototype/assets/slices.example.html

@@ -0,0 +1,201 @@
+<!--
+  Example slice blocks — the contract for what the `prototype` skill generates, one block per slice,
+  pasted at @@SLICES@@ in index.html. One of each kind: state change, state view, automation.
+
+  Inside a block:
+  - JSX and modern JavaScript; React hooks via React.useState etc.
+  - useCommand, useReadModel, useNav, useNotModeled are globals (the kit defines them).
+  - EMRuntime.reject('<message>') rejects a command with a scenario's errorDescription.
+  - Never the text of a closing script tag, not even in a string or comment.
+  - Every element belongs to exactly one slice: a command to its state-change slice, a read model to
+    its state-view slice, a todo list and its automation to the automation slice.
+-->
+
+<script type="text/plain" data-em-slice="11111111-1111-4111-8111-111111111111" data-em-title="Register Customer" data-em-hash="0f3c9a1d2b4e5f60">
+// State change: the screen part is the form the command's inputs come from, plus its button.
+const ofType = (events, type) => events.filter((e) => e.type === type);
+
+function RegisterCustomerForm() {
+  const register = useCommand('RegisterCustomer');
+  const { go } = useNav();
+  const [form, setForm] = React.useState({ name: '', email: '' });
+  const set = (k) => (e) => setForm({ ...form, [k]: e.target.value });
+  // Markup translated 1:1 from the screen's HTML page; inputs bound to the command's fields.
+  return (
+    <section className="section">
+      <div className="box" style={{ maxWidth: 420 }}>
+        <h1 className="title is-4">Register</h1>
+        <div className="field">
+          <label className="label" htmlFor="name">Name</label>
+          <input id="name" className="input" placeholder="Jane Doe" value={form.name} onChange={set('name')} />
+        </div>
+        <div className="field">
+          <label className="label" htmlFor="email">Email</label>
+          <input id="email" className="input" placeholder="jane@example.com" value={form.email} onChange={set('email')} />
+        </div>
+        {register.error && <p className="help is-danger">{register.error}</p>}
+        <button id="register" className="button is-primary" onClick={() => register.run(form).ok && go('Customers')}>
+          Register Customer
+        </button>
+      </div>
+    </section>
+  );
+}
+
+EMRuntime.defineSlice({
+  id: '11111111-1111-4111-8111-111111111111',
+  title: 'Register Customer',
+  order: 1,
+  commands: {
+    RegisterCustomer: {
+      decide(history, cmd, ctx) {
+        // Scenario "Email must be unique"
+        if (ofType(history, 'CustomerRegistered').some((e) => e.data.email === cmd.email)) {
+          EMRuntime.reject('Email is already registered');
+        }
+        return [{ type: 'CustomerRegistered', data: { customerId: ctx.uuid(), name: cmd.name, email: cmd.email } }];
+      },
+    },
+  },
+  specs: [
+    {
+      title: 'Customer registers',
+      kind: 'command',
+      given: [],
+      when: { type: 'RegisterCustomer', data: { name: 'Jane Doe', email: 'jane@example.com' } },
+      then: [{ type: 'CustomerRegistered', data: { name: 'Jane Doe', email: 'jane@example.com' } }],
+    },
+    {
+      title: 'Email must be unique',
+      kind: 'command',
+      given: [{ type: 'CustomerRegistered', data: { customerId: 'c-1', name: 'Jane Doe', email: 'jane@example.com' } }],
+      when: { type: 'RegisterCustomer', data: { name: 'John Doe', email: 'jane@example.com' } },
+      error: 'Email is already registered',
+    },
+  ],
+  screens: { Registration: { actor: 'Customer', part: RegisterCustomerForm } },
+});
+</script>
+
+<script type="text/plain" data-em-slice="22222222-2222-4222-8222-222222222222" data-em-title="Customer List" data-em-hash="7a1e44c09d2b3f81">
+// State view: the read model is one component — the region of the screen that shows its data.
+function CustomerTable() {
+  const customers = useReadModel('Customers');
+  const notModeled = useNotModeled();
+  return (
+    <section className="section">
+      <h1 className="title is-4">Customers</h1>
+      {customers.length === 0 ? (
+        <p>No customers yet.</p>
+      ) : (
+        <table className="table">
+          <tbody>
+            {customers.map((c) => (
+              <tr key={c.customerId}>
+                <td>{c.name}</td>
+                <td>{c.email}</td>
+                <td>{c.mailSent ? 'mail sent' : 'pending'}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+      <button className="button" onClick={() => notModeled('Export')}>Export</button>
+    </section>
+  );
+}
+
+EMRuntime.defineSlice({
+  id: '22222222-2222-4222-8222-222222222222',
+  title: 'Customer List',
+  order: 2,
+  readModels: {
+    Customers: {
+      initial: () => [],
+      evolve(state, e) {
+        if (e.type === 'CustomerRegistered') return [...state, { customerId: e.data.customerId, name: e.data.name, email: e.data.email }];
+        if (e.type === 'ConfirmationMailSent') return state.map((c) => (c.customerId === e.data.customerId ? { ...c, mailSent: true } : c));
+        return state;
+      },
+    },
+  },
+  specs: [
+    {
+      title: 'Registered customers are listed',
+      kind: 'readmodel',
+      readModel: 'Customers',
+      given: [{ type: 'CustomerRegistered', data: { customerId: 'c-1', name: 'Jane Doe', email: 'jane@example.com' } }],
+      expect: [{ customerId: 'c-1', name: 'Jane Doe' }],
+    },
+  ],
+  screens: { Customers: { actor: 'Back Office', part: CustomerTable } },
+});
+</script>
+
+<script type="text/plain" data-em-slice="33333333-3333-4333-8333-333333333333" data-em-title="Send Confirmation Mail" data-em-hash="c5d2e8f1a0b39476">
+// Automation: its todo list, the automation and the command it issues. How an item gets onto the
+// list and off it comes from the todo list's scenarios: given CustomerRegistered → listed;
+// given CustomerRegistered + ConfirmationMailSent → empty.
+EMRuntime.defineSlice({
+  id: '33333333-3333-4333-8333-333333333333',
+  title: 'Send Confirmation Mail',
+  order: 3,
+  readModels: {
+    PendingConfirmationMails: {
+      initial: () => ({}),
+      evolve(state, e) {
+        if (e.type === 'CustomerRegistered') return { ...state, [e.data.customerId]: { customerId: e.data.customerId, email: e.data.email } };
+        if (e.type === 'ConfirmationMailSent') {
+          const { [e.data.customerId]: _done, ...rest } = state;
+          return rest;
+        }
+        return state;
+      },
+      query: (state) => Object.values(state),
+    },
+  },
+  commands: {
+    SendConfirmationMail: {
+      decide: (history, cmd, ctx) => [{ type: 'ConfirmationMailSent', data: { customerId: cmd.customerId, sentAt: ctx.now.toISOString() } }],
+    },
+  },
+  automations: {
+    SendConfirmationMail: {
+      readModel: 'PendingConfirmationMails',
+      trigger: 'auto',
+      external: true,
+      todo: (items) => items,
+      process: (item) => ({
+        effect: `E-mail with confirmation link to ${item.email}`,
+        command: { type: 'SendConfirmationMail', data: { customerId: item.customerId, email: item.email } },
+      }),
+    },
+  },
+  specs: [
+    {
+      title: 'A new registration is waiting for its mail',
+      kind: 'readmodel',
+      readModel: 'PendingConfirmationMails',
+      given: [{ type: 'CustomerRegistered', data: { customerId: 'c-1', name: 'Jane Doe', email: 'jane@example.com' } }],
+      expect: [{ customerId: 'c-1' }],
+    },
+    {
+      title: 'A sent mail leaves the list',
+      kind: 'readmodel',
+      readModel: 'PendingConfirmationMails',
+      given: [
+        { type: 'CustomerRegistered', data: { customerId: 'c-1', name: 'Jane Doe', email: 'jane@example.com' } },
+        { type: 'ConfirmationMailSent', data: { customerId: 'c-1' } },
+      ],
+      expect: [],
+    },
+    {
+      title: 'A new registration gets a confirmation mail',
+      kind: 'automation',
+      automation: 'SendConfirmationMail',
+      given: [{ type: 'CustomerRegistered', data: { customerId: 'c-1', name: 'Jane Doe', email: 'jane@example.com' } }],
+      expectCommands: [{ type: 'SendConfirmationMail', data: { customerId: 'c-1' } }],
+    },
+  ],
+});
+</script>

package/stacks/modeling-kit/templates/.claude/skills/prototype/references/api-fallback.md

@@ -0,0 +1,30 @@
+# Prototype — curl Fallback Calls
+
+Only needed when MCP is not connected. `prototype.mjs status` (Step 2) already uses the REST API directly and needs no MCP.
+
+## Step 1 — Contexts and timelines
+
+```bash
+curl -s -H "x-token: $TOKEN" "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=MODEL_CONTEXT&projection=line"
+curl -s -H "x-token: $TOKEN" "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER&projection=line"
+```
+
+## Step 3 — One flagged slice
+
+```bash
+# Elements with fields + dependencies
+curl -s -G -H "x-token: $TOKEN" "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/slicedata" \
+  --data-urlencode "contextName=<CONTEXT>" -d sliceId=<SLICE_ID> -d projection=fields -d format=json
+
+# Scenarios and storylines
+curl -s -G -H "x-token: $TOKEN" "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/slicedata" \
+  --data-urlencode "contextName=<CONTEXT>" -d sliceId=<SLICE_ID> -d projection=specs -d format=json
+
+# Full screen records (meta.pages, meta.marks, meta.fields)
+curl -s -X POST -H "x-token: $TOKEN" -H "Content-Type: application/json" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/query" -d '{"ids": ["<id1>", "<id2>"]}'
+
+# A sketch SCREEN's elements — 404 when the screen is an uploaded image
+curl -s -H "x-token: $TOKEN" -H "x-user-id: agent" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/images/<NODE_ID>/description"
+```

package/stacks/modeling-kit/templates/kit/CLAUDE.md

@@ -316,6 +316,7 @@ for it. Instead:
      `code` block with Mermaid/PlantUML/ASCII), **never** drawn on the board with stickies, arrows or `create_drawing`.
      Only an explicit request to put it on the board changes that, and then as an image (`/domain-story` § board), not rebuilt from shapes;
    - **rows and columns** — a comparison, a matrix, a short list with a few attributes per item → `table`.
+   - **a prototype you just built** (the `/prototype` skill) → `prototype`, the uploaded page running in the chat with a Full screen button;
    - anything the customer defined **their own snippet type** for → `custom` with its `ref`: `list_snippet_types`
      shows them with `instructions` on when to use each; prefer a fitting one over a built-in kind. A click on it arrives
      with the button's `then` — what the type's author meant the click to do, after the message as a fenced
@@ -422,6 +423,7 @@ nothing to sanitize either, since a board change is not user text.
 | Find what changed in the code since the last analysis (git history from the chapter note's baseline) that the model doesn't reflect, and propose fixes | `/detect-model-drift` |
 | Walk someone through a feature slice by slice, or through every slice a planned feature needs (existing, to adjust, new), as a player in the chat | `/walkthrough` |
 | Turn a document or image (e.g. a tender/RFP) into a chaptered event model with screens, scenarios and a written blueprint summary | `/summarize` |
+| Build or update a clickable prototype of one context — one page uploaded to the platform and played with the timeline ▶ button, built slice by slice (only changed slices are rebuilt), screens as tabs, in-browser event sourcing, logic from the scenarios, automations runnable (read-only on the board) | `/prototype` |
 | Look up any API endpoint or element type not already covered by the skill you're executing | `/learn-eventmodelers-api` |
 | Add or rename an attribute across a chain of elements | `/attributes` |
 | Add or improve example data on element fields | `/examples` |

package/stacks/node/templates/.claude/skills/build-automation/SKILL.md

@@ -64,6 +64,8 @@ Refer to the build-state-change skill for the full command handler structure.
 
 ### Storyline-derived tests
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 If `storylines[]` includes a beat sequence running through this automation's trigger event → this slice's command, the command-handler test for that segment is already covered by build-state-change's own "Storyline-derived tests" step — it runs as part of following that skill above. This skill has no separate reactor-test format: the processor's event-to-command field mapping is exercised only indirectly, through that command-handler test, never by a dedicated `processor.test.ts`.
 
 ---

package/stacks/node/templates/.claude/skills/build-state-change/SKILL.md

@@ -230,6 +230,8 @@ Add one test per specification in the slice.json. If the spec has no preconditio
 
 ### Storyline-derived tests (optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `storylines[]` in slice.json (optional — only present when the board author built an explicit walkthrough) can also supply command-handler tests, in addition to the specifications-derived ones above. A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `commands[]` by id/title. Just scan each storyline's ordered `elements` for a `type: COMMAND` beat, followed by its emitted EVENT beat(s):
 
 - `given` — the cumulative ordered events from the start of the storyline up to (not including) the command beat

package/stacks/node/templates/.claude/skills/build-state-view/SKILL.md

@@ -327,6 +327,8 @@ Write one `it` block per specification in the slice.json. Use `given([events]).w
 
 ### Storyline-derived tests (optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `storylines[]` in slice.json is optional — present only when the board author explicitly built a walkthrough for this flow; most slices have none. When present, mine it for **additional** read-model-chain tests, on top of (never instead of) the specifications-derived tests above.
 
 A storyline is `{ id, title, elements: [...] }`, where `elements` is an ordered list of beats — the same element can repeat to show its state at different points in the flow. A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `readmodels[]` by id/title. Just scan for a pair of adjacent beats that are both `type: READMODEL`, with only EVENT beat(s) between them and no COMMAND beat in that run. That pair is one self-contained projection test:

package/stacks/opencqrs/templates/.claude/skills/build-automation/SKILL.md

@@ -394,6 +394,8 @@ class {AutomationName}ProcessorTest {
 
 ### Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may also carry a `storylines[]` array — narrated walkthroughs with an ordered
 `elements[]` "beats" sequence (EVENT/COMMAND/READMODEL/...). This is a secondary, supplementary
 source; `specifications[]` above stays the primary and default source of test cases. Most slices

package/stacks/opencqrs/templates/.claude/skills/build-state-change/SKILL.md

@@ -368,6 +368,8 @@ Full fluent-API cheat sheet: see
 
 ## Step 7b: Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may carry a `storylines[]` array alongside `specifications[]` — narrated walkthroughs
 where an ordered sequence of `elements[]` "beats" (EVENT/COMMAND/READMODEL/...) shows one use case
 end to end. This is a secondary, supplementary source — `specifications[]` (Step 7) stays the

package/stacks/opencqrs/templates/.claude/skills/build-state-view/SKILL.md

@@ -300,6 +300,8 @@ class {SliceName}ProjectorTest {
 
 ## Step 4b: Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may also carry a `storylines[]` array — narrated walkthroughs where the *same* read
 model appears as multiple ordered "beats" across one flow (see `elements[]` on each storyline).
 This is a secondary, supplementary source: `specifications[]` (Step 3) remains the primary and

package/stacks/supabase/templates/.claude/skills/build-state-change/SKILL.md

@@ -232,6 +232,8 @@ Add one test per specification in the slice.json. If the spec has no preconditio
 
 ## Step 4b — Storyline-derived tests (optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 Some slices also have a `storylines[]` array in slice.json — narrated walkthroughs of one use case as an ordered sequence of beats (`elements[]`). Most slices have no storylines; skip this step silently when `storylines[]` is empty or absent.
 
 A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `commands[]` by id/title. For each storyline, find a `type: COMMAND` beat directly followed by its EVENT beat(s). That pair is a command-handler test — the same shape as the specifications-derived tests above:

package/stacks/supabase/templates/.claude/skills/build-state-view/SKILL.md

@@ -309,6 +309,8 @@ Write one `it` block per specification in the slice.json. Use `given([events]).w
 
 ## Step 5b — Storyline-derived tests (optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 Some slices also have a `storylines[]` array in slice.json — narrated walkthroughs where the *same* read model repeats across several beats in one ordered `elements[]` list, showing its state at different points in a single flow. Most slices have no storylines; skip this step silently when `storylines[]` is empty or absent.
 
 A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `readmodels[]` by id/title. For each storyline, scan `elements[]` for pairs of adjacent `type: 'READMODEL'` beats with only EVENT beat(s) in between. Each such pair is a clean, self-contained projection test — the same shape as the specifications-derived tests above:

package/stacks/umadb/templates/.claude/skills/build-automation/SKILL.md

@@ -282,6 +282,8 @@ verifyNoMoreInteractions(targetCommandHandler);
 
 ### Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may also carry a `storylines[]` array — narrated walkthroughs with an ordered
 `elements[]` "beats" sequence (EVENT/COMMAND/READMODEL/...). This is a secondary, supplementary
 source; `specifications[]` above stays the primary and default source of test cases. Most slices

package/stacks/umadb/templates/.claude/skills/build-state-change/SKILL.md

@@ -344,6 +344,8 @@ behaviour, why `subscribe()` isn't faked: see
 
 ## Step 7b: Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may carry a `storylines[]` array alongside `specifications[]` — narrated walkthroughs
 where an ordered sequence of `elements[]` "beats" (EVENT/COMMAND/READMODEL/...) shows one use case
 end to end. This is a secondary, supplementary source — `specifications[]` (Step 7) stays the

package/stacks/umadb/templates/.claude/skills/build-state-view/SKILL.md

@@ -286,6 +286,8 @@ Add a `com.h2database:h2` test-scope dependency once, project-wide, if it isn't
 
 ## Step 4b: Storyline-Derived Tests (Optional)
 
+> **Note beats**: an entry with `type: STORYLINE_NOTE` is a note the board author placed in the walkthrough — its `description` is markdown context (an assumption, an external condition, a time gap), and its `id` is not a board node. Read it as background for the beats around it, but it is never a step: skip it when looking for COMMAND/EVENT/READMODEL beats or judging which beats are adjacent, and never turn it into test setup or an assertion on its own.
+
 `slice.json` may also carry a `storylines[]` array — narrated walkthroughs where the *same* read
 model appears as multiple ordered "beats" across one flow. This is a secondary, supplementary
 source: `specifications[]` (Step 4) remains the primary and default source of test cases. Most