@emkodev/emroute 1.0.3 → 1.6.0

package/server/esbuild-manifest.plugin.ts

@@ -0,0 +1,243 @@
+/**
+ * esbuild Virtual Manifest Plugin
+ *
+ * Intercepts `emroute:routes` and `emroute:widgets` import specifiers.
+ * Reads JSON manifests from the runtime and generates TypeScript modules
+ * with `moduleLoaders` (dynamic `import()` calls) in-memory — no .g.ts
+ * files on disk.
+ *
+ * This is the single source of truth: JSON manifest → esbuild bundle.
+ */
+
+import type { Runtime } from '../runtime/abstract.runtime.ts';
+import { ROUTES_MANIFEST_PATH, WIDGETS_MANIFEST_PATH } from '../runtime/abstract.runtime.ts';
+
+/** Escape a string for use inside a single-quoted JS/TS string literal. */
+function esc(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+interface ManifestPluginOptions {
+  runtime: Runtime;
+  /** HTML base path prefix for route patterns (e.g. '/html'). */
+  basePath?: string;
+  /**
+   * Directory prefix to strip from module paths so that import() calls
+   * are relative to the entry point (e.g. 'routes/' strips '/routes/').
+   */
+  stripPrefix?: string;
+  /** Absolute directory for resolving relative import() paths in generated code. */
+  resolveDir: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type EsbuildPlugin = any;
+
+export function createManifestPlugin(options: ManifestPluginOptions): EsbuildPlugin {
+  const { runtime, basePath = '', stripPrefix = '', resolveDir } = options;
+
+  const prefixPattern = (pattern: string): string =>
+    basePath ? (pattern === '/' ? basePath : basePath + pattern) : pattern;
+
+  const strip = (p: string): string =>
+    stripPrefix && p.startsWith(stripPrefix) ? p.slice(stripPrefix.length) : p;
+
+  return {
+    name: 'emroute-manifest',
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    setup(build: any) {
+      // ── Resolve virtual specifiers ──────────────────────────────────
+      build.onResolve(
+        { filter: /^emroute:/ },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (args: any) => ({ path: args.path, namespace: 'emroute' }),
+      );
+
+      // ── Load virtual modules ────────────────────────────────────────
+      build.onLoad(
+        { filter: /.*/, namespace: 'emroute' },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async (args: any) => {
+          if (args.path === 'emroute:routes') {
+            return { contents: await generateRoutesModule(), loader: 'ts' as const, resolveDir };
+          }
+          if (args.path === 'emroute:widgets') {
+            return { contents: await generateWidgetsModule(), loader: 'ts' as const, resolveDir };
+          }
+          return undefined;
+        },
+      );
+    },
+  };
+
+  // ── Routes module generator ───────────────────────────────────────
+
+  async function generateRoutesModule(): Promise<string> {
+    const response = await runtime.query(ROUTES_MANIFEST_PATH);
+    if (response.status === 404) {
+      return `export const routesManifest = { routes: [], errorBoundaries: [], statusPages: new Map(), moduleLoaders: {} };`;
+    }
+    const raw = await response.json();
+
+    // Routes array
+    const routesArray = (raw.routes ?? [])
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .map((r: any) => {
+        const filesStr = r.files
+          ? `\n    files: { ${
+            Object.entries(r.files)
+              .filter(([_, v]) => v)
+              .map(([k, v]) => `${k}: '${esc(strip(v as string))}'`)
+              .join(', ')
+          } },`
+          : '';
+
+        return `  {
+    pattern: '${esc(prefixPattern(r.pattern))}',
+    type: '${esc(r.type)}',
+    modulePath: '${esc(strip(r.modulePath))}',${filesStr}${
+          r.parent ? `\n    parent: '${esc(prefixPattern(r.parent))}',` : ''
+        }${r.statusCode ? `\n    statusCode: ${r.statusCode},` : ''}
+  }`;
+      })
+      .join(',\n');
+
+    // Error boundaries
+    const errorBoundariesArray = (raw.errorBoundaries ?? [])
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .map((e: any) => `  {
+    pattern: '${esc(prefixPattern(e.pattern))}',
+    modulePath: '${esc(strip(e.modulePath))}',
+  }`)
+      .join(',\n');
+
+    // Status pages
+    const statusPagesEntries = (raw.statusPages ?? [])
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .map(([status, route]: [number, any]) => {
+        const filesStr = route.files
+          ? `, files: { ${
+            Object.entries(route.files)
+              .map(([k, v]) => `${k}: '${esc(strip(v as string))}'`)
+              .join(', ')
+          } }`
+          : '';
+        return `  [${status}, { pattern: '${esc(prefixPattern(route.pattern))}', type: '${
+          esc(route.type)
+        }', modulePath: '${
+          esc(strip(route.modulePath))
+        }', statusCode: ${status}${filesStr} }]`;
+      })
+      .join(',\n');
+
+    // Error handler
+    const errorHandlerCode = raw.errorHandler
+      ? `{
+  pattern: '${esc(prefixPattern(raw.errorHandler.pattern))}',
+  type: '${esc(raw.errorHandler.type)}',
+  modulePath: '${esc(strip(raw.errorHandler.modulePath))}',
+}`
+      : 'undefined';
+
+    // Module loaders — collect all .ts module paths
+    const tsModulePaths = new Set<string>();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    for (const route of (raw.routes ?? []) as any[]) {
+      if (route.files?.ts) tsModulePaths.add(route.files.ts);
+      if (route.modulePath.endsWith('.ts')) tsModulePaths.add(route.modulePath);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    for (const boundary of (raw.errorBoundaries ?? []) as any[]) {
+      tsModulePaths.add(boundary.modulePath);
+    }
+    if (raw.errorHandler) {
+      tsModulePaths.add(raw.errorHandler.modulePath);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    for (const [_, statusRoute] of (raw.statusPages ?? []) as [number, any][]) {
+      if (statusRoute.modulePath.endsWith('.ts')) {
+        tsModulePaths.add(statusRoute.modulePath);
+      }
+    }
+
+    const moduleLoadersCode = [...tsModulePaths]
+      .map((p) => {
+        const key = strip(p);
+        const rel = key.replace(/^\.?\//, '');
+        return `    '${esc(key)}': () => import('./${esc(rel)}'),`;
+      })
+      .join('\n');
+
+    return `import type { RoutesManifest } from '@emkodev/emroute';
+
+export const routesManifest: RoutesManifest = {
+  routes: [
+${routesArray}
+  ],
+
+  errorBoundaries: [
+${errorBoundariesArray}
+  ],
+
+  statusPages: new Map([
+${statusPagesEntries}
+  ]),
+
+  errorHandler: ${errorHandlerCode},
+
+  moduleLoaders: {
+${moduleLoadersCode}
+  },
+};
+`;
+  }
+
+  // ── Widgets module generator ──────────────────────────────────────
+
+  async function generateWidgetsModule(): Promise<string> {
+    const response = await runtime.query(WIDGETS_MANIFEST_PATH);
+    if (response.status === 404) {
+      return `export const widgetsManifest = { widgets: [], moduleLoaders: {} };`;
+    }
+    const entries = await response.json();
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const widgetEntries = (entries as any[]).map((e) => {
+      const filesStr = e.files
+        ? `\n      files: { ${
+          Object.entries(e.files)
+            .filter(([_, v]) => v)
+            .map(([k, v]) => `${k}: '${esc(strip(v as string))}'`)
+            .join(', ')
+        } },`
+        : '';
+
+      return `    {
+      name: '${esc(e.name)}',
+      modulePath: '${esc(strip(e.modulePath))}',
+      tagName: '${esc(e.tagName)}',${filesStr}
+    }`;
+    }).join(',\n');
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const loaderEntries = (entries as any[]).map((e) => {
+      const key = strip(e.modulePath);
+      const rel = key.replace(/^\.?\//, '');
+      return `    '${esc(key)}': () => import('./${esc(rel)}'),`;
+    }).join('\n');
+
+    return `import type { WidgetsManifest } from '@emkodev/emroute';
+
+export const widgetsManifest: WidgetsManifest = {
+  widgets: [
+${widgetEntries}
+  ],
+
+  moduleLoaders: {
+${loaderEntries}
+  },
+};
+`;
+  }
+}

package/server/scanner.util.ts

@@ -0,0 +1,243 @@
+/**
+ * Standalone Scanning Utilities
+ *
+ * Runtime-agnostic route and widget scanning. Works with any Runtime
+ * that implements query() — used by tests with mock runtimes and by
+ * the CLI generate command.
+ *
+ * Note: BunFsRuntime has these as instance methods with lazy caching.
+ * These standalone functions are the same logic without caching.
+ */
+
+import type { Runtime } from '../runtime/abstract.runtime.ts';
+import {
+  filePathToPattern,
+  getPageFileType,
+  getRouteType,
+  sortRoutesBySpecificity,
+} from '../src/route/route.matcher.ts';
+import type {
+  ErrorBoundary,
+  RouteConfig,
+  RouteFiles,
+  RoutesManifest,
+} from '../src/type/route.type.ts';
+import type { WidgetManifestEntry } from '../src/type/widget.type.ts';
+
+export interface GeneratorResult extends RoutesManifest {
+  warnings: string[];
+}
+
+/** Walk directory recursively and collect files via Runtime. */
+async function* walkDirectory(runtime: Runtime, dir: string): AsyncGenerator<string> {
+  const trailingDir = dir.endsWith('/') ? dir : dir + '/';
+  const response = await runtime.query(trailingDir);
+  const entries: string[] = await response.json();
+
+  for (const entry of entries) {
+    const path = `${trailingDir}${entry}`;
+    if (entry.endsWith('/')) {
+      yield* walkDirectory(runtime, path);
+    } else {
+      yield path;
+    }
+  }
+}
+
+/** Generate routes manifest by scanning a directory via Runtime. */
+export async function generateRoutesManifest(
+  routesDir: string,
+  runtime: Runtime,
+): Promise<GeneratorResult> {
+  const pageFiles: Array<{
+    path: string;
+    pattern: string;
+    fileType: 'ts' | 'html' | 'md' | 'css';
+  }> = [];
+  const redirects: RouteConfig[] = [];
+  const errorBoundaries: ErrorBoundary[] = [];
+  const statusPages = new Map<number, RouteConfig>();
+  let errorHandler: RouteConfig | undefined;
+
+  const allFiles: string[] = [];
+  for await (const file of walkDirectory(runtime, routesDir)) {
+    allFiles.push(file);
+  }
+
+  for (const filePath of allFiles) {
+    const relativePath = filePath.replace(`${routesDir}/`, '');
+    const filename = relativePath.split('/').pop() ?? '';
+
+    if (filename === 'index.error.ts' && relativePath === 'index.error.ts') {
+      errorHandler = {
+        pattern: '/',
+        type: 'error',
+        modulePath: filePath,
+      };
+      continue;
+    }
+
+    const cssFileType = getPageFileType(filename);
+    if (cssFileType === 'css') {
+      const pattern = filePathToPattern(relativePath);
+      pageFiles.push({ path: filePath, pattern, fileType: 'css' });
+      continue;
+    }
+
+    const routeType = getRouteType(filename);
+    if (!routeType) continue;
+
+    const statusMatch = filename.match(/^(\d{3})\.page\.(ts|html|md)$/);
+    if (statusMatch) {
+      const statusCode = parseInt(statusMatch[1], 10);
+      const fileType = getPageFileType(filename);
+      if (fileType) {
+        const existing = statusPages.get(statusCode);
+        if (existing) {
+          existing.files ??= {};
+          existing.files[fileType] = filePath;
+          existing.modulePath = existing.files.ts ?? existing.files.html ?? existing.files.md ?? '';
+        } else {
+          const files: RouteFiles = { [fileType]: filePath };
+          statusPages.set(statusCode, {
+            pattern: `/${statusCode}`,
+            type: 'page',
+            modulePath: filePath,
+            statusCode,
+            files,
+          });
+        }
+      }
+      continue;
+    }
+
+    const pattern = filePathToPattern(relativePath);
+
+    if (routeType === 'error') {
+      const boundaryPattern = pattern.replace(/\/[^/]+$/, '') || '/';
+      errorBoundaries.push({ pattern: boundaryPattern, modulePath: filePath });
+      continue;
+    }
+
+    if (routeType === 'redirect') {
+      redirects.push({ pattern, type: 'redirect', modulePath: filePath });
+      continue;
+    }
+
+    const fileType = getPageFileType(filename);
+    if (fileType) {
+      pageFiles.push({ path: filePath, pattern, fileType });
+    }
+  }
+
+  // Group files by pattern
+  const groups = new Map<string, { pattern: string; files: RouteFiles; parent?: string }>();
+  for (const { path, pattern, fileType } of pageFiles) {
+    let group = groups.get(pattern);
+    if (!group) {
+      group = { pattern, files: {} };
+      const segments = pattern.split('/').filter(Boolean);
+      if (segments.length > 1) {
+        group.parent = '/' + segments.slice(0, -1).join('/');
+      }
+      groups.set(pattern, group);
+    }
+    const existing = group.files[fileType];
+    if (existing?.includes('/index.page.') && !path.includes('/index.page.')) {
+      continue;
+    }
+    group.files[fileType] = path;
+  }
+
+  // Detect collisions
+  const warnings: string[] = [];
+  for (const [pattern, group] of groups) {
+    const filePaths = Object.values(group.files).filter(Boolean);
+    const hasIndex = filePaths.some((p) => p?.includes('/index.page.'));
+    const hasFlat = filePaths.some((p) => p && !p.includes('/index.page.'));
+    if (hasIndex && hasFlat) {
+      warnings.push(
+        `Warning: Mixed file structure for ${pattern}:\n` +
+          filePaths.map((p) => `     ${p}`).join('\n') +
+          `\n     Both folder/index and flat files detected`,
+      );
+    }
+  }
+
+  // Convert groups to RouteConfig array
+  const routes: RouteConfig[] = [];
+  for (const [_, group] of groups) {
+    const modulePath = group.files.ts ?? group.files.html ?? group.files.md ?? '';
+    if (!modulePath) continue;
+    const route: RouteConfig = {
+      pattern: group.pattern,
+      type: 'page',
+      modulePath,
+      files: group.files,
+    };
+    if (group.parent) route.parent = group.parent;
+    routes.push(route);
+  }
+
+  routes.push(...redirects);
+  const sortedRoutes = sortRoutesBySpecificity(routes);
+
+  return {
+    routes: sortedRoutes,
+    errorBoundaries,
+    statusPages,
+    errorHandler,
+    warnings,
+  };
+}
+
+/**
+ * Discover widget modules and companion files by scanning a directory.
+ */
+export async function discoverWidgets(
+  widgetsDir: string,
+  runtime: Runtime,
+  pathPrefix?: string,
+): Promise<WidgetManifestEntry[]> {
+  const COMPANION_EXTENSIONS = ['html', 'md', 'css'] as const;
+  const WIDGET_FILE_SUFFIX = '.widget.ts';
+  const entries: WidgetManifestEntry[] = [];
+
+  const trailingDir = widgetsDir.endsWith('/') ? widgetsDir : widgetsDir + '/';
+  const response = await runtime.query(trailingDir);
+  const listing: string[] = await response.json();
+
+  for (const item of listing) {
+    if (!item.endsWith('/')) continue;
+
+    const name = item.slice(0, -1);
+    const moduleFile = `${name}${WIDGET_FILE_SUFFIX}`;
+    const modulePath = `${trailingDir}${name}/${moduleFile}`;
+
+    if ((await runtime.query(modulePath)).status === 404) continue;
+
+    const prefix = pathPrefix ? `${pathPrefix}/` : '';
+    const entry: WidgetManifestEntry = {
+      name,
+      modulePath: `${prefix}${name}/${moduleFile}`,
+      tagName: `widget-${name}`,
+    };
+
+    const files: { html?: string; md?: string; css?: string } = {};
+    let hasFiles = false;
+    for (const ext of COMPANION_EXTENSIONS) {
+      const companionFile = `${name}.widget.${ext}`;
+      const companionPath = `${trailingDir}${name}/${companionFile}`;
+      if ((await runtime.query(companionPath)).status !== 404) {
+        files[ext] = `${prefix}${name}/${companionFile}`;
+        hasFiles = true;
+      }
+    }
+
+    if (hasFiles) entry.files = files;
+    entries.push(entry);
+  }
+
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  return entries;
+}

package/server/server-api.type.ts

@@ -0,0 +1,90 @@
+/**
+ * Server API Types
+ *
+ * Interfaces for the emroute server.
+ * Consumers use `createEmrouteServer()` to get a server that handles
+ * SSR rendering, static file serving, and route matching.
+ */
+
+import type { RoutesManifest } from '../src/type/route.type.ts';
+import type { MarkdownRenderer } from '../src/type/markdown.type.ts';
+import type { SpaMode, WidgetManifestEntry } from '../src/type/widget.type.ts';
+import type { ContextProvider } from '../src/component/abstract.component.ts';
+import type { BasePath } from '../src/route/route.core.ts';
+import type { WidgetRegistry } from '../src/widget/widget.registry.ts';
+import type { SsrHtmlRouter } from '../src/renderer/ssr/html.renderer.ts';
+import type { SsrMdRouter } from '../src/renderer/ssr/md.renderer.ts';
+
+// ── SSR Render Result ──────────────────────────────────────────────────
+
+/** Result of rendering a URL through an SSR renderer. */
+export interface SsrRenderResult {
+  /** Rendered content (HTML or Markdown) */
+  content: string;
+  /** HTTP status code */
+  status: number;
+  /** Page title (from the leaf route's getTitle) */
+  title?: string;
+  /** Redirect target URL (for 301/302 responses) */
+  redirect?: string;
+}
+
+// ── Server ─────────────────────────────────────────────────────────────
+
+/**
+ * Config for `createEmrouteServer()`.
+ *
+ * The server reads manifests from the Runtime and handles SSR rendering,
+ * static file serving, and route matching.
+ */
+export interface EmrouteServerConfig {
+  /** Pre-built manifest (alternative to reading from runtime) */
+  routesManifest?: RoutesManifest;
+
+  /** Pre-built widget registry (alternative to reading from runtime) */
+  widgets?: WidgetRegistry;
+
+  /** SPA mode — controls which routers are constructed and what gets served */
+  spa?: SpaMode;
+
+  /** Base paths for SSR endpoints (default: { html: '/html', md: '/md' }) */
+  basePath?: BasePath;
+
+  /** Page title (fallback when no route provides one) */
+  title?: string;
+
+  /** Markdown renderer for server-side <mark-down> expansion */
+  markdownRenderer?: MarkdownRenderer;
+
+  /** Enrich every ComponentContext with app-level services. */
+  extendContext?: ContextProvider;
+}
+
+/**
+ * An emroute server instance.
+ *
+ * Handles SSR rendering, static file serving, and route matching.
+ * Use `handleRequest(req)` to compose with your own request handling.
+ */
+export interface EmrouteServer {
+  /**
+   * Handle an HTTP request for SSR routes and bare paths.
+   * Returns `null` for unmatched file requests — consumer handles 404.
+   */
+  handleRequest(req: Request): Promise<Response | null>;
+
+  /** The SSR HTML router (null in 'only' mode — no server rendering). */
+  readonly htmlRouter: SsrHtmlRouter | null;
+
+  /** The SSR Markdown router (null in 'only' mode). */
+  readonly mdRouter: SsrMdRouter | null;
+
+  /** The resolved routes manifest. */
+  readonly manifest: RoutesManifest;
+
+  /** Discovered widget entries. */
+  readonly widgetEntries: WidgetManifestEntry[];
+
+  /** The resolved HTML shell. */
+  readonly shell: string;
+}