charming 0.1.1 → 0.1.2

data/lib/charming/database_commands.rb

@@ -3,13 +3,19 @@
 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
@@ -23,8 +29,10 @@ module Charming
 
     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
@@ -33,18 +41,21 @@ module Charming
       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!
@@ -52,6 +63,7 @@ module Charming
       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")
@@ -61,6 +73,7 @@ module Charming
       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)
@@ -68,14 +81,17 @@ module Charming
       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
 

data/lib/charming/database_installer.rb

@@ -3,7 +3,13 @@
 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
@@ -11,6 +17,9 @@ module Charming
       @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"
 
@@ -25,8 +34,11 @@ module Charming
 
     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)
@@ -39,6 +51,8 @@ module Charming
       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}/**/*")')
@@ -47,6 +61,8 @@ module Charming
       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
@@ -61,6 +77,8 @@ module Charming
       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)
 
@@ -72,6 +90,8 @@ module Charming
       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}"))
 
@@ -79,6 +99,8 @@ module Charming
       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
 
@@ -95,6 +117,7 @@ ActiveRecord::Base.establish_connection(
 )
     end
 
+    # The contents of the new `app/models/application_record.rb` (abstract ActiveRecord base).
     def application_record
       %(# frozen_string_literal: true
 
@@ -106,18 +129,22 @@ 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

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

data/lib/charming/generators/app_generator.rb

@@ -2,94 +2,170 @@
 
 module Charming
   module Generators
+    # AppGenerator implements `charming new NAME`. Writes a complete Bundler-gem-style
+    # Charming app skeleton: Gemfile, Rakefile, gemspec, exe, lib root + application +
+    # version, config/routes.rb, app/state, app/controllers, app/views/layouts + home view,
+    # and a baseline spec/ tree. Optionally also creates the database files when
+    # `database:` is set.
     class AppGenerator < Base
-      include BasicTemplates
-      include ComponentTemplates
-      include ControllerTemplate
-      include DatabaseTemplates
-      include LayoutTemplate
-      include StateTemplates
-      include ScreenSpecTemplates
-      include ViewTemplate
-      include AppSpecTemplates
-
+      # The list of [relative-path, template-path, executable-flag] triples to render
+      # for a non-database app.
       BASE_FILE_TEMPLATES = [
-        ["Gemfile", :gemfile],
-        ["Rakefile", :rakefile],
-        ["README.md", :readme],
-        ["%<name>s.gemspec", :gemspec],
-        ["exe/%<name>s", :executable],
-        ["lib/%<name>s.rb", :root_file],
-        ["lib/%<name>s/application.rb", :application],
-        ["lib/%<name>s/version.rb", :version],
-        ["config/routes.rb", :routes],
-        ["app/state/application_state.rb", :application_state],
-        ["app/state/home_state.rb", :home_state],
-        ["app/controllers/application_controller.rb", :application_controller],
-        ["app/controllers/home_controller.rb", :controller],
-        ["app/views/layouts/application.tui.erb", :layout],
-        ["app/views/home/show.tui.erb", :view],
-        ["app/components/app_frame_component.rb", :component],
-        ["spec/spec_helper.rb", :spec_helper],
-        ["spec/state/home_state_spec.rb", :spec_state],
-        ["spec/controllers/home_controller_spec.rb", :spec_controller],
-        ["spec/views/home/show_template_spec.rb", :spec_view],
-        ["spec/components/app_frame_component_spec.rb", :spec_component]
+        ["Gemfile", "app/Gemfile.template", false],
+        ["Rakefile", "app/Rakefile.template", false],
+        ["README.md", "app/README.md.template", false],
+        ["%<name>s.gemspec", "app/gemspec.template", false],
+        ["exe/%<name>s", "app/executable.template", true],
+        ["lib/%<name>s.rb", "app/root_file.template", false],
+        ["lib/%<name>s/application.rb", "app/application.template", false],
+        ["lib/%<name>s/version.rb", "app/version.template", false],
+        ["config/routes.rb", "app/routes.template", false],
+        ["app/state/application_state.rb", "app/application_state.template", false],
+        ["app/state/home_state.rb", "app/home_state.template", false],
+        ["app/controllers/application_controller.rb", "app/application_controller.template", false],
+        ["app/controllers/home_controller.rb", "app/home_controller.template", false],
+        ["app/views/layouts/application_layout.rb", "app/layout.template", false],
+        ["app/views/home/show_view.rb", "app/view.template", false],
+        ["app/components/.keep", "app/keep.template", false],
+        ["spec/spec_helper.rb", "app/spec_helper.template", false],
+        ["spec/state/home_state_spec.rb", "app/spec_state.template", false],
+        ["spec/controllers/home_controller_spec.rb", "app/spec_controller.template", false],
+        ["spec/views/home/show_view_spec.rb", "app/spec_view.template", false]
       ].freeze
 
+      # The list of [relative-path, template-path, executable-flag] triples to render in
+      # addition to the base list when `database:` is set on the generator.
       DATABASE_FILE_TEMPLATES = [
-        ["config/database.rb", :database_config],
-        ["app/models/application_record.rb", :application_record],
-        ["db/migrate/.keep", :keep],
-        ["db/seeds.rb", :seeds]
+        ["config/database.rb", "app/database_config.template", false],
+        ["app/models/application_record.rb", "app/application_record.template", false],
+        ["db/migrate/.keep", "app/keep.template", false],
+        ["db/seeds.rb", "app/seeds.template", false]
       ].freeze
 
+      # *name* is the new app's name. *out* is the status stream. *destination* is the
+      # parent directory under which `<name>/` will be created. *force* allows overwriting
+      # existing files. *database* optionally enables the database template set.
       def initialize(name, out:, destination:, force: false, database: nil)
         super(out: out, destination: File.join(destination, name), force: force)
         @name = Name.new(name)
         @database = database
       end
 
+      # Renders every template in the chosen template list (base + optional database)
+      # and writes the files, then initializes a git repository in the new app directory.
       def generate
-        file_templates.each do |path, template|
-          create_file(file_path(path), send(template), executable: template == :executable)
+        file_templates.each do |path, template_path, executable|
+          create_file(file_path(path), render_app_template(template_path), executable: executable)
         end
         initialize_git_repository
       end
 
       private
 
+      # The resource name and the database adapter name (or nil).
       attr_reader :name, :database
       alias_method :app_name, :name
 
+      # True when the database template set should be rendered.
       def database?
         !!database
       end
 
+      # Returns the template list: base only, or base + database extras.
       def file_templates
         database? ? BASE_FILE_TEMPLATES + DATABASE_FILE_TEMPLATES : BASE_FILE_TEMPLATES
       end
 
+      # Substitutes `name.snake_name` into a relative-path template (paths use `%<name>s`).
       def file_path(path)
         format(path, name: name.snake_name)
       end
 
-      def routes
-        %(# frozen_string_literal: true
+      # Renders an app template file by replacing `__TOKEN__` placeholders with the
+      # appropriate values derived from the current *name* and *database* setting.
+      def render_app_template(relative_path)
+        render_template(relative_path, **app_template_tokens)
+      end
 
-#{name.class_name}::Application.routes do
-  root "home#show"
-end
-)
+      # Returns the token map used to render every app template.
+      def app_template_tokens
+        {
+          app_name: name.class_name,
+          app_snake: name.snake_name,
+          app_class: name.class_name,
+          gemspec_attributes: gemspec_attributes,
+          gemspec_dependencies: gemspec_dependencies,
+          controller_actions: controller_actions,
+          controller_helpers: controller_helpers,
+          database_require: database_require,
+          model_loader: model_loader
+        }
+      end
+
+      # The `Gem::Specification` attributes block (indented two spaces to match the wrapping
+      # `Gem::Specification.new do |spec|`).
+      def gemspec_attributes
+        "  spec.name = \"#{name.snake_name}\"\n" \
+          "  spec.version = #{name.class_name}::VERSION\n" \
+          "  spec.summary = \"A Charming terminal user interface.\"\n" \
+          "  spec.authors = [\"TODO: Your name\"]\n" \
+          "  spec.email = [\"TODO: Your email\"]\n" \
+          "  spec.files = Dir.glob(\"#{gemspec_file_glob}/**/*\") + %w[README.md]\n" \
+          "  spec.bindir = \"exe\"\n" \
+          "  spec.executables = [\"#{name.snake_name}\"]\n" \
+          "  spec.require_paths = [\"lib\"]\n" \
+          "  spec.required_ruby_version = \">= 4.0.0\"\n" \
+          "  spec.metadata[\"rubygems_mfa_required\"] = \"true\""
+      end
+
+      # The `Gem::Specification` `add_dependency` lines (trailing newline).
+      def gemspec_dependencies
+        "\n  spec.add_dependency \"charming\"#{database_dependencies}\n"
+      end
+
+      # The file glob used by the gemspec to enumerate packaged files.
+      def gemspec_file_glob
+        database? ? "{app,config,db,exe,lib}" : "{app,config,exe,lib}"
+      end
+
+      # The optional `activerecord`/`sqlite3` dependency lines (with leading newlines and
+      # trailing newline) when the app is database-configured; otherwise an empty string.
+      def database_dependencies
+        return "" unless database?
+
+        "\n  spec.add_dependency \"activerecord\", \"~> 8.1\"\n" \
+          "  spec.add_dependency \"sqlite3\", \"~> 2.0\""
+      end
+
+      # The body of the home controller's `show` action.
+      def controller_actions
+        "\n    def show\n" \
+          "      render :show, home: home, palette: command_palette\n" \
+          "    end"
+      end
+
+      # The body of the home controller's private `home` helper, prefixed by a blank line.
+      def controller_helpers
+        "\n\n    private\n" \
+          "    def home\n" \
+          "      state(:home, HomeState)\n" \
+          "    end"
+      end
+
+      # The `require_relative "../config/database"` line when the app is database-configured.
+      def database_require
+        database? ? "require_relative \"../config/database\"" : ""
       end
 
-      def spec_helper
-        %(# frozen_string_literal: true
+      # The model loader `push_dir` line (with trailing newline) when the app is
+      # database-configured; otherwise an empty string.
+      def model_loader
+        return "" unless database?
 
-require "#{name.snake_name}"
-)
+        "loader.push_dir(File.expand_path(\"../app/models\", __dir__), namespace: #{name.class_name})\n"
       end
 
+      # Initializes a git repository in the new app's directory. Raises Error on failure.
       def initialize_git_repository
         unless system("git", "init", chdir: destination, out: File::NULL, err: File::NULL)
           raise Error, "Could not initialize git repository"

data/lib/charming/generators/base.rb

@@ -4,7 +4,13 @@ require "fileutils"
 
 module Charming
   module Generators
+    # Base is the parent class for all Charming file generators. Subclasses implement
+    # `generate` to write the appropriate files. The base class provides `create_file`,
+    # which writes content to a path under the configured *destination* and refuses to
+    # overwrite existing files unless *force* was set.
     class Base
+      # *out* is the status-output stream. *destination* is the app root for generated files.
+      # *force* (default false) allows overwriting existing files.
       def initialize(out:, destination:, force: false)
         @out = out
         @destination = destination
@@ -13,8 +19,12 @@ module Charming
 
       private
 
+      # Status output stream and destination directory accessor (subclasses use these).
       attr_reader :out, :destination
 
+      # Writes *content* to *path* (relative to the destination), creating intermediate
+      # directories as needed. Raises Generators::Error when the file already exists and
+      # *force* is false. Marks the file as executable when *executable:* is true.
       def create_file(path, content, executable: false)
         absolute_path = File.join(destination, path)
         raise Error, "File already exists: #{path}" if File.exist?(absolute_path) && !@force
@@ -24,6 +34,22 @@ module Charming
         FileUtils.chmod("u+x,go+rx", absolute_path) if executable
         out.puts "create #{path}"
       end
+
+      # Renders a template file by replacing `__TOKEN__` placeholders with values from
+      # *tokens*. *template_path* is relative to the generators templates directory.
+      def render_template(template_path, **tokens)
+        body = File.read(template_file(template_path))
+        tokens.each do |key, value|
+          body = body.gsub("__#{key.to_s.upcase}__", value.to_s)
+        end
+        body
+      end
+
+      # Absolute path to a generator template file. *relative_path* is relative to the
+      # generators templates directory.
+      def template_file(relative_path)
+        File.join(__dir__, "templates", relative_path)
+      end
     end
   end
 end

data/lib/charming/generators/component_generator.rb

@@ -2,28 +2,28 @@
 
 module Charming
   module Generators
+    # ComponentGenerator implements `charming generate component NAME`. Writes a
+    # `Charming::Presentation::Component` subclass to `app/components/<name>_component.rb`.
     class ComponentGenerator < AppFileGenerator
+      # Writes the component file to the standard `app/components` path.
       def generate
         create_file(app_path("app", "components"), component)
       end
 
       private
 
+      # The file-name suffix used by `app_path` (sets "component" so the file is
+      # `<name>_component.rb`).
       def suffix
         "component"
       end
 
+      # The full source of the generated component class.
       def component
-        %(# frozen_string_literal: true
-
-module #{app_name.class_name}
-  class #{name.component_class_name} < Charming::Presentation::Component
-    def render
-      text "#{name.class_name}"
-    end
-  end
-end
-)
+        render_template("component/component.rb.template",
+          app_class: app_name.class_name,
+          component_class: name.component_class_name,
+          resource_name: name.class_name)
       end
     end
   end