monkrb 0.20.0 → 0.21.1

data/lib/monk/bin.rb

@@ -0,0 +1,107 @@
+module Monk
+  # What a scaffolded app's bin/ scripts run their work in:
+  #
+  #   Monk::Bin.run(__FILE__) do
+  #     require_relative "../config/persistence"
+  #     ...
+  #   end
+  #
+  # An unreachable Postgres or Redis, a missing database, refused
+  # credentials or an unset setting end the script with what failed, which
+  # setting decides it, and the commands that fix it (the same as SETUP.md),
+  # on stderr, exit 1 -- not a backtrace. Anything else is re-raised as it
+  # is. Errors are recognized by class name, so this file loads neither pg
+  # nor redis (docs/adr/0017).
+  module Bin
+    class << self
+      def run(script)
+        yield
+      rescue StandardError => e
+        message = explain(e, script)
+        raise unless message
+
+        # Not warn: it prints nothing when $VERBOSE is nil (ruby -W0), and
+        # this message is the whole point of the failure.
+        $stderr.puts message # rubocop:disable Style/StderrPuts
+        exit 1
+      end
+
+      # The explanation for an error, or nil when it's not one of the above.
+      def explain(error, script)
+        context = Context.for(script)
+
+        case error.class.name
+        when "PG::ConnectionBad" then postgres(error, context)
+        when "Redis::CannotConnectError" then redis(context)
+        when "Monk::WebSocket::ListenError" then fanout(error, context)
+        when "Monk::MissingSettingError" then missing_setting(error.message[/ENV\["([^"]+)"\]/, 1], context)
+        when "KeyError" then missing_setting(error.key, context) if error.receiver.equal?(ENV)
+        end
+      end
+
+      private
+
+      def postgres(error, context)
+        host = error.message[/server at "([^"]+)"/, 1] || ENV.fetch("DB_HOST", "127.0.0.1")
+        port = error.message[/port (\d+)/, 1] || ENV.fetch("DB_PORT", "5432")
+        at = "Postgres at #{host}:#{port}"
+
+        if (database = error.message[/database "([^"]+)" does not exist/, 1])
+          context.message("database \"#{database}\" doesn't exist on #{at} (DB_NAME in .env).",
+            "Create it (it asks for DB_PASSWORD), then run #{context.name} again -- SETUP.md:",
+            "createdb -h #{host} -p #{port} -U #{ENV.fetch("DB_USER", "postgres")} #{database}",)
+        elsif (user = error.message[/authentication failed for user "([^"]+)"/, 1])
+          context.message("#{at} refused user \"#{user}\" (DB_USER/DB_PASSWORD in .env).",
+            "Check them, then run #{context.name} again.",)
+        elsif error.message.include?("Connection refused")
+          context.message("can't connect to #{at} (DB_HOST/DB_PORT in .env).",
+            "Start it, then run #{context.name} again -- SETUP.md:",
+            "docker run --rm -d -p #{port}:5432 -e POSTGRES_PASSWORD=postgres --name #{context.app}_pg postgres:16",)
+        else
+          context.message("can't connect to #{at} (DB_* in .env): #{error.message.lines.first.strip}")
+        end
+      end
+
+      # The WS process's subscriber connection, opened by listen! at boot.
+      def fanout(error, context)
+        if error.message.include?("RedisFanout")
+          redis(context)
+        elsif error.message.include?("PgFanout")
+          postgres(error, context)
+        end
+      end
+
+      def redis(context)
+        url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
+        port = url[%r{//[^/]*:(\d+)}, 1] || "6379"
+        shown = url.sub(%r{//([^@/]*):[^@/]*@}, '//\1:***@') # never the password
+        context.message("can't connect to Redis at #{shown} (REDIS_URL in .env).",
+          "Start it, then run #{context.name} again -- SETUP.md:",
+          "docker run --rm -d -p #{port}:6379 --name #{context.app}_redis redis:7",)
+      end
+
+      def missing_setting(name, context)
+        return unless name
+
+        context.message("#{name} is not set.",
+          "Set it in .env (development) or the environment, then run #{context.name} again.",)
+      end
+    end
+
+    # The script being run: its name as typed from the app's root
+    # (bin/setup_db), and the app's directory name, which SETUP.md's
+    # container names use.
+    Context = Data.define(:name, :app) do
+      def self.for(script)
+        path = File.expand_path(script)
+        new(name: "bin/#{File.basename(path)}", app: File.basename(File.dirname(path, 2)))
+      end
+
+      # The first line says what failed; the next, what to do; the last,
+      # if there's one, is the command to run.
+      def message(what, todo = nil, command = nil)
+        ["#{name}: #{what}", todo, ("  #{command}" if command)].compact.join("\n")
+      end
+    end
+  end
+end

data/lib/monk/cli.rb

@@ -0,0 +1,277 @@
+require "json"
+require "fileutils"
+require_relative "generators"
+
+module Monk
+  # What exe/monk runs (docs/history/plan-scaffold.md Phase 5): `monk new`,
+  # `monk add`, `monk add --list`, `monk help`. Each answers in text, or
+  # as one JSON object with --json, and returns the exit code: 0 done,
+  # 1 usage error, 2 a missing choice, 3 a conflict on a wiring file
+  # (decision 28). It never prompts without a terminal (decision 23).
+  class CLI
+    Error = Class.new(StandardError) do
+      attr_reader :suggestion
+
+      def initialize(message, suggestion: nil)
+        @suggestion = suggestion
+        super(message)
+      end
+    end
+
+    # `monk new`'s flags before docs/adr/0017, in the order --with lists
+    # them. Each is a usage error now, showing the command to type instead.
+    OLD_FLAGS = %w[postgres auth mail jobs redis live].freeze
+
+    USAGE = <<~TEXT.freeze
+      Usage:
+        monk new NAME [--with a,b] [options]   create an app, with modules
+        monk add MODULE... [options]           add modules to the app here
+        monk add --list                        the modules, and which are installed
+        monk help [MODULE] [--file PATH]       this, a module's details, or Monk's version of one of its files
+
+      Options:
+        --transport=postgres|redis   websocket's transport (inferred when only one is installed)
+        --no-demo                    live without its demo
+        --dry-run                    say what would be written, and write nothing
+        --json                       answer as one JSON object
+    TEXT
+
+    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd, registry: Generator.registry,
+                   now: Time.now)
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @cwd = cwd
+      @registry = registry
+      @now = now
+    end
+
+    def run(argv)
+      command, *args = argv
+      @args = parse(args)
+      case command
+      when nil, "help", "--help", "-h" then help
+      when "new" then new_app
+      when "add" then @args[:list] ? list : add
+      else raise Error.new("Unknown command: #{command}.", suggestion: "monk help")
+      end
+    rescue Error => e
+      report(Generator::Result.new(status: :usage_error, written: false, message: e.message, suggestion: e.suggestion))
+    end
+
+    private
+
+    def parse(args)
+      parsed = { positional: [], options: {}, with: [], old: [] }
+      args = args.dup
+      until args.empty?
+        arg = args.shift
+        case arg
+        when "--json" then parsed[:json] = true
+        when "--dry-run" then parsed[:dry_run] = true
+        when "--list" then parsed[:list] = true
+        when "--no-demo" then parsed[:options][:demo] = "off"
+        when /\A--(with|transport|file)(?:=(.*))?\z/
+          value = Regexp.last_match(2) || args.shift || raise(Error, "--#{Regexp.last_match(1)} needs a value.")
+          key = Regexp.last_match(1).to_sym
+          case key
+          when :with then parsed[:with].concat(value.split(",").map(&:strip).reject(&:empty?).map(&:to_sym))
+          when :transport then parsed[:options][:transport] = value
+          else parsed[:file] = value
+          end
+        when /\A--(#{OLD_FLAGS.join("|")})\z/ then parsed[:old] << Regexp.last_match(1)
+        when /\A-/ then raise Error.new("Unknown option: #{arg}.", suggestion: "monk help")
+        else parsed[:positional] << arg
+        end
+      end
+      parsed
+    end
+
+    def new_app
+      name = @args[:positional].first || raise(Error.new("monk new needs a name.", suggestion: "monk new my_app"))
+      old_flags!(name)
+      dir = File.expand_path(name, @cwd)
+      raise Error.new("#{name} already exists.", suggestion: "cd #{name} && monk add <module>") if File.exist?(dir)
+
+      FileUtils.mkdir_p(dir) unless @args[:dry_run]
+      command = "monk new #{name}#{" --with #{@args[:with].join(",")}" unless @args[:with].empty?}"
+      result = run_generators(dir, [:base, *@args[:with]], command)
+      FileUtils.rm_rf(dir) if !result.ok? && !@args[:dry_run]
+      report(result, app: name)
+    end
+
+    def add
+      modules = @args[:positional].map(&:to_sym)
+      raise Error.new("monk add needs a module.", suggestion: "monk add --list") if modules.empty?
+      unless monk_app?
+        raise Error.new("This isn't a Monk app (no config/load.rb here).",
+          suggestion: "monk new my_app, or cd into your app",)
+      end
+
+      report(run_generators(@cwd, modules, "monk add #{modules.join(" ")}"))
+    end
+
+    # A choice the result says is missing is asked for, in a terminal only,
+    # then the run starts over with it.
+    def run_generators(dir, modules, command)
+      options = @args[:options].dup
+      loop do
+        result = @registry.add(dir, modules, options: options, dry_run: @args[:dry_run], now: @now, command: command)
+        return result unless result.status == :missing_choice && interactive?
+
+        value = ask(result)
+        return result unless value
+
+        options[result.choice[:option].to_sym] = value
+      end
+    end
+
+    def interactive?
+      !@args[:json] && @stdin.respond_to?(:tty?) && @stdin.tty?
+    end
+
+    def ask(result)
+      choice = result.choice
+      @stdout.puts result.message, ""
+      width = choice[:values].map(&:size).max
+      choice[:values].each_with_index do |value, index|
+        @stdout.puts "  #{index + 1}) #{value.ljust(width)}   #{choice[:describe]&.fetch(value, nil)}".rstrip
+      end
+      @stdout.print "\n#{choice[:option].capitalize} [#{(1..choice[:values].size).to_a.join("/")}]: "
+      answer = @stdin.gets&.strip.to_s
+      number = answer.match?(/\A\d+\z/) ? answer.to_i : 0
+      value = number.between?(1, choice[:values].size) ? choice[:values][number - 1] : nil
+      value ||= answer if choice[:values].include?(answer)
+      @stdout.puts "# Using --#{choice[:option]}=#{value} skips this question." if value
+      value
+    end
+
+    def old_flags!(name)
+      return if @args[:old].empty?
+
+      old = @args[:old]
+      transport = (%w[redis postgres] & old).first if old.include?("live")
+      with = (OLD_FLAGS & old) - [transport]
+      new_form = "monk new #{name} --with #{with.join(",")}#{" --transport=#{transport}" if transport}"
+      raise Error.new("monk new no longer takes module flags. The same command is now:", suggestion: new_form)
+    end
+
+    def monk_app? = File.exist?(File.join(@cwd, "config/load.rb"))
+
+    def list
+      installed = monk_app? ? @registry.definitions.select { |d| File.exist?(File.join(@cwd, d.installed_if)) } : []
+      rows = @registry.definitions.reject { |definition| definition.name == :base }.map do |definition|
+        list_row(definition, installed.include?(definition))
+      end
+      if @args[:json]
+        @stdout.puts JSON.pretty_generate(modules: rows)
+      else
+        @stdout.puts "Modules#{" (✓ installed)" if monk_app?}", ""
+        width = rows.map { |row| row[:name].size }.max
+        rows.each do |row|
+          needs = row[:needs].empty? ? row[:needs_one_of] : row[:needs]
+          needs_text = "  (needs #{needs.join(row[:needs].empty? ? " or " : ", ")})" unless needs.empty?
+          @stdout.puts "  #{row[:installed] ? "✓" : " "} #{row[:name].ljust(width)}   #{row[:summary]}#{needs_text}"
+        end
+        @stdout.puts "", "Add one: monk add <module>      Details: monk help <module>"
+      end
+      0
+    end
+
+    def list_row(definition, installed)
+      dependency_options = definition.options.select { |option| definition.dependency_options.include?(option.name) }
+      {
+        name: definition.name.to_s, summary: definition.summary, installed: installed,
+        needs: definition.dependencies.map(&:to_s), needs_one_of: dependency_options.flat_map(&:values),
+        options: definition.options.to_h { |option| [option.name, option.values] },
+      }
+    end
+
+    def help
+      name = @args[:positional].first
+      return general_help unless name
+
+      definition = @registry.names.include?(name.to_sym) ? @registry.fetch(name) : nil
+      raise Error.new("Unknown module: #{name}.", suggestion: "monk add --list") unless definition
+      return file_help(definition) if @args[:file]
+
+      module_help(definition)
+    end
+
+    def general_help
+      @stdout.puts USAGE, "Modules:"
+      @registry.definitions.reject { |definition| definition.name == :base }.each do |definition|
+        @stdout.puts "  #{definition.name.to_s.ljust(10)} #{definition.summary}"
+      end
+      0
+    end
+
+    def module_help(definition)
+      @stdout.puts "#{definition.name}: #{definition.summary}"
+      @stdout.puts "Needs: #{definition.dependencies.join(", ")}" unless definition.dependencies.empty?
+      definition.options.each do |option|
+        default = " (default #{option.default})" if option.default
+        @stdout.puts "Option --#{option.name}: #{option.values.join(", ")}#{default}"
+      end
+      @stdout.puts "", "Writes:"
+      definition.copies.each { |copy| @stdout.puts "  #{copy.path.ljust(32)} #{copy.role}" }
+      definition.migrations.each do |migration|
+        @stdout.puts "  db/migrate/<timestamp>_#{migration.name}.{up,down}.sql  wiring"
+      end
+      @stdout.puts "", "Monk's version of one of these: monk help #{definition.name} --file PATH"
+      0
+    end
+
+    # Monk's version of one of a module's files, for a file the app already
+    # had (a conflict, docs/history/plan-scaffold.md decision 26).
+    def file_help(definition)
+      path = @args[:file]
+      source = migration_template(definition, path) || copy_template(definition, path)
+      unless source
+        raise Error.new("#{definition.name} doesn't write #{path}.", suggestion: "monk help #{definition.name}")
+      end
+
+      @stdout.print File.read(source)
+      0
+    end
+
+    def migration_template(definition, path)
+      migration = definition.migrations.find { |m| path.match?(/_#{Regexp.escape(m.name)}\.(up|down)\.sql\z/) }
+      return unless migration
+
+      pattern = "db/migrate/*_#{migration.name}.#{path[/\.(up|down)\.sql\z/, 1]}.sql"
+      Dir[File.join(@registry.templates_dir, definition.name.to_s, pattern)].first
+    end
+
+    def copy_template(definition, path)
+      copy = definition.copies.find { |candidate| candidate.path == path }
+      File.join(@registry.templates_dir, template_for_copy(definition, copy)) if copy
+    end
+
+    def template_for_copy(definition, copy)
+      return "#{definition.name}/#{copy.path}" unless copy.from
+      return copy.from unless copy.from.respond_to?(:call)
+
+      options = definition.options.to_h { |option| [option.name, @args[:options][option.name] || option.default] }
+      missing = definition.options.find { |option| options[option.name].nil? }
+      if missing
+        raise Error.new("#{copy.path} depends on --#{missing.name}.",
+          suggestion: "monk help #{definition.name} --file #{copy.path} --#{missing.name}=#{missing.values.first}",)
+      end
+      copy.from.call(options)
+    end
+
+    def report(result, app: nil)
+      if @args&.fetch(:json, false)
+        hash = result.to_h
+        hash["app"] = app if app
+        @stdout.puts JSON.pretty_generate(hash)
+      elsif result.ok?
+        @stdout.print app ? result.new_text(app) : result.to_text
+      else
+        @stderr.print result.to_text
+      end
+      result.exit_code
+    end
+  end
+end

data/lib/monk/context.rb

@@ -4,8 +4,18 @@ require_relative "views"
 require_relative "assets"
 
 module Monk
+  # The base of Context#head_tags: no tags. A module's helpers, included
+  # into Context after this, add theirs with `def head_tags = super + [...]`
+  # (Monk::Live::Helpers does), so a layout's <%= monk_head %> renders
+  # every loaded module's tags and adding a module never edits the layout
+  # (docs/adr/0017).
+  module HeadTags
+    def head_tags = []
+  end
+
   class Context
     include Monk::Views::Compiled
+    include Monk::HeadTags
 
     attr_reader :params, :env, :headers
     attr_accessor :status
@@ -68,6 +78,13 @@ module Monk
       Monk::Assets.path_for(path)
     end
 
+    # Every loaded module's <head> tags, one per line, for the layout:
+    #   <head> ... <%= monk_head %> </head>
+    # Each tag is built by Monk, which escapes what it interpolates.
+    def monk_head
+      raw(head_tags.join("\n"))
+    end
+
     # Same frozen values Monk::Settings[] reads, e.g. `settings[:api_key]`
     # -- returns the module itself rather than duplicating its #[] here,
     # so an undeclared key raises the exact same way through either path.

data/lib/monk/errors.rb

@@ -31,10 +31,4 @@ module Monk
 
   class TemplateSyntaxError < StandardError
   end
-
-  class ScaffoldExistsError < StandardError
-  end
-
-  class AmbiguousLiveTransportError < StandardError
-  end
 end

data/lib/monk/generator/definition.rb

@@ -0,0 +1,153 @@
+module Monk
+  module Generator
+    # One module's generator, as `Monk::Generator.define(:jobs) { ... }`
+    # declares it. Only declarations: Run decides what they mean for a given
+    # app, and writes nothing until it has checked every file.
+    class Definition
+      Copy = Data.define(:path, :from, :role, :executable, :condition)
+      Migration = Data.define(:name)
+      Env = Data.define(:file, :key, :value, :commented)
+      Option = Data.define(:name, :values, :infer_from, :describe, :default)
+      Service = Data.define(:name, :check, :setup)
+      Step = Data.define(:text, :note, :needs_service, :condition)
+      Example = Data.define(:tag, :todo)
+      Production = Data.define(:key, :note, :placeholder)
+
+      # What a role means when the file already exists with other content:
+      # a wiring file stops the whole command, anything else is skipped
+      # (docs/history/plan-scaffold.md decision 26).
+      ROLES = %i[wiring example test view demo].freeze
+
+      # Which .env file each env group appends to.
+      ENV_FILES = { development: ".env", test: ".env.test", example: ".env.example" }.freeze
+
+      attr_reader :name, :copies, :migrations, :gems, :envs, :ignores, :options, :services, :steps,
+        :examples, :productions, :sections
+
+      def initialize(name)
+        @name = name.to_sym
+        @summary = ""
+        @dependencies = []
+        @option_dependencies = []
+        @installed_if = "config/#{name}.rb"
+        @copies = []
+        @migrations = []
+        @gems = []
+        @envs = []
+        @ignores = []
+        @options = []
+        @services = []
+        @steps = []
+        @examples = []
+        @productions = []
+        @sections = {}
+        @closing = nil
+      end
+
+      def summary(text = nil)
+        return @summary if text.nil?
+
+        @summary = text
+      end
+
+      # Modules this one needs, added first when they're missing.
+      def depends_on(*names)
+        @dependencies.concat(names.map(&:to_sym))
+      end
+
+      # A choice the user makes (websocket's transport). It's inferred when
+      # exactly one of `infer_from` is installed or being added, and the
+      # chosen value is a dependency when `dependency: true`. An option with
+      # a `default:` (live's demo) is never inferred.
+      def option(name, values:, infer_from: values, dependency: false, describe: {}, default: nil)
+        @options << Option.new(name: name.to_sym, values: values.map(&:to_s), infer_from: infer_from.map(&:to_s),
+          describe: describe.transform_keys(&:to_s), default: default&.to_s,)
+        @option_dependencies << name.to_sym if dependency
+      end
+
+      # The file whose existence means this module is installed.
+      def installed_if(path = nil)
+        return @installed_if if path.nil?
+
+        @installed_if = path
+      end
+
+      # A file copied verbatim from templates/<module>/<path>, or from
+      # `from:`, a template path or a block taking the options. `if:`, a
+      # block taking the options, decides whether it's copied at all.
+      def copy(*paths, role:, from: nil, executable: false, if: nil)
+        raise ArgumentError, "unknown role #{role.inspect}, one of #{ROLES.inspect}" unless ROLES.include?(role)
+        raise ArgumentError, "from: needs a single path" if from && paths.size > 1
+
+        condition = binding.local_variable_get(:if)
+        paths.each do |path|
+          @copies << Copy.new(path: path, from: from, role: role, executable: executable, condition: condition)
+        end
+      end
+
+      # db/migrate/<timestamp>_<name>.{up,down}.sql, from the template
+      # migration named *_<name>.{up,down}.sql.
+      def migration(name)
+        @migrations << Migration.new(name: name)
+      end
+
+      # A line appended to the Gemfile unless that gem is already there.
+      def gem(line)
+        @gems << line
+      end
+
+      # A KEY=value line appended to one of the .env files unless KEY is
+      # already there (the app's own value wins). The value may be a block
+      # taking the app's name.
+      def env(file, values, commented: false)
+        raise ArgumentError, "unknown env file #{file.inspect}" unless ENV_FILES.key?(file)
+
+        values.each { |key, value| @envs << Env.new(file: file, key: key.to_s, value: value, commented: commented) }
+      end
+
+      # A line appended to .gitignore and .dockerignore unless it's there.
+      def ignore(line)
+        @ignores << line
+      end
+
+      def service(name, check:, setup:)
+        @services << Service.new(name: name.to_s, check: check, setup: setup)
+      end
+
+      # This module's section of SETUP.md or AGENTS.md: a template path.
+      def setup_section(path) = @sections[:setup] = path
+      def agents_section(path) = @sections[:agents] = path
+
+      def set_before_production(key, note, placeholder: false)
+        @productions << Production.new(key: key, note: note, placeholder: placeholder)
+      end
+
+      # A command (`bin/jobs`) or something to do; `note:` says what for.
+      def next_step(text, note: nil, needs_service: nil, if: nil)
+        @steps << Step.new(text: text, note: note, needs_service: needs_service&.to_s,
+          condition: binding.local_variable_get(:if),)
+      end
+
+      # What to do with an example block (`# monk:example <tag>`). `todo`
+      # may be a block taking the names of the installed modules.
+      def example(tag, todo:)
+        @examples << Example.new(tag: tag, todo: todo)
+      end
+
+      # The one thing that matters most after adding this module: a String,
+      # or a block taking the options.
+      def closing(text = nil)
+        return @closing if text.nil?
+
+        @closing = text
+      end
+
+      # The options whose value is a module to depend on (websocket's transport).
+      def dependency_options = @option_dependencies
+
+      def dependencies(options = {})
+        @dependencies + @option_dependencies.filter_map { |option| options[option]&.to_sym }
+      end
+    end
+  end
+end