plum-cms 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9daf7a444c4aca840d3395ef9e290708192a904b8d7effa9aa0954819ab3a046
-  data.tar.gz: 5987aaecba9e612f37eae6cebb8ad663fcd39fc0add1342762836339bbaf5a3c
+  metadata.gz: a62b9b90b91530846a18cac552fcc7ee10cafcd67ef23ea135d12ff0d175f7e9
+  data.tar.gz: 7eada3af7d1000b9dbd526b3b7eab29af60de2790fad7cb7d5ddcb56146c8a68
 SHA512:
-  metadata.gz: f7718730fa5d92db2a89d1ef13724d2a7cb0198322ff0bb239982390f4af3125747d3261ca1a61161da64d3dd45119a37d2396181dd7631d3193294428491781
-  data.tar.gz: 9ddd57edac63fc212ac7ddfd20f3616551f84a437c72496b31d3f86d30fafdd4ac002454fd14a66e7bbe9faea6d274274e7fd69642790ded89bc29fe39c7596d
+  metadata.gz: f038e184d32a8fb9bb1c0449b7f67328d895f2974e0e71fd7e88d5b0f24be5329ad9c348d9d86e9115d0415507fb9366ac3988d121894691d23741d036e96ee7
+  data.tar.gz: eb22b20f634d5ff40d715c53c0c07d31109785305ed27dd6989fd44e923b89a6509efc4ff7289bb9aacf0788c008301c747cf088a888381510af9678e8bb8b04

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## Unreleased
+
+- `plum deploy`'s health wait no longer requires a Dockerfile HEALTHCHECK:
+  images without one are probed via HTTP /up through the proxy instead
+  (resolved to loopback so SNI routing matches).
+- Added `plum promote`: go-live for a preview, in place. The preview app
+  is re-homed onto the production domain via `once update --host` — same
+  container, same database, all content built during the preview — with
+  TLS provisioned on the spot. Preflights preview existence, hostname
+  collisions, and DNS. Verified live: a hostname re-home round-trip on a
+  running app served on the new domain within seconds, data intact.
+- Added `plum deploy --preview` — the agency preview workflow: ship the
+  same image as a separate Once app under a preview hostname, shareable
+  with a client before their domain points anywhere. Uses `preview_host:`
+  from plum.yml (wildcard-record agency domains) or auto-derives
+  `<app>.<server-ip>.sslip.io` with zero DNS setup. Previews are
+  independent apps: they never touch the live site, and going live later
+  is a plain `plum deploy`.
+- `plum deploy` now preflights DNS on first deploys: Once verifies
+  https://<hostname> as its final step and rolls the app back when the
+  domain doesn't reach the server, so the CLI checks A records against
+  the server's addresses before building anything and asks before
+  proceeding (proxied DNS like Cloudflare legitimately mismatches, hence
+  a confirm rather than a refusal).
+- Fixed the install generator mounting Plum ABOVE the app's own routes:
+  Rails' `route` helper prepends, so an at-"/" mount shadowed everything
+  below it — including `get "up"`, the health check that load balancers
+  and deploy tooling (Once, kamal-proxy, plum deploy) probe, which made
+  freshly scaffolded sites fail health checks with Plum's 404 page. The
+  mount is now appended at the bottom of routes.rb with a comment
+  explaining why it must stay last. Found by the first real `plum new` →
+  `plum deploy` run.
+
+- Fixed `plum connect` in a directory with no plum.yml silently targeting
+  the globally active project (running it from a fresh repo could show —
+  or with --reconfigure, rewrite — a different project's connection).
+  Connect now always means "set up the current directory"; only an
+  explicit `--project NAME` redirects it.
+- Connect now finishes the journey: when the once app isn't deployed yet
+  it offers to build and ship right there (chains into plum deploy), and
+  connecting a project always makes it the active one — working in a
+  directory means that's the project you're "in". A brand-new site's app
+  question also now defaults to "a new app on this server (type its
+  hostname)" instead of pre-selecting an already-deployed app, which
+  would have silently pointed the repo at another site's container.
+- Untangled project vs. remote in connect's wording: the wizard now asks
+  for an "Environment name" (production, staging — plum.yml's remotes)
+  with a line explaining the concept, and the closing hint no longer
+  prints the nonsensical `plum pull --project production` — it points at
+  `plum pull` from the directory, or `--project <site>` from anywhere.
+  Terminology now spelled out in docs/plum-cli.md: projects are sites,
+  remotes are environments.
+- Connect's server pick-list now knows every stored server, not just the
+  plum-* SSH aliases: hosts from every registered project's remotes are
+  merged in (annotated "— used by <project>"), so a server appears even
+  when its alias offer was declined.
+- Added `plum new NAME`: scaffold a deploy-ready Plum site in one command
+  — rails new, the plum-cms gem, the install generator mounted at `/`, a
+  prepared database, and a git history. Bootstraps its own toolchain:
+  missing Ruby or Rails are offered for install (mise → ruby → rails),
+  each step confirm-gated. Refuses clearly when run inside an existing
+  Rails app, and registers the new project in the global registry.
+- Added `plum deploy [remote]`: registry-free deploys — build the image
+  locally for linux/amd64, stream it to the server over SSH
+  (docker save | docker load; no registry, no CI, no accounts), roll the
+  Once app to it, and wait for the container health check. Auto-update is
+  disabled for these apps: deploys are explicit, never by surprise.
+- Added docs/zero-to-agency.md and a matching tutorial chapter: empty
+  directory → client sites on a $6 DigitalOcean droplet with `plum new`,
+  `plum connect`, `plum deploy`, and the pull/push/backup rhythm.
+
 ## 0.2.2 — 2026-08-13
 
 ### Fixed

data/README.md

@@ -251,7 +251,9 @@ ergonomics for self-hosted Plum sites:
 
 ```sh
 plum tutorial              # interactive guided tour, right in the terminal
+plum new client-site       # scaffold a deploy-ready site (installs Rails if needed)
 plum connect 203.0.113.5   # guided setup: SSH keys, server tooling, plum.yml
+plum deploy                # build locally, ship over SSH — no registry, no CI
 plum connect               # already configured? verifies the setup instead
 plum pull                  # replace your local site with production's content
 plum push                  # apply plum/ config-as-code files to the remote
@@ -265,7 +267,9 @@ A Firebase-style project registry (`plum use`, `--project`) manages a fleet
 of sites from one machine. Every command degrades to plain, script-friendly
 output when piped or under `NO_COLOR`. See [the CLI guide](docs/plum-cli.md)
 for transports (`via: ssh|kamal|once`), fleet management, and how `pull`
-works across database engines.
+works across database engines — and [the zero-to-agency
+guide](docs/zero-to-agency.md) for running client sites on a single
+cheap VPS with no registry, CI, or PaaS.
 
 ## Content API
 

data/app/views/layouts/plum/cp.html.erb

@@ -8,7 +8,7 @@
   <%= favicon_link_tag "plum-mark.svg", type: "image/svg+xml" %>
   <%= stylesheet_link_tag "plum/control_panel", "data-turbo-track": "reload" %>
   <%= stylesheet_link_tag "lexxy", "data-turbo-track": "reload" %>
-  <%= javascript_importmap_tags %>
+  <%= javascript_importmap_tags(importmap: Plum.importmap || Rails.application.importmap) %>
   <script type="module">import "plum/application"</script>
   <style>
     :root {

data/app/views/layouts/plum/session.html.erb

@@ -7,7 +7,7 @@
   <%= csp_meta_tag %>
   <%= favicon_link_tag "plum-mark.svg", type: "image/svg+xml" %>
   <%= stylesheet_link_tag "plum/control_panel", "data-turbo-track": "reload" %>
-  <%= javascript_importmap_tags %>
+  <%= javascript_importmap_tags(importmap: Plum.importmap || Rails.application.importmap) %>
   <style>
     :root { --plum-accent: <%= Plum.configuration.cp_accent_color %>; }
     .bg-purple-600 { background-color: var(--plum-accent) !important; }

data/app/views/layouts/plum/write.html.erb

@@ -8,7 +8,7 @@
   <%= favicon_link_tag "plum-mark.svg", type: "image/svg+xml" %>
   <%= stylesheet_link_tag "plum/control_panel", "data-turbo-track": "reload" %>
   <%= stylesheet_link_tag "lexxy", "data-turbo-track": "reload" %>
-  <%= javascript_importmap_tags %>
+  <%= javascript_importmap_tags(importmap: Plum.importmap || Rails.application.importmap) %>
   <script type="module">import "plum/application"</script>
   <style>
     :root { --plum-accent: <%= Plum.configuration.cp_accent_color %>; }

data/docs/plum-cli.md

@@ -84,12 +84,78 @@ accepted since the content is public. The host key persists at
 `~/.config/plum/tutorial_host_ed25519` so returning visitors don't get
 host-key warnings.
 
+## plum new — zero to running site
+
+```
+plum new client-site
+```
+
+Scaffolds a deploy-ready Plum site: `rails new`, the plum-cms gem, the
+install generator mounted at `/`, a prepared database, and a git history.
+It bootstraps its own toolchain the way connect bootstraps a server — no
+Ruby? It offers to install mise, then Ruby, then Rails, each step
+confirm-gated. It also refuses (clearly) to run inside an existing Rails
+app, and registers the new project in the global registry.
+
+## plum deploy — no registry, no CI
+
+```
+plum deploy [remote]
+```
+
+Ships the site with nothing but local Docker and SSH: builds the image
+locally (`--platform linux/amd64`), streams it to the server through the
+SSH connection (`docker save | gzip | ssh docker load` — no registry
+account anywhere), then has Once roll the app to it (`once update
+--image`, or `once deploy --host <once_app>` on first deploy) and waits
+for the container's health check to go green. Auto-update is switched
+off for these apps: there's no registry to poll, so the site changes
+when you deploy it — never by surprise. Currently `via: once` remotes.
+
+```
+plum deploy --preview
+```
+
+Ships the same image as a **separate Once app under a preview hostname** —
+the agency workflow: share the work-in-progress with a client before
+their domain points anywhere. With `preview_host:` set on the remote in
+plum.yml (e.g. `client.preview.your-agency.com` behind a wildcard A
+record) you get clean branded preview URLs; with nothing configured it
+auto-derives `<app>.<server-ip>.sslip.io` — magic wildcard DNS that
+resolves to your server with zero setup. Preview and production are
+independent apps, so previews never touch a live site.
+
+```
+plum promote [remote]
+```
+
+Go-live for a preview, in place: re-homes the preview app onto the
+production domain (`once update --host`) — same container, same
+database, all the content built during the preview — with TLS
+provisioned on the spot. Preflights that a preview exists, that the
+production hostname isn't already a separate app, and that DNS reaches
+the server (confirm to override for proxied DNS).
+
+The full story — one droplet, several client sites, honest costs — is
+[the zero-to-agency guide](zero-to-agency.md).
+
 ## Two layers of configuration
 
 This mirrors the Firebase CLI's model deliberately, because it solves the
 same two problems: "how does this directory reach its server" and "how do I
 work with a project without cd-ing into its directory first."
 
+Two words, two meanings — keep them straight:
+
+- A **project** is a site: `the-final-word`, `client-site`. That's what
+  the registry, `plum use`, and `--project NAME` refer to.
+- A **remote** is one *environment* of a site: `production`, `staging`.
+  That's the positional argument on commands — `plum pull production`,
+  `plum logs staging` — and the keys under `remotes:` in plum.yml.
+
+So `plum pull --project client-site staging` means "the staging
+environment of the client-site project."
+
 1. **`plum.yml`** — lives in a site's own repo, defines its **remotes**
    (servers). This is the source of truth for how to reach that one site.
 2. **The global project registry** (`~/.config/plum/config.yml`, or

data/docs/zero-to-agency.md

@@ -0,0 +1,172 @@
+# Zero to Agency
+
+How to go from an empty directory to hosting client sites — with one
+cheap VPS, the `plum` CLI, and nothing else. No GitHub required, no
+container registry, no CI pipeline, no platform-as-a-service bill. Your
+laptop builds, your server runs, SSH connects them.
+
+The stack under the hood: Rails + Plum in a Docker container, managed by
+[Once](https://once.com) (37signals' single-container deploy tool) behind
+its bundled TLS-terminating proxy, on any Linux box. The examples use
+DigitalOcean; any VPS provider works the same way.
+
+## What you need
+
+- A [DigitalOcean](https://digitalocean.com) account (or any VPS provider)
+- Docker on your laptop (Docker Desktop or Docker Engine) — `plum deploy`
+  builds images locally
+- The `plum` CLI
+- Ruby and Rails — and if you don't have them, `plum new` offers to
+  install both for you (via [mise](https://mise.jdx.dev))
+
+## 1. Create the server
+
+In DigitalOcean: **Create → Droplet**. Ubuntu LTS, the $6/month size is
+enough to start (pick $12 for headroom). Add your SSH key if you have one
+— if you don't, that's fine: `plum connect` will generate one and offer
+to copy it over with the root password DigitalOcean emails you. Note the
+droplet's IP.
+
+That's the last time you touch a cloud dashboard.
+
+## 2. Create the site
+
+```bash
+plum new client-site
+cd client-site
+bin/rails server
+```
+
+You have a running Plum site at `http://localhost:3000` — the control
+panel is at `/cp`. Build the client's theme in `app/themes/`, model
+their content types in the CP (or as YAML in `plum/` — see
+`docs/config-as-code.md`), and load in their content.
+
+## 3. Connect the server
+
+```bash
+plum connect 203.0.113.5      # your droplet's IP
+```
+
+The wizard handles the entire first-contact ritual: SSH keys, passwordless
+login, detecting that this is a Once-shaped app, and — on a fresh droplet —
+**installing Docker Engine and Once for you** (each with your
+confirmation). When it asks for the app hostname, give it the client's
+real domain (`clientname.com`): that's how the server routes requests and
+provisions TLS.
+
+## 4. Point DNS
+
+At the client's DNS: an **A record** for their domain (and `www`) to the
+droplet's IP. **This must happen before the first deploy** — Once
+verifies `https://<domain>` end-to-end as the final step of a first
+deploy and rolls back if the domain doesn't reach the server yet
+(`plum deploy` checks this up front and warns you). Proxied DNS
+(Cloudflare in Full strict mode) is fine.
+
+Building ahead of a domain cutover? That's what previews are for:
+
+```bash
+plum deploy --preview
+```
+
+This ships the site as a *separate* Once app under a preview hostname —
+by default `<app>.<server-ip>.sslip.io`, magic wildcard DNS that reaches
+your server with zero configuration, so you have a shareable client
+preview URL before any real DNS exists. For branded previews, point one
+wildcard record (`*.preview.your-agency.com`) at the droplet and set
+`preview_host: client.preview.your-agency.com` on the remote in
+plum.yml.
+
+Iterate on the preview as long as you like — build the content, tune the
+theme, let the client click around. Then, when they flip DNS to the
+droplet:
+
+```bash
+plum promote
+```
+
+The preview app *becomes* the site: same container, same database, every
+word of content you built during the preview — it simply starts answering
+to the real domain, with TLS provisioned on the spot. No rebuild, no
+content migration, no separate go-live deploy. (If the site should live
+on its own droplet instead, `plum connect` it there and `plum deploy` —
+site archives carry the content across.)
+
+## 5. Deploy
+
+```bash
+plum deploy
+```
+
+Watch it go: the image builds on your laptop, streams to the server over
+SSH (`docker save | docker load` — this is why no registry account
+exists in this guide), Once starts it behind the proxy, and the CLI waits
+for the container to report healthy. `https://clientname.com` is live.
+
+Deploys are explicit — the site changes when you run `plum deploy`,
+never by surprise. Ship again any time with the same command.
+
+## 6. The agency rhythm
+
+Day-to-day, the CLI is your relationship with every client site:
+
+```bash
+plum pull                # production content → your laptop, any DB engine
+plum push                # content-model changes (plum/ YAML) → production
+plum check               # did anyone drift the model? (CI-friendly)
+plum logs --follow       # heroku-style tail, prettified
+plum backup              # timestamped archive on the server
+plum run -- TASK         # any rake task, any remote
+```
+
+Content pulls down, structure pushes up. Clients edit in `/cp` on
+production; you develop locally against a full copy of their real
+content. Turn on **static caching** (`docs/static-caching.md`) and the
+site serves rendered pages from disk — SQLite happily runs a
+production site on the smallest droplet, because cached reads never
+touch the database at all.
+
+## 7. The second client
+
+This is where it becomes an agency:
+
+```bash
+plum new second-client
+cd second-client
+plum connect             # the host prompt offers your existing server
+plum deploy
+```
+
+Once runs each site in its own container on the same box, routing by
+hostname, each with its own TLS certificate. A $6–12 droplet comfortably
+hosts several small client sites; each new client is marginal-cost-zero
+until the box runs hot. Manage the fleet from anywhere:
+
+```bash
+plum projects list       # every site you run
+plum use second-client   # switch the active project
+plum pull --project client-site   # or target one explicitly
+```
+
+## 8. When you outgrow one box
+
+- **More sites than one droplet likes**: create a second droplet,
+  `plum connect` the new sites there. The registry doesn't care how many
+  servers are behind it.
+- **A client needs Postgres** (heavy dynamic features): switch that app's
+  database and redeploy — `plum pull` still works across engines.
+- **Backups off the box**: `plum backup` writes archives on the server;
+  Once's auto-backup handles scheduling. Pull copies down with `plum pull`
+  or scp them to storage you control.
+
+## Costs, honestly
+
+| Thing | Cost |
+| --- | --- |
+| Droplet (several small sites) | $6–12/mo |
+| Domains | the client's problem |
+| Registry, CI, PaaS, per-seat CMS pricing | $0 — none exist in this setup |
+
+The whole model: you charge for design and content strategy; the
+infrastructure is a rounding error.

data/lib/generators/plum/install/install_generator.rb

@@ -30,7 +30,19 @@ module Plum
       def mount_engine
         return if options[:skip_route]
 
-        route %(mount Plum::Engine, at: "#{options[:mount_path]}")
+        # Mounted at "/", Plum serves every path the app doesn't claim — so
+        # it must come AFTER the app's own routes (notably `get "up"`, the
+        # health check load balancers and deploy tooling probe). Rails'
+        # `route` helper prepends, which would shadow them; append at the
+        # bottom of the block instead.
+        inject_into_file "config/routes.rb", before: /^end\s*\z/ do
+          <<~RUBY.indent(2)
+
+            # Plum last: mounted at #{options[:mount_path].inspect} it serves every path
+            # the app doesn't claim, so app routes (like /up) must come first.
+            mount Plum::Engine, at: #{options[:mount_path].inspect}
+          RUBY
+        end
       end
 
       def print_next_steps

data/lib/plum/engine.rb

@@ -30,10 +30,17 @@ module Plum
       end
     end
 
-    initializer "plum.importmap", before: "importmap" do |app|
-      if app.config.respond_to?(:importmap)
-        app.config.importmap.paths << root.join("config/plum_importmap.rb")
-      end
+    # Build a Plum-scoped importmap instead of merging Plum's pins into the
+    # host app's global importmap. Plum's layouts render this map (host JS stack
+    # + Plum's additions), while the host app's own pages keep a clean importmap
+    # free of Plum's controllers/lexxy/activestorage pins. Runs after the host's
+    # importmap is configured so we can copy its paths.
+    initializer "plum.importmap", after: "importmap" do |app|
+      next unless defined?(Importmap::Map) && app.config.respond_to?(:importmap)
+
+      Plum.importmap = Importmap::Map.new
+      Array(app.config.importmap.paths).each { |path| Plum.importmap.draw(path) }
+      Plum.importmap.draw(root.join("config/plum_importmap.rb"))
     end
   end
 end

data/lib/plum/version.rb

@@ -1,6 +1,6 @@
 module Plum
   module Version
-    STRING = "0.2.2"
+    STRING = "0.2.3"
   end
 
   VERSION = Version::STRING

data/lib/plum.rb

@@ -3,6 +3,13 @@ require_relative "plum/content_source"
 require_relative "plum/configuration"
 
 module Plum
+  class << self
+    # A Plum-scoped importmap (host pins + Plum's own pins), used only by Plum's
+    # layouts. Keeps Plum's controllers/lexxy/activestorage out of the host
+    # app's global importmap so a mounted Plum can't pollute the host's JS.
+    attr_accessor :importmap
+  end
+
   def self.table_name_prefix
     "plum_"
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plum-cms
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Ben Simmons
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt
@@ -180,16 +180,22 @@ dependencies:
   name: image_processing
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 description: Plum is a Rails-native CMS engine with Hotwire control panel, Liquid
   themes, and site-scoped content.
 email:
@@ -404,6 +410,7 @@ files:
 - docs/statamic-parity.md
 - docs/static-caching.md
 - docs/vision.md
+- docs/zero-to-agency.md
 - lib/generators/plum/install/install_generator.rb
 - lib/generators/plum/install/templates/plum_initializer.rb
 - lib/plum.rb