webspresso 0.0.95 → 0.0.96

package/CLAUDE.md

@@ -0,0 +1,54 @@
+# Webspresso — Claude Code Assistant Guide
+
+Webspresso is a lightweight, zero-dependency-sprawl full-stack Node.js SSR & API framework.
+
+> [!IMPORTANT]
+> **Authoritative Rules & Architecture**: Always follow [AGENTS.md](AGENTS.md) and the modular topic guides in [.agents/](.agents/AGENTS.md).
+> **API & Types Ground Truth**: Inspect [index.d.ts](index.d.ts) for exact method signatures.
+
+---
+
+## ⚡ Essential Commands
+
+```bash
+# Run test suite (Node >= 20 required)
+npm test
+npx vitest run tests/unit/
+npx vitest run tests/integration/
+npx vitest run tests/security/
+
+# Development & diagnostics
+npm run dev
+npx webspresso doctor
+npx webspresso db:migrate
+```
+
+---
+
+## 🛡️ Critical Architecture Rules
+
+1. **100% File-Based Routing (NO `routes/` or `app.get()`)**:
+   - All endpoints live in `pages/api/...` with HTTP method extensions:
+     - `pages/api/notes.get.js` → `GET /api/notes`
+     - `pages/api/notes.post.js` → `POST /api/notes`
+     - `pages/api/notes/[id].get.js` → `GET /api/notes/:id`
+     - `pages/api/notes/[id].delete.js` → `DELETE /api/notes/:id`
+   - Contract: `module.exports = { schema: ({ z }) => ({ body, query, params }), middleware: ['auth'], handler: async (req, res) => ... }`
+
+2. **Strict Repository Pattern (NO Raw `db('table')`)**:
+   - Never run raw Knex queries (`req.db('table')`).
+   - Always use `req.db.getRepository('ModelName')` to ensure schema validation, hooks, scopes, and query caching.
+
+3. **Services Layer (NO `controllers/`)**:
+   - Place business logic in `services/domain/action.js` and invoke via `ctx.service('domain.action', input)`.
+
+4. **Zero-Dependency Native Dual Auth**:
+   - Never install `jsonwebtoken`, `passport`, or `express-session`.
+   - Use built-in `req.auth` and `webspresso/core/auth`.
+
+5. **Semantic Exceptions & Page Loaders**:
+   - Throw `NotFoundError`, `ValidationError`, `UnauthorizedError`, `ForbiddenError`.
+   - For SSR pages (`pages/name.njk`), use companion loaders `pages/name.js` exporting `async function load({ req, res, db, ctx })`. Never call `res.render()` manually.
+
+6. **Zero Regression Policy**:
+   - Always run the relevant Vitest tests before declaring any task complete.

package/README.md

@@ -28,7 +28,9 @@ Open **`http://localhost:3000`** in your browser.
 ## ✨ Why Webspresso?
 
 - **Zero-Dependency Sprawl**: Core framework features (Dual Auth, JWT signing, Error handling, Streaming Compression, Graceful Shutdown, Template Helpers) rely strictly on native Node.js standard modules (`crypto`, `path`, `fs`, `events`, `zlib`, `async_hooks`) without bloated dependency trees.
-- **File-Based Routing**: Templates in `pages/` automatically become public URL routes with support for dynamic params (`[id]`) and catch-all wildcards (`[...slug]`).
+- **File-Based Routing & API Suffixes**: Pages and APIs automatically map to clean URLs with dynamic params (`[id]`), wildcards (`[...slug]`), and method suffixes (`.get.js`, `.post.js`, `.delete.js`, `.patch.js`, `.put.js`).
+- **Feature Modules (`defineModule`)**: Domain-driven modular organization for large projects (`modules/{name}/pages`, `api`, `services`, `middleware`).
+- **Modern Page & API Helpers (`definePage`, `defineApi`)**: Declarative Zod request schemas, unified execution context, and automatic JSON response serialization.
 - **Server Data Prefetching (`load()`)**: Page routes export `async function load({ req, res, db, ctx })` to fetch data server-side before template compilation.
 - **Services Layer**: File-based auto-discovery in `services/` with declarative Zod validation, role/predicate authorization guards, and memoization.
 - **Ambient Transactions**: Knex database transactions automatically bind to `AsyncLocalStorage` (`core/orm/transaction.js`). Scoped repositories seamlessly participate in active transactions without manual `trx` passing.
@@ -78,33 +80,35 @@ app.listen(PORT, () => {
 
 ```javascript
 // pages/index.js
-module.exports = {
+const { definePage } = require('webspresso');
+
+module.exports = definePage({
   async load({ req, ctx }) {
     return {
       title: 'Home Page',
       user: req.user || null,
     };
   },
-};
+});
 ```
 
 ### 3. Validated JSON API Endpoint (`pages/api/greet.post.js`)
 ```javascript
-module.exports = {
-  schema({ z }) {
-    return {
-      body: z.object({
-        name: z.string().min(2),
-      }),
-    };
+const { defineApi, z } = require('webspresso');
+
+module.exports = defineApi({
+  schema: {
+    body: z.object({
+      name: z.string().min(2),
+    }),
   },
 
-  async handler(req, res) {
+  async handler(req, res, ctx) {
     // req.input is typed and validated by Zod
-    const result = await req.service('user.greet', req.input.body);
-    res.json(result);
+    const result = await ctx.service('user.greet', req.input.body);
+    return result; // Automatically serialized as JSON (HTTP 200)
   },
-};
+});
 ```
 
 ---

package/bin/commands/agents-init.js

@@ -0,0 +1,169 @@
+'use strict';
+
+/**
+ * Agents Init Command
+ * Scaffold and synchronize AI Agent guidelines (.agents/, AGENTS.md, CLAUDE.md, .cursorrules)
+ * @module bin/commands/agents-init
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SOURCE_ROOT = path.resolve(__dirname, '../../');
+const SOURCE_AGENTS_DIR = path.join(SOURCE_ROOT, '.agents');
+const SOURCE_AGENTS_MD = path.join(SOURCE_ROOT, 'AGENTS.md');
+const SOURCE_CLAUDE_MD = path.join(SOURCE_ROOT, 'CLAUDE.md');
+const SOURCE_CURSORRULES = path.join(SOURCE_ROOT, '.cursorrules');
+
+/**
+ * Copies a file if force is true or if target file does not exist.
+ * @param {string} src
+ * @param {string} dest
+ * @param {boolean} force
+ * @returns {'created'|'overwritten'|'skipped'}
+ */
+function copyFileSafe(src, dest, force = false) {
+  if (!fs.existsSync(src)) return 'skipped';
+  const destExists = fs.existsSync(dest);
+
+  if (destExists && !force) {
+    return 'skipped';
+  }
+
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  fs.copyFileSync(src, dest);
+  return destExists ? 'overwritten' : 'created';
+}
+
+/**
+ * Scaffolds AI Agent rules and guidebook files into target project directory.
+ * @param {string} targetDir
+ * @param {Object} [options]
+ * @param {boolean} [options.force=false]
+ * @param {boolean} [options.claude=true]
+ * @param {boolean} [options.cursor=true]
+ * @param {boolean} [options.guides=true]
+ * @returns {{ installed: string[], skipped: string[], errors: string[] }}
+ */
+function scaffoldAgentsFiles(targetDir, options = {}) {
+  const force = options.force === true;
+  const includeClaude = options.claude !== false;
+  const includeCursor = options.cursor !== false;
+  const includeGuides = options.guides !== false;
+
+  const result = {
+    installed: [],
+    skipped: [],
+    errors: [],
+  };
+
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  // 1. Root AGENTS.md
+  if (fs.existsSync(SOURCE_AGENTS_MD)) {
+    const destAgentsMd = path.join(targetDir, 'AGENTS.md');
+    const status = copyFileSafe(SOURCE_AGENTS_MD, destAgentsMd, force);
+    if (status === 'created' || status === 'overwritten') {
+      result.installed.push('AGENTS.md');
+    } else {
+      result.skipped.push('AGENTS.md');
+    }
+  }
+
+  // 2. CLAUDE.md
+  if (includeClaude && fs.existsSync(SOURCE_CLAUDE_MD)) {
+    const destClaudeMd = path.join(targetDir, 'CLAUDE.md');
+    const status = copyFileSafe(SOURCE_CLAUDE_MD, destClaudeMd, force);
+    if (status === 'created' || status === 'overwritten') {
+      result.installed.push('CLAUDE.md');
+    } else {
+      result.skipped.push('CLAUDE.md');
+    }
+  }
+
+  // 3. .cursorrules
+  if (includeCursor && fs.existsSync(SOURCE_CURSORRULES)) {
+    const destCursor = path.join(targetDir, '.cursorrules');
+    const status = copyFileSafe(SOURCE_CURSORRULES, destCursor, force);
+    if (status === 'created' || status === 'overwritten') {
+      result.installed.push('.cursorrules');
+    } else {
+      result.skipped.push('.cursorrules');
+    }
+  }
+
+  // 4. .agents/*.md Guidebook directory
+  if (includeGuides && fs.existsSync(SOURCE_AGENTS_DIR)) {
+    const destAgentsDir = path.join(targetDir, '.agents');
+    if (!fs.existsSync(destAgentsDir)) {
+      fs.mkdirSync(destAgentsDir, { recursive: true });
+    }
+
+    const files = fs.readdirSync(SOURCE_AGENTS_DIR).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+      const srcFile = path.join(SOURCE_AGENTS_DIR, file);
+      const destFile = path.join(destAgentsDir, file);
+      const relPath = path.join('.agents', file);
+      const status = copyFileSafe(srcFile, destFile, force);
+      if (status === 'created' || status === 'overwritten') {
+        result.installed.push(relPath);
+      } else {
+        result.skipped.push(relPath);
+      }
+    }
+  }
+
+  return result;
+}
+
+function registerCommand(program) {
+  program
+    .command('agents:init')
+    .alias('agents')
+    .alias('agents:setup')
+    .alias('ai:init')
+    .description('Scaffold AI Agent guidelines (.agents/, AGENTS.md, CLAUDE.md, .cursorrules)')
+    .option('-p, --path <path>', 'Target project directory', process.cwd())
+    .option('-f, --force', 'Overwrite existing agent guideline files', false)
+    .option('--no-claude', 'Skip generating CLAUDE.md')
+    .option('--no-cursor', 'Skip generating .cursorrules')
+    .option('--no-guides', 'Skip generating .agents/ topic guide bundle')
+    .action(async (options) => {
+      const targetDir = path.resolve(options.path || process.cwd());
+      console.log(`\n🤖 Initializing AI Agent Guidelines in: ${targetDir}\n`);
+
+      const result = scaffoldAgentsFiles(targetDir, {
+        force: options.force,
+        claude: options.claude,
+        cursor: options.cursor,
+        guides: options.guides,
+      });
+
+      if (result.installed.length > 0) {
+        console.log('✅ Installed/Updated:');
+        for (const file of result.installed) {
+          console.log(`   + ${file}`);
+        }
+      }
+
+      if (result.skipped.length > 0) {
+        console.log('\n⚠️  Skipped (already exists, use --force to overwrite):');
+        for (const file of result.skipped) {
+          console.log(`   - ${file}`);
+        }
+      }
+
+      console.log('\n🎉 AI Agent Guidelines ready! Agents (Cursor, Claude Code, Antigravity) will follow strict Webspresso standards.\n');
+    });
+}
+
+module.exports = {
+  registerCommand,
+  scaffoldAgentsFiles,
+};

package/bin/commands/api.js

@@ -1,6 +1,9 @@
+'use strict';
+
 /**
  * API Command
- * Add a new API endpoint to the current project
+ * Add a new API endpoint with modern Webspresso schema & handler contract
+ * @module bin/commands/api
  */
 
 let _inquirer;
@@ -13,64 +16,127 @@ const inquirer = {
 const fs = require('fs');
 const path = require('path');
 
+const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+
+function parseRouteAndMethod(rawInput, optionMethod) {
+  let route = String(rawInput || '').trim();
+  let method = optionMethod ? String(optionMethod).toUpperCase() : null;
+
+  // Normalize /api/ prefix if present
+  route = route.replace(/^\/?api\/?/, '');
+
+  // Check if route has method suffix (e.g. notes.post or notes.post.js or [id].get)
+  for (const m of VALID_METHODS) {
+    const lower = m.toLowerCase();
+    if (route.endsWith(`.${lower}.js`)) {
+      method = m;
+      route = route.slice(0, -(lower.length + 4));
+      break;
+    } else if (route.endsWith(`.${lower}`)) {
+      method = m;
+      route = route.slice(0, -(lower.length + 1));
+      break;
+    }
+  }
+
+  return {
+    route: route.replace(/^\/+|\/+$/g, ''),
+    method: method || 'GET',
+  };
+}
+
 function registerCommand(program) {
   program
-    .command('api')
-    .description('Add a new API endpoint to the current project')
-    .action(async () => {
-      if (!fs.existsSync('pages')) {
-        console.error('❌ Not a Webspresso project! Run this command in your project directory.');
+    .command('api [route]')
+    .description('Add a new API endpoint to pages/api/ with schema validation and handler')
+    .option('-m, --method <method>', 'HTTP method (GET, POST, PUT, PATCH, DELETE)', 'GET')
+    .option('--auth', 'Protect with session auth middleware')
+    .option('--jwt', 'Protect with JWT bearer middleware')
+    .action(async (routeArg, options) => {
+      const pagesDir = path.resolve(process.cwd(), 'pages');
+      if (!fs.existsSync(pagesDir)) {
+        console.error('❌ Not a Webspresso project! (pages/ directory not found)');
         process.exit(1);
       }
-      
-      const answers = await inquirer.prompt([
-        {
-          type: 'input',
-          name: 'route',
-          message: 'API route path (e.g., /api/users or /api/users/[id]):',
-          validate: (input) => {
-            if (!input.startsWith('/api/')) {
-              return 'API route must start with /api/';
-            }
-            return true;
-          }
-        },
-        {
-          type: 'list',
-          name: 'method',
-          message: 'HTTP method:',
-          choices: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
-          default: 'GET'
-        }
-      ]);
-      
-      const route = answers.route.replace(/^\/api\//, '');
-      const routePath = path.join('pages', 'api', route);
+
+      let route;
+      let method;
+
+      if (routeArg) {
+        const parsed = parseRouteAndMethod(routeArg, options.method);
+        route = parsed.route;
+        method = parsed.method;
+      } else {
+        const answers = await inquirer.prompt([
+          {
+            type: 'input',
+            name: 'route',
+            message: 'API route path (e.g., users or users/[id] or /api/notes):',
+            validate: (input) => {
+              if (!input || !input.trim()) return 'API route is required';
+              return true;
+            },
+          },
+          {
+            type: 'list',
+            name: 'method',
+            message: 'HTTP method:',
+            choices: VALID_METHODS,
+            default: options.method ? options.method.toUpperCase() : 'GET',
+          },
+        ]);
+
+        const parsed = parseRouteAndMethod(answers.route, answers.method);
+        route = parsed.route;
+        method = parsed.method;
+      }
+
+      const methodUpper = String(method).toUpperCase();
+      const methodLower = methodUpper.toLowerCase();
+      const routePath = path.join(pagesDir, 'api', route);
       const dirPath = path.dirname(routePath);
       const fileName = path.basename(routePath);
-      
-      // Create directory
+
       fs.mkdirSync(dirPath, { recursive: true });
-      
-      // Create API file
-      const apiFile = path.join(dirPath, `${fileName}.${answers.method.toLowerCase()}.js`);
-      
-      const apiContent = `/**
- * ${answers.method} ${answers.route}
+
+      const apiFile = path.join(dirPath, `${fileName}.${methodLower}.js`);
+
+      const middlewares = [];
+      if (options.auth) middlewares.push("'auth'");
+      if (options.jwt) middlewares.push("'jwt'");
+      const middlewareStr = middlewares.length > 0 ? `\n  middleware: [${middlewares.join(', ')}],` : '';
+
+      const hasParams = route.includes('[');
+      const hasBody = ['POST', 'PUT', 'PATCH'].includes(methodUpper);
+
+      const apiContent = `'use strict';
+
+/**
+ * ${methodUpper} /api/${route}
  */
+module.exports = {
+  // Input validation schema (Zod)
+  schema: ({ z }) => ({
+    ${hasParams ? 'params: z.object({ id: z.string().min(1) }),\n    ' : ''}${hasBody ? 'body: z.object({\n      // Define body schema here\n    }),\n    ' : ''}query: z.object({\n      // Define query params here\n    }),
+  }),${middlewareStr}
 
-module.exports = async function handler(req, res) {
-  res.json({
-    message: 'Hello from ${answers.route}',
-    method: '${answers.method}',
-    timestamp: new Date().toISOString()
-  });
+  // Request Handler
+  handler: async (req, res) => {
+    // req.db.getRepository('ModelName') -> Access ORM models
+    // req.service('service.name', payload) -> Invoke service
+    // req.input -> Type-safe validated body, query, params
+    return res.json({
+      success: true,
+      message: 'Hello from /api/${route}',
+      timestamp: new Date().toISOString(),
+    });
+  },
 };
 `;
-      
-      fs.writeFileSync(apiFile, apiContent);
-      console.log(`\n✅ Created ${apiFile}\n`);
+
+      fs.writeFileSync(apiFile, apiContent, 'utf8');
+      console.log(`\n✅ Created API endpoint:\n   ${path.relative(process.cwd(), apiFile)}\n`);
     });
 }
 
-module.exports = { registerCommand };
+module.exports = { registerCommand, parseRouteAndMethod };

package/bin/commands/doctor.js

@@ -99,6 +99,23 @@ function registerCommand(program) {
         warnings += 1;
       }
 
+      // Check anti-pattern directories
+      const forbiddenRoutes = [path.join(cwd, 'routes'), path.join(cwd, 'src', 'routes')];
+      for (const p of forbiddenRoutes) {
+        if (fs.existsSync(p) && fs.statSync(p).isDirectory()) {
+          line('⚠', `Anti-pattern detected: "${path.relative(cwd, p)}" folder found. Webspresso uses 100% file-based routing; move endpoints to "pages/api/".`);
+          warnings += 1;
+        }
+      }
+
+      const forbiddenControllers = [path.join(cwd, 'controllers'), path.join(cwd, 'src', 'controllers')];
+      for (const p of forbiddenControllers) {
+        if (fs.existsSync(p) && fs.statSync(p).isDirectory()) {
+          line('⚠', `Anti-pattern detected: "${path.relative(cwd, p)}" folder found. Encapsulate business logic in "services/<domain>/<action>.js" instead of controllers.`);
+          warnings += 1;
+        }
+      }
+
       const pagesPath = path.join(cwd, 'pages');
       if (fs.existsSync(pagesPath) && fs.statSync(pagesPath).isDirectory()) {
         line('✓', 'pages/ directory present');
@@ -119,6 +136,8 @@ function registerCommand(program) {
           return name;
         }
 
+        const VALID_API_METHODS = ['.get.js', '.post.js', '.put.js', '.patch.js', '.delete.js'];
+
         function scanRoutes(dirPath, relativeDir = '', isApi = false) {
           const children = fs.readdirSync(dirPath);
           const kept = [];
@@ -148,6 +167,12 @@ function registerCommand(program) {
               const ext = path.extname(child);
               if (isApi) {
                 if (ext === '.js') {
+                  const hasMethod = VALID_API_METHODS.some((m) => child.endsWith(m));
+                  if (!hasMethod && !child.startsWith('_')) {
+                    line('⚠', `API route "pages/${relPath}" is missing an HTTP method suffix (e.g. .get.js, .post.js).`);
+                    warnings += 1;
+                    routingChecksPassed = false;
+                  }
                   const base = path.basename(child, ext);
                   kept.push({ name: base, isDir: false, original: child });
                 }
@@ -190,6 +215,16 @@ function registerCommand(program) {
         warnings += 1;
       }
 
+      console.log('\nAI Agent Guidelines');
+      console.log('-------------------');
+      const agentsMdPath = path.join(cwd, 'AGENTS.md');
+      const agentsDirPath = path.join(cwd, '.agents');
+      if (fs.existsSync(agentsMdPath) && fs.existsSync(agentsDirPath)) {
+        line('✓', 'AGENTS.md and .agents/ topic guides present');
+      } else {
+        line('○', 'No AGENTS.md / .agents/ found. Tip: run "npx webspresso agents:init" to scaffold AI agent guidelines.');
+      }
+
       console.log('\nEnvironment files');
       console.log('-----------------');
 

package/bin/commands/new.js

@@ -14,6 +14,7 @@ const fs = require('fs');
 const path = require('path');
 const { runInstallation, startDevServer } = require('../utils/project');
 const { getSeedFileTemplate } = require('../utils/seed');
+const { scaffoldAgentsFiles } = require('./agents-init');
 
 /** `.` / `./` mean scaffold into the current working directory */
 function isCurrentDirAlias(name) {
@@ -45,6 +46,7 @@ function registerCommand(program) {
     .description('Create a new Webspresso project')
     .option('-t, --template <template>', 'Template to use (minimal, full)', 'minimal')
     .option('--no-tailwind', 'Skip Tailwind CSS setup')
+    .option('--no-agents', 'Skip AI Agent guidelines setup (.agents/, AGENTS.md, CLAUDE.md, .cursorrules)')
     .option('-i, --install', 'Auto install dependencies and build CSS')
     .option('-y, --yes', 'Non-interactive: no database, skip install unless -i/--install, skip dev server')
     .action(async (projectNameArg, options) => {
@@ -718,8 +720,17 @@ module.exports = {
         
         console.log('✅ Tailwind CSS setup complete!');
       }
-      
-      
+
+      // Scaffold AI Agent guidelines unless --no-agents is specified
+      if (options.agents !== false) {
+        try {
+          console.log('\n🤖 Setting up AI Agent guidelines (.agents/, AGENTS.md, CLAUDE.md, .cursorrules)...\n');
+          scaffoldAgentsFiles(projectPath, { force: true, claude: true, cursor: true, guides: true });
+        } catch (e) {
+          // Non-fatal
+        }
+      }
+
       // Auto install if requested or ask interactively
       if (autoInstall) {
         await runInstallation(projectPath, useTailwind);