@eventmodelers/cli 2.0.9 → 2.0.11

package/shared/build-kit/lib/mcp-register.js

@@ -1,125 +1,5 @@
-// Registers the eventmodelers MCP server with an external agent harness (OpenCode, Gemini, Codex, Hermes),
-// for both loops that hand turns to one: the modeling loop (lib/modeling-exec.js) and the build
-// loop (ralph-exec.js).
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { spawnSync } from 'child_process';
-import { homedir } from 'os';
-import { dirname, join } from 'path';
-
-// POSIX single-quote escaping: close, insert an escaped quote, reopen. A turn is multi-line
-// text with backticks and $ in it, so it cannot go in unquoted.
-export function shellQuote(s) {
-  return `'${String(s).replace(/'/g, `'\\''`)}'`;
-}
-
-// Older OpenCode releases have no `run --standalone`; passing it makes `opencode run` print its
-// usage and exit 1, so every turn fails. Ask the installed binary once. Overridable for tests.
-let standaloneSupported = null;
-export function opencodeSupportsStandalone() {
-  if (standaloneSupported === null) {
-    const r = spawnSync('opencode', ['run', '--help'], { encoding: 'utf8' });
-    standaloneSupported = /--standalone\b/.test(`${r.stdout || ''}${r.stderr || ''}`);
-  }
-  return standaloneSupported;
-}
-export function setOpencodeStandaloneSupport(value) { standaloneSupported = value; }
-
-// Adds or refreshes one key in a project JSON config, leaving everything else in it alone. A file
-// that isn't plain JSON (a JSONC one with comments) is not rewritten — returns false instead, and
-// the caller says what to add by hand.
-function mergeJsonConfig(path, apply) {
-  let config = {};
-  if (existsSync(path)) {
-    try { config = JSON.parse(readFileSync(path, 'utf8')); } catch { return false; }
-  }
-  apply(config);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
-  return true;
-}
-
-// How each known harness learns about the eventmodelers MCP server — the --exec counterpart of
-// ensureMcpRegistered's `.mcp.json` for Claude, and like it rewritten every run, always into the
-// harness's *project* config in the agent's working dir (never a user-wide one), and always with
-// the token as an env reference the harness resolves from the env this runner hands it, never its
-// value. Each entry returns the command to run, which is where a harness without a usable project
-// config (Codex only loads one for a trusted project) takes the server as flags instead. Adding a
-// harness is one entry here.
-const MCP_REGISTRATIONS = {
-  opencode: (command, projectDir, url) => {
-    const entry = {
-      type: 'remote',
-      url,
-      headers: { 'x-token': '{env:EVENTMODELERS_TOKEN}', 'x-agent-id': '{env:EVENTMODELERS_AGENT_ID}' },
-    };
-    const ok = mergeJsonConfig(join(projectDir, 'opencode.json'), (config) => {
-      // OpenCode 2 nests servers under mcp.servers and still reads the older flat mcp.<name>;
-      // follow whichever form the file already uses.
-      config.mcp = config.mcp || {};
-      if (config.mcp.servers) config.mcp.servers.eventmodelers = entry;
-      else config.mcp.eventmodelers = entry;
-    });
-    // A plain `opencode run` hands the turn to opencode's shared background service, which was
-    // started with some other env: {env:EVENTMODELERS_TOKEN} resolves to nothing there and the
-    // server refuses every call. --standalone runs a private server that inherits this one's env.
-    // A binary without the flag runs the turn in-process already, so the flag is dropped, not added.
-    const supported = opencodeSupportsStandalone();
-    const standalone = !supported ? command.replace(/\s--standalone\b/, '')
-      : /\s--(standalone|server)\b/.test(` ${command}`) ? command : `${command} --standalone`;
-    return { command: standalone, file: ok ? 'opencode.json' : null, manual: ok ? null : `add mcp.eventmodelers = ${JSON.stringify(entry)} to opencode.json` };
-  },
-  gemini: (command, projectDir, url) => {
-    const entry = { httpUrl: url, headers: { 'x-token': '$EVENTMODELERS_TOKEN', 'x-agent-id': '$EVENTMODELERS_AGENT_ID' } };
-    const ok = mergeJsonConfig(join(projectDir, '.gemini', 'settings.json'), (config) => {
-      config.mcpServers = config.mcpServers || {};
-      config.mcpServers.eventmodelers = entry;
-    });
-    return { command, file: ok ? '.gemini/settings.json' : null, manual: ok ? null : `add mcpServers.eventmodelers = ${JSON.stringify(entry)} to .gemini/settings.json` };
-  },
-  // Hermes reads MCP servers from ~/.hermes/config.yaml only (there is no project-level file), so
-  // this never writes it — a user-wide file is not ours to rewrite. It reports the server as
-  // registered when the file already names it (the docker images ship it), and says what to add otherwise.
-  hermes: (command, _projectDir, url) => {
-    const file = join(process.env.HERMES_HOME || join(homedir(), '.hermes'), 'config.yaml');
-    const has = existsSync(file) && /^\s+eventmodelers:/m.test(readFileSync(file, 'utf8'));
-    return {
-      command,
-      file: null,
-      manual: has ? null : `add to ${file}:\nmcp_servers:\n  eventmodelers:\n    url: "${url}"\n    headers:\n      x-token: "\${EVENTMODELERS_TOKEN}"`,
-    };
-  },
-  codex: (command, _projectDir, url) => ({
-    // -c values are TOML; env_http_headers names the env var each header is read from.
-    command: `${command} -c ${shellQuote(`mcp_servers.eventmodelers.url="${url}"`)} -c ${shellQuote('mcp_servers.eventmodelers.env_http_headers={x-token="EVENTMODELERS_TOKEN",x-agent-id="EVENTMODELERS_AGENT_ID"}')}`,
-    file: null,
-    manual: null,
-  }),
-};
-
-// Which known harness a command runs — the first word naming one, so `npx @openai/codex exec`
-// and `/opt/bin/opencode run` are recognised as well as the bare names.
-export function harnessOf(command) {
-  for (const word of String(command).trim().split(/\s+/).slice(0, 3)) {
-    const name = word.split('/').pop().replace(/@.*$/, '');
-    if (MCP_REGISTRATIONS[name]) return name;
-  }
-  return null;
-}
-
-// Registers the MCP server for the command's harness. Returns the command to run with it, and
-// whether the server is now registered — false for an unknown command or a config it could not
-// update, where the turn still has to connect the way the kit says to.
-export function registerMcp(command, projectDir, baseUrl, log) {
-  const url = `${baseUrl}/mcp`;
-  const harness = harnessOf(command);
-  if (!harness) {
-    log(`MCP: unknown agent command — register the eventmodelers MCP server with it yourself: ${url}, header x-token from $EVENTMODELERS_TOKEN (and x-agent-id from $EVENTMODELERS_AGENT_ID)`);
-    return { command, registered: false };
-  }
-  const reg = MCP_REGISTRATIONS[harness](command, projectDir, url);
-  if (reg.manual) log(`MCP: could not update the ${harness} config${harness === 'hermes' ? '' : ' (not plain JSON)'} — ${reg.manual}`);
-  else log(`MCP: eventmodelers registered for ${harness}${reg.file ? ` in ${reg.file}` : ' via -c flags'}`);
-  return { command: reg.command, registered: !reg.manual };
-}
+// Registers the eventmodelers MCP server with an external agent harness. The per-harness logic
+// lives in ./harnesses/<name>.js; this module is the stable import for both loops that hand turns
+// to one: the modeling loop (lib/modeling-exec.js) and the build loop (ralph-exec.js).
 
+export { shellQuote, harnessOf, registerMcp, opencodeSupportsStandalone, setOpencodeStandaloneSupport } from './harnesses/index.js';

package/shared/build-kit/lib/ralph.js

@@ -320,9 +320,9 @@ export async function fetchAndPersistSlices(cfg, kitDir) {
       mkdirSync(sliceDir, { recursive: true });
       const sliceJsonPath = join(sliceDir, 'slice.json');
       const existingSlice = existsSync(sliceJsonPath) ? JSON.parse(readFileSync(sliceJsonPath, 'utf-8')) : {};
-      // The summary omits ticketNumber and assignee when the slice has none, so a cleared one must be cleared
+      // The summary omits ticketNumber, assignee and features when the slice has none, so a cleared one must be cleared
       // here too — otherwise the old one survives the merge and lands on the next build.
-      writeFileSync(sliceJsonPath, JSON.stringify({ ...existingSlice, ...slice, status: statusOf(state, slice), ticketNumber: slice.ticketNumber ?? null, assignee: slice.assignee ?? null }, null, 2), 'utf-8');
+      writeFileSync(sliceJsonPath, JSON.stringify({ ...existingSlice, ...slice, status: statusOf(state, slice), ticketNumber: slice.ticketNumber ?? null, assignee: slice.assignee ?? null, features: slice.features ?? null }, null, 2), 'utf-8');
     }
   }
 
@@ -508,6 +508,25 @@ export function readPickupStatus(kitDir) {
   return 'Planned';
 }
 
+// `run --feature <name>` (RALPH_FEATURE): only slices that belong to this feature are picked up.
+// Matched like the board does — trimmed, case-insensitive. Empty means no filter.
+export function readFeatureFilter() {
+  return (process.env.RALPH_FEATURE || '').trim().toLowerCase();
+}
+
+// Whether a slice is in the feature — its `features` as of the last fetch, from its slice.json. A slice
+// whose slice.json is missing or has no features is not in any feature, so a filter skips it.
+export function sliceInFeature(kitDir, ctx, folder, feature) {
+  if (!feature) return true;
+  if (!folder) return false;
+  try {
+    const { features } = JSON.parse(readFileSync(join(kitDir, '.slices', ctx, folder, 'slice.json'), 'utf-8'));
+    return Array.isArray(features) && features.some((f) => typeof f === 'string' && f.trim().toLowerCase() === feature);
+  } catch {
+    return false;
+  }
+}
+
 function readCurrentContext(kitDir) {
   const ctxPath = join(kitDir, '.slices', 'current_context.json');
   if (!existsSync(ctxPath)) return null;
@@ -531,7 +550,7 @@ function readSliceMeta(kitDir, ctx, folder) {
 // before the next one starts. When the current context has no planned work, the first other
 // context that does becomes the current one (current_context.json is rewritten), so a slice
 // set to Planned in any context is eventually built. Ids in `skipIds` are passed over.
-function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
+export function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
   const slicesDir = join(kitDir, '.slices');
   const currentCtx = readCurrentContext(kitDir);
   let others = [];
@@ -539,13 +558,14 @@ function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
     others = readdirSync(slicesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
   } catch {}
   const pickup = statusKey(readPickupStatus(kitDir));
+  const feature = readFeatureFilter();
   const candidates = [...(currentCtx ? [currentCtx] : []), ...others.filter((c) => c !== currentCtx)];
   for (const ctx of candidates) {
     const indexPath = join(slicesDir, ctx, 'index.json');
     if (!existsSync(indexPath)) continue;
     try {
       const { slices } = JSON.parse(readFileSync(indexPath, 'utf-8'));
-      const planned = slices && slices.find((s) => statusKey(s.status) === pickup && !skipIds.has(s.id));
+      const planned = slices && slices.find((s) => statusKey(s.status) === pickup && !skipIds.has(s.id) && sliceInFeature(kitDir, ctx, s.folder, feature));
       if (!planned) continue;
       if (ctx !== currentCtx) {
         writeFileSync(join(slicesDir, 'current_context.json'), JSON.stringify({ name: ctx }, null, 2), 'utf-8');
@@ -561,13 +581,14 @@ function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
 function listPlannedIds(kitDir) {
   const slicesDir = join(kitDir, '.slices');
   const pickup = statusKey(readPickupStatus(kitDir));
+  const feature = readFeatureFilter();
   const ids = new Set();
   try {
     for (const d of readdirSync(slicesDir, { withFileTypes: true })) {
       if (!d.isDirectory()) continue;
       try {
         const { slices } = JSON.parse(readFileSync(join(slicesDir, d.name, 'index.json'), 'utf-8'));
-        for (const s of slices ?? []) if (statusKey(s.status) === pickup) ids.add(s.id);
+        for (const s of slices ?? []) if (statusKey(s.status) === pickup && sliceInFeature(kitDir, d.name, s.folder, feature)) ids.add(s.id);
       } catch {}
     }
   } catch {}
@@ -770,6 +791,7 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false,
   const board = credentialed ? createBoard(cfg) : null;
   const meta = eventMeta(cfg);
   ensureLearningsGitRules(kitDir);
+  if (readFeatureFilter()) console.log(`[ralph] --feature "${process.env.RALPH_FEATURE.trim()}" — only slices of that feature are picked up.`);
   // Sharing the event log with the board (`run --sync`): needs the board, so never with --local.
   const share = createBuildLogShare({ kitDir, cfg, meta, agentType: cfg?.agentType ?? 'BUILD', kitType: kitTypeOf(readPickupStatus(kitDir)), sync: process.env.RALPH_SYNC === '1', enabled: credentialed, log: (line) => console.log(`[ralph] ${line}`) });
   if (process.env.RALPH_SYNC === '1' && !credentialed) console.log('[ralph] --sync needs board credentials — the build log stays local.');

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

@@ -831,6 +831,29 @@ Build structured slice data from board state.
 
 ---
 
+### Slice features (`features`)
+
+A slice can belong to one or more **features** — free-text names such as `Seat reservation` that group slices across chapters (the people on the board see them in the Features list in the toolbar, where picking one fades every column that isn't part of it). They live on the slice's SLICE_BORDER as `meta.features`, an array of strings.
+
+- **Read**: the slice data of a slice carries `features` (omitted when it has none), next to `ticketNumber` and `assignee`.
+- **Use**: treat `features` as context — slices sharing a feature belong together, so when a build touches shared concepts, look at the sibling slices of the same feature before inventing a new name or shape. It never changes what a slice must do, and an empty list is normal.
+- **Set** (only when the user asks you to group slices): a `node:changed` event on the SLICE_BORDER, same shape as the status update. Send the **whole** list — it replaces the old one — and reuse an existing feature's exact spelling instead of adding a near-duplicate (`Booking` vs `booking`; the board treats them as one, but keep them tidy):
+
+```bash
+curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
+  -H "Content-Type: application/json" \
+  -H "x-token: <TOKEN>" \
+  -d '[{
+    "id": "<new-random-uuid>",
+    "eventType": "node:changed",
+    "nodeId": "<SLICE_NODE_ID>",
+    "changedAttributes": ["features"],
+    "meta": { "type": "SLICE_BORDER", "features": ["Seat reservation"] }
+  }]'
+```
+
+---
+
 ### GET `/api/org/:orgId/boards/:boardId/slicedata/slices`
 List all slices on a board.
 

package/shared/skills/load-slice/SKILL.md

@@ -57,7 +57,7 @@ This returns `{ "slices": [ { "id": "...", "title": "...", "status": "..." } ] }
 mcp__eventmodelers__get_slice_data { "boardId": "<BOARD_ID>", "contextName": "<name>" }
 ```
 
-This call stays full (no `projection`): Step 3 persists the complete slice object as `slice.json`, which the build skills read fields, specs and comments from. When only one slice is needed, pass `sliceId` as well.
+This call stays full (no `projection`): Step 3 persists the complete slice object as `slice.json`, which the build skills read fields, specs and comments from. It also carries the slice's `features` (names grouping slices across chapters, see `learn-eventmodelers-api` → "Slice features"), `ticketNumber` and `assignee` when it has them. When only one slice is needed, pass `sliceId` as well.
 
 (`get_slice_data` requires a `contextName` or `contextId`. If the context isn't already known, list the context names in one call — `mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "MODEL_CONTEXT", "projection": "line" }` (only titles needed; a timeline name works as `contextName` too, so fall back to `type: "CHAPTER"` with `projection: "line"` when there are no MODEL_CONTEXT nodes) — then map slices to contexts with `list_slices { "boardId": "<BOARD_ID>", "contextName": "<name>" }` per context. Don't `get_node` each `SLICE_BORDER`.)