charming 0.2.0 → 0.2.2

data/lib/charming/database/commands.rb

@@ -8,11 +8,17 @@ module Charming
     # `db:install`, which lives in Generators::DatabaseInstaller). It loads the app's
     # `config/database.rb`, delegates the actual work to ActiveRecord, and prints a short
     # status line on success.
+    #
+    # Supported commands: db:create, db:migrate, db:rollback [STEP=n], db:drop, db:seed,
+    # db:setup, db:reset, db:prepare, db:status, db:version, db:schema:dump, db:schema:load.
+    # The target database file is selected by CHARMING_ENV (development, test, production).
     class Commands
-      # *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* is the subcommand string (e.g., "db:create"). *args* holds extra CLI
+      # arguments such as "STEP=2". *out* is the status-output stream. *destination* is the
+      # app root for resolving `config/database.rb` and `db/`.
+      def initialize(command, out:, destination:, args: [])
         @command = command
+        @args = args
         @out = out
         @destination = destination
       end
@@ -25,14 +31,21 @@ module Charming
         when "db:rollback" then rollback
         when "db:drop" then drop
         when "db:seed" then seed
+        when "db:setup" then setup
+        when "db:reset" then reset
+        when "db:prepare" then prepare
+        when "db:status" then status
+        when "db:version" then version
+        when "db:schema:dump" then schema_dump
+        when "db:schema:load" then schema_load
         else raise Generators::Error, "Unknown database command: #{command}"
         end
       end
 
       private
 
-      # The subcommand, output stream, and app destination.
-      attr_reader :command, :out, :destination
+      # The subcommand, extra arguments, output stream, and app destination.
+      attr_reader :command, :args, :out, :destination
 
       # Creates the SQLite database file (touch) and establishes the connection.
       def create
@@ -43,18 +56,21 @@ module Charming
         out.puts "create #{relative_database_path}"
       end
 
-      # Runs all pending migrations from `db/migrate`.
+      # Runs all pending migrations from `db/migrate`, then refreshes `db/schema.rb`.
       def migrate
         load_database
         migration_context.migrate
+        dump_schema
         out.puts "migrate db/migrate"
       end
 
-      # Rolls back the most recent migration.
+      # Rolls back the most recent migration(s). Accepts `STEP=n` (default 1), then
+      # refreshes `db/schema.rb`.
       def rollback
         load_database
-        migration_context.rollback(1)
-        out.puts "rollback db/migrate"
+        migration_context.rollback(step_argument)
+        dump_schema
+        out.puts "rollback db/migrate (#{step_argument} step#{"s" if step_argument > 1})"
       end
 
       # Disconnects ActiveRecord, then deletes the database file.
@@ -65,16 +81,92 @@ module Charming
         out.puts "drop #{relative_database_path}"
       end
 
-      # Loads `db/seeds.rb` (raises if missing).
+      # Loads `db/seeds.rb` (raises if missing). The full application is loaded first so
+      # seeds can reference app models.
       def seed
         load_database
-        seed_path = File.join(destination, "db", "seeds.rb")
+        load_application
         raise Generators::Error, "Missing file: db/seeds.rb" unless File.exist?(seed_path)
 
         load seed_path
         out.puts "seed db/seeds.rb"
       end
 
+      # Creates the database, loads the schema when one exists (otherwise migrates), and seeds.
+      def setup
+        create
+        File.exist?(schema_path) ? schema_load : migrate
+        seed if File.exist?(seed_path)
+        out.puts "setup #{relative_database_path}"
+      end
+
+      # Drops and re-creates the database from scratch (drop + setup).
+      def reset
+        load_database
+        drop
+        setup
+      end
+
+      # CI-friendly: sets up the database when it doesn't exist, otherwise just migrates.
+      def prepare
+        load_database
+        if database_path && File.exist?(database_path)
+          migrate
+        else
+          setup
+        end
+      end
+
+      # Prints a Rails-style migration status table (status, version, name).
+      def status
+        load_database
+        out.puts "Status   Version          Name"
+        out.puts "-" * 48
+        migration_context.migrations_status.each do |migration_status, version, name|
+          out.puts format("%-8s %-16s %s", migration_status, version, name)
+        end
+      end
+
+      # Prints the current schema version.
+      def version
+        load_database
+        out.puts "version #{migration_context.current_version}"
+      end
+
+      # Writes the current database structure to `db/schema.rb`.
+      def schema_dump
+        load_database
+        dump_schema
+        out.puts "dump db/schema.rb"
+      end
+
+      # Loads `db/schema.rb` into the database (fast alternative to replaying migrations).
+      def schema_load
+        load_database
+        raise Generators::Error, "Missing file: db/schema.rb. Run `charming db:schema:dump` first." unless File.exist?(schema_path)
+
+        load schema_path
+        out.puts "load db/schema.rb"
+      end
+
+      # Dumps the connected database's structure to `db/schema.rb` via ActiveRecord.
+      def dump_schema
+        File.open(schema_path, "w") do |file|
+          ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, file)
+        end
+      end
+
+      # Parses the `STEP=n` argument for db:rollback (defaults to 1).
+      def step_argument
+        step = args.find { |arg| arg.start_with?("STEP=") }
+        return 1 unless step
+
+        value = step.delete_prefix("STEP=").to_i
+        raise Generators::Error, "STEP must be a positive integer" unless value.positive?
+
+        value
+      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")
@@ -83,11 +175,31 @@ module Charming
         require database_config
       end
 
+      # Requires the app's root loader (`lib/<app>.rb`, derived from the gemspec name) so
+      # app constants — models in particular — are available. No-op when not in an app root.
+      def load_application
+        gemspec = Dir.glob(File.join(destination, "*.gemspec")).first
+        return unless gemspec
+
+        root_file = File.join(destination, "lib", "#{File.basename(gemspec, ".gemspec")}.rb")
+        require root_file if File.exist?(root_file)
+      end
+
       # The ActiveRecord migration context rooted at `db/migrate` inside the app.
       def migration_context
         ActiveRecord::MigrationContext.new(File.join(destination, "db", "migrate"))
       end
 
+      # Path to the app's `db/schema.rb`.
+      def schema_path
+        File.join(destination, "db", "schema.rb")
+      end
+
+      # Path to the app's `db/seeds.rb`.
+      def seed_path
+        File.join(destination, "db", "seeds.rb")
+      end
+
       # The configured database file path (nil when ActiveRecord isn't connected to a file).
       def database_path
         ActiveRecord::Base.connection_db_config.database

data/lib/charming/escape.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Charming
+  # Escape is the out-of-band terminal channel: escape sequences written straight to the terminal,
+  # *before* each frame, bypassing the line-based renderer (which measures width and would shred raw
+  # control sequences). It is the shared substrate for several primitives — image transmissions
+  # ({Charming::Image::Transmit}), clipboard writes, desktop notifications, and the window title.
+  #
+  # Sequences are gathered during an event's dispatch via a thread-local collector ({collecting} /
+  # {register}) and attached to the {Response}; the {Runtime} flushes them through
+  # `backend.write_escape`. Any object that responds to `#payload` (a string) can ride the channel;
+  # the builders here return {Sequence} value objects and sanitize interpolated text so user content
+  # can't break out of the sequence.
+  module Escape
+    # A single out-of-band sequence. *payload* is the literal escape string written to the terminal.
+    Sequence = Data.define(:payload)
+
+    # Thread-local key under which the active collection bucket is stored.
+    BUCKET_KEY = :charming_escape_bucket
+
+    class << self
+      # Runs *block* with a fresh collection bucket active and returns the bucket — the {Sequence}s
+      # registered via {register} during the block. The block's own return value is ignored (capture
+      # it via a closure). Nesting is supported: an inner collection shadows the outer.
+      def collecting
+        previous = Thread.current[BUCKET_KEY]
+        bucket = []
+        Thread.current[BUCKET_KEY] = bucket
+        yield
+        bucket
+      ensure
+        Thread.current[BUCKET_KEY] = previous
+      end
+
+      # Registers *sequence* with the active collection bucket so it is flushed to the backend. A
+      # no-op (outside a collection, or when *sequence* is nil) so callers can register freely.
+      def register(sequence)
+        return sequence unless sequence
+
+        Thread.current[BUCKET_KEY]&.push(sequence)
+        sequence
+      end
+
+      # Builds an OSC 52 clipboard-write sequence setting the *target* selection (`"c"` clipboard,
+      # `"p"` primary) to *text*. The text is base64-encoded, so any bytes are safe.
+      def clipboard(text, target: "c")
+        Sequence.new(payload: "\e]52;#{target};#{[text.to_s].pack("m0")}\a")
+      end
+
+      # Builds a desktop-notification sequence: OSC 777 (`title` + `body`) when a *title* is given,
+      # else OSC 9 (body only) — the broadly supported baseline (Ghostty, iTerm2, Kitty).
+      def notification(body, title: nil)
+        payload =
+          if title
+            "\e]777;notify;#{sanitize(title)};#{sanitize(body)}\e\\"
+          else
+            "\e]9;#{sanitize(body)}\a"
+          end
+        Sequence.new(payload: payload)
+      end
+
+      # Builds a terminal-bell sequence (BEL).
+      def bell
+        Sequence.new(payload: "\a")
+      end
+
+      # Builds an OSC 0 sequence setting the terminal window (and icon) title to *text*.
+      def title(text)
+        Sequence.new(payload: "\e]0;#{sanitize(text)}\a")
+      end
+
+      private
+
+      # Strips C0 control characters (incl. ESC and BEL) so interpolated user text can't terminate
+      # or inject into the surrounding escape sequence.
+      def sanitize(text)
+        text.to_s.gsub(/[\x00-\x1f\x7f]/, "")
+      end
+    end
+  end
+end

data/lib/charming/events/focus_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # FocusEvent reports the terminal window gaining or losing focus (focus reporting
+    # mode `\e[?1004h`, markers `\e[I` / `\e[O`). Controllers opt in by defining a
+    # `focus_changed` action; apps can use it to pause timers or dim the UI.
+    FocusEvent = Data.define(:focused) do
+      def focused? = focused
+    end
+  end
+end

data/lib/charming/events/mouse_event.rb

@@ -10,11 +10,12 @@ module Charming
     }.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)
+    # 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. *motion*
+    # marks drag/hover movement and *release* marks an SGR button release.
+    MouseEvent = Data.define(:button, :x, :y, :ctrl, :alt, :shift, :motion, :release) do
+      def initialize(button:, x:, y:, ctrl: false, alt: false, shift: false, motion: false, release: false)
         super
       end
 
@@ -23,9 +24,9 @@ module Charming
         MOUSE_BUTTON_MAP.fetch(button, :unknown)
       end
 
-      # Returns `true` when the current event is a click (left, middle, or right button).
+      # Returns `true` for a button press (left, middle, or right) — not a release, drag, or hover.
       def click?
-        %i[left middle right].include?(button_name)
+        !motion && !release? && %i[left middle right].include?(button_name)
       end
 
       # Returns `true` when the button name maps to either direction of scroll.
@@ -33,9 +34,21 @@ module Charming
         %i[scroll_up scroll_down].include?(button_name)
       end
 
-      # Returns `true` when the current event is a mouse release action.
+      # Returns `true` for a button release: the SGR release marker, or the legacy
+      # button-3 release code on a non-motion event. (During motion, button 3
+      # means "no button held", not a release.)
       def release?
-        button_name == :release
+        release || (!motion && button_name == :release)
+      end
+
+      # Returns `true` for any mouse movement report (drag or hover).
+      def motion?
+        motion
+      end
+
+      # Returns `true` when the mouse moved with a button held down.
+      def drag?
+        motion && %i[left middle right].include?(button_name)
       end
     end
   end

data/lib/charming/events/paste_event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # PasteEvent carries text pasted via the terminal's bracketed-paste mode
+    # (`\e[200~ ... \e[201~`). Without bracketed paste, pasted text arrives as a storm
+    # of individual key events; with it, components receive the whole string at once
+    # via `handle_paste`.
+    PasteEvent = Data.define(:text)
+  end
+end

data/lib/charming/events/task_progress_event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # TaskProgressEvent reports incremental progress from a running background task.
+    # *name* matches the task name, *current*/*total* describe completion (total may be
+    # nil for indeterminate work), and *message* is an optional human-readable status.
+    TaskProgressEvent = Data.define(:name, :current, :total, :message) do
+      def initialize(name:, current:, total: nil, message: nil)
+        super
+      end
+
+      # Completion as a 0.0..1.0 fraction, or nil when the total is unknown.
+      def fraction
+        return nil unless total&.positive?
+
+        (current.to_f / total).clamp(0.0, 1.0)
+      end
+    end
+  end
+end

data/lib/charming/generators/app_generator.rb

@@ -13,6 +13,7 @@ module Charming
       BASE_FILE_TEMPLATES = [
         ["Gemfile", "app/Gemfile.template", false],
         ["Rakefile", "app/Rakefile.template", false],
+        [".rspec", "app/dot_rspec.template", false],
         ["README.md", "app/README.md.template", false],
         ["%<name>s.gemspec", "app/gemspec.template", false],
         ["exe/%<name>s", "app/executable.template", true],
@@ -98,10 +99,47 @@ module Charming
           controller_actions: controller_actions,
           controller_helpers: controller_helpers,
           database_require: database_require,
-          model_loader: model_loader
+          model_loader: model_loader,
+          env_setup: env_setup,
+          database_spec_setup: database_spec_setup
         }
       end
 
+      # Pins CHARMING_ENV to "test" before the app (and its database config) loads, so
+      # specs hit db/test.sqlite3. Empty for non-database apps.
+      def env_setup
+        return "" unless database?
+
+        "ENV[\"CHARMING_ENV\"] ||= \"test\"\n\n"
+      end
+
+      # Prepares the test database schema before the suite and rolls back each example's
+      # writes in a transaction. Empty for non-database apps.
+      def database_spec_setup
+        return "" unless database?
+
+        <<~RUBY
+
+          # Prepare the test database, preferring the dumped schema over replaying migrations.
+          schema = File.expand_path("../db/schema.rb", __dir__)
+          if File.exist?(schema)
+            load schema
+          else
+            ActiveRecord::MigrationContext.new(File.expand_path("../db/migrate", __dir__)).migrate
+          end
+
+          RSpec.configure do |config|
+            # Roll back database writes after each example so tests stay isolated.
+            config.around(:each) do |example|
+              ActiveRecord::Base.transaction(requires_new: true) do
+                example.run
+                raise ActiveRecord::Rollback
+              end
+            end
+          end
+        RUBY
+      end
+
       # The `Gem::Specification` attributes block (indented two spaces to match the wrapping
       # `Gem::Specification.new do |spec|`).
       def gemspec_attributes
@@ -146,10 +184,10 @@ module Charming
 
       # The body of the home controller's private `home` helper, prefixed by a blank line.
       def controller_helpers
-        "\n\n    private\n" \
+        "\n\n    private\n\n" \
           "    def home\n" \
           "      state(:home, HomeState)\n" \
-          "    end"
+          "    end\n"
       end
 
       # The `require_relative "../config/database"` line when the app is database-configured.

data/lib/charming/generators/database_installer.rb

@@ -100,22 +100,11 @@ 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`).
+      # The contents of the new `config/database.rb` — read from the shared app template so
+      # `charming new --database` and `charming db:install` stay in sync. Environment-aware:
+      # the database file is `db/<CHARMING_ENV>.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
-)
-)
+        File.read(File.join(__dir__, "templates", "app", "database_config.template"))
       end
 
       # The contents of the new `app/models/application_record.rb` (abstract ActiveRecord base).

data/lib/charming/generators/migration_generator.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Charming
+  module Generators
+    # MigrationGenerator implements `charming generate migration NAME [field:type ...]`.
+    # Follows Rails naming conventions:
+    # - `create_<table>` generates a create_table migration (fields become columns)
+    # - `add_<x>_to_<table>` generates add_column lines for the supplied fields
+    # - `remove_<x>_from_<table>` generates remove_column lines
+    # - anything else generates an empty `change` method to fill in
+    class MigrationGenerator < AppFileGenerator
+      # A single migration field: column *name* and ActiveRecord *type*.
+      Field = Data.define(:name, :type)
+
+      # The set of ActiveRecord column types accepted on the command line.
+      VALID_TYPES = ModelGenerator::VALID_TYPES
+
+      def initialize(name, args, out:, destination:, force: false)
+        super
+        @fields = args.map { |arg| parse_field(arg) }
+      end
+
+      # Validates database support, then writes the timestamped migration file.
+      def generate
+        raise Error, "Database support is not configured. Run `charming db:install sqlite3` first." unless database_configured?
+
+        create_file(migration_path, migration)
+      end
+
+      private
+
+      attr_reader :fields
+
+      # No file-name suffix; MigrationGenerator writes to an explicit path.
+      def suffix
+        nil
+      end
+
+      # Path to the generated `db/migrate/<timestamp>_<name>.rb` file.
+      def migration_path
+        File.join("db", "migrate", "#{timestamp}_#{name.snake_name}.rb")
+      end
+
+      # The ActiveRecord migration API version stamped into generated migrations. Matches
+      # the version used by the model generator's migration template.
+      MIGRATION_VERSION = "8.1"
+
+      # The full source of the generated migration, dispatching on the name convention.
+      def migration
+        <<~RUBY
+          # frozen_string_literal: true
+
+          class #{migration_class_name} < ActiveRecord::Migration[#{MIGRATION_VERSION}]
+            def change
+          #{change_body.chomp}
+            end
+          end
+        RUBY
+      end
+
+      # The CamelCase migration class name derived from the snake_case migration name.
+      def migration_class_name
+        ActiveSupport::Inflector.camelize(name.snake_name)
+      end
+
+      # Builds the `change` method body based on the migration name convention.
+      def change_body
+        case name.snake_name
+        when /\Acreate_(.+)\z/
+          create_table_body(Regexp.last_match(1))
+        when /\Aadd_.+_to_(.+)\z/
+          column_lines(Regexp.last_match(1), :add_column)
+        when /\Aremove_.+_from_(.+)\z/
+          column_lines(Regexp.last_match(1), :remove_column)
+        else
+          "    # Add your migration steps here.\n"
+        end
+      end
+
+      # Generates a `create_table` block with one column line per field plus timestamps.
+      def create_table_body(table)
+        field_lines = fields.map { |field| "      t.#{field.type} :#{field.name}\n" }.join
+        "    create_table :#{table} do |t|\n#{field_lines}      t.timestamps\n    end\n"
+      end
+
+      # Generates one add_column/remove_column line per field for the given table.
+      def column_lines(table, method)
+        return "    # No fields given — add #{method} lines here.\n" if fields.empty?
+
+        fields.map { |field| "    #{method} :#{table}, :#{field.name}, :#{field.type}\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` exists in the app.
+      def database_configured?
+        File.exist?(File.join(destination, "config", "database.rb"))
+      end
+
+      # A migration timestamp in ActiveRecord's filename format, bumped past any
+      # existing migration's version so two generators run in the same second
+      # can't produce colliding versions.
+      def timestamp
+        MigrationTimestamp.next(File.join(destination, "db", "migrate"))
+      end
+    end
+  end
+end

data/lib/charming/generators/migration_timestamp.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Charming
+  module Generators
+    # MigrationTimestamp produces ActiveRecord-format migration version numbers
+    # (YYYYMMDDHHMMSS) that are guaranteed unique within a `db/migrate` directory:
+    # when generators run within the same second, the version is bumped one second
+    # past the highest existing migration version.
+    module MigrationTimestamp
+      module_function
+
+      # Returns the next available version string for *migrate_dir*.
+      def next(migrate_dir)
+        now = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        highest = highest_existing(migrate_dir)
+        return now unless highest && highest >= now
+
+        (highest.to_i + 1).to_s
+      end
+
+      # The highest version prefix among existing migration files, or nil.
+      def highest_existing(migrate_dir)
+        Dir.glob(File.join(migrate_dir, "*.rb"))
+          .filter_map { |path| File.basename(path)[/\A\d{14}/] }
+          .max
+      end
+    end
+  end
+end

data/lib/charming/generators/model_generator.rb

@@ -111,9 +111,11 @@ module Charming
         ActiveSupport::Inflector.camelize(table_name)
       end
 
-      # The current UTC timestamp in the format ActiveRecord uses for migration filenames.
+      # A migration timestamp in ActiveRecord's filename format, bumped past any
+      # existing migration's version so two generators run in the same second
+      # can't produce colliding versions.
       def timestamp
-        Time.now.utc.strftime("%Y%m%d%H%M%S")
+        MigrationTimestamp.next(File.join(destination, "db", "migrate"))
       end
     end
   end

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

@@ -3,3 +3,9 @@
 source "https://rubygems.org"
 
 gemspec
+
+group :development, :test do
+  gem "irb"     # `charming console` (not a default gem on Ruby 4.0+)
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.13"
+end

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

@@ -5,7 +5,7 @@ module __APP_CLASS__
     layout Layouts::ApplicationLayout
     focus_ring :sidebar, :content
 
-    key "p", :open_command_palette, scope: :global
+    key "ctrl+p", :open_command_palette, scope: :global
     key "q", :quit, scope: :global
 
     command "Home" do

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

@@ -3,7 +3,9 @@
 require "active_record"
 require "fileutils"
 
-database_path = File.expand_path("../db/development.sqlite3", __dir__)
+# The database file is selected by CHARMING_ENV (development, test, production).
+environment = ENV["CHARMING_ENV"] || "development"
+database_path = File.expand_path("../db/#{environment}.sqlite3", __dir__)
 FileUtils.mkdir_p(File.dirname(database_path))
 
 ActiveRecord::Base.establish_connection(