@eventcatalog/cli 0.3.3 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 ## @eventcatalog/cli
 
-Command-line interface for [EventCatalog](https://eventcatalog.dev). Execute catalog operations directly from your terminal to automate your EventCatalog.
+Command-line interface for [EventCatalog](https://eventcatalog.dev). Import and export catalogs using the [EventCatalog DSL](https://www.eventcatalog.dev/docs/development/dsl/introduction), run SDK functions directly from your terminal, and automate your EventCatalog workflows.
 
 ### Installation
 
@@ -11,7 +11,7 @@ npm i @eventcatalog/cli
 ### Running with npx (no installation required)
 
 ```bash
-npx @eventcatalog/cli --dir <catalog-path> <function-name> [args...]
+npx @eventcatalog/cli --dir <catalog-path> <command> [args...]
 ```
 
 ### Running after installation
@@ -19,77 +19,180 @@ npx @eventcatalog/cli --dir <catalog-path> <function-name> [args...]
 If you've installed the package, the `eventcatalog` command is available:
 
 ```bash
-eventcatalog --dir <catalog-path> <function-name> [args...]
+eventcatalog --dir <catalog-path> <command> [args...]
 ```
 
-### Common Operations
+### Global Options
 
-**List all available functions:**
+| Option             | Description                    | Default                 |
+| ------------------ | ------------------------------ | ----------------------- |
+| `-d, --dir <path>` | Path to your catalog directory | `.` (current directory) |
+
+---
+
+### Commands
+
+#### `import` — Import DSL files into your catalog
+
+Parse `.ec` (EventCatalog DSL) files and write them as catalog resources (markdown + frontmatter).
 
 ```bash
-npx @eventcatalog/cli list
+eventcatalog import [files...] [options]
 ```
 
-**Get an event:**
+**Options:**
+
+| Option      | Description                                                  |
+| ----------- | ------------------------------------------------------------ |
+| `--stdin`   | Read DSL from stdin instead of files                         |
+| `--dry-run` | Preview changes without writing to disk                      |
+| `--flat`    | Write all resources at the top level (no nested directories) |
+| `--no-init` | Skip the interactive catalog scaffolding prompt              |
+
+**Examples:**
 
 ```bash
-npx @eventcatalog/cli --dir ./my-catalog getEvent "OrderCreated"
-npx @eventcatalog/cli --dir ./my-catalog getEvent "OrderCreated" "1.0.0"
+# Import a single DSL file
+eventcatalog import architecture.ec
+
+# Import multiple files
+eventcatalog import services.ec events.ec domains.ec
+
+# Pipe DSL from another tool
+cat architecture.ec | eventcatalog import --stdin
+
+# Preview what would change
+eventcatalog import architecture.ec --dry-run
+
+# Import without nesting services inside domains
+eventcatalog import architecture.ec --flat
 ```
 
-**Get all events:**
+**Behaviors:**
+
+- If no `eventcatalog.config.js` exists, you'll be prompted to scaffold a new catalog (skip with `--no-init`).
+- Importing a newer version of an existing resource automatically versions the old one.
+- Re-importing the same version overwrites the existing resource.
+- Referenced resources that aren't defined in the DSL (e.g., `sends event OrderCreated` without an inline body) are created as stubs at version `0.0.1`.
+- Existing resource locations are preserved — updates go to where the resource already lives.
+
+---
+
+#### `export` — Export catalog resources to DSL
+
+Convert catalog resources back into EventCatalog DSL (`.ec`) format.
 
 ```bash
-npx @eventcatalog/cli --dir ./my-catalog getEvents
-npx @eventcatalog/cli --dir ./my-catalog getEvents '{"latestOnly":true}'
+eventcatalog export [options]
 ```
 
-**Write an event:**
+**Options:**
+
+| Option                | Description                                                                                  |
+| --------------------- | -------------------------------------------------------------------------------------------- |
+| `--all`               | Export the entire catalog                                                                    |
+| `--resource <type>`   | Resource type to export (`event`, `command`, `query`, `service`, `domain`, `channel`)        |
+| `--id <id>`           | Export a specific resource by ID (requires `--resource`)                                     |
+| `--version <version>` | Export a specific version (requires `--resource` and `--id`)                                 |
+| `--hydrate`           | Include referenced resources (e.g., messages referenced by a service)                        |
+| `--stdout`            | Print to stdout instead of writing a file                                                    |
+| `--playground`        | Open the exported DSL in the [EventCatalog Playground](https://playground.eventcatalog.dev/) |
+| `--output <path>`     | Custom output file path                                                                      |
+
+**Examples:**
 
 ```bash
-npx @eventcatalog/cli --dir ./my-catalog writeEvent '{"id":"OrderCreated","name":"Order Created","version":"1.0.0","markdown":"# Order Created Event"}'
+# Export a single event
+eventcatalog export --resource event --id OrderCreated --stdout
+
+# Export all services with their referenced messages
+eventcatalog export --resource service --hydrate --stdout
+
+# Export the entire catalog to a file
+eventcatalog export --all --output catalog.ec
+
+# Export and open in the playground
+eventcatalog export --all --playground
 ```
 
-**Get a service:**
+---
+
+#### `list` — List available SDK functions
+
+Display all SDK functions organized by category (Events, Commands, Queries, Services, Domains, etc.).
 
 ```bash
-npx @eventcatalog/cli --dir ./my-catalog getService "InventoryService"
+eventcatalog list
 ```
 
-**Add an event to a service:**
+---
+
+#### `<function>` — Run any SDK function
+
+Any unrecognized command is treated as an SDK function call. Output is JSON.
 
 ```bash
-npx @eventcatalog/cli --dir ./my-catalog addEventToService "InventoryService" "sends" '{"id":"OrderCreated","version":"1.0.0"}'
+eventcatalog <function-name> [args...]
 ```
 
-### Piping to Other Tools
+**Examples:**
+
+```bash
+# Get an event (latest version)
+eventcatalog --dir ./my-catalog getEvent "OrderCreated"
+
+# Get a specific version
+eventcatalog --dir ./my-catalog getEvent "OrderCreated" "1.0.0"
+
+# Get all events with options
+eventcatalog --dir ./my-catalog getEvents '{"latestOnly":true}'
 
-Output is JSON by default, making it easy to pipe to tools like `jq`:
+# Write an event
+eventcatalog --dir ./my-catalog writeEvent '{"id":"OrderCreated","name":"Order Created","version":"1.0.0","markdown":"# Order Created"}'
+
+# Get a service
+eventcatalog --dir ./my-catalog getService "InventoryService"
+
+# Add an event to a service
+eventcatalog --dir ./my-catalog addEventToService "InventoryService" "sends" '{"id":"OrderCreated","version":"1.0.0"}'
+```
+
+Run `eventcatalog list` to see all available functions.
+
+---
+
+### Piping and Composing
+
+Output from SDK functions is JSON, making it easy to pipe to tools like `jq`:
 
 ```bash
-# Get all events and filter by version
-npx @eventcatalog/cli --dir ./my-catalog getEvents | jq '.[] | select(.version == "1.0.0")'
+# Filter events by version
+eventcatalog --dir ./my-catalog getEvents | jq '.[] | select(.version == "1.0.0")'
 
 # Count total events
-npx @eventcatalog/cli --dir ./my-catalog getEvents | jq 'length'
+eventcatalog --dir ./my-catalog getEvents | jq 'length'
 
 # Extract event IDs
-npx @eventcatalog/cli --dir ./my-catalog getEvents | jq '.[].id'
+eventcatalog --dir ./my-catalog getEvents | jq '.[].id'
 ```
 
 ### Arguments Format
 
 Arguments are automatically parsed:
 
-- **JSON objects:** `'{"key":"value"}'` - parsed as object
-- **JSON arrays:** `'["item1","item2"]'` - parsed as array
-- **Booleans:** `true` or `false` - parsed as boolean
-- **Numbers:** `42` or `3.14` - parsed as number
-- **Strings:** anything else - kept as string
+- **JSON objects:** `'{"key":"value"}'` — parsed as object
+- **JSON arrays:** `'["item1","item2"]'` — parsed as array
+- **Booleans:** `true` or `false` — parsed as boolean
+- **Numbers:** `42` or `3.14` — parsed as number
+- **Strings:** anything else — kept as string
+
+### Documentation
 
-See the [SDK docs](https://www.eventcatalog.dev/docs/sdk) for more information and examples.
+- [EventCatalog DSL](https://www.eventcatalog.dev/docs/development/dsl/introduction)
+- [SDK reference](https://www.eventcatalog.dev/docs/sdk)
+- [CLI documentation](https://www.eventcatalog.dev/docs/development/cli)
 
-# Enterprise support
+## Enterprise support
 
 Interested in collaborating with us? Our offerings include dedicated support, priority assistance, feature development, custom integrations, and more.
 

package/dist/cli/index.js

@@ -250,19 +250,45 @@ ${items.join("\n\n")}`);
   }
   return sections.join("\n\n");
 }
-function buildVisualizerBlock(dsl, name, filterTypes) {
-  const types = Array.isArray(filterTypes) ? filterTypes : [filterTypes];
-  const entries = [];
-  for (const line of dsl.split("\n")) {
-    const trimmed = line.trimStart();
+function extractResourceDefinitions(dsl, filterTypes) {
+  const results = [];
+  const lines = dsl.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trimStart();
     const parts = trimmed.split(/\s/);
     const keyword = parts[0];
     const id = parts[1];
-    if (!types.includes(keyword)) continue;
+    if (!filterTypes.includes(keyword)) continue;
     if (!id || !trimmed.endsWith("{")) continue;
-    entries.push(`  ${keyword} ${id}`);
+    let version2;
+    for (let j = i + 1; j < lines.length; j++) {
+      const inner = lines[j].trim();
+      if (inner === "}") break;
+      const vMatch = inner.match(/^version\s+(.+)$/);
+      if (vMatch) {
+        version2 = vMatch[1];
+        break;
+      }
+    }
+    results.push({ keyword, id, version: version2 });
+  }
+  return results;
+}
+function buildVisualizerBlock(dsl, name, filterTypes) {
+  const types = Array.isArray(filterTypes) ? filterTypes : [filterTypes];
+  const definitions = extractResourceDefinitions(dsl, types);
+  if (definitions.length === 0) return "";
+  const counts = /* @__PURE__ */ new Map();
+  for (const def of definitions) {
+    const key = `${def.keyword}:${def.id}`;
+    counts.set(key, (counts.get(key) || 0) + 1);
   }
-  if (entries.length === 0) return "";
+  const entries = definitions.map((def) => {
+    const key = `${def.keyword}:${def.id}`;
+    const needsVersion = (counts.get(key) || 0) > 1 && def.version;
+    const ref = needsVersion ? `${def.id}@${def.version}` : def.id;
+    return `  ${def.keyword} ${ref}`;
+  });
   return `
 visualizer main {
   name "${name}"
@@ -356,7 +382,8 @@ async function exportResource(options) {
   }
   const rawDsl = await sdk.toDSL(data, { type, hydrate });
   const grouped = hydrate ? groupDSLBlocks(rawDsl) : rawDsl;
-  const vizBlock = buildVisualizerBlock(grouped, `View of ${id}`, type);
+  const vizTypes = hydrate ? [...RESOURCE_TYPES] : [type];
+  const vizBlock = buildVisualizerBlock(grouped, `View of ${id}`, vizTypes);
   const dsl = vizBlock ? `${grouped}
 ${vizBlock}` : grouped;
   if (stdout) {
@@ -385,6 +412,17 @@ var import_node_crypto = require("crypto");
 var import_node_readline = require("readline");
 var import_gray_matter = __toESM(require("gray-matter"));
 var import_sdk4 = __toESM(require("@eventcatalog/sdk"));
+
+// src/cli/dsl-managed-keys.ts
+var MESSAGE_MANAGED_KEYS = /* @__PURE__ */ new Set(["id", "name", "version", "owners", "deprecated", "draft", "summary"]);
+var DSL_MANAGED_KEYS_BY_TYPE = {
+  domain: /* @__PURE__ */ new Set(["id", "name", "version", "owners", "deprecated", "draft", "summary", "services", "domains"]),
+  event: MESSAGE_MANAGED_KEYS,
+  command: MESSAGE_MANAGED_KEYS,
+  query: MESSAGE_MANAGED_KEYS
+};
+
+// src/cli/import.ts
 function normalizeImportedFrontmatter(type, frontmatter) {
   const normalized = { ...frontmatter };
   if (type === "container") {
@@ -399,6 +437,27 @@ function normalizeImportedFrontmatter(type, frontmatter) {
   }
   return normalized;
 }
+function toFrontmatter(resource) {
+  if (!resource || typeof resource !== "object") return {};
+  const { markdown: _markdown, ...frontmatter } = resource;
+  return frontmatter;
+}
+function mergeImportedFrontmatter(type, incomingFrontmatter, existing, latest) {
+  const normalizedIncoming = normalizeImportedFrontmatter(type, incomingFrontmatter);
+  const managedKeys = DSL_MANAGED_KEYS_BY_TYPE[type];
+  if (!managedKeys) {
+    return normalizedIncoming;
+  }
+  const baseFrontmatter = toFrontmatter(existing ?? latest);
+  const preservedFrontmatter = { ...baseFrontmatter };
+  for (const key of managedKeys) {
+    delete preservedFrontmatter[key];
+  }
+  return {
+    ...preservedFrontmatter,
+    ...normalizedIncoming
+  };
+}
 var RESOURCE_TYPE_FROM_FOLDER = {
   events: "event",
   commands: "command",
@@ -945,7 +1004,7 @@ async function importDSL(options) {
         }
       }
       const resourceData = {
-        ...normalizeImportedFrontmatter(resource.type, resource.frontmatter),
+        ...mergeImportedFrontmatter(resource.type, resource.frontmatter, existing, latest),
         markdown
       };
       const writeOptions = {