monkrb 0.20.0 → 0.21.1

data/lib/monk/generators/websocket.rb

@@ -0,0 +1,24 @@
+# The WebSocket server process, over a transport between processes:
+# Postgres or Redis.
+Monk::Generator.define(:websocket) do
+  summary "WebSocket server process"
+  installed_if "config/websocket.rb"
+  option :transport, values: %w[postgres redis], dependency: true,
+    describe: { postgres: "LISTEN/NOTIFY, nothing else to run; 8 KB per broadcast",
+                redis: "no size limit; Redis must be running", }
+
+  copy "config/websocket.rb", role: :wiring,
+    from: ->(options) { "websocket/config/websocket_#{options[:transport]}.rb" }
+  copy "bin/websocket_server", role: :wiring, executable: true
+  copy "app/sockets/chat.rb", role: :example
+  copy "test/websocket_test.rb", role: :test
+
+  env :example, { "WS_PORT" => "9293" }
+  env :example, { "WS_ALLOWED_ORIGINS" => "https://example.com" }, commented: true
+
+  setup_section "websocket/setup.md"
+  agents_section "websocket/agents.md"
+  set_before_production "WS_ALLOWED_ORIGINS", "defaults to PUBLIC_URL; list every origin your pages use"
+  next_step "bin/websocket_server", note: "beside bin/server"
+  example "websocket-chat", todo: "uncomment for one chat room, or write your own handler in app/sockets/"
+end

data/lib/monk/generators.rb

@@ -0,0 +1,7 @@
+require_relative "generator"
+
+# Monk's own modules, one generator each (docs/adr/0017), in dependency
+# order only for readability: the registry resolves dependencies itself.
+%w[base postgres redis mail auth jobs websocket live].each do |name|
+  require_relative "generators/#{name}"
+end

data/lib/monk/jobs.rb

@@ -227,3 +227,10 @@ module Monk
 end
 
 require_relative "jobs/job"
+
+# What jobs provide together with another module, when that module is
+# loaded too -- either order works (lib/monk/mail.rb and lib/monk/auth.rb
+# end the same way), so an app's config files never require these
+# themselves (docs/adr/0017).
+require_relative "mail/deliver_later" if Monk.const_defined?(:Mail)
+require_relative "auth/send_login_link" if Monk.const_defined?(:Auth)

data/lib/monk/live/helpers.rb

@@ -17,6 +17,19 @@ module Monk
 
         raw(%(data-live-topic="#{names.join(" ")}"))
       end
+
+      # For the layout's <%= monk_head %>: where the client opens its
+      # WebSocket (live_ws_url, which config/live.rb declares) and the
+      # client runtime itself. Nothing until Live is configured, i.e. until
+      # config/live.rb has run.
+      def head_tags
+        return super unless Monk::Live.registry
+
+        super + [
+          %(<meta name="monk-live-url" content="#{h(settings[:live_ws_url])}">),
+          %(<script type="module" src="#{h(asset_path("#{Live::CLIENT_PATH}/monk_live.js"))}"></script>),
+        ]
+      end
     end
   end
 end

data/lib/monk/live.rb

@@ -35,14 +35,25 @@ module Monk
       ).run
     end
 
+    # A rule block that lets everyone in, for Monk::Live.authorize:
+    #   Monk::Live.authorize("demo:hits", anonymous: true, &Monk::Live::ALLOW_ALL)
+    # A block written at the top of config/live.rb isn't Ractor-shareable
+    # (self there is the main object), so rules need one built here.
+    ALLOW_ALL = Ractor.make_shareable(proc { |_subject, _topic| true })
+
     CLIENT_DIR = File.expand_path("live/client", __dir__).freeze
+    # Where Monk serves CLIENT_DIR from: the layout's <%= monk_head %> loads
+    # CLIENT_PATH/monk_live.js (Live::Helpers#head_tags), so an app never
+    # copies the client and never serves an older copy than its gem.
+    CLIENT_PATH = "/_monk/live".freeze
+    Monk::Assets.mount(CLIENT_PATH, CLIENT_DIR)
 
     class << self
       attr_reader :publisher, :registry, :rules, :max_topics
 
       # Where the browser runtime ships inside the gem: monk_live.js,
       # protocol.js and idiomorph.js (they import each other by relative
-      # path, so an app serves or copies the directory as a unit).
+      # path, so they're served as a unit, from CLIENT_PATH).
       def client_dir = CLIENT_DIR
 
       # Boot-time, main Ractor. `registry` is a Monk::WebSocket::Registry,

data/lib/monk/log.rb

@@ -118,7 +118,16 @@ module Monk
       end
 
       def handle
-        Ractor.current[:monk_log_handle] ||= File.open(@path, "a")
+        Ractor.current[:monk_log_handle] ||= File.open(@path || path_before_boot, "a")
+      end
+
+      # Before Boot -- bin/console, a script that loads config/load.rb and
+      # never boots -- nothing has frozen the path yet. Worked out here
+      # instead, the way #freeze_registry! does: only the main Ractor runs
+      # before Boot, so reading Monk.env and writing log/ is safe.
+      def path_before_boot
+        FileUtils.mkdir_p(root)
+        File.join(root, "#{Monk.env}.log")
       end
     end
 

data/lib/monk/mail/deliver_later.rb

@@ -0,0 +1,54 @@
+# Monk::Mail.deliver_later and its job. Loaded at the end of whichever of
+# monk/mail and monk/jobs is required second, once both are defined
+# (docs/adr/0017), so it requires neither itself.
+
+module Monk
+  module Mail
+    # Sends one message from a job process (docs/adr/0014-mail-from-jobs-and-login-links-created-in-the-job.md).
+    # Enqueued by Monk::Mail.deliver_later, never directly: its argument
+    # is the message's fields, already checked and with from: resolved.
+    class DeliveryJob < Monk::Job
+      queue "mailers"
+      never_retry PermanentDeliveryError
+
+      # The SMTP failures that are final, by class name so this file never
+      # loads net/smtp itself (the app's Gemfile decides that, ADR 0012):
+      # a 5xx reply, a malformed command, refused credentials. Everything
+      # else -- a 4xx "try later", a refused connection, TLS, a timeout --
+      # is worth retrying.
+      PERMANENT_SMTP_ERRORS = %w[Net::SMTPFatalError Net::SMTPSyntaxError Net::SMTPAuthenticationError].freeze
+
+      def self.perform(fields)
+        Monk::Mail.deliver(**fields.transform_keys(&:to_sym))
+      rescue DeliveryError => e
+        raise unless PERMANENT_SMTP_ERRORS.include?(e.cause&.class&.name)
+
+        raise PermanentDeliveryError, e.message
+      end
+    end
+
+    class << self
+      # deliver, later: the same arguments, plus enqueue's wait:, at: and
+      # conn: (the last one enqueues inside the caller's transaction, so the
+      # email commits or rolls back with the app's own writes). Returns the
+      # job's id. The message is built -- and so checked -- here, before
+      # anything is enqueued: bad input raises InvalidMessageError in the
+      # caller, exactly as deliver would, rather than failing later in the
+      # job process. Render HTML before calling (html: Monk::Mail.render(...)):
+      # the job stores the finished message and only sends it.
+      #
+      #   Monk::Mail.deliver_later(to: order[:email], subject: "Your receipt", text: receipt_text)
+      def deliver_later(to:, subject:, text: nil, html: nil, reply_to: nil, from: nil, wait: nil, at: nil, conn: nil)
+        raise NotConfiguredError, "call Monk::Mail.configure(url:, from:) before Monk::Mail.deliver_later" unless config
+
+        from ||= config[:from]
+        if from.nil?
+          raise InvalidMessageError, "no from: given, and Monk::Mail.configure has no default from: (MAIL_FROM)"
+        end
+
+        message = Message.new(from: from, to: to, subject: subject, text: text, html: html, reply_to: reply_to)
+        DeliveryJob.enqueue(message.to_h.transform_keys(&:to_s), wait: wait, at: at, conn: conn)
+      end
+    end
+  end
+end

data/lib/monk/mail/later.rb

@@ -1,53 +1,5 @@
+# Monk::Mail.deliver_later (docs/adr/0014). Loading monk/mail and
+# monk/jobs is enough -- the second one loads it (docs/adr/0017) -- so
+# this file only exists for apps whose config/jobs.rb still requires it.
 require_relative "../mail"
 require_relative "../jobs"
-
-module Monk
-  module Mail
-    # Sends one message from a job process (docs/adr/0014-mail-from-jobs-and-login-links-created-in-the-job.md).
-    # Enqueued by Monk::Mail.deliver_later, never directly: its argument
-    # is the message's fields, already checked and with from: resolved.
-    class DeliveryJob < Monk::Job
-      queue "mailers"
-      never_retry PermanentDeliveryError
-
-      # The SMTP failures that are final, by class name so this file never
-      # loads net/smtp itself (the app's Gemfile decides that, ADR 0012):
-      # a 5xx reply, a malformed command, refused credentials. Everything
-      # else -- a 4xx "try later", a refused connection, TLS, a timeout --
-      # is worth retrying.
-      PERMANENT_SMTP_ERRORS = %w[Net::SMTPFatalError Net::SMTPSyntaxError Net::SMTPAuthenticationError].freeze
-
-      def self.perform(fields)
-        Monk::Mail.deliver(**fields.transform_keys(&:to_sym))
-      rescue DeliveryError => e
-        raise unless PERMANENT_SMTP_ERRORS.include?(e.cause&.class&.name)
-
-        raise PermanentDeliveryError, e.message
-      end
-    end
-
-    class << self
-      # deliver, later: the same arguments, plus enqueue's wait:, at: and
-      # conn: (the last one enqueues inside the caller's transaction, so the
-      # email commits or rolls back with the app's own writes). Returns the
-      # job's id. The message is built -- and so checked -- here, before
-      # anything is enqueued: bad input raises InvalidMessageError in the
-      # caller, exactly as deliver would, rather than failing later in the
-      # job process. Render HTML before calling (html: Monk::Mail.render(...)):
-      # the job stores the finished message and only sends it.
-      #
-      #   Monk::Mail.deliver_later(to: order[:email], subject: "Your receipt", text: receipt_text)
-      def deliver_later(to:, subject:, text: nil, html: nil, reply_to: nil, from: nil, wait: nil, at: nil, conn: nil)
-        raise NotConfiguredError, "call Monk::Mail.configure(url:, from:) before Monk::Mail.deliver_later" unless config
-
-        from ||= config[:from]
-        if from.nil?
-          raise InvalidMessageError, "no from: given, and Monk::Mail.configure has no default from: (MAIL_FROM)"
-        end
-
-        message = Message.new(from: from, to: to, subject: subject, text: text, html: html, reply_to: reply_to)
-        DeliveryJob.enqueue(message.to_h.transform_keys(&:to_s), wait: wait, at: at, conn: conn)
-      end
-    end
-  end
-end

data/lib/monk/mail.rb

@@ -119,3 +119,7 @@ module Monk
     Monk.freeze_hooks << self
   end
 end
+
+# Monk::Mail.deliver_later, when jobs are loaded too -- either order works
+# (lib/monk/jobs.rb ends the same way, docs/adr/0017).
+require_relative "mail/deliver_later" if Monk.const_defined?(:Jobs)

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

@@ -0,0 +1,29 @@
+## auth
+
+**Where:** `config/auth.rb` (settings, `callback_path:`),
+`app/routes/auth.rb` (the routes, commented: block `auth-routes`),
+`app/mailers/auth_mailer.rb` (sends the link), `app/views/auth/login.erb`
+(the login page), `app/views/mail/magic_link.erb` (the email's HTML).
+
+**Main calls:** `Monk::Auth.request_login(email)` returns a token;
+`Monk::Auth.login_link(token)` builds its link;
+`Monk::Auth.deliver_link(email:, link:, token:)` sends it;
+`Monk::Auth.redeem(token)` returns a session or nil. In routes:
+`set_session_cookie(session)`, `current_subject` (nil when logged out),
+`require_user!` (halts 401), `require_csrf!`, `log_out!`. With jobs:
+`Monk::Auth::SendLoginLink.enqueue(email)`.
+
+**Test:** `test/auth_test.rb` sends a link to `log/test.log` and redeems it.
+
+**Pitfalls:**
+- `/auth/request` needs a per-email rate limit before it goes live: without
+  one, anyone can make the app send mail to any address.
+- Never point `deliver:` at `Monk::Mail.deliver_later`: the link, token
+  included, would sit in the job queue. Use `SendLoginLink` instead.
+- Links come from `Monk::Settings[:public_url]`, never from request headers.
+- A `redirect_to` must be listed in `redirect_allowlist`.
+- Monk reads `params` from JSON bodies and query strings, not form bodies:
+  pages post with `fetch`. A cookie-authenticated POST sends the
+  `x-csrf-token` header (the `csrf_token` cookie's value).
+
+**Examples:** `auth-routes` in `app/routes/auth.rb`.

data/lib/monk/templates/auth/app/mailers/{app_mailer.rb → auth_mailer.rb}

@@ -1,9 +1,9 @@
-# The emails this app sends, through Monk::Mail (config/mail.rb). Module
-# constants and module methods rather than an instance, since Monk::Auth's
-# deliver: hook must be Ractor-shareable (a lambda built at a file's top
-# level, where self isn't, would fail) -- the same constraint as
+# The login email Monk::Auth sends (config/auth.rb's deliver:), through
+# Monk::Mail (config/mail.rb). A lambda in a module constant: the deliver:
+# hook must be Ractor-shareable, and a lambda built at a file's top level,
+# where self isn't, would fail -- the same constraint as
 # Monk::Live.authorize blocks.
-module AppMailer
+module AuthMailer
   # Monk::Auth's deliver: hook (config/auth.rb), called by
   # Monk::Auth.deliver_link. The HTML part is
   # app/views/mail/magic_link.erb. Swap the body for SMS or any other

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

@@ -0,0 +1,48 @@
+# Logging in by email link (monk add auth). Monk::Auth makes and checks the
+# tokens and sessions; these routes are the app's own, because they carry
+# its decisions: the rate limit, where to go after logging in, JSON or HTML.
+#
+# monk:example auth-routes -- log in by email link, log out, a page for logged-in users.
+# # Before going live: keep a rate limit (without one, anyone can make this
+# # app send mail to any address), and list your redirects in config/auth.rb.
+# module AuthRoutes
+#   # Per process and approximate: 5 links per address per 10 minutes. With
+#   # several bin/server processes, count in the database instead.
+#   LIMIT = Monk::Auth::RateLimiter.new(limit: 5, window: 600)
+# end
+#
+# class App
+#   get("/login") { @title = "Log in"; render "auth/login" }
+#
+#   # app/views/auth/login.erb sends {"email": "..."} as JSON.
+#   post("/auth/request") do
+#     email = params[:email].to_s.strip.downcase
+#     halt(422) if email.empty?
+#     halt(429) if AuthRoutes::LIMIT.exceeded?(email)
+#
+#     # Sent here, in the request. With jobs, replace these two lines with
+#     # Monk::Auth::SendLoginLink.enqueue(email): the token is then made and
+#     # sent in bin/jobs, and never stored.
+#     token = Monk::Auth.request_login(email)
+#     Monk::Auth.deliver_link(email: email, link: Monk::Auth.login_link(token), token: token)
+#     json(sent: true)
+#   end
+#
+#   # The link in the email: callback_path in config/auth.rb.
+#   get("/auth/callback/:token") do
+#     session = Monk::Auth.redeem(params[:token]) || halt(401, "This link has expired or was already used.")
+#     set_session_cookie(session)
+#     redirect(session[:redirect_to] || "/")
+#   end
+#
+#   # From a page: fetch("/auth/logout", { method: "POST", headers: { "x-csrf-token": csrfToken } }),
+#   # where csrfToken is the csrf_token cookie's value.
+#   post("/auth/logout") do
+#     require_csrf!
+#     log_out!
+#     json(logged_out: true)
+#   end
+#
+#   get("/me") { json(email: require_user!) }
+# end
+# monk:end

data/lib/monk/templates/auth/app/views/auth/login.erb

@@ -0,0 +1,25 @@
+<h1>Log in</h1>
+
+<%# Sent with fetch and a JSON body: Monk reads params from JSON bodies,
+    not form bodies. POST /auth/request is in app/routes/auth.rb. %>
+<form id="login">
+  <label>Email <input type="email" name="email" required autocomplete="email"></label>
+  <button>Send me a login link</button>
+</form>
+<p id="login-sent" hidden>Check your email for the link.</p>
+
+<script type="module">
+  const form = document.getElementById("login")
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault()
+    const response = await fetch("/auth/request", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ email: form.email.value }),
+    })
+    if (response.ok) {
+      form.hidden = true
+      document.getElementById("login-sent").hidden = false
+    }
+  })
+</script>

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

@@ -2,17 +2,16 @@ require "monk"
 require "monk/auth"
 require_relative "persistence"
 
-# config/settings.rb already declares public_url -- the trusted origin for
-# the magic link your own login route builds (e.g.
-# "#{Monk::Settings[:public_url]}/auth/callback/#{token}"), see its comment
-# there and auth.md's "Sending the magic link".
+# Magic links are Monk::Auth.login_link(token): config/settings.rb's
+# public_url (the trusted origin), then callback_path: below, then the
+# token -- see auth.md's "Sending the magic link".
 
-# Sends the magic link by email: AppMailer::MAGIC_LINK, in
-# app/mailers/app_mailer.rb. Required here, not left to config/load.rb:
+# Sends the magic link by email: AuthMailer::MAGIC_LINK, in
+# app/mailers/auth_mailer.rb. Required here, not left to config/load.rb:
 # Monk::Auth.configure checks deliver: right away, and bin/websocket_server
 # loads this file without config/load.rb. The mailer only touches
 # Monk::Mail when it's called, so that process needs no mail config.
-require_relative "../app/mailers/app_mailer"
+require_relative "../app/mailers/auth_mailer"
 
 Monk::Auth.configure(
   db_name: :primary,
@@ -20,8 +19,9 @@ Monk::Auth.configure(
   login_ttl: 600,          # seconds a login token stays redeemable
   session_ttl: 1_209_600,  # seconds a session stays valid (14 days)
   redirect_allowlist: [],  # paths request_login(redirect_to:) is allowed to target
+  callback_path: "/auth/callback", # your route redeeming a token: GET "#{callback_path}/:token"
   secure: !Monk.env.development?, # Secure cookie flag; off in dev so plain-http testing works (Safari drops it)
-  deliver: AppMailer::MAGIC_LINK,
+  deliver: AuthMailer::MAGIC_LINK,
 )
 
 # bin/websocket_server checks each socket's session through this pool, so

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

@@ -0,0 +1,37 @@
+## auth
+
+Logging in by email link. `config/auth.rb` configures Monk::Auth,
+`app/mailers/auth_mailer.rb` sends the link through mail, and a migration
+creates the `login_tokens` and `sessions` tables: run `bin/setup_db` and
+`DB_NAME={{app}}_test bin/setup_db` (postgres, above).
+
+### Before production
+
+`AUTH_SECRET` in `.env` and `.env.test` is a placeholder. Set a long random
+one in production's environment, e.g. from
+`ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'`. `config/auth.rb`
+reads it with `ENV.fetch`: unset, the app doesn't boot.
+
+### Check it works
+
+1. `bundle exec rake test` runs `test/auth_test.rb`: a link is sent (to
+   `log/test.log`) and redeemed into a session.
+2. By hand: the login routes are commented out in `app/routes/auth.rb`,
+   block `auth-routes`. Uncomment them and restart `bin/server`. Then:
+   - http://localhost:9292/me answers `401`: nobody is logged in.
+   - http://localhost:9292/login: enter an email. In development the link
+     is printed, not sent: in `bin/server`'s console, or in `bin/jobs`'
+     when a job sends it (`Monk::Auth::SendLoginLink`), and in
+     `log/development.log` either way. Open it: it logs you in and goes
+     back to `/`.
+   - http://localhost:9292/me now shows your email.
+   - To log out, from the browser's console on any page of the app:
+
+     ```js
+     fetch("/auth/logout", { method: "POST", headers: {
+       "x-csrf-token": document.cookie.match(/csrf_token=([^;]+)/)[1] } })
+     ```
+
+     and `/me` answers `401` again.
+3. Before going live: keep the rate limit, and list in `config/auth.rb`
+   (`redirect_allowlist`) the paths a login may send the user back to.

data/lib/monk/templates/auth/test/auth_test.rb

@@ -0,0 +1,17 @@
+require_relative "test_helper"
+
+# Monk::Auth works end to end without any route: a login link is created,
+# sent by config/auth.rb's deliver: (AuthMailer, to log/test.log here), and
+# redeemed into a session. SETUP.md, auth.
+class AuthTest < Minitest::Test
+  def test_a_login_link_is_sent_and_redeems_into_a_session
+    email = "login-check-#{rand(1_000_000)}@example.test"
+    token = Monk::Auth.request_login(email)
+
+    Monk::Auth.deliver_link(email: email, link: Monk::Auth.login_link(token), token: token)
+
+    assert_includes File.read(File.expand_path("../log/test.log", __dir__)), Monk::Auth.login_link(token)
+    session = Monk::Auth.redeem(token)
+    assert_equal email, Monk::Auth.verify(session[:token])
+  end
+end

data/lib/monk/templates/base/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

data/lib/monk/templates/base/Dockerfile

@@ -1,15 +1,19 @@
 # Two-stage build: the builder resolves and installs gems, the final image
 # only keeps the installed bundle plus the app -- no compiler, no gem
-# cache, in the image that actually runs. No system packages needed here:
-# kino ships as precompiled platform gems, and a plain `bundle install`
+# cache, in the image that actually runs. The builder has a compiler for
+# the gems that build a native extension (irb's dependencies, with monk
+# add postgres); kino ships as precompiled platform gems, and pg 1.6+
+# ships precompiled with its own libpq. A plain `bundle install`
 # (Gemfile.lock committed) already resolves every compatible platform, not
 # just the machine that ran it -- nothing to add by hand before building on
 # a different host (docs/guides/deploying.md, "Before the first build").
-# monk/rackup/webrick are pure Ruby. The --postgres/--auth scaffold
-# overrides this file to add libpq for the pg gem's native extension.
 FROM ruby:4.0-slim AS builder
 WORKDIR /app
 
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends build-essential \
+  && rm -rf /var/lib/apt/lists/*
+
 COPY Gemfile Gemfile.lock* ./
 RUN bundle install
 
@@ -23,6 +27,7 @@ COPY . .
 # platform that assigns its own). bin/websocket_server (WS_PORT default
 # 9293) is a separate process/deploy unit -- run this same image with
 # `bin/websocket_server` as the command instead of publishing another
-# port from this Dockerfile -- see docs/guides/deploying.md.
+# port from this Dockerfile -- see docs/guides/deploying.md. Every other
+# process in bin/ (bin/jobs, say) is the same: this image, that command.
 EXPOSE 9292
 CMD ["bin/server", "--bind", "0.0.0.0"]

data/lib/monk/templates/base/Gemfile

@@ -1,7 +1,12 @@
 source "https://rubygems.org"
 
-gem "monkrb", require: "monk"
+gem "monkrb", "~> 0.21", require: "monk"
 gem "rackup"
 gem "webrick"
 gem "kino"
-# gem "dotenv" # uncomment to load a local .env file (config/settings.rb)
+gem "dotenv" # loads .env files, see config/settings.rb
+
+group :test do
+  gem "minitest"
+  gem "rake"
+end

data/lib/monk/templates/base/Rakefile

@@ -0,0 +1,8 @@
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

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

@@ -0,0 +1,41 @@
+# {{app}}: notes for coding agents
+
+A Monk app (Ruby, Ractor-based). Read this before changing code.
+
+## Commands
+
+- `bin/server`: the app on :9292.
+- `bundle exec rake test`: all tests. Run them after every change.
+- `monk add --list --json`: the modules available, and which are installed.
+- `monk add <module> --json`: add a module. Never wire one by hand in
+  `config/load.rb`: it loads every module's config already.
+
+## Where code goes
+
+| Path | What |
+|---|---|
+| `app/app.rb` | `class App`, its base routes; loads `app/routes/*.rb` |
+| `app/routes/<name>.rb` | more routes, each file reopening `class App` |
+| `app/models/` `presenters/` `helpers/` `mailers/` `broadcasts/` `jobs/` | code by role, loaded in that order by `config/load.rb` |
+| `app/views/` | `.erb` templates only, the one template root |
+| `config/<module>.rb` | one per Monk module, loaded by `config/load.rb` in a fixed order |
+| `test/` | Minitest; `test/test_helper.rb` boots the app as `APP` |
+
+## Rules that break the app if ignored
+
+- Everything loads before `Monk.boot` freezes the app. Nothing can be
+  required later, from a route or a job.
+- Routes, jobs and Live rules run in Ractors. A block they use must be
+  Ractor-shareable: define it inside a module or class body, never at the
+  top level of a file (`self` there is the main object).
+- State shared across requests lives in a `Monk::StateRactor`, never in a
+  constant or a class variable.
+- Templates escape what they print. `raw(...)` is only for HTML the app
+  built itself.
+
+## Examples
+
+Commented examples are tagged `# monk:example <name>` ... `# monk:end`.
+`grep -rn "monk:example" app config` lists them; uncomment one and adapt it.
+
+## Modules

data/lib/monk/templates/base/app/app.rb

@@ -7,3 +7,8 @@ class App < Monk::Base
   get("/hello") { "hello from monk" }
   get("/api/hello") { json(message: "hello from monk") }
 end
+
+# More routes, each file reopening `class App`: the ones Monk modules add
+# (monk add), and any of your own. Loaded in name order, before Monk.boot
+# freezes the app.
+Dir[File.expand_path("routes/*.rb", __dir__)].sort.each { |file| require file }

data/lib/monk/templates/base/app/views/index.erb

@@ -1,6 +1,6 @@
 <h1>It works</h1>
 <p>
-  Edit <code>views/index.erb</code> and restart the server to see this
+  Edit <code>app/views/index.erb</code> and restart the server to see this
   change. Templates compile once at boot; <code>&lt;%= %&gt;</code>
   escapes by default, <code>raw(...)</code> opts out.
 </p>

data/lib/monk/templates/base/app/views/layouts/app.erb

@@ -11,6 +11,8 @@
       { "imports": {} }
     </script>
     <script type="module" src="<%= asset_path "/js/app.js" %>"></script>
+    <%# The <head> tags of the Monk modules this app uses (Monk::Live's, say). %>
+    <%= monk_head %>
   </head>
   <body>
     <main><%= yield %></main>

data/lib/monk/templates/base/config/load.rb

@@ -3,6 +3,14 @@
 # it never boots the app itself (that's config.ru's Monk.boot).
 require_relative "settings"
 
+# Each Monk module's config, if this app has it (`monk add <module>` writes
+# it), in Monk's fixed order: a module's config may rely on the ones
+# before it. Nothing to edit here when a module is added.
+%w[persistence redis auth mail jobs websocket live storage].each do |name|
+  path = File.expand_path("#{name}.rb", __dir__)
+  require path if File.exist?(path)
+end
+
 # The app's code, one directory per role, in the order they call each
 # other: presenters read models, helpers, mailers and broadcasts use both,
 # and jobs call all of them. Everything is loaded here, before Monk.boot
@@ -16,3 +24,9 @@ require_relative "settings"
 %w[models presenters helpers mailers broadcasts jobs].each do |role|
   Dir[File.expand_path("../app/#{role}/**/*.rb", __dir__)].sort.each { |file| require file }
 end
+
+# With websocket (monk add websocket), every process that loads this file
+# can broadcast (bin/server, bin/jobs, bin/console, the tests), so its
+# transport is started here, once everything above has declared its
+# databases.
+AppWebSocket.start! if defined?(AppWebSocket)

data/lib/monk/templates/base/config/settings.rb

@@ -1,8 +1,7 @@
-# Loads a local .env file in development, if the app has uncommented the
-# dotenv gem in its Gemfile (see the commented-out line there) and added
-# a .env file of its own. A missing .env, or the gem not being in the
-# bundle at all, is a harmless no-op either way -- production deploys
-# get their env vars from the hosting platform directly, not from here.
+# Loads a local .env file, written by the modules `monk add` adds (DB_*,
+# MAIL_*, ...). A missing .env, or the dotenv gem not being in the bundle
+# at all, is a harmless no-op either way -- production deploys get their
+# env vars from the hosting platform directly, not from here.
 begin
   require "dotenv/load"
 rescue LoadError

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

@@ -0,0 +1,22 @@
+# Setting up {{app}}
+
+## First run
+
+```bash
+bundle install
+bin/server              # the app on http://localhost:9292
+```
+
+## Check it works
+
+1. `bundle exec rake test` runs the tests.
+2. By hand: with `bin/server` running, http://localhost:9292 shows
+   "It works", and http://localhost:9292/hello answers `hello from monk`.
+
+`test/test_helper.rb` loads `.env.test` (if there is one), then the app the
+way `config.ru` does, booted once as `APP`; `test/app_test.rb` makes a
+request through it. Minitest, like Monk's own suite.
+
+Each module added with `monk add` appends its own section below: the
+services it needs, how to start them, and how to check it works, with its
+test and by hand.