monkrb 0.20.0 → 0.21.1

data/lib/monk/generator/run.rb

@@ -0,0 +1,449 @@
+require "fileutils"
+
+module Monk
+  module Generator
+    # One `monk add`: works out every module to add (dependencies first,
+    # options inferred or missing), checks every file against the app,
+    # and only then writes -- or writes nothing, on a usage error, a missing
+    # choice, a conflict on a wiring file, or a dry run
+    # (docs/history/plan-scaffold.md decisions 2-5, 25-28).
+    class Run
+      # A choice the user has to make before anything can be planned.
+      MissingChoice = Class.new(StandardError) do
+        attr_reader :choice
+
+        def initialize(choice)
+          @choice = choice
+          super(choice[:message])
+        end
+      end
+
+      UsageError = Class.new(StandardError) do
+        attr_reader :suggestion
+
+        def initialize(message, suggestion: nil)
+          @suggestion = suggestion
+          super(message)
+        end
+      end
+
+      def initialize(registry:, dir:, requested:, options: {}, dry_run: false, now: Time.now, command: nil)
+        @registry = registry
+        @dir = File.expand_path(dir)
+        @requested = requested.map(&:to_sym)
+        @options = options.transform_keys(&:to_sym).transform_values(&:to_s)
+        @dry_run = dry_run
+        @now = now
+        @command = command || "monk add #{@requested.join(" ")}"
+      end
+
+      def call
+        validate!
+        @installed = @registry.definitions.select { |definition| installed?(definition) }.map(&:name)
+        @plan = resolve
+        @files = Files.new(@dir)
+        @migration_count = 0
+        entries = @plan.flat_map { |definition, options| entries_for(definition, options) }
+        conflicts = entries.select { |entry| entry[:action] == :conflict && entry[:role] == :wiring }
+        return conflict_result(conflicts) unless conflicts.empty?
+
+        result(entries)
+      rescue UsageError => e
+        error_result(:usage_error, e.message, suggestion: e.suggestion)
+      rescue MissingChoice => e
+        error_result(:missing_choice, e.message, choice: e.choice.except(:message))
+      end
+
+      private
+
+      def validate!
+        raise UsageError.new("Nothing to add.", suggestion: "monk add --list") if @requested.empty?
+
+        unknown = @requested - @registry.names
+        unless unknown.empty?
+          raise UsageError.new(
+            "Unknown module#{"s" if unknown.size > 1}: #{unknown.join(", ")}. Modules: #{@registry.names.join(", ")}.",
+            suggestion: "monk add --list",
+          )
+        end
+
+        @registry.definitions.flat_map(&:options).each do |option|
+          value = @options[option.name]
+          next if value.nil? || option.values.include?(value)
+
+          raise UsageError, "--#{option.name}=#{value} isn't one of #{option.values.join(", ")}."
+        end
+      end
+
+      def installed?(definition)
+        File.exist?(File.join(@dir, definition.installed_if))
+      end
+
+      # [definition, options] for every module to add, dependencies first.
+      # Options are inferred from the modules installed or being added in
+      # this same command (decision 13), so `--with jobs,live` picks
+      # Postgres for websocket's transport.
+      def resolve
+        available = (@installed + static_closure).map(&:to_s)
+        plan = []
+        visiting = []
+        visit = lambda do |name, needed_by|
+          @needed_by[name] |= [needed_by] if needed_by
+          return if @installed.include?(name) || plan.any? { |definition, _| definition.name == name }
+          raise UsageError, "Modules depend on each other in a cycle: #{(visiting + [name]).join(" -> ")}." if
+            visiting.include?(name)
+
+          definition = @registry.fetch(name)
+          options = resolve_options(definition, available)
+          visiting.push(name)
+          definition.dependencies(options).each { |dependency| visit.call(dependency, name) }
+          visiting.pop
+          plan << [definition, options]
+        end
+        @needed_by = Hash.new { |hash, key| hash[key] = [] }
+        @requested.each { |name| visit.call(name, nil) }
+        plan
+      end
+
+      def static_closure
+        seen = []
+        queue = @requested.dup
+        until queue.empty?
+          name = queue.shift
+          next if seen.include?(name)
+
+          seen << name
+          queue.concat(@registry.fetch(name).dependencies)
+        end
+        seen
+      end
+
+      def resolve_options(definition, available)
+        definition.options.to_h do |option|
+          given = @options[option.name] || option.default
+          next [option.name, given] if given
+
+          candidates = option.infer_from & available
+          next [option.name, candidates.first] if candidates.size == 1
+
+          raise MissingChoice, missing_choice(definition, option, candidates)
+        end
+      end
+
+      def missing_choice(definition, option, candidates)
+        reason = if candidates.empty?
+                   "this app has none of #{option.infer_from.join(", ")}"
+                 else
+                   "this app has both #{candidates.join(" and ")}"
+                 end
+        {
+          module: definition.name.to_s, option: option.name.to_s, values: option.values, reason: reason,
+          describe: option.describe, command: @command,
+          message: "#{definition.name} needs a #{option.name}, and #{reason}.",
+        }
+      end
+
+      def entries_for(definition, options)
+        copies = definition.copies.select { |copy| copy.condition.nil? || copy.condition.call(options) }
+        entries = copies.map { |copy| copy_entry(definition, copy, options) }
+        entries.concat(definition.migrations.flat_map { |migration| migration_entries(definition, migration) })
+        entries.concat(gem_entries(definition))
+        entries.concat(env_entries(definition))
+        entries.concat(ignore_entries(definition))
+        entries.compact
+      end
+
+      def copy_entry(definition, copy, options)
+        from = copy.from.respond_to?(:call) ? copy.from.call(options) : copy.from
+        content = File.binread(template(from || "#{definition.name}/#{copy.path}"))
+        entry = { path: copy.path, module: definition.name, role: copy.role }
+
+        case @files.compare(copy.path, content)
+        when :missing
+          @files.create(copy.path, content, executable: copy.executable)
+          entry.merge(action: :created, examples: example_tags(content))
+        when :same then nil
+        else entry.merge(action: :conflict)
+        end
+      end
+
+      def migration_entries(definition, migration)
+        target_dir = "db/migrate"
+        return [] unless @files.glob("#{target_dir}/*_#{migration.name}.up.sql").empty?
+
+        stamp = (@now + @migration_count).strftime("%Y%m%d%H%M%S")
+        @migration_count += 1
+        %w[up down].map do |direction|
+          pattern = File.join(@registry.templates_dir, definition.name.to_s, target_dir,
+            "*_#{migration.name}.#{direction}.sql",)
+          source = Dir[pattern].first || raise(ArgumentError, "no template migration matches #{pattern}")
+          path = "#{target_dir}/#{stamp}_#{migration.name}.#{direction}.sql"
+          @files.create(path, File.binread(source))
+          { path: path, module: definition.name, role: :wiring, action: :created, examples: [] }
+        end
+      end
+
+      def gem_entries(definition)
+        names = definition.gems.filter_map do |line|
+          name = line[/\Agem\s+["']([^"']+)/, 1]
+          next if @files.read("Gemfile").match?(/^\s*gem\s+["']#{Regexp.escape(name)}["']/)
+
+          @files.append("Gemfile", "#{line}\n")
+          name
+        end
+        names.empty? ? [] : [appended("Gemfile", definition, names)]
+      end
+
+      def env_entries(definition)
+        definition.envs.group_by(&:file).filter_map do |file, envs|
+          path = Definition::ENV_FILES.fetch(file)
+          keys = envs.filter_map do |env|
+            next if @files.read(path).match?(/^#?\s*#{Regexp.escape(env.key)}=/)
+
+            value = env.value.respond_to?(:call) ? env.value.call(app_name) : env.value
+            @files.append(path, "#{"# " if env.commented}#{env.key}=#{value}\n")
+            env.key
+          end
+          appended(path, definition, keys) unless keys.empty?
+        end
+      end
+
+      def ignore_entries(definition)
+        %w[.gitignore .dockerignore].filter_map do |path|
+          lines = definition.ignores.reject { |line| @files.read(path).lines.map(&:chomp).include?(line) }
+          lines.each { |line| @files.append(path, "#{line}\n") }
+          appended(path, definition, lines) unless lines.empty?
+        end
+      end
+
+      def appended(path, definition, items)
+        { path: path, module: definition.name, action: :appended, items: items }
+      end
+
+      # SETUP.md and AGENTS.md: each added module's section, after the
+      # others, marked so it's never added twice.
+      def section_entries
+        { setup: "SETUP.md", agents: "AGENTS.md" }.filter_map do |kind, path|
+          names = @plan.filter_map do |definition, _|
+            section = definition.sections[kind]
+            marker = "<!-- monk:module #{definition.name} -->"
+            next if section.nil? || @files.read(path).include?(marker)
+
+            body = File.read(template(section)).gsub("{{app}}", app_name)
+            @files.append(path, "#{"\n" unless @files.read(path).empty?}#{marker}\n#{body}")
+            definition.name
+          end
+          { path: path, action: :appended, items: names, sections: true } unless names.empty?
+        end
+      end
+
+      # [tag, line number] for each `# monk:example <tag>` in a file.
+      def example_tags(content)
+        content.each_line.with_index(1).filter_map do |line, number|
+          tag = line[/#\s*monk:example\s+(\S+)/, 1]
+          [tag, number] if tag
+        end
+      end
+
+      def result(entries)
+        entries += section_entries
+        @files.write! unless @dry_run
+        conflicts, done = entries.partition { |entry| entry[:action] == :conflict }
+        Result.new(
+          status: :ok, written: !@dry_run && !done.empty?, dry_run: @dry_run, requested: @requested,
+          modules: module_entries, files: done, skipped: conflicts.map { |entry| skipped(entry) },
+          env: production_entries, examples: examples(entries), services: services, next_steps: next_steps(entries),
+          docs: docs(entries), closing: closing,
+          command: @command,
+        )
+      end
+
+      def module_entries
+        added = @plan.map do |definition, options|
+          entry = { name: definition.name, action: :added }
+          needed_by = @needed_by[definition.name]
+          entry[:reason] = "needed by #{needed_by.join(", ")}" unless @requested.include?(definition.name)
+          entry[:options] = options unless options.empty?
+          entry
+        end
+        already = (@requested & @installed).map { |name| { name: name, action: :already_installed } }
+        needed = @plan.flat_map { |definition, options| definition.dependencies(options) }.uniq
+        dependencies_installed = ((needed & @installed) - @requested).map do |name|
+          { name: name, action: :already_installed, reason: "needed by #{needers(name).join(", ")}" }
+        end
+        already + dependencies_installed + added
+      end
+
+      def needers(name)
+        @plan.filter_map { |definition, options| definition.name if definition.dependencies(options).include?(name) }
+      end
+
+      def skipped(entry)
+        entry.slice(:path, :module, :role).merge(show: "monk help #{entry[:module]} --file #{entry[:path]}")
+      end
+
+      def production_entries
+        @plan.flat_map do |definition, _|
+          definition.productions.map do |production|
+            files = definition.envs.select { |env| env.key == production.key }.map { |env| Definition::ENV_FILES.fetch(env.file) }
+            { key: production.key, module: definition.name, files: files, placeholder: production.placeholder,
+              required_in: %w[staging production], note: production.note, }
+          end
+        end
+      end
+
+      def examples(entries)
+        all = (@installed + @plan.map { |definition, _| definition.name }).map(&:to_s)
+        entries.select { |entry| entry[:action] == :created }.flat_map do |entry|
+          definition = @registry.fetch(entry[:module])
+          entry[:examples].map do |tag, line|
+            todo = definition.examples.find { |example| example.tag == tag }&.todo
+            todo = todo.call(all) if todo.respond_to?(:call)
+            { tag: tag, path: entry[:path], line: line, module: entry[:module], todo: todo }.compact
+          end
+        end
+      end
+
+      def services
+        @plan.flat_map { |definition, _| definition.services }.uniq(&:name)
+             .map { |service| { name: service.name, check: service.check, setup: service.setup } }
+      end
+
+      # Every step, in the order they're done: bundle install when gems were
+      # added, what to do first (start a service), bin/setup_db when a
+      # migration was added, each module's own commands (bin/jobs), and the
+      # tests last.
+      def next_steps(entries)
+        all_services = (@installed.map { |name| @registry.fetch(name) } + @plan.map(&:first))
+                       .flat_map(&:services).map(&:name).uniq
+        steps = []
+        gems_added = entries.any? { |entry| entry[:path] == "Gemfile" && %i[appended created].include?(entry[:action]) }
+        steps << { run: "bundle install" } if gems_added
+        own = @plan.flat_map do |definition, options|
+          definition.steps.select { |step| step.condition.nil? || step.condition.call(options) }
+                    .map { |step| step_entry(step, definition.name) }
+        end
+        commands, todos = own.partition { |step| step.key?(:run) }
+        steps.concat(todos)
+        migrating = entries.select { |entry| entry[:path].end_with?(".up.sql") && entry[:action] == :created }
+        unless migrating.empty?
+          needed = services_of(migrating.map { |entry| entry[:module] }.uniq)
+          steps << { run: "bin/setup_db", needs_service: (needed.join(",") unless needed.empty?) }.compact
+        end
+        steps.concat(commands)
+        steps << { run: "bundle exec rake test",
+                   needs_service: (all_services.join(",") unless all_services.empty?), }.compact
+        steps.uniq
+      end
+
+      # The services these modules need, theirs or their dependencies'.
+      def services_of(names)
+        seen = []
+        queue = names.dup
+        until queue.empty?
+          name = queue.shift
+          next if seen.include?(name)
+
+          seen << name
+          options = @plan.find { |definition, _| definition.name == name }&.last || {}
+          queue.concat(@registry.fetch(name).dependencies(options))
+        end
+        seen.flat_map { |name| @registry.fetch(name).services }.map(&:name).uniq
+      end
+
+      # The last added module's closing line that applies.
+      def closing
+        @plan.filter_map do |definition, options|
+          text = definition.closing
+          text.respond_to?(:call) ? text.call(options) : text
+        end.last
+      end
+
+      def step_entry(step, module_name)
+        key = step.text.match?(%r{\A(bin/|bundle |ruby |curl )}) ? :run : :do
+        { key => step.text, note: step.note, needs_service: step.needs_service, module: module_name }.compact
+      end
+
+      def docs(entries)
+        entries.select { |entry| entry[:sections] }.flat_map do |entry|
+          entry[:items].map { |name| "#{entry[:path]}##{name}" }
+        end
+      end
+
+      def conflict_result(conflicts)
+        first = conflicts.first
+        message = "#{first[:path]} exists and differs, and #{first[:module]} needs it to run."
+        message = "#{conflicts.size} files #{first[:module]} needs exist and differ." if conflicts.size > 1
+        Result.new(
+          status: :conflict, written: false, dry_run: @dry_run, requested: @requested, message: message,
+          conflicts: conflicts.map { |entry| skipped(entry) }, command: @command,
+        )
+      end
+
+      def error_result(status, message, suggestion: nil, choice: nil)
+        Result.new(status: status, written: false, dry_run: @dry_run, requested: @requested, message: message,
+          suggestion: suggestion, choice: choice, command: @command,)
+      end
+
+      def template(path)
+        File.join(@registry.templates_dir, path)
+      end
+
+      def app_name = File.basename(@dir)
+    end
+
+    # The app's files as the run will leave them: read from disk once, then
+    # changed in memory, and written only by write!.
+    class Files
+      def initialize(dir)
+        @dir = dir
+        @contents = {}
+        @changed = {}
+        @executable = []
+      end
+
+      def read(path)
+        @contents.fetch(path) do
+          full = File.join(@dir, path)
+          @contents[path] = File.exist?(full) ? File.binread(full) : +""
+        end
+      end
+
+      def compare(path, content)
+        return :missing unless exists?(path)
+
+        read(path) == content ? :same : :different
+      end
+
+      def exists?(path) = @changed.key?(path) || File.exist?(File.join(@dir, path))
+
+      def glob(pattern)
+        on_disk = Dir.glob(pattern, base: @dir)
+        on_disk + @changed.keys.select { |path| File.fnmatch?(pattern, path) }
+      end
+
+      def create(path, content, executable: false)
+        @contents[path] = content.dup
+        @changed[path] = true
+        @executable << path if executable
+      end
+
+      def append(path, text)
+        current = read(path)
+        current = "#{current}\n" unless current.empty? || current.end_with?("\n")
+        @contents[path] = current + text
+        @changed[path] = true
+      end
+
+      def write!
+        @changed.each_key do |path|
+          full = File.join(@dir, path)
+          FileUtils.mkdir_p(File.dirname(full))
+          File.binwrite(full, @contents.fetch(path))
+          File.chmod(0o755, full) if @executable.include?(path)
+        end
+        @changed.clear
+      end
+    end
+  end
+end

data/lib/monk/generator.rb

@@ -0,0 +1,48 @@
+require_relative "generator/definition"
+require_relative "generator/run"
+require_relative "generator/result"
+
+module Monk
+  # `monk add`: one generator per module, run on any app, new or existing
+  # (docs/adr/0017, docs/history/plan-scaffold.md). A generator only creates files
+  # and appends lines; Run plans and checks everything before writing.
+  module Generator
+    TEMPLATES_DIR = File.expand_path("templates", __dir__)
+
+    # The modules `monk add` knows, by name. Monk's own live in
+    # lib/monk/generators/; tests build their own registry, over their own
+    # templates.
+    class Registry
+      attr_reader :templates_dir
+
+      def initialize(templates_dir:)
+        @templates_dir = templates_dir
+        @definitions = {}
+      end
+
+      def define(name, &)
+        definition = Definition.new(name)
+        definition.instance_eval(&)
+        @definitions[definition.name] = definition
+      end
+
+      def fetch(name) = @definitions.fetch(name.to_sym)
+      def names = @definitions.keys
+      def definitions = @definitions.values
+
+      # Adds `modules` (names) to the app in `dir`. Returns a Result, never
+      # raises for a usage error, a missing choice or a conflict.
+      def add(dir, modules, **)
+        Run.new(registry: self, dir: dir, requested: modules, **).call
+      end
+    end
+
+    class << self
+      def registry
+        @registry ||= Registry.new(templates_dir: TEMPLATES_DIR)
+      end
+
+      def define(name, &) = registry.define(name, &)
+    end
+  end
+end

data/lib/monk/generators/auth.rb

@@ -0,0 +1,29 @@
+# Passwordless login by email link (Monk::Auth).
+Monk::Generator.define(:auth) do
+  summary "Passwordless magic-link login"
+  installed_if "config/auth.rb"
+  depends_on :postgres, :mail
+
+  copy "config/auth.rb", "app/mailers/auth_mailer.rb", role: :wiring
+  copy "app/views/mail/magic_link.erb", "app/views/auth/login.erb", role: :view
+  copy "app/routes/auth.rb", role: :example
+  copy "test/auth_test.rb", role: :test
+  migration "create_auth_tables"
+
+  env :development, { "AUTH_SECRET" => "change-me-dev-secret" }
+  env :test, { "AUTH_SECRET" => "change-me-test-secret" }
+  env :example, { "AUTH_SECRET" => "change-me" }
+
+  setup_section "auth/setup.md"
+  agents_section "auth/agents.md"
+  set_before_production "AUTH_SECRET", "placeholder in .env — replace it", placeholder: true
+  example "auth-routes", todo: lambda { |installed|
+    if installed.include?("jobs")
+      "uncomment, keep the rate limit; send with Monk::Auth::SendLoginLink (jobs is installed)"
+    else
+      "uncomment, keep the rate limit, and list your redirects in config/auth.rb"
+    end
+  }
+  closing 'Then turn on the login routes: app/routes/auth.rb, block "auth-routes" ' \
+          "(keep the rate limit — AGENTS.md, auth, says why)."
+end

data/lib/monk/generators/base.rb

@@ -0,0 +1,19 @@
+# The bare app `monk new` writes: every other module is added on top of it.
+Monk::Generator.define(:base) do
+  summary "The bare app: routes, views, static files, tests, SETUP.md and AGENTS.md"
+  installed_if "config/load.rb"
+
+  copy "Gemfile", "config.ru", "config/settings.rb", "config/load.rb", "app/app.rb", ".ruby-version",
+    ".gitignore", ".dockerignore", "Dockerfile", "public/css/app.css", "public/js/app.js", "Rakefile",
+    "CLAUDE.md", role: :wiring
+  copy "bin/server", role: :wiring, executable: true
+  copy "app/views/layouts/app.erb", "app/views/index.erb", role: :view
+  # Every role directory, empty, so the tree shows where each kind of code
+  # goes (docs/adr/0015), and app/routes/ for the routes modules add.
+  copy(*%w[models presenters helpers mailers broadcasts jobs routes].map { |role| "app/#{role}/.keep" }, role: :wiring)
+  copy "test/test_helper.rb", "test/app_test.rb", role: :test
+
+  setup_section "base/setup.md"
+  agents_section "base/agents.md"
+  next_step "bin/server", note: "http://localhost:9292"
+end

data/lib/monk/generators/jobs.rb

@@ -0,0 +1,21 @@
+# Background jobs on Postgres (Monk::Jobs), run by bin/jobs.
+Monk::Generator.define(:jobs) do
+  summary "Background jobs on Postgres"
+  installed_if "config/jobs.rb"
+  depends_on :postgres
+
+  copy "config/jobs.rb", role: :wiring
+  copy "bin/jobs", role: :wiring, executable: true
+  copy "app/jobs/hello_job.rb", "app/routes/jobs.rb", role: :example
+  copy "test/jobs_test.rb", role: :test
+  migration "create_jobs_tables"
+
+  queues = { "JOBS_WORKERS" => "2", "JOBS_QUEUES" => "mailers,default" }
+  env :development, queues
+  env :example, queues
+
+  setup_section "jobs/setup.md"
+  agents_section "jobs/agents.md"
+  next_step "bin/jobs", note: "beside bin/server"
+  example "jobs-enqueue", todo: "uncomment, or enqueue your own jobs from any route"
+end

data/lib/monk/generators/live.rb

@@ -0,0 +1,26 @@
+# Server-pushed HTML updates (Monk::Live), over the app's WebSocket.
+Monk::Generator.define(:live) do
+  summary "Server-pushed HTML updates"
+  installed_if "config/live.rb"
+  depends_on :websocket
+  option :demo, values: %w[on off], default: "on"
+
+  demo = ->(options) { options[:demo] == "on" }
+  copy "config/live.rb", role: :wiring,
+    from: ->(options) { demo.call(options) ? "live/config/live.rb" : "live/config/live_without_demo.rb" }
+  copy "app/broadcasts/greeting.rb", "app/routes/live.rb", role: :example
+  copy "app/views/live/_greeting.erb", role: :view
+  copy "app/routes/demo_live.rb", "app/views/demo/live.erb", "app/views/demo/_hits.erb", role: :demo, if: demo
+  copy "test/live_test.rb", role: :test
+
+  setup_section "live/setup.md"
+  agents_section "live/agents.md"
+  set_before_production "LIVE_WS_URL", "defaults to /ws under PUBLIC_URL (wss:// for https)"
+  next_step "open http://localhost:9292/demo/live in two tabs, press +1", if: demo
+  example "live-rule", todo: "uncomment and adapt: nothing can be subscribed to until a rule allows it"
+  example "live-broadcast", todo: "uncomment, add a rule for its topic, and put the live_topic element in a page"
+  closing lambda { |options|
+    "Remove the demo when done: app/routes/demo_live.rb, app/views/demo/, and its lines in config/live.rb." if
+      demo.call(options)
+  }
+end

data/lib/monk/generators/mail.rb

@@ -0,0 +1,24 @@
+# Email over SMTP (Monk::Mail); printed to the console in development.
+Monk::Generator.define(:mail) do
+  summary "Email over SMTP (log:// in development)"
+  installed_if "config/mail.rb"
+
+  copy "config/mail.rb", role: :wiring
+  copy "app/mailers/app_mailer.rb", "app/routes/mail.rb", role: :example
+  copy "app/views/mail/welcome.erb", role: :view
+  copy "test/mail_test.rb", role: :test
+
+  gem %(gem "net-smtp", "~> 0.5" # Monk::Mail's smtp:// transport)
+  env :development, { "MAIL_FROM" => ->(app) { %("#{app} <no-reply@localhost>") } }
+  env :test, { "MAIL_URL" => "log://", "MAIL_FROM" => ->(app) { %("#{app} <no-reply@localhost>") } }
+  env :example, { "MAIL_URL" => "smtp://user:password@smtp.example.com:587",
+                  "MAIL_FROM" => ->(app) { %("#{app} <no-reply@example.com>") }, }
+
+  setup_section "mail/setup.md"
+  agents_section "mail/agents.md"
+  set_before_production "MAIL_URL", "unset = printed to the console in development"
+  set_before_production "MAIL_FROM", "a sender on a domain verified with your provider"
+  example "mail-welcome", todo: lambda { |installed|
+    "uncomment and adapt#{"; send it with deliver_later, jobs is installed" if installed.include?("jobs")}"
+  }
+end

data/lib/monk/generators/postgres.rb

@@ -0,0 +1,23 @@
+# Postgres persistence and migrations (Monk::Persistence::Pg).
+Monk::Generator.define(:postgres) do
+  summary "Postgres persistence and migrations"
+  installed_if "config/persistence.rb"
+
+  copy "config/persistence.rb", "db/migrate/.keep", role: :wiring
+  copy "bin/console", "bin/setup_db", "bin/migrate", role: :wiring, executable: true
+  copy "app/routes/postgres.rb", role: :example
+  copy "test/persistence_test.rb", role: :test
+
+  gem %(gem "pg", "~> 1.6" # 1.6+ ships precompiled, libpq included: no system packages)
+  gem %(gem "irb")
+  database = { "DB_HOST" => "127.0.0.1", "DB_PORT" => "5432", "DB_USER" => "postgres", "DB_PASSWORD" => "postgres" }
+  env :development, database.merge("DB_NAME" => ->(app) { "#{app}_development" })
+  env :test, database.merge("DB_NAME" => ->(app) { "#{app}_test" })
+  env :example, database.merge("DB_NAME" => ->(app) { "#{app}_development" })
+
+  service :postgres, check: "pg_isready -h 127.0.0.1 -p 5432", setup: "SETUP.md#postgres"
+  next_step "start Postgres and create the databases (SETUP.md › postgres)"
+  setup_section "postgres/setup.md"
+  agents_section "postgres/agents.md"
+  example "postgres-model", todo: "uncomment, then move the table to a migration and the model to app/models/"
+end

data/lib/monk/generators/redis.rb

@@ -0,0 +1,20 @@
+# The app's Redis connection setting: a cache, rate limits, locks, or
+# WebSocket's transport.
+Monk::Generator.define(:redis) do
+  summary "Redis connection setting, for caching or as a WebSocket transport"
+  installed_if "config/redis.rb"
+
+  copy "config/redis.rb", role: :wiring
+  copy "app/routes/redis.rb", role: :example
+  copy "test/redis_test.rb", role: :test
+
+  gem %(gem "redis", "~> 5.0")
+  %i[development test example].each { |file| env file, { "REDIS_URL" => "redis://localhost:6379/0" } }
+
+  service :redis, check: "redis-cli -p 6379 ping", setup: "SETUP.md#redis"
+  next_step "start Redis (SETUP.md › redis)"
+  setup_section "redis/setup.md"
+  agents_section "redis/agents.md"
+  set_before_production "REDIS_URL", "required outside development and test"
+  example "redis-cache", todo: "uncomment and adapt; open a client per request, and close it"
+end