eventmodeler 0.6.0 → 0.6.2

package/dist/slices/guide/guides/information-flow.js

@@ -1,304 +0,0 @@
-export const meta = {
-    name: 'information-flow',
-    description: 'Design fields, map data between elements, update properties, and check completeness',
-};
-export const content = `
-# Information Flow: Fields, Mappings, and Completeness
-
-This guide covers the full lifecycle of information in an event model: designing fields, adding them to elements, mapping data between connected elements, updating field properties, and verifying completeness.
-
----
-
-## Designing Read Models
-
-Read models are projections of event data - views that serve specific screens or use cases. Every field in a read model should trace back to event fields.
-
-### Understand the Context
-\`\`\`bash
-# Look at the slice containing the read model
-eventmodeler show slice "<slice-name>"
-
-# Check current completeness - what's missing?
-eventmodeler show completeness "<read-model-name>"
-
-# See what events feed into this read model
-eventmodeler list events
-\`\`\`
-
-### Design the Fields
-Based on the use case, identify what fields are needed:
-- **Identity fields** - IDs to identify the entity
-- **Display fields** - What the user sees
-- **Status fields** - Current state
-- **Computed fields** - Aggregations, counts, derived values
-- **Timestamp fields** - When things happened
-
-### Propose Before Adding
-\`\`\`
-I suggest these fields for the OrderHistory read model:
-- orderId (UUID) - identifies the order
-- customerId (UUID) - who placed it
-- status (String) - current status: pending, shipped, delivered, cancelled
-- total (Decimal) - order total
-- placedAt (DateTime) - when it was placed
-- lastUpdatedAt (DateTime) - when status last changed
-
-Does this look right?
-\`\`\`
-
-## Adding Fields
-
-Field types: \`UUID\`, \`String\`, \`Int\`, \`Long\`, \`Double\`, \`Decimal\`, \`Boolean\`, \`Date\`, \`DateTime\`, \`Custom\`
-
-\`\`\`bash
-# Add a simple field
-eventmodeler add field "OrderSummary" '{"name": "orderId", "type": "UUID"}'
-
-# Add an optional field
-eventmodeler add field "OrderSummary" '{"name": "cancelledAt", "type": "DateTime", "isOptional": true}'
-
-# Add a list field
-eventmodeler add field "OrderSummary" '{"name": "itemIds", "type": "UUID", "isList": true}'
-
-# Add a complex/nested field
-eventmodeler add field "OrderSummary" '{"name": "shippingAddress", "type": "Custom", "subfields": [
-  {"name": "street", "type": "String"},
-  {"name": "city", "type": "String"},
-  {"name": "postalCode", "type": "String"}
-]}'
-\`\`\`
-
-**CRITICAL: Custom fields MUST contain subfields.** A Custom field without subfields is invalid.
-
-### Lists and Custom Types
-
-**List of custom objects** - combine \`"type": "Custom"\` with \`"isList": true\`:
-\`\`\`bash
-eventmodeler add field "OrderSummary" '{"name": "lineItems", "type": "Custom", "isList": true, "subfields": [
-  {"name": "productId", "type": "UUID"},
-  {"name": "productName", "type": "String"},
-  {"name": "quantity", "type": "Int"},
-  {"name": "unitPrice", "type": "Decimal"}
-]}'
-\`\`\`
-
-**Nested custom types** - subfields can themselves be Custom:
-\`\`\`bash
-eventmodeler add field "OrderSummary" '{"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"}
-  ]}
-]}'
-\`\`\`
-
----
-
-## Mapping Fields on Flows
-
-Field mappings define how data flows from source elements to target elements. When you connect an Event to a ReadModel with a flow, the field mappings specify which event fields populate which read model fields.
-
-### Command Syntax
-
-\`\`\`bash
-eventmodeler map fields --from "<source>" --to "<target>" '[{"from": "sourceField", "to": "targetField"}]'
-\`\`\`
-
-Or with multiple mappings:
-
-\`\`\`bash
-eventmodeler map fields --from "OrderPlaced" --to "OrderSummary" '[
-  {"from": "orderId", "to": "orderId"},
-  {"from": "customerId", "to": "customerId"},
-  {"from": "totalAmount", "to": "total"}
-]'
-\`\`\`
-
-### Source/Target Formats
-
-The \`--from\` and \`--to\` arguments accept:
-
-1. **Element name** (most common): \`"OrderPlaced"\`
-2. **Element ID prefix** (for duplicates): \`"id:abc12345"\`
-
-### Workflow
-
-1. **Find flows needing mappings**: \`eventmodeler show model-completeness\`
-2. **See source fields**: \`eventmodeler show event "OrderPlaced"\`
-3. **See target fields**: \`eventmodeler show completeness "OrderSummary"\`
-4. **Create mappings**: \`eventmodeler map fields --from "OrderPlaced" --to "OrderSummary" '[...]'\`
-5. **Verify**: \`eventmodeler show completeness "OrderSummary"\`
-
-### Mapping Nested Fields
-
-For Custom (nested) field types, use dot notation:
-
-\`\`\`bash
-eventmodeler map fields --from "OrderPlaced" --to "OrderSummary" '[
-  {"from": "shippingAddress.street", "to": "deliveryAddress.street"},
-  {"from": "shippingAddress.city", "to": "deliveryAddress.city"},
-  {"from": "shippingAddress.postalCode", "to": "deliveryAddress.zip"}
-]'
-\`\`\`
-
-### Multiple Flows to Same Target
-
-A read model often receives data from multiple events. Map each flow separately:
-
-\`\`\`bash
-# Initial data from OrderPlaced
-eventmodeler map fields --from "OrderPlaced" --to "OrderSummary" '[
-  {"from": "orderId", "to": "orderId"},
-  {"from": "customerId", "to": "customerId"},
-  {"from": "totalAmount", "to": "total"}
-]'
-
-# Status updates from OrderShipped
-eventmodeler map fields --from "OrderShipped" --to "OrderSummary" '[
-  {"from": "shippedAt", "to": "shippedDate"},
-  {"from": "trackingNumber", "to": "trackingNumber"}
-]'
-\`\`\`
-
-### Updating Existing Mappings
-
-Running \`map fields\` again **merges** with existing mappings:
-- New mappings are added
-- If a target field already has a mapping, it's replaced with the new source
-
-### Common Mapping Patterns
-
-| Pattern | Example |
-|---------|---------|
-| Identity | \`{"from": "orderId", "to": "orderId"}\` |
-| Rename | \`{"from": "totalAmount", "to": "total"}\` |
-| Nested to flat | \`{"from": "customer.id", "to": "customerId"}\` |
-| Flat to nested | \`{"from": "street", "to": "address.street"}\` |
-
----
-
-## Updating Field Properties
-
-Use \`update field\` to modify field attributes without changing the field's name or structure.
-
-### Command Syntax
-
-\`\`\`bash
-eventmodeler update field <element-name> --field "<field-name>" [options]
-\`\`\`
-
-### Available Options
-
-| Option | Values | Description |
-|--------|--------|-------------|
-| \`--optional\` | \`true\`/\`false\` | Mark field as not required for completeness |
-| \`--generated\` | \`true\`/\`false\` | Mark field as system-generated (not from user input) |
-| \`--user-input\` | \`true\`/\`false\` | Mark field as user-provided (screens only) |
-| \`--type\` | Field type | Change the field's data type |
-
-### Examples
-
-\`\`\`bash
-# Mark a field as optional
-eventmodeler update field "OrderPlaced" --field "promoCode" --optional true
-
-# Mark a field as system-generated
-eventmodeler update field "OrderPlaced" --field "orderId" --generated true
-
-# Mark screen fields as user input
-eventmodeler update field "Checkout" --field "email" --user-input true
-
-# Change a field's type
-eventmodeler update field "OrderSummary" --field "total" --type Decimal
-
-# Combine multiple updates
-eventmodeler update field "UserRegistered" --field "createdAt" --generated true --optional false
-\`\`\`
-
-### Updating Nested Fields
-
-Use dot notation for fields inside Custom types:
-
-\`\`\`bash
-eventmodeler update field "OrderPlaced" --field "shippingAddress.postalCode" --optional true
-\`\`\`
-
-### Field Property Meanings
-
-**isOptional**: Field may not always have a value. Completeness checks don't require this field to have a mapping source.
-
-**isGenerated**: Field is system-generated, not derived from other fields. Completeness checks don't require this field to have a mapping source. Use for: IDs, timestamps, sequence numbers, computed values.
-
-**isUserInput** (screens only): Field comes from user input on the screen. Identifies which screen fields are inputs vs. display-only.
-
----
-
-## Removing Fields
-
-\`\`\`bash
-# Remove a field from an event
-eventmodeler remove field "OrderPlaced" --field "legacyId"
-
-# Remove a field from a read model
-eventmodeler remove field "OrderSummary" --field "deprecatedStatus"
-
-# Remove a nested field using dot notation
-eventmodeler remove field "OrderPlaced" --field "metadata.debugInfo"
-\`\`\`
-
-**Caution**: Removing a field may break existing field mappings. Check completeness first:
-\`\`\`bash
-eventmodeler show completeness "<element-name>"
-\`\`\`
-
----
-
-## Checking Completeness
-
-### Check a Specific Element
-\`\`\`bash
-eventmodeler show completeness "<name>"
-\`\`\`
-Shows incoming flows and which fields are satisfied vs unsatisfied.
-
-### Check the Entire Model
-\`\`\`bash
-eventmodeler show model-completeness
-\`\`\`
-Project-wide view: complete count, incomplete count, and all incomplete flows with their unsatisfied fields.
-
-### Check Aggregate ID Fields
-\`\`\`bash
-eventmodeler show aggregate-completeness "<aggregate-name>"
-\`\`\`
-
----
-
-## Common Mistakes
-
-- **Creating empty Custom fields**: Custom fields MUST have subfields.
-  - Wrong: \`{"name": "address", "type": "Custom"}\`
-  - Right: \`{"name": "address", "type": "Custom", "subfields": [{"name": "street", "type": "String"}, ...]}\`
-
-- **Using "List" as a field 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\`
-  - Right: \`"isOptional": true\`, \`"isGenerated": true\`, \`"isList": true\`
-
-## Best Practices
-
-1. **Get approval before adding fields** - Propose the design, let the user confirm
-2. **Consider all source events** - A read model may need data from multiple events
-3. **Use appropriate types** - \`Decimal\` for money, \`DateTime\` for timestamps
-4. **Mark optional fields** - Fields that may not always have values (e.g., \`cancelledAt\`)
-5. **Mark generated fields early** - When creating slices, immediately mark IDs and timestamps as generated
-6. **Map all fields at once** - More efficient than one mapping at a time
-7. **Verify after mapping** - Run \`show completeness\` to confirm all fields are satisfied
-8. **Check mappings before removing** - Removing a field can break existing mappings
-`;

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

@@ -1,214 +0,0 @@
-export const meta = {
-    name: 'scenarios',
-    description: 'Design Given-When-Then scenarios for slices: happy paths, errors, automations',
-};
-export const content = `
-# Designing Scenarios for Slices
-
-Scenarios define the behavior of a slice. There are two main scenario patterns:
-
-1. **State-Change Scenarios** (for state-change slices): Given events → When command → Then events/error
-2. **Automation Scenarios** (for automation slices): Given events → Then command (simpler Given-Then format)
-
-## Your Workflow
-
-When helping design scenarios for a slice:
-
-### 1. Gather Context
-\`\`\`bash
-# Look at the slice to understand its components
-eventmodeler show slice "<slice-name>"
-
-# See what chapter it belongs to and nearby slices for context
-eventmodeler list chapters
-eventmodeler show chapter "<chapter-name>"
-
-# List all events to understand what's available for Given clauses
-eventmodeler list events
-\`\`\`
-
-### 2. Identify the Slice Type
-
-**State-Change Slice** (Screen → Command → Event):
-- User triggers a command
-- Command produces event(s)
-- Use: Given → When command → Then events/error
-
-**Automation Slice** (ReadModel → Processor → Command → Event):
-- Events trigger the processor to issue a command
-- Use simpler Given → Then format (no When)
-- Given: All events that lead to the trigger condition
-- Then: The command that should be dispatched (or noCommand)
-
-### 3. Design Scenarios by Type
-
----
-
-## State-Change Scenarios
-
-For slices where a user action triggers a command:
-
-**Happy Path** - The command succeeds under normal conditions
-- Given: Any required preconditions (existing events)
-- When: The command with valid input
-- Then: The expected event(s) with field values
-
-**Validation Errors** - Bad input is rejected
-- Given: (may be empty)
-- When: Command with invalid input
-- Then: Error with message
-
-**Business Rule Violations** - Valid input but rule prevents action
-- Given: Events that create a state where the action isn't allowed
-- When: The command
-- Then: Error explaining why
-
-### State-Change Examples
-
-\`\`\`bash
-# Happy path - command succeeds
-eventmodeler add scenario --slice "<slice-name>" '{
-  "name": "Successfully place order",
-  "description": "A registered customer can place an order with valid items",
-  "given": [
-    {"event": "CustomerRegistered", "fieldValues": {"customerId": "cust-123"}}
-  ],
-  "when": {
-    "command": "PlaceOrder",
-    "commandFieldValues": {"customerId": "cust-123", "items": [{"productId": "prod-1", "quantity": 2}]}
-  },
-  "then": {
-    "type": "events",
-    "events": [
-      {"event": "OrderPlaced", "fieldValues": {"orderId": "order-456", "customerId": "cust-123"}}
-    ]
-  }
-}'
-\`\`\`
-
-\`\`\`bash
-# Validation error
-eventmodeler add scenario --slice "<slice-name>" '{
-  "name": "Cannot place empty order",
-  "description": "Orders must contain at least one item - empty item lists are rejected",
-  "when": {
-    "command": "PlaceOrder",
-    "commandFieldValues": {"customerId": "cust-123", "items": []}
-  },
-  "then": {
-    "type": "error",
-    "errorType": "ValidationError",
-    "errorMessage": "Order must contain at least one item"
-  }
-}'
-\`\`\`
-
-\`\`\`bash
-# Business rule violation
-eventmodeler add scenario --slice "Cancel Order" '{
-  "name": "Cannot cancel shipped order",
-  "description": "Once an order has been shipped, it can no longer be cancelled",
-  "given": [
-    {"event": "OrderPlaced", "fieldValues": {"orderId": "order-123"}},
-    {"event": "OrderShipped", "fieldValues": {"orderId": "order-123", "shippedAt": "2024-01-15T10:00:00Z"}}
-  ],
-  "when": {
-    "command": "CancelOrder",
-    "commandFieldValues": {"orderId": "order-123"}
-  },
-  "then": {
-    "type": "error",
-    "errorType": "BusinessRuleViolation",
-    "errorMessage": "Cannot cancel an order that has already shipped"
-  }
-}'
-\`\`\`
-
----
-
-## Automation Scenarios
-
-For slices where events trigger a processor to issue a command. Use the simpler **Given-Then** format:
-
-**Trigger Conditions Met** - Events cause processor to act
-- Given: All the events that have occurred (including the trigger events)
-- Then: The command the processor issues
-
-**Trigger Conditions Not Met** - Events don't cause action
-- Given: Events that don't meet the trigger condition
-- Then: noCommand (processor should not dispatch)
-
-### Automation Examples
-
-\`\`\`bash
-# Payment received triggers shipment initiation
-eventmodeler add scenario --slice "Auto Ship Order" '{
-  "name": "Payment triggers shipment",
-  "description": "Given an order has been placed and payment received, the system automatically initiates shipment",
-  "given": [
-    {"event": "OrderPlaced", "fieldValues": {"orderId": "order-123", "customerId": "cust-456"}},
-    {"event": "PaymentReceived", "fieldValues": {"orderId": "order-123", "amount": 99.99}}
-  ],
-  "then": {
-    "type": "command",
-    "command": "InitiateShipment",
-    "commandFieldValues": {"orderId": "order-123", "warehouseId": "wh-001"}
-  }
-}'
-\`\`\`
-
-\`\`\`bash
-# Negative case - conditions not met, no command dispatched
-eventmodeler add scenario --slice "Auto Ship Order" '{
-  "name": "No shipment without payment",
-  "description": "Given only an order placed (no payment), the system should not initiate shipment",
-  "given": [
-    {"event": "OrderPlaced", "fieldValues": {"orderId": "order-123", "customerId": "cust-456"}}
-  ],
-  "then": {
-    "type": "noCommand"
-  }
-}'
-\`\`\`
-
----
-
-## Read Model Assertions
-
-For state-view slices, test that events project correctly to read models:
-
-\`\`\`bash
-eventmodeler add scenario --slice "<slice-name>" '{
-  "name": "Order appears in summary",
-  "description": "After placing an order, it should be visible in the order summary with pending status",
-  "given": [
-    {"event": "OrderPlaced", "fieldValues": {"orderId": "order-456", "customerId": "cust-123", "status": "pending"}}
-  ],
-  "then": {
-    "type": "readModelAssertion",
-    "readModel": "OrderSummary",
-    "expected": {"orderId": "order-456", "status": "pending"}
-  }
-}'
-\`\`\`
-
----
-
-## Scenario Types Summary
-
-| Slice Type | Format | Then Contains |
-|------------|--------|---------------|
-| State-Change | Given → When (Command) → Then | Events or Error |
-| Automation | Given (Events) → Then | Command or noCommand |
-| State-View | Given → Then | Read Model Assertion |
-
-## Best Practices
-
-1. **Write clear descriptions** - Explain why this scenario matters and what business rule it captures
-2. **Use realistic example values** - "cust-123" not "string", "2024-01-15" not "date"
-3. **Name scenarios descriptively** - "Cannot cancel shipped order" not "Error case 1"
-4. **Include all relevant fields** - Don't skip fields that matter for the scenario
-5. **Think about state** - What events need to exist for this scenario to make sense?
-6. **Cover the negative cases** - These often reveal missing business rules (use \`noCommand\` for automations)
-7. **Match format to slice type** - Use Given-When-Then for state-change, Given-Then for automation
-`;

package/dist/slices/guide/index.js

@@ -1,40 +0,0 @@
-import { meta as exploreMeta, content as exploreContent } from './guides/explore';
-import { meta as scenariosMeta, content as scenariosContent } from './guides/scenarios';
-import { meta as informationFlowMeta, content as informationFlowContent } from './guides/information-flow';
-import { meta as createSlicesMeta, content as createSlicesContent } from './guides/create-slices';
-import { meta as connectSlicesMeta, content as connectSlicesContent } from './guides/connect-slices';
-import { meta as codegenMeta, content as codegenContent } from './guides/codegen';
-const GUIDES = [
-    { meta: exploreMeta, content: exploreContent },
-    { meta: createSlicesMeta, content: createSlicesContent },
-    { meta: connectSlicesMeta, content: connectSlicesContent },
-    { meta: informationFlowMeta, content: informationFlowContent },
-    { meta: scenariosMeta, content: scenariosContent },
-    { meta: codegenMeta, content: codegenContent },
-];
-export function runGuide(subcommand) {
-    if (!subcommand) {
-        printGuideList();
-        return;
-    }
-    const guide = GUIDES.find(g => g.meta.name === subcommand);
-    if (!guide) {
-        console.error(`Unknown guide: ${subcommand}`);
-        console.error(`Run "eventmodeler guide" to see available guides.`);
-        process.exit(1);
-    }
-    console.log(guide.content);
-}
-function printGuideList() {
-    console.log(`
-eventmodeler guide - Conceptual guides for working with event models
-
-USAGE:
-  eventmodeler guide <name>
-
-AVAILABLE GUIDES:
-${GUIDES.map(g => `  ${g.meta.name.padEnd(20)} ${g.meta.description}`).join('\n')}
-
-Run "eventmodeler guide <name>" to read a guide.
-`);
-}

package/dist/slices/help/index.js

@@ -1,96 +0,0 @@
-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
-`);
-}