@jay-framework/stack-server-runtime 0.11.0 → 0.12.0

package/dist/index.js

@@ -17,6 +17,7 @@ import "js-beautify";
 import fs$2 from "fs";
 import path$1 from "path";
 import YAML from "yaml";
+import { getLogger } from "@jay-framework/logger";
 import crypto from "node:crypto";
 const serviceRegistry = /* @__PURE__ */ new Map();
 function registerService(marker, service) {
@@ -40,9 +41,13 @@ function hasService(marker) {
 function clearServiceRegistry() {
   serviceRegistry.clear();
 }
+function getServiceRegistry() {
+  return serviceRegistry;
+}
 function resolveServices(serviceMarkers) {
   return serviceMarkers.map((marker) => getService(marker));
 }
+globalThis.__JAY_SERVICE_RESOLVER__ = resolveServices;
 const initCallbacks = [];
 const shutdownCallbacks = [];
 function onInit(callback) {
@@ -94,10 +99,17 @@ class DevSlowlyChangingPhase {
   }
   async runSlowlyForPage(pageParams, pageProps, parts) {
     for (const part of parts) {
-      const { compDefinition } = part;
+      const { compDefinition, contractInfo } = part;
       if (compDefinition.loadParams) {
         const services = resolveServices(compDefinition.services);
-        const compParams = compDefinition.loadParams(services);
+        const loadParamsArgs = contractInfo ? [
+          ...services,
+          {
+            contractName: contractInfo.contractName,
+            metadata: contractInfo.metadata
+          }
+        ] : services;
+        const compParams = compDefinition.loadParams(loadParamsArgs);
         if (!await findMatchingParams(pageParams, compParams))
           return notFound();
       }
@@ -105,11 +117,19 @@ class DevSlowlyChangingPhase {
     let slowlyViewState = {};
     let carryForward = {};
     for (const part of parts) {
-      const { compDefinition, key } = part;
+      const { compDefinition, key, contractInfo } = part;
       if (compDefinition.slowlyRender) {
         const services = resolveServices(compDefinition.services);
+        const partProps = {
+          ...pageProps,
+          ...pageParams,
+          ...contractInfo && {
+            contractName: contractInfo.contractName,
+            metadata: contractInfo.metadata
+          }
+        };
         const slowlyRenderedPart = await compDefinition.slowlyRender(
-          { ...pageProps, ...pageParams },
+          partProps,
           ...services
         );
         if (slowlyRenderedPart.kind === "PhaseOutput") {
@@ -136,12 +156,20 @@ async function renderFastChangingData(pageParams, pageProps, carryForward, parts
   let fastViewState = {};
   let fastCarryForward = {};
   for (const part of parts) {
-    const { compDefinition, key } = part;
+    const { compDefinition, key, contractInfo } = part;
     if (compDefinition.fastRender) {
       const partSlowlyCarryForward = key ? carryForward[key] : carryForward;
       const services = resolveServices(compDefinition.services);
+      const partProps = {
+        ...pageProps,
+        ...pageParams,
+        ...contractInfo && {
+          contractName: contractInfo.contractName,
+          metadata: contractInfo.metadata
+        }
+      };
       const fastRenderedPart = await compDefinition.fastRender(
-        { ...pageProps, ...pageParams },
+        partProps,
         partSlowlyCarryForward,
         ...services
       );
@@ -234,13 +262,13 @@ ${clientInitExecution}
       const target = document.getElementById('target');
       const pageComp = makeCompositeJayComponent(render, viewState, fastCarryForward, ${compositeParts}, trackByMap)
 
-      const instance = pageComp({...viewState, ...fastCarryForward})
+      const instance = pageComp({/* placeholder for page props */})
 ${automationWrap}
     <\/script>
   </body>
 </html>`;
 }
-const require$2 = createRequire(import.meta.url);
+const require$3 = createRequire(import.meta.url);
 async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfig, options) {
   const exists = await fs$1.access(route.compPath, fs$1.constants.F_OK).then(() => true).catch(() => false);
   const parts = [];
@@ -268,11 +296,12 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
   );
   return jayHtmlWithValidations.mapAsync(async (jayHtml) => {
     const usedPackages = /* @__PURE__ */ new Set();
+    const headlessInstanceComponents = [];
     for await (const headlessImport of jayHtml.headlessImports) {
       const module = headlessImport.codeLink.module;
       const name = headlessImport.codeLink.names[0].name;
       const isLocalModule = module[0] === "." || module[0] === "/";
-      const modulePath = isLocalModule ? path__default.resolve(dirName, module) : require$2.resolve(module, { paths: require$2.resolve.paths(dirName) });
+      const modulePath = isLocalModule ? path__default.resolve(dirName, module) : require$3.resolve(module, { paths: require$3.resolve.paths(dirName) });
       const compDefinition = (await vite.ssrLoadModule(modulePath))[name];
       const moduleImport = isLocalModule ? path__default.resolve(dirName, module) : module;
       const isNpmPackage = !isLocalModule;
@@ -281,23 +310,85 @@ async function loadPageParts(vite, route, pagesBase, projectBase, jayRollupConfi
         const packageName = module.startsWith("@") ? module.split("/").slice(0, 2).join("/") : module.split("/")[0];
         usedPackages.add(packageName);
       }
-      const key = headlessImport.key;
-      const part = {
-        key,
-        compDefinition,
-        clientImport: `import {${name}} from '${clientModuleImport}'`,
-        clientPart: `{comp: ${name}.comp, contextMarkers: ${name}.contexts || [], key: '${headlessImport.key}'}`
-      };
-      parts.push(part);
+      if (headlessImport.key) {
+        const key = headlessImport.key;
+        const part = {
+          key,
+          compDefinition,
+          clientImport: `import {${name}} from '${clientModuleImport}'`,
+          clientPart: `{comp: ${name}.comp, contextMarkers: ${name}.contexts || [], key: '${key}'}`,
+          // Include contract info for dynamic contract components
+          contractInfo: headlessImport.contract ? {
+            contractName: headlessImport.contract.name,
+            metadata: headlessImport.metadata
+          } : void 0
+        };
+        parts.push(part);
+      }
+      if (!headlessImport.key && headlessImport.contract) {
+        headlessInstanceComponents.push({
+          contractName: headlessImport.contractName,
+          compDefinition,
+          contract: headlessImport.contract
+        });
+      }
     }
+    const headlessContracts = jayHtml.headlessImports.filter((hi) => hi.contract !== void 0 && hi.key !== void 0).map((hi) => ({
+      key: hi.key,
+      contract: hi.contract,
+      contractPath: hi.contractPath
+    }));
     return {
       parts,
       serverTrackByMap: jayHtml.serverTrackByMap,
       clientTrackByMap: jayHtml.clientTrackByMap,
-      usedPackages
+      usedPackages,
+      headlessContracts,
+      headlessInstanceComponents
     };
   });
 }
+async function slowRenderInstances(discovered, headlessInstanceComponents) {
+  const componentByContractName = /* @__PURE__ */ new Map();
+  for (const comp of headlessInstanceComponents) {
+    componentByContractName.set(comp.contractName, comp);
+  }
+  const resolvedData = [];
+  const slowViewStates = {};
+  const discoveredForFast = [];
+  const carryForwards = {};
+  for (const instance of discovered) {
+    const comp = componentByContractName.get(instance.contractName);
+    if (!comp || !comp.compDefinition.slowlyRender) {
+      continue;
+    }
+    const services = resolveServices(comp.compDefinition.services);
+    const slowResult = await comp.compDefinition.slowlyRender(instance.props, ...services);
+    if (slowResult.kind === "PhaseOutput") {
+      const coordKey = instance.coordinate.join("/");
+      resolvedData.push({
+        coordinate: instance.coordinate,
+        contract: comp.contract,
+        slowViewState: slowResult.rendered
+      });
+      slowViewStates[coordKey] = slowResult.rendered;
+      carryForwards[coordKey] = slowResult.carryForward;
+      discoveredForFast.push({
+        contractName: instance.contractName,
+        props: instance.props,
+        coordinate: instance.coordinate
+      });
+    }
+  }
+  if (discoveredForFast.length === 0) {
+    return void 0;
+  }
+  return {
+    resolvedData,
+    slowViewStates,
+    instancePhaseData: { discovered: discoveredForFast, carryForwards }
+  };
+}
 class ActionRegistry {
   constructor() {
     __publicField(this, "actions", /* @__PURE__ */ new Map());
@@ -445,10 +536,6 @@ async function executeAction(actionName, input) {
 function getActionCacheHeaders(actionName) {
   return actionRegistry.getCacheHeaders(actionName);
 }
-async function runAction(action, input) {
-  const services = resolveServices(action.services);
-  return action.handler(input, ...services);
-}
 var __defProp2 = Object.defineProperty;
 var __defNormalProp2 = (obj, key, value) => key in obj ? __defProp2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField2 = (obj, key, value) => {
@@ -545,7 +632,7 @@ new Proxy(e, {
     return t[r];
   }
 });
-const require$1 = createRequire$1(import.meta.url);
+const require$2 = createRequire$1(import.meta.url);
 async function discoverAndRegisterActions(options) {
   const {
     projectRoot,
@@ -562,13 +649,13 @@ async function discoverAndRegisterActions(options) {
   const actionsPath = path.resolve(projectRoot, actionsDir);
   if (!fs.existsSync(actionsPath)) {
     if (verbose) {
-      console.log(`[Actions] No actions directory found at ${actionsPath}`);
+      getLogger().info(`[Actions] No actions directory found at ${actionsPath}`);
     }
     return result;
   }
   const actionFiles = await findActionFiles(actionsPath);
   if (verbose) {
-    console.log(`[Actions] Found ${actionFiles.length} action file(s)`);
+    getLogger().info(`[Actions] Found ${actionFiles.length} action file(s)`);
   }
   for (const filePath of actionFiles) {
     result.scannedFiles.push(filePath);
@@ -585,12 +672,14 @@ async function discoverAndRegisterActions(options) {
           result.actionNames.push(exportValue.actionName);
           result.actionCount++;
           if (verbose) {
-            console.log(`[Actions] Registered: ${exportValue.actionName}`);
+            getLogger().info(
+              `[Actions] Registered: ${exportValue.actionName}`
+            );
           }
         }
       }
     } catch (error) {
-      console.error(`[Actions] Failed to import ${filePath}:`, error);
+      getLogger().error(`[Actions] Failed to import ${filePath}: ${error}`);
     }
   }
   return result;
@@ -657,9 +746,8 @@ async function discoverNpmPluginActions(projectRoot, registry, verbose, viteServ
           continue;
         }
         if (verbose) {
-          console.log(
-            `[Actions] NPM plugin "${packageName}" declares actions:`,
-            pluginConfig.actions
+          getLogger().info(
+            `[Actions] NPM plugin "${packageName}" declares actions: ${JSON.stringify(pluginConfig.actions)}`
           );
         }
         const actions = await registerNpmPluginActions(
@@ -675,13 +763,13 @@ async function discoverNpmPluginActions(projectRoot, registry, verbose, viteServ
       }
     }
   } catch (error) {
-    console.error("[Actions] Failed to read project package.json:", error);
+    getLogger().error(`[Actions] Failed to read project package.json: ${error}`);
   }
   return allActions;
 }
 function tryResolvePluginYaml(packageName, projectRoot) {
   try {
-    return require$1.resolve(`${packageName}/plugin.yaml`, {
+    return require$2.resolve(`${packageName}/plugin.yaml`, {
       paths: [projectRoot]
     });
   } catch {
@@ -703,18 +791,18 @@ async function registerNpmPluginActions(packageName, pluginConfig, registry, ver
         registry.register(actionExport);
         registeredActions.push(actionExport.actionName);
         if (verbose) {
-          console.log(
+          getLogger().info(
             `[Actions] Registered NPM plugin action: ${actionExport.actionName}`
           );
         }
       } else {
-        console.warn(
+        getLogger().warn(
           `[Actions] NPM plugin "${packageName}" declares action "${actionName}" but it's not exported or not a JayAction`
         );
       }
     }
   } catch (importError) {
-    console.error(`[Actions] Failed to import NPM plugin "${packageName}":`, importError);
+    getLogger().error(`[Actions] Failed to import NPM plugin "${packageName}": ${importError}`);
   }
   return registeredActions;
 }
@@ -729,7 +817,9 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
   const registeredActions = [];
   const pluginName = pluginConfig.name || path.basename(pluginPath);
   if (verbose) {
-    console.log(`[Actions] Plugin "${pluginName}" declares actions:`, pluginConfig.actions);
+    getLogger().info(
+      `[Actions] Plugin "${pluginName}" declares actions: ${JSON.stringify(pluginConfig.actions)}`
+    );
   }
   let modulePath = pluginConfig.module ? path.join(pluginPath, pluginConfig.module) : path.join(pluginPath, "index.ts");
   if (!fs.existsSync(modulePath)) {
@@ -740,7 +830,7 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
     } else if (fs.existsSync(jsPath)) {
       modulePath = jsPath;
     } else {
-      console.warn(`[Actions] Plugin "${pluginName}" module not found at ${modulePath}`);
+      getLogger().warn(`[Actions] Plugin "${pluginName}" module not found at ${modulePath}`);
       return [];
     }
   }
@@ -757,25 +847,32 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
         registry.register(actionExport);
         registeredActions.push(actionExport.actionName);
         if (verbose) {
-          console.log(
+          getLogger().info(
             `[Actions] Registered plugin action: ${actionExport.actionName}`
           );
         }
       } else {
-        console.warn(
+        getLogger().warn(
           `[Actions] Plugin "${pluginName}" declares action "${actionName}" but it's not exported or not a JayAction`
         );
       }
     }
   } catch (importError) {
-    console.error(`[Actions] Failed to import plugin module at ${modulePath}:`, importError);
+    getLogger().error(
+      `[Actions] Failed to import plugin module at ${modulePath}: ${importError}`
+    );
   }
   return registeredActions;
 }
-const require2 = createRequire$1(import.meta.url);
-async function discoverPluginsWithInit(options) {
-  const { projectRoot, verbose = false } = options;
-  const plugins = [];
+const require$1 = createRequire$1(import.meta.url);
+async function scanPlugins(options) {
+  const {
+    projectRoot,
+    verbose = false,
+    includeDevDeps = false,
+    discoverTransitive = false
+  } = options;
+  const plugins = /* @__PURE__ */ new Map();
   const visitedPackages = /* @__PURE__ */ new Set();
   const localPluginsPath = path.join(projectRoot, "src/plugins");
   if (fs.existsSync(localPluginsPath)) {
@@ -788,37 +885,37 @@ async function discoverPluginsWithInit(options) {
         const manifest = loadPluginManifest(pluginPath);
         if (!manifest)
           continue;
-        const initConfig = resolvePluginInit(pluginPath, manifest.init, true);
-        if (!initConfig)
-          continue;
         const dependencies = await getPackageDependencies(pluginPath);
-        plugins.push({
-          name: manifest.name || entry.name,
+        const pluginName = manifest.name || entry.name;
+        plugins.set(entry.name, {
+          name: pluginName,
           pluginPath,
           packageName: pluginPath,
-          // For local, use path
+          // For local, use path as identifier
           isLocal: true,
-          initModule: initConfig.module,
-          initExport: initConfig.export,
+          manifest,
           dependencies
         });
         visitedPackages.add(pluginPath);
         if (verbose) {
-          console.log(
-            `[PluginInit] Found local plugin with init: ${manifest.name || entry.name}`
-          );
+          getLogger().info(`[PluginScanner] Found local plugin: ${pluginName}`);
         }
       }
     } catch (error) {
-      console.warn(`[PluginInit] Failed to scan local plugins: ${error}`);
+      if (verbose) {
+        getLogger().warn(`[PluginScanner] Failed to scan local plugins: ${error}`);
+      }
     }
   }
   const projectPackageJsonPath = path.join(projectRoot, "package.json");
   if (fs.existsSync(projectPackageJsonPath)) {
     try {
       const projectPackageJson = JSON.parse(fs.readFileSync(projectPackageJsonPath, "utf-8"));
-      const initialDeps = Object.keys(projectPackageJson.dependencies || {});
-      const packagesToCheck = [...initialDeps];
+      const deps = {
+        ...projectPackageJson.dependencies,
+        ...includeDevDeps ? projectPackageJson.devDependencies : {}
+      };
+      const packagesToCheck = Object.keys(deps);
       while (packagesToCheck.length > 0) {
         const depName = packagesToCheck.shift();
         if (visitedPackages.has(depName))
@@ -826,7 +923,7 @@ async function discoverPluginsWithInit(options) {
         visitedPackages.add(depName);
         let pluginYamlPath;
         try {
-          pluginYamlPath = require2.resolve(`${depName}/plugin.yaml`, {
+          pluginYamlPath = require$1.resolve(`${depName}/plugin.yaml`, {
             paths: [projectRoot]
           });
         } catch {
@@ -836,30 +933,76 @@ async function discoverPluginsWithInit(options) {
         const manifest = loadPluginManifest(pluginPath);
         if (!manifest)
           continue;
-        const initConfig = resolvePluginInit(pluginPath, manifest.init, false);
-        if (!initConfig)
-          continue;
         const dependencies = await getPackageDependencies(pluginPath);
-        plugins.push({
+        plugins.set(depName, {
           name: manifest.name || depName,
           pluginPath,
           packageName: depName,
           isLocal: false,
-          initModule: initConfig.module,
-          initExport: initConfig.export,
+          manifest,
           dependencies
         });
         if (verbose) {
-          console.log(`[PluginInit] Found NPM plugin with init: ${depName}`);
+          getLogger().info(`[PluginScanner] Found NPM plugin: ${depName}`);
         }
-        for (const transitiveDep of dependencies) {
-          if (!visitedPackages.has(transitiveDep)) {
-            packagesToCheck.push(transitiveDep);
+        if (discoverTransitive) {
+          for (const transitiveDep of dependencies) {
+            if (!visitedPackages.has(transitiveDep)) {
+              packagesToCheck.push(transitiveDep);
+            }
           }
         }
       }
     } catch (error) {
-      console.warn(`[PluginInit] Failed to scan NPM plugins: ${error}`);
+      if (verbose) {
+        getLogger().warn(`[PluginScanner] Failed to scan NPM plugins: ${error}`);
+      }
+    }
+  }
+  return plugins;
+}
+async function getPackageDependencies(pluginPath) {
+  const packageJsonPath = path.join(pluginPath, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return [];
+  }
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    return Object.keys(packageJson.dependencies || {});
+  } catch {
+    return [];
+  }
+}
+async function discoverPluginsWithInit(options) {
+  const { projectRoot, verbose = false } = options;
+  const scannedPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    includeDevDeps: false,
+    // Only runtime dependencies
+    discoverTransitive: true
+    // Need transitive for dependency ordering
+  });
+  const plugins = [];
+  for (const [key, scanned] of scannedPlugins) {
+    const initConfig = resolvePluginInit(
+      scanned.pluginPath,
+      scanned.manifest.init,
+      scanned.isLocal
+    );
+    if (!initConfig)
+      continue;
+    plugins.push({
+      name: scanned.name,
+      pluginPath: scanned.pluginPath,
+      packageName: scanned.packageName,
+      isLocal: scanned.isLocal,
+      initModule: initConfig.module,
+      initExport: initConfig.export,
+      dependencies: scanned.dependencies
+    });
+    if (verbose) {
+      getLogger().info(`[PluginInit] Found plugin with init: ${scanned.name}`);
     }
   }
   return plugins;
@@ -899,18 +1042,6 @@ function resolvePluginInit(pluginPath, initConfig, isLocal) {
     return null;
   }
 }
-async function getPackageDependencies(pluginPath) {
-  const packageJsonPath = path.join(pluginPath, "package.json");
-  if (!fs.existsSync(packageJsonPath)) {
-    return [];
-  }
-  try {
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-    return Object.keys(packageJson.dependencies || {});
-  } catch {
-    return [];
-  }
-}
 function sortPluginsByDependencies(plugins) {
   const pluginNames = new Set(plugins.map((p) => p.packageName));
   const sorted = [];
@@ -920,7 +1051,7 @@ function sortPluginsByDependencies(plugins) {
     if (visited.has(plugin.packageName))
       return;
     if (visiting.has(plugin.packageName)) {
-      console.warn(`[PluginInit] Circular dependency detected for ${plugin.name}`);
+      getLogger().warn(`[PluginInit] Circular dependency detected for ${plugin.name}`);
       return;
     }
     visiting.add(plugin.packageName);
@@ -960,14 +1091,14 @@ async function executePluginServerInits(plugins, viteServer, verbose = false) {
       }
       const jayInit = pluginModule[plugin.initExport];
       if (!jayInit || jayInit.__brand !== "JayInit") {
-        console.warn(
+        getLogger().warn(
           `[PluginInit] Plugin "${plugin.name}" init module doesn't export a valid JayInit at "${plugin.initExport}"`
         );
         continue;
       }
       if (typeof jayInit._serverInit === "function") {
         if (verbose) {
-          console.log(`[DevServer] Running server init: ${plugin.name}`);
+          getLogger().info(`[DevServer] Running server init: ${plugin.name}`);
         }
         const clientData = await jayInit._serverInit();
         if (clientData !== void 0 && clientData !== null) {
@@ -975,9 +1106,8 @@ async function executePluginServerInits(plugins, viteServer, verbose = false) {
         }
       }
     } catch (error) {
-      console.error(
-        `[PluginInit] Failed to execute server init for "${plugin.name}":`,
-        error
+      getLogger().error(
+        `[PluginInit] Failed to execute server init for "${plugin.name}": ${error}`
       );
     }
   }
@@ -1146,6 +1276,451 @@ class SlowRenderCache {
     return Array.from(this.pathToKeys.keys());
   }
 }
+const require2 = createRequire(import.meta.url);
+async function executeDynamicGenerator(plugin, config, projectRoot, services, verbose, viteServer) {
+  const { pluginPath, name: pluginName, isLocal, packageName } = plugin;
+  if (!config.generator) {
+    throw new Error(
+      `Plugin "${pluginName}" has dynamic_contracts entry but no generator specified`
+    );
+  }
+  const isFilePath = config.generator.startsWith("./") || config.generator.startsWith("/") || config.generator.includes(".ts") || config.generator.includes(".js");
+  let generator;
+  if (isFilePath) {
+    let generatorPath;
+    if (!isLocal) {
+      try {
+        generatorPath = require2.resolve(`${packageName}/${config.generator}`, {
+          paths: [projectRoot]
+        });
+      } catch {
+        generatorPath = path.join(pluginPath, config.generator);
+      }
+    } else {
+      generatorPath = path.join(pluginPath, config.generator);
+    }
+    if (!fs.existsSync(generatorPath)) {
+      const withTs = generatorPath + ".ts";
+      const withJs = generatorPath + ".js";
+      if (fs.existsSync(withTs)) {
+        generatorPath = withTs;
+      } else if (fs.existsSync(withJs)) {
+        generatorPath = withJs;
+      }
+    }
+    if (!fs.existsSync(generatorPath)) {
+      throw new Error(
+        `Generator file not found for plugin "${pluginName}": ${config.generator}`
+      );
+    }
+    if (verbose) {
+      getLogger().info(`   Loading generator from file: ${generatorPath}`);
+    }
+    let generatorModule;
+    if (viteServer) {
+      generatorModule = await viteServer.ssrLoadModule(generatorPath);
+    } else {
+      generatorModule = await import(generatorPath);
+    }
+    generator = generatorModule.generator || generatorModule.default;
+  } else {
+    if (verbose) {
+      getLogger().info(
+        `   Loading generator export: ${config.generator} from ${packageName}`
+      );
+    }
+    let pluginModule;
+    if (viteServer) {
+      pluginModule = await viteServer.ssrLoadModule(packageName);
+    } else {
+      pluginModule = await import(packageName);
+    }
+    generator = pluginModule[config.generator];
+    if (!generator) {
+      throw new Error(
+        `Generator "${config.generator}" not exported from plugin "${pluginName}". Ensure it's exported from the package's index.ts`
+      );
+    }
+  }
+  if (!generator || typeof generator.generate !== "function") {
+    throw new Error(
+      `Generator "${config.generator}" for plugin "${pluginName}" must have a 'generate' function. Use makeContractGenerator() to create valid generators.`
+    );
+  }
+  const resolvedServices = [];
+  for (const marker of generator.services) {
+    const service = services.get(marker);
+    if (!service) {
+      const markerName = marker.description ?? "unknown";
+      throw new Error(
+        `Service "${markerName}" required by ${pluginName} generator not found. Ensure it's registered in init.ts`
+      );
+    }
+    resolvedServices.push(service);
+  }
+  if (verbose) {
+    getLogger().info(`   Executing generator...`);
+  }
+  const result = await generator.generate(...resolvedServices);
+  return result;
+}
+function resolveStaticContractPath(plugin, contractSpec, projectRoot) {
+  const { pluginPath, isLocal, packageName } = plugin;
+  if (!isLocal) {
+    try {
+      return require2.resolve(`${packageName}/${contractSpec}`, {
+        paths: [projectRoot]
+      });
+    } catch {
+      const possiblePaths = [
+        path.join(pluginPath, "dist", contractSpec),
+        path.join(pluginPath, "lib", contractSpec),
+        path.join(pluginPath, contractSpec)
+      ];
+      const found = possiblePaths.find((p) => fs.existsSync(p));
+      return found || possiblePaths[0];
+    }
+  } else {
+    return path.join(pluginPath, contractSpec);
+  }
+}
+function toKebabCase(str) {
+  return str.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
+}
+function getJayStackVersion() {
+  try {
+    const packageJsonPath = path.join(__dirname, "..", "package.json");
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    return packageJson.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function materializeContracts(options, services = /* @__PURE__ */ new Map()) {
+  const {
+    projectRoot,
+    outputDir = path.join(projectRoot, "build", "materialized-contracts"),
+    dynamicOnly = false,
+    pluginFilter,
+    verbose = false,
+    viteServer
+  } = options;
+  const contracts = [];
+  const pluginsIndexMap = /* @__PURE__ */ new Map();
+  let staticCount = 0;
+  let dynamicCount = 0;
+  if (verbose) {
+    getLogger().info("Scanning for plugins...");
+  }
+  const plugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    includeDevDeps: true
+    // Include dev deps for contract discovery
+  });
+  if (verbose) {
+    getLogger().info(`Found ${plugins.size} plugin(s)`);
+  }
+  for (const [pluginKey, plugin] of plugins) {
+    if (pluginFilter && plugin.name !== pluginFilter && pluginKey !== pluginFilter)
+      continue;
+    if (verbose) {
+      getLogger().info(`
+📦 Processing plugin: ${plugin.name}`);
+    }
+    const { manifest } = plugin;
+    if (!dynamicOnly && manifest.contracts) {
+      for (const contract of manifest.contracts) {
+        const contractPath = resolveStaticContractPath(
+          plugin,
+          contract.contract,
+          projectRoot
+        );
+        const relativePath = path.relative(projectRoot, contractPath);
+        const entry = {
+          plugin: plugin.name,
+          name: contract.name,
+          type: "static",
+          path: "./" + relativePath
+        };
+        contracts.push(entry);
+        staticCount++;
+        const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+        if (!pluginsIndexMap.has(plugin.name)) {
+          pluginsIndexMap.set(plugin.name, {
+            path: "./" + pluginRelPath.replace(/\\/g, "/"),
+            contracts: []
+          });
+        }
+        pluginsIndexMap.get(plugin.name).contracts.push({
+          name: contract.name,
+          type: "static",
+          path: "./" + relativePath
+        });
+        if (verbose) {
+          getLogger().info(`   📄 Static: ${contract.name}`);
+        }
+      }
+    }
+    if (manifest.dynamic_contracts) {
+      const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
+      const pluginOutputDir = path.join(outputDir, plugin.name.replace(/[@/]/g, "_"));
+      fs.mkdirSync(pluginOutputDir, { recursive: true });
+      for (const config of dynamicConfigs) {
+        if (verbose) {
+          getLogger().info(`   ⚡ Dynamic contracts (prefix: ${config.prefix})`);
+        }
+        try {
+          const generatedContracts = await executeDynamicGenerator(
+            plugin,
+            config,
+            projectRoot,
+            services,
+            verbose,
+            viteServer
+          );
+          const prefix = config.prefix;
+          for (const generated of generatedContracts) {
+            const fullName = `${prefix}/${toKebabCase(generated.name)}`;
+            const fileName = `${prefix}-${toKebabCase(generated.name)}.jay-contract`;
+            const filePath = path.join(pluginOutputDir, fileName);
+            fs.writeFileSync(filePath, generated.yaml, "utf-8");
+            const relativePath = path.relative(projectRoot, filePath);
+            const dynEntry = {
+              plugin: plugin.name,
+              name: fullName,
+              type: "dynamic",
+              path: "./" + relativePath,
+              metadata: generated.metadata
+            };
+            contracts.push(dynEntry);
+            dynamicCount++;
+            const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+            if (!pluginsIndexMap.has(plugin.name)) {
+              pluginsIndexMap.set(plugin.name, {
+                path: "./" + pluginRelPath.replace(/\\/g, "/"),
+                contracts: []
+              });
+            }
+            pluginsIndexMap.get(plugin.name).contracts.push({
+              name: fullName,
+              type: "dynamic",
+              path: "./" + relativePath
+            });
+            if (verbose) {
+              getLogger().info(`   ⚡ Materialized: ${fullName}`);
+            }
+          }
+        } catch (error) {
+          getLogger().error(
+            `   ❌ Failed to materialize dynamic contracts for ${plugin.name} (${config.prefix}): ${error}`
+          );
+        }
+      }
+    }
+  }
+  const index = {
+    materialized_at: (/* @__PURE__ */ new Date()).toISOString(),
+    jay_stack_version: getJayStackVersion(),
+    contracts
+  };
+  fs.mkdirSync(outputDir, { recursive: true });
+  const indexPath = path.join(outputDir, "contracts-index.yaml");
+  fs.writeFileSync(indexPath, YAML.stringify(index), "utf-8");
+  const pluginsIndex = {
+    materialized_at: index.materialized_at,
+    jay_stack_version: index.jay_stack_version,
+    plugins: Array.from(pluginsIndexMap.entries()).map(([name, data]) => ({
+      name,
+      path: data.path,
+      contracts: data.contracts
+    }))
+  };
+  const pluginsIndexPath = path.join(outputDir, "plugins-index.yaml");
+  fs.writeFileSync(pluginsIndexPath, YAML.stringify(pluginsIndex), "utf-8");
+  if (verbose) {
+    getLogger().info(`
+✅ Contracts index written to: ${indexPath}`);
+    getLogger().info(`✅ Plugins index written to: ${pluginsIndexPath}`);
+  }
+  return {
+    index,
+    staticCount,
+    dynamicCount,
+    outputDir
+  };
+}
+async function listContracts(options) {
+  const { projectRoot, dynamicOnly = false, pluginFilter } = options;
+  const contracts = [];
+  const plugins = await scanPlugins({
+    projectRoot,
+    includeDevDeps: true
+  });
+  for (const [pluginKey, plugin] of plugins) {
+    if (pluginFilter && plugin.name !== pluginFilter && pluginKey !== pluginFilter)
+      continue;
+    const { manifest } = plugin;
+    if (!dynamicOnly && manifest.contracts) {
+      for (const contract of manifest.contracts) {
+        const contractPath = resolveStaticContractPath(
+          plugin,
+          contract.contract,
+          projectRoot
+        );
+        const relativePath = path.relative(projectRoot, contractPath);
+        contracts.push({
+          plugin: plugin.name,
+          name: contract.name,
+          type: "static",
+          path: "./" + relativePath
+        });
+      }
+    }
+    if (manifest.dynamic_contracts) {
+      const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
+      for (const config of dynamicConfigs) {
+        contracts.push({
+          plugin: plugin.name,
+          name: `${config.prefix}/*`,
+          type: "dynamic",
+          path: "(run materialization to generate)"
+        });
+      }
+    }
+  }
+  return {
+    materialized_at: (/* @__PURE__ */ new Date()).toISOString(),
+    jay_stack_version: getJayStackVersion(),
+    contracts
+  };
+}
+async function discoverPluginsWithSetup(options) {
+  const { projectRoot, verbose, pluginFilter } = options;
+  const allPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    discoverTransitive: true
+  });
+  const pluginsWithSetup = [];
+  for (const [packageName, plugin] of allPlugins) {
+    if (!plugin.manifest.setup?.handler)
+      continue;
+    if (pluginFilter && plugin.name !== pluginFilter && packageName !== pluginFilter) {
+      continue;
+    }
+    pluginsWithSetup.push({
+      name: plugin.name,
+      pluginPath: plugin.pluginPath,
+      packageName: plugin.packageName,
+      isLocal: plugin.isLocal,
+      setupHandler: plugin.manifest.setup.handler,
+      setupDescription: plugin.manifest.setup.description,
+      dependencies: plugin.dependencies
+    });
+    if (verbose) {
+      getLogger().info(`[Setup] Found plugin with setup: ${plugin.name}`);
+    }
+  }
+  return sortByDependencies(pluginsWithSetup);
+}
+async function discoverPluginsWithReferences(options) {
+  const { projectRoot, verbose, pluginFilter } = options;
+  const allPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    discoverTransitive: true
+  });
+  const pluginsWithRefs = [];
+  for (const [packageName, plugin] of allPlugins) {
+    if (!plugin.manifest.setup?.references)
+      continue;
+    if (pluginFilter && plugin.name !== pluginFilter && packageName !== pluginFilter) {
+      continue;
+    }
+    pluginsWithRefs.push({
+      name: plugin.name,
+      pluginPath: plugin.pluginPath,
+      packageName: plugin.packageName,
+      isLocal: plugin.isLocal,
+      referencesHandler: plugin.manifest.setup.references,
+      dependencies: plugin.dependencies
+    });
+    if (verbose) {
+      getLogger().info(`[AgentKit] Found plugin with references: ${plugin.name}`);
+    }
+  }
+  return sortByDependencies(pluginsWithRefs);
+}
+function sortByDependencies(plugins) {
+  return [...plugins].sort((a, b) => {
+    const aDepsOnB = a.dependencies.some((d) => d === b.name || d === b.packageName) ? 1 : 0;
+    const bDepsOnA = b.dependencies.some((d) => d === a.name || d === a.packageName) ? 1 : 0;
+    return aDepsOnB - bDepsOnA;
+  });
+}
+async function executePluginSetup(plugin, options) {
+  const { projectRoot, configDir, force, initError, viteServer, verbose } = options;
+  const context = {
+    pluginName: plugin.name,
+    projectRoot,
+    configDir,
+    services: getServiceRegistry(),
+    initError,
+    force
+  };
+  const handler = await loadHandler(plugin, plugin.setupHandler, viteServer);
+  return handler(context);
+}
+async function executePluginReferences(plugin, options) {
+  const { projectRoot, force, viteServer } = options;
+  const referencesDir = path.join(projectRoot, "agent-kit", "references", plugin.name);
+  const context = {
+    pluginName: plugin.name,
+    projectRoot,
+    referencesDir,
+    services: getServiceRegistry(),
+    force
+  };
+  const handler = await loadHandler(
+    plugin,
+    plugin.referencesHandler,
+    viteServer
+  );
+  return handler(context);
+}
+async function loadHandler(plugin, handlerName, viteServer) {
+  let module;
+  if (plugin.isLocal) {
+    const handlerPath = path.resolve(plugin.pluginPath, handlerName);
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(handlerPath);
+    } else {
+      module = await import(handlerPath);
+    }
+    if (typeof module[handlerName] === "function")
+      return module[handlerName];
+    if (typeof module.setup === "function")
+      return module.setup;
+    if (typeof module.default === "function")
+      return module.default;
+    throw new Error(
+      `Handler "${handlerName}" not found in "${plugin.pluginPath}". Available exports: ${Object.keys(module).join(", ")}`
+    );
+  } else {
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(plugin.packageName);
+    } else {
+      module = await import(plugin.packageName);
+    }
+    if (typeof module[handlerName] !== "function") {
+      throw new Error(
+        `Handler "${handlerName}" not found as export in "${plugin.packageName}". Available exports: ${Object.keys(module).join(", ")}`
+      );
+    }
+    return module[handlerName];
+  }
+}
 export {
   ActionRegistry,
   DevSlowlyChangingPhase,
@@ -1159,8 +1734,12 @@ export {
   discoverAndRegisterActions,
   discoverPluginActions,
   discoverPluginsWithInit,
+  discoverPluginsWithReferences,
+  discoverPluginsWithSetup,
   executeAction,
+  executePluginReferences,
   executePluginServerInits,
+  executePluginSetup,
   generateClientScript,
   getActionCacheHeaders,
   getClientInitData,
@@ -1168,9 +1747,12 @@ export {
   getRegisteredAction,
   getRegisteredActionNames,
   getService,
+  getServiceRegistry,
   hasAction,
   hasService,
+  listContracts,
   loadPageParts,
+  materializeContracts,
   onInit,
   onShutdown,
   preparePluginClientInits,
@@ -1178,11 +1760,12 @@ export {
   registerService,
   renderFastChangingData,
   resolveServices,
-  runAction,
   runInitCallbacks,
   runLoadParams,
   runShutdownCallbacks,
   runSlowlyChangingRender,
+  scanPlugins,
   setClientInitData,
+  slowRenderInstances,
   sortPluginsByDependencies
 };