charming 0.1.1 → 0.1.2

data/lib/charming/generators/controller_generator.rb

@@ -2,45 +2,56 @@
 
 module Charming
   module Generators
+    # ControllerGenerator implements `charming generate controller NAME [ACTION ...]`.
+    # Writes `app/controllers/<name>_controller.rb` containing a class that inherits
+    # from the app's `ApplicationController` and a `show` (or named) action that renders
+    # the conventional view with the command palette passed as an assign.
     class ControllerGenerator < AppFileGenerator
+      # *name* is the resource name. *args* is the list of action names (defaults to `show`).
+      # *out*, *destination*, and *force* are forwarded to the parent.
       def initialize(name, args, out:, destination:, force: false)
         super
         @actions = args
       end
 
+      # Writes the controller file to the standard app/controllers path.
       def generate
         create_file(app_path("app", "controllers"), controller)
       end
 
       private
 
+      # The list of action names supplied on the command line.
       attr_reader :actions
 
+      # The file-name suffix used by `app_path` (sets "controller" so the file is
+      # `<name>_controller.rb`).
       def suffix
         "controller"
       end
 
+      # The full source of the generated controller file.
       def controller
-        %(# frozen_string_literal: true
-
-module #{app_name.class_name}
-  class #{name.controller_class_name} < ApplicationController
-#{action_methods}  end
-end
-)
+        render_template("controller/controller.rb.template",
+          app_class: app_name.class_name,
+          controller_class: name.controller_class_name,
+          action_methods: action_methods)
       end
 
+      # Renders one action method per action name; falls back to a single `show` action
+      # when no actions were specified.
       def action_methods
         return action_method("show") if actions.empty?
 
         actions.map { |action| action_method(action) }.join("\n")
       end
 
+      # Source for a single action method that renders the matching conventional view and
+      # passes the command palette as an assign.
       def action_method(action)
-        %(    def #{action}
-      render :#{action}, palette: command_palette
-    end
-)
+        "    def #{action}\n" \
+          "      render :#{action}, palette: command_palette\n" \
+          "    end\n"
       end
     end
   end

data/lib/charming/generators/model_generator.rb

@@ -2,15 +2,25 @@
 
 module Charming
   module Generators
+    # ModelGenerator implements `charming generate model NAME [name:type ...]`. Writes an
+    # ActiveRecord model class, a `Create<Table>` migration (with one column per supplied
+    # field), and a baseline spec. Requires the app to have been generated with
+    # `--database sqlite3`.
     class ModelGenerator < AppFileGenerator
+      # A single model field: column *name* and ActiveRecord *type* (e.g., "string").
       Field = Data.define(:name, :type)
+
+      # The set of ActiveRecord column types accepted on the command line.
       VALID_TYPES = %w[string text integer float decimal boolean date datetime time].freeze
 
+      # *name* is the resource name. *args* is the list of `name:type` field specifications.
       def initialize(name, args, out:, destination:, force: false)
         super
         @fields = args.map { |arg| parse_field(arg) }
       end
 
+      # Validates that the app is database-configured, then writes the model, migration,
+      # and spec files.
       def generate
         raise Error, "Database support is not configured. Generate the app with --database sqlite3 first." unless database_configured?
 
@@ -21,67 +31,61 @@ module Charming
 
       private
 
+      # The list of parsed Field entries supplied on the command line.
       attr_reader :fields
 
+      # No file-name suffix; ModelGenerator writes files to explicit paths.
       def suffix
         nil
       end
 
+      # Path to the generated `app/models/<name>.rb` file.
       def model_path
         File.join("app", "models", "#{name.snake_name}.rb")
       end
 
+      # Path to the generated `db/migrate/<timestamp>_create_<table>.rb` file.
       def migration_path
         File.join("db", "migrate", "#{timestamp}_create_#{table_name}.rb")
       end
 
+      # Path to the generated `spec/models/<name>_spec.rb` file.
       def spec_path
         File.join("spec", "models", "#{name.snake_name}_spec.rb")
       end
 
+      # The full source of the generated ActiveRecord model class.
       def model
-        %(# frozen_string_literal: true
-
-module #{app_name.class_name}
-  class #{name.class_name} < ApplicationRecord
-  end
-end
-)
+        render_template("model/model.rb.template",
+          app_class: app_name.class_name,
+          model_class: name.class_name)
       end
 
+      # The full source of the generated migration, with one `t.<type> :<name>` line per field.
       def migration
-        %(# frozen_string_literal: true
-
-class Create#{table_class_name} < ActiveRecord::Migration[8.1]
-  def change
-    create_table :#{table_name} do |t|
-#{field_lines}      t.timestamps
-    end
-  end
-end
-)
+        render_template("model/migration.rb.template",
+          table_class: table_class_name,
+          table_name: table_name,
+          field_lines: field_lines)
       end
 
+      # The full source of the generated model spec (asserts the model inherits from
+      # `ApplicationRecord`).
       def spec
-        %(# frozen_string_literal: true
-
-require "#{app_name.snake_name}"
-
-RSpec.describe #{app_name.class_name}::#{name.class_name} do
-  it "inherits from ApplicationRecord" do
-    expect(described_class.superclass).to eq(#{app_name.class_name}::ApplicationRecord)
-  end
-end
-)
+        render_template("model/spec.rb.template",
+          app_snake: app_name.snake_name,
+          app_class: app_name.class_name,
+          model_class: name.class_name)
       end
 
+      # Renders one `t.<type> :<name>` line per field, joined together.
       def field_lines
         fields.map { |field|
-          %(      t.#{field.type} :#{field.name}
-)
+          "      t.#{field.type} :#{field.name}\n"
         }.join
       end
 
+      # Parses a single `name:type` argument. Raises Error on invalid names or unsupported types.
       def parse_field(value)
         field_name, type = value.split(":", 2)
         raise Error, "Invalid field: #{value.inspect}" unless field_name && type
@@ -91,19 +95,23 @@ end
         Field.new(name: field_name, type: type)
       end
 
+      # True when `config/database.rb` and `app/models/application_record.rb` both exist.
       def database_configured?
         File.exist?(File.join(destination, "config", "database.rb")) &&
           File.exist?(File.join(destination, "app", "models", "application_record.rb"))
       end
 
+      # The pluralized table name (e.g., "user" → "users", "category" → "categories").
       def table_name
         pluralize(name.snake_name)
       end
 
+      # The CamelCase migration class name (e.g., "users" → "Users").
       def table_class_name
         table_name.split("_").map(&:capitalize).join
       end
 
+      # Minimal English pluralization for the model name (covers the common -y, -s/x/z/ch/sh cases).
       def pluralize(value)
         return value.sub(/y\z/, "ies") if value.end_with?("y")
         return "#{value}es" if value.match?(/(?:s|x|z|ch|sh)\z/)
@@ -111,6 +119,7 @@ end
         "#{value}s"
       end
 
+      # The current UTC timestamp in the format ActiveRecord uses for migration filenames.
       def timestamp
         Time.now.utc.strftime("%Y%m%d%H%M%S")
       end

data/lib/charming/generators/name.rb

@@ -2,24 +2,34 @@
 
 module Charming
   module Generators
+    # Name validates a generator resource name and exposes the conventional Ruby class-name
+    # variants (singular class, controller, component) derived from it. The original input
+    # must match `VALID_NAME` (lowercase, snake_case, must start with a letter).
     class Name
+      # Regex matching a valid snake_case resource name: lowercase letter, then any
+      # combination of lowercase letters, digits, and underscores.
       VALID_NAME = /\A[a-z][a-z0-9_]*\z/
 
+      # The original snake_case name as supplied.
       attr_reader :snake_name
 
+      # Raises Error when *value* doesn't match `VALID_NAME`.
       def initialize(value)
         @snake_name = value.to_s
         raise Error, "Invalid name: #{value}" unless VALID_NAME.match?(@snake_name)
       end
 
+      # The CamelCase class name (e.g., "user" → "User").
       def class_name
         snake_name.split("_").map(&:capitalize).join
       end
 
+      # The controller class name (e.g., "user" → "UserController").
       def controller_class_name
         "#{class_name}Controller"
       end
 
+      # The component class name (e.g., "user" → "UserComponent").
       def component_class_name
         "#{class_name}Component"
       end

data/lib/charming/generators/screen_generator.rb

@@ -2,14 +2,19 @@
 
 module Charming
   module Generators
+    # ScreenGenerator implements `charming generate screen NAME`. Writes a complete vertical
+    # slice for a new screen: a state class, a controller with a `show` action, a view,
+    # matching spec files, and inserts a route into `config/routes.rb` and a command entry
+    # into `ApplicationController` for the command palette.
     class ScreenGenerator < AppFileGenerator
-      include AppGenerator::ScreenSpecTemplates
-
+      # *name* is the resource name. *args* is unused (raises Error when non-empty).
       def initialize(name, args, out:, destination:, force: false)
         super
         raise Error, "Usage: charming generate screen NAME" if args.any?
       end
 
+      # Writes the state, controller, view, and three spec files, then inserts a route
+      # and a command-palette entry.
       def generate
         create_file(state_path, state)
         create_file(controller_path, controller)
@@ -23,88 +28,124 @@ module Charming
 
       private
 
+      # The file-name suffix used by `app_path` ("screen" — only used by the parent class).
       def suffix
         "screen"
       end
 
+      # Path to the generated state class.
       def state_path
         File.join("app", "state", "#{name.snake_name}_state.rb")
       end
 
+      # Path to the generated controller class.
       def controller_path
         File.join("app", "controllers", "#{name.snake_name}_controller.rb")
       end
 
+      # Path to the generated `show` view.
       def view_path
-        File.join("app", "views", name.snake_name, "show.tui.erb")
+        File.join("app", "views", name.snake_name, "show_view.rb")
       end
 
+      # Path to the generated state spec.
       def spec_state_path
         File.join("spec", "state", "#{name.snake_name}_state_spec.rb")
       end
 
+      # Path to the generated controller spec.
       def spec_controller_path
         File.join("spec", "controllers", "#{name.snake_name}_controller_spec.rb")
       end
 
+      # Path to the generated view spec.
       def spec_view_path
-        File.join("spec", "views", name.snake_name, "show_template_spec.rb")
+        File.join("spec", "views", name.snake_name, "show_view_spec.rb")
       end
 
+      # Absolute path to the app's `config/routes.rb`.
       def route_path
         File.join(destination, "config", "routes.rb")
       end
 
+      # Absolute path to the app's `ApplicationController`.
       def application_controller_path
         File.join(destination, "app", "controllers", "application_controller.rb")
       end
 
+      # The source of the generated state class.
       def state
-        %(# frozen_string_literal: true
-
-module #{app_name.class_name}
-  class #{name.class_name}State < ApplicationState
-    attribute :title, :string, default: "#{name.class_name}"
-  end
-end
-)
+        render_template("screen/state.rb.template",
+          app_class: app_name.class_name,
+          state_class: "#{name.class_name}State",
+          title: name.class_name)
       end
 
+      # The source of the generated controller class.
       def controller
-        %(# frozen_string_literal: true
-
-module #{app_name.class_name}
-  class #{name.controller_class_name} < ApplicationController
-#{controller_body}
-  end
-end
-)
+        render_template("screen/controller.rb.template",
+          app_class: app_name.class_name,
+          controller_class: name.controller_class_name,
+          controller_body: controller_body)
       end
 
+      # The body of the controller: a `show` action and a private accessor for the state.
       def controller_body
-        %(    def show
-      render :show,
-        #{name.snake_name}: #{name.snake_name},
-        palette: command_palette
-    end
+        "    def show\n" \
+          "      render :show,\n" \
+          "        #{name.snake_name}: #{name.snake_name},\n" \
+          "        palette: command_palette\n" \
+          "    end\n" \
+          "\n" \
+          "    private\n" \
+          "\n" \
+          "    def #{name.snake_name}\n" \
+          "      state(:#{name.snake_name}, #{name.class_name}State)\n" \
+          "    end"
+      end
+
+      # The source of the generated view class.
+      def view
+        render_template("screen/view.rb.template",
+          app_class: app_name.class_name,
+          resource_module: name.class_name,
+          screen_name: name.snake_name)
+      end
 
-    private
+      # The source of the generated state spec.
+      def spec_state
+        render_template("screen/spec_state.rb.template",
+          app_snake: app_name.snake_name,
+          app_class: app_name.class_name,
+          state_class: "#{name.class_name}State",
+          title: name.class_name)
+      end
 
-    def #{name.snake_name}
-      state(:#{name.snake_name}, #{name.class_name}State)
-    end)
+      # The source of the generated controller spec.
+      def spec_controller
+        render_template("screen/spec_controller.rb.template",
+          app_snake: app_name.snake_name,
+          app_class: app_name.class_name,
+          controller_class: name.controller_class_name)
       end
 
-      def view
-        %(<%= #{name.snake_name}.title %>
-)
+      # The source of the generated view spec.
+      def spec_view
+        render_template("screen/spec_view.rb.template",
+          app_snake: app_name.snake_name,
+          app_class: app_name.class_name,
+          resource_module: name.class_name,
+          screen_name: name.snake_name,
+          title: name.class_name)
       end
 
+      # Inserts a `screen` route into `config/routes.rb`, idempotently.
       def insert_route
         route = %(  screen "/#{name.snake_name}", to: "#{name.snake_name}#show", title: "#{name.class_name}")
         insert_before_end(route_path, route, "route", "end")
       end
 
+      # Inserts a `command` block into `ApplicationController`, idempotently.
       def insert_command
         command = %(    command "#{name.class_name}" do
       navigate_to "/#{name.snake_name}"
@@ -112,6 +153,8 @@ end
         insert_before_end(application_controller_path, command, "command", "  end")
       end
 
+      # Inserts *content* into *path* just before the line matching *end_line*. No-ops when
+      # the content is already present. Raises Error when the file or end-line is missing.
       def insert_before_end(path, content, label, end_line)
         raise Error, "Missing file: #{relative_path(path)}" unless File.exist?(path)
 
@@ -125,6 +168,8 @@ end
         out.puts "insert #{label} #{relative_path(path)}"
       end
 
+      # Returns the index of the last line in *lines* that matches *end_line* (the line
+      # just before which new content will be inserted). Raises Error when not found.
       def insertion_index(lines, path, end_line)
         index = lines.rindex { |line| line.chomp == end_line }
         raise Error, "Could not update #{relative_path(path)}" unless index
@@ -132,6 +177,7 @@ end
         index
       end
 
+      # Strips the destination prefix from *path* for human-friendly status output.
       def relative_path(path)
         path.delete_prefix("#{destination}/")
       end

data/lib/charming/generators/templates/app/Gemfile.template

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/lib/charming/generators/templates/app/README.md.template

@@ -0,0 +1,9 @@
+# __APP_NAME__
+
+A Charming terminal user interface.
+
+Run it with:
+
+```sh
+bundle exec __APP_SNAKE__
+```

data/lib/charming/generators/templates/app/Rakefile.template

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

data/lib/charming/generators/templates/app/application.template

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class Application < Charming::Application
+    root File.expand_path("../..", __dir__)
+
+    Charming::Presentation::UI::Theme.built_in_names.each do |theme_name|
+      theme theme_name.to_sym, built_in: theme_name
+    end
+
+    default_theme :phosphor
+  end
+end

data/lib/charming/generators/templates/app/application_controller.template

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class ApplicationController < Charming::Controller
+    layout Layouts::ApplicationLayout
+    focus_ring :sidebar, :content
+
+    key "p", :open_command_palette, scope: :global
+    key "q", :quit, scope: :global
+
+    command "Home" do
+      navigate_to "/"
+    end
+
+    command "Theme", :open_theme_palette
+    command "Close palette", :close_command_palette
+    command "Quit app", :quit
+  end
+end

data/lib/charming/generators/templates/app/application_record.template

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/charming/generators/templates/app/application_state.template

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class ApplicationState < Charming::ApplicationState
+  end
+end

data/lib/charming/generators/templates/app/database_config.template

@@ -0,0 +1,12 @@
+# 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
+)

data/lib/charming/generators/templates/app/executable.template

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "__APP_SNAKE__"
+
+Charming.run(__APP_CLASS__::Application.new)

data/lib/charming/generators/templates/app/gemspec.template

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "lib/__APP_SNAKE__/version"
+
+Gem::Specification.new do |spec|
+__GEMSPEC_ATTRIBUTES____GEMSPEC_DEPENDENCIES__end

data/lib/charming/generators/templates/app/home_controller.template

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class HomeController < ApplicationController
+__CONTROLLER_ACTIONS____CONTROLLER_HELPERS__  end
+end

data/lib/charming/generators/templates/app/home_state.template

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module __APP_CLASS__
+  class HomeState < ApplicationState
+    attribute :title, :string, default: "__APP_NAME__"
+  end
+end