mikser-io-schemas 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Almero Digital Marketing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# mikser-io-schemas
+
+Zod schemas as entities for [mikser-io](https://github.com/almero-digital-marketing/mikser-io). Loads `.js` files from a `schemas/` folder, registers each as an entity in the catalog (`type: 'schema'`), and validates other entities against their declared schema during the lifecycle.
+
+Mirrors the layouts pattern: each file in the folder becomes one entity, content references a schema by name in front-matter, and the plugin handles validation transparently — the same way layouts handles auto-matching and rendering.
+
+## Why schemas as entities
+
+At agency-scale content sites, content shapes need to be:
+
+- **Discoverable** — the frontend, an admin UI, or an AI agent can query "what schemas exist?" via the api plugin and get back the field metadata, perfect for form generation.
+- **Versioned with the content** — schemas live as plain files in `schemas/`. Diffable, portable, takeable on day one and year ten (see ADR-0002 in mikser-io).
+- **Validated in the build** — a doc that doesn't fit its declared schema fails at build time, not at runtime in front of users.
+- **AI-friendly** — an agent reading `schemas/product.js` understands the shape of every product doc without ad-hoc inference.
+
+This plugin treats schemas the same way mikser treats layouts: file in a folder, entity in the catalog, plugin handles the rest.
+
+## Install
+
+```bash
+npm install mikser-io-schemas zod
+```
+
+`zod` is a peer dependency — bring your own version (`^3.0.0` or `^4.0.0`).
+
+## Configure
+
+```js
+// mikser.config.js
+export default {
+    plugins: ['documents', 'layouts', 'render-hbs', 'schemas'],
+
+    schemas: {
+        schemasFolder: 'schemas',        // default
+        extensions: ['js', 'mjs', 'cjs'], // default
+        validateOn: 'meta',              // 'meta' | 'entity' | 'content'; default 'meta'
+        strict: false,                   // throw on failure (default: warn)
+        match: entity => entity.meta?.schema ?? entity.meta?.type, // default resolver
+    },
+}
+```
+
+## Author a schema
+
+```js
+// schemas/article.js
+import { z } from 'zod'
+
+export default z.object({
+    title:    z.string().describe('Article title'),
+    summary:  z.string().describe('Short summary shown in cards and meta tags'),
+    date:     z.string(),
+    author:   z.string().optional(),
+    tags:     z.array(z.string()).optional(),
+    published: z.boolean().default(false),
+}).describe('A long-form article')
+```
+
+## Reference it from a document
+
+```yaml
+---
+schema: article
+title: Q2 product launch
+summary: A short summary of what shipped this quarter.
+date: 2026-04-15
+author: Mikser Team
+tags: [product, launch]
+published: true
+---
+
+Article body in markdown…
+```
+
+By default the plugin resolves the schema name from `meta.schema`, falling back to `meta.type`. So a document with `type: article` (and no explicit `meta.schema`) will validate against `schemas/article.js` automatically — exactly the way `meta.layout` auto-matches.
+
+## What gets validated
+
+The `validateOn` config decides what subject is passed to the schema:
+
+| `validateOn` | What gets `.safeParse(subject)`-ed |
+|---|---|
+| `'meta'` *(default)* | `entity.meta` — front-matter / structured fields. The common case. |
+| `'entity'` | the entire entity object (id, name, type, meta, content, …). Use when the schema describes the whole entity. |
+| `'content'` | `entity.content` — useful when content itself is structured (e.g. YAML in `.yml` documents). |
+
+Validation runs in `onProcess`, after the front-matter / yaml / aml parsers have populated `entity.meta`. Failures are reported with field paths:
+
+```
+Schema "article" failed for /documents/en/q2.md: title: Required; date: Invalid date
+```
+
+In `strict: true` mode the build halts on the first failure. Default (`strict: false`) logs a warning and continues — useful during a migration when not every document is conformant yet.
+
+## What the catalog stores
+
+Each schema becomes an entity with a JSON-serialisable description of its shape:
+
+```json
+{
+    "id": "/schemas/article",
+    "type": "schema",
+    "name": "article",
+    "format": "js",
+    "meta": {
+        "description": "A long-form article",
+        "shape": {
+            "type": "object",
+            "fields": {
+                "title":   { "type": "string",  "description": "Article title" },
+                "summary": { "type": "string",  "description": "Short summary shown in cards and meta tags" },
+                "date":    { "type": "string" },
+                "author":  { "type": "string",  "optional": true },
+                "tags":    { "type": "array", "items": { "type": "string" }, "optional": true },
+                "published": { "type": "boolean", "default": false }
+            }
+        }
+    }
+}
+```
+
+The runtime Zod object stays in process memory (exposed at `runtime.schemas` as a `Map` keyed by name). The catalog representation is *enough for discovery* — frontends, form builders, and AI tools can read field names, types, descriptions, and optional/default markers without re-importing the JS.
+
+For richer JSON Schema output (full constraints, refinements, conditional schemas) plug in [`zod-to-json-schema`](https://www.npmjs.com/package/zod-to-json-schema) at consume time — it's not built in to keep this plugin zero-extra-dep-at-runtime.
+
+## Querying schemas via the api plugin
+
+With `mikser-io` running `--server` and the api plugin configured:
+
+```bash
+curl http://localhost:3001/api/public/entities?type=schema
+```
+
+```json
+{
+    "items": [
+        {
+            "id": "/schemas/article",
+            "name": "article",
+            "type": "schema",
+            "meta": { "description": "...", "shape": { ... } }
+        }
+    ]
+}
+```
+
+A form builder reads this and renders fields automatically. An AI assistant reads it to understand what valid content for the site looks like.
+
+## Programmatic access
+
+Other plugins (or one-shot scripts) can pull a schema and use it:
+
+```js
+const { runtime } = await import('mikser-io')
+// after start():
+const article = runtime.schemas.get('article')
+article.parse(payload)  // throws on failure
+article.safeParse(payload).success  // boolean
+```
+
+## Watch mode
+
+Schema files hot-reload on save in `--watch` mode. The next process cycle re-validates every affected document against the new shape.
+
+## Hooks used
+
+| Hook | What it does |
+|---|---|
+| `onLoaded` | Resolves the schemas folder path |
+| `onLoad` | Scans the folder, imports each `.js` / `.mjs` / `.cjs`, registers entity + runtime Zod object |
+| `onProcess` | Iterates the journal, validates each CREATE / UPDATE against its declared schema |
+| `onSync` | Hot-reloads schema files on filesystem change in watch mode |
+
+## Limitations (worth knowing up front)
+
+- **`.refine()` / `.transform()` bodies aren't serialisable.** The catalog representation notes that an effect exists; the validation itself still runs because the runtime Zod object is the source of truth.
+- **Cross-schema references work via JS imports.** A `product` schema can import an `address` schema with normal ESM; load order doesn't matter because JS resolves references at runtime.
+- **Validation runs at `onProcess`.** This is after parsers populate `meta`, so default values from the front-matter / yaml plugin are visible. It is *before* render — so a render-time field that doesn't yet exist won't be checked.
+- **Strict mode halts the build.** Use it for production builds; use the default (warn) during migrations.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,211 @@
+// mikser-io-schemas
+//
+// Loads Zod schemas from a configurable folder, registers each as an
+// entity (type: 'schema') in the mikser catalog, and validates other
+// entities against their declared schema during onProcess.
+//
+// The runtime Zod objects live in process memory (exposed at
+// runtime.schemas — a Map keyed by name). The catalog holds a
+// JSON-serialisable shape description so frontends, form generators,
+// and AI tools can introspect without re-importing the JS.
+//
+// The file scanning, loading, hot-reload, and catalog registration
+// machinery is delegated to mikser-io's useSource helper. This plugin
+// only carries the schema-specific concerns: Zod introspection and
+// onProcess-time validation.
+
+import { pathToFileURL } from 'node:url'
+
+const DEFAULT_FOLDER = 'schemas'
+const DEFAULT_EXTENSIONS = ['js', 'mjs', 'cjs']
+
+export default (core) => {
+    const { runtime, useSource, onProcess, useLogger, useJournal, constants: { OPERATION } } = core
+
+    // Per-name registry of live Zod objects. Exposed on `runtime.schemas`
+    // so other plugins (an editor UI, the api plugin's POST handlers)
+    // can pull a schema and use it for ad-hoc validation.
+    const schemas = new Map()
+    runtime.schemas = schemas
+
+    useSource(core, {
+        collection: 'schemas',
+        type: 'schema',
+        folder: runtime.config?.schemas?.schemasFolder ?? DEFAULT_FOLDER,
+        extensions: runtime.config?.schemas?.extensions ?? DEFAULT_EXTENSIONS,
+        stripExtensionFromId: true, // /schemas/article rather than /schemas/article.js
+        load: async ({ file, name }) => {
+            // Cache-bust on reload so a changed file actually re-imports.
+            // Node's ESM loader caches by URL; appending a query string
+            // forces a fresh module evaluation.
+            const url = `${pathToFileURL(file).href}?t=${Date.now()}`
+            const mod = await import(url)
+            const schema = mod.default ?? mod.schema
+
+            if (!isZodSchema(schema)) {
+                useLogger().warn('Schema %s does not export a Zod schema as default; skipping', file)
+                return null
+            }
+
+            schemas.set(name, schema)
+            return {
+                meta: {
+                    description: schema.description ?? undefined,
+                    shape: introspect(schema),
+                },
+            }
+        },
+    })
+
+    onProcess(async (signal) => {
+        const logger = useLogger()
+        const config = runtime.config?.schemas ?? {}
+        const resolveName = config.match ?? defaultMatch
+        const strict = config.strict === true
+        const validateOn = config.validateOn ?? 'meta'
+
+        for await (const { entity } of useJournal(
+            'Schema validation',
+            [OPERATION.CREATE, OPERATION.UPDATE],
+            signal,
+        )) {
+            if (entity.type === 'schema') continue // schemas don't validate themselves
+
+            const schemaName = resolveName(entity)
+            if (!schemaName) continue
+
+            const schema = schemas.get(schemaName)
+            if (!schema) {
+                logger.trace('Schema %s not found for %s', schemaName, entity.id)
+                continue
+            }
+
+            const subject = validateOn === 'entity'
+                ? entity
+                : validateOn === 'content'
+                    ? entity.content
+                    : entity.meta ?? {}
+
+            const result = schema.safeParse(subject)
+            if (result.success) {
+                logger.trace('Schema %s OK: %s', schemaName, entity.id)
+                continue
+            }
+
+            const issues = result.error.issues ?? result.error.errors ?? []
+            const message = issues
+                .map(i => `${(i.path ?? []).join('.') || '(root)'}: ${i.message}`)
+                .join('; ')
+            const summary = `Schema "${schemaName}" failed for ${entity.id}: ${message}`
+
+            if (strict) {
+                throw new Error(summary)
+            } else {
+                logger.warn(summary)
+            }
+        }
+    })
+}
+
+// --------------------------------------------------------------------
+// Helpers
+// --------------------------------------------------------------------
+
+function defaultMatch(entity) {
+    return entity.meta?.schema ?? entity.meta?.type
+}
+
+function isZodSchema(value) {
+    return value
+        && typeof value === 'object'
+        && typeof value.safeParse === 'function'
+        && typeof value.parse === 'function'
+}
+
+// Normalise the Zod-version-specific type tag.
+//
+//   Zod 3: _def.typeName = 'ZodObject', 'ZodString', ...
+//   Zod 4: _def.type     = 'object',    'string',    ...
+//
+// We collapse both to a lowercase, un-prefixed string so the switch
+// below works on either version.
+function zodKind(def) {
+    if (!def) return 'unknown'
+    if (typeof def.typeName === 'string') return def.typeName.replace(/^Zod/, '').toLowerCase()
+    if (typeof def.type === 'string') return def.type.toLowerCase()
+    return 'unknown'
+}
+
+// Walk a Zod schema and produce a JSON-serialisable shape description.
+// Covers the common Zod types in v3 and v4; falls back to a generic
+// { type: '...' } for anything else. Frontends and AI tools can read
+// this directly; for richer output use a real Zod → JSON-Schema
+// converter at consume time.
+function introspect(schema) {
+    if (!schema || typeof schema !== 'object') return { type: 'unknown' }
+    const def = schema._def
+    if (!def) return { type: 'unknown' }
+
+    const description = def.description ?? schema.description
+    const wrap = (out) => description ? { ...out, description } : out
+
+    const kind = zodKind(def)
+
+    switch (kind) {
+        case 'object': {
+            const fields = {}
+            const shape =
+                typeof schema.shape === 'function' ? schema.shape() :
+                schema.shape ??
+                (typeof def.shape === 'function' ? def.shape() : def.shape)
+            for (const [key, fieldSchema] of Object.entries(shape ?? {})) {
+                fields[key] = introspect(fieldSchema)
+            }
+            return wrap({ type: 'object', fields })
+        }
+        case 'string':   return wrap({ type: 'string' })
+        case 'number':   return wrap({ type: 'number' })
+        case 'boolean':  return wrap({ type: 'boolean' })
+        case 'date':     return wrap({ type: 'date' })
+        case 'bigint':   return wrap({ type: 'bigint' })
+        case 'literal':  return wrap({ type: 'literal', value: def.value })
+        case 'enum':
+        case 'nativeenum': {
+            const raw = def.values ?? def.entries ?? {}
+            const values = Array.isArray(raw) ? raw : Object.values(raw)
+            return wrap({ type: 'enum', values })
+        }
+        case 'array': {
+            const items = introspect(def.element ?? def.type)
+            return wrap({ type: 'array', items })
+        }
+        case 'tuple':
+            return wrap({ type: 'tuple', items: (def.items ?? []).map(introspect) })
+        case 'union':
+        case 'discriminatedunion':
+            return wrap({ type: 'union', options: (def.options ?? []).map(introspect) })
+        case 'record':
+            return wrap({ type: 'record', values: introspect(def.valueType ?? def.value) })
+        case 'optional':
+            return { ...introspect(def.innerType), optional: true }
+        case 'nullable':
+            return { ...introspect(def.innerType), nullable: true }
+        case 'default': {
+            // v3: defaultValue is a thunk returning the default.
+            // v4: defaultValue is the value itself.
+            const def_ = typeof def.defaultValue === 'function' ? def.defaultValue() : def.defaultValue
+            return { ...introspect(def.innerType), default: def_ }
+        }
+        case 'any':      return wrap({ type: 'any' })
+        case 'unknown':  return wrap({ type: 'unknown' })
+        case 'null':     return wrap({ type: 'null' })
+        case 'effects':
+        case 'pipe':
+        case 'pipeline': {
+            const inner = introspect(def.schema ?? def.in ?? def.innerType)
+            return { ...inner, effect: def.effect?.type ?? kind }
+        }
+        default:
+            return wrap({ type: kind })
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mikser-io-schemas",
+  "version": "1.1.0",
+  "description": "Zod schemas as entities for mikser-io — load from a folder, register in the catalog, validate documents in the lifecycle",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almero-digital-marketing/mikser-io-schemas.git"
+  },
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/almero-digital-marketing/mikser-io-schemas/issues"
+  },
+  "homepage": "https://github.com/almero-digital-marketing/mikser-io-schemas#readme",
+  "keywords": [
+    "mikser",
+    "mikser-io",
+    "schemas",
+    "zod",
+    "validation"
+  ],
+  "peerDependencies": {
+    "mikser-io": "^6.24.0",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}