raindown 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dffe3184c451794454149de18701ac6bd1afc2674b6a41385773d0f052bb2e5
-  data.tar.gz: 4e49463244dffc8e9b39873e2137f072f8632daec02c314d928fe09bbb115fd5
+  metadata.gz: 6ea9df31d83ebabf0649ad353b75e2f2546aeb10c31aa97038bdd85f5e45fd2c
+  data.tar.gz: cc736f0d57e576c476629bfa7fe37405139cb1b880e86908e71e7e8d8b22926c
 SHA512:
-  metadata.gz: 9502a0acb5cca634c884f74b8f2fc3e3a83c3fbe5bc635df7fccb779147718563a0a44679b3b3e6a1cf9da9e691026ff55953fc9a6b0aafad9cc48444eec12c6
-  data.tar.gz: dc928865b0da23c1b3dd67d859e94a3e718fe370b3d21d9344060cd5019e82fd5cce029b56d6008632690f9f1cc6f782cd41a8c38ca6d233bd06336f29fb7077
+  metadata.gz: 851438f9079a944aca1dc2f97d0c5081822d0ce31df12e536ca10dce8d471233ee0879fc91b7004fcf7949159554dec7cd0d1e4aa3d50b8cee4009dbd3180766
+  data.tar.gz: 27863d35bb59084303144bdc0b1ea3852028a55c854e8142456c3e1d8f9ee495a3d5489dc00c91ce474bcd9eda833deb42d4f3696118bb24c25e913dabb54372

data/lib/raindown/actions.rb

@@ -24,7 +24,7 @@ module Raindown
     # Writes back the whole file, like saving it while it's watched, with bare directives allowed, and endpoints with no
     # response run, when asked, like with --bare and -x.
     def write_back(path, bare: false, execute: false)
-      Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
+      Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path)).changed?
     end
 
     # Runs one endpoint's request and writes its response, replacing any response it had, then raises when the response

data/lib/raindown/blueprints.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require 'fileutils'
 require 'json'
 require 'time'
 require 'unicode/display_width'
 require_relative 'projects'
 
 module Raindown
-  # Blueprints from Claude Code's replies, kept in a project's .raindown/blueprints.md, which the terminal UI's Blueprints page
+  # Blueprints from Claude Code's replies, kept in a project's .raindown/data/blueprints.md, which the terminal UI's Blueprints page
   # shows, newest first. Each is a code block under a heading of when it was saved and its kind:
   #   ## 2026-10-30T03:14:07Z · mockup
   #
@@ -32,7 +33,7 @@ module Raindown
         "#{time.sub('T', ' ').sub(/:\d\dZ\z/, ' UTC')}#{SEPARATOR}#{kind}"
       end
 
-      # As it's saved in .raindown/blueprints.md, under when it was saved and its kind, then its description.
+      # As it's saved in .raindown/data/blueprints.md, under when it was saved and its kind, then its description.
       def markdown(saved_at)
         about = "#{description}\n\n" if description
         "## #{saved_at}#{SEPARATOR}#{kind}\n\n#{about}```#{kind}\n#{lines.join("\n")}\n```\n\n"
@@ -49,7 +50,7 @@ module Raindown
       def distance(other) = [(top - other.top).abs, (left + right - other.left - other.right).abs]
     end
 
-    FILE = File.join('.raindown', 'blueprints.md')
+    FILE = File.join('.raindown', 'data', 'blueprints.md')
     # The kinds a code block can be marked with to be a blueprint.
     KINDS = %w[mockup diagram chart table other].freeze
     # What a blueprint's drawn with: lines, like boxes' and arrows', and blocks, like charts' bars.
@@ -79,8 +80,7 @@ module Raindown
       return [] unless File.exist?(path)
 
       lines = File.readlines(path, chomp: true)
-      starts = lines.each_index.select { lines[it].start_with?('## ') }
-      starts.filter_map { |start| blueprint(lines, start) }.reverse
+      lines.each_index.select { lines[it].start_with?('## ') }.filter_map { blueprint(lines, it) }.reverse
     end
 
     # Saves the blueprints in Claude Code's last reply, from its Stop hook's JSON, to the project it's working in, if any,
@@ -91,7 +91,8 @@ module Raindown
       return if drawn.empty?
 
       time = Time.now.utc.iso8601
-      File.open(File.join(root, FILE), 'a') { |file| drawn.each { file.write(it.markdown(time)) } }
+      path = File.join(root, FILE).tap { FileUtils.mkdir_p(File.dirname(it)) }
+      File.open(path, 'a') { |file| drawn.each { file.write(it.markdown(time)) } }
     end
 
     # The text's code blocks that are blueprints, each with its kind and the paragraph above it.

data/lib/raindown/cli.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'open3'
+require 'tmpdir'
 require 'trees'
 require_relative '../raindown'
 require_relative '../version'
@@ -32,7 +34,7 @@ module Raindown
         init [DIRECTORY]    Create a .raindown folder for the project's config and nodes (default: current directory)
         server              Keep Raindown loaded for an editor, answering a JSON request a line on stdin with its HTML,
                             or its Markdown as it would be written back, like --stdin and --stdin --rewrite
-        blueprints            Save the blueprints in Claude Code's last reply to .raindown/blueprints.md, for the terminal
+        blueprints            Save the blueprints in Claude Code's last reply to .raindown/data/blueprints.md, for the terminal
                             UI's Blueprints page, as a Stop hook that's given the hook's JSON
 
       Options:
@@ -52,12 +54,8 @@ module Raindown
       Set RAINDOWN_DEBUG=1 to show where an error happened.
     TEXT
 
-    CONFIG = <<~YAML
-      # Raindown project settings. See https://raindown.dev/docs/config
-      #
-      # Leave code blocks unhighlighted, so the browser can highlight them instead:
-      # highlight_code: false
-    YAML
+    # The files "raindown init" puts in a project's .raindown folder, like "rain new" clones raindeer-template.
+    TEMPLATE_URL = 'https://github.com/rainpour/raindown-init'
 
     # A path opens the terminal UI, or after "watch" it's watched, and with --html or --stdin it's rendered. The flags
     # are keyword arguments, in any order, like -x for x:, and --html is the OUTPUT when it's given one.
@@ -111,16 +109,20 @@ module Raindown
       abort("raindown: #{path}: #{error.message}")
     end
 
-    # Creates the .raindown folder that marks a project's root and holds its config.yml and nodes.
+    # Clones raindown-init into the .raindown folder that marks a project's root and holds its config.yml and nodes,
+    # keeping any files already there.
     def self.init(directory = nil)
       folder = File.join(directory || Dir.pwd, Nodes::FOLDER)
       config = File.join(folder, Config::FILE)
       return puts("#{config} already exists") if File.exist?(config)
 
-      FileUtils.mkdir_p(folder)
-      File.write(config, CONFIG)
-      gitignore = File.join(folder, '.gitignore')
-      File.write(gitignore, "#{EndpointVariables::LOCAL_FILE}\n") unless File.exist?(gitignore)
+      Dir.mktmpdir do |clone|
+        clone_template(clone)
+        FileUtils.mkdir_p(folder)
+        (Dir.children(clone) - ['.git']).each do |name|
+          FileUtils.cp_r(File.join(clone, name), folder) unless File.exist?(File.join(folder, name))
+        end
+      end
       puts "Created #{config}"
       puts 'Put your own nodes in the same folder. See https://raindown.dev/docs/components'
     end
@@ -136,6 +138,11 @@ module Raindown
     class << self
       private
 
+      def clone_template(directory)
+        output, status = Open3.capture2e('git', 'clone', '--quiet', '--depth', '1', TEMPLATE_URL, directory)
+        abort("Couldn't clone #{TEMPLATE_URL}:\n#{output}") unless status.success?
+      end
+
       # Endpoints run while formatting, which --stdin skips, so -x can't go with it. --html - prints, like --html.
       def open_path(path, html:, stdin:, bare:, execute:)
         output = html unless [true, '-'].include?(html)
@@ -152,14 +159,13 @@ module Raindown
         Nodes.load(path)
 
         metadata = Pages.for(path)
-        Rewriter.update(path:, bare:, execute:, metadata:)
+        failures = Rewriter.update(path:, bare:, execute:, metadata:).failures
         write(output, Raindown.render_file(path:, bare:, metadata:))
-        check_endpoints(path, bare:)
+        check_endpoints(failures)
       end
 
       # Endpoint responses that fail their checks, like status: 200, are listed, and fail the command, for CI.
-      def check_endpoints(path, bare:)
-        failures = EndpointRunner.failures(content: Utils.read_markdown(path), path:, bare:)
+      def check_endpoints(failures)
         return if failures.empty?
 
         warn(*failures.map { "Endpoint check failed: #{it}" })

data/lib/raindown/code_blocks.rb

@@ -5,6 +5,8 @@ module Raindown
   module CodeBlocks
     FENCE = /\A {0,3}(`{3,}|~{3,})[ \t]*(\S*)/
     SNIPPET_LANGUAGES = %w[sh bash shell zsh console curl].freeze
+    # The line closing a fence, like ``` or ~~~~, compiled once per fence.
+    CLOSINGS = Hash.new { |closings, fence| closings[fence] = /\A {0,3}#{fence[0]}{#{fence.length},}[ \t]*$/ }
 
     module_function
 
@@ -13,7 +15,7 @@ module Raindown
       fence, language = lines[index]&.match(FENCE)&.captures
       return unless fence
 
-      close = (index + 1...lines.length).find { |i| lines[i].match?(/\A {0,3}#{fence[0]}{#{fence.length},}[ \t]*$/) }
+      close = (index + 1...lines.length).find { |i| lines[i].match?(CLOSINGS[fence]) }
       { open: index, close:, language:, body: lines[index + 1...close].join } if close
     end
 

data/lib/raindown/editing.rb

@@ -17,8 +17,8 @@ module Raindown
 
     def rewrite_markdown(markdown, path:, bare: false, execute: false)
       Nodes.load(path)
-      rewritten = Rewriter.rewrite(content: markdown, path:, bare:, execute:, metadata: Pages.for(path))
-      { output: rewritten, warnings: EndpointRunner.failures(content: rewritten, path:, bare:).map { "Endpoint check failed: #{it}" } }
+      rewrite = Rewriter.rewrite(content: markdown, path:, bare:, execute:, metadata: Pages.for(path))
+      { output: rewrite.content, warnings: rewrite.failures.map { "Endpoint check failed: #{it}" } }
     end
   end
 end

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -42,11 +42,6 @@ module Raindown
       new(content:, path:, bare: BareDirectives.enabled?(path:, content:, bare:), execute:).rewrite
     end
 
-    # The file's failed checks, like "api.md:3: expected status 200, received 404", from the responses in it.
-    def self.failures(content:, path: nil, bare: false)
-      new(content:, path:, bare: BareDirectives.enabled?(path:, content:, bare:)).tap(&:rewrite).failures
-    end
-
     def initialize(content:, path: nil, bare: false, execute: false, only: nil)
       @lines = content.lines
       @path = path

data/lib/raindown/markdown_nodes.rb

@@ -26,7 +26,7 @@ module Raindown
       end
     end
 
-    # Whether a file is a Markdown Component, by its extension and name, so .raindown/blueprints.md isn't one.
+    # Whether a file is a Markdown Component, by its extension and name, so .raindown/data/blueprints.md isn't one.
     def file?(path)
       EXTENSIONS.include?(File.extname(path)) && File.basename(path, '.*').match?(NAME)
     end

data/lib/raindown/pages.rb

@@ -13,23 +13,49 @@ module Raindown
   #   folder: basics, order: 1, path: docs/_basics/_1-getting-started.md
   # Folder tags can share a folder name with "&", like docs/_1&_basics/getting-started.md.
   # An app can add its own metadata by subclassing and overriding implicit_metadata, like Raindeer's URL paths.
+  # Each file's front matter is only read once something lists the files. The listing and the front matter are kept for
+  # as long as the process runs, like "raindown server", until they change.
   class Pages
     EXTENSIONS = %w[md rd markdown raindown].freeze
     SEGMENTS = Regexp.union(['/', '&', '-'])
 
     class << self
+      # Each file's front matter, by its path, with the time it was modified when it was read.
+      def front_matters
+        @front_matters ||= {}
+      end
+
       # The Markdown files under a project's root, the folder with its .raindown folder or else the file's folder.
       def for(path)
         file_directory = File.dirname(File.expand_path(path))
         load(root: Nodes.find_folder(file_directory)&.then { File.dirname(it) } || file_directory)
       end
 
-      # Lists the files under the root with Dirload, without loading them.
+      # Lists the files under the root, without loading them, for Dirload.
       def load(root:)
         require 'dirload'
-        file_types = Dirload.file_paths(absolute_path: root).group_by { Dirload.extension(file_path: it) }
+        file_types = file_paths(root).group_by { Dirload.extension(file_path: it) }
         new(metadata: Dirload::Metadata.new(loaded_paths: {}, missed_paths: [], file_types:), root:)
       end
+
+      # The files under the root, outside hidden folders, like Dirload lists them. They're listed again once a folder
+      # among them has changed, which adding, removing or renaming a file or folder in it does.
+      def file_paths(root)
+        listing = listings[root]
+        return listing[:file_paths] if listing&.dig(:folders)&.all? { |folder, modified| modified_at(folder) == modified }
+
+        folders, file_paths = Dir["#{root}/**/*"].partition { File.directory?(it) }
+        listings[root] = { file_paths:, folders: [root, *folders].to_h { [it, modified_at(it)] } }
+        file_paths
+      end
+
+      def listings
+        @listings ||= {}
+      end
+
+      def modified_at(path)
+        File.mtime(path) if File.exist?(path)
+      end
     end
 
     attr_reader :root
@@ -39,10 +65,6 @@ module Raindown
       @root = root
       @render_options = render_options
       @file_paths = metadata.file_types.values_at(*EXTENSIONS).flatten.compact
-      @metadata = {}
-      @tags = {}
-
-      @file_paths.each { |file_path| process(file_path:) }
     end
 
     # The files with any of the tags, like list(folder: 'basics') or list(tags: 'ruby'), sorted by order.
@@ -53,21 +75,46 @@ module Raindown
     end
 
     def tagged(**tags)
-      tags.flat_map { |type, tag| @tags.dig(type.to_sym, tag) || [] }.uniq
+      tags.flat_map { |type, tag| self.tags.dig(type.to_sym, tag) || [] }.uniq
     end
 
     private
 
+    def metadata
+      process_files unless @metadata
+      @metadata
+    end
+
+    def tags
+      process_files unless @tags
+      @tags
+    end
+
+    def process_files
+      @metadata = {}
+      @tags = {}
+      @file_paths.each { |file_path| process(file_path:) }
+    end
+
     def listed_page(file_path)
-      Page.new(file_path:, metadata: @metadata[file_path], render_options: @render_options)
+      Page.new(file_path:, metadata: metadata[file_path], render_options: @render_options)
     end
 
     def process(file_path:)
-      metadata = implicit_metadata(file_path:).merge(FrontMatter.parse(Utils.read_markdown(file_path)).first)
+      metadata = implicit_metadata(file_path:).merge(front_matter(file_path))
       @metadata[file_path] = metadata
       metadata.each { |type, tag| Array(tag).each { |item| tag(type:, tag: item, file_path:) } }
     end
 
+    # The file's front matter, read again only when the file's changed since it was last read.
+    def front_matter(file_path)
+      modified = File.mtime(file_path)
+      modified_then, front_matter = self.class.front_matters[file_path]
+      return front_matter if modified_then == modified
+
+      FrontMatter.parse(Utils.read_markdown(file_path)).first.tap { self.class.front_matters[file_path] = [modified, it] }
+    end
+
     # The path is relative to the root, like docs/_basics/_1-getting-started.md.
     # A subclass can add or replace metadata here, like Raindeer's Rain::Pages replacing the path with a URL path.
     def implicit_metadata(file_path:)
@@ -104,8 +151,8 @@ module Raindown
 
     # Files with an order come first, by order, then the rest by path.
     def sort_key(file_path)
-      order = @metadata[file_path][:order]
-      [order.is_a?(Numeric) ? 0 : 1, order.is_a?(Numeric) ? order : 0, @metadata[file_path][:path].to_s]
+      order = metadata[file_path][:order]
+      [order.is_a?(Numeric) ? 0 : 1, order.is_a?(Numeric) ? order : 0, metadata[file_path][:path].to_s]
     end
   end
 end

data/lib/raindown/rewriter.rb

@@ -8,26 +8,27 @@ require_relative 'utils'
 module Raindown
   # Rewrites the generated parts of a Markdown file in place before it's rendered:
   # node output, like the TOC, endpoint responses and table alignment.
-  # Each rewriter responds to rewrite(content:, path:, bare:, execute:, metadata:) and returns the new content.
   module Rewriter
-    REWRITERS = [NodeInjector, EndpointRunner, TableFormatter].freeze
+    # The content written back, and the endpoint checks it failed, like "api.md:3: expected status 200, received 404".
+    Rewrite = Data.define(:original, :content, :failures) do
+      def changed?
+        content != original
+      end
+    end
 
     module_function
 
     def rewrite(content:, path:, bare: false, execute: false, metadata: NoMetadata)
-      REWRITERS.reduce(content) do |rewritten, rewriter|
-        rewriter.rewrite(content: rewritten, path:, bare:, execute:, metadata:)
-      end
+      injected = NodeInjector.rewrite(content:, path:, bare:, metadata:)
+      endpoints = EndpointRunner.new(content: injected, path:, bare: BareDirectives.enabled?(path:, content: injected, bare:), execute:)
+      Rewrite.new(original: content, content: TableFormatter.rewrite(content: endpoints.rewrite), failures: endpoints.failures)
     end
 
-    # Returns true when the file changed.
+    # Writes the file only when it changed.
     def update(path:, bare: false, execute: false, metadata: NoMetadata)
-      content = Utils.read_markdown(path)
-      rewritten = rewrite(content:, path:, bare:, execute:, metadata:)
-      return false if rewritten == content
-
-      File.write(path, rewritten)
-      true
+      rewrite(content: Utils.read_markdown(path), path:, bare:, execute:, metadata:).tap do |rewrite|
+        File.write(path, rewrite.content) if rewrite.changed?
+      end
     end
   end
 end

data/lib/raindown/tui/blueprints/blueprints_view.rb

@@ -11,7 +11,7 @@ require_relative 'filter'
 
 module Raindown
   module TUI
-    # The blueprints from Claude Code's replies, in the project's .raindown/blueprints.md, newest first, then those in its
+    # The blueprints from Claude Code's replies, in the project's .raindown/data/blueprints.md, newest first, then those in its
     # code's comments, one at a time, of
     # those its Filter's keywords match, each traced to its code: the arrows move between the boxes drawn in one, or a
     # click on one, the code each box names shows below, Space or another click moving on to

data/lib/raindown/tui/feelings/feelings_log.rb

@@ -22,16 +22,16 @@ module Raindown
       end
     end
 
-    # The feelings everyone's sorted about the code as it is now, kept in .raindown/feelings.csv with the commit they were
+    # The feelings everyone's sorted about the code as it is now, kept in .raindown/data/feelings.csv with the commit they were
     # felt at, which a node can count, like the README's code debt. A feeling about code that's since changed, or gone, moves to
-    # .raindown/memories.csv, so the feelings stay few, and the history's kept.
+    # .raindown/data/memories.csv, so the feelings stay few, and the history's kept.
     class FeelingsLog
       TEMPERS = %w[frolic numb woe dread malice].freeze
       HEADER = %i[timestamp commit checksum location method temper note].freeze
       def initialize(root:)
         @root = root
-        @csv = File.join(root, '.raindown', 'feelings.csv')
-        @memories = File.join(root, '.raindown', 'memories.csv')
+        @csv = File.join(root, '.raindown', 'data', 'feelings.csv')
+        @memories = File.join(root, '.raindown', 'data', 'memories.csv')
       end
 
       # Adds the feeling, as the newest, in place of one about the method before, which moves to the memories if it was

data/lib/raindown/watcher/file_watcher.rb

@@ -51,9 +51,9 @@ module Raindown
 
       # The files' metadata is loaded again each time, so new and renamed files are listed.
       def rewrite
-        changed = Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
-        EndpointRunner.failures(content: Utils.read_markdown(path), path:, bare:).each { warn "Endpoint check failed: #{it}" }
-        changed
+        rewrite = Rewriter.update(path:, bare:, execute:, metadata: Pages.for(path))
+        rewrite.failures.each { warn "Endpoint check failed: #{it}" }
+        rewrite.changed?
       end
     end
   end

data/lib/raindown/watcher/project.rb

@@ -28,10 +28,9 @@ module Raindown
 
       # Writing back saves the file again, and that save changes nothing, so it ends there.
       def update(path)
-        changed = Rewriter.update(path:, bare: @bare, execute: @execute, metadata: Pages.for(path))
-        puts "[#{name}] Updated #{relative(path)}" if changed
-        EndpointRunner.failures(content: Utils.read_markdown(path), path:, bare: @bare)
-                      .each { warn "[#{name}] Endpoint check failed: #{it}" }
+        rewrite = Rewriter.update(path:, bare: @bare, execute: @execute, metadata: Pages.for(path))
+        puts "[#{name}] Updated #{relative(path)}" if rewrite.changed?
+        rewrite.failures.each { warn "[#{name}] Endpoint check failed: #{it}" }
       rescue StandardError => e
         raise if ENV['RAINDOWN_DEBUG']
 

data/lib/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - maedi