@jay-framework/plugin-validator 0.24.2 → 0.24.3

package/dist/index.d.ts

@@ -18,7 +18,7 @@ interface ValidationResult {
     typesGenerated?: number;
 }
 interface ValidationError {
-    type: 'schema' | 'file-missing' | 'export-mismatch' | 'contract-invalid' | 'component-contract-mismatch' | 'type-generation-failed' | 'add-menu-catalog';
+    type: 'schema' | 'file-missing' | 'export-mismatch' | 'contract-invalid' | 'component-contract-mismatch' | 'type-generation-failed' | 'add-menu-catalog' | 'compiler-leak';
     message: string;
     location?: string;
     suggestion?: string;

package/dist/index.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import YAML from "yaml";
-import { loadPluginManifest } from "@jay-framework/compiler-shared";
+import { loadPluginManifest, normalizeActionEntry } from "@jay-framework/compiler-shared";
 import { parseContract } from "@jay-framework/compiler-jay-html";
 import { ts } from "@jay-framework/typescript-bridge";
 const FRAMEWORK_PROP_TYPES = /* @__PURE__ */ new Set(["PageProps", "RequestQuery"]);
@@ -1225,6 +1225,7 @@ async function validatePluginPackage(pluginPath, options) {
   }
   await validateAddMenuCatalog(context, result);
   await validateAiditorSettings(context, result);
+  validateNoCompilerLeak(context, result);
   result.valid = result.errors.length === 0;
   return result;
 }
@@ -1398,13 +1399,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)) {
@@ -1468,14 +1484,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(entry);
       if (exportName) {
         validateHandlerRef(
           exportName,
           `Action "${exportName}"`,
           "plugin.yaml actions",
           context,
-          result
+          result,
+          devOnly ? "./tools" : "."
         );
       }
     }
@@ -1520,7 +1544,8 @@ async function validateSchema(context, result) {
             `Route "${route.path}" component`,
             `plugin.yaml routes`,
             context,
-            result
+            result,
+            route.devOnly ? "./tools" : "."
           );
         }
         if (route.jayHtml) {
@@ -1574,7 +1599,8 @@ async function validateSchema(context, result) {
             `Validator "${validator.name}" handler`,
             "plugin.yaml validators",
             context,
-            result
+            result,
+            "./tools"
           );
         }
       });
@@ -1594,7 +1620,8 @@ async function validateSchema(context, result) {
         "Setup handler",
         "plugin.yaml setup",
         context,
-        result
+        result,
+        "./tools"
       );
     }
   }
@@ -1604,22 +1631,23 @@ async function validateSchema(context, result) {
       "Agent-kit handler",
       "plugin.yaml agentkit",
       context,
-      result
+      result,
+      "./tools"
     );
   }
 }
-function checkExportExists(exportName, context) {
+function checkExportExists(exportName, context, exportKey = ".") {
   const packageJsonPath = path.join(context.pluginPath, "package.json");
   if (!fs.existsSync(packageJsonPath)) return true;
   let mainPath;
   try {
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-    if (packageJson.exports?.["."]) {
-      const entry = packageJson.exports["."];
+    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 (!mainPath && packageJson.main) {
+    if (!mainPath && exportKey === "." && packageJson.main) {
       mainPath = path.join(context.pluginPath, packageJson.main);
     }
   } catch {
@@ -1641,7 +1669,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.join(context.pluginPath, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return void 0;
+  try {
+    const packageJson = JSON.parse(fs.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.join(context.pluginPath, entryPath || packageJson.main) : void 0;
+    return resolved && fs.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(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.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.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({
@@ -1650,12 +1734,13 @@ 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)) {
@@ -1929,11 +2014,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/plugin-validator",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Validation tool for Jay Stack plugins",
@@ -25,14 +25,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.24.2",
-    "@jay-framework/compiler-shared": "^0.24.2",
-    "@jay-framework/typescript-bridge": "^0.24.2",
+    "@jay-framework/compiler-jay-html": "^0.24.3",
+    "@jay-framework/compiler-shared": "^0.24.3",
+    "@jay-framework/typescript-bridge": "^0.24.3",
     "chalk": "^4.1.2",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.24.2",
+    "@jay-framework/dev-environment": "^0.24.3",
     "@types/node": "^22.15.21",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",