webspresso 0.0.76 → 0.0.78

package/plugins/content/helpers.js

@@ -0,0 +1,77 @@
+/**
+ * Request-scoped template helpers for content inline editing.
+ * @module plugins/content/helpers
+ */
+
+const { wrapEditable, wrapEntryBlock } = require('../../core/content');
+
+/**
+ * @param {import('express').Request} req
+ * @param {string} [adminPath='/_admin']
+ * @returns {boolean}
+ */
+function isAdminSession(req, adminPath = '/_admin') {
+  return Boolean(req.session && req.session.adminUser);
+}
+
+/**
+ * @param {Object} options
+ * @param {string} [options.adminPath='/_admin']
+ * @returns {(req: import('express').Request) => Object}
+ */
+function createRequestContentHelpers(options = {}) {
+  const adminPath = options.adminPath || '/_admin';
+
+  return function buildContentHelpers(req) {
+    const isAdmin = isAdminSession(req);
+
+    return {
+      isAdmin() {
+        return isAdmin;
+      },
+
+      adminPath() {
+        return adminPath;
+      },
+
+      /**
+       * @param {import('../../core/content/types').ContentEntryResult|null|undefined} entry
+       */
+      raw(entry) {
+        return entry?.data ?? {};
+      },
+
+      /**
+       * @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.safeHtml]
+       */
+      editable(value, meta = {}) {
+        return wrapEditable(value, {
+          ...meta,
+          isAdmin,
+        });
+      },
+
+      /**
+       * @param {string} innerHtml
+       * @param {Object} meta
+       */
+      block(innerHtml, meta = {}) {
+        return wrapEntryBlock(innerHtml, {
+          ...meta,
+          isAdmin,
+        });
+      },
+    };
+  };
+}
+
+module.exports = {
+  isAdminSession,
+  createRequestContentHelpers,
+};

package/plugins/content/index.js

@@ -0,0 +1,231 @@
+/**
+ * Schema-driven content CMS plugin for Webspresso.
+ * @module plugins/content
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createContentService } = require('../../core/content');
+const { createContentTypeModel } = require('./models/content-type');
+const { createContentEntryModel } = require('./models/content-entry');
+const { createContentApiHandlers } = require('./api-handlers');
+const { createRequestContentHelpers, isAdminSession } = require('./helpers');
+const { generateContentTypesComponent } = require('./admin/content-types-component');
+const { generateContentEntriesComponent } = require('./admin/content-entries-component');
+const { generateContentMigrations } = require('./migration-template');
+
+const INLINE_EDIT_JS = fs.readFileSync(path.join(__dirname, 'client/inline-edit.js'), 'utf8');
+const INLINE_EDIT_CSS = fs.readFileSync(path.join(__dirname, 'client/inline-edit.css'), 'utf8');
+
+/**
+ * @param {Object} options
+ * @param {import('../../core/orm').Database} options.db
+ * @param {string} [options.adminPath='/_admin']
+ * @param {string} [options.publicApiPath='/api/content']
+ * @param {boolean} [options.inlineEdit=true]
+ * @param {number|null} [options.cacheTtlMs] - In-memory cache TTL; null (default) = until write invalidation
+ */
+function contentPlugin(options = {}) {
+  const {
+    db,
+    adminPath: adminPathOpt,
+    publicApiPath = '/api/content',
+    inlineEdit = true,
+    cacheTtlMs,
+  } = options;
+
+  if (!db) {
+    throw new Error('content plugin requires a database instance. Pass `db` in options.');
+  }
+
+  /** @type {ReturnType<typeof createContentService>|null} */
+  let contentService = null;
+  let adminPath = adminPathOpt || '/_admin';
+
+  function getService(database) {
+    if (!contentService) {
+      let sanitizeRichHtml;
+      try {
+        ({ sanitizeRichHtml } = require('../admin-panel/lib/sanitize-rich-html'));
+      } catch {
+        sanitizeRichHtml = (v) => v;
+      }
+      contentService = createContentService(database || db, { cacheTtlMs, sanitizeRichHtml });
+    }
+    return contentService;
+  }
+
+  function maybeInjectInlineEdit(req, html) {
+    if (!inlineEdit || !isAdminSession(req, adminPath)) {
+      return html;
+    }
+    const configScript =
+      '<script>window.__WS_CONTENT__=' +
+      JSON.stringify({ enabled: true, adminPath }) +
+      ';</script>';
+    const styleTag = '<style id="ws-content-inline-css">' + INLINE_EDIT_CSS + '</style>';
+    const scriptTag = '<script id="ws-content-inline-edit">' + INLINE_EDIT_JS + '</script>';
+    const bundle = configScript + styleTag + scriptTag;
+    if (html.includes('</body>')) {
+      return html.replace('</body>', bundle + '</body>');
+    }
+    return html + bundle;
+  }
+
+  return {
+    name: 'content',
+    version: '1.0.0',
+    description: 'Schema-driven SQLite CMS with inline admin editing',
+    dependencies: { 'admin-panel': '*' },
+
+    csp: {
+      styleSrc: ["'unsafe-inline'"],
+      scriptSrc: ["'unsafe-inline'"],
+    },
+
+    api: {
+      getContentService: getService,
+      createRequestHelpers: () => createRequestContentHelpers({ adminPath }),
+      maybeInjectInlineEdit,
+      getMigrationTemplate: generateContentMigrations,
+      _options: { adminPath },
+    },
+
+    register(ctx) {
+      const { hasModel, getModel } = require('../../core/orm/model');
+
+      if (!hasModel('ContentType')) {
+        db.registerModel(createContentTypeModel());
+      } else if (!db.hasModel('ContentType')) {
+        db.registerModel(getModel('ContentType'));
+      }
+
+      if (!hasModel('ContentEntry')) {
+        db.registerModel(createContentEntryModel());
+      } else if (!db.hasModel('ContentEntry')) {
+        db.registerModel(getModel('ContentEntry'));
+      }
+
+      getService(db);
+    },
+
+    onRoutesReady(ctx) {
+      adminPath = adminPathOpt || '/_admin';
+      this.api._options = { adminPath };
+
+      const service = getService(ctx.db || db);
+      const handlers = createContentApiHandlers({ contentService: service });
+
+      const publicBase = publicApiPath.replace(/\/$/, '');
+      ctx.addRoute(
+        'get',
+        `${publicBase}/:typeSlug/:entrySlug`,
+        handlers.publicGetEntryHandler
+      );
+
+      const adminApi = ctx.usePlugin('admin-panel');
+      if (!adminApi) {
+        console.warn('[content] admin-panel plugin not found, skipping admin UI');
+        const { requireAuth } = require('../admin-panel/auth');
+        const base = `${adminPath}/api/content`;
+        ctx.addRoute('get', `${base}/types`, requireAuth, handlers.listTypesHandler);
+        ctx.addRoute('post', `${base}/types`, requireAuth, handlers.createTypeHandler);
+        ctx.addRoute('get', `${base}/types/:id`, requireAuth, handlers.getTypeHandler);
+        ctx.addRoute('put', `${base}/types/:id`, requireAuth, handlers.updateTypeHandler);
+        ctx.addRoute('delete', `${base}/types/:id`, requireAuth, handlers.deleteTypeHandler);
+        ctx.addRoute('get', `${base}/types/:typeSlug/schema`, requireAuth, handlers.getTypeSchemaHandler);
+        ctx.addRoute('get', `${base}/types/:typeSlug/entries`, requireAuth, handlers.listEntriesHandler);
+        ctx.addRoute('post', `${base}/types/:typeSlug/entries`, requireAuth, handlers.createEntryHandler);
+        ctx.addRoute('get', `${base}/entries/:id`, requireAuth, handlers.getEntryHandler);
+        ctx.addRoute('put', `${base}/entries/:id`, requireAuth, handlers.updateEntryHandler);
+        ctx.addRoute('delete', `${base}/entries/:id`, requireAuth, handlers.deleteEntryHandler);
+        return;
+      }
+
+      const apiPrefix = '/content';
+      adminApi.registerModule({
+        id: 'content',
+
+        menuGroups: {
+          cms: {
+            label: 'CMS',
+            icon: 'database',
+            order: -1,
+          },
+        },
+
+        menu: [
+          {
+            id: 'content-types',
+            label: 'Content Types',
+            path: '/content/types',
+            icon: 'database',
+            group: 'cms',
+            order: 0,
+          },
+        ],
+
+        pages: [
+          {
+            id: 'content-types',
+            title: 'Content Types',
+            path: '/content/types',
+            icon: 'database',
+            component: generateContentTypesComponent({ apiPrefix }),
+          },
+          {
+            id: 'content-types-new',
+            title: 'New Content Type',
+            path: '/content/types/new',
+            component: generateContentTypesComponent({ apiPrefix }),
+          },
+          {
+            id: 'content-types-edit',
+            title: 'Edit Content Type',
+            path: '/content/types/edit/:id',
+            component: generateContentTypesComponent({ apiPrefix }),
+          },
+          {
+            id: 'content-entries',
+            title: 'Content Entries',
+            path: '/content/types/:typeSlug/entries',
+            component: generateContentEntriesComponent({ apiPrefix }),
+          },
+          {
+            id: 'content-entries-new',
+            title: 'New Content Entry',
+            path: '/content/types/:typeSlug/entries/new',
+            component: generateContentEntriesComponent({ apiPrefix }),
+          },
+          {
+            id: 'content-entries-edit',
+            title: 'Edit Content Entry',
+            path: '/content/types/:typeSlug/entries/edit/:id',
+            component: generateContentEntriesComponent({ apiPrefix }),
+          },
+        ],
+
+        api: {
+          prefix: apiPrefix,
+          routes: [
+            { method: 'get', path: '/types', handler: handlers.listTypesHandler },
+            { method: 'post', path: '/types', handler: handlers.createTypeHandler },
+            { method: 'get', path: '/types/:typeSlug/schema', handler: handlers.getTypeSchemaHandler },
+            { method: 'get', path: '/types/:typeSlug/entries', handler: handlers.listEntriesHandler },
+            { method: 'post', path: '/types/:typeSlug/entries', handler: handlers.createEntryHandler },
+            { method: 'get', path: '/types/:id', handler: handlers.getTypeHandler },
+            { method: 'put', path: '/types/:id', handler: handlers.updateTypeHandler },
+            { method: 'delete', path: '/types/:id', handler: handlers.deleteTypeHandler },
+            { method: 'get', path: '/entries/:id', handler: handlers.getEntryHandler },
+            { method: 'put', path: '/entries/:id', handler: handlers.updateEntryHandler },
+            { method: 'delete', path: '/entries/:id', handler: handlers.deleteEntryHandler },
+          ],
+        },
+      });
+    },
+  };
+}
+
+module.exports = contentPlugin;
+module.exports.contentPlugin = contentPlugin;
+module.exports.generateContentMigrations = generateContentMigrations;

package/plugins/content/migration-template.js

@@ -0,0 +1,54 @@
+/**
+ * Migration template for content plugin tables.
+ * @module plugins/content/migration-template
+ */
+
+/**
+ * @param {string} [typesTable='content_types']
+ * @param {string} [entriesTable='content_entries']
+ * @returns {string}
+ */
+function generateContentMigrations(typesTable = 'content_types', entriesTable = 'content_entries') {
+  return `/**
+ * Migration: Create content_types and content_entries tables
+ * Generated by content plugin — customize table names if needed.
+ */
+
+exports.up = async function (knex) {
+  await knex.schema.createTable('${typesTable}', (table) => {
+    table.increments('id').primary();
+    table.string('slug', 128).notNullable().unique();
+    table.string('name', 255).notNullable();
+    table.text('description').nullable();
+    table.json('schema').notNullable();
+    table.json('settings').nullable();
+    table.timestamp('created_at').defaultTo(knex.fn.now()).notNullable();
+    table.timestamp('updated_at').defaultTo(knex.fn.now()).notNullable();
+  });
+
+  await knex.schema.createTable('${entriesTable}', (table) => {
+    table.increments('id').primary();
+    table.integer('content_type_id').unsigned().notNullable()
+      .references('id').inTable('${typesTable}').onDelete('CASCADE');
+    table.string('slug', 128).notNullable();
+    table.string('title', 255).nullable();
+    table.json('data').notNullable();
+    table.string('status', 32).notNullable().defaultTo('published');
+    table.string('locale', 16).nullable();
+    table.integer('revision').notNullable().defaultTo(1);
+    table.timestamp('created_at').defaultTo(knex.fn.now()).notNullable();
+    table.timestamp('updated_at').defaultTo(knex.fn.now()).notNullable();
+
+    table.unique(['content_type_id', 'slug', 'locale']);
+    table.index(['content_type_id', 'status']);
+  });
+};
+
+exports.down = async function (knex) {
+  await knex.schema.dropTableIfExists('${entriesTable}');
+  await knex.schema.dropTableIfExists('${typesTable}');
+};
+`;
+}
+
+module.exports = { generateContentMigrations };

package/plugins/content/models/content-entry.js

@@ -0,0 +1,45 @@
+/**
+ * ContentEntry model — content entries with JSON field data.
+ * @module plugins/content/models/content-entry
+ */
+
+const { defineModel } = require('../../../core/orm/model');
+const { zdb } = require('../../../core/orm');
+
+const ContentEntrySchema = zdb.schema({
+  id: zdb.id(),
+  content_type_id: zdb.foreignKey('content_types', { index: true }),
+  slug: zdb.string({ maxLength: 128, index: true }),
+  title: zdb.string({ maxLength: 255, nullable: true }),
+  data: zdb.json(),
+  status: zdb.enum(['published', 'draft'], { default: 'published', index: true }),
+  locale: zdb.string({ maxLength: 16, nullable: true, index: true }),
+  revision: zdb.integer({ default: 1 }),
+  created_at: zdb.timestamp({ auto: 'create' }),
+  updated_at: zdb.timestamp({ auto: 'update' }),
+});
+
+/**
+ * @returns {import('../../../core/orm/types').ModelDefinition}
+ */
+function createContentEntryModel() {
+  return defineModel({
+    name: 'ContentEntry',
+    table: 'content_entries',
+    schema: ContentEntrySchema,
+    scopes: { timestamps: true },
+    admin: { enabled: false },
+    relations: {
+      contentType: {
+        type: 'belongsTo',
+        model: () => require('../../../core/orm/model').getModel('ContentType'),
+        foreignKey: 'content_type_id',
+      },
+    },
+  });
+}
+
+module.exports = {
+  createContentEntryModel,
+  ContentEntrySchema,
+};

package/plugins/content/models/content-type.js

@@ -0,0 +1,36 @@
+/**
+ * ContentType model — schema-driven content type definitions.
+ * @module plugins/content/models/content-type
+ */
+
+const { defineModel } = require('../../../core/orm/model');
+const { zdb } = require('../../../core/orm');
+
+const ContentTypeSchema = zdb.schema({
+  id: zdb.id(),
+  slug: zdb.string({ unique: true, maxLength: 128, index: true }),
+  name: zdb.string({ maxLength: 255 }),
+  description: zdb.text({ nullable: true }),
+  schema: zdb.json(),
+  settings: zdb.json({ nullable: true }),
+  created_at: zdb.timestamp({ auto: 'create' }),
+  updated_at: zdb.timestamp({ auto: 'update' }),
+});
+
+/**
+ * @returns {import('../../../core/orm/types').ModelDefinition}
+ */
+function createContentTypeModel() {
+  return defineModel({
+    name: 'ContentType',
+    table: 'content_types',
+    schema: ContentTypeSchema,
+    scopes: { timestamps: true },
+    admin: { enabled: false },
+  });
+}
+
+module.exports = {
+  createContentTypeModel,
+  ContentTypeSchema,
+};

package/plugins/index.js

@@ -21,6 +21,7 @@ const { uploadPlugin, createLocalFileProvider } = require('./upload');
 const { dataExchangePlugin } = require('./data-exchange');
 const { redirectPlugin } = require('./redirect');
 const { rateLimitPlugin } = require('./rate-limit');
+const contentPlugin = require('./content');
 
 module.exports = {
   sitemapPlugin,
@@ -41,5 +42,6 @@ module.exports = {
   dataExchangePlugin,
   redirectPlugin,
   rateLimitPlugin,
+  contentPlugin,
 };
 

package/src/file-router.js

@@ -810,6 +810,13 @@ function mountPages(app, options) {
         // Create context with plugin helpers merged
         const baseHelpers = createHelpers({ req, res, locale });
         const pluginHelpers = pluginManager ? pluginManager.getHelpers() : {};
+        if (pluginManager) {
+          const contentApi = pluginManager.getPluginAPI('content');
+          if (contentApi?.createRequestHelpers) {
+            const buildHelpers = contentApi.createRequestHelpers();
+            pluginHelpers.content = buildHelpers(req);
+          }
+        }
         
         const njkTpl = loadNjkRouteTemplate(route.fullPath, isDev);
 
@@ -863,6 +870,12 @@ function mountPages(app, options) {
         await executeHook(routeHooks, 'afterMiddleware', ctx);
         
         // Execute hooks: beforeLoad
+        if (pluginManager && db) {
+          const contentApi = pluginManager.getPluginAPI('content');
+          if (contentApi?.getContentService) {
+            ctx.content = contentApi.getContentService(db);
+          }
+        }
         await executeHook(globalHooks, 'beforeLoad', ctx);
         await executeHook(routeHooks, 'beforeLoad', ctx);
         
@@ -908,10 +921,17 @@ function mountPages(app, options) {
         
         // Render the template
         const templatePath = route.file.split(path.sep).join('/');
-        const html =
+        let html =
           njkTpl.useStringRender && njkTpl.templateBody != null
             ? nunjucks.renderString(njkTpl.templateBody, renderContext, { path: route.fullPath })
             : nunjucks.render(templatePath, renderContext);
+
+        if (pluginManager) {
+          const contentApi = pluginManager.getPluginAPI('content');
+          if (contentApi?.maybeInjectInlineEdit) {
+            html = contentApi.maybeInjectInlineEdit(req, html);
+          }
+        }
         
         // Execute hooks: afterRender
         ctx.html = html;

package/templates/skills/webspresso-usage/REFERENCE-framework.md

@@ -178,7 +178,7 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 
 **Query builder:** `UserRepo.query().where(...).with('relation').orderBy(...).list()` / `.first()` / `.paginate()` / `.count()`. **`with()`** eager-loads relations; **`count()`** ignores builder `.limit`/`.offset` for total; see ORM docs for edge cases.
 
-**Migrations:** `webspresso db:migrate`, `db:rollback`, `db:status`, `db:make`.
+**Migrations:** `webspresso db:migrate`, `db:rollback`, `db:status`, `db:make`, `db:scaffold` (all models → create migrations).
 
 **Transactions:** `db.transaction(async (trx) => { trx.getRepository('User') })`.
 

package/templates/skills/webspresso-usage/SKILL.md

@@ -21,6 +21,7 @@ There are **three** files in this folder; open the reference that matches the ta
 | Greenfield project, `webspresso new`, `dev`, `db:migrate`, `doctor` | [`REFERENCE-framework.md`](./REFERENCE-framework.md) § CLI | Full command table there. |
 | Event bus, `kernel.createApp`, `defineFlow`, `definePlugin`, simulated `BaseRepository`, namespaced minimal views | [`REFERENCE-kernel.md`](./REFERENCE-kernel.md) | **Not** SSR **`createApp`** — [`doc/index.html#application-kernel`](../../../doc/index.html#application-kernel). |
 | Long-form narrative, all options | [`README.md`](../../../README.md), [`doc/index.html`](../../../doc/index.html) | Single-page HTML docs. |
+| System structure, feature sets, C4 map | [`docs/ARCHITECTURE.md`](../../../docs/ARCHITECTURE.md) | **Update when adding plugins, CLI commands, or extension points.** |
 
 ## CLI cheat sheet
 
@@ -40,3 +41,7 @@ There are **three** files in this folder; open the reference that matches the ta
 - **`REFERENCE-kernel.md`:** `kernel`, domain events, `dispatch` / `publish`, `registerFlow`, `definePlugin` inside the kernel.
 
 They are independent: most apps only need SSR **`createApp`**; the kernel is optional.
+
+## Architecture maintenance
+
+When you add or materially change a **plugin**, **CLI command**, **extension point**, or **request-pipeline rule**, update [`docs/ARCHITECTURE.md`](../../../docs/ARCHITECTURE.md) (feature-set section + changelog).