@eventcatalog/core 4.11.2 → 4.12.0-beta.1

package/eventcatalog/astro.config.mjs

@@ -3,7 +3,6 @@ import { unified } from '@astrojs/markdown-remark';
 import tailwindcss from '@tailwindcss/vite';
 import mdx from '@astrojs/mdx';
 import react from '@astrojs/react';
-import { searchForWorkspaceRoot } from 'vite';
 import { mermaid } from './src/remark-plugins/mermaid';
 import { plantuml } from './src/remark-plugins/plantuml';
 import { join } from 'node:path';
@@ -22,24 +21,36 @@ import { linkValidation } from './src/plugins/link-validation';
 
 import rehypeExpressiveCode from 'rehype-expressive-code';
 
-/** @type {import('bin/eventcatalog.config').Config} */
-import config from './eventcatalog.config';
 import expressiveCode from 'astro-expressive-code';
 // Expressive Code options (including the non-serializable `themeCssSelector`
-// function) live in ec.config.mjs. The `expressiveCode()` integration loads that
-// file automatically; the rehype plugin used by mdx() below needs it passed
-// explicitly, so we import it here to keep a single source of truth.
+// function) live in the package's ec.config.mjs. Both the integration's
+// preprocessors and the rehype plugin below load those same package defaults.
 import expressiveCodeConfig from './ec.config.mjs';
 import ecstudioWatcher from './integrations/ecstudio-watcher.mjs';
 import eventCatalogIntegration from './src/enterprise/integrations/eventcatalog-features.ts';
+import eventCatalogRuntime, { getDevServerFileSystem, packageDirectory } from './integrations/eventcatalog-runtime.mjs';
+import config from './src/utils/eventcatalog-config/source.ts';
+import preprocessExpressiveCodeConfig from './integrations/expressive-code-config.mjs';
+import catalogAssets from './integrations/catalog-assets.mjs';
+import runtimeDependencies from './integrations/runtime-dependencies.mjs';
+import { getRuntimePaths } from './integrations/runtime-paths.mjs';
 
 const projectDirectory = process.env.PROJECT_DIR || process.cwd();
+const { runtimeDirectory } = getRuntimePaths(projectDirectory, process.env.CATALOG_DIR);
 const base = config.base || '/';
 const host = config.host || false;
 const compress = config.compress ?? false;
 const isDevMode = process.env.EVENTCATALOG_DEV_MODE === 'true';
 const effectiveOutput = isDevMode ? 'server' : config.output || 'static';
 const searchType = config.search?.type || 'resource';
+const bundledRuntimeDependencies = [
+  '@xyflow/react',
+  '@eventcatalog/core',
+  '@astrojs/react',
+  '@astrojs/node',
+  '@astrojs/internal-helpers',
+];
+const externalRuntimeDependencies = ['astro/assets/services/sharp'];
 
 const markdownRemarkPlugins = [remarkDirective, remarkDirectives, remarkComment, mermaid, plantuml];
 const mdxRemarkPlugins = [...markdownRemarkPlugins, remarkResourceRef, remarkCodeGroup];
@@ -62,6 +73,9 @@ const mdxRehypePlugins = [
 
 // https://astro.build/config
 export default defineConfig({
+  root: projectDirectory,
+  srcDir: runtimeDirectory,
+  publicDir: join(projectDirectory, 'public'),
   base,
   server: {
     port: config.port || 3000,
@@ -105,9 +119,14 @@ export default defineConfig({
     entrypoint: new URL('./src/plugins/quiet-empty-collections-logger.mjs', import.meta.url),
   },
   integrations: [
+    eventCatalogRuntime({ projectDirectory, runtimeDirectory }),
     react(),
-    // Options are loaded automatically from ec.config.mjs.
-    expressiveCode(),
+    expressiveCode({
+      customConfigPreprocessors: {
+        preprocessAstroIntegrationConfig: preprocessExpressiveCodeConfig,
+        preprocessComponentConfig: `export { default } from ${JSON.stringify(join(packageDirectory, 'integrations/expressive-code-config.mjs'))};`,
+      },
+    }),
     mdx({
       // https://docs.astro.build/en/guides/integrations-guide/mdx/#optimize
       optimize: config.mdxOptimize || false,
@@ -116,13 +135,31 @@ export default defineConfig({
         rehypePlugins: mdxRehypePlugins,
       }),
     }),
+    catalogAssets({ projectDirectory, generatedDirectory: join(runtimeDirectory, 'public') }),
     effectiveOutput !== 'server' && compress && (await loadAstroCompressIntegration(projectDirectory)),
     ecstudioWatcher(),
     eventCatalogIntegration(),
     linkValidation(config.linkValidation),
   ].filter(Boolean),
   vite: {
+    // Resolve Core's private dependencies from the installed package (including
+    // strict pnpm layouts), while Astro owns the user's project and content.
+    root: packageDirectory,
+    // User components must share the renderer's React, even if the catalog has
+    // installed its own version. Preserve the former copied-component contract.
+    resolve: { dedupe: ['react', 'react-dom'] },
+    envDir: projectDirectory,
+    cacheDir: join(runtimeDirectory, 'vite'),
+    environments: {
+      prerender: {
+        resolve: {
+          noExternal: bundledRuntimeDependencies,
+          external: externalRuntimeDependencies,
+        },
+      },
+    },
     plugins: [
+      runtimeDependencies(),
       tailwindcss(),
       ...(await eventCatalogLikeC4(projectDirectory)),
       ...(config.trailingSlash === true ? [astroTrailingSlashEndpointFix()] : []),
@@ -139,34 +176,23 @@ export default defineConfig({
       __EC_SEARCH_TYPE__: JSON.stringify(searchType),
     },
     server: {
-      fs: {
-        allow: ['..', './node_modules/@fontsource', projectDirectory, searchForWorkspaceRoot(process.cwd())],
-      },
-      // Prevent stale FSEvents from triggering a config-dependency restart on first run.
-      // During startup, catalogToAstro copies eventcatalog.config.js into .eventcatalog-core
-      // shortly before Astro/Vite begins watching. On macOS, FSEvents can deliver buffered
-      // notifications for those recent writes, causing Vite to restart mid-dep-scan.
-      // awaitWriteFinish makes chokidar verify the file is stable before emitting events,
-      // filtering out those stale notifications.
-      watch: {
-        awaitWriteFinish: {
-          stabilityThreshold: 100,
-          pollInterval: 50,
-        },
-      },
+      fs: getDevServerFileSystem({ projectDirectory }),
       ...(config.server?.allowedHosts ? { allowedHosts: config.server?.allowedHosts } : {}),
       // Pre-transform critical modules during startup so they're ready when
       // the first page request arrives. Without this, Vite transforms each
       // module on-demand during the first request, adding seconds to TTFB.
       warmup: {
         ssrFiles: [
-          './src/pages/index.astro',
-          './src/pages/_index.astro',
-          './src/layouts/VerticalSideBarLayout.astro',
-          './src/components/Header.astro',
-          './src/components/SideNav/SideNav.astro',
+          join(packageDirectory, 'src/pages/index.astro'),
+          join(packageDirectory, 'src/pages/_index.astro'),
+          join(packageDirectory, 'src/layouts/VerticalSideBarLayout.astro'),
+          join(packageDirectory, 'src/components/Header.astro'),
+          join(packageDirectory, 'src/components/SideNav/SideNav.astro'),
+        ],
+        clientFiles: [
+          join(packageDirectory, 'src/components/SideNav/NestedSideBar/index.tsx'),
+          join(packageDirectory, 'src/components/Search/SearchModal.tsx'),
         ],
-        clientFiles: ['./src/components/SideNav/NestedSideBar/index.tsx', './src/components/Search/SearchModal.tsx'],
       },
     },
     worker: {
@@ -178,8 +204,8 @@ export default defineConfig({
       },
     },
     ssr: {
-      noExternal: ['@xyflow/react'],
-      external: ['eventcatalog.auth.js', 'eventcatalog.chat.js'],
+      noExternal: bundledRuntimeDependencies,
+      external: ['eventcatalog.auth.js', 'eventcatalog.chat.js', ...externalRuntimeDependencies],
     },
     optimizeDeps: {
       exclude: [],

package/eventcatalog/integrations/catalog-assets.mjs

@@ -0,0 +1,204 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const defaultCoreDirectory = fileURLToPath(new URL('../', import.meta.url));
+// This is the legacy public-asset URL contract, not the content collection list.
+// entities, containers, data-products, teams and users were never mirrored here.
+// Adding them would publish new files/URLs and needs a separate compatibility
+// review; do not substitute the full content-collection registry.
+const collectionDirectories = new Set([
+  'agents',
+  'events',
+  'commands',
+  'services',
+  'domains',
+  'flows',
+  'pages',
+  'changelogs',
+  'queries',
+  'channels',
+  'ubiquitousLanguages',
+  'dependencies',
+]);
+const sourceExtensions = /\.(?:md|mdx|astro|[cm]?js|[cm]?ts|jsx|tsx|c4|likec4)$/i;
+const contentTypes = {
+  '.json': 'application/json',
+  '.yaml': 'application/yaml',
+  '.yml': 'application/yaml',
+  '.xml': 'application/xml',
+  '.xsl': 'application/xml',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.css': 'text/css',
+  '.js': 'text/javascript',
+  '.mjs': 'text/javascript',
+  '.html': 'text/html',
+  '.txt': 'text/plain',
+  '.csv': 'text/csv',
+  '.pdf': 'application/pdf',
+  '.wasm': 'application/wasm',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+function listFiles(directory, excludedDirectories = new Set()) {
+  if (!fs.existsSync(directory)) return [];
+  const files = [];
+  const visit = (current, segments = []) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name.startsWith('.')) continue;
+      const relative = [...segments, entry.name];
+      if (entry.isDirectory() && !excludedDirectories.has(entry.name)) visit(path.join(current, entry.name), relative);
+      // Never follow symlinks out of the selected source directories.
+      if (entry.isFile()) files.push(relative.join('/'));
+    }
+  };
+  visit(directory);
+  return files;
+}
+
+// Keep the existing generated URL convention: nested resources are rooted at
+// their nearest collection directory (domains/.../events/Foo -> events/Foo).
+export function getResourceAssetPath(relativePath) {
+  const parts = relativePath.split(/[\\/]/);
+  if (!collectionDirectories.has(parts[0]) || parts.some((part) => part.startsWith('.'))) return;
+  if (sourceExtensions.test(relativePath) || ['package.json', 'Dockerfile'].includes(parts.at(-1))) return;
+  if (parts[0] === 'pages') return `/generated/${parts.join('/')}`;
+  let collectionIndex = 0;
+  for (let index = 1; index < parts.length - 1; index++) {
+    if (collectionDirectories.has(parts[index])) collectionIndex = index;
+  }
+  return `/generated/${parts.slice(collectionIndex).join('/')}`;
+}
+
+export function createAssetManifest({ projectDirectory, coreDirectory = defaultCoreDirectory, generatedDirectory }) {
+  const assets = new Map();
+  const publicDirectory = path.join(coreDirectory, 'public');
+  for (const file of listFiles(publicDirectory, new Set(['generated', 'pagefind']))) {
+    assets.set(`/${file}`, path.join(publicDirectory, file));
+  }
+  for (const collection of collectionDirectories) {
+    const directory = path.join(projectDirectory, collection);
+    for (const file of listFiles(directory, new Set(['node_modules', 'dist']))) {
+      const resourcePath = `${collection}/${file}`;
+      const url = getResourceAssetPath(resourcePath);
+      if (url) assets.set(url, path.join(projectDirectory, resourcePath));
+    }
+  }
+  if (generatedDirectory) {
+    for (const file of listFiles(generatedDirectory)) assets.set(`/${file}`, path.join(generatedDirectory, file));
+  }
+  return assets;
+}
+
+function decodeAssetUrl(requestUrl, base) {
+  let pathname;
+  try {
+    pathname = decodeURIComponent((requestUrl || '').split('?')[0]);
+  } catch {
+    return;
+  }
+  if (pathname.includes('\\') || pathname.includes('\0') || pathname.split('/').some((part) => part === '..' || part === '.'))
+    return;
+  const prefix = `/${base.split('/').filter(Boolean).join('/')}`;
+  if (prefix !== '/') {
+    if (!pathname.startsWith(`${prefix}/`)) return;
+    pathname = pathname.slice(prefix.length);
+  }
+  return pathname;
+}
+
+export function createAssetMiddleware({ getAssets, projectDirectory, base = '/' }) {
+  return (request, response, next) => {
+    if (request.method !== 'GET' && request.method !== 'HEAD') return next();
+    // Astro strips the configured base before integration middleware runs.
+    // Connect preserves the incoming URL so matching also works under /docs/.
+    const pathname = decodeAssetUrl(request.originalUrl || request.url, base);
+    if (!pathname) return next();
+    // Astro owns the user's public directory, including deliberate overrides.
+    const publicFile = path.join(projectDirectory, 'public', pathname.slice(1));
+    if (fs.existsSync(publicFile) && fs.statSync(publicFile).isFile()) return next();
+    const file = getAssets().get(pathname);
+    if (!file) return next();
+    let stats;
+    try {
+      stats = fs.statSync(file);
+      if (!stats.isFile()) return next();
+    } catch (error) {
+      if (error.code === 'ENOENT') return next();
+      return next(error);
+    }
+    response.statusCode = 200;
+    response.setHeader('Content-Type', contentTypes[path.extname(file).toLowerCase()] || 'application/octet-stream');
+    response.setHeader('Content-Length', stats.size);
+    response.setHeader('Cache-Control', 'no-cache');
+    if (request.method === 'HEAD') return response.end();
+    const stream = fs.createReadStream(file);
+    stream.on('error', (error) => response.destroy(error));
+    stream.pipe(response);
+  };
+}
+
+export function emitCatalogAssets(assets, outputDirectory, projectDirectory) {
+  for (const [url, source] of assets) {
+    const relative = url.slice(1);
+    if (fs.existsSync(path.join(projectDirectory, 'public', relative))) continue;
+    const target = path.join(outputDirectory, relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(source, target);
+  }
+}
+
+export default function catalogAssets(options) {
+  let base = '/';
+  return {
+    name: 'eventcatalog:assets',
+    hooks: {
+      'astro:config:done': ({ config }) => {
+        base = config.base;
+      },
+      'astro:server:setup': ({ server }) => {
+        let assets = createAssetManifest(options);
+        let dirty = false;
+        const roots = [...collectionDirectories].map((collection) => path.join(options.projectDirectory, collection));
+        if (options.generatedDirectory) roots.push(options.generatedDirectory);
+        server.watcher.add(roots);
+        const refresh = (file) => {
+          if (!roots.some((root) => file === root || file.startsWith(`${root}${path.sep}`))) return;
+          dirty = true;
+        };
+        server.watcher.on('add', refresh);
+        server.watcher.on('unlink', refresh);
+        server.watcher.on('unlinkDir', refresh);
+        server.httpServer?.once('close', () => {
+          server.watcher.off('add', refresh);
+          server.watcher.off('unlink', refresh);
+          server.watcher.off('unlinkDir', refresh);
+        });
+        server.middlewares.use(
+          createAssetMiddleware({
+            getAssets: () => {
+              if (dirty) {
+                assets = createAssetManifest(options);
+                dirty = false;
+              }
+              return assets;
+            },
+            projectDirectory: options.projectDirectory,
+            base,
+          })
+        );
+      },
+      'astro:build:done': ({ dir }) => {
+        emitCatalogAssets(createAssetManifest(options), fileURLToPath(dir), options.projectDirectory);
+      },
+    },
+  };
+}

package/eventcatalog/integrations/config-loader.mjs

@@ -0,0 +1,85 @@
+import { readFile, rm, copyFile, mkdtemp, symlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { tmpdir } from 'node:os';
+
+export async function cleanup(projectDirectory) {
+  const filePath = path.join(projectDirectory, 'eventcatalog.config.mjs');
+  if (existsSync(filePath)) {
+    await rm(filePath);
+  }
+}
+
+const findNodeModulesDirectory = (directory) => {
+  let currentDirectory = directory;
+
+  while (true) {
+    const nodeModulesDirectory = path.join(currentDirectory, 'node_modules');
+
+    if (existsSync(nodeModulesDirectory)) {
+      return nodeModulesDirectory;
+    }
+
+    const parentDirectory = path.dirname(currentDirectory);
+
+    if (parentDirectory === currentDirectory) {
+      return undefined;
+    }
+
+    currentDirectory = parentDirectory;
+  }
+};
+
+const linkNodeModulesIntoTempDirectory = async ({ projectDirectory, tempDir }) => {
+  const nodeModulesDirectory = findNodeModulesDirectory(projectDirectory);
+
+  if (!nodeModulesDirectory) {
+    return;
+  }
+
+  await symlink(nodeModulesDirectory, path.join(tempDir, 'node_modules'), 'dir');
+};
+
+const createTemporaryConfigDirectory = async (projectDirectory) => {
+  const nodeModulesDirectory = findNodeModulesDirectory(projectDirectory);
+
+  if (nodeModulesDirectory) {
+    return mkdtemp(path.join(nodeModulesDirectory, '.eventcatalog-config-'));
+  }
+
+  const tempDir = await mkdtemp(path.join(tmpdir(), 'eventcatalog-config-'));
+  await linkNodeModulesIntoTempDirectory({ projectDirectory, tempDir });
+  return tempDir;
+};
+
+export const getEventCatalogConfigFile = async (projectDirectory) => {
+  let tempDir;
+
+  try {
+    let configFilePath = path.join(projectDirectory, 'eventcatalog.config.js');
+
+    const filePath = path.join(projectDirectory, 'package.json');
+    const packageJson = JSON.parse(await readFile(filePath, 'utf-8'));
+
+    if (packageJson?.type !== 'module') {
+      // Importing CommonJS config via ESM import requires an .mjs file.
+      // Keep this temp copy outside the project directory so Astro/Vite
+      // file watchers do not trigger a dev-server restart during startup.
+      tempDir = await createTemporaryConfigDirectory(projectDirectory);
+      configFilePath = path.join(tempDir, 'eventcatalog.config.mjs');
+      await copyFile(path.join(projectDirectory, 'eventcatalog.config.js'), configFilePath);
+    }
+
+    const configFileURL = `${pathToFileURL(configFilePath).href}?t=${Date.now()}`;
+    const config = await import(/* @vite-ignore */ configFileURL);
+
+    return config.default;
+  } finally {
+    await cleanup(projectDirectory);
+
+    if (tempDir) {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  }
+};

package/eventcatalog/integrations/ecstudio-watcher.mjs

@@ -8,19 +8,21 @@ export default function ecstudioWatcher() {
           return;
         }
 
-        // Get the project root directory - server.config.root is already a string path
-        const rootDir = server.config.root;
-        const isEcstudioFile = (path) => path.endsWith('.ecstudio') && !path.includes('public/generated') && !path.includes('public\\generated');
-        
+        // Vite resolves dependencies from Core's package, while designs belong
+        // to the user's catalog and must be watched at their original paths.
+        const rootDir = process.env.PROJECT_DIR || process.cwd();
+        const isEcstudioFile = (path) =>
+          path.endsWith('.ecstudio') && !path.includes('public/generated') && !path.includes('public\\generated');
+
         // Set up chokidar to watch for new .ecstudio files
         server.watcher
           .on('add', async (path) => {
             if (isEcstudioFile(path)) {
               console.log(`New .ecstudio file detected: ${path}`);
-              
+
               // Add the new file to the watcher and refresh content
               server.watcher.add(path);
-              
+
               if (refreshContent) {
                 try {
                   await refreshContent();
@@ -34,7 +36,7 @@ export default function ecstudioWatcher() {
           .on('unlink', async (path) => {
             if (isEcstudioFile(path)) {
               console.log(`Removed .ecstudio file: ${path}`);
-              
+
               if (refreshContent) {
                 try {
                   await refreshContent();
@@ -54,9 +56,9 @@ export default function ecstudioWatcher() {
 
         // Also add the root directory to watch for new files
         server.watcher.add(rootDir);
-        
+
         // console.log('Set up dynamic .ecstudio file watcher with content refresh');
       },
     },
   };
-}
+}