charming 0.2.0 → 0.2.1

data/lib/charming/tasks/task.rb

@@ -1,12 +1,32 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Charming
   module Tasks
     # Task is the unit of work submitted to a task executor. It pairs a *name* (used by
-    # `on_task` handlers to route the result) with a *block* to invoke on the executor.
-    Task = Data.define(:name, :block) do
-      # Invokes the task's block in the executor's thread and returns its value (or raises).
-      def call = block.call
+    # `on_task` handlers to route the result) with a *block* to invoke on the executor,
+    # plus an optional *timeout* in seconds.
+    Task = Data.define(:name, :block, :timeout) do
+      def initialize(name:, block:, timeout: nil)
+        super
+      end
+
+      # Invokes the task's block, passing *progress* when the block accepts an argument.
+      # Enforces the timeout (raising Tasks::Cancelled) when one was configured.
+      def call(progress = nil)
+        return invoke(progress) unless timeout
+
+        Timeout.timeout(timeout, Cancelled, "task #{name} timed out after #{timeout}s") do
+          invoke(progress)
+        end
+      end
+
+      private
+
+      def invoke(progress)
+        block.arity.zero? ? block.call : block.call(progress)
+      end
     end
   end
 end

data/lib/charming/tasks/threaded_executor.rb

@@ -5,30 +5,53 @@ module Charming
     # ThreadedExecutor runs submitted tasks on background Ruby threads. Each submission
     # creates a new thread that invokes the block and pushes the resulting TaskEvent
     # onto the shared *queue*. Threads are tracked so `shutdown` can wait (or kill)
-    # in-flight work.
+    # in-flight work, and tracked by name so `cancel` can interrupt a specific task.
     class ThreadedExecutor
       # *queue* is the thread-safe Queue (typically `runtime.@task_queue`) into which
       # completed TaskEvents are pushed.
       def initialize(queue)
         @queue = queue
         @threads = []
+        @threads_by_name = {}
         @mutex = Mutex.new
+        @shutting_down = false
       end
 
       # Wraps *block* in a Task and spawns a new thread to invoke it. The thread's
       # return value (or rescued exception) is pushed onto the queue as a TaskEvent.
-      # Returns nil immediately.
-      def submit(name, &block)
-        task = Task.new(name: name.to_sym, block: block)
-        thread = Thread.new(task) { |t| @queue << run(t) }
-        @mutex.synchronize { @threads << thread }
+      # Blocks that accept an argument receive a Progress reporter. *timeout* (seconds)
+      # cancels the task when exceeded. Returns nil immediately. Raises if called after
+      # shutdown has begun.
+      def submit(name, timeout: nil, &block)
+        task = Task.new(name: name.to_sym, block: block, timeout: timeout)
+        @mutex.synchronize do
+          raise "cannot submit task after shutdown" if @shutting_down
+
+          thread = Thread.new(task) { |t| @queue << run(t) }
+          @threads << thread
+          @threads_by_name[task.name] = thread
+        end
+        nil
+      end
+
+      # Cancels the named in-flight task by raising Tasks::Cancelled in its thread.
+      # The task completes with a TaskEvent whose error is the Cancelled exception.
+      # No-op when the task isn't running.
+      def cancel(name)
+        thread = @mutex.synchronize { @threads_by_name[name.to_sym] }
+        return unless thread&.alive?
+
+        thread.raise(Cancelled, "task #{name} cancelled")
         nil
       end
 
       # Waits up to *timeout* seconds for in-flight threads to finish, then kills any
-      # remaining live threads. Used by Runtime during teardown.
-      def shutdown(timeout: 0.0)
-        threads = @mutex.synchronize { @threads.dup }
+      # remaining live threads. Refuses new submissions once called.
+      def shutdown(timeout: 2.0)
+        threads = @mutex.synchronize do
+          @shutting_down = true
+          @threads.dup
+        end
         threads.each { |thread| thread.join(timeout) }
         threads.each do |thread|
           next unless thread.alive?
@@ -40,9 +63,10 @@ module Charming
 
       private
 
-      # Invokes the task's block and wraps the result (or rescued exception) in a TaskEvent.
+      # Invokes the task's block (passing a Progress reporter) and wraps the result
+      # (or rescued exception) in a TaskEvent.
       def run(task)
-        Events::TaskEvent.new(name: task.name, value: task.call)
+        Events::TaskEvent.new(name: task.name, value: task.call(Progress.new(@queue, task.name)))
       rescue StandardError, ScriptError => e
         Events::TaskEvent.new(name: task.name, error: e)
       end

data/lib/charming/test_helper.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "charming"
+
+module Charming
+  # TestHelper provides controller- and component-level test ergonomics for Charming apps,
+  # in the spirit of Rails' ActionController::TestCase:
+  #
+  #   require "charming/test_helper"
+  #
+  #   RSpec.describe HomeController do
+  #     include Charming::TestHelper
+  #
+  #     let(:ctrl) { build_controller(HomeController) }
+  #
+  #     it "renders a greeting" do
+  #       expect(ctrl.dispatch(:show)).to render_text("Welcome")
+  #     end
+  #
+  #     it "quits on q" do
+  #       expect(press(ctrl_class: HomeController, key: "q")).to be_quit
+  #     end
+  #   end
+  #
+  # Helpers:
+  # - `build_controller(klass, app:, screen:, route:)` — controller instance wired to an app
+  # - `key_event("ctrl+p")` — build a KeyEvent from a human-readable string
+  # - `press(controller_or_class, "down")` — dispatch a key press, returns the Response
+  # - `press_sequence(klass, ["down", "down", "enter"], app:)` — dispatch several presses
+  #
+  # RSpec matchers (when RSpec is loaded):
+  # - `expect(response).to render_text("...")` / `render_match(/.../)`
+  # - `expect(response).to be_quit` / `be_navigate` (predicate matchers on Response)
+  # - `expect(response).to navigate_to("/path")`
+  module TestHelper
+    # Builds a controller instance with sensible test defaults: a fresh Application,
+    # an 80x24 screen, and no event.
+    def build_controller(controller_class, app: nil, screen: nil, route: nil, event: nil)
+      app ||= Charming::Application.new
+      screen ||= Charming::Screen.new(width: 80, height: 24)
+      controller_class.new(application: app, event: event, screen: screen, route: route)
+    end
+
+    # Builds a KeyEvent from a human-readable string like "q", "down", "ctrl+p",
+    # or "shift+tab". Modifier order is irrelevant.
+    def key_event(description)
+      parts = description.to_s.split("+")
+      key = parts.pop
+      modifiers = parts.map(&:downcase)
+      char = (key.length == 1) ? key : nil
+      Charming::Events::KeyEvent.new(
+        key: key.to_sym,
+        char: char,
+        ctrl: modifiers.include?("ctrl") || modifiers.include?("control"),
+        alt: modifiers.include?("alt"),
+        shift: modifiers.include?("shift")
+      )
+    end
+
+    # Dispatches a single key press against *controller_class* and returns the Response.
+    # Pass `app:` to share session state across presses.
+    def press(controller_class, key, app:, screen: nil, route: nil)
+      controller = build_controller(controller_class, app: app, screen: screen, route: route, event: key_event(key))
+      controller.dispatch_key
+    end
+
+    # Dispatches each key in *keys* in order against fresh controller instances sharing
+    # *app*'s session (mirroring the runtime's controller-per-event model). Returns the
+    # last Response.
+    def press_sequence(controller_class, keys, app:, screen: nil, route: nil)
+      keys.map { |key| press(controller_class, key, app: app, screen: screen, route: route) }.last
+    end
+
+    # Builds a MemoryBackend pre-seeded with KeyEvents parsed from *keys*, ready to be
+    # passed to Charming::Runtime for integration-style tests.
+    def memory_backend(*keys, width: 80, height: 24)
+      events = keys.map { |key| key.is_a?(String) ? key_event(key) : key }
+      Charming::Internal::Terminal::MemoryBackend.new(events: events, width: width, height: height)
+    end
+  end
+end
+
+if defined?(RSpec)
+  # Both matchers compare against the ANSI-stripped body: styled output interleaves
+  # escape codes mid-phrase (each styled segment emits its own codes), so raw
+  # substring matching would fail on any text spanning two styles.
+  RSpec::Matchers.define :render_text do |expected|
+    match do |response|
+      response.respond_to?(:body) &&
+        Charming::UI::Width.strip_ansi(response.body.to_s).include?(expected)
+    end
+
+    failure_message do |response|
+      body = response.respond_to?(:body) ? Charming::UI::Width.strip_ansi(response.body.to_s) : response.inspect
+      "expected response body to include #{expected.inspect}, got:\n#{body}"
+    end
+  end
+
+  RSpec::Matchers.define :render_match do |pattern|
+    match do |response|
+      response.respond_to?(:body) &&
+        Charming::UI::Width.strip_ansi(response.body.to_s).match?(pattern)
+    end
+
+    failure_message do |response|
+      body = response.respond_to?(:body) ? Charming::UI::Width.strip_ansi(response.body.to_s) : response.inspect
+      "expected response body to match #{pattern.inspect}, got:\n#{body}"
+    end
+  end
+
+  RSpec::Matchers.define :navigate_to do |expected_path|
+    match do |response|
+      response.respond_to?(:navigate?) && response.navigate? && response.path == expected_path
+    end
+
+    failure_message do |response|
+      "expected a navigation response to #{expected_path.inspect}, got: #{response.inspect}"
+    end
+  end
+end

data/lib/charming/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Charming
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/charming.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/inflector"
+require "active_support/string_inquirer"
 require "logger"
 require "zeitwerk"
 
@@ -15,7 +16,8 @@ loader.inflector.inflect(
   "erb_handler" => "ErbHandler",
   "key_normalizer" => "KeyNormalizer",
   "mouse_parser" => "MouseParser",
-  "tty_backend" => "TTYBackend"
+  "tty_backend" => "TTYBackend",
+  "url_resolver" => "URLResolver"
 )
 loader.collapse("#{__dir__}/charming/presentation")
 loader.setup
@@ -24,6 +26,17 @@ module Charming
   # Base error class for all Charming-specific exceptions (used by templates, generators, runtime, etc.).
   class Error < StandardError; end
 
+  # The current environment, read from CHARMING_ENV (default "development"). Returns a
+  # StringInquirer so callers can write `Charming.env.test?` / `Charming.env.production?`.
+  def self.env
+    @env ||= ActiveSupport::StringInquirer.new(ENV["CHARMING_ENV"] || "development")
+  end
+
+  # Overrides the environment (used by tests and the CLI).
+  def self.env=(value)
+    @env = value.nil? ? nil : ActiveSupport::StringInquirer.new(value.to_s)
+  end
+
   # Entry point for running a Charming application. Instantiates a Runtime for *application* and starts
   # the event loop. *backend* defaults to TTYBackend; tests pass MemoryBackend directly via `Charming::Runtime.new`.
   def self.run(application, backend: nil)
@@ -36,6 +49,35 @@ module Charming
     key = event.respond_to?(:key) ? event.key : event
     key.to_sym
   end
+
+  # Returns the key signature used for controller bindings, including modifier flags.
+  def self.key_signature(event)
+    key = key_of(event)
+    modifiers = []
+    modifiers << "ctrl" if event.respond_to?(:ctrl) && event.ctrl
+    modifiers << "alt" if event.respond_to?(:alt) && event.alt
+    modifiers << "shift" if event.respond_to?(:shift) && event.shift
+
+    return key if modifiers.empty?
+
+    :"#{modifiers.join("+")}+#{key}"
+  end
+
+  # Normalizes key declarations so `control+p` and `ctrl+p` resolve to the same binding.
+  def self.key_binding_name(name)
+    parts = name.to_s.split("+")
+    return name.to_sym if parts.size == 1
+
+    key = parts.pop.downcase
+    modifiers = parts.map do |part|
+      modifier = part.downcase
+      (modifier == "control") ? "ctrl" : modifier
+    end
+    ordered_modifiers = %w[ctrl alt shift].select { |modifier| modifiers.include?(modifier) }
+    ordered_modifiers += modifiers - ordered_modifiers
+
+    :"#{(ordered_modifiers + [key]).join("+")}"
+  end
 end
 
 Charming::Templates.register ".tui.erb", Charming::Templates::ErbHandler

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: charming
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - pando
@@ -29,26 +29,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.1.2
-- !ruby/object:Gem::Dependency
-  name: activerecord
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 8.1.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 8.1.2
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -111,20 +91,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: tty-cursor
   requirement: !ruby/object:Gem::Requirement
@@ -153,20 +119,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
-- !ruby/object:Gem::Dependency
-  name: tty-progressbar
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.18'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: tty-table
   requirement: !ruby/object:Gem::Requirement
@@ -238,8 +190,11 @@ files:
 - lib/charming.rb
 - lib/charming/application.rb
 - lib/charming/application_state.rb
+- lib/charming/audio/player.rb
+- lib/charming/audio/system.rb
 - lib/charming/cli.rb
 - lib/charming/controller.rb
+- lib/charming/controller/action_hooks.rb
 - lib/charming/controller/class_methods.rb
 - lib/charming/controller/command_palette.rb
 - lib/charming/controller/component_dispatching.rb
@@ -250,10 +205,13 @@ files:
 - lib/charming/controller/session_state.rb
 - lib/charming/controller/sidebar_navigation.rb
 - lib/charming/database/commands.rb
+- lib/charming/events/focus_event.rb
 - lib/charming/events/key_event.rb
 - lib/charming/events/mouse_event.rb
+- lib/charming/events/paste_event.rb
 - lib/charming/events/resize_event.rb
 - lib/charming/events/task_event.rb
+- lib/charming/events/task_progress_event.rb
 - lib/charming/events/timer_event.rb
 - lib/charming/generators/app_file_generator.rb
 - lib/charming/generators/app_generator.rb
@@ -262,6 +220,8 @@ files:
 - lib/charming/generators/controller_generator.rb
 - lib/charming/generators/database_installer.rb
 - lib/charming/generators/error.rb
+- lib/charming/generators/migration_generator.rb
+- lib/charming/generators/migration_timestamp.rb
 - lib/charming/generators/model_generator.rb
 - lib/charming/generators/name.rb
 - lib/charming/generators/screen_generator.rb
@@ -310,9 +270,14 @@ files:
 - lib/charming/internal/terminal/tty_backend.rb
 - lib/charming/presentation/component.rb
 - lib/charming/presentation/components/activity_indicator.rb
+- lib/charming/presentation/components/audio.rb
+- lib/charming/presentation/components/autocomplete.rb
+- lib/charming/presentation/components/badge.rb
+- lib/charming/presentation/components/breadcrumbs.rb
 - lib/charming/presentation/components/command_palette.rb
 - lib/charming/presentation/components/command_palette_modal.rb
 - lib/charming/presentation/components/empty_state.rb
+- lib/charming/presentation/components/error_screen.rb
 - lib/charming/presentation/components/form.rb
 - lib/charming/presentation/components/form/builder.rb
 - lib/charming/presentation/components/form/confirm.rb
@@ -321,16 +286,26 @@ files:
 - lib/charming/presentation/components/form/note.rb
 - lib/charming/presentation/components/form/select.rb
 - lib/charming/presentation/components/form/textarea.rb
+- lib/charming/presentation/components/fuzzy_matcher.rb
+- lib/charming/presentation/components/help_overlay.rb
 - lib/charming/presentation/components/keyboard_handler.rb
 - lib/charming/presentation/components/list.rb
 - lib/charming/presentation/components/markdown.rb
 - lib/charming/presentation/components/modal.rb
+- lib/charming/presentation/components/multi_select_list.rb
 - lib/charming/presentation/components/progressbar.rb
 - lib/charming/presentation/components/spinner.rb
+- lib/charming/presentation/components/status_bar.rb
+- lib/charming/presentation/components/tab_bar.rb
 - lib/charming/presentation/components/table.rb
 - lib/charming/presentation/components/text_area.rb
 - lib/charming/presentation/components/text_input.rb
+- lib/charming/presentation/components/toast.rb
+- lib/charming/presentation/components/tree.rb
 - lib/charming/presentation/components/viewport.rb
+- lib/charming/presentation/components/viewport/content_lines.rb
+- lib/charming/presentation/components/viewport/line_window.rb
+- lib/charming/presentation/components/viewport/position.rb
 - lib/charming/presentation/layout.rb
 - lib/charming/presentation/layout/builder.rb
 - lib/charming/presentation/layout/overlay.rb
@@ -346,6 +321,9 @@ files:
 - lib/charming/presentation/markdown/renderer.rb
 - lib/charming/presentation/markdown/style_config.rb
 - lib/charming/presentation/markdown/syntax_highlighter.rb
+- lib/charming/presentation/markdown/table_renderer.rb
+- lib/charming/presentation/markdown/text_wrapper.rb
+- lib/charming/presentation/markdown/url_resolver.rb
 - lib/charming/presentation/template_view.rb
 - lib/charming/presentation/templates.rb
 - lib/charming/presentation/templates/erb_handler.rb
@@ -355,18 +333,27 @@ files:
 - lib/charming/presentation/ui/border.rb
 - lib/charming/presentation/ui/border_painter.rb
 - lib/charming/presentation/ui/canvas.rb
+- lib/charming/presentation/ui/color_support.rb
 - lib/charming/presentation/ui/style.rb
 - lib/charming/presentation/ui/theme.rb
+- lib/charming/presentation/ui/themes/catppuccin-latte.json
+- lib/charming/presentation/ui/themes/catppuccin-mocha.json
+- lib/charming/presentation/ui/themes/gruvbox-dark.json
+- lib/charming/presentation/ui/themes/nord.json
 - lib/charming/presentation/ui/themes/phosphor.json
+- lib/charming/presentation/ui/themes/tokyonight.json
 - lib/charming/presentation/ui/width.rb
 - lib/charming/presentation/view.rb
 - lib/charming/response.rb
 - lib/charming/router.rb
 - lib/charming/runtime.rb
 - lib/charming/screen.rb
+- lib/charming/tasks/cancelled.rb
 - lib/charming/tasks/inline_executor.rb
+- lib/charming/tasks/progress.rb
 - lib/charming/tasks/task.rb
 - lib/charming/tasks/threaded_executor.rb
+- lib/charming/test_helper.rb
 - lib/charming/version.rb
 - sig/charming.rbs
 homepage: https://github.com/pandorocks/charming