eventmodeler 0.5.0 → 0.6.1

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

@@ -1,269 +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>" --xml '<scenario name="Successfully place order" description="A registered customer can place an order with valid items">
-  <given>
-    <event name="CustomerRegistered">
-      <field name="customerId">cust-123</field>
-    </event>
-  </given>
-  <when>
-    <command name="PlaceOrder">
-      <field name="customerId">cust-123</field>
-      <field name="items">[{"productId": "prod-1", "quantity": 2}]</field>
-    </command>
-  </when>
-  <then type="events">
-    <event name="OrderPlaced">
-      <field name="orderId">order-456</field>
-      <field name="customerId">cust-123</field>
-    </event>
-  </then>
-</scenario>'
-\`\`\`
-
-\`\`\`bash
-# Validation error
-eventmodeler add scenario --slice "<slice-name>" --xml '<scenario name="Cannot place empty order" description="Orders must contain at least one item - empty item lists are rejected">
-  <when>
-    <command name="PlaceOrder">
-      <field name="customerId">cust-123</field>
-      <field name="items">[]</field>
-    </command>
-  </when>
-  <then type="error" errorType="ValidationError">Order must contain at least one item</then>
-</scenario>'
-\`\`\`
-
-\`\`\`bash
-# Business rule violation
-eventmodeler add scenario --slice "Cancel Order" --xml '<scenario name="Cannot cancel shipped order" description="Once an order has been shipped, it can no longer be cancelled">
-  <given>
-    <event name="OrderPlaced">
-      <field name="orderId">order-123</field>
-    </event>
-    <event name="OrderShipped">
-      <field name="orderId">order-123</field>
-      <field name="shippedAt">2024-01-15T10:00:00Z</field>
-    </event>
-  </given>
-  <when>
-    <command name="CancelOrder">
-      <field name="orderId">order-123</field>
-    </command>
-  </when>
-  <then type="error" errorType="BusinessRuleViolation">Cannot cancel an order that has already shipped</then>
-</scenario>'
-\`\`\`
-
----
-
-## 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
-# Given: OrderPlaced + PaymentReceived → Then: InitiateShipment command
-eventmodeler add scenario --slice "Auto Ship Order" --xml '<scenario name="Payment triggers shipment" description="Given an order has been placed and payment received, the system automatically initiates shipment">
-  <given>
-    <event name="OrderPlaced">
-      <field name="orderId">order-123</field>
-      <field name="customerId">cust-456</field>
-    </event>
-    <event name="PaymentReceived">
-      <field name="orderId">order-123</field>
-      <field name="amount">99.99</field>
-    </event>
-  </given>
-  <then type="command">
-    <command name="InitiateShipment">
-      <field name="orderId">order-123</field>
-      <field name="warehouseId">wh-001</field>
-    </command>
-  </then>
-</scenario>'
-\`\`\`
-
-\`\`\`bash
-# Negative case - conditions not met, no command dispatched
-eventmodeler add scenario --slice "Auto Ship Order" --xml '<scenario name="No shipment without payment" description="Given only an order placed (no payment), the system should not initiate shipment">
-  <given>
-    <event name="OrderPlaced">
-      <field name="orderId">order-123</field>
-      <field name="customerId">cust-456</field>
-    </event>
-  </given>
-  <then type="noCommand"/>
-</scenario>'
-\`\`\`
-
----
-
-## Read Model Assertions
-
-For state-view slices, test that events project correctly to read models:
-
-\`\`\`bash
-eventmodeler add scenario --slice "<slice-name>" --xml '<scenario name="Order appears in summary" description="After placing an order, it should be visible in the order summary with pending status">
-  <then type="readModelAssertion">
-    <read-model name="OrderSummary">
-      <field name="orderId">order-456</field>
-      <field name="status">pending</field>
-    </read-model>
-  </then>
-</scenario>'
-\`\`\`
-
----
-
-## 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 |
-
-## JSON Format Alternative
-
-You can also use JSON format:
-
-**State-Change Scenario:**
-\`\`\`bash
-eventmodeler add scenario --slice "<slice-name>" --json '{
-  "name": "Successfully place order",
-  "description": "A registered customer can place an order",
-  "given": [
-    { "event": "CustomerRegistered", "fieldValues": { "customerId": "cust-123" } }
-  ],
-  "when": {
-    "command": "PlaceOrder",
-    "commandFieldValues": { "customerId": "cust-123", "items": [] }
-  },
-  "then": {
-    "type": "events",
-    "events": [
-      { "event": "OrderPlaced", "fieldValues": { "orderId": "order-456" } }
-    ]
-  }
-}'
-\`\`\`
-
-**Automation Scenario (Given-Then format):**
-\`\`\`bash
-eventmodeler add scenario --slice "<slice-name>" --json '{
-  "name": "Payment triggers shipment",
-  "description": "Given order placed and payment received, shipment is initiated",
-  "given": [
-    { "event": "OrderPlaced", "fieldValues": { "orderId": "order-123" } },
-    { "event": "PaymentReceived", "fieldValues": { "orderId": "order-123", "amount": 99.99 } }
-  ],
-  "then": {
-    "type": "command",
-    "command": "InitiateShipment",
-    "commandFieldValues": { "orderId": "order-123" }
-  }
-}'
-\`\`\`
-
-**Automation Scenario (negative case):**
-\`\`\`bash
-eventmodeler add scenario --slice "<slice-name>" --json '{
-  "name": "No shipment without payment",
-  "description": "Given only order placed (no payment), no command dispatched",
-  "given": [
-    { "event": "OrderPlaced", "fieldValues": { "orderId": "order-123" } }
-  ],
-  "then": {
-    "type": "noCommand"
-  }
-}'
-\`\`\`
-
-## 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.d.ts

@@ -1 +0,0 @@
-export declare function runGuide(subcommand: string | undefined): void;

package/dist/slices/guide/index.js

@@ -1,40 +0,0 @@
-import { meta as exploreMeta, content as exploreContent } from './guides/explore.js';
-import { meta as scenariosMeta, content as scenariosContent } from './guides/scenarios.js';
-import { meta as informationFlowMeta, content as informationFlowContent } from './guides/information-flow.js';
-import { meta as createSlicesMeta, content as createSlicesContent } from './guides/create-slices.js';
-import { meta as connectSlicesMeta, content as connectSlicesContent } from './guides/connect-slices.js';
-import { meta as codegenMeta, content as codegenContent } from './guides/codegen.js';
-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/import/index.d.ts

@@ -1,8 +0,0 @@
-export interface ImportOptions {
-    name?: string;
-}
-/**
- * Import a .eventmodel file to the cloud backend.
- * Creates a new cloud model with a fresh modelId.
- */
-export declare function importModel(filePath: string, options?: ImportOptions): Promise<void>;

package/dist/slices/import/index.js

@@ -1,63 +0,0 @@
-import * as path from 'node:path';
-import * as crypto from 'node:crypto';
-import { loadRawEvents } from '../../lib/file-loader.js';
-import { createCloudClient } from '../../lib/cloud-client.js';
-import { isAuthenticated } from '../../lib/config.js';
-/**
- * Import a .eventmodel file to the cloud backend.
- * Creates a new cloud model with a fresh modelId.
- */
-export async function importModel(filePath, options = {}) {
-    // 1. Validate authentication
-    if (!isAuthenticated()) {
-        console.error('Not authenticated. Run "eventmodeler login" first.');
-        process.exit(1);
-    }
-    // 2. Load and validate file
-    const absolutePath = path.resolve(filePath);
-    console.log(`Loading events from: ${absolutePath}`);
-    let events;
-    try {
-        events = loadRawEvents(absolutePath);
-    }
-    catch (error) {
-        console.error(`Failed to load file: ${error instanceof Error ? error.message : error}`);
-        process.exit(1);
-    }
-    if (events.length === 0) {
-        console.error('File contains no events.');
-        process.exit(1);
-    }
-    console.log(`Found ${events.length} events`);
-    // 3. Determine model name
-    const modelName = options.name ?? deriveModelName(filePath, events);
-    // 4. Generate new unique modelId
-    const modelId = crypto.randomUUID();
-    // 5. Filter out any existing EventModelCreated events (we'll create a new one)
-    const filteredEvents = events.filter((e) => e.type !== 'EventModelCreated');
-    // 6. Import to cloud
-    console.log(`Importing as: ${modelName} (${modelId})`);
-    const client = await createCloudClient();
-    try {
-        const result = await client.importModel(modelId, modelName, filteredEvents);
-        console.log(`\nSuccessfully imported ${result.eventCount} events!`);
-        console.log(`Model ID: ${result.modelId}`);
-        console.log(`\nView at: https://eventmodeler.app/model/${result.modelId}`);
-    }
-    catch (error) {
-        console.error(`Import failed: ${error instanceof Error ? error.message : error}`);
-        process.exit(1);
-    }
-}
-/**
- * Derive model name from file or existing EventModelCreated event.
- */
-function deriveModelName(filePath, events) {
-    // Try to extract from existing EventModelCreated event
-    const createEvent = events.find((e) => e.type === 'EventModelCreated');
-    if (createEvent?.data?.name) {
-        return createEvent.data.name;
-    }
-    // Fall back to filename without extension
-    return path.basename(filePath, '.eventmodel');
-}

package/dist/slices/init/index.d.ts

@@ -1,5 +0,0 @@
-/**
- * Interactive init command to set up a project.
- * Connects the current directory to an event model.
- */
-export declare function init(): Promise<void>;

package/dist/slices/init/index.js

@@ -1,80 +0,0 @@
-import * as readline from 'node:readline';
-import { isAuthenticated } from '../../lib/config.js';
-import { listModels } from '../../api/index.js';
-import { saveProjectConfig, getProjectRoot, isInProject } from '../../lib/project-config.js';
-/**
- * Interactive init command to set up a project.
- * Connects the current directory to an event model.
- */
-export async function init() {
-    if (isInProject()) {
-        console.log('This project is already initialized.');
-        console.log('To reconfigure, delete .eventmodeler.json and run init again.');
-        return;
-    }
-    const projectRoot = getProjectRoot();
-    console.log(`Initializing event model project in: ${projectRoot}\n`);
-    if (!isAuthenticated()) {
-        console.log('You need to be logged in first.');
-        console.log('Run "eventmodeler login" first, then try init again.');
-        return;
-    }
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    const question = (prompt) => {
-        return new Promise((resolve) => {
-            rl.question(prompt, (answer) => {
-                resolve(answer.trim());
-            });
-        });
-    };
-    try {
-        console.log('Fetching your event models...\n');
-        const models = await listModels();
-        if (models.length === 0) {
-            console.log('You don\'t have any event models yet.');
-            console.log('Create one at https://eventmodeler.app first, then run init again.');
-            rl.close();
-            return;
-        }
-        console.log('Your event models:\n');
-        models.forEach((model, index) => {
-            console.log(`  ${index + 1}. ${model.name} (${model.modelId})`);
-        });
-        console.log(`  ${models.length + 1}. Create a new model\n`);
-        const modelChoice = await question(`Select a model (1-${models.length + 1}): `);
-        const modelIndex = parseInt(modelChoice, 10) - 1;
-        let selectedModel;
-        if (modelIndex === models.length) {
-            console.log('\nTo create a new model, visit https://eventmodeler.app');
-            console.log('After creating it, run init again to link it to this project.');
-            rl.close();
-            return;
-        }
-        else if (modelIndex >= 0 && modelIndex < models.length) {
-            selectedModel = models[modelIndex];
-        }
-        else {
-            console.log('\nInvalid choice. Please run init again.');
-            rl.close();
-            return;
-        }
-        const config = {
-            type: 'cloud',
-            modelId: selectedModel.modelId,
-            modelName: selectedModel.name,
-        };
-        const configPath = saveProjectConfig(config, projectRoot);
-        console.log(`\nProject initialized successfully!`);
-        console.log(`Config saved to: ${configPath}`);
-        console.log(`\nLinked to model: ${selectedModel.name}`);
-        console.log('\nYou can now use eventmodeler commands in this directory.');
-        rl.close();
-    }
-    catch (err) {
-        rl.close();
-        throw err;
-    }
-}

package/dist/slices/list-chapters/index.d.ts

@@ -1,3 +0,0 @@
-import type { EventModel } from '../../types.js';
-import { type OutputFormat } from '../../lib/format.js';
-export declare function listChapters(model: EventModel, format: OutputFormat): void;

package/dist/slices/list-chapters/index.js

@@ -1,21 +0,0 @@
-import { escapeXml, outputJson } from '../../lib/format.js';
-export function listChapters(model, format) {
-    const chapters = [...model.chapters.values()];
-    // Sort by x position (left to right on timeline)
-    const sorted = [...chapters].sort((a, b) => a.position.x - b.position.x);
-    if (format === 'json') {
-        outputJson({
-            chapters: sorted.map(ch => ({ id: ch.id, name: ch.name }))
-        });
-        return;
-    }
-    if (chapters.length === 0) {
-        console.log('<chapters/>');
-        return;
-    }
-    console.log('<chapters>');
-    for (const chapter of sorted) {
-        console.log(`  <chapter id="${chapter.id}" name="${escapeXml(chapter.name)}"/>`);
-    }
-    console.log('</chapters>');
-}

package/dist/slices/list-commands/index.d.ts

@@ -1,3 +0,0 @@
-import type { EventModel } from '../../types.js';
-import { type OutputFormat } from '../../lib/format.js';
-export declare function listCommands(model: EventModel, format: OutputFormat): void;

package/dist/slices/list-commands/index.js

@@ -1,20 +0,0 @@
-import { escapeXml, outputJson } from '../../lib/format.js';
-export function listCommands(model, format) {
-    const commands = [...model.commands.values()];
-    const sorted = [...commands].sort((a, b) => a.name.localeCompare(b.name));
-    if (format === 'json') {
-        outputJson({
-            commands: sorted.map(cmd => ({ id: cmd.id, name: cmd.name, fields: cmd.fields.length }))
-        });
-        return;
-    }
-    if (commands.length === 0) {
-        console.log('<commands/>');
-        return;
-    }
-    console.log('<commands>');
-    for (const cmd of sorted) {
-        console.log(`  <command id="${cmd.id}" name="${escapeXml(cmd.name)}" fields="${cmd.fields.length}"/>`);
-    }
-    console.log('</commands>');
-}

package/dist/slices/list-events/index.d.ts

@@ -1,3 +0,0 @@
-import type { EventModel } from '../../types.js';
-import { type OutputFormat } from '../../lib/format.js';
-export declare function listEvents(model: EventModel, format: OutputFormat): void;

package/dist/slices/list-events/index.js

@@ -1,98 +0,0 @@
-import { escapeXml, outputJson } from '../../lib/format.js';
-// Find which aggregate an event belongs to (center point inside aggregate bounds)
-function findAggregateForEvent(model, event) {
-    const centerX = event.position.x + event.width / 2;
-    const centerY = event.position.y + event.height / 2;
-    for (const aggregate of model.aggregates.values()) {
-        const bounds = {
-            left: aggregate.position.x,
-            right: aggregate.position.x + aggregate.size.width,
-            top: aggregate.position.y,
-            bottom: aggregate.position.y + aggregate.size.height,
-        };
-        if (centerX >= bounds.left && centerX <= bounds.right && centerY >= bounds.top && centerY <= bounds.bottom) {
-            return aggregate;
-        }
-    }
-    return null;
-}
-// Find which slice contains an event
-function findSliceForEvent(model, event) {
-    for (const slice of model.slices.values()) {
-        const centerX = event.position.x + event.width / 2;
-        const centerY = event.position.y + event.height / 2;
-        if (centerX >= slice.position.x &&
-            centerX <= slice.position.x + slice.size.width &&
-            centerY >= slice.position.y &&
-            centerY <= slice.position.y + slice.size.height) {
-            return slice.name;
-        }
-    }
-    return null;
-}
-export function listEvents(model, format) {
-    const events = [...model.events.values()];
-    // Sort: originals first, then copies; alphabetically within each group
-    const sorted = [...events].sort((a, b) => {
-        // Originals before copies
-        if (!a.originalNodeId && b.originalNodeId)
-            return -1;
-        if (a.originalNodeId && !b.originalNodeId)
-            return 1;
-        // Alphabetically by name
-        return a.name.localeCompare(b.name);
-    });
-    if (format === 'json') {
-        outputJson({
-            events: sorted.map(evt => {
-                const aggregate = findAggregateForEvent(model, evt);
-                const result = {
-                    id: evt.id,
-                    name: evt.name,
-                    fields: evt.fields.length,
-                };
-                if (aggregate)
-                    result.aggregate = aggregate.name;
-                if (evt.originalNodeId) {
-                    result.linkedCopy = true;
-                    const original = model.events.get(evt.originalNodeId);
-                    const originSlice = original ? findSliceForEvent(model, original) : null;
-                    if (originSlice)
-                        result.originSlice = originSlice;
-                }
-                else if (evt.canonicalId) {
-                    const copyCount = [...model.events.values()].filter(e => e.canonicalId === evt.canonicalId && e.originalNodeId).length;
-                    if (copyCount > 0)
-                        result.copies = copyCount;
-                }
-                return result;
-            })
-        });
-        return;
-    }
-    if (events.length === 0) {
-        console.log('<events/>');
-        return;
-    }
-    console.log('<events>');
-    for (const evt of sorted) {
-        const aggregate = findAggregateForEvent(model, evt);
-        const aggregateAttr = aggregate ? ` aggregate="${escapeXml(aggregate.name)}"` : '';
-        if (evt.originalNodeId) {
-            // This is a linked copy - show origin info
-            const original = model.events.get(evt.originalNodeId);
-            const originSlice = original ? findSliceForEvent(model, original) : null;
-            const originAttr = originSlice ? ` origin-slice="${escapeXml(originSlice)}"` : '';
-            console.log(`  <event id="${evt.id}" name="${escapeXml(evt.name)}" fields="${evt.fields.length}"${aggregateAttr} linked-copy="true"${originAttr}/>`);
-        }
-        else {
-            // This is an original - show copy count
-            const copyCount = evt.canonicalId
-                ? [...model.events.values()].filter(e => e.canonicalId === evt.canonicalId && e.originalNodeId).length
-                : 0;
-            const copiesAttr = copyCount > 0 ? ` copies="${copyCount}"` : '';
-            console.log(`  <event id="${evt.id}" name="${escapeXml(evt.name)}" fields="${evt.fields.length}"${aggregateAttr}${copiesAttr}/>`);
-        }
-    }
-    console.log('</events>');
-}

package/dist/slices/list-processors/index.d.ts

@@ -1,3 +0,0 @@
-import type { EventModel } from '../../types.js';
-import { type OutputFormat } from '../../lib/format.js';
-export declare function listProcessors(model: EventModel, format: OutputFormat): void;

package/dist/slices/list-processors/index.js

@@ -1,20 +0,0 @@
-import { escapeXml, outputJson } from '../../lib/format.js';
-export function listProcessors(model, format) {
-    const processors = [...model.processors.values()];
-    const sorted = [...processors].sort((a, b) => a.name.localeCompare(b.name));
-    if (format === 'json') {
-        outputJson({
-            processors: sorted.map(proc => ({ id: proc.id, name: proc.name, fields: proc.fields.length }))
-        });
-        return;
-    }
-    if (processors.length === 0) {
-        console.log('<processors/>');
-        return;
-    }
-    console.log('<processors>');
-    for (const proc of sorted) {
-        console.log(`  <processor id="${proc.id}" name="${escapeXml(proc.name)}" fields="${proc.fields.length}"/>`);
-    }
-    console.log('</processors>');
-}

package/dist/slices/list-readmodels/index.d.ts

@@ -1,3 +0,0 @@
-import type { EventModel } from '../../types.js';
-import { type OutputFormat } from '../../lib/format.js';
-export declare function listReadModels(model: EventModel, format: OutputFormat): void;