@jay-framework/jay-stack-cli 0.24.1 → 0.24.3

package/dist/index.js

@@ -3,21 +3,26 @@ import express from "express";
 import http from "node:http";
 import { mkDevServer, createViteForCli } from "@jay-framework/dev-server";
 import getPort from "get-port";
-import path from "path";
-import fs, { promises } from "fs";
+import path$1 from "path";
+import fs$1, { promises } from "fs";
 import YAML from "yaml";
 import { getLogger, setDevLogger, createDevLogger } from "@jay-framework/logger";
-import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, parseContract, generateElementFile, generateServerElementFile, htmlElementTagNameMap, loadLinkedContract, getLinkedContractDir } from "@jay-framework/compiler-jay-html";
-import { scanPlugins, listContracts, materializeContracts, SetupNeedsAnswerError, discoverPluginsWithSetup, sortPluginsByDependencies, discoverPluginsWithInit, executePluginSetup, executePluginServerInits, runInitCallbacks } from "@jay-framework/stack-server-runtime";
-import { listContracts as listContracts2, materializeContracts as materializeContracts2 } from "@jay-framework/stack-server-runtime";
+import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, parseAction, parseContract, generateElementFile, generateServerElementFile, htmlElementTagNameMap, loadLinkedContract, getLinkedContractDir } from "@jay-framework/compiler-jay-html";
+import fs$2 from "node:fs/promises";
+import * as path from "node:path";
+import path__default from "node:path";
+import { createRequire } from "module";
+import jsBeautify from "js-beautify";
+import { scanPlugins, sortPluginsByDependencies, getServiceRegistry, actionRegistry, resolveServices, ActionRegistry, discoverPluginsWithInit, executePluginServerInits, runInitCallbacks, registerService } from "@jay-framework/stack-server-runtime";
+import "node:crypto";
+import * as fs from "node:fs";
+import fs__default from "node:fs";
+import { createRequire as createRequire$1 } from "node:module";
+import { isJayAction, isJayStreamAction, isJayCliCommand, CONSOLE_CONTEXT } from "@jay-framework/fullstack-component";
 import { Command } from "commander";
 import chalk from "chalk";
-import path$1 from "node:path";
-import fs$1 from "node:fs/promises";
-import { loadPluginManifest, JAY_EXTENSION, RuntimeMode, GenerateTarget, JAY_CONTRACT_EXTENSION, findDynamicContract } from "@jay-framework/compiler-shared";
-import { createRequire } from "module";
+import { loadPluginManifest as loadPluginManifest$1, normalizeActionEntry as normalizeActionEntry$1, JAY_EXTENSION, RuntimeMode as RuntimeMode$1, GenerateTarget, JAY_CONTRACT_EXTENSION, findDynamicContract } from "@jay-framework/compiler-shared";
 import { glob } from "glob";
-import fsSync from "node:fs";
 import { fileURLToPath } from "node:url";
 import { select, confirm, input } from "@inquirer/prompts";
 const DEFAULT_CONFIG = {
@@ -29,13 +34,13 @@ const DEFAULT_CONFIG = {
     configBase: "./config"
   }
 };
-function loadConfig() {
-  const configPath = path.resolve(".jay");
-  if (!fs.existsSync(configPath)) {
+function loadConfig(projectRoot) {
+  const configPath = projectRoot ? path$1.resolve(projectRoot, ".jay") : path$1.resolve(".jay");
+  if (!fs$1.existsSync(configPath)) {
     return DEFAULT_CONFIG;
   }
   try {
-    const configContent = fs.readFileSync(configPath, "utf-8");
+    const configContent = fs$1.readFileSync(configPath, "utf-8");
     const userConfig = YAML.parse(configContent);
     return {
       devServer: {
@@ -62,7 +67,7 @@ function getConfigWithDefaults(config) {
   };
 }
 function updateConfig(updates) {
-  const configPath = path.resolve(".jay");
+  const configPath = path$1.resolve(".jay");
   try {
     const existingConfig = loadConfig();
     const updatedConfig = {
@@ -78,7 +83,7 @@ function updateConfig(updates) {
       }
     };
     const yamlContent = YAML.stringify(updatedConfig, { indent: 2 });
-    fs.writeFileSync(configPath, yamlContent);
+    fs$1.writeFileSync(configPath, yamlContent);
   } catch (error) {
     getLogger().warn(`Failed to update .jay config file: ${error}`);
   }
@@ -86,14 +91,14 @@ function updateConfig(updates) {
 async function generatePageDefinitionFiles(routes, tsConfigPath, projectRoot) {
   for (const route of routes) {
     const jayHtmlPath = route.fsRoute.jayHtmlPath;
-    if (!fs.existsSync(jayHtmlPath)) {
+    if (!fs$1.existsSync(jayHtmlPath)) {
       continue;
     }
     const definitionFilePath = jayHtmlPath + ".d.ts";
     try {
       const [sourceStats, defStats] = await Promise.all([
-        fs.promises.stat(jayHtmlPath),
-        fs.promises.stat(definitionFilePath).catch(() => null)
+        fs$1.promises.stat(jayHtmlPath),
+        fs$1.promises.stat(definitionFilePath).catch(() => null)
       ]);
       if (defStats && defStats.mtime >= sourceStats.mtime) {
         continue;
@@ -101,9 +106,9 @@ async function generatePageDefinitionFiles(routes, tsConfigPath, projectRoot) {
     } catch (error) {
     }
     try {
-      const jayHtml = await fs.promises.readFile(jayHtmlPath, "utf-8");
-      const filename = path.basename(jayHtmlPath);
-      const dirname = path.dirname(jayHtmlPath);
+      const jayHtml = await fs$1.promises.readFile(jayHtmlPath, "utf-8");
+      const filename = path$1.basename(jayHtmlPath);
+      const dirname = path$1.dirname(jayHtmlPath);
       const parsedJayHtml = await parseJayFile(
         jayHtml,
         filename,
@@ -119,7 +124,7 @@ async function generatePageDefinitionFiles(routes, tsConfigPath, projectRoot) {
         );
       } else {
         const definitionFilePath2 = jayHtmlPath + ".d.ts";
-        await fs.promises.writeFile(definitionFilePath2, definitionFile.val, "utf-8");
+        await fs$1.promises.writeFile(definitionFilePath2, definitionFile.val, "utf-8");
         getLogger().info(`📦 Generated definition file: ${definitionFilePath2}`);
       }
     } catch (error) {
@@ -143,7 +148,7 @@ async function startDevServer(options = {}) {
   const devServerPort = await getPort({ port: resolvedConfig.devServer.portRange });
   const log = getLogger();
   const { server, viteServer, routes, service } = await mkDevServer({
-    pagesRootFolder: path.resolve(resolvedConfig.devServer.pagesBase),
+    pagesRootFolder: path$1.resolve(resolvedConfig.devServer.pagesBase),
     projectRootFolder: process.cwd(),
     publicBaseUrlPath: "/",
     jayRollupConfig: jayOptions,
@@ -151,15 +156,15 @@ async function startDevServer(options = {}) {
     httpServer
   });
   app.use(server);
-  const publicPath = path.resolve(resolvedConfig.devServer.publicFolder);
-  if (!fs.existsSync(path.join(publicPath, "sitemap.xml"))) {
+  const publicPath = path$1.resolve(resolvedConfig.devServer.publicFolder);
+  if (!fs$1.existsSync(path$1.join(publicPath, "sitemap.xml"))) {
     app.get("/sitemap.xml", (_req, res) => {
       res.type("application/xml").send(
         '<?xml version="1.0" encoding="UTF-8"?>\n<!-- Sitemap is generated by the production server from the route manifest. -->\n<!-- Run jay-stack build && jay-stack serve to see the full sitemap. -->\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" />\n'
       );
     });
   }
-  if (fs.existsSync(publicPath)) {
+  if (fs$1.existsSync(publicPath)) {
     app.use(express.static(publicPath));
   } else {
     log.important(`⚠️  Public folder not found: ${resolvedConfig.devServer.publicFolder}`);
@@ -177,7 +182,7 @@ async function startDevServer(options = {}) {
     log.important(`🚀 Jay Stack dev server started successfully!`);
     log.important(`📱 Dev Server: http://localhost:${devServerPort}`);
     log.important(`📁 Pages directory: ${resolvedConfig.devServer.pagesBase}`);
-    if (fs.existsSync(publicPath)) {
+    if (fs$1.existsSync(publicPath)) {
       log.important(`📁 Public folder: ${resolvedConfig.devServer.publicFolder}`);
     }
     if (options.testMode) {
@@ -222,12 +227,1326 @@ async function startDevServer(options = {}) {
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
+createRequire(import.meta.url);
+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) => __defNormalProp2(obj, key + "", value);
+class JayAtomicType {
+  constructor(name) {
+    __publicField2(this, "kind", 0);
+    this.name = name;
+  }
+}
+new JayAtomicType("string");
+new JayAtomicType("string");
+new JayAtomicType("number");
+new JayAtomicType("boolean");
+new JayAtomicType("Date");
+new JayAtomicType("file");
+new JayAtomicType("Unknown");
+class JayObjectType {
+  constructor(name, props) {
+    __publicField2(this, "kind", 8);
+    this.name = name;
+    this.props = props;
+  }
+}
+new JayObjectType("Error", {
+  message: new JayAtomicType("string"),
+  name: new JayAtomicType("string"),
+  stack: new JayAtomicType("string")
+});
+function isOptionalType(aType) {
+  return aType.kind === 14;
+}
+function isAtomicType(aType) {
+  return aType.kind === 0;
+}
+function isEnumType(aType) {
+  return aType.kind === 2;
+}
+function isImportedType(aType) {
+  return aType.kind === 4;
+}
+function isObjectType(aType) {
+  return aType.kind === 8;
+}
+function isArrayType(aType) {
+  return aType.kind === 9;
+}
+function isRecordType(aType) {
+  return aType.kind === 11;
+}
+function jayTypeToJsonSchema(type) {
+  if (isOptionalType(type)) {
+    return jayTypeToJsonSchema(type.innerType);
+  }
+  if (isAtomicType(type)) {
+    const name = type.name.toLowerCase();
+    if (name === "string" || name === "number" || name === "boolean") {
+      return { type: name };
+    }
+    if (name === "file") {
+      return { type: "string", description: "Binary file upload (JayFile)" };
+    }
+    return { type: "string" };
+  }
+  if (isEnumType(type)) {
+    return { type: "string", enum: type.values };
+  }
+  if (isImportedType(type)) {
+    return { type: "object", description: `Contract: ${type.name}` };
+  }
+  if (isArrayType(type)) {
+    const itemSchema = jayTypeToJsonSchema(type.itemType);
+    if (itemSchema) {
+      return { type: "array", items: itemSchema };
+    }
+    return { type: "array" };
+  }
+  if (isRecordType(type)) {
+    const valueSchema = jayTypeToJsonSchema(type.itemType);
+    if (valueSchema) {
+      return { type: "object", additionalProperties: valueSchema };
+    }
+    return { type: "object" };
+  }
+  if (isObjectType(type)) {
+    const properties = {};
+    const required = [];
+    for (const [key, propType] of Object.entries(type.props)) {
+      const isOpt = isOptionalType(propType);
+      const schema = jayTypeToJsonSchema(propType);
+      if (schema) {
+        properties[key] = schema;
+        if (!isOpt) {
+          required.push(key);
+        }
+      }
+    }
+    return {
+      type: "object",
+      properties,
+      ...required.length > 0 && { required }
+    };
+  }
+  return null;
+}
+var RuntimeMode = /* @__PURE__ */ ((RuntimeMode2) => {
+  RuntimeMode2["MainTrusted"] = "mainTrusted";
+  RuntimeMode2["MainSandbox"] = "mainSandbox";
+  RuntimeMode2["WorkerTrusted"] = "workerTrusted";
+  RuntimeMode2["WorkerSandbox"] = "workerSandbox";
+  return RuntimeMode2;
+})(RuntimeMode || {});
+const TS_EXTENSION = ".ts";
+const JAY_QUERY_PREFIX = "?jay-";
+const JAY_QUERY_HYDRATE = `${JAY_QUERY_PREFIX}hydrate`;
+[
+  // Hydrate target
+  {
+    pattern: JAY_QUERY_HYDRATE,
+    buildEnv: "client",
+    isHydrate: true
+  },
+  // Build environments
+  {
+    pattern: `${JAY_QUERY_PREFIX}${"client"}`,
+    buildEnv: "client"
+    /* Client */
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${"server"}`,
+    buildEnv: "server"
+    /* Server */
+  },
+  // Runtime modes (with .ts suffix)
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.MainSandbox}${TS_EXTENSION}`,
+    runtimeMode: RuntimeMode.MainSandbox
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerTrusted}${TS_EXTENSION}`,
+    runtimeMode: RuntimeMode.WorkerTrusted
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerSandbox}${TS_EXTENSION}`,
+    runtimeMode: RuntimeMode.WorkerSandbox
+  },
+  // Runtime modes (without .ts suffix)
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.MainSandbox}`,
+    runtimeMode: RuntimeMode.MainSandbox
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerTrusted}`,
+    runtimeMode: RuntimeMode.WorkerTrusted
+  },
+  {
+    pattern: `${JAY_QUERY_PREFIX}${RuntimeMode.WorkerSandbox}`,
+    runtimeMode: RuntimeMode.WorkerSandbox
+  }
+];
+const { html: htmlBeautify } = jsBeautify;
+createRequire(import.meta.url);
+function normalizeActionEntry(entry) {
+  if (typeof entry === "string") {
+    return { name: entry };
+  }
+  return { name: entry.name, action: entry.action, devOnly: entry.devOnly };
+}
+function loadPluginManifest(pluginDir) {
+  const pluginYamlPath = path$1.join(pluginDir, "plugin.yaml");
+  if (!fs$1.existsSync(pluginYamlPath)) {
+    return null;
+  }
+  try {
+    const yamlContent = fs$1.readFileSync(pluginYamlPath, "utf-8");
+    return YAML.parse(yamlContent);
+  } catch (error) {
+    return null;
+  }
+}
+const s$1 = createRequire(import.meta.url), e$1 = s$1("typescript");
+new Proxy(e$1, {
+  get(t, r) {
+    return t[r];
+  }
+});
+function parseActionMetadata(yamlContent, fileName) {
+  try {
+    const parsed = parseAction(yamlContent, fileName);
+    if (parsed.validations.length > 0) {
+      getLogger().warn(
+        `[ActionMetadata] ${fileName}: validation errors: ${parsed.validations.join(", ")}`
+      );
+      return null;
+    }
+    if (!parsed.val) {
+      getLogger().warn(`[ActionMetadata] ${fileName}: parsing returned no result`);
+      return null;
+    }
+    const action = parsed.val;
+    const inputJsonSchema = jayTypeToJsonSchema(action.inputType);
+    let inputSchema;
+    if (inputJsonSchema && inputJsonSchema.type === "object") {
+      inputSchema = {
+        type: "object",
+        properties: inputJsonSchema.properties || {},
+        ...inputJsonSchema.required && inputJsonSchema.required.length > 0 && { required: inputJsonSchema.required }
+      };
+    } else {
+      inputSchema = { type: "object", properties: {} };
+    }
+    const metadata = {
+      name: action.name,
+      description: action.description,
+      inputSchema
+    };
+    if (action.outputType) {
+      const outputJsonSchema = jayTypeToJsonSchema(action.outputType);
+      if (outputJsonSchema) {
+        metadata.outputSchema = outputJsonSchema;
+      }
+    }
+    return metadata;
+  } catch (error) {
+    getLogger().error(
+      `[ActionMetadata] Failed to parse ${fileName}: ${error instanceof Error ? error.message : error}`
+    );
+    return null;
+  }
+}
+function loadActionMetadata(filePath) {
+  if (!fs.existsSync(filePath)) {
+    getLogger().warn(`[ActionMetadata] File not found: ${filePath}`);
+    return null;
+  }
+  const yamlContent = fs.readFileSync(filePath, "utf-8");
+  const fileName = path.basename(filePath);
+  return parseActionMetadata(yamlContent, fileName);
+}
+function resolveActionMetadataPath(actionPath, pluginDir) {
+  return path.resolve(pluginDir, actionPath);
+}
+const require$2 = createRequire$1(import.meta.url);
+async function discoverAndRegisterActions(options) {
+  const {
+    projectRoot,
+    actionsDir = "src/actions",
+    registry = actionRegistry,
+    verbose = false,
+    viteServer
+  } = options;
+  const result = {
+    actionCount: 0,
+    actionNames: [],
+    scannedFiles: []
+  };
+  const actionsPath = path.resolve(projectRoot, actionsDir);
+  if (!fs.existsSync(actionsPath)) {
+    if (verbose) {
+      getLogger().info(`[Actions] No actions directory found at ${actionsPath}`);
+    }
+    return result;
+  }
+  const actionFiles = await findActionFiles(actionsPath);
+  if (verbose) {
+    getLogger().info(`[Actions] Found ${actionFiles.length} action file(s)`);
+  }
+  for (const filePath of actionFiles) {
+    result.scannedFiles.push(filePath);
+    try {
+      let module;
+      if (viteServer) {
+        module = await viteServer.ssrLoadModule(filePath);
+      } else {
+        module = await import(filePath);
+      }
+      for (const [exportName, exportValue] of Object.entries(module)) {
+        if (isJayAction(exportValue)) {
+          registry.register(exportValue);
+          result.actionNames.push(exportValue.actionName);
+          result.actionCount++;
+          if (verbose) {
+            getLogger().info(
+              `[Actions] Registered: ${exportValue.actionName}`
+            );
+          }
+        } else if (isJayStreamAction(exportValue)) {
+          registry.registerStream(exportValue);
+          result.actionNames.push(exportValue.actionName);
+          result.actionCount++;
+          if (verbose) {
+            getLogger().info(
+              `[Actions] Registered stream: ${exportValue.actionName}`
+            );
+          }
+        }
+      }
+    } catch (error) {
+      getLogger().error(`[Actions] Failed to import ${filePath}: ${error}`);
+    }
+  }
+  return result;
+}
+async function findActionFiles(dir) {
+  const files = [];
+  const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const subFiles = await findActionFiles(fullPath);
+      files.push(...subFiles);
+    } else if (entry.isFile() && entry.name.endsWith(".actions.ts")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+async function discoverAllPluginActions(options) {
+  const { projectRoot, registry = actionRegistry, verbose = false, viteServer } = options;
+  const allActions = [];
+  const localPluginsPath = path.join(projectRoot, "src/plugins");
+  if (fs.existsSync(localPluginsPath)) {
+    const pluginDirs = await fs.promises.readdir(localPluginsPath, { withFileTypes: true });
+    for (const entry of pluginDirs) {
+      if (entry.isDirectory()) {
+        const pluginPath = path.join(localPluginsPath, entry.name);
+        const actions = await discoverPluginActions(
+          pluginPath,
+          projectRoot,
+          registry,
+          verbose,
+          viteServer
+        );
+        allActions.push(...actions);
+      }
+    }
+  }
+  const npmActions = await discoverNpmPluginActions(projectRoot, registry, verbose, viteServer);
+  allActions.push(...npmActions);
+  return allActions;
+}
+async function discoverNpmPluginActions(projectRoot, registry, verbose, viteServer) {
+  const allActions = [];
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return allActions;
+  }
+  try {
+    const packageJson = JSON.parse(await fs.promises.readFile(packageJsonPath, "utf-8"));
+    const dependencies = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies
+    };
+    for (const packageName of Object.keys(dependencies)) {
+      try {
+        const pluginYamlPath = tryResolvePluginYaml(packageName, projectRoot);
+        if (!pluginYamlPath) {
+          continue;
+        }
+        const pluginDir = path.dirname(pluginYamlPath);
+        const pluginConfig = loadPluginManifest(pluginDir);
+        if (!pluginConfig || !pluginConfig.actions || !Array.isArray(pluginConfig.actions)) {
+          continue;
+        }
+        if (verbose) {
+          getLogger().info(
+            `[Actions] NPM plugin "${packageName}" declares actions: ${JSON.stringify(pluginConfig.actions)}`
+          );
+        }
+        const actions = await registerNpmPluginActions(
+          packageName,
+          pluginConfig,
+          pluginDir,
+          registry,
+          verbose,
+          viteServer
+        );
+        allActions.push(...actions);
+      } catch {
+        continue;
+      }
+    }
+  } catch (error) {
+    getLogger().error(`[Actions] Failed to read project package.json: ${error}`);
+  }
+  return allActions;
+}
+function tryResolvePluginYaml(packageName, projectRoot) {
+  try {
+    return require$2.resolve(`${packageName}/plugin.yaml`, {
+      paths: [projectRoot]
+    });
+  } catch {
+    return null;
+  }
+}
+function resolveNpmActionMetadataPath(actionPath, packageName, pluginDir) {
+  if (!actionPath.startsWith(".")) {
+    try {
+      return require$2.resolve(`${packageName}/${actionPath}`, {
+        paths: [pluginDir]
+      });
+    } catch {
+    }
+  }
+  const resolved = resolveActionMetadataPath(actionPath, pluginDir);
+  if (fs.existsSync(resolved)) {
+    return resolved;
+  }
+  getLogger().warn(
+    `[Actions] Could not resolve .jay-action file "${actionPath}" for package "${packageName}"`
+  );
+  return null;
+}
+async function registerNpmPluginActions(packageName, pluginConfig, pluginDir, registry, verbose, viteServer) {
+  const registeredActions = [];
+  try {
+    let pluginModule;
+    if (viteServer) {
+      pluginModule = await viteServer.ssrLoadModule(packageName);
+    } else {
+      pluginModule = await import(packageName);
+    }
+    let toolsModule;
+    const loadToolsModule = async () => {
+      if (!toolsModule) {
+        const toolsEntry = `${packageName}/tools`;
+        toolsModule = viteServer ? await viteServer.ssrLoadModule(toolsEntry) : await import(toolsEntry);
+      }
+      return toolsModule;
+    };
+    for (const entry of pluginConfig.actions) {
+      const { name: actionName, action: actionPath, devOnly } = normalizeActionEntry(entry);
+      const sourceModule = devOnly ? await loadToolsModule() : pluginModule;
+      const actionExport = sourceModule[actionName];
+      if (actionExport && isJayAction(actionExport)) {
+        registry.register(actionExport);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (actionPath) {
+          const metadataFilePath = resolveNpmActionMetadataPath(
+            actionPath,
+            packageName,
+            pluginDir
+          );
+          if (metadataFilePath) {
+            const metadata = loadActionMetadata(metadataFilePath);
+            if (metadata) {
+              registry.setMetadata(registeredName, metadata);
+              if (verbose) {
+                getLogger().info(
+                  `[Actions] Loaded metadata for "${registeredName}" from ${actionPath}`
+                );
+              }
+            }
+          }
+        }
+        if (verbose) {
+          getLogger().info(`[Actions] Registered NPM plugin action: ${registeredName}`);
+        }
+      } else if (actionExport && isJayStreamAction(actionExport)) {
+        registry.registerStream(actionExport);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (verbose) {
+          getLogger().info(`[Actions] Registered NPM plugin stream: ${registeredName}`);
+        }
+      } else {
+        getLogger().warn(
+          `[Actions] NPM plugin "${packageName}" declares action "${actionName}" but it's not exported or not a JayAction`
+        );
+      }
+    }
+  } catch (importError) {
+    getLogger().error(`[Actions] Failed to import NPM plugin "${packageName}": ${importError}`);
+  }
+  return registeredActions;
+}
+async function discoverPluginActions(pluginPath, projectRoot, registry = actionRegistry, verbose = false, viteServer) {
+  const pluginConfig = loadPluginManifest(pluginPath);
+  if (!pluginConfig) {
+    return [];
+  }
+  if (!pluginConfig.actions || !Array.isArray(pluginConfig.actions)) {
+    return [];
+  }
+  const registeredActions = [];
+  const pluginName = pluginConfig.name || path.basename(pluginPath);
+  if (verbose) {
+    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)) {
+    const tsPath = modulePath + ".ts";
+    const jsPath = modulePath + ".js";
+    if (fs.existsSync(tsPath)) {
+      modulePath = tsPath;
+    } else if (fs.existsSync(jsPath)) {
+      modulePath = jsPath;
+    } else {
+      getLogger().warn(`[Actions] Plugin "${pluginName}" module not found at ${modulePath}`);
+      return [];
+    }
+  }
+  const resolveLocalToolsModulePath = () => {
+    for (const candidate of ["tools.ts", "tools.js"]) {
+      const candidatePath = path.join(pluginPath, candidate);
+      if (fs.existsSync(candidatePath)) return candidatePath;
+    }
+    return null;
+  };
+  try {
+    let pluginModule;
+    if (viteServer) {
+      pluginModule = await viteServer.ssrLoadModule(modulePath);
+    } else {
+      pluginModule = await import(modulePath);
+    }
+    let toolsModule;
+    const loadToolsModule = async () => {
+      if (toolsModule) return toolsModule;
+      const toolsPath = resolveLocalToolsModulePath();
+      if (!toolsPath) {
+        getLogger().warn(
+          `[Actions] Plugin "${pluginName}" declares a devOnly action but has no tools.ts/tools.js module`
+        );
+        return void 0;
+      }
+      toolsModule = viteServer ? await viteServer.ssrLoadModule(toolsPath) : await import(toolsPath);
+      return toolsModule;
+    };
+    for (const entry of pluginConfig.actions) {
+      const { name: actionName, action: actionPath, devOnly } = normalizeActionEntry(entry);
+      const sourceModule = devOnly ? await loadToolsModule() : pluginModule;
+      const actionExport = sourceModule?.[actionName];
+      if (actionExport && isJayAction(actionExport)) {
+        registry.register(actionExport);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (actionPath) {
+          const metadataFilePath = resolveActionMetadataPath(actionPath, pluginPath);
+          const metadata = loadActionMetadata(metadataFilePath);
+          if (metadata) {
+            registry.setMetadata(registeredName, metadata);
+            if (verbose) {
+              getLogger().info(
+                `[Actions] Loaded metadata for "${registeredName}" from ${actionPath}`
+              );
+            }
+          }
+        }
+        if (verbose) {
+          getLogger().info(`[Actions] Registered plugin action: ${registeredName}`);
+        }
+      } else if (actionExport && isJayStreamAction(actionExport)) {
+        registry.registerStream(actionExport);
+        const registeredName = actionExport.actionName;
+        registeredActions.push(registeredName);
+        if (verbose) {
+          getLogger().info(`[Actions] Registered plugin stream: ${registeredName}`);
+        }
+      } else {
+        getLogger().warn(
+          `[Actions] Plugin "${pluginName}" declares action "${actionName}" but it's not exported or not a JayAction`
+        );
+      }
+    }
+  } catch (importError) {
+    getLogger().error(
+      `[Actions] Failed to import plugin module at ${modulePath}: ${importError}`
+    );
+  }
+  return registeredActions;
+}
+const require$1 = 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 = require$1.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...`);
+  }
+  return await generator.generate(...resolvedServices);
+}
+function resolveStaticContractPath(plugin, contractSpec, projectRoot) {
+  const { pluginPath, isLocal, packageName } = plugin;
+  if (!isLocal) {
+    try {
+      return require$1.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 resolveActionFilePath(actionPath, packageName, pluginPath, isLocal, projectRoot) {
+  if (!isLocal && !actionPath.startsWith(".")) {
+    try {
+      return require$1.resolve(`${packageName}/${actionPath}`, {
+        paths: [projectRoot]
+      });
+    } catch {
+      const possiblePaths = [
+        path.join(pluginPath, "dist", actionPath),
+        path.join(pluginPath, "lib", actionPath),
+        path.join(pluginPath, actionPath)
+      ];
+      const found = possiblePaths.find((p) => fs.existsSync(p));
+      return found || null;
+    }
+  }
+  const resolved = resolveActionMetadataPath(actionPath, pluginPath);
+  return fs.existsSync(resolved) ? resolved : null;
+}
+function toKebabCase(str) {
+  return str.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
+}
+async function materializeContracts(options, services = /* @__PURE__ */ new Map()) {
+  const {
+    projectRoot,
+    outputDir = path.join(projectRoot, "agent-kit", "materialized-contracts"),
+    dynamicOnly = false,
+    pluginFilter,
+    verbose = false,
+    viteServer
+  } = options;
+  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;
+    const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+    if (!pluginsIndexMap.has(plugin.name)) {
+      const entry = {
+        path: "./" + pluginRelPath.replace(/\\/g, "/"),
+        contracts: [],
+        actions: []
+      };
+      if (manifest.services?.length) {
+        entry.services = manifest.services.map((s2) => {
+          const docPath = s2.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, s2.doc)) : void 0;
+          return {
+            name: s2.name,
+            marker: s2.marker,
+            ...s2.description && { description: s2.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      if (manifest.contexts?.length) {
+        entry.contexts = manifest.contexts.map((c) => {
+          const docPath = c.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, c.doc)) : void 0;
+          return {
+            name: c.name,
+            marker: c.marker,
+            ...c.description && { description: c.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      if (manifest.routes?.length) {
+        entry.routes = manifest.routes.map((r) => ({
+          path: r.path,
+          ...r.description && { description: r.description }
+        }));
+      }
+      if (manifest.commands?.length) {
+        entry.commands = manifest.commands.map((c) => {
+          let description;
+          if (c.command) {
+            try {
+              const cmdPath = path.resolve(plugin.pluginPath, c.command);
+              const cmdContent = fs.readFileSync(cmdPath, "utf-8");
+              const parsed = YAML.parse(cmdContent);
+              description = parsed?.description;
+            } catch {
+            }
+          }
+          return {
+            name: c.name,
+            ...description && { description }
+          };
+        });
+      }
+      pluginsIndexMap.set(plugin.name, entry);
+    }
+    if (!dynamicOnly && manifest.contracts) {
+      for (const contract of manifest.contracts) {
+        const contractPath = resolveStaticContractPath(
+          plugin,
+          contract.contract,
+          projectRoot
+        );
+        const relativePath = path.relative(projectRoot, contractPath);
+        let description = contract.description;
+        if (!description) {
+          try {
+            const contractContent = fs.readFileSync(contractPath, "utf-8");
+            const parsed = YAML.parse(contractContent);
+            if (parsed?.description && typeof parsed.description === "string") {
+              description = parsed.description;
+            }
+          } catch {
+          }
+        }
+        pluginsIndexMap.get(plugin.name).contracts.push({
+          name: contract.name,
+          ...description && { description },
+          type: "static",
+          path: "./" + relativePath
+        });
+        staticCount++;
+        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;
+          if (generatedContracts.length > 1) {
+            const missing = generatedContracts.filter((c) => !c.name);
+            if (missing.length > 0) {
+              getLogger().error(
+                `   ❌ Dynamic contract generator for "${prefix}" returned ${generatedContracts.length} contracts but ${missing.length} are missing a name. Names are required when a generator returns multiple contracts.`
+              );
+              continue;
+            }
+          }
+          for (const generated of generatedContracts) {
+            const kebabName = generated.name ? toKebabCase(generated.name) : null;
+            const fullName = kebabName ? `${prefix}/${kebabName}` : prefix;
+            const fileName = kebabName ? `${prefix}-${kebabName}.jay-contract` : `${prefix}.jay-contract`;
+            const filePath = path.join(pluginOutputDir, fileName);
+            fs.writeFileSync(filePath, generated.yaml, "utf-8");
+            const relativePath = path.relative(projectRoot, filePath);
+            let dynDescription;
+            try {
+              const parsedYaml = YAML.parse(generated.yaml);
+              if (parsedYaml?.description && typeof parsedYaml.description === "string") {
+                dynDescription = parsedYaml.description;
+              }
+            } catch {
+            }
+            const contractEntry = {
+              name: fullName,
+              ...dynDescription && { description: dynDescription },
+              type: "dynamic",
+              path: "./" + relativePath,
+              ...generated.metadata && { metadata: generated.metadata }
+            };
+            pluginsIndexMap.get(plugin.name).contracts.push(contractEntry);
+            dynamicCount++;
+            if (verbose) {
+              getLogger().info(`   ⚡ Materialized: ${fullName}`);
+            }
+          }
+        } catch (error) {
+          getLogger().error(
+            `   ❌ Failed to materialize dynamic contracts for ${plugin.name} (${config.prefix}): ${error}`
+          );
+        }
+      }
+    }
+    if (manifest.actions && Array.isArray(manifest.actions)) {
+      for (const entry of manifest.actions) {
+        const { name: actionName, action: actionPath } = normalizeActionEntry(entry);
+        if (!actionPath) continue;
+        const metadataFilePath = resolveActionFilePath(
+          actionPath,
+          plugin.packageName,
+          plugin.pluginPath,
+          plugin.isLocal,
+          projectRoot
+        );
+        if (!metadataFilePath) continue;
+        const metadata = loadActionMetadata(metadataFilePath);
+        if (!metadata) continue;
+        const actionRelPath = path.relative(projectRoot, metadataFilePath);
+        const pluginEntry = pluginsIndexMap.get(plugin.name);
+        if (!pluginEntry.actions) pluginEntry.actions = [];
+        pluginEntry.actions.push({
+          name: metadata.name,
+          description: metadata.description,
+          path: "./" + actionRelPath.replace(/\\/g, "/")
+        });
+        if (verbose) {
+          getLogger().info(`   🔧 Action: ${metadata.name} (${actionPath})`);
+        }
+      }
+    }
+  }
+  const pluginsIndex = {
+    plugins: Array.from(pluginsIndexMap.entries()).map(([name, data]) => ({
+      name,
+      path: data.path,
+      contracts: data.contracts,
+      ...data.actions && data.actions.length > 0 && { actions: data.actions },
+      ...data.services?.length && { services: data.services },
+      ...data.contexts?.length && { contexts: data.contexts },
+      ...data.routes?.length && { routes: data.routes },
+      ...data.commands?.length && { commands: data.commands }
+    }))
+  };
+  fs.mkdirSync(outputDir, { recursive: true });
+  const agentKitDir = path.dirname(outputDir);
+  const pluginsIndexPath = path.join(agentKitDir, "plugins-index.yaml");
+  fs.writeFileSync(pluginsIndexPath, YAML.stringify(pluginsIndex), "utf-8");
+  if (verbose) {
+    getLogger().info(`
+✅ Plugins index written to: ${pluginsIndexPath}`);
+  }
+  return {
+    pluginsIndex,
+    staticCount,
+    dynamicCount,
+    outputDir
+  };
+}
+async function listContracts(options) {
+  const { projectRoot, dynamicOnly = false, pluginFilter } = options;
+  const pluginsMap = /* @__PURE__ */ new Map();
+  const plugins = await scanPlugins({
+    projectRoot,
+    includeDevDeps: true
+  });
+  for (const [pluginKey, plugin] of plugins) {
+    if (pluginFilter && plugin.name !== pluginFilter && pluginKey !== pluginFilter) continue;
+    const { manifest } = plugin;
+    const pluginRelPath = path.relative(projectRoot, plugin.pluginPath);
+    if (!pluginsMap.has(plugin.name)) {
+      const entry = {
+        path: "./" + pluginRelPath.replace(/\\/g, "/"),
+        contracts: []
+      };
+      if (manifest.services?.length) {
+        entry.services = manifest.services.map((s2) => {
+          const docPath = s2.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, s2.doc)) : void 0;
+          return {
+            name: s2.name,
+            marker: s2.marker,
+            ...s2.description && { description: s2.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      if (manifest.contexts?.length) {
+        entry.contexts = manifest.contexts.map((c) => {
+          const docPath = c.doc ? "./" + path.relative(projectRoot, path.resolve(plugin.pluginPath, c.doc)) : void 0;
+          return {
+            name: c.name,
+            marker: c.marker,
+            ...c.description && { description: c.description },
+            ...docPath && { doc: docPath }
+          };
+        });
+      }
+      if (manifest.routes?.length) {
+        entry.routes = manifest.routes.map((r) => ({
+          path: r.path,
+          ...r.description && { description: r.description }
+        }));
+      }
+      if (manifest.commands?.length) {
+        entry.commands = manifest.commands.map((c) => {
+          let description;
+          if (c.command) {
+            try {
+              const cmdPath = path.resolve(plugin.pluginPath, c.command);
+              const cmdContent = fs.readFileSync(cmdPath, "utf-8");
+              const parsed = YAML.parse(cmdContent);
+              description = parsed?.description;
+            } catch {
+            }
+          }
+          return {
+            name: c.name,
+            ...description && { description }
+          };
+        });
+      }
+      pluginsMap.set(plugin.name, entry);
+    }
+    if (!dynamicOnly && manifest.contracts) {
+      for (const contract of manifest.contracts) {
+        const contractPath = resolveStaticContractPath(
+          plugin,
+          contract.contract,
+          projectRoot
+        );
+        const relativePath = path.relative(projectRoot, contractPath);
+        let listDescription = contract.description;
+        if (!listDescription) {
+          try {
+            const contractContent = fs.readFileSync(contractPath, "utf-8");
+            const parsed = YAML.parse(contractContent);
+            if (parsed?.description && typeof parsed.description === "string") {
+              listDescription = parsed.description;
+            }
+          } catch {
+          }
+        }
+        pluginsMap.get(plugin.name).contracts.push({
+          name: contract.name,
+          ...listDescription && { description: listDescription },
+          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) {
+        pluginsMap.get(plugin.name).contracts.push({
+          name: `${config.prefix}/*`,
+          type: "dynamic",
+          path: "(run materialization to generate)"
+        });
+      }
+    }
+  }
+  return {
+    plugins: Array.from(pluginsMap.entries()).map(([name, data]) => ({
+      name,
+      path: data.path,
+      contracts: data.contracts,
+      ...data.services?.length && { services: data.services },
+      ...data.contexts?.length && { contexts: data.contexts },
+      ...data.routes?.length && { routes: data.routes },
+      ...data.commands?.length && { commands: data.commands }
+    }))
+  };
+}
+async function discoverPluginCommands(options) {
+  const { projectRoot, verbose, pluginFilter } = options;
+  const allPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    discoverTransitive: true,
+    includeDevDeps: true
+  });
+  const commands = [];
+  for (const [packageName, plugin] of allPlugins) {
+    if (!plugin.manifest.commands || plugin.manifest.commands.length === 0) continue;
+    if (pluginFilter && plugin.name !== pluginFilter && packageName !== pluginFilter) {
+      continue;
+    }
+    for (const cmd of plugin.manifest.commands) {
+      let metadata;
+      let metadataPath;
+      if (cmd.command) {
+        metadataPath = path.resolve(plugin.pluginPath, cmd.command);
+        metadata = loadCommandMetadata(metadataPath);
+      }
+      commands.push({
+        pluginName: plugin.name,
+        pluginPath: plugin.pluginPath,
+        packageName: plugin.packageName,
+        isLocal: plugin.isLocal,
+        commandName: cmd.name,
+        handlerExport: cmd.name,
+        pluginModule: plugin.manifest.module,
+        metadata,
+        metadataPath
+      });
+      if (verbose) {
+        getLogger().info(`[Commands] Found ${plugin.name}/${cmd.name}`);
+      }
+    }
+  }
+  return commands;
+}
+function loadCommandMetadata(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return YAML.parse(content);
+  } catch {
+    return void 0;
+  }
+}
+function commandSchemaToFlags(inputSchema) {
+  const flags = [];
+  for (const [field, type] of Object.entries(inputSchema)) {
+    const isOptional = field.endsWith("?");
+    const cleanName = isOptional ? field.slice(0, -1) : field;
+    const kebabName = camelToKebab(cleanName);
+    const cleanType = type.toLowerCase().trim();
+    const isBoolean = cleanType === "boolean";
+    flags.push({
+      flag: isBoolean ? `--${kebabName}` : `--${kebabName} <value>`,
+      description: "",
+      required: !isOptional,
+      type: cleanType === "number" ? "number" : isBoolean ? "boolean" : "string"
+    });
+  }
+  return flags;
+}
+function camelToKebab(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function parseInputFromFlags(rawOptions, schema) {
+  const input2 = {};
+  for (const [field, type] of Object.entries(schema)) {
+    const isOptional = field.endsWith("?");
+    const cleanName = isOptional ? field.slice(0, -1) : field;
+    const kebabName = camelToKebab(cleanName);
+    const value = rawOptions[kebabName];
+    if (value === void 0) {
+      if (!isOptional) {
+        throw new Error(`Missing required flag: --${kebabName}`);
+      }
+      continue;
+    }
+    const cleanType = type.toLowerCase().trim();
+    if (cleanType === "number") {
+      const parsed = Number(value);
+      if (isNaN(parsed)) throw new Error(`Flag --${kebabName} must be a number`);
+      input2[cleanName] = parsed;
+    } else if (cleanType === "boolean") {
+      input2[cleanName] = value === true || value === "true";
+    } else {
+      input2[cleanName] = String(value);
+    }
+  }
+  return input2;
+}
+async function executePluginCommand(command, input2, viteServer) {
+  const cliCommand = await loadCommandHandler(command, viteServer);
+  const services = resolveServices(cliCommand.services);
+  return cliCommand.handler(input2, ...services);
+}
+async function loadCommandHandler(command, viteServer) {
+  let module;
+  if (command.isLocal) {
+    const moduleFile = command.pluginModule || "index";
+    const modulePath = path.resolve(command.pluginPath, moduleFile);
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(modulePath);
+    } else {
+      module = await import(modulePath);
+    }
+  } else {
+    const toolsEntry = `${command.packageName}/tools`;
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(toolsEntry);
+    } else {
+      module = await import(toolsEntry);
+    }
+  }
+  for (const [, exported] of Object.entries(module)) {
+    if (isJayCliCommand(exported) && exported.commandName === command.commandName) {
+      return exported;
+    }
+  }
+  const byName = module[command.handlerExport];
+  if (byName && isJayCliCommand(byName)) {
+    return byName;
+  }
+  throw new Error(
+    `CLI command "${command.commandName}" not found as export in "${command.isLocal ? command.pluginPath : command.packageName}". Available exports: ${Object.keys(module).join(", ")}`
+  );
+}
+class SetupNeedsAnswerError extends Error {
+  constructor(plugin, key, type, promptMessage, choices) {
+    super(`Setup needs answer for "${key}": ${promptMessage}`);
+    this.plugin = plugin;
+    this.key = key;
+    this.type = type;
+    this.promptMessage = promptMessage;
+    this.choices = choices;
+    this.name = "SetupNeedsAnswerError";
+  }
+}
+async function discoverPluginsWithSetup(options) {
+  const { projectRoot, verbose, pluginFilter } = options;
+  const allPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    includeDevDeps: true,
+    discoverTransitive: true
+  });
+  const pluginsWithSetup = [];
+  for (const [packageName, plugin] of allPlugins) {
+    if (!plugin.manifest.setup) 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,
+      setupDescription: plugin.manifest.description,
+      dependencies: plugin.dependencies
+    });
+    if (verbose) {
+      getLogger().info(`[Setup] Found plugin with setup: ${plugin.name}`);
+    }
+  }
+  return sortPluginsByDependencies(pluginsWithSetup);
+}
+async function discoverPluginsWithAgentKit(options) {
+  const { projectRoot, verbose, pluginFilter } = options;
+  const allPlugins = await scanPlugins({
+    projectRoot,
+    verbose,
+    includeDevDeps: true,
+    discoverTransitive: true
+  });
+  const pluginsWithAgentKit = [];
+  for (const [packageName, plugin] of allPlugins) {
+    if (!plugin.manifest.agentkit) continue;
+    if (pluginFilter && plugin.name !== pluginFilter && packageName !== pluginFilter) {
+      continue;
+    }
+    pluginsWithAgentKit.push({
+      name: plugin.name,
+      pluginPath: plugin.pluginPath,
+      packageName: plugin.packageName,
+      isLocal: plugin.isLocal,
+      agentKitHandler: plugin.manifest.agentkit,
+      dependencies: plugin.dependencies
+    });
+    if (verbose) {
+      getLogger().info(`[AgentKit] Found plugin with agent-kit handler: ${plugin.name}`);
+    }
+  }
+  return sortPluginsByDependencies(pluginsWithAgentKit);
+}
+async function executePluginSetup(plugin, options) {
+  const { projectRoot, configDir, force, interactive, prompt, initError, viteServer } = options;
+  const context = {
+    pluginName: plugin.name,
+    projectRoot,
+    configDir,
+    services: getServiceRegistry(),
+    initError,
+    force,
+    interactive,
+    prompt
+  };
+  const handler = await loadHandler(plugin, plugin.setupHandler, viteServer);
+  return handler(context);
+}
+async function executePluginAgentKit(plugin, options) {
+  const { projectRoot, force, initError, viteServer } = options;
+  const referencesDir = path.join(projectRoot, "agent-kit", "references", plugin.name);
+  const context = {
+    pluginName: plugin.name,
+    projectRoot,
+    referencesDir,
+    services: getServiceRegistry(),
+    initError,
+    force
+  };
+  const handler = await loadHandler(
+    plugin,
+    plugin.agentKitHandler,
+    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.agentkit === "function") return module.agentkit;
+    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 {
+    const toolsEntry = `${plugin.packageName}/tools`;
+    if (viteServer) {
+      module = await viteServer.ssrLoadModule(toolsEntry);
+    } else {
+      module = await import(toolsEntry);
+    }
+    if (typeof module[handlerName] !== "function") {
+      throw new Error(
+        `Handler "${handlerName}" not found as export in "${toolsEntry}". Available exports: ${Object.keys(module).join(", ")}`
+      );
+    }
+    return module[handlerName];
+  }
+}
 async function initializeServicesForCli(projectRoot, viteServer, quiet = false) {
   const path2 = await import("node:path");
   const fs2 = await import("node:fs");
   const {
     runInitCallbacks: runInitCallbacks2,
-    getServiceRegistry,
+    getServiceRegistry: getServiceRegistry2,
     discoverPluginsWithInit: discoverPluginsWithInit2,
     sortPluginsByDependencies: sortPluginsByDependencies2,
     executePluginServerInits: executePluginServerInits2
@@ -260,7 +1579,7 @@ async function initializeServicesForCli(projectRoot, viteServer, quiet = false)
     getLogger().warn(chalk.yellow(`⚠️  Service initialization failed: ${error.message}`));
     getLogger().warn(chalk.gray("   Static contracts will still be listed."));
   }
-  return { services: getServiceRegistry(), initErrors };
+  return { services: getServiceRegistry2(), initErrors };
 }
 async function runDev(projectPath, options) {
   const logLevel = options.quiet ? "silent" : options.verbose ? "verbose" : "info";
@@ -274,12 +1593,12 @@ async function runDev(projectPath, options) {
   });
 }
 async function resolveProductionContext(projectPath, versionOverride) {
-  const resolvedPath = path$1.resolve(projectPath || process.cwd());
-  const jayConfigPath = path$1.join(resolvedPath, ".jay");
+  const resolvedPath = path__default.resolve(projectPath || process.cwd());
+  const jayConfigPath = path__default.join(resolvedPath, ".jay");
   let pagesBase = "./src/pages";
   let siteBaseUrl;
   try {
-    const jayConfig = YAML.parse(await fs$1.readFile(jayConfigPath, "utf-8"));
+    const jayConfig = YAML.parse(await fs$2.readFile(jayConfigPath, "utf-8"));
     pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
     siteBaseUrl = jayConfig?.site?.baseUrl;
   } catch {
@@ -287,17 +1606,17 @@ async function resolveProductionContext(projectPath, versionOverride) {
   const version = versionOverride || await resolveVersionFromPackageJson(resolvedPath);
   return {
     resolvedPath,
-    pagesRoot: path$1.resolve(resolvedPath, pagesBase),
-    buildRoot: path$1.join(resolvedPath, "build"),
+    pagesRoot: path__default.resolve(resolvedPath, pagesBase),
+    buildRoot: path__default.join(resolvedPath, "build"),
     version,
-    tsConfigFilePath: path$1.join(resolvedPath, "tsconfig.json"),
+    tsConfigFilePath: path__default.join(resolvedPath, "tsconfig.json"),
     siteBaseUrl
   };
 }
 async function resolveVersionFromPackageJson(projectRoot) {
   try {
     const pkgJson = JSON.parse(
-      await fs$1.readFile(path$1.join(projectRoot, "package.json"), "utf-8")
+      await fs$2.readFile(path__default.join(projectRoot, "package.json"), "utf-8")
     );
     if (pkgJson.version) {
       return pkgJson.version;
@@ -313,7 +1632,7 @@ function initLogger(verbose) {
 async function runBuild(projectPath, options) {
   initLogger(options.verbose);
   const ctx = await resolveProductionContext(projectPath, options.version);
-  const { buildVersion } = await import("@jay-framework/production-server");
+  const { buildVersion } = await import("./index-B9vCxAZ1.js");
   await buildVersion({
     version: ctx.version,
     projectRoot: ctx.resolvedPath,
@@ -1158,7 +2477,7 @@ function isRelativeHandlerRef(value) {
 function resolveModulePath$1(basePath) {
   for (const ext of ["", ".ts", ".js", "/index.ts", "/index.js"]) {
     const candidate = basePath + ext;
-    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+    if (fs$1.existsSync(candidate) && fs$1.statSync(candidate).isFile()) {
       return candidate;
     }
   }
@@ -1166,10 +2485,10 @@ function resolveModulePath$1(basePath) {
 }
 function collectTypeScriptFiles(dir, depth = 0) {
   if (depth > 4) return [];
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const entries = fs$1.readdirSync(dir, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const fullPath = path.join(dir, entry.name);
+    const fullPath = path$1.join(dir, entry.name);
     if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== "test") {
       files.push(...collectTypeScriptFiles(fullPath, depth + 1));
     } else if (entry.isFile() && (entry.name.endsWith(".ts") || entry.name.endsWith(".js"))) {
@@ -1180,13 +2499,13 @@ function collectTypeScriptFiles(dir, depth = 0) {
 }
 function resolveHandlerSourceFile(pluginPath, handlerRef, isNpmPackage) {
   if (isRelativeHandlerRef(handlerRef)) {
-    return resolveModulePath$1(path.join(pluginPath, handlerRef)) ?? null;
+    return resolveModulePath$1(path$1.join(pluginPath, handlerRef)) ?? null;
   }
-  const searchRoots = isNpmPackage ? [path.join(pluginPath, "lib"), path.join(pluginPath, "dist")] : [pluginPath];
+  const searchRoots = isNpmPackage ? [path$1.join(pluginPath, "lib"), path$1.join(pluginPath, "dist")] : [pluginPath];
   for (const root of searchRoots) {
-    if (!fs.existsSync(root)) continue;
+    if (!fs$1.existsSync(root)) continue;
     for (const file of collectTypeScriptFiles(root)) {
-      const content = fs.readFileSync(file, "utf-8");
+      const content = fs$1.readFileSync(file, "utf-8");
       const definesHandler = new RegExp(
         `export\\s+(?:async\\s+)?function\\s+${handlerRef}\\b`
       ).test(content);
@@ -1203,7 +2522,7 @@ function resolveHandlerSourceFile(pluginPath, handlerRef, isNpmPackage) {
       );
       if (reExportMatch) {
         const importSpec = reExportMatch[1].replace(/\.js$/, "");
-        const resolved = resolveModulePath$1(path.resolve(path.dirname(file), importSpec));
+        const resolved = resolveModulePath$1(path$1.resolve(path$1.dirname(file), importSpec));
         if (resolved) return resolved;
       }
     }
@@ -1279,7 +2598,7 @@ function handlerBodyWritesAddMenuCatalog(body) {
 function resolveSetupHandlerFunctionBody(pluginPath, handlerRef, isNpmPackage) {
   const sourceFile = resolveHandlerSourceFile(pluginPath, handlerRef, isNpmPackage);
   if (!sourceFile) return null;
-  const source = fs.readFileSync(sourceFile, "utf-8");
+  const source = fs$1.readFileSync(sourceFile, "utf-8");
   if (isRelativeHandlerRef(handlerRef)) {
     return extractDefaultExportFunctionBody(source) ?? extractFunctionBody(source, "setup") ?? extractFunctionBody(source, handlerRef);
   }
@@ -1312,7 +2631,7 @@ function mapLintFinding(finding, catalogPath, severity) {
 }
 function pluginShipsAddMenuCatalog(context) {
   return ADD_MENU_CATALOG_REL_PATHS.some(
-    (relPath) => fs.existsSync(path.join(context.pluginPath, relPath))
+    (relPath) => fs$1.existsSync(path$1.join(context.pluginPath, relPath))
   );
 }
 function validateAddMenuAgentKitHandler(context, result) {
@@ -1346,7 +2665,7 @@ function validateAddMenuAgentKitHandler(context, result) {
 async function validateAddMenuCatalogFileAtPath(catalogPath, relPath, result) {
   let parsed;
   try {
-    const content = await fs.promises.readFile(catalogPath, "utf-8");
+    const content = await fs$1.promises.readFile(catalogPath, "utf-8");
     parsed = YAML.parse(content);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1375,8 +2694,8 @@ async function validateAddMenuCatalogFileAtPath(catalogPath, relPath, result) {
 async function validateAddMenuCatalog(context, result) {
   validateAddMenuAgentKitHandler(context, result);
   for (const relPath of ADD_MENU_CATALOG_REL_PATHS) {
-    const catalogPath = path.join(context.pluginPath, relPath);
-    if (!fs.existsSync(catalogPath)) continue;
+    const catalogPath = path$1.join(context.pluginPath, relPath);
+    if (!fs$1.existsSync(catalogPath)) continue;
     await validateAddMenuCatalogFileAtPath(catalogPath, relPath, result);
   }
 }
@@ -1493,7 +2812,7 @@ function mapSchemaError(error, relPath) {
 function validateSettingsTemplateAtPath(catalogPath, relPath, result, manifest) {
   let parsed;
   try {
-    parsed = YAML.parse(fs.readFileSync(catalogPath, "utf-8"));
+    parsed = YAML.parse(fs$1.readFileSync(catalogPath, "utf-8"));
   } catch (err) {
     result.errors.push({
       type: "schema",
@@ -1527,8 +2846,8 @@ function validateSettingsTemplateAtPath(catalogPath, relPath, result, manifest)
   }
 }
 async function validateAiditorSettings(context, result) {
-  const templatePath = path.join(context.pluginPath, AIDITOR_SETTINGS_TEMPLATE_REL_PATH);
-  if (!fs.existsSync(templatePath)) {
+  const templatePath = path$1.join(context.pluginPath, AIDITOR_SETTINGS_TEMPLATE_REL_PATH);
+  if (!fs$1.existsSync(templatePath)) {
     return;
   }
   validateSettingsTemplateAtPath(
@@ -1563,10 +2882,10 @@ async function validatePluginPackage(pluginPath, options) {
     contractsChecked: 0,
     componentsChecked: 0
   };
-  const pluginYamlPath = path.join(pluginPath, "plugin.yaml");
-  const pluginManifest = loadPluginManifest(pluginPath);
+  const pluginYamlPath = path$1.join(pluginPath, "plugin.yaml");
+  const pluginManifest = loadPluginManifest$1(pluginPath);
   if (!pluginManifest) {
-    if (!fs.existsSync(pluginYamlPath)) {
+    if (!fs$1.existsSync(pluginYamlPath)) {
       result.errors.push({
         type: "file-missing",
         message: "plugin.yaml not found",
@@ -1587,7 +2906,7 @@ async function validatePluginPackage(pluginPath, options) {
   const context = {
     manifest: pluginManifest,
     pluginPath,
-    isNpmPackage: fs.existsSync(path.join(pluginPath, "package.json"))
+    isNpmPackage: fs$1.existsSync(path$1.join(pluginPath, "package.json"))
   };
   await validateSchema(context, result);
   if (pluginManifest.contracts) {
@@ -1615,12 +2934,13 @@ async function validatePluginPackage(pluginPath, options) {
   }
   await validateAddMenuCatalog(context, result);
   await validateAiditorSettings(context, result);
+  validateNoCompilerLeak(context, result);
   result.valid = result.errors.length === 0;
   return result;
 }
 async function validateLocalPlugins(projectPath, options) {
-  const pluginsPath = path.join(projectPath, "src/plugins");
-  if (!fs.existsSync(pluginsPath)) {
+  const pluginsPath = path$1.join(projectPath, "src/plugins");
+  if (!fs$1.existsSync(pluginsPath)) {
     return {
       valid: false,
       errors: [
@@ -1634,10 +2954,10 @@ async function validateLocalPlugins(projectPath, options) {
       warnings: []
     };
   }
-  const pluginDirs = fs.readdirSync(pluginsPath, { withFileTypes: true }).filter((d) => d.isDirectory());
+  const pluginDirs = fs$1.readdirSync(pluginsPath, { withFileTypes: true }).filter((d) => d.isDirectory());
   const allResults = [];
   for (const pluginDir of pluginDirs) {
-    const pluginPath = path.join(pluginsPath, pluginDir.name);
+    const pluginPath = path$1.join(pluginsPath, pluginDir.name);
     const result = await validatePluginPackage(pluginPath, options);
     allResults.push(result);
   }
@@ -1651,8 +2971,8 @@ async function validateLocalPlugins(projectPath, options) {
   };
 }
 function validateDocFile(docPath, label, context, result) {
-  const resolvedPath = path.join(context.pluginPath, docPath);
-  if (!fs.existsSync(resolvedPath)) {
+  const resolvedPath = path$1.join(context.pluginPath, docPath);
+  if (!fs$1.existsSync(resolvedPath)) {
     result.errors.push({
       type: "file-missing",
       message: `Doc file for ${label} not found: ${docPath}`,
@@ -1662,9 +2982,9 @@ function validateDocFile(docPath, label, context, result) {
     return;
   }
   if (context.isNpmPackage) {
-    const packageJsonPath = path.join(context.pluginPath, "package.json");
+    const packageJsonPath = path$1.join(context.pluginPath, "package.json");
     try {
-      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+      const packageJson = JSON.parse(fs$1.readFileSync(packageJsonPath, "utf-8"));
       if (packageJson.exports) {
         const exportKey = "./" + docPath.replace(/^\.\//, "");
         if (!packageJson.exports[exportKey]) {
@@ -1788,13 +3108,28 @@ async function validateSchema(context, result) {
       }
     }
   }
-  if (!manifest.contracts && !manifest.dynamic_contracts) {
-    result.warnings.push({
-      type: "schema",
-      message: "Plugin has no contracts or dynamic_contracts defined",
-      location: "plugin.yaml",
-      suggestion: 'Add either "contracts" or "dynamic_contracts" to expose functionality'
-    });
+  const hasCapability = Boolean(
+    manifest.contracts || manifest.dynamic_contracts || manifest.actions || manifest.validators || manifest.routes || manifest.services || manifest.contexts || manifest.init || manifest.setup || manifest.agentkit || manifest.commands
+  );
+  if (!hasCapability) {
+    if (manifest.global === true) {
+      const hasGlobalEntry = !context.isNpmPackage || checkExportExists("init", context, ".") || checkExportExists("setup", context, ".");
+      if (!hasGlobalEntry) {
+        result.errors.push({
+          type: "export-mismatch",
+          message: 'Plugin declares "global: true" but exports no init/setup handler to run on each page',
+          location: "plugin.yaml",
+          suggestion: 'Export an "init" (or "setup") handler from the package entry, or declare a capability'
+        });
+      }
+    } else {
+      result.warnings.push({
+        type: "schema",
+        message: "Plugin declares no capabilities (contracts, dynamic_contracts, actions, validators, routes, services, contexts, init, setup, agentkit, commands)",
+        location: "plugin.yaml",
+        suggestion: "Declare at least one capability. See agent-kit/plugin/plugin-structure.md"
+      });
+    }
   }
   if (manifest.services) {
     if (!Array.isArray(manifest.services)) {
@@ -1858,14 +3193,22 @@ async function validateSchema(context, result) {
   }
   if (manifest.actions) {
     for (const entry of manifest.actions) {
-      const exportName = typeof entry === "string" ? entry : entry.name;
+      if (typeof entry === "object" && entry.devOnly !== void 0 && typeof entry.devOnly !== "boolean") {
+        result.errors.push({
+          type: "schema",
+          message: `Action "${entry.name}" devOnly must be a boolean`,
+          location: "plugin.yaml actions"
+        });
+      }
+      const { name: exportName, devOnly } = normalizeActionEntry$1(entry);
       if (exportName) {
         validateHandlerRef(
           exportName,
           `Action "${exportName}"`,
           "plugin.yaml actions",
           context,
-          result
+          result,
+          devOnly ? "./tools" : "."
         );
       }
     }
@@ -1910,7 +3253,8 @@ async function validateSchema(context, result) {
             `Route "${route.path}" component`,
             `plugin.yaml routes`,
             context,
-            result
+            result,
+            route.devOnly ? "./tools" : "."
           );
         }
         if (route.jayHtml) {
@@ -1964,7 +3308,8 @@ async function validateSchema(context, result) {
             `Validator "${validator.name}" handler`,
             "plugin.yaml validators",
             context,
-            result
+            result,
+            "./tools"
           );
         }
       });
@@ -1984,7 +3329,8 @@ async function validateSchema(context, result) {
         "Setup handler",
         "plugin.yaml setup",
         context,
-        result
+        result,
+        "./tools"
       );
     }
   }
@@ -1994,30 +3340,31 @@ async function validateSchema(context, result) {
       "Agent-kit handler",
       "plugin.yaml agentkit",
       context,
-      result
+      result,
+      "./tools"
     );
   }
 }
-function checkExportExists(exportName, context) {
-  const packageJsonPath = path.join(context.pluginPath, "package.json");
-  if (!fs.existsSync(packageJsonPath)) return true;
+function checkExportExists(exportName, context, exportKey = ".") {
+  const packageJsonPath = path$1.join(context.pluginPath, "package.json");
+  if (!fs$1.existsSync(packageJsonPath)) return true;
   let mainPath;
   try {
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-    if (packageJson.exports?.["."]) {
-      const entry = packageJson.exports["."];
+    const packageJson = JSON.parse(fs$1.readFileSync(packageJsonPath, "utf-8"));
+    if (packageJson.exports?.[exportKey]) {
+      const entry = packageJson.exports[exportKey];
       const entryPath = typeof entry === "string" ? entry : entry.default || entry.import;
-      if (entryPath) mainPath = path.join(context.pluginPath, entryPath);
+      if (entryPath) mainPath = path$1.join(context.pluginPath, entryPath);
     }
-    if (!mainPath && packageJson.main) {
-      mainPath = path.join(context.pluginPath, packageJson.main);
+    if (!mainPath && exportKey === "." && packageJson.main) {
+      mainPath = path$1.join(context.pluginPath, packageJson.main);
     }
   } catch {
     return true;
   }
-  if (!mainPath || !fs.existsSync(mainPath)) return true;
+  if (!mainPath || !fs$1.existsSync(mainPath)) return true;
   try {
-    const content = fs.readFileSync(mainPath, "utf-8");
+    const content = fs$1.readFileSync(mainPath, "utf-8");
     const patterns = [
       new RegExp(`export\\s*\\{[^}]*\\b${exportName}\\b[^}]*\\}`, "m"),
       new RegExp(`export\\s+(?:async\\s+)?function\\s+${exportName}\\b`),
@@ -2031,7 +3378,63 @@ function checkExportExists(exportName, context) {
 function isRelativePath(value) {
   return value.startsWith("./") || value.startsWith("../");
 }
-function validateHandlerRef(value, label, location, context, result) {
+function resolveEntryFile(context, exportKey) {
+  const packageJsonPath = path$1.join(context.pluginPath, "package.json");
+  if (!fs$1.existsSync(packageJsonPath)) return void 0;
+  try {
+    const packageJson = JSON.parse(fs$1.readFileSync(packageJsonPath, "utf-8"));
+    const entry = packageJson.exports?.[exportKey];
+    const entryPath = typeof entry === "string" ? entry : entry?.default || entry?.import || void 0;
+    const resolved = entryPath || (exportKey === "." ? packageJson.main : void 0) ? path$1.join(context.pluginPath, entryPath || packageJson.main) : void 0;
+    return resolved && fs$1.existsSync(resolved) ? resolved : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function hasComponentCapability(context) {
+  const m = context.manifest;
+  return Boolean(m.contracts || m.dynamic_contracts || m.routes);
+}
+function needsToolsEntry(manifest) {
+  if (manifest.validators || manifest.commands || manifest.agentkit || manifest.setup) {
+    return true;
+  }
+  if (manifest.actions) {
+    return manifest.actions.some((entry) => normalizeActionEntry$1(entry).devOnly === true);
+  }
+  return false;
+}
+function detectInteractivePhase(context) {
+  if (!context.isNpmPackage) return "unknown";
+  const entryFile = resolveEntryFile(context, ".");
+  if (!entryFile) return "unknown";
+  try {
+    const content = fs$1.readFileSync(entryFile, "utf-8");
+    return content.includes("withInteractiveMark(");
+  } catch {
+    return "unknown";
+  }
+}
+function validateNoCompilerLeak(context, result) {
+  if (!context.isNpmPackage) return;
+  const entryFile = resolveEntryFile(context, ".");
+  if (!entryFile) return;
+  let content;
+  try {
+    content = fs$1.readFileSync(entryFile, "utf-8");
+  } catch {
+    return;
+  }
+  if (content.includes("@jay-framework/compiler-")) {
+    result.errors.push({
+      type: "compiler-leak",
+      message: 'Serve entry "." (dist/index.js) imports "@jay-framework/compiler-…" — the compiler must not reach the production serve bundle',
+      location: entryFile,
+      suggestion: 'Move the compiler-using handler (validator, agentkit, setup, or a devOnly action) to lib/tools.ts (the "./tools" export) and remove its re-export from lib/index.ts. A compiler-using action is really a command or a devOnly action (DL#179/#180).'
+    });
+  }
+}
+function validateHandlerRef(value, label, location, context, result, exportKey = ".") {
   if (context.isNpmPackage) {
     if (isRelativePath(value)) {
       result.errors.push({
@@ -2040,18 +3443,19 @@ function validateHandlerRef(value, label, location, context, result) {
         location,
         suggestion: `Export the function from the package entry point and use the export name instead of a path`
       });
-    } else if (!checkExportExists(value, context)) {
+    } else if (!checkExportExists(value, context, exportKey)) {
+      const entryFile = exportKey === "./tools" ? "lib/tools.ts" : exportKey === "./client" ? "lib/index.client.ts" : "lib/index.ts";
       result.errors.push({
         type: "export-mismatch",
-        message: `${label} "${value}" is not exported from the package`,
+        message: `${label} "${value}" is not exported from the "${exportKey}" entry`,
         location,
-        suggestion: `Add "export { ${value} } from '...'" to the package entry point`
+        suggestion: `Add "export { ${value} } from '...'" to ${entryFile} (the "${exportKey}" export)`
       });
     }
   } else if (isRelativePath(value)) {
-    const handlerPath = path.join(context.pluginPath, value);
+    const handlerPath = path$1.join(context.pluginPath, value);
     const extensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
-    const found = extensions.some((ext) => fs.existsSync(handlerPath + ext));
+    const found = extensions.some((ext) => fs$1.existsSync(handlerPath + ext));
     if (!found) {
       result.errors.push({
         type: "file-missing",
@@ -2064,18 +3468,18 @@ function validateHandlerRef(value, label, location, context, result) {
 }
 function resolveContractFile(contractSpec, context) {
   if (context.isNpmPackage) {
-    const packageJsonPath = path.join(context.pluginPath, "package.json");
-    if (fs.existsSync(packageJsonPath)) {
+    const packageJsonPath = path$1.join(context.pluginPath, "package.json");
+    if (fs$1.existsSync(packageJsonPath)) {
       try {
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+        const packageJson = JSON.parse(fs$1.readFileSync(packageJsonPath, "utf-8"));
         if (packageJson.exports) {
           const exportKey = "./" + contractSpec;
           const exportValue = packageJson.exports[exportKey];
           if (exportValue) {
             const resolvedPath = typeof exportValue === "string" ? exportValue : exportValue.default || exportValue.import || exportValue.require;
             if (resolvedPath) {
-              const fullPath = path.join(context.pluginPath, resolvedPath);
-              if (fs.existsSync(fullPath)) return fullPath;
+              const fullPath = path$1.join(context.pluginPath, resolvedPath);
+              if (fs$1.existsSync(fullPath)) return fullPath;
             }
           }
         }
@@ -2083,13 +3487,13 @@ function resolveContractFile(contractSpec, context) {
       }
     }
     for (const dir of ["dist", "lib", ""]) {
-      const candidate = path.join(context.pluginPath, dir, contractSpec);
-      if (fs.existsSync(candidate)) return candidate;
+      const candidate = path$1.join(context.pluginPath, dir, contractSpec);
+      if (fs$1.existsSync(candidate)) return candidate;
     }
     return void 0;
   } else {
-    const candidate = path.join(context.pluginPath, contractSpec);
-    return fs.existsSync(candidate) ? candidate : void 0;
+    const candidate = path$1.join(context.pluginPath, contractSpec);
+    return fs$1.existsSync(candidate) ? candidate : void 0;
   }
 }
 async function validateContract(contract, index, context, generateTypes, result) {
@@ -2100,12 +3504,12 @@ async function validateContract(contract, index, context, generateTypes, result)
       type: "file-missing",
       message: `Contract file not found: ${contract.contract}`,
       location: `plugin.yaml contracts[${index}]`,
-      suggestion: context.isNpmPackage ? `Ensure the contract is exported in package.json and the file exists` : `Create the contract file at ${path.join(context.pluginPath, contract.contract)}`
+      suggestion: context.isNpmPackage ? `Ensure the contract is exported in package.json and the file exists` : `Create the contract file at ${path$1.join(context.pluginPath, contract.contract)}`
     });
     return;
   }
   try {
-    const contractContent = await fs.promises.readFile(contractPath, "utf-8");
+    const contractContent = await fs$1.promises.readFile(contractPath, "utf-8");
     const parsedContract = YAML.parse(contractContent);
     if (!parsedContract.name) {
       result.errors.push({
@@ -2172,21 +3576,21 @@ function hasExportModifier(node) {
 function resolveModulePath(basePath) {
   for (const ext of ["", ".ts", ".js", "/index.ts", "/index.js"]) {
     const candidate = basePath + ext;
-    if (fs.existsSync(candidate)) return candidate;
+    if (fs$1.existsSync(candidate)) return candidate;
   }
   return void 0;
 }
 function resolveComponentSourcePath(componentName, context) {
   const modulePath = context.manifest.module || "index";
-  const entryBase = path.join(context.pluginPath, modulePath);
+  const entryBase = path$1.join(context.pluginPath, modulePath);
   const entryFile = resolveModulePath(entryBase);
-  const libEntryFile = !entryFile ? resolveModulePath(path.join(context.pluginPath, "lib", modulePath)) : void 0;
+  const libEntryFile = !entryFile ? resolveModulePath(path$1.join(context.pluginPath, "lib", modulePath)) : void 0;
   const sourceEntry = entryFile || libEntryFile;
   if (!sourceEntry) return void 0;
   if (!sourceEntry.endsWith(".ts")) return void 0;
   let sourceCode;
   try {
-    sourceCode = fs.readFileSync(sourceEntry, "utf-8");
+    sourceCode = fs$1.readFileSync(sourceEntry, "utf-8");
   } catch {
     return void 0;
   }
@@ -2212,7 +3616,7 @@ function resolveComponentSourcePath(componentName, context) {
       for (const element of exportClause.elements) {
         const exportedName = element.name.text;
         if (exportedName === componentName) {
-          const resolvedBase = path.resolve(path.dirname(sourceEntry), moduleSpec);
+          const resolvedBase = path$1.resolve(path$1.dirname(sourceEntry), moduleSpec);
           return resolveModulePath(resolvedBase);
         }
       }
@@ -2220,11 +3624,11 @@ function resolveComponentSourcePath(componentName, context) {
   }
   for (const moduleSpec of starReexportModules) {
     if (!moduleSpec.startsWith(".")) continue;
-    const resolvedBase = path.resolve(path.dirname(sourceEntry), moduleSpec);
+    const resolvedBase = path$1.resolve(path$1.dirname(sourceEntry), moduleSpec);
     const resolvedPath = resolveModulePath(resolvedBase);
     if (!resolvedPath || !resolvedPath.endsWith(".ts")) continue;
     try {
-      const modSource = fs.readFileSync(resolvedPath, "utf-8");
+      const modSource = fs$1.readFileSync(resolvedPath, "utf-8");
       const modFile = u.createSourceFile(
         resolvedPath,
         modSource,
@@ -2263,15 +3667,15 @@ async function checkComponentContractConsistency(contract, context, result) {
   if (!contractPath) return;
   let contractContent;
   try {
-    contractContent = await fs.promises.readFile(contractPath, "utf-8");
+    contractContent = await fs$1.promises.readFile(contractPath, "utf-8");
   } catch {
     return;
   }
-  const parsed = parseContract(contractContent, path.basename(contractPath));
+  const parsed = parseContract(contractContent, path$1.basename(contractPath));
   if (parsed.validations.length > 0) return;
   let sourceCode;
   try {
-    sourceCode = await fs.promises.readFile(sourcePath, "utf-8");
+    sourceCode = await fs$1.promises.readFile(sourcePath, "utf-8");
   } catch {
     return;
   }
@@ -2290,8 +3694,8 @@ async function checkComponentContractConsistency(contract, context, result) {
   result.warnings.push(...checkResult.warnings);
 }
 async function validatePackageJson(context, result) {
-  const packageJsonPath = path.join(context.pluginPath, "package.json");
-  if (!fs.existsSync(packageJsonPath)) {
+  const packageJsonPath = path$1.join(context.pluginPath, "package.json");
+  if (!fs$1.existsSync(packageJsonPath)) {
     result.warnings.push({
       type: "file-missing",
       message: "package.json not found",
@@ -2301,7 +3705,7 @@ async function validatePackageJson(context, result) {
     return;
   }
   try {
-    const packageJson = JSON.parse(await fs.promises.readFile(packageJsonPath, "utf-8"));
+    const packageJson = JSON.parse(await fs$1.promises.readFile(packageJsonPath, "utf-8"));
     if (!packageJson.exports) {
       result.warnings.push({
         type: "export-mismatch",
@@ -2319,11 +3723,30 @@ async function validatePackageJson(context, result) {
         });
       }
       if (!packageJson.exports["./client"]) {
-        result.warnings.push({
+        const interactivity = detectInteractivePhase(context);
+        const needsClient = context.manifest.contexts !== void 0 || interactivity === true;
+        if (needsClient) {
+          result.errors.push({
+            type: "export-mismatch",
+            message: 'package.json exports missing "./client" entry point, but the plugin ' + (context.manifest.contexts !== void 0 ? "declares contexts (client-side by definition)" : "provides an interactive component"),
+            location: packageJsonPath,
+            suggestion: 'Add "./client": "./dist/index.client.js" to exports. The client bundle provides components for hydration and client-side contexts. Build with: vite build (client) + vite build --ssr (server)'
+          });
+        } else if (interactivity === "unknown" && hasComponentCapability(context)) {
+          result.warnings.push({
+            type: "export-mismatch",
+            message: 'package.json exports missing "./client" entry point; could not determine whether any component is interactive (build the plugin before validating)',
+            location: packageJsonPath,
+            suggestion: 'If any component declares an interactive phase, add "./client": "./dist/index.client.js"'
+          });
+        }
+      }
+      if (!packageJson.exports["./tools"] && needsToolsEntry(context.manifest)) {
+        result.errors.push({
           type: "export-mismatch",
-          message: 'package.json exports missing "./client" entry point',
+          message: 'package.json exports missing "./tools" entry point, but the plugin declares tools capabilities (validators, commands, agentkit, setup, or devOnly actions)',
           location: packageJsonPath,
-          suggestion: 'Add "./client": "./dist/index.client.js" to exports. The client bundle provides components for hydration and client-side contexts. Build with: vite build (client) + vite build --ssr (server)'
+          suggestion: 'Add "./tools": "./dist/tools.js" to exports and re-export those handlers from lib/tools.ts'
         });
       }
       if (context.manifest.contracts) {
@@ -2365,8 +3788,8 @@ async function validatePackageJson(context, result) {
         suggestion: 'Add "./plugin.yaml": "./plugin.yaml" to exports field'
       });
     }
-    const agentKitDir = path.join(context.pluginPath, "agent-kit");
-    if (fs.existsSync(agentKitDir) && fs.statSync(agentKitDir).isDirectory()) {
+    const agentKitDir = path$1.join(context.pluginPath, "agent-kit");
+    if (fs$1.existsSync(agentKitDir) && fs$1.statSync(agentKitDir).isDirectory()) {
       const filesArray = packageJson.files;
       if (!filesArray || !filesArray.includes("agent-kit")) {
         result.warnings.push({
@@ -2390,7 +3813,7 @@ function isBareFunctionExport(exportName, context) {
   if (!sourcePath) return false;
   let sourceCode;
   try {
-    sourceCode = fs.readFileSync(sourcePath, "utf-8");
+    sourceCode = fs$1.readFileSync(sourcePath, "utf-8");
   } catch {
     return false;
   }
@@ -2418,8 +3841,8 @@ function resolveModulePathWithJsToTs(basePath) {
 }
 function resolveExportSourceFile(exportName, context) {
   const modulePath = context.manifest.module || "index";
-  const entryBase = path.join(context.pluginPath, modulePath);
-  const libEntryBase = path.join(context.pluginPath, "lib", modulePath);
+  const entryBase = path$1.join(context.pluginPath, modulePath);
+  const libEntryBase = path$1.join(context.pluginPath, "lib", modulePath);
   const sourceEntry = resolveModulePath(entryBase) || resolveModulePath(libEntryBase);
   if (!sourceEntry || !sourceEntry.endsWith(".ts")) return void 0;
   return followExportChain(exportName, sourceEntry);
@@ -2427,7 +3850,7 @@ function resolveExportSourceFile(exportName, context) {
 function followExportChain(exportName, filePath) {
   let sourceCode;
   try {
-    sourceCode = fs.readFileSync(filePath, "utf-8");
+    sourceCode = fs$1.readFileSync(filePath, "utf-8");
   } catch {
     return void 0;
   }
@@ -2450,7 +3873,7 @@ function followExportChain(exportName, filePath) {
       if (u.isNamedExports(statement.exportClause)) {
         for (const element of statement.exportClause.elements) {
           if (element.name.text === exportName) {
-            const resolvedBase = path.resolve(path.dirname(filePath), moduleSpec);
+            const resolvedBase = path$1.resolve(path$1.dirname(filePath), moduleSpec);
             return resolveModulePathWithJsToTs(resolvedBase);
           }
         }
@@ -2467,7 +3890,7 @@ function followExportChain(exportName, filePath) {
   }
   for (const moduleSpec of starReexportModules) {
     if (!moduleSpec.startsWith(".")) continue;
-    const resolvedBase = path.resolve(path.dirname(filePath), moduleSpec);
+    const resolvedBase = path$1.resolve(path$1.dirname(filePath), moduleSpec);
     const resolved = resolveModulePathWithJsToTs(resolvedBase);
     if (!resolved) continue;
     const found = followExportChain(exportName, resolved);
@@ -2484,11 +3907,11 @@ async function validateDynamicContracts(context, result) {
     if (config.generator) {
       const isFilePath = config.generator.startsWith("./") || config.generator.startsWith("/") || config.generator.includes(".ts") || config.generator.includes(".js");
       if (isFilePath) {
-        const generatorPath = path.join(context.pluginPath, config.generator);
+        const generatorPath = path$1.join(context.pluginPath, config.generator);
         const possibleExtensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
         let found = false;
         for (const ext of possibleExtensions) {
-          if (fs.existsSync(generatorPath + ext)) {
+          if (fs$1.existsSync(generatorPath + ext)) {
             found = true;
             break;
           }
@@ -2513,11 +3936,11 @@ async function validateDynamicContracts(context, result) {
     if (config.component) {
       const isFilePath = config.component.startsWith("./") || config.component.startsWith("/") || config.component.includes(".ts") || config.component.includes(".js");
       if (isFilePath) {
-        const componentPath = path.join(context.pluginPath, config.component);
+        const componentPath = path$1.join(context.pluginPath, config.component);
         const possibleExtensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
         let found = false;
         for (const ext of possibleExtensions) {
-          if (fs.existsSync(componentPath + ext)) {
+          if (fs$1.existsSync(componentPath + ext)) {
             found = true;
             break;
           }
@@ -2838,12 +4261,12 @@ function checkRefElementTypes(jayHtml, file) {
   return warnings;
 }
 function checkPageComponentExport(jayHtmlPath) {
-  const dirname = path.dirname(jayHtmlPath);
-  const compPath = path.join(dirname, "page.ts");
-  if (!fs.existsSync(compPath)) return null;
+  const dirname = path$1.dirname(jayHtmlPath);
+  const compPath = path$1.join(dirname, "page.ts");
+  if (!fs$1.existsSync(compPath)) return null;
   let content;
   try {
-    content = fs.readFileSync(compPath, "utf-8");
+    content = fs$1.readFileSync(compPath, "utf-8");
   } catch {
     return null;
   }
@@ -2854,7 +4277,7 @@ function checkPageComponentExport(jayHtmlPath) {
     new RegExp(`export\\s+(?:const|let|var)\\s+${exportName}\\b`)
   ];
   if (patterns.some((p) => p.test(content))) return null;
-  return `${path.relative(dirname, compPath)} exists but does not export "${exportName}". Remove the file or add the export.`;
+  return `${path$1.relative(dirname, compPath)} exists but does not export "${exportName}". Remove the file or add the export.`;
 }
 const DOCUMENT_ACCESS_PATTERNS = [
   /document\.getElementById\b/,
@@ -2867,15 +4290,15 @@ const DOCUMENT_ACCESS_PATTERNS = [
 ];
 const DOM_SUPPRESS_COMMENT = "jay-dom: allow";
 function checkDirectDocumentAccess(jayHtmlPath) {
-  const dirname = path.dirname(jayHtmlPath);
-  const basename = path.basename(jayHtmlPath, JAY_EXTENSION);
-  const candidates = [path.join(dirname, `${basename}.ts`), path.join(dirname, "page.ts")];
-  const compPath = candidates.find((p) => fs.existsSync(p));
+  const dirname = path$1.dirname(jayHtmlPath);
+  const basename = path$1.basename(jayHtmlPath, JAY_EXTENSION);
+  const candidates = [path$1.join(dirname, `${basename}.ts`), path$1.join(dirname, "page.ts")];
+  const compPath = candidates.find((p) => fs$1.existsSync(p));
   if (!compPath) return [];
-  const compName = path.basename(compPath);
+  const compName = path$1.basename(compPath);
   let content;
   try {
-    content = fs.readFileSync(compPath, "utf-8");
+    content = fs$1.readFileSync(compPath, "utf-8");
   } catch {
     return [];
   }
@@ -2898,8 +4321,8 @@ function checkDirectDocumentAccess(jayHtmlPath) {
 }
 const PARSE_PARAM = /^\[(\[)?(\.\.\.)?([^\]]+)\]?\]$/;
 function extractRouteParams(filePath, pagesBase) {
-  const relative = path.relative(pagesBase, filePath);
-  const segments = relative.split(path.sep);
+  const relative = path$1.relative(pagesBase, filePath);
+  const segments = relative.split(path$1.sep);
   const params = /* @__PURE__ */ new Set();
   for (const segment of segments) {
     const match = PARSE_PARAM.exec(segment);
@@ -3109,7 +4532,7 @@ function resolveLinkedTags(tags, contractDir) {
 }
 function resolveContractLinks(contract, contractPath) {
   if (!contractPath) return contract;
-  const contractDir = path.dirname(contractPath);
+  const contractDir = path$1.dirname(contractPath);
   return { ...contract, tags: resolveLinkedTags(contract.tags, contractDir) };
 }
 async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
@@ -3123,10 +4546,10 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
       try {
         let handlerModule;
         if (plugin.isLocal) {
-          const handlerPath = path.resolve(plugin.pluginPath, validatorDef.handler);
+          const handlerPath = path$1.resolve(plugin.pluginPath, validatorDef.handler);
           handlerModule = await import(handlerPath);
         } else {
-          handlerModule = await import(plugin.packageName);
+          handlerModule = await import(`${plugin.packageName}/tools`);
         }
         validatorFn = plugin.isLocal ? handlerModule.validate ?? handlerModule.default : handlerModule[validatorDef.handler];
         if (typeof validatorFn !== "function") {
@@ -3151,8 +4574,8 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
       }
       loadedValidators.push(source);
       for (const { relativePath, parsed } of parsedFiles) {
-        const pageContractPath = parsed.contractRef ? path.resolve(
-          path.dirname(path.resolve(projectRoot, relativePath)),
+        const pageContractPath = parsed.contractRef ? path$1.resolve(
+          path$1.dirname(path$1.resolve(projectRoot, relativePath)),
           parsed.contractRef
         ) : void 0;
         const resolvedPageContract = parsed.contract ? resolveContractLinks(parsed.contract, pageContractPath) : void 0;
@@ -3196,7 +4619,8 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
               providedHeadTags
             };
           }),
-          projectRoot
+          projectRoot,
+          validationOverrides: parsed.validationOverrides
         };
         try {
           const findings = await validatorFn(ctx);
@@ -3232,11 +4656,11 @@ async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
   return loadedValidators;
 }
 async function validateJayFiles(options = {}) {
-  const config = loadConfig();
-  const resolvedConfig = getConfigWithDefaults(config);
   const projectRoot = options.projectRoot ?? process.cwd();
-  const scanDir = options.path ? path.resolve(options.path) : path.resolve(resolvedConfig.devServer.pagesBase);
-  const componentsDir = path.resolve(resolvedConfig.devServer.componentsBase);
+  const config = loadConfig(projectRoot);
+  const resolvedConfig = getConfigWithDefaults(config);
+  const scanDir = options.path ? path$1.resolve(options.path) : path$1.resolve(resolvedConfig.devServer.pagesBase);
+  const componentsDir = path$1.resolve(resolvedConfig.devServer.componentsBase);
   const errors = [];
   const warnings = [];
   const coverage = [];
@@ -3255,10 +4679,10 @@ async function validateJayFiles(options = {}) {
 `));
   }
   for (const contractFile of contractFiles) {
-    const relativePath = path.relative(projectRoot, contractFile);
+    const relativePath = path$1.relative(projectRoot, contractFile);
     try {
       const content = await promises.readFile(contractFile, "utf-8");
-      const result = parseContract(content, path.basename(contractFile));
+      const result = parseContract(content, path$1.basename(contractFile));
       if (result.validations.length > 0) {
         for (const validation of result.validations) {
           errors.push({
@@ -3285,9 +4709,9 @@ async function validateJayFiles(options = {}) {
     }
   }
   for (const jayFile of jayHtmlFiles) {
-    const relativePath = path.relative(projectRoot, jayFile);
-    const filename = path.basename(jayFile.replace(JAY_EXTENSION, ""));
-    const dirname = path.dirname(jayFile);
+    const relativePath = path$1.relative(projectRoot, jayFile);
+    const filename = path$1.basename(jayFile.replace(JAY_EXTENSION, ""));
+    const dirname = path$1.dirname(jayFile);
     try {
       const content = await promises.readFile(jayFile, "utf-8");
       const parsedFile = await parseJayFile(
@@ -3313,9 +4737,10 @@ async function validateJayFiles(options = {}) {
       }
       parsedFiles.push({ relativePath, parsed: parsedFile.val });
       if (content.includes("application/jay-params")) {
-        warnings.push({
+        errors.push({
           file: relativePath,
-          message: '<script type="application/jay-params"> is deprecated. Move the values into the YAML body of the headless component that uses them. See agent-kit/developer/routing.md for details.'
+          message: '<script type="application/jay-params"> is no longer supported and is ignored. Move the values into the YAML body of the headless component that uses them. See agent-kit/developer/routing.md for details.',
+          stage: "parse"
         });
       }
       const pageExportError = checkPageComponentExport(jayFile);
@@ -3346,17 +4771,34 @@ async function validateJayFiles(options = {}) {
       for (const msg of refTypeErrors) {
         errors.push({ file: relativePath, message: msg, stage: "generate" });
       }
-      const headlessPropWarnings = checkHeadlessInstanceProps(parsedFile.val, relativePath);
-      for (const msg of headlessPropWarnings) {
-        warnings.push({ file: relativePath, message: msg });
+      const headlessPropResults = checkHeadlessInstanceProps(parsedFile.val, relativePath);
+      for (const msg of headlessPropResults) {
+        if (msg.includes("is missing required prop") || msg.includes("source phase must be")) {
+          errors.push({ file: relativePath, message: msg, stage: "generate" });
+        } else {
+          warnings.push({ file: relativePath, message: msg });
+        }
       }
       const fileCoverage = analyzeTagCoverage(parsedFile.val, relativePath);
       if (fileCoverage) {
         coverage.push(fileCoverage);
+        const allowedUnused = parsedFile.val.validationOverrides?.["jay-stack"]?.["allow-unused-tags"];
+        const allowedSet = new Set(Array.isArray(allowedUnused) ? allowedUnused : []);
+        for (const contract of fileCoverage.contracts) {
+          for (const tag of contract.requiredUnusedTags) {
+            const qualifiedTag = contract.key ? `${contract.key}.${tag}` : tag;
+            if (allowedSet.has(qualifiedTag) || allowedSet.has(tag)) continue;
+            const label = contract.key ? `${contract.key} (${contract.contractName})` : contract.contractName;
+            warnings.push({
+              file: relativePath,
+              message: `Required tag "${tag}" from contract "${label}" is not used in the template. Suppress with jay-stack: { allow-unused-tags: ["${qualifiedTag}"] } in <script type="application/jay-validations">. See agent-kit/designer/validation-guide.md`
+            });
+          }
+        }
       }
       const generatedFile = generateElementFile(
         parsedFile.val,
-        RuntimeMode.MainTrusted,
+        RuntimeMode$1.MainTrusted,
         GenerateTarget.jay
       );
       if (generatedFile.validations.length > 0) {
@@ -3394,8 +4836,8 @@ async function validateJayFiles(options = {}) {
       }
     }
   }
-  const robotsTxtPath = path.resolve(projectRoot, "public/robots.txt");
-  if (!fs.existsSync(robotsTxtPath)) {
+  const robotsTxtPath = path$1.resolve(projectRoot, "public/robots.txt");
+  if (!fs$1.existsSync(robotsTxtPath)) {
     warnings.push({
       file: "public/robots.txt",
       message: "public/robots.txt not found — search engines may crawl pages you don't intend to expose.",
@@ -3406,7 +4848,7 @@ async function validateJayFiles(options = {}) {
     warnings.push({
       file: ".jay",
       message: "site.baseUrl not configured — sitemap.xml will not be generated in production.",
-      suggestion: "Add to .jay config: site:\n  baseUrl: https://your-domain.com"
+      suggestion: "Add to .jay config:\n  site:\n    baseUrl: https://your-domain.com"
     });
   }
   const pluginValidators = await runPluginValidators(projectRoot, parsedFiles, errors, warnings);
@@ -3491,7 +4933,7 @@ function printJayValidationResult(result, options) {
       }
     }
   }
-  if (result.coverage.length > 0) {
+  if (options.verbose && result.coverage.length > 0) {
     logger.important("");
     logger.important(chalk.bold("📦 Tag Coverage"));
     for (const fileCov of result.coverage) {
@@ -3506,23 +4948,26 @@ function printJayValidationResult(result, options) {
             chalk.gray(`       Unused: ${contract.unusedTags.join(", ")}`)
           );
         }
-        if (contract.requiredUnusedTags.length > 0) {
-          logger.important(
-            chalk.yellow(
-              `       ⚠ Required unused: ${contract.requiredUnusedTags.join(", ")}`
-            )
-          );
-        }
       }
     }
   }
   logger.important("");
-  if (result.valid) {
+  if (result.valid && result.warnings.length === 0) {
     logger.important(chalk.green("Validation passed."));
+  } else if (result.valid) {
+    logger.important(
+      chalk.yellow(
+        `Validation passed with ${result.warnings.length} warning(s). Warnings must be fixed or explicitly suppressed — do not ignore them.`
+      )
+    );
   } else {
-    logger.important(chalk.red(`Validation failed — ${result.errors.length} error(s).`));
+    logger.important(
+      chalk.red(
+        `Validation failed — ${result.errors.length} error(s)` + (result.warnings.length > 0 ? `, ${result.warnings.length} warning(s). Errors must be fixed. Warnings must be fixed or explicitly suppressed.` : ".")
+      )
+    );
   }
-  const totalIssues = result.errors.length + result.warnings.length + result.coverage.length;
+  const totalIssues = result.errors.length + result.warnings.length;
   if (totalIssues > 0) {
     logger.important(
       chalk.gray(
@@ -3626,7 +5071,7 @@ async function runAgentKit(options) {
   }
 }
 async function runMaterialize(projectRoot, options, defaultOutputRelative, keepViteAlive = false) {
-  const outputDir = options.output ?? path$1.join(projectRoot, defaultOutputRelative);
+  const outputDir = options.output ?? path__default.join(projectRoot, defaultOutputRelative);
   let viteServer;
   let initErrors = /* @__PURE__ */ new Map();
   try {
@@ -3692,81 +5137,81 @@ Materialized ${totalContracts} contracts`));
   return { initErrors };
 }
 async function ensureAgentKitDocs(projectRoot, _force, mode) {
-  const agentKitDir = path$1.join(projectRoot, "agent-kit");
-  const thisDir = path$1.dirname(fileURLToPath(import.meta.url));
-  const templateDir = path$1.resolve(thisDir, "..", "agent-kit-template");
+  const agentKitDir = path__default.join(projectRoot, "agent-kit");
+  const thisDir = path__default.dirname(fileURLToPath(import.meta.url));
+  const templateDir = path__default.resolve(thisDir, "..", "agent-kit-template");
   const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
   for (const role of roles) {
-    const roleTemplateDir = path$1.join(templateDir, role);
-    const roleOutputDir = path$1.join(agentKitDir, role);
+    const roleTemplateDir = path__default.join(templateDir, role);
+    const roleOutputDir = path__default.join(agentKitDir, role);
     let files;
     try {
-      files = (await fs$1.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
+      files = (await fs$2.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
     } catch {
       continue;
     }
-    await fs$1.mkdir(roleOutputDir, { recursive: true });
+    await fs$2.mkdir(roleOutputDir, { recursive: true });
     for (const filename of files) {
-      await fs$1.copyFile(
-        path$1.join(roleTemplateDir, filename),
-        path$1.join(roleOutputDir, filename)
+      await fs$2.copyFile(
+        path__default.join(roleTemplateDir, filename),
+        path__default.join(roleOutputDir, filename)
       );
       getLogger().info(chalk.gray(`   Created agent-kit/${role}/${filename}`));
     }
   }
-  const topLevelFiles = (await fs$1.readdir(templateDir)).filter((f) => f.endsWith(".md"));
+  const topLevelFiles = (await fs$2.readdir(templateDir)).filter((f) => f.endsWith(".md"));
   for (const filename of topLevelFiles) {
-    await fs$1.copyFile(path$1.join(templateDir, filename), path$1.join(agentKitDir, filename));
+    await fs$2.copyFile(path__default.join(templateDir, filename), path__default.join(agentKitDir, filename));
     getLogger().info(chalk.gray(`   Created agent-kit/${filename}`));
   }
   const sharedDirs = ["contracts"];
   for (const dir of sharedDirs) {
-    const srcDir = path$1.join(templateDir, dir);
-    if (!fsSync.existsSync(srcDir)) continue;
-    await copyDirRecursive(srcDir, path$1.join(agentKitDir, dir));
+    const srcDir = path__default.join(templateDir, dir);
+    if (!fs__default.existsSync(srcDir)) continue;
+    await copyDirRecursive(srcDir, path__default.join(agentKitDir, dir));
     getLogger().info(chalk.gray(`   Created agent-kit/${dir}/`));
   }
 }
 async function copyDirRecursive(src, dest) {
-  await fs$1.mkdir(dest, { recursive: true });
-  const entries = await fs$1.readdir(src, { withFileTypes: true });
+  await fs$2.mkdir(dest, { recursive: true });
+  const entries = await fs$2.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path$1.join(src, entry.name);
-    const destPath = path$1.join(dest, entry.name);
+    const srcPath = path__default.join(src, entry.name);
+    const destPath = path__default.join(dest, entry.name);
     if (entry.isDirectory()) {
       await copyDirRecursive(srcPath, destPath);
     } else if (entry.name.endsWith(".md")) {
-      await fs$1.copyFile(srcPath, destPath);
+      await fs$2.copyFile(srcPath, destPath);
     }
   }
 }
 async function mergePluginAgentKitGuides(projectRoot, mode) {
   const plugins = await scanPlugins({ projectRoot, includeDevDeps: true });
-  const agentKitDir = path$1.join(projectRoot, "agent-kit");
+  const agentKitDir = path__default.join(projectRoot, "agent-kit");
   const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
   const copiedPerRole = /* @__PURE__ */ new Map();
   for (const [, plugin] of plugins) {
-    const pluginAgentKitDir = path$1.join(plugin.pluginPath, "agent-kit");
-    if (!fsSync.existsSync(pluginAgentKitDir)) continue;
+    const pluginAgentKitDir = path__default.join(plugin.pluginPath, "agent-kit");
+    if (!fs__default.existsSync(pluginAgentKitDir)) continue;
     for (const role of roles) {
-      const roleSourceDir = path$1.join(pluginAgentKitDir, role);
+      const roleSourceDir = path__default.join(pluginAgentKitDir, role);
       let files;
       try {
-        files = (await fs$1.readdir(roleSourceDir)).filter(
+        files = (await fs$2.readdir(roleSourceDir)).filter(
           (f) => f.endsWith(".md") && f !== "INSTRUCTIONS.md"
         );
       } catch {
         continue;
       }
       if (files.length === 0) continue;
-      const roleOutputDir = path$1.join(agentKitDir, role);
-      await fs$1.mkdir(roleOutputDir, { recursive: true });
+      const roleOutputDir = path__default.join(agentKitDir, role);
+      await fs$2.mkdir(roleOutputDir, { recursive: true });
       for (const filename of files) {
-        const sourcePath = path$1.join(roleSourceDir, filename);
-        await fs$1.copyFile(sourcePath, path$1.join(roleOutputDir, filename));
+        const sourcePath = path__default.join(roleSourceDir, filename);
+        await fs$2.copyFile(sourcePath, path__default.join(roleOutputDir, filename));
         let description = "";
         try {
-          const content = await fs$1.readFile(sourcePath, "utf-8");
+          const content = await fs$2.readFile(sourcePath, "utf-8");
           const lines = content.split("\n");
           let pastHeading = false;
           for (const line of lines) {
@@ -3792,8 +5237,8 @@ async function mergePluginAgentKitGuides(projectRoot, mode) {
     }
   }
   for (const [role, entries] of copiedPerRole) {
-    const instructionsPath = path$1.join(agentKitDir, role, "INSTRUCTIONS.md");
-    if (!fsSync.existsSync(instructionsPath)) continue;
+    const instructionsPath = path__default.join(agentKitDir, role, "INSTRUCTIONS.md");
+    if (!fs__default.existsSync(instructionsPath)) continue;
     const lines = [
       "",
       "## Plugin-Contributed Guides",
@@ -3805,11 +5250,10 @@ async function mergePluginAgentKitGuides(projectRoot, mode) {
       lines.push(`| [${filename}](${filename}) | ${pluginName} | ${description} |`);
     }
     lines.push("");
-    await fs$1.appendFile(instructionsPath, lines.join("\n"));
+    await fs$2.appendFile(instructionsPath, lines.join("\n"));
   }
 }
 async function generatePluginAgentKit(projectRoot, options, initErrors, viteServer) {
-  const { discoverPluginsWithAgentKit, executePluginAgentKit } = await import("@jay-framework/stack-server-runtime");
   const plugins = await discoverPluginsWithAgentKit({
     projectRoot,
     verbose: options.verbose,
@@ -3882,7 +5326,6 @@ async function runAction(actionRef, options, projectRoot, initializeServices) {
     }
     viteServer = await createViteForCli({ projectRoot });
     await initializeServices(projectRoot, viteServer);
-    const { discoverAndRegisterActions, discoverAllPluginActions, ActionRegistry } = await import("@jay-framework/stack-server-runtime");
     const registry = new ActionRegistry();
     await discoverAndRegisterActions({
       projectRoot,
@@ -3994,8 +5437,8 @@ async function runParams(contractRef, options, projectRoot, initializeServices)
       );
       process.exit(1);
     }
-    const { resolveServices } = await import("@jay-framework/stack-server-runtime");
-    const resolvedServices = resolveServices(component.services || []);
+    const { resolveServices: resolveServices2 } = await import("@jay-framework/stack-server-runtime");
+    const resolvedServices = resolveServices2(component.services || []);
     const paramsGenerator = component.loadParams(resolvedServices);
     let total = 0;
     for await (const batch of paramsGenerator) {
@@ -4089,7 +5532,7 @@ async function runSetup(pluginFilter, options, projectRoot) {
   try {
     const logger = getLogger();
     const jayConfig = loadConfig();
-    const configDir = path$1.resolve(projectRoot, jayConfig.devServer?.configBase || "./config");
+    const configDir = path__default.resolve(projectRoot, jayConfig.devServer?.configBase || "./config");
     logger.important(chalk.bold("\n🔧 Setting up plugins...\n"));
     if (options.verbose) {
       logger.info("Starting Vite for TypeScript support...");
@@ -4121,7 +5564,7 @@ async function runSetup(pluginFilter, options, projectRoot) {
     const interactive = options.interactive === true;
     let answersMap;
     if (options.answers) {
-      answersMap = YAML.parse(fsSync.readFileSync(options.answers, "utf-8")) || {};
+      answersMap = YAML.parse(fs__default.readFileSync(options.answers, "utf-8")) || {};
     }
     let configured = 0;
     let needsConfig = 0;
@@ -4248,12 +5691,12 @@ async function initPlugin(pluginName, allPluginsWithInit, viteServer, logger) {
 }
 async function runProjectInit(projectRoot, viteServer) {
   try {
-    const initPathTs = path$1.join(projectRoot, "src", "init.ts");
-    const initPathJs = path$1.join(projectRoot, "src", "init.js");
+    const initPathTs = path__default.join(projectRoot, "src", "init.ts");
+    const initPathJs = path__default.join(projectRoot, "src", "init.js");
     let initModule;
-    if (fsSync.existsSync(initPathTs) && viteServer) {
+    if (fs__default.existsSync(initPathTs) && viteServer) {
       initModule = await viteServer.ssrLoadModule(initPathTs);
-    } else if (fsSync.existsSync(initPathJs)) {
+    } else if (fs__default.existsSync(initPathJs)) {
       initModule = await import(initPathJs);
     }
     if (initModule?.init?._serverInit) {
@@ -4266,12 +5709,6 @@ async function runProjectInit(projectRoot, viteServer) {
 async function runCommand(commandRef, rawArgs, options, projectRoot, initializeServices) {
   let viteServer;
   try {
-    const {
-      discoverPluginCommands,
-      commandSchemaToFlags,
-      parseInputFromFlags,
-      executePluginCommand
-    } = await import("@jay-framework/stack-server-runtime");
     const commands = await discoverPluginCommands({
       projectRoot,
       verbose: options.verbose
@@ -4327,21 +5764,19 @@ async function runCommand(commandRef, rawArgs, options, projectRoot, initializeS
     }
     viteServer = await createViteForCli({ projectRoot });
     await initializeServices(projectRoot, viteServer);
-    const { registerService } = await import("@jay-framework/stack-server-runtime");
-    const { CONSOLE_CONTEXT } = await import("@jay-framework/fullstack-component");
     const jayConfig = loadConfig();
-    const publicFolder = path$1.resolve(
+    const publicFolder = path__default.resolve(
       projectRoot,
       jayConfig.devServer?.publicFolder || "public"
     );
     const version = await resolveVersionFromPackageJson(projectRoot);
-    const buildRoot = path$1.resolve(projectRoot, `build/v${version}`);
+    const buildRoot = path__default.resolve(projectRoot, `build/v${version}`);
     registerService(CONSOLE_CONTEXT, {
       projectRoot,
       publicFolder,
       build: {
-        frontend: path$1.join(buildRoot, "frontend"),
-        backend: path$1.join(buildRoot, "backend")
+        frontend: path__default.join(buildRoot, "frontend"),
+        backend: path__default.join(buildRoot, "backend")
       },
       verbose: options.verbose ?? false,
       log: (msg) => getLogger().important(msg),
@@ -4515,9 +5950,9 @@ if (!process.argv.slice(2).length) {
 }
 export {
   getConfigWithDefaults,
-  listContracts2 as listContracts,
+  listContracts,
   loadConfig,
-  materializeContracts2 as materializeContracts,
+  materializeContracts,
   startDevServer,
   updateConfig
 };