eventmodeler 0.6.0 → 0.6.2

package/dist/slices/guide/guides/create-slices.js

@@ -1,273 +0,0 @@
-export const meta = {
-    name: 'create-slices',
-    description: 'Understand slice types, fields, and how to build slices with flows',
-};
-export const content = `
-# Understanding Slices
-
-There are three slice types in an event model. Each represents a different pattern of data flow.
-
----
-
-## State-Change Slices
-
-A state-change slice represents a **user-initiated action** that changes system state:
-
-\`\`\`
-Screen → Command → Event
-\`\`\`
-
-- **Screen**: The UI where the user initiates the action
-- **Command**: The intent/request to change state
-- **Event**: The fact that state changed
-
-### When to Use
-
-Use state-change slices when:
-- A user performs an action (clicks a button, submits a form)
-- That action changes the state of an entity
-- Examples: "Place Order", "Cancel Subscription", "Update Profile", "Add Item to Cart"
-
-### Building a State-Change Slice
-
-To build a state-change slice, you add the individual elements and connect them with flows:
-
-1. Add a screen, a command, and an event (using \`add field\` to define their fields)
-2. Create flows: Screen → Command, Command → Event
-3. Map the fields on each flow
-
-### Example: Place Order Slice
-
-First, add fields to each element:
-\`\`\`bash
-eventmodeler add field "Checkout Screen" '{"name": "customerId", "type": "UUID"}'
-eventmodeler add field "Checkout Screen" '{"name": "items", "type": "String", "isUserInput": true}'
-eventmodeler add field "Checkout Screen" '{"name": "shippingAddress", "type": "String", "isUserInput": true}'
-
-eventmodeler add field "PlaceOrder" '{"name": "customerId", "type": "UUID"}'
-eventmodeler add field "PlaceOrder" '{"name": "items", "type": "String"}'
-eventmodeler add field "PlaceOrder" '{"name": "shippingAddress", "type": "String"}'
-
-eventmodeler add field "OrderPlaced" '{"name": "orderId", "type": "UUID", "isGenerated": true}'
-eventmodeler add field "OrderPlaced" '{"name": "customerId", "type": "UUID"}'
-eventmodeler add field "OrderPlaced" '{"name": "items", "type": "String"}'
-eventmodeler add field "OrderPlaced" '{"name": "shippingAddress", "type": "String"}'
-eventmodeler add field "OrderPlaced" '{"name": "placedAt", "type": "DateTime", "isGenerated": true}'
-\`\`\`
-
-Then connect with flows:
-\`\`\`bash
-eventmodeler create flow --from "Checkout Screen" --to "PlaceOrder"
-eventmodeler create flow --from "PlaceOrder" --to "OrderPlaced"
-\`\`\`
-
-Then map fields on the flows:
-\`\`\`bash
-eventmodeler map fields --from "PlaceOrder" --to "OrderPlaced" '[
-  {"from": "customerId", "to": "customerId"},
-  {"from": "items", "to": "items"},
-  {"from": "shippingAddress", "to": "shippingAddress"}
-]'
-\`\`\`
-
----
-
-## Automation Slices
-
-An automation slice represents a **system-initiated action**:
-
-\`\`\`
-ReadModel → Processor → Command → Event
-\`\`\`
-
-- **ReadModel**: The state/data the processor needs to make decisions
-- **Processor**: The system component that decides when and how to act
-- **Command**: The intent/request to change state
-- **Event**: The fact that state changed
-
-### When to Use
-
-Use automation slices when:
-- The system automatically responds to events
-- No direct user interaction triggers the action
-- Examples: "Auto-assign Reviewer", "Send Reminder Email", "Calculate Shipping", "Process Payment"
-
-### Building an Automation Slice
-
-1. Add a read model, processor, command, and event with their fields
-2. Create internal flows: ReadModel → Processor, Processor → Command, Command → Event
-3. Connect external events to the read model with flows
-
-### Example: Auto-Fulfill Order
-
-\`\`\`bash
-eventmodeler add field "OrderReadyForFulfillment" '{"name": "orderId", "type": "UUID"}'
-eventmodeler add field "OrderReadyForFulfillment" '{"name": "isPaid", "type": "Boolean"}'
-eventmodeler add field "OrderReadyForFulfillment" '{"name": "shippingAddress", "type": "String"}'
-
-eventmodeler add field "FulfillOrder" '{"name": "orderId", "type": "UUID"}'
-eventmodeler add field "FulfillOrder" '{"name": "warehouseId", "type": "UUID", "isGenerated": true}'
-
-eventmodeler add field "OrderFulfilled" '{"name": "orderId", "type": "UUID"}'
-eventmodeler add field "OrderFulfilled" '{"name": "warehouseId", "type": "UUID"}'
-eventmodeler add field "OrderFulfilled" '{"name": "fulfilledAt", "type": "DateTime", "isGenerated": true}'
-\`\`\`
-
-Connect internal flows:
-\`\`\`bash
-eventmodeler create flow --from "OrderReadyForFulfillment" --to "Order Fulfillment Processor"
-eventmodeler create flow --from "Order Fulfillment Processor" --to "FulfillOrder"
-eventmodeler create flow --from "FulfillOrder" --to "OrderFulfilled"
-\`\`\`
-
-### Connecting Trigger Events
-
-Connect external events to the automation's read model:
-
-\`\`\`bash
-eventmodeler create flow --from "OrderPlaced" --to "OrderReadyForFulfillment"
-eventmodeler create flow --from "PaymentReceived" --to "OrderReadyForFulfillment"
-\`\`\`
-
-### Automation vs State-View Read Models
-
-| Automation ReadModel | State-View ReadModel |
-|---------------------|---------------------|
-| Inside automation slice | Standalone slice |
-| Feeds a Processor | Feeds a Screen |
-| "What the processor needs" | "What the user sees" |
-
----
-
-## State-View Slices
-
-A state-view slice represents a **read model** - a projection of event data for querying:
-
-\`\`\`
-Read Model (fed by events)
-\`\`\`
-
-### When to Use
-
-Use state-view slices when:
-- You need to display data to users
-- A processor needs to query current state
-- You want to aggregate data from multiple events
-- Examples: "Order Summary", "User Dashboard", "Inventory Levels", "Account Balance"
-
-### Building a State-View Slice
-
-1. Add the read model with its fields
-2. Create flows from events to the read model
-3. Map the fields on each flow
-
-### Example: Order Summary View
-
-\`\`\`bash
-eventmodeler add field "OrderSummary" '{"name": "orderId", "type": "UUID"}'
-eventmodeler add field "OrderSummary" '{"name": "customerId", "type": "UUID"}'
-eventmodeler add field "OrderSummary" '{"name": "customerName", "type": "String"}'
-eventmodeler add field "OrderSummary" '{"name": "status", "type": "String"}'
-eventmodeler add field "OrderSummary" '{"name": "totalAmount", "type": "Decimal"}'
-eventmodeler add field "OrderSummary" '{"name": "itemCount", "type": "Int"}'
-eventmodeler add field "OrderSummary" '{"name": "placedAt", "type": "DateTime"}'
-eventmodeler add field "OrderSummary" '{"name": "lastUpdatedAt", "type": "DateTime"}'
-\`\`\`
-
-### Connecting Events After Creation
-
-To complete the picture:
-
-1. Create flows from events: \`eventmodeler create flow --from "EventName" --to "ReadModelName"\`
-2. Map fields: \`eventmodeler map fields --from "EventName" --to "ReadModelName" '[...]'\`
-3. Verify: \`eventmodeler show completeness "ReadModelName"\`
-
----
-
-## Field Types
-
-\`UUID\`, \`String\`, \`Int\`, \`Long\`, \`Double\`, \`Decimal\`, \`Boolean\`, \`Date\`, \`DateTime\`, \`Custom\`
-
-## Field Attributes
-
-- \`"isOptional": true\` - Field may not have a value
-- \`"isGenerated": true\` - System-generated (e.g., IDs, timestamps), not from user input
-- \`"isUserInput": true\` - Entered by the user on the screen
-- \`"isList": true\` - Field is a list/array of the specified type
-
-## Working with Lists and Custom Types
-
-**List of primitives** - use \`"isList": true\` with any valid type:
-\`\`\`json
-{"name": "tags", "type": "String", "isList": true}
-{"name": "quantities", "type": "Int", "isList": true}
-\`\`\`
-
-### Custom Types (Nested Objects)
-
-**CRITICAL: Custom fields MUST contain subfields.** The \`"type": "Custom"\` indicates a nested object structure, and the \`"subfields"\` array defines its properties. A Custom field without subfields is invalid and creates an empty, useless type.
-
-**Custom type with nested fields:**
-\`\`\`json
-{"name": "address", "type": "Custom", "subfields": [
-  {"name": "street", "type": "String"},
-  {"name": "city", "type": "String"},
-  {"name": "postalCode", "type": "String"}
-]}
-\`\`\`
-
-**List of custom objects** - combine \`"type": "Custom"\` with \`"isList": true\`:
-\`\`\`json
-{"name": "lineItems", "type": "Custom", "isList": true, "subfields": [
-  {"name": "productId", "type": "UUID"},
-  {"name": "quantity", "type": "Int"},
-  {"name": "unitPrice", "type": "Decimal"}
-]}
-\`\`\`
-
-**Nested custom types** - subfields can themselves be Custom types:
-\`\`\`json
-{"name": "customer", "type": "Custom", "subfields": [
-  {"name": "customerId", "type": "UUID"},
-  {"name": "name", "type": "String"},
-  {"name": "billingAddress", "type": "Custom", "subfields": [
-    {"name": "street", "type": "String"},
-    {"name": "city", "type": "String"},
-    {"name": "country", "type": "String"}
-  ]}
-]}
-\`\`\`
-
-## Common Mistakes
-
-- **Creating empty Custom fields**: Custom fields MUST have subfields that define their structure.
-  - Wrong: \`{"name": "address", "type": "Custom"}\`
-  - Right: \`{"name": "address", "type": "Custom", "subfields": [{"name": "street", "type": "String"}, ...]}\`
-
-- **Using "List" as a field type**: "List" is not a valid type. Use \`"isList": true\` with a valid type instead.
-  - Wrong: \`{"name": "items", "type": "List"}\`
-  - Right: \`{"name": "items", "type": "String", "isList": true}\`
-
-- **Using wrong attribute names**: Always use camelCase attributes.
-  - Wrong: \`"optional": true\`, \`"generated": true\`, \`"list": true\`, \`"user-input": true\`
-  - Right: \`"isOptional": true\`, \`"isGenerated": true\`, \`"isList": true\`, \`"isUserInput": true\`
-
-## Workflow
-
-1. **Understand the action** - What is the user/system trying to do?
-2. **Design the fields** - What information flows through this slice?
-3. **Propose before creating** - Get approval on the design first
-4. **Create the elements and flows** - Add fields and connect with flows
-5. **Verify** - \`eventmodeler show slice "<name>"\`
-6. **Connect** - Create flows to/from other slices as needed
-
-## Best Practices
-
-1. **Get approval first** - Propose the design before creating
-2. **Use meaningful names** - Slice name should describe the action ("Place Order" not "Order Slice")
-3. **Include generated fields** - Events should have IDs and timestamps
-4. **Match field names** - Same names enable automatic mapping
-5. **Consider what's user input vs system data** - Mark appropriately
-6. **Name automation read models for their purpose** - "OrderReadyForFulfillment" not "OrderData"
-7. **Name processors descriptively** - "Order Fulfillment Processor" not just "Processor"
-`;

package/dist/slices/guide/guides/explore.js

@@ -1,238 +0,0 @@
-export const meta = {
-    name: 'explore',
-    description: 'Navigate and query an event model: list, show, search, completeness',
-};
-export const content = `
-# Exploring Event Models with the CLI
-
-The \`eventmodeler\` CLI lets you query and explore event models linked to your project.
-
-## Getting an Overview
-
-**Start here** to understand the model:
-
-\`\`\`bash
-eventmodeler summary
-\`\`\`
-Shows statistics: total slices, events, commands, read models, etc.
-
-\`\`\`bash
-eventmodeler list slices
-\`\`\`
-Lists all slices with their status (created, in-progress, blocked, done). Slices represent vertical features.
-
-\`\`\`bash
-eventmodeler list slices --chapter "<name>"
-\`\`\`
-Lists only slices within a specific chapter.
-
-\`\`\`bash
-eventmodeler list chapters
-\`\`\`
-Lists chapters - timeline sections that group slices.
-
-## Listing Elements
-
-\`\`\`bash
-eventmodeler list events      # All events in the model
-eventmodeler list commands    # All commands in the model
-eventmodeler list readmodels  # All read models
-eventmodeler list screens     # All screens
-eventmodeler list processors  # All processors
-eventmodeler list scenarios   # All scenarios
-eventmodeler list aggregates  # All aggregates (event groupings)
-eventmodeler list actors      # All actors (user/system roles)
-\`\`\`
-
-All \`list\` commands output JSON.
-
-## Searching
-
-\`\`\`bash
-eventmodeler search "<term>"
-\`\`\`
-Searches across all entity names: slices, events, commands, read models, aggregates, and actors.
-
-## Drilling Into Details
-
-### Show a Slice
-\`\`\`bash
-eventmodeler show slice "<name>"
-\`\`\`
-Returns JSON with:
-- All components in the slice (screens, commands, events, read-models, processors)
-- **Flow annotations** on each component showing incoming and outgoing connections
-- Fields on each component with types and attributes
-- Information flow (which components connect to which)
-- **Inbound flows**: External elements flowing INTO this slice (with field mappings)
-- **Outbound flows**: Elements in this slice flowing OUT to other slices (with field mappings)
-- Scenarios (Given-When-Then test cases)
-
-The inbound/outbound flows show cross-slice dependencies - crucial for understanding how a slice integrates with the rest of the system.
-
-**Scenarios are key** - they define the slice's behavior and give it context. A slice's scenarios show:
-- **Given**: What events have already occurred (the starting state)
-- **When**: What command is being executed with what field values
-- **Then**: The expected outcome - either:
-  - Events that should be produced
-  - An error that should occur
-  - A read model assertion (expected state)
-
-Example scenario in slice output:
-\`\`\`json
-{
-  "scenarios": [
-    {
-      "name": "Successfully place order",
-      "given": [
-        { "event": "CustomerRegistered", "fieldValues": { "customerId": "123" } }
-      ],
-      "when": {
-        "command": "PlaceOrder",
-        "commandFieldValues": { "customerId": "123", "items": ["..."] }
-      },
-      "then": {
-        "type": "events",
-        "events": [
-          { "event": "OrderPlaced", "fieldValues": { "orderId": "456", "customerId": "123" } }
-        ]
-      }
-    },
-    {
-      "name": "Cannot place order without items",
-      "when": {
-        "command": "PlaceOrder",
-        "commandFieldValues": { "customerId": "123", "items": [] }
-      },
-      "then": {
-        "type": "error",
-        "errorType": "ValidationError",
-        "errorMessage": "Order must contain at least one item"
-      }
-    }
-  ]
-}
-\`\`\`
-
-Reading scenarios helps understand:
-- What preconditions the slice expects
-- What inputs the command accepts
-- What the happy path looks like
-- What error cases are handled
-
-### Show an Event or Command
-\`\`\`bash
-eventmodeler show event "<name>"
-eventmodeler show command "<name>"
-\`\`\`
-Returns JSON with the element's fields and connections.
-
-### Show Read Models, Screens, and Processors
-\`\`\`bash
-eventmodeler show readmodel "<name>"
-eventmodeler show screen "<name>"
-eventmodeler show processor "<name>"
-\`\`\`
-Use these for detailed flow context:
-- \`show readmodel\`: fields, source events, and who consumes it
-- \`show screen\`: fields, source read models, and triggered commands
-- \`show processor\`: fields, source read models, and triggered commands
-
-### Show Aggregate and Scenario
-\`\`\`bash
-eventmodeler show aggregate "<name>"
-eventmodeler show scenario "<name>"
-\`\`\`
-- \`show aggregate\`: aggregate ID configuration and contained events
-- \`show scenario\`: complete Given-When-Then with field values
-
-### Show a Chapter
-\`\`\`bash
-eventmodeler show chapter "<name>"
-\`\`\`
-Shows the chapter with:
-- All slices within the chapter
-- **Flow graph**: How slices connect to each other (which events flow to which read models, etc.) with field mappings
-- **External dependencies**:
-  - Inbound: Flows from outside the chapter into slices within it
-  - Outbound: Flows from slices in this chapter to elements outside it
-
-Use \`show chapter\` to understand the relationships between slices in a feature area. Use \`list slices --chapter\` for a simple list without flow details.
-
-### Show an Actor
-\`\`\`bash
-eventmodeler show actor "<name>"
-\`\`\`
-Shows the actor and lists all screens associated with it.
-
-## Managing Slice Status
-
-Slices have a status that tracks their progress: \`created\`, \`in-progress\`, \`blocked\`, \`done\`.
-
-\`\`\`bash
-# Mark a slice as in progress
-eventmodeler mark "Place Order" in-progress
-
-# Mark a slice as done
-eventmodeler mark "Place Order" done
-
-# Mark a slice as blocked
-eventmodeler mark "Place Order" blocked
-
-# Reset to created
-eventmodeler mark "Place Order" created
-\`\`\`
-
-Use \`list slices\` to see current statuses.
-
-## Checking Information Completeness
-
-Information completeness tracks whether fields flow correctly between connected elements.
-
-### Check a Specific Element
-\`\`\`bash
-eventmodeler show completeness "<name>"
-\`\`\`
-Auto-detects the element type (command, event, read model, screen, or processor) and shows:
-- Incoming flows to that element
-- Which fields are satisfied (have a source)
-- Which fields are unsatisfied (missing a source)
-
-### Check the Entire Model
-\`\`\`bash
-eventmodeler show model-completeness
-\`\`\`
-Project-wide view of all information flows:
-- Summary: complete count, incomplete count, total
-- Lists all incomplete flows with their unsatisfied fields
-
-### Check Aggregate ID Fields
-\`\`\`bash
-eventmodeler show aggregate-completeness "<aggregate-name>"
-\`\`\`
-Checks if all events in an aggregate have the aggregate's ID field.
-
-## Exploration Strategy
-
-When exploring an unfamiliar event model:
-
-1. **Get the big picture**: \`eventmodeler summary\` → understand scale
-2. **See the features**: \`eventmodeler list slices\` → what does this system do?
-3. **Understand organization**: \`eventmodeler list chapters\` → how is it structured over time?
-4. **Dive into a slice**: \`eventmodeler show slice "<name>"\` → how does one feature work?
-5. **Read the scenarios**: They tell you what the slice actually does, its preconditions, and edge cases
-6. **Search for specifics**: \`eventmodeler search "<term>"\` → find related elements
-
-When checking model health:
-1. **Overall completeness**: \`eventmodeler show model-completeness\` → any broken flows?
-2. **Specific element**: \`eventmodeler show completeness "<name>"\` → what's missing here?
-3. **Aggregate consistency**: \`eventmodeler show aggregate-completeness "<name>"\` → ID fields present?
-
-When looking for something specific:
-- Know the feature name? → \`show slice\`
-- Know an event name? → \`show event\` or \`search\`
-- Know a read model/screen/processor name? → \`show readmodel\` / \`show screen\` / \`show processor\`
-- Need scenario details? → \`list scenarios\` then \`show scenario\`
-- Want all events? → \`list events\`
-- Checking data flow? → \`show completeness\` or \`show model-completeness\`
-`;