webspresso 0.0.112 → 0.0.114

package/core/orm/json-fields.js

@@ -3,6 +3,8 @@
  * @module core/orm/json-fields
  */
 
+const { getZodDef, getZodInner, getZodTypeName } = require('../validation/zod-introspect');
+
 /**
  * Get JSON column names from model
  * @param {import('./types').ModelDefinition} model - Model definition
@@ -31,16 +33,15 @@ function getJsonColumns(model) {
   if (model && model.schema && model.schema.shape) {
     for (const [name, fieldSchema] of Object.entries(model.schema.shape)) {
       let current = fieldSchema;
-      while (current && current._def) {
-        if (current._def.innerType) {
-          current = current._def.innerType;
-        } else if (current._def.schema) {
-          current = current._def.schema;
+      while (current && getZodDef(current)) {
+        const inner = getZodInner(current);
+        if (inner) {
+          current = inner;
         } else {
           break;
         }
       }
-      const typeName = current?._def?.typeName;
+      const typeName = getZodTypeName(current);
       if (typeName === 'ZodRecord' || typeName === 'ZodObject' || typeName === 'ZodArray') {
         jsonCols.add(name);
       }

package/core/orm/schema-helpers.js

@@ -5,6 +5,13 @@
  */
 
 const { safeJsonParse } = require('../utils/json');
+const {
+  getZodDef,
+  getZodTypeName,
+  getZodInner,
+  getZodEnumValues,
+  isZodInt,
+} = require('../validation/zod-introspect');
 
 const METADATA_MARKER = '__wdb__';
 const metaWeakMap = new WeakMap();
@@ -665,10 +672,7 @@ function createSchemaHelpers(z) {
      */
     json(options = {}) {
       const { nullable = false, ...rest } = options;
-      let schema = z.unknown();
-      if (nullable) {
-        schema = schema.nullable().optional();
-      }
+      let schema = nullable ? z.unknown().nullable().optional() : z.unknown().optional();
       return createSchemaBuilder(schema, {
         type: 'json',
         nullable,
@@ -888,14 +892,14 @@ function extractColumnsFromSchema(schema) {
     // Unwrap optional/nullable wrappers to get to the base schema
     let current = schemaToCheck;
     let isNullable = false;
-    while (current && current._def) {
-      if (current._def.typeName === 'ZodNullable' || current._def.typeName === 'ZodOptional') {
+    while (current && getZodDef(current)) {
+      const currentType = getZodTypeName(current);
+      if (currentType === 'ZodNullable' || currentType === 'ZodOptional') {
         isNullable = true;
       }
-      if (current._def.innerType) {
-        current = current._def.innerType;
-      } else if (current._def.schema) {
-        current = current._def.schema;
+      const inner = getZodInner(current);
+      if (inner) {
+        current = inner;
       } else {
         break;
       }
@@ -905,16 +909,15 @@ function extractColumnsFromSchema(schema) {
     const meta = getColumnMeta(schemaToCheck) || (current ? getColumnMeta(current) : null);
     if (meta) {
       columns.set(key, meta);
-    } else if (current && current._def && current._def.typeName) {
-      const typeName = current._def.typeName;
+    } else if (current && getZodTypeName(current)) {
+      const typeName = getZodTypeName(current);
       let inferred = null;
       switch (typeName) {
         case 'ZodString':
           inferred = { type: 'string', maxLength: 255, nullable: isNullable };
           break;
         case 'ZodNumber': {
-          const isInt = current._def.checks?.some((c) => c.kind === 'int');
-          inferred = { type: isInt ? 'integer' : 'float', nullable: isNullable };
+          inferred = { type: isZodInt(current) ? 'integer' : 'float', nullable: isNullable };
           break;
         }
         case 'ZodBoolean':
@@ -924,7 +927,7 @@ function extractColumnsFromSchema(schema) {
           inferred = { type: 'timestamp', nullable: isNullable };
           break;
         case 'ZodEnum':
-          inferred = { type: 'enum', enumValues: current._def.values || [], nullable: isNullable };
+          inferred = { type: 'enum', enumValues: getZodEnumValues(current), nullable: isNullable };
           break;
         case 'ZodArray':
           inferred = { type: 'files', nullable: isNullable };

package/core/orm/utils/nanoid.js

@@ -63,14 +63,13 @@ function resolveNanoidSize(arg) {
  * @param {typeof import('zod').z} zod
  */
 function extendZ(zod) {
-  return new Proxy(zod, {
-    get(target, prop, receiver) {
-      if (prop === 'nanoid') {
-        return function nanoid(arg) {
-          return zodNanoid(zod, resolveNanoidSize(arg));
-        };
-      }
-      return Reflect.get(target, prop, receiver);
+  return Object.create(zod, {
+    nanoid: {
+      value: function nanoid(arg) {
+        return zodNanoid(zod, resolveNanoidSize(arg));
+      },
+      enumerable: true,
+      configurable: true,
     },
   });
 }

package/core/plugins/plugin-manager.js

@@ -147,6 +147,9 @@ class PluginManager {
     this.routes = [];                   // Collected route metadata
     this.customRoutes = [];             // Routes added by plugins
     this.cspDirectives = new Map();     // directive -> Set of sources (from plugins)
+    this.clientControllers = new Map(); // name -> { name, filePath, pluginName }
+    this.clientServices = new Map();    // name -> { name, filePath, pluginName }
+    this.registeredFragments = new Map(); // name -> { name, def, pluginName }
     this.disposers = [];                // Array<{ name: string, fn: Function }>
     this._cachedHelpers = null;         // Cached helpers object
     this.pendingAsyncOperations = [];   // Track background promises
@@ -271,7 +274,7 @@ class PluginManager {
 
     // Build graph
     for (const plugin of plugins) {
-      if (!plugin.name) {
+      if (!plugin || !plugin.name) {
         console.warn('[plugin-manager] Skipping plugin without name:', plugin);
         continue;
       }
@@ -730,6 +733,33 @@ class PluginManager {
        */
       getScriptInjector() {
         return getCachedScriptInjector();
+      },
+
+      /**
+       * Register a client controller entry file (`.client.js` / `.client.ts`) for bundler discovery
+       * @param {string} name - Controller name used in `data-w-controller="<name>"`
+       * @param {string} filePath - Absolute or project-relative path to the client controller module
+       */
+      registerClientController(name, filePath) {
+        self.registerClientController(name, filePath, pluginName);
+      },
+
+      /**
+       * Register a client service module (`defineClientService(...)`) for bundler discovery
+       * @param {string} name - Service name used in `ctx.services.get('<name>')`
+       * @param {string} filePath - Absolute or project-relative path to the client service module
+       */
+      registerClientService(name, filePath) {
+        self.registerClientService(name, filePath, pluginName);
+      },
+
+      /**
+       * Register a reusable SSR fragment (`defineFragment(...)`) usable across pages
+       * @param {string} name - Fragment name used in `fsy.fragment('<name>', ...)`
+       * @param {Object} fragmentDef - Fragment definition created via `defineFragment(...)`
+       */
+      registerFragment(name, fragmentDef) {
+        self.registerFragment(name, fragmentDef, pluginName);
       }
     };
   }
@@ -808,6 +838,130 @@ class PluginManager {
     }
   }
 
+  /**
+   * Register a client controller module from a plugin.
+   * @param {string} name
+   * @param {string} filePath
+   * @param {string} [pluginName='unknown']
+   */
+  registerClientController(name, filePath, pluginName = 'unknown') {
+    const cleanName = typeof name === 'string' ? name.trim() : '';
+    const cleanPath = typeof filePath === 'string' ? filePath.trim() : '';
+    if (!cleanName || !cleanPath) {
+      throw new TypeError(`[plugin-manager] registerClientController(name, filePath) requires non-empty strings (plugin "${pluginName}").`);
+    }
+    const existing = this.clientControllers.get(cleanName);
+    if (existing && existing.filePath !== cleanPath) {
+      const err = new Error(
+        `Client controller name collision: "${cleanName}" is registered by both plugin "${existing.pluginName}" (${existing.filePath}) and "${pluginName}" (${cleanPath}).`
+      );
+      err.code = 'PLUGIN_CLIENT_CONTROLLER_COLLISION';
+      throw err;
+    }
+    this.clientControllers.set(cleanName, {
+      name: cleanName,
+      filePath: cleanPath,
+      pluginName,
+    });
+  }
+
+  /**
+   * Register a client service module from a plugin.
+   * @param {string} name
+   * @param {string} filePath
+   * @param {string} [pluginName='unknown']
+   */
+  registerClientService(name, filePath, pluginName = 'unknown') {
+    const cleanName = typeof name === 'string' ? name.trim() : '';
+    const cleanPath = typeof filePath === 'string' ? filePath.trim() : '';
+    if (!cleanName || !cleanPath) {
+      throw new TypeError(`[plugin-manager] registerClientService(name, filePath) requires non-empty strings (plugin "${pluginName}").`);
+    }
+    const existing = this.clientServices.get(cleanName);
+    if (existing && existing.filePath !== cleanPath) {
+      const err = new Error(
+        `Client service name collision: "${cleanName}" is registered by both plugin "${existing.pluginName}" (${existing.filePath}) and "${pluginName}" (${cleanPath}).`
+      );
+      err.code = 'PLUGIN_CLIENT_SERVICE_COLLISION';
+      throw err;
+    }
+    this.clientServices.set(cleanName, {
+      name: cleanName,
+      filePath: cleanPath,
+      pluginName,
+    });
+  }
+
+  /**
+   * Register a reusable SSR fragment definition from a plugin.
+   * @param {string} name
+   * @param {Object} fragmentDef
+   * @param {string} [pluginName='unknown']
+   */
+  registerFragment(name, fragmentDef, pluginName = 'unknown') {
+    const cleanName = typeof name === 'string' ? name.trim() : '';
+    if (!cleanName || !fragmentDef || typeof fragmentDef !== 'object') {
+      throw new TypeError(`[plugin-manager] registerFragment(name, fragmentDef) requires a valid fragment name and definition (plugin "${pluginName}").`);
+    }
+    if (this.registeredFragments.has(cleanName)) {
+      console.warn(`[plugin-manager] Fragment "${cleanName}" is already registered (registered by "${pluginName}" overwrites existing fragment).`);
+    }
+    this.registeredFragments.set(cleanName, {
+      name: cleanName,
+      def: fragmentDef,
+      pluginName,
+    });
+  }
+
+  /**
+   * Get all client controllers registered by plugins.
+   * @returns {Array<{ name: string, filePath: string, pluginName: string }>}
+   */
+  getClientControllers() {
+    return Array.from(this.clientControllers.values());
+  }
+
+  /**
+   * Get all client services registered by plugins.
+   * @returns {Array<{ name: string, filePath: string, pluginName: string }>}
+   */
+  getClientServices() {
+    return Array.from(this.clientServices.values());
+  }
+
+  /**
+   * Look up a plugin-registered fragment definition by name.
+   * @param {string} name
+   * @returns {Object|null}
+   */
+  getFragment(name) {
+    const entry = this.registeredFragments.get(name);
+    return entry ? entry.def : null;
+  }
+
+  /**
+   * Get all plugin-registered fragments as a plain map `{ [name]: fragmentDef }`.
+   * @returns {Record<string, Object>}
+   */
+  getFragments() {
+    const out = {};
+    for (const [name, entry] of this.registeredFragments) {
+      out[name] = entry.def;
+    }
+    return out;
+  }
+
+  /**
+   * Get combined client manifest of controllers, services, and fragment names registered by plugins.
+   */
+  getClientManifest() {
+    return {
+      controllers: this.getClientControllers(),
+      services: this.getClientServices(),
+      fragments: Array.from(this.registeredFragments.keys()),
+    };
+  }
+
   /**
    * Register a request-scoped helper provider (called on each SSR request)
    * @param {Function} fn - (req) => Record<string, any>

package/core/services/validator.js

@@ -293,7 +293,18 @@ function validateServiceInput(schema, input, serviceName, options = {}) {
   // 1. Zod schema validation
   if (compiled instanceof z.ZodType || typeof compiled.safeParse === 'function') {
     try {
-      const result = compiled.safeParse(sanitized);
+      let result;
+      if (compiled._zod && typeof compiled._zod.run === 'function') {
+        const rawRun = compiled._zod.run({ value: sanitized, issues: [] }, { async: true });
+        if (rawRun instanceof Promise) {
+          // Attach no-op catch so async refinements rejected during sync preflight don't emit UnhandledRejection
+          rawRun.catch(() => {});
+          throw new Error('Encountered Promise during synchronous parse');
+        }
+        result = rawRun.issues.length ? compiled.safeParse(sanitized) : { success: true, data: rawRun.value };
+      } else {
+        result = compiled.safeParse(sanitized);
+      }
       if (!result.success) {
         const { message, fields, fieldErrors } = formatZodErrors(result.error, serviceName);
         throw createServiceValidationError(message, {

package/core/validation/apply.js

@@ -6,6 +6,9 @@
  * @module core/validation/apply
  */
 
+const { ensureZodCompat } = require('./zod-introspect');
+ensureZodCompat();
+
 const EMPTY_INPUT = Object.freeze({
   body: undefined,
   params: undefined,

package/core/validation/index.js

@@ -28,6 +28,31 @@ if (z.ZodType && z.ZodType.prototype && typeof z.ZodType.prototype._refinement =
   };
   wrappedRefinement.__webspresso_wrapped = true;
   z.ZodType.prototype._refinement = wrappedRefinement;
+} else if (z.ZodType && z.ZodType.prototype && typeof z.ZodType.prototype.refine === 'function' && !z.ZodType.prototype.refine.__webspresso_wrapped) {
+  const origRefine = z.ZodType.prototype.refine;
+  const wrappedRefine = function (check, params) {
+    const wrappedCheck = typeof check === 'function'
+      ? (val) => {
+          const res = check(val);
+          if (res && typeof res.catch === 'function') {
+            res.catch(() => {});
+          }
+          return res;
+        }
+      : check;
+    return origRefine.call(this, wrappedCheck, params);
+  };
+  wrappedRefine.__webspresso_wrapped = true;
+  z.ZodType.prototype.refine = wrappedRefine;
+}
+
+if (z.ZodError && z.ZodError.prototype && !Object.getOwnPropertyDescriptor(z.ZodError.prototype, 'errors')) {
+  Object.defineProperty(z.ZodError.prototype, 'errors', {
+    get() {
+      return this.issues;
+    },
+    configurable: true,
+  });
 }
 
 /**

package/core/validation/zod-introspect.js

@@ -0,0 +1,187 @@
+/**
+ * Zod v3 & v4 Introspection Helpers
+ * Provides a unified abstraction over Zod v3 (`_def.typeName`) and Zod v4 (`_zod.def.type`)
+ * for ORM column inference, TypeGen, API TypeGen, and OpenAPI/MCP JSON Schema generation.
+ * @module core/validation/zod-introspect
+ */
+
+const z = require('zod');
+
+const V4_TYPE_MAP = Object.freeze({
+  string: 'ZodString',
+  number: 'ZodNumber',
+  boolean: 'ZodBoolean',
+  date: 'ZodDate',
+  bigint: 'ZodBigInt',
+  any: 'ZodAny',
+  unknown: 'ZodUnknown',
+  never: 'ZodNever',
+  undefined: 'ZodUndefined',
+  void: 'ZodVoid',
+  null: 'ZodNull',
+  literal: 'ZodLiteral',
+  enum: 'ZodEnum',
+  array: 'ZodArray',
+  optional: 'ZodOptional',
+  nullable: 'ZodNullable',
+  default: 'ZodDefault',
+  prefault: 'ZodDefault',
+  transform: 'ZodEffects',
+  pipe: 'ZodPipeline',
+  union: 'ZodUnion',
+  object: 'ZodObject',
+  record: 'ZodRecord',
+  tuple: 'ZodTuple',
+  set: 'ZodSet',
+  map: 'ZodMap',
+  nonoptional: 'ZodNonOptional',
+  readonly: 'ZodReadonly',
+  catch: 'ZodCatch',
+});
+
+function getZodDef(schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  return (schema._zod && schema._zod.def) || schema._def || null;
+}
+
+function getZodTypeName(schema) {
+  const def = getZodDef(schema);
+  if (!def) return null;
+  if (def.typeName) return def.typeName;
+  if (typeof def.type === 'string') {
+    return V4_TYPE_MAP[def.type] || null;
+  }
+  return null;
+}
+
+function isZodSchema(val) {
+  return Boolean(val && typeof val === 'object' && (val._zod || val._def) && typeof val.safeParse === 'function');
+}
+
+function getZodInner(schema) {
+  const def = getZodDef(schema);
+  if (!def) return null;
+  return def.innerType || def.schema || def.in || null;
+}
+
+function getZodPipeOut(schema) {
+  const def = getZodDef(schema);
+  if (!def) return null;
+  return def.out || null;
+}
+
+function getZodArrayElement(schema) {
+  const def = getZodDef(schema);
+  if (!def) return null;
+  if (def.element) return def.element;
+  if (def.type && typeof def.type === 'object') return def.type;
+  return null;
+}
+
+function getZodObjectShape(schema) {
+  if (!schema || typeof schema !== 'object') return {};
+  if (typeof schema.shape === 'object' && schema.shape !== null) return schema.shape;
+  const def = getZodDef(schema);
+  if (!def) return {};
+  if (typeof def.shape === 'function') return def.shape() || {};
+  if (typeof def.shape === 'object' && def.shape !== null) return def.shape;
+  return {};
+}
+
+function getZodEnumValues(schema) {
+  const def = getZodDef(schema);
+  if (!def) return [];
+  if (Array.isArray(def.values)) return def.values;
+  if (def.entries && typeof def.entries === 'object') return Object.values(def.entries);
+  if (def.values && typeof def.values === 'object') return Object.values(def.values);
+  return [];
+}
+
+function getZodLiteralValue(schema) {
+  const def = getZodDef(schema);
+  if (!def) return undefined;
+  if (def.value !== undefined) return def.value;
+  if (Array.isArray(def.values)) return def.values[0];
+  return undefined;
+}
+
+function isZodInt(schema) {
+  const def = getZodDef(schema);
+  if (!def) return false;
+  if (def.format === 'safeint' || def.format === 'int32' || def.format === 'uint32') return true;
+  if (!Array.isArray(def.checks)) return false;
+  return def.checks.some((c) => {
+    if (!c) return false;
+    if (c.kind === 'int') return true;
+    const cDef = c._zod && c._zod.def;
+    return Boolean(cDef && cDef.check === 'number_format' && (cDef.format === 'safeint' || cDef.format === 'int32'));
+  });
+}
+
+function isZodCoerced(schema) {
+  const def = getZodDef(schema);
+  return Boolean(def && def.coerce);
+}
+
+function zodToJsonSchemaCompat(schema, options = {}) {
+  if (typeof z.toJSONSchema === 'function') {
+    try {
+      const target = options.target === 'openApi3' ? 'openapi-3.0' : (options.target || 'draft-7');
+      const jsonSchema = z.toJSONSchema(schema, {
+        target,
+        unrepresentable: 'any',
+      });
+      if (jsonSchema && typeof jsonSchema === 'object') {
+        delete jsonSchema.$schema;
+      }
+      return jsonSchema;
+    } catch (_) {
+      // Fall through to legacy helper if needed
+    }
+  }
+  const { zodToJsonSchema } = require('zod-to-json-schema');
+  return zodToJsonSchema(schema, options);
+}
+
+/**
+ * Apply Zod v3 compatibility shims onto Zod v4 prototypes (idempotent).
+ * - Exposes `ZodError.prototype.errors` -> `this.issues`
+ */
+function ensureZodCompat(zodModule = z) {
+  if (!zodModule) return;
+
+  const sampleError = typeof zodModule.string === 'function'
+    ? zodModule.string().safeParse(123)?.error
+    : null;
+  const errProtos = [
+    sampleError ? Object.getPrototypeOf(sampleError) : null,
+    zodModule.ZodError?.prototype,
+  ];
+  for (const errProto of errProtos) {
+    if (errProto && !Object.getOwnPropertyDescriptor(errProto, 'errors')) {
+      Object.defineProperty(errProto, 'errors', {
+        get() {
+          return this.issues;
+        },
+        configurable: true,
+      });
+    }
+  }
+}
+
+module.exports = {
+  getZodDef,
+  getZodTypeName,
+  isZodSchema,
+  getZodInner,
+  getZodPipeOut,
+  getZodArrayElement,
+  getZodObjectShape,
+  getZodEnumValues,
+  getZodLiteralValue,
+  isZodInt,
+  isZodCoerced,
+  zodToJsonSchemaCompat,
+  ensureZodCompat,
+};
+