charming 0.1.0 → 0.1.2

data/lib/charming/generators/app_generator.rb

@@ -2,74 +2,176 @@
 
 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 LayoutTemplate
-      include ModelTemplates
-      include ScreenSpecTemplates
-      include ViewTemplate
-      include AppSpecTemplates
-
-      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/models/application_model.rb", :application_model],
-        ["app/models/home_model.rb", :home_model],
-        ["app/controllers/application_controller.rb", :application_controller],
-        ["app/controllers/home_controller.rb", :controller],
-        ["app/views/layouts/application.rb", :layout],
-        ["app/views/home_view.rb", :view],
-        ["app/components/app_frame_component.rb", :component],
-        ["spec/spec_helper.rb", :spec_helper],
-        ["spec/models/home_model_spec.rb", :spec_model],
-        ["spec/controllers/home_controller_spec.rb", :spec_controller],
-        ["spec/views/home_view_spec.rb", :spec_view],
-        ["spec/components/app_frame_component_spec.rb", :spec_component]
+      # The list of [relative-path, template-path, executable-flag] triples to render
+      # for a non-database app.
+      BASE_FILE_TEMPLATES = [
+        ["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
 
-      def initialize(name, out:, destination:, force: false)
+      # 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", "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
 
-      attr_reader :name
+      # 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
+
+      # 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
 
-#{name.class_name}::Application.routes do
-  root "home#show"
-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
 
-      def spec_helper
-        %(# frozen_string_literal: true
+      # 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
+
+      # 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?
+
+        "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"
+        end
 
-require "#{name.snake_name}"
-)
+        out.puts "init git"
       end
     end
   end

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::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

data/lib/charming/generators/controller_generator.rb

@@ -2,48 +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 #{name.view_class_name}.new(
-        palette: command_palette,
-        screen: screen
-      )
-    end
-)
+        "    def #{action}\n" \
+          "      render :#{action}, palette: command_palette\n" \
+          "    end\n"
       end
     end
   end

data/lib/charming/generators/model_generator.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+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?
+
+        create_file(model_path, model)
+        create_file(migration_path, migration)
+        create_file(spec_path, spec)
+      end
+
+      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
+        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
+        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
+        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}\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
+        raise Error, "Invalid field name: #{field_name.inspect}" unless Name::VALID_NAME.match?(field_name)
+        raise Error, "Unsupported field type: #{type.inspect}" unless VALID_TYPES.include?(type)
+
+        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/)
+
+        "#{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
+    end
+  end
+end

data/lib/charming/generators/name.rb

@@ -2,28 +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
 
-      def view_class_name
-        "#{class_name}View"
-      end
-
+      # The component class name (e.g., "user" → "UserComponent").
       def component_class_name
         "#{class_name}Component"
       end