@eventmodelers/cli 1.0.45 → 1.0.46

package/README.md

@@ -19,6 +19,9 @@ npx @eventmodelers/cli init --stack node            # Node.js / TypeScript
 npx @eventmodelers/cli init --stack supabase         # Supabase
 npx @eventmodelers/cli init --stack axon             # Axon Framework (Java/Kotlin)
 npx @eventmodelers/cli init --stack cratis-csharp    # Cratis (.NET/C#)
+npx @eventmodelers/cli init --stack opencqrs         # OpenCQRS (Java, EventSourcingDB)
+npx @eventmodelers/cli init --stack umadb            # UmaDB (Java)
+npx @eventmodelers/cli init --stack kurrent          # Kurrent (Java, KurrentDB)
 ```
 
 The installer prompts for your API token, Organization ID, and Board ID from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account), scaffolds the stack into your project, and writes `.eventmodelers/config.json` with your credentials.
@@ -73,7 +76,7 @@ your-project/
 └── CLAUDE.md                      ← agent instructions
 ```
 
-The four backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
+The seven backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`, `opencqrs`, `umadb`, `kurrent`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
 
 ## Skills
 

package/cli.js

@@ -70,6 +70,27 @@ const STACKS = {
     useShared: true,
     needsBoardId: true,
   },
+  opencqrs: {
+    label: 'OpenCQRS (Java, EventSourcingDB)',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
+  umadb: {
+    label: 'UmaDB (Java)',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
+  kurrent: {
+    label: 'Kurrent (Java, KurrentDB)',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
 };
 
 // Not a stack — no backend scaffold, just skills + the agent loop. Installed via
@@ -774,7 +795,10 @@ async function installStack(stackKey, stackCfg, options = {}) {
       // first-installed kit added (e.g. node_modules/.idea from a build-kit install).
       const gitignoreDest = join(targetDir, '.gitignore');
       const priorGitignore = existsSync(gitignoreDest) ? readFileSync(gitignoreDest, 'utf-8') : null;
-      copyDirContents(rootSrc, targetDir, { skip: ['CLAUDE.md'] });
+      // .githooks/ (the slice commit-scope guard) is opt-in via `init --hooks` — skipped
+      // here and handled explicitly below so a plain `init` never silently changes the
+      // project's git hook wiring.
+      copyDirContents(rootSrc, targetDir, { skip: ['CLAUDE.md', '.githooks'] });
       if (priorGitignore !== null && existsSync(gitignoreDest)) {
         const incoming = readFileSync(gitignoreDest, 'utf-8');
         const merged = mergeGitignoreLines(priorGitignore, incoming);
@@ -888,6 +912,31 @@ async function installStack(stackKey, stackCfg, options = {}) {
       }
     }
 
+    // --- 3b. Opt-in slice commit-scope guard (`init --hooks`) ---
+    // Skipped from the generic root copy above so a plain `init` never touches git's
+    // hook wiring; installed explicitly here only when requested.
+    if (options.hooks) {
+      const hooksSrc = join(rootSrc, '.githooks');
+      if (existsSync(hooksSrc)) {
+        copyDirContents(hooksSrc, join(targetDir, '.githooks'));
+        const preCommitHook = join(targetDir, '.githooks', 'pre-commit');
+        if (existsSync(preCommitHook)) {
+          // cpSync doesn't reliably carry over the executable bit across platforms,
+          // and git silently skips a non-executable hook.
+          try { execSync(`chmod +x "${preCommitHook}"`); } catch {}
+        }
+        try {
+          execSync('git rev-parse --git-dir', { cwd: targetDir, stdio: 'ignore' });
+          execSync('git config core.hooksPath .githooks', { cwd: targetDir });
+          console.log('  ✓ Installed .githooks/ and set core.hooksPath — commits touching src/slices/ are now scope-guarded');
+        } catch {
+          console.log('  ✓ Installed .githooks/ — run `git config core.hooksPath .githooks` once this directory is a git repo to activate it');
+        }
+      } else {
+        console.log('  ℹ️  --hooks was given but this stack ships no .githooks/ template — nothing to install');
+      }
+    }
+
     // --- 4. Install kit dependencies ---
     if (existsSync(join(kitDir, 'package.json'))) {
       console.log('📦 Installing kit dependencies...');
@@ -1539,6 +1588,7 @@ credentialFlags(program
   .option('--target <name>', `Bridge target framework (${Object.keys(BRIDGE_TARGETS).join(', ')}) — only meaningful with --bridge`)
   .option('--hook <command>', 'Persist a default shell command hook for `bridge` to run per batch of slice changes instead of Claude/Ollama (e.g. commit + push .slices/ for a CI pipeline to pick up) — only meaningful with --bridge. Can also be set per-run with `bridge --hook`.')
   .option('--build-kit', 'Install a blank build-kit scaffold (.build-kit/ + .claude/skills/build-*/SKILL.md placeholders, all TODO-marked) for a stack not built into this CLI yet — no fixed backend. Mutually exclusive with --stack/--modeling/--bridge.')
+  .option('--hooks', 'Install the slice commit-scope guard (.githooks/pre-commit, running .build-kit/lib/check-commit-scope.cjs) and wire it up via `git config core.hooksPath .githooks` — only meaningful with --stack (build-kit stacks). Off by default.')
   .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json'))
   .action(async (opts, command) => {
@@ -1628,6 +1678,7 @@ credentialFlags(program
         force: opts.force,
         credentialOverrides: credentialOverridesFromOpts(opts),
         templatesSource: join(clonedDir, 'templates'),
+        hooks: opts.hooks,
       });
       return;
     }
@@ -1639,6 +1690,7 @@ credentialFlags(program
       global: opts.global,
       force: opts.force,
       credentialOverrides: credentialOverridesFromOpts(opts),
+      hooks: opts.hooks,
     });
   });
 

package/package.json

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

package/shared/build-kit/lib/checks/README.md

@@ -0,0 +1,59 @@
+# Commit-scope guard checks
+
+Every `*.cjs` file in this folder is loaded and run automatically by
+`../check-commit-scope.cjs` against the staged changeset of a slice commit
+(a commit that touches `src/slices/{context}/{slice}/**`). Files run in
+filename sort order — that's why they're numbered.
+
+## Adding a check
+
+Create a new file here, e.g. `60-my-check.cjs`, exporting:
+
+```js
+'use strict';
+
+module.exports = {
+  name: 'my-check',            // short id, prefixed onto any violation it reports
+  skipIfAlreadyFailing: false, // optional: true = skip this check once an earlier
+                                // one already found a violation (use for slow checks,
+                                // e.g. a build/typecheck — no point running it if the
+                                // commit is already going to be rejected)
+  run(ctx) {
+    // Inspect ctx and return an array of violations. No violations → return
+    // [] (or undefined/null).
+    return [
+      { path: 'src/slices/cart/AddItem/AddItemCommand.ts', reason: 'why this is a problem' },
+    ];
+  },
+};
+```
+
+### `ctx` passed to every check
+
+| field           | type            | meaning                                                              |
+|-----------------|-----------------|-----------------------------------------------------------------------|
+| `changes`       | `{status, path}[]` | staged files — `status` is git's single-letter code (`A`/`M`/`D`/...) |
+| `touchesSlice`  | `boolean`       | always `true` — the runner only loads checks once this is true        |
+| `repoRoot`      | `string`        | absolute path to the repo root (`git rev-parse --show-toplevel`)       |
+| `SLICE_PATTERN` | `RegExp`        | matches a path inside a slice's own folder: `src/slices/{ctx}/{slice}/`|
+
+### Return value
+
+An array of `{ path, reason }` objects — one per violation. `path` should be
+the offending file (or a synthetic label like `'(slice.json)'` if the problem
+isn't tied to one staged file). `reason` is a short, human-readable sentence
+explaining what's wrong; the runner prefixes it with `[<check name>]`.
+
+Return `[]`, `undefined`, or `null` when there's nothing to report. Throwing
+is treated as a violation too (`[<check name>] threw: <message>`), so a check
+doesn't need its own top-level try/catch.
+
+### Conventions used by the existing checks
+
+- Prefer **not blocking** over a false positive when a check can't determine
+  the answer confidently (e.g. slice.json isn't found, or a file's shape isn't
+  recognized) — these are heuristics layered on top of the hard path-scope
+  rules, not a full compiler/schema validator.
+- If two checks would flag the *same file*, only the first one to run reports
+  it (the runner dedupes by path) — so keep genuinely distinct concerns in
+  separate files rather than trying to avoid overlap yourself.

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

@@ -201,14 +201,28 @@ async function fetchAndPersistSlices(cfg, kitDir) {
     writeFileSync(ctxPath, JSON.stringify({ name: activeCtx }, null, 2), 'utf-8');
   }
 
-  // Write per-context index.json and per-slice slice.json
+  // Write per-context index.json and per-slice slice.json.
+  //
+  // This endpoint (`/slicedata/slices`) is the CHEAP summary one — `{ id, title, status }`
+  // only, no commands/events/specifications/codeGen prompts. Its whole job here is to keep
+  // `status` fresh so hasPendingTasks/getFirstPlannedSliceTitle see live transitions; it must
+  // NEVER clobber the richer slice.json a full fetch (`/load-slice`, `eventmodelers fetch`,
+  // `eventmodelers listen`) already wrote for the same slice. So every write below merges
+  // onto whatever's already on disk — spreading the existing object first, the fresh summary
+  // fields second — instead of replacing it wholesale.
   for (const [contextSlug, { slices: ctxSlices }] of Object.entries(contexts)) {
     const contextDir = join(slicesDir, contextSlug);
     mkdirSync(contextDir, { recursive: true });
 
+    const indexPath = join(contextDir, 'index.json');
+    const existingIndex = existsSync(indexPath) ? JSON.parse(readFileSync(indexPath, 'utf-8')) : { slices: [] };
+    const existingById = new Map((existingIndex.slices ?? []).map((e) => [e.id, e]));
+
     const indexSlices = ctxSlices.map((s, i) => {
       const folder = (s.title ?? s.id).replaceAll(' ', '').toLowerCase();
+      const existing = existingById.get(s.id);
       return {
+        ...existing,
         id: s.id,
         slice: s.title,
         index: i,
@@ -216,16 +230,18 @@ async function fetchAndPersistSlices(cfg, kitDir) {
         contextSlug,
         folder,
         status: s.status,
-        definition: { id: s.id, title: s.title, status: s.status },
+        definition: { ...existing?.definition, id: s.id, title: s.title, status: s.status },
       };
     });
-    writeFileSync(join(contextDir, 'index.json'), JSON.stringify({ slices: indexSlices }, null, 2), 'utf-8');
+    writeFileSync(indexPath, JSON.stringify({ slices: indexSlices }, null, 2), 'utf-8');
 
     for (const slice of ctxSlices) {
       const folder = (slice.title ?? slice.id).replaceAll(' ', '').toLowerCase();
       const sliceDir = join(contextDir, folder);
       mkdirSync(sliceDir, { recursive: true });
-      writeFileSync(join(sliceDir, 'slice.json'), JSON.stringify(slice, null, 2), 'utf-8');
+      const sliceJsonPath = join(sliceDir, 'slice.json');
+      const existingSlice = existsSync(sliceJsonPath) ? JSON.parse(readFileSync(sliceJsonPath, 'utf-8')) : {};
+      writeFileSync(sliceJsonPath, JSON.stringify({ ...existingSlice, ...slice }, null, 2), 'utf-8');
     }
   }
 
@@ -265,30 +281,83 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
 
   const channelName = `board:${cfg.boardId}-slicechanged`;
   const realtime = await createRealtimeAdapter(cfg, realtimeToken);
-  realtime.subscribe(
-    channelName,
-    {
-      message: (payload) => {
-        if (payload === 'Exit') {
-          console.log('[agent] Received "Exit" — shutting down');
-          process.exit(0);
+
+  // Shared by the scheduled timer, a CHANNEL_ERROR/TIMED_OUT subscribe status, and a
+  // 401 from the alive-ping — whichever notices the token is bad first wins; the rest
+  // just await the same in-flight refresh instead of firing duplicate mint requests.
+  const ts = () => new Date().toISOString();
+  let refreshing = null;
+  const refreshToken = (reason) => {
+    if (!refreshing) {
+      const startedAt = Date.now();
+      console.log(`[agent] ${ts()} Refreshing realtime token (reason: ${reason})...`);
+      refreshing = (async () => {
+        try {
+          realtimeToken = await retryOn401('getRealtimeToken (refresh)', () => getRealtimeToken(cfg));
+          await realtime.setAuth(realtimeToken);
+          console.log(`[agent] ${ts()} Token refreshed (reason: ${reason}, took ${Date.now() - startedAt}ms)`);
+        } catch (err) {
+          console.error(`[agent] ${ts()} Token refresh FAILED (reason: ${reason}):`, err);
+          throw err;
+        } finally {
+          refreshing = null;
         }
+      })();
+    }
+    return refreshing;
+  };
+
+  // A subscribe that errors on a stale token needs a fresh token AND a new join
+  // attempt — setAuth alone doesn't re-join a channel that already errored out.
+  // Capped so a non-expiry auth failure (e.g. genuinely revoked access) can't turn
+  // into a tight resubscribe loop hammering the platform forever.
+  let channelErrorStreak = 0;
+  const subscribeChannel = () => {
+    realtime.subscribe(
+      channelName,
+      {
+        message: (payload) => {
+          if (payload === 'Exit') {
+            console.log(`[agent] ${ts()} Received "Exit" — shutting down`);
+            process.exit(0);
+          }
+        },
+        'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
       },
-      'slice:changed': (payload) => handleSliceChanged(payload, cfg, kitDir, queueAllStatuses),
-    },
-    (status) => console.log(`[agent] Channel "${channelName}": ${status}`),
-  );
+      async (status) => {
+        if (status !== 'CHANNEL_ERROR' && status !== 'TIMED_OUT') {
+          if (channelErrorStreak > 0) {
+            console.log(`[agent] ${ts()} Channel "${channelName}": ${status} — recovered after ${channelErrorStreak} failed attempt(s)`);
+          } else {
+            console.log(`[agent] ${ts()} Channel "${channelName}": ${status}`);
+          }
+          channelErrorStreak = 0;
+          return;
+        }
+        channelErrorStreak += 1;
+        console.warn(`[agent] ${ts()} Channel "${channelName}": ${status} (attempt ${channelErrorStreak}/5)`);
+        if (channelErrorStreak > 5) {
+          console.error(`[agent] ${ts()} Channel "${channelName}" failed ${channelErrorStreak} times in a row — giving up until the next scheduled token refresh (every 10min)`);
+          return;
+        }
+        try {
+          await refreshToken(`channel ${status}`);
+          await new Promise((r) => setTimeout(r, 2_000));
+          console.log(`[agent] ${ts()} Resubscribing to channel "${channelName}" (attempt ${channelErrorStreak}/5)...`);
+          subscribeChannel();
+        } catch (err) {
+          console.error(`[agent] ${ts()} Token refresh after channel error failed, will not resubscribe this round:`, err);
+        }
+      },
+    );
+  };
+  subscribeChannel();
 
-  setInterval(async () => {
-    try {
-      realtimeToken = await retryOn401('getRealtimeToken (refresh)', () => getRealtimeToken(cfg));
-      await realtime.setAuth(realtimeToken);
-      console.log('[agent] Token refreshed');
-    } catch (err) {
-      console.error('[agent] Token refresh failed:', err);
-    }
+  setInterval(() => {
+    refreshToken('scheduled 10min refresh').catch((err) => console.error(`[agent] ${ts()} Scheduled token refresh failed:`, err));
   }, 10 * 60 * 1000);
 
+  let lastPingFailed = false;
   const ping = async () => {
     try {
       const res = await fetch(`${cfg.baseUrl}/api/agent-alive`, {
@@ -297,9 +366,19 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', queueAllSt
         body: JSON.stringify({ token: cfg.token, board_id: cfg.boardId, agent_type: agentType, agent_id: cfg.agentId }),
         signal: AbortSignal.timeout(10_000),
       });
-      if (!res.ok) console.error(`[agent] Ping failed: ${res.status} ${await res.text().catch(() => '')}`);
+      if (!res.ok) {
+        console.error(`[agent] ${ts()} Ping failed: ${res.status} ${await res.text().catch(() => '')}`);
+        lastPingFailed = true;
+        if (res.status === 401) {
+          await refreshToken('ping-401').catch((err) => console.error(`[agent] ${ts()} Token refresh after 401 ping failed:`, err));
+        }
+        return;
+      }
+      if (lastPingFailed) console.log(`[agent] ${ts()} Ping recovered`);
+      lastPingFailed = false;
     } catch (err) {
-      console.error('[agent] Ping error:', err);
+      console.error(`[agent] ${ts()} Ping error:`, err);
+      lastPingFailed = true;
     }
   };
   await ping();
@@ -354,10 +433,13 @@ async function runWithRetry(label, fn) {
   }
 }
 
-async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice) {
+async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false) {
   const promptFile = join(kitDir, 'lib', 'prompt.md');
   const backendPromptFile = join(kitDir, 'lib', 'backend-prompt.md');
-  const credentialed = hasCredentials(cfg);
+  // --local must mean zero board contact even when .eventmodelers/config.json
+  // happens to hold valid credentials — never let a locally-present token flip
+  // this back on.
+  const credentialed = !localOnly && hasCredentials(cfg);
   let lastIdleCtx;
 
   while (true) {
@@ -410,7 +492,7 @@ export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice, a
   // reaches out to the platform at all.
   if (localOnly || !hasCredentials(local)) {
     console.log(`         mode: local-only (no platform sync)${localOnly ? ' — forced by --local' : ''}\n`);
-    await ralphLoop(kitDir, local, onTask, onPlannedSlice);
+    await ralphLoop(kitDir, local, onTask, onPlannedSlice, localOnly);
     return;
   }
 

package/shared/build-kit/lib/util/find-slice.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+// Shared by checks that need to cross-reference code against the slice's own
+// definition. Not a check itself — no `run(ctx)` interface here.
+
+const fs = require('fs');
+const path = require('path');
+
+function normalize(s) {
+  return String(s || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+// Given the {context}/{SliceName} folder names used under src/slices/, find the
+// matching slice.json under .build-kit/.slices/<contextSlug>/<sliceFolder>/. The
+// two sides are slugified differently (see shared/skills/load-slice/SKILL.md —
+// contextSlug is hyphenated, sliceFolder strips all spaces), so this matches on
+// a normalized (lowercase, alphanumeric-only) form instead of exact equality.
+// Returns null — never throws — when zero or more than one candidate matches;
+// callers should treat that as "can't verify" and skip rather than block.
+function findSliceJson(repoRoot, context, sliceName) {
+  const root = path.join(repoRoot, '.build-kit', '.slices');
+  if (!fs.existsSync(root)) return null;
+
+  const wantSlice = normalize(sliceName);
+  const candidates = [];
+
+  let contextDirs;
+  try {
+    contextDirs = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const contextDir of contextDirs) {
+    if (!contextDir.isDirectory()) continue;
+    const contextPath = path.join(root, contextDir.name);
+    let sliceDirs;
+    try {
+      sliceDirs = fs.readdirSync(contextPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const sliceDir of sliceDirs) {
+      if (!sliceDir.isDirectory()) continue;
+      if (normalize(sliceDir.name) !== wantSlice) continue;
+      const slicePath = path.join(contextPath, sliceDir.name, 'slice.json');
+      if (fs.existsSync(slicePath)) candidates.push(slicePath);
+    }
+  }
+
+  if (candidates.length !== 1) return null;
+  try {
+    return JSON.parse(fs.readFileSync(candidates[0], 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { findSliceJson, normalize };

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

@@ -11,7 +11,11 @@ const kitDir = dirname(fileURLToPath(import.meta.url));
 const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir, '..');
 
 const cfg = loadLocalConfig(kitDir);
-const inlineHeader = cfg.boardId
+const localOnly = process.env.RALPH_LOCAL === '1';
+// --local must mean zero board contact — never hand Claude live board
+// credentials via the inline header, even if config.json has them, or it'll
+// treat them as already-connected and skip straight to board sync.
+const inlineHeader = !localOnly && cfg.boardId
   ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
   : '';
 
@@ -96,7 +100,7 @@ startRalph({
   projectDir,
   onTask: runClaude,
   onPlannedSlice: runClaude,
-  localOnly: process.env.RALPH_LOCAL === '1',
+  localOnly,
 }).catch((err) => {
   console.error('[ralph] Fatal:', err);
   process.exit(1);