eventmodeler 0.2.1 → 0.2.4

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,11 +26,15 @@ 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';
 import { showActor, listActors } from './slices/show-actor/index.js';
+import { createStateChangeSlice } from './slices/create-state-change-slice/index.js';
+import { createAutomationSlice } from './slices/create-automation-slice/index.js';
+import { createStateViewSlice } from './slices/create-state-view-slice/index.js';
+import { createFlow } from './slices/create-flow/index.js';
 const args = process.argv.slice(2);
 function getNamedArg(argList, ...names) {
     for (let i = 0; i < argList.length; i++) {
@@ -53,7 +64,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
@@ -79,13 +91,29 @@ COMMANDS:
   update field --command|--event|--read-model <name> --field <name> [--optional true|false] [--generated true|false]
                                  Update field properties
 
+  create state-change-slice --xml <data>
+                                 Create a state-change slice (Screen → Command → Event)
+  create automation-slice --xml <data>
+                                 Create an automation slice (Processor → Command → Event)
+  create state-view-slice --xml <data>
+                                 Create a state-view slice (Read Model)
+  create flow --from <source> --to <target>
+                                 Create a flow between elements (Event→ReadModel, ReadModel→Screen/Processor)
+
   summary                        Show model summary statistics
 
   export json                    Export entire model as JSON
 
 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 +123,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 +177,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 +207,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 +266,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 +277,7 @@ async function main() {
             markSliceStatus(model, filePath, subcommand, target);
             break;
         case 'summary':
-            showModelSummary(model);
+            showModelSummary(model, format);
             break;
         case 'export':
             switch (subcommand) {
@@ -381,6 +426,56 @@ async function main() {
                     process.exit(1);
             }
             break;
+        case 'create':
+            switch (subcommand) {
+                case 'state-change-slice': {
+                    const xmlArg = getNamedArg(filteredArgs, '--xml');
+                    if (!xmlArg) {
+                        console.error('Error: --xml is required');
+                        console.error('Usage: eventmodeler create state-change-slice --xml \'<state-change-slice>...</state-change-slice>\'');
+                        process.exit(1);
+                    }
+                    createStateChangeSlice(model, filePath, xmlArg);
+                    break;
+                }
+                case 'automation-slice': {
+                    const xmlArg = getNamedArg(filteredArgs, '--xml');
+                    if (!xmlArg) {
+                        console.error('Error: --xml is required');
+                        console.error('Usage: eventmodeler create automation-slice --xml \'<automation-slice>...</automation-slice>\'');
+                        process.exit(1);
+                    }
+                    createAutomationSlice(model, filePath, xmlArg);
+                    break;
+                }
+                case 'state-view-slice': {
+                    const xmlArg = getNamedArg(filteredArgs, '--xml');
+                    if (!xmlArg) {
+                        console.error('Error: --xml is required');
+                        console.error('Usage: eventmodeler create state-view-slice --xml \'<state-view-slice>...</state-view-slice>\'');
+                        process.exit(1);
+                    }
+                    createStateViewSlice(model, filePath, xmlArg);
+                    break;
+                }
+                case 'flow': {
+                    const fromArg = getNamedArg(filteredArgs, '--from');
+                    const toArg = getNamedArg(filteredArgs, '--to');
+                    if (!fromArg || !toArg) {
+                        console.error('Error: --from and --to are required');
+                        console.error('Usage: eventmodeler create flow --from <source> --to <target>');
+                        console.error('Valid flows: Event→ReadModel, ReadModel→Screen, ReadModel→Processor');
+                        process.exit(1);
+                    }
+                    createFlow(model, filePath, fromArg, toArg);
+                    break;
+                }
+                default:
+                    console.error(`Unknown create target: ${subcommand}`);
+                    console.error('Valid targets: state-change-slice, automation-slice, state-view-slice, flow');
+                    process.exit(1);
+            }
+            break;
         default:
             console.error(`Unknown command: ${command}`);
             printHelp();

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/element-lookup.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Element lookup utilities for CLI commands.
+ * Provides exact-match lookup with UUID disambiguation for duplicate names.
+ */
+export type LookupResult<T> = {
+    success: true;
+    element: T;
+} | {
+    success: false;
+    error: 'not_found' | 'ambiguous';
+    matches: T[];
+};
+/**
+ * Find an element by exact name (case-insensitive) or UUID.
+ * - If search starts with "id:", treats rest as UUID/UUID prefix
+ * - Otherwise, performs case-insensitive exact name match
+ * - Returns error if multiple elements have the same name
+ */
+export declare function findElement<T extends {
+    id: string;
+    name: string;
+}>(elements: Map<string, T> | T[], search: string): LookupResult<T>;
+/**
+ * Format an element name with its ID for display
+ */
+export declare function formatElementWithId<T extends {
+    id: string;
+    name: string;
+}>(element: T, truncateId?: boolean): string;
+/**
+ * Print error message for lookup failures and exit
+ */
+export declare function handleLookupError<T extends {
+    id: string;
+    name: string;
+}>(search: string, elementType: string, result: {
+    success: false;
+    error: 'not_found' | 'ambiguous';
+    matches: T[];
+}, allElements: Map<string, T> | T[]): never;
+/**
+ * Convenience function: find element or exit with error
+ */
+export declare function findElementOrExit<T extends {
+    id: string;
+    name: string;
+}>(elements: Map<string, T> | T[], search: string, elementType: string): T;

package/dist/lib/element-lookup.js

@@ -0,0 +1,86 @@
+/**
+ * Element lookup utilities for CLI commands.
+ * Provides exact-match lookup with UUID disambiguation for duplicate names.
+ */
+/**
+ * Find an element by exact name (case-insensitive) or UUID.
+ * - If search starts with "id:", treats rest as UUID/UUID prefix
+ * - Otherwise, performs case-insensitive exact name match
+ * - Returns error if multiple elements have the same name
+ */
+export function findElement(elements, search) {
+    const elementArray = Array.isArray(elements) ? elements : [...elements.values()];
+    // Check for UUID lookup (id:prefix or full UUID format)
+    if (search.startsWith('id:')) {
+        const idSearch = search.slice(3).toLowerCase();
+        const match = elementArray.find(e => e.id.toLowerCase().startsWith(idSearch));
+        if (match) {
+            return { success: true, element: match };
+        }
+        return { success: false, error: 'not_found', matches: [] };
+    }
+    // Check if the search looks like a UUID (contains dashes in UUID pattern)
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (uuidPattern.test(search)) {
+        const match = elementArray.find(e => e.id.toLowerCase() === search.toLowerCase());
+        if (match) {
+            return { success: true, element: match };
+        }
+        return { success: false, error: 'not_found', matches: [] };
+    }
+    // Case-insensitive exact name match
+    const searchLower = search.toLowerCase();
+    const matches = elementArray.filter(e => e.name.toLowerCase() === searchLower);
+    if (matches.length === 1) {
+        return { success: true, element: matches[0] };
+    }
+    if (matches.length > 1) {
+        return { success: false, error: 'ambiguous', matches };
+    }
+    return { success: false, error: 'not_found', matches: [] };
+}
+/**
+ * Format an element name with its ID for display
+ */
+export function formatElementWithId(element, truncateId = true) {
+    const id = truncateId ? element.id.slice(0, 8) : element.id;
+    return `"${element.name}" (id: ${id})`;
+}
+/**
+ * Print error message for lookup failures and exit
+ */
+export function handleLookupError(search, elementType, result, allElements) {
+    const elementArray = Array.isArray(allElements) ? allElements : [...allElements.values()];
+    if (result.error === 'ambiguous') {
+        console.error(`Error: Multiple ${elementType}s found with name "${search}"`);
+        console.error('Please specify using the element ID:');
+        for (const el of result.matches) {
+            console.error(`  - ${formatElementWithId(el, false)}`);
+        }
+        console.error('');
+        console.error(`Usage: eventmodeler <command> "id:${result.matches[0].id.slice(0, 8)}"`);
+    }
+    else {
+        console.error(`Error: ${elementType.charAt(0).toUpperCase() + elementType.slice(1)} not found: "${search}"`);
+        if (elementArray.length > 0) {
+            console.error(`Available ${elementType}s:`);
+            for (const el of elementArray) {
+                console.error(`  - ${formatElementWithId(el)}`);
+            }
+        }
+        else {
+            console.error(`No ${elementType}s exist in the model.`);
+        }
+    }
+    process.exit(1);
+}
+/**
+ * Convenience function: find element or exit with error
+ */
+export function findElementOrExit(elements, search, elementType) {
+    const result = findElement(elements, search);
+    if (!result.success) {
+        handleLookupError(search, elementType, result, elements);
+    }
+    return result.element;
+}

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));
+}