@eventmodelers/cli 2.0.1 → 2.0.3

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.3",
   "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/build-log-share.js

@@ -0,0 +1,149 @@
+// A build agent shares its event log with the board — two capabilities, both build-agent only (a modeling
+// agent gets no-ops):
+//
+//   iterations  every slice build turn is an iteration: `iteration-started` / `iteration-closed` events in the
+//               log, each carrying the slice, the iteration id, the board, the org and the date — and a
+//               `slice-done` after an iteration that settled the slice as Done. Always on.
+//   sync        with --sync, the events that name a slice are uploaded to POST …/boards/:boardId/buildlog,
+//               numbered (the event's own `seq`, which defines the order) and tagged with the kit type (backend, or ui for a kit that picks up from Waiting) —
+//               constantly, on a short interval for as long as the loop runs, so a live dashboard follows the
+//               build, and once more at the start and end of each iteration.
+//
+// Best effort, like tracing: a cursor (the last event id sent) lives next to the log and only moves forward
+// when the upload succeeded, so a failed upload is simply sent again with the next one. The server holds one
+// iteration per slice and kit type — every `iteration-started` resets that log — and at most 1000 entries.
+
+import { randomUUID } from 'crypto';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { appendEvent, readEvents } from './slice-events.js';
+import { statusKey } from './slice-state.js';
+
+export const SYNC_STATE_FILE = 'build-log-sync.json';
+export const SYNC_INTERVAL_MS = 2_000;
+const NOOP = { iterationStarted: () => null, iterationClosed: () => {}, flush: async () => {}, start: () => {}, stop: () => {} };
+
+function readState(path) {
+  try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return {}; }
+}
+
+function writeState(path, state) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state), 'utf-8');
+  renameSync(tmp, path);
+}
+
+// The wire shape of one log event: the envelope the endpoint reads, everything else as payload.
+export function toBuildLogEntry(e, { agentId, iteration, boardId, organizationId, kitType, seq }) {
+  const { id, at, type, slice, meta: _meta, tags: _tags, ...rest } = e;
+  return { ...rest, id, type, sliceId: slice, agentId, iteration, occurredAt: at, boardId, organizationId, kitType, seq };
+}
+
+// A kit that picks slices up from Waiting builds the UI; any other builds the backend.
+export const kitTypeOf = (pickupStatus) => (String(pickupStatus ?? '').trim().toLowerCase() === 'waiting' ? 'ui' : 'backend');
+
+export function createBuildLogShare({ kitDir, cfg, meta, agentType = 'BUILD', kitType = 'backend', sync = false, enabled = true, intervalMs = SYNC_INTERVAL_MS, log = () => {} } = {}) {
+  if (agentType !== 'BUILD') return NOOP;
+  const statePath = join(kitDir, SYNC_STATE_FILE);
+  const canUpload = !!(sync && enabled && cfg?.baseUrl && cfg?.token && cfg?.organizationId && cfg?.boardId && cfg?.agentId);
+  const open = new Map(); // slice → the iteration in progress
+  let timer = null;
+  let inFlight = null;
+  let warned = false;
+
+  async function upload() {
+    const state = readState(statePath);
+    const events = readEvents(kitDir);
+    const from = state.cursor ? events.findIndex((e) => e.id === state.cursor) + 1 : 0; // a pruned cursor re-sends; the server drops duplicates
+    const fresh = events.slice(from);
+    if (!fresh.length) return;
+    const iterations = { ...(state.iterations ?? {}) };
+    const entries = [];
+    for (const e of fresh) {
+      if (!e.slice) continue;
+      if (e.type === 'iteration-started') iterations[e.slice] = e.iteration;
+      entries.push(toBuildLogEntry(e, { agentId: cfg.agentId, iteration: e.iteration ?? iterations[e.slice], boardId: cfg.boardId, organizationId: cfg.organizationId, kitType, seq: e.seq }));
+    }
+    if (entries.length) {
+      const res = await fetch(`${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/buildlog`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-agent-id': cfg.agentId },
+        body: JSON.stringify({ events: entries }),
+        signal: AbortSignal.timeout(15_000),
+      });
+      if (!res.ok) {
+        const reason = `HTTP ${res.status}${await res.text().then((t) => `: ${t}`).catch(() => '')}`;
+        // A batch the platform rejects as invalid can never succeed: skip it rather than resend it every interval.
+        if (res.status !== 400) throw new Error(reason);
+        log(`info: the platform did not take ${entries.length} build log entries (${reason}) — skipped`);
+      }
+    }
+    writeState(statePath, { cursor: fresh[fresh.length - 1].id, iterations });
+  }
+
+  // One upload at a time. A call that arrives while one runs asks for another pass right after it, so events
+  // appended in between are never left to wait for the interval.
+  let again = false;
+  function flush() {
+    if (!canUpload) return Promise.resolve();
+    if (inFlight) { again = true; return inFlight; }
+    inFlight = (async () => {
+      do {
+        again = false;
+        try { await upload(); warned = false; } catch (err) {
+          if (!warned) { warned = true; log(`info: build log upload failed (${err.message}) — will send it with the next one`); }
+          break;
+        }
+      } while (again);
+    })().finally(() => { inFlight = null; });
+    return inFlight;
+  }
+
+  return {
+    iterationStarted(planned) {
+      const iteration = randomUUID();
+      try {
+        appendEvent(kitDir, { type: 'iteration-started', slice: planned.id, iteration, title: planned.title, kitType, boardId: cfg?.boardId, organizationId: cfg?.organizationId }, meta);
+      } catch (err) {
+        log(`info: could not record the start of an iteration (${err.message}) — the build goes on`);
+        return null;
+      }
+      open.set(planned.id, iteration);
+      flush();
+      return iteration;
+    },
+    async iterationClosed(planned, status) {
+      const iteration = open.get(planned.id);
+      if (!iteration) return;
+      open.delete(planned.id);
+      try {
+        appendEvent(kitDir, { type: 'iteration-closed', slice: planned.id, iteration, status, kitType, boardId: cfg?.boardId, organizationId: cfg?.organizationId }, meta);
+      } catch (err) {
+        log(`info: could not record the end of an iteration (${err.message}) — the build goes on`);
+        return;
+      }
+      // The iteration that settled the slice as Done ends with `slice-done`; if it is the slice's newest entry when
+      // the next iteration starts, the platform knows the slice was reopened and starts its log over.
+      try {
+        const events = readEvents(kitDir);
+        const from = events.findLastIndex((e) => e.type === 'iteration-started' && e.iteration === iteration);
+        if (events.slice(from + 1).some((e) => e.type === 'settled' && e.slice === planned.id && statusKey(e.status) === 'done')) {
+          appendEvent(kitDir, { type: 'slice-done', slice: planned.id, iteration, kitType, boardId: cfg?.boardId, organizationId: cfg?.organizationId }, meta);
+        }
+      } catch (err) {
+        log(`info: could not record that the slice is done (${err.message}) — the build goes on`);
+      }
+      await flush();
+    },
+    flush,
+    start() {
+      if (!canUpload || timer) return;
+      timer = setInterval(flush, intervalMs);
+      timer.unref?.();
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      timer = null;
+    },
+  };
+}