eventmodeler 0.5.0 → 0.6.0

package/dist/slices/help/index.js

@@ -0,0 +1,96 @@
+import { meta as exploreModelMeta, content as exploreModelContent } from './topics/explore-model';
+import { meta as buildSliceMeta, content as buildSliceContent } from './topics/build-slice';
+import { meta as connectSlicesMeta, content as connectSlicesContent } from './topics/connect-slices';
+import { meta as writeScenariosMeta, content as writeScenariosContent } from './topics/write-scenarios';
+import { meta as manipulateCanvasMeta, content as manipulateCanvasContent } from './topics/manipulate-canvas';
+import { meta as linkedCopiesMeta, content as linkedCopiesContent } from './topics/linked-copies';
+import { meta as checkCompletenessMeta, content as checkCompletenessContent } from './topics/check-completeness';
+import { meta as jsonReferenceMeta, content as jsonReferenceContent } from './topics/json-reference';
+import { meta as buildCodegenMeta, content as buildCodegenContent } from './topics/build-codegen';
+const TOPICS = [
+    { meta: exploreModelMeta, content: exploreModelContent },
+    { meta: buildSliceMeta, content: buildSliceContent },
+    { meta: connectSlicesMeta, content: connectSlicesContent },
+    { meta: writeScenariosMeta, content: writeScenariosContent },
+    { meta: manipulateCanvasMeta, content: manipulateCanvasContent },
+    { meta: linkedCopiesMeta, content: linkedCopiesContent },
+    { meta: checkCompletenessMeta, content: checkCompletenessContent },
+    { meta: jsonReferenceMeta, content: jsonReferenceContent },
+    { meta: buildCodegenMeta, content: buildCodegenContent },
+];
+export function runHelp(query) {
+    if (!query) {
+        printTopicIndex();
+        return;
+    }
+    // Exact name match
+    const exact = TOPICS.find(t => t.meta.name === query);
+    if (exact) {
+        console.log(exact.content);
+        return;
+    }
+    // Fuzzy keyword match
+    const matches = fuzzyMatch(query);
+    if (matches.length === 0) {
+        console.error(`No help topics matched: "${query}"`);
+        console.error(`Run "eventmodeler help" to see all topics.`);
+        process.exit(1);
+    }
+    if (matches.length === 1) {
+        console.log(matches[0].topic.content);
+        return;
+    }
+    console.log(`\nMultiple topics matched "${query}":\n`);
+    for (const m of matches) {
+        console.log(`  ${m.topic.meta.name.padEnd(24)} ${m.topic.meta.description}  (${m.score} keyword hits)`);
+    }
+    console.log(`\nRun "eventmodeler help <topic-name>" to read one.\n`);
+}
+function fuzzyMatch(query) {
+    const words = query.toLowerCase().split(/\s+/).filter(w => w.length > 0);
+    if (words.length === 0)
+        return [];
+    const scored = [];
+    for (const topic of TOPICS) {
+        let score = 0;
+        const allKeywords = topic.meta.keywords.map(k => k.toLowerCase());
+        const nameWords = topic.meta.name.toLowerCase().split('-');
+        const descWords = topic.meta.description.toLowerCase().split(/\s+/);
+        const searchable = [...allKeywords, ...nameWords, ...descWords];
+        for (const word of words) {
+            for (const kw of searchable) {
+                if (kw === word) {
+                    score += 2;
+                    break;
+                }
+                else if (kw.startsWith(word) || word.startsWith(kw)) {
+                    score += 1;
+                    break;
+                }
+            }
+        }
+        if (score > 0) {
+            scored.push({ topic, score });
+        }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, 5);
+}
+function printTopicIndex() {
+    console.log(`
+eventmodeler help - Task-oriented help for the Event Modeler CLI
+
+USAGE:
+  eventmodeler help <topic>        Show a specific topic
+  eventmodeler help <search words>  Search topics by keyword
+
+TOPICS:
+${TOPICS.map(t => `  ${t.meta.name.padEnd(24)} ${t.meta.description}`).join('\n')}
+
+EXAMPLES:
+  eventmodeler help build-slice
+  eventmodeler help json
+  eventmodeler help place move canvas
+  eventmodeler help scenario given when then
+`);
+}

package/dist/slices/help/topics/build-codegen.js

@@ -0,0 +1,109 @@
+export const meta = {
+    name: 'build-codegen',
+    keywords: ['codegen', 'generator', 'generate', 'code', 'export', 'template', 'scaffold', 'boilerplate', 'loop', 'ralph', 'ai', 'agent', 'automation', 'pipeline', 'show', 'model', 'slice', 'chapter', 'context', 'schema', 'shape', 'response'],
+    description: 'Build a code generator that consumes show-* outputs to scaffold a slice',
+};
+export const content = `
+# Building a Code Generator
+
+WHEN TO USE: You want to turn an event model into code — REST endpoints,
+handlers, projections, tests, whatever your stack uses. The CLI gives you
+JSON; you own the template.
+
+## The input surface
+
+The CLI is the export layer. These four commands emit JSON that a code
+generator can consume:
+
+  eventmodeler show model              # whole model, all elements
+  eventmodeler show context <name>     # one bounded context + its chapters + slices
+  eventmodeler show chapter <name>     # one chapter + its slices
+  eventmodeler show slice <name>       # one slice: elements, fields, flows, scenarios
+
+Pick the grain that fits what you generate. Most generators work at the
+slice level — one slice maps to one vertical feature's worth of code.
+
+## Response shapes
+
+Every show-* command documents its exact response schema in its own --help:
+
+  eventmodeler show model --help
+  eventmodeler show context --help
+  eventmodeler show chapter --help
+  eventmodeler show slice --help
+  eventmodeler show event --help          # same shape for command/readmodel/screen/processor/external-event
+  eventmodeler show completeness --help
+
+The schemas include every field, all enum values, and the nested types
+(ElementView, FieldView, FlowView, ScenarioView, etc.). Read them before
+writing templates — don't guess.
+
+## Minimum viable pipeline
+
+  # 1. Fetch one slice as JSON
+  eventmodeler show slice "Place Order" > slice.json
+
+  # 2. Read it in any language — it's just JSON matching the shapes above
+  # 3. Render your templates (one per elementType is a common split)
+  # 4. Write files into your target project
+
+A good generator is idempotent: running it twice produces the same output.
+Use the slice name or ID as the stable key.
+
+## Ralph loop — driving generation from the model
+
+The "loop" command polls for slices marked "planned" and runs your script
+against each one. Combined with your codegen, you get a closed loop: mark
+a slice "planned" in the UI, and the generator picks it up.
+
+Config (.eventmodeler.json):
+
+  {
+    "loop": {
+      "command": "./generate.sh",
+      "interval": 30
+    }
+  }
+
+Run:
+
+  eventmodeler loop
+
+The loop doesn't touch slice status — your script does. A typical
+generate.sh:
+
+  #!/usr/bin/env bash
+  set -e
+  SLICE="$1"
+
+  eventmodeler mark "$SLICE" in-progress
+
+  eventmodeler show slice "$SLICE" > /tmp/slice.json
+  ./render-templates.sh /tmp/slice.json || {
+    eventmodeler mark "$SLICE" blocked
+    exit 1
+  }
+
+  eventmodeler mark "$SLICE" done
+
+If the script crashes before marking anything, the slice stays "planned"
+and the next poll retries it.
+
+## Good generator patterns
+
+- One template per elementType (screen, command, event, readmodel, processor).
+- Use the slice's flows to decide wiring — flows tell you which handler
+  emits which event and which projection reads which event.
+- Scenarios map naturally to test cases: Given = fixture, When = command
+  invocation, Then = assertion.
+- Treat the model as the source of truth. Don't hand-edit generated files
+  — regenerate.
+- Skip elements with "linkedCopy": true during codegen — they're visual
+  proxies and the real element lives in another slice.
+
+## Related
+
+  eventmodeler help explore-model       # how to navigate a model
+  eventmodeler help json-reference      # write-command input shapes
+  eventmodeler loop --help              # loop flags and script contract
+`;

package/dist/slices/help/topics/build-slice.js

@@ -0,0 +1,147 @@
+export const meta = {
+    name: 'build-slice',
+    keywords: ['build', 'create', 'slice', 'new', 'add', 'field', 'subfield', 'element', 'command', 'event', 'readmodel', 'screen', 'processor', 'type', 'custom', 'UUID', 'String', 'Int', 'Boolean', 'state-change', 'automation', 'state-view'],
+    description: 'Build a complete slice from scratch with elements, fields, and flows',
+};
+export const content = `
+# Building a Slice from Scratch
+
+WHEN TO USE: You need to create a new vertical feature slice with its elements, fields, and flows.
+
+## Slice Types
+
+STATE-CHANGE:  Screen -> Command -> Event                    (user action)
+AUTOMATION:    ReadModel -> Processor -> Command -> Event    (system reaction)
+STATE-VIEW:    ReadModel (fed by events from other slices)   (query/projection)
+
+## Task: Create a slice with elements and flows in one command
+
+COMMAND:
+  eventmodeler create slice '<json>'
+
+EXAMPLE:
+  eventmodeler create slice '{
+    "sliceName": "Place Order",
+    "elements": [
+      {"id": "a1b2c3d4-0001-0000-0000-000000000001", "type": "screen", "name": "OrderForm", "fields": [
+        {"name": "customerId", "type": "UUID"},
+        {"name": "items", "type": "Custom", "isList": true, "subfields": [
+          {"name": "productId", "type": "UUID"},
+          {"name": "quantity", "type": "Int"}
+        ]}
+      ]},
+      {"id": "a1b2c3d4-0001-0000-0000-000000000002", "type": "command", "name": "PlaceOrder", "fields": [
+        {"name": "orderId", "type": "UUID", "isGenerated": true},
+        {"name": "customerId", "type": "UUID"},
+        {"name": "items", "type": "Custom", "isList": true, "subfields": [
+          {"name": "productId", "type": "UUID"},
+          {"name": "quantity", "type": "Int"}
+        ]}
+      ]},
+      {"id": "a1b2c3d4-0001-0000-0000-000000000003", "type": "event", "name": "OrderPlaced", "fields": [
+        {"name": "orderId", "type": "UUID"},
+        {"name": "customerId", "type": "UUID"},
+        {"name": "placedAt", "type": "DateTime", "isGenerated": true}
+      ]}
+    ],
+    "flows": [
+      {"id": "f1000000-0000-0000-0000-000000000001", "from": "OrderForm", "to": "PlaceOrder"},
+      {"id": "f1000000-0000-0000-0000-000000000002", "from": "PlaceOrder", "to": "OrderPlaced"}
+    ]
+  }'
+
+NOTES:
+  - The JSON is a positional argument (not a --json flag)
+  - Every element and flow needs a unique UUID
+  - Valid flow pairs: screen->command, command->event, command->external-event,
+    event->readmodel, readmodel->screen, readmodel->processor, processor->command,
+    external-event->processor
+  - "from" and "to" reference element names within the slice
+  - Layout is auto-calculated from Y bands and X spacing
+
+## Task: Place individual elements (alternative to create slice)
+
+COMMAND:
+  eventmodeler create place <type> <name> --x <n> --y <n>
+
+EXAMPLES:
+  eventmodeler create place screen "OrderForm" --x 2040 --y 120
+  eventmodeler create place command "PlaceOrder" --x 2040 --y 460
+  eventmodeler create place event "OrderPlaced" --x 2040 --y 860
+
+NOTES:
+  - See "help manipulate-canvas" for Y band positions and spacing rules
+  - Use this when adding elements to an existing slice or building incrementally
+
+## Task: Add a field to an existing element
+
+COMMAND:
+  eventmodeler add field [elementName] '<json>'
+  eventmodeler --id <uuid> add field '<json>'
+
+EXAMPLES:
+  eventmodeler add field "PlaceOrder" '{"name": "email", "type": "String"}'
+  eventmodeler add field "OrderPlaced" '{"name": "orderId", "type": "UUID", "isGenerated": true}'
+  eventmodeler add field "PlaceOrder" '{"name": "address", "type": "Custom", "subfields": [
+    {"name": "street", "type": "String"},
+    {"name": "city", "type": "String"},
+    {"name": "zip", "type": "String"}
+  ]}'
+
+FIELD TYPES:
+  UUID, String, Int, Long, Double, Decimal, Boolean, Date, DateTime, Custom
+
+FIELD ATTRIBUTES (add to the JSON, all optional):
+  "isOptional": true    — field may be absent
+  "isGenerated": true   — system-generated (IDs, timestamps)
+  "isList": true        — array of this type
+  "isUserInput": true   — provided by user (screens only)
+
+CUSTOM TYPE RULES:
+  - Custom fields MUST have "subfields" array — empty Custom is invalid
+  - Subfields can themselves be Custom (arbitrary nesting)
+  - Combine with "isList": true for arrays of objects
+
+## Task: Add a subfield to an existing Custom field
+
+COMMAND:
+  eventmodeler add subfield [elementName] '{"name": "country", "type": "String"}' --field "address"
+
+NOTES:
+  - --field identifies the parent field by name
+  - Parent field must be type "Custom"
+
+## Task: Remove a field
+
+COMMAND:
+  eventmodeler remove field [elementName] --field <fieldName>
+
+EXAMPLE:
+  eventmodeler remove field "OrderPlaced" --field "legacyId"
+
+## Task: Update a field (rename, change type, mark flags)
+
+COMMAND:
+  eventmodeler update field [elementName] --field <name> [--name <new>] [--type <new>] [--optional true|false] [--generated true|false] [--list true|false] [--user-input true|false]
+
+EXAMPLES:
+  eventmodeler update field "OrderPlaced" --field "total" --type Decimal
+  eventmodeler update field "OrderPlaced" --field "promoCode" --optional true
+  eventmodeler update field "Checkout" --field "email" --user-input true
+
+## Task: Update a subfield (rename, change type)
+
+COMMAND:
+  eventmodeler update subfield [elementName] --subfield <subfieldId> [--name <new>] [--type <new>]
+
+NOTES:
+  - Subfield ID comes from show output (not the field name)
+
+## Task: Reorder a field
+
+COMMAND:
+  eventmodeler update reorder [elementName] --field <name> --position <n>
+
+EXAMPLE:
+  eventmodeler update reorder "OrderPlaced" --field "orderId" --position 0
+`;

package/dist/slices/help/topics/check-completeness.js

@@ -0,0 +1,57 @@
+export const meta = {
+    name: 'check-completeness',
+    keywords: ['completeness', 'missing', 'unsatisfied', 'incomplete', 'mapping', 'field', 'flow', 'aggregate', 'model', 'health', 'check', 'validate'],
+    description: 'Find and fix missing field mappings and incomplete flows',
+};
+export const content = `
+# Checking Completeness
+
+WHEN TO USE: You need to verify that all fields are properly mapped across flows.
+
+## Task: Check completeness of a specific element
+
+COMMANDS:
+  eventmodeler show completeness "<name>"
+  eventmodeler show completeness --id "<uuid>"
+
+EXAMPLE:
+  eventmodeler show completeness "OrderSummary"
+
+NOTES:
+  - Auto-detects element type (command, event, readmodel, screen, processor)
+  - Shows: incoming flows, satisfied fields, unsatisfied fields
+  - An unsatisfied field has no source mapping from any incoming flow
+
+## Task: Check completeness of the entire model
+
+COMMANDS:
+  eventmodeler show model-completeness
+
+NOTES:
+  - Returns: complete count, incomplete count, total
+  - Lists all incomplete flows with their unsatisfied fields
+  - Use this as a health check after making changes
+
+## Task: Check aggregate ID field consistency
+
+COMMANDS:
+  eventmodeler show aggregate-completeness "<aggregateName>"
+
+EXAMPLE:
+  eventmodeler show aggregate-completeness "Order"
+
+NOTES:
+  - Checks if all events in the aggregate have the aggregate's ID field
+  - Events missing the aggregate ID field are flagged
+
+## Fixing Incomplete Flows
+
+STRATEGY:
+  1. Run: eventmodeler show model-completeness
+  2. For each incomplete flow, check what fields are missing
+  3. Either:
+     a. Add the missing field to the source element:
+        eventmodeler add field "SourceElement" '{"name": "missingField", "type": "String"}'
+     b. Map an existing source field to the target field:
+        eventmodeler map fields '[{"source": "existingField", "target": "missingField"}]' --from "Source" --to "Target"
+`;

package/dist/slices/help/topics/connect-slices.js

@@ -0,0 +1,99 @@
+export const meta = {
+    name: 'connect-slices',
+    keywords: ['connect', 'flow', 'wire', 'link', 'map', 'mapping', 'field', 'between', 'cross-slice', 'inbound', 'outbound', 'from', 'to', 'remove', 'mapping'],
+    description: 'Wire slices together with flows and field mappings',
+};
+export const content = `
+# Connecting Slices with Flows and Field Mappings
+
+WHEN TO USE: You need to wire elements together within or across slices.
+
+## Task: Create a flow between two elements
+
+COMMAND:
+  eventmodeler create flow --from <sourceName> --to <targetName>
+
+EXAMPLES:
+  eventmodeler create flow --from "OrderPlaced" --to "OrderSummary"
+  eventmodeler create flow --from "OrderForm" --to "PlaceOrder"
+  eventmodeler create flow --from "OrderSummary" --to "Order Details Screen"
+
+VALID FLOW PAIRS:
+  screen       -> command
+  command      -> event
+  command      -> external-event
+  event        -> readmodel
+  readmodel    -> screen
+  readmodel    -> processor
+  processor    -> command
+  external-event -> processor
+
+NOTES:
+  - Flows can connect elements within the same slice or across slices
+  - The CLI auto-detects the flow type from the source/target element types
+  - Use --id for source/target when elements share names (linked copies)
+
+## Task: Map fields on a flow
+
+COMMAND:
+  eventmodeler map fields '<json>' --from <sourceName> --to <targetName>
+
+EXAMPLE:
+  eventmodeler map fields '[
+    {"source": "orderId", "target": "orderId"},
+    {"source": "customerId", "target": "customerId"},
+    {"source": "totalAmount", "target": "total"}
+  ]' --from "OrderPlaced" --to "OrderSummary"
+
+MAPPINGS JSON:
+  [ { "source": "sourceFieldName", "target": "targetFieldName" } ]
+
+NOTES:
+  - Source and target are field names on the respective elements
+  - You can map fields with different names (e.g., source "userId" -> target "customerId")
+  - Unmapped fields show up as incomplete in completeness checks
+  - Run multiple map commands to add mappings incrementally
+
+## Task: Remove a specific field mapping
+
+COMMAND:
+  eventmodeler remove mapping --from <sourceName> --to <targetName> --mapping <mappingId>
+
+NOTES:
+  - Mapping IDs are visible in show slice output (flow mappings section)
+
+## Task: Remove a flow entirely
+
+COMMAND:
+  eventmodeler remove flow --from <sourceName> --to <targetName>
+
+## Task: View existing flows
+
+COMMANDS:
+  eventmodeler show slice "Place Order"     (shows all flows + field mappings)
+  eventmodeler show event "OrderPlaced"     (shows cross-cutting flow connections)
+  eventmodeler show completeness            (shows which fields are unmapped)
+
+## Typical Workflow: Connect Slice A's event to Slice B's readmodel
+
+1. Check what events Slice A produces:
+     eventmodeler show slice "Place Order"
+
+2. Check what readmodel Slice B has:
+     eventmodeler show slice "View Order"
+
+3. If the event needs to appear in Slice B, create a linked copy:
+     eventmodeler create place-copy event "OrderPlaced" --x 3000 --y 860
+
+4. Create the flow:
+     eventmodeler create flow --from "OrderPlaced" --to "OrderHistory"
+
+5. Map the fields:
+     eventmodeler map fields '[
+       {"source": "orderId", "target": "orderId"},
+       {"source": "customerId", "target": "customerId"}
+     ]' --from "OrderPlaced" --to "OrderHistory"
+
+6. Verify completeness:
+     eventmodeler show completeness
+`;

package/dist/slices/help/topics/explore-model.js

@@ -0,0 +1,112 @@
+export const meta = {
+    name: 'explore-model',
+    keywords: ['explore', 'list', 'show', 'search', 'summary', 'navigate', 'query', 'overview', 'inspect', 'detail', 'slice', 'chapter', 'event', 'command', 'readmodel', 'screen', 'processor', 'aggregate', 'actor', 'scenario', 'status', 'mark'],
+    description: 'Navigate, query, and understand an existing event model',
+};
+export const content = `
+# Exploring an Event Model
+
+WHEN TO USE: You have an existing model and need to understand what's in it.
+
+## Task: Get a high-level overview
+
+COMMANDS:
+  eventmodeler summary
+
+NOTES:
+  - Returns counts of all element types (slices, events, commands, etc.)
+
+## Task: List all slices
+
+COMMANDS:
+  eventmodeler list slices
+  eventmodeler list slices --chapter "User Onboarding"
+
+NOTES:
+  - Each slice is a vertical feature with status: created, in-progress, blocked, done
+  - --chapter filters to slices within that chapter
+
+## Task: List elements by type
+
+COMMANDS:
+  eventmodeler list events
+  eventmodeler list commands
+  eventmodeler list readmodels
+  eventmodeler list screens
+  eventmodeler list processors
+  eventmodeler list scenarios
+  eventmodeler list aggregates
+  eventmodeler list actors
+  eventmodeler list chapters
+
+NOTES:
+  - All list commands output JSON
+
+## Task: Search for something by name
+
+COMMANDS:
+  eventmodeler search "order"
+
+NOTES:
+  - Searches across all entity names: slices, events, commands, read models, aggregates, actors
+
+## Task: Inspect a specific slice
+
+COMMANDS:
+  eventmodeler show slice "Place Order"
+
+NOTES:
+  - Returns: components (screens, commands, events, readmodels, processors), flows, fields, scenarios
+  - Shows inbound flows (external elements flowing INTO this slice) and outbound flows (flowing OUT)
+  - Scenarios define the slice's behavior as Given-When-Then test cases
+
+## Task: Inspect a specific element
+
+COMMANDS:
+  eventmodeler show event "OrderPlaced"
+  eventmodeler show command "PlaceOrder"
+  eventmodeler show readmodel "OrderSummary"
+  eventmodeler show screen "OrderForm"
+  eventmodeler show processor "NotifyCustomer"
+  eventmodeler show aggregate "Order"
+  eventmodeler show scenario "Successfully place order"
+  eventmodeler show chapter "Order Management"
+  eventmodeler show actor "Customer"
+
+NOTES:
+  - show event/command: fields, connections, containing slice
+  - show readmodel: fields, source events, consumers
+  - show screen: fields, source readmodels, triggered commands
+  - show processor: fields, source readmodels, triggered commands
+  - show aggregate: ID field, contained events
+  - show scenario: full Given-When-Then with field values
+  - show chapter: contained slices, inter-slice flow graph, external dependencies
+  - show actor: associated screens
+
+## Task: Use --id to target a specific element by UUID
+
+COMMANDS:
+  eventmodeler show event --id "550e8400-e29b-41d4-a716-446655440000"
+
+NOTES:
+  - Skips name resolution, targets element by UUID directly
+  - Essential when multiple elements share the same name (linked copies)
+  - Works on all name-based commands
+
+## Task: Mark a slice's status
+
+COMMANDS:
+  eventmodeler mark "Place Order" in-progress
+  eventmodeler mark "Place Order" done
+  eventmodeler mark "Place Order" blocked
+  eventmodeler mark "Place Order" created
+
+## Exploration strategy
+
+1. eventmodeler summary              -> understand scale
+2. eventmodeler list slices           -> what features exist?
+3. eventmodeler list chapters         -> how are features organized?
+4. eventmodeler show slice "<name>"   -> how does one feature work?
+5. Read the scenarios                 -> what does it actually do?
+6. eventmodeler search "<term>"       -> find related elements
+`;