raindown 0.3.0 → 0.5.0

data/lib/raindown/tui/navigator.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative 'file_tree'
+require_relative 'commands'
+require_relative 'outline'
+require_relative 'pane'
+
+module Raindown
+  module TUI
+    # What the terminal UI shows and does, in plain Ruby, with no terminal: a FileTree of the project's Markdown files,
+    # beside the open file's Outline. The Screen draws it and sends it events, like :down or
+    # [:press, :outline, 3, :execute], and handle returns what the Screen should do next:
+    #   nil                     draw again
+    #   :quit                   stop
+    #   [:run, command]         leave the screen to run a command, like the editor, then call ran
+    #   [:wait, message, task]  show the message while the task runs, like an endpoint's request
+    class Navigator
+      include Commands
+
+      # Keys of the events that move the cursor or the focus, and those that act on what's selected.
+      MOVES = { up: -1, down: 1 }.freeze
+      PANES = { tab: nil, left: :files, right: :outline }.freeze
+      ACTIONS = { execute: :execute, edit: :edit, write_back: :write_back, reload: :reload, tick: :refresh }.freeze
+
+      attr_reader :focus, :status
+
+      def initialize(root:, path: nil)
+        @files = FileTree.new(root:)
+        @focus = :files
+        @panes = { files: Pane.new { @files.rows }, outline: Pane.new { @outline ? @outline.rows : [] } }
+        @status = [:info, 'Tab switches panes, Enter opens and folds, q quits']
+        first = @files.rows.find { it.kind == :file }&.target
+        show(path || first) if path || first
+      end
+
+      def handle(event)
+        name, *args = event
+        return :quit if name == :quit
+        return move(MOVES[name]) if MOVES.key?(name)
+        return switch(PANES[name] || other_pane) if PANES.key?(name)
+        return select(*args) if name == :select
+        return press(*args) if name == :press
+        return activate(name) if %i[enter toggle].include?(name)
+
+        send(ACTIONS[name]) if ACTIONS.key?(name)
+      end
+
+      # After the editor closes, the file is written back, like a save while it's watched, and read again.
+      def ran
+        write_back
+      end
+
+      def root = @files.root
+      def path = @outline&.path
+      def relative(path) = @files.relative(path)
+
+      def rows(pane) = @panes[pane].rows
+      def cursor(pane) = @panes[pane].cursor
+      def visible(pane, height) = @panes[pane].visible(height)
+
+      private
+
+      def show(path)
+        @outline = Outline.new(File.expand_path(path))
+        @panes[:outline].reset
+      end
+
+      def other_pane
+        @focus == :files ? :outline : :files
+      end
+
+      def move(by)
+        @panes[@focus].move(by)
+        nil
+      end
+
+      def switch(pane)
+        @focus = pane
+        nil
+      end
+
+      def select(pane, index)
+        @focus = pane
+        @panes[pane].cursor = index
+        nil
+      end
+
+      def press(pane, index, event)
+        select(pane, index)
+        handle(event)
+      end
+
+      def selected(pane = @focus)
+        @panes[pane].selected
+      end
+
+      # Enter opens what's selected, or folds it, and Space only folds.
+      # A line of output, or a directive without any, opens in the editor.
+      def activate(name)
+        row = selected
+        return edit if name == :enter && editable?(row)
+
+        case row&.kind
+        when :folder then @files.toggle(row.target)
+        when :file then open_file(row.target) if name == :enter
+        when :heading then @outline.fold(row.target)
+        when :directive then @outline.expand(row.target) if row.target.output
+        end
+        nil
+      end
+
+      def editable?(row)
+        row&.kind == :output || (row&.kind == :directive && !row.target.output)
+      end
+
+      def open_file(path)
+        show(path)
+        @focus = :outline
+        info("Opened #{relative(path)}")
+      end
+    end
+  end
+end

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,9 +19,8 @@ module Raindown
 
       $stdout.sync = true
 
-      rewrite
-      render
-      puts "Watching #{path} for changes (writing to #{output})..."
+      safely { rewrite }
+      puts "Watching #{path} for changes..."
 
       listener.start
       sleep
@@ -35,25 +34,24 @@ module Raindown
 
       Listen.to(directory) do |modified, added, _removed|
         next unless (modified + added).any? { |f| File.basename(f) == filename }
-        # Formatting saves the file again, and that change triggers the render.
-        next if rewrite
 
-        render
-        puts "Re-rendered #{path} -> #{output}"
+        # Writing back saves the file again, and that save changes nothing, so it ends there.
+        safely { puts "Updated #{path}" if rewrite }
       end
     end
 
-    # The files' metadata is loaded again each time, so new and renamed files are listed.
-    def rewrite
-      Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
-    end
+    # An error in the file is shown rather than stopping the watcher, so it can be fixed and saved again.
+    def safely
+      yield
+    rescue StandardError => e
+      raise if ENV['RAINDOWN_DEBUG']
 
-    def render
-      File.write(output, Raindown.render_file(path:, bare:, metadata: Pages.for(path)))
+      warn "raindown: #{path}: #{e.message}"
     end
 
-    def default_output
-      "#{File.dirname(path)}/#{File.basename(path, '.*')}.html"
+    # The files' metadata is loaded again each time, so new and renamed files are listed.
+    def rewrite
+      Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
     end
   end
 end

data/lib/raindown.rb

@@ -35,9 +35,6 @@ module Raindown
     def self.list(**) = []
   end
 
-  # Headings with an id, which are the ones a table of contents links to.
-  HEADINGS = 'h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]'
-
   module_function
 
   # Directives show in bold and code is highlighted, unless the file's project changes them in .raindown/config.yml.

data/lib/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-10-20 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
@@ -80,21 +94,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: lownode
+  name: lowkey
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.7.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.7.0
 - !ruby/object:Gem::Dependency
-  name: nokogiri
+  name: lownode
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -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