plum-cms 0.1.2 → 0.2.0

data/docs/blueprint-fields.md

@@ -0,0 +1,55 @@
+# Blueprint fields
+
+Plum stores a content type blueprint as JSON with a `fields` array. Field
+handles are stable template and storage keys: lowercase letters, numbers, and
+underscores, beginning with a letter.
+
+## Shared configuration
+
+Every data field accepts `handle`, `type`, `label`, `instructions`, `required`,
+`default`, `placeholder`, and `width`. Width is a grid span from 1 through 12.
+A `section` organizes the entry form but stores no value.
+
+`condition` controls visibility using another field:
+
+```json
+{ "field": "format", "operator": "equals", "value": "feature" }
+```
+
+Operators: `equals`, `not_equals`, `contains`, `empty`, and `not_empty`.
+
+## Type-specific configuration
+
+| Type | Configuration | Stored value |
+|---|---|---|
+| `text`, `textarea`, `rich_text`, `url`, `color` | Shared options | String |
+| `number` | `number_kind`, `min`, `max`, `step`, `unit` | Number |
+| `boolean` | Shared options | Boolean |
+| `date` | `date_mode`, `min`, `max` | ISO date/time string |
+| `select`, `radio`, `button_group` | `options` | Option value |
+| `checkboxes` | `options` | Option-value array |
+| `taxonomy` | `taxonomy` | Entry-term associations |
+| `image` | Optional `folder` | Asset ID |
+| `images` | `min_items`, `max_items` | Asset-ID array |
+| `relationship` | `content_type`, `multiple`, item limits | Entry ID or ID array |
+| `blocks` | Optional `blocks` allowlist | Block array |
+| `list` | `min_items`, `max_items`, `unique` | String array |
+| `group` | Nested `fields` | Object |
+| `repeater` | Nested `fields`, item limits | Object array |
+| `section` | Shared presentation options | Nothing |
+
+Options may be strings or `{ "label": "Human label", "value": "stable_value" }`
+objects. Existing string options remain supported.
+
+## Theme values
+
+Liquid receives expanded assets and relationships. An `image` becomes an asset
+object, `images` becomes an array of asset objects, and relationships become an
+entry object or ordered array. Stored IDs remain internal to the editor.
+
+## Compatibility policy
+
+Blueprint additions are backward compatible. Plum continues to read legacy
+string options and single-value relationship/image fields. Changing a field's
+type or handle is a content migration and should be performed in application
+code before deploying the new blueprint.

data/docs/extensions.md

@@ -0,0 +1,32 @@
+# Extending Plum
+
+Plum exposes Rails-native extension points for host applications and gems. An
+initializer can register a field type with its control-panel partial and value
+pipeline:
+
+```ruby
+Plum.register_field_type(
+  handle: :postal_code,
+  label: "Postal Code",
+  partial: "my_engine/fields/postal_code",
+  normalizer: ->(value:, **) { value.to_s.upcase.delete(" ") },
+  validator: ->(value:, **) { "is invalid" unless value.to_s.match?(/\A\d{5}\z/) },
+  expander: ->(value:, **) { { "value" => value, "country" => "US" } }
+)
+```
+
+The partial receives `field`, `field_handle`, `field_id`, `field_value`, and
+`entry`. Its submitted input must use `entry[data][HANDLE]`.
+
+The normalizer runs before persistence and receives `value`, `field`, `entry`,
+and `controller`. The validator runs on the normalized entry value and returns
+one message, multiple messages, or `nil`. The expander controls the value sent
+to Liquid and the JSON content API and receives `value`, `field`, `site`, and
+`expander`.
+
+Registration rejects invalid or duplicate handles. Custom types automatically
+appear in the visual blueprint type picker and participate in normal required,
+default, instruction, conditional-visibility, and field-width behavior.
+
+Plum also supports registered content sources and host-owned authorization; see
+the corresponding README sections for those APIs.

data/docs/product-principles.md

@@ -0,0 +1,73 @@
+# Product Principles
+
+These principles guide product and architectural decisions in Plum.
+
+## Rails Owns the Application
+
+The host application has the final say. Plum should integrate with its users,
+authorization, tenancy, models, jobs, mail, storage, routes, and deployment
+instead of creating parallel systems.
+
+## The First Useful Result Is Fast
+
+Installation must lead to an editable, published page in less than ten minutes.
+Defaults should be good enough to ship and understandable enough to replace.
+
+## The Escape Hatches Are Ruby
+
+When a project exceeds Plum's conventions, developers should extend it with
+ordinary Ruby, Rails configuration, models, controllers, helpers, and views.
+Plum should not require a proprietary plugin runtime.
+
+## Editors Do Not Need to Know Rails
+
+Developers define content structure and presentation. Editors should receive a
+clear, forgiving interface with preview, validation, history, and recovery.
+
+## Content Is Structured and Portable
+
+Content should be reusable across templates and exportable with its schema and
+assets. A site owner must be able to leave without scraping rendered HTML or
+depending on a Plum service.
+
+## One Stack Is a Feature
+
+Plum should not require Node services, a remote CMS database, webhooks, API
+tokens, or a separate frontend. Optional integrations may add capability, but
+the complete product must work as a conventional Rails application.
+
+## SQLite Is a First-Class Production Path
+
+Small content sites should run reliably with SQLite and persistent storage.
+Plum must also remain database-agnostic for embedded and higher-scale uses.
+
+## Sites Are Operationally Independent
+
+For agency work, one client site should be one portable application, container,
+database, and backup unit. For SaaS products, site scoping should support many
+tenants inside one host application. Plum should document both patterns rather
+than forcing one onto the other.
+
+## Deployment Tools Have Clear Boundaries
+
+Plum creates and manages content applications. A Plum CLI may scaffold, inspect,
+export, import, upgrade, and package them. ONCE, Kamal, and other deployment
+tools operate the resulting containers and servers. Plum should integrate
+cleanly without becoming an infrastructure orchestrator.
+
+## Documentation Is Part of the Product
+
+Every public capability needs an example and a clear contract. If a feature is
+difficult to explain, its design is not finished.
+
+## Dogfood Without Special Cases
+
+The Plum marketing and documentation site must run on the public product. Any
+general improvement it needs belongs in Plum; site-specific behavior belongs in
+the site's application or theme.
+
+## Prefer Coherence Over Feature Count
+
+Plum should excel at the everyday path from modeling content to publishing a
+site. Features that strengthen installation, authoring confidence, portability,
+and Rails integration take priority over breadth for its own sake.

data/docs/roadmap.md

@@ -0,0 +1,98 @@
+# Roadmap
+
+Plum's roadmap is organized by outcomes rather than promised dates. Items move
+as the product is exercised in real applications and the Rails community gives
+feedback.
+
+## Now: Make Plum Real and Adoptable
+
+The current milestone is to build and publish the Plum marketing and
+documentation site as a standalone Rails application powered by Plum and
+SQLite.
+
+### Product foundation
+
+- Publish a clear vision, product principles, and supported use cases.
+- Build `plumcms.org` with Plum as an external dependency.
+- Define a portable production layout for the SQLite database, uploaded assets,
+  and mutable site data.
+- Package the site as an ONCE-compatible Docker application.
+- Exercise installation, initialization, health checks, upgrades, backup, and
+  restore on a real VM.
+- Keep SQLite and PostgreSQL verification in CI.
+
+### Documentation
+
+- Document installation and the first editable page.
+- Document sites, content types, fields, entries, and publishing.
+- Document blocks, assets, relationships, taxonomies, navigation, globals, and
+  forms.
+- Document Liquid themes and host content sources.
+- Document embedded authentication, authorization, tenancy, and routing.
+- Document standalone SQLite and embedded PostgreSQL deployments.
+- Publish configuration, troubleshooting, and upgrade references.
+
+### Distribution
+
+- Publish the `plum` gem.
+- State supported Ruby and Rails versions.
+- Establish semantic versioning and an upgrade policy.
+- Test fresh external installations and upgrades in CI.
+- Provide a production-ready container contract and example application.
+
+## Next: Editorial Confidence and Portability
+
+Once the public site proves the basic workflow, focus on the features editors
+and agencies need to trust Plum in production.
+
+- Draft preview.
+- Revisions and rollback.
+- Scheduled publishing.
+- Multi-entry relationships.
+- Reusable blocks and sections.
+- Content, schema, and asset export/import.
+- Document hierarchy, tables of contents, and site search.
+- SEO metadata, canonical URLs, sitemaps, feeds, and redirect management.
+- Stronger asset organization and image editing.
+- Form spam protection and improved submission workflows.
+- Tested backup and restore commands.
+
+## Later: The Rails Content Ecosystem
+
+After installation and production operation are dependable, make Plum easier to
+adopt repeatedly and extend publicly.
+
+- A thin `plum` CLI for new sites, diagnostics, themes, export/import, upgrades,
+  and packaging.
+- Starter applications for common content-site use cases.
+- A documented extension contract for fields, blocks, and content sources.
+- A collection of high-quality open themes and blocks.
+- Theme scaffolding, validation, packaging, and distribution tools.
+- Importers for common CMS and structured-data formats.
+- Optional content APIs for applications that genuinely need them.
+- Community examples, case studies, talks, and contribution programs.
+
+## 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 currently trying to become a general-purpose admin framework, a
+freeform visual design tool, an ecommerce platform, or a hosted headless CMS.
+Those products solve different problems. 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/version.rb

@@ -1,6 +1,6 @@
 module Plum
   module Version
-    STRING = "0.1.2"
+    STRING = "0.2.0"
   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_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