raindown 0.9.1 → 0.11.0

data/lib/raindown/endpoint/endpoint_runner.rb

@@ -4,22 +4,27 @@ require 'date'
 require_relative '../bare_directives'
 require_relative '../code_blocks'
 require_relative 'curl'
+require_relative 'endpoint_args'
+require_relative 'schema_block'
+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.
+  # block below it, followed by the date it was fetched, its status and how long it took.
+  # 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
   #   ```
   #   ```json
   #   { "id": 1 }
   #   ```
-  #   <!-- raindown:fetched 2026-10-14 -->
+  #   <!-- raindown:fetched 2026-10-14 · 200 · 142 ms -->
   #   <!-- :endpoint -->
+  # Its snippet's {placeholders} are filled from EndpointVariables, and with as: login, later snippets can use its
+  # response, like {login.token}. With status: and schema:, each response in the file is checked, and failures are kept.
+  # A schema: can name a SchemaBlock above it, like schema: 'User', or one in .raindown/schemas.rd.
   # 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,19 +32,30 @@ 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]*$/
+    FETCHED_STATUS = /raindown:fetched \S+ · (\d{3}) /
+
+    attr_reader :failures
 
     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
+
+    # 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:, bare: false, execute: false, only: nil)
+    def initialize(content:, path: nil, bare: false, execute: false, only: nil)
       @lines = content.lines
+      @path = path
+      @variables = EndpointVariables.new(path:, content:)
       @bare = bare
       @execute = execute
       @only = only
+      @failures = []
+      @schemas = SchemaBlock.shared(path)
     end
 
     def rewrite
@@ -48,6 +64,9 @@ module Raindown
       while index < @lines.length
         if (block = CodeBlocks.at(@lines, index))
           index = block[:close]
+        elsif (schema = SchemaBlock.at(@lines, index, bare: @bare))
+          @schemas[schema.name] = SchemaBlock.resolve(schema.type, @schemas)
+          index = schema.last
         elsif (args = directive_args(@lines[index]))
           index = fill(index + 1, args, directive: index)
         end
@@ -64,42 +83,65 @@ module Raindown
     def directive_args(line)
       args = line[COMMENT, 1]
       args ||= BareDirectives.wrap(line)&.[](DIRECTIVE, 1) if @bare
-      args&.split
+      EndpointArgs.parse(args, schemas: @schemas) if args
     end
 
     # Returns the index of the last line it handled.
     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:, args:, directive:) if run?(output, directive)
+      return curl[:close] unless output
 
-      write_output(curl:, output:)
+      @variables.remember(args.name, output[:body])
+      check(args, directive:, body: output[:body], status: fetched_status(output))
+      curl[:close]
     end
 
-    def run?(args, output, directive)
-      return directive == @only if @only
+    # The status in the fetched comment after a response, which responses fetched before statuses were kept don't have.
+    def fetched_status(output)
+      @lines[output[:close] + 1]&.[](FETCHED_STATUS, 1)&.to_i
+    end
+
+    # Run alone, only the endpoint that ran is checked. One without a response or a status hasn't run, so it has nothing
+    # to check, while one that ran has a status even when its body is empty.
+    def check(args, directive:, body:, status:)
+      return if (@only && directive != @only) || (body.strip.empty? && status.nil?)
 
-      (output.nil? || output[:body].strip.empty?) && execute?(args)
+      location = [@path, directive + 1].compact.join(':')
+      @failures.concat(args.failures(body:, status:).map { "#{location}: #{it}" })
     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]
+    # Secrets that a response echoes are written as their placeholders.
+    def write_output(curl:, output:, args:, directive:)
+      response = Curl.run(curl[:body], @variables)
+      body = @variables.redact(response.body)
+      @variables.remember(args.name, body)
+      check(args, directive:, body:, status: response.status)
+      replace_output(curl:, output:, block: [*output_block(body, response.language), fetched(response)])
+    rescue Curl::Error => e
+      message = @variables.redact(e.message)
+      # The one endpoint that was asked for fails for the caller to show, like in the terminal UI.
+      raise Curl::Error, message if @only
+
+      warn "Endpoint failed: #{message}"
+      curl[:close]
+    end
+
+    # Returns the index of the block's last line.
+    def replace_output(curl:, output:, block:)
       block.unshift("\n") unless output
       start = output ? output[:open] : curl[:close] + 1
 
       @lines[start, output ? replaced_length(output) : 0] = block
       start + block.length - 1
-    rescue Curl::Error => e
-      # The one endpoint that was asked for fails for the caller to show, like in the terminal UI.
-      raise if @only
-
-      warn "Endpoint failed: #{e.message}"
-      curl[:close]
     end
 
     # The output block, and the line after it when that's the date it was last fetched.
@@ -108,8 +150,8 @@ module Raindown
       @lines[output[:close] + 1]&.match?(FETCHED) ? length + 1 : length
     end
 
-    def fetched
-      "<!-- raindown:fetched #{Date.today.iso8601} -->\n"
+    def fetched(response)
+      "<!-- raindown:fetched #{Date.today.iso8601} · #{response.status} · #{response.milliseconds} ms -->\n"
     end
 
     # The fence is longer than any run of backticks in the body, so the body can't close it.

data/lib/raindown/endpoint/endpoint_variables.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require 'antlers/api'
+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
+  # Secrets go in environments.local.yml beside it, which git ignores, and which adds to and overrides its environments.
+  # Its values and env's are secret, so a response or error that echoes one is written with its placeholder instead.
+  class EndpointVariables
+    class Error < Curl::Error; end
+
+    FILE = 'environments.yml'
+    LOCAL_FILE = 'environments.local.yml'
+    # Shorter values, like a port or a flag, would be replaced wherever they happen to appear in a response.
+    SECRET_LENGTH = 4
+    PLACEHOLDER = /\{([A-Za-z_][\w.-]*)\}/
+
+    def initialize(path:, content:)
+      @path = path
+      @content = content
+      @local_names = []
+      @secrets = {}
+    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|
+        name = Regexp.last_match(1)
+        value = value(name)
+        next placeholder if value.nil?
+        next value.to_json if value.is_a?(Hash) || value.is_a?(Array)
+
+        value = depth.positive? && value.is_a?(String) ? substitute(value, depth: 0) : value.to_s
+        @secrets[value] = placeholder if secret?(name) && value.length >= SECRET_LENGTH
+        value
+      end
+    end
+
+    # The text with each secret that was filled in put back as its placeholder, like {env.TOKEN}, longest first.
+    def redact(text)
+      @secrets.keys.sort_by { -it.length }.reduce(text) { |redacted, secret| redacted.gsub(secret, @secrets[secret]) }
+    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)))
+      return {} unless folder
+
+      shared, local = [FILE, LOCAL_FILE].map { environments(File.join(folder, it)) }
+      return {} if shared.empty? && local.empty?
+
+      name = environment_name(shared, local)
+      @local_names = local.fetch(name, {}).keys
+      shared.fetch(name, {}).merge(local.fetch(name, {}))
+    end
+
+    # The one --env or RAINDOWN_ENV names, or else the first.
+    def environment_name(shared, local)
+      name = ENV.fetch('RAINDOWN_ENV') { (shared.keys + local.keys).first }
+      return name if shared.key?(name) || local.key?(name)
+
+      raise Error, "There's no #{name} environment in #{Nodes::FOLDER}/#{FILE}"
+    end
+
+    def environments(file)
+      return {} unless File.exist?(file)
+
+      YAML.safe_load_file(file) || {}
+    end
+
+    def secret?(name)
+      first = name.split('.').first
+      first == 'env' || @local_names.include?(first)
+    end
+
+    # A value by its path, like login.token or users.0.id.
+    def value(name)
+      Antlers::Queries.read_path(value: values, path: name.split('.'))
+    end
+  end
+end

data/lib/raindown/endpoint/schema_block.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative '../nodes'
+
+module Raindown
+  # A schema named for endpoints to check their responses against: a schema directive with its fields below it,
+  # indented, which become a LowType Schema[], where a key with no type holds the more indented fields below it:
+  #   <!-- schema: 'User'          schema: 'User'
+  #     name: String                 name: String
+  #     address:                     address:
+  #       city: String                 city: String
+  #   -->
+  # is Schema[name: String, address: Schema[city: String]]. Bare, in a Raindown file, its fields end at the first line
+  # that isn't indented. An endpoint below it names it, like schema: 'User' or schema: Array[User], as can a schema.
+  # Schemas in the project's .raindown/schemas.rd, written the same way, are named for every file's endpoints.
+  class SchemaBlock < Data.define(:name, :fields, :last)
+    # The name is quoted or not, like 'User' or User.
+    COMMENT = /\A {0,3}<!--\s*schema:\s*(['"]?)([A-Z]\w*)\1\s*$/
+    BARE = /\A {0,3}schema:\s*(['"]?)([A-Z]\w*)\1\s*$/
+    FIELD = /\A([ \t]*)(\S+:)[ \t]*(.*?)\s*\z/
+    FILE = 'schemas.rd'
+
+    # The schema starting at index, or nil when the line doesn't start one.
+    def self.at(lines, index, bare: false)
+      if (name = lines[index][COMMENT, 2])
+        close = (index + 1...lines.length).find { lines[it].strip == '-->' }
+        new(name:, fields: lines[index + 1...close], last: close) if close
+      elsif bare && (name = lines[index][BARE, 2])
+        last = index
+        last += 1 while lines[last + 1]&.match?(/\A[ \t]+\S/)
+        new(name:, fields: lines[index + 1..last], last:)
+      end
+    end
+
+    # The schemas in the project's .raindown/schemas.rd, by name.
+    def self.shared(path)
+      folder = path && Nodes.find_folder(File.dirname(File.expand_path(path)))
+      file = folder && File.join(folder, FILE)
+      return {} unless file && File.exist?(file)
+
+      lines = File.readlines(file)
+      schemas = {}
+      index = 0
+
+      while index < lines.length
+        if (block = at(lines, index, bare: true))
+          schemas[block.name] = resolve(block.type, schemas)
+          index = block.last
+        end
+        index += 1
+      end
+
+      schemas
+    end
+
+    # A schema: argument with the schemas it names written out, like Array[User] as Array[Schema[name: String]].
+    def self.resolve(text, schemas)
+      text = text.strip
+      text = text[1...-1] if text.match?(/\A(['"]).*\1\z/)
+      text.gsub(/\b[A-Z]\w*\b/) { schemas.fetch(it, it) }
+    end
+
+    # Each field's indent, key and type, as Schema[key: Type].
+    def self.type(fields)
+      pairs = []
+
+      until fields.empty?
+        indent, key, value = fields.shift
+        nested = []
+        nested << fields.shift while fields.first && fields.first[0].length > indent.length
+        value = type(nested) if nested.any?
+        pairs << "#{key} #{value}"
+      end
+
+      "Schema[#{pairs.join(', ')}]"
+    end
+
+    def type
+      self.class.type(fields.filter_map { it.match(FIELD)&.captures })
+    end
+  end
+end

data/lib/raindown/markdown_nodes.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'front_matter'
+require_relative 'node'
+require_relative 'variables'
+
+module Raindown
+  # Markdown Components, the .md and .rd files in a project's .raindown folder named like a component, like BookCard.md,
+  # which write their Markdown with their props as variables, so they need no code:
+  #   ---                          BookCard: title: Dune rating: 5
+  #   rating: 0
+  #   ---
+  #   **{title}** {rating}/5
+  # Its front matter is its props' defaults, and a value before its props, like Dune in BookCard: Dune, is {value}.
+  # Its template is read each time it's written, so changing it changes the next render.
+  module MarkdownNodes
+    EXTENSIONS = %w[.md .rd].freeze
+    NAME = /\A[A-Z]\w*\z/
+
+    module_function
+
+    def load(folder)
+      Dir.glob(EXTENSIONS.map { "*#{it}" }, base: folder).each do |file|
+        name = File.basename(file, '.*')
+        node_classes[name] ||= MarkdownNode.for(name:, path: File.join(folder, file)) if name.match?(NAME)
+      end
+    end
+
+    # Whether a file is a Markdown Component, by its extension and name, so .raindown/blueprints.md isn't one.
+    def file?(path)
+      EXTENSIONS.include?(File.extname(path)) && File.basename(path, '.*').match?(NAME)
+    end
+
+    def node_class(name)
+      node_classes[name]
+    end
+
+    def node_classes
+      @node_classes ||= {}
+    end
+  end
+
+  # A Markdown Component, made with its props, which writes its template's Markdown.
+  class MarkdownNode < Node
+    def self.for(name:, path:)
+      Class.new(self) do
+        define_singleton_method(:name) { name }
+        define_singleton_method(:path) { path }
+      end
+    end
+
+    def initialize(value = nil, **props)
+      super()
+      @props = props
+      @props = { value:, **props } unless value.nil?
+    end
+
+    # Braces that the template pass hid, in its code or its props' values, are written back as braces.
+    # The template pass loads here, as it loads nodes itself.
+    def replace(metadata: NoMetadata, bare: false)
+      require_relative 'pre_renderer'
+      defaults, template = FrontMatter.parse(File.read(self.class.path))
+      markdown = PreRenderer.render(template, variables: Variables.new(defaults.merge(@props)), metadata:, bare:)
+      Variables.unwrap(markdown.sub(/\A(?:[ \t]*\n)+/, '').rstrip)
+    end
+  end
+end

data/lib/raindown/node_blocks.rb

@@ -21,6 +21,7 @@ module Raindown
   # a block when it's a loaded node, so other text like "Note:" is left alone.
   module NodeBlocks
     class MissingEndTag < StandardError; end
+    class BrokenText < StandardError; end
 
     NAME = "(?:#{Nodes::BUILT_INS.keys.join('|')}|[A-Z]\\w*(?:::[A-Z]\\w*)*)".freeze
     OPEN = /\A( {0,3})<\{\s*(#{NAME}):(?:\s+(.*?))?\s*\}>[ \t]*$/
@@ -28,11 +29,13 @@ module Raindown
     BARE_OPEN = /\A( {0,3})(#{NAME}):(?:[ \t]+(.*?))?[ \t]*$/
     SELF_CLOSING = /\A( {0,3})<\{\s*:(#{NAME})(?:\s+(.*?))?\s*\}>[ \t]*$/
     BARE_SELF_CLOSING = /\A( {0,3}):(#{NAME})(?:[ \t]+(.*?))?[ \t]*$/
+    # Unquoted text after name:, like YAML's, runs up to the next prop, so title: Hello world limit: 3 has two.
+    UNQUOTED = /.+?(?=[ \t]+\w+(?:=|:[ \t])|[ \t]*\z)/
     # A prop is name=value or name: value, where the value is quoted text, a number, true, false
-    # or a variable like author.name.
-    PROP = /(\w+)(?:=|:[ \t]+)("[^"]*"|'[^']*'|\S+)/
+    # or a variable like author.name. After name= it's one word.
+    PROP = /(\w+)(?:=|:[ \t]+)("[^"]*"|'[^']*'|(?<==)\S+|#{UNQUOTED})/
     # A value before the props is the node's argument.
-    ARG = /\A("[^"]*"|'[^']*'|[^\s"']\S*)(?:\s+|\z)/
+    ARG = /\A("[^"]*"|'[^']*'|[^\s"']#{UNQUOTED}|[^\s"'])(?:\s+|\z)/
 
     module_function
 
@@ -43,7 +46,8 @@ module Raindown
       variables = Variables.new(front_matter)
 
       spans(lines, bare:).map do |span|
-        span.except(:name, :class, :args).merge(node: Nodes.instance(span[:class], *args(span[:args], variables)))
+        node = Nodes.instance(span[:class], *args(span[:args], variables, antlers: span[:antlers]))
+        span.except(:name, :class, :args, :antlers).merge(node:)
       end
     end
 
@@ -99,7 +103,7 @@ module Raindown
       found, pattern = directive(lines[index], bare:)
       return unless found && (klass = Nodes.node_class(found[2]))
 
-      span = { name: found[2], class: klass, args: found[3].to_s }
+      span = { name: found[2], class: klass, args: found[3].to_s, antlers: %i[open self_closing].include?(pattern) }
       case pattern
       when :open, :comment_open
         end_tag(lines, index, found[2], comment: pattern == :comment_open)
@@ -141,21 +145,30 @@ module Raindown
     end
 
     # The props, after a value that's the node's argument when it comes first, like 'data.csv' in chart: 'data.csv'.
-    def args(text, variables)
+    def args(text, variables, antlers: true)
       arg = text.match(ARG) unless text.match?(/\A#{PROP}/)
-      return [props(text, variables)] unless arg
+      return [props(text, variables, antlers:)] unless arg
 
-      [props(arg.post_match, variables), [value(arg[1], variables)]]
+      [props(arg.post_match, variables, antlers:), [value(arg[1], variables, antlers:)]]
     end
 
-    def props(text, variables)
-      text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, variables)] }
+    # Text that isn't a prop, like world in title: 'Hello' world or tag=a b, is an error rather than left out.
+    def props(text, variables, antlers: true)
+      unread = text.gsub(PROP, '').split
+      raise BrokenText, "Can't read #{unread.join(' ')} in #{text.strip}. Text with spaces needs quotes" if unread.any?
+
+      text.scan(PROP).to_h { |name, value| [name.to_sym, value(value, variables, antlers:)] }
     end
 
-    # A value, like 'text', 3, true, nil or :draft, or else a variable, like author.name.
-    def value(value, variables)
+    # A value, like 'text', 3, true, nil or :draft, or else a variable. In Antlers' delimiters a word is a variable, like
+    # author.name, while bare or in a comment, which read like Markdown, it's text, like notes in files: folder: notes,
+    # and only one in braces is a variable, like {author.name}.
+    def value(value, variables, antlers: true)
       Lowkey::ValueParser.parse(value) do
         next value[1..-2] if value.match?(/\A(["']).*\1\z/)
+        next Variables.value(variables, value[1..-2]) if !antlers && value.match?(/\A\{.+\}\z/)
+        next value unless antlers
+        raise BrokenText, "Can't read #{value} as a variable. Text with spaces needs quotes" if value.match?(/\s/)
 
         Variables.value(variables, value)
       end

data/lib/raindown/nodes.rb

@@ -3,13 +3,15 @@
 require_relative 'chart/chart'
 require_relative 'files'
 require_relative 'js/js_nodes'
+require_relative 'markdown_nodes'
 require_relative 'node'
 require_relative 'stat'
 require_relative 'toc'
 
 module Raindown
   # Nodes are LowNodes that a node block writes into the Markdown and renders into the HTML.
-  # A project keeps them in a .raindown folder, which is loaded with Dirload, beside its JavaScript Components, if any.
+  # A project keeps them in a .raindown folder, which is loaded with Dirload, beside its JavaScript and Markdown
+  # Components, if any.
   # A node writes Markdown with #replace, and HTML with #render if it has one. Either can take the keywords
   # document: (the Markdown being rendered), metadata: and bare:, and gets the ones it asks for.
   module Nodes
@@ -31,6 +33,7 @@ module Raindown
       loaded << folder
       dirload(folder)
       JSNodes.load(folder)
+      MarkdownNodes.load(folder)
     end
 
     def find_folder(directory)
@@ -56,12 +59,12 @@ module Raindown
       loaded_class(BUILT_INS[name]) || Raindown.const_get(BUILT_INS[name])
     end
 
-    # A Ruby node of the name, or else a JavaScript one.
+    # A Ruby node of the name, or else a JavaScript one, or else a Markdown one.
     def loaded_class(name)
       klass = Object.const_get(name) if Object.const_defined?(name)
       return klass if node?(klass)
 
-      JSNodes.node_class(name)
+      JSNodes.node_class(name) || MarkdownNodes.node_class(name)
     end
 
     # A LowNode, or one of Raindown's own nodes, that writes Markdown. In an app, LowNodes are also routes and pages,

data/lib/raindown/projects.rb

@@ -69,7 +69,8 @@ module Raindown
 
     # Whether a file is one of a project's own nodes, which load when its watcher starts.
     def node?(path, root:)
-      File.expand_path(path).start_with?(File.join(root, Nodes::FOLDER, '')) && NODE_EXTENSIONS.include?(File.extname(path))
+      File.expand_path(path).start_with?(File.join(root, Nodes::FOLDER, '')) &&
+        (NODE_EXTENSIONS.include?(File.extname(path)) || MarkdownNodes.file?(path))
     end
 
     # The roots that aren't inside another of them, as a project's code includes the projects inside it.

data/lib/raindown/server.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../version'
+require_relative 'editing'
+require_relative 'projects'
+require_relative 'workers/workers'
+
+module Raindown
+  # "raindown server" keeps Raindown loaded for editors, like the Obsidian plugin and the VS Code extension, so a render
+  # doesn't start Ruby again. Once it's ready, it says so, then answers a JSON request a line, in order:
+  #   {"ready": true, "version": "0.10.0"}
+  #   {"id": 1, "path": "/notes/a.md", "markdown": "<!-- toc: -->", "rewrite": true}
+  #   {"id": 1, "output": "<!-- toc: -->\n- ...", "warnings": []}
+  # Rewriting answers like --stdin --rewrite, with "execute" like -x, and otherwise it's HTML, like --stdin. An error's
+  # answered as {"id": 1, "error": "raindown: /notes/a.md: ..."}, like the CLI writes it.
+  # Each project renders in a worker of its own, which starts again when its .raindown folder changes, so its nodes,
+  # config and schemas are never stale. Without fork, as on Windows, node changes need the server started again.
+  class Server
+    def initialize(input: $stdin, output: $stdout)
+      @input = input
+      @output = output
+      @workers = Workers.new(root: Dir.pwd) { Editing }
+      @stamps = {}
+    end
+
+    def start
+      write(ready: true, version: VERSION)
+      @input.each_line { |line| write(answer(line)) }
+    ensure
+      @workers.stop
+    end
+
+    private
+
+    def answer(line)
+      request = JSON.parse(line)
+      { id: request['id'], **edit(request) }
+    rescue JSON::ParserError, KeyError => e
+      { id: request&.dig('id'), error: "raindown: #{e.message}" }
+    rescue Workers::Worker::Error => e
+      { id: request['id'], error: "raindown: #{request['path']}: #{e.message}" }
+    end
+
+    def edit(request)
+      path = File.expand_path(request.fetch('path'))
+      options = { path:, bare: request['bare'] == true }
+      worker = worker_for(path)
+      return worker.call(:rewrite_markdown, request.fetch('markdown'), **options, execute: request['execute'] == true) if request['rewrite']
+
+      { output: worker.call(:render_markdown, request.fetch('markdown'), **options) }
+    end
+
+    # The project's worker, started again first when a file in its .raindown folder was added, changed or removed.
+    def worker_for(path)
+      project = Projects.root(path) || @workers.root
+      @workers.restart(project) if nodes_changed?(project)
+      @workers[project]
+    end
+
+    def nodes_changed?(project)
+      stamp = Dir.glob(File.join(project, Nodes::FOLDER, '**', '*')).to_h { [it, File.mtime(it)] }
+      changed = @stamps.key?(project) && @stamps[project] != stamp
+      @stamps[project] = stamp
+      changed
+    end
+
+    def write(message)
+      @output.puts(JSON.generate(message))
+      @output.flush
+    end
+  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,8 +90,9 @@ module Raindown
 
       def endpoint(path, lines, directive)
         snippet = CodeBlocks.endpoint(lines, directive.line).first&.dig(:body)
-        request = Curl.request(snippet.to_s)
-        Endpoint.new(project: root, path:, line: directive.line, **request.to_h) if request
+        variables = EndpointVariables.new(path:, content: lines.join)
+        request = Curl.request(snippet.to_s, variables)
+        Endpoint.new(project: root, path:, line: directive.line, method: request.method, url: variables.redact(request.url)) if request
       end
 
       def charts_in(path)