kiln 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 651c0899f42d04129a81c15dffe03cf24d95cdfb1cf7de0ec04ca4474c7e62e8
+  data.tar.gz: 23e810402d542846992a347836560c327e05d719a178301a4c76ccd77fdbb755
+SHA512:
+  metadata.gz: 606f816dc7ff50268542d41386d744d621cbe28faeea446cf8f60b2fe4fe7115d6c54e08d6099105a831c881f8ac59acd0c2600d63f77b4b4591cbc53b9b6fd9
+  data.tar.gz: 49a7c794bf38f681e794e8141da259ba3d0699ec257e9f32fe8dd16677bc4d6ed9b126cc914a3e569d91f2372de4acf5b6b0b192ee168589ba997c1897b4c7b1

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 (2026-11-07)
+
+- First release.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,164 @@
+# Kiln
+
+Kiln fires a Rails app into a static site. Build pages with normal Rails (routes, controllers, views,
+helpers, Turbo, Stimulus), then run:
+
+```sh
+RAILS_ENV=production bin/rails kiln:build
+```
+
+Kiln renders every GET route through Rack, the same way a browser request goes through your app,
+and writes plain files to `dist/` that any static host can serve.
+
+- **Routes are the page list.** A GET route with no params is built automatically. A route with
+  params needs a param source or an explicit `skip`, or the build fails and names it.
+- **Builds fail loudly.** Every render error, missing asset and broken link is collected and printed
+  as one report, and the task exits non-zero.
+- **Kiln knows nothing about your data.** Models and repositories stay ordinary app code.
+
+Requires Ruby 4.0+ and Rails 8.1+.
+
+Releases: push a `vX.Y.Z` tag matching `Kiln::VERSION`. CI runs, then the release workflow publishes
+to RubyGems through trusted publishing.
+
+## Setup
+
+```ruby
+# Gemfile
+gem "kiln"
+```
+
+```ruby
+# config/kiln.rb
+Kiln.configure do |config|
+  config.url = "https://example.com"   # sitemap, absolute URLs, request host
+  config.not_found = "/404"            # rendered to 404.html
+end
+
+Kiln.pages do
+  params :post, -> { Post.published.map { { slug: it.slug } } }
+  params :page, -> { %w[en es ja].map { { locale: it } } + [ {} ] }  # scope "(:locale)"
+  paginate :blog_page, per: 10, total: -> { Post.count }, start: 2  # /blog/page/2 ...
+  skip :search, reason: "dynamic"
+end
+```
+
+`bin/rails kiln:routes` shows every GET route and whether it is built, skipped or uncovered.
+
+Rails internals (`/rails/*`), the health check, mounted engines and turbo-rails' native navigation
+routes are skipped by default. Redirect routes become redirects, and mounted Rack apps are built
+like any other route.
+
+## Tasks
+
+| Task | What it does |
+|---|---|
+| `kiln:build` | Renders every page, exports assets, copies `public/`, writes redirects, sitemap and manifest, then verifies the output. Lists pages changed since the last build. `VERBOSE=1` shows request logs. |
+| `kiln:routes` | The route table. Exits 1 if any route is uncovered. |
+| `kiln:verify` | Checks internal links, anchors and importmap modules in the existing output. |
+| `kiln:check` | Builds into a temp dir and fails if the committed output differs. For CI. |
+| `kiln:serve` | Serves the output with static-host path resolution (`PORT`, default 4000). |
+
+## Configuration
+
+| Option | Default | |
+|---|---|---|
+| `output` | `"dist"` | Relative to `Rails.root`, or absolute. Wiped at the start of every build. |
+| `url` | `nil` | Public base URL. Needed for the sitemap and `absolute_urls`. |
+| `host` | from `url`, else `"localhost"` | Host header sent with every request. |
+| `paths` | `:directory` | `/now` → `now/index.html`. `:file` writes `now.html`. |
+| `assets` | `:referenced` | Only assets the output references (HTML, importmap, CSS `url()`). `:all` exports everything. |
+| `cname` | `nil` | Writes a `CNAME` file. |
+| `not_found` | `nil` | Path rendered to `404.html`. It may respond with 200 or 404. |
+| `redirects` | `:file` | `:file` (`_redirects`), `:meta_refresh` (HTML pages, for GitHub Pages), `:both`, or `false`. |
+| `sitemap` | `true` | Writes `sitemap.xml` (needs `url`). Pages marked `noindex` are left out. |
+| `strip_source_maps` | `true` | Removes `sourceMappingURL` comments from JS and CSS. |
+| `absolute_urls` | `false` | Makes image URLs (img, srcset, og:/twitter: images) absolute. |
+| `external_links` | `false` | Adds `target="_blank" rel="noopener"` to links to other hosts. |
+| `processors` | `[]` | Your own HTML processors: `call(html, context)` returning a String. |
+| `verify` | `true` | Runs the verifier after every build. |
+| `copy_public` | `true` | Copies `public/` (minus `public/assets`) into the output. |
+
+Hooks get a context with `output`, `env`, `manifest` and `report`:
+
+```ruby
+Kiln.configure do |config|
+  config.before_build { |context| SearchIndex.generate! }
+  config.after_build { |context| puts "#{context.manifest.entries.size} pages" }
+end
+```
+
+CSRF tokens and meta tags are always stripped. Everything else in the HTML is left byte for byte as
+the app rendered it.
+
+## In your app
+
+- `Kiln.building?` is true while a build renders pages. Use it to hide dev-only things.
+- `Kiln.build_cache.fetch(key) { ... }` memoizes for one build and is cleared before and after.
+- Builds run in production. Kiln runs `assets:precompile` in-process when needed and removes
+  `public/assets` afterwards. Assets are fetched through the app, so keep
+  `config.public_file_server.enabled = true` for builds.
+- Use root-absolute asset paths so every page's `<head>` stays identical and Turbo visits never
+  force a full reload.
+- Feeds, `robots.txt`, `llms.txt` or JSON files are ordinary routes with views
+  (`get "feed.xml"`). The file is written under the route's path.
+
+## Testing
+
+```ruby
+require "kiln/test_helper"
+
+class StaticSiteTest < ActiveSupport::TestCase
+  include Kiln::TestHelper
+
+  test("builds the same output twice") { assert_repeatable_build }
+  test("home page") { assert_page "/", selector: "h1", text: "Welcome" }
+end
+```
+
+`kiln_build { |output| ... }` builds into a temp dir, fails with the report on any error and
+yields the output path.
+
+## Content layer
+
+Optional, and it works in server-rendered apps too:
+
+```ruby
+# Gemfile
+gem "redcarpet"
+gem "rouge"
+
+# config/application.rb, after Bundler.require
+require "kiln/content"
+```
+
+- **Markdown views:** `app/views/pages/about.html.md` renders through the layout like any view.
+  `.md.erb` runs ERB first. Code blocks get Rouge CSS classes (`rougify style github`).
+- **Collections:** `content/blog/2024-05-01-hello.md` with YAML frontmatter.
+
+  ```ruby
+  posts = Kiln::Content.collection("blog")
+  posts.all                     # visible entries, newest first
+  posts.find("hello")           # raises Kiln::Content::NotFound (a 404)
+  post.title, post.published_at, post.html, post[:tags]
+
+  # config/kiln.rb
+  params :post, -> { Kiln::Content.collection("blog").map { { slug: it.slug } } }
+  ```
+
+- **Publishing:** `draft: true` and future `published_at` entries are hidden, except in
+  development when not building. `Kiln::Content.show_drafts` overrides this. Server-rendered apps
+  can share a hidden entry with `posts.find(slug, preview_token: params[:token])`.
+
+## Limitations in 0.1
+
+- Pages render one at a time. Parallel rendering is planned.
+- Only exact `_redirects` rules count for the verifier and `kiln:serve`. Splat and placeholder
+  rules in your own `public/_redirects` are written out but not followed.
+- JS modules are found through the importmap. Relative `import "./x.js"` between files is not
+  followed.
+- Collections read `*.md` files only (`.md.erb` works for views).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/kiln/assets.rb

@@ -0,0 +1,162 @@
+require "fileutils"
+require "json"
+require "nokogiri"
+require "set"
+
+module Kiln
+  # Finds the /assets/* files the output uses and fetches them through the app, so the same code works
+  # with dynamic Propshaft (development, test) and with precompiled assets served from public/assets.
+  class Assets
+    CSS_REFERENCE = /url\(\s*["']?([^"')]+?)["']?\s*\)|@import\s+["']([^"']+)["']/
+    EXTERNAL = %r{\A(?:[a-z][a-z0-9+.-]*:|//|#)}i
+
+    class << self
+      # Compiles assets in-process when the app does not serve them dynamically. Returns a callable that
+      # removes what the precompile created, or nil when nothing was compiled.
+      def precompile(app)
+        return unless precompile?(app)
+
+        output_path = Pathname(app.config.assets.output_path)
+        created = !output_path.exist?
+        run_precompile(app)
+
+        -> { created ? FileUtils.rm_rf(output_path) : FileUtils.rm_f(app.config.assets.manifest_path) }
+      end
+
+      def precompile?(app)
+        assets = app.config.respond_to?(:assets) && app.config.assets
+        return false unless assets.respond_to?(:server) && assets.manifest_path
+
+        !assets.server && !Pathname(assets.manifest_path).exist?
+      end
+
+      # Copies public/ into the output, minus public/assets. Files already in the output win, with a
+      # warning unless they are listed in `generated` (files Kiln writes on purpose, like 404.html).
+      def copy_public(from:, to:, report:, generated: [])
+        from = Pathname(from)
+        return unless from.directory?
+
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: from).sort.each do |relative|
+          source = from.join(relative)
+          next if source.directory? || relative.start_with?("assets/")
+
+          target = Pathname(to).join(relative)
+          if target.exist?
+            next if generated.include?(relative)
+
+            report.warn(:write, "public/#{relative} not copied, a rendered file already exists", path: "/#{relative}")
+          else
+            FileUtils.mkdir_p(target.dirname)
+            FileUtils.cp(source, target)
+            report.wrote(relative)
+          end
+        end
+      end
+
+      private
+        def run_precompile(app)
+          require "rake"
+          app.load_tasks unless Rake::Task.task_defined?("assets:precompile")
+          task = Rake::Task["assets:precompile"]
+          task.reenable
+          task.invoke
+        rescue StandardError => error
+          raise Kiln::Error, "assets:precompile failed: #{error.class}: #{error.message}"
+        end
+    end
+
+    def initialize(renderer:, output:, config:, report:, app: Rails.application)
+      @renderer = renderer
+      @output = Pathname(output)
+      @config = config
+      @report = report
+      @app = app
+    end
+
+    def export
+      queue = referenced_paths
+      queue.concat(all_paths) if @config.assets == :all
+      seen = Set.new
+
+      while (path = queue.shift)
+        next unless seen.add?(path)
+        queue.concat(fetch(path))
+      end
+    end
+
+    private
+      # Writes one asset and returns the asset paths it references (CSS url() and @import).
+      def fetch(path)
+        response = @renderer.get(path)
+        unless response.success?
+          @report.error(:asset, "responded with #{response.status}", path:)
+          return []
+        end
+
+        extension = File.extname(path)
+        body = response.body
+        body = Processors::StripSourceMaps.call(body) if @config.strip_source_maps && %w[.js .css].include?(extension)
+        write(path, body)
+        extension == ".css" ? css_references(path, body) : []
+      rescue StandardError => error
+        @report.error(:asset, "#{error.class}: #{error.message}", path:)
+        []
+      end
+
+      def write(path, body)
+        relative = path.delete_prefix("/")
+        file = @output.join(relative)
+        FileUtils.mkdir_p(file.dirname)
+        File.binwrite(file, body)
+        @report.wrote(relative)
+      end
+
+      def referenced_paths
+        Dir.glob("**/*.html", base: @output).sort.flat_map do |relative|
+          html_references(Nokogiri::HTML(File.read(@output.join(relative))))
+        end.filter_map { asset_path(it) }.uniq
+      end
+
+      def html_references(doc)
+        urls = doc.xpath("//@href | //@src").map(&:value)
+        urls += doc.xpath("//@srcset").flat_map { |attr| attr.value.split(",").map { it.strip.split(/\s+/).first } }
+        doc.css('script[type="importmap"]').each do |script|
+          map = JSON.parse(script.text)
+          urls += map.fetch("imports", {}).values
+          urls += map.fetch("scopes", {}).values.flat_map(&:values)
+        rescue JSON::ParserError
+          @report.error(:asset, "invalid importmap JSON")
+        end
+        urls.compact
+      end
+
+      def css_references(css_path, body)
+        body.to_s.scan(CSS_REFERENCE).filter_map do |url, import|
+          ref = (url || import).strip
+          next if ref.empty? || ref.match?(EXTERNAL)
+
+          asset_path(URI.join("http://kiln#{css_path}", ref).path)
+        rescue URI::Error
+          nil
+        end
+      end
+
+      def all_paths
+        @app.assets.load_path.assets.map { "#{prefix}/#{it.digested_path}" }
+      end
+
+      # Normalizes a URL to an asset path ("/assets/app-abc.css"), or nil when it isn't one of ours.
+      def asset_path(url)
+        uri = URI.parse(url.to_s.strip)
+        return if uri.host && uri.host != @config.host
+
+        uri.path if uri.path&.start_with?("#{prefix}/")
+      rescue URI::Error
+        nil
+      end
+
+      def prefix
+        @prefix ||= @app.config.assets.prefix.to_s.chomp("/")
+      end
+  end
+end

data/lib/kiln/build.rb

@@ -0,0 +1,146 @@
+require "fileutils"
+
+module Kiln
+  # Runs the whole pipeline and returns a Report. Never raises for page-level problems: those go in
+  # the report so the build can show every failure at once.
+  class Build
+    # Passed to before_build / after_build hooks.
+    Context = Data.define(:output, :env, :manifest, :report)
+
+    attr_reader :app, :config, :pages_dsl, :output, :report, :manifest, :previous_manifest
+
+    def initialize(app: Rails.application, config: Kiln.config, pages: Kiln.pages, output: nil)
+      @app = app
+      @config = config
+      @pages_dsl = pages
+      @output = Pathname(output || config.output_path(app.root))
+      @report = Report.new
+      @manifest = Manifest.new
+      @redirects = []
+    end
+
+    # Pages added, removed and changed since the previous build in the same output, or nil.
+    def changes
+      previous_manifest&.diff(manifest)
+    end
+
+    def run
+      Kiln.building! do
+        guard_output!
+        guard_static_files!
+        cleanup = Assets.precompile(app)
+        begin
+          run_hooks(config.before_build_hooks)
+          prepare_output
+
+          pages = Router.new(app.routes, pages_dsl, report:).pages
+          pages.reject { it.path == config.not_found }.each { render_page(it) }
+          render_not_found if config.not_found
+
+          Assets.new(renderer:, output:, config:, report:).export
+          Assets.copy_public(from: app.root.join("public"), to: output, report:, generated: generated_files) if config.copy_public
+          write_redirects if config.redirects && @redirects.any?
+          Sitemap.new(manifest, url: config.url).write(output) if config.sitemap && config.url
+          write_cname if config.cname
+          manifest.write(output)
+
+          Verifier.new(output, config:).verify(report) if config.verify
+          run_hooks(config.after_build_hooks)
+        ensure
+          cleanup&.call
+        end
+      end
+      report
+    end
+
+    private
+      def renderer
+        @renderer ||= Renderer.new(app, host: config.host)
+      end
+
+      def writer
+        @writer ||= Writer.new(output, mode: config.paths)
+      end
+
+      def render_page(page)
+        response = renderer.get(page.path)
+
+        if response.redirect?
+          @redirects << Redirects::Entry.new(from: page.path, to: response.location, status: response.status)
+        elsif response.success?
+          body = response.html? ? Processors.apply(response.body, Processors::Context.new(path: page.path, config:, response:)) : response.body
+          file = writer.write(page.path, response.content_type, body)
+          manifest.add(page.path, file:, body:, content_type: response.content_type, noindex: Sitemap.noindex?(response, body))
+          report.wrote(file)
+        else
+          report.error(:render, "responded with #{response.status}", path: page.path)
+        end
+      rescue StandardError => error
+        report.error(:render, describe(error), path: page.path)
+      end
+
+      def render_not_found
+        response = renderer.get(config.not_found)
+        unless [ 200, 404 ].include?(response.status)
+          return report.error(:render, "404 page responded with #{response.status}", path: config.not_found)
+        end
+
+        body = Processors.apply(response.body, Processors::Context.new(path: config.not_found, config:, response:))
+        report.wrote(writer.write_file("404.html", body))
+      rescue StandardError => error
+        report.error(:render, describe(error), path: config.not_found)
+      end
+
+      def write_redirects
+        Redirects.new(@redirects, mode: config.redirects, writer:, host: config.host, url: config.url).write(output).each { report.wrote(it) }
+      end
+
+      # Files Kiln writes on purpose that may also exist in public/ (Rails ships a public/404.html).
+      def generated_files
+        [ ("404.html" if config.not_found), ("CNAME" if config.cname) ].compact
+      end
+
+      def write_cname
+        report.wrote(writer.write_file("CNAME", "#{config.cname}\n"))
+      end
+
+      def run_hooks(hooks)
+        context = Context.new(output:, env: Rails.env, manifest:, report:)
+        hooks.each do |hook|
+          hook.call(context)
+        rescue StandardError => error
+          report.error(:hook, describe(error))
+        end
+      end
+
+      def prepare_output
+        previous = output.join(Manifest::FILENAME)
+        @previous_manifest = Manifest.load(previous) if previous.file?
+        FileUtils.rm_rf(output)
+        FileUtils.mkdir_p(output)
+      end
+
+      # Refuse to wipe anything that contains the app.
+      def guard_output!
+        root = app.root.expand_path
+        out = output.expand_path
+        if out == root || root.to_s.start_with?("#{out}/") || out.root?
+          raise Kiln::Error, "Refusing to use #{out} as the output directory"
+        end
+      end
+
+      # After a precompile, assets are fetched from public/assets through ActionDispatch::Static.
+      def guard_static_files!
+        return unless app.config.respond_to?(:assets) && !app.config.assets.server
+        return if app.config.public_file_server.enabled
+
+        raise Kiln::Error, "Kiln fetches compiled assets through the public file server. " \
+          "Set config.public_file_server.enabled = true for the build environment."
+      end
+
+      def describe(error)
+        where = error.backtrace&.find { it.start_with?(app.root.to_s) }&.delete_prefix("#{app.root}/")
+        [ "#{error.class}: #{error.message}", where && "(#{where})" ].compact.join(" ")
+      end
+  end
+end

data/lib/kiln/build_cache.rb

@@ -0,0 +1,23 @@
+module Kiln
+  # A plain in-memory store that returns the cached objects themselves (no copies), so memoized
+  # repositories and collections keep their state for the whole build.
+  class BuildCache
+    def initialize
+      @store = {}
+      @mutex = Monitor.new
+    end
+
+    def fetch(key)
+      @mutex.synchronize do
+        return @store[key] if @store.key?(key)
+
+        @store[key] = yield
+      end
+    end
+
+    def read(key) = @mutex.synchronize { @store[key] }
+    def write(key, value) = @mutex.synchronize { @store[key] = value }
+    def delete(key) = @mutex.synchronize { @store.delete(key) }
+    def clear = @mutex.synchronize { @store.clear }
+  end
+end

data/lib/kiln/check.rb

@@ -0,0 +1,22 @@
+require "tmpdir"
+
+module Kiln
+  # Builds into a temp dir and compares the result with the committed output.
+  class Check
+    Result = Data.define(:report, :diff) do
+      def success? = report.success? && diff.empty?
+    end
+
+    def initialize(app: Rails.application, config: Kiln.config)
+      @app = app
+      @config = config
+    end
+
+    def run
+      Dir.mktmpdir("kiln-check") do |dir|
+        report = Build.new(app: @app, config: @config, output: dir).run
+        Result.new(report:, diff: TreeDiff.call(@config.output_path(@app.root), dir))
+      end
+    end
+  end
+end

data/lib/kiln/configuration.rb

@@ -0,0 +1,65 @@
+module Kiln
+  class Configuration
+    # Output directory, relative to Rails.root unless absolute.
+    attr_accessor :output
+    # Public base URL ("https://davafons.com"). Used by the sitemap and absolute_urls processor.
+    attr_accessor :url
+    # :directory ("/now" -> now/index.html) or :file ("/now" -> now.html).
+    attr_accessor :paths
+    # :referenced (only assets the output uses) or :all (everything under /assets).
+    attr_accessor :assets
+    # Writes a CNAME file with this domain when set.
+    attr_accessor :cname
+    # Removes `sourceMappingURL` comments from JS and CSS.
+    attr_accessor :strip_source_maps
+    # Extra HTML processors: objects responding to call(html, context) -> html.
+    attr_accessor :processors
+    # Built-in optional processors, off by default.
+    attr_accessor :absolute_urls, :external_links
+    # Path rendered to 404.html (expected to respond with 404 or 200), nil to skip.
+    attr_accessor :not_found
+    # :file (_redirects), :meta_refresh (HTML pages), :both, or false.
+    attr_accessor :redirects
+    # Writes sitemap.xml when true and `url` is set.
+    attr_accessor :sitemap
+    # Runs the verifier (links, anchors, importmap) after every build.
+    attr_accessor :verify
+    # Copy public/ into the output (minus public/assets).
+    attr_accessor :copy_public
+
+    attr_reader :before_build_hooks, :after_build_hooks
+    attr_writer :host
+
+    def initialize
+      @output = "dist"
+      @url = nil
+      @host = nil
+      @paths = :directory
+      @assets = :referenced
+      @cname = nil
+      @strip_source_maps = true
+      @processors = []
+      @absolute_urls = false
+      @external_links = false
+      @not_found = nil
+      @redirects = :file
+      @sitemap = true
+      @verify = true
+      @copy_public = true
+      @before_build_hooks = []
+      @after_build_hooks = []
+    end
+
+    # Host sent with every request. Derived from `url`, falls back to "localhost".
+    def host
+      @host || (url && URI(url).host) || "localhost"
+    end
+
+    def output_path(root = Rails.root)
+      Pathname(output).absolute? ? Pathname(output) : Pathname(root).join(output)
+    end
+
+    def before_build(&block) = @before_build_hooks << block
+    def after_build(&block) = @after_build_hooks << block
+  end
+end

data/lib/kiln/content/collection.rb

@@ -0,0 +1,43 @@
+module Kiln
+  module Content
+    class Collection
+      include Enumerable
+
+      attr_reader :name
+
+      def initialize(name, dir)
+        @name, @dir = name.to_s, Pathname(dir)
+        @stamp = stamp
+        @entries = files.map { Entry.new(@name, it) }
+          .sort_by { [ it.published_at&.in_time_zone || Time.at(0), it.slug ] }.reverse
+      end
+
+      # Visible entries, newest first.
+      def all
+        Content.show_drafts ? @entries : @entries.select(&:published?)
+      end
+
+      def each(&) = all.each(&)
+
+      def find(slug, preview_token: nil)
+        entry = @entries.find { it.slug == slug.to_s }
+        return entry if entry && (Content.show_drafts || entry.published? || preview?(entry, preview_token))
+        raise NotFound, "no #{name} entry with slug #{slug.inspect}"
+      end
+
+      def find_by(slug:) = all.find { it.slug == slug.to_s }
+
+      # True when files were added, removed or changed since loading.
+      def stale? = stamp != @stamp
+
+      private
+        def files = Dir[@dir.join("*.md")].sort
+
+        def stamp = files.map { [ it, File.mtime(it) ] }
+
+        def preview?(entry, token)
+          token.present? && ActiveSupport::SecurityUtils.secure_compare(entry.preview_token, token.to_s)
+        end
+    end
+  end
+end