@eventmodelers/cli 0.0.1

package/stacks/axon/templates/.claude/skills/build-state-change/references/rest-api-patterns.md

@@ -0,0 +1,115 @@
+# REST API Patterns
+
+Ground truth: `RegisterCustomerRestController`
+(`src/main/java/.../foo/register/RegisterCustomerRestController.java`), this project's only REST
+controller for a write slice. This project uses WebFlux (`spring-boot-starter-webflux`), not
+`spring-boot-starter-web` — controller methods return `Mono<ResponseEntity<...>>`, not `ResponseEntity`
+directly, and tests use `WebTestClient`, not `MockMvc`.
+
+## Controller
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+import org.axonframework.messaging.commandhandling.gateway.CommandGateway;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+import reactor.core.publisher.Mono;
+
+@RestController
+@ConditionalOnProperty(prefix = "slices.{context}.write", name = "{slicename}.enabled")
+public class {SliceName}RestController {
+
+    private final CommandGateway commandGateway;
+
+    public {SliceName}RestController(CommandGateway commandGateway) {
+        this.commandGateway = commandGateway;
+    }
+
+    @PostMapping("/api/{context}/{resource}")
+    public Mono<ResponseEntity<Void>> handle(@RequestBody {SliceName}RequestBody body) {
+        var command = new {SliceName}Command(body.field1(), body.idField());
+        return Mono.fromFuture(commandGateway.send(command).getResultMessage())
+            .map(ignored -> ResponseEntity.ok().<Void>build())
+            .onErrorResume(e -> Mono.just(ResponseEntity.badRequest().<Void>build()));
+    }
+
+    public record {SliceName}RequestBody(String field1, String idField) {}
+}
+```
+
+Notes, all taken directly from the real controller:
+- `CommandGateway.send(command)` returns a `CommandResult`; `.getResultMessage()` on it returns a
+  `CompletableFuture<? extends Message>` — wrap with `Mono.fromFuture(...)`, don't call `.get()`/`.join()`.
+- Success → `200` with an empty body (`ResponseEntity.ok().<Void>build()`); any exception from the
+  command handler (e.g. the `IllegalStateException` a business-rule violation throws) → `400` via
+  `onErrorResume`. There's no per-exception-type branching here — every failure maps to `400`.
+- The request body record (`{SliceName}RequestBody`) is a plain nested record matching the command's
+  fields — it is not the Command itself; the controller maps one to the other explicitly.
+- `@ConditionalOnProperty` uses the exact same `prefix`/`name` pair as the command handler (see
+  Step 6 in `SKILL.md`) — both gate on the same flag.
+
+## Test — `WebTestClient` (not `MockMvc`)
+
+No REST test exists yet in this repo for `RegisterCustomerRestController` — this is the recommended
+shape for the first one, matching the project's WebFlux stack and the `@ConditionalOnProperty`
+feature-flag convention (tests disable all slices by default; opt in per test class):
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+import org.axonframework.messaging.commandhandling.gateway.CommandGateway;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.test.context.TestPropertySource;
+import org.springframework.test.web.reactive.server.WebTestClient;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.verify;
+
+@WebFluxTest({SliceName}RestController.class)
+@TestPropertySource(properties = "slices.{context}.write.{slicename}.enabled=true")
+class {SliceName}RestControllerTest {
+
+    @Autowired
+    private WebTestClient webTestClient;
+
+    @MockBean
+    private CommandGateway commandGateway;
+
+    @Test
+    void acceptsValidRequest() {
+        var resultMessage = /* stub a CompletableFuture<CommandResultMessage<?>> completing normally */;
+        doReturn(resultMessage).when(commandGateway).send(any()).getResultMessage();
+
+        webTestClient.post().uri("/api/{context}/{resource}")
+            .bodyValue(new {SliceName}RestController.{SliceName}RequestBody("value1", "id-1"))
+            .exchange()
+            .expectStatus().isOk();
+
+        verify(commandGateway).send(new {SliceName}Command("value1", "id-1"));
+    }
+
+    @Test
+    void mapsHandlerFailureTo400() {
+        var resultMessage = /* stub a CompletableFuture failing with IllegalStateException */;
+        doReturn(resultMessage).when(commandGateway).send(any()).getResultMessage();
+
+        webTestClient.post().uri("/api/{context}/{resource}")
+            .bodyValue(new {SliceName}RestController.{SliceName}RequestBody("value1", "id-1"))
+            .exchange()
+            .expectStatus().isBadRequest();
+    }
+}
+```
+
+`CommandGateway.send(cmd)` returns `CommandResult`; stub with `doReturn(...).when(mock).getResultMessage()`
+— `when(mock.send(...)).thenReturn(...)` hits a wildcard-capture generics compile error on this API.

package/stacks/axon/templates/.claude/skills/build-state-view/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: build-state-view
+authors:
+  - Mateusz Nowak
+  - Martin Dilger
+description: >
+  Implement read slices (projections + query handlers + REST API + tests) using Axon Framework 5
+  with Spring Boot. A read slice is: Events projected into a Read Model, queried via QueryGateway.
+  Use when: (1) implementing a new read slice / projection in an AF5 Java project,
+  (2) migrating/porting a read slice from Axon Framework 4 (Java or Kotlin) to AF5,
+  (3) user provides a read slice specification or Event Modeling artifact and asks to implement it,
+  (4) user says "implement", "create", "add" a read slice, projection, query handler,
+  or read model in an Axon Framework 5 / Vertical Slice Architecture project.
+---
+
+# Axon Framework 5 — Read Slice (Java)
+
+## Step 0: Discover Target Project Conventions
+
+> **Comments & description**: Each element in the slice carries a `comments: string[]` array and a `description` field. Use these as implementation hints. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get IDs first via GET on same path).
+
+Before writing any code, read the target project's `CLAUDE.md`
+
+## Step 1: Ensure Events Exist
+
+Before implementing the read slice, verify that all events the projector handles exist in the
+codebase. If they don't, create them **first**.
+
+### Concrete event records
+
+```java
+@Event(namespace = "{Context}", name = "{EventName}", version = "1.0.0")
+public record {EventName}(
+    @EventTag
+    String {tagProperty},
+    String field1
+){}
+```
+
+Key rules:
+- Import `@Event` from `org.axonframework.messaging.eventhandling.annotation.Event`
+- `namespace` = context name, `name` = record name, `version` = `"1.0.0"` for new events
+- When an event participates in a DCB, add extra `@EventTag` on cross-stream fields
+
+## Step 2: Implement the Read Slice
+
+If the Event Modeling artifact includes slice details with `## Scenarios (GWTs)`, use them to
+derive test cases. GWT format for read slices: `Given (events) → Then (information)` — no When.
+Events in Given tell you which events the projector handles. The information element in Then
+describes the expected query result.
+
+If the slice description or comments contain `## Implementation Guidelines`, **follow them**.
+
+### Query annotation
+
+Every query record must have `@Query(namespace, name, version)`:
+
+```java
+@Query(namespace = "{Context}", name = "Get{SliceName}", version = "1.0.0")
+public record Get{SliceName}(String {filterField}) {
+    public record Result(List<{SliceName}Summary> items) {}
+}
+```
+
+- Import `@Query` from `org.axonframework.messaging.queryhandling.annotation.Query`
+
+A read slice lives in a single package. **Do NOT add Domain/Application/Presentation section
+comments** — those are only for write slices.
+
+### Slice package structure
+
+```
+de/<package>/{context}/slices/{slicename}/
+├── Get{SliceName}.java       ← query record + nested Result
+├── {SliceName}Summary.java   ← read model (projection output shape)
+├── {SliceName}Projector.java ← @Component with @EventHandler + @QueryHandler
+└── {SliceName}RestApi.java   ← @RestController (if REST chosen)
+```
+
+### Projector + query handler (JPA-backed)
+
+Projections persist to a database via Spring Data JPA — this is the only supported style.
+
+```java
+public record AllCustomersSummary(String name, String email) {}
+
+@Query(namespace = "CustomerManagement", name = "GetAllCustomers", version = "1.0.0")
+public record GetAllCustomers() {
+    public record Result(List<AllCustomersSummary> items) {}
+}
+
+@Entity
+@Table(name = "customer_management_allcustomers")
+class AllCustomersEntity {
+
+    @Id
+    private String email;
+    private String name;
+
+    protected AllCustomersEntity() {
+    }
+
+    AllCustomersEntity(String email, String name) {
+        this.email = email;
+        this.name = name;
+    }
+
+    AllCustomersSummary toSummary() {
+        return new AllCustomersSummary(name, email);
+    }
+}
+
+@Component
+public class AllCustomersProjector {
+
+    private final AllCustomersRepository repository;
+
+    public AllCustomersProjector(AllCustomersRepository repository) {
+        this.repository = repository;
+    }
+
+    @EventHandler
+    public void on(CustomerRegistered event) {
+        repository.save(new AllCustomersEntity(event.email(), event.name()));
+    }
+
+    @QueryHandler
+    public GetAllCustomers.Result handle(GetAllCustomers query) {
+        List<AllCustomersSummary> items = repository.findAll().stream()
+                .map(AllCustomersEntity::toSummary)
+                .toList();
+        return new GetAllCustomers.Result(items);
+    }
+}
+
+interface AllCustomersRepository extends JpaRepository<AllCustomersEntity, String> {
+}
+```
+
+### Result DTO rules
+
+- If the read model matches the query result **1:1**, expose the summary record directly.
+- If the read model contains fields the caller already knows from the query (e.g., the filter field),
+  omit those from the `Result` and map from the projector's internal model.
+
+### Entity + repository template
+
+For filtered queries, add an index and a derived-query method instead of `findAll()`:
+
+```java
+@Entity
+@Table(
+    name = "{context}_read_{slicename}",
+    indexes = {@Index(name = "idx_{context}_{slicename}_{col}", columnList = "{filterField}")}
+)
+public class {SliceName}Entity {
+    @Id private String id;
+    private String {filterField};
+    // ... other fields
+}
+
+@Repository
+interface {SliceName}Repository extends JpaRepository<{SliceName}Entity, String> {
+    List<{SliceName}Entity> findAllBy{FilterField}(String {filterField});
+}
+```
+
+Use `findAllBy{FilterField}(...)` in the `@QueryHandler` — DB-level filtering, not client-side.
+
+## Step 3: REST API Exposure (Optional)
+
+Check the target project's convention first.
+
+```java
+// File: {SliceName}RestApi.java
+@RestController
+public class {SliceName}RestApi {
+
+    private final QueryGateway queryGateway;
+
+    public {SliceName}RestApi(QueryGateway queryGateway) {
+        this.queryGateway = queryGateway;
+    }
+
+    @GetMapping("/api/{context}/{filterField}")
+    public Mono<Get{SliceName}.Result> query(@PathVariable String {filterField}) {
+        return Mono.fromFuture(
+            queryGateway.query(new Get{SliceName}({filterField}), Get{SliceName}.Result.class)
+        );
+    }
+}
+```
+
+## Step 4: Design Test Cases
+
+Implement the test cases provided in the slice definition. 
+Do not design your own test cases unless specifically instructed to do so.
+
+### Mapping GWT Scenarios to Tests
+
+| GWT Element | Test Code |
+|---|---|
+| `NOTHING` in Given | instantiate projector, call `handle(query)` directly |
+| Event in Given | call `projector.on(event)` |
+| Information in Then | `assertThat(result.items()).containsExactlyInAnyOrder(...)` |
+
+## Step 5: Implement the Slice Test
+
+Pure unit tests — instantiate the projector directly, no Spring context needed.
+Fast, no container startup.
+
+```java
+// File: src/test/java/de/<package>/{context}/slices/{slicename}/{SliceName}ProjectorTest.java
+class {SliceName}ProjectorTest {
+
+    private {SliceName}Projector projector;
+
+    @BeforeEach
+    void setUp() {
+        projector = new {SliceName}Projector();
+    }
+
+    @Test
+    @DisplayName("given no events, when query, then empty result")
+    void emptyState() {
+        var result = projector.handle(new Get{SliceName}("filter-value"));
+
+        assertThat(result.items()).isEmpty();
+    }
+
+    @Test
+    @DisplayName("given creation event, then item appears in result")
+    void creationEvent() {
+        projector.on(new {CreationEvent}("id-1", "filter-value" /*, other fields */));
+
+        var result = projector.handle(new Get{SliceName}("filter-value"));
+
+        assertThat(result.items()).containsExactly(
+            new {SliceName}Summary("id-1", "filter-value" /*, expected fields */)
+        );
+    }
+
+    @Test
+    @DisplayName("given creation then deletion, then item disappears")
+    void deletionEvent() {
+        projector.on(new {CreationEvent}("id-1", "filter-value"));
+        projector.on(new {DeletionEvent}("id-1"));
+
+        var result = projector.handle(new Get{SliceName}("filter-value"));
+
+        assertThat(result.items()).isEmpty();
+    }
+
+    @Test
+    @DisplayName("items are isolated by filter field")
+    void isolation() {
+        projector.on(new {CreationEvent}("id-1", "group-A"));
+        projector.on(new {CreationEvent}("id-2", "group-B"));
+
+        assertThat(projector.handle(new Get{SliceName}("group-A")).items()).hasSize(1);
+        assertThat(projector.handle(new Get{SliceName}("group-B")).items()).hasSize(1);
+    }
+}
+```
+
+### Key Rules
+
+- **Metadata when needed**: If the projector uses `@MetadataValue(...)`, pass metadata by publishing
+  events to an `AxonTestFixture` rather than calling `on(event)` directly. Use the Spring Boot
+  integration test approach in that case.
+- **Assert with full objects**: Use `containsExactlyInAnyOrder(new Summary(...))` rather than
+  field-by-field assertions — catches serialization mismatches.
+
+## Final Verification: Does the Implementation Match slice.json?
+
+Before marking this slice as `Done`, verify the implementation against slice.json:
+
+- [ ] Every field in the read model / query result definition in slice.json has a field in `{SliceName}Summary` — no invented fields
+- [ ] Every event type in `events[]` has an `@EventHandler` in the projector — no events missed or assumed
+- [ ] Every GWT scenario in `specifications[]` maps to a test case in `{SliceName}ProjectorTest`
+- [ ] No extra query parameters or filter logic were added beyond what slice.json defines
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code

package/stacks/axon/templates/.claude/skills/connect/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: connect
+description: Resolve eventmodelers connection config (token, boardId, baseUrl) from inline params or .eventmodelers/config.json — ask the user for missing values, persist them, and add the file to .gitignore. All other skills invoke this first.
+---
+
+# Connect — Resolve Eventmodelers Config
+
+**Every other skill invokes this skill first** before making any API calls. Do not proceed past this skill until all four values (`TOKEN`, `BOARD_ID`, `ORG_ID`, `BASE_URL`) are resolved.
+
+---
+
+## What this skill produces
+
+After running, the following variables are available for the rest of the session:
+
+| Variable | Header sent to API | Description |
+|----------|--------------------|-------------|
+| `TOKEN` | `x-token` | API token UUID |
+| `BOARD_ID` | `x-board-id` | Target board UUID |
+| `ORG_ID` | — | Organization UUID (used in all board-scoped URLs) |
+| `BASE_URL` | — | Base URL, e.g. `http://localhost:3000` |
+
+Every API call in every skill must include these headers:
+```
+x-token: <TOKEN>
+x-board-id: <BOARD_ID>
+x-user-id: <skill-name>   ← set by each skill individually
+```
+
+All board-scoped URLs follow the pattern: `<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/...`
+
+---
+
+## Step 0 — Check for inline parameters
+
+Before reading the config file, scan the prompt/arguments that invoked this skill for inline overrides. Supported formats:
+
+| Pattern | Example |
+|---------|---------|
+| `board=<uuid>` | `board=05cda19d-d5b8-4b51-ae88-c72f2611548a` |
+| `token=<uuid>` | `token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
+| `org=<uuid>` | `org=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
+| `baseUrl=<url>` | `baseUrl=http://localhost:3000` |
+
+If an inline `board=<uuid>` is found, use it as `BOARD_ID` — **it takes priority over the config file**. Same for `token`, `org`, and `baseUrl`. Record which values came from inline params so they are not overwritten in Step 3.
+
+---
+
+## Step 1 — Read config file
+
+Search for `.eventmodelers/config.json` starting from the current working directory and walking up through all parent directories:
+
+```bash
+dir="$PWD"
+config_file=""
+while [ "$dir" != "/" ]; do
+  if [ -f "$dir/.eventmodelers/config.json" ]; then
+    config_file="$dir/.eventmodelers/config.json"
+    break
+  fi
+  dir="$(dirname "$dir")"
+done
+[ -n "$config_file" ] && cat "$config_file"
+```
+
+If a file is found (at any level), note its path and extract any values **not already set by Step 0**:
+- `token` → `TOKEN`
+- `boardId` → `BOARD_ID`
+- `organizationId` → `ORG_ID`
+- `baseUrl` → `BASE_URL` (default: `https://api.eventmodelers.ai` if missing)
+
+Resolution priority: **inline param > config file > ask user**
+
+If all four are present (from any source), skip to **Step 4 — Verify**.
+
+---
+
+## Step 2 — Ask for missing values
+
+If after Steps 0 and 1 any required field is still missing, **ask the user one question first**:
+
+> "Do you have a config from the eventmodelers accounts page? (yes / no)"
+
+**If the user answers yes:**
+Stop asking questions. Show this hint and wait for them to paste:
+
+> "Great — please paste your config from https://app.eventmodelers.ai/account here."
+
+When they paste a JSON object, parse it immediately — accept both `orgId` and `organizationId` as the organization field — apply all values, and proceed directly to Step 3.
+
+**If the user answers no** (or pastes only a partial config), ask for each still-missing field one at a time, in this order: `token`, then `boardId`, then `orgId`. Wait for the answer before asking the next.
+
+| Field | What to ask |
+|-------|-------------|
+| `token` | "Please provide your eventmodelers API token (a UUID from your workspace settings)." |
+| `boardId` | "Please provide the board ID you want to work with (the UUID from the board URL)." |
+| `orgId` | "Please provide your organization ID (the UUID from your organization settings)." |
+| `baseUrl` | Do **not** ask — default to `https://api.eventmodelers.ai` silently. |
+
+Where to find the token: users generate API tokens in their workspace settings at the eventmodelers platform. The token is shown only once at creation time. It is a UUID and must belong to the same organization as the board.
+
+---
+
+## Step 3 — Persist config
+
+Once all values are collected, write the config file. When writing, merge with any existing config — do **not** overwrite fields that were provided as inline params with values from a previous config (the inline param is the user's explicit intent for this session, but the persisted value should reflect the most recently user-supplied value):
+
+```bash
+mkdir -p .eventmodelers
+cat > .eventmodelers/config.json << 'EOF'
+{
+  "token": "<TOKEN>",
+  "boardId": "<BOARD_ID>",
+  "orgId": "<ORG_ID>",
+  "baseUrl": "<BASE_URL>"
+}
+EOF
+```
+
+Then ensure `.eventmodelers/config.json` is in `.gitignore`. Check whether it is already present:
+
+```bash
+grep -q ".eventmodelers/config.json" .gitignore 2>/dev/null || echo "MISSING"
+```
+
+If `MISSING`, append it:
+
+```bash
+echo ".eventmodelers/config.json" >> .gitignore
+```
+
+Tell the user: `"Config saved to .eventmodelers/config.json and added to .gitignore."`
+
+---
+
+## Step 4 — Verify
+
+Confirm the token and board are valid with a lightweight call:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" \
+  -H "x-token: <TOKEN>" \
+  -H "x-board-id: <BOARD_ID>" \
+  -H "x-user-id: connect-skill" \
+  "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes?type=CHAPTER"
+```
+
+| Response | Action |
+|----------|--------|
+| `200` | Config is valid. Print one line: `"Connected — board <BOARD_ID>"` and return. |
+| `401` | Token is invalid or missing. Tell the user and re-run from Step 2, clearing `token`. |
+| `403` | Token organization does not match board. Tell the user to check that the token was issued for the correct workspace. Re-run from Step 2 for both fields. |
+| `404` | Board not found. Tell the user and re-run from Step 2, clearing `boardId`. |
+| Any other | Print the status code and raw response. Ask the user how to proceed. |
+
+---
+
+## Config file format
+
+`.eventmodelers/config.json`:
+```json
+{
+  "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "boardId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "orgId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "baseUrl": "http://localhost:3000"
+}
+```
+
+The `token` field is a secret. It is never logged or shown after initial confirmation.
+
+---
+
+## Security notes
+
+- The config file is workspace-local and gitignored — never commit it.
+- The token grants write access to all boards in its organization — treat it like a password.
+- If a skill receives a `401` or `403` mid-session, re-invoke this skill to refresh the config before retrying.