cms42 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e1f04a63886b81a25188c13e92f78957e2433dea300d98d0d35b06e56fcd214f
+  data.tar.gz: 79b2e0b306959f37b5bbd96fe50e1ab28c8d842067f8cd7c98dd15d1fed845cb
+SHA512:
+  metadata.gz: 1a29897d35a8e3c9663b0b3630070255f470049e14e3908770b13c8e41db465eb7d74c469d4dec80c6db0fe94da951397edeed74d4df74ae2e26745a92cfbd4b
+  data.tar.gz: 7fa437f289d48be262d3188ee1d04cedd163e8856a3f19f2963997d7d5edf04e2ac6d8a098cf4796f850a7f0f708029bf3cba6947110fbd557967a5e0114ce94

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shift42
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,299 @@
+# CMS
+
+A mountable Rails CMS engine by [Shift42](https://shift42.io).
+
+Rails-native, straightforward to extend, and easy for content editors to use.
+
+## Compatibility
+
+- Ruby >= 3.1
+- Rails >= 7.1 (tested up to 8.x)
+- PostgreSQL
+
+## Features
+
+| Feature                                                        | Status |
+| -------------------------------------------------------------- | ------ |
+| Multi-site support                                             | ✅     |
+| Content blocks / StreamField (`Cms::Section`)                  | ✅     |
+| Multilingual (locale-scoped translations)                      | ✅     |
+| Publishing workflow (draft / published / archived)             | ✅     |
+| Soft-delete for pages and sections (`discard` gem)             | ✅     |
+| Draft preview URLs (token-based, shareable without auth)       | ✅     |
+| Page tree (parent/child hierarchy)                             | ✅     |
+| Media management (images + documents)                          | ✅     |
+| Reusable sections across pages + standalone admin library      | ✅     |
+| Form fields + submission capture + email notification          | ✅     |
+| Full-text search (title + slug, ilike/unaccent)                | ✅     |
+| Headless JSON API v1 (API key auth)                            | ✅     |
+| Webhooks (HMAC-signed, per status change, delivery log)        | ✅     |
+| Engine-owned English I18n defaults                             | ✅     |
+| Host app extension points (`Cms.setup`)                        | ✅     |
+
+## Installation
+
+Add to your host app's `Gemfile`:
+
+```ruby
+gem "cms42"
+```
+
+The published gem name is `cms42`, but the engine namespace remains `Cms::`.
+If you load gems manually instead of letting Bundler auto-require them, use:
+
+```ruby
+require "cms42"
+```
+
+Install and migrate:
+
+```bash
+bundle install
+bin/rails active_storage:install  # skip if already installed
+bin/rails generate cms:install
+bin/rails db:migrate
+```
+
+Mount in `config/routes.rb`:
+
+```ruby
+mount Cms::Engine, at: "/cms"
+```
+
+Copy engine views into your host app (for Hyper/admin customisation, etc):
+
+```bash
+# Copy all CMS views
+bin/rails generate cms:views
+
+# Copy only admin/public/mailer views
+bin/rails generate cms:views admin
+bin/rails generate cms:views public
+bin/rails generate cms:views mailer
+
+# Or select scopes explicitly
+bin/rails generate cms:views -v admin public
+```
+
+## Configuration
+
+Create `config/initializers/cms.rb`:
+
+```ruby
+Cms.setup do |config|
+  # Public/API controllers inherit from this host controller
+  config.parent_controller = "ApplicationController"
+
+  # Required: admin inherits from a host app controller that already handles
+  # authentication/authorization for the CMS admin area
+  config.admin_parent_controller = "Admin::BaseController"
+
+  # Optional for public/API if you resolve sites via URL slug, subdomain,
+  # or X-CMS-SITE-SLUG. Required for admin once any Cms::Site exists.
+  config.current_site_resolver = ->(controller) { controller.current_organization&.cms_site }
+
+  # Optional: image renditions (used by cms_image_tag helper)
+  config.image_renditions = {
+    thumb: "300x200",
+    hero:  "1200x630"
+  }
+
+  # Optional: notification email for form submissions
+  config.form_submission_email = ->(page) { "admin@example.com" }
+
+  # Optional: sender address for outgoing CMS mailers (defaults to "noreply@example.com")
+  config.mailer_from = "cms@myapp.com"
+
+  # Optional: gate admin access — return false/nil to respond with 403
+  config.authorize_admin = ->(controller) { controller.current_user&.admin? }
+
+  # Optional: auto-destroy sections that become orphaned after page removal (default: false)
+  config.auto_destroy_orphaned_sections = false
+
+  # Optional: replace the page resolver used by public/API requests
+  config.page_resolver_class = "Cms::PageResolver"
+
+  # Optional: replace API serializer classes
+  config.api_site_serializer_class = "Cms::Api::SiteSerializer"
+  config.api_page_serializer_class = "Cms::Api::PageSerializer"
+end
+```
+
+## Configuration Surface
+
+These are the supported host app extension points today:
+
+| Config key | Signature | Purpose |
+|---|---|---|
+| `parent_controller` | String class name | Base public/API controller to inherit from |
+| `admin_parent_controller` | String class name | Base admin controller to inherit from |
+| `current_site_resolver` | `->(controller)` | Host-provided current site resolver; required for admin once sites exist |
+| `authorize_admin` | `->(controller)` | Optional RBAC hook; return false/nil to respond 403 |
+| `form_submission_email` | `->(page)` | Notification email recipient address |
+| `mailer_from` | String | Sender address for CMS mailers (default: `"noreply@example.com"`) |
+| `image_renditions` | Hash | Named variant dimensions |
+| `page_templates` | Array of strings/symbols | Registers additional public page template keys |
+| `page_resolver_class` | String class name / Class | Resolver used by public and API page lookup |
+| `api_site_serializer_class` | String class name / Class | Serializer for `GET /api/v1/site` and `GET /api/v1/sites/:site_slug` |
+| `api_page_serializer_class` | String class name / Class | Serializer for `GET /api/v1/pages/:slug` and site-scoped page endpoints |
+| `admin_layout` | String layout name | Admin layout override |
+| `public_layout` | String layout name | Public layout override |
+| `auto_destroy_orphaned_sections` | Boolean | Auto-destroy sections that have no remaining page placements (default: `false`) |
+
+Controller class replacement per namespace is not a supported config seam today. Public/API inherit from `parent_controller`, admin inherits from `admin_parent_controller`, and deeper controller replacement should still happen with normal Rails route/controller overrides in the host app.
+
+## Host App Extension
+
+The engine is intentionally CMS-only. It manages content structure, publishing, media, reusable sections, forms, and CMS rendering.
+
+If the host app needs business-specific public behavior such as ecommerce pages, customer login, account areas, or custom data models, implement that in the host app using standard Rails patterns:
+
+- add host app routes before or alongside the mounted CMS engine
+- use host app controllers and views for business-specific pages
+- query host app models directly from the host app
+- override engine views or controllers only when CMS behavior itself needs to change
+- reuse CMS sections or rendered content inside host app pages when helpful
+
+The CMS engine should not know about host concepts such as products, carts, customers, orders, or accounts.
+
+## Locales
+
+Engine-owned UI strings live in `config/locales/en.yml` under `cms.*`.
+
+- Host apps can override or extend them with normal Rails locale files such as `config/locales/el.yml`.
+- Public and API locale resolution is explicit: `Cms::PageResolver` returns the chosen locale, and controllers apply it with `I18n.with_locale`.
+- Public and API page lookup uses `config.page_resolver_class`, which defaults to `Cms::PageResolver`.
+- Public form errors and notices are translated through I18n, so host apps can localize validation and flash output without monkey-patching engine code.
+
+## Content Blocks (StreamField)
+
+Register custom block types in your host app:
+
+```ruby
+Cms::Section::KindRegistry.register(
+  "my_custom_block",
+  partial:     "cms/sections/my_custom_block",
+  block_class: MyApp::MyCustomBlock
+)
+```
+
+Block classes inherit from `Cms::Section::BlockBase` and declare typed settings:
+
+```ruby
+class MyApp::MyCustomBlock < Cms::Section::BlockBase
+  settings_schema do
+    field :background_color, type: :string,  default: "#ffffff"
+    field :columns,          type: :integer, default: 3
+  end
+end
+```
+
+## Reusable Sections
+
+Sections are site-scoped reusable content blocks that can be attached to multiple pages.
+They can be managed centrally in the admin section library and then attached where needed.
+
+Built-in image sections reference `Cms::Image` records from the CMS media library via `settings["image_id"]` instead of storing raw URLs.
+
+Use the `cms_sections` helper in views when you need to list reusable sections by kind:
+
+```erb
+<% cms_sections(kind: "cta").each do |section| %>
+  <%= render_section(section) %>
+<% end %>
+```
+
+## Page Templates
+
+`Cms::Page#template_key` drives public page rendering as a presentation concern.
+
+Public pages render through a shared shell at `cms/public/pages/show`, which then resolves a template partial at:
+
+- `cms/public/pages/templates/_<template_key>.html.erb`
+- fallback: `cms/public/pages/templates/_standard.html.erb`
+
+The engine ships `standard`, `landing`, `form`, and `custom` template partials. Host apps can override any of them with normal Rails view overrides by placing files at the same paths in `app/views`.
+
+This keeps page templates simple and maintainable:
+
+- routes stay stable
+- controllers stay shared
+- `template_key` stays presentation-only
+- host apps can customize page types without replacing the full public rendering flow
+
+## Headless API
+
+The JSON API is available at `/api/v1/` and requires a Bearer token.
+Create API keys in the admin UI (`/admin/api_keys`).
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+     https://yourapp.com/cms/api/v1/pages/about
+```
+
+Endpoints:
+
+- `GET /api/v1/site` — site info + published pages
+- `GET /api/v1/pages/:slug` — single page resource with sections
+- `GET /api/v1/pages/:slug?include_site=true` — page resource plus lightweight site metadata
+- `GET /api/v1/sites/:site_slug` — (multi-site) site info
+- `GET /api/v1/sites/:site_slug/pages/:slug` — (multi-site) page
+
+## Webhooks
+
+Configure webhooks in the admin UI. Each webhook receives a HMAC-signed POST:
+
+```
+POST https://yourapp.com/webhook-receiver
+X-CMS-Event: page.published
+X-CMS-Signature: sha256=<hex>
+Content-Type: application/json
+```
+
+Supported events: `page.published`, `page.unpublished`.
+
+Verify the signature in your receiver:
+
+```ruby
+expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', YOUR_SECRET, request.body.read)}"
+ActiveSupport::SecurityUtils.secure_compare(expected, request.headers['X-CMS-Signature'])
+```
+
+## Routes
+
+| Path | Description |
+|---|---|
+| `/admin/` | Admin UI |
+| `/api/v1/` | Headless JSON API (requires API key) |
+| `/sites/:site_slug/` | Public SSR (multi-site) |
+| `/` and `/*slug` | Public SSR (single-site) |
+
+## Notes
+
+- Admin does not guess a site. If no `Cms::Site` records exist yet it redirects to `new_admin_site_path`; otherwise it expects `config.current_site_resolver` to return a `Cms::Site`.
+- Public/API site resolution supports `config.current_site_resolver`, `params[:site_slug]`, `X-CMS-SITE-SLUG`, or first subdomain.
+- API serialization is handled by `config.api_site_serializer_class` and `config.api_page_serializer_class`, which default to `Cms::Api::SiteSerializer` and `Cms::Api::PageSerializer`.
+- Navigation rendering uses `header_nav` and `footer_nav` page scopes.
+- `template_key` selects `cms/public/pages/templates/<template_key>` with fallback to `standard`, so host apps can override page presentation per template key.
+- Page hierarchy is a simple parent/child adjacency list and is intentionally optimized for modest marketing-style site trees, not large catalog trees.
+- Revisions and snippets are not part of the current engine architecture. Reusable content is centered on `Cms::Section` and `Cms::PageSection`.
+
+## Development
+
+```bash
+# Run tests (uses spec/cms_app dummy app)
+bundle exec rspec
+
+# Run linter
+bin/rubocop
+
+# Console in dummy app
+cd spec/cms_app && bin/rails console
+
+# Run dummy app server
+cd spec/cms_app && bin/rails server
+```
+
+## License
+
+MIT. See [LICENSE](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/cms_app/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)

data/app/assets/stylesheets/cms/application.css

@@ -0,0 +1,3 @@
+/*
+ *= require_self
+ */

data/app/controllers/cms/admin/api_keys_controller.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Cms
+  module Admin
+    class ApiKeysController < BaseController
+      before_action :set_api_key, only: %i[edit update destroy]
+
+      def index
+        @api_keys = current_site.api_keys.order(created_at: :desc)
+      end
+
+      def new
+        @api_key = current_site.api_keys.build
+      end
+
+      def create
+        @api_key = current_site.api_keys.build(api_key_params)
+        if @api_key.save
+          @new_token = @api_key.token
+          render :create
+        else
+          render :new, status: :unprocessable_content
+        end
+      end
+
+      def edit; end
+
+      def update
+        if @api_key.update(api_key_params.except(:token))
+          redirect_to admin_api_keys_path, notice: t("cms.notices.api_key_updated")
+        else
+          render :edit, status: :unprocessable_content
+        end
+      end
+
+      def destroy
+        @api_key.destroy
+        redirect_to admin_api_keys_path, notice: t("cms.notices.api_key_deleted")
+      end
+
+      private
+
+      def set_api_key
+        @api_key = current_site.api_keys.find(params[:id])
+      end
+
+      def api_key_params
+        params.require(:api_key).permit(:name, :active)
+      end
+    end
+  end
+end

data/app/controllers/cms/admin/base_controller.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Cms
+  module Admin
+    class BaseController < (Cms.config.admin_parent_controller.presence || Cms.parent_controller).constantize
+      include Cms::CurrentSiteResolver
+
+      layout -> { Cms.config.admin_layout }
+      helper Cms::ApplicationHelper
+
+      rescue_from ActiveRecord::RecordNotFound, with: :render_admin_not_found
+
+      before_action :authorize_admin_action!
+      before_action :ensure_site_access!
+
+      private
+
+      def current_site
+        @current_site ||= configured_current_site || raise_missing_current_site!
+      end
+
+      def ensure_site_access!
+        return if bootstrap_site_request? && Cms::Site.none?
+        return if configured_current_site.present?
+
+        if Cms::Site.none?
+          redirect_to new_admin_site_path
+          return
+        end
+
+        raise_missing_current_site!
+      end
+
+      def authorize_admin_action!
+        return unless Cms.config.authorize_admin.present?
+        return if Cms.config.authorize_admin.call(self)
+
+        head :forbidden
+      end
+
+      def bootstrap_site_request?
+        controller_name == "sites" && action_name.in?(%w[new create])
+      end
+
+      def render_admin_not_found
+        redirect_to admin_pages_path, alert: t("cms.errors.record_not_found")
+      end
+
+      def raise_missing_current_site!
+        raise t("cms.errors.current_site_required")
+      end
+    end
+  end
+end

data/app/controllers/cms/admin/documents_controller.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Cms
+  module Admin
+    class DocumentsController < BaseController
+      before_action :set_document, only: %i[edit update destroy]
+
+      def index
+        @documents = current_site.documents.ordered
+      end
+
+      def new
+        @document = current_site.documents.build
+      end
+
+      def edit; end
+
+      def create
+        @document = current_site.documents.build(document_params)
+
+        if @document.save
+          redirect_to admin_documents_path, notice: t("cms.notices.document_uploaded")
+        else
+          render :new, status: :unprocessable_content
+        end
+      end
+
+      def update
+        @document.assign_attributes(document_params)
+
+        if @document.save
+          redirect_to admin_documents_path, notice: t("cms.notices.document_updated")
+        else
+          render :edit, status: :unprocessable_content
+        end
+      end
+
+      def destroy
+        @document.file.purge_later
+        @document.destroy
+        redirect_to admin_documents_path, notice: t("cms.notices.document_deleted")
+      end
+
+      private
+
+      def set_document
+        @document = current_site.documents.find(params[:id])
+      end
+
+      def document_params
+        params.fetch(:cms_document, params.fetch(:document, ActionController::Parameters.new))
+              .permit(:title, :description, :file)
+      end
+    end
+  end
+end

data/app/controllers/cms/admin/form_fields_controller.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Cms
+  module Admin
+    class FormFieldsController < BaseController
+      before_action :set_page
+      before_action :set_field, only: %i[edit update destroy]
+
+      def index
+        @fields = @page.form_fields.ordered
+      end
+
+      def new
+        @field = @page.form_fields.build(position: @page.form_fields.count)
+      end
+
+      def edit; end
+
+      def create
+        @field = @page.form_fields.build(field_params)
+
+        if @field.save
+          redirect_to admin_page_form_fields_path(@page), notice: t("cms.notices.field_added")
+        else
+          render :new, status: :unprocessable_content
+        end
+      end
+
+      def update
+        @field.assign_attributes(field_params)
+
+        if @field.save
+          redirect_to admin_page_form_fields_path(@page), notice: t("cms.notices.field_updated")
+        else
+          render :edit, status: :unprocessable_content
+        end
+      end
+
+      def destroy
+        @field.destroy
+        redirect_to admin_page_form_fields_path(@page), notice: t("cms.notices.field_removed")
+      end
+
+      def sort
+        Array(params[:field_ids]).each_with_index do |id, position|
+          @page.form_fields.find(id).update!(position: position)
+        end
+        head :ok
+      end
+
+      private
+
+      def set_page
+        @page = current_site.pages.find(params[:page_id])
+      end
+
+      def set_field
+        @field = @page.form_fields.find(params[:id])
+      end
+
+      def field_params
+        params.fetch(:cms_form_field, params.fetch(:form_field, ActionController::Parameters.new))
+              .permit(
+                :kind, :label, :field_name, :placeholder, :hint, :required, :position,
+                options: []
+              )
+      end
+    end
+  end
+end

data/app/controllers/cms/admin/form_submissions_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Cms
+  module Admin
+    class FormSubmissionsController < BaseController
+      before_action :set_page
+
+      def index
+        @submissions = @page.form_submissions.recent
+        @fields = @page.form_fields.ordered
+
+        respond_to do |format|
+          format.html
+          format.csv do
+            csv = Cms::FormSubmission.to_csv(@submissions, @fields)
+            send_data csv,
+                      filename: "#{@page.slug}-submissions-#{Date.today}.csv",
+                      type: "text/csv"
+          end
+        end
+      end
+
+      def destroy
+        @submission = @page.form_submissions.find(params[:id])
+        @submission.destroy
+        redirect_to admin_page_form_submissions_path(@page), notice: t("cms.notices.submission_deleted")
+      end
+
+      private
+
+      def set_page
+        @page = current_site.pages.find(params[:page_id])
+      end
+    end
+  end
+end

data/app/controllers/cms/admin/images_controller.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Cms
+  module Admin
+    class ImagesController < BaseController
+      before_action :set_image, only: %i[edit update destroy]
+
+      def index
+        @images = current_site.images.includes(:localised).ordered
+      end
+
+      def new
+        @image = current_site.images.build
+        @translation_locale = requested_locale
+        @image.image_translations.build(locale: @translation_locale)
+      end
+
+      def edit
+        @translation_locale = requested_locale
+        @image.image_translations.find_or_initialize_by(locale: @translation_locale)
+      end
+
+      def create
+        @image = current_site.images.build(image_params)
+        @translation_locale = requested_locale
+
+        if @image.save
+          redirect_to admin_images_path, notice: t("cms.notices.image_uploaded")
+        else
+          render :new, status: :unprocessable_content
+        end
+      end
+
+      def update
+        @translation_locale = requested_locale
+        @image.assign_attributes(image_params)
+
+        if @image.save
+          redirect_to admin_images_path, notice: t("cms.notices.image_updated")
+        else
+          render :edit, status: :unprocessable_content
+        end
+      end
+
+      def destroy
+        @image.file.purge_later
+        @image.destroy
+        redirect_to admin_images_path, notice: t("cms.notices.image_deleted")
+      end
+
+      private
+
+      def set_image
+        @image = current_site.images.includes(:image_translations, :localised).find(params[:id])
+      end
+
+      def image_params
+        params.fetch(:cms_image, params.fetch(:image, ActionController::Parameters.new))
+              .permit(:title, :file, image_translations_attributes: %i[id locale alt_text caption])
+      end
+
+      def requested_locale
+        params[:locale].presence || current_site.default_locale.presence || I18n.locale.to_s
+      end
+    end
+  end
+end