webspresso 0.0.76 → 0.0.78

package/README.md

@@ -1792,6 +1792,11 @@ webspresso db:make create_posts_table
 # Create migration from model (scaffolding)
 webspresso db:make create_users_table --model User
 
+# Scaffold create-table migrations for all models in models/
+webspresso db:scaffold
+webspresso db:scaffold --only User,Post
+webspresso db:scaffold --dry-run
+
 # Admin Panel Setup
 webspresso admin:setup   # Create admin_users migration
 webspresso admin:list    # List all admin users
@@ -2165,7 +2170,7 @@ const { app } = createApp({
 ```
 
 - **ORM:** `zdb.file({ maxLength: 2048, nullable: true })` — string column for the stored public URL or path; migrations use `table.string(..., maxLength)`.
-- **Admin forms:** columns with `zdb.file()` automatically render a drag-and-drop upload widget (or a manual URL text field when `uploadUrl` is not configured). Optional `ui: { label, hint, accept, maxBytes }` on the column customizes the widget. For existing `zdb.string()` columns you can use `admin.customFields: { columnName: { type: 'file-upload' } }` instead of changing the schema type.
+- **Admin forms:** columns with `zdb.file()` automatically render a drag-and-drop upload widget (or a manual URL text field when `uploadUrl` is not configured). Image URLs show an inline thumbnail preview; use `ui.accept: 'image/*'` for image-only fields. Optional `ui: { label, hint, accept, maxBytes }` on the column customizes the widget. For existing `zdb.string()` columns you can use `admin.customFields: { columnName: { type: 'file-upload' } }` instead of changing the schema type.
 - **Admin:** the panel reads **`settings.uploadUrl`** from the registry (set automatically when `uploadPlugin` is registered **before** `adminPanelPlugin`, or pass **`adminPanelPlugin({ uploadUrl: '/api/upload' })`**). File fields (`type: 'file'` or `customFields` type `file-upload`) POST to that URL with credentials; the saved record stores the returned **`url`** / **`publicUrl`** string.
 - **Response:** `{ url, publicUrl, key? }` — clients typically persist **`url`** / **`publicUrl`** in the model.
 - **Custom storage:** `uploadPlugin({ provider: { async put({ buffer, originalName, mimeType, size, req }) { return { publicUrl: '...' }; } } })`.

package/bin/commands/db-scaffold.js

@@ -0,0 +1,81 @@
+/**
+ * DB Scaffold Command
+ * Generate migration files from all models in models/
+ */
+
+const path = require('path');
+const { loadDbConfig } = require('../utils/db');
+const { scaffoldMigrationsFromModels } = require('../utils/model-migrations');
+
+function registerCommand(program) {
+  program
+    .command('db:scaffold')
+    .description('Generate create-table migrations from models/*.js')
+    .option('-c, --config <path>', 'Path to database config file (webspresso.db.js or knexfile.js)')
+    .option('-m, --models <path>', 'Models directory (overrides config.models)')
+    .option('--migrations <path>', 'Migrations directory (overrides config.migrations.directory)')
+    .option('--only <names>', 'Comma-separated model names (e.g. User,Post)')
+    .option('-f, --force', 'Create migration even if createTable for table already exists')
+    .option('--dry-run', 'List files that would be created without writing')
+    .action(async (options) => {
+      try {
+        const { config, path: configPath } = loadDbConfig(options.config);
+        console.log(`\n📦 Using config: ${configPath}\n`);
+
+        const modelsDir = options.models || config.models || './models';
+        const migrationDir = path.resolve(
+          process.cwd(),
+          options.migrations || config.migrations?.directory || './migrations'
+        );
+        const only = options.only
+          ? options.only.split(',').map((s) => s.trim()).filter(Boolean)
+          : null;
+
+        const result = scaffoldMigrationsFromModels({
+          modelsDir,
+          migrationDir,
+          force: Boolean(options.force),
+          dryRun: Boolean(options.dryRun),
+          only,
+        });
+
+        if (result.created.length > 0) {
+          const verb = options.dryRun ? 'Would create' : 'Created';
+          console.log(`✅ ${verb} ${result.created.length} migration(s):\n`);
+          for (const row of result.created) {
+            console.log(`   - ${row.model} → ${row.file}`);
+          }
+          console.log();
+        }
+
+        if (result.skipped.length > 0) {
+          console.log(`⏭️  Skipped ${result.skipped.length} (migration already exists, use --force):\n`);
+          for (const row of result.skipped) {
+            console.log(`   - ${row.model} (${row.table}) — ${row.file}`);
+          }
+          console.log();
+        }
+
+        if (result.errors.length > 0) {
+          console.error(`❌ Failed for ${result.errors.length} model(s):\n`);
+          for (const row of result.errors) {
+            console.error(`   - ${row.model}: ${row.message}`);
+          }
+          process.exit(1);
+        }
+
+        if (result.created.length === 0 && result.skipped.length > 0 && !options.force) {
+          console.log('ℹ️  No new migrations written. Use --force to regenerate.\n');
+        } else if (result.created.length === 0) {
+          console.log('ℹ️  Nothing to scaffold.\n');
+        } else if (!options.dryRun) {
+          console.log('📝 Next step: webspresso db:migrate\n');
+        }
+      } catch (err) {
+        console.error('❌ Error:', err.message);
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { registerCommand };

package/bin/utils/model-migrations.js

@@ -0,0 +1,211 @@
+/**
+ * Generate Knex migrations from ORM model definitions
+ * @module bin/utils/model-migrations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { clearRegistry, getAllModels } = require('../../core/orm/model');
+const {
+  scaffoldMigration,
+  generateMigrationName,
+} = require('../../core/orm/migrations/scaffold');
+
+/**
+ * @param {Date} [date]
+ * @returns {string}
+ */
+function migrationTimestamp(date = new Date()) {
+  return [
+    date.getFullYear(),
+    String(date.getMonth() + 1).padStart(2, '0'),
+    String(date.getDate()).padStart(2, '0'),
+    '_',
+    String(date.getHours()).padStart(2, '0'),
+    String(date.getMinutes()).padStart(2, '0'),
+    String(date.getSeconds()).padStart(2, '0'),
+  ].join('');
+}
+
+/**
+ * @param {import('../../core/orm/types').ModelDefinition} model
+ * @returns {Set<string>}
+ */
+function getReferencedTables(model) {
+  const deps = new Set();
+  for (const meta of model.columns.values()) {
+    if (meta.references) {
+      deps.add(meta.references);
+    }
+  }
+  return deps;
+}
+
+/**
+ * Topological sort so parent tables migrate before dependents.
+ * @param {import('../../core/orm/types').ModelDefinition[]} models
+ * @returns {import('../../core/orm/types').ModelDefinition[]}
+ */
+function sortModelsByDependencies(models) {
+  const byTable = new Map(models.map((m) => [m.table, m]));
+  const sorted = [];
+  const visiting = new Set();
+  const done = new Set();
+
+  function visit(model) {
+    if (done.has(model.table)) return;
+    if (visiting.has(model.table)) {
+      throw new Error(`Circular table dependency involving "${model.table}"`);
+    }
+    visiting.add(model.table);
+    for (const depTable of getReferencedTables(model)) {
+      const dep = byTable.get(depTable);
+      if (dep && dep.table !== model.table) {
+        visit(dep);
+      }
+    }
+    visiting.delete(model.table);
+    done.add(model.table);
+    sorted.push(model);
+  }
+
+  for (const model of models) {
+    visit(model);
+  }
+  return sorted;
+}
+
+/**
+ * @param {string} migrationDir
+ * @param {string} table
+ * @returns {string|null} existing filename
+ */
+function findExistingCreateMigration(migrationDir, table) {
+  if (!fs.existsSync(migrationDir)) {
+    return null;
+  }
+  const needle = `createTable('${table}'`;
+  for (const file of fs.readdirSync(migrationDir)) {
+    if (!file.endsWith('.js')) continue;
+    const content = fs.readFileSync(path.join(migrationDir, file), 'utf8');
+    if (content.includes(needle)) {
+      return file;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} modelsDir
+ * @returns {import('../../core/orm/types').ModelDefinition[]}
+ */
+function loadModelsFromDirectory(modelsDir) {
+  const absoluteModelsDir = path.resolve(process.cwd(), modelsDir);
+  if (!fs.existsSync(absoluteModelsDir)) {
+    throw new Error(`Models directory not found: ${absoluteModelsDir}`);
+  }
+
+  clearRegistry();
+
+  const files = fs
+    .readdirSync(absoluteModelsDir)
+    .filter((file) => file.endsWith('.js') && !file.startsWith('_'))
+    .sort();
+
+  const errors = [];
+  for (const file of files) {
+    try {
+      const modelPath = path.join(absoluteModelsDir, file);
+      delete require.cache[require.resolve(modelPath)];
+      require(modelPath);
+    } catch (err) {
+      errors.push({ file, message: err.message });
+    }
+  }
+
+  const models = [...getAllModels().values()];
+
+  if (errors.length > 0) {
+    throw new Error(
+      `Failed to load models from ${absoluteModelsDir}:\n` +
+        errors.map((e) => `  - ${e.file}: ${e.message}`).join('\n')
+    );
+  }
+
+  return sortModelsByDependencies(models);
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.modelsDir
+ * @param {string} options.migrationDir
+ * @param {boolean} [options.force]
+ * @param {boolean} [options.dryRun]
+ * @param {string[]} [options.only] model names
+ * @returns {{ created: object[], skipped: object[], errors: object[] }}
+ */
+function scaffoldMigrationsFromModels(options) {
+  const { modelsDir, migrationDir, force = false, dryRun = false, only = null } = options;
+  let models = loadModelsFromDirectory(modelsDir);
+
+  if (only && only.length > 0) {
+    const allow = new Set(only);
+    models = models.filter((m) => allow.has(m.name));
+    const missing = only.filter((name) => !models.some((m) => m.name === name));
+    if (missing.length > 0) {
+      throw new Error(`Model(s) not found: ${missing.join(', ')}`);
+    }
+  }
+
+  if (models.length === 0) {
+    throw new Error(`No models found in ${path.resolve(process.cwd(), modelsDir)}`);
+  }
+
+  const created = [];
+  const skipped = [];
+  const errors = [];
+
+  if (!dryRun && !fs.existsSync(migrationDir)) {
+    fs.mkdirSync(migrationDir, { recursive: true });
+  }
+
+  models.forEach((model, index) => {
+    const existing = findExistingCreateMigration(migrationDir, model.table);
+    if (existing && !force) {
+      skipped.push({ model: model.name, table: model.table, file: existing });
+      return;
+    }
+
+    try {
+      const migrationName = generateMigrationName(model, 'create');
+      const stamp = migrationTimestamp(new Date(Date.now() + index * 1000));
+      const filename = `${stamp}_${migrationName}.js`;
+      const filepath = path.join(migrationDir, filename);
+      const content = scaffoldMigration(model);
+
+      if (!dryRun) {
+        fs.writeFileSync(filepath, content);
+      }
+
+      created.push({
+        model: model.name,
+        table: model.table,
+        file: filename,
+        path: filepath,
+      });
+    } catch (err) {
+      errors.push({ model: model.name, table: model.table, message: err.message });
+    }
+  });
+
+  return { created, skipped, errors };
+}
+
+module.exports = {
+  migrationTimestamp,
+  getReferencedTables,
+  sortModelsByDependencies,
+  findExistingCreateMigration,
+  loadModelsFromDirectory,
+  scaffoldMigrationsFromModels,
+};

package/bin/webspresso.js

@@ -23,6 +23,7 @@ const { registerCommand: registerDbMigrate } = require('./commands/db-migrate');
 const { registerCommand: registerDbRollback } = require('./commands/db-rollback');
 const { registerCommand: registerDbStatus } = require('./commands/db-status');
 const { registerCommand: registerDbMake } = require('./commands/db-make');
+const { registerCommand: registerDbScaffold } = require('./commands/db-scaffold');
 const { registerCommand: registerSeed } = require('./commands/seed');
 const { registerCommand: registerAdminSetup } = require('./commands/admin-setup');
 const { registerCommand: registerAdminPassword } = require('./commands/admin-password');
@@ -43,6 +44,7 @@ registerDbMigrate(program);
 registerDbRollback(program);
 registerDbStatus(program);
 registerDbMake(program);
+registerDbScaffold(program);
 registerSeed(program);
 registerAdminSetup(program);
 registerAdminPassword(program);

package/core/content/cache.js

@@ -0,0 +1,64 @@
+/**
+ * Simple in-memory TTL cache for content reads.
+ * @module core/content/cache
+ */
+
+/**
+ * @param {number|null|undefined} [ttlMs] - Expiry in ms; null/undefined = no TTL (invalidate only on writes)
+ */
+function createContentCache(ttlMs = null) {
+  /** @type {Map<string, { value: unknown, expires: number }>} */
+  const store = new Map();
+  const noExpiry = ttlMs == null || ttlMs === Infinity;
+
+  /**
+   * @param {string} key
+   * @returns {unknown|undefined}
+   */
+  function get(key) {
+    const entry = store.get(key);
+    if (!entry) return undefined;
+    if (!noExpiry && Date.now() > entry.expires) {
+      store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  /**
+   * @param {string} key
+   * @param {unknown} value
+   */
+  function set(key, value) {
+    store.set(key, {
+      value,
+      expires: noExpiry ? Number.POSITIVE_INFINITY : Date.now() + ttlMs,
+    });
+  }
+
+  /**
+   * @param {string} key
+   */
+  function del(key) {
+    store.delete(key);
+  }
+
+  function invalidateAll() {
+    store.clear();
+  }
+
+  /**
+   * @param {string} prefix
+   */
+  function invalidatePrefix(prefix) {
+    for (const key of store.keys()) {
+      if (key.startsWith(prefix)) {
+        store.delete(key);
+      }
+    }
+  }
+
+  return { get, set, del, invalidateAll, invalidatePrefix };
+}
+
+module.exports = { createContentCache };

package/core/content/field-types.js

@@ -0,0 +1,180 @@
+/**
+ * Content field type registry — validate and normalize values per field type.
+ * @module core/content/field-types
+ */
+
+const { z } = require('zod');
+
+/** @type {Set<string>} */
+const FIELD_TYPES = new Set([
+  'text',
+  'textarea',
+  'rich-text',
+  'number',
+  'boolean',
+  'image',
+  'url',
+  'date',
+  'select',
+  'repeater',
+]);
+
+/**
+ * @param {string} type
+ * @returns {boolean}
+ */
+function isValidFieldType(type) {
+  return FIELD_TYPES.has(type);
+}
+
+/**
+ * @param {unknown} value
+ * @param {import('./types').ContentFieldDefinition} field
+ * @param {{ sanitizeRichHtml?: (v: string) => string }} [options]
+ * @returns {unknown}
+ */
+function normalizeFieldValue(value, field, options = {}) {
+  if (value === undefined || value === null) {
+    if (field.required) {
+      throw new Error(`Field "${field.name}" is required`);
+    }
+    return field.type === 'repeater' ? [] : null;
+  }
+
+  switch (field.type) {
+    case 'text':
+    case 'textarea':
+      if (typeof value !== 'string') {
+        throw new Error(`Field "${field.name}" must be a string`);
+      }
+      return value;
+
+    case 'rich-text': {
+      if (typeof value !== 'string') {
+        throw new Error(`Field "${field.name}" must be a string`);
+      }
+      return options.sanitizeRichHtml ? options.sanitizeRichHtml(value) : value;
+    }
+
+    case 'number': {
+      const num = typeof value === 'number' ? value : Number(value);
+      if (Number.isNaN(num)) {
+        throw new Error(`Field "${field.name}" must be a number`);
+      }
+      return num;
+    }
+
+    case 'boolean':
+      if (typeof value === 'boolean') return value;
+      if (value === 'true' || value === '1' || value === 1) return true;
+      if (value === 'false' || value === '0' || value === 0) return false;
+      throw new Error(`Field "${field.name}" must be a boolean`);
+
+    case 'image':
+    case 'url': {
+      if (typeof value !== 'string') {
+        throw new Error(`Field "${field.name}" must be a URL string`);
+      }
+      const trimmed = value.trim();
+      if (field.required && !trimmed) {
+        throw new Error(`Field "${field.name}" is required`);
+      }
+      if (trimmed && field.type === 'url') {
+        try {
+          // eslint-disable-next-line no-new
+          new URL(trimmed);
+        } catch {
+          throw new Error(`Field "${field.name}" must be a valid URL`);
+        }
+      }
+      return trimmed || null;
+    }
+
+    case 'date': {
+      if (typeof value !== 'string') {
+        throw new Error(`Field "${field.name}" must be a date string`);
+      }
+      const parsed = z.string().date().safeParse(value);
+      if (!parsed.success) {
+        throw new Error(`Field "${field.name}" must be a valid date (YYYY-MM-DD)`);
+      }
+      return value;
+    }
+
+    case 'select': {
+      if (typeof value !== 'string') {
+        throw new Error(`Field "${field.name}" must be a string`);
+      }
+      const optionsList = field.options || [];
+      if (optionsList.length > 0 && !optionsList.includes(value)) {
+        throw new Error(`Field "${field.name}" must be one of: ${optionsList.join(', ')}`);
+      }
+      return value;
+    }
+
+    case 'repeater': {
+      if (!Array.isArray(value)) {
+        throw new Error(`Field "${field.name}" must be an array`);
+      }
+      const nestedFields = field.fields || [];
+      return value.map((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+          throw new Error(`Field "${field.name}" item ${index} must be an object`);
+        }
+        return normalizeEntryData(item, nestedFields, options);
+      });
+    }
+
+    default:
+      throw new Error(`Unknown field type "${field.type}"`);
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} data
+ * @param {import('./types').ContentFieldDefinition[]} fields
+ * @param {{ sanitizeRichHtml?: (v: string) => string }} [options]
+ * @returns {Record<string, unknown>}
+ */
+function normalizeEntryData(data, fields, options = {}) {
+  const input = data && typeof data === 'object' ? data : {};
+  /** @type {Record<string, unknown>} */
+  const result = {};
+
+  for (const field of fields) {
+    const raw = Object.prototype.hasOwnProperty.call(input, field.name)
+      ? input[field.name]
+      : undefined;
+    result[field.name] = normalizeFieldValue(raw, field, options);
+  }
+
+  return result;
+}
+
+/**
+ * Map content field types to admin panel customField types.
+ * @param {import('./types').ContentFieldDefinition} field
+ * @returns {Object|null}
+ */
+function toAdminCustomField(field) {
+  switch (field.type) {
+    case 'rich-text':
+      return { type: 'rich-text' };
+    case 'image':
+      return { type: 'file-upload' };
+    case 'textarea':
+      return { type: 'text' };
+    case 'select':
+      return { type: 'enum', options: field.options || [] };
+    default:
+      return null;
+  }
+}
+
+module.exports = {
+  FIELD_TYPES,
+  isValidFieldType,
+  normalizeFieldValue,
+  normalizeEntryData,
+  toAdminCustomField,
+};

package/core/content/index.js

@@ -0,0 +1,30 @@
+/**
+ * Schema-driven content system — core module (framework-agnostic).
+ * @module core/content
+ */
+
+const { createContentService } = require('./service');
+const { createContentCache } = require('./cache');
+const { parseContentTypeSchema, validateEntryData, isValidSlug } = require('./schema');
+const { wrapEditable, wrapEntryBlock, escapeHtml } = require('./renderer');
+const {
+  FIELD_TYPES,
+  isValidFieldType,
+  normalizeEntryData,
+  toAdminCustomField,
+} = require('./field-types');
+
+module.exports = {
+  createContentService,
+  createContentCache,
+  parseContentTypeSchema,
+  validateEntryData,
+  isValidSlug,
+  wrapEditable,
+  wrapEntryBlock,
+  escapeHtml,
+  FIELD_TYPES,
+  isValidFieldType,
+  normalizeEntryData,
+  toAdminCustomField,
+};

package/core/content/renderer.js

@@ -0,0 +1,84 @@
+/**
+ * Content renderer — wraps values with inline-edit data attributes for admins.
+ * @module core/content/renderer
+ */
+
+/**
+ * Escape HTML for text nodes (not for rich-text which uses | safe separately).
+ * @param {unknown} value
+ * @returns {string}
+ */
+function escapeHtml(value) {
+  if (value === null || value === undefined) return '';
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * @param {unknown} value
+ * @param {Object} meta
+ * @param {number|string} meta.entryId
+ * @param {string} meta.typeSlug
+ * @param {string} [meta.field]
+ * @param {string} [meta.label]
+ * @param {boolean} [meta.isAdmin]
+ * @param {boolean} [meta.safeHtml]
+ * @returns {string}
+ */
+function wrapEditable(value, meta) {
+  const display = meta.safeHtml ? String(value ?? '') : escapeHtml(value);
+
+  if (!meta.isAdmin) {
+    return display;
+  }
+
+  const attrs = [
+    'class="ws-content-editable"',
+    `data-ws-content-entry="${meta.entryId}"`,
+    `data-ws-content-type="${meta.typeSlug}"`,
+  ];
+
+  if (meta.field) {
+    attrs.push(`data-ws-content-field="${meta.field}"`);
+  }
+  if (meta.label) {
+    attrs.push(`data-ws-content-label="${escapeHtml(meta.label)}"`);
+  }
+  if (meta.safeHtml) {
+    attrs.push('data-ws-content-html="true"');
+  }
+
+  return `<span ${attrs.join(' ')}>${display}</span>`;
+}
+
+/**
+ * Wrap an entire content entry block for entry-level edit button.
+ * @param {string} innerHtml
+ * @param {Object} meta
+ * @param {number|string} meta.entryId
+ * @param {string} meta.typeSlug
+ * @param {string} [meta.label]
+ * @param {boolean} meta.isAdmin
+ * @returns {string}
+ */
+function wrapEntryBlock(innerHtml, meta) {
+  if (!meta.isAdmin) {
+    return innerHtml;
+  }
+
+  const label = meta.label ? escapeHtml(meta.label) : meta.typeSlug;
+  return (
+    `<div class="ws-content-block" data-ws-content-entry="${meta.entryId}" ` +
+    `data-ws-content-type="${meta.typeSlug}" data-ws-content-label="${label}">` +
+    `${innerHtml}</div>`
+  );
+}
+
+module.exports = {
+  escapeHtml,
+  wrapEditable,
+  wrapEntryBlock,
+};