@jay-framework/jay-stack-cli 0.18.0 → 0.18.2

package/agent-kit-template/developer/cli-commands.md

@@ -93,6 +93,8 @@ Errors:
 1 error(s) found, 7 file(s) valid.
 ```
 
+Plugins can provide custom validators that run as part of `jay-stack validate`. Plugin findings include a suggestion field with fix instructions. See the plugin [validation.md](../plugin/validation.md) guide.
+
 Always run validate after creating or editing jay-html and contract files.
 
 ## jay-stack params

package/agent-kit-template/plugin/INSTRUCTIONS.md

@@ -34,7 +34,7 @@ A plugin provides headless components (data + interactions, no UI) that project
 | [plugin-routes.md](plugin-routes.md)             | Plugin-provided pages: routes, jay-html templates, page components      |
 | [seo-guide.md](seo-guide.md)                     | SEO head tags: title, meta, OG, canonical via phaseOutput               |
 | [commands-guide.md](commands-guide.md)           | makeCliCommand, .jay-command files, CONSOLE_CONTEXT, jay-stack run      |
-| [validation.md](validation.md)                   | jay-stack validate-plugin usage                                         |
+| [validation.md](validation.md)                   | jay-stack validate-plugin, writing custom jay-html validators           |
 | [dev-server-service.md](dev-server-service.md)   | Dev server service API: routes, params, freeze management               |
 | `../references/<plugin>/`                        | Plugin reference data                                                   |
 

package/agent-kit-template/plugin/contracts-guide.md

@@ -190,6 +190,21 @@ name: product-search
 description: Product listing with filters, sorting, and pagination. Use for search results and category pages.
 ```
 
+## Tag Metadata
+
+Tags can carry a `meta` field — a free-form key-value map for plugin validators. The framework ignores `meta`; only validators read it.
+
+```yaml
+- tag: heroImage
+  type: data
+  dataType: string
+  meta:
+    vendor: wix-image
+    defaultTransform: w_800,h_400,q_80
+```
+
+Use `meta` to attach semantic meaning that goes beyond the data type — e.g., marking a `string` tag as a URL that requires specific formatting. See [validation.md](validation.md) for writing validators that consume `meta`.
+
 ## Validation Rules
 
 - Tag names must be unique at each level

package/agent-kit-template/plugin/plugin-structure.md

@@ -61,6 +61,11 @@ commands:
   - name: sync-catalog
     command: commands/sync-catalog.jay-command
 
+validators:
+  - name: media-optimization
+    handler: ./validators/media-validator
+    description: Ensures media URLs use resize parameters
+
 setup:
   handler: setup-handler
   references: references-handler
@@ -185,6 +190,14 @@ Plugin routes are served by the dev server alongside project routes. If a projec
 
 Commands are CLI operations run via `jay-stack run`. Use `makeCliCommand()` to create handlers with service injection. See [commands-guide.md](commands-guide.md).
 
+### Validator Entry Fields
+
+- `name` — Validator name (shown in validation output as `plugin-name/validator-name`)
+- `handler` — Relative path to the validator module (must export a `validate` function)
+- `description` — (optional) What this validator checks
+
+Validators run during `jay-stack validate` against every parsed jay-html file. The handler module exports a `validate` function that receives a `JayHtmlValidationContext` and returns an array of findings. See [validation.md](validation.md) for implementation details.
+
 ### Setup Fields
 
 - `handler` — Setup handler for `jay-stack setup` (handles config, credentials)
@@ -210,6 +223,8 @@ my-plugin/
 │   │   └── upload-public.jay-command
 │   ├── webhooks/
 │   │   └── on-product-change.ts
+│   ├── validators/
+│   │   └── media-validator.ts
 │   ├── components/
 │   │   ├── product-page.ts
 │   │   └── product-search.ts

package/agent-kit-template/plugin/validation.md

@@ -99,3 +99,93 @@ component: ./lib/components/product-page.ts
 # Right
 component: productPage
 ```
+
+## Plugin Validators
+
+Plugins can provide custom jay-html validation rules that run during `jay-stack validate`. Declare validators in `plugin.yaml`:
+
+```yaml
+validators:
+  - name: media-optimization
+    handler: ./validators/media-validator
+    description: Ensures media URLs use resize parameters
+```
+
+### Writing a Validator
+
+The handler module exports a `validate` function:
+
+```typescript
+import type { JayHtmlValidatorFn, JayHtmlValidationFinding } from '@jay-framework/compiler-shared';
+
+export const validate: JayHtmlValidatorFn = (ctx) => {
+  const findings: JayHtmlValidationFinding[] = [];
+
+  // ctx.body — parsed DOM tree (HTMLElement from node-html-parser)
+  // ctx.filePath — relative path to the jay-html file
+  // ctx.contract — page contract (if any), with tags including meta
+  // ctx.headlessImports — headless components used in this file
+  // ctx.projectRoot — absolute project root path
+
+  return findings;
+};
+```
+
+Each finding has:
+
+- `severity` — `'error'` (fails validation) or `'warning'`
+- `message` — what's wrong
+- `suggestion` — how to fix it (shown to agents and developers)
+- `element` — (optional) which element
+- `attribute` — (optional) which attribute
+
+### Validator Utilities
+
+- **`parseTemplateParts(value)`** — split `"{url}/v1/fit/w_300/file.jpg"` into binding and static parts (import from `@jay-framework/compiler-jay-html`)
+- **`walkElements(root, ctx, visitor)`** — depth-first traversal tracking data scope through `forEach` and `<jay:component>` boundaries (import from `@jay-framework/compiler-shared`)
+- **`resolveBinding(path, scope)`** — resolve a binding path to its contract tag (including `meta`) (import from `@jay-framework/compiler-shared`)
+
+### Contract Tag `meta`
+
+Contract tags can carry a `meta` field — arbitrary key-value metadata that validators read:
+
+```yaml
+tags:
+  - tag: imageUrl
+    type: data
+    dataType: string
+    meta:
+      vendor: wix-image
+      defaultTransform: w_300,h_200,q_80
+```
+
+Validators use `resolveBinding` to find the tag and inspect `meta`:
+
+```typescript
+import { walkElements, resolveBinding } from '@jay-framework/compiler-shared';
+import { parseTemplateParts } from '@jay-framework/compiler-jay-html';
+
+export const validate: JayHtmlValidatorFn = (ctx) => {
+  const findings: JayHtmlValidationFinding[] = [];
+
+  walkElements(ctx.body, ctx, (el, scope) => {
+    if (el.rawTagName !== 'img') return;
+    const src = el.getAttribute('src');
+    if (!src) return;
+
+    for (const part of parseTemplateParts(src)) {
+      if (part.kind !== 'binding') continue;
+      const resolved = resolveBinding(part.value, scope);
+      if (resolved.tag?.meta?.vendor !== 'wix-image') continue;
+
+      findings.push({
+        severity: 'warning',
+        message: `Image binding {${part.value}} may need resize parameters`,
+        suggestion: 'Add /v1/fit/w_{WIDTH},h_{HEIGHT},q_80/file.jpg after the binding',
+      });
+    }
+  });
+
+  return findings;
+};
+```

package/dist/index.js

@@ -10,7 +10,7 @@ import YAML from "yaml";
 import { getLogger, setDevLogger, createDevLogger } from "@jay-framework/logger";
 import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, ContractTagType, parseContract, generateElementFile, generateServerElementFile, htmlElementTagNameMap } from "@jay-framework/compiler-jay-html";
 import { JAY_CONTRACT_EXTENSION, JAY_EXTENSION, resolvePluginManifest, LOCAL_PLUGIN_PATH, JayAtomicType, JayEnumType, loadPluginManifest, RuntimeMode, GenerateTarget } from "@jay-framework/compiler-shared";
-import { listContracts, materializeContracts, scanPlugins as scanPlugins$1 } from "@jay-framework/stack-server-runtime";
+import { scanPlugins as scanPlugins$1, listContracts, materializeContracts } from "@jay-framework/stack-server-runtime";
 import { listContracts as listContracts2, materializeContracts as materializeContracts2 } from "@jay-framework/stack-server-runtime";
 import { Command } from "commander";
 import chalk from "chalk";
@@ -3358,6 +3358,46 @@ async function validateSchema(context, result) {
       });
     }
   }
+  if (manifest.validators) {
+    if (!Array.isArray(manifest.validators)) {
+      result.errors.push({
+        type: "schema",
+        message: 'Field "validators" must be an array',
+        location: "plugin.yaml"
+      });
+    } else {
+      manifest.validators.forEach((validator, index) => {
+        if (!validator.name) {
+          result.errors.push({
+            type: "schema",
+            message: `Validator at index ${index} is missing "name" field`,
+            location: "plugin.yaml"
+          });
+        }
+        if (!validator.handler) {
+          result.errors.push({
+            type: "schema",
+            message: `Validator "${validator.name || index}" is missing "handler" field`,
+            location: "plugin.yaml",
+            suggestion: "Specify the relative path to the validator handler module"
+          });
+        }
+        if (validator.handler && !context.isNpmPackage) {
+          const handlerPath = path.join(context.pluginPath, validator.handler);
+          const extensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
+          const found = extensions.some((ext) => fs.existsSync(handlerPath + ext));
+          if (!found) {
+            result.errors.push({
+              type: "file-missing",
+              message: `Validator "${validator.name}" handler not found: ${validator.handler}`,
+              location: "plugin.yaml validators",
+              suggestion: `Create the validator handler at ${handlerPath}.ts`
+            });
+          }
+        }
+      });
+    }
+  }
 }
 function resolveContractFile(contractSpec, context) {
   if (context.isNpmPackage) {
@@ -4226,6 +4266,88 @@ function checkHeadlessInstanceProps(jayHtml, file) {
   walkElement(jayHtml.body);
   return warnings;
 }
+async function runPluginValidators(projectRoot, parsedFiles, errors, warnings) {
+  const scannedPlugins = await scanPlugins$1({ projectRoot });
+  for (const [, plugin] of scannedPlugins) {
+    if (!plugin.manifest.validators)
+      continue;
+    for (const validatorDef of plugin.manifest.validators) {
+      let validatorFn;
+      try {
+        const handlerPath = path.resolve(plugin.pluginPath, validatorDef.handler);
+        const handlerModule = await import(handlerPath);
+        validatorFn = handlerModule.validate;
+        if (typeof validatorFn !== "function") {
+          errors.push({
+            file: `plugin:${plugin.name}`,
+            message: `Validator "${validatorDef.name}" handler does not export a "validate" function`,
+            stage: "plugin"
+          });
+          continue;
+        }
+      } catch (loadErr) {
+        errors.push({
+          file: `plugin:${plugin.name}`,
+          message: `Failed to load validator "${validatorDef.name}": ${loadErr.message}`,
+          stage: "plugin"
+        });
+        continue;
+      }
+      const source = `${plugin.name}/${validatorDef.name}`;
+      for (const { relativePath, parsed } of parsedFiles) {
+        const ctx = {
+          filePath: relativePath,
+          body: parsed.body,
+          contract: parsed.contract ? {
+            name: parsed.contract.name,
+            tags: parsed.contract.tags,
+            props: parsed.contract.props,
+            params: parsed.contract.params
+          } : void 0,
+          headlessImports: parsed.headlessImports.map((imp) => ({
+            key: imp.key,
+            contractName: imp.contractName,
+            contract: imp.contract ? {
+              name: imp.contract.name,
+              tags: imp.contract.tags,
+              props: imp.contract.props,
+              params: imp.contract.params
+            } : void 0
+          })),
+          projectRoot
+        };
+        try {
+          const findings = await validatorFn(ctx);
+          for (const finding of findings) {
+            if (finding.severity === "error") {
+              errors.push({
+                file: relativePath,
+                message: finding.message,
+                stage: "plugin",
+                source,
+                suggestion: finding.suggestion
+              });
+            } else {
+              warnings.push({
+                file: relativePath,
+                message: finding.message,
+                source,
+                suggestion: finding.suggestion
+              });
+            }
+          }
+        } catch (runErr) {
+          errors.push({
+            file: relativePath,
+            message: `Validator "${source}" threw: ${runErr.message}`,
+            stage: "plugin",
+            source
+          });
+        }
+      }
+    }
+  }
+}
 async function validateJayFiles(options = {}) {
   const config = loadConfig();
   const resolvedConfig = getConfigWithDefaults(config);
@@ -4234,6 +4356,7 @@ async function validateJayFiles(options = {}) {
   const errors = [];
   const warnings = [];
   const coverage = [];
+  const parsedFiles = [];
   const jayHtmlFiles = await findJayFiles(scanDir);
   const contractFiles = await findContractFiles(scanDir);
   if (options.verbose) {
@@ -4299,6 +4422,7 @@ async function validateJayFiles(options = {}) {
         }
         continue;
       }
+      parsedFiles.push({ relativePath, parsed: parsedFile.val });
       const routeParamWarnings = checkRouteParams(parsedFile.val, jayFile, scanDir, content);
       for (const msg of routeParamWarnings) {
         warnings.push({ file: relativePath, message: msg });
@@ -4363,6 +4487,7 @@ async function validateJayFiles(options = {}) {
       }
     }
   }
+  await runPluginValidators(projectRoot, parsedFiles, errors, warnings);
   return {
     valid: errors.length === 0,
     jayHtmlFilesScanned: jayHtmlFiles.length,
@@ -4389,8 +4514,12 @@ function printJayValidationResult(result, options) {
     logger.important(chalk.red("❌ Jay Stack validation failed\n"));
     logger.important("Errors:");
     for (const error of result.errors) {
+      const prefix = error.source ? `[${error.source}] ` : "";
       logger.important(chalk.red(`  ❌ ${error.file}`));
-      logger.important(chalk.gray(`     ${error.message}`));
+      logger.important(chalk.gray(`     ${prefix}${error.message}`));
+      if (error.suggestion) {
+        logger.important(chalk.blue(`     Suggestion: ${error.suggestion}`));
+      }
       logger.important("");
     }
     const validFiles = result.jayHtmlFilesScanned + result.contractFilesScanned - result.errors.length;
@@ -4402,8 +4531,12 @@ function printJayValidationResult(result, options) {
     logger.important("");
     logger.important(chalk.yellow("Warnings:"));
     for (const warning of result.warnings) {
+      const prefix = warning.source ? `[${warning.source}] ` : "";
       logger.important(chalk.yellow(`  ⚠ ${warning.file}`));
-      logger.important(chalk.gray(`    ${warning.message}`));
+      logger.important(chalk.gray(`    ${prefix}${warning.message}`));
+      if (warning.suggestion) {
+        logger.important(chalk.blue(`    Suggestion: ${warning.suggestion}`));
+      }
       logger.important("");
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -24,15 +24,15 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.18.0",
-    "@jay-framework/compiler-shared": "^0.18.0",
-    "@jay-framework/dev-server": "^0.18.0",
-    "@jay-framework/editor-server": "^0.18.0",
-    "@jay-framework/fullstack-component": "^0.18.0",
-    "@jay-framework/logger": "^0.18.0",
-    "@jay-framework/plugin-validator": "^0.18.0",
-    "@jay-framework/production-server": "^0.18.0",
-    "@jay-framework/stack-server-runtime": "^0.18.0",
+    "@jay-framework/compiler-jay-html": "^0.18.2",
+    "@jay-framework/compiler-shared": "^0.18.2",
+    "@jay-framework/dev-server": "^0.18.2",
+    "@jay-framework/editor-server": "^0.18.2",
+    "@jay-framework/fullstack-component": "^0.18.2",
+    "@jay-framework/logger": "^0.18.2",
+    "@jay-framework/plugin-validator": "^0.18.2",
+    "@jay-framework/production-server": "^0.18.2",
+    "@jay-framework/stack-server-runtime": "^0.18.2",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -43,7 +43,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.18.0",
+    "@jay-framework/dev-environment": "^0.18.2",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",