thundercli 0.2.0

data/lib/thunder/console/views/operation.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module Thunder
+  class Console
+    module Views
+      # An operation class as its interface, one section per part, one item per line: the params with their type
+      # (and optional when they are), what it uses, and the flow with the steps numbered in the order they run. A
+      # clause (transaction...) indents its steps; the step that ends the flow (success, render) is written as in the
+      # flow block, under the step names.
+      #   =>  OPERATION  books.add  Library::Internal::Operations::Books::Add
+      #      params 1
+      #        title  String
+      #      uses
+      #        model  book
+      #      flow
+      #         1  create_book
+      #            success :book
+      class Operation
+        include Format
+
+        MAX_PARAMS = 16
+        MAX_STEPS = 24
+        KIND_LABELS = { external_operation: 'external' }.freeze
+        STEP_INDENT = '  '
+
+        def initialize(klass)
+          @klass = klass
+        end
+
+        def call
+          header = "#{badge('OPERATION')} #{paint(key_for(@klass), :bold)}  #{paint(@klass.name, :faint)}"
+          sections = [
+            (section('params', params, count: parameters.size) if parameters.any?),
+            (section('uses', uses) if dependencies.any?),
+            section('flow', @klass.flow.steps.any? ? flow : [paint('empty', :faint)])
+          ]
+          [header, *sections.compact.flatten].join("\n")
+        end
+
+        private
+
+        def parameters = @klass.respond_to?(:base_parameter) ? @klass.base_parameter.configuration : {}
+
+        def dependencies = @klass.respond_to?(:dependencies) ? @klass.dependencies : []
+
+        def params
+          lines = aligned(parameters.map do |name, parameter|
+            [name.to_s, paint(type(parameter), :faint), *(paint('optional', :faint) if parameter.optional?),
+             *(paint('sensitive', :warn) if parameter.sensitive?)]
+          end)
+          cap(lines, MAX_PARAMS, 'params')
+        end
+
+        def type(parameter)
+          case parameter
+          when ThunderOperation::Parameters::HashParameter then hash_type(parameter.configuration.keys)
+          when ThunderOperation::Parameters::ArrayParameter
+            parameter.items ? "[#{type(parameter.items)}]" : 'Array'
+          else
+            parameter.type&.name&.demodulize || 'any'
+          end
+        end
+
+        # The first keys of a hash param: {street, city, zip, …}.
+        def hash_type(keys) = keys.empty? ? 'Hash' : "{#{keys.first(3).join(', ')}#{', …' if keys.size > 3}}"
+
+        def uses
+          aligned(dependencies.map do |dependency|
+            [paint(KIND_LABELS.fetch(dependency.kind, dependency.kind).to_s, :faint), dependency.path]
+          end)
+        end
+
+        def flow
+          @number = 0
+          @hidden = 0
+          lines = flow_lines(@klass.flow.steps, 0)
+          @more << paint("… #{@hidden} more steps", :faint) if @hidden.positive?
+          lines
+        end
+
+        # Past MAX_STEPS the numbered steps are counted, not listed; "… N more" takes the place of the first one left
+        # out. The steps that end the flow are always listed.
+        def flow_lines(steps, depth)
+          indent = STEP_INDENT * depth
+          steps.flat_map do |step|
+            case step
+            when ThunderOperation::Steps::Clause
+              heading = paint(step.send(:signature, step.name, step.args, step.kwargs), :bold)
+              ["#{indent}#{heading}", *flow_lines(step.steps, depth + 1)]
+            when ThunderOperation::Steps::Method
+              @number += 1
+              next ["#{indent}#{paint(@number.to_s.rjust(2), :faint)}  #{step.name}"] if @number <= MAX_STEPS
+
+              @hidden += 1
+              # Filled in by flow once the hidden steps are counted.
+              @hidden == 1 ? [@more = "#{indent}    "] : []
+            else
+              ["#{indent}    #{paint(step.to_s.sub(/\((.*)\)\z/, ' \1'), :ok)}"]
+            end
+          end
+        end
+
+        def cap(lines, max, name)
+          return lines if lines.size <= max
+
+          [*lines.first(max - 1), paint("… #{lines.size - (max - 1)} more #{name}", :faint)]
+        end
+      end
+    end
+  end
+end

data/lib/thunder/console/views/record.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module Thunder
+  class Console
+    module Views
+      # A record as a block: its key and primary key in the header (a uuid in full), the state and unsaved changes,
+      # then one row per filled attribute in schema order, a belongs_to key under the association's name, the nil
+      # attributes on one row and the timestamps on another.
+      #   =>  order  7c1e0b5a-3f2a-4d9e-8b1c-2a9f0e6d4c11  persisted · changed: status
+      #      │ number    ORD-2026-000431
+      #      │ status    "paid"  (was "pending")
+      #      │ customer  9d0f3a2b…  customer_id
+      #      │ nil       coupon_id, canceled_at, +6
+      class Record
+        include Format
+
+        MAX_ROWS = 20
+
+        def initialize(record)
+          @record = record
+          @klass = record.class
+        end
+
+        def call
+          [header, *rows(attribute_rows, indent: 3, guide: :accent)].join("\n")
+        end
+
+        private
+
+        def header
+          id = @record[@klass.primary_key] if @klass.primary_key
+          head = "#{badge(key_for(@klass))} "
+          head += "#{paint(uuid?(id) ? id : "##{id}", :bold)}  " if id
+          head + paint(state(screen_width - 3 - visible_size(head)), :faint)
+        end
+
+        # The changed attributes, or only how many when they do not fit the width left on the header line.
+        def state(width)
+          base = if @record.new_record? then 'new'
+                 elsif @record.destroyed? then 'destroyed'
+                 else 'persisted'
+                 end
+          changed = @record.changes_to_save.keys
+          return base if changed.empty?
+
+          full = "#{base} · changed: #{changed.join(', ')}"
+          full.size <= width ? full : "#{base} · #{changed.size} changed"
+        end
+
+        def attribute_rows
+          names = @record.attribute_names - [@klass.primary_key]
+          stamps = names & TIMESTAMPS
+          nils, filled = (names - stamps).partition { |name| @record[name].nil? }
+          labels = filled.map { |name| label(name) }
+          width = screen_width - MARGIN - [*labels, 'timestamps'].map(&:size).max - 2
+
+          rows = filled.zip(labels).map { |name, label| [label, attribute(name, width)] }
+          [
+            *cap(rows, MAX_ROWS, ' · .attributes for all'),
+            (['nil', list(nils, width)] if nils.any?),
+            (['timestamps', timestamps(stamps, width)] if stamps.any?)
+          ]
+        end
+
+        def label(name) = foreign_keys.fetch(name, name)
+
+        def foreign_keys
+          @foreign_keys ||= @klass.reflect_on_all_associations(:belongs_to).to_h do |association|
+            [association.foreign_key.to_s, association.name.to_s]
+          end
+        end
+
+        def attribute(name, width)
+          value = @record[name]
+          change = @record.changes_to_save[name]
+          was = change ? "  (was #{truncate(change.first.inspect, 30)})" : ''
+          text = if foreign_keys.key?(name) then "#{paint(short_id(value), :bold)}  #{paint(name, :faint)}"
+                 else value_text(value, width - was.size)
+                 end
+          "#{text}#{paint(was, :faint)}"
+        end
+
+        def timestamps(stamps, width)
+          parts = stamps.map do |name|
+            value = @record[name]
+            "#{paint(name.delete_suffix('_at'), :faint)} #{value ? value_text(value, 20) : paint('nil', :faint)}"
+          end
+          line = parts.join(paint(' · ', :faint))
+          visible_size(line) <= width ? line : parts.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/thunder/console/views.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'views/layout'
+require_relative 'views/format'
+require_relative 'views/record'
+require_relative 'views/collection'
+require_relative 'views/model'
+require_relative 'views/operation'
+
+# WARN: AI MADE
+module Thunder
+  class Console
+    # How the console prints the framework's own objects: records, relations and arrays of records, model classes and
+    # operation classes. Anything else goes to Pretty.
+    module Views
+      extend Format
+
+      # The view for the value; nil when it has none.
+      def self.for(value)
+        case value
+        when ActiveRecord::Base then Record.new(value)
+        when ActiveRecord::Relation then Collection.new(value)
+        when Array then Collection.new(value) if Collection.records?(value)
+        when Class then class_view(value)
+        end
+      end
+
+      def self.class_view(klass)
+        if klass < ActiveRecord::Base && !klass.abstract_class? then Model.new(klass)
+        elsif klass < ThunderOperation::Base then Operation.new(klass)
+        end
+      end
+
+      # A record inside a hash or an array: its key and id ("book #1", "order 7c1e0b5a…").
+      def self.reference(record)
+        id = record[record.class.primary_key] if record.class.primary_key
+        id = if id.nil? then 'new'
+             elsif uuid?(id) then short_id(id)
+             else "##{id}"
+             end
+        paint("#{key_for(record.class)} #{id}", :accent)
+      end
+    end
+  end
+end

data/lib/thunder/console.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'irb'
+
+require_relative 'console/theme'
+require_relative 'console/prompt'
+require_relative 'console/banner'
+require_relative 'console/evaluation'
+require_relative 'console/pretty'
+require_relative 'console/views'
+require_relative 'console/inspector'
+require_relative 'console/completion'
+require_relative 'console/constants'
+require_relative 'console/backtrace'
+require_relative 'console/help'
+require_relative 'console/helpers'
+
+# WARN: AI MADE
+module Thunder
+  # IRB with one chunk of the application booted. `chunk :name` restarts the process on another chunk, so a console
+  # never holds two chunks: no constants, connection or records of the previous one, and each chunk keeps its own
+  # bundle.
+  class Console
+    include Theme
+
+    # Commands kept from IRB; the rest (ls, cd, show_source, edit, debug...) are removed.
+    IRB_COMMANDS = %i[exit exit!].freeze
+
+    IRB::Inspector.def_inspector(:thunder) do |value, colorize: true|
+      Console.current.inspector.call(value, colorize:)
+    end
+
+    class << self
+      attr_accessor :current
+    end
+
+    attr_reader :application, :chunk, :env, :evaluation, :inspector
+
+    def initialize(application, chunk_name, env:)
+      @application = application
+      @env = env
+      @chunk = chunk_name && application.chunk(chunk_name)
+      @used = []
+      @constants = Constants.new
+      @prompt = Prompt.new(self)
+      @evaluation = Evaluation.new(@prompt)
+      @inspector = Inspector.new(self)
+    end
+
+    def start
+      self.class.current = self
+      ENV['THUNDER_ENV'] = env
+      # The console gem (async) logs nothing here: 5 is above fatal. CONSOLE_LEVEL=info turns it on.
+      ENV['CONSOLE_LEVEL'] ||= '5'
+      puts Banner.new(self).lines(boot_error: chunk && boot)
+
+      TOPLEVEL_BINDING.receiver.extend(Helpers)
+      IRB.setup(nil, argv: [])
+      configure_irb
+
+      irb = IRB::Irb.new
+      install_completion(irb.context.io)
+      irb.run(IRB.conf)
+    end
+
+    def within_chunk
+      return yield(self) if chunk
+
+      puts paint("no chunk selected; chunks: #{chunks_list} (chunk :name)", :warn)
+    end
+
+    def use!(kind, key) = selected_chunk.registry.get!(kind, key)
+
+    # Defines the key's path constant on Object: 'book' -> Book, 'books.add' -> Books::Add. reload! repoints it.
+    # false when the key is not registered or its path hits a constant use did not define (see Constants); use! still
+    # returns the class.
+    def use(kind, key) # rubocop:disable Naming/PredicateMethod -- a console helper named like the DSL, returning true/false
+      klass = selected_chunk.registry.get(kind, key)
+      return false unless klass
+
+      if (taken = @constants.define(key, klass))
+        puts paint("#{taken} already exists; use! #{kind.inspect}, '#{key}' returns the class", :warn)
+        return false
+      end
+
+      @used << [kind, key] unless @used.include?([kind, key])
+      true
+    end
+
+    def reload!
+      @constants.clear
+      error = boot
+      return puts(paint("✗ boot failed: #{error.class}: #{error.message.lines.first.to_s.strip}", :fail)) if error
+
+      puts paint('reloaded', :ok)
+      @used.each { |kind, key| use(kind, key) }
+      nil
+    end
+
+    def toggle_sql_log
+      evaluation.sql_log = !evaluation.sql_log
+      puts paint("sql log #{evaluation.sql_log ? 'on' : 'off'}", :muted)
+    end
+
+    # Replaces this process with a console on another chunk. An unknown name prints the chunks and keeps the current
+    # one.
+    def change_chunk(name)
+      application.chunk(name)
+      save_history
+
+      ruby_flags = defined?(DEBUGGER__) ? ['-rdebug'] : []
+      exec(RbConfig.ruby, *ruby_flags, $PROGRAM_NAME, 'console', '-c', name.to_s, '--env', env)
+    rescue Error => e
+      puts paint(e.message, :warn)
+    end
+
+    private
+
+    # nil when the chunk booted, the error otherwise.
+    def boot
+      selected_chunk.boot
+      nil
+    rescue StandardError, ScriptError => e
+      e
+    end
+
+    def selected_chunk
+      chunk || raise(Error, "no chunk selected; chunks: #{chunks_list} (chunk :name)")
+    end
+
+    def chunks_list = application.chunks.map(&:identifier).join(', ')
+
+    def configure_irb
+      restrict_commands
+      evaluation.install
+      IRB.conf[:INSPECT_MODE] = :thunder
+      IRB.conf[:NEWLINE_BEFORE_MULTILINE_OUTPUT] = false
+      IRB.conf[:PROMPT][:THUNDER] = @prompt.irb_prompts
+      IRB.conf[:PROMPT_MODE] = :THUNDER
+      IRB.conf[:BACKTRACE_FILTER] = Backtrace.new(application.root)
+    end
+
+    # IRB keeps commands in a global registry and caches which names they override; both are reset here, as IRB's own
+    # registration does. Internal API of irb 1.18.
+    def restrict_commands
+      IRB::Command.commands.select! { |name, _| IRB_COMMANDS.include?(name) }
+      IRB::Command.register(:help, Help)
+      IRB::Command.class_variable_set(:@@command_override_policies, nil) # rubocop:disable Style/ClassVars -- IRB's cache
+      IRB::HelperMethod.helper_methods.each_key do |name|
+        IRB::HelpersContainer.send(:remove_method, name) if IRB::HelpersContainer.method_defined?(name)
+      end
+      IRB::HelperMethod.helper_methods.clear
+      IRB.conf[:COMMAND_ALIASES] = {}
+    end
+
+    # Only the Reline input method has a completor; a non-terminal stdin uses another one.
+    def install_completion(io)
+      completor = io.instance_variable_get(:@completor)
+      completor&.singleton_class&.prepend(Completion)
+    end
+
+    def save_history
+      io = IRB.CurrentContext&.io
+      io.save_history if io.respond_to?(:save_history)
+    end
+  end
+end

data/lib/thunder/generator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+require 'erb'
+require 'pathname'
+
+module Thunder
+  # Writes files from the templates in lib/thunder/templates. A `.erb` file is rendered with the locals and loses the
+  # extension; a leading `_` in a name becomes a dot (`_gitignore` -> `.gitignore`), so the gem packages it.
+  # Nothing is written when a target exists, unless force is given.
+  class Generator
+    TEMPLATES = Pathname(__dir__).join('templates')
+
+    # The repository of the framework, for the Gemfile of a generated app while the gems are not published.
+    FRAMEWORK_ROOT = Pathname(__dir__).join('../../..').expand_path
+
+    def initialize(root, force: false, out: $stdout)
+      @root = Pathname(root)
+      @force = force
+      @out = out
+    end
+
+    # Renders one template into target, relative to the root. namespace wraps the result in those modules.
+    def template(source, target, namespace: [], **locals)
+      write({ @root.join(target) => [nest(namespace, render(TEMPLATES.join(source), locals)), nil] })
+    end
+
+    # Copies a template directory into target, relative to the root.
+    def directory(source, target, **locals)
+      source = TEMPLATES.join(source)
+      files = source.glob('**/*', File::FNM_DOTMATCH).select(&:file?).to_h do |file|
+        path = file.relative_path_from(source).to_s.gsub(%r{(\A|/)_}, '\1.').delete_suffix('.erb')
+
+        [@root.join(target, path), [render(file, locals), file.stat.mode]]
+      end
+
+      write(files)
+    end
+
+    private
+
+    def render(file, locals)
+      file.extname == '.erb' ? ERB.new(file.read, trim_mode: '-').result_with_hash(locals) : file.read
+    end
+
+    # Each module opens one level more; the code goes inside the last one.
+    def nest(namespace, code)
+      return code if namespace.empty?
+
+      inner = nest(namespace.drop(1), code).gsub(/^(?=.)/, '  ')
+
+      "module #{namespace.first}\n#{inner}end\n"
+    end
+
+    def write(files)
+      existing = files.keys.select(&:exist?)
+      if existing.any? && !@force
+        raise Error, "#{existing.map { |path| relative(path) }.join(', ')} already exists (--force overwrites)"
+      end
+
+      files.each do |path, (content, mode)|
+        path.dirname.mkpath
+        path.write(content)
+        path.chmod(mode) if mode
+        @out.puts "create  #{relative(path)}"
+      end
+    end
+
+    def relative(path)
+      path.expand_path.relative_path_from(Pathname.pwd).to_s
+    end
+  end
+end

data/lib/thunder/templates/chunk/app/common/models/application_model.rb.erb

@@ -0,0 +1,4 @@
+<%# WARN: AI MADE -%>
+class ApplicationModel < ThunderChunk::Model
+  self.abstract_class = true
+end

data/lib/thunder/templates/chunk/app/common/operations/external_operation.rb.erb

@@ -0,0 +1,3 @@
+<%# WARN: AI MADE -%>
+class ExternalOperation < ThunderChunk::Operations::External
+end

data/lib/thunder/templates/chunk/app/common/operations/internal_operation.rb.erb

@@ -0,0 +1,3 @@
+<%# WARN: AI MADE -%>
+class InternalOperation < ThunderChunk::Operations::Internal
+end

data/lib/thunder/templates/chunk/config/chunk.rb.erb

@@ -0,0 +1,9 @@
+<%# WARN: AI MADE -%>
+ThunderChunk::Configuration.new do
+  # Database name: <%= chunk_name %>_<env> unless database.database is given.
+  database.adapter = 'postgresql'
+  database.host = ENV.fetch('POSTGRES_HOST', '127.0.0.1')
+  database.port = Integer(ENV.fetch('POSTGRES_PORT', 5432))
+  database.username = ENV.fetch('POSTGRES_USERNAME', 'postgres')
+  database.password = ENV.fetch('POSTGRES_PASSWORD', 'password')
+end

data/lib/thunder/templates/event/event.rb.erb

@@ -0,0 +1,6 @@
+<%# WARN: AI MADE -%>
+class <%= class_name %> < ThunderChunk::Event
+<% fields.each do |name, type, optional| -%>
+  field :<%= name %>, <%= type %><%= ', optional: true' if optional %>
+<% end -%>
+end

data/lib/thunder/templates/model/migration.rb.erb

@@ -0,0 +1,17 @@
+<%# WARN: AI MADE -%>
+# frozen_string_literal: true
+
+class <%= migration_class %> < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    create_table :<%= table_name %>, id: :uuid do |t|
+<% columns.each do |name, type| -%>
+<% if type == 'references' -%>
+      t.references :<%= name %>, foreign_key: true, type: :uuid
+<% else -%>
+      t.<%= type %> :<%= name %>
+<% end -%>
+<% end -%>
+      t.timestamps
+    end
+  end
+end

data/lib/thunder/templates/model/model.rb.erb

@@ -0,0 +1,6 @@
+<%# WARN: AI MADE -%>
+class <%= class_name %> < <%= parent %>
+<% references.each do |name| -%>
+  belongs_to :<%= name %>
+<% end -%>
+end

data/lib/thunder/templates/new/Gemfile.erb

@@ -0,0 +1,21 @@
+<%# WARN: AI MADE -%>
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+<% if framework_path -%>
+# The gems of the framework from its repository, while they are not published.
+<% %w[thunderfoundation thunderframe thunderoperation thunderchunk thunderwire thunder thunderspec].each do |gem| -%>
+gem '<%= gem %>', path: '<%= framework_path %>/<%= gem %>'
+<% end -%>
+gem 'thunderbolt', path: '<%= framework_path %>'
+<% else -%>
+gem 'thunderbolt'
+<% end -%>
+
+gem 'pg'
+
+# The chunks' specs, run by `thunder spec`.
+group :test do
+  gem 'thunderspec', require: false
+end

data/lib/thunder/templates/new/README.md.erb

@@ -0,0 +1,8 @@
+<%# WARN: AI MADE -%>
+# <%= app_name %>
+
+```sh
+thunder generate chunk NAME   # a chunk in chunks/NAME
+thunder db setup              # creates and migrates the database of every chunk
+thunder console -c NAME
+```

data/lib/thunder/templates/new/_gitignore.erb

@@ -0,0 +1,4 @@
+<%# WARN: AI MADE -%>
+/log/
+/tmp/
+.env

data/lib/thunder/templates/new/_ruby-version.erb

@@ -0,0 +1,2 @@
+<%# WARN: AI MADE -%>
+<%= ruby_version %>

data/lib/thunder/templates/new/bin/thunder.erb

@@ -0,0 +1,6 @@
+<%# WARN: AI MADE -%>
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+load Gem.bin_path('thunder', 'thunder')

data/lib/thunder/templates/operation/external.rb.erb

@@ -0,0 +1,24 @@
+<%# WARN: AI MADE -%>
+class <%= class_name %> < <%= parent %>
+<% params.each do |name, type, optional| -%>
+  param :<%= name %>, <%= type %><%= ', optional: true' if optional %>
+<% end -%>
+<% uses.each do |line| -%>
+  <%= line %>
+<% end -%>
+<% unless params.empty? && uses.empty? -%>
+
+<% end -%>
+  flow do
+    success
+  end
+
+  steps do
+  end
+
+  returns Hash do
+<% returns.each do |name, type| -%>
+    field :<%= name %>, <%= type %>
+<% end -%>
+  end
+end

data/lib/thunder/templates/operation/internal.rb.erb

@@ -0,0 +1,26 @@
+<%# WARN: AI MADE -%>
+class <%= class_name %> < <%= parent %>
+<% params.each do |name, type, optional| -%>
+  param :<%= name %>, <%= type %><%= ', optional: true' if optional %>
+<% end -%>
+<% uses.each do |line| -%>
+  <%= line %>
+<% end -%>
+<% unless params.empty? && uses.empty? -%>
+
+<% end -%>
+  flow do
+    success
+  end
+
+  steps do
+  end
+<% unless returns.empty? -%>
+
+  returns Hash do
+<% returns.each do |name, type| -%>
+    field :<%= name %>, <%= type %>
+<% end -%>
+  end
+<% end -%>
+end