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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "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.1",
+    "@jay-framework/compiler-shared": "^0.18.1",
+    "@jay-framework/dev-server": "^0.18.1",
+    "@jay-framework/editor-server": "^0.18.1",
+    "@jay-framework/fullstack-component": "^0.18.1",
+    "@jay-framework/logger": "^0.18.1",
+    "@jay-framework/plugin-validator": "^0.18.1",
+    "@jay-framework/production-server": "^0.18.1",
+    "@jay-framework/stack-server-runtime": "^0.18.1",
     "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.1",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",