ratamin 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 657e9468e290eff1deeeb657db061a98dca992bece11887421737f1094bbfa28
+  data.tar.gz: 2d0672f141d7cd9596ccd108e848a0fbd7418f77de46b3f67e6a2aa6a1efe7b9
+SHA512:
+  metadata.gz: 93d38f02ff57591d942ed0f463ed5098a46e084a1270b0aadbdf6b1f3496d23e7a4ec5a30c95f6c6fec23baa92dbe63ee82a5763991d4b4be7ae8cbf4d7dba98
+  data.tar.gz: 15cf1c96fd1193292b98ef73626ea02859ee34c5d6f565c612a93a3d3adddaa62e1b3796185dadb2caa185e7fff0eddd4c43eade57a3e49560163a42fa813acb

data/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ["3.3", "3.4", "4.0"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "references/ratatui_ruby"]
+	path = references/ratatui_ruby
+	url = https://git.sr.ht/~kerrick/ratatui_ruby

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-03-14
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 merely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,109 @@
+# Ratamin
+
+A TUI admin console for ActiveRecord, built on [ratatui_ruby](https://github.com/nicholasgasior/ratatui_ruby).
+
+Give it a scope, get a navigable table with inline editing and `$EDITOR` support for long text.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ratamin"
+```
+
+## Usage
+
+### With ActiveRecord
+
+```ruby
+require "ratamin"
+
+# Edit all users
+Ratamin::App.new(Ratamin::ScopeDataSource.new(User.all)).run
+
+# Edit a filtered scope
+Ratamin::App.new(Ratamin::ScopeDataSource.new(User.where(role: "admin"))).run
+
+# Specify which columns to show
+columns = [
+  Ratamin::Column.new(key: :name, label: "Name", width: 20),
+  Ratamin::Column.new(key: :email, label: "Email", width: 30),
+  Ratamin::Column.new(key: :bio, label: "Bio", type: :text),
+]
+Ratamin::App.new(Ratamin::ScopeDataSource.new(User.all, columns: columns)).run
+```
+
+### Without ActiveRecord
+
+```ruby
+require "ratamin"
+
+columns = [
+  Ratamin::Column.new(key: :name, width: 20),
+  Ratamin::Column.new(key: :email, width: 30),
+]
+
+rows = [
+  { name: "Alice", email: "alice@example.com" },
+  { name: "Bob",   email: "bob@example.com" },
+]
+
+ds = Ratamin::ArrayDataSource.new(columns: columns, rows: rows)
+Ratamin::App.new(ds).run
+```
+
+## Keybindings
+
+### Table view
+
+| Key | Action |
+|-----|--------|
+| `j` / `Down` | Next row |
+| `k` / `Up` | Previous row |
+| `g` | First row |
+| `G` | Last row |
+| `Enter` | Edit selected record |
+| `r` | Reload data |
+| `q` | Quit |
+
+### Form view
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Next field |
+| `Shift+Tab` | Previous field |
+| `Enter` | Save |
+| `Esc` | Cancel |
+| `e` | Open `$EDITOR` (on `:text` fields) |
+
+## Architecture
+
+Ratamin separates data, state, and rendering:
+
+- **DataSource** — duck-type protocol (`#columns`, `#rows`, `#update_row`, `#reload!`)
+  - `ArrayDataSource` — in-memory arrays
+  - `ScopeDataSource` — wraps an ActiveRecord scope
+- **State** — pure Ruby, no TUI dependency, fully unit-testable
+  - `FormState` — field values, cursor, text editing, validation errors
+- **Views** — thin renderers that read from state objects
+  - `TableView` — record list with selection
+  - `FormView` — field-by-field editor
+
+## Column types
+
+| Type | Behavior |
+|------|----------|
+| `:string` (default) | Inline text editing |
+| `:text` | Truncated in table, opens `$EDITOR` for editing |
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/demo.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ratamin"
+
+columns = [
+  Ratamin::Column.new(key: :id, label: "ID", width: 6),
+  Ratamin::Column.new(key: :name, label: "Name", width: 20),
+  Ratamin::Column.new(key: :email, label: "Email", width: 30),
+  Ratamin::Column.new(key: :role, label: "Role", width: 10),
+  Ratamin::Column.new(key: :bio, label: "Bio", type: :text)
+]
+
+rows = [
+  {id: 1, name: "Alice", email: "alice@example.com", role: "admin", bio: "Software engineer with 10 years of experience in distributed systems and cloud infrastructure."},
+  {id: 2, name: "Bob", email: "bob@example.com", role: "user", bio: "Designer"},
+  {id: 3, name: "Charlie", email: "charlie@example.com", role: "user", bio: "Product manager focused on developer tools and platform engineering."},
+  {id: 4, name: "Diana", email: "diana@example.com", role: "moderator", bio: "Community lead"},
+  {id: 5, name: "Eve", email: "eve@example.com", role: "admin", bio: "Security researcher specializing in cryptographic protocols and zero-knowledge proofs."},
+  {id: 6, name: "Frank", email: "frank@example.com", role: "user", bio: "Full-stack developer"},
+  {id: 7, name: "Grace", email: "grace@example.com", role: "user", bio: "Data scientist working on ML pipelines and recommendation systems."},
+  {id: 8, name: "Hank", email: "hank@example.com", role: "moderator", bio: "DevOps engineer"},
+  {id: 9, name: "Ivy", email: "ivy@example.com", role: "user", bio: "Frontend developer passionate about accessibility and design systems."},
+  {id: 10, name: "Jack", email: "jack@example.com", role: "user", bio: "Backend engineer focused on high-performance APIs and database optimization."},
+]
+
+data_source = Ratamin::ArrayDataSource.new(columns: columns, rows: rows)
+app = Ratamin::App.new(data_source)
+app.run

data/lib/ratamin/app.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Ratamin
+  class App
+    attr_reader :data_source, :mode, :table_view, :form_state, :form_view
+
+    def initialize(data_source)
+      @data_source = data_source
+      @table_view = TableView.new(data_source)
+      @form_state = nil
+      @form_view = nil
+      @mode = :table
+    end
+
+    def run
+      RatatuiRuby.run do |tui|
+        loop do
+          tui.draw { |frame| render(tui, frame) }
+
+          event = tui.poll_event
+          result = handle_event(event)
+          break if result == :quit
+        end
+      end
+    end
+
+    private
+
+    def render(tui, frame)
+      body_area, status_area = RatatuiRuby::Layout::Layout.split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          RatatuiRuby::Layout::Constraint.fill(1),
+          RatatuiRuby::Layout::Constraint.length(1)
+        ]
+      )
+
+      case @mode
+      when :table
+        @table_view.render(tui, frame, body_area)
+        render_status_bar(tui, frame, status_area, table_help)
+      when :form
+        @form_view.render(tui, frame, body_area)
+        render_status_bar(tui, frame, status_area, form_help)
+      end
+    end
+
+    def render_status_bar(tui, frame, area, text)
+      bar = tui.paragraph(
+        text: text,
+        style: {fg: :black, bg: :cyan}
+      )
+      frame.render_widget(bar, area)
+    end
+
+    def table_help
+      help = " q:quit  j/↓:down  k/↑:up  g:first  G:last  enter:edit  r:reload"
+      help += "  n:next page  p:prev page" if @data_source.paginated?
+      help + " "
+    end
+
+    def form_help
+      " Tab:next field  Shift+Tab:prev  Enter:save  Esc:cancel "
+    end
+
+    def handle_event(event)
+      case @mode
+      when :table then handle_table_event(event)
+      when :form then handle_form_event(event)
+      end
+    end
+
+    def handle_table_event(event)
+      case event
+      in {type: :key, code: "q"} | {type: :key, code: "c", modifiers: ["ctrl"]}
+        :quit
+      in {type: :key, code: "j"} | {type: :key, code: "down"}
+        @table_view.select_next
+        nil
+      in {type: :key, code: "k"} | {type: :key, code: "up"}
+        @table_view.select_previous
+        nil
+      in {type: :key, code: "g"}
+        @table_view.select_first
+        nil
+      in {type: :key, code: "G"} | {type: :key, code: "g", modifiers: ["shift"]}
+        @table_view.select_last
+        nil
+      in {type: :key, code: "enter"}
+        enter_form
+        nil
+      in {type: :key, code: "n"} if @data_source.paginated?
+        @data_source.next_page
+        @table_view.reset_selection
+        nil
+      in {type: :key, code: "p"} if @data_source.paginated?
+        @data_source.prev_page
+        @table_view.reset_selection
+        nil
+      in {type: :key, code: "r"}
+        @data_source.reload!
+        @table_view.reset_selection
+        nil
+      else
+        nil
+      end
+    end
+
+    def handle_form_event(event)
+      result = @form_state.handle_event(event)
+      case result
+      when :save
+        save_form
+      when :cancel
+        exit_form
+      when :editor
+        open_editor
+      end
+      nil
+    end
+
+    def enter_form
+      row = @table_view.selected_row
+      return unless row
+
+      @form_state = FormState.new(@data_source.columns, row)
+      @form_view = FormView.new(@form_state)
+      @mode = :form
+    end
+
+    def exit_form
+      @mode = :table
+      @form_state = nil
+      @form_view = nil
+    end
+
+    def save_form
+      idx = @table_view.selected_index
+      return unless idx
+
+      result = @data_source.update_row(idx, @form_state.changes)
+      if result.ok?
+        exit_form
+      else
+        @form_state.set_errors(result.errors)
+      end
+    end
+
+    def open_editor
+      field_idx = @form_state.field_index
+      current_value = @form_state.values[field_idx]
+
+      edited = EditorBridge.edit(current_value)
+      @form_state.set_value(field_idx, edited.chomp)
+    end
+  end
+end

data/lib/ratamin/array_data_source.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ratamin
+  class ArrayDataSource
+    include DataSource
+
+    attr_reader :columns, :rows
+
+    # @param columns [Array<Column>] column definitions
+    # @param rows [Array<Hash>] row data, each hash maps column key -> value
+    def initialize(columns:, rows:)
+      @columns = columns
+      @rows = rows.map(&:dup)
+    end
+
+    def row_count
+      @rows.length
+    end
+
+    def update_row(index, changes)
+      changes.each { |k, v| @rows[index][k] = v }
+      UpdateResult.success
+    end
+
+    def reload!
+      # no-op for array source
+    end
+  end
+end

data/lib/ratamin/column.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ratamin
+  Column = Data.define(:key, :label, :width, :type, :editable) do
+    def initialize(key:, label: nil, width: nil, type: :string, editable: true)
+      super(key: key, label: label || key.to_s.capitalize, width: width, type: type, editable: editable)
+    end
+  end
+end

data/lib/ratamin/data_source.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ratamin
+  # Duck-type protocol for data sources.
+  # Implementations must respond to:
+  #   #columns    -> [Column]
+  #   #rows       -> [Hash]  (current page of data)
+  #   #row_count  -> Integer
+  #   #update_row(index, changes) -> UpdateResult
+  #   #reload!    -> void
+  #
+  # Pagination (optional, when #paginated? returns true):
+  #   #page        -> Integer (1-indexed)
+  #   #total_count -> Integer
+  #   #total_pages -> Integer
+  #   #next_page   -> void
+  #   #prev_page   -> void
+  #   #go_to_page(n) -> void
+  module DataSource
+    def paginated?
+      false
+    end
+  end
+end

data/lib/ratamin/editor_bridge.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "shellwords"
+
+module Ratamin
+  module EditorBridge
+    # Opens $EDITOR with the given text, returns edited text.
+    # Temporarily restores the terminal so the editor can run normally.
+    def self.edit(text)
+      editor = ENV["EDITOR"] || ENV["VISUAL"] || "vi"
+
+      tmpfile = Tempfile.new(["ratamin_edit", ".txt"])
+      tmpfile.write(text)
+      tmpfile.flush
+
+      RatatuiRuby.restore_terminal
+
+      # Use shell expansion so editors with arguments (e.g. "code --wait") work
+      success = system(*Shellwords.split(editor), tmpfile.path)
+
+      RatatuiRuby.init_terminal
+
+      unless success
+        tmpfile.close
+        tmpfile.unlink
+        return text
+      end
+
+      tmpfile.rewind
+      result = tmpfile.read
+      tmpfile.close
+      tmpfile.unlink
+
+      result
+    end
+  end
+end

data/lib/ratamin/form_state.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Ratamin
+  class FormState
+    attr_reader :columns, :values, :field_index, :cursor_positions, :errors
+
+    def initialize(columns, row)
+      @columns = columns
+      @values = columns.map { |col| row[col.key].to_s }
+      @original_values = @values.dup
+      @field_index = first_editable_index || 0
+      @cursor_positions = @values.map(&:length)
+      @errors = []
+    end
+
+    def errors?
+      !@errors.empty?
+    end
+
+    def set_errors(errors)
+      @errors = Array(errors)
+    end
+
+    def clear_errors
+      @errors = []
+    end
+
+    def handle_event(event)
+      # Enter/Esc always work, even when all fields are read-only.
+      case event
+      in {type: :key, code: "enter"}
+        return :save
+      in {type: :key, code: "esc"}
+        return :cancel
+      else
+        nil
+      end
+
+      case event
+      in {type: :key, code: "tab", modifiers: []}
+        return next_field
+      in {type: :key, code: "backtab"} | {type: :key, code: "tab", modifiers: ["shift"]}
+        return prev_field
+      else
+        nil
+      end
+
+      return nil unless current_column&.editable
+
+      case event
+      in {type: :key, code: "e"} if current_column.type == :text
+        return :editor
+      in {type: :key, code: "backspace"}
+        handle_backspace
+      in {type: :key, code: "delete"}
+        handle_delete
+      in {type: :key, code: "left"}
+        move_cursor_left
+      in {type: :key, code: "right"}
+        move_cursor_right
+      in {type: :key, code: "home"}
+        @cursor_positions[@field_index] = 0
+      in {type: :key, code: "end"}
+        @cursor_positions[@field_index] = @values[@field_index].length
+      in {type: :key, code: c, modifiers: []} if c.length == 1
+        insert_char(c)
+      else
+        nil
+      end
+    end
+
+    def current_column
+      columns[@field_index]
+    end
+
+    def current_value
+      @values[@field_index]
+    end
+
+    def set_value(index, value)
+      @values[index] = value.to_s
+      @cursor_positions[index] = @values[index].length
+    end
+
+    # Returns only dirty editable fields.
+    def changes
+      result = {}
+      columns.each_with_index do |col, i|
+        next unless col.editable
+        next if @values[i] == @original_values[i]
+        result[col.key] = @values[i]
+      end
+      result
+    end
+
+    def next_field
+      return unless any_editable?
+      loop do
+        @field_index = (@field_index + 1) % columns.length
+        break if current_column.editable
+      end
+    end
+
+    def prev_field
+      return unless any_editable?
+      loop do
+        @field_index = (@field_index - 1) % columns.length
+        break if current_column.editable
+      end
+    end
+
+    def insert_char(c)
+      pos = @cursor_positions[@field_index]
+      @values[@field_index] = @values[@field_index].dup.insert(pos, c)
+      @cursor_positions[@field_index] += 1
+    end
+
+    def handle_backspace
+      pos = @cursor_positions[@field_index]
+      return if pos == 0
+      val = @values[@field_index].dup
+      val.slice!(pos - 1)
+      @values[@field_index] = val
+      @cursor_positions[@field_index] -= 1
+    end
+
+    def handle_delete
+      pos = @cursor_positions[@field_index]
+      val = @values[@field_index].dup
+      return if pos >= val.length
+      val.slice!(pos)
+      @values[@field_index] = val
+    end
+
+    def move_cursor_left
+      @cursor_positions[@field_index] = [0, @cursor_positions[@field_index] - 1].max
+    end
+
+    def move_cursor_right
+      @cursor_positions[@field_index] = [@values[@field_index].length, @cursor_positions[@field_index] + 1].min
+    end
+
+    private
+
+    def any_editable?
+      columns.any?(&:editable)
+    end
+
+    def first_editable_index
+      columns.index(&:editable)
+    end
+  end
+end

data/lib/ratamin/form_view.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Ratamin
+  class FormView
+    attr_reader :state
+
+    def initialize(state)
+      @state = state
+    end
+
+    def render(tui, frame, area)
+      border_style = state.errors? ? {fg: :red} : {fg: :yellow}
+      inner_block = tui.block(
+        title: " Edit Record ",
+        borders: [:all],
+        border_type: :rounded,
+        border_style: border_style
+      )
+      inner_area = inner_block.inner(area)
+      frame.render_widget(inner_block, area)
+
+      columns = state.columns
+
+      constraints = []
+      # Error lines
+      if state.errors?
+        constraints << RatatuiRuby::Layout::Constraint.length(state.errors.length + 1)
+      end
+      # Field rows
+      columns.each { constraints << RatatuiRuby::Layout::Constraint.length(1) }
+      # Help line + spacer
+      constraints << RatatuiRuby::Layout::Constraint.length(1)
+      constraints << RatatuiRuby::Layout::Constraint.fill(1)
+
+      regions = RatatuiRuby::Layout::Layout.split(
+        inner_area,
+        direction: :vertical,
+        constraints: constraints
+      )
+
+      region_idx = 0
+
+      # Render errors if present
+      if state.errors?
+        error_text = state.errors.map { |e| " ! #{e}" }.join("\n")
+        error_widget = tui.paragraph(text: error_text, style: {fg: :red, modifiers: [:bold]})
+        frame.render_widget(error_widget, regions[region_idx])
+        region_idx += 1
+      end
+
+      label_width = columns.map { |c| c.label.length }.max + 2
+
+      columns.each_with_index do |col, i|
+        field_area = regions[region_idx + i]
+        label_area, value_area = RatatuiRuby::Layout::Layout.split(
+          field_area,
+          direction: :horizontal,
+          constraints: [
+            RatatuiRuby::Layout::Constraint.length(label_width),
+            RatatuiRuby::Layout::Constraint.fill(1)
+          ]
+        )
+
+        active = i == state.field_index
+
+        if col.editable
+          label_style = active ? {fg: :yellow, modifiers: [:bold]} : {fg: :dark_gray}
+          frame.render_widget(tui.paragraph(text: "#{col.label}: ", style: label_style), label_area)
+
+          display_value = if col.type == :text && state.values[i].length > 40
+            "[press 'e' to edit in $EDITOR]"
+          else
+            state.values[i]
+          end
+
+          value_style = active ? {fg: :white, modifiers: [:underlined]} : {fg: :gray}
+          frame.render_widget(tui.paragraph(text: display_value, style: value_style), value_area)
+
+          if active && col.type != :text
+            cursor_x = value_area.x + [state.cursor_positions[i], value_area.width - 1].min
+            frame.set_cursor_position(cursor_x, value_area.y)
+          end
+        else
+          frame.render_widget(tui.paragraph(text: "#{col.label}: ", style: {fg: :dark_gray}), label_area)
+          frame.render_widget(tui.paragraph(text: state.values[i], style: {fg: :dark_gray, modifiers: [:dim]}), value_area)
+        end
+      end
+
+      help_area = regions[region_idx + columns.length]
+      help = tui.paragraph(
+        text: " Tab:next  Shift+Tab:prev  Enter:save  Esc:cancel  e:editor(text) ",
+        style: {fg: :dark_gray}
+      )
+      frame.render_widget(help, help_area)
+    end
+  end
+end

data/lib/ratamin/scope_data_source.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Ratamin
+  class ScopeDataSource
+    include DataSource
+
+    attr_reader :columns, :page, :per_page, :total_count
+
+    # @param scope [ActiveRecord::Relation] the AR scope to display
+    # @param columns [Array<Column>, nil] explicit columns, or nil to infer from model
+    # @param per_page [Integer] records per page
+    def initialize(scope, columns: nil, per_page: 20)
+      @scope = scope
+      @columns = columns || infer_columns
+      @per_page = per_page
+      @page = 1
+      @total_count = 0
+      @records = []
+      reload!
+    end
+
+    def paginated?
+      true
+    end
+
+    def total_pages
+      [(@total_count.to_f / @per_page).ceil, 1].max
+    end
+
+    def next_page
+      go_to_page(@page + 1)
+    end
+
+    def prev_page
+      go_to_page(@page - 1)
+    end
+
+    def go_to_page(n)
+      n = [[1, n].max, total_pages].min
+      return if n == @page
+      @page = n
+      load_page
+    end
+
+    def rows
+      @records.map { |record| row_hash(record) }
+    end
+
+    def row_count
+      @records.length
+    end
+
+    def update_row(index, changes)
+      record = @records[index]
+      cast_changes = changes.transform_keys(&:to_s)
+      record.assign_attributes(cast_changes)
+
+      if record.save
+        UpdateResult.success
+      else
+        UpdateResult.failure(record.errors.full_messages)
+      end
+    end
+
+    def reload!
+      @total_count = @scope.reset.count
+      @page = [[1, @page].max, total_pages].min
+      load_page
+    end
+
+    private
+
+    def load_page
+      @records = ordered_scope.limit(@per_page).offset((@page - 1) * @per_page).to_a
+    end
+
+    def ordered_scope
+      s = @scope.reset
+      if s.order_values.empty?
+        s.order(s.klass.arel_table[s.klass.primary_key])
+      else
+        s
+      end
+    end
+
+    def row_hash(record)
+      columns.each_with_object({}) do |col, hash|
+        hash[col.key] = record.public_send(col.key)
+      end
+    end
+
+    READONLY_COLUMNS = %w[id created_at updated_at].freeze
+
+    def infer_columns
+      model = @scope.klass
+      model.column_names.map do |name|
+        col = model.columns_hash[name]
+        Column.new(
+          key: name.to_sym,
+          type: map_ar_type(col.type),
+          width: guess_width(name, col.type),
+          editable: !READONLY_COLUMNS.include?(name)
+        )
+      end
+    end
+
+    def map_ar_type(ar_type)
+      case ar_type
+      when :text then :text
+      else :string
+      end
+    end
+
+    def guess_width(name, ar_type)
+      case ar_type
+      when :text then nil
+      when :integer then 12
+      when :boolean then 8
+      when :datetime, :timestamp then 22
+      when :date then 12
+      else
+        name == "id" ? 8 : nil
+      end
+    end
+  end
+end

data/lib/ratamin/table_view.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Ratamin
+  class TableView
+    attr_reader :data_source, :table_state
+
+    def initialize(data_source)
+      @data_source = data_source
+      @table_state = RatatuiRuby::TableState.new(0)
+    end
+
+    def render(tui, frame, area)
+      columns = data_source.columns
+      rows = data_source.rows
+
+      header = columns.map(&:label)
+
+      table_rows = rows.map do |row|
+        columns.map { |col| format_cell(row[col.key], col) }
+      end
+
+      widths = compute_widths(columns, area.width)
+
+      table = tui.table(
+        header: header,
+        rows: table_rows,
+        widths: widths,
+        row_highlight_style: {bg: :dark_gray, modifiers: [:bold]},
+        highlight_symbol: "> ",
+        block: tui.block(
+          title: " #{title_text} ",
+          borders: [:all],
+          border_type: :rounded,
+          border_style: {fg: :cyan}
+        ),
+        style: {fg: :white}
+      )
+
+      frame.render_stateful_widget(table, area, @table_state)
+    end
+
+    def selected_index
+      @table_state.selected
+    end
+
+    def selected_row
+      idx = selected_index
+      return nil if idx.nil? || idx >= data_source.row_count
+      data_source.rows[idx]
+    end
+
+    def select_next
+      max = data_source.row_count - 1
+      return if max < 0
+      return if (selected_index || 0) >= max
+      @table_state.select_next
+    end
+
+    def select_previous
+      return if (selected_index || 0) <= 0
+      @table_state.select_previous
+    end
+
+    def select_first
+      @table_state.select_first
+    end
+
+    def select_last
+      max = data_source.row_count - 1
+      @table_state.select(max) if max >= 0
+    end
+
+    def reset_selection
+      @table_state.select(0)
+    end
+
+    private
+
+    def title_text
+      ds = data_source
+      if ds.paginated?
+        "Records (page #{ds.page}/#{ds.total_pages}, #{ds.total_count} total)"
+      else
+        "Records (#{ds.row_count})"
+      end
+    end
+
+    def format_cell(value, column)
+      text = value.to_s
+      case column.type
+      when :text
+        # Truncate long text for table display
+        text.length > 40 ? "#{text[0, 37]}..." : text
+      else
+        text
+      end
+    end
+
+    def compute_widths(columns, available_width)
+      # Reserve space for borders (2) + highlight symbol (2) + column spacing
+      usable = available_width - 4
+      total_spacing = [columns.length - 1, 0].max
+
+      columns.map do |col|
+        if col.width
+          RatatuiRuby::Layout::Constraint.length(col.width)
+        else
+          RatatuiRuby::Layout::Constraint.fill(1)
+        end
+      end
+    end
+  end
+end

data/lib/ratamin/update_result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ratamin
+  UpdateResult = Data.define(:ok, :errors) do
+    def initialize(ok:, errors: [])
+      super
+    end
+
+    def ok? = ok
+    def failed? = !ok
+
+    def self.success
+      new(ok: true)
+    end
+
+    def self.failure(errors)
+      new(ok: false, errors: Array(errors))
+    end
+  end
+end

data/lib/ratamin/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ratamin
+  VERSION = "0.1.0"
+end

data/lib/ratamin.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "ratatui_ruby"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module Ratamin
+  class Error < StandardError; end
+end

data/sig/ratamin.rbs

@@ -0,0 +1,4 @@
+module Ratamin
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: ratamin
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- merely
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ratatui_ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: A terminal UI for browsing and editing ActiveRecord scopes, built on
+  ratatui_ruby.
+email:
+- git@merely.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitmodules"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/demo.rb
+- lib/ratamin.rb
+- lib/ratamin/app.rb
+- lib/ratamin/array_data_source.rb
+- lib/ratamin/column.rb
+- lib/ratamin/data_source.rb
+- lib/ratamin/editor_bridge.rb
+- lib/ratamin/form_state.rb
+- lib/ratamin/form_view.rb
+- lib/ratamin/scope_data_source.rb
+- lib/ratamin/table_view.rb
+- lib/ratamin/update_result.rb
+- lib/ratamin/version.rb
+- sig/ratamin.rbs
+homepage: https://github.com/onyxblade/ratamin
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/onyxblade/ratamin
+  source_code_uri: https://github.com/onyxblade/ratamin
+  changelog_uri: https://github.com/onyxblade/ratamin/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: TUI admin console for ActiveRecord
+test_files: []