@eventmodelers/cli 1.0.45 → 1.0.46

package/stacks/kurrent/templates/root/mvnw.cmd

@@ -0,0 +1,149 @@
+<# : batch portion
+@REM ----------------------------------------------------------------------------
+@REM Licensed to the Apache Software Foundation (ASF) under one
+@REM or more contributor license agreements.  See the NOTICE file
+@REM distributed with this work for additional information
+@REM regarding copyright ownership.  The ASF licenses this file
+@REM to you under the Apache License, Version 2.0 (the
+@REM "License"); you may not use this file except in compliance
+@REM with the License.  You may obtain a copy of the License at
+@REM
+@REM    http://www.apache.org/licenses/LICENSE-2.0
+@REM
+@REM Unless required by applicable law or agreed to in writing,
+@REM software distributed under the License is distributed on an
+@REM "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+@REM KIND, either express or implied.  See the License for the
+@REM specific language governing permissions and limitations
+@REM under the License.
+@REM ----------------------------------------------------------------------------
+
+@REM ----------------------------------------------------------------------------
+@REM Apache Maven Wrapper startup batch script, version 3.3.2
+@REM
+@REM Optional ENV vars
+@REM   MVNW_REPOURL - repo url base for downloading maven distribution
+@REM   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+@REM   MVNW_VERBOSE - true: enable verbose log; others: silence the output
+@REM ----------------------------------------------------------------------------
+
+@IF "%__MVNW_ARG0_NAME__%"=="" (SET __MVNW_ARG0_NAME__=%~nx0)
+@SET __MVNW_CMD__=
+@SET __MVNW_ERROR__=
+@SET __MVNW_PSMODULEP_SAVE=%PSModulePath%
+@SET PSModulePath=
+@FOR /F "usebackq tokens=1* delims==" %%A IN (`powershell -noprofile "& {$scriptDir='%~dp0'; $script='%__MVNW_ARG0_NAME__%'; icm -ScriptBlock ([Scriptblock]::Create((Get-Content -Raw '%~f0'))) -NoNewScope}"`) DO @(
+  IF "%%A"=="MVN_CMD" (set __MVNW_CMD__=%%B) ELSE IF "%%B"=="" (echo %%A) ELSE (echo %%A=%%B)
+)
+@SET PSModulePath=%__MVNW_PSMODULEP_SAVE%
+@SET __MVNW_PSMODULEP_SAVE=
+@SET __MVNW_ARG0_NAME__=
+@SET MVNW_USERNAME=
+@SET MVNW_PASSWORD=
+@IF NOT "%__MVNW_CMD__%"=="" (%__MVNW_CMD__% %*)
+@echo Cannot start maven from wrapper >&2 && exit /b 1
+@GOTO :EOF
+: end batch / begin powershell #>
+
+$ErrorActionPreference = "Stop"
+if ($env:MVNW_VERBOSE -eq "true") {
+  $VerbosePreference = "Continue"
+}
+
+# calculate distributionUrl, requires .mvn/wrapper/maven-wrapper.properties
+$distributionUrl = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionUrl
+if (!$distributionUrl) {
+  Write-Error "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+}
+
+switch -wildcard -casesensitive ( $($distributionUrl -replace '^.*/','') ) {
+  "maven-mvnd-*" {
+    $USE_MVND = $true
+    $distributionUrl = $distributionUrl -replace '-bin\.[^.]*$',"-windows-amd64.zip"
+    $MVN_CMD = "mvnd.cmd"
+    break
+  }
+  default {
+    $USE_MVND = $false
+    $MVN_CMD = $script -replace '^mvnw','mvn'
+    break
+  }
+}
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+if ($env:MVNW_REPOURL) {
+  $MVNW_REPO_PATTERN = if ($USE_MVND) { "/org/apache/maven/" } else { "/maven/mvnd/" }
+  $distributionUrl = "$env:MVNW_REPOURL$MVNW_REPO_PATTERN$($distributionUrl -replace '^.*'+$MVNW_REPO_PATTERN,'')"
+}
+$distributionUrlName = $distributionUrl -replace '^.*/',''
+$distributionUrlNameMain = $distributionUrlName -replace '\.[^.]*$','' -replace '-bin$',''
+$MAVEN_HOME_PARENT = "$HOME/.m2/wrapper/dists/$distributionUrlNameMain"
+if ($env:MAVEN_USER_HOME) {
+  $MAVEN_HOME_PARENT = "$env:MAVEN_USER_HOME/wrapper/dists/$distributionUrlNameMain"
+}
+$MAVEN_HOME_NAME = ([System.Security.Cryptography.MD5]::Create().ComputeHash([byte[]][char[]]$distributionUrl) | ForEach-Object {$_.ToString("x2")}) -join ''
+$MAVEN_HOME = "$MAVEN_HOME_PARENT/$MAVEN_HOME_NAME"
+
+if (Test-Path -Path "$MAVEN_HOME" -PathType Container) {
+  Write-Verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"
+  exit $?
+}
+
+if (! $distributionUrlNameMain -or ($distributionUrlName -eq $distributionUrlNameMain)) {
+  Write-Error "distributionUrl is not valid, must end with *-bin.zip, but found $distributionUrl"
+}
+
+# prepare tmp dir
+$TMP_DOWNLOAD_DIR_HOLDER = New-TemporaryFile
+$TMP_DOWNLOAD_DIR = New-Item -Itemtype Directory -Path "$TMP_DOWNLOAD_DIR_HOLDER.dir"
+$TMP_DOWNLOAD_DIR_HOLDER.Delete() | Out-Null
+trap {
+  if ($TMP_DOWNLOAD_DIR.Exists) {
+    try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+    catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+  }
+}
+
+New-Item -Itemtype Directory -Path "$MAVEN_HOME_PARENT" -Force | Out-Null
+
+# Download and Install Apache Maven
+Write-Verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+Write-Verbose "Downloading from: $distributionUrl"
+Write-Verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+$webclient = New-Object System.Net.WebClient
+if ($env:MVNW_USERNAME -and $env:MVNW_PASSWORD) {
+  $webclient.Credentials = New-Object System.Net.NetworkCredential($env:MVNW_USERNAME, $env:MVNW_PASSWORD)
+}
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+$webclient.DownloadFile($distributionUrl, "$TMP_DOWNLOAD_DIR/$distributionUrlName") | Out-Null
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+$distributionSha256Sum = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionSha256Sum
+if ($distributionSha256Sum) {
+  if ($USE_MVND) {
+    Write-Error "Checksum validation is not supported for maven-mvnd. `nPlease disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties."
+  }
+  Import-Module $PSHOME\Modules\Microsoft.PowerShell.Utility -Function Get-FileHash
+  if ((Get-FileHash "$TMP_DOWNLOAD_DIR/$distributionUrlName" -Algorithm SHA256).Hash.ToLower() -ne $distributionSha256Sum) {
+    Write-Error "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised. If you updated your Maven version, you need to update the specified distributionSha256Sum property."
+  }
+}
+
+# unzip and move
+Expand-Archive "$TMP_DOWNLOAD_DIR/$distributionUrlName" -DestinationPath "$TMP_DOWNLOAD_DIR" | Out-Null
+Rename-Item -Path "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" -NewName $MAVEN_HOME_NAME | Out-Null
+try {
+  Move-Item -Path "$TMP_DOWNLOAD_DIR/$MAVEN_HOME_NAME" -Destination $MAVEN_HOME_PARENT | Out-Null
+} catch {
+  if (! (Test-Path -Path "$MAVEN_HOME" -PathType Container)) {
+    Write-Error "fail to move MAVEN_HOME"
+  }
+} finally {
+  try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null }
+  catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" }
+}
+
+Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD"

package/stacks/kurrent/templates/root/pom.xml

@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>com.example.quickstart</groupId>
+    <artifactId>quickstart</artifactId>
+    <name>Kurrent Quickstart</name>
+    <version>0.0.1-SNAPSHOT</version>
+
+    <properties>
+        <java.version>21</java.version>
+        <kurrentdb.version>1.2.1</kurrentdb.version>
+        <spring-boot.version>4.1.0</spring-boot.version>
+        <!-- Must track whatever version kurrentdb-client itself pulls in transitively (grpc-api is
+             runtime-scope only there) — check `mvn dependency:tree | grep grpc` after bumping
+             kurrentdb.version, and bump this to match. -->
+        <grpc.version>1.80.0</grpc.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-webmvc</artifactId>
+        </dependency>
+
+        <!-- Classic Jackson 2 (com.fasterxml.jackson.core), for hand-serializing event payloads
+             (LibraryEventTypes and friends) with the same ObjectMapper the kurrentdb-client's own
+             samples use. Spring Boot 4 moved its own internal JSON handling to Jackson 3
+             (tools.jackson.core) and only pulls classic Jackson 2 in at *runtime* scope, transitively
+             via kurrentdb-client itself — not on the compile classpath by default. Declared explicitly,
+             version still resolved from Spring Boot's dependency-management BOM. -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+
+        <!-- Read model persistence: Spring Data JPA + PostgreSQL, default for all projections -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-data-jpa</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.postgresql</groupId>
+            <artifactId>postgresql</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
+
+        <!-- KurrentDB Java client (plain SDK — no Spring Boot auto-configuration of its own,
+             see config.KurrentConfiguration for the beans this project wires by hand) -->
+        <dependency>
+            <groupId>io.kurrent</groupId>
+            <artifactId>kurrentdb-client</artifactId>
+            <version>${kurrentdb.version}</version>
+        </dependency>
+
+        <!-- io.grpc.Status/StatusRuntimeException — needed at compile scope to detect an
+             ALREADY_EXISTS conflict when idempotently creating a persistent-subscription group
+             (see build-state-view/build-automation). Only pulled in transitively by
+             kurrentdb-client at *runtime* scope otherwise. -->
+        <dependency>
+            <groupId>io.grpc</groupId>
+            <artifactId>grpc-api</artifactId>
+            <version>${grpc.version}</version>
+        </dependency>
+
+        <!-- Auto-starts docker-compose.yml services (KurrentDB, Postgres) on app run -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-docker-compose</artifactId>
+            <scope>runtime</scope>
+            <optional>true</optional>
+        </dependency>
+
+        <!-- Testing -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <!-- Spring Boot 4 test slices: @DataJpaTest and @WebMvcTest each moved to their own artifact -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-data-jpa-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-webmvc-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-testcontainers</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>testcontainers</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>testcontainers-postgresql</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.testcontainers</groupId>
+            <artifactId>testcontainers-junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                    <parameters>true</parameters>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-dependencies</artifactId>
+                <version>${spring-boot.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+</project>

package/stacks/kurrent/templates/root/src/main/java/com/example/quickstart/QuickstartApplication.java

@@ -0,0 +1,12 @@
+package com.example.quickstart;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class QuickstartApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(QuickstartApplication.class, args);
+    }
+}

package/stacks/kurrent/templates/root/src/main/java/com/example/quickstart/common/EventStore.java

@@ -0,0 +1,91 @@
+package com.example.quickstart.common;
+
+import io.kurrent.dbclient.*;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+import java.util.concurrent.ExecutionException;
+
+/**
+ * Thin wrapper around {@link KurrentDBClient} shared by every write slice — reads a stream into a
+ * plain list (or empty, if the stream doesn't exist yet) and appends events, translating the client's
+ * checked/wrapped exceptions into unchecked ones so slice code doesn't repeat this boilerplate.
+ *
+ * <p>This project has no CQRS framework layer (unlike the OpenCQRS/Axon kits) — this class, plus each
+ * slice's own {@code decide}/{@code evolve} functions, is the entire "framework". See
+ * {@code .build-kit/CLAUDE.md} for the full convention.
+ */
+@Component
+public class EventStore {
+
+    private final KurrentDBClient client;
+
+    public EventStore(KurrentDBClient client) {
+        this.client = client;
+    }
+
+    /**
+     * Reads every event in {@code streamId}, forwards from the start. Returns
+     * {@link StreamEvents#empty()} if the stream doesn't exist yet — this is the normal, expected case
+     * for a creation command, not an error.
+     */
+    public StreamEvents read(String streamId) {
+        try {
+            ReadResult result = client.readStream(streamId, ReadStreamOptions.get().forwards().fromStart()).get();
+            return new StreamEvents(result.getEvents(), result.getLastStreamPosition());
+        } catch (ExecutionException e) {
+            if (e.getCause() instanceof StreamNotFoundException) {
+                return StreamEvents.empty();
+            }
+            throw new EventStoreException(e.getCause());
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new EventStoreException(e);
+        }
+    }
+
+    /**
+     * Appends {@code events} to {@code streamId} under the given {@code expectedState} (see
+     * {@link StreamState#noStream()}/{@link StreamState#streamRevision(long)}/etc). Throws
+     * {@link WrongExpectedVersionException} directly (unwrapped) on an optimistic-concurrency
+     * conflict — callers decide for themselves whether that's a real conflict (map it to HTTP 409) or
+     * an expected redelivery to swallow (see build-automation's SKILL.md).
+     */
+    public WriteResult append(String streamId, StreamState expectedState, List<EventData> events) {
+        try {
+            AppendToStreamOptions options = AppendToStreamOptions.get().streamState(expectedState);
+            return client.appendToStream(streamId, options, events.toArray(new EventData[0])).get();
+        } catch (ExecutionException e) {
+            if (e.getCause() instanceof WrongExpectedVersionException wrongExpectedVersion) {
+                throw wrongExpectedVersion;
+            }
+            throw new EventStoreException(e.getCause());
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new EventStoreException(e);
+        }
+    }
+
+    public record StreamEvents(List<ResolvedEvent> events, long lastStreamPosition) {
+        private static final long NO_STREAM_POSITION = -1;
+
+        public static StreamEvents empty() {
+            return new StreamEvents(List.of(), NO_STREAM_POSITION);
+        }
+
+        public boolean isEmpty() {
+            return events.isEmpty();
+        }
+
+        /** The {@link StreamState} to append under, given this stream's current position. */
+        public StreamState expectedState() {
+            return isEmpty() ? StreamState.noStream() : StreamState.streamRevision(lastStreamPosition);
+        }
+    }
+
+    public static class EventStoreException extends RuntimeException {
+        public EventStoreException(Throwable cause) {
+            super(cause);
+        }
+    }
+}

package/stacks/kurrent/templates/root/src/main/java/com/example/quickstart/config/KurrentConfiguration.java

@@ -0,0 +1,42 @@
+package com.example.quickstart.config;
+
+import io.kurrent.dbclient.ConnectionStringParsingException;
+import io.kurrent.dbclient.KurrentDBClient;
+import io.kurrent.dbclient.KurrentDBClientSettings;
+import io.kurrent.dbclient.KurrentDBConnectionString;
+import io.kurrent.dbclient.KurrentDBPersistentSubscriptionsClient;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * The KurrentDB Java client ({@code kurrentdb-client}) ships no Spring Boot auto-configuration of its
+ * own (unlike OpenCQRS's {@code framework-spring-boot-starter}) — it is a plain SDK. These beans are
+ * this project's own wiring, not a vendor-provided starter.
+ */
+@Configuration
+public class KurrentConfiguration {
+
+    @Value("${kurrentdb.connection-string}")
+    private String connectionString;
+
+    /**
+     * A single client instance is safe to share as a singleton across the whole application — it does
+     * not need to be opened/closed per request (see the client's own getting-started guide).
+     */
+    @Bean(destroyMethod = "shutdown")
+    public KurrentDBClient kurrentDBClient() throws ConnectionStringParsingException {
+        KurrentDBClientSettings settings = KurrentDBConnectionString.parseOrThrow(connectionString);
+        return KurrentDBClient.create(settings);
+    }
+
+    /**
+     * Separate client for managing/consuming persistent subscriptions — used by build-state-view and
+     * build-automation slices, not by build-state-change (which only appends/reads streams directly).
+     */
+    @Bean(destroyMethod = "shutdown")
+    public KurrentDBPersistentSubscriptionsClient kurrentDBPersistentSubscriptionsClient() throws ConnectionStringParsingException {
+        KurrentDBClientSettings settings = KurrentDBConnectionString.parseOrThrow(connectionString);
+        return KurrentDBPersistentSubscriptionsClient.create(settings);
+    }
+}

package/stacks/kurrent/templates/root/src/main/resources/application.properties

@@ -0,0 +1,14 @@
+spring.application.name=quickstart
+server.port=8080
+
+kurrentdb.connection-string=${KURRENTDB_CONNECTION_STRING:kurrentdb://localhost:2113?tls=false}
+
+spring.datasource.url=jdbc:postgresql://localhost:5432/quickstart
+spring.datasource.username=quickstart
+spring.datasource.password=quickstart
+spring.jpa.hibernate.ddl-auto=update
+
+spring.docker.compose.enabled=true
+spring.docker.compose.file=docker-compose.yml
+
+management.endpoint.health.show-components=always

package/stacks/kurrent/templates/root/src/main/resources/static/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Kurrent Quickstart</title>
+</head>
+<body>
+  <h1>Kurrent Quickstart</h1>
+  <p>Backend is running. Slices built from the event model board are wired up under their own REST paths.</p>
+</body>
+</html>

package/stacks/node/templates/build-kit/CLAUDE.md

@@ -57,6 +57,28 @@ When asked to build a slice, always follow this flow:
 
 After you are done, automatically run the tests for the slice that was edited.
 
+## Commit Scope Guard
+
+A pre-commit hook (`.githooks/pre-commit`, installed via `init --hooks` — see its own project's setup)
+runs `.build-kit/lib/check-commit-scope.cjs` on every commit that touches `src/slices/{context}/{slice}/`.
+It loads every check under `.build-kit/lib/checks/` and rejects the commit if any of them find a problem:
+
+- **blocked-paths** — `package.json`/lockfiles and `server.ts` are never touched by slice work
+- **slice-scope** — everything staged must be inside the slice folder or a documented exception:
+  `src/slices/{context}/{Context}Events.ts` or `src/common/loadPostgresEventstore.ts`
+- **append-only-migrations** — `migrations/V{n}__*.sql` may only be **added**, never edited
+- **test-file-present** — a changed Command/Projection/processor file needs a sibling `*.test.ts`
+- **no-invented-fields** — heuristic: flags a field used in code that isn't declared anywhere in
+  `.build-kit/.slices/{context}/{slice}/slice.json`
+- **spec-coverage** — heuristic: the test file needs at least as many `it(...)` blocks as slice.json
+  has `specifications[]` entries
+- **tsc-build** — `npx tsc --noEmit` must still pass
+
+If a commit is rejected, split it — commit the out-of-scope file separately from the slice work, or add
+the missing test/fix the field — rather than passing `--no-verify`. Run `npm run check:scope` any time
+you want to check staged files before committing. To add a new check, read
+`.build-kit/lib/checks/README.md` and drop in a file following its interface — no other wiring needed.
+
 ## Example Slice Structure
 
 ```

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;
+  },
+};