webspresso 0.0.95 → 0.0.97

package/bin/commands/admin-setup.js

@@ -6,7 +6,6 @@
 const fs = require('fs');
 const path = require('path');
 const { loadDbConfig } = require('../utils/db');
-const { generateAdminUsersMigration } = require('../../plugins/admin-panel/migration-template');
 
 function registerCommand(program) {
   program
@@ -53,6 +52,7 @@ function registerCommand(program) {
         const filepath = path.join(migrationDir, filename);
         
         // Generate migration content
+        const { generateAdminUsersMigration } = require('../../plugins/admin-panel/migration-template');
         const content = generateAdminUsersMigration();
         
         // Write migration file

package/bin/commands/agents-init.js

@@ -0,0 +1,209 @@
+'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';
+}
+
+/**
+ * Recursively copies a directory safely.
+ * @param {string} srcDir
+ * @param {string} destDir
+ * @param {boolean} force
+ * @param {string[]} installed
+ * @param {string[]} skipped
+ * @param {string} baseRel
+ */
+function copyDirSafe(srcDir, destDir, force = false, installed = [], skipped = [], baseRel = '') {
+  if (!fs.existsSync(srcDir)) return;
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    const relPath = path.join(baseRel, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirSafe(srcPath, destPath, force, installed, skipped, relPath);
+    } else {
+      const status = copyFileSafe(srcPath, destPath, force);
+      if (status === 'created' || status === 'overwritten') {
+        installed.push(relPath);
+      } else {
+        skipped.push(relPath);
+      }
+    }
+  }
+}
+
+/**
+ * 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 and skills/ directory
+  if (includeGuides && fs.existsSync(SOURCE_AGENTS_DIR)) {
+    const destAgentsDir = path.join(targetDir, '.agents');
+    if (!fs.existsSync(destAgentsDir)) {
+      fs.mkdirSync(destAgentsDir, { recursive: true });
+    }
+
+    const entries = fs.readdirSync(SOURCE_AGENTS_DIR, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === 'internal') continue; // exclude internal reviews from user projects
+      const srcPath = path.join(SOURCE_AGENTS_DIR, entry.name);
+      const destPath = path.join(destAgentsDir, entry.name);
+      const relPath = path.join('.agents', entry.name);
+
+      if (entry.isDirectory()) {
+        copyDirSafe(srcPath, destPath, force, result.installed, result.skipped, relPath);
+      } else if (entry.name.endsWith('.md')) {
+        const status = copyFileSafe(srcPath, destPath, 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/audit-prune.js

@@ -3,7 +3,6 @@
  */
 
 const { loadDbConfig, createDbInstance } = require('../utils/db');
-const { purgeAuditLogs } = require('../../plugins/audit-log/purge');
 
 function registerCommand(program) {
   program
@@ -28,6 +27,7 @@ function registerCommand(program) {
       const olderThan = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
 
       try {
+        const { purgeAuditLogs } = require('../../plugins/audit-log/purge');
         const deleted = await purgeAuditLogs(knex, {
           tableName: options.table,
           olderThan,

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/favicon-generate.js

@@ -6,7 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 function getSharp() {
-  return process.env.NODE_ENV === 'test'
+  return (process.env.NODE_ENV === 'test' || process.env.VITEST)
     ? require('../../tests/mocks/sharp')
     : require('sharp');
 }

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);

package/bin/commands/orm-map.js

@@ -6,10 +6,6 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const { getWebspressoOrmForProject } = require('../utils/resolve-webspresso-orm');
-const { loadProjectModels } = require('../utils/orm-map-load');
-const { buildSnapshot, buildMermaidErDiagram } = require('../utils/orm-map-snapshot');
-const { buildOrmMapHtml, readPackageName } = require('../utils/orm-map-html');
 
 function ensureOpenInsideTrustedRoots(absFile, cwd) {
   if (!fs.existsSync(absFile)) {
@@ -72,6 +68,11 @@ function registerCommand(program) {
     .option('-e, --env <environment>', 'Config environment', 'development')
     .option('-m, --models <dir>', 'Models directory (overrides config default ./models)')
     .action((options) => {
+      const { getWebspressoOrmForProject } = require('../utils/resolve-webspresso-orm');
+      const { loadProjectModels } = require('../utils/orm-map-load');
+      const { buildSnapshot, buildMermaidErDiagram } = require('../utils/orm-map-snapshot');
+      const { buildOrmMapHtml, readPackageName } = require('../utils/orm-map-html');
+
       const cwd = process.cwd();
       const { modelsDir, loaded, errors } = loadProjectModels(cwd, {
         modelsOverride: options.models,