eventmodeler 0.4.7 → 0.6.0

package/dist/commands/add.js

@@ -0,0 +1,315 @@
+import { getGlobalId } from '../lib/globals';
+import { randomUUID } from 'node:crypto';
+import { requireModelId } from '../lib/model';
+import { resolve, resolveAnyElement, unwrap, elementIdKey } from '../lib/resolve';
+import { resolveScenarioId } from '../lib/scenario';
+import * as sdk from '../api/generated/sdk.gen';
+const ADD_FIELD_MAP = {
+    command: sdk.addCommandField,
+    event: sdk.addEventField,
+    readmodel: sdk.addReadModelField,
+    screen: sdk.addScreenField,
+    processor: sdk.addProcessorField,
+    'external-event': sdk.addExternalEventField,
+};
+const ADD_SUBFIELD_MAP = {
+    command: sdk.addCommandSubfield,
+    event: sdk.addEventSubfield,
+    readmodel: sdk.addReadModelSubfield,
+    screen: sdk.addScreenSubfield,
+    processor: sdk.addProcessorSubfield,
+    'external-event': sdk.addExternalEventSubfield,
+};
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// Maps entry type in a GWT section to { sdkCall, idKey, primitive + Custom setters }
+export const ENTRY_DISPATCH = {
+    given: {
+        event: { add: sdk.addScenarioGivenEvent, resolveType: 'event', idKey: 'eventStickyId', setFieldValue: sdk.setScenarioEventFieldValue, setFieldListValues: sdk.setScenarioEventFieldListValues, setFieldCustomValue: sdk.setScenarioEventFieldCustomValue, setFieldCustomListValues: sdk.setScenarioEventFieldCustomListValues },
+        readmodel: { add: sdk.addScenarioGivenReadModel, resolveType: 'readmodel', idKey: 'readModelStickyId', setFieldValue: sdk.setScenarioReadModelFieldValue, setFieldListValues: sdk.setScenarioReadModelFieldListValues, setFieldCustomValue: sdk.setScenarioReadModelFieldCustomValue, setFieldCustomListValues: sdk.setScenarioReadModelFieldCustomListValues },
+    },
+    when: {
+        command: { add: sdk.addScenarioWhenCommand, resolveType: 'command', idKey: 'commandStickyId', setFieldValue: sdk.setScenarioCommandFieldValue, setFieldListValues: sdk.setScenarioCommandFieldListValues, setFieldCustomValue: sdk.setScenarioCommandFieldCustomValue, setFieldCustomListValues: sdk.setScenarioCommandFieldCustomListValues },
+        event: { add: sdk.addScenarioWhenEvent, resolveType: 'event', idKey: 'eventStickyId', setFieldValue: sdk.setScenarioEventFieldValue, setFieldListValues: sdk.setScenarioEventFieldListValues, setFieldCustomValue: sdk.setScenarioEventFieldCustomValue, setFieldCustomListValues: sdk.setScenarioEventFieldCustomListValues },
+    },
+    then: {
+        event: { add: sdk.addScenarioThenEvent, resolveType: 'event', idKey: 'eventStickyId', setFieldValue: sdk.setScenarioEventFieldValue, setFieldListValues: sdk.setScenarioEventFieldListValues, setFieldCustomValue: sdk.setScenarioEventFieldCustomValue, setFieldCustomListValues: sdk.setScenarioEventFieldCustomListValues },
+        command: { add: sdk.addScenarioThenCommand, resolveType: 'command', idKey: 'commandStickyId', setFieldValue: sdk.setScenarioCommandFieldValue, setFieldListValues: sdk.setScenarioCommandFieldListValues, setFieldCustomValue: sdk.setScenarioCommandFieldCustomValue, setFieldCustomListValues: sdk.setScenarioCommandFieldCustomListValues },
+        readmodel: { add: sdk.addScenarioThenReadModel, resolveType: 'readmodel', idKey: 'readModelStickyId', setFieldValue: sdk.setScenarioReadModelFieldValue, setFieldListValues: sdk.setScenarioReadModelFieldListValues, setFieldCustomValue: sdk.setScenarioReadModelFieldCustomValue, setFieldCustomListValues: sdk.setScenarioReadModelFieldCustomListValues },
+        error: { add: sdk.addScenarioThenError, resolveType: '', idKey: '', setFieldValue: undefined, setFieldListValues: undefined },
+    },
+};
+async function addEntries(modelId, scenarioId, section, entries, positionOffset = 0) {
+    const dispatch = ENTRY_DISPATCH[section];
+    if (!dispatch)
+        throw new Error(`Unknown scenario section: ${section}`);
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const entryId = randomUUID();
+        const info = dispatch[entry.entryType];
+        if (!info)
+            throw new Error(`Unknown ${section} entry type: ${entry.entryType}`);
+        if (entry.entryType === 'error') {
+            unwrap(await info.add({
+                body: {
+                    modelId,
+                    scenarioId,
+                    entryId,
+                    position: positionOffset + i,
+                    errorType: entry.errorType ?? '',
+                    errorMessage: entry.errorMessage ?? '',
+                }
+            }));
+        }
+        else {
+            const elementId = await resolve(modelId, info.resolveType, entry.elementName);
+            unwrap(await info.add({
+                body: {
+                    modelId,
+                    scenarioId,
+                    entryId,
+                    position: positionOffset + i,
+                    [info.idKey]: elementId,
+                }
+            }));
+            // Set field values if provided. Dispatch by JS shape — backend rejects mismatches.
+            //   string         → primitive scalar
+            //   string[]       → primitive list (objects in array → Custom list)
+            //   object         → Custom scalar (recursive tree)
+            //   object[]       → Custom list of trees
+            if (entry.fieldValues) {
+                for (const [fieldName, value] of Object.entries(entry.fieldValues)) {
+                    if (Array.isArray(value)) {
+                        const allObjects = value.length > 0 && value.every(isPlainObject);
+                        const anyObject = value.some((v) => isPlainObject(v));
+                        if (allObjects) {
+                            if (!info.setFieldCustomListValues)
+                                throw new Error(`Cannot set Custom list values on ${entry.entryType}`);
+                            unwrap(await info.setFieldCustomListValues({
+                                body: { modelId, scenarioId, entryId, fieldName, items: value }
+                            }));
+                        }
+                        else if (anyObject) {
+                            throw new Error(`Field "${fieldName}": list mixes primitives and objects — use either all strings or all objects.`);
+                        }
+                        else {
+                            if (!info.setFieldListValues)
+                                throw new Error(`Cannot set list values on ${entry.entryType}`);
+                            unwrap(await info.setFieldListValues({
+                                body: { modelId, scenarioId, entryId, fieldName, values: value.map(String) }
+                            }));
+                        }
+                    }
+                    else if (isPlainObject(value)) {
+                        if (!info.setFieldCustomValue)
+                            throw new Error(`Cannot set Custom value on ${entry.entryType}`);
+                        unwrap(await info.setFieldCustomValue({
+                            body: { modelId, scenarioId, entryId, fieldName, value }
+                        }));
+                    }
+                    else {
+                        if (!info.setFieldValue)
+                            throw new Error(`Cannot set value on ${entry.entryType}`);
+                        unwrap(await info.setFieldValue({
+                            body: { modelId, scenarioId, entryId, fieldName, value: String(value) }
+                        }));
+                    }
+                }
+            }
+        }
+    }
+}
+export function registerAddCommands(program) {
+    const add = program.command('add').description('Add fields or scenarios');
+    add.command('field [elementName] <json>')
+        .description('Add a field to an element')
+        .action(async (elementNameOrJson, jsonOrUndefined, cmd) => {
+        const modelId = requireModelId();
+        const hasId = getGlobalId();
+        const elementName = jsonOrUndefined ? elementNameOrJson : '';
+        const json = jsonOrUndefined ?? elementNameOrJson;
+        const { elementId, elementType } = await resolveAnyElement(modelId, elementName, hasId);
+        const fn = ADD_FIELD_MAP[elementType];
+        if (!fn)
+            throw new Error(`Cannot add fields to type: ${elementType}`);
+        const field = JSON.parse(json);
+        const key = elementIdKey(elementType);
+        unwrap(await fn({
+            body: {
+                modelId,
+                [key]: elementId,
+                fieldId: randomUUID(),
+                fieldName: field.name,
+                fieldType: field.type,
+            }
+        }));
+        console.log(`Added field "${field.name}".`);
+    });
+    // add subfield [elementName] --field <parentFieldName> <json>
+    add.command('subfield [elementName]')
+        .description('Add a subfield to an existing field')
+        .requiredOption('--field <name>', 'Parent field name')
+        .argument('<json>', 'Subfield JSON: {"name": "...", "type": "..."}')
+        .action(async (elementName, json, opts, cmd) => {
+        const modelId = requireModelId();
+        const hasId = getGlobalId();
+        const { elementId, elementType } = await resolveAnyElement(modelId, elementName ?? '', hasId);
+        const fn = ADD_SUBFIELD_MAP[elementType];
+        if (!fn)
+            throw new Error(`Cannot add subfields to type: ${elementType}`);
+        const fieldResult = unwrap(await sdk.resolveField({
+            query: { modelId, elementId, fieldName: opts.field }
+        }));
+        const parentFieldId = fieldResult.fieldId;
+        const sub = JSON.parse(json);
+        const key = elementIdKey(elementType);
+        unwrap(await fn({
+            body: {
+                modelId,
+                [key]: elementId,
+                parentFieldId,
+                subfieldId: randomUUID(),
+                fieldName: sub.name,
+                fieldType: sub.type,
+            }
+        }));
+        console.log(`Added subfield "${sub.name}" to "${opts.field}".`);
+    });
+    add.command('scenario <json>')
+        .description('Atomically create a full Given/When/Then scenario (shell + entries + field example values) in a single backend transaction')
+        .requiredOption('--slice <name>', 'Slice name')
+        .addHelpText('after', `
+The entire scenario is created in ONE backend command — either everything
+succeeds or nothing is persisted. No orphan shells, no half-applied entries,
+no partial field values. All validation runs up-front; on any failure the
+whole spec is rejected with a single error message.
+
+Spec shape:
+  {
+    "name": "Scenario name",
+    "description": "(optional)",
+    "given": [<entry>, ...],
+    "when":  [<entry>, ...],
+    "then":  [<entry>, ...]
+  }
+
+Entry shape (non-error):
+  { "entryType": "event"|"command"|"readmodel",
+    "elementName": "ElementName",
+    "fieldValues": { "<fieldName>": <value>, ... } }
+
+Entry shape (error, "then" only):
+  { "entryType": "error", "errorType": "...", "errorMessage": "..." }
+
+Allowed entry types per section:
+  given: event, readmodel
+  when:  command, event
+  then:  event, command, readmodel, error
+
+fieldValues — backend dispatches by FIELD METADATA (not by JSON shape):
+  field is primitive scalar      → value must be a JSON string         "42"
+  field is primitive list        → value must be string[]              ["a","b"]
+  field is Custom (object)       → value must be object                { "city": "NYC" }
+  field is Custom list           → value must be object[]              [{...}, {...}]
+
+Inside a Custom tree, primitive leaves MUST be JSON strings ("42", "true",
+ISO dates). Field type/listness mismatches are rejected up-front.
+Discover field shapes (incl. nested subfields) with: show element <name>
+
+Element names are resolved to UUIDs client-side before the call. If any
+element name doesn't resolve, the whole spec is rejected before hitting the
+backend.
+
+Example (primitives + Custom + list):
+  add scenario --slice "Place Order" '{
+    "name": "happy path",
+    "when":  [{ "entryType": "command", "elementName": "PlaceOrder",
+                "fieldValues": { "orderId": "uuid-1",
+                                 "items": ["sku-1","sku-2"],
+                                 "shipTo": { "city": "NYC", "zip": "10001" } } }],
+    "then":  [{ "entryType": "event", "elementName": "OrderPlaced",
+                "fieldValues": { "lines": [ { "sku": "sku-1", "qty": "2" },
+                                            { "sku": "sku-2", "qty": "1" } ] } }]
+  }'
+`)
+        .action(async (json, opts, cmd) => {
+        const modelId = requireModelId();
+        const sliceId = await resolve(modelId, 'slice', opts.slice, getGlobalId());
+        const spec = JSON.parse(json);
+        const scenarioId = randomUUID();
+        const buildEntries = async (section, entries) => {
+            if (!entries)
+                return [];
+            const dispatch = ENTRY_DISPATCH[section];
+            const out = [];
+            for (const entry of entries) {
+                const info = dispatch[entry.entryType];
+                if (!info) {
+                    throw new Error(`Unknown ${section} entry type: ${entry.entryType}`);
+                }
+                if (entry.entryType === 'error') {
+                    out.push({
+                        entryType: 'error',
+                        errorType: entry.errorType ?? '',
+                        errorMessage: entry.errorMessage ?? '',
+                        fieldValues: {},
+                    });
+                }
+                else {
+                    if (!entry.elementName) {
+                        throw new Error(`${section} ${entry.entryType} entry is missing elementName`);
+                    }
+                    const elementId = await resolve(modelId, info.resolveType, entry.elementName);
+                    out.push({
+                        entryType: entry.entryType,
+                        elementId,
+                        fieldValues: entry.fieldValues ?? {},
+                    });
+                }
+            }
+            return out;
+        };
+        const given = await buildEntries('given', spec.given);
+        const when = await buildEntries('when', spec.when);
+        const then = await buildEntries('then', spec.then);
+        unwrap(await sdk.createScenario({
+            body: {
+                modelId,
+                sliceId,
+                scenarioId,
+                name: spec.name,
+                ...(spec.description ? { description: spec.description } : {}),
+                given,
+                when,
+                then,
+            },
+        }));
+        const entryCount = given.length + when.length + then.length;
+        console.log(`Added scenario "${spec.name}"${entryCount > 0 ? ` with ${entryCount} entries` : ''}.`);
+    });
+    // add entry --scenario <name> --section given|when|then --type event|command|readmodel|error --element <name> [--error-type <type>] [--error-message <msg>]
+    add.command('entry')
+        .description('Add a GWT entry to a scenario')
+        .requiredOption('--scenario <name>', 'Scenario name')
+        .requiredOption('--section <section>', 'Section: given, when, or then')
+        .requiredOption('--type <type>', 'Entry type: event, command, readmodel, or error')
+        .option('--element <name>', 'Element name (required unless --type error)')
+        .option('--error-type <type>', 'Error type (for --type error)')
+        .option('--error-message <msg>', 'Error message (for --type error)')
+        .option('--position <n>', 'Position within section (appends at end by default)', parseInt)
+        .action(async (opts) => {
+        const modelId = requireModelId();
+        const scenarioId = await resolveScenarioId(modelId, opts.scenario, getGlobalId());
+        const entry = {
+            entryType: opts.type,
+            elementName: opts.element,
+            errorType: opts.errorType,
+            errorMessage: opts.errorMessage,
+        };
+        // Use a high position to append at end if not specified
+        const position = opts.position ?? 9999;
+        await addEntries(modelId, scenarioId, opts.section, [entry], position);
+        console.log(`Added ${opts.section} ${opts.type} entry${opts.element ? ` "${opts.element}"` : ''}.`);
+    });
+}

package/dist/commands/auth.js

@@ -0,0 +1,14 @@
+import { login } from '../slices/login/index';
+import { logout } from '../slices/logout/index';
+import { whoami } from '../slices/whoami/index';
+export function registerAuthCommands(program) {
+    program.command('login')
+        .description('Log in to Event Modeler')
+        .action(() => login());
+    program.command('logout')
+        .description('Log out of Event Modeler')
+        .action(() => logout());
+    program.command('whoami')
+        .description('Show current authentication status')
+        .action(() => whoami());
+}

package/dist/commands/create.js

@@ -0,0 +1,192 @@
+import { getGlobalId } from '../lib/globals';
+import { randomUUID } from 'node:crypto';
+import { requireModelId } from '../lib/model';
+import { resolve, resolveAnyElement, unwrap, elementIdKey } from '../lib/resolve';
+import * as sdk from '../api/generated/sdk.gen';
+const FLOW_DISPATCH = {
+    'screen->command': { fn: sdk.specifyScreenToCommandFlow, sourceHandle: 'bottom-source', targetHandle: 'top-target' },
+    'command->event': { fn: sdk.specifyCommandToEventFlow, sourceHandle: 'bottom-source', targetHandle: 'top-target' },
+    'command->external-event': { fn: sdk.specifyCommandToExternalEventFlow, sourceHandle: 'bottom-source', targetHandle: 'top-target' },
+    'event->readmodel': { fn: sdk.specifyEventToReadModelFlow, sourceHandle: 'bottom-source', targetHandle: 'top-target' },
+    'readmodel->screen': { fn: sdk.specifyReadModelToScreenFlow, sourceHandle: 'top-source', targetHandle: 'bottom-target' },
+    'readmodel->processor': { fn: sdk.specifyReadModelToProcessorFlow, sourceHandle: 'top-source', targetHandle: 'bottom-target' },
+    'processor->command': { fn: sdk.specifyProcessorToCommandFlow, sourceHandle: 'right-source', targetHandle: 'left-target' },
+    'external-event->processor': { fn: sdk.specifyExternalEventToProcessorFlow, sourceHandle: 'top-source', targetHandle: 'bottom-target' },
+};
+// Canonical dimensions per element type — matches frontend ELEMENT_DIMENSIONS.
+// Sizes are not user-configurable; the CLI always sends these so dimensions stay
+// consistent with the canvas's rendered components.
+const PLACE_MAP = {
+    command: { fn: sdk.placeCommandSticky, idKey: 'commandStickyId', nameKey: 'name', width: 160, height: 100 },
+    event: { fn: sdk.placeEventSticky, idKey: 'eventStickyId', nameKey: 'name', width: 160, height: 100 },
+    readmodel: { fn: sdk.placeReadModelSticky, idKey: 'readModelStickyId', nameKey: 'name', width: 160, height: 100 },
+    screen: { fn: sdk.placeScreen, idKey: 'screenId', nameKey: 'name', width: 180, height: 120 },
+    processor: { fn: sdk.placeProcessor, idKey: 'processorId', nameKey: 'name', width: 120, height: 120 },
+    'external-event': { fn: sdk.placeExternalEvent, idKey: 'externalEventId', nameKey: 'name', width: 160, height: 100 },
+    aggregate: { fn: sdk.placeAggregate, idKey: 'aggregateId', nameKey: 'name', width: 300, height: 200 },
+    actor: { fn: sdk.placeActor, idKey: 'actorId', nameKey: 'name', width: 300, height: 200 },
+    chapter: { fn: sdk.placeChapter, idKey: 'chapterId', nameKey: 'name', width: 800, height: 1200 },
+    context: { fn: sdk.placeContext, idKey: 'contextId', nameKey: 'name', width: 300, height: 200 },
+    note: { fn: sdk.placeNote, idKey: 'noteId', nameKey: 'title', width: 200, height: 150 },
+    swimlane: { fn: sdk.placeSwimLane, idKey: 'swimLaneId', nameKey: 'name', width: 300, height: 200 },
+    slice: { fn: sdk.placeSlice, idKey: 'sliceId', nameKey: 'name', width: 300, height: 200 },
+};
+// Linked copy placement — these reference an original element
+const LINKED_COPY_MAP = {
+    event: { fn: sdk.placeEventStickyLinkedCopy, idKey: 'eventStickyId', originalKey: 'originalEventStickyId', resolveType: 'event', width: 160, height: 100 },
+    readmodel: { fn: sdk.placeReadModelStickyLinkedCopy, idKey: 'readModelStickyId', originalKey: 'originalReadModelStickyId', resolveType: 'readmodel', width: 160, height: 100 },
+    screen: { fn: sdk.placeScreenLinkedCopy, idKey: 'screenId', originalKey: 'originalScreenId', resolveType: 'screen', width: 180, height: 120 },
+    'external-event': { fn: sdk.placeExternalEventLinkedCopy, idKey: 'copyId', originalKey: 'originalExternalEventId', resolveType: 'external-event', width: 160, height: 100 },
+};
+// Linked copy move — different SDK functions from regular move
+const MOVE_LINKED_COPY_MAP = {
+    event: sdk.moveEventStickyLinkedCopy,
+    readmodel: sdk.moveReadModelStickyLinkedCopy,
+    screen: sdk.moveScreenLinkedCopy,
+    'external-event': sdk.moveExternalEventLinkedCopy,
+};
+// Linked copy remove
+const REMOVE_LINKED_COPY_MAP = {
+    event: sdk.removeEventStickyLinkedCopy,
+    readmodel: sdk.removeReadModelStickyLinkedCopy,
+    screen: sdk.removeScreenLinkedCopy,
+    'external-event': sdk.removeExternalEventLinkedCopy,
+};
+export function registerCreateCommands(program) {
+    const create = program.command('create').description('Create new elements');
+    // create model <name>
+    create.command('model <name>')
+        .description('Create a new event model')
+        .action(async (name) => {
+        const result = unwrap(await sdk.createModel({ body: { name } }));
+        const modelId = result.modelId;
+        console.log(`Created model "${name}".`);
+        console.log(`Model ID: ${modelId}`);
+        console.log(`Run: eventmodeler init --model ${modelId}`);
+    });
+    create.command('slice <json>')
+        .description('Create a full slice from JSON specification')
+        .action(async (json) => {
+        const modelId = requireModelId();
+        const spec = JSON.parse(json);
+        unwrap(await sdk.createSlice({ body: { modelId, sliceId: randomUUID(), ...spec } }));
+        console.log('Created slice.');
+    });
+    create.command('flow')
+        .description('Create a flow between two elements')
+        .requiredOption('--from <source>', 'Source element name')
+        .requiredOption('--to <target>', 'Target element name')
+        .option('--source-handle <handle>', 'Source handle ID (default: auto based on flow type)')
+        .option('--target-handle <handle>', 'Target handle ID (default: auto based on flow type)')
+        .action(async (opts) => {
+        const modelId = requireModelId();
+        const source = await resolveAnyElement(modelId, opts.from);
+        const target = await resolveAnyElement(modelId, opts.to);
+        const flowKey = `${source.elementType}->${target.elementType}`;
+        const config = FLOW_DISPATCH[flowKey];
+        if (!config)
+            throw new Error(`No flow type for ${flowKey}. Valid: ${Object.keys(FLOW_DISPATCH).join(', ')}`);
+        const sourceHandle = opts.sourceHandle ?? config.sourceHandle;
+        const targetHandle = opts.targetHandle ?? config.targetHandle;
+        const sourceKey = elementIdKey(source.elementType);
+        const targetKey = elementIdKey(target.elementType);
+        unwrap(await config.fn({
+            body: {
+                modelId,
+                flowId: randomUUID(),
+                [sourceKey]: source.elementId,
+                [targetKey]: target.elementId,
+                sourceHandle,
+                targetHandle,
+            }
+        }));
+        console.log(`Created ${flowKey} flow (${sourceHandle} → ${targetHandle})`);
+    });
+    // place <type> <name> --x <n> --y <n>
+    // For aggregate: also --id-field-name and --id-field-type
+    const validTypes = Object.keys(PLACE_MAP).join(', ');
+    create.command('place <type> <name>')
+        .description(`Place a new element on the canvas. Types: ${validTypes}`)
+        .requiredOption('--x <n>', 'X coordinate', Number)
+        .requiredOption('--y <n>', 'Y coordinate', Number)
+        .option('--id-field-name <name>', 'Aggregate ID field name (aggregates only)')
+        .option('--id-field-type <type>', 'Aggregate ID field type (aggregates only)', 'UUID')
+        .action(async (type, name, opts) => {
+        const modelId = requireModelId();
+        const config = PLACE_MAP[type];
+        if (!config)
+            throw new Error(`Unknown type: ${type}. Valid: ${validTypes}`);
+        const body = {
+            modelId,
+            [config.idKey]: randomUUID(),
+            [config.nameKey]: name,
+            x: opts.x,
+            y: opts.y,
+            width: config.width,
+            height: config.height,
+        };
+        // Aggregate needs ID field info
+        if (type === 'aggregate') {
+            body.aggregateIdFieldName = opts.idFieldName ?? 'id';
+            body.aggregateIdFieldType = opts.idFieldType ?? 'UUID';
+        }
+        unwrap(await config.fn({ body }));
+        console.log(`Placed ${type} "${name}" at (${opts.x}, ${opts.y}).`);
+    });
+    // place linked-copy <type> <originalName> --x <n> --y <n>
+    const linkableTypes = Object.keys(LINKED_COPY_MAP).join(', ');
+    create.command('place-copy <type> [originalName]')
+        .description(`Place a linked copy of an element. Types: ${linkableTypes}`)
+        .requiredOption('--x <n>', 'X coordinate', Number)
+        .requiredOption('--y <n>', 'Y coordinate', Number)
+        .action(async (type, originalName, opts) => {
+        const modelId = requireModelId();
+        const config = LINKED_COPY_MAP[type];
+        if (!config)
+            throw new Error(`Cannot create linked copies of type: ${type}. Valid: ${linkableTypes}`);
+        const originalId = await resolve(modelId, config.resolveType, originalName ?? '', getGlobalId());
+        const body = {
+            modelId,
+            [config.idKey]: randomUUID(),
+            [config.originalKey]: originalId,
+            x: opts.x,
+            y: opts.y,
+        };
+        // External event linked copy has no width/height in its command
+        if (type !== 'external-event') {
+            body.width = config.width;
+            body.height = config.height;
+        }
+        unwrap(await config.fn({ body }));
+        console.log(`Placed linked copy of ${type} at (${opts.x}, ${opts.y}).`);
+    });
+    // move-copy <type> [name] --x <n> --y <n>  (uses --id for targeting specific copy)
+    create.command('move-copy <type> [name]')
+        .description(`Move a linked copy. Types: ${linkableTypes}`)
+        .requiredOption('--x <n>', 'X coordinate', Number)
+        .requiredOption('--y <n>', 'Y coordinate', Number)
+        .action(async (type, name, opts) => {
+        const modelId = requireModelId();
+        const fn = MOVE_LINKED_COPY_MAP[type];
+        if (!fn)
+            throw new Error(`Cannot move linked copies of type: ${type}. Valid: ${linkableTypes}`);
+        const id = await resolve(modelId, type, name ?? '', getGlobalId());
+        // External event linked copies use 'copyId', others use standard elementIdKey
+        const key = type === 'external-event' ? 'copyId' : elementIdKey(type);
+        unwrap(await fn({ body: { modelId, [key]: id, x: opts.x, y: opts.y } }));
+        console.log(`Moved linked copy to (${opts.x}, ${opts.y}).`);
+    });
+    // remove-copy <type> [name]  (uses --id for targeting specific copy)
+    create.command('remove-copy <type> [name]')
+        .description(`Remove a linked copy. Types: ${linkableTypes}`)
+        .action(async (type, name) => {
+        const modelId = requireModelId();
+        const fn = REMOVE_LINKED_COPY_MAP[type];
+        if (!fn)
+            throw new Error(`Cannot remove linked copies of type: ${type}. Valid: ${linkableTypes}`);
+        const id = await resolve(modelId, type, name ?? '', getGlobalId());
+        const key = type === 'external-event' ? 'copyId' : elementIdKey(type);
+        unwrap(await fn({ body: { modelId, [key]: id } }));
+        console.log(`Removed linked copy.`);
+    });
+}

package/dist/commands/design.js

@@ -0,0 +1,108 @@
+import { getGlobalId } from '../lib/globals';
+import { requireModelId } from '../lib/model';
+import { resolve, unwrap } from '../lib/resolve';
+import { ExcalidrawDesign, formatZodError } from '../lib/excalidraw-schema';
+import * as sdk from '../api/generated/sdk.gen';
+const DESIGN_HELP = `
+INPUT FORMAT
+  A JSON array of Excalidraw element objects — NOT the full Excalidraw
+  document ({ type, version, elements, appState, files }). Pass only the
+  inner "elements" array.
+
+ELEMENT TYPES
+  rectangle, ellipse, diamond, line, arrow, text, freedraw, image,
+  frame, magicframe, iframe, embeddable
+
+REQUIRED FIELDS (all types)
+  id          string   Unique within the array
+  type        string   One of the element types above
+  x, y        number   Top-left position
+  width       number   Box width
+  height      number   Box height
+
+REQUIRED FIELDS (text elements)
+  id, type, x, y       As above (width/height optional for text)
+  text        string   The rendered text
+  fontSize    number   Pixels
+
+OPTIONAL STYLE FIELDS
+  strokeColor       string   Any color string (hex "#000", "transparent", or
+                             named — Excalidraw accepts any string here)
+  backgroundColor   string   As above; default "transparent"
+  fillStyle         enum     "solid" | "hachure" | "cross-hatch" | "zigzag"
+  strokeStyle       enum     "solid" | "dashed" | "dotted"
+  strokeWidth       number   Non-negative (default 2, typical 1 / 2 / 4)
+  roughness         number   Non-negative (0 clean, 1 artist [default], 2 sketchy)
+  opacity           number   0–100 (default 100)
+  angle             number   Rotation in radians
+  fontFamily        number   Positive int. Known codes:
+                             1 Virgil · 2 Helvetica · 3 Cascadia ·
+                             5 Excalifont (default) · 6 Nunito ·
+                             7 Lilita One · 8 Comic Shanns ·
+                             9 Liberation Sans · 10 Assistant
+  textAlign         enum     "left" | "center" | "right"
+  verticalAlign     enum     "top" | "middle" | "bottom"
+
+EXAMPLE
+  eventmodeler design "Login" '[
+    {"id":"bg","type":"rectangle","x":0,"y":0,"width":320,"height":200,
+     "strokeColor":"#000","backgroundColor":"#fff","fillStyle":"solid",
+     "strokeWidth":1,"roughness":0,"opacity":100},
+    {"id":"title","type":"text","x":20,"y":20,"width":280,"height":30,
+     "text":"Sign in","fontSize":20,"fontFamily":2,"textAlign":"left",
+     "strokeColor":"#000","opacity":100},
+    {"id":"btn","type":"rectangle","x":20,"y":150,"width":100,"height":32,
+     "strokeColor":"#000","backgroundColor":"#4a90e2","fillStyle":"solid",
+     "strokeWidth":1,"roughness":0,"opacity":100}
+  ]'
+
+NOTES
+  - An empty array ([]) clears the screen's design.
+  - The screen must already exist (create it first with the place command).
+`;
+export function registerDesignCommands(program) {
+    program.command('design')
+        .description('Update screen design (Excalidraw JSON array)')
+        .argument('<names...>', 'Screen name followed by JSON array')
+        .addHelpText('after', DESIGN_HELP)
+        .action(async (names) => {
+        const modelId = requireModelId();
+        const idOverride = getGlobalId();
+        const jsonIdx = names.findIndex(a => a.startsWith('['));
+        if (jsonIdx === -1) {
+            console.error('Error: Design must be a JSON array of Excalidraw elements');
+            console.error('');
+            console.error('Example:');
+            console.error('  eventmodeler design "My Screen" \'[');
+            console.error('    {"id":"1","type":"rectangle","x":10,"y":10,"width":150,"height":30,"strokeColor":"#000","backgroundColor":"#eee","fillStyle":"solid","strokeWidth":1,"roughness":0,"opacity":100},');
+            console.error('    {"id":"2","type":"text","x":20,"y":15,"width":80,"height":20,"text":"Hello","fontSize":14,"fontFamily":1,"textAlign":"left","strokeColor":"#000","opacity":100}');
+            console.error('  ]\'');
+            process.exit(1);
+        }
+        const screenName = names.slice(0, jsonIdx).join(' ');
+        const json = names.slice(jsonIdx).join(' ');
+        let parsed;
+        try {
+            parsed = JSON.parse(json);
+        }
+        catch (e) {
+            console.error(`Invalid JSON: ${e.message}`);
+            process.exit(1);
+        }
+        const result = ExcalidrawDesign.safeParse(parsed);
+        if (!result.success) {
+            console.error('Invalid Excalidraw design:');
+            for (const e of formatZodError(result.error))
+                console.error(`  ${e}`);
+            console.error('');
+            console.error('Run "eventmodeler design --help" for the full schema.');
+            process.exit(1);
+        }
+        if (result.data.length === 0) {
+            console.error('Design array is empty — this will clear the screen design');
+        }
+        const screenId = await resolve(modelId, 'screen', screenName, idOverride);
+        unwrap(await sdk.updateScreenDesign({ body: { modelId, screenId, design: json } }));
+        console.log(`Updated design on "${idOverride ? screenId : screenName}" (${result.data.length} elements)`);
+    });
+}

package/dist/commands/guide.js

@@ -0,0 +1,15 @@
+import { runHelp } from '../slices/help/index';
+export function registerGuideCommands(program) {
+    program.command('help [query...]')
+        .description('Show task-oriented help for working with event models')
+        .action((queryParts) => {
+        const query = queryParts.length > 0 ? queryParts.join(' ') : undefined;
+        runHelp(query);
+    });
+    program.command('guide [query...]')
+        .description('Alias for "help"')
+        .action((queryParts) => {
+        const query = queryParts.length > 0 ? queryParts.join(' ') : undefined;
+        runHelp(query);
+    });
+}