@jay-framework/plugin-validator 0.22.1 → 0.23.0

package/dist/index.d.ts

@@ -153,4 +153,28 @@ declare function lintAddMenuCatalog(items: AddMenuItem[], sourcePath: string): {
 /** Human-readable fix hints for validate-plugin output. */
 declare const ADD_MENU_VALIDATION_SUGGESTIONS: Record<string, string>;
 
-export { ADD_MENU_VALIDATION_SUGGESTIONS, type AddMenuBrowseSize, type AddMenuCatalogFile, type AddMenuCatalogLintWarning, type AddMenuInteraction, type AddMenuItem, type AddMenuPresentation, type AddMenuValidationError, type PluginContext, type ValidatePluginOptions, type ValidationError, type ValidationResult, type ValidationWarning, checkComponentPropsAndParams, lintAddMenuCatalog, validateAddMenuCatalogFile, validateAddMenuItem, validatePlugin };
+/**
+ * AIditor Project settings contribution schema (materialized YAML).
+ * Source of truth for plugin-validator and AIditor runtime discovery.
+ */
+type AiditorSettingsRequire = {
+    plugin: string;
+    status: 'configured';
+};
+type AiditorSettingsFile = {
+    label: string;
+    route: string;
+    pluginName?: string;
+    requires?: AiditorSettingsRequire[];
+};
+type AiditorSettingsValidationError = {
+    path: string;
+    message: string;
+    code?: string;
+};
+declare function validateAiditorSettingsFile(raw: unknown, sourcePath: string): {
+    file?: AiditorSettingsFile;
+    errors: AiditorSettingsValidationError[];
+};
+
+export { ADD_MENU_VALIDATION_SUGGESTIONS, type AddMenuBrowseSize, type AddMenuCatalogFile, type AddMenuCatalogLintWarning, type AddMenuInteraction, type AddMenuItem, type AddMenuPresentation, type AddMenuValidationError, type AiditorSettingsFile, type AiditorSettingsRequire, type AiditorSettingsValidationError, type PluginContext, type ValidatePluginOptions, type ValidationError, type ValidationResult, type ValidationWarning, checkComponentPropsAndParams, lintAddMenuCatalog, validateAddMenuCatalogFile, validateAddMenuItem, validateAiditorSettingsFile, validatePlugin };

package/dist/index.js

@@ -279,7 +279,7 @@ const FOLDER_PATH_MAX_SEGMENTS = 32;
 const BLOCKED_TAGS = /<\s*(script|iframe|object|embed)\b[^>]*>[\s\S]*?<\/\s*\1\s*>|<\s*(script|iframe|object|embed)\b[^>]*\/?>/gi;
 const EVENT_HANDLER_ATTR = /\s+on[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi;
 const JAVASCRIPT_URL = /\b(href|src|xlink:href)\s*=\s*("|')\s*javascript:/gi;
-function isRecord(value) {
+function isRecord$1(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function byteLengthUtf8(value) {
@@ -349,7 +349,7 @@ function optionalString(obj, field) {
 function validateInteraction(raw, itemPath, errors) {
   if (raw === void 0)
     return void 0;
-  if (!isRecord(raw)) {
+  if (!isRecord$1(raw)) {
     errors.push({
       path: itemPath,
       message: "interaction must be an object",
@@ -374,7 +374,7 @@ function validateInteraction(raw, itemPath, errors) {
 function validatePresentation(raw, itemPath, errors) {
   if (raw === void 0)
     return void 0;
-  if (!isRecord(raw)) {
+  if (!isRecord$1(raw)) {
     errors.push({
       path: itemPath,
       message: "presentation must be an object",
@@ -447,7 +447,7 @@ const BROWSE_SIZES = /* @__PURE__ */ new Set(["large", "medium", "small"]);
 function validateBrowse(raw, itemPath, errors) {
   if (raw === void 0)
     return void 0;
-  if (!isRecord(raw)) {
+  if (!isRecord$1(raw)) {
     errors.push({
       path: itemPath,
       message: "browse must be an object",
@@ -530,7 +530,7 @@ function validateFolderPath(raw, itemPath, errors) {
 }
 function validateAddMenuItem(raw, itemPath) {
   const errors = [];
-  if (!isRecord(raw)) {
+  if (!isRecord$1(raw)) {
     return {
       item: null,
       errors: [
@@ -581,7 +581,7 @@ function validateAddMenuItem(raw, itemPath) {
 }
 function validateAddMenuCatalogFile(raw, sourcePath) {
   const errors = [];
-  if (!isRecord(raw)) {
+  if (!isRecord$1(raw)) {
     return {
       file: null,
       errors: [
@@ -940,7 +940,7 @@ function suggestionForCode(code) {
     return `See ${CONTRIBUTOR_GUIDE} for schema and validation rules`;
   return ADD_MENU_VALIDATION_SUGGESTIONS[code] ?? `See ${CONTRIBUTOR_GUIDE} for schema and validation rules`;
 }
-function mapSchemaError(error, catalogPath) {
+function mapSchemaError$1(error, catalogPath) {
   const code = error.code ?? "catalog-validation-error";
   return {
     type: "add-menu-catalog",
@@ -1014,7 +1014,7 @@ async function validateAddMenuCatalogFileAtPath(catalogPath, relPath, result) {
     return;
   }
   const validated = validateAddMenuCatalogFile(parsed, relPath);
-  result.errors.push(...validated.errors.map((error) => mapSchemaError(error, relPath)));
+  result.errors.push(...validated.errors.map((error) => mapSchemaError$1(error, relPath)));
   if (!validated.file?.items.length) {
     return;
   }
@@ -1035,6 +1035,173 @@ async function validateAddMenuCatalog(context, result) {
     await validateAddMenuCatalogFileAtPath(catalogPath, relPath, result);
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseRequires(raw, filePath) {
+  const errors = [];
+  if (raw === void 0) {
+    return { requires: [], errors };
+  }
+  if (!Array.isArray(raw)) {
+    errors.push({
+      path: `${filePath}.requires`,
+      message: "requires must be an array",
+      code: "settings-requires-type"
+    });
+    return { requires: [], errors };
+  }
+  const requires = [];
+  raw.forEach((entry, index) => {
+    if (!isRecord(entry)) {
+      errors.push({
+        path: `${filePath}.requires[${index}]`,
+        message: "require entry must be an object",
+        code: "settings-require-shape"
+      });
+      return;
+    }
+    if (typeof entry.plugin !== "string" || !entry.plugin.trim()) {
+      errors.push({
+        path: `${filePath}.requires[${index}].plugin`,
+        message: "plugin is required",
+        code: "settings-require-plugin"
+      });
+      return;
+    }
+    if (entry.status !== "configured") {
+      errors.push({
+        path: `${filePath}.requires[${index}].status`,
+        message: 'status must be "configured"',
+        code: "settings-require-status"
+      });
+      return;
+    }
+    requires.push({ plugin: entry.plugin.trim(), status: "configured" });
+  });
+  return { requires, errors };
+}
+function validateAiditorSettingsFile(raw, sourcePath) {
+  const errors = [];
+  if (!isRecord(raw)) {
+    return {
+      errors: [
+        {
+          path: sourcePath,
+          message: "settings file must be a YAML object",
+          code: "settings-root-type"
+        }
+      ]
+    };
+  }
+  if (typeof raw.label !== "string" || !raw.label.trim()) {
+    errors.push({
+      path: `${sourcePath}.label`,
+      message: "label is required",
+      code: "settings-label"
+    });
+  }
+  if (typeof raw.route !== "string" || !raw.route.trim()) {
+    errors.push({
+      path: `${sourcePath}.route`,
+      message: "route is required",
+      code: "settings-route"
+    });
+  } else if (!raw.route.startsWith("/")) {
+    errors.push({
+      path: `${sourcePath}.route`,
+      message: "route must start with /",
+      code: "settings-route-format"
+    });
+  }
+  if (raw.pluginName !== void 0 && typeof raw.pluginName !== "string") {
+    errors.push({
+      path: `${sourcePath}.pluginName`,
+      message: "pluginName must be a string",
+      code: "settings-plugin-name-type"
+    });
+  }
+  const { requires, errors: requireErrors } = parseRequires(raw.requires, sourcePath);
+  errors.push(...requireErrors);
+  if (errors.length > 0) {
+    return { errors };
+  }
+  return {
+    file: {
+      label: raw.label.trim(),
+      route: raw.route.trim(),
+      ...typeof raw.pluginName === "string" && raw.pluginName.trim() ? { pluginName: raw.pluginName.trim() } : {},
+      ...requires.length > 0 ? { requires } : {}
+    },
+    errors: []
+  };
+}
+const AIDITOR_SETTINGS_TEMPLATE_REL_PATH = "agent-kit/aiditor/settings.template.yaml";
+function mapSchemaError(error, relPath) {
+  return {
+    type: "schema",
+    message: error.message,
+    location: error.path || relPath,
+    code: error.code
+  };
+}
+function validateSettingsTemplateAtPath(catalogPath, relPath, result, manifest) {
+  let parsed;
+  try {
+    parsed = YAML.parse(fs.readFileSync(catalogPath, "utf-8"));
+  } catch (err) {
+    result.errors.push({
+      type: "schema",
+      message: `Invalid YAML in ${relPath}: ${err instanceof Error ? err.message : String(err)}`,
+      location: relPath
+    });
+    return;
+  }
+  const validated = validateAiditorSettingsFile(parsed, relPath);
+  result.errors.push(...validated.errors.map((error) => mapSchemaError(error, relPath)));
+  if (!validated.file) {
+    return;
+  }
+  const routeEntry = manifest.routes?.find((route) => route.path === validated.file.route);
+  if (!routeEntry) {
+    result.warnings.push({
+      type: "schema",
+      message: `settings route "${validated.file.route}" is not declared in plugin.yaml routes[]`,
+      location: relPath,
+      code: "settings-route-missing",
+      suggestion: "Add a matching routes[] entry or fix the route in settings.template.yaml"
+    });
+  } else if (routeEntry.devOnly !== true) {
+    result.warnings.push({
+      type: "schema",
+      message: `settings route "${validated.file.route}" should declare devOnly: true on routes[]`,
+      location: "plugin.yaml routes",
+      code: "settings-route-dev-only",
+      suggestion: "Add devOnly: true when the settings page is dev-server tooling (see Design Log #171)"
+    });
+  }
+}
+async function validateAiditorSettings(context, result) {
+  const templatePath = path.join(context.pluginPath, AIDITOR_SETTINGS_TEMPLATE_REL_PATH);
+  if (!fs.existsSync(templatePath)) {
+    return;
+  }
+  validateSettingsTemplateAtPath(
+    templatePath,
+    AIDITOR_SETTINGS_TEMPLATE_REL_PATH,
+    result,
+    context.manifest
+  );
+  if (!context.manifest.agentkit) {
+    result.warnings.push({
+      type: "schema",
+      message: "Plugin ships agent-kit/aiditor/settings.template.yaml but has no agentkit handler",
+      location: "plugin.yaml",
+      code: "settings-missing-agentkit-handler",
+      suggestion: "Declare agentkit in plugin.yaml and materialize to agent-kit/aiditor/settings/<plugin>.yaml on jay-stack agent-kit — see agent-kit/plugin/aiditor-settings-guide.md"
+    });
+  }
+}
 async function validatePlugin(options = {}) {
   const pluginPath = options.pluginPath || process.cwd();
   if (options.local) {
@@ -1102,6 +1269,7 @@ async function validatePluginPackage(pluginPath, options) {
     await validateDynamicContracts(context, result);
   }
   await validateAddMenuCatalog(context, result);
+  await validateAiditorSettings(context, result);
   result.valid = result.errors.length === 0;
   return result;
 }
@@ -1411,6 +1579,13 @@ async function validateSchema(context, result) {
         if (route.css) {
           validateDocFile(route.css, `route "${route.path}" css`, context, result);
         }
+        if (route.devOnly !== void 0 && typeof route.devOnly !== "boolean") {
+          result.errors.push({
+            type: "schema",
+            message: `Route "${route.path}" devOnly must be a boolean`,
+            location: "plugin.yaml"
+          });
+        }
       });
     }
   }
@@ -1942,5 +2117,6 @@ export {
   lintAddMenuCatalog,
   validateAddMenuCatalogFile,
   validateAddMenuItem,
+  validateAiditorSettingsFile,
   validatePlugin
 };

package/package.json

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