@eventmodelers/cli 1.0.7 → 1.0.9

package/cli.js

@@ -1932,9 +1932,10 @@ program
   .command('fetch')
   .description('Pull full slice detail for one context on the board via the slicedata API and write it into .slices/ — the pull-based counterpart to `listen`, without screen images')
   .requiredOption('--context <name>', 'Name of the MODEL_CONTEXT to fetch')
-  .option('--slice-id <id>', 'After fetching, print just the slice with this id')
-  .option('--slice-title <title>', 'After fetching, print just the slice with this title (case-insensitive)')
-  .option('--spec-kitty', "After fetching, also restate this context as a Spec Kitty mission brief (.kittify/mission-brief.md via `spec-kitty intake`) — deterministic, no LLM call, no mission/spec.md/tasks created. Run `/spec-kitty.specify` afterward to turn the brief into a mission. Requires `spec-kitty init` to already be set up in this project (see lib/adapters/spec-kitty-adapter.js). One-shot: does not start a loop.")
+  .option('--format <format>', 'Output format: json (default, builds the full .slices/ folder structure), yaml, textual, toon, emlang, or esdm (each of these five is dumped to a single .slices/<context>/slicedata.<ext> file instead)', 'json')
+  .option('--slice-id <id>', 'After fetching, print just the slice with this id (requires --format json)')
+  .option('--slice-title <title>', 'After fetching, print just the slice with this title, case-insensitive (requires --format json)')
+  .option('--spec-kitty', "After fetching, also restate this context as a Spec Kitty mission brief (.kittify/mission-brief.md via `spec-kitty intake`) — deterministic, no LLM call, no mission/spec.md/tasks created. Run `/spec-kitty.specify` afterward to turn the brief into a mission. Requires `spec-kitty init` to already be set up in this project (see lib/adapters/spec-kitty-adapter.js) and --format json. One-shot: does not start a loop.")
   .action(async (opts, command) => {
     const cwd = process.cwd();
     const kitDir = findInstalledKitDir(cwd);

package/lib/fetch.js

@@ -17,6 +17,14 @@ export class FetchAuthError extends Error {
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+// Mirrors the server's exporter registry (backend/src/slices/change/slicedata/exporters/
+// ExporterRegistry.ts) — json is the canonical shape (drives the full .slices/ folder
+// structure below); every other format is a transform of it and gets dumped as a single
+// file instead, so its extension reflects the transform's actual output, not its name
+// (textual is JSON-wrapped; emlang/esdm are YAML documents; toon is its own thing).
+const SUPPORTED_FORMATS = ['json', 'yaml', 'textual', 'toon', 'emlang', 'esdm'];
+const FORMAT_EXTENSIONS = { yaml: 'yaml', textual: 'json', toon: 'toon', emlang: 'yaml', esdm: 'yaml' };
+
 // `--context` accepts any of: a MODEL_CONTEXT name or id, or a timeline (CHAPTER) name or id.
 // /slicedata's contextId/contextName params now both resolve against MODEL_CONTEXT nodes first,
 // then timelines (id matched exactly, name case-insensitively) — including a timeline with no
@@ -72,7 +80,7 @@ export async function runFetch({ cwd, kitDir, cfg, opts = {} }) {
   // never "board not found". Only 401/403 are credential problems worth the
   // reconfigure-and-retry dance in cli.js; 404 gets reported and the process exits,
   // same as any other non-auth error.
-  async function fetchJson(url, what, { allow404 = false } = {}) {
+  async function fetchResponse(url, what, { allow404 = false } = {}) {
     let res;
     try {
       res = await fetch(url, { headers });
@@ -92,7 +100,19 @@ export async function runFetch({ cwd, kitDir, cfg, opts = {} }) {
       console.error(`❌ ${what}: HTTP ${res.status}`);
       process.exit(1);
     }
-    return res.json();
+    return res;
+  }
+
+  async function fetchJson(url, what, options) {
+    const res = await fetchResponse(url, what, options);
+    return res ? res.json() : res;
+  }
+
+  // Non-json formats aren't a {slices: [...]} payload — just the exporter's raw output
+  // (a YAML doc, a TOON encoding, ...) — so it's written straight to disk, not parsed.
+  async function fetchText(url, what, options) {
+    const res = await fetchResponse(url, what, options);
+    return res ? res.text() : res;
   }
 
   // Falls back to cwd when no kit is installed — fetch doesn't need kit-specific
@@ -100,6 +120,17 @@ export async function runFetch({ cwd, kitDir, cfg, opts = {} }) {
   const SLICES_DIR = join(kitDir || cwd, '.slices');
 
   const contextInput = opts.context;
+  const format = (opts.format || 'json').toLowerCase();
+  if (!SUPPORTED_FORMATS.includes(format)) {
+    console.error(`❌ Unsupported format "${format}". Supported: ${SUPPORTED_FORMATS.join(', ')}`);
+    process.exit(1);
+  }
+  // --slice-id/--slice-title/--spec-kitty all depend on the parsed {slices: [...]} list
+  // that only the json format produces — fail fast instead of silently ignoring them.
+  if (format !== 'json' && (opts.sliceId || opts.sliceTitle || opts.specKitty)) {
+    console.error('❌ --slice-id, --slice-title, and --spec-kitty require --format json (the default).');
+    process.exit(1);
+  }
 
   console.log(`▶ Fetching context "${contextInput}" from ${baseUrl} (board ${cfg.boardId})...`);
 
@@ -112,10 +143,25 @@ export async function runFetch({ cwd, kitDir, cfg, opts = {} }) {
   const contextQuery = UUID_RE.test(contextInput)
     ? `contextId=${encodeURIComponent(contextInput)}`
     : `contextName=${encodeURIComponent(contextInput)}`;
-  const payload = await fetchJson(
-    `${baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata?${contextQuery}`,
-    `slicedata?${contextQuery}`,
-  );
+  const url = `${baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata?${contextQuery}&format=${format}`;
+
+  // Only json builds the full .slices/<context>/<slice>/slice.json folder structure —
+  // every other format has no guaranteed {slices: [...]} shape to walk (it's the
+  // exporter's raw output: a YAML doc, a TOON encoding, ...), so it's just dumped
+  // as a single file. The resolved context name isn't known without parsing JSON,
+  // so the folder is slugified from the raw --context input instead.
+  if (format !== 'json') {
+    const body = await fetchText(url, `slicedata?${contextQuery}&format=${format}`);
+    const contextSlug = slugify(contextInput) || 'default';
+    const baseFolder = join(SLICES_DIR, contextSlug);
+    mkdirSync(baseFolder, { recursive: true });
+    const outFile = join(baseFolder, `slicedata.${FORMAT_EXTENSIONS[format]}`);
+    writeFileSync(outFile, body);
+    console.log(`✅ Fetched context "${contextInput}" as ${format} → ${relative(cwd, outFile)}`);
+    return;
+  }
+
+  const payload = await fetchJson(url, `slicedata?${contextQuery}&format=${format}`);
   const { slices: allSlices } = payload;
   const displayContext = allSlices[0]?.context || contextInput;
 

package/package.json

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

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -26,7 +26,7 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 | `get_board_events` | `boardId` | All board events, in sequence | §1 `GET .../events` |
 | `search_board_events` | `boardId`, `name` | Search events by node name | §1 `GET .../events/search` |
 | `submit_node_events` | `boardId`, `events[]` | Create/update nodes (raw `NodeChangeEvent`/edge events) | §3 `POST .../nodes/events` |
-| `delete_node` | `boardId`, `nodeId` | Delete a node | (via `node:deleted` event, §3) |
+| `delete_node` | `boardId`, `nodeId` | Delete a node. Deleting a chapter (timeline) cascades — every node placed in one of its cells, plus any node parented to it (e.g. SLICE_BORDER), is deleted too, along with all their edges | (via `node:deleted` event, §3) |
 | `create_drawing` | `boardId`, `kind`, `x`, `y`, `width`, `height`, ... | Freehand canvas annotation (path/rect/text) — never placed in a cell | — (no REST equivalent; MCP-only) |
 | `find_nodes_in_drawing` | `boardId`, `drawingId` | Nodes fully contained inside a drawing's bounding box | — (no REST equivalent; MCP-only) |
 | `create_chapter` | `boardId`, `x?`, `y?` | Create a timeline | §2 `POST .../chapters` |
@@ -34,12 +34,12 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 | `delete_column` | `boardId`, `timelineId`, `columnId` | Delete a column | §2 `DELETE .../columns/:columnId` |
 | `add_lane` | `boardId`, `timelineId`, `type`, `label?`, `index?` | Add a lane/row | §2 `POST .../timelines/:id/lanes` |
 | `remove_lane` | `boardId`, `timelineId`, `rowId` | Remove a lane | — (extends §2; no direct REST route) |
-| `move_node_in_timeline` | `boardId`, `timelineId`, `movedNodeId`, `toCellId` | Move a placed node to another cell | — (MCP-only convenience) |
+| `move_node_in_timeline` | `boardId`, `timelineId`, `movedNodeId`, `toCellId` | Move a placed node to another cell — its previous cell is automatically cleared | — (MCP-only convenience) |
 | `move_timeline_structure` | `boardId`, `timelineId`, `kind` (`'column'\|'lane'`), `id`, `toIndex` | Reorder a column or lane (row) — `kind` picks which `id` refers to | — (MCP-only convenience) |
 | `move_timeline_position` | `boardId`, `timelineId`, `x`, `y` | Move a chapter node on canvas | — (MCP-only convenience) |
-| `drop_node_to_cell` | `boardId`, `timelineId`, `cellId`, `nodeId`, `nodeType` | Place an existing node into a cell | §2 `POST .../cells/:cellId/drop` |
-| `clear_cell` | `boardId`, `timelineId`, `cellId` | Remove+delete the node in a cell | — (MCP-only convenience) |
-| `create_slice` | `boardId`, `timelineId`, `type`, `index?` | Create a full slice (column + nodes + SLICE_BORDER) | §5 `POST .../slices` |
+| `drop_node_to_cell` | `boardId`, `timelineId`, `cellId`, `nodeId`, `nodeType` | Place an existing node into a cell — if it was already placed elsewhere on this timeline, that cell is automatically cleared | §2 `POST .../cells/:cellId/drop` |
+| `clear_cell` | `boardId`, `timelineId`, `cellId` | Unassign the node from a cell without deleting it — the cell becomes empty and the node survives (unplaced); no-op if already empty. Use `delete_node` to remove the node entirely | — (MCP-only convenience) |
+| `create_slice` | `boardId`, `timelineId`, `type`, `index?`, `nodes?: {actor?, interaction?, swimlane?}` (each `{rowId?, title?}`) | Create a full slice (column + nodes + SLICE_BORDER). `rowId` targets a specific lane when the chapter has more than one lane of that type (e.g. several actor lanes); omit to use the first matching lane | §5 `POST .../slices` |
 | `create_slice_definition` | `boardId`, `timelineId`, `columnId`, `title`, `data?`, `meta?` | Create a SLICE_BORDER over an existing column | §5 `POST .../slice-definitions` |
 | `place_element` | `boardId`, `timelineId`, `elementType`, `title`, `columnIndex?` | Find/create an empty cell in the right lane and place a COMMAND/READMODEL/EVENT | — (MCP-only convenience; composes §2+§3) |
 | `list_slices` | `boardId` | List slices (id, title, status) | §8 `GET .../slicedata/slices` |
@@ -254,7 +254,7 @@ Add a lane (row) to a timeline.
 ---
 
 ### POST `/api/org/:orgId/boards/:boardId/timelines/:timelineId/cells/:cellId/drop`
-Drop a node into a timeline cell. Validates placement rules.
+Drop a node into a timeline cell. Validates placement rules. If the node was already placed in another cell on this timeline, that cell is automatically cleared as part of the same operation — a node can only ever occupy one cell.
 
 **Request body**: `{ nodeId: string, nodeType: ElementType }`
 
@@ -283,6 +283,8 @@ Submit node change events.
 
 Any `node:created` event carrying a `chapterId` plus `cellId`/`cellName` (i.e. placing a node on a timeline) also triggers a best-effort, fire-and-forget auto-connect to type-compatible neighbors — same rules as the auto-connect endpoint below. Failures there never fail this call.
 
+A `node:deleted` event cascades: if the deleted node is a chapter (timeline), every node placed in one of its cells and any node parented to it (e.g. a SLICE_BORDER spanning one of its columns) is deleted too, along with all their edges.
+
 **Request body**: `NodeChangeEvent[]`
 
 ```typescript
@@ -427,9 +429,9 @@ Create a complete slice (1 column + 3 nodes automatically placed).
   type: 'state-change' | 'state-view' | 'automation'
   index?: number
   nodes?: {
-    actor?: Partial<NodeData>
-    interaction?: Partial<NodeData>
-    swimlane?: Partial<NodeData>
+    actor?: Partial<NodeData> & { rowId?: string }
+    interaction?: Partial<NodeData> & { rowId?: string }
+    swimlane?: Partial<NodeData> & { rowId?: string }
   }
 }
 ```
@@ -439,6 +441,8 @@ Create a complete slice (1 column + 3 nodes automatically placed).
 - `state-view` → HTML_SCREEN (actor) + READMODEL (interaction) + EVENT (swimlane)
 - `automation` → AUTOMATION (actor) + COMMAND (interaction) + EVENT (swimlane)
 
+Each chapter has exactly one actor/interaction/swimlane lane by default, but a chapter can have several lanes of the same type (e.g. multiple actor lanes). Without a `rowId`, the node is always placed in the **first** lane of the matching type — pass `nodes.<actor|interaction|swimlane>.rowId` (a row id from the chapter's `timelineData.rows`) to target a specific lane instead. An invalid `rowId` (not found, or found but the wrong lane type) is a `400 ROW_NOT_FOUND`/`ROW_TYPE_MISMATCH` error.
+
 The actor HTML_SCREEN is created as a **stub** — a single visibly-placeholder page ("Untitled screen — design pending") unless `nodes.actor.pages` is passed explicitly. Whoever calls this (the `add-next-slice` skill — the one that creates a brand-new slice from scratch, as opposed to `eventmodeling-slicing-event-models`, which only makes existing elements explicit) is responsible for immediately replacing that stub via the `html-screen` skill — including gathering the board's existing screens first so the new one matches their established style, since `html-screen` itself has no visibility into other screens.
 
 **Response**: `200` — slice data

package/stacks/modeling-kit/templates/.claude/skills/add-next-slice/SKILL.md

@@ -63,6 +63,8 @@ mcp__eventmodelers__create_slice { "boardId": "<BOARD_ID>", "timelineId": "<TL>"
 
 Pick `type` based on what you decided in Step 1 — `state-change` for a new command, `state-view` for a new read model, `automation` for a new automation. Always pass `nodes.interaction.title` as the command/read model/automation name you decided on in Step 1 — per the Core Concept above, the slice is *named after that element*, and the backend only derives the slice title from this field; omitting it produces a useless generic "State Change"/"State View"/"Automation" label instead. This also creates the slice's `SLICE_BORDER` automatically — no separate `create_slice_definition` call needed.
 
+If the chapter has more than one lane of the same type (e.g. several actor lanes for different user roles), `create_slice` places each node in the **first** matching lane by default — pass `nodes.<actor|interaction|swimlane>.rowId` (the target row's id, from the chapter's `timelineData.rows`) to target a specific lane instead of the first one.
+
 **Fallback (no MCP):**
 ```bash
 curl -X POST $BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/slices \