charming 0.2.0 → 0.2.1

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/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(

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

@@ -68,7 +68,7 @@ module __APP_CLASS__
       end
 
       def shortcuts
-        text "tab focus\np commands\nq quit", style: theme.muted
+        text "tab focus\nctrl+p commands\nq quit", style: theme.muted
       end
 
       def sidebar_style

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

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
-require "__APP_SNAKE__"
+__ENV_SETUP__require "__APP_SNAKE__"
+__DATABASE_SPEC_SETUP__

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

@@ -14,7 +14,7 @@ module __APP_CLASS__
       end
 
       def help_line
-        text "Press p for commands, q to quit.", style: theme.muted
+        text "Press ctrl+p for commands, q to quit.", style: theme.muted
       end
     end
   end

data/lib/charming/internal/terminal/memory_backend.rb

@@ -33,6 +33,12 @@ module Charming
           @events.shift
         end
 
+        # True when every pre-seeded event has been consumed. The Runtime stops its loop
+        # on an exhausted backend so tests can't hang waiting for input that never comes.
+        def exhausted?
+          @events.empty?
+        end
+
         # Stores *frame* as the current frame and appends it to `frames`.
         def write_frame(frame)
           @current_frame = frame

data/lib/charming/internal/terminal/tty_backend.rb

@@ -22,6 +22,19 @@ module Charming
         AUTO_WRAP_OFF = "\e[?7l"
         AUTO_WRAP_ON = "\e[?7h"
 
+        # Escape sequences for enabling/disabling bracketed-paste mode, and the markers
+        # the terminal wraps around pasted text.
+        BRACKETED_PASTE_ON = "\e[?2004h"
+        BRACKETED_PASTE_OFF = "\e[?2004l"
+        PASTE_START = "\e[200~"
+        PASTE_END = "\e[201~"
+
+        # Escape sequences for terminal focus reporting and the focus-in/out markers.
+        FOCUS_REPORTING_ON = "\e[?1004h"
+        FOCUS_REPORTING_OFF = "\e[?1004l"
+        FOCUS_IN = "\e[I"
+        FOCUS_OUT = "\e[O"
+
         # *input* and *output* default to `$stdin`/`$stdout` for normal terminal use;
         # tests can inject IO objects. *reader* is a TTY::Reader instance (created from
         # *input*/*output* when nil). *cursor* is the TTY::Cursor class used for cursor control.
@@ -37,13 +50,17 @@ module Charming
         end
 
         # Reads the next event. If a SIGWINCH was received, returns a ResizeEvent with the
-        # current terminal dimensions. Mouse escape sequences are parsed by MouseParser;
-        # other input is normalized via KeyNormalizer. Returns nil on timeout.
+        # current terminal dimensions. Bracketed pastes return a PasteEvent; mouse escape
+        # sequences are parsed by MouseParser; other input is normalized via KeyNormalizer.
+        # Returns nil on timeout.
         def read_event(timeout: nil)
           return resize_event if resized?
 
           raw = @reader.read_keypress(echo: false, raw: true, nonblock: timeout)
           return nil unless raw
+          return Events::FocusEvent.new(focused: true) if raw == FOCUS_IN
+          return Events::FocusEvent.new(focused: false) if raw == FOCUS_OUT
+          return paste_event(raw) if raw.start_with?(PASTE_START)
           return MouseParser.parse(raw) if MouseParser.sequence?(raw)
 
           @key_normalizer.normalize(raw)
@@ -51,6 +68,38 @@ module Charming
           nil
         end
 
+        # Emits the ANSI sequence enabling terminal focus reporting. Idempotent.
+        def enable_focus_reporting
+          return if @focus_reporting
+
+          write_control(FOCUS_REPORTING_ON)
+          @focus_reporting = true
+        end
+
+        # Emits the ANSI sequence disabling terminal focus reporting. Idempotent.
+        def disable_focus_reporting
+          return unless @focus_reporting
+
+          write_control(FOCUS_REPORTING_OFF)
+          @focus_reporting = false
+        end
+
+        # Emits the ANSI sequence enabling bracketed-paste mode. Idempotent.
+        def enable_bracketed_paste
+          return if @bracketed_paste
+
+          write_control(BRACKETED_PASTE_ON)
+          @bracketed_paste = true
+        end
+
+        # Emits the ANSI sequence disabling bracketed-paste mode. Idempotent.
+        def disable_bracketed_paste
+          return unless @bracketed_paste
+
+          write_control(BRACKETED_PASTE_OFF)
+          @bracketed_paste = false
+        end
+
         # Keeps terminal input in raw/no-echo mode for the duration of a TUI run. Reading a
         # single keypress in raw mode is not enough: keys pressed while rendering or dispatching
         # events can otherwise be echoed into the alternate screen before the next read.
@@ -185,6 +234,19 @@ module Charming
           Events::ResizeEvent.new(width: width, height: height)
         end
 
+        # Builds a PasteEvent from a bracketed-paste chunk, reading further keypresses
+        # until the paste-end marker arrives (large pastes can span multiple reads).
+        def paste_event(raw)
+          buffer = raw.delete_prefix(PASTE_START)
+          until buffer.include?(PASTE_END)
+            chunk = @reader.read_keypress(echo: false, raw: true, nonblock: 0.2)
+            break unless chunk
+
+            buffer << chunk
+          end
+          Events::PasteEvent.new(text: buffer.sub(/#{Regexp.escape(PASTE_END)}.*\z/mo, ""))
+        end
+
         # Writes a raw escape *sequence* to the output stream and flushes.
         def write_control(sequence)
           @output.write(sequence)

data/lib/charming/presentation/component.rb

@@ -4,5 +4,12 @@ module Charming
   # Component is the base class for all reusable terminal widgets. It inherits from View to gain assigns,
   # helper methods (text, box, row, column, etc.), and rendering via render.
   class Component < View
+    # True for components that accept free-typed text (TextInput, TextArea, Form, …).
+    # While such a component is focused, the controller routes printable characters to
+    # it BEFORE global/content key bindings — so typing "q" or "?" into a field inserts
+    # the character instead of triggering an app shortcut.
+    def captures_text?
+      false
+    end
   end
 end

data/lib/charming/presentation/components/audio.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Audio is a one-line playback-status indicator for a {Charming::Audio::Player}. It
+    # reads the player's `playing?` state and renders a play/stop glyph with an optional
+    # *label*; pair it with a controller timer (or `on_task` re-render) to keep it live.
+    #
+    # Note: this view component (`Charming::Components::Audio`) is distinct from the
+    # playback engine namespace (`Charming::Audio`) — the component only displays state,
+    # the engine spawns the sound.
+    class Audio < Component
+      # *player* is the {Charming::Audio::Player} whose state is shown. *label* is an
+      # optional suffix (e.g. the track name) appended after the glyph. *theme* is the
+      # active theme, forwarded to the view layer.
+      def initialize(player:, label: nil, theme: nil)
+        super(theme: theme)
+        @player = player
+        @label = label
+      end
+
+      # Renders `▶`/`■` for playing/stopped, followed by the label when present.
+      def render
+        glyph = @player.playing? ? "▶" : "■"
+        return glyph unless @label
+
+        "#{glyph} #{@label}"
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/autocomplete.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Autocomplete is a combobox: a TextInput with a suggestion list beneath it,
+    # filtered live against the typed value. Up/down move through suggestions,
+    # Enter submits the highlighted suggestion (or the free text when nothing
+    # matches), Escape cancels.
+    #
+    #   Autocomplete.new(suggestions: ["ruby", "rails", "rspec"], value: "r")
+    #
+    # `handle_key` returns `[:submitted, value]` on Enter, `:cancelled` on Escape,
+    # `:handled` for consumed keys, nil otherwise.
+    class Autocomplete < Component
+      DEFAULT_MAX_SUGGESTIONS = 6
+
+      # The current typed value and the highlighted suggestion index.
+      attr_reader :selected_index
+
+      # *suggestions* is the full candidate list. *value*/*cursor* seed the inner
+      # TextInput. *max_suggestions* caps the visible dropdown rows.
+      def initialize(suggestions:, value: "", cursor: nil, placeholder: "", selected_index: 0,
+        max_suggestions: DEFAULT_MAX_SUGGESTIONS, theme: nil)
+        super(theme: theme)
+        @suggestions = Array(suggestions).map(&:to_s)
+        @input = TextInput.new(value: value, cursor: cursor, placeholder: placeholder)
+        @selected_index = selected_index
+        @max_suggestions = max_suggestions
+        clamp_selection
+      end
+
+      # The typed text.
+      def value
+        @input.value
+      end
+
+      # The inner input's cursor offset.
+      def cursor
+        @input.cursor
+      end
+
+      # The suggestions matching the current value (case-insensitive substring),
+      # capped at max_suggestions. All suggestions when the value is empty.
+      def filtered_suggestions
+        query = value.downcase
+        matches = query.empty? ? @suggestions : @suggestions.select { |s| s.downcase.include?(query) }
+        matches.first(@max_suggestions)
+      end
+
+      # Free-typed characters belong to this component while it is focused.
+      def captures_text?
+        true
+      end
+
+      # Enter submits, Escape cancels, up/down move the highlight, everything else
+      # edits the text (resetting the highlight).
+      def handle_key(event)
+        case Charming.key_of(event)
+        when :escape then :cancelled
+        when :enter then [:submitted, submission_value]
+        when :up then move_selection(-1)
+        when :down then move_selection(+1)
+        else
+          result = @input.handle_key(event)
+          clamp_selection if result
+          result
+        end
+      end
+
+      # Renders the input row followed by the suggestion dropdown.
+      def render
+        [input_line, *suggestion_lines].join("\n")
+      end
+
+      private
+
+      # The highlighted suggestion, or the raw text when none match.
+      def submission_value
+        filtered_suggestions[selected_index] || value
+      end
+
+      def input_line
+        @input.render
+      end
+
+      # One row per suggestion; the highlighted row in the selected style.
+      def suggestion_lines
+        filtered_suggestions.each_with_index.map do |suggestion, index|
+          line = "  #{suggestion}"
+          (index == selected_index) ? theme.selected.render(line) : theme.muted.render(line)
+        end
+      end
+
+      def move_selection(delta)
+        count = filtered_suggestions.length
+        return :handled if count.zero?
+
+        @selected_index = (selected_index + delta).clamp(0, count - 1)
+        :handled
+      end
+
+      def clamp_selection
+        max = [filtered_suggestions.length - 1, 0].max
+        @selected_index = selected_index.clamp(0, max)
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/badge.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Badge is a small inline label rendered as a styled pill — useful for versions,
+    # counts, and statuses inside status bars, lists, and headers.
+    #
+    #   Badge.new("v1.2").render            # themed default
+    #   Badge.new("3 errors", style: theme.warn).render
+    class Badge < Component
+      # *label* is the badge text. *style* overrides the default themed style.
+      def initialize(label, style: nil, theme: nil)
+        super(theme: theme)
+        @label = label.to_s
+        @badge_style = style
+      end
+
+      # Renders the pill: a space-padded label with the badge style applied.
+      def render
+        resolved_style.render(" #{@label} ")
+      end
+
+      private
+
+      # The user style or the theme's selected style (which guarantees contrast).
+      def resolved_style
+        @badge_style || theme.selected
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/breadcrumbs.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Breadcrumbs renders a navigation trail like `Home › Projects › My App`, with the
+    # final (current) item highlighted and ancestors muted.
+    class Breadcrumbs < Component
+      DEFAULT_SEPARATOR = " › "
+
+      # *items* is the trail (strings or anything responding to to_s), first-to-last.
+      # *separator* joins the items.
+      def initialize(items:, separator: DEFAULT_SEPARATOR, theme: nil)
+        super(theme: theme)
+        @items = Array(items).map(&:to_s)
+        @separator = separator
+      end
+
+      # Renders the trail; ancestors muted, current item in the title style.
+      def render
+        return "" if @items.empty?
+
+        *ancestors, current = @items
+        parts = ancestors.map { |item| theme.muted.render(item) }
+        parts << theme.title.render(current)
+        parts.join(theme.muted.render(@separator))
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/command_palette.rb

@@ -43,6 +43,11 @@ module Charming
         }
       end
 
+      # Free-typed characters belong to this component while it is focused.
+      def captures_text?
+        true
+      end
+
       # Handles key events by routing them to the appropriate sub-component: Escape kills the
       # palette returning :cancelled; up/down/home/end keys go to the List selection handler
       # via handle_list_key; all other keys (including typed characters) are passed to the TextInput
@@ -104,14 +109,12 @@ module Charming
         List.new(items: filtered_commands, selected_index: selected_index, height: height, label: :label.to_proc, theme: theme)
       end
 
-      # Returns the full commands array when input value is empty; otherwise a subset whose labels match case-insensitively
-      # against the current TextInput value. Used to drive the fuzzy search behavior. Returns an Array of Command entries.
+      # Returns the full commands array when input value is empty; otherwise the commands
+      # fuzzy-matched against the typed value, best matches first (see FuzzyMatcher).
       def filtered_commands
         return commands if input.value.empty?
 
-        commands.select do |command|
-          command.label.downcase.include?(input.value.downcase)
-        end
+        FuzzyMatcher.filter(input.value, commands) { |command| command.label.to_s }
       end
     end
   end

data/lib/charming/presentation/components/error_screen.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # ErrorScreen renders an unhandled exception as a styled, centered panel instead of
+    # letting the backtrace crash into the raw terminal. Shows the exception class, message,
+    # the most relevant backtrace lines, and a dismiss hint. The Runtime displays it when a
+    # dispatched action raises and no `rescue_from` handler claimed the exception.
+    class ErrorScreen < Component
+      DEFAULT_WIDTH = 64
+      BACKTRACE_LINES = 6
+
+      # *error* is the rescued exception. *width* is the panel's total width. *root* is the
+      # app root used to shorten backtrace paths (defaults to the working directory).
+      def initialize(error:, width: DEFAULT_WIDTH, root: Dir.pwd, theme: nil)
+        super(theme: theme)
+        @error = error
+        @width = width
+        @root = root
+      end
+
+      # Renders the bordered error panel.
+      def render
+        box(column(*sections, gap: 1), style: panel_style)
+      end
+
+      private
+
+      attr_reader :error, :width, :root
+
+      # The panel sections: class name, message, backtrace, dismiss hint.
+      def sections
+        [
+          text(error.class.name, style: theme.warn.bold),
+          text(wrapped_message),
+          backtrace_section,
+          text("press any key to continue · q to quit", style: theme.muted)
+        ].compact
+      end
+
+      # The exception message, wrapped to the panel's inner width.
+      def wrapped_message
+        Charming::Markdown::TextWrapper.new(width: inner_width).wrap(error.message.to_s)
+      end
+
+      # The first few backtrace lines with the app root stripped, styled muted.
+      def backtrace_section
+        lines = (error.backtrace || []).first(BACKTRACE_LINES)
+        return nil if lines.empty?
+
+        body = lines.map { |line| shorten(line) }.join("\n")
+        text(body, style: theme.muted)
+      end
+
+      # Strips the app root prefix and clips each backtrace line to the inner width.
+      def shorten(line)
+        cleaned = line.delete_prefix("#{root}/")
+        UI.visible_slice(cleaned, 0, inner_width)
+      end
+
+      # The panel's content width inside border and padding.
+      def inner_width
+        [width - 6, 10].max
+      end
+
+      # The bordered panel style: warn-colored rounded border with padding.
+      def panel_style
+        style.border(:rounded, foreground: :red).padding(1, 2).width(width)
+      end
+    end
+  end
+end

data/lib/charming/presentation/components/form.rb

@@ -7,6 +7,9 @@ module Charming
     # and bound to a per-form mutable state hash. Tab/Shift+Tab cycles focus through
     # focusable fields, Enter advances to the next field (or submits on the last), Escape
     # cancels, and Ctrl+S submits from any field.
+    #
+    # Exception: inside a Textarea field, Enter inserts a newline (it's a text editor) —
+    # leave it with Tab and submit with Ctrl+S, matching charm.sh's huh behavior.
     class Form < Component
       # The list of field objects and the mutable state hash the form is bound to.
       attr_reader :fields, :state
@@ -35,6 +38,12 @@ module Charming
         advance_or_submit if key == :enter
       end
 
+      # Forms accept free-typed text (their input/textarea fields do), so printable
+      # characters route here before global/content key bindings.
+      def captures_text?
+        true
+      end
+
       # Returns a hash of `{field_name => value}` for the current field values.
       def values
         state[:values]