@eventmodelers/cli 1.0.159 → 1.0.160

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.159",
+  "version": "1.0.160",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

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

@@ -63,6 +63,9 @@ Extract:
   isn't built or re-fetched yet: fall back to `apiEndpoint` / `fields[]` as above and note the assumption
   in `progress.txt`. If contract and `command.fields[]` disagree, the contract wins for the request and
   you record the mismatch in `progress.txt`.
+  **Build the call from it**: `postCommand(buildPath('<contract path>', { <path params> }), { <requestBody
+  properties> })` — `buildPath` (in `src/lib/api.ts`) fills and URL-encodes `{param}` segments; the body
+  carries exactly the contract's `requestBody` properties (props the contract doesn't list stay out).
 - **events[]** — informational only (what the backend is expected to emit); this stack does not
   act on them directly.
 - **screens[]** — the actor `SCREEN` element(s) that trigger this command, if any. Empty when the
@@ -127,11 +130,14 @@ lane concept, so the frontend path isn't a strict 1:1 mirror of it. `CommandTitl
 `title` verbatim (e.g. `ReserveBike.tsx`).
 
 **Markup**: translate the blueprint HTML from Step 2 into JSX **1:1** — same tags, same classes
-(Bulma or whatever the mockup used), same layout and copy. This is not a redesign; the screen *is*
+(the screen's `cssFrameworks` framework), same layout and copy. This is not a redesign; the screen *is*
 the design. Only change what must become dynamic:
 - A field's example value becomes that input's controlled `value`.
 - An element repeated for a `cardinality: "List"` field becomes a `.map()` over that field.
-- `class`/`style`/structure otherwise stay exactly as drawn.
+- `class`/`style`/structure otherwise stay exactly as drawn — except the board's own mark plumbing:
+  drop every `data-em-mark-id` attribute and `em-mark`/`em-mark-<hex>` class (they only draw the
+  highlight outline on the canvas; the app never ships it).
+- The classes only render correctly if the screen's CSS framework (`cssFrameworks`) is loaded in the app — see Step 7 (styles); don't hand-write CSS to compensate.
 
 **Props**: exactly `command.fields[]`, typed per each field's `type` (`String`→`string`,
 `Boolean`→`boolean`, `Int`/`Long`→`number`, etc. — `subfields[]` become a nested object type),
@@ -290,9 +296,52 @@ how many pages this app needs — not one page per slice.
    - If `src/pages/<ScreenTitle>.tsx` already exists, update only this slice's marked position;
      leave every other position (already-wired slices, and untouched mockup content) exactly as is.
 
-## Step 7 — Verify against slice.json
-
-After writing the hook/component (and context/page, if any), confirm:
+## Step 7 — Load the screen's styles, every slice
+
+The mockup's classes only mean something with the CSS framework the board renders it with, so the
+app must load that same one. This runs on **every** slice (not just the first) and is idempotent —
+an existing project that is missing it gets fixed on its next build.
+
+1. **Detect** the framework the screen loads, from the node fetched in Step 2: `cssFrameworks` (one id).
+   If it isn't returned, infer it from the classes in `meta.pages` (`title`/`field`/`is-*` → bulma,
+   `btn`/`form-control`/`col-*` → bootstrap, utility classes like `flex p-6` → tailwind). If the
+   screen loads **no** framework (`[]`, or nothing detectable), use Vite's default: change nothing —
+   skip this whole step, leave `index.html` and `src/index.css` as the template ships them.
+2. **Ensure it's loaded** in `index.html`'s `<head>`, same pinned version the board uses — check with
+   `grep -n -i "bulma\|bootstrap\|cdn.tailwindcss" index.html` first, add only what's missing:
+   - `bulma` → `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css">`
+   - `bootstrap` → `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">`
+   - `tailwind` → `<script src="https://cdn.tailwindcss.com/3.4.16"></script>`
+
+   A *different* framework already there means two screens disagree: don't mix them — keep what's
+   there and flag it via `request-feedback`.
+3. **Neutralise the Vite demo CSS** (only because a framework was detected). If `src/index.css` still holds the demo (it contains `#social` or
+   `--social-bg`), replace the whole file with `body { margin: 0; }` — the centred 1126px `#root`,
+   dark-mode palette, `color-scheme: light dark`, grey text and 56px `h1` all fight the mockup. A file
+   without those markers was already customised (or filled from `learn-styleguide`): leave it alone.
+
+## Step 8 — Base page, only if this is the first slice
+
+`src/App.tsx` ships as the Vite demo scaffold. The **first slice built in this project** replaces it
+with the app's **base page**, so there is something real to open in the browser; every later slice
+leaves it alone.
+
+1. **First slice?** Yes only if `src/slices/` holds no other slice folder than this one (only
+   `.gitkeep` besides it) *and* `src/App.tsx` still contains the scaffold (`Get started` heading).
+   Otherwise skip this step entirely.
+2. Rewrite `src/App.tsx` as the base page: a minimal `<main>` that renders the top-level thing this
+   slice produced — `src/pages/<ScreenTitle>.tsx` when Step 6 composed a shared page, else this
+   slice's own component. Nothing from the Vite demo (counter, logos, doc links) stays. No router and
+   no new dependency — a single page needs neither.
+3. Delete what the scaffold alone used and nothing else now imports: `src/App.css` and
+   `src/assets/{hero.png,react.svg,vite.svg}` (check with `grep -rn` first); `public/icons.svg` too if
+   nothing references it. Leave `src/main.tsx` and `src/index.css` (Step 7 handles it) as they are.
+4. Keep the page working with no backend, per the isolation rule in `.build-kit/CLAUDE.md`: the
+   slice component must render its empty state, and `VITE_DATA_MODE=mock` must show its sample.
+
+## Step 9 — Verify against slice.json
+
+After writing the hook/component (and context/page/base page, if any), confirm:
 - Every prop matches a `command.fields[]` entry exactly (name + type) — no invented or missing
   fields.
 - The `postCommand` call uses the UI contract's `path` and `body` when one was found, else `command.apiEndpoint` verbatim — or, when it was missing at build

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

@@ -29,7 +29,8 @@ convenient — for a component to read it straight from Supabase, with no bespok
 between, the same way `miro-eventmodeling` and this stack's other Supabase-backed components do.
 
 That said, a component never calls `supabase.from(...)` (or imports `src/lib/supabase.ts`) itself —
-it calls `queryReadModel(...)` from `src/lib/api.ts`, same as `build-state-change` components only
+it calls `getReadModel(...)` (backend `GET` UI contract available) or `queryReadModel(...)` (table
+read) from `src/lib/api.ts`, same as `build-state-change` components only
 ever call `postCommand`. `queryReadModel` is the real Supabase call in production, but in mock mode
 it serves a numbered sample instead (see Step 4) — routing every read through this one seam is what
 makes a component testable/previewable in isolation, with zero Supabase project needed.
@@ -66,10 +67,22 @@ Extract:
        a Slice" step 6) — the built, mocked component still needs a real table/view before it's done,
        so don't flip it to `Done`.
   - `description` — implementation hints (filtering rules, sort order, business meaning).
-- **No UI contract for reads** — the backend's `ui-contract` skill publishes a `GET` contract, but this
-  stack reads the table/view directly (RLS-protected) and never calls a read endpoint, so that
-  contract does not apply here. `readmodel.apiEndpoint` (table/view name) and `fields[]` stay the
-  source. (Only the write side, `build-state-change`, consumes a contract.)
+- **UI contract (read)** — the backend slice's published `GET` contract: look it up as described in
+  the `ui-contract` skill ("How the UI build kit looks the contract up" — the `## UI Contract` entry in
+  `slice.json` `notes[]`; parse only its `ui-contract` block — an OpenAPI operation). **When present it
+  is the specification and you build the call from it** — it overrides `apiEndpoint` and the table read:
+  - fetch with `getReadModel(buildPath('<contract path>', { <path params> }), { <query params> }, samples)`
+    from `src/lib/api.ts` — path and query `parameters` exactly as the contract names them, never a
+    guessed URL, never `supabase.from(...)`;
+  - type the result from the 2xx `responses` schema (it must match `readmodel.fields[]`; the contract
+    wins for the wire shape, record any mismatch in `progress.txt`);
+  - render **every** non-2xx response (status + description) as its own distinct state — a 404 "no
+    reservation" is an empty state, not an error banner; don't collapse them into one generic failure;
+  - the numbered samples (Step 4) are shaped like the contract's 2xx response body.
+
+  **When absent** (backend slice not built or not re-fetched yet): fall back to the table read —
+  `readmodel.apiEndpoint` (table/view name) + `fields[]` via `queryReadModel` — and note the assumption
+  in `progress.txt`.
 - **screens[]** — the actor `SCREEN` element(s) that display this data, if any (see Step 2).
 - **specifications[]** — GWT scenarios/storyline; treat as acceptance criteria (e.g. "given no
   active reservation, show an empty state").
@@ -103,8 +116,13 @@ the mockup is the design, not a starting point for a redesign.
 its parent, never read from a global store. The queried data itself is **not** a prop — the
 component fetches it.
 
-**Default — call `queryReadModel` from `src/lib/api.ts` inside the component**. Never `supabase.from(...)`
-directly, never a raw `fetch`:
+**With a UI contract (Step 1)**: call `getReadModel(buildPath(path, pathParams), queryParams, samples)`
+from `src/lib/api.ts` inside the component instead of the `queryReadModel` snippet below — same
+effect shape (`useEffect` → loading / empty / error / data), but each documented non-2xx response
+(`ApiError.status`) maps to its own state. Never a raw `fetch`.
+
+**Default (no contract) — call `queryReadModel` from `src/lib/api.ts` inside the component**. Never
+`supabase.from(...)` directly, never a raw `fetch`:
 
 ```tsx
 // ActiveReservationView.tsx
@@ -196,7 +214,7 @@ component doesn't do anything with that number itself, `queryReadModel` reads it
 
 ## Step 5 — Compose onto the shared page, if this screen's name is shared
 
-Identical to `build-state-change` Step 5 — a screen's **title is the page name**, and the number
+Identical to `build-state-change` Step 6 — a screen's **title is the page name**, and the number
 of *distinct* screen titles across the board is a direct hint at how many pages this app needs, not
 one page per slice.
 
@@ -216,10 +234,55 @@ one page per slice.
    slice component still only knows its own declared props. Update only this slice's marked
    position if the page file already exists.
 
-## Step 6 — Verify against slice.json
+## Step 6 — Load the screen's styles, every slice
+
+The mockup's classes only mean something with the CSS framework the board renders it with, so the
+app must load that same one. This runs on **every** slice (not just the first) and is idempotent —
+an existing project that is missing it gets fixed on its next build.
+
+1. **Detect** the framework the screen loads, from the node fetched in Step 2: `cssFrameworks` (one id).
+   If it isn't returned, infer it from the classes in `meta.pages` (`title`/`field`/`is-*` → bulma,
+   `btn`/`form-control`/`col-*` → bootstrap, utility classes like `flex p-6` → tailwind). If the
+   screen loads **no** framework (`[]`, or nothing detectable), use Vite's default: change nothing —
+   skip this whole step, leave `index.html` and `src/index.css` as the template ships them.
+2. **Ensure it's loaded** in `index.html`'s `<head>`, same pinned version the board uses — check with
+   `grep -n -i "bulma\|bootstrap\|cdn.tailwindcss" index.html` first, add only what's missing:
+   - `bulma` → `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css">`
+   - `bootstrap` → `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">`
+   - `tailwind` → `<script src="https://cdn.tailwindcss.com/3.4.16"></script>`
+
+   A *different* framework already there means two screens disagree: don't mix them — keep what's
+   there and flag it via `request-feedback`.
+3. **Neutralise the Vite demo CSS** (only because a framework was detected). If `src/index.css` still holds the demo (it contains `#social` or
+   `--social-bg`), replace the whole file with `body { margin: 0; }` — the centred 1126px `#root`,
+   dark-mode palette, `color-scheme: light dark`, grey text and 56px `h1` all fight the mockup. A file
+   without those markers was already customised (or filled from `learn-styleguide`): leave it alone.
+
+## Step 7 — Base page, only if this is the first slice
+
+`src/App.tsx` ships as the Vite demo scaffold. The **first slice built in this project** replaces it
+with the app's **base page**, so there is something real to open in the browser; every later slice
+leaves it alone.
+
+1. **First slice?** Yes only if `src/slices/` holds no other slice folder than this one (only
+   `.gitkeep` besides it) *and* `src/App.tsx` still contains the scaffold (`Get started` heading).
+   Otherwise skip this step entirely.
+2. Rewrite `src/App.tsx` as the base page: a minimal `<main>` that renders the top-level thing this
+   slice produced — `src/pages/<ScreenTitle>.tsx` when Step 5 composed a shared page, else this
+   slice's own component. Nothing from the Vite demo (counter, logos, doc links) stays. No router and
+   no new dependency — a single page needs neither.
+3. Delete what the scaffold alone used and nothing else now imports: `src/App.css` and
+   `src/assets/{hero.png,react.svg,vite.svg}` (check with `grep -rn` first); `public/icons.svg` too if
+   nothing references it. Leave `src/main.tsx` and `src/index.css` (Step 6 handles it) as they are.
+4. Keep the page working with no backend, per the isolation rule in `.build-kit/CLAUDE.md`: the
+   slice component must render its empty state, and `VITE_DATA_MODE=mock` must show its sample.
+
+## Step 8 — Verify against slice.json
 
 - Every rendered field traces back to a `readmodel.fields[]` entry — no invented or missing
   fields.
+- With a UI contract: the `getReadModel` call uses the contract's path and query `parameters`
+  verbatim, and every non-2xx response has its own rendered state. Otherwise:
 - The `queryReadModel` call targets `readmodel.apiEndpoint` verbatim as `table` — or, when it was
   missing at build time, the provisional `mock_...` table name noted in a comment (Step 1) — never a
   raw `fetch`, a direct `supabase.from(...)` call, or a hardcoded table name that doesn't match

package/stacks/supabase-react/templates/build-kit/CLAUDE.md

@@ -11,8 +11,9 @@ not attempt to build it, flag it via `request-feedback` instead.
 ## File Structure Constraints
 
 - **Strict Path Limitation**: `src/slices/{contextSlug}/{laneSlug}/{slicename}/*` — the one
-  exception is `src/pages/`, where multiple slices sharing one screen get composed together (see
-  guideline 8 below)
+  exceptions are `src/pages/`, where multiple slices sharing one screen get composed together (see
+  guideline 7 below), and — for the **first slice only** — `src/App.tsx` plus the Vite demo files it
+  replaces (guideline 10 below); `index.html` and the demo `src/index.css` for every slice (guideline 11)
 - **Slice Organization**: Each feature/domain should be organized as a separate slice
 
 ## Code Standards
@@ -27,7 +28,7 @@ not attempt to build it, flag it via `request-feedback` instead.
 2. Maintain clear separation of concerns within each slice
 3. Headers, auth, `fetch`, and Supabase table access live exclusively in `src/lib/api.ts` — a
    slice component never imports `src/lib/supabase.ts` itself, never calls `fetch`, and never
-   calls `supabase.from(...)` directly; it calls `postCommand`/`queryReadModel` and only contains
+   calls `supabase.from(...)` directly; when the backend slice published a UI contract (`ui-contract` skill, `slice.json` `notes[]`) the slice is built *from* it — path, parameters, body and every error response — and falls back to `apiEndpoint`/`fields[]` only when none exists; it calls `postCommand`/`getReadModel`/`queryReadModel` and only contains
    business logic (validation, request-body shaping, response handling)
 4. A command's/read-model's screen markup (`meta.pages` on its actor HTML_SCREEN node, scoped to
    this slice's `meta.marks` when the screen is shared) is the visual blueprint — translate it into
@@ -82,6 +83,18 @@ not attempt to build it, flag it via `request-feedback` instead.
    the app, not an arbitrary per-component index. See `build-state-change`/`build-state-view`'s
    samples step for the full convention.
 
+10. **The first slice also builds the base page.** `src/App.tsx` ships as the Vite demo. When the
+    slice being built is the first one in the project (no other folder under `src/slices/`), replace
+    it with a minimal base page rendering that slice's page or component and delete the demo-only
+    files; no router, no new dependency. Later slices never touch `src/App.tsx`. See
+    `build-state-change` Step 8 / `build-state-view` Step 7.
+11. **Every slice loads its screen's styles.** The mockup's classes are meaningless without the CSS
+    framework the board renders them with. Each slice detects it (`cssFrameworks`, else the classes
+    in `meta.pages`; none → Vite's default stays as is), makes sure `index.html` loads it, and neutralises the Vite demo
+    `src/index.css` if it's still there — automatically, idempotently, so an existing project heals
+    on its next build. Never hand-write CSS to imitate a framework. See `build-state-change` Step 7 /
+    `build-state-view` Step 6.
+
 At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
 
 When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
@@ -124,6 +137,7 @@ src/lib/supabase.ts                                # Supabase client singleton
 src/lib/api.ts                                     # postCommand/queryReadModel + auth headers + mock-mode switch (shared, not per-slice)
 src/lib/<CrossCutting>Provider.tsx                  # only for concerns every slice might need (session, theme, ...)
 src/pages/<ScreenTitle>.tsx                         # only when >1 slice shares a screen title — composes their components
+src/App.tsx                                        # base page — replaces the Vite demo when the first slice is built, untouched afterwards
 src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/
   <CommandTitle>.tsx                                # STATE_CHANGE slice — component (logic inline by default)
   use<CommandTitle>.ts                              # only if the logic was genuinely worth splitting out

package/stacks/supabase-react/templates/root/src/lib/api.ts

@@ -84,6 +84,58 @@ export async function postCommand<TResponse = unknown>(
   return payload as TResponse;
 }
 
+/**
+ * Fill an OpenAPI path template (`/api/customers/{customerId}/reservation`) with values,
+ * URL-encoding each one. Throws if a `{param}` has no value — a contract's path parameters are
+ * required. Use the contract's path verbatim as `template`; never hand-assemble a URL.
+ */
+export function buildPath(template: string, params: Record<string, string | number> = {}): string {
+  return template.replace(/\{(\w+)\}/g, (_, name: string) => {
+    const value = params[name];
+    if (value === undefined) throw new Error(`Missing path parameter "${name}" for ${template}`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+function mockSample<T>(samples: Record<string, T> | undefined, what: string): T {
+  const n = activeMockSample();
+  const sample = samples?.[n];
+  if (sample === undefined) {
+    throw new Error(
+      `Mock mode is on (VITE_MOCK_SAMPLE=${n}) but no sample-${n}.json exists for ${what} — add one under this component's samples/ folder.`,
+    );
+  }
+  return sample;
+}
+
+/**
+ * GET a read model from the backend's published `GET` UI contract (`path` already filled via
+ * `buildPath`, `query` = the contract's query `parameters`). Resolves with the parsed JSON, or
+ * throws `ApiError` on a non-2xx response — the status and body let a component render each
+ * documented error response as its own state. Mock mode serves `samples` like `queryReadModel`.
+ */
+export async function getReadModel<T>(
+  path: string,
+  query?: Record<string, string | number | boolean | undefined>,
+  samples?: Record<string, T>,
+): Promise<T> {
+  if (isMockMode()) return mockSample(samples, `GET ${path}`);
+
+  const qs = new URLSearchParams(
+    Object.entries(query ?? {}).filter(([, v]) => v !== undefined).map(([k, v]) => [k, String(v)]),
+  ).toString();
+  const headers = await getAuthHeaders();
+  const res = await fetch(`${API_BASE}${path}${qs ? `?${qs}` : ''}`, { method: 'GET', headers });
+
+  const payload = await res.json().catch(() => undefined);
+  if (!res.ok) {
+    const message =
+      (payload && (payload.error || payload.message)) || `Request failed with status ${res.status}`;
+    throw new ApiError(message, res.status, payload);
+  }
+  return payload as T;
+}
+
 export interface ReadModelParams {
   /** `readmodel.apiEndpoint`, verbatim — the Postgres table/view name. */
   table: string;
@@ -105,16 +157,7 @@ export async function queryReadModel<T>(
   params: ReadModelParams,
   samples?: Record<string, T>,
 ): Promise<T> {
-  if (isMockMode()) {
-    const n = activeMockSample();
-    const sample = samples?.[n];
-    if (sample === undefined) {
-      throw new Error(
-        `Mock mode is on (VITE_MOCK_SAMPLE=${n}) but no sample-${n}.json exists for table "${params.table}" — add one under this component's samples/ folder.`,
-      );
-    }
-    return sample;
-  }
+  if (isMockMode()) return mockSample(samples, `table "${params.table}"`);
 
   let query = supabase.from(params.table).select(params.select);
   for (const [column, value] of Object.entries(params.filters ?? {})) {