@eventmodelers/cli 1.0.163 → 2.0.2

package/lib/adapters/spec-kitty-adapter.js

@@ -14,11 +14,8 @@
 // adapter's whole job is producing a good brief and calling `intake`, nothing
 // more.
 //
-// Lives here (not only inside a bridge-kit install) so it has exactly one
-// entry point regardless of caller: `eventmodelers fetch --spec-kitty` calls
-// it directly for a one-shot sync; `eventmodelers bridge` (via
-// ralph-static.js) calls the same run() from a copy the bridge-kit installer
-// places at .bridge-kit/adapters/ — see installStack in cli.js.
+// Its one entry point is `eventmodelers fetch --spec-kitty`, a one-shot sync. (A standing bridge loop that
+// ran the same run() from a copy in .bridge-kit/ is retired.)
 //
 // Exports run({ cfg, projectDir, contextName }).
 
@@ -43,8 +40,7 @@ function slugify(text) {
 
 // Mirrors lib/fetch.js's per-context call rather than importing runFetch
 // directly — this fetches raw JSON only, it never touches .slices/ (fetch.js
-// owns writing that), and a copy of this file also has to run standalone
-// inside an installed .bridge-kit/ with no access to lib/fetch.js at all.
+// owns writing that).
 async function fetchFullSliceData(cfg, contextName) {
   const baseUrl = cfg.baseUrl || DEFAULT_BASE_URL;
   const url = `${baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata?contextName=${encodeURIComponent(contextName)}`;

package/lib/build-kits.js

@@ -0,0 +1,23 @@
+// Where the build kits of a project live: the root and up to two directory levels below it, so `run --all` finds
+// both kits of a scaffolded app (root and web/) whether it is started in the app or in the folder holding it.
+// Hidden directories and node_modules are not searched.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MAX_DEPTH = 2;
+
+export function findBuildKitDirs(root, kitDirNames) {
+  const has = (dir) => kitDirNames.some((name) => existsSync(join(dir, name)));
+  const found = [];
+  const visit = (dir, depth) => {
+    if (has(dir)) found.push(dir);
+    if (depth === MAX_DEPTH) return;
+    const children = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+      .map((e) => join(dir, e.name))
+      .sort();
+    for (const child of children) visit(child, depth + 1);
+  };
+  visit(root, 0);
+  return found;
+}

package/lib/global-agent-id.js

@@ -0,0 +1,45 @@
+// A run on the global install keeps one agent id per board and repo — "repo" being the directory the run is
+// started in (its git root, or the directory itself outside git). It is the same agent on every start: its chat
+// sessions, its star on the board and the prompts it holds all stay addressed to it. The ids live in one small
+// file next to the per-board credentials; nothing is written into the repo.
+
+import { execFileSync } from 'child_process';
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { dirname } from 'path';
+
+function real(path) {
+  try { return realpathSync(path); } catch { return path; }
+}
+
+// The git root of `dir`, else `dir` — both with symlinks resolved, so two paths to one repo are one repo.
+export function repoKey(dir) {
+  const start = real(dir);
+  try {
+    const top = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: start, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return top ? real(top) : start;
+  } catch {
+    return start;
+  }
+}
+
+function readIds(file) {
+  try {
+    const ids = JSON.parse(readFileSync(file, 'utf-8'));
+    return ids && typeof ids === 'object' && !Array.isArray(ids) ? ids : {};
+  } catch {
+    return {};
+  }
+}
+
+export function stableGlobalAgentId({ file, boardId, dir, mint = randomUUID }) {
+  const key = `${boardId}|${repoKey(dir)}`;
+  const ids = readIds(file);
+  if (typeof ids[key] === 'string' && ids[key]) return ids[key];
+  const id = mint();
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ ...ids, [key]: id }, null, 2), 'utf-8');
+  renameSync(tmp, file);
+  return id;
+}

package/lib/modeling-local-ai.js

@@ -2,7 +2,7 @@
 //
 // The build kit's own local runner (shared/build-kit/lib/local-ai-agent.js) is a
 // template copied into user projects, so it owns its whole lifecycle: it reads
-// config.json off disk, pulls one task out of tasks.json and exits. This one is the
+// config.json off disk, pulls one task off the queue and exits. This one is the
 // same idea mounted the other way round — the modeling loop already owns the prompt
 // queue, the standalone board-change lane and the idle review, and only ever needed
 // something to hand a turn's text to. So this exports a runner with one method,
@@ -175,7 +175,7 @@ function systemPrompt({ boardId, organizationId, standalone }) {
   ].join('\n');
 }
 
-export function createModelingLocalAiRunner({ cfg, target, log, verbose = false, standalone = false }) {
+export function createModelingLocalAiRunner({ cfg, target, log, verbose = false, standalone = false, onToolUse = () => () => {} }) {
   const t = resolveLocalAiTarget({ target, localAi: cfg.localAi || {} });
   let tools = null; // the MCP tool set, fetched once per session
 
@@ -269,6 +269,7 @@ export function createModelingLocalAiRunner({ cfg, target, log, verbose = false,
           : rawArgs;
 
         log(verbose ? `→ ${name}(${JSON.stringify(args).slice(0, 120)})` : `→ ${name}`);
+        const finish = onToolUse(name, args);
 
         let toolResult;
         try {
@@ -276,6 +277,7 @@ export function createModelingLocalAiRunner({ cfg, target, log, verbose = false,
         } catch (err) {
           toolResult = { isError: true, content: [{ type: 'text', text: err.message }] };
         }
+        finish({ isError: !!toolResult.isError });
         if (verbose) log(`  ${JSON.stringify(toolResult).slice(0, 160)}`);
 
         messages.push({

package/lib/scaffold-model.js

@@ -0,0 +1,71 @@
+// Builds the `model.json` the scaffold generators read, from the board's REST API.
+// `api` is `{ get(path), post(path, body) }` rooted at /api/org/:orgId/boards/:boardId, so this
+// stays testable without a server.
+
+const SCREEN_BATCH = 20;
+// Class names that only a Bulma mockup uses; any one in a screen's HTML means the screen is Bulma.
+const BULMA_CLASS = /class="[^"]*\b(navbar|is-primary|modal-card|columns|box)\b/;
+
+// A route is only taken when the screen's description states one ("route /orders/:orderId").
+export function routeFrom(description) {
+  const m = /\broute\s+(\/[^\s,;)]*)/i.exec(description ?? '');
+  return m ? m[1].replace(/[.]+$/, '') : undefined;
+}
+
+export function isHomeScreen(description) {
+  return /\bhome\s*page\b|\b(?:page|screen)\s+(?:shown\s+)?after\s+sign-?\s?in\b|\bshown\s+after\s+sign-?\s?in\b/i.test(description ?? '');
+}
+
+const descriptionOf = (node) => node.description ?? node.meta?.description ?? node.data?.description ?? '';
+
+export async function buildModel({ api, appTitle }) {
+  const { chapters = [] } = await api.get('/chapters/bounds');
+  const timelines = chapters.filter((c) => c.title).map(({ title, x, y }) => ({ title, x, y }));
+
+  // Timelines of one context return the same slices, so slices are keyed by id.
+  const slicesById = new Map();
+  for (const t of timelines) {
+    const { slices = [] } = await api.get(`/slicedata?contextName=${encodeURIComponent(t.title)}&projection=outline`);
+    for (const s of slices) {
+      if (s.title && !slicesById.has(s.id ?? s.title)) slicesById.set(s.id ?? s.title, s);
+    }
+  }
+
+  // One screen node id per distinct screen title is enough to read route, home flag and CSS.
+  const screenIdByTitle = new Map();
+  for (const s of slicesById.values()) {
+    for (const screen of s.screens ?? []) {
+      if (screen?.title && screen.id && !screenIdByTitle.has(screen.title)) screenIdByTitle.set(screen.title, screen.id);
+    }
+  }
+  const titleById = new Map([...screenIdByTitle].map(([title, id]) => [id, title]));
+  const ids = [...screenIdByTitle.values()];
+  const screens = [];
+  let bulma = false;
+  for (let i = 0; i < ids.length; i += SCREEN_BATCH) {
+    const nodes = await api.post('/nodes/query', { ids: ids.slice(i, i + SCREEN_BATCH) });
+    for (const node of nodes) {
+      const title = titleById.get(node.id);
+      if (!title) continue;
+      const description = descriptionOf(node);
+      const route = routeFrom(description);
+      const home = isHomeScreen(description);
+      screens.push({ title, ...(route ? { route } : {}), ...(home ? { home: true } : {}) });
+      const pages = Array.isArray(node.meta?.pages) ? node.meta.pages : [];
+      if (pages.some((html) => typeof html === 'string' && BULMA_CLASS.test(html))) bulma = true;
+    }
+  }
+
+  return {
+    appTitle: appTitle || 'App',
+    css: bulma ? 'bulma' : 'none',
+    timelines,
+    slices: [...slicesById.values()].map((s) => ({
+      title: s.title,
+      sliceType: s.sliceType,
+      chapter: s.chapter || s.context,
+      screens: (s.screens ?? []).map((sc) => sc.title).filter(Boolean),
+    })),
+    screens,
+  };
+}

package/lib/scaffold.js

@@ -0,0 +1,224 @@
+// `eventmodelers scaffold`: turns a board into a runnable app skeleton the build kits then add
+// slices to. A scaffold *type* names the kits it installs, the tools its app needs and the
+// generator that writes the skeleton around them — adding a type (e.g. a Java one) is adding an
+// entry to SCAFFOLD_TYPES plus a generator under shared/scaffold/<type>/.
+//
+// The skeleton generators are adapted from the em-scaffold skill by Adrian Mowat (MIT,
+// shared/scaffold/LICENSE-em-scaffold).
+import { execFileSync } from 'node:child_process';
+import { createServer } from 'node:net';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const SCAFFOLD_DIR = join(here, '..', 'shared', 'scaffold');
+
+export const SCAFFOLD_TYPES = {
+  supabase: {
+    label: 'Supabase backend + React front end (runs supabase + supabase-react)',
+    // Installed in order; `dir` is relative to the target.
+    kits: [
+      { stack: 'supabase', dir: '.' },
+      { stack: 'supabase-react', dir: 'web' },
+    ],
+    generator: join(SCAFFOLD_DIR, 'supabase', 'generate.mjs'),
+    tools: [
+      { command: 'docker', name: 'Docker' },
+      { command: 'supabase', name: 'Supabase CLI' },
+      { command: 'flyway', name: 'Flyway' },
+      { command: 'java', name: 'Java (Flyway runtime)' },
+    ],
+    minNode: 22,
+    // Command (run in the app root) that adds a sign-in user; omit it for a type without sign-in — `scaffold add-user` is then a no-op.
+    addUser: { requires: 'scripts/create-user.mjs', command: (email, password) => [process.execPath, 'scripts/create-user.mjs', email, password] },
+    // Run in the target after the generator; the first failure stops the run.
+    installSteps: [
+      ['npm', 'install'],
+      ['npm', '--prefix', 'web', 'install'],
+    ],
+    checkSteps: [
+      ['npx', 'tsc', '--noEmit'],
+      ['npx', 'tsx', '--test', 'src/common/notImplemented.test.ts'],
+      ['npm', '--prefix', 'web', 'run', 'build'],
+      ['npm', '--prefix', 'web', 'run', 'lint'],
+    ],
+    // One entry per port the generator takes. `flag` is passed to it with the picked value, `saved` is the
+    // key it writes to skeleton.json (so a refresh keeps its ports), `occupies` lists every TCP port the value
+    // needs free (default: itself), `render` turns it into the flag's value. A Supabase prefix NNN owns
+    // NNN20..NNN29 and can't go above 654.
+    ports: [
+      { name: 'api', flag: '--api-port', saved: 'apiPort', start: 3100 },
+      { name: 'web', flag: '--web-port', saved: 'webPort', start: 5273 },
+      { name: 'db', flag: '--db-port-prefix', saved: 'dbPortPrefix', start: 564, limit: 654,
+        occupies: (n) => Array.from({ length: 10 }, (_, i) => n * 100 + 20 + i) },
+    ],
+  },
+};
+
+const walkFiles = (dir) => readdirSync(dir).flatMap((n) => (statSync(join(dir, n)).isDirectory() ? walkFiles(join(dir, n)) : [join(dir, n)]));
+
+// The type's built-in templates as template path (the path they generate, always '/') -> source file.
+export function builtInTemplates(type) {
+  const dir = join(dirname(type.generator), 'template');
+  return new Map(walkFiles(dir).sort().map((file) => [relative(dir, file).split(sep).join('/').replace(/\.tmpl$/, ''), file]));
+}
+
+// Copies built-in templates into `dest` so they can be edited there; the generator then uses what is in `dest`
+// and falls back to the built-in template for everything else. `only` limits it to paths (a file, or a folder
+// prefix); an existing file is kept unless `force`.
+export function initTemplates(type, dest, { only = [], force = false } = {}) {
+  const all = builtInTemplates(type);
+  const wanted = only.map((p) => p.replace(/\\/g, '/').replace(/\.tmpl$/, '').replace(/\/+$/, ''));
+  const unknown = wanted.filter((p) => ![...all.keys()].some((rel) => rel === p || rel.startsWith(`${p}/`)));
+  if (unknown.length) throw new Error(`no built-in template at ${unknown.map((p) => `"${p}"`).join(', ')} — \`init-templates --list\` shows them`);
+  const copied = [];
+  const kept = [];
+  for (const [rel, file] of all) {
+    if (wanted.length && !wanted.some((p) => rel === p || rel.startsWith(`${p}/`))) continue;
+    const out = join(dest, `${rel}.tmpl`);
+    if (existsSync(out) && !force) { kept.push(rel); continue; }
+    mkdirSync(dirname(out), { recursive: true });
+    copyFileSync(file, out);
+    copied.push(rel);
+  }
+  return { copied, kept };
+}
+
+export function scaffoldTypeNames() {
+  return Object.keys(SCAFFOLD_TYPES);
+}
+
+// How to start `file` on this platform. On Windows npm and npx are .cmd shims that only start through a
+// shell (Node refuses to spawn them directly), so they get one; everything else is a plain executable.
+export function invocation(file, args, platform = process.platform) {
+  const shimmed = platform === 'win32' && ['npm', 'npx'].includes(file);
+  return shimmed ? { file: [file, ...args].join(' '), args: [], shell: true } : { file, args, shell: false };
+}
+
+// The command that answers "is `command` on the PATH": `where` on Windows (it honours PATHEXT), `command -v` elsewhere.
+export function probe(command, platform = process.platform) {
+  return platform === 'win32' ? { file: 'where', args: [command] } : { file: 'sh', args: ['-c', `command -v ${command}`] };
+}
+
+export function hasCommand(command) {
+  const { file, args } = probe(command);
+  try {
+    execFileSync(file, args, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// What the type needs that this machine lacks, as printable names. Node is checked by version.
+export function missingPrerequisites(type, { nodeVersion = process.versions.node, has = hasCommand } = {}) {
+  const missing = [];
+  if (Number(nodeVersion.split('.')[0]) < type.minNode) missing.push(`Node ${type.minNode} or newer (found ${nodeVersion})`);
+  for (const tool of type.tools) if (!has(tool.command)) missing.push(tool.name);
+  return missing;
+}
+
+// Free means nothing listens on any interface, which is what a Docker-published port looks like too.
+export function isPortFree(port) {
+  return new Promise((done) => {
+    const server = createServer();
+    server.once('error', () => done(false));
+    server.listen(port, () => server.close(() => done(true)));
+  });
+}
+
+// The first value from the spec's start whose ports are all free, one spec at a time. Specs picked in the
+// same run don't share ports as long as their ranges differ, which they do for every type so far.
+export async function pickPorts(specs, { free = isPortFree } = {}) {
+  const picked = {};
+  for (const spec of specs) {
+    const occupies = spec.occupies ?? ((n) => [n]);
+    const limit = spec.limit ?? spec.start + 100;
+    let value = spec.start;
+    while (value <= limit && !(await Promise.all(occupies(value).map(free))).every(Boolean)) value++;
+    if (value > limit) throw new Error(`no free "${spec.name}" port from ${spec.start} up to ${limit}`);
+    picked[spec.name] = String(value);
+  }
+  return picked;
+}
+
+// An empty/new directory or an earlier skeleton (has skeleton.json) is fair game; anything else is not ours.
+export function targetState(target) {
+  if (!existsSync(target)) return 'new';
+  if (existsSync(join(target, 'skeleton.json'))) return 'skeleton';
+  return readdirSync(target).length === 0 ? 'new' : 'foreign';
+}
+
+function run(file, args, { cwd, env, quiet = false } = {}) {
+  const inv = invocation(file, args);
+  execFileSync(inv.file, inv.args, { cwd, env: { ...process.env, ...env }, stdio: quiet ? 'ignore' : 'inherit', shell: inv.shell });
+}
+
+// cfg: { token, organizationId, boardId, baseUrl }. Credentials reach the child installers through
+// EVENTMODELERS_* env vars so the token never shows up in a process list.
+// templates: a folder of *.tmpl files overriding the type's built-in templates; when omitted, `<target>/templates`
+// is used if it exists, so a project's customisations survive every refresh.
+export async function runScaffold({ typeName, target, cfg, model, cliPath, install = true, check = true, templates, ports: portOverrides = {}, log = console.log }) {
+  const type = SCAFFOLD_TYPES[typeName];
+  const root = resolve(target);
+  const state = targetState(root);
+  if (state === 'foreign') {
+    throw new Error(`${root} is not empty and is not a scaffolded skeleton — pass an empty or new directory`);
+  }
+
+  const unknown = Object.keys(portOverrides).filter((n) => !type.ports.some((p) => p.name === n));
+  if (unknown.length) {
+    throw new Error(`unknown port ${unknown.map((n) => `"${n}"`).join(', ')} for type ${typeName} (it has: ${type.ports.map((p) => p.name).join(', ')})`);
+  }
+  // A refresh keeps the ports the skeleton already runs on; only a new one picks free ports.
+  const previous = state === 'skeleton' ? JSON.parse(readFileSync(join(root, 'skeleton.json'), 'utf8')) : {};
+  const pending = type.ports.filter((p) => previous[p.saved] === undefined && portOverrides[p.name] === undefined);
+  const picked = await pickPorts(pending);
+  const ports = Object.fromEntries(type.ports.map((p) => [p.name, String(portOverrides[p.name] ?? previous[p.saved] ?? picked[p.name])]));
+
+  for (const kit of type.kits) mkdirSync(join(root, kit.dir), { recursive: true });
+  if (!existsSync(join(root, '.git'))) run('git', ['init', '-q'], { cwd: root });
+
+  const env = {
+    EVENTMODELERS_TOKEN: cfg.token,
+    EVENTMODELERS_ORGANIZATION_ID: cfg.organizationId,
+    EVENTMODELERS_BOARD_ID: cfg.boardId,
+    ...(cfg.baseUrl ? { EVENTMODELERS_BASE_URL: cfg.baseUrl } : {}),
+  };
+  for (const kit of type.kits) {
+    const cwd = join(root, kit.dir);
+    if (existsSync(join(cwd, '.build-kit'))) {
+      log(`▶ ${kit.stack}: already installed in ${kit.dir}, skipping`);
+      continue;
+    }
+    log(`▶ Installing the ${kit.stack} kit in ${kit.dir}`);
+    run(process.execPath, [cliPath, 'init', '--stack', kit.stack, '--print'], { cwd, env });
+  }
+
+  // Next to the target, not in it: the model is an input of the skeleton, not a project file.
+  const modelFile = `${root}.model.json`;
+  writeFileSync(modelFile, JSON.stringify(model, null, 2) + '\n');
+  const templatesDir = templates ? resolve(templates) : existsSync(join(root, 'templates')) ? join(root, 'templates') : null;
+  if (templates && !existsSync(templatesDir)) throw new Error(`--templates ${templatesDir} does not exist`);
+  log(`▶ Generating the skeleton (model: ${modelFile}${templatesDir ? `, templates: ${templatesDir}` : ''})`);
+  run(process.execPath, [
+    type.generator, '--model', modelFile, '--target', root,
+    ...type.ports.flatMap((p) => [p.flag, ports[p.name]]),
+    ...(templatesDir ? ['--templates', templatesDir] : []),
+  ]);
+
+  if (install) {
+    for (const [file, ...args] of type.installSteps) run(file, args, { cwd: root });
+    if (check) {
+      for (const [file, ...args] of type.checkSteps) run(file, args, { cwd: root });
+    }
+    try {
+      run('git', ['add', '-A'], { cwd: root });
+      run('git', ['commit', '-q', '-m', 'chore: app skeleton from the event model'], { cwd: root });
+    } catch {
+      log('ℹ️  Nothing to commit (or git refused) — commit the skeleton yourself.');
+    }
+  }
+  return { root, ports, modelFile };
+}

package/lib/supervise.js

@@ -0,0 +1,60 @@
+// Runs several long-lived processes side by side in one terminal: output prefixed with the process name,
+// Ctrl+c (or any one of them exiting) stops all of them, children included.
+import { spawn, spawnSync } from 'node:child_process';
+import { invocation } from './scaffold.js';
+
+// Stops a process and everything it started. POSIX: the child leads its own process group, so one signal
+// reaches the tree. Windows has no groups, taskkill walks the tree instead.
+export function killTree(pid, signal = 'SIGINT', platform = process.platform) {
+  if (platform === 'win32') spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+  else try { process.kill(-pid, signal); } catch {}
+}
+
+// specs: [{ name, file, args, cwd }]. Resolves with the exit code once everything has stopped.
+export function supervise(specs, { log = console.log, graceMs = 3000, handleSignals = true } = {}) {
+  const width = Math.max(...specs.map((s) => s.name.length));
+  return new Promise((done) => {
+    let stopping = false;
+    let exitCode = 0;
+    let running = specs.length;
+    const children = [];
+
+    const finish = () => done(exitCode);
+    const stop = (code = 0) => {
+      if (stopping) return;
+      stopping = true;
+      exitCode = code;
+      for (const child of children) if (child.exitCode === null) killTree(child.pid);
+      setTimeout(finish, graceMs).unref();
+    };
+
+    for (const spec of specs) {
+      const inv = invocation(spec.file, spec.args);
+      // POSIX: detached makes the child its own group leader (see killTree). Windows: it would open a console window.
+      const child = spawn(inv.file, inv.args, { cwd: spec.cwd, shell: inv.shell, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+      children.push(child);
+      for (const out of [child.stdout, child.stderr]) {
+        let rest = '';
+        out.on('data', (chunk) => {
+          const lines = (rest + chunk).split('\n');
+          rest = lines.pop();
+          for (const line of lines) log(`${spec.name.padEnd(width)} | ${line}`);
+        });
+      }
+      child.on('error', (err) => {
+        log(`${spec.name.padEnd(width)} | failed to start: ${err.message}`);
+        stop(1);
+      });
+      child.on('exit', (code) => {
+        if (!stopping) log(`${spec.name.padEnd(width)} | exited (${code}), stopping the rest`);
+        stop(code ?? 0);
+        if (--running === 0) finish();
+      });
+    }
+
+    if (handleSignals) {
+      process.once('SIGINT', () => stop());
+      process.once('SIGTERM', () => stop());
+    }
+  });
+}

package/lib/ui-baseline.js

@@ -0,0 +1,123 @@
+// Decides whether a slice's UI needs work: a hash of what the board says about the UI (the screen nodes'
+// node hash, the user's `codeGen.uiPrompts`) is recorded after each
+// successful UI build, and compared on the next one. Only a difference sends the agent back to the UI.
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+export const BASELINE_FILE = 'ui-baseline.json';
+
+const sha = (value) => createHash('sha256').update(stable(value)).digest('hex').slice(0, 16);
+
+// JSON with sorted keys, so key order on the board never reads as a change.
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stable(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+const readJson = (path) => {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+};
+
+// The slice's folder under `.slices/`, found by id or (case-insensitive) title.
+export function findSliceDir(kitDir, idOrTitle) {
+  const slicesDir = join(kitDir, '.slices');
+  if (!existsSync(slicesDir)) return null;
+  const wanted = String(idOrTitle).trim().toLowerCase();
+  for (const ctx of readdirSync(slicesDir, { withFileTypes: true })) {
+    if (!ctx.isDirectory()) continue;
+    for (const dir of readdirSync(join(slicesDir, ctx.name), { withFileTypes: true })) {
+      if (!dir.isDirectory()) continue;
+      const path = join(slicesDir, ctx.name, dir.name);
+      const slice = readJson(join(path, 'slice.json'));
+      if (slice && (slice.id === idOrTitle || slice.title?.toLowerCase() === wanted)) return { path, slice };
+    }
+  }
+  return null;
+}
+
+// Lists of the slice that are not board elements (or are hashed on their own).
+const NOT_ELEMENTS = new Set(['screens', 'comments', 'screenImages']);
+const BATCH = 50;
+
+// `fetchNodes(ids)` -> the board's nodes for those ids (POST /nodes/query).
+// The board stamps every node with a `hash`; use it as is. Content hash only as a fallback, for a board
+// (or a /nodes/query) that does not return it.
+// scope 'backend' (a kit that builds no UI) leaves out the screens and the UI prompts: a screen edit must not
+// make it rebuild.
+export async function fingerprint({ slice, fetchNodes, scope = 'ui' }) {
+  const ui = scope !== 'backend';
+  const prompts = ui ? slice.codeGen?.uiPrompts ?? [] : [];
+  const screens = ui ? (slice.screens ?? []).filter((s) => s?.id) : [];
+  // Every element the slice carries — commands, events, read models, processors, tables, actors, aggregates,
+  // specifications, ... — so a new list the export grows is covered without touching this.
+  const elements = Object.entries(slice)
+    .filter(([k, v]) => !NOT_ELEMENTS.has(k) && Array.isArray(v))
+    .flatMap(([, v]) => v)
+    .filter((e) => e && typeof e === 'object' && e.id);
+  const ids = [...new Set([...screens, ...elements].map((e) => e.id))];
+  const byId = new Map();
+  for (let i = 0; i < ids.length; i += BATCH) {
+    for (const node of await fetchNodes(ids.slice(i, i + BATCH))) byId.set(node.id, node);
+  }
+  const missing = screens.filter((s) => !byId.has(s.id)).map((s) => s.title ?? s.id);
+  if (missing.length) throw new Error(`screen node(s) not found on the board: ${missing.join(', ')}`);
+  // One entry per node, so a later check can say *which* ones moved, not just that something did.
+  const entry = (kind) => (item) => {
+    const node = byId.get(item.id);
+    const base = { id: item.id, kind, title: item.title ?? node?.node?.data?.title ?? node?.data?.title ?? item.id };
+    if (!node) return { ...base, hash: 'missing' };
+    if (node.hash) return { ...base, hash: node.hash };
+    return { ...base, hash: sha({ content: node.meta ?? node.data ?? null, fields: item.fields ?? [] }) };
+  };
+  const screenNodes = screens.map(entry('screen'));
+  const elementNodes = Object.entries(slice)
+    .filter(([k, v]) => !NOT_ELEMENTS.has(k) && Array.isArray(v))
+    .flatMap(([k, v]) => v.filter((e) => e && typeof e === 'object' && e.id).map(entry(k)));
+  return {
+    screen: screenNodes.length ? sha(screenNodes.map((n) => [n.id, n.hash])) : null,
+    elements: elementNodes.length ? sha(elementNodes.map((n) => [n.id, n.hash])) : null,
+    prompts: sha(prompts),
+    promptList: prompts,
+    nodes: [...screenNodes, ...elementNodes],
+  };
+}
+
+export function readBaseline(sliceDir) {
+  return readJson(join(sliceDir, BASELINE_FILE));
+}
+
+export function writeBaseline(sliceDir, fp, scope = 'ui') {
+  const baseline = { scope, screenHash: fp.screen, elementsHash: fp.elements, uiPromptsHash: fp.prompts, uiPrompts: fp.promptList, nodes: fp.nodes, recordedAt: new Date().toISOString() };
+  writeFileSync(join(sliceDir, BASELINE_FILE), JSON.stringify(baseline, null, 2) + '\n');
+  return baseline;
+}
+
+// What differs node by node, against a baseline that recorded its nodes ({id, kind, title, hash}).
+function diffNodes(before, now) {
+  const was = new Map(before.map((n) => [n.id, n]));
+  const is = new Map(now.map((n) => [n.id, n]));
+  return {
+    changedNodes: now.filter((n) => was.has(n.id) && was.get(n.id).hash !== n.hash),
+    addedNodes: now.filter((n) => !was.has(n.id)),
+    removedNodes: before.filter((n) => !is.has(n.id)),
+  };
+}
+
+// Verdict: NO_BASELINE | UNCHANGED | CHANGED, with which parts changed, which nodes, and the prompts that are new.
+// A baseline from before elements/nodes were tracked has no elementsHash/nodes — that is not a change.
+export function compare(baseline, fp, scope = 'ui') {
+  const none = { changedNodes: [], addedNodes: [], removedNodes: [] };
+  // A baseline recorded under another scope says nothing about this one.
+  if (!baseline || (baseline.scope ?? 'ui') !== scope) return { verdict: 'NO_BASELINE', screenChanged: true, elementsChanged: true, promptsChanged: fp.promptList.length > 0, newPrompts: fp.promptList, ...none };
+  const screenChanged = baseline.screenHash !== fp.screen;
+  const elementsChanged = baseline.elementsHash !== undefined && baseline.elementsHash !== fp.elements;
+  const promptsChanged = baseline.uiPromptsHash !== fp.prompts;
+  const seen = new Set(baseline.uiPrompts ?? []);
+  const newPrompts = promptsChanged ? fp.promptList.filter((p) => !seen.has(p)) : [];
+  const nodes = Array.isArray(baseline.nodes) ? diffNodes(baseline.nodes, fp.nodes) : none;
+  return { verdict: screenChanged || elementsChanged || promptsChanged ? 'CHANGED' : 'UNCHANGED', screenChanged, elementsChanged, promptsChanged, newPrompts, ...nodes };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.163",
+  "version": "2.0.2",
   "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": {