eventmodeler 0.2.1 → 0.2.3

package/README.md

@@ -0,0 +1,175 @@
+# eventmodeler
+
+CLI tool for interacting with [Event Model](https://eventmodeling.org) files. Query, update, and export event models from the terminal.
+
+Works with `.eventmodel` files created by the [Event Modeling App](https://www.eventmodeling.app).
+
+## Installation
+
+```bash
+npm install -g eventmodeler
+```
+
+## Quick Start
+
+```bash
+# Open Event Modeling app in browser
+eventmodeler
+
+# List all slices
+eventmodeler list slices
+
+# Show details of a slice
+eventmodeler show slice "Place Order"
+
+# Search for elements
+eventmodeler search "order"
+
+# Get JSON output instead of XML
+eventmodeler list slices --format json
+```
+
+## Commands
+
+### List Commands
+
+```bash
+eventmodeler list slices              # List all slices with status
+eventmodeler list events              # List all events
+eventmodeler list commands            # List all commands
+eventmodeler list chapters            # List all chapters
+eventmodeler list aggregates          # List all aggregates
+eventmodeler list actors              # List all actors
+```
+
+### Show Commands
+
+```bash
+eventmodeler show slice <name>        # Show detailed view of a slice
+eventmodeler show event <name>        # Show detailed view of an event
+eventmodeler show command <name>      # Show detailed view of a command
+eventmodeler show chapter <name>      # Show chapter with its slices
+eventmodeler show actor <name>        # Show actor with its screens
+```
+
+### Completeness Commands
+
+```bash
+eventmodeler show completeness <name>       # Show field mapping completeness for any element
+eventmodeler show model-completeness        # Show completeness of all flows in the model
+eventmodeler show aggregate-completeness <name>  # Check if events have the aggregate ID field
+```
+
+### Search
+
+```bash
+eventmodeler search <term>            # Search for entities by name
+```
+
+### Modify Commands
+
+```bash
+# Mark slice status
+eventmodeler mark "Place Order" done
+eventmodeler mark "Cancel Order" in-progress
+
+# Add scenario to a slice
+eventmodeler add scenario --slice "Place Order" --json '{"name": "Happy path", ...}'
+
+# Add field to an entity
+eventmodeler add field --event "OrderPlaced" --json '{"name": "orderId", "type": "UUID"}'
+
+# Remove field
+eventmodeler remove field --event "OrderPlaced" --field "legacyId"
+
+# Update field properties
+eventmodeler update field --read-model "OrderSummary" --field "notes" --optional true
+
+# Map fields between elements
+eventmodeler map fields --flow "OrderPlaced→OrderSummary" --json '[{"from": "total", "to": "totalAmount"}]'
+```
+
+### Export
+
+```bash
+eventmodeler summary                  # Show model summary statistics
+eventmodeler export json              # Export entire model as JSON
+```
+
+## Output Format
+
+By default, output is in XML format (optimized for AI agents). Use `--format json` for JSON output:
+
+```bash
+eventmodeler list slices --format json
+eventmodeler show slice "Place Order" --format json
+```
+
+### Setting Default Format
+
+Set your preferred default format via:
+
+**Environment variable:**
+```bash
+export EVENTMODELER_FORMAT=json
+```
+
+**Config file** (`~/.eventmodeler/config.json`):
+```json
+{
+  "format": "json"
+}
+```
+
+Priority: CLI flag > environment variable > config file > default (xml)
+
+## Options
+
+```
+-f, --file <path>       Path to .eventmodel file (default: auto-detect)
+--format <xml|json>     Output format (default: xml)
+-h, --help              Show help message
+-v, --version           Show version number
+```
+
+## Use Cases
+
+### For AI Agents
+
+The CLI is designed to work well with AI coding assistants. The XML output format provides structured, readable data that AI agents can easily parse and understand:
+
+```bash
+eventmodeler show slice "Place Order"
+```
+
+### For Code Generators
+
+Use JSON output to build code generators that read your event model:
+
+```bash
+eventmodeler list events --format json | your-codegen-tool
+eventmodeler show slice "Place Order" --format json
+```
+
+### For CI/CD
+
+Check model completeness in your pipeline:
+
+```bash
+eventmodeler show model-completeness --format json
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- A `.eventmodel` file in the current directory (or specify with `-f`)
+
+## License
+
+MIT
+
+## Links
+
+- [Event Modeling App](https://www.eventmodeling.app)
+- [Event Modeling](https://eventmodeling.org)
+- [GitHub Repository](https://github.com/theoema/event-modeler)

package/dist/index.js

@@ -1,6 +1,13 @@
 #!/usr/bin/env node
 import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { findEventModelFile, loadModel } from './lib/file-loader.js';
+import { getDefaultFormat } from './lib/config.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
+const VERSION = packageJson.version;
 // Import slices
 import { listSlices } from './slices/list-slices/index.js';
 import { listEvents } from './slices/list-events/index.js';
@@ -19,7 +26,7 @@ import { addScenario } from './slices/add-scenario/index.js';
 import { addField } from './slices/add-field/index.js';
 import { removeScenario } from './slices/remove-scenario/index.js';
 import { removeField } from './slices/remove-field/index.js';
-import { showCompleteness } from './slices/show-completeness/index.js';
+import { showCompleteness, showModelCompleteness } from './slices/show-completeness/index.js';
 import { mapFields } from './slices/map-fields/index.js';
 import { updateField } from './slices/update-field/index.js';
 import { showAggregateCompleteness, listAggregates } from './slices/show-aggregate-completeness/index.js';
@@ -53,7 +60,8 @@ COMMANDS:
   show event <name>              Show detailed XML view of an event
   show command <name>            Show detailed XML view of a command
   show chapter <name>            Show chapter with its slices
-  show completeness <read-model> Show field mapping completeness status
+  show completeness <name>       Show field mapping completeness for any element
+  show model-completeness        Show completeness of all flows in the model
   show aggregate-completeness <name>
                                  Show if events in aggregate have the ID field
   show actor <name>              Show actor with its screens
@@ -85,7 +93,14 @@ COMMANDS:
 
 OPTIONS:
   -f, --file <path>              Path to .eventmodel file (default: auto-detect)
+  --format <xml|json>            Output format (default: xml, or from config)
   -h, --help                     Show this help message
+  -v, --version                  Show version number
+
+CONFIGURATION:
+  Set default output format via:
+  - Environment variable: EVENTMODELER_FORMAT=json
+  - Config file: ~/.eventmodeler/config.json with {"format": "json"}
 
 EXAMPLES:
   eventmodeler list slices
@@ -95,25 +110,38 @@ EXAMPLES:
   eventmodeler add field --event "OrderPlaced" --json '{"name": "orderId", "type": "UUID"}'
   eventmodeler remove field --event "OrderPlaced" --field "orderId"
   eventmodeler show completeness "OrderSummary"
+  eventmodeler show model-completeness
   eventmodeler map fields --flow "OrderPlaced→OrderSummary" --json '[{"from": "total", "to": "totalAmount"}]'
   eventmodeler update field --read-model "OrderSummary" --field "notes" --optional true
 `);
 }
 async function main() {
     let fileArg = null;
+    let formatArg = null;
     const filteredArgs = [];
     for (let i = 0; i < args.length; i++) {
         if (args[i] === '-f' || args[i] === '--file') {
             fileArg = args[++i];
         }
+        else if (args[i] === '--format') {
+            formatArg = args[++i];
+        }
         else if (args[i] === '-h' || args[i] === '--help') {
             printHelp();
             process.exit(0);
         }
+        else if (args[i] === '-v' || args[i] === '--version') {
+            console.log(`eventmodeler ${VERSION}`);
+            process.exit(0);
+        }
         else {
             filteredArgs.push(args[i]);
         }
     }
+    // Determine output format
+    const format = formatArg === 'json' ? 'json'
+        : formatArg === 'xml' ? 'xml'
+            : getDefaultFormat();
     const command = filteredArgs[0];
     const subcommand = filteredArgs[1];
     const target = filteredArgs[2];
@@ -136,22 +164,22 @@ async function main() {
         case 'list':
             switch (subcommand) {
                 case 'slices':
-                    listSlices(model);
+                    listSlices(model, format);
                     break;
                 case 'events':
-                    listEvents(model);
+                    listEvents(model, format);
                     break;
                 case 'commands':
-                    listCommands(model);
+                    listCommands(model, format);
                     break;
                 case 'chapters':
-                    listChapters(model);
+                    listChapters(model, format);
                     break;
                 case 'aggregates':
-                    listAggregates(model);
+                    listAggregates(model, format);
                     break;
                 case 'actors':
-                    listActors(model);
+                    listActors(model, format);
                     break;
                 default:
                     console.error(`Unknown list target: ${subcommand}`);
@@ -166,53 +194,57 @@ async function main() {
                         console.error('Usage: eventmodeler show slice <name>');
                         process.exit(1);
                     }
-                    showSlice(model, target);
+                    showSlice(model, target, format);
                     break;
                 case 'event':
                     if (!target) {
                         console.error('Usage: eventmodeler show event <name>');
                         process.exit(1);
                     }
-                    showEvent(model, target);
+                    showEvent(model, target, format);
                     break;
                 case 'command':
                     if (!target) {
                         console.error('Usage: eventmodeler show command <name>');
                         process.exit(1);
                     }
-                    showCommand(model, target);
+                    showCommand(model, target, format);
                     break;
                 case 'chapter':
                     if (!target) {
                         console.error('Usage: eventmodeler show chapter <name>');
                         process.exit(1);
                     }
-                    showChapter(model, target);
+                    showChapter(model, target, format);
                     break;
                 case 'completeness':
                     if (!target) {
-                        console.error('Usage: eventmodeler show completeness <read-model-name>');
+                        console.error('Usage: eventmodeler show completeness <element-name>');
+                        console.error('Searches: commands, events, read models, screens, processors');
                         process.exit(1);
                     }
-                    showCompleteness(model, target);
+                    showCompleteness(model, target, format);
+                    break;
+                case 'model-completeness':
+                    showModelCompleteness(model, format);
                     break;
                 case 'aggregate-completeness':
                     if (!target) {
                         console.error('Usage: eventmodeler show aggregate-completeness <aggregate-name>');
                         process.exit(1);
                     }
-                    showAggregateCompleteness(model, target);
+                    showAggregateCompleteness(model, target, format);
                     break;
                 case 'actor':
                     if (!target) {
                         console.error('Usage: eventmodeler show actor <actor-name>');
                         process.exit(1);
                     }
-                    showActor(model, target);
+                    showActor(model, target, format);
                     break;
                 default:
                     console.error(`Unknown show target: ${subcommand}`);
-                    console.error('Valid targets: slice, event, command, chapter, completeness, aggregate-completeness, actor');
+                    console.error('Valid targets: slice, event, command, chapter, completeness, model-completeness, aggregate-completeness, actor');
                     process.exit(1);
             }
             break;
@@ -221,7 +253,7 @@ async function main() {
                 console.error('Usage: eventmodeler search <term>');
                 process.exit(1);
             }
-            search(model, subcommand);
+            search(model, subcommand, format);
             break;
         case 'mark':
             if (!subcommand || !target) {
@@ -232,7 +264,7 @@ async function main() {
             markSliceStatus(model, filePath, subcommand, target);
             break;
         case 'summary':
-            showModelSummary(model);
+            showModelSummary(model, format);
             break;
         case 'export':
             switch (subcommand) {

package/dist/lib/config.d.ts

@@ -0,0 +1,2 @@
+import type { OutputFormat } from './format.js';
+export declare function getDefaultFormat(): OutputFormat;

package/dist/lib/config.js

@@ -0,0 +1,26 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+export function getDefaultFormat() {
+    // 1. Check environment variable
+    const envFormat = process.env.EVENTMODELER_FORMAT;
+    if (envFormat === 'json')
+        return 'json';
+    if (envFormat === 'xml')
+        return 'xml';
+    // 2. Check config file
+    try {
+        const configPath = path.join(os.homedir(), '.eventmodeler', 'config.json');
+        if (fs.existsSync(configPath)) {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (config.format === 'json' || config.format === 'xml') {
+                return config.format;
+            }
+        }
+    }
+    catch {
+        // Ignore config file errors
+    }
+    // 3. Default to XML (better for AI agents)
+    return 'xml';
+}

package/dist/lib/format.d.ts

@@ -0,0 +1,3 @@
+export type OutputFormat = 'xml' | 'json';
+export declare function escapeXml(str: string): string;
+export declare function outputJson(data: unknown): void;

package/dist/lib/format.js

@@ -0,0 +1,11 @@
+export function escapeXml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+export function outputJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}

package/dist/projection.js

@@ -826,57 +826,51 @@ function applyEvent(model, event) {
             break;
     }
 }
+// Merge propagated fields with existing fields:
+// - If a field with the same name exists, update its subfields
+// - If it doesn't exist, add as new field
+function mergeFieldsInto(existingFields, propagatedFields) {
+    for (const propagatedField of propagatedFields) {
+        const existingIdx = existingFields.findIndex(f => f.name === propagatedField.name);
+        if (existingIdx !== -1) {
+            // Field exists - update its subfields
+            existingFields[existingIdx] = {
+                ...existingFields[existingIdx],
+                subfields: propagatedField.subfields,
+            };
+        }
+        else {
+            // New field - add it
+            existingFields.push(propagatedField);
+        }
+    }
+}
 function handleFieldPropagation(model, event) {
     const fields = event.fields;
     // Determine target based on event type
     if ('eventStickyId' in event) {
         const evt = model.events.get(event.eventStickyId);
-        if (evt) {
-            for (const field of fields) {
-                if (!evt.fields.some(f => f.name === field.name)) {
-                    evt.fields.push(field);
-                }
-            }
-        }
+        if (evt)
+            mergeFieldsInto(evt.fields, fields);
     }
     else if ('commandStickyId' in event) {
         const cmd = model.commands.get(event.commandStickyId);
-        if (cmd) {
-            for (const field of fields) {
-                if (!cmd.fields.some(f => f.name === field.name)) {
-                    cmd.fields.push(field);
-                }
-            }
-        }
+        if (cmd)
+            mergeFieldsInto(cmd.fields, fields);
     }
     else if ('readModelStickyId' in event) {
         const rm = model.readModels.get(event.readModelStickyId);
-        if (rm) {
-            for (const field of fields) {
-                if (!rm.fields.some(f => f.name === field.name)) {
-                    rm.fields.push(field);
-                }
-            }
-        }
+        if (rm)
+            mergeFieldsInto(rm.fields, fields);
     }
     else if ('screenId' in event) {
         const scr = model.screens.get(event.screenId);
-        if (scr) {
-            for (const field of fields) {
-                if (!scr.fields.some(f => f.name === field.name)) {
-                    scr.fields.push(field);
-                }
-            }
-        }
+        if (scr)
+            mergeFieldsInto(scr.fields, fields);
     }
     else if ('processorId' in event) {
         const proc = model.processors.get(event.processorId);
-        if (proc) {
-            for (const field of fields) {
-                if (!proc.fields.some(f => f.name === field.name)) {
-                    proc.fields.push(field);
-                }
-            }
-        }
+        if (proc)
+            mergeFieldsInto(proc.fields, fields);
     }
 }

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

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

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

@@ -1,19 +1,18 @@
-function escapeXml(str) {
-    return str
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&apos;');
-}
-export function listChapters(model) {
+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 => ({ name: ch.name }))
+        });
+        return;
+    }
     if (chapters.length === 0) {
         console.log('<chapters/>');
         return;
     }
-    // Sort by x position (left to right on timeline)
-    const sorted = [...chapters].sort((a, b) => a.position.x - b.position.x);
     console.log('<chapters>');
     for (const chapter of sorted) {
         console.log(`  <chapter name="${escapeXml(chapter.name)}"/>`);

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

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

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

@@ -1,18 +1,17 @@
-function escapeXml(str) {
-    return str
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&apos;');
-}
-export function listCommands(model) {
+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 => ({ name: cmd.name, fields: cmd.fields.length }))
+        });
+        return;
+    }
     if (commands.length === 0) {
         console.log('<commands/>');
         return;
     }
-    const sorted = [...commands].sort((a, b) => a.name.localeCompare(b.name));
     console.log('<commands>');
     for (const cmd of sorted) {
         console.log(`  <command name="${escapeXml(cmd.name)}" fields="${cmd.fields.length}"/>`);

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

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

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

@@ -1,11 +1,4 @@
-function escapeXml(str) {
-    return str
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&apos;');
-}
+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;
@@ -37,12 +30,8 @@ function findSliceForEvent(model, event) {
     }
     return null;
 }
-export function listEvents(model) {
+export function listEvents(model, format) {
     const events = [...model.events.values()];
-    if (events.length === 0) {
-        console.log('<events/>');
-        return;
-    }
     // Sort: originals first, then copies; alphabetically within each group
     const sorted = [...events].sort((a, b) => {
         // Originals before copies
@@ -53,6 +42,37 @@ export function listEvents(model) {
         // Alphabetically by name
         return a.name.localeCompare(b.name);
     });
+    if (format === 'json') {
+        outputJson({
+            events: sorted.map(evt => {
+                const aggregate = findAggregateForEvent(model, evt);
+                const result = {
+                    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);

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

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