raindown 0.4.0 → 0.5.0

data/lib/raindown/tui/outline.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative '../document'
+require_relative 'row'
+
+module Raindown
+  module TUI
+    # The outline pane: a file's headings and directives, read from its Document. Headings fold the section below them,
+    # and a directive's output, the lines Raindown wrote back, expands below it. Both start folded away.
+    class Outline
+      attr_reader :path, :error
+
+      def initialize(path)
+        @path = path
+        @folded = Set.new
+        @expanded = Set.new
+        read
+      end
+
+      # Reads the file again, keeping what's folded.
+      def read
+        @mtime = File.mtime(path)
+        @document = Document.read(path)
+        @lines = File.readlines(path, chomp: true)
+        @document.directives # Finds an error in the file, like a missing end tag, now rather than while drawing.
+        @error = nil
+      rescue StandardError => e
+        @error = e.message
+      end
+
+      def changed?
+        File.exist?(path) && File.mtime(path) != @mtime
+      end
+
+      def fold(heading)
+        @folded.delete?(heading.line) || @folded.add(heading.line)
+      end
+
+      def expand(directive)
+        @expanded.delete?(directive.line) || @expanded.add(directive.line)
+      end
+
+      def rows
+        return [Row.new(text: error, depth: 0, kind: :error, target: 1)] if error
+
+        sections.flat_map do |heading, items|
+          next items.flat_map { directive_rows(it, depth: 0) } unless heading
+
+          depth = heading.level - min_level + 1
+          [heading_row(heading), *(items.flat_map { directive_rows(it, depth:) } unless @folded.include?(heading.line))]
+        end
+      end
+
+      private
+
+      # Each heading with the directives below it, leaving out the headings in a folded heading's section.
+      # Directives before the first heading come first, with no heading.
+      def sections
+        sections = [[nil, []]]
+        hidden = nil
+
+        items.each do |item|
+          heading = item.is_a?(Document::Heading)
+          next if hidden && !(heading && item.level <= hidden)
+
+          hidden = (item.level if @folded.include?(item.line)) if heading
+          heading ? sections << [item, []] : sections.last.last << item
+        end
+
+        sections
+      end
+
+      # Headings a directive wrote are part of its output, so they show when it's expanded rather than on their own.
+      def items
+        outputs = @document.directives.filter_map(&:output)
+        @document.outline.reject { |item| item.is_a?(Document::Heading) && outputs.any? { it.cover?(item.line) } }
+      end
+
+      def min_level
+        @document.headings.map(&:level).min || 1
+      end
+
+      def heading_row(heading)
+        folded = @folded.include?(heading.line) ? ' …' : ''
+        Row.new(text: "#{'#' * heading.level} #{heading.text}#{folded}", depth: heading.level - min_level, kind: :heading,
+                target: heading)
+      end
+
+      def directive_rows(directive, depth:)
+        expanded = @expanded.include?(directive.line)
+        row = Row.new(text: directive_text(directive), depth:, kind: :directive, target: directive,
+                      buttons: buttons(directive, expanded:))
+        return [row] unless expanded
+
+        [row, *directive.output.map do |number|
+          Row.new(text: @lines[number - 1].to_s, depth: depth + 1, kind: :output, target: number)
+        end]
+      end
+
+      def buttons(directive, expanded:)
+        buttons = []
+        buttons << [expanded ? '[-]' : "[+#{directive.output.size}]", :toggle] if directive.output
+        buttons << ['[Run]', :execute] if directive.endpoint?
+        buttons
+      end
+
+      def directive_text(directive)
+        return ":#{directive.name}" unless directive.writes
+
+        [directive.name, ':', (" #{directive.args}" unless directive.args.empty?)].join
+      end
+    end
+  end
+end

data/lib/raindown/tui/pane.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # A pane's cursor and how far it's scrolled, over rows that can change between draws, like when a folder folds.
+    class Pane
+      attr_writer :cursor
+
+      def initialize(&rows)
+        @rows = rows
+        @cursor = 0
+        @offset = 0
+      end
+
+      def rows = @rows.call
+      def selected = rows[cursor]
+
+      # The cursor stays on a row when there are fewer rows than before.
+      def cursor
+        @cursor.clamp(0, [rows.length - 1, 0].max)
+      end
+
+      def move(by)
+        @cursor = (cursor + by).clamp(0, [rows.length - 1, 0].max)
+      end
+
+      def reset
+        @cursor = 0
+        @offset = 0
+      end
+
+      # The rows that fit in the height, scrolled so the cursor's row is one of them, and the first one's index.
+      def visible(height)
+        cursor = self.cursor
+        @offset = @offset.clamp([cursor - height + 1, 0].max, cursor)
+
+        [rows[@offset, height] || [], @offset]
+      end
+    end
+  end
+end

data/lib/raindown/tui/row.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # A line of a pane. Target is what it's about: a folder or file path, a Heading or Directive, or a line number.
+    # Buttons are [label, event] pairs, like ['[Run]', :execute].
+    Row = Data.define(:text, :depth, :kind, :target, :buttons) do
+      def initialize(buttons: [], **) = super
+
+      # The line the editor opens at for the row.
+      def line
+        target.is_a?(Integer) ? target : target.line
+      end
+    end
+  end
+end

data/lib/raindown/tui/screen.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'curses'
+
+require_relative 'input'
+require_relative 'layout'
+require_relative 'styles'
+
+module Raindown
+  module TUI
+    # Paints a Navigator's Layout with curses, and sends the Navigator the events of keys and clicks, read with Input.
+    # Only this class draws on the terminal, so another library could draw the same Layout.
+    class Screen
+      # How often, in milliseconds, the open file is checked for changes while no key is pressed.
+      TICK = 500
+
+      def initialize(navigator)
+        @navigator = navigator
+        @zones = []
+      end
+
+      def run
+        start
+
+        loop do
+          draw
+          effect = @navigator.handle(read)
+          break if effect == :quit
+
+          perform(*effect) if effect.is_a?(Array)
+        end
+      rescue Interrupt
+        nil
+      ensure
+        stop
+      end
+
+      private
+
+      def perform(name, *args)
+        case name
+        when :run
+          suspend { system(*args.first) }
+          @navigator.ran
+        when :wait
+          message, task = args
+          show(message)
+          task.call
+        end
+      end
+
+      def start
+        ENV['ESCDELAY'] ||= '25'
+        Curses.init_screen
+        @styles = Styles.start
+        Curses.noecho
+        Curses.cbreak
+        Curses.nonl
+        Curses.curs_set(0)
+        Curses.stdscr.keypad(true)
+        Curses.stdscr.timeout = TICK
+        Curses.mousemask(Curses::BUTTON1_PRESSED | Curses::BUTTON1_CLICKED | Input.wheel.keys.sum)
+        Curses.mouseinterval(0)
+      end
+
+      def stop
+        Curses.close_screen
+      end
+
+      def draw
+        lines = Layout.new(@navigator, width: Curses.cols, height: Curses.lines).lines
+        @zones = Input.zones(lines)
+        window = Curses.stdscr
+        window.erase
+
+        lines.each_with_index do |segments, row|
+          window.setpos(row, 0)
+          # Writing the bottom-right corner would scroll the screen, so the last line stops a column short.
+          segments = last_line(segments) if row == Curses.lines - 1
+          segments.each { |segment| paint(window, segment) }
+        end
+
+        window.refresh
+      end
+
+      def paint(window, segment)
+        window.attron(@styles.fetch(segment.style, Curses::A_NORMAL)) { window.addstr(segment.text) }
+      end
+
+      def last_line(segments)
+        *rest, last = segments
+        [*rest, last.with(text: last.text[0...-1])]
+      end
+
+      # The next event, or :tick when no key is pressed in time, or nil for keys without one, like a resize.
+      def read
+        key = Curses.stdscr.getch
+        return :tick if key.nil?
+        return mouse if key == Curses::KEY_MOUSE
+
+        Curses.stdscr.clear if key == Curses::KEY_RESIZE
+        Input.key_event(key)
+      end
+
+      def mouse
+        event = Curses.getmouse
+        Input.mouse_event(event, @zones) if event
+      end
+
+      # Shows a message in the status line while something slow runs, like an endpoint's request.
+      def show(message)
+        window = Curses.stdscr
+        window.setpos(Curses.lines - 2, 0)
+        window.clrtoeol
+        window.addstr(" #{message}"[0, Curses.cols])
+        window.refresh
+      end
+
+      # Leaves the screen to the command, like the editor, and comes back to it after.
+      def suspend
+        Curses.def_prog_mode
+        Curses.close_screen
+        yield
+      ensure
+        Curses.reset_prog_mode
+        Curses.stdscr.clear
+        Curses.refresh
+      end
+    end
+  end
+end

data/lib/raindown/tui/styles.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'curses'
+
+module Raindown
+  module TUI
+    # The curses attributes of a Layout's styles, in colour on the terminal's own background when it has colours.
+    module Styles
+      COLORS = { directive: Curses::COLOR_CYAN, button: Curses::COLOR_YELLOW, error: Curses::COLOR_RED,
+                 folder: Curses::COLOR_BLUE }.freeze
+
+      module_function
+
+      # Sets up the colours, once the screen has started, and returns the attribute of each style.
+      def start
+        colors = Curses.has_colors?
+        start_colors if colors
+        color = ->(name) { colors ? Curses.color_pair(COLORS.keys.index(name) + 1) : Curses::A_NORMAL }
+
+        {
+          title: Curses::A_REVERSE | Curses::A_BOLD, selected: Curses::A_REVERSE, cursor: Curses::A_UNDERLINE,
+          heading: Curses::A_BOLD, directive: color[:directive], output: Curses::A_DIM,
+          error: color[:error] | Curses::A_BOLD, button: color[:button] | Curses::A_BOLD,
+          selected_button: color[:button] | Curses::A_REVERSE, folder: color[:folder] | Curses::A_BOLD,
+          key: Curses::A_REVERSE, border: Curses::A_DIM
+        }
+      end
+
+      def start_colors
+        Curses.start_color
+        Curses.use_default_colors
+        COLORS.each_value.with_index(1) { |color, pair| Curses.init_pair(pair, color, -1) }
+      end
+    end
+  end
+end

data/lib/raindown/tui.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'nodes'
+require_relative 'projects'
+require_relative 'tui/navigator'
+
+module Raindown
+  # The terminal UI, started with "raindown tui": a project's Markdown files beside the open file's outline,
+  # where directives fold, endpoints run and the editor opens at a line. Curses only loads here,
+  # so watching and rendering start without it.
+  module TUI
+    module_function
+
+    # PATH is a file to open, or a directory. Its project is the one it's in, or else the directory itself.
+    def start(path)
+      require_relative 'tui/screen'
+      # Without a terminal, curses' own error is "Error opening terminal: unknown".
+      abort('raindown tui needs a terminal') unless $stdin.tty? && $stdout.tty?
+
+      path = File.expand_path(path)
+      root = Projects.root(path) || (File.directory?(path) ? path : File.dirname(path))
+      Nodes.load(File.join(root, Nodes::FOLDER))
+
+      Screen.new(Navigator.new(root:, path: (path unless File.directory?(path)))).run
+    end
+  end
+end

data/lib/raindown/watcher.rb

@@ -4,12 +4,12 @@ require_relative '../raindown'
 require_relative 'rewriter'
 
 module Raindown
+  # Watches one file and writes back to it as it's saved, like its TOC, tables and endpoint responses.
   class Watcher
-    attr_reader :path, :output, :bare, :execute
+    attr_reader :path, :bare, :execute
 
-    def initialize(path:, output: nil, bare: false, execute: false)
+    def initialize(path:, bare: false, execute: false)
       @path = path
-      @output = output || default_output
       @bare = bare
       @execute = execute
     end
@@ -19,11 +19,8 @@ module Raindown
 
       $stdout.sync = true
 
-      safely do
-        rewrite
-        render
-      end
-      puts "Watching #{path} for changes (writing to #{output})..."
+      safely { rewrite }
+      puts "Watching #{path} for changes..."
 
       listener.start
       sleep
@@ -38,13 +35,8 @@ module Raindown
       Listen.to(directory) do |modified, added, _removed|
         next unless (modified + added).any? { |f| File.basename(f) == filename }
 
-        safely do
-          # Formatting saves the file again, and that change triggers the render.
-          next if rewrite
-
-          render
-          puts "Re-rendered #{path} -> #{output}"
-        end
+        # Writing back saves the file again, and that save changes nothing, so it ends there.
+        safely { puts "Updated #{path}" if rewrite }
       end
     end
 
@@ -61,13 +53,5 @@ module Raindown
     def rewrite
       Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
     end
-
-    def render
-      File.write(output, Raindown.render_file(path:, bare:, metadata: Pages.for(path)))
-    end
-
-    def default_output
-      "#{File.dirname(path)}/#{File.basename(path, '.*')}.html"
-    end
   end
 end

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Raindown
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: curses
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: dirload
   requirement: !ruby/object:Gem::Requirement
@@ -167,6 +181,7 @@ files:
 - lib/nodes/endpoint_node.rb
 - lib/nodes/list_node.rb
 - lib/raindown.rb
+- lib/raindown/actions.rb
 - lib/raindown/bare_directives.rb
 - lib/raindown/chart/bars.rb
 - lib/raindown/chart/chart.rb
@@ -180,6 +195,7 @@ files:
 - lib/raindown/code_blocks.rb
 - lib/raindown/config.rb
 - lib/raindown/directives.rb
+- lib/raindown/document.rb
 - lib/raindown/endpoint/curl.rb
 - lib/raindown/endpoint/endpoint_runner.rb
 - lib/raindown/files.rb
@@ -193,9 +209,23 @@ files:
 - lib/raindown/page.rb
 - lib/raindown/pages.rb
 - lib/raindown/pre_renderer.rb
+- lib/raindown/project_worker.rb
+- lib/raindown/projects.rb
 - lib/raindown/rewriter.rb
+- lib/raindown/supervisor.rb
 - lib/raindown/table_formatter.rb
 - lib/raindown/toc.rb
+- lib/raindown/tui.rb
+- lib/raindown/tui/commands.rb
+- lib/raindown/tui/file_tree.rb
+- lib/raindown/tui/input.rb
+- lib/raindown/tui/layout.rb
+- lib/raindown/tui/navigator.rb
+- lib/raindown/tui/outline.rb
+- lib/raindown/tui/pane.rb
+- lib/raindown/tui/row.rb
+- lib/raindown/tui/screen.rb
+- lib/raindown/tui/styles.rb
 - lib/raindown/variables.rb
 - lib/raindown/watcher.rb
 - lib/version.rb