webspresso 0.0.57 → 0.0.58

package/README.md

@@ -143,7 +143,7 @@ The project includes:
 - Tailwind CSS with build process
 - Optimized layout template with navigation and footer
 - Responsive starter page
-- i18n setup (en/tr)
+- i18n setup (e.g. en/de)
 - Development and production scripts
 
 ### `webspresso page`
@@ -191,6 +191,32 @@ webspresso start
 webspresso start --port 3000
 ```
 
+### `webspresso doctor`
+
+Check Node.js version, `package.json` / `engines.node`, typical project files (`server.js`, `pages/`), and whether `webspresso.db.js` or `knexfile.js` exists. Use `--db` to run a quick connection test when a config is present. Warnings alone exit with code `0`; pass `--strict` to fail (exit `1`) on any warning—useful in CI.
+
+```bash
+webspresso doctor
+webspresso doctor --db
+webspresso doctor --strict
+```
+
+### `webspresso skill`
+
+Scaffold a **Cursor Agent Skill**: creates `.cursor/skills/<name>/SKILL.md` with valid YAML frontmatter (`name`, `description`) and a short markdown template for AI tooling. Use `--global` to write under `~/.cursor/skills/` instead of the current project.
+
+**Bundled preset:** `--preset webspresso` copies the full **Webspresso usage** reference skill (framework routing, ORM, plugins, CLI, pitfalls) into `.cursor/skills/webspresso-usage/SKILL.md` — no prompts.
+
+```bash
+webspresso skill my-workflow
+webspresso skill review-pr --description "Runs PR review checklist. Use when reviewing pull requests."
+webspresso skill deploy-check -g
+
+# Install the bundled Webspresso agent reference (same content shipped in templates/skills/)
+webspresso skill --preset webspresso
+webspresso skill -p webspresso --global
+```
+
 ### `webspresso add tailwind`
 
 Add Tailwind CSS to your project with build process.
@@ -277,7 +303,7 @@ my-app/
 ├── pages/
 │   ├── locales/          # Global i18n translations
 │   │   ├── en.json
-│   │   └── tr.json
+│   │   └── de.json
 │   ├── _hooks.js         # Global lifecycle hooks
 │   ├── index.njk         # Home page (GET /)
 │   ├── about/
@@ -482,7 +508,7 @@ const { app } = createApp({
       hostname: 'https://example.com',
       exclude: ['/admin/*', '/api/*'],
       i18n: true,
-      locales: ['en', 'tr']
+      locales: ['en', 'de']
     }),
     analyticsPlugin({
       google: {
@@ -748,6 +774,55 @@ const { app } = createApp({
 
 Programmatic API (other plugins): `ctx.usePlugin('audit-log')` exposes `queryLogs`, `purgeAuditLogs`, and `getMigrationTemplate()`.
 
+**reCAPTCHA plugin:**
+- Google reCAPTCHA **v2** (checkbox) or **v3** (score): server verification via `https://www.google.com/recaptcha/api/siteverify` (no extra npm dependency; Node 18+ `fetch`)
+- Registers CSP entries for Google scripts/iframes; Nunjucks helpers: `recaptchaScript`, `recaptchaWidget` (v2), `recaptchaV3Token` (hidden input + execute for v3 — use with `version: 'v3'` and `recaptchaScript` loads `api.js?render=siteKey`)
+- Secret key: `options.secretKey` or env `RECAPTCHA_SECRET_KEY` (never expose to templates)
+
+```javascript
+const {
+  recaptchaPlugin,
+  createRecaptchaMiddleware,
+  resolveRecaptchaMiddlewareParams,
+} = require('webspresso/plugins/recaptcha');
+
+const recaptchaConfig = {
+  siteKey: process.env.RECAPTCHA_SITE_KEY,
+  secretKey: process.env.RECAPTCHA_SECRET_KEY,
+  version: 'v2', // or 'v3'
+  minScore: 0.5,
+  expectedAction: 'contact', // v3 verification only
+  defaultV3Action: 'submit', // for recaptchaV3Token helper
+};
+
+const { app } = createApp({
+  pagesDir: './pages',
+  plugins: [recaptchaPlugin(recaptchaConfig)],
+  middlewares: {
+    recaptcha: createRecaptchaMiddleware({
+      ...resolveRecaptchaMiddlewareParams(recaptchaConfig),
+      bodyField: 'g-recaptcha-response',
+    }),
+  },
+});
+```
+
+**File-based API** (`pages/api/...post.js`): use the named middleware instead of duplicating verification in the handler; on success, `req.recaptcha` contains a short summary of Google’s response.
+
+```javascript
+// pages/api/contact.post.js
+module.exports = async function post(req, res) {
+  // recaptcha middleware already returned 400 if token invalid
+  return res.json({ ok: true, hostname: req.recaptcha.hostname });
+};
+
+module.exports.middleware = ['recaptcha'];
+```
+
+Optional: after `createApp`, use `pluginManager.getPluginAPI('recaptcha').createMiddleware({ bodyField: '...' })` to override plugin defaults and attach to the `app.use` chain (after body parsers).
+
+Low-level usage (without middleware): import `verifyRecaptcha` / `getRemoteIp` from `webspresso/plugins/recaptcha/verify`.
+
 **SEO Checker Plugin:**
 - Client-side SEO analysis tool (inspired by django-check-seo)
 - Integrated with dev toolbar
@@ -1349,6 +1424,10 @@ await UserRepo.query().onlyTrashed().list();   // Only deleted
 await UserRepo.query().forTenant(tenantId).list();
 ```
 
+`list()`, `first()`, and `paginate()` emit the same `beforeFind` / `afterFind` lifecycle hooks as `findAll` / `findOne` (one `afterFind` per row). `count()` ignores any `.limit()` / `.offset()` on the builder so it returns the full matching row count.
+
+`query().delete()` runs a SQL `DELETE` for matching rows. On models with soft deletes, use `UserRepo.delete(id)` (or equivalent) to set `deleted_at`; the query builder does not convert deletes to soft deletes.
+
 ### Transactions
 
 ```javascript

package/bin/commands/doctor.js

@@ -0,0 +1,182 @@
+/**
+ * Doctor Command — environment and project sanity checks
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveDbConfigIfExists, createDbInstance } = require('../utils/db');
+
+/**
+ * @param {string} enginesNode - e.g. ">=18.0.0", "^20.1.0"
+ * @returns {boolean|null} null if could not interpret
+ */
+function nodeEngineOk(enginesNode) {
+  const v = process.version;
+  const major = parseInt(v.replace(/^v/, '').split('.')[0], 10);
+  if (Number.isNaN(major)) return null;
+
+  const s = String(enginesNode).trim();
+  const ge = s.match(/^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (ge) {
+    const reqMajor = parseInt(ge[1], 10);
+    return major >= reqMajor;
+  }
+  const gt = s.match(/^>\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (gt) {
+    const reqMajor = parseInt(gt[1], 10);
+    return major > reqMajor;
+  }
+  const caret = s.match(/^\^\s*(\d+)/);
+  if (caret) {
+    const reqMajor = parseInt(caret[1], 10);
+    return major === reqMajor;
+  }
+  const exact = s.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+  if (exact) {
+    const reqMajor = parseInt(exact[1], 10);
+    return major === reqMajor;
+  }
+  return null;
+}
+
+function registerCommand(program) {
+  program
+    .command('doctor')
+    .description('Check Node version, project layout, and optional database connectivity')
+    .option('--db', 'Run a database connection test when webspresso.db.js or knexfile.js exists')
+    .option('--strict', 'Exit with code 1 if any warning is reported')
+    .option('-e, --env <environment>', 'Environment for DB config (with --db)', 'development')
+    .action(async (options) => {
+      const cwd = process.cwd();
+      let errors = 0;
+      let warnings = 0;
+
+      const line = (icon, msg) => console.log(`  ${icon} ${msg}`);
+
+      console.log('\nWebspresso Doctor');
+      console.log('=================\n');
+
+      console.log('Environment');
+      console.log('-----------');
+      line('✓', `Node.js ${process.version} (${process.platform}, ${process.arch})`);
+
+      const pkgPath = path.join(cwd, 'package.json');
+      let pkg = null;
+      if (!fs.existsSync(pkgPath)) {
+        line('✗', 'package.json not found (run this from a project directory)');
+        errors += 1;
+      } else {
+        try {
+          pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+          line('✓', `package.json readable (${pkg.name || 'unnamed'})`);
+        } catch (e) {
+          line('✗', `package.json invalid JSON: ${e.message}`);
+          errors += 1;
+        }
+      }
+
+      if (pkg && pkg.engines && pkg.engines.node) {
+        const ok = nodeEngineOk(pkg.engines.node);
+        if (ok === null) {
+          line('⚠', `engines.node "${pkg.engines.node}" — could not verify; check manually`);
+          warnings += 1;
+        } else if (ok) {
+          line('✓', `engines.node "${pkg.engines.node}" satisfied`);
+        } else {
+          line('⚠', `engines.node "${pkg.engines.node}" may not match current Node (adjust nvm / install)`);
+          warnings += 1;
+        }
+      }
+
+      console.log('\nProject layout');
+      console.log('--------------');
+
+      const serverPath = path.join(cwd, 'server.js');
+      if (fs.existsSync(serverPath)) {
+        line('✓', 'server.js present');
+      } else {
+        line('⚠', 'server.js not found (expected for standard Webspresso apps)');
+        warnings += 1;
+      }
+
+      const pagesPath = path.join(cwd, 'pages');
+      if (fs.existsSync(pagesPath) && fs.statSync(pagesPath).isDirectory()) {
+        line('✓', 'pages/ directory present');
+      } else {
+        line('⚠', 'pages/ not found (file-based routes may be missing)');
+        warnings += 1;
+      }
+
+      console.log('\nDatabase config');
+      console.log('---------------');
+
+      let resolved = null;
+      let configLoadError = false;
+      try {
+        resolved = resolveDbConfigIfExists();
+      } catch (e) {
+        configLoadError = true;
+        line('✗', `Database config could not be loaded: ${e.message}`);
+        errors += 1;
+      }
+
+      if (resolved) {
+        line('✓', `Found ${path.relative(cwd, resolved.path)}`);
+      } else if (!configLoadError) {
+        line('○', 'No webspresso.db.js or knexfile.js (ORM/CLI DB commands need one)');
+      }
+
+      if (options.db) {
+        console.log('\nDatabase connection (--db)');
+        console.log('--------------------------');
+        if (!resolved) {
+          line('○', 'Skipped — no database config file');
+        } else {
+          let knexMod;
+          try {
+            knexMod = require('knex');
+          } catch {
+            line('✗', 'knex is not installed. Run: npm install knex');
+            errors += 1;
+          }
+          if (knexMod) {
+            let knex;
+            try {
+              knex = await createDbInstance(resolved.config, options.env);
+              await knex.raw('select 1');
+              line('✓', `Connection OK (env: ${options.env})`);
+            } catch (e) {
+              line('✗', `Connection failed: ${e.message}`);
+              errors += 1;
+            } finally {
+              if (knex && typeof knex.destroy === 'function') {
+                try {
+                  await knex.destroy();
+                } catch {
+                  /* ignore */
+                }
+              }
+            }
+          }
+        }
+      }
+
+      console.log('');
+
+      const strict = options.strict === true;
+      const failWarnings = strict && warnings > 0;
+      const exitCode = errors > 0 || failWarnings ? 1 : 0;
+
+      if (errors > 0) {
+        console.log(`Summary: ${errors} error(s)${warnings ? `, ${warnings} warning(s)` : ''}\n`);
+      } else if (warnings > 0) {
+        console.log(`Summary: ${warnings} warning(s)${strict ? ' (strict: treating as failure)' : ''}\n`);
+      } else {
+        console.log('Summary: all checks passed.\n');
+      }
+
+      process.exit(exitCode);
+    });
+}
+
+module.exports = { registerCommand };

package/bin/commands/new.js

@@ -227,7 +227,7 @@ app.listen(PORT, () => {
       let envExample = `PORT=3000
 NODE_ENV=development
 DEFAULT_LOCALE=en
-SUPPORTED_LOCALES=en,tr
+SUPPORTED_LOCALES=en,de
 BASE_URL=http://localhost:3000
 `;
       
@@ -454,23 +454,23 @@ coverage/
         JSON.stringify(enJson, null, 2) + '\n'
       );
       
-      const trJson = {
+      const deJson = {
         site: {
           name: 'Webspresso'
         },
         nav: {
-          home: 'Ana Sayfa'
+          home: 'Startseite'
         },
         footer: {
-          copyright: '© 2025 Webspresso. Tüm hakları saklıdır.'
+          copyright: '© 2025 Webspresso. All rights reserved.'
         },
-        welcome: 'Webspresso\'ya Hoş Geldiniz',
-        description: 'SSR uygulamanızı oluşturmaya başlayın!'
+        welcome: 'Willkommen bei Webspresso',
+        description: 'Start building your SSR app!'
       };
       
       fs.writeFileSync(
-        path.join(projectPath, 'pages', 'locales', 'tr.json'),
-        JSON.stringify(trJson, null, 2) + '\n'
+        path.join(projectPath, 'pages', 'locales', 'de.json'),
+        JSON.stringify(deJson, null, 2) + '\n'
       );
       
       // Create README

package/bin/commands/page.js

@@ -110,18 +110,18 @@ function registerCommand(program) {
           JSON.stringify(enContent, null, 2) + '\n'
         );
         
-        const trContent = {
+        const deContent = {
           title: route,
-          description: 'Sayfa açıklaması',
+          description: 'Seitenbeschreibung',
           meta: {
             title: `${route} - Webspresso`,
-            description: 'Sayfa açıklaması'
+            description: 'Seitenbeschreibung'
           }
         };
         
         fs.writeFileSync(
-          path.join(localesDir, 'tr.json'),
-          JSON.stringify(trContent, null, 2) + '\n'
+          path.join(localesDir, 'de.json'),
+          JSON.stringify(deContent, null, 2) + '\n'
         );
         
         console.log(`✅ Created locale files in ${localesDir}`);

package/bin/commands/skill.js

@@ -0,0 +1,165 @@
+/**
+ * Skill Command — scaffold Agent Skill (SKILL.md) for Cursor / AI tools
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const inquirer = require('inquirer');
+
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$|^[a-z0-9]$/;
+
+function validateSkillName(name) {
+  const t = String(name).trim().toLowerCase();
+  if (!t) return 'Skill name is required';
+  if (t.length > 64) return 'Skill name must be at most 64 characters';
+  if (!NAME_PATTERN.test(t)) {
+    return 'Use lowercase letters, numbers, and hyphens only (e.g. my-skill-name)';
+  }
+  return true;
+}
+
+function skillDir(base, skillName) {
+  return path.join(base, '.cursor', 'skills', skillName);
+}
+
+function defaultDescription(skillName) {
+  const label = skillName.replace(/-/g, ' ');
+  return `Guides the agent through tasks for ${label}. Use when the user works on ${label} or asks about related workflows.`;
+}
+
+/** Bundled presets: CLI flag → template path under bin/ */
+const PRESETS = {
+  webspresso: {
+    skillName: 'webspresso-usage',
+    templatePath: path.join(__dirname, '../../templates/skills/webspresso-usage/SKILL.md'),
+  },
+};
+
+function buildSkillMarkdown(skillName, description) {
+  const title = skillName
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+  const descYaml = JSON.stringify(description.trim());
+
+  return `---
+name: ${skillName}
+description: ${descYaml}
+---
+
+# ${title}
+
+## Instructions
+
+- Describe step-by-step what the agent should do.
+- Add constraints, file paths, and conventions for this project.
+
+## When to use
+
+- List concrete user phrases or tasks that should trigger this skill.
+
+## Examples
+
+\`\`\`
+Example prompt or command
+\`\`\`
+
+`;
+
+}
+
+function registerCommand(program) {
+  program
+    .command('skill [name]')
+    .description('Create an Agent Skill folder with SKILL.md (Cursor / AI tools)')
+    .option('-g, --global', 'Write to ~/.cursor/skills/ instead of ./.cursor/skills/')
+    .option('-d, --description <text>', 'Skill description (for YAML frontmatter)')
+    .option('-f, --force', 'Overwrite existing SKILL.md')
+    .option('-p, --preset <name>', 'Install bundled skill: webspresso → full Webspresso agent reference (SKILL.md)')
+    .action(async (nameArg, options) => {
+      const presetKey = options.preset ? String(options.preset).trim().toLowerCase() : '';
+
+      if (presetKey) {
+        const preset = PRESETS[presetKey];
+        if (!preset) {
+          console.error(`❌ Unknown preset "${presetKey}". Available: ${Object.keys(PRESETS).join(', ')}`);
+          process.exit(1);
+        }
+        if (!fs.existsSync(preset.templatePath)) {
+          console.error(`❌ Preset template missing: ${preset.templatePath}`);
+          process.exit(1);
+        }
+        const root = options.global ? os.homedir() : process.cwd();
+        const dir = skillDir(root, preset.skillName);
+        const skillFile = path.join(dir, 'SKILL.md');
+
+        if (!options.force && fs.existsSync(skillFile)) {
+          console.error(`❌ Already exists: ${skillFile}`);
+          console.error('   Use --force to overwrite.');
+          process.exit(1);
+        }
+
+        fs.mkdirSync(dir, { recursive: true });
+        fs.copyFileSync(preset.templatePath, skillFile);
+
+        console.log(`\n✅ Installed bundled skill "${presetKey}" →\n   ${skillFile}\n`);
+        console.log('   Edit SKILL.md if needed, then restart Cursor or reload the window.\n');
+        return;
+      }
+
+      let skillName = nameArg ? String(nameArg).trim().toLowerCase() : '';
+
+      if (!skillName) {
+        const { name } = await inquirer.prompt([
+          {
+            type: 'input',
+            name: 'name',
+            message: 'Skill name (kebab-case, e.g. review-api):',
+            validate: validateSkillName,
+          },
+        ]);
+        skillName = name.trim().toLowerCase();
+      } else {
+        const v = validateSkillName(skillName);
+        if (v !== true) {
+          console.error(`❌ ${v}`);
+          process.exit(1);
+        }
+        skillName = skillName.trim().toLowerCase();
+      }
+
+      let description = options.description;
+      if (!description) {
+        const { desc } = await inquirer.prompt([
+          {
+            type: 'input',
+            name: 'desc',
+            message: 'Short description (what/when the agent should use this skill):',
+            default: defaultDescription(skillName),
+          },
+        ]);
+        description = desc || defaultDescription(skillName);
+      }
+
+      const root = options.global ? os.homedir() : process.cwd();
+      const dir = skillDir(root, skillName);
+      const skillFile = path.join(dir, 'SKILL.md');
+
+      if (!options.force && fs.existsSync(skillFile)) {
+        console.error(`❌ Already exists: ${skillFile}`);
+        console.error('   Use --force to overwrite.');
+        process.exit(1);
+      }
+
+      fs.mkdirSync(dir, { recursive: true });
+
+      const body = buildSkillMarkdown(skillName, description);
+      fs.writeFileSync(skillFile, body, 'utf8');
+
+      console.log(`\n✅ Agent skill created:\n   ${skillFile}\n`);
+      console.log('   Edit SKILL.md, then restart Cursor or reload the window if needed.\n');
+    });
+}
+
+module.exports = { registerCommand };

package/bin/utils/db.js

@@ -26,6 +26,24 @@ function loadDbConfig(configPath) {
   process.exit(1);
 }
 
+/**
+ * Resolve database config if present (no exit when missing; for doctor / tooling)
+ * @param {string} [configPath] - Custom config path
+ * @returns {{ config: Object, path: string } | null}
+ */
+function resolveDbConfigIfExists(configPath) {
+  const defaultPaths = ['webspresso.db.js', 'knexfile.js'];
+  const paths = configPath ? [configPath, ...defaultPaths] : defaultPaths;
+
+  for (const p of paths) {
+    const fullPath = path.resolve(process.cwd(), p);
+    if (fs.existsSync(fullPath)) {
+      return { config: require(fullPath), path: fullPath };
+    }
+  }
+  return null;
+}
+
 /**
  * Create database instance from config
  * @param {Object} config - Database config
@@ -50,5 +68,6 @@ async function createDbInstance(config, env) {
 
 module.exports = {
   loadDbConfig,
+  resolveDbConfigIfExists,
   createDbInstance
 };

package/bin/webspresso.js

@@ -28,6 +28,8 @@ const { registerCommand: registerAdminSetup } = require('./commands/admin-setup'
 const { registerCommand: registerAdminPassword } = require('./commands/admin-password');
 const { registerCommand: registerFaviconGenerate } = require('./commands/favicon-generate');
 const { registerCommand: registerAuditPrune } = require('./commands/audit-prune');
+const { registerCommand: registerDoctor } = require('./commands/doctor');
+const { registerCommand: registerSkill } = require('./commands/skill');
 
 registerNew(program);
 registerPage(program);
@@ -44,6 +46,8 @@ registerAdminSetup(program);
 registerAdminPassword(program);
 registerFaviconGenerate(program);
 registerAuditPrune(program);
+registerDoctor(program);
+registerSkill(program);
 
 // Parse arguments
 program.parse();

package/core/orm/index.js

@@ -186,7 +186,7 @@ function createDatabase(config) {
    * Get query builder for a model
    * @param {string} modelName - Model name
    * @param {import('./types').ScopeContext} [scopeContext] - Scope context
-   * @returns {import('knex').Knex.QueryBuilder}
+   * @returns {import('./query-builder').QueryBuilder}
    */
   function query(modelName, scopeContext) {
     const model = getModelInstance(modelName);

package/core/orm/json-fields.js

@@ -0,0 +1,70 @@
+/**
+ * Webspresso ORM - JSON column helpers (shared by repository and query builder)
+ * @module core/orm/json-fields
+ */
+
+/**
+ * Get JSON column names from model
+ * @param {import('./types').ModelDefinition} model - Model definition
+ * @returns {Set<string>} Set of JSON column names
+ */
+function getJsonColumns(model) {
+  const jsonCols = new Set();
+  if (model.columns) {
+    for (const [name, meta] of model.columns) {
+      if (meta.type === 'json') {
+        jsonCols.add(name);
+      }
+    }
+  }
+  return jsonCols;
+}
+
+/**
+ * Serialize JSON fields for database storage
+ * @param {Object} data - Data to serialize
+ * @param {Set<string>} jsonColumns - JSON column names
+ * @returns {Object} Serialized data
+ */
+function serializeJsonFields(data, jsonColumns) {
+  if (jsonColumns.size === 0) return data;
+
+  const serialized = { ...data };
+  for (const col of jsonColumns) {
+    if (col in serialized && serialized[col] !== null && serialized[col] !== undefined) {
+      if (typeof serialized[col] !== 'string') {
+        serialized[col] = JSON.stringify(serialized[col]);
+      }
+    }
+  }
+  return serialized;
+}
+
+/**
+ * Deserialize JSON fields from database
+ * @param {Object} record - Record from database
+ * @param {Set<string>} jsonColumns - JSON column names
+ * @returns {Object} Deserialized record
+ */
+function deserializeJsonFields(record, jsonColumns) {
+  if (!record || jsonColumns.size === 0) return record;
+
+  for (const col of jsonColumns) {
+    if (col in record && record[col] !== null && record[col] !== undefined) {
+      if (typeof record[col] === 'string') {
+        try {
+          record[col] = JSON.parse(record[col]);
+        } catch {
+          // If parsing fails, keep the original string value
+        }
+      }
+    }
+  }
+  return record;
+}
+
+module.exports = {
+  getJsonColumns,
+  serializeJsonFields,
+  deserializeJsonFields,
+};