raindown 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad54482b1bd78c23942aefb02bc8a8b9cce56e369ecbb67366668187ed521323
-  data.tar.gz: 9d8475c719c52063424a6215c762a926e67641700981b6834dd56e07d410d535
+  metadata.gz: 9d8b4a4baae078b6b14f7ae6fd66dde441f97776e7107a07864ca4c12beebb74
+  data.tar.gz: 582a5012c02638f89991497cc789ef9513e7c13262445784c40ddb026b246574
 SHA512:
-  metadata.gz: 8789f0135781bfe782ae2af47f2bd537cafef9d55a522ba592bbcc1c8f27e0364cfbb860cb0aa106617af0bd6e82d2bd0174084ca4bd3ca7779b82e2e284ff79
-  data.tar.gz: 88237d0429270a0651434511d462b0051b9a752a2e8aae315e4d2bafc0ef833fa1818d8424cf5e025b12655c9df3de6a22e6eab7e23e1b40ec0063d7fe4f3396
+  metadata.gz: 1e8fc0825e5462616ce435e35188f5d41b45b23fdbbb59ff840c140cf46279de4a0e696def346a92f168dc6e04e97d1bcac9e309b1db3d9219fe59eeaadad52a
+  data.tar.gz: 5025d3381c0e0e2049a6b5fe462102438226feaa2d1a563c89b34dde74b1679163071d4df43e61d3a261e489ed71a107ae925db7f4cf08f1b9e83e773b45b46c

data/lib/raindown/actions.rb

@@ -32,7 +32,7 @@ module Raindown
       raise NotAnEndpoint, "The endpoint on line #{directive.line} only renders, so put it in comments to run it" unless directive.writes
 
       content = Utils.read_markdown(path)
-      rewritten = EndpointRunner.new(content:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1).rewrite
+      rewritten = EndpointRunner.new(content:, path:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1).rewrite
       return false if rewritten == content
 
       File.write(path, rewritten)

data/lib/raindown/cli.rb

@@ -37,6 +37,7 @@ module Raindown
                             its extension (to allow bare directives) and can be unsaved. Add --html OUTPUT to write a file
         --bare              Allow bare directives like :toc in Markdown files
         -x, --execute       Run endpoint curl snippets that have no output yet, as files are written back
+        --env NAME          Fill endpoint snippets from the NAME environment in .raindown/environments.yml
         -h, --help          Show this message
         -v, --version       Show the version
 
@@ -52,12 +53,18 @@ module Raindown
 
     # 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.
-    line(':path') do |path, html: nil, stdin: false, bare: false, execute: false, x: false| # rubocop:disable Metrics/ParameterLists -- each keyword is a flag
-      execute { open_path(path, html:, stdin:, bare:, execute: execute || x) }
+    line(':path') do |path, html: nil, stdin: false, bare: false, execute: false, x: false, env: nil| # rubocop:disable Metrics/ParameterLists -- each keyword is a flag
+      execute do
+        ENV['RAINDOWN_ENV'] = env if env
+        open_path(path, html:, stdin:, bare:, execute: execute || x)
+      end
     end
 
-    line('watch :path') do |path, bare: false, execute: false, x: false|
-      execute { watch(path, bare:, execute: execute || x) }
+    line('watch :path') do |path, bare: false, execute: false, x: false, env: nil|
+      execute do
+        ENV['RAINDOWN_ENV'] = env if env
+        watch(path, bare:, execute: execute || x)
+      end
     end
 
     def self.run(argv)

data/lib/raindown/endpoint/curl.rb

@@ -1,18 +1,25 @@
 # frozen_string_literal: true
 
+require 'ipaddr'
 require 'json'
 require 'open3'
 require 'shellwords'
+require 'socket'
+require 'uri'
 
 module Raindown
   # Runs a curl snippet with the curl binary. There's no shell, so pipes, redirects and variables don't apply.
   # Snippets come from files that anyone (or any agent) may have written, so only options that make an HTTP request
   # are allowed: nothing that reads or writes local files, loads a config, or uses another protocol.
+  # Link-local addresses, like the cloud metadata service at 169.254.169.254, are refused, as they can give out
+  # credentials, and redirects aren't followed (no -L), so a URL can't redirect there either.
   module Curl
     class Error < StandardError; end
     Request = Data.define(:method, :url)
 
     TIMEOUT = '30'
+    # The variables curl reads a proxy from, which then looks the names up rather than curl.
+    PROXY_VARIABLES = %w[http_proxy https_proxy HTTPS_PROXY all_proxy ALL_PROXY].freeze
     # --disable must come first and skips ~/.curlrc. The protocol options stop redirects to file:// and the like.
     SAFE_OPTIONS = ['--disable', '--proto', '=http,https', '--proto-redir', '=http,https'].freeze
 
@@ -21,7 +28,7 @@ module Raindown
 
     # Options without a value.
     FLAGS = {
-      '-G' => '--get', '-I' => '--head', '-L' => '--location', '-i' => '--include', '-k' => '--insecure',
+      '-G' => '--get', '-I' => '--head', '-i' => '--include', '-k' => '--insecure',
       '-f' => '--fail', '-g' => '--globoff', '-s' => '--silent', '-S' => '--show-error'
     }.freeze
     LONG_FLAGS = (FLAGS.values + %w[--compressed --http1.1 --http2]).freeze
@@ -52,9 +59,11 @@ module Raindown
     module_function
 
     # Returns the response body and the code block language for its content type.
-    def run(snippet)
+    # Placeholders like {base_url} are replaced from the variables, word by word, so a value can't add options.
+    def run(snippet, variables = nil)
+      args = arguments(snippet, variables)
       stdout, stderr, status = Open3.capture3('curl', *SAFE_OPTIONS, '--silent', '--show-error', '--max-time', TIMEOUT,
-                                              *arguments(snippet), '--write-out', WRITE_OUT)
+                                              *resolve_options(args), *args, '--write-out', WRITE_OUT)
       raise Error, stderr.strip.empty? ? "curl exited with #{status.exitstatus}" : stderr.strip unless status.success?
 
       body, _, content_type = stdout.rpartition(TYPE_MARKER)
@@ -66,8 +75,8 @@ module Raindown
     end
 
     # The snippet's method and URL, like GET https://httpbin.org/uuid, or nil when it can't be read.
-    def request(snippet)
-      args = arguments(snippet)
+    def request(snippet, variables = nil)
+      args = arguments(snippet, variables)
       Request.new(method: request_method(args), url: args.find { it.match?(URL) })
     rescue Error
       nil
@@ -83,8 +92,9 @@ module Raindown
       'GET'
     end
 
-    def arguments(snippet)
+    def arguments(snippet, variables = nil)
       words = Shellwords.split(snippet.gsub(/\\\r?\n/, ' ').strip.delete_prefix('$ '))
+      words = words.map { variables.substitute(it) } if variables
       raise Error, 'Endpoint snippets must start with curl' unless words.first == 'curl'
       raise Error, 'Endpoint snippets must be a single curl command' if words.intersect?(OPERATORS)
 
@@ -120,7 +130,7 @@ module Raindown
       [option, value(option, words.shift)]
     end
 
-    # Short flags can be grouped like -sSL, and a short option's value can be attached like -XPOST.
+    # Short flags can be grouped like -sS, and a short option's value can be attached like -XPOST.
     def short_options(word, words)
       letters = word.delete_prefix('-')
       args = []
@@ -160,6 +170,50 @@ module Raindown
       value
     end
 
+    # Resolves each URL's host and pins curl to the address it was checked at, like --resolve api.io:443:203.0.113.5,
+    # so the name can't point somewhere else by the time curl looks it up. A host that's already an IP isn't pinned,
+    # and behind a proxy, which looks names up itself, only a host that's an IP is checked.
+    def resolve_options(args)
+      args.grep(URL).flat_map { pin_option(URI.parse(it)) }
+    rescue URI::InvalidURIError => e
+      raise Error, "Can't read the URL: #{e.message}"
+    end
+
+    def pin_option(uri)
+      raise Error, "#{uri} has no host" if uri.hostname.to_s.empty?
+      return [] if proxy? && !ip?(uri.hostname)
+
+      address = allowed_address(uri.hostname)
+      return [] if ip?(uri.hostname)
+
+      pinned = address.to_s
+      pinned = "[#{pinned}]" if address.ipv6?
+      ['--resolve', "#{uri.hostname}:#{uri.port}:#{pinned}"]
+    end
+
+    # Any way of writing an IP, like 169.254.169.254 or 2852039166, found without a DNS lookup.
+    def ip?(host)
+      Addrinfo.getaddrinfo(host, nil, nil, :STREAM, nil, Socket::AI_NUMERICHOST)
+      true
+    rescue SocketError
+      false
+    end
+
+    def proxy?
+      PROXY_VARIABLES.any? { !ENV[it].to_s.empty? }
+    end
+
+    # The host's first address, unless any of them is link-local.
+    def allowed_address(host)
+      addresses = Addrinfo.getaddrinfo(host, nil, nil, :STREAM).map { IPAddr.new(it.ip_address.sub(/%.*/, '')).native }
+      blocked = addresses.find(&:link_local?)
+      raise Error, "Endpoint snippets can't request link-local addresses, like cloud metadata at #{blocked}" if blocked
+
+      addresses.first
+    rescue SocketError => e
+      raise Error, "Can't resolve #{host}: #{e.message}"
+    end
+
     def language(content_type)
       LANGUAGES.find { |pattern, _| content_type.match?(pattern) }&.last || ''
     end

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -4,14 +4,15 @@ require 'date'
 require_relative '../bare_directives'
 require_relative '../code_blocks'
 require_relative 'curl'
+require_relative 'endpoint_variables'
 
 module Raindown
   # Runs the curl block under an endpoint directive in a comment, or a bare one, and writes the response in the code
   # block below it,
   # followed by the date it was fetched.
-  # Only runs when that block is missing or empty, and the directive has :x/:execute or --execute is passed.
+  # Only runs when that block is missing or empty, and --execute is passed, so a file can't run requests by itself.
   # Or with only: and a directive's line index, runs just that endpoint, replacing any response it has.
-  #   <!-- endpoint: :x -->
+  #   <!-- endpoint: -->
   #   ```sh
   #   curl https://api.example.com
   #   ```
@@ -20,6 +21,8 @@ module Raindown
   #   ```
   #   <!-- raindown:fetched 2026-10-14 -->
   #   <!-- :endpoint -->
+  # Its snippet's {placeholders} are filled from EndpointVariables, and with as: login, later snippets can use its
+  # response, like {login.token}.
   # One in Antlers' delimiters, <{ endpoint: }>, only renders, so it's never run.
   class EndpointRunner
     # An endpoint's directive in Antlers' delimiters, which only renders, or in a comment, which writes its response back,
@@ -27,16 +30,16 @@ module Raindown
     DIRECTIVE = /\A {0,3}<\{\s*endpoint:(.*?)\}>[ \t]*$/
     COMMENT = /\A {0,3}<!--\s*endpoint:(.*?)-->[ \t]*$/
     END_TAG = /\A {0,3}(?:<\{\s*:endpoint\s*\}>|<!--\s*:endpoint\s*-->)[ \t]*$/
-    EXECUTE_ARGS = %w[:x :execute].freeze
     # The date a response was fetched, on the line after it.
     FETCHED = /\A {0,3}<!-- raindown:fetched [^\n]*? -->[ \t]*$/
 
     def self.rewrite(content:, path: nil, bare: false, execute: false, **)
-      new(content:, bare: BareDirectives.enabled?(path:, content:, bare:), execute:).rewrite
+      new(content:, path:, bare: BareDirectives.enabled?(path:, content:, bare:), execute:).rewrite
     end
 
-    def initialize(content:, bare: false, execute: false, only: nil)
+    def initialize(content:, path: nil, bare: false, execute: false, only: nil)
       @lines = content.lines
+      @variables = EndpointVariables.new(path:, content:)
       @bare = bare
       @execute = execute
       @only = only
@@ -71,24 +74,29 @@ module Raindown
     def fill(index, args, directive:)
       curl, output = CodeBlocks.endpoint(@lines, index)
       return index - 1 unless curl&.dig(:body)&.lstrip&.start_with?('curl')
-      return curl[:close] unless run?(args, output, directive)
+      return write_output(curl:, output:, name: response_name(args)) if run?(output, directive)
 
-      write_output(curl:, output:)
+      @variables.remember(response_name(args), output[:body]) if output
+      curl[:close]
     end
 
-    def run?(args, output, directive)
-      return directive == @only if @only
-
-      (output.nil? || output[:body].strip.empty?) && execute?(args)
+    # The name that as: gives the endpoint, for later snippets to use its response.
+    def response_name(args)
+      index = args.index('as:')
+      args[index + 1] if index
     end
 
-    def execute?(args)
-      @execute || args.intersect?(EXECUTE_ARGS)
+    def run?(output, directive)
+      return directive == @only if @only
+
+      @execute && (output.nil? || output[:body].strip.empty?)
     end
 
     # Replaces the output block and the date it was fetched, or with no block, replaces nothing just after the curl block.
-    def write_output(curl:, output:)
-      block = [*output_block(*Curl.run(curl[:body])), fetched]
+    def write_output(curl:, output:, name:)
+      body, language = Curl.run(curl[:body], @variables)
+      @variables.remember(name, body)
+      block = [*output_block(body, language), fetched]
       block.unshift("\n") unless output
       start = output ? output[:open] : curl[:close] + 1
 

data/lib/raindown/endpoint/endpoint_variables.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require_relative '../front_matter'
+require_relative 'curl'
+
+module Raindown
+  # The values that {placeholders} in an endpoint's curl snippet are replaced with, like {base_url} or {login.token}.
+  # From least to most specific: the file's front matter, the project's environment, and the responses of endpoints
+  # named with as:, read from the file as it goes. {env.NAME} is the environment variable NAME, for secrets, and an
+  # environment's values can use it too, like token: '{env.STAGING_TOKEN}'.
+  # The environment is one in .raindown/environments.yml, chosen with --env or RAINDOWN_ENV, or else the first:
+  #   local:
+  #     base_url: http://localhost:3000
+  #   staging:
+  #     base_url: https://staging.example.com
+  class EndpointVariables
+    class Error < Curl::Error; end
+
+    FILE = 'environments.yml'
+    PLACEHOLDER = /\{([A-Za-z_][\w.-]*)\}/
+
+    def initialize(path:, content:)
+      @path = path
+      @content = content
+    end
+
+    # Keeps a named endpoint's response, as its JSON's data when it's JSON, or else its text.
+    def remember(name, body)
+      return unless name
+
+      values[name] = begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body.strip
+      end
+    end
+
+    # The text with each placeholder that has a value replaced by it, and the rest left as they are. A value's own
+    # placeholders are replaced once, so an environment can read secrets like {env.TOKEN}.
+    def substitute(text, depth: 1)
+      text.gsub(PLACEHOLDER) do |placeholder|
+        value = value(Regexp.last_match(1))
+        next placeholder if value.nil?
+        next value.to_json if value.is_a?(Hash) || value.is_a?(Array)
+        next substitute(value, depth: 0) if depth.positive? && value.is_a?(String)
+
+        value.to_s
+      end
+    end
+
+    private
+
+    # Read when they're first needed, so a file without endpoints doesn't need its environment.
+    def values
+      @values ||= FrontMatter.parse(@content).first.transform_keys(&:to_s).merge(environment, 'env' => ENV.to_h)
+    end
+
+    def environment
+      folder = @path && Nodes.find_folder(File.dirname(File.expand_path(@path)))
+      file = folder && File.join(folder, FILE)
+      return {} unless file && File.exist?(file)
+
+      environments = YAML.safe_load_file(file) || {}
+      name = ENV.fetch('RAINDOWN_ENV') { environments.keys.first }
+      environments.fetch(name) { raise Error, "There's no #{name} environment in #{file}" }
+    end
+
+    # A value by its path, like login.token or users.0.id.
+    def value(name)
+      name.split('.').reduce(values) do |value, key|
+        case value
+        when Hash then value.fetch(key) { value[key.to_sym] }
+        when Array then value[Integer(key, exception: false) || value.length]
+        end
+      end
+    end
+  end
+end

data/lib/raindown/gitignore.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Raindown
+  # The folders .gitignore files leave out, like a Drupal site's web/core, so finding the projects in a folder of
+  # them, like ~/dev, skips them. Only lines naming a folder are read, like /vendor/, node_modules or
+  # /web/modules/contrib/*, as a wildcard could leave out a project, and a ! takes a folder back out.
+  class Gitignore
+    WILDCARD = /[*?\[]/
+
+    # The rules for the folders inside a folder: its .gitignore's and those of the folders above it, up to its
+    # repository, as a repository's rules don't reach the repositories inside it.
+    def initialize(folder, above = nil)
+      above = nil if File.exist?(File.join(folder, '.git'))
+      @paths = Set.new(above&.paths)
+      @names = Set.new(above&.names)
+      file = File.join(folder, '.gitignore')
+      File.foreach(file, chomp: true) { read(it.strip, folder) } if File.file?(file)
+    end
+
+    def ignores?(path)
+      @paths.include?(path) || @names.include?(File.basename(path))
+    end
+
+    protected
+
+    attr_reader :paths, :names
+
+    private
+
+    # A folder with a slash, like /vendor or web/files, is from the .gitignore's folder, and one without, like
+    # node_modules, is any folder of that name below it.
+    def read(line, folder)
+      pattern = line.delete_suffix('/*').delete_suffix('/')
+      negated = pattern.delete_prefix!('!')
+      return if pattern.empty? || pattern.start_with?('#') || pattern.match?(WILDCARD)
+
+      if pattern.include?('/')
+        update(@paths, File.join(folder, pattern.delete_prefix('/')), negated:)
+      else
+        update(@names, pattern, negated:)
+      end
+    end
+
+    def update(rules, rule, negated:)
+      return rules.delete(rule) if negated
+
+      rules.add(rule)
+    end
+  end
+end

data/lib/raindown/projects.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'find'
+require_relative 'gitignore'
 require_relative 'nodes'
 require_relative 'pages'
 
@@ -18,16 +19,21 @@ module Raindown
     # The roots of the projects in a directory: the project the directory is in, if any, and every project below it.
     def roots(directory)
       directory = File.expand_path(directory)
-      roots = [root(directory)].compact
+      [root(directory), *project_folders(directory)].compact.uniq
+    end
 
-      Find.find(directory) do |path|
-        next unless File.directory?(path)
+    # The folders below a directory with a .raindown folder. Only folders are walked, leaving out ignored, linked and
+    # gitignored ones, so it stays quick in a big folder like ~/dev.
+    def project_folders(directory, gitignore = Gitignore.new(directory))
+      Dir.glob('*/', base: directory).flat_map do |folder|
+        path = File.join(directory, folder.chomp('/'))
+        next [] if ignored?(folder.chomp('/')) || File.symlink?(path) || gitignore.ignores?(path)
 
-        Find.prune if path != directory && ignored?(File.basename(path))
-        roots << path if File.directory?(File.join(path, Nodes::FOLDER))
-      end
+        inside = project_folders(path, Gitignore.new(path, gitignore))
+        next inside unless project?(path)
 
-      roots.uniq
+        [path, *inside]
+      end
     end
 
     # The root of the project a file or directory is in, or nil when it isn't in one.
@@ -38,13 +44,13 @@ module Raindown
     end
 
     # The project's Markdown files, sorted, leaving out ignored folders. The projects inside it are left out too,
-    # since they have nodes of their own, unless they're asked for, like by the terminal UI, which lists them all.
-    def files(root, nested: false)
+    # since they have nodes of their own.
+    def files(root)
       files = []
 
       Find.find(root) do |path|
         if File.directory?(path)
-          Find.prune if path != root && (ignored?(File.basename(path)) || (!nested && project?(path)))
+          Find.prune if path != root && (ignored?(File.basename(path)) || project?(path))
         elsif markdown?(path, root:)
           files << path
         end
@@ -66,6 +72,11 @@ module Raindown
       File.expand_path(path).start_with?(File.join(root, Nodes::FOLDER, '')) && NODE_EXTENSIONS.include?(File.extname(path))
     end
 
+    # The roots that aren't inside another of them, as a project's code includes the projects inside it.
+    def outer_roots(roots)
+      roots.reject { |root| roots.any? { root != it && root.start_with?(File.join(it, '')) } }
+    end
+
     def project?(folder)
       File.directory?(File.join(folder, Nodes::FOLDER))
     end

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

@@ -3,6 +3,7 @@
 require_relative '../code_box'
 require_relative '../events'
 require_relative '../../blueprints'
+require_relative '../../projects'
 require_relative 'traced_code'
 require_relative 'canvas'
 require_relative 'code_comments'
@@ -32,9 +33,10 @@ module Raindown
 
       attr_reader :cursor
 
-      def initialize(root:)
+      def initialize(root:, projects: [root])
         @root = root
-        @path = File.join(root, Blueprints::FILE)
+        @projects = projects
+        @paths = projects.map { File.join(it, Blueprints::FILE) }
         @all = []
         @cursor = 0
         select_box(0)
@@ -51,7 +53,7 @@ module Raindown
       end
 
       # Whether there are any blueprints yet, saved or in the code's comments, which are looked for once until it's loaded.
-      def any? = File.exist?(@path) || commented.any?
+      def any? = @paths.any? { File.exist?(it) } || commented.any?
 
       # Whether the file's changed since it was read, so it's read again on the next tick.
       def changed? = mtime != @read_at
@@ -60,13 +62,26 @@ module Raindown
         @read_at = mtime
         newest = @all.first&.time
         @commented = nil
-        @all = Blueprints.read(@root) + commented
+        @all = saved + commented
         self.cursor = 0 unless @all.first&.time == newest
         self.cursor = @cursor
       end
 
       def selected = blueprints[@cursor]
 
+      # Narrows the blueprints to a project's, or with nil, shows every project's.
+      def project=(project)
+        @project = project
+        self.cursor = 0
+      end
+
+      # The blueprints in the project they're narrowed to, if any, which the filter's keywords narrow further.
+      def in_project
+        return @all unless @project
+
+        @all.select { File.expand_path(it.path, @root).start_with?(File.join(@project, '')) }
+      end
+
       # Another blueprint's shown from its first box, while the same one keeps its box and canvas, like when it's clicked.
       def cursor=(index)
         shown = selected
@@ -115,7 +130,7 @@ module Raindown
         method = code
         return Edit.new(path: method.path, line: method.line) if method
 
-        Edit.new(path: File.join(@root, selected.path), line: selected.line)
+        Edit.new(path: File.expand_path(selected.path, @root), line: selected.line)
       end
 
       # A click on a box drawn in the blueprint, which moves on to the next code it names when it's already selected.
@@ -138,9 +153,20 @@ module Raindown
 
       def count(number, noun) = "#{number} #{number == 1 ? noun : "#{noun}s"}"
 
-      def mtime = File.exist?(@path) ? File.mtime(@path) : nil
+      def mtime = @paths.map { File.exist?(it) ? File.mtime(it) : nil }
+
+      # Every project's saved blueprints, newest first, each by its file from the root.
+      def saved
+        @projects.flat_map { |project| Blueprints.read(project).map { it.with(path: from_root(File.join(project, it.path))) } }
+                 .sort_by(&:time).reverse
+      end
+
+      def from_root(path) = path.delete_prefix(File.join(@root, ''))
+
+      # The projects whose code is read, as a project's code includes the projects inside it.
+      def code_projects = @code_projects ||= Projects.outer_roots(@projects)
 
-      def commented = @commented ||= CodeComments.blueprints(@root)
+      def commented = @commented ||= CodeComments.blueprints(@root, projects: code_projects)
     end
   end
 end

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

@@ -16,9 +16,10 @@ module Raindown
 
       module_function
 
-      # The blueprints in the comments of the project's code, by file, from the top of each.
-      def blueprints(root)
-        CodeMethods.files(root).flat_map { |path| in_file(path, path.delete_prefix(File.join(root, ''))) }
+      # The blueprints in the comments of the projects' code, by file from the root, from the top of each. In a folder of
+      # projects, like ~/dev, only the projects' code is read.
+      def blueprints(root, projects: [root])
+        projects.flat_map { CodeMethods.files(it) }.flat_map { |path| in_file(path, path.delete_prefix(File.join(root, ''))) }
       end
 
       def in_file(path, relative)

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

@@ -15,10 +15,11 @@ module Raindown
 
       def typing? = @filtering == true
 
-      # The blueprints with every keyword, or all of them, filtered again only when the keywords or the blueprints change,
+      # The blueprints with every keyword, or all of them, in the project they're narrowed to, if any, filtered again only when
+      # the keywords, the project or the blueprints change,
       # as what's drawn asks for the selected one many times a frame.
       def blueprints
-        @filtered = [query, @all, filtered(query.to_s.downcase.split)] unless filtered_now?
+        @filtered = [query, @all, @project, filtered(query.to_s.downcase.split)] unless filtered_now?
         @filtered.last
       end
 
@@ -38,12 +39,12 @@ module Raindown
 
       private
 
-      def filtered_now? = @filtered && @filtered[0] == query && @filtered[1].equal?(@all)
+      def filtered_now? = @filtered && @filtered[0] == query && @filtered[1].equal?(@all) && @filtered[2] == @project
 
       def filtered(keywords)
-        return @all if keywords.empty?
+        return in_project if keywords.empty?
 
-        @all.select { |blueprint| keywords.all? { blueprint.words.downcase.include?(it) || blueprint.kind.include?(it) } }
+        in_project.select { |blueprint| keywords.all? { blueprint.words.downcase.include?(it) || blueprint.kind.include?(it) } }
       end
 
       def open_filter

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

@@ -50,7 +50,8 @@ module Raindown
 
       def first_method(owner) = methods.select { it.owner == owner }.min_by { [it.path, it.line] }
 
-      def methods = @methods ||= CodeMethods.list(@root)
+      # The projects' methods. In a folder of projects, like ~/dev, only the projects' code is read.
+      def methods = @methods ||= code_projects.flat_map { CodeMethods.list(it) }
     end
   end
 end

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

@@ -18,7 +18,7 @@ module Raindown
 
       # The five bins, each a box with its number, its temper, and a bar of how many feelings it holds.
       def bins
-        counts = view.log.counts
+        counts = view.counts
         most = [counts.values.max, 1].max
         chosen = chosen_temper
         boxes = counts.each_with_index.map { |(temper, count), index| bin(index + 1, temper, count, most, chosen) }

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

@@ -41,9 +41,24 @@ module Raindown
 
       module_function
 
+      # Git log runs in a thread of its own while the methods are read, as it's as slow as reading them. Waiting on git's
+      # output frees the main thread to read, and the two meet when each method gets its file's changes, for its drift:
+      #   Thread                                  main thread
+      #   ┌──────────────────────────┐            ┌─────────────────────────┐
+      #   │ CodeMethods.file_changes │            │ CodeMethods.tagged      │
+      #   │ git log, in a subprocess │            │ or CodeMethods.indented │
+      #   └────────────┬─────────────┘            └────────────┬────────────┘
+      #                │ changes.value waits for it            │
+      #                └───────────────────┬───────────────────┘
+      #                                    │
+      #                                    ▼
+      #                         ┌──────────────────────┐
+      #                         │ CodeMethods.drifting │
+      #                         └──────────────────────┘
       def list(root)
-        changes = file_changes(root)
-        drifting((tagged(root) || indented(root)).map { it.with(changes: changes.fetch(it.path, 0)) })
+        changes = Thread.new { file_changes(root) }
+        methods = tagged(root) || indented(root)
+        drifting(methods.map { it.with(changes: changes.value.fetch(it.path, 0)) })
       end
 
       # Each method with its drift, from 0 for the lightest to 9 for the heaviest, where methods that weigh the same

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

@@ -81,9 +81,9 @@ module Raindown
       # How the method last felt, while its code's the same as when it was felt, or nil.
       def temper(method) = rows.reverse.find { felt_row?(it, method) }&.fetch(:temper)
 
-      # How many feelings there are of each temper, in the bins' order.
-      def counts
-        tally = rows.map { it[:temper] }.tally
+      # How many feelings there are of each temper, in the bins' order, of those within a folder, like a project, if one's given.
+      def counts(within: nil)
+        tally = rows.select { within.nil? || File.join(@root, path(it)).start_with?(File.join(within, '')) }.map { it[:temper] }.tally
         TEMPERS.to_h { [it, tally.fetch(it, 0)] }
       end
 
@@ -132,5 +132,33 @@ module Raindown
         nil
       end
     end
+
+    # The feelings about each project's code, in its own FeelingsLog, so in a folder of projects, like ~/dev, each project
+    # keeps its own feelings, and the folder isn't made a project.
+    class FeelingsLogs
+      def initialize(projects:)
+        @logs = projects.to_h { [it, FeelingsLog.new(root: it)] }
+      end
+
+      def add(feeling) = log_of(feeling.method).add(feeling)
+      def felt?(method) = log_of(method).felt?(method)
+      def temper(method) = log_of(method).temper(method)
+      def rows = @logs.values.flat_map(&:rows)
+
+      # Each project's feelings about methods that have changed, or gone, from its methods there are now, to its memories.
+      def move_stale_to_memories(methods)
+        by_log = methods.group_by { log_of(it) }
+        @logs.each_value { it.move_stale_to_memories(by_log.fetch(it, [])) }
+      end
+
+      def counts(within: nil)
+        empty = FeelingsLog::TEMPERS.to_h { [it, 0] }
+        @logs.values.map { it.counts(within:) }.reduce(empty) { |sum, counts| sum.merge(counts) { |_, felt, more| felt + more } }
+      end
+
+      private
+
+      def log_of(method) = @logs.find { |root, _| method.path.start_with?(File.join(root, '')) }&.last
+    end
   end
 end

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

@@ -76,9 +76,10 @@ module Raindown
 
       def view = navigator.view
 
-      # Instead of the grid, that there's nothing to feel, or the celebration.
+      # Instead of the grid, that there's nothing to feel, as there are no projects or no methods, or the celebration.
       def instead
-        return blank(" No functions or methods in #{File.basename(navigator.root)} to feel") if view.code_methods.empty?
+        return alert(NO_PROJECTS) if navigator.projects.empty?
+        return alert(["No functions or methods in #{File.basename(navigator.root)} to feel."]) if view.code_methods.empty?
 
         celebration(view.celebration)
       end
@@ -174,10 +175,6 @@ module Raindown
         lines[(height - shown.length) / 2, shown.length] = shown
         lines.map { [segment(it.center(width), :too_small)] }
       end
-
-      def blank(message)
-        [[segment(message, :feelings)], *Array.new([height - 1, 0].max) { [segment('', :blank)] }].first(height)
-      end
     end
   end
 end

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

@@ -29,12 +29,13 @@ module Raindown
       KEYS = %i[up down left right edit execute enter toggle expand celebrate].freeze
 
       # The temper being noted, and the note typed so far, while it's asking why, whether the selected method's code
-      # shows all that fits, until another's selected, and the rain then the waffle, once the batch is refined.
-      attr_reader :noting, :note, :cursor, :log, :celebration
+      # shows all that fits, until another's selected, the rain then the waffle, once the batch is refined, and the project
+      # its methods and counts are narrowed to, if any.
+      attr_reader :noting, :note, :cursor, :log, :celebration, :project
 
-      def initialize(root:)
-        @root = root
-        @log = FeelingsLog.new(root:)
+      def initialize(projects:)
+        @projects = projects
+        @log = FeelingsLogs.new(projects:)
         @last_feelings = {}
         @cursor = 0
         @week = WeeklyBatch.new(log: @log)
@@ -63,12 +64,20 @@ module Raindown
       # the memories.
       def load
         was = selected
-        every = CodeMethods.list(@root)
-        @log.move_stale_to_memories(every)
-        @week.read(every)
+        @every = @projects.flat_map { CodeMethods.list(it) }
+        @log.move_stale_to_memories(@every)
+        @week.read(in_project)
         reselect(was)
       end
 
+      # Narrows the methods to a project's, or with nil, shows every project's, picking the batch again from them.
+      def project=(project)
+        @project = project
+        @week.read(in_project)
+        @week.pick_again
+        self.cursor = 0
+      end
+
       # Selects the method again, by its file and name, wherever it is now, or keeps the cursor where it was.
       def reselect(was)
         self.cursor = code_methods.index { [it.path, it.label] == [was&.path, was&.label] } || @cursor
@@ -78,6 +87,9 @@ module Raindown
       def batch = @week.batch
       def code_methods = batch.code_methods
 
+      # How many feelings there are of each temper, in the project the methods are narrowed to, if any.
+      def counts = log.counts(within: project)
+
       def selected = code_methods[@cursor]
 
       def cursor=(index)
@@ -106,6 +118,11 @@ module Raindown
 
       private
 
+      # The methods of the project they're narrowed to, if any, which are none until they're read.
+      def in_project
+        @every.to_a.select { @project.nil? || it.path.start_with?(File.join(@project, '')) }
+      end
+
       # Moves between the methods, or acts on the selected one.
       def method_step(key)
         case key

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

@@ -38,6 +38,11 @@ module Raindown
         refill(grid_cells)
       end
 
+      # Picks the batch again on the next fill, like when the methods are narrowed to a project's.
+      def pick_again
+        @filled_for = nil
+      end
+
       private
 
       def refill(grid_cells)

data/lib/raindown/tui/file_tree.rb

@@ -28,8 +28,8 @@ module Raindown
       PROJECT = '🌧'
 
       def load
-        @files = Projects.files(root, nested: true)
-        @projects = Projects.roots(root).to_set
+        @projects = @workers.roots
+        @files = @projects.flat_map { Projects.files(it) }.sort
       end
 
       # The folder the tree starts from: the scope's, or the root's.

data/lib/raindown/tui/navigator/navigator.rb

@@ -45,10 +45,10 @@ module Raindown
         @files = FileTree.new(root:, workers:)
         @endpoints = Endpoints.new(workers:)
         @dashboard = DashboardView.new(root:, workers:)
-        @feelings = FeelingsView.new(root:)
-        @blueprints = BlueprintsView.new(root:)
+        @feelings = FeelingsView.new(projects: Projects.outer_roots(workers.roots))
+        @blueprints = BlueprintsView.new(root:, projects: workers.roots)
         @nav = ListView.new { nav_rows }
-        first = Projects.files(root, nested: true).first
+        first = @files.files.first
         # The dashboard is the first page, unless a file is asked for, and "d" goes from it to the first file.
         @view = OutlineView.new(first, workers:) if first
         path ? open_at(path, nil) : open_view(dashboard)

data/lib/raindown/tui/navigator/project_menu.rb

@@ -3,8 +3,8 @@
 module Raindown
   module TUI
     # The list of projects that drops down from the header's path, with "p" or a click, when there's more than one.
-    # Choosing one narrows the files and the dashboard to its own, and "All projects" shows every project's again.
-    # It stays open until a project's chosen, with Enter or a click, while up and down move its cursor.
+    # Choosing one narrows the files, the dashboard, Code feelings and Blueprints to its own, and "All projects" shows every
+    # project's again. It stays open until a project's chosen, with Enter or a click, while up and down move its cursor.
     # Esc or "p" close it without choosing, and other keys and clicks do nothing while it's open.
     module ProjectMenu
       # The menu's cursor, while it's open.
@@ -54,6 +54,8 @@ module Raindown
         @files.scope = project
         @endpoints.project = project
         dashboard.project = project
+        feelings.project = project
+        blueprints.project = project
         open_view(dashboard)
       end
     end

data/lib/raindown/tui/project.rb

@@ -15,6 +15,7 @@ require_relative 'card'
 require_relative 'endpoint'
 require_relative '../code_blocks'
 require_relative '../endpoint/curl'
+require_relative '../endpoint/endpoint_variables'
 
 module Raindown
   module TUI
@@ -89,7 +90,7 @@ module Raindown
 
       def endpoint(path, lines, directive)
         snippet = CodeBlocks.endpoint(lines, directive.line).first&.dig(:body)
-        request = Curl.request(snippet.to_s)
+        request = Curl.request(snippet.to_s, EndpointVariables.new(path:, content: lines.join))
         Endpoint.new(project: root, path:, line: directive.line, **request.to_h) if request
       end
 

data/lib/raindown/tui/renderers/dashboard_renderer.rb

@@ -28,8 +28,10 @@ module Raindown
       def page = 'Dashboard'
 
       def lines
+        return alert(NO_PROJECTS) if navigator.projects.empty?
+
         cards = dashboard.cards
-        return blank(height, " No charts in #{File.basename(navigator.root)} yet, like <{ chart: '3 5 2 8' }>") if cards.empty?
+        return alert(["No charts in #{File.basename(navigator.root)} yet.", "Add one like <{ chart: '3 5 2 8' }>"]) if cards.empty?
 
         rows = dashboard.rows(width)
         @headings = headings(rows, cards)
@@ -94,9 +96,7 @@ module Raindown
         [segment(" #{from_home(project)}", :project)]
       end
 
-      def blank(count, message = '')
-        [[segment(message, :info)], *Array.new([count - 1, 0].max) { [segment('', :blank)] }].first(count)
-      end
+      def blank(count) = Array.new(count) { [segment('', :blank)] }
     end
   end
 end

data/lib/raindown/tui/renderers/renderer.rb

@@ -6,6 +6,9 @@ require_relative '../text'
 
 module Raindown
   module TUI
+    # Said in place of a page, like the charts or the code to feel, when the folder has no projects, with how to make one.
+    NO_PROJECTS = ['No projects found in this directory.', %(Run "raindown init" in a project's folder.)].freeze
+
     # Draws what's in a pane, :nav or :main, as lines of the pane's width and height, which the Layout puts in it.
     # Like the Layout, it's made again for each draw, so it draws what the Navigator and its view hold then.
     Renderer = Struct.new(:navigator, :pane, :width, :height) do
@@ -14,6 +17,23 @@ module Raindown
 
       # Its side of the line above the panes, which is blank unless it has something to say there, like a progress.
       def spacer = [segment('', :blank)]
+
+      # The lines in a purple box, like an alert, at the top left, with blank below it, like when there's nothing to show.
+      # It's no wider than the pane, cutting the lines to fit.
+      def alert(messages)
+        inner = [messages.map { display_width(it) }.max, width - 5].min.clamp(0..)
+        box = [alert_edge('╔', '╗', inner), *messages.map { alert_line(it, inner) }, alert_edge('╚', '╝', inner)]
+        (box + Array.new(height) { [segment('', :blank)] }).first(height)
+      end
+
+      def alert_edge(left, right, inner)
+        padded([segment('', :blank, width: 1), segment("#{left}#{'═' * (inner + 2)}#{right}", :alert, width: inner + 4)])
+      end
+
+      def alert_line(message, inner)
+        padded([segment('', :blank, width: 1), segment('║ ', :alert, width: 2), segment(message, :alert, width: inner),
+                segment(' ║', :alert, width: 2)])
+      end
     end
   end
 end

data/lib/raindown/tui/terminal/styles.rb

@@ -85,7 +85,7 @@ module Raindown
           cursor: Curses::A_UNDERLINE, cursor_button: Curses::A_UNDERLINE | Curses::A_BOLD, heading: Curses::A_BOLD,
           body: Curses::A_DIM, error: Curses::A_BOLD, button: Curses::A_BOLD, folder: Curses::A_BOLD, project: Curses::A_BOLD, page: Curses::A_BOLD,
           key: Curses::A_REVERSE, border: Curses::A_DIM, divider: Curses::A_BOLD,
-          code_keyword: Curses::A_BOLD, code_comment: Curses::A_DIM
+          code_keyword: Curses::A_BOLD, code_comment: Curses::A_DIM, alert: Curses::A_BOLD
         )
       end
 
@@ -112,11 +112,12 @@ module Raindown
         Hash.new(text).merge(plain.transform_values { it | text })
       end
 
-      # Headings, the waffle's butter's shine and its syrup, and Code feelings' text and lines, bold around the method the
+      # Headings, alerts, the waffle's butter's shine and its syrup, and Code feelings' text and lines, bold around the method the
       # mouse is over, and its purple.
       def emphasis
         { heading: pair(:heading) | Curses::A_BOLD, feelings: pair(:feelings), nearby: pair(:feelings) | Curses::A_BOLD,
-          feelings_purple: pair(:feelings_purple), shine: pair(:shine) | Curses::A_BOLD, syrup: pair(:syrup) }
+          feelings_purple: pair(:feelings_purple), alert: pair(:feelings_purple) | Curses::A_BOLD,
+          shine: pair(:shine) | Curses::A_BOLD, syrup: pair(:syrup) }
       end
 
       # Highlighted code's tokens, like keywords and comments, with comments dim in 8 colours, where there's no grey.

data/lib/raindown/variables.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
+require 'antlers/api'
+
 module Raindown
   # The front matter values that Antlers variables like {title} and <{ title }> render.
   # Antlers reads a variable from the binding's locals, then by sending it to the binding's receiver, which is this.
   # It's a BasicObject so a key like "hash" or "display" isn't shadowed by a method, and unknown names render nothing.
-  # Nested values work too, like {author.name} and <{ for: tag in: tags }>.
+  # Nested values are hashes and arrays like {author.name}, {tags.0} or <{ for: name, url in: links }>.
   class Variables < BasicObject
     # Braces in a value become the placeholders that render as braces, so Antlers doesn't read them as a variable.
     def self.wrap(value)
       case value
-      when ::Hash then new(value)
+      when ::Hash then value.transform_values { |item| wrap(item) }
       when ::Array then value.map { |item| wrap(item) }
       when ::String then value.gsub(/[{}]/, CODE_BRACES)
       else value
@@ -20,6 +22,7 @@ module Raindown
     def self.unwrap(value)
       case value
       when Variables then value.to_h
+      when ::Hash then value.transform_values { |item| unwrap(item) }
       when ::Array then value.map { |item| unwrap(item) }
       when ::String then value.tr(CODE_BRACES.values.join, CODE_BRACES.keys.join)
       else value
@@ -28,7 +31,8 @@ module Raindown
 
     # A variable's value, like author.name, read the way {author.name} reads it, unwrapped. Unknown names are nil.
     def self.value(variables, name)
-      unwrap(name.split('.').reduce(variables) { |value, key| value.respond_to?(key) ? value.send(key) : nil })
+      first, *path = name.split('.')
+      unwrap(::Antlers::Queries.read_path(value: variables.send(first), path:))
     end
 
     def initialize(values)

data/lib/raindown/workers/workers.rb

@@ -25,7 +25,7 @@ module Raindown
     end
 
     # The folder's project and those inside it, found when they're first asked for, and again after a restart.
-    def roots = @roots ||= [root, *Projects.roots(root)].uniq.sort
+    def roots = @roots ||= Projects.roots(root).sort
 
     # A worker for each project, as they were found when the workers last started.
     def each(&)

data/lib/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-11-03 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: 1.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: 1.4.0
 - !ruby/object:Gem::Dependency
   name: commonmarker
   requirement: !ruby/object:Gem::Requirement
@@ -213,9 +213,11 @@ files:
 - lib/raindown/document.rb
 - lib/raindown/endpoint/curl.rb
 - lib/raindown/endpoint/endpoint_runner.rb
+- lib/raindown/endpoint/endpoint_variables.rb
 - lib/raindown/files.rb
 - lib/raindown/fragments.rb
 - lib/raindown/front_matter.rb
+- lib/raindown/gitignore.rb
 - lib/raindown/heading_ids.rb
 - lib/raindown/js/host.mjs
 - lib/raindown/js/js_nodes.rb
@@ -306,11 +308,11 @@ files:
 - lib/raindown/workers/worker.rb
 - lib/raindown/workers/workers.rb
 - lib/version.rb
-homepage: https://github.com/raindeer-rb/raindown
+homepage: https://github.com/rainpour/raindown
 licenses: []
 metadata:
-  homepage_uri: https://github.com/raindeer-rb/raindown
-  source_code_uri: https://github.com/raindeer-rb/raindown/src/branch/main
+  homepage_uri: https://github.com/rainpour/raindown
+  source_code_uri: https://github.com/rainpour/raindown/tree/main
 rdoc_options: []
 require_paths:
 - lib