charming 0.1.0 → 0.1.2

data/lib/charming/database_commands.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Charming
+  # DatabaseCommands implements the runtime side of `charming db:COMMAND` (other than
+  # `db:install`, which lives in DatabaseInstaller). It loads the app's `config/database.rb`,
+  # delegates the actual work to ActiveRecord, and prints a short status line on success.
+  class DatabaseCommands
+    # *command* is the subcommand string (e.g., "db:create"). *out* is the status-output
+    # stream. *destination* is the app root for resolving `config/database.rb` and `db/`.
+    def initialize(command, out:, destination:)
+      @command = command
+      @out = out
+      @destination = destination
+    end
+
+    # Dispatches the configured command. Raises Generators::Error for unknown commands.
+    def run
+      case command
+      when "db:create" then create
+      when "db:migrate" then migrate
+      when "db:rollback" then rollback
+      when "db:drop" then drop
+      when "db:seed" then seed
+      else raise Generators::Error, "Unknown database command: #{command}"
+      end
+    end
+
+    private
+
+    # The subcommand, output stream, and app destination.
+    attr_reader :command, :out, :destination
+
+    # Creates the SQLite database file (touch) and establishes the connection.
+    def create
+      load_database
+      FileUtils.mkdir_p(File.dirname(database_path)) if database_path
+      FileUtils.touch(database_path) if database_path
+      ActiveRecord::Base.connection
+      out.puts "create #{relative_database_path}"
+    end
+
+    # Runs all pending migrations from `db/migrate`.
+    def migrate
+      load_database
+      migration_context.migrate
+      out.puts "migrate db/migrate"
+    end
+
+    # Rolls back the most recent migration.
+    def rollback
+      load_database
+      migration_context.rollback(1)
+      out.puts "rollback db/migrate"
+    end
+
+    # Disconnects ActiveRecord, then deletes the database file.
+    def drop
+      load_database
+      ActiveRecord::Base.connection.disconnect!
+      File.delete(database_path) if database_path && File.exist?(database_path)
+      out.puts "drop #{relative_database_path}"
+    end
+
+    # Loads `db/seeds.rb` (raises if missing).
+    def seed
+      load_database
+      seed_path = File.join(destination, "db", "seeds.rb")
+      raise Generators::Error, "Missing file: db/seeds.rb" unless File.exist?(seed_path)
+
+      load seed_path
+      out.puts "seed db/seeds.rb"
+    end
+
+    # Loads the app's `config/database.rb` (raises if missing) which establishes the connection.
+    def load_database
+      database_config = File.join(destination, "config", "database.rb")
+      raise Generators::Error, "Database support is not configured. Missing config/database.rb." unless File.exist?(database_config)
+
+      require database_config
+    end
+
+    # The ActiveRecord migration context rooted at `db/migrate` inside the app.
+    def migration_context
+      ActiveRecord::MigrationContext.new(File.join(destination, "db", "migrate"))
+    end
+
+    # The configured database file path (nil when ActiveRecord isn't connected to a file).
+    def database_path
+      ActiveRecord::Base.connection_db_config.database
+    end
+
+    # The database path relative to the app root, used for human-friendly status output.
+    def relative_database_path
+      return "database" unless database_path
+
+      base = File.realpath(destination)
+      path = File.expand_path(database_path)
+      path.start_with?("#{base}/") ? path.delete_prefix("#{base}/") : path
+    end
+  end
+end

data/lib/charming/database_installer.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Charming
+  # DatabaseInstaller implements `charming db:install sqlite3`. It adds database support
+  # to an existing Charming app by creating `config/database.rb`, `app/models/application_record.rb`,
+  # `db/migrate/`, and `db/seeds.rb`, and patching the gemspec and root loader to include
+  # the new dependencies and the `app/models` autoload directory.
+  class DatabaseInstaller
+    # *database* is the adapter name (only "sqlite3" is currently supported). *out* is the
+    # status-output stream. *destination* is the app root.
+    def initialize(database, out:, destination:)
+      @database = database
+      @out = out
+      @destination = destination
+      @app_name = Generators::Name.new(app_name_from_gemspec)
+    end
+
+    # Performs the install: writes the database config, application record, migrate directory,
+    # seeds file, and patches the gemspec + root loader. Idempotent: existing files are
+    # reported with "exist <path>" instead of being overwritten.
+    def install
+      raise Generators::Error, "Unsupported database: #{database.inspect}" unless database == "sqlite3"
+
+      create_file("config/database.rb", database_config)
+      create_file("app/models/application_record.rb", application_record)
+      create_file("db/migrate/.keep", "")
+      create_file("db/seeds.rb", %(# frozen_string_literal: true
+))
+      update_gemspec
+      update_root_file
+    end
+
+    private
+
+    # The database adapter, status stream, app destination, and derived app name.
+    attr_reader :database, :out, :destination, :app_name
+
+    # Writes *content* to *path* (relative to the app root), creating intermediate directories.
+    # Reports "exist <path>" without overwriting when the file already exists.
+    def create_file(path, content)
+      absolute_path = File.join(destination, path)
+      if File.exist?(absolute_path)
+        out.puts "exist #{path}"
+        return
+      end
+
+      FileUtils.mkdir_p(File.dirname(absolute_path))
+      File.write(absolute_path, content)
+      out.puts "create #{path}"
+    end
+
+    # Patches the gemspec to include the `db` directory in the gem files glob and to add
+    # activerecord + sqlite3 dependencies.
+    def update_gemspec
+      update_file(gemspec_path) do |current|
+        updated = current.sub('Dir.glob("{app,config,exe,lib}/**/*")', 'Dir.glob("{app,config,db,exe,lib}/**/*")')
+        updated = insert_dependency(updated, "activerecord", "~> 8.1")
+        insert_dependency(updated, "sqlite3", "~> 2.0")
+      end
+    end
+
+    # Patches the root loader file (`lib/<app>.rb`) to require `config/database` and to push
+    # the `app/models` autoload directory. Both edits are no-ops when already applied.
+    def update_root_file
+      update_file(root_file_path) do |current|
+        updated = current
+        updated = updated.sub(%(require "zeitwerk"\n), %(require "zeitwerk"\nrequire_relative "../config/database"\n)) unless updated.include?(%(require_relative "../config/database"))
+        unless updated.include?(%[loader.push_dir(File.expand_path("../app/models", __dir__), namespace: #{app_name.class_name})])
+          updated = updated.sub(
+            %[loader.push_dir(File.expand_path("../app/state", __dir__), namespace: #{app_name.class_name})\n],
+            %[loader.push_dir(File.expand_path("../app/models", __dir__), namespace: #{app_name.class_name})\nloader.push_dir(File.expand_path("../app/state", __dir__), namespace: #{app_name.class_name})\n]
+          )
+        end
+        updated
+      end
+    end
+
+    # Reads *path*, yields its contents to the block, and writes the result back when it
+    # differs. Raises Generators::Error when the file is missing.
+    def update_file(path)
+      raise Generators::Error, "Missing file: #{relative_path(path)}" unless File.exist?(path)
+
+      current = File.read(path)
+      updated = yield current
+      return if updated == current
+
+      File.write(path, updated)
+      out.puts "update #{relative_path(path)}"
+    end
+
+    # Inserts a `spec.add_dependency "name", "version"` line after the `charming` dependency
+    # when it's not already present.
+    def insert_dependency(content, gem_name, version)
+      return content if content.include?(%(spec.add_dependency "#{gem_name}"))
+
+      dependency = %(  spec.add_dependency "#{gem_name}", "#{version}")
+      content.sub(%(  spec.add_dependency "charming"\n), %(  spec.add_dependency "charming"\n#{dependency}\n))
+    end
+
+    # The contents of the new `config/database.rb` (establishes an SQLite connection to
+    # `db/development.sqlite3`).
+    def database_config
+      %(# frozen_string_literal: true
+
+require "active_record"
+require "fileutils"
+
+database_path = File.expand_path("../db/development.sqlite3", __dir__)
+FileUtils.mkdir_p(File.dirname(database_path))
+
+ActiveRecord::Base.establish_connection(
+  adapter: "sqlite3",
+  database: database_path
+)
+)
+    end
+
+    # The contents of the new `app/models/application_record.rb` (abstract ActiveRecord base).
+    def application_record
+      %(# frozen_string_literal: true
+
+module #{app_name.class_name}
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end
+)
+    end
+
+    # Reads the app's gemspec filename to derive the app name.
+    def app_name_from_gemspec
+      File.basename(gemspec_path, ".gemspec")
+    end
+
+    # The path to the app's gemspec (raises when not found).
+    def gemspec_path
+      @gemspec_path ||= Dir.glob(File.join(destination, "*.gemspec")).first || raise(Generators::Error, "Run this command from a Charming app root")
+    end
+
+    # The path to the app's root loader file (`lib/<app_name>.rb`).
+    def root_file_path
+      File.join(destination, "lib", "#{app_name.snake_name}.rb")
+    end
+
+    # Strips the app destination prefix from *path* for human-friendly status output.
+    def relative_path(path)
+      path.delete_prefix("#{destination}/")
+    end
+  end
+end

data/lib/charming/events/key_event.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # KeyEvent represents a terminal key press parsed by the backend. *key* is the normalized semantic
+    # action name (e.g., `:up`, `:down`, `:q`), while *char*, *ctrl*, *alt*, and *shift* capture raw
+    # input details for custom bindings.
+    KeyEvent = Data.define(:key, :char, :ctrl, :alt, :shift) do
+      # Constructs a key event with the required *key* symbol, plus optional *char* string and modifier booleans.
+      def initialize(key:, char: nil, ctrl: false, alt: false, shift: false)
+        super(key: key.to_sym, char: char, ctrl: ctrl, alt: alt, shift: shift)
+      end
+    end
+  end
+end

data/lib/charming/events/mouse_event.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # MOUSE_BUTTON_MAP encodes terminal mouse button codes to semantic symbols. The constant is frozen and private.
+    MOUSE_BUTTON_MAP = {
+      0 => :left, 1 => :middle, 2 => :right, 3 => :release,
+      64 => :scroll_up, 65 => :scroll_down,
+      66 => :scroll_up, 67 => :scroll_down
+    }.freeze
+    private_constant :MOUSE_BUTTON_MAP
+
+    # MouseEvent represents a mouse input event. *button* encodes which button or action was triggered (left,
+    # right, scroll), while *x* and *y* provide the cursor position. Modifier booleans (*ctrl*, *alt*, *shift*)
+    # capture key state at the time of the event.
+    MouseEvent = Data.define(:button, :x, :y, :ctrl, :alt, :shift) do
+      def initialize(button:, x:, y:, ctrl: false, alt: false, shift: false)
+        super
+      end
+
+      # Returns the semantic symbol for *button* — one of `left`, `right`, `scroll_up`, etc. or `:unknown`.
+      def button_name
+        MOUSE_BUTTON_MAP.fetch(button, :unknown)
+      end
+
+      # Returns `true` when the current event is a click (left, middle, or right button).
+      def click?
+        %i[left middle right].include?(button_name)
+      end
+
+      # Returns `true` when the button name maps to either direction of scroll.
+      def scroll?
+        %i[scroll_up scroll_down].include?(button_name)
+      end
+
+      # Returns `true` when the current event is a mouse release action.
+      def release?
+        button_name == :release
+      end
+    end
+  end
+end

data/lib/charming/events/resize_event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # ResizeEvent represents a terminal window resize. *width* and *height* carry the new terminal dimensions
+    # in screen cells, replacing the previous Screen dimensions for all subsequent rendering.
+    ResizeEvent = Data.define(:width, :height)
+  end
+end

data/lib/charming/events/task_event.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # TaskEvent represents background task completion. *name* is the declared task identifier, *value* carries
+    # the return result and *error* captures any exception raised during execution. The `error?` predicate
+    # simplifies error handling in controller handlers.
+    TaskEvent = Data.define(:name, :value, :error) do
+      def initialize(name:, value: nil, error: nil)
+        super
+      end
+
+      # Returns `true` when the task finished with a non-nil exception.
+      def error?
+        !error.nil?
+      end
+    end
+  end
+end

data/lib/charming/events/timer_event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # TimerEvent represents a timed dispatch from the runtime loop. *name* is the declared timer identifier;
+    # *now* is the monotonically rising clock value at emission for throttle comparisons.
+    TimerEvent = Data.define(:name, :now)
+  end
+end

data/lib/charming/focus.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 module Charming
+  # Focus manages a stack of focus scopes (rings) for a single controller class. Each scope has
+  # a slot ring (a fixed list of named slots) and a current slot within that ring. Multiple
+  # scopes can be stacked so the command palette, modals, and layouts can each have their own
+  # focus contexts without interfering with one another.
+  #
+  # State lives under `session[:focus_state][controller_class_name]` so focus persists across
+  # controller dispatches within the same session.
   class Focus
+    # Returns the Focus object for *controller_class* under the given *session*, creating the
+    # underlying session hash if absent.
     def self.for(session, controller_class)
       session[:focus_state] ||= {}
       key = controller_class.name
@@ -13,34 +22,54 @@ module Charming
       @state = state
     end
 
+    # Defines the primary focus ring for the controller with the given *slots*. Only effective
+    # the first time it is called; subsequent calls are no-ops.
     def define(slots)
       return if @state[:scopes].any? { |scope| scope[:origin] == :ring }
 
       @state[:scopes] << build_scope(slots, :ring)
     end
 
+    # Defines a layout scope (inserted after the primary ring and before modal scopes). *slots*
+    # is the list of pane names; the previously-focused layout slot is preserved when it is still
+    # part of the new ring.
+    def define_layout(slots)
+      current = current_layout_slot(slots)
+      remove_scope(:layout)
+      return if slots.empty?
+
+      @state[:scopes].insert(layout_scope_index, build_scope(slots, :layout, current))
+    end
+
+    # Pushes a new focus scope with the given *slots* onto the stack. Used by modals, palettes,
+    # and other overlays. *origin* is a label for the scope kind.
     def push_scope(slots, origin: :modal)
       @state[:scopes] << build_scope(slots, origin)
     end
 
+    # Pops the topmost focus scope from the stack.
     def pop_scope
       @state[:scopes].pop
     end
 
+    # Returns the currently focused slot, or nil when no scope is active.
     def current
       top && top[:current]
     end
 
+    # Returns the slot ring of the topmost scope (an array of slot names). Empty when no scope.
     def ring
       top ? top[:ring] : []
     end
 
+    # Sets the current slot within the topmost scope to *slot*. No-op when *slot* is not in the ring.
     def focus(slot)
       return unless ring.include?(slot)
 
       top[:current] = slot
     end
 
+    # Cycles focus by *direction* (default +1 forward) within the topmost ring. No-op on an empty ring.
     def cycle(direction = +1)
       return if ring.empty?
 
@@ -48,18 +77,45 @@ module Charming
       top[:current] = ring[(index + direction) % ring.length]
     end
 
+    # True when *slot* is the current focus slot.
     def focused?(slot)
       current == slot
     end
 
     private
 
+    # Returns the topmost scope hash (the last entry pushed onto `@state[:scopes]`).
     def top
       @state[:scopes].last
     end
 
-    def build_scope(slots, origin)
-      {ring: slots.dup.freeze, current: slots.first, origin: origin}
+    # Removes every scope whose origin equals *origin* (in place).
+    def remove_scope(origin)
+      @state[:scopes].reject! { |scope| scope[:origin] == origin }
+    end
+
+    # Returns the index in the scope stack where a layout scope belongs: just before the first
+    # non-ring, non-layout scope (i.e., at the end of the "structural" stack).
+    def layout_scope_index
+      index = @state[:scopes].index { |scope| !%i[ring layout].include?(scope[:origin]) }
+      index || @state[:scopes].length
+    end
+
+    # Returns the current layout scope's current slot, but only when it is still part of *slots*.
+    # Otherwise returns the first slot in *slots* (so a new layout reverts to its first pane).
+    def current_layout_slot(slots)
+      current_slot = current_layout_scope&.fetch(:current)
+      slots.include?(current_slot) ? current_slot : slots.first
+    end
+
+    # Returns the layout scope, or nil when no layout scope is present.
+    def current_layout_scope
+      @state[:scopes].find { |scope| scope[:origin] == :layout }
+    end
+
+    # Builds an immutable scope hash with the given *slots*, *origin*, and starting *current* slot.
+    def build_scope(slots, origin, current = slots.first)
+      {ring: slots.dup.freeze, current: current, origin: origin}
     end
   end
 end

data/lib/charming/generators/app_file_generator.rb

@@ -2,7 +2,14 @@
 
 module Charming
   module Generators
+    # AppFileGenerator is the parent class for "in-app" sub-generators (controller, model,
+    # screen, view, component) that run inside an existing Charming app. It derives the
+    # app's namespace from the local gemspec and exposes path-building helpers that put
+    # files under the right `app/...` subdirectory.
     class AppFileGenerator < Base
+      # *name* is the singular resource name (e.g., "user"). *_args* are subcommand-specific
+      # (e.g., controller actions or model fields). *out*, *destination*, and *force* are
+      # forwarded to Base.
       def initialize(name, _args, out:, destination:, force: false)
         super(out: out, destination: destination, force: force)
         @name = Name.new(name)
@@ -11,12 +18,18 @@ module Charming
 
       private
 
+      # The resource name and the parent app name (both wrapped in Generators::Name).
       attr_reader :name, :app_name
 
+      # Builds the full file path under `app/<dir>/<resource>_<suffix>.rb` for the
+      # configured *parts* (the immediate directory chain). The suffix is supplied by
+      # the subclass (controller, model, view, etc.).
       def app_path(*parts)
         File.join(*parts, "#{name.snake_name}_#{suffix}.rb")
       end
 
+      # Reads the gemspec filename from the destination directory to derive the app name.
+      # Raises Error when no gemspec is found.
       def app_name_from_gemspec
         gemspec = Dir.glob(File.join(destination, "*.gemspec")).first
         raise Error, "Run this generator from a Charming app root" unless gemspec