webspresso 0.0.97 → 0.0.99

package/.agents/ROUTING.md

@@ -53,7 +53,10 @@ All routes are automatically discovered and registered from the `pages/` directo
 | `pages/index.njk` | `GET` | `/` | Home page (SSR Nunjucks) |
 | `pages/about.njk` | `GET` | `/about` | Static SSR page |
 | `pages/notes/[id].njk` | `GET` | `/notes/:id` | Dynamic SSR route with param |
+| `pages/(marketing)/about.njk` | `GET` | `/about` | Route Group page (omits `(marketing)`) |
+| `pages/(auth)/login.njk` | `GET` | `/login` | Route Group with isolated layout & middleware |
 | `pages/api/notes.get.js` | `GET` | `/api/notes` | List notes API endpoint |
+| `pages/api/(v1)/notes.get.js` | `GET` | `/api/notes` | API route inside Route Group |
 | `pages/api/notes.post.js` | `POST` | `/api/notes` | Create note API endpoint |
 | `pages/api/notes/[id].get.js` | `GET` | `/api/notes/:id` | Get single note API endpoint |
 | `pages/api/notes/[id].put.js` | `PUT` | `/api/notes/:id` | Update note API endpoint |
@@ -148,7 +151,50 @@ module.exports = {
 
 ---
 
-## 4. SSR Page Routes (`load()` Loader)
+## 4. Route Groups `(group)` Syntax & Layout Isolation
+
+Webspresso supports Next.js / Nuxt-style **Route Groups**. Any directory name wrapped in parentheses `(groupName)` is treated as an organizational group:
+- **Clean Public URLs**: The parenthesized directory name is completely omitted from the generated URL path.
+- **Layout & Middleware Isolation**: The directory hierarchy is preserved for cascading middleware (`_middleware.js`) and nested layouts (`_layout.njk`), allowing distinct shells and security guards without polluting public route URLs.
+- **Nesting & Dynamic Route Support**: Route groups can be nested (e.g. `(shop)/(checkout)/cart.njk` → `/cart`), combined with dynamic segments (e.g. `(app)/users/[id].njk` → `/users/:id`), and applied to API routes (`pages/api/(v1)/items.get.js` → `/api/items` or `pages/(marketing)/api/newsletter.post.js` → `/api/newsletter`).
+
+### 4.1 Route Group Structure Example
+
+```
+pages/
+├── (marketing)/
+│   ├── _layout.njk          # Marketing layout (Hero header, footer)
+│   ├── _middleware.js       # Track analytics / marketing headers
+│   ├── index.njk            -> GET /
+│   ├── about.njk            -> GET /about
+│   └── api/
+│       └── newsletter.post.js -> POST /api/newsletter
+├── (auth)/
+│   ├── _layout.njk          # Centered card layout (no nav/footer)
+│   ├── _middleware.js       # Guest-only guard (redirects authenticated users)
+│   ├── login.njk            -> GET /login
+│   └── register.njk         -> GET /register
+└── (app)/
+    ├── _layout.njk          # App shell layout with sidebar
+    ├── _middleware.js       # Strict session auth guard
+    └── dashboard.njk        -> GET /dashboard
+```
+
+### 4.2 Programmatic Utilities
+Webspresso exports core helpers to inspect and transform route group paths:
+```javascript
+const { isRouteGroupSegment, stripRouteGroups } = require('webspresso');
+
+isRouteGroupSegment('(marketing)'); // true
+isRouteGroupSegment('about');       // false
+
+stripRouteGroups('/(marketing)/about'); // '/about'
+stripRouteGroups('/(shop)/(checkout)/cart'); // '/cart'
+```
+
+---
+
+## 5. SSR Page Routes (`load()` Loader)
 
 For server-rendered Nunjucks HTML pages, use `.njk` templates and companion `.js` loader files (or inline `async function load` in a `.js` file):
 
@@ -174,7 +220,7 @@ module.exports = {
 
 ---
 
-## 5. Module & File-Based Discovery (`src/pages`, `src/api`, `modules/{name}`)
+## 6. Module & File-Based Discovery (`src/pages`, `src/api`, `modules/{name}`)
 
 Webspresso supports clean, domain-driven module discovery alongside root-level pages and APIs:
 
@@ -204,7 +250,7 @@ src/
         auth-guard.js   -> module-local named middleware 'authGuard'
 ```
 
-### 5.1 `definePage()` Contract
+### 6.1 `definePage()` Contract
 ```javascript
 const { definePage } = require('webspresso');
 
@@ -230,7 +276,7 @@ module.exports = definePage({
 });
 ```
 
-### 5.2 `defineApi()` Contract
+### 6.2 `defineApi()` Contract
 ```javascript
 const { defineApi, z } = require('webspresso');
 
@@ -252,7 +298,7 @@ module.exports = defineApi({
 });
 ```
 
-### 5.3 `defineModule()` Contract
+### 6.3 `defineModule()` Contract
 ```javascript
 const { defineModule } = require('webspresso');
 
@@ -270,7 +316,7 @@ module.exports = defineModule({
 });
 ```
 
-### 5.4 Route Introspection (`app.routes.list()`)
+### 6.4 Route Introspection (`app.routes.list()`)
 Compiled routes are accessible at runtime for tooling, CLI inspection, and documentation:
 ```javascript
 const routeList = app.routes.list();
@@ -280,9 +326,83 @@ const routeList = app.routes.list();
 // ]
 ```
 
+### 6.5 Server-Sent Events (SSE) Streaming (`res.sse`)
+For real-time event streaming and LLM token outputs, use the native `res.sse()` helper (or `{ sse }` from `ctx`):
+
+```javascript
+// File: pages/api/ai/chat.post.js
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  handler: async (req, res, { sse }) => {
+    // 1. Controller mode with automatic keepalive & reconnection directives
+    const stream = sse({ heartbeat: 15000, retry: 3000 });
+
+    await stream.send({ delta: 'Hello ' });
+    await stream.send({ event: 'delta', data: { text: 'world!' }, id: '1' });
+    stream.close();
+
+    // 2. OR stream an async generator / LLM stream directly:
+    // return res.sse(async function*() {
+    //   for await (const chunk of llmStream) {
+    //     yield { token: chunk.text };
+    //   }
+    // });
+  },
+});
+```
+
+### 6.6 Cascading Middleware (`_middleware.js`) & Nested Layouts (`_layout.njk`)
+
+Webspresso supports folder-level cascading middleware inheritance and nested layouts across directory trees:
+
+#### 1. Cascading Middleware (`_middleware.js`)
+Any directory under `pages/` can declare a `_middleware.js` file:
+- **Execution Order**: Middlewares execute in top-down ancestral order (from root down to route leaf) before route handlers and route-specific middleware.
+- **Early Termination**: If any middleware sends headers (e.g. `res.status(401).json(...)` or `res.redirect('/login')`), execution halts immediately and downstream middlewares/handlers are skipped.
+- **Export Formats**: Standard Express middleware function `(req, res, next)`, async function, named middleware string/array `['auth', 'cors']`, or middleware tuples with options `[['rateLimit', { max: 100 }]]`.
+
+```
+pages/
+├── _middleware.js            # Runs for ALL routes (adds global headers / request ID)
+├── api/
+│   └── admin/
+│       ├── _middleware.js    # Protects all /api/admin/* endpoints
+│       └── metrics.get.js    # Inherits root + admin middleware
+└── dashboard/
+    ├── _middleware.js        # Auth guard for /dashboard/* pages
+    └── settings.njk
+```
+
+#### 2. Nested Layouts (`_layout.njk` & `_layout.js`)
+Pages under `pages/` automatically inherit ancestor layouts:
+- **Wrapping Order**: Child template is rendered first, then wrapped by layouts from innermost to outermost using `{{ content | safe }}`.
+- **Layout Loaders (`_layout.js`)**: Companion `_layout.js` files can export `async function load(req, ctx)` to supply shared data (e.g., site title, navigation, breadcrumbs) in top-down order before the page loader runs.
+- **Opt-Out**: A page can opt out of automatic layout wrapping by setting `layout: false` in its companion `.js` config/loader, or by explicitly using `{% extends "..." %}` in its Nunjucks template.
+
+```html
+{# pages/_layout.njk #}
+<!DOCTYPE html>
+<html>
+<head><title>{{ siteTitle }}</title></head>
+<body>
+  <header>Global Nav</header>
+  {{ content | safe }}
+</body>
+</html>
+```
+
+```html
+{# pages/dashboard/_layout.njk #}
+<div class="dashboard-shell">
+  <aside>Dashboard Sidebar</aside>
+  <main>{{ content | safe }}</main>
+</div>
+```
+
 ---
 
-## 6. Summary Checklist for Agents
+## 7. Summary Checklist for Agents
 
 When a user asks to add or modify endpoints:
 1. Identify the URL and method (e.g. `POST /api/auth/register` or `POST /auth/login`).

package/AGENTS.md

@@ -142,6 +142,7 @@ Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register
 - `restResourcePlugin`: Zero-boilerplate RESTful CRUD API generator directly from ORM models with eager loading, sanitization, filtering, pagination, and soft-delete scoping.
 - `xlsxPlugin`: Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and built-in services (`xlsx.generate`, `xlsx.parse`, `xlsx.exportModel`).
 - `csvPlugin`: RFC 4180 CSV generator, parser, Excel UTF-8 BOM compatibility, formula sanitization, streaming writer (`res.csv`), and built-in services (`csv.generate`, `csv.parse`, `csv.exportModel`).
+- `apiKeyPlugin`: Zero-dependency B2B & Developer API Key Management with SHA-256 secure storage, constant-time verification, granular wildcard scopes, named route middleware (`ctx.middlewares.apiKey`), and non-blocking usage tracking.
 
 ---
 

package/bin/commands/add-esbuild.js

@@ -0,0 +1,80 @@
+/**
+ * Add esbuild Command
+ * Add esbuild client bundling and incremental watch to the project
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function registerCommand(program) {
+  program
+    .command('add esbuild')
+    .alias('add:esbuild')
+    .description('Add esbuild client bundling and incremental watch to the project')
+    .action(async () => {
+      if (!fs.existsSync('package.json')) {
+        console.error('❌ Not a Webspresso project! Run this command in your project directory.');
+        process.exit(1);
+      }
+
+      console.log('\n⚡ Adding esbuild client bundler to your project...\n');
+
+      // Read package.json
+      const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+      packageJson.devDependencies = packageJson.devDependencies || {};
+      packageJson.devDependencies['esbuild'] = '^0.25.0';
+
+      packageJson.scripts = packageJson.scripts || {};
+      packageJson.scripts['build:js'] = 'esbuild src/client/main.js --bundle --outdir=public/js --minify --sourcemap';
+      packageJson.scripts['watch:js'] = 'esbuild src/client/main.js --bundle --outdir=public/js --sourcemap --watch';
+
+      fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2) + '\n');
+      console.log('✅ Updated package.json (esbuild devDependency and build:js / watch:js scripts)');
+
+      // Create src/client directory
+      if (!fs.existsSync('src/client')) {
+        fs.mkdirSync('src/client', { recursive: true });
+      }
+
+      // Create src/client/main.js if not exists
+      const mainJsPath = path.join('src', 'client', 'main.js');
+      if (!fs.existsSync(mainJsPath)) {
+        const clientStarterCode = `// Client-side JavaScript entry point
+console.log('⚡ Webspresso client script loaded');
+
+document.addEventListener('DOMContentLoaded', () => {
+  // Client interactivity
+});
+`;
+        fs.writeFileSync(mainJsPath, clientStarterCode);
+        console.log('✅ Created src/client/main.js');
+      }
+
+      // Create public/js directory
+      if (!fs.existsSync(path.join('public', 'js'))) {
+        fs.mkdirSync(path.join('public', 'js'), { recursive: true });
+      }
+
+      // Update layout.njk to include script if not present
+      const layoutPath = path.join('views', 'layout.njk');
+      if (fs.existsSync(layoutPath)) {
+        let layoutContent = fs.readFileSync(layoutPath, 'utf-8');
+        if (!layoutContent.includes('/js/main.js')) {
+          layoutContent = layoutContent.replace(
+            /(<\/head>)/,
+            '  <script defer src="/js/main.js"></script>\n$1'
+          );
+          fs.writeFileSync(layoutPath, layoutContent);
+          console.log('✅ Updated views/layout.njk (<script defer src="/js/main.js"></script>)');
+        }
+      }
+
+      console.log('\n✅ esbuild setup complete!\n');
+      console.log('Next steps:');
+      console.log('  npm install');
+      console.log('  npm run build:js');
+      console.log('  npm run dev\n');
+    });
+}
+
+module.exports = { registerCommand };

package/bin/commands/add-tailwind.js

@@ -10,14 +10,26 @@ const { execSync } = require('child_process');
 function registerCommand(program) {
   program
     .command('add tailwind')
+    .alias('add:tailwind')
     .description('Add Tailwind CSS to the project with build process')
-    .action(async () => {
+    .option('--v4', 'Use Tailwind CSS v4 (Oxide engine, LightningCSS, zero postcss config)')
+    .option('--v3', 'Use Tailwind CSS v3 (legacy PostCSS engine)')
+    .option('-v, --tailwind-version <version>', 'Tailwind version (3 or 4)', '3')
+    .option('--upgrade', 'Upgrade existing Tailwind v3 project to Tailwind v4')
+    .action(async (...actionArgs) => {
+      const cmd = actionArgs[actionArgs.length - 1];
+      const options = (cmd && typeof cmd.opts === 'function')
+        ? cmd.opts()
+        : (actionArgs.find(a => a && typeof a === 'object') || {});
+
       if (!fs.existsSync('package.json')) {
         console.error('❌ Not a Webspresso project! Run this command in your project directory.');
         process.exit(1);
       }
       
-      console.log('\n🎨 Adding Tailwind CSS to your project...\n');
+      const isV4 = Boolean(options.v4 || options.upgrade || options.tailwindVersion === '4');
+
+      console.log(`\n🎨 Adding Tailwind CSS ${isV4 ? 'v4 (Oxide engine, zero-config)' : 'v3'} to your project...\n`);
       
       // Read package.json
       const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
@@ -27,17 +39,26 @@ function registerCommand(program) {
         packageJson.devDependencies = {};
       }
       
-      packageJson.devDependencies['tailwindcss'] = '^3.4.1';
-      packageJson.devDependencies['postcss'] = '^8.4.35';
-      packageJson.devDependencies['autoprefixer'] = '^10.4.17';
-      
-      // Add build scripts
       if (!packageJson.scripts) {
         packageJson.scripts = {};
       }
-      
-      packageJson.scripts['build:css'] = 'tailwindcss -i ./src/input.css -o ./public/css/style.css --minify';
-      packageJson.scripts['watch:css'] = 'tailwindcss -i ./src/input.css -o ./public/css/style.css --watch';
+
+      if (isV4) {
+        packageJson.devDependencies['@tailwindcss/cli'] = '^4.0.0';
+        packageJson.devDependencies['tailwindcss'] = '^4.0.0';
+        delete packageJson.devDependencies['postcss'];
+        delete packageJson.devDependencies['autoprefixer'];
+
+        packageJson.scripts['build:css'] = '@tailwindcss/cli -i ./src/input.css -o ./public/css/style.css --minify';
+        packageJson.scripts['watch:css'] = '@tailwindcss/cli -i ./src/input.css -o ./public/css/style.css --watch';
+      } else {
+        packageJson.devDependencies['tailwindcss'] = '^3.4.1';
+        packageJson.devDependencies['postcss'] = '^8.4.35';
+        packageJson.devDependencies['autoprefixer'] = '^10.4.17';
+
+        packageJson.scripts['build:css'] = 'tailwindcss -i ./src/input.css -o ./public/css/style.css --minify';
+        packageJson.scripts['watch:css'] = 'tailwindcss -i ./src/input.css -o ./public/css/style.css --watch';
+      }
       
       // Update dev script to include CSS watch
       if (packageJson.scripts.dev) {
@@ -50,24 +71,48 @@ function registerCommand(program) {
       }
       
       fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2) + '\n');
-      console.log('✅ Updated package.json');
+      console.log(`✅ Updated package.json (${isV4 ? 'Tailwind v4' : 'Tailwind v3'})`);
       
       // Create src directory if it doesn't exist
       if (!fs.existsSync('src')) {
         fs.mkdirSync('src', { recursive: true });
       }
       
-      // Create input.css
-      const inputCss = `@tailwind base;
+      if (isV4) {
+        // Create v4 input.css
+        const inputCss = `@import "tailwindcss";
+
+@source "../pages/**/*.{njk,js}";
+@source "../views/**/*.njk";
+@source "../src/**/*.js";
+`;
+        fs.writeFileSync('src/input.css', inputCss);
+        console.log('✅ Created src/input.css (@import "tailwindcss"; + @source directives)');
+
+        // If upgrading from v3, clean up obsolete configs
+        if (fs.existsSync('postcss.config.js')) {
+          try {
+            fs.unlinkSync('postcss.config.js');
+            console.log('🧹 Removed obsolete postcss.config.js (not needed in v4)');
+          } catch (_) {}
+        }
+        if (fs.existsSync('tailwind.config.js')) {
+          try {
+            fs.renameSync('tailwind.config.js', 'tailwind.config.js.backup');
+            console.log('ℹ️  Renamed tailwind.config.js to tailwind.config.js.backup (v4 is CSS-first)');
+          } catch (_) {}
+        }
+      } else {
+        // Create v3 input.css
+        const inputCss = `@tailwind base;
 @tailwind components;
 @tailwind utilities;
 `;
-      
-      fs.writeFileSync('src/input.css', inputCss);
-      console.log('✅ Created src/input.css');
-      
-      // Create tailwind.config.js
-      const tailwindConfig = `/** @type {import('tailwindcss').Config} */
+        fs.writeFileSync('src/input.css', inputCss);
+        console.log('✅ Created src/input.css');
+        
+        // Create tailwind.config.js
+        const tailwindConfig = `/** @type {import('tailwindcss').Config} */
 module.exports = {
   content: [
     './pages/**/*.{njk,js}',
@@ -80,21 +125,20 @@ module.exports = {
   plugins: [],
 }
 `;
-      
-      fs.writeFileSync('tailwind.config.js', tailwindConfig);
-      console.log('✅ Created tailwind.config.js');
-      
-      // Create postcss.config.js
-      const postcssConfig = `module.exports = {
+        fs.writeFileSync('tailwind.config.js', tailwindConfig);
+        console.log('✅ Created tailwind.config.js');
+        
+        // Create postcss.config.js
+        const postcssConfig = `module.exports = {
   plugins: {
     tailwindcss: {},
     autoprefixer: {},
   },
 }
 `;
-      
-      fs.writeFileSync('postcss.config.js', postcssConfig);
-      console.log('✅ Created postcss.config.js');
+        fs.writeFileSync('postcss.config.js', postcssConfig);
+        console.log('✅ Created postcss.config.js');
+      }
       
       // Check if layout.njk exists and update it (before creating CSS)
       const layoutPath = 'views/layout.njk';
@@ -128,9 +172,10 @@ module.exports = {
       fs.writeFileSync('public/css/style.css', '/* Run npm run build:css */\n');
       console.log('✅ Created public/css/style.css');
       
-      // Try to build CSS if tailwindcss is already installed
+      // Try to build CSS if tailwindcss / @tailwindcss/cli is already installed
       const tailwindBin = path.join(process.cwd(), 'node_modules', '.bin', 'tailwindcss');
-      if (fs.existsSync(tailwindBin)) {
+      const tailwindCliBin = path.join(process.cwd(), 'node_modules', '.bin', '@tailwindcss/cli');
+      if (fs.existsSync(tailwindBin) || fs.existsSync(tailwindCliBin)) {
         try {
           console.log('\n🎨 Building Tailwind CSS from your templates...');
           execSync('npm run build:css', { stdio: 'inherit', cwd: process.cwd() });
@@ -139,7 +184,7 @@ module.exports = {
           console.log('\n⚠️  CSS build failed. Run "npm run build:css" manually.\n');
         }
       } else {
-        console.log('\n✅ Tailwind CSS added successfully!\n');
+        console.log(`\n✅ Tailwind CSS ${isV4 ? 'v4' : 'v3'} added successfully!\n`);
         console.log('Next steps:');
         console.log('  npm install');
         console.log('  npm run build:css');

package/bin/commands/analytics-prune.js

@@ -0,0 +1,57 @@
+/**
+ * Prune old site analytics records (CLI)
+ */
+
+const { loadDbConfig, createDbInstance } = require('../utils/db');
+
+function registerCommand(program) {
+  program
+    .command('analytics:prune')
+    .description('Delete analytics page views and client errors older than the given retention window')
+    .option('--days <n>', 'Delete page views older than this many days', '90')
+    .option('--error-days <n>', 'Delete client errors older than this many days', '30')
+    .option('--table <name>', 'Page views table name', 'analytics_page_views')
+    .option('--errors-table <name>', 'Client errors table name', 'analytics_client_errors')
+    .option('-e, --env <environment>', 'Environment (development, production)', 'development')
+    .option('-c, --config <path>', 'Path to database config file')
+    .action(async (options) => {
+      const days = parseInt(options.days, 10);
+      if (Number.isNaN(days) || days < 1) {
+        console.error('❌ --days must be a positive integer');
+        process.exit(1);
+      }
+
+      const errorDays = parseInt(options.errorDays, 10);
+      if (Number.isNaN(errorDays) || errorDays < 1) {
+        console.error('❌ --error-days must be a positive integer');
+        process.exit(1);
+      }
+
+      const { config, path: configPath } = loadDbConfig(options.config);
+      console.log(`\n📦 Using config: ${configPath}`);
+      console.log(`   Environment: ${options.env}\n`);
+
+      const knex = await createDbInstance(config, options.env);
+
+      try {
+        const { purgeAnalyticsData } = require('../../plugins/site-analytics/purge');
+        const result = await purgeAnalyticsData(knex, {
+          days,
+          errorDays,
+          tableName: options.table,
+          errorsTableName: options.errorsTable,
+        });
+
+        console.log(`✅ Analytics purge completed:`);
+        console.log(`   - Page views deleted: ${result.viewsDeleted} (cutoff: ${result.viewsCutoff})`);
+        console.log(`   - Client errors deleted: ${result.errorsDeleted} (cutoff: ${result.errorsCutoff})\n`);
+      } catch (err) {
+        console.error('❌ analytics:prune failed:', err.message);
+        process.exit(1);
+      } finally {
+        await knex.destroy();
+      }
+    });
+}
+
+module.exports = { registerCommand };