monkrb 0.20.0 → 0.21.0

data/lib/monk/templates/base/test/test_helper.rb

@@ -0,0 +1,18 @@
+ENV["MONK_ENV"] ||= "test"
+
+# The test values the modules this app uses wrote (.env.test), loaded
+# before config/settings.rb's .env, which doesn't override them. Only the
+# database name and MONK_ENV differ from development, and they're two
+# separate settings: MONK_ENV=test alone doesn't change DB_NAME.
+env_test = File.expand_path("../.env.test", __dir__)
+if File.exist?(env_test)
+  require "dotenv"
+  Dotenv.load(env_test)
+end
+
+require "minitest/autorun"
+require_relative "../config/load"
+require_relative "../app/app"
+
+# Booted once, as config.ru does: request tests call APP.
+APP = Monk.boot(App)

data/lib/monk/templates/jobs/agents.md

@@ -0,0 +1,25 @@
+## jobs
+
+**Where:** `config/jobs.rb` (the queue lives in the `:primary` database),
+job classes in `app/jobs/`, `bin/jobs` runs them.
+
+**Main calls:** `class SendInvoice < Monk::Job` with
+`def self.perform(id)`; `SendInvoice.enqueue(id)`, `wait: 300`, `at: time`,
+or `conn: conn` to enqueue inside your own transaction. Class settings:
+`queue "mailers"`, `max_attempts 5`, `never_retry SomeError`. With mail:
+`Monk::Mail.deliver_later(...)`; with auth:
+`Monk::Auth::SendLoginLink.enqueue(email)`.
+
+**Test:** `test/jobs_test.rb`. In tests, `Monk::Jobs.drain!` runs every
+enqueued job right away, each in a Ractor; `Monk::Jobs.clear!` in
+`teardown` empties the queue.
+
+**Pitfalls:**
+- A job's arguments are stored as JSON: pass ids and plain values, never
+  records or objects.
+- A job may run more than once (its process was killed mid-job): make it
+  safe to repeat.
+- Jobs run in Ractors: the same shareability rules as routes.
+
+**Examples:** `jobs-enqueue` in `app/routes/jobs.rb`; `app/jobs/hello_job.rb`
+is a real, deletable demo job.

data/lib/monk/templates/jobs/app/routes/jobs.rb

@@ -0,0 +1,9 @@
+# Routes that hand work to bin/jobs (monk add jobs).
+#
+# monk:example jobs-enqueue -- a route enqueueing the demo job (app/jobs/hello_job.rb).
+# # bin/jobs runs it, and its line lands in log/development.log:
+# #   curl -X POST "http://localhost:9292/jobs/hello?name=Ann"
+# class App
+#   post("/jobs/hello") { json(enqueued: HelloJob.enqueue(params[:name] || "world")) }
+# end
+# monk:end

data/lib/monk/templates/jobs/bin/jobs

@@ -1,18 +1,24 @@
 #!/usr/bin/env ruby
 require "bundler/setup"
-# The configs and app/, as the web process loads them, so a job can use
-# the app's models and mailers, send mail, or push a Live update --
-# config/load.rb, never Monk.boot: this process serves no routes.
-require_relative "../config/load"
-require "monk/jobs/runtime"
+# A service that's down, a missing database or setting ends this script
+# with what to fix (SETUP.md's commands), not a backtrace.
+require "monk/bin"
 
-# The app's templates, so a job can render one (a mail's HTML part, say):
-# there's no App class here to point Monk::Views at them.
-Monk::Views.root = File.expand_path("../app/views", __dir__)
+Monk::Bin.run(__FILE__) do
+  # The configs and app/, as the web process loads them, so a job can use
+  # the app's models and mailers, send mail, or push a Live update --
+  # config/load.rb, never Monk.boot: this process serves no routes.
+  require_relative "../config/load"
+  require "monk/jobs/runtime"
 
-workers = Integer(ENV.fetch("JOBS_WORKERS", "5"))
-queues = ENV.fetch("JOBS_QUEUES", "default").split(",").map(&:strip)
-puts "Monk::Jobs: #{workers} worker(s) on #{queues.join(", ")} -- TERM or Ctrl-C finishes the jobs in hand and stops"
-$stdout.flush
+  # The app's templates, so a job can render one (a mail's HTML part, say):
+  # there's no App class here to point Monk::Views at them.
+  Monk::Views.root = File.expand_path("../app/views", __dir__)
 
-Monk::Jobs::Runtime.new(workers: workers, queues: queues).run
+  workers = Integer(ENV.fetch("JOBS_WORKERS", "5"))
+  queues = ENV.fetch("JOBS_QUEUES", "mailers,default").split(",").map(&:strip)
+  puts "Monk::Jobs: #{workers} worker(s) on #{queues.join(", ")} -- TERM or Ctrl-C finishes the jobs in hand and stops"
+  $stdout.flush
+
+  Monk::Jobs::Runtime.new(workers: workers, queues: queues).run
+end

data/lib/monk/templates/jobs/setup.md

@@ -0,0 +1,30 @@
+## jobs
+
+Background jobs on the app's own Postgres. A migration creates the queue's
+tables: run `bin/setup_db` and `DB_NAME={{app}}_test bin/setup_db`
+(postgres, above).
+
+### Run them
+
+`bin/jobs` is the process that runs jobs, next to `bin/server`:
+
+```bash
+bin/jobs
+```
+
+`JOBS_WORKERS` (in `.env`) is how many jobs run at once, and `JOBS_QUEUES`
+which queues it takes them from, in order: `mailers,default` serves mail
+first. `TERM` or Ctrl-C lets the jobs in hand finish before it exits. In
+production it's one more process from the same image, with `bin/jobs` as
+its command.
+
+### Check it works
+
+1. `bundle exec rake test` runs `test/jobs_test.rb`, which enqueues the
+   demo job (`app/jobs/hello_job.rb`) and runs it.
+2. By hand, with `bin/jobs` running: in `bin/console`,
+   `HelloJob.enqueue("Ann")`, and `log/development.log` shows
+   `Hello, Ann, from a background job`.
+3. The example: uncomment the `jobs-enqueue` block in `app/routes/jobs.rb`,
+   restart `bin/server`, and
+   `curl -X POST "http://localhost:9292/jobs/hello?name=Bob"`.

data/lib/monk/templates/jobs/test/jobs_test.rb

@@ -0,0 +1,16 @@
+require_relative "test_helper"
+
+# A job enqueued in the app's database runs: Monk::Jobs.drain! runs every
+# enqueued job right here, each in its own Ractor as bin/jobs would, so a
+# job that only works outside one fails here too. SETUP.md, jobs.
+class JobsTest < Minitest::Test
+  def teardown
+    Monk::Jobs.clear!
+  end
+
+  def test_the_demo_job_runs
+    HelloJob.enqueue("test")
+
+    assert_equal 1, Monk::Jobs.drain!
+  end
+end

data/lib/monk/templates/live/agents.md

@@ -0,0 +1,25 @@
+## live
+
+**Where:** `config/live.rb` (subscribe rules, `live_ws_url`), broadcasts in
+`app/broadcasts/`, the partials they push in `app/views/` (e.g.
+`app/views/live/`), the routes calling them in `app/routes/`.
+
+**Main calls:** in a view, `<div <%= live_topic "topic" %>>`; from a route,
+job or broadcast, `Monk::Live.patch(topic, to: "#id", partial: "live/_x",
+**locals)`, also `append`, `prepend`, `remove(topic, to:)`, `batch`. Rules:
+`Monk::Live.authorize("contacts:*") { |subject, topic| ... }` with a block
+built in a module, `anonymous: true` to let visitors in.
+
+**Test:** `test/live_test.rb` publishes and checks a subscribed socket gets
+it. To test a page, render it and look for `data-live-topic`.
+
+**Pitfalls:**
+- Nothing can be subscribed to until a rule in `config/live.rb` allows it;
+  rules are checked in `bin/websocket_server`, which never loads `app/`.
+- A pushed partial sees only its locals (`locals[:text]`), never `params`
+  or the session.
+- Each topic name must match what pages subscribe to, exactly.
+- The demo (`/demo/live`) is development only; delete it when done.
+
+**Examples:** `live-rule` in `config/live.rb`; `live-broadcast` in
+`app/broadcasts/greeting.rb` and `app/routes/live.rb`.

data/lib/monk/templates/live/app/broadcasts/greeting.rb

@@ -0,0 +1,13 @@
+# What this app pushes to open pages (monk add live).
+#
+# monk:example live-broadcast -- a greeting that changes in every open page at once.
+# # A page shows it in an element subscribed to the topic (and a rule in
+# # config/live.rb lets pages subscribe to "greeting"):
+# #   <p <%= live_topic "greeting" %>><%= render "live/_greeting", text: "Hello", layout: false %></p>
+# # The route that changes it is in app/routes/live.rb.
+# module GreetingBroadcast
+#   def self.update(text)
+#     Monk::Live.patch("greeting", to: "#greeting", partial: "live/_greeting", text: text)
+#   end
+# end
+# monk:end

data/lib/monk/templates/live/app/routes/demo_live.rb

@@ -0,0 +1,21 @@
+# monk:demo live -- Monk::Live's demo, development only: a counter whose
+# open tabs update together. Open http://localhost:9292/demo/live in two
+# tabs and press the button in one. To remove it, delete this file,
+# app/views/demo/, and the `monk:demo live` lines in config/live.rb.
+if Monk.env.development?
+  class App
+    # State shared across requests lives in a StateRactor; the update block
+    # is built here, where self is shareable, not inline in the route.
+    demo_hits = Monk::StateRactor.new(0)
+    demo_increment = Ractor.make_shareable(proc { |n| n + 1 })
+
+    get("/demo/live") { @title = "Monk::Live demo"; render "demo/live", hits: demo_hits.value }
+
+    # Change state, then tell every open page that shows it. Monk::Live.patch
+    # renders the partial once and pushes it to the topic's subscribers.
+    post("/demo/live/hit") do
+      Monk::Live.patch("demo:hits", to: "#hits", partial: "demo/_hits", hits: demo_hits.update(&demo_increment))
+      redirect "/demo/live"
+    end
+  end
+end

data/lib/monk/templates/live/app/routes/live.rb

@@ -0,0 +1,10 @@
+# Routes that push updates to open pages (monk add live).
+#
+# monk:example live-broadcast -- the route changing the greeting (app/broadcasts/greeting.rb).
+# class App
+#   post("/greeting") do
+#     GreetingBroadcast.update(params[:text].to_s)
+#     json(updated: true)
+#   end
+# end
+# monk:end

data/lib/monk/templates/live/app/views/demo/live.erb

@@ -0,0 +1,18 @@
+<h1>Monk::Live demo</h1>
+<p>
+  Open this page in two tabs and press the button in one: the counter in the
+  other updates by itself. The server pushes the new HTML over a WebSocket;
+  there is no polling and no page JavaScript of your own.
+</p>
+
+<%# live_topic makes this element's page subscribe to the "demo:hits" topic. %>
+<p <%= live_topic "demo:hits" %>>Hits so far: <%= render "demo/_hits", hits: locals[:hits], layout: false %></p>
+
+<form method="post" action="/demo/live/hit"><button>+1</button></form>
+
+<p>
+  The pieces: <code>live_topic</code> in this view, the partial
+  <code>app/views/demo/_hits.erb</code>, <code>Monk::Live.patch</code> in
+  <code>POST /demo/live/hit</code> (<code>app/routes/demo_live.rb</code>), and
+  the subscribe rule in <code>config/live.rb</code>.
+</p>

data/lib/monk/templates/live/app/views/live/_greeting.erb

@@ -0,0 +1 @@
+<span id="greeting"><%= locals[:text] %></span>

data/lib/monk/templates/live/config/live.rb

@@ -1,47 +1,45 @@
-# Monk::Live wiring, required by both processes: config/load.rb (this app
-# publishes updates, e.g. from a route) and bin/websocket_server (the browsers'
-# sockets terminate there and are handed the updates).
-#
-# They are separate processes, so Redis is what carries a publish from one to
-# the other -- REDIS_URL (set in .env by `monk new --live`) is required.
-require_relative "settings"
+require "monk"
 require "monk/live"
-require "monk/websocket/redis_fanout"
+require_relative "websocket"
+
+# Monk::Live (monk add live): HTML pushed to open pages, over the app's
+# WebSocket registry (config/websocket.rb), so it has no transport of its
+# own. Loaded by config/load.rb (bin/server and bin/jobs publish) and by
+# bin/websocket_server (it delivers).
 
-# Where the browser opens its WebSocket (read by the layout). In
-# development there's no reverse proxy in front, so this is the direct WS
-# port; outside development it defaults to a /ws path under public_url
-# (config/settings.rb) -- matching the path-based proxy routing
-# docs/guides/deploying.md's "Adding Monk::WebSocket" section sets up, so
-# setting PUBLIC_URL alone keeps this in sync instead of two env vars
-# drifting apart. Override with LIVE_WS_URL directly if your setup doesn't
-# fit that shape.
+# Where the browser opens its WebSocket, for the layout's <%= monk_head %>:
+# the direct port in development; elsewhere a /ws path under public_url
+# (config/settings.rb), matching the proxy docs/guides/deploying.md sets
+# up, so PUBLIC_URL alone keeps both in sync. LIVE_WS_URL overrides it.
 default_live_ws_url =
   if Monk.env.development?
     "ws://localhost:9293"
   else
-    Monk::Settings[:public_url].sub(/\Ahttps:\/\//, "wss://").sub(/\Ahttp:\/\//, "ws://") + "/ws"
+    Monk::Settings[:public_url].sub(%r{\Ahttps://}, "wss://").sub(%r{\Ahttp://}, "ws://") + "/ws"
   end
 
 Monk::Settings.configure do
   optional :live_ws_url, default: default_live_ws_url
 end
 
-redis_url = ENV["REDIS_URL"] or raise "Monk::Live needs REDIS_URL: bin/server and bin/websocket_server " \
-  "are separate processes, and Redis is how an update published in one reaches a socket in the other"
-
-Monk::Live.configure(
-  registry: Monk::WebSocket::RedisFanout.new(Monk::WebSocket::Registry.new, redis_url: redis_url),
-)
+Monk::Live.configure(registry: AppWebSocket::REGISTRY)
 
 # Who may subscribe to what. Nothing is allowed unless a rule says so, and an
-# anonymous connection is denied unless the rule opts in with `anonymous: true`.
-# The rule blocks live in a module because they have to be Ractor-shareable
-# (self at the top of this file is not).
-module AppLive
-  # The demo counter is public. A real rule looks at who is asking:
-  #   proc { |subject, topic| topic == "contacts:#{subject}" }
-  PUBLIC = proc { |_subject, _topic| true }
-end
+# anonymous socket is denied unless its rule says `anonymous: true`. Rule
+# blocks must be Ractor-shareable, so they're built in a module (self at the
+# top of this file is not); Monk::Live::ALLOW_ALL lets everyone in.
+#
+# monk:example live-rule -- each person may subscribe to their own contacts topic.
+# # subject is the logged-in user (with auth), nil for a visitor.
+# module AppLive
+#   OWN_CONTACTS = proc { |subject, topic| topic == "contacts:#{subject}" }
+# end
+# Monk::Live.authorize("contacts:*", &AppLive::OWN_CONTACTS)
+# monk:end
 
-Monk::Live.authorize("hits", anonymous: true, &AppLive::PUBLIC)
+# monk:demo live -- the demo's topic (app/routes/demo_live.rb), development
+# only. Remove these lines with it.
+if Monk.env.development?
+  Monk::Live.authorize("demo:hits", anonymous: true, &Monk::Live::ALLOW_ALL)
+end
+# monk:end

data/lib/monk/templates/live/config/live_without_demo.rb

@@ -0,0 +1,38 @@
+require "monk"
+require "monk/live"
+require_relative "websocket"
+
+# Monk::Live (monk add live): HTML pushed to open pages, over the app's
+# WebSocket registry (config/websocket.rb), so it has no transport of its
+# own. Loaded by config/load.rb (bin/server and bin/jobs publish) and by
+# bin/websocket_server (it delivers).
+
+# Where the browser opens its WebSocket, for the layout's <%= monk_head %>:
+# the direct port in development; elsewhere a /ws path under public_url
+# (config/settings.rb), matching the proxy docs/guides/deploying.md sets
+# up, so PUBLIC_URL alone keeps both in sync. LIVE_WS_URL overrides it.
+default_live_ws_url =
+  if Monk.env.development?
+    "ws://localhost:9293"
+  else
+    Monk::Settings[:public_url].sub(%r{\Ahttps://}, "wss://").sub(%r{\Ahttp://}, "ws://") + "/ws"
+  end
+
+Monk::Settings.configure do
+  optional :live_ws_url, default: default_live_ws_url
+end
+
+Monk::Live.configure(registry: AppWebSocket::REGISTRY)
+
+# Who may subscribe to what. Nothing is allowed unless a rule says so, and an
+# anonymous socket is denied unless its rule says `anonymous: true`. Rule
+# blocks must be Ractor-shareable, so they're built in a module (self at the
+# top of this file is not); Monk::Live::ALLOW_ALL lets everyone in.
+#
+# monk:example live-rule -- each person may subscribe to their own contacts topic.
+# # subject is the logged-in user (with auth), nil for a visitor.
+# module AppLive
+#   OWN_CONTACTS = proc { |subject, topic| topic == "contacts:#{subject}" }
+# end
+# Monk::Live.authorize("contacts:*", &AppLive::OWN_CONTACTS)
+# monk:end

data/lib/monk/templates/live/setup.md

@@ -0,0 +1,39 @@
+## live
+
+HTML pushed to open pages over the WebSocket (websocket, above): a route
+changes something and calls `Monk::Live.patch`; every page showing it
+updates, with no page JavaScript of your own. The layout's
+`<%= monk_head %>` loads the browser client, which Monk serves from the gem.
+
+### Try the demo
+
+With `bin/server` and `bin/websocket_server` running, open
+http://localhost:9292/demo/live in two tabs and press the button in one:
+the other updates by itself. The demo exists in development only. To
+remove it, delete `app/routes/demo_live.rb`, `app/views/demo/`, and the
+`monk:demo live` lines in `config/live.rb`.
+
+### Before production
+
+`LIVE_WS_URL` defaults to a `/ws` path under `PUBLIC_URL`, with `wss://`
+for an `https://` origin: the proxy in front routes `/ws` to
+`bin/websocket_server` (docs/guides/deploying.md in the monk repo).
+
+### Check it works
+
+1. `bundle exec rake test` runs `test/live_test.rb`: an update reaches a
+   socket subscribed to its topic.
+2. By hand: the demo, above.
+3. The example: uncomment `live-broadcast` (in
+   `app/broadcasts/greeting.rb` and `app/routes/live.rb`) and add a rule
+   for its topic in `config/live.rb`, e.g.
+   `Monk::Live.authorize("greeting", anonymous: true, &Monk::Live::ALLOW_ALL)`.
+   Put `<p <%= live_topic "greeting" %>><%= render "live/_greeting", text: "Hello", layout: false %></p>`
+   in a page, open it in two tabs, and change the greeting:
+
+   ```bash
+   curl -X POST http://localhost:9292/greeting -H "content-type: application/json" \
+     -d '{"text": "Hi all"}'
+   ```
+
+   Both tabs update.

data/lib/monk/templates/live/test/live_test.rb

@@ -0,0 +1,22 @@
+require_relative "test_helper"
+require "json"
+require "timeout"
+
+# Monk::Live publishes through the app's WebSocket registry
+# (config/websocket.rb): an update reaches a socket subscribed to its topic.
+# SETUP.md, live.
+class LiveTest < Minitest::Test
+  def test_an_update_reaches_a_subscribed_socket
+    assert_same AppWebSocket::REGISTRY, Monk::Live.registry
+    AppWebSocket::REGISTRY.listen!
+    port = Ractor::Port.new
+    AppWebSocket::REGISTRY.register(:"live:check", port)
+
+    Monk::Live.remove("live:check", to: "#gone")
+
+    assert_equal "remove", JSON.parse(Timeout.timeout(5) { port.receive })["mode"]
+  ensure
+    AppWebSocket::REGISTRY.unregister(:"live:check", port) if port
+    port&.close
+  end
+end

data/lib/monk/templates/mail/agents.md

@@ -0,0 +1,22 @@
+## mail
+
+**Where:** `config/mail.rb` (from `MAIL_URL`, `MAIL_FROM`), mailers in
+`app/mailers/` (module methods), HTML parts in `app/views/mail/`.
+
+**Main calls:** `Monk::Mail.deliver(to:, subject:, text:, html:)`;
+`Monk::Mail.render("mail/<template>", **locals)` for the HTML part (the
+template reads `locals[:name]`). With jobs:
+`Monk::Mail.deliver_later(...)`, the same arguments.
+
+**Test:** `test/mail_test.rb` delivers to `log/test.log` (`MAIL_URL=log://`
+in `.env.test`); assert on that file's lines.
+
+**Pitfalls:**
+- `deliver` waits for the mail server. In a request that matters: use
+  `deliver_later` once jobs are installed.
+- Render the HTML before `deliver_later`: the job only sends.
+- `MAIL_URL` is required outside development; `MAIL_FROM` must be on a
+  verified domain, or mail lands in spam.
+
+**Examples:** `mail-welcome` in `app/mailers/app_mailer.rb` and
+`app/routes/mail.rb`.

data/lib/monk/templates/mail/app/mailers/app_mailer.rb

@@ -0,0 +1,14 @@
+# The emails this app sends, through Monk::Mail (config/mail.rb). Module
+# methods, so a route or a job can call them from any Ractor.
+module AppMailer
+  # monk:example mail-welcome -- an email, sent from a route (app/routes/mail.rb).
+  # def self.welcome(to:, name:)
+  #   Monk::Mail.deliver(
+  #     to: to,
+  #     subject: "Welcome, #{name}",
+  #     text: "Hello #{name}, thanks for signing up.",
+  #     html: Monk::Mail.render("mail/welcome", name: name),
+  #   )
+  # end
+  # monk:end
+end

data/lib/monk/templates/mail/app/routes/mail.rb

@@ -0,0 +1,12 @@
+# Routes that send email (monk add mail).
+#
+# monk:example mail-welcome -- the route that sends AppMailer.welcome
+# # (app/mailers/app_mailer.rb). Sending waits for the mail server; with
+# # monk add jobs, send it from a job instead (AGENTS.md, mail).
+# class App
+#   post("/welcome") do
+#     AppMailer.welcome(to: params[:email].to_s, name: params[:name].to_s)
+#     json(sent: true)
+#   end
+# end
+# monk:end

data/lib/monk/templates/mail/app/views/mail/welcome.erb

@@ -0,0 +1 @@
+<p>Hello <%= locals[:name] %>, thanks for signing up.</p>

data/lib/monk/templates/mail/config/mail.rb

@@ -1,10 +1,10 @@
 require "monk"
 require "monk/mail"
 
-# Sends email with Monk::Mail.deliver(to:, subject:, text:, html:) from
-# any route -- and, with --auth, the magic links AppMailer::MAGIC_LINK
-# (app/mailers/app_mailer.rb) delivers. See docs/guides/mail.md. Required from config/load.rb (not from
-# config/auth.rb: bin/websocket_server loads that too, and never sends mail).
+# Sends email with Monk::Mail.deliver(to:, subject:, text:, html:): the
+# app's mailers (app/mailers/) and, with auth, its magic links. See
+# docs/guides/mail.md in the monk repo. Loaded by config/load.rb, never by
+# config/auth.rb: bin/websocket_server loads that, and never sends mail.
 Monk::Settings.configure do
   # Where mail goes. Unset in development means log:// (printed to the
   # console, nothing sent); anywhere else an unset one fails the boot.

data/lib/monk/templates/mail/setup.md

@@ -0,0 +1,32 @@
+## mail
+
+In development `MAIL_URL` is unset, so every message is printed to the
+console (and `log/development.log`) instead of sent. Tests use
+`MAIL_URL=log://` (`.env.test`): messages go to `log/test.log`.
+
+### Before production
+
+Set `MAIL_URL` to your provider's SMTP relay, e.g.
+`smtp://user:password@smtp.provider.com:587`, and `MAIL_FROM` to a sender on
+a domain you've verified with that provider (SPF, DKIM). An unset `MAIL_URL`
+fails the boot outside development. Provider examples:
+`docs/guides/mail.md` in the monk repo.
+
+### Check it works
+
+1. `bundle exec rake test` runs `test/mail_test.rb`, which delivers a
+   message to `log/test.log`.
+2. By hand, in `bin/console`:
+   `Monk::Mail.deliver(to: "you@example.com", subject: "Hi", text: "Hello")`.
+   In development the message is printed right there (and in
+   `log/development.log`), not sent.
+3. The example: uncomment the `mail-welcome` blocks in
+   `app/mailers/app_mailer.rb` and `app/routes/mail.rb`, restart
+   `bin/server`, and send one:
+
+   ```bash
+   curl -X POST http://localhost:9292/welcome -H "content-type: application/json" \
+     -d '{"email": "ann@example.com", "name": "Ann"}'
+   ```
+
+   The welcome email is printed in `bin/server`'s console.

data/lib/monk/templates/mail/test/mail_test.rb

@@ -0,0 +1,13 @@
+require_relative "test_helper"
+
+# Monk::Mail is configured, and with .env.test's MAIL_URL=log:// a message
+# lands in log/test.log instead of being sent: SETUP.md, mail.
+class MailTest < Minitest::Test
+  def test_a_message_is_delivered_to_the_test_log
+    subject = "Mail check #{rand(1_000_000)}"
+
+    Monk::Mail.deliver(to: "ann@example.test", subject: subject, text: "Hello")
+
+    assert_includes File.read(File.expand_path("../log/test.log", __dir__)), subject.inspect
+  end
+end

data/lib/monk/templates/postgres/agents.md

@@ -0,0 +1,25 @@
+## postgres
+
+**Where:** `config/persistence.rb` registers the `:primary` connection from
+`DB_*`. Migrations: `db/migrate/<timestamp>_<name>.up.sql` and `.down.sql`,
+plain SQL. Models: `app/models/`.
+
+**Main calls:** a model is `class Note < Monk::Persistence::Pg::Model` with
+`self.db_name = :primary` and `self.table_name = "notes"`; then
+`Note.create(...)`, `.find(id)`, `.where(...)`, `.update(id, ...)`,
+`.delete(id)`. Rows are plain Symbol-keyed Hashes: no ORM, no associations.
+Raw SQL: `Monk::Persistence::Pg.checkout(:primary) { |conn| conn.exec_params(sql, params) }`.
+Commands: `bin/setup_db` (apply pending migrations), `bin/migrate
+[migrate|rollback N|status]`, `bin/console`.
+
+**Test:** `test/persistence_test.rb` connects to the test database. Tests use
+`.env.test`'s `DB_NAME`: migrate it with `DB_NAME={{app}}_test bin/setup_db`.
+
+**Pitfalls:**
+- Models and connections must exist before `Monk.boot`: put models in
+  `app/models/`, never define one inside a route.
+- Never interpolate params into SQL: use `exec_params` with `$1`, `$2`.
+- A new migration gets a new, later timestamp. Never edit one that's
+  already applied.
+
+**Examples:** `postgres-model` in `app/routes/postgres.rb`.

data/lib/monk/templates/postgres/app/routes/postgres.rb

@@ -0,0 +1,22 @@
+# Routes that read and write the app's own tables (monk add postgres).
+#
+# monk:example postgres-model -- a table, a model, and the routes using it.
+# # Uncomment, then move each part where its comment says.
+#
+# # 1. The table, in a migration: db/migrate/<timestamp>_create_notes.up.sql
+# #    (and .down.sql with DROP TABLE notes;), then bin/setup_db.
+# #
+# #    CREATE TABLE notes (id BIGSERIAL PRIMARY KEY, body TEXT NOT NULL);
+#
+# # 2. The model, in app/models/note.rb. Rows are plain Hashes, not objects.
+# class Note < Monk::Persistence::Pg::Model
+#   self.db_name = :primary
+#   self.table_name = "notes"
+# end
+#
+# # 3. The routes, here. params come from the query string or a JSON body.
+# class App
+#   get("/notes") { json(notes: Note.where({}, order: :id, limit: 20)) }
+#   post("/notes") { json(note: Note.create(body: params[:body].to_s)) }
+# end
+# monk:end

data/lib/monk/templates/postgres/bin/console

@@ -3,7 +3,9 @@ require "bundler/setup"
 # The configs and app/ (models, jobs, mailers...), as the app sees them --
 # config/load.rb, never Monk.boot, so nothing is frozen and you can poke at
 # anything.
-require_relative "../config/load"
+# A service that's down or a missing setting ends here with what to fix.
+require "monk/bin"
+Monk::Bin.run(__FILE__) { require_relative "../config/load" }
 require "irb"
 
 IRB.start(__FILE__)