@eventcatalog/core 3.39.5 → 3.40.0

package/dist/docs/editor/how-to/review-and-commit-changes.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 9
+sidebar_label: Review and publish changes
+title: Review and publish editor changes
+description: Use the editor changes view to inspect local Git changes and publish a local commit.
+---
+
+EventCatalog Editor writes to your local catalog files. Use the **Changes** page to inspect what changed before you publish.
+
+## Open the Changes page
+
+Choose **Changes** from the editor navigation.
+
+If the catalog is a Git repository, the editor shows local changes grouped by EventCatalog resource.
+
+![Changes page with a grouped resource diff](../images/change-diff.png)
+
+## Inspect a file diff
+
+Open a changed file to view the unified diff.
+
+Use the diff to check:
+
+- The intended Markdown or MDX changed
+- Metadata changes are correct
+- Generated schema or specification paths look right
+- Unrelated files were not changed accidentally
+
+## Publish from the editor
+
+When the changes look right, click **Publish** in the editor.
+
+In the beta editor, **Publish** commits your changes locally to Git. It does not deploy your catalog or open a pull request.
+
+Use a short message that describes the catalog change, for example:
+
+```txt
+Document OrderPlaced event schema
+```
+
+## Continue with your team's workflow
+
+After publishing, use your existing Git workflow to share and release the change.
+
+For example:
+
+```bash
+git push
+```
+
+Then open a pull request if your team reviews catalog changes through GitHub or another Git hosting provider.
+
+::::info Pull request creation
+
+Built-in pull request creation is planned, but beta users should continue using their existing Git workflow after publishing local changes.
+
+::::

package/dist/docs/editor/how-to/run-locally.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 1
+sidebar_label: Run locally
+title: Run EventCatalog Editor locally
+description: Start EventCatalog Editor against a local EventCatalog project.
+---
+
+Use this guide when you want to start EventCatalog Editor on your machine.
+
+## Prerequisites
+
+You need:
+
+- Node.js 22 or later
+- Git
+- An EventCatalog project containing `eventcatalog.config.js`
+- EventCatalog Editor access through [EventCatalog Cloud](https://eventcatalog.cloud)
+
+## Run from a catalog directory
+
+Open a terminal in your EventCatalog project and run:
+
+```bash
+npx @eventcatalog/editor
+```
+
+The editor starts on [http://localhost:3900](http://localhost:3900).
+
+## Run with an explicit catalog path
+
+If you are not in the catalog directory, pass the catalog path:
+
+```bash
+npx @eventcatalog/editor --catalog /path/to/my-catalog
+```
+
+The directory must contain `eventcatalog.config.js`.
+
+## Choose a different editor port
+
+Use `--port` when port `3900` is already in use:
+
+```bash
+npx @eventcatalog/editor --port 3999
+```
+
+## Connect preview links to a running catalog
+
+The editor looks for a local EventCatalog preview on port `3000` by default.
+
+Start EventCatalog in your catalog project:
+
+```bash
+npm run dev
+```
+
+Then start the editor in another terminal:
+
+```bash
+npx @eventcatalog/editor
+```
+
+If your EventCatalog preview runs on another port, pass it to the editor:
+
+```bash
+npx @eventcatalog/editor --eventcatalog-port 3001
+```
+
+## Stop the editor
+
+Return to the terminal running the editor and press `Ctrl+C`.

package/dist/docs/editor/how-to/use-flow-editor.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 5
+sidebar_label: Flow Editor
+title: Use the Flow Editor
+description: Create and update EventCatalog flows visually with EventCatalog Editor.
+---
+
+Use the Flow Editor when you want to document a business process, user journey, or architecture workflow without editing the [flow](/docs/development/guides/flows/introduction) files by hand.
+
+Flow resources are still stored in your local EventCatalog project. The editor gives you a visual way to create and arrange the steps, then writes the change back to your catalog files.
+
+![Flow editor showing a service node in a business flow](../images/flow-editor.png)
+
+## Open a flow
+
+Start EventCatalog Editor and open a flow from the resource list.
+
+If you are creating a new flow, create it from the editor first, then open it from the flow list.
+
+Click the **Flow Editor** tab at the top of the resource to switch from the documentation view into the visual editor.
+
+## Add a step
+
+Use **Add step** or choose an empty node in the flow.
+
+The editor opens a picker so you can choose what kind of node belongs in the flow.
+
+![Flow editor node type picker](../images/flow-editor-pick-a-node.png)
+
+## Choose the right node
+
+Use the node picker to add the resource that best represents the next step.
+
+For example:
+
+- Add a [service](/docs/development/guides/services/introduction) when a system performs work
+- Add an [event](/docs/development/guides/messages/events/introduction) when something has happened
+- Add a [command](/docs/development/guides/messages/commands/introduction) when one system asks another system to do something
+- Add a [query](/docs/development/guides/messages/queries/introduction) when the flow reads information
+
+Use existing catalog resources when they already exist. Create new resources when the flow reveals something that is missing from the catalog.
+
+## Review the flow
+
+After adding steps, read the flow from left to right and check that it tells the story clearly.
+
+Check that:
+
+- The flow starts with the trigger or first meaningful step
+- Each step uses the most accurate resource type
+- Resource names match the language your team uses
+- The flow is clear enough for someone who was not in the design discussion
+
+## Preview the flow
+
+Use **Open Preview** to view the flow in your local EventCatalog site.
+
+Preview helps you check how the flow will look to readers before you publish the local commit.
+
+## Publish the change
+
+Open **Changes** and review the files the Flow Editor changed.
+
+When the diff looks right, click **Publish**. In the beta editor, **Publish** commits your changes locally to Git.
+
+After publishing, continue with your team's normal Git review and release workflow.

package/dist/docs/editor/how-to/use-slash-commands.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 6
+sidebar_label: Use slash commands
+title: Use slash commands
+description: Insert Markdown blocks and EventCatalog components from the rich editor.
+---
+
+Slash commands let you add content without remembering Markdown syntax or MDX component names.
+
+Type `/` in an empty paragraph to open the command menu. The menu shows matching blocks, grouped by purpose, with a visual preview of the selected command.
+
+![Slash command menu showing EventCatalog diagram components](../images/custom-slash-commands.png)
+
+## Insert a block
+
+1. Click into the resource documentation.
+2. Start a new empty paragraph.
+3. Type `/`.
+4. Search or scroll to the block you want.
+5. Press `Enter` or click the command.
+
+The editor inserts the matching Markdown or MDX block into the resource.
+
+## Add EventCatalog components
+
+Slash commands are useful for adding EventCatalog-specific components without switching to source mode.
+
+You can insert components such as:
+
+- Node Graph
+- Miro diagram
+- Draw.io diagram
+- Lucid diagram
+- IcePanel diagram
+- [Flow](/docs/development/guides/flows/introduction)
+- Mermaid diagram
+- Entity Map
+- Schema Viewer
+- Steps
+- Tiles
+- Accordion group
+- Prompt
+- Visibility
+- Admonitions such as note, tip, warning, danger, and info
+
+Some commands are available only when they make sense for the current resource. For example, **Schema Viewer** is available for [events](/docs/development/guides/messages/events/introduction), [commands](/docs/development/guides/messages/commands/introduction), and [queries](/docs/development/guides/messages/queries/introduction), while **Entity Map** is available for [domains](/docs/development/guides/domains/introduction).
+
+## Use visual previews
+
+The preview panel shows what the selected command is for before you insert it.
+
+Use this when you are deciding between similar blocks, such as diagram components or callout types.
+
+## Edit the inserted block
+
+After inserting a component, you can usually edit it directly in the rich editor.
+
+If the component needs configuration that is not exposed visually yet, switch to source mode and edit the MDX.
+
+## When to use source mode instead
+
+Use source mode when you need to:
+
+- Paste an existing MDX component
+- Change advanced component attributes
+- Edit custom components that the slash menu does not know about
+- Review the exact Markdown or MDX that will be saved

package/dist/docs/editor/reference/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Reference",
+  "position": 4,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Editor reference",
+    "description": "Lookup information for EventCatalog Editor commands, supported resources, content support, and troubleshooting."
+  }
+}

package/dist/docs/editor/reference/cli.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 1
+sidebar_label: CLI
+title: EventCatalog Editor CLI reference
+description: Command and option reference for running EventCatalog Editor.
+---
+
+Run the editor with:
+
+```bash
+npx @eventcatalog/editor
+```
+
+## Requirements
+
+- Node.js 22 or later
+- Git
+- An EventCatalog directory containing `eventcatalog.config.js`
+
+## Options
+
+| Option | Description | Default |
+| --- | --- | --- |
+| `--catalog <path>` | Path to the EventCatalog root to edit. | Current directory, a detected child catalog, or browser selection |
+| `--port <n>` | Port for the editor server. | `3900` |
+| `--eventcatalog-port <n>` | Port where local EventCatalog preview is running. | `3000` |
+| `--no-open` | Start the editor without opening the browser automatically. | Opens browser |
+| `--help`, `-h` | Show CLI help. |  |
+| `--version`, `-v` | Show the installed editor version. |  |
+
+## Examples
+
+Run from a catalog directory:
+
+```bash
+npx @eventcatalog/editor
+```
+
+Run against a specific catalog:
+
+```bash
+npx @eventcatalog/editor --catalog /Users/me/dev/my-catalog
+```
+
+Use a different editor port:
+
+```bash
+npx @eventcatalog/editor --port 3999
+```
+
+Use a different EventCatalog preview port:
+
+```bash
+npx @eventcatalog/editor --eventcatalog-port 3001
+```
+
+Start without opening a browser:
+
+```bash
+npx @eventcatalog/editor --no-open
+```

package/dist/docs/editor/reference/supported-content.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 3
+sidebar_label: Supported content
+title: Supported content and MDX
+description: Markdown, MDX, and component support in EventCatalog Editor.
+---
+
+EventCatalog Editor supports rich editing for common Markdown content and source editing for advanced Markdown and MDX.
+
+## Rich editor content
+
+The rich editor supports:
+
+- Headings
+- Paragraphs
+- Bold and italic text
+- Links
+- Bullet lists
+- Numbered lists
+- Blockquotes
+- Code blocks
+- Horizontal dividers
+- Tables
+
+Use `/` in an empty paragraph to open the slash command menu.
+
+![Slash command menu showing component previews](../images/custom-slash-commands.png)
+
+## Slash commands
+
+Slash commands can insert Markdown blocks and EventCatalog components from the rich editor.
+
+Common command groups include:
+
+- Text: headings, paragraphs, and quotes
+- Lists: bullet and ordered lists
+- Advanced: code blocks, dividers, and tables
+- Admonitions: note, tip, warning, danger, and info callouts
+- Diagrams: Node Graph, [Flow](/docs/development/guides/flows/introduction), Mermaid, Miro, Draw.io, Lucid, IcePanel, Entity Map, and Schema Viewer
+- Layout: Steps, Tiles, and Accordion group
+- AI: Prompt and Visibility blocks
+
+Some commands are resource-aware. For example, Schema Viewer appears for [events](/docs/development/guides/messages/events/introduction), [commands](/docs/development/guides/messages/commands/introduction), and [queries](/docs/development/guides/messages/queries/introduction), and Entity Map appears for [domains](/docs/development/guides/domains/introduction).
+
+## Source mode
+
+Use source mode for:
+
+- Frontmatter edits
+- Custom Markdown
+- MDX components
+- Content the rich editor does not expose yet
+
+Source mode edits the full document source.
+
+## MDX components
+
+The editor understands common EventCatalog MDX components and keeps unknown or complex components as blocks so they can round trip through the editor.
+
+Examples of EventCatalog content you may see include:
+
+- `NodeGraph`
+- `EntityMap`
+- `Mermaid`
+- `Steps`
+- `Schema`
+- `SchemaViewer`
+- `MessageTable`
+- `ChannelInformation`
+- `OpenAPI`
+- `AsyncAPI`
+- `Admonition`
+- `ResourceGroupList`
+
+If a component cannot be edited visually yet, use source mode.
+
+## Editor modes
+
+Use the header controls to switch between visual editing and source editing.
+
+![Editor header showing visual and source mode controls](../images/header.png)

package/dist/docs/editor/reference/supported-resources.md

@@ -0,0 +1,51 @@
+---
+sidebar_position: 2
+sidebar_label: Supported resources
+title: Supported resources
+description: Resource types and capabilities currently supported by EventCatalog Editor.
+---
+
+EventCatalog Editor can browse and edit the main EventCatalog resource types.
+
+| Resource type | Browse | Edit docs | Edit metadata | Create | Delete | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| [Domain](/docs/development/guides/domains/introduction) | Yes | Yes | Yes | Yes | Yes | Supports services, messages, entities, specifications, and ubiquitous language |
+| [Service](/docs/development/guides/services/introduction) | Yes | Yes | Yes | Yes | Yes | Supports message relationships, data store relationships, and specifications |
+| [Event](/docs/development/guides/messages/events/introduction) | Yes | Yes | Yes | Yes | Yes | Supports schemas and producer/consumer relationships |
+| [Command](/docs/development/guides/messages/commands/introduction) | Yes | Yes | Yes | Yes | Yes | Supports schemas, operations, and producer/consumer relationships |
+| [Query](/docs/development/guides/messages/queries/introduction) | Yes | Yes | Yes | Yes | Yes | Supports schemas, operations, and producer/consumer relationships |
+| [Channel](/docs/development/guides/channels/introduction) | Yes | Yes | Yes | Yes | Yes | Supports common metadata |
+| [Entity](/docs/development/guides/domains/entities/introduction) | Yes | Yes | Yes | Yes | Yes | Supports common metadata |
+| [Data store](/docs/development/guides/data/introduction) | Yes | Yes | Yes | Yes | Yes | Represented as EventCatalog container resources |
+| [Flow](/docs/development/guides/flows/introduction) | Yes | Yes | Yes | Yes | Yes | Supports flow step editing |
+| [User](/docs/development/guides/owners/users/introduction) | Yes | Yes | Yes | Yes | Yes | Versionless |
+| [Team](/docs/development/guides/owners/teams/introduction) | Yes | Yes | Yes | Yes | Yes | Versionless |
+
+## Schemas
+
+Schemas are supported on:
+
+- [Events](/docs/development/guides/messages/events/introduction)
+- [Commands](/docs/development/guides/messages/commands/introduction)
+- [Queries](/docs/development/guides/messages/queries/introduction)
+
+## Specifications
+
+Specifications are supported on:
+
+- [Domains](/docs/development/guides/domains/introduction)
+- [Services](/docs/development/guides/services/introduction)
+
+Supported specification types:
+
+- OpenAPI
+- AsyncAPI
+- GraphQL
+
+## Versionless resources
+
+Users and teams are versionless in EventCatalog. Other resources use versions.
+
+## Beta limitations
+
+Some advanced resource fields may still require source mode. If a visual field is missing, switch to source mode and edit the underlying Markdown, MDX, or frontmatter directly.

package/dist/docs/editor/reference/troubleshooting.md

@@ -0,0 +1,76 @@
+---
+sidebar_position: 4
+sidebar_label: Troubleshooting
+title: Troubleshooting EventCatalog Editor
+description: Fix common issues when running EventCatalog Editor.
+---
+
+## The editor cannot find my catalog
+
+Check that:
+
+- You are running the editor from the catalog directory, or using `--catalog`
+- The directory contains `eventcatalog.config.js`
+- The config file can be loaded by Node.js
+- Catalog dependencies are installed
+
+Run with an explicit path:
+
+```bash
+npx @eventcatalog/editor --catalog /path/to/my-catalog
+```
+
+## I cannot sign in
+
+The editor uses [EventCatalog Cloud](https://eventcatalog.cloud) for access.
+
+If sign-in fails:
+
+- Check your internet connection
+- Try signing out of [EventCatalog Cloud](https://eventcatalog.cloud) and signing in again
+- Restart the local editor
+- Check that your account has editor access
+
+If you see an editor access message, ask an organization admin to [invite you as an editor](/docs/editor/how-to/invite-editors) or change your role to **Editor** or **Admin**. Viewer accounts can sign in to [EventCatalog Cloud](https://eventcatalog.cloud), but they cannot open a local editor session.
+
+## Preview is unavailable
+
+Preview links require a local EventCatalog development server.
+
+Start EventCatalog:
+
+```bash
+npm run dev
+```
+
+Then restart the editor. If your catalog runs on a different port, pass it with `--eventcatalog-port`.
+
+## Changes are not shown
+
+The Changes page uses Git. Check that:
+
+- Your catalog is inside a Git repository
+- Git is installed
+- The files have actually changed on disk
+
+You can also check from a terminal:
+
+```bash
+git status
+```
+
+## A save reports a conflict
+
+A conflict means the file changed on disk after the editor loaded it.
+
+Reload the resource, review the external change, and apply your edit again.
+
+## A visual field is missing
+
+The beta editor does not expose every possible EventCatalog field as a form yet.
+
+Use source mode to edit unsupported frontmatter or MDX directly.
+
+## Get help
+
+Join the [EventCatalog Discord](https://eventcatalog.dev/discord) or [open an issue in the editor repository](https://github.com/event-catalog/eventcatalog-editor-code/issues).

package/dist/eventcatalog.cjs

@@ -114,7 +114,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "3.39.5";
+var version = "3.40.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.config.d.cts

@@ -47,6 +47,47 @@ type PagesConfiguration = {
 type AuthConfig = {
     enabled: boolean;
 };
+type McpAuthConfig = {
+    /**
+     * Require OAuth Bearer tokens for the built-in MCP server.
+     * EventCatalog acts as the MCP protected resource server; the
+     * configured authorization server remains responsible for login,
+     * consent, token issuance, and client registration.
+     */
+    enabled?: boolean;
+    /**
+     * Absolute URL for the MCP resource. Defaults to the request origin
+     * plus `/docs/mcp`, but production deployments behind proxies should
+     * set this explicitly.
+     */
+    resource?: string;
+    /**
+     * Optional absolute URL for the OAuth Protected Resource Metadata
+     * document. Defaults to `/.well-known/oauth-protected-resource`.
+     */
+    protectedResourceMetadataUrl?: string;
+    /** Authorization server issuer/base URLs advertised to MCP clients. */
+    authorizationServers?: string[];
+    /** Expected token issuer (`iss`). */
+    issuer?: string;
+    /** Expected token audience (`aud`). Defaults to `resource`. */
+    audience?: string | string[];
+    /** Scopes required to call the MCP server. */
+    requiredScopes?: string[];
+    /** JWKS endpoint used to validate asymmetric JWT access tokens. */
+    jwksUri?: string;
+    /** Inline public key for asymmetric JWT validation. */
+    publicKey?: string;
+    /** Environment variable containing the public key. */
+    publicKeyEnvVar?: string;
+    /** Inline shared secret for symmetric JWT validation. Prefer `sharedSecretEnvVar`. */
+    sharedSecret?: string;
+    /** Environment variable containing the shared secret. */
+    sharedSecretEnvVar?: string;
+};
+type McpConfig = {
+    auth?: McpAuthConfig;
+};
 type GA4Config = {
     measurementId: string;
 };
@@ -90,6 +131,7 @@ interface Config {
      */
     theme?: CatalogTheme;
     auth?: AuthConfig;
+    mcp?: McpConfig;
     rss?: {
         enabled: boolean;
         limit: number;

package/dist/eventcatalog.config.d.ts

@@ -47,6 +47,47 @@ type PagesConfiguration = {
 type AuthConfig = {
     enabled: boolean;
 };
+type McpAuthConfig = {
+    /**
+     * Require OAuth Bearer tokens for the built-in MCP server.
+     * EventCatalog acts as the MCP protected resource server; the
+     * configured authorization server remains responsible for login,
+     * consent, token issuance, and client registration.
+     */
+    enabled?: boolean;
+    /**
+     * Absolute URL for the MCP resource. Defaults to the request origin
+     * plus `/docs/mcp`, but production deployments behind proxies should
+     * set this explicitly.
+     */
+    resource?: string;
+    /**
+     * Optional absolute URL for the OAuth Protected Resource Metadata
+     * document. Defaults to `/.well-known/oauth-protected-resource`.
+     */
+    protectedResourceMetadataUrl?: string;
+    /** Authorization server issuer/base URLs advertised to MCP clients. */
+    authorizationServers?: string[];
+    /** Expected token issuer (`iss`). */
+    issuer?: string;
+    /** Expected token audience (`aud`). Defaults to `resource`. */
+    audience?: string | string[];
+    /** Scopes required to call the MCP server. */
+    requiredScopes?: string[];
+    /** JWKS endpoint used to validate asymmetric JWT access tokens. */
+    jwksUri?: string;
+    /** Inline public key for asymmetric JWT validation. */
+    publicKey?: string;
+    /** Environment variable containing the public key. */
+    publicKeyEnvVar?: string;
+    /** Inline shared secret for symmetric JWT validation. Prefer `sharedSecretEnvVar`. */
+    sharedSecret?: string;
+    /** Environment variable containing the shared secret. */
+    sharedSecretEnvVar?: string;
+};
+type McpConfig = {
+    auth?: McpAuthConfig;
+};
 type GA4Config = {
     measurementId: string;
 };
@@ -90,6 +131,7 @@ interface Config {
      */
     theme?: CatalogTheme;
     auth?: AuthConfig;
+    mcp?: McpConfig;
     rss?: {
         enabled: boolean;
         limit: number;