webspresso 0.0.90 → 0.0.93

package/src/services/registry.js

@@ -0,0 +1,290 @@
+/**
+ * Webspresso Service Registry
+ * Central registry holding discovered and programmatically registered services
+ * @module src/services/registry
+ */
+
+const path = require('path');
+const { ConfigurationError, WebspressoError } = require('../../core/errors');
+const { discoverServices } = require('./discovery');
+const { executeService } = require('./executor');
+const { memoize } = require('./memoize');
+
+class ServiceRegistry {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.servicesDir] - Path to services directory
+   * @param {boolean} [options.isDev=false] - Whether in development mode
+   * @param {Object} [options.logger] - Logger instance
+   */
+  constructor(options = {}) {
+    this.servicesDir = options.servicesDir ? path.resolve(options.servicesDir) : null;
+    this.isDev = Boolean(options.isDev);
+    this.logger = options.logger || null;
+
+    /** @type {Map<string, Object>} */
+    this.services = new Map();
+
+    /** @type {Map<string, string>} */
+    this.aliases = new Map();
+  }
+
+  /**
+   * Discover and load all services from servicesDir
+   * @returns {ServiceRegistry}
+   */
+  load() {
+    if (!this.servicesDir) {
+      return this;
+    }
+
+    const discovered = discoverServices(this.servicesDir);
+
+    for (const item of discovered) {
+      const { name, aliases, filePath } = item;
+
+      // Duplicate check
+      if (this.services.has(name)) {
+        const existing = this.services.get(name);
+        throw new ConfigurationError(
+          `Duplicate service registered: ${name} (files: ${existing.filePath} and ${filePath})`
+        );
+      }
+
+      // In dev mode, ensure fresh require
+      if (this.isDev) {
+        try {
+          const resolved = require.resolve(filePath);
+          delete require.cache[resolved];
+        } catch (e) {}
+      }
+
+      let mod;
+      try {
+        mod = require(filePath);
+      } catch (err) {
+        throw new ConfigurationError(`Failed to load service file '${filePath}': ${err.message}`, {
+          cause: err,
+        });
+      }
+
+      const raw = mod && mod.__esModule && mod.default ? mod.default : (mod && mod.default ? mod.default : mod);
+      const definition = typeof raw === 'function' ? { handler: raw } : raw;
+
+      if (!definition || typeof definition !== 'object') {
+        throw new ConfigurationError(
+          `Service file '${filePath}' must export an object or handler function`
+        );
+      }
+
+      if (typeof definition.handler !== 'function') {
+        throw new ConfigurationError(
+          `Service '${name}' in '${filePath}' must provide a handler function`
+        );
+      }
+
+      let handler = definition.handler;
+      let memoizeFn = null;
+
+      if (definition.cache) {
+        const memoizeOpts = typeof definition.cache === 'object' && definition.cache !== null
+          ? definition.cache
+          : { ttl: definition.cache };
+        memoizeFn = memoize(definition.handler, memoizeOpts);
+        handler = memoizeFn;
+      }
+
+      const serviceDef = {
+        name,
+        filePath,
+        schema: definition.schema || null,
+        handler,
+        rawHandler: definition.handler,
+        memoize: memoizeFn,
+        metadata: definition.metadata || {},
+        description: definition.description || definition.metadata?.description || '',
+        auth: definition.auth,
+        cache: definition.cache,
+        timeout: definition.timeout,
+        transaction: definition.transaction,
+      };
+
+      this.services.set(name, serviceDef);
+
+      for (const alias of aliases) {
+        this.aliases.set(alias, name);
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Programmatically register a service
+   * @param {string} name - Service name (e.g. 'user.get')
+   * @param {Object|Function} definition - Service definition or handler function
+   * @returns {ServiceRegistry}
+   */
+  register(name, definition) {
+    if (!name || typeof name !== 'string') {
+      throw new WebspressoError('Service name must be a non-empty string');
+    }
+
+    if (this.services.has(name)) {
+      throw new ConfigurationError(`Duplicate service registered: ${name}`);
+    }
+
+    const def = typeof definition === 'function' ? { handler: definition } : definition;
+
+    if (!def || typeof def !== 'object' || typeof def.handler !== 'function') {
+      throw new ConfigurationError(`Service '${name}' must provide a handler function`);
+    }
+
+    let handler = def.handler;
+    let memoizeFn = null;
+
+    if (def.cache) {
+      const memoizeOpts = typeof def.cache === 'object' && def.cache !== null
+        ? def.cache
+        : { ttl: def.cache };
+      memoizeFn = memoize(def.handler, memoizeOpts);
+      handler = memoizeFn;
+    }
+
+    const serviceDef = {
+      name,
+      filePath: def.filePath || null,
+      schema: def.schema || null,
+      handler,
+      rawHandler: def.handler,
+      memoize: memoizeFn,
+      metadata: def.metadata || {},
+      description: def.description || def.metadata?.description || '',
+      auth: def.auth,
+      cache: def.cache,
+      timeout: def.timeout,
+      transaction: def.transaction,
+    };
+
+    this.services.set(name, serviceDef);
+    return this;
+  }
+
+  /**
+   * Get a service definition by name or alias
+   * @param {string} name - Service name
+   * @returns {Object|undefined}
+   */
+  get(name) {
+    if (!name || typeof name !== 'string') {
+      return undefined;
+    }
+
+    if (this.services.has(name)) {
+      return this.services.get(name);
+    }
+
+    const aliasedName = this.aliases.get(name);
+    if (aliasedName && this.services.has(aliasedName)) {
+      return this.services.get(aliasedName);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Check if a service exists
+   * @param {string} name - Service name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this.get(name) !== undefined;
+  }
+
+  /**
+   * List all registered service names
+   * @returns {string[]}
+   */
+  list() {
+    return Array.from(this.services.keys());
+  }
+
+  /**
+   * Invalidate cached results for a specific service and input
+   * @param {string} name - Service name
+   * @param {*} [input] - Input arguments
+   * @param {Object} [ctx] - Context
+   * @returns {boolean} Whether cache was invalidated
+   */
+  invalidate(name, input, ctx) {
+    const serviceDef = this.get(name);
+    if (serviceDef && serviceDef.memoize) {
+      return serviceDef.memoize.invalidate(input, ctx);
+    }
+    return false;
+  }
+
+  /**
+   * Clear cache for a specific service or all services
+   * @param {string} [name] - Optional service name (omitting clears all)
+   * @returns {boolean}
+   */
+  clearCache(name) {
+    if (name) {
+      const serviceDef = this.get(name);
+      if (serviceDef && serviceDef.memoize) {
+        serviceDef.memoize.clear();
+        return true;
+      }
+      return false;
+    }
+
+    for (const serviceDef of this.services.values()) {
+      if (serviceDef.memoize) {
+        serviceDef.memoize.clear();
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Clear all service caches
+   * @returns {boolean}
+   */
+  clearAllCaches() {
+    return this.clearCache();
+  }
+
+  /**
+   * Execute a service by name
+   * @param {string} name - Service name
+   * @param {*} [input={}] - Input data
+   * @param {Object} [ctx={}] - Context object
+   * @param {Object} [options={}] - Options
+   * @returns {Promise<*>}
+   */
+  call(name, input = {}, ctx = {}, options = {}) {
+    return executeService(this, name, input, ctx, options);
+  }
+
+  /**
+   * Alias for call()
+   */
+  execute(name, input = {}, ctx = {}, options = {}) {
+    return this.call(name, input, ctx, options);
+  }
+
+  /**
+   * Reload services from disk (useful in development)
+   * @returns {ServiceRegistry}
+   */
+  reload() {
+    this.services.clear();
+    this.aliases.clear();
+    return this.load();
+  }
+}
+
+module.exports = {
+  ServiceRegistry,
+};

package/src/services/validator.js

@@ -0,0 +1,230 @@
+/**
+ * Webspresso Services Input Validation
+ * Powered by Zod with sync/async validation, prototype poisoning defense, and functional schema compilation
+ * @module src/services/validator
+ */
+
+const { ValidationError } = require('../../core/errors');
+const { z: zForServices, sanitizeInput, hasDangerousKeys } = require('../../core/validation');
+const z = zForServices;
+
+/**
+ * Compile a concise type string descriptor into a Zod schema
+ * @param {string} typeName - Type name descriptor (e.g. 'number', 'string', 'email', 'string?')
+ * @returns {z.ZodTypeAny}
+ */
+function descriptorToZod(typeName) {
+  const isOptional = typeName.endsWith('?');
+  const baseType = isOptional ? typeName.slice(0, -1).toLowerCase() : typeName.toLowerCase();
+
+  let schema;
+  switch (baseType) {
+    case 'string':
+    case 'text':
+      schema = z.string();
+      break;
+    case 'number':
+    case 'int':
+    case 'integer':
+    case 'float':
+      schema = z.number();
+      break;
+    case 'boolean':
+    case 'bool':
+      schema = z.boolean();
+      break;
+    case 'email':
+      schema = z.string().email();
+      break;
+    case 'uuid':
+      schema = z.string().uuid();
+      break;
+    case 'nanoid':
+      schema = zForServices.nanoid ? zForServices.nanoid() : z.string();
+      break;
+    case 'array':
+      schema = z.array(z.any());
+      break;
+    case 'object':
+      schema = z.record(z.any());
+      break;
+    case 'date':
+      schema = z.date().or(z.string().datetime()).or(z.string().refine(val => !Number.isNaN(Date.parse(val)), { message: 'Invalid date string' }));
+      break;
+    case 'function':
+      schema = z.function();
+      break;
+    case 'any':
+    default:
+      schema = z.any();
+      break;
+  }
+
+  return isOptional ? schema.optional() : schema;
+}
+
+/**
+ * Compile service schema definition into an executable validator
+ * @param {Function|Object|null} rawSchema - Schema definition
+ * @returns {Object|Function|null} Compiled schema
+ */
+function compileServiceSchema(rawSchema) {
+  if (!rawSchema) return null;
+
+  // If already a Zod schema
+  if (rawSchema instanceof z.ZodType || typeof rawSchema.safeParse === 'function') {
+    return rawSchema;
+  }
+
+  // If function: check if ({ z }) schema compiler or custom validator function
+  if (typeof rawSchema === 'function') {
+    try {
+      const compiled = rawSchema({ z: zForServices });
+      if (compiled && (compiled instanceof z.ZodType || typeof compiled.safeParse === 'function')) {
+        return compiled;
+      }
+    } catch (e) {
+      // If invoking with { z } throws, treat as a direct validator function
+    }
+    return rawSchema;
+  }
+
+  // If object descriptor: { id: 'number', name: 'string', email: 'email' }
+  if (typeof rawSchema === 'object' && rawSchema !== null) {
+    const keys = Object.keys(rawSchema);
+    if (keys.length === 0) {
+      return null;
+    }
+    const shape = {};
+    for (const [key, val] of Object.entries(rawSchema)) {
+      if (typeof val === 'string') {
+        shape[key] = descriptorToZod(val);
+      } else if (val instanceof z.ZodType || (val && typeof val.safeParse === 'function')) {
+        shape[key] = val;
+      } else if (typeof val === 'object' && val !== null) {
+        const isOpt = val.optional === true || val.required === false;
+        let base = val.type ? descriptorToZod(String(val.type)) : z.any();
+        shape[key] = isOpt ? base.optional() : base;
+      } else if (typeof val === 'function') {
+        shape[key] = z.custom(val);
+      } else {
+        shape[key] = z.any();
+      }
+    }
+    return z.object(shape);
+  }
+
+  return rawSchema;
+}
+
+/**
+ * Format Zod validation errors into a clean string and fields map
+ * @param {z.ZodError} zodError
+ * @param {string} serviceName
+ * @returns {{ message: string, fields: Record<string, string> }}
+ */
+function formatZodErrors(zodError, serviceName) {
+  const fields = {};
+  const lines = [];
+
+  for (const issue of zodError.issues || []) {
+    const pathKey = issue.path && issue.path.length > 0 ? issue.path.join('.') : '_root';
+    const fieldMsg = issue.message || 'invalid value';
+    fields[pathKey] = fieldMsg;
+    lines.push(`- ${pathKey}: ${fieldMsg}`);
+  }
+
+  const message = `Invalid service input for ${serviceName}:\n${lines.join('\n')}`;
+  return { message, fields };
+}
+
+/**
+ * Validate service input against compiled schema (supports sync & async Zod/custom schemas)
+ * @param {Object|Function|null} schema - Schema definition
+ * @param {*} input - Input to validate
+ * @param {string} serviceName - Service name
+ * @returns {*|Promise<*>} Validated input
+ * @throws {ValidationError} When validation fails
+ */
+function validateServiceInput(schema, input, serviceName) {
+  const sanitized = sanitizeInput(input);
+
+  if (!schema) {
+    return sanitized;
+  }
+
+  const compiled = compileServiceSchema(schema);
+  if (!compiled) {
+    return sanitized;
+  }
+
+  // 1. Zod schema validation
+  if (compiled instanceof z.ZodType || typeof compiled.safeParse === 'function') {
+    try {
+      const result = compiled.safeParse(sanitized);
+      if (!result.success) {
+        const { message, fields } = formatZodErrors(result.error, serviceName);
+        throw new ValidationError(message, {
+          fields,
+          details: result.error.issues,
+        });
+      }
+      return result.data;
+    } catch (err) {
+      if (err instanceof ValidationError) {
+        throw err;
+      }
+      // If error occurred because of async refinements, evaluate with safeParseAsync
+      if (typeof compiled.safeParseAsync === 'function') {
+        return compiled.safeParseAsync(sanitized).then((asyncResult) => {
+          if (!asyncResult.success) {
+            const { message, fields } = formatZodErrors(asyncResult.error, serviceName);
+            throw new ValidationError(message, {
+              fields,
+              details: asyncResult.error.issues,
+            });
+          }
+          return asyncResult.data;
+        });
+      }
+      throw err;
+    }
+  }
+
+  // 2. Custom validation function (sync or async)
+  if (typeof compiled === 'function') {
+    try {
+      const res = compiled(sanitized);
+      if (res instanceof Promise) {
+        return res.then((asyncRes) => {
+          if (asyncRes === false) {
+            throw new ValidationError(`Invalid service input for ${serviceName}: custom validation rejected input`);
+          }
+          return typeof asyncRes === 'object' && asyncRes !== null ? asyncRes : sanitized;
+        });
+      }
+      if (res === false) {
+        throw new ValidationError(`Invalid service input for ${serviceName}: custom validation rejected input`);
+      }
+      return typeof res === 'object' && res !== null ? res : sanitized;
+    } catch (err) {
+      if (err instanceof ValidationError) {
+        throw err;
+      }
+      throw new ValidationError(`Invalid service input for ${serviceName}: ${err.message}`, {
+        cause: err,
+      });
+    }
+  }
+
+  return sanitized;
+}
+
+module.exports = {
+  z: zForServices,
+  compileServiceSchema,
+  descriptorToZod,
+  formatZodErrors,
+  sanitizeInput,
+  validateServiceInput,
+};

package/templates/skills/webspresso-usage/REFERENCE-framework.md

@@ -4,8 +4,10 @@ Sections follow the source repo layout (`index.js`, `src/`, `core/orm`, `doc/ind
 
 ## 1. What this framework is
 
-- **SSR**: Express + **Nunjucks**; URLs map to files under `pages/`.
-- **API**: File-based handlers under `pages/api/` with method suffixes and optional **Zod** validation (`req.input`).
+- **Architecture**: Modern full-stack Node.js framework with Next.js/Nuxt-style file-based routing.
+- **SSR**: Native server-side rendering with **Nunjucks**; URLs map directly to files under `pages/`.
+- **API**: 100% file-based handlers under `pages/api/` with HTTP method suffixes (`.get.js`, `.post.js`, `[id].delete.js`) and declarative **Zod** validation (`req.input`).
+- ⚠️ **CRITICAL ANTI-PATTERN**: **NEVER** create a `routes/` or `src/routes/` directory. **NEVER** use `app.get()`, `app.post()`, or `express.Router()`. All application routes must live under `pages/` and `pages/api/`.
 - **i18n**: JSON locales; `t('key')` in templates.
 - **ORM**: Knex-backed layer in `core/orm` — `defineModel`, `zdb` schema helpers, repositories, query builder, migrations.
 - **Plugins**: Register in `createApp({ plugins })`; optional `db` passed as `ctx.db`.
@@ -60,7 +62,7 @@ project/
 | `pageAssets` | Opt-in **`true`** or **`{ enabled?, stylesheets?, scripts? }`**. When on, route **`load()`** may return reserved keys **`stylesheets`** (string or list; also `{ href, media? }` objects) and **`scripts`** (string, `{ src, defer?, async?, type? }`, or list). They are removed from the root Nunjucks context and passed as **`pageHead`** with **`pageAssets: true`**. The app layout must print them (see [`views/layout.njk`](../../../views/layout.njk) in the package). Default **off** — `stylesheets` / `scripts` in **`load()`** behave as normal data keys. |
 | `clientRuntime` | Opt-in **`{ alpine?: boolean \| object, swup?: boolean \| object }`**. Serves **`/__webspresso/client-runtime/*`** (Alpine 3, swup 4 + Head + Scripts plugins + bootstrap). Template context **`clientRuntime`**; include [`views/partials/webspresso-client-runtime.njk`](../../../views/partials/webspresso-client-runtime.njk) and set **`<main id="swup">`** when swup is on. Env overrides: **`WEBSPRESSO_ALPINE`**, **`WEBSPRESSO_SWUP`** (`1` or `true`). Admin / dev dashboard HTML is unchanged (Mithril). Use **`data-no-swup`** on links for full page loads. HTMX is not used. |
 | `auth` | `AuthManager` from **`createAuth()`** / **`quickAuth()`** (`webspresso/core/auth`). Mounts cookie parser + **`express-session`** + per-request **`authenticate`**; sets **`req.user`**, **`req.auth`**. Injects named route middleware **`auth`** and **`guest`** (overwrites same keys in `middlewares` if you passed both — avoid reusing those names for custom handlers). |
-| `setupRoutes(app, ctx)` | **Register custom Express routes here** — runs **after** file routes and plugins’ `onRoutesReady`, **before** 404. **`ctx.clientRuntime`** is the resolved flags. **`ctx.authMiddleware`** is set when `auth` was passed (guards: `requireAuth`, `requireGuest`, `requireCan`, `requireVerified`, …). Do not rely on `app.get` *after* `createApp` returns unless routes are appended before the 404 middleware (see [`src/server.js`](../../../src/server.js)). |
+| `setupRoutes(app, ctx)` | Low-level server extension hook (e.g. mounting third-party sub-apps or raw middleware). ⚠️ **NEVER** use `setupRoutes` to define application domain or API routes. All application endpoints **MUST** live under `pages/` and `pages/api/`. |
 
 **Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware }` — `authMiddleware` is **`null`** when `auth` was not configured.
 
@@ -267,7 +269,7 @@ Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and pl
 
 ## 14. Pitfalls (for agents)
 
-1. **Custom Express routes** — use **`setupRoutes`**, not only `app.use` after `createApp` returns.
+1. **NEVER use Express routes (`app.get` / `routes/`)** — Webspresso is 100% file-based. Never create `routes/` or call `app.get()`. All routes must live in `pages/` and `pages/api/`.
 2. **File-router order** — understand precedence vs manual routes.
 3. **`ctx.db`** — only when `createApp({ db })` is set.
 4. **ORM hidden fields** — never expose to clients unintentionally.