@eventmodelers/cli 1.0.44 → 1.0.46

package/stacks/node/templates/build-kit/lib/check-commit-scope.cjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+// Runner for the slice commit-scope guard. Loads every check module from
+// ./checks/*.cjs and runs it against the currently staged changeset.
+//
+// Check interface (see ./checks/README.md for the full contract + a template):
+//   module.exports = {
+//     name: 'my-check',              // short id, shown in violation output
+//     skipIfAlreadyFailing: false,   // optional — skip this check once an earlier
+//                                    // one has already failed (use for slow checks)
+//     run(ctx) {
+//       return [{ path: 'some/file.ts', reason: 'why this is a problem' }];
+//     },
+//   };
+// `run()` returns an array of violations (empty array/undefined/null = pass).
+//
+// `ctx` passed to every check:
+//   changes        [{status, path}] — staged files (git status letter + path)
+//   touchesSlice    true — this commit touches src/slices/{context}/{slice}/**
+//                   (the runner already gates on this before loading checks)
+//   repoRoot        absolute path to the repo root
+//   SLICE_PATTERN   RegExp matching a path inside a slice's own folder
+//
+// Zero dependencies — plain Node, so it works from git's pre-commit hook
+// (see ../../.githooks/pre-commit), from `npm run check:scope`, or from CI.
+// Invoked as: node .build-kit/lib/check-commit-scope.cjs
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const SLICE_PATTERN = /^src\/slices\/[^/]+\/[^/]+\//;
+
+function stagedChanges() {
+  const out = execSync('git diff --cached --name-status --no-renames', { encoding: 'utf8' });
+  return out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [status, ...rest] = line.split('\t');
+      return { status: status[0], path: rest.join('\t') };
+    });
+}
+
+function loadChecks() {
+  const checksDir = path.join(__dirname, 'checks');
+  if (!fs.existsSync(checksDir)) return [];
+  return fs
+    .readdirSync(checksDir)
+    .filter((f) => f.endsWith('.cjs'))
+    .sort() // numeric filename prefixes (00-, 10-, ...) control run order
+    .map((f) => {
+      let mod;
+      try {
+        mod = require(path.join(checksDir, f));
+      } catch (err) {
+        console.error(`check-commit-scope: failed to load checks/${f} — ${err.message}`);
+        return null;
+      }
+      if (typeof mod?.run !== 'function') {
+        console.error(`check-commit-scope: skipping checks/${f} — does not export { name, run(ctx) }`);
+        return null;
+      }
+      return { file: f, name: mod.name || f, run: mod.run, skipIfAlreadyFailing: !!mod.skipIfAlreadyFailing };
+    })
+    .filter(Boolean);
+}
+
+function main() {
+  let changes;
+  try {
+    changes = stagedChanges();
+  } catch (err) {
+    console.error('check-commit-scope: could not read staged changes —', err.message);
+    process.exit(1);
+  }
+
+  if (changes.length === 0) process.exit(0);
+
+  const touchesSlice = changes.some((c) => SLICE_PATTERN.test(c.path));
+  if (!touchesSlice) process.exit(0); // not a slice commit — nothing to enforce
+
+  const ctx = {
+    changes,
+    touchesSlice,
+    repoRoot: execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim(),
+    SLICE_PATTERN,
+  };
+
+  const checks = loadChecks();
+  const violations = [];
+  const claimedPaths = new Set(); // first check to flag a path wins — avoids repeat noise
+
+  for (const check of checks) {
+    if (check.skipIfAlreadyFailing && violations.length > 0) continue;
+
+    let result;
+    try {
+      result = check.run(ctx) || [];
+    } catch (err) {
+      violations.push({ path: '(check error)', reason: `[${check.name}] threw: ${err.message}` });
+      continue;
+    }
+
+    for (const v of result) {
+      if (claimedPaths.has(v.path)) continue;
+      claimedPaths.add(v.path);
+      violations.push({ path: v.path, reason: `[${check.name}] ${v.reason}` });
+    }
+  }
+
+  if (violations.length > 0) {
+    console.error('\n❌ commit blocked — slice commit-scope guard found issues:\n');
+    for (const v of violations) console.error(`  - ${v.path} — ${v.reason}`);
+    console.error('\nSee .build-kit/lib/checks/ for what each check enforces.\n');
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+main();

package/stacks/node/templates/build-kit/lib/checks/00-blocked-paths.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+// Rejects a slice commit that touches shared infra which must never change from
+// slice work: the package manifest/lockfiles (no new/changed dependencies) and
+// server.ts (routes/processors are auto-discovered — never wired there by hand).
+
+const BLOCKED = [
+  {
+    pattern: /^(package(-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|npm-shrinkwrap\.json)$/,
+    reason: 'dependency/package manifest changes are not allowed from a slice commit',
+  },
+  {
+    pattern: /^server\.ts$/,
+    reason: 'server.ts is shared infra (routes/processors are auto-discovered) — never touched by slice work',
+  },
+];
+
+module.exports = {
+  name: 'blocked-paths',
+  run(ctx) {
+    const violations = [];
+    for (const { path: p } of ctx.changes) {
+      const hit = BLOCKED.find((b) => b.pattern.test(p));
+      if (hit) violations.push({ path: p, reason: hit.reason });
+    }
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/10-slice-scope.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Everything staged in a slice commit must be inside the slice's own folder, or
+// one of the documented shared-infra exceptions a slice legitimately registers
+// *into* (never rewrites wholesale). See build-kit/lib/AGENT.md and the
+// build-state-view/build-automation SKILL.md files for what a compliant edit to
+// an exception file looks like. Migration files have their own dedicated check
+// (20-append-only-migrations.cjs), so they're allowed through here.
+
+const ALLOWED_EXCEPTIONS = [
+  /^src\/slices\/[^/]+\/[A-Za-z0-9]+Events\.ts$/, // per-context event union (append-only)
+  /^src\/common\/loadPostgresEventstore\.ts$/, // projection registration / schema.migrate()
+];
+
+const MIGRATION_PATTERN = /^migrations\/V\d+__.*\.sql$/;
+
+module.exports = {
+  name: 'slice-scope',
+  run(ctx) {
+    const violations = [];
+    for (const { path: p } of ctx.changes) {
+      if (ctx.SLICE_PATTERN.test(p)) continue;
+      if (MIGRATION_PATTERN.test(p)) continue;
+      if (ALLOWED_EXCEPTIONS.some((r) => r.test(p))) continue;
+      violations.push({ path: p, reason: 'outside src/slices/{context}/{slice}/ and not a documented exception' });
+    }
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/20-append-only-migrations.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+// migrations/V{n}__*.sql may only be ADDED, never modified or deleted — migrations
+// are append-only; a fix belongs in a new migration, not an edit to an old one.
+
+const MIGRATION_PATTERN = /^migrations\/V\d+__.*\.sql$/;
+
+module.exports = {
+  name: 'append-only-migrations',
+  run(ctx) {
+    const violations = [];
+    for (const { status, path: p } of ctx.changes) {
+      if (!MIGRATION_PATTERN.test(p)) continue;
+      if (status !== 'A') {
+        violations.push({ path: p, reason: 'existing migrations are append-only; add a new V{n} file instead of editing this one' });
+      }
+    }
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/30-test-file-present.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+// A slice commit that adds/changes a command handler, projection, or processor
+// must also include a *.test.ts for that slice — catches the agent skipping the
+// matching build skill's test step (build-state-change Step 4 / build-state-view
+// Step 5 / build-automation's DeciderSpecification tests).
+
+const { execSync } = require('child_process');
+
+const IMPLEMENTATION_FILE = /^src\/slices\/([^/]+)\/([^/]+)\/(?:[A-Za-z0-9]+Command|[A-Za-z0-9]+Projection|processor(?:-[A-Za-z0-9]+)?)\.ts$/;
+
+module.exports = {
+  name: 'test-file-present',
+  run(ctx) {
+    const sliceDirs = new Set();
+    for (const { path: p } of ctx.changes) {
+      const m = IMPLEMENTATION_FILE.exec(p);
+      if (m) sliceDirs.add(`src/slices/${m[1]}/${m[2]}`);
+    }
+    if (sliceDirs.size === 0) return [];
+
+    let tracked = [];
+    try {
+      tracked = execSync('git ls-files -- src/slices', { cwd: ctx.repoRoot, encoding: 'utf8' })
+        .split('\n')
+        .filter(Boolean);
+    } catch {
+      // best-effort — fall through with whatever's staged
+    }
+    const known = new Set([...tracked, ...ctx.changes.map((c) => c.path)]);
+
+    const violations = [];
+    for (const dir of sliceDirs) {
+      const hasTest = [...known].some((f) => f.startsWith(`${dir}/`) && f.endsWith('.test.ts'));
+      if (!hasTest) {
+        violations.push({
+          path: dir,
+          reason: 'no *.test.ts found for this slice — command handlers/projections/processors need test coverage',
+        });
+      }
+    }
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/40-no-invented-fields.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+// Heuristic: flags a field name used in a slice's Command/ReadModel type literal
+// that doesn't appear anywhere in that slice's own slice.json. Not a real
+// TS/schema-aware check (no parser dependency) — it regex-extracts the fields
+// declared inside `Command<'Name', { ... }, ...>` and `type XReadModel = { ... }`
+// literals, so unusual formatting (nested object/array field types, nonstandard
+// generics) can slip past undetected. It only ever adds violations for fields it
+// is confident about; when slice.json can't be found/parsed for a slice, that
+// slice's files are skipped entirely rather than guessed at.
+
+const fs = require('fs');
+const path = require('path');
+const { findSliceJson, normalize } = require('../util/find-slice.cjs');
+
+const COMMON_ALLOWED = new Set(
+  ['id', 'userId', 'correlationId', 'causationId', 'streamName', 'type', 'data', 'metadata', 'createdAt', 'updatedAt', 'timestamp'].map(normalize),
+);
+
+const TYPE_LITERALS = [
+  /(?:Command|Event)<\s*'[^']+'\s*,\s*{([^}]*)}/g,
+  /type\s+[A-Za-z0-9_]+ReadModel\s*=\s*{([^}]*)}/g,
+];
+
+const FIELD_LINE = /^\s*([A-Za-z_][A-Za-z0-9_]*)\??\s*:/gm;
+
+function collectDeclaredFields(node, out) {
+  if (Array.isArray(node)) {
+    for (const item of node) collectDeclaredFields(item, out);
+  } else if (node && typeof node === 'object') {
+    if (typeof node.name === 'string' && ('type' in node || 'optional' in node)) {
+      out.add(normalize(node.name));
+    }
+    for (const key of Object.keys(node)) collectDeclaredFields(node[key], out);
+  }
+}
+
+module.exports = {
+  name: 'no-invented-fields',
+  run(ctx) {
+    const bySlice = new Map(); // "context/SliceName" -> { context, sliceName, files: [] }
+
+    for (const { path: p } of ctx.changes) {
+      if (!p.endsWith('.ts') || p.endsWith('.test.ts')) continue;
+      const m = /^src\/slices\/([^/]+)\/([^/]+)\//.exec(p);
+      if (!m) continue;
+      const key = `${m[1]}/${m[2]}`;
+      if (!bySlice.has(key)) bySlice.set(key, { context: m[1], sliceName: m[2], files: [] });
+      bySlice.get(key).files.push(p);
+    }
+
+    const violations = [];
+
+    for (const { context, sliceName, files } of bySlice.values()) {
+      const slice = findSliceJson(ctx.repoRoot, context, sliceName);
+      if (!slice) continue; // can't verify — don't block
+
+      const declared = new Set();
+      collectDeclaredFields(slice, declared);
+      if (declared.size === 0) continue; // slice.json shape not recognized — don't block
+
+      for (const file of files) {
+        let content;
+        try {
+          content = fs.readFileSync(path.join(ctx.repoRoot, file), 'utf8');
+        } catch {
+          continue; // deleted/unreadable — nothing to check
+        }
+
+        for (const pattern of TYPE_LITERALS) {
+          pattern.lastIndex = 0;
+          let typeMatch;
+          while ((typeMatch = pattern.exec(content))) {
+            FIELD_LINE.lastIndex = 0;
+            let fieldMatch;
+            while ((fieldMatch = FIELD_LINE.exec(typeMatch[1]))) {
+              const raw = fieldMatch[1];
+              const norm = normalize(raw);
+              if (COMMON_ALLOWED.has(norm) || declared.has(norm)) continue;
+              violations.push({
+                path: file,
+                reason: `field "${raw}" is not declared anywhere in slice.json for this slice — check for an invented field`,
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/50-spec-coverage.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+// Heuristic: a slice's *.test.ts must have at least as many `it(...)` blocks as
+// slice.json has `specifications[]` entries. Doesn't verify each spec is
+// actually tested (that would need matching scenario content, not just count),
+// just that nobody's silently short a test case. Skipped (not blocked) when
+// slice.json can't be found or has no specifications[] array.
+
+const fs = require('fs');
+const path = require('path');
+const { findSliceJson } = require('../util/find-slice.cjs');
+
+const TEST_FILE = /^src\/slices\/([^/]+)\/([^/]+)\/[^/]+\.test\.ts$/;
+const IT_BLOCK = /\bit(?:\.(?:only|skip))?\s*\(/g;
+
+module.exports = {
+  name: 'spec-coverage',
+  run(ctx) {
+    const violations = [];
+
+    for (const { path: p } of ctx.changes) {
+      TEST_FILE.lastIndex = 0;
+      const m = TEST_FILE.exec(p);
+      if (!m) continue;
+      const [, context, sliceName] = m;
+
+      const slice = findSliceJson(ctx.repoRoot, context, sliceName);
+      if (!slice || !Array.isArray(slice.specifications) || slice.specifications.length === 0) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(path.join(ctx.repoRoot, p), 'utf8');
+      } catch {
+        continue; // deleted — nothing to check
+      }
+
+      const specCount = slice.specifications.length;
+      const itCount = (content.match(IT_BLOCK) || []).length;
+
+      if (itCount < specCount) {
+        violations.push({
+          path: p,
+          reason: `slice.json declares ${specCount} specification(s) but this test file only has ${itCount} it(...) block(s)`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/stacks/node/templates/build-kit/lib/checks/90-tsc-build.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+// The project must still typecheck after the slice change. Uses the project's
+// own `typescript` devDependency via `npx tsc --noEmit` — no new dependency,
+// but it does mean this check needs node_modules already installed (same
+// prerequisite `npm run build` already has).
+
+const { execSync } = require('child_process');
+
+module.exports = {
+  name: 'tsc-build',
+  skipIfAlreadyFailing: true, // slow — don't bother once the commit is rejected already
+  run(ctx) {
+    try {
+      execSync('npx tsc --noEmit', { cwd: ctx.repoRoot, stdio: 'pipe' });
+      return [];
+    } catch (err) {
+      const output = String(err.stdout || err.message || '').trim().split('\n').slice(0, 20).join('\n');
+      return [{ path: '(tsc --noEmit)', reason: `TypeScript build failed:\n${output}` }];
+    }
+  },
+};

package/stacks/node/templates/root/.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Installed via setup-env.sh (`git config core.hooksPath .githooks`), so this file
+# is versioned and shared by every clone instead of living only in .git/hooks/.
+set -e
+
+repo_root=$(git rev-parse --show-toplevel)
+script="$repo_root/.build-kit/lib/check-commit-scope.cjs"
+
+if [ -f "$script" ]; then
+  node "$script"
+fi

package/stacks/node/templates/root/README.md

@@ -0,0 +1,67 @@
+# Node.js / TypeScript Event-Sourced Service
+
+An event-sourced backend scaffolded by [`@eventmodelers/cli`](https://www.npmjs.com/package/@eventmodelers/cli).
+It uses [Emmett](https://event-driven-io.github.io/emmett/) over Postgres for the event store,
+Express for the HTTP layer, and Flyway for schema migrations.
+
+Features are built as **vertical slices** under `src/slices/`, generated from the slices on your
+Eventmodelers board by the agent in `.build-kit/`.
+
+## Prerequisites
+
+- Node.js 20 or later (the dev/start scripts use `node --env-file`)
+- Docker and Docker Compose (for local Postgres)
+- Flyway CLI on your `PATH` (for `npm run flyway:migrate`)
+- [Claude Code](https://claude.com/claude-code) if you want to run the build agent
+
+## Getting started
+
+1. Start Postgres:
+
+   ```bash
+   docker compose up -d
+   ```
+
+2. Create your `.env`:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Or run `./setup-env.sh` to be prompted for host, port, database, user and password.
+
+3. Activate the baseline migration and apply it:
+
+   ```bash
+   mv migrations/V1__schema.sql.example migrations/V1__schema.sql
+   npm install
+   npm run flyway:migrate
+   ```
+
+   `V1__schema.sql` creates the processor dead-letter queue table the runtime expects. Add your own
+   `V2__*.sql`, `V3__*.sql` and so on as slices introduce projections.
+
+4. Run the server:
+
+   ```bash
+   npm run build   # slice routes and processors are loaded from dist/
+   npm run dev
+   ```
+
+The API is on http://localhost:3000, with Swagger UI at http://localhost:3000/api-docs and the raw
+OpenAPI document at http://localhost:3000/swagger.json.
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `npm run dev` | Start the server locally with `.env` loaded |
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm start` | Start in production mode |
+| `npm test` | Run `src/**/*.test.ts` via `tsx --test` |
+| `npm run flyway:migrate` | Apply pending migrations from `migrations/` |
+
+## Learn more
+
+- [Eventmodelers](https://eventmodelers.ai)
+- [Emmett documentation](https://event-driven-io.github.io/emmett/)

package/stacks/node/templates/root/package.json

@@ -7,7 +7,8 @@
     "dev": "node --env-file=.env --require ts-node/register server.ts",
     "build": "tsc",
     "start": "NODE_ENV=production node --env-file=.env --require ts-node/register server.ts",
-    "test": "tsx --test 'src/**/*.test.ts'"
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "check:scope": "node .build-kit/lib/check-commit-scope.cjs"
   },
   "dependencies": {
     "@event-driven-io/emmett": "^0.42.1-alpha.1",

package/stacks/node/templates/root/setup-env.sh

@@ -50,4 +50,10 @@ FLYWAY_PASSWORD=${DB_PASSWORD}
 EOF
 
 echo ""
-echo ".env created successfully."
+echo ".env created successfully."
+
+if [ -f .githooks/pre-commit ] && git rev-parse --git-dir >/dev/null 2>&1; then
+  chmod +x .githooks/pre-commit 2>/dev/null || true
+  git config core.hooksPath .githooks
+  echo "Configured git to use .githooks/ (slice commit-scope guard)."
+fi