webspresso 0.0.112 → 0.0.114

package/index.d.ts

@@ -1919,6 +1919,9 @@ export interface PluginRegisterContext {
   addHelper(name: string, fn: (...args: unknown[]) => unknown): void;
   addFilter(name: string, fn: (...args: unknown[]) => unknown): void;
   addRoute(method: string, path: string, ...handlers: RequestHandler[]): void;
+  registerClientController(name: string, filePath: string): void;
+  registerClientService(name: string, filePath: string): void;
+  registerFragment(name: string, fragmentDef: FragmentDefinition<any, any>): void;
   routes: unknown;
   [key: string]: unknown;
 }
@@ -1936,6 +1939,18 @@ export interface WebspressoPlugin {
 }
 
 export class PluginManager {
+  registerClientController(name: string, filePath: string, pluginName?: string): void;
+  registerClientService(name: string, filePath: string, pluginName?: string): void;
+  registerFragment(name: string, fragmentDef: FragmentDefinition<any, any>, pluginName?: string): void;
+  getClientControllers(): Array<{ name: string; filePath: string; pluginName: string }>;
+  getClientServices(): Array<{ name: string; filePath: string; pluginName: string }>;
+  getFragment(name: string): FragmentDefinition<any, any> | null;
+  getFragments(): Record<string, FragmentDefinition<any, any>>;
+  getClientManifest(): {
+    controllers: Array<{ name: string; filePath: string; pluginName: string }>;
+    services: Array<{ name: string; filePath: string; pluginName: string }>;
+    fragments: string[];
+  };
   [key: string]: unknown;
 }
 
@@ -5075,6 +5090,11 @@ export interface DefineApiOptions<
   middleware?: (string | import('express').RequestHandler | [string, Record<string, unknown>])[];
   flag?: string | { key: string; statusCode?: number; message?: string };
   schema?: TSchema;
+  validateFields?: boolean | string[];
+  validate?: (
+    req: ApiRequest<TBody, TParams, TQuery, THeaders>,
+    ctx: { body: TBody; fields: string[]; req: ApiRequest<TBody, TParams, TQuery, THeaders>; res: ApiResponse<TBody, TParams, TQuery, THeaders> }
+  ) => Promise<Record<string, string> | null | undefined> | Record<string, string> | null | undefined;
   response?: Record<number | string, unknown>;
   handler: (
     req: ApiRequest<TBody, TParams, TQuery, THeaders>,
@@ -5094,6 +5114,16 @@ export function defineApi<
 >(
   config: {
     schema: TSchema;
+    validateFields?: boolean | string[];
+    validate?: (
+      req: ApiRequest<ApiNoInfer<TBody>, ApiNoInfer<TParams>, ApiNoInfer<TQuery>, ApiNoInfer<THeaders>>,
+      ctx: {
+        body: ApiNoInfer<TBody>;
+        fields: string[];
+        req: ApiRequest<ApiNoInfer<TBody>, ApiNoInfer<TParams>, ApiNoInfer<TQuery>, ApiNoInfer<THeaders>>;
+        res: ApiResponse<ApiNoInfer<TBody>, ApiNoInfer<TParams>, ApiNoInfer<TQuery>, ApiNoInfer<THeaders>>;
+      }
+    ) => Promise<Record<string, string> | null | undefined> | Record<string, string> | null | undefined;
     description?: string;
     tags?: string[];
     middleware?: (string | import('express').RequestHandler | [string, Record<string, unknown>])[];
@@ -6367,6 +6397,9 @@ export class ClientRequestError<TData = unknown> extends Error {
   readonly isTimedOut: boolean;
   readonly isDropped: boolean;
   readonly isSuperseded: boolean;
+  readonly dispatched: boolean;
+  readonly outcomeUnknown: boolean;
+  readonly outcome: 'unknown' | 'failed' | 'not_sent';
   readonly cause?: unknown;
   constructor(options: {
     message: string;
@@ -6383,6 +6416,9 @@ export class ClientRequestError<TData = unknown> extends Error {
     isTimedOut?: boolean;
     isDropped?: boolean;
     isSuperseded?: boolean;
+    dispatched?: boolean;
+    outcomeUnknown?: boolean;
+    outcome?: 'unknown' | 'failed' | 'not_sent';
   });
 }
 
@@ -6411,6 +6447,12 @@ export interface ClientRequestCallOptions<
   timeout?: number;
   retry?: boolean | number | ClientRetryOptions;
   retryMutations?: boolean;
+  onUploadProgress?: (progress: {
+    loaded: number;
+    total: number;
+    percent: number | null;
+    lengthComputable: boolean;
+  }) => void;
 }
 
 export interface AppApiRouteMap {
@@ -6440,6 +6482,8 @@ export interface ClientTaskOptions {
   concurrency?: ClientConcurrencyPolicy;
   policy?: ClientConcurrencyPolicy;
   key?: string;
+  mutation?: boolean;
+  kind?: 'query' | 'mutation';
   staleTime?: number | string;
   refetchOnMount?: ClientRefetchPolicy;
   refetchOnVisit?: ClientRefetchPolicy;
@@ -6714,6 +6758,8 @@ export interface ClientFormSubmitResult<TData = any> {
   hookError?: Error | null;
   error?: ClientRequestError | Error;
   aborted?: boolean;
+  outcomeUnknown?: boolean;
+  outcome?: 'unknown' | 'failed' | 'not_sent';
 }
 
 export interface ClientFormHookMeta<
@@ -6738,6 +6784,9 @@ export interface ClientFormHandle<
   readonly services: ClientServicesRegistry<TServices>;
   readonly pending: boolean;
   readonly dirty: boolean;
+  readonly touched: boolean;
+  readonly touchedFields: string[];
+  readonly submitted: boolean;
   readonly inputRevision: number;
   readonly draftKey: string;
   readonly baseline: TValues;
@@ -6746,6 +6795,34 @@ export interface ClientFormHandle<
   readonly lastError: ClientRequestError | Error | null;
   readonly fieldErrors: Partial<Record<keyof TValues & string, string>> & Record<string, string>;
   disabled: boolean;
+  isTouched(fieldName?: keyof TValues & string | string): boolean;
+  touch(fieldName?: keyof TValues & string | string): this;
+  untouch(fieldName?: keyof TValues & string | string): this;
+  validateField(
+    fieldName: (keyof TValues & string) | string,
+    options?: { url?: string; method?: string; contextFields?: string[] | '*' }
+  ): Promise<{
+    ok: boolean;
+    valid?: boolean;
+    stale?: boolean;
+    canceled?: boolean;
+    networkError?: boolean;
+    errors?: Record<string, string>;
+    error?: Error;
+  }>;
+  readonly uploads: Array<{
+    field: string;
+    name: string;
+    size: number;
+    status: 'uploading' | 'done' | 'error' | 'canceled';
+    loaded: number;
+    total: number;
+    percent: number | null;
+    error: string | null;
+  }>;
+  cancelUpload(): boolean;
+  createPreviewUrl(file: File | Blob, fieldName?: string): string | null;
+  revokePreviewUrls(fieldName?: string): void;
   values(): TValues;
   read(submitter?: HTMLElement | null): TValues;
   fill(values: Partial<TValues> & Record<string, unknown>, options?: ClientFormFillOptions): this;
@@ -6801,10 +6878,12 @@ export interface ControllerFormsRegistry<TServices = AppClientServices> {
 
 export interface FragmentRefreshResult {
   ok: boolean;
+  partial?: boolean;
   refreshed: string[];
   errors?: Error[];
   skipped?: boolean;
   canceled?: boolean;
+  superseded?: boolean;
   error?: Error | null;
   timings?: {
     loadMs: number;
@@ -6816,6 +6895,12 @@ export interface FragmentRefreshOptions {
   replaceInput?: boolean;
   timeout?: number;
   throwOnError?: boolean;
+  mode?: 'replace' | 'append' | 'prepend';
+  limit?: number;
+  target?: string;
+  removeKeys?: string[];
+  onBeforePatch?: (el: Element, inst: any) => void;
+  onAfterPatch?: (el: Element, inst: any) => void;
   onSuccess?: (result: FragmentRefreshResult) => void | Promise<void>;
   onFailure?: (error: Error) => void | Promise<void>;
   onError?: (error: Error) => void | Promise<void>;
@@ -6825,6 +6910,7 @@ export interface FragmentRefreshOptions {
 
 export interface ControllerFragmentHandle<TInput extends Record<string, any> = Record<string, any>> {
   readonly input: TInput;
+  readonly inputs: Record<string, TInput>;
   refresh(
     nextInput?: Partial<TInput> & Record<string, unknown>,
     options?: FragmentRefreshOptions
@@ -6836,10 +6922,17 @@ export interface ControllerErrorMeta {
   task?: string;
   event?: Event;
   actionEl?: HTMLElement | null;
-  phase?: 'action' | 'task' | 'connect' | 'disconnect';
+  phase?: 'action' | 'task' | 'connect' | 'disconnect' | 'beforePatch' | 'afterPatch';
   [key: string]: unknown;
 }
 
+export interface FragmentPatchHookMeta {
+  fragmentId?: string | null;
+  fragmentName?: string | null;
+  isFragmentRoot?: boolean;
+  isDescendant?: boolean;
+}
+
 export type WatchSource<T = any> =
   | (() => T)
   | string
@@ -6988,6 +7081,22 @@ export interface ControllerDefinition<
       TServices
     >
   ) => void;
+  beforePatch?: (
+    ctx: ControllerContext<
+      [TState][TState extends any ? 0 : never] & { readonly [K in keyof TComputed]: ReturnType<TComputed[K]> },
+      Record<string, ClientTask>,
+      TServices
+    >,
+    meta: FragmentPatchHookMeta
+  ) => void;
+  afterPatch?: (
+    ctx: ControllerContext<
+      [TState][TState extends any ? 0 : never] & { readonly [K in keyof TComputed]: ReturnType<TComputed[K]> },
+      Record<string, ClientTask>,
+      TServices
+    >,
+    meta: FragmentPatchHookMeta
+  ) => void | Promise<void>;
   onError?: ControllerErrorHandler<
     [TState][TState extends any ? 0 : never] & { readonly [K in keyof TComputed]: ReturnType<TComputed[K]> },
     Record<string, ClientTask>,
@@ -7052,6 +7161,9 @@ export interface FragmentDefinition<TInput = Record<string, unknown>, TData = Re
   refetchOnVisit?: ClientRefetchPolicy;
   refetchInterval?: number | string | false;
   refetchIntervalInBackground?: boolean;
+  lazy?: boolean;
+  placeholder?: string | ((ctx: { input: TInput; instanceId: string; name: string }) => string);
+  placeholderTemplate?: string;
   load?: (context: FragmentLoaderContext<TInput>) => TData | Promise<TData>;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.112",
+  "version": "0.0.114",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",
@@ -100,7 +100,7 @@
     "bench:ci:local": "npm run bench:baseline && npm run bench:ci",
     "bench:profile": "softscope --top 30 node scripts/profile-bench.mjs",
     "bench:profile:ai": "softscope --top 40 -o softscope-bench.ai node scripts/profile-bench.mjs",
-    "check:types": "tsc --project tests/ts-smoke/tsconfig.json && tsc --noEmit --skipLibCheck false --types node index.d.ts",
+    "check:types": "tsc --project tests/ts-smoke/tsconfig.json && tsc --noEmit --skipLibCheck false --esModuleInterop --types node index.d.ts",
     "rebuild:native": "npm rebuild better-sqlite3 bcrypt sharp",
     "docs:dev": "docboot dev ./docs",
     "docs:build": "docboot build ./docs",
@@ -134,21 +134,21 @@
     "views/partials/webspresso-client-runtime.njk"
   ],
   "dependencies": {
-    "commander": "^11.1.0",
+    "commander": "^14.0.3",
     "cookie-parser": "^1.4.7",
     "csv-parse": "^7.0.2",
     "dayjs": "^1.11.19",
     "express": "^5.2.1",
     "express-session": "^1.18.0",
-    "helmet": "^7.2.0",
-    "inquirer": "^8.2.6",
+    "helmet": "^8.3.0",
+    "inquirer": "^13.4.3",
     "knex": "^3.1.0",
     "multer": "^2.4.0",
     "nunjucks": "^3.2.4",
     "qs": "^6.17.1",
     "sanitize-html": "^2.18.1",
     "yaml": "^2.8.3",
-    "zod": "^3.23.0",
+    "zod": "^4.6.7",
     "zod-to-json-schema": "^3.25.2"
   },
   "peerDependencies": {
@@ -218,7 +218,7 @@
     "@swup/scripts-plugin": "^2.1.0",
     "@types/express": "^5.0.0",
     "@types/node": "^20.14.0",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^4.1.12",
     "bcrypt": "^6.0.0",
     "better-sqlite3": "^11.10.0",
     "chokidar": "^4.0.3",
@@ -226,7 +226,7 @@
     "dotenv": "^16.3.1",
     "exceljs": "^4.4.0",
     "express-rate-limit": "^8.4.1",
-    "hono": "^4.13.13",
+    "hono": "^4.13.16",
     "mjml": "^5.4.0",
     "nodemailer": "^10.0.10",
     "release-it": "^20.2.1",
@@ -235,14 +235,14 @@
     "supertest": "^6.3.4",
     "swup": "^4.8.3",
     "typescript": "~5.6.3",
-    "vitest": "^4.1.11",
+    "vitest": "^4.1.12",
     "vitest-doctor": "^0.3.0"
   },
   "engines": {
     "node": ">=20.0.0"
   },
   "overrides": {
-    "basic-ftp": "^6.2.1",
+    "basic-ftp": "^6.2.4",
     "chokidar": "^4.0.3",
     "katex": "^0.18.2",
     "tar": "^7.5.11",
@@ -251,7 +251,8 @@
     "js-yaml": "^5.4.2",
     "qs": "^6.17.1",
     "sanitize-html": "^2.18.1",
-    "vite": "^8.3.5"
+    "vite": "^8.3.5",
+    "minimatch@>=7.0.0 <=11.0.0": "^11.0.8"
   },
   "allowScripts": {
     "bcrypt@6.0.0": true,

package/plugins/mcp/providers/services.js

@@ -4,7 +4,7 @@
  * @module plugins/mcp/providers/services
  */
 
-const { zodToJsonSchema } = require('zod-to-json-schema');
+const { zodToJsonSchemaCompat } = require('../../../core/validation/zod-introspect');
 
 /**
  * Normalizes a dot-separated service name to an MCP-safe tool name
@@ -99,7 +99,7 @@ function convertZodToInputSchema(schema) {
   }
 
   try {
-    const rawSchema = zodToJsonSchema(schema, {
+    const rawSchema = zodToJsonSchemaCompat(schema, {
       $refStrategy: 'none',
       removeAdditionalStrategy: 'strict',
     });

package/src/api/define-api.js

@@ -13,6 +13,8 @@
  * @param {Array<string|Function>} [config.middleware] - Named or functional middlewares
  * @param {string|{ key: string, statusCode?: number, message?: string }} [config.flag] - Feature flag required to access this endpoint
  * @param {Object|Function} [config.schema] - Request schemas (params, query, body, headers)
+ * @param {boolean|string[]} [config.validateFields] - Opt-in field-level validation without running mutation handler
+ * @param {Function} [config.validate] - Optional async read-only validation hook: async (ctx, fields) => ({ field: 'msg' })
  * @param {Object} [config.response] - Expected response schemas by status code
  * @param {Function} config.handler - Request handler: async (req, ctx) => data
  * @returns {Object}

package/src/api/validation-i18n.js

@@ -94,8 +94,12 @@ function translateSingleIssue(issue, t) {
 
   const pathKey = Array.isArray(issue.path) && issue.path.length > 0 ? issue.path.join('.') : '';
   const field = Array.isArray(issue.path) && issue.path.length > 0 ? issue.path[issue.path.length - 1] : '';
-  const isRequired = (issue.code === 'invalid_type' && (issue.received === 'undefined' || issue.message === 'Required'))
-    || issue.message === 'Required';
+  const isRequired = (issue.code === 'invalid_type' && (
+    issue.received === 'undefined' ||
+    issue.input === undefined ||
+    issue.message === 'Required' ||
+    /received undefined$/i.test(issue.message || '')
+  )) || issue.message === 'Required';
 
   const params = Object.assign(
     {

package/src/bundle/index.js

@@ -213,22 +213,52 @@ function findPageEntryPoints(cwd = process.cwd()) {
     walkViews(dirToScan);
   }
 
+  // 4. Plugin-registered client controllers and services (if PluginManager is active)
+  try {
+    const { getPluginManager } = require('../../core/plugins/plugin-manager');
+    const pm = typeof getPluginManager === 'function' ? getPluginManager() : null;
+    if (pm) {
+      if (typeof pm.getClientControllers === 'function') {
+        for (const ctrl of pm.getClientControllers()) {
+          const entryName = `plugins/${ctrl.pluginName}/${ctrl.name}`;
+          if (!pageEntries[entryName]) {
+            pageEntries[entryName] = path.isAbsolute(ctrl.filePath)
+              ? ctrl.filePath
+              : path.resolve(cwd, ctrl.filePath);
+          }
+        }
+      }
+      if (typeof pm.getClientServices === 'function') {
+        for (const svc of pm.getClientServices()) {
+          const entryName = `plugins/${svc.pluginName}/services/${svc.name}`;
+          if (!pageEntries[entryName]) {
+            pageEntries[entryName] = path.isAbsolute(svc.filePath)
+              ? svc.filePath
+              : path.resolve(cwd, svc.filePath);
+          }
+        }
+      }
+    }
+  } catch (_e) {}
+
   return pageEntries;
 }
 
 /**
- * Discovers all `.client.{js,ts,mjs,jsx,tsx}` controller files across `pages/` and `views/`
+ * Discovers all `.client.{js,ts,mjs,jsx,tsx}` controller files across `pages/`, `views/`, and plugins
  * and validates deterministic controller names for collisions.
  *
  * @param {string} [cwd=process.cwd()]
- * @returns {Array<{ controllerName: string, entryName: string, filePath: string, relativePath: string }>}
+ * @param {object} [options]
+ * @returns {Array<{ controllerName: string, entryName: string, filePath: string, relativePath: string, pluginName?: string }>}
  */
-function discoverClientControllers(cwd = process.cwd()) {
+function discoverClientControllers(cwd = process.cwd(), options = {}) {
   const pageEntries = findPageEntryPoints(cwd);
   const discovered = [];
   const byControllerName = new Map();
 
   for (const [entryName, filePath] of Object.entries(pageEntries)) {
+    if (entryName.startsWith('plugins/')) continue;
     const relativePath = path.relative(cwd, filePath).replace(/\\/g, '/');
     const controllerName = deriveControllerNameFromPath(relativePath);
     if (!controllerName) continue;
@@ -256,6 +286,46 @@ function discoverClientControllers(cwd = process.cwd()) {
     discovered.push(record);
   }
 
+  try {
+    const pm =
+      options.pluginManager ||
+      require('../../core/plugins/plugin-manager').getPluginManager();
+    if (pm && typeof pm.getClientControllers === 'function') {
+      for (const ctrl of pm.getClientControllers()) {
+        const absPath = path.isAbsolute(ctrl.filePath)
+          ? ctrl.filePath
+          : path.resolve(cwd, ctrl.filePath);
+        const relativePath = path.relative(cwd, absPath).replace(/\\/g, '/');
+        if (byControllerName.has(ctrl.name)) {
+          const existing = byControllerName.get(ctrl.name);
+          if (existing.filePath !== absPath) {
+            const err = new Error(
+              `Controller name collision: "${ctrl.name}" is defined by both "${existing.relativePath}" and "${relativePath}".`
+            );
+            err.code = 'CONTROLLER_NAME_COLLISION';
+            err.controllerName = ctrl.name;
+            err.files = [existing.relativePath, relativePath];
+            throw err;
+          }
+          continue;
+        }
+        const record = {
+          controllerName: ctrl.name,
+          entryName: `plugins/${ctrl.pluginName}/${ctrl.name}`,
+          filePath: absPath,
+          relativePath,
+          pluginName: ctrl.pluginName,
+        };
+        byControllerName.set(ctrl.name, record);
+        discovered.push(record);
+      }
+    }
+  } catch (err) {
+    if (err && err.code === 'CONTROLLER_NAME_COLLISION') {
+      throw err;
+    }
+  }
+
   return discovered;
 }
 
@@ -944,17 +1014,34 @@ function buildBundleFallback({ cwd, entryPoints, outdir, publicDir, manifestPath
   const emittedChunksBySource = new Map(); // absSourcePath -> { absOut, relFromOutdir, relOutput }
 
   function transpileSource(absFile, rawCode) {
+    let code = rawCode;
     if ((absFile.endsWith('.ts') || absFile.endsWith('.tsx')) && ts) {
-      const transpiled = ts.transpileModule(rawCode, {
+      const transpiled = ts.transpileModule(code, {
         compilerOptions: {
           module: ts.ModuleKind.ESNext,
           target: ts.ScriptTarget.ES2020,
         },
         fileName: absFile,
       });
-      return transpiled.outputText;
+      code = transpiled.outputText;
+    }
+    return code.replace(/\bprocess\.env\.NODE_ENV\b/g, '"production"');
+  }
+
+  function extractCjsExportNames(code) {
+    const match = code.match(/module\.exports\s*=\s*\{([\s\S]*?)\};?\s*$/);
+    if (!match) return [];
+    const body = match[1].replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+    const names = new Set();
+    const propRegex = /^\s*(?:get\s+|set\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:,|:|\()/gm;
+    let m;
+    while ((m = propRegex.exec(body)) !== null) {
+      const name = m[1];
+      if (name && name !== 'get' && name !== 'set' && name !== 'function') {
+        names.add(name);
+      }
     }
-    return rawCode;
+    return Array.from(names);
   }
 
   function emitChunkModule(absModulePath) {
@@ -1038,6 +1125,53 @@ function buildBundleFallback({ cwd, entryPoints, outdir, publicDir, manifestPath
       }
     );
 
+    // 3. Transform CommonJS modules (`module.exports = ...` / `require('./...')`) into native ESM chunks
+    if (/\bmodule\.exports\b/.test(rewritten)) {
+      const cjsImports = [];
+      let depSeq = 0;
+      const depVarBySpec = new Map();
+      const exportNames = extractCjsExportNames(rewritten);
+
+      rewritten = rewritten.replace(
+        /\b(?:reqFn|require)\s*\(\s*(['"])(\.[^'"]+)\1\s*\)/g,
+        (fullMatch, quote, spec) => {
+          if (spec === './debug' || spec === './devtool' || spec === './server-fragments') {
+            return '{}';
+          }
+          const resolved = resolveLocalModuleFile(importerAbsPath, spec);
+          if (!resolved) return fullMatch;
+          const chunkInfo = emitChunkModule(resolved);
+          if (!chunkInfo || !chunkInfo.absOut) return fullMatch;
+          let relSpec = path.relative(emitterOutDir, chunkInfo.absOut).replace(/\\/g, '/');
+          if (!relSpec.startsWith('.')) relSpec = './' + relSpec;
+          let depVar = depVarBySpec.get(relSpec);
+          if (!depVar) {
+            depVar = `__cjs_dep_${++depSeq}`;
+            depVarBySpec.set(relSpec, depVar);
+            cjsImports.push(`import ${depVar} from ${quote}${relSpec}${quote};`);
+            collectedImports.push({ path: chunkInfo.relOutput, kind: 'import-statement' });
+          }
+          return depVar;
+        }
+      );
+
+      const strippedBody = rewritten.replace(/^\s*['"]use strict['"];?\s*/, '');
+      const namedExportLines = exportNames.map(
+        (name) => `export const ${name} = __cjs_exports.${name};`
+      );
+      rewritten = [
+        ...cjsImports,
+        'const __cjs_exports = (() => {',
+        'const module = { exports: {} };',
+        'const exports = module.exports;',
+        strippedBody,
+        'return module.exports;',
+        '})();',
+        'export default __cjs_exports;',
+        ...namedExportLines,
+      ].join('\n');
+    }
+
     return rewritten;
   }