@eventmodelers/cli 2.0.1 → 2.0.2

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": "2.0.1",
+  "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": {

package/shared/build-kit/lib/events-view.js

@@ -85,10 +85,23 @@ export function formatPayload(e) {
   return JSON.stringify(rest, null, 2).split('\n').map((l) => `    ${l}`).join('\n');
 }
 
+// The kit's first look at each slice: its first `board-observed` event. A fresh kit records every slice already on
+// the board this way, which says nothing happened — the ids to leave out of the default view of the log.
+export function baselineIds(events) {
+  const seen = new Set();
+  const ids = new Set();
+  for (const e of events) {
+    if (e.type !== 'board-observed' || !e.slice || seen.has(e.slice)) continue;
+    seen.add(e.slice);
+    ids.add(e.id);
+  }
+  return ids;
+}
+
 // types / slice (an id prefix or part of a title) / tag / board (an id prefix — a global kit's log mixes boards) narrow
-// the log; last keeps the final N that remain.
-export function filterEvents(events, { types, slice, tag, board, last } = {}, titles = {}) {
-  let out = events;
+// the log; omit is a set of event ids to leave out (see baselineIds); last keeps the final N that remain.
+export function filterEvents(events, { types, slice, tag, board, last, omit } = {}, titles = {}) {
+  let out = omit?.size ? events.filter((e) => !omit.has(e.id)) : events;
   if (board) out = out.filter((e) => String(e.meta?.board_id ?? '').toLowerCase().startsWith(board.toLowerCase()));
   if (types?.length) out = out.filter((e) => types.includes(e.type));
   if (slice) {

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

@@ -15,7 +15,7 @@ import { randomUUID } from 'crypto';
 import { createRealtimeAdapter, keepSubscribed } from './adapters/realtime-adapter.js';
 import { backoffMs, sleep } from './backoff.js';
 import { adoptAgentEdits, observeBoard, projectStatus, statusOf } from './slice-projection.js';
-import { fold } from './slice-state.js';
+import { fold, statusKey } from './slice-state.js';
 import { readEvents } from './slice-events.js';
 import { claimSlice, recordEvent, settleSlice, settleLeftoverClaims } from './slice-run.js';
 import { isTreeClean } from './slice-git.js';
@@ -273,8 +273,8 @@ export async function fetchAndPersistSlices(cfg, kitDir) {
   if (!activeCtx || !contexts[activeCtx]) {
     // First run (or the current context disappeared): seed with a context that
     // has planned work, else the first one. This is the ONLY place we choose it.
-    const pickup = readPickupStatus(kitDir).toLowerCase();
-    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => (s.status || '').toLowerCase() === pickup));
+    const pickup = statusKey(readPickupStatus(kitDir));
+    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => statusKey(s.status) === pickup));
     activeCtx = plannedCtx || Object.keys(contexts)[0] || 'default';
     writeFileSync(ctxPath, JSON.stringify({ name: activeCtx }, null, 2), 'utf-8');
   }
@@ -377,9 +377,9 @@ async function handleSliceChanged(payload, cfg, kitDir) {
   await fetchAndPersistSlices(cfg, kitDir).catch((err) =>
     console.error('[agent] Slice persist error:', err),
   );
-  // Slices in the kit's pickup status (Planned, or Handover for UI kits) are handled by
+  // Slices in the kit's pickup status (Planned, or Waiting for UI kits) are handled by
   // onPlannedSlice directly — no task needed.
-  if ((payload.sliceStatus || '').toLowerCase() !== readPickupStatus(kitDir).toLowerCase()) {
+  if (statusKey(payload.sliceStatus) !== statusKey(readPickupStatus(kitDir))) {
     try {
       queueTask({ kitDir, payload, meta: eventMeta(cfg) });
       console.log(`[agent] Task queued — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
@@ -490,15 +490,19 @@ async function startRealtimeAgent(cfg, kitDir, { agentType = 'BUILD', createAdap
 // ── Ralph loop ────────────────────────────────────────────────────────────────
 
 // The slice status this kit claims work from. A stack declares it in `lib/kit.json`
-// ({ "pickupStatus": "Handover" } for the UI kits, which build what a backend kit handed over);
+// ({ "pickupStatus": "Waiting" } for the UI kits, which build what a backend kit handed over);
 // absent means "Planned", the backend default. `run --status-trigger <status>` (RALPH_STATUS_TRIGGER)
 // overrides either for that run.
+// `Handover` was renamed `Waiting`; a kit.json or --status-trigger written before that still says it,
+// and a board served by an older platform still reports it.
+const canonicalStatus = (s) => (statusKey(s) === 'waiting' ? 'Waiting' : s);
+
 export function readPickupStatus(kitDir) {
   const override = (process.env.RALPH_STATUS_TRIGGER || '').trim();
-  if (override) return override;
+  if (override) return canonicalStatus(override);
   try {
     const s = JSON.parse(readFileSync(join(kitDir, 'lib', 'kit.json'), 'utf-8')).pickupStatus;
-    if (typeof s === 'string' && s.trim()) return s.trim();
+    if (typeof s === 'string' && s.trim()) return canonicalStatus(s.trim());
   } catch {}
   return 'Planned';
 }
@@ -533,14 +537,14 @@ function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
   try {
     others = readdirSync(slicesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
   } catch {}
-  const pickup = readPickupStatus(kitDir).toLowerCase();
+  const pickup = statusKey(readPickupStatus(kitDir));
   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) => (s.status || '').toLowerCase() === pickup && !skipIds.has(s.id));
+      const planned = slices && slices.find((s) => statusKey(s.status) === pickup && !skipIds.has(s.id));
       if (!planned) continue;
       if (ctx !== currentCtx) {
         writeFileSync(join(slicesDir, 'current_context.json'), JSON.stringify({ name: ctx }, null, 2), 'utf-8');
@@ -555,14 +559,14 @@ function getFirstPlannedSlice(kitDir, skipIds = new Set()) {
 // Ids of every slice currently waiting for pickup, across all contexts.
 function listPlannedIds(kitDir) {
   const slicesDir = join(kitDir, '.slices');
-  const pickup = readPickupStatus(kitDir).toLowerCase();
+  const pickup = statusKey(readPickupStatus(kitDir));
   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 ((s.status || '').toLowerCase() === pickup) ids.add(s.id);
+        for (const s of slices ?? []) if (statusKey(s.status) === pickup) ids.add(s.id);
       } catch {}
     }
   } catch {}
@@ -666,7 +670,7 @@ async function runWithRetry(label, fn) {
 // alone, the agent read it as background, answered "what would you like me to help with?" with
 // no tool calls, and a Planned slice stayed Planned until the stuck-slice guard blocked it. So
 // every turn ends with the concrete request — here, once, for every runner.
-// Whether a backend kit finishes UI-bearing slices at `Handover` instead of `Done`: this run's
+// Whether a backend kit finishes UI-bearing slices at `Waiting` instead of `Done`: this run's
 // `run --handover` (RALPH_HANDOVER) over the project's `handover` setting in config.json.
 export function resolveHandover(cfg) {
   return process.env.RALPH_HANDOVER === '1' || cfg?.handover === true;
@@ -720,8 +724,8 @@ function taskRequest(planned = null, cfg = null, pickupStatus = 'Planned', queue
     ? `build the ${pickupStatus} slice "${planned.title}" (id=${planned.id}, context="${planned.ctx}")`
     : `process this queued task (id=${queued?.id}) — the slice change that queued it: ${JSON.stringify(queued?.payload ?? {})}`;
   // Stated explicitly so the agent never has to work it out from config.json: this run's effective
-  // value, which is what the `ui-contract` skill (Step 4) follows. UI kits (pickup Handover) ignore it.
-  const handover = planned && pickupStatus.toLowerCase() !== 'handover' ? `\nHandover: ${resolveHandover(cfg) ? 'on' : 'off'}\n` : '';
+  // value, which is what the `ui-contract` skill (Step 4) follows. UI kits (pickup Waiting) ignore it.
+  const handover = planned && statusKey(pickupStatus) !== 'waiting' ? `\nHandover: ${resolveHandover(cfg) ? 'on' : 'off'}\n` : '';
   return `\n\n---\n\nYour task now: ${task}, following the instructions above. Start immediately.\n${handover}`;
 }
 

package/shared/build-kit/lib/slice-run.js

@@ -6,7 +6,7 @@
 // no board (--local): nothing is pushed or read, the log alone decides.
 
 import { appendEvent, readEvents } from './slice-events.js';
-import { fold, decideSettle, decideRecovery } from './slice-state.js';
+import { fold, decideSettle, decideRecovery, statusKey } from './slice-state.js';
 import { adoptAgentEdits, projectStatus } from './slice-projection.js';
 import { discardUnfinishedWork, gitBase } from './slice-git.js';
 
@@ -71,7 +71,7 @@ export async function claimSlice({ kitDir, planned, board, meta, cleanTree, pid
       console.error(`[ralph] Could not read the board before claiming "${planned.title}":`, err.message);
       return 'lost';
     }
-    if (current && current.toLowerCase() !== pickupStatus.toLowerCase()) {
+    if (current && statusKey(current) !== statusKey(pickupStatus)) {
       console.log(`[ralph] "${planned.title}" is ${current} on the board, not ${pickupStatus} — someone else got there first.`);
       recordEvent(kitDir, { type: 'board-observed', slice: planned.id, status: current }, meta);
       return 'lost';