@jxsuite/compiler 0.35.0 → 1.0.0

package/src/site/site-build.ts

@@ -23,13 +23,16 @@ import { basename, dirname, join, resolve } from "node:path";
 import { isMappedArray, isRef } from "@jxsuite/schema/guards";
 import { loadProjectConfig } from "./site-loader.ts";
 import { discoverPages, expandDynamicRoutes, readPageDocument } from "./pages-discovery.ts";
-import { buildProjectFormatRegistry } from "./format-host.ts";
-import type { FormatRegistry } from "@jxsuite/schema/format-registry";
+import { buildProjectExtensionRegistry } from "./format-host.ts";
+import { loadProjectSections } from "./project-sections.ts";
+import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registry";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import { resolveLayout } from "./layout-resolver.ts";
 import { mergeHead, renderHead } from "./head-merger.ts";
 import { injectContext } from "./context-injection.ts";
 import { compile, compileServer, compileSiteServer } from "../compiler.ts";
 import { compileElement } from "../targets/compile-element.ts";
+import type { SiteConnectorSpec, SiteMountSpec } from "../targets/compile-server.ts";
 import {
   DEFAULT_LIT_HTML_SRC,
   DEFAULT_REACTIVITY_SRC,
@@ -45,7 +48,6 @@ import {
   resolveRefValue,
   resolveStaticValue,
 } from "../shared.ts";
-import { loadContentConfig, loadContentTypes, resolveContentTypeRefs } from "./content-loader.ts";
 import { resolvePrototypes } from "./prototype-resolver.ts";
 import { transformImageNodes } from "./image-transform.ts";
 import { getImageCacheDir, loadCache, saveCache } from "./image-cache.ts";
@@ -62,7 +64,6 @@ import type {
   JxStyle,
   ProjectConfig,
 } from "@jxsuite/schema/types";
-import type { ContentLoaderEntry } from "@jxsuite/parser/types";
 import type { SiteRoute } from "../types.ts";
 import type { CacheManifest } from "./image-cache.js";
 
@@ -90,13 +91,24 @@ export async function buildSite(
   log("Loading project.json...");
   const { config: projectConfig } = loadProjectConfig(projectRoot);
 
+  // The legacy imports-based content model is gone (specs/extensions.md v2) — fail loudly with
+  // The migration path instead of silently ignoring the section.
+  if ("contentTypes" in projectConfig) {
+    throw new Error(
+      `project.json declares "contentTypes", which is no longer supported. ` +
+        `Run \`bun scripts/migrate-project-extensions.ts <project>\` to migrate to ` +
+        `"extensions" + "content", then \`jx schema\`.`,
+    );
+  }
+
   const outDir = resolve(projectRoot, projectConfig.build.outDir);
   const pagesDir = resolve(projectRoot, "pages");
   const publicDir = resolve(projectRoot, "public");
   const trailingSlash = projectConfig.build.trailingSlash ?? "always";
 
-  // ── 1b. Build the format registry from project imports ─────────────────
-  const formatRegistry = await buildProjectFormatRegistry(projectRoot, projectConfig);
+  // ── 1b. Build the extension registry from project.json#/extensions ─────
+  const registry = await buildProjectExtensionRegistry(projectRoot, projectConfig);
+  const formatRegistry = registry.formats;
   if (formatRegistry.entries.length > 0) {
     log(
       `  Registered ${formatRegistry.entries.length} format(s): ${formatRegistry.entries
@@ -105,6 +117,28 @@ export async function buildSite(
     );
   }
 
+  // ── 1c. Active extension server mounts (specs/extensions.md §11) ────────
+  // A mount is active when its class owns no project section, or the project declares a
+  // Non-empty value for its section key. Sites with active mounts always get a worker; a
+  // Static site cannot serve dynamic sections, so that combination is a build error.
+  const activeMounts = registry.serverMounts().filter((entry) => {
+    if (!entry.project) {
+      return true;
+    }
+    const value = projectConfig[entry.project.key] as Record<string, unknown> | undefined;
+    return value !== undefined && typeof value === "object" && Object.keys(value).length > 0;
+  });
+  if (activeMounts.length > 0 && !projectConfig.build.adapter) {
+    const sections = activeMounts
+      .map((entry) => (entry.project ? `"${entry.project.key}"` : `"${entry.server!.basePath}"`))
+      .join(", ");
+    throw new Error(
+      `project.json declares dynamic section(s) ${sections} served by extension mounts, but ` +
+        `build.adapter is "static". Dynamic tables need a server-capable adapter — set ` +
+        `build.adapter to "cloudflare-workers", "cloudflare-pages", "node", or "bun".`,
+    );
+  }
+
   // ── 2. Clean output directory ───────────────────────────────────────────
   if (clean && existsSync(outDir)) {
     rmSync(outDir, { force: true, recursive: true });
@@ -120,20 +154,22 @@ export async function buildSite(
   const staticRoutes = await discoverPages(pagesDir, formatRegistry);
   log(`  Found ${staticRoutes.length} page(s)`);
 
-  // ── 3b. Load content types ─────────────────────────────────────────────
-  log("Loading content types...");
-  const contentTypes = await loadContentTypes(projectRoot, projectConfig, formatRegistry);
-  if (contentTypes.size > 0) {
-    log(`  Loaded ${contentTypes.size} content type(s): ${[...contentTypes.keys()].join(", ")}`);
-    // Resolve cross-content-type $ref references
-    const contentConfig = loadContentConfig(projectRoot, projectConfig);
-    if (contentConfig) {
-      resolveContentTypeRefs(contentTypes, contentConfig.config);
-    }
+  // ── 3b. Load extension-contributed project sections ────────────────────
+  log("Loading project sections...");
+  const sections = await loadProjectSections(projectRoot, projectConfig, registry);
+  const sectionKeys = Object.keys(sections);
+  if (sectionKeys.length > 0) {
+    log(`  Loaded ${sectionKeys.length} section(s): ${sectionKeys.join(", ")}`);
   }
 
   // ── 4. Expand dynamic routes ────────────────────────────────────────────
-  const routes = await expandDynamicRoutes(staticRoutes, projectRoot, contentTypes, formatRegistry);
+  const routes = await expandDynamicRoutes(
+    staticRoutes,
+    projectRoot,
+    sections,
+    registry,
+    projectConfig,
+  );
   log(`  ${routes.length} route(s) after expansion`);
 
   let fileCount = 0;
@@ -235,11 +271,12 @@ export async function buildSite(
         route as unknown as SiteRoute,
         projectConfig,
         projectRoot,
-        contentTypes,
+        sections,
         imageCache,
         componentDefs,
         imageMetaCache,
         formatRegistry,
+        registry,
       );
 
       // Determine which component tags are fully static (for script omission)
@@ -355,11 +392,22 @@ export async function buildSite(
       }
     }
 
+    // Extension server mounts: static imports of the mount modules and used connector classes,
+    // Inlined JSON options (the project's section manifest — identifiers only, never secrets).
+    const { mounts, connectors } = buildMountSpecs(activeMounts, registry, projectConfig);
+    if (mounts.length > 0) {
+      log(
+        `  Mounting ${mounts.length} extension route(s): ${mounts.map((m) => m.basePath).join(", ")}`,
+      );
+    }
+
     // Cloudflare Pages uses advanced mode (_worker.js inside the build output) — the
     // Functions/ directory convention only works from the project root, not from dist/.
-    // A static-only Pages site needs no worker at all.
-    const skipWorker = adapter === "cloudflare-pages" && deduped.size === 0;
-    const workerSource = skipWorker ? null : compileSiteServer([...deduped.values()], { adapter });
+    // A static-only Pages site needs no worker at all; sites with mounts always get one.
+    const skipWorker = adapter === "cloudflare-pages" && deduped.size === 0 && mounts.length === 0;
+    const workerSource = skipWorker
+      ? null
+      : compileSiteServer([...deduped.values()], { adapter, connectors, mounts });
 
     if (workerSource) {
       const workerName = adapter === "cloudflare-pages" ? "_worker.js" : "worker.js";
@@ -445,7 +493,7 @@ export async function buildSite(
  * @param {SiteRoute} route
  * @param {ProjectConfig} projectConfig
  * @param {string} projectRoot
- * @param {Map<string, ContentLoaderEntry[]>} [contentTypes]
+ * @param {Record<string, unknown>} [sections] - Extension-loaded project sections
  * @param {import("./image-cache.js").CacheManifest | null} [imageCache]
  * @param {Map<string, JxElement>} [componentDefs]
  * @param {ImageMetaCache | null} [imageMetaCache] - Set when images.service is "cloudflare"
@@ -460,11 +508,12 @@ async function compilePage(
   route: SiteRoute,
   projectConfig: ProjectConfig,
   projectRoot: string,
-  contentTypes = new Map<string, ContentLoaderEntry[]>(),
+  sections: Record<string, unknown> = {},
   imageCache: CacheManifest | null = null,
   componentDefs = new Map<string, JxElement>(),
   imageMetaCache: ImageMetaCache | null = null,
   formatRegistry?: FormatRegistry,
+  registry?: ExtensionRegistry,
 ) {
   // Load the raw page document (.json natively, other formats via the registry)
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
@@ -482,12 +531,13 @@ async function compilePage(
   delete layoutDoc._pageTitle;
 
   // Inject $site and $page context
-  injectContext(layoutDoc, projectConfig, route, contentTypes, projectRoot);
+  injectContext(layoutDoc, projectConfig, route, projectRoot);
 
-  // Resolve generic $prototype entries via .class.json imports
+  // Resolve generic $prototype entries via .class.json imports (and lower registry classes)
   await resolvePrototypes(layoutDoc, route, projectRoot, {
     config: projectConfig,
-    contentTypes,
+    sections,
+    ...(registry === undefined ? {} : { registry }),
   });
 
   // Build scope from resolved state so template strings in title/$head can be evaluated
@@ -617,6 +667,92 @@ async function compilePage(
   };
 }
 
+/**
+ * Build the mount + connector specs for the generated worker (specs/extensions.md §11–§12).
+ *
+ * Mount options inline the extension-contributed sections from project.json — identifiers only,
+ * never secrets (§13). Connector classes are included when any section entry names their
+ * `connector.provider`; the import specifier comes from the descriptor's `connector.module` (bare
+ * specifier — Workers cannot import filesystem paths).
+ *
+ * @param {FormatEntry[]} activeMounts - Server-mount classes with active sections
+ * @param {ExtensionRegistry} registry
+ * @param {ProjectConfig} projectConfig
+ * @returns {{ mounts: SiteMountSpec[]; connectors: SiteConnectorSpec[] }}
+ */
+function buildMountSpecs(
+  activeMounts: FormatEntry[],
+  registry: ExtensionRegistry,
+  projectConfig: ProjectConfig,
+): { mounts: SiteMountSpec[]; connectors: SiteConnectorSpec[] } {
+  if (activeMounts.length === 0) {
+    return { connectors: [], mounts: [] };
+  }
+
+  const sections: Record<string, unknown> = {};
+  for (const contribution of registry.projectContributions()) {
+    const { key } = contribution.project!;
+    if (key in projectConfig) {
+      sections[key] = projectConfig[key];
+    }
+  }
+
+  const mounts: SiteMountSpec[] = activeMounts.map((entry) => {
+    const server = entry.server!;
+    const { module } = server;
+    if (typeof module !== "string" || module === "") {
+      throw new Error(
+        `Extension class "${entry.name}": server.module (a bare import specifier) is required ` +
+          `to generate a deployable worker`,
+      );
+    }
+    return {
+      basePath: server.basePath,
+      className: (entry.classDef.title as string | undefined) ?? entry.name,
+      module,
+      options: { basePath: server.basePath, sections },
+      order: server.order ?? 100,
+    };
+  });
+
+  // Used providers: any section entry object carrying a string `provider` field (the connector
+  // Vocabulary, §12) marks that provider's class for import.
+  const usedProviders = new Set<string>();
+  for (const value of Object.values(sections)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      continue;
+    }
+    for (const sectionEntry of Object.values(value as Record<string, unknown>)) {
+      const provider = (sectionEntry as { provider?: unknown } | null)?.provider;
+      if (typeof provider === "string") {
+        usedProviders.add(provider);
+      }
+    }
+  }
+
+  const connectors: SiteConnectorSpec[] = [];
+  for (const entry of registry.connectors()) {
+    const provider = String(entry.connector!.provider);
+    if (!usedProviders.has(provider)) {
+      continue;
+    }
+    const { module } = entry.connector!;
+    if (typeof module !== "string" || module === "") {
+      throw new Error(
+        `Connector class "${entry.name}": connector.module (a bare import specifier) is ` +
+          `required to generate a deployable worker`,
+      );
+    }
+    connectors.push({
+      className: (entry.classDef.title as string | undefined) ?? entry.name,
+      module,
+      provider,
+    });
+  }
+
+  return { connectors, mounts };
+}
+
 /**
  * Resolve template strings in $head entries against the compiled scope.
  *

package/src/site/site-loader.ts

@@ -39,7 +39,6 @@ const DEFAULTS = {
     provider: null,
     trailingSlash: "always",
   },
-  contentTypes: {},
   defaults: {
     charset: "utf8",
     lang: "en",
@@ -83,7 +82,9 @@ export function loadProjectConfig(projectRoot: string) {
     throw new Error(`Invalid project.json: ${errorMessage(error)}`, { cause: error });
   }
 
-  // Deep merge with defaults
+  // Deep merge with defaults. The `...raw` spread carries every author-declared key through
+  // Untouched — including `extensions` and extension-contributed sections (`content`, ...), which
+  // Are opaque to the loader (specs/extensions.md §3.1).
   const config: ResolvedProjectConfig = {
     ...DEFAULTS,
     ...raw,
@@ -111,9 +112,6 @@ export function loadProjectConfig(projectRoot: string) {
   if (raw.imports) {
     config.imports = raw.imports;
   }
-  if (raw.contentTypes) {
-    config.contentTypes = raw.contentTypes;
-  }
 
   // Validate adapter
   const VALID_ADAPTERS = ["cloudflare-workers", "cloudflare-pages", "node", "bun"];

package/src/targets/compile-server.ts

@@ -56,15 +56,47 @@ export default app
 `;
 }
 
+/**
+ * One extension server mount to emit into the generated worker (specs/extensions.md §11). The
+ * module is imported statically (Workers cannot dynamic-import), the options are inlined JSON
+ * (identifiers only — never secrets), and every mount shares one context object, called in
+ * ascending `order`.
+ */
+export interface SiteMountSpec {
+  /** Export name of the mount class (the descriptor title, e.g. "Data"). */
+  className: string;
+  /** Bare module specifier the worker imports (`server.module`). */
+  module: string;
+  /** Route subtree the mount owns (`server.basePath`). */
+  basePath: string;
+  /** Mount order (`server.order`, ascending). */
+  order: number;
+  /** JSON-inlined mount options (project sections manifest etc.). */
+  options: Record<string, unknown>;
+}
+
+/** A connector provider class the worker imports and hands to mounts via `options.connectors`. */
+export interface SiteConnectorSpec {
+  /** The `connector.provider` id (options.connectors key). */
+  provider: string;
+  /** Export name of the provider implementation (the descriptor title). */
+  className: string;
+  /** Bare module specifier (`connector.module`). */
+  module: string;
+}
+
 /**
  * Generate a bundled Hono server entry from pre-collected server entries across an entire site.
- * Used when `build.adapter` is set in project.json. Returns null if no entries are provided.
+ * Used when `build.adapter` is set in project.json. Returns null if no entries or mounts are
+ * provided.
  *
  * @param {{ exportName: string; src: string }[]} entries - Resolved server entries
  * @param {object} [opts]
  * @param {string} [opts.baseUrl] - Base path for server endpoints. Default is `'/_jx/server'`
  * @param {string | null} [opts.adapter] - Deployment adapter: `"cloudflare-workers"`,
  *   `"cloudflare-pages"`, `"node"`, `"bun"`
+ * @param {SiteMountSpec[]} [opts.mounts] - Extension server mounts, already sorted by order
+ * @param {SiteConnectorSpec[]} [opts.connectors] - Connector classes used by the mounts
  * @returns {string | null} Complete worker/server source string, or null
  */
 export function compileSiteServer(
@@ -72,10 +104,12 @@ export function compileSiteServer(
   opts: {
     baseUrl?: string;
     adapter?: string | null;
+    mounts?: SiteMountSpec[];
+    connectors?: SiteConnectorSpec[];
   } = {},
 ) {
-  const { baseUrl = "/_jx/server", adapter = null } = opts;
-  if (entries.length === 0 && !adapter) {
+  const { baseUrl = "/_jx/server", adapter = null, mounts = [], connectors = [] } = opts;
+  if (entries.length === 0 && mounts.length === 0 && !adapter) {
     return null;
   }
 
@@ -83,6 +117,8 @@ export function compileSiteServer(
     .map(({ exportName, src }) => `import { ${exportName} } from '${src}'`)
     .join("\n");
 
+  const mountBlock = buildMountBlock(mounts, connectors);
+
   const routes = entries.map(({ exportName }) => buildRoute(exportName, baseUrl)).join("\n");
 
   // Workers static assets and Pages advanced mode (_worker.js) both route every request
@@ -94,15 +130,57 @@ export function compileSiteServer(
 
   return `// Generated by @jxsuite/compiler — do not edit manually
 import { Hono } from 'hono'
-${imports}
+${imports}${mountBlock.imports}
 
 const app = new Hono()
-${routes}
+${mountBlock.routes}${routes}
 ${adapterBlock}
 export default app
 `;
 }
 
+/**
+ * Emit the extension-mount section: static imports, one shared ctx, ordered `mount()` calls at
+ * module init (top-level await), and `app.all('<basePath>/*', …)` wrappers registered BEFORE the
+ * /_jx/server routes and the ASSETS fallthrough.
+ *
+ * @param {SiteMountSpec[]} mounts
+ * @param {SiteConnectorSpec[]} connectors
+ * @returns {{ imports: string; routes: string }}
+ */
+function buildMountBlock(mounts: SiteMountSpec[], connectors: SiteConnectorSpec[]) {
+  if (mounts.length === 0) {
+    return { imports: "", routes: "" };
+  }
+  const ordered = mounts.toSorted((a, b) => a.order - b.order);
+
+  const importLines: string[] = [];
+  for (const mount of ordered) {
+    importLines.push(`import { ${mount.className} } from '${mount.module}'`);
+  }
+  for (const connector of connectors) {
+    importLines.push(`import { ${connector.className} } from '${connector.module}'`);
+  }
+
+  const lines: string[] = [
+    "// Extension server mounts (specs/extensions.md §11): one shared ctx, mounted in order.",
+    "const jxCtx = {}",
+    `const jxConnectors = { ${connectors
+      .map((c) => `${JSON.stringify(c.provider)}: ${c.className}`)
+      .join(", ")} }`,
+  ];
+  for (const [index, mount] of ordered.entries()) {
+    const optionsJson = JSON.stringify(mount.options);
+    lines.push(
+      `const jxMount${index} = await ${mount.className}.mount({ ...${optionsJson}, connectors: jxConnectors }, jxCtx)`,
+      `app.all('${mount.basePath}/*', (c) => jxMount${index}(c.req.raw, c.env))`,
+      `app.all('${mount.basePath}', (c) => jxMount${index}(c.req.raw, c.env))`,
+    );
+  }
+
+  return { imports: `\n${importLines.join("\n")}`, routes: `${lines.join("\n")}\n` };
+}
+
 /** @param {string} exportName @param {string} baseUrl */
 function buildRoute(exportName: string, baseUrl: string) {
   return `