plum-cms 0.1.2 → 0.2.1

data/docs/roadmap.md

@@ -0,0 +1,100 @@
+# Roadmap
+
+Plum's roadmap is organized by outcomes rather than promised dates. Priorities
+move as the product is exercised in real Rails applications.
+
+## Shipped: Plum 0.2.0 — Authoring Foundation
+
+Plum 0.2.0 established the practical authoring surface:
+
+- a visual blueprint builder with 21 field types, reusable fieldsets, nested
+  structures, validation, field widths, sections, and conditions;
+- assets with single and multiple image fields, metadata, focal points, and
+  responsive variants;
+- relationships, taxonomies, navigation, globals, forms, and Liquid themes;
+- drafts, scheduled publishing, immutable revisions, and rollback;
+- localized entries, locale-aware public routes, and a live-only content API;
+- registry-backed custom field types and packaged Tailwind control-panel styles.
+
+See [the Statamic parity matrix](statamic-parity.md) for the supported surface.
+
+## Now: Plum 0.3.0 — Production Readiness
+
+The 0.3.0 milestone makes Plum safe to adopt, move, recover, and operate outside
+its development repository.
+
+### 1. Portability and recovery
+
+- Versioned site export/import covering schemas, entries, relationships,
+  taxonomies, navigation, globals, forms, settings, and assets.
+- Tested backup and restore commands with integrity checks and clear failure
+  behavior.
+- A documented archive format that remains readable across compatible releases.
+
+### 2. Real-world installation
+
+- Build `plumcms.org` as a standalone Rails application using the released gem.
+- Test fresh external installations and 0.2.x upgrades in CI.
+- Publish a production Docker contract and SQLite deployment example.
+- Exercise health checks, upgrades, persistence, backup, and restore on a VM.
+
+### 3. Publishing and discovery
+
+- SEO metadata, canonical URLs, redirects, XML sitemaps, and feeds.
+- Document hierarchy, breadcrumbs, generated tables of contents, and site search.
+- Secure, shareable preview links for draft and scheduled content.
+
+### 4. Editorial operations
+
+- Asset folders, search, replacement, cropping, and richer transformations.
+- Granular editorial roles, approvals, and publish permissions.
+- Form spam protection and improved submission review/export workflows.
+
+### 5. Documentation
+
+- Complete installation and first-page guides.
+- Document every supported field and content primitive.
+- Document standalone SQLite and embedded PostgreSQL operation.
+- Publish configuration, troubleshooting, extension, upgrade, backup, and
+  restore references.
+
+## Next: Plum 0.4.0 — Repeatable Adoption
+
+- A thin `plum` CLI for diagnostics, export/import, backup/restore, upgrades,
+  themes, and packaging.
+- Starter applications for common publishing use cases.
+- Theme scaffolding, validation, packaging, and distribution tools.
+- A collection of high-quality open themes and blocks.
+- Importers for common CMS and structured-data formats.
+- Addon discovery and a documented compatibility contract.
+
+## Later: The Rails Content Ecosystem
+
+- Translation-service integrations and richer localization workflows.
+- Agency-oriented multisite operations and reusable project recipes.
+- Community examples, case studies, talks, and contribution programs.
+- Broader content APIs where real applications demonstrate the need.
+
+## Plum 1.0
+
+Plum 1.0 means another Rails developer can reproduce what powers
+`plumcms.org` without private knowledge or site-specific patches.
+
+It requires:
+
+- a published, versioned gem;
+- an editable page within ten minutes of installation;
+- dependable standalone and embedded installation paths;
+- a documented SQLite production deployment;
+- clean host authentication, authorization, and tenancy integration;
+- preview, revisions, export, backup, and restore;
+- complete documentation for the supported public surface;
+- a tested upgrade path;
+- at least one production standalone site and one production embedded use; and
+- a public example application that agencies can study and adapt.
+
+## Not on the Near-Term Roadmap
+
+Plum is not trying to become a general-purpose admin framework, a freeform
+visual design tool, an ecommerce platform, or a hosted headless CMS. Plum's
+focus is managed content that belongs inside Rails.

data/docs/site/homepage.md

@@ -0,0 +1,104 @@
+# Homepage Copy
+
+## Hero
+
+### Plum
+
+**The Rails-native CMS.**
+
+Add managed content to an existing Rails application or build a complete
+content-first site—without leaving the Rails stack.
+
+Primary action: **Get started**
+
+Secondary action: **View on GitHub**
+
+Supporting note: Open source. Self-hosted. SQLite and PostgreSQL.
+
+## One Stack, Complete Control
+
+Plum uses the Rails application you already understand: its database, users,
+authorization, jobs, mail, storage, and deployment. There is no external CMS to
+synchronize and no second frontend to maintain.
+
+```ruby
+gem "plum"
+```
+
+```bash
+bin/rails generate plum:install --mount-path=/website
+bin/rails db:migrate
+```
+
+## Two Ways to Use Plum
+
+### Add content to your application
+
+Mount Plum in an existing Rails product. Let customers or editors manage pages,
+navigation, documentation, announcements, and structured content while the host
+application continues to own identity and business data.
+
+Action: **Embed Plum**
+
+### Build the whole site with Plum
+
+Start with Rails, SQLite, and a Plum theme. Ship a fast, portable content site
+that can grow into a custom Rails application whenever the project demands it.
+
+Action: **Build a Plum site**
+
+## Application Data Meets Editorial Content
+
+Expose host application data safely to Plum templates without copying it into a
+remote CMS.
+
+```ruby
+Plum.configure do |config|
+  config.current_site_resolver = ->(_) { Current.account.plum_site }
+  config.current_user_resolver = ->(_) { Current.user }
+
+  config.register_content_source :products do |context|
+    context.owner.products.published
+  end
+end
+```
+
+Editors manage the story. Rails remains the source of truth for the application.
+
+## Familiar Rails Foundations
+
+- Rails 8 engine
+- Hotwire control panel
+- Active Record content
+- Active Storage assets
+- Active Job notifications
+- Liquid themes
+- SQLite and PostgreSQL
+- Host-owned authentication and authorization
+
+## For Independent Developers and Agencies
+
+Package each client site as an independent Rails application with its own
+SQLite database, assets, domain, and backup. Run several sites economically on
+one VM with an ONCE-compatible container, and move any client without untangling
+a shared CMS installation.
+
+Action: **See the agency model**
+
+## Built in Public, Used for Real
+
+This website is a Rails application powered by Plum and SQLite. The same public
+engine, theme system, and deployment path are available to every Plum project.
+
+Action: **How this site works**
+
+## Closing Call to Action
+
+### Keep content in Rails.
+
+Give editors the tools they need without giving up the application stack you
+want.
+
+Primary action: **Read the getting-started guide**
+
+Secondary action: **Explore the roadmap**

data/docs/site/information-architecture.md

@@ -0,0 +1,176 @@
+# plumcms.org Information Architecture
+
+The site serves three audiences: developers adding content to an existing Rails
+application, developers building a content-first site, and agencies operating
+multiple client sites.
+
+## Primary Navigation
+
+- Why Plum
+- Use Cases
+- Documentation
+- Roadmap
+- GitHub
+
+The persistent primary action is **Get started**.
+
+## Routes
+
+```text
+/
+/why-plum
+/features
+/use-cases
+  /existing-rails-apps
+  /content-sites
+  /agencies
+/docs
+  /getting-started
+  /concepts
+  /content-modeling
+  /themes
+  /embedding
+  /deployment
+  /reference
+/roadmap
+/changelog
+/demo
+```
+
+## Homepage Story
+
+The homepage should answer five questions in order:
+
+1. What is Plum?
+2. Why would a Rails developer use it instead of another CMS?
+3. Can it work in my kind of project?
+4. What does the code and editing experience look like?
+5. Can I trust and try it?
+
+## Documentation Structure
+
+### Start
+
+- Introduction
+- Installation
+- Your first editable page
+- Build a small content site
+
+### Core concepts
+
+- Sites
+- Content types and blueprints
+- Entries and publishing
+- Fields
+- Liquid rendering
+
+### Content features
+
+- Blocks
+- Rich text
+- Assets and images
+- Relationships
+- Taxonomies
+- Navigation
+- Globals
+- Forms
+
+### Themes
+
+- Theme anatomy
+- Templates and layouts
+- Theme manifests
+- Settings
+- Assets
+- Blocks
+- Packaging and installation
+
+### Embed Plum
+
+- Mounting the engine
+- Host authentication
+- Authorization
+- Site resolution and tenancy
+- Host content sources
+- Routes and URLs
+- White labelling
+
+### Operate
+
+- SQLite deployment
+- PostgreSQL deployment
+- Active Storage
+- Jobs and email
+- Docker and ONCE
+- Backups and restore
+- Upgrading
+
+### Reference
+
+- Configuration
+- Blueprint field contracts
+- Liquid objects and filters
+- Theme manifest
+- Generators
+- Troubleshooting
+
+## Content Types
+
+### Pages
+
+- Title
+- Slug
+- Summary
+- Sections (`blocks`)
+- SEO title
+- SEO description
+
+### Documentation pages
+
+- Title
+- Slug
+- Section taxonomy
+- Parent relationship
+- Position
+- Summary
+- Body
+
+### Releases
+
+- Version
+- Published date
+- Summary
+- Body
+
+### Roadmap items
+
+- Title
+- Horizon (`now`, `next`, or `later`)
+- Status
+- Problem
+- Intended outcome
+
+## Initial Blocks
+
+- Hero
+- Prose
+- Code example
+- Feature grid
+- Use-case cards
+- Steps
+- Comparison
+- Quote
+- Call to action
+
+Blocks should be general enough to ship as examples or reusable base blocks.
+Site-specific styling belongs in the plumcms.org theme.
+
+## Proof the Site Must Provide
+
+- The homepage is editable through Plum.
+- Documentation is navigable and pleasant to read.
+- A visitor can see real installation code immediately.
+- The public roadmap distinguishes current capability from future intent.
+- The application runs on Rails and SQLite in production.
+- Its container, persistence, backup, and restore approach are documented.
+- No private Plum features or site-specific engine patches are required.

data/docs/statamic-parity.md

@@ -0,0 +1,28 @@
+# Statamic capability parity
+
+This matrix tracks practical authoring parity rather than matching Statamic's
+internal architecture or naming.
+
+| Capability | Plum status | Notes |
+|---|---|---|
+| Blueprint field builder | Supported | Visual, nested, typed configuration |
+| Reusable fieldsets | Supported | Site-scoped snapshots with collision-safe insertion |
+| Field instructions/defaults/required | Supported | Client and server validation |
+| Field widths and sections | Supported | Twelve-column responsive editor |
+| Conditional fields | Supported | Five common operators |
+| Text, rich text, numbers, dates | Supported | Bounds and modes included |
+| Choice controls | Supported | Select, radio, buttons, checkboxes |
+| Assets | Supported | Single/multi-image fields, metadata, focal points, variants |
+| Relationships | Supported | Single/multiple, type-filtered, site-scoped |
+| Structured content | Supported | Lists, groups, repeaters, blocks |
+| Taxonomies | Supported | Managed terms and public archives |
+| Globals and navigation | Supported | Liquid-accessible content |
+| Forms | Supported | Definitions, submissions, notifications |
+| Themes | Supported | Liquid packages, settings, blocks |
+| Revisions and publishing workflow | Supported | Attributed snapshots, restoration, drafts, scheduling |
+| Localization/multisite | Supported | Site locales, translation groups, localized URLs/API |
+| Content API | Supported | Public, site-scoped, live-only JSON collections |
+| Addon field types | Supported | Registry-backed editor and value pipeline |
+
+Longer-term ecosystem work can add commercial-style addon discovery, more
+workflow roles, and translation services without changing these authoring APIs.

data/docs/vision.md

@@ -0,0 +1,82 @@
+# Plum's Vision
+
+Plum is the Rails-native CMS.
+
+It gives Rails developers a default way to add managed content to an existing
+application or build a complete content-first site without introducing another
+application stack.
+
+## Why Plum Exists
+
+Rails is excellent at building applications, but content management is still
+usually assembled from bespoke admin screens, delegated to a remote headless
+CMS, or moved into a separate publishing platform. Each choice adds work or
+pulls content away from the application that uses it.
+
+Plum makes content a native part of Rails. It uses the application's database,
+models, users, authorization, jobs, mail, storage, and deployment environment.
+Developers keep the flexibility of Ruby and Rails. Editors get a focused,
+polished place to manage content.
+
+## Who Plum Is For
+
+### Rails application teams
+
+Mount Plum inside an existing application to manage marketing pages,
+documentation, announcements, navigation, help content, and other editorial
+material. Application records can be exposed safely alongside managed content
+without copying them into an external CMS.
+
+### Independent developers and agencies
+
+Use Plum as the foundation of a complete client site. Start with Rails, SQLite,
+a Plum theme, and one deployable container. Retain the ability to add ordinary
+Rails features when the project grows beyond a brochure site.
+
+### SaaS products
+
+Give each account a site-scoped, white-labelled editing experience while the
+host application continues to own identity, authorization, tenancy, and
+business data.
+
+## The Promise
+
+A developer should be able to add Plum to a Rails application and publish an
+editable page in less than ten minutes.
+
+A small content site should be able to run as one Rails application with SQLite
+and persistent storage. An agency should be able to operate several independent
+Plum sites on one VM as portable containers. A larger application should be
+able to use PostgreSQL and embed Plum without changing its content model.
+
+Content must remain portable. Plum should never require a hosted Plum account,
+a proprietary runtime, or a second frontend application.
+
+## What Makes Plum Different
+
+- It is Rails infrastructure, not a remote content service.
+- It works both as a mountable engine and as the center of a standalone site.
+- It lets editorial content and host application data participate in the same
+  rendering context.
+- It follows the Rails approach: strong conventions, ordinary Ruby extension
+  points, and ownership of the complete application.
+- It supports a low-operations SQLite path without limiting applications that
+  need PostgreSQL.
+- It treats themes, content, assets, backups, and deployments as portable parts
+  of a site rather than features of a vendor account.
+
+## The Long-Term Goal
+
+When a Rails developer asks, "How do I let someone edit this content?", Plum
+should be the obvious answer.
+
+Plum succeeds when it becomes normal to:
+
+- mount Plum in a Rails product;
+- start a client content site with Plum;
+- publish and share Plum themes and blocks;
+- run a collection of independent Plum sites economically; and
+- extend content workflows with familiar Rails code.
+
+The goal is not to reproduce every feature of every CMS. The goal is to make
+content management feel like it has always belonged in Rails.

data/lib/plum/engine.rb

@@ -8,7 +8,9 @@ module Plum
 
     initializer "plum.assets" do |app|
       app.config.assets.paths << root.join("app/assets/javascripts")
-      app.config.assets.paths << root.join("app/javascript/controllers/plum")
+      # Importmap exposes these files as `plum/*`, so Propshaft must resolve
+      # them relative to the parent controllers directory.
+      app.config.assets.paths << root.join("app/javascript/controllers")
       app.config.assets.paths << root.join("vendor/javascript")
 
       lexxy_spec = Gem.loaded_specs["lexxy"]

data/lib/plum/version.rb

@@ -1,6 +1,6 @@
 module Plum
   module Version
-    STRING = "0.1.2"
+    STRING = "0.2.1"
   end
 
   VERSION = Version::STRING

data/lib/plum.rb

@@ -6,6 +6,10 @@ module Plum
   def self.table_name_prefix
     "plum_"
   end
+
+  def self.register_field_type(**options)
+    FieldTypeRegistry.register(**options)
+  end
 end
 
 require_relative "plum/engine" if defined?(Rails::Engine)

data/lib/tasks/plum_portability.rake

@@ -0,0 +1,37 @@
+namespace :plum do
+  namespace :site do
+    desc "Export a complete Plum site archive (SITE_ID or first site; ARCHIVE required)"
+    task export: :environment do
+      path = ENV.fetch("ARCHIVE") { abort "ARCHIVE is required" }
+      site = ENV["SITE_ID"].present? ? Plum::Site.find(ENV["SITE_ID"]) : Plum::Site.first
+      abort "No Plum site exists" unless site
+
+      archive = Plum::SiteArchive.dump(site: site, path: path)
+      puts "Exported #{site.name} to #{archive}"
+    end
+
+    desc "Import a Plum site archive as a new site (ARCHIVE required; NAME and DOMAIN optional)"
+    task import: :environment do
+      path = ENV.fetch("ARCHIVE") { abort "ARCHIVE is required" }
+      site = Plum::SiteArchive.load(path: path, name: ENV["NAME"], domain: ENV["DOMAIN"])
+      puts "Imported #{site.name} as site #{site.id}"
+    end
+  end
+
+  namespace :backup do
+    desc "Create a timestamped Plum site backup (SITE_ID optional; DIRECTORY defaults to backups/plum)"
+    task create: :environment do
+      site = ENV["SITE_ID"].present? ? Plum::Site.find(ENV["SITE_ID"]) : Plum::Site.first
+      abort "No Plum site exists" unless site
+      directory = Rails.root.join(ENV.fetch("DIRECTORY", "backups/plum"))
+      filename = "plum-site-#{site.id}-#{Time.current.utc.strftime('%Y%m%d%H%M%S')}.plum.zip"
+      archive = Plum::SiteArchive.dump(site: site, path: directory.join(filename))
+      puts "Backed up #{site.name} to #{archive}"
+    end
+
+    desc "Restore a Plum backup as a new site (ARCHIVE required; NAME and DOMAIN optional)"
+    task restore: :environment do
+      Rake::Task["plum:site:import"].invoke
+    end
+  end
+end

data/lib/tasks/plum_styles.rake

@@ -0,0 +1,12 @@
+require "fileutils"
+
+namespace :plum do
+  desc "Build Tailwind and copy the result into Plum's packaged stylesheet"
+  task build_styles: :environment do
+    system(Rails.root.join("bin/rails").to_s, "tailwindcss:build", exception: true)
+    source = Rails.root.join("app/assets/builds/tailwind.css")
+    destination = Rails.root.join("app/assets/stylesheets/plum/control_panel.css")
+    FileUtils.cp(source, destination)
+    puts "Packaged #{destination.relative_path_from(Rails.root)}"
+  end
+end