datalog-theme 0.10.1 → 0.11.0

data/lib/datalog/citations/markup.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Datalog
+  module Citations
+    # The HTML a page's citations become: the label of each cited work, the
+    # marker in the text, and the reference list with its links back.
+    module Markup
+      module_function
+
+      # key => "1" (numeric) or "Smith 2020a" (author-year).
+      def labels(entries, style, words)
+        return entries.each_with_index.to_h { |entry, index| [entry.key, (index + 1).to_s] } if style == "numeric"
+
+        base = entries.to_h { |entry| [entry.key, [entry.names_in_text(words), entry.year_or(words[:no_date])]] }
+        suffixes = {}
+        base.group_by { |_, label| label }.each_value do |group|
+          next if group.size < 2
+
+          group.each_with_index { |(key, _), index| suffixes[key] = ("a".ord + index).chr }
+        end
+        base.to_h { |key, (names, year)| [key, "#{names} #{year}#{suffixes[key]}"] }
+      end
+
+      # An id for each key, safe in a URL fragment and unique on the page.
+      def anchors(entries)
+        seen = Hash.new(0)
+        entries.to_h do |entry|
+          anchor = entry.key.gsub(/[^A-Za-z0-9_.:-]/, "-")
+          seen[anchor] += 1
+          [entry.key, seen[anchor] > 1 ? "#{anchor}-#{seen[anchor]}" : anchor]
+        end
+      end
+
+      def marker(links, locator, style)
+        tail = locator ? ", #{CGI.escapeHTML(locator)}" : ""
+        if style == "numeric"
+          %(<span class="datalog-cite">[#{links.join(', ')}#{tail}]</span>)
+        else
+          %(<span class="datalog-cite">(#{links.join('; ')}#{tail})</span>)
+        end
+      end
+
+      def locator_text(value, words)
+        return nil if value.to_s.empty?
+
+        kind, text = CGI.unescapeHTML(value).split("|", 2)
+        kind == "loc" ? text : "#{words[:locators][kind]} #{text}"
+      end
+
+      def list_html(entries, labels, anchors, backlinks, style, words)
+        return "" if entries.empty?
+
+        tag = style == "numeric" ? "ol" : "ul"
+        items = entries.map do |entry|
+          suffix = style == "author-year" ? labels[entry.key][/\d([a-z])\z/, 1].to_s : ""
+          back = backlinks_html(backlinks[entry.key], words)
+          %(<li id="cite-#{anchors[entry.key]}">#{entry.reference_html(words, suffix: suffix)}#{back}</li>)
+        end
+        %(<#{tag} class="datalog-bibliography datalog-bibliography--#{style}">#{items.join}</#{tag}>)
+      end
+
+      # A return arrow for one citation; the arrow and a b c for several, each
+      # letter a link back to its place in the text.
+      def backlinks_html(refs, words)
+        return "" if refs.empty?
+
+        links = refs.each_with_index.map do |ref, index|
+          label = CGI.escapeHTML(words[:back].gsub("{{n}}", (index + 1).to_s))
+          text = refs.size == 1 ? "↩" : ("a".ord + index).chr
+          %(<a href="##{ref}" aria-label="#{label}">#{text}</a>)
+        end
+        prefix = refs.size == 1 ? "" : "↩ "
+        %( <span class="datalog-bibliography__back">#{prefix}#{links.join(' ')}</span>)
+      end
+    end
+  end
+end

data/lib/datalog/cli.rb

@@ -9,13 +9,117 @@ require "tmpdir"
 require "yaml"
 require "thor"
 
+require_relative "site_config"
 require_relative "slug"
 require_relative "theme/version"
+require_relative "packages/command"
 
 module Datalog
+  module ArchiveScaffold
+    private
+
+    def scaffold_archive
+      type = options[:type].to_s.downcase
+      unless %w[year tag category topic].include?(type)
+        say_status :error, "Archive type must be year, tag, category, or topic", :red
+        exit 1
+      end
+
+      path = options[:path] || { "year" => "/archives/years/", "tag" => "/tags/",
+                                 "category" => "/categories/", "topic" => "/archives/topic/" }.fetch(type)
+      unless path.match?(%r{\A/[a-zA-Z0-9/_-]+/\z}) && !path.include?("//")
+        say_status :error, "Archive path must be a site URL such as /tags/", :red
+        exit 1
+      end
+
+      title = options[:title] || { "year" => "Years", "tag" => "Tags", "category" => "Categories",
+                                   "topic" => "Topic" }.fetch(type)
+      file = File.join(ensure_directory!("_pages"), "archive-#{type}.md")
+      if File.exist?(file)
+        say_status :error, "Archive already exists: #{file}", :red
+        exit 1
+      end
+
+      topic = type == "topic" ? "topic:\n  tags: [example-topic]\n  categories: []\n  featured: []\n" : ""
+      front = "---\nlayout: archive\ntitle: #{title.to_json}\narchive: #{type}\n"
+      create_file(file, "#{front}permalink: #{path.to_json}\n#{topic}---\n\n")
+      say_status :create, relative_to_root(file), :green
+    end
+  end
+
+  # Publishing to a branch through a temporary git worktree: `datalog publish`.
+  module PublishWorktree
+    private
+
+    def remote_branch?(root, branch)
+      system("git", "ls-remote", "--exit-code", "origin", "refs/heads/#{branch}", out: File::NULL, err: File::NULL,
+                                                                                  chdir: root)
+    end
+
+    def prepare_worktree(root, branch, worktree_path)
+      unless system("git", "show-ref", "--verify", "--quiet", "refs/heads/#{branch}", chdir: root)
+        say_status :info, "Creating #{branch} branch", :blue
+        if remote_branch?(root, branch)
+          system("git", "branch", branch, "origin/#{branch}", chdir: root)
+        else
+          system("git", "branch", branch, chdir: root)
+        end
+      end
+
+      say_status :git, "git worktree add --force #{worktree_path} #{branch}", :blue
+      return if system("git", "worktree", "add", "--force", worktree_path, branch, chdir: root)
+
+      say_error "Unable to create git worktree for #{branch}."
+      exit 1
+    end
+
+    def copy_site_output(root, worktree_path)
+      say_status :sync, "Copying _site to #{worktree_path}", :blue
+      FileUtils.rm_rf(Dir.glob(File.join(worktree_path, "*"),
+                               File::FNM_DOTMATCH) - [File.join(worktree_path, "."), File.join(worktree_path, ".."),
+                                                      File.join(worktree_path, ".git")])
+      Dir.glob(File.join(root, "_site", "*"), File::FNM_DOTMATCH).each do |entry|
+        next if [".", ".."].include?(File.basename(entry))
+
+        FileUtils.cp_r(entry, worktree_path, preserve: true)
+      end
+    end
+
+    # Returns whether the branch now holds the site. The exit status of commit
+    # and push used to be ignored, so a rejected push still ended as a publish.
+    def commit_and_push(worktree_path, branch, message)
+      Dir.chdir(worktree_path) do
+        system("git", "add", "--all")
+        if system("git", "diff", "--cached", "--quiet")
+          say_status :skip, "No changes to publish", :yellow
+          return true
+        end
+
+        unless system("git", "commit", "-m", message)
+          say_error "git commit failed, so nothing was published."
+          return false
+        end
+
+        say_status :git, "git push origin #{branch}", :blue
+        return true if system("git", "push", "origin", branch)
+
+        say_error "git push to #{branch} failed, so the site was not published."
+        false
+      end
+    end
+
+    def cleanup_worktree(root, worktree_path)
+      say_status :git, "git worktree remove --force #{worktree_path}", :blue
+      system("git", "worktree", "remove", "--force", worktree_path, chdir: root)
+    ensure
+      FileUtils.rm_rf(File.dirname(worktree_path)) if worktree_path && File.directory?(File.dirname(worktree_path))
+    end
+  end
+
   # Command line interface for automating common theme workflows.
   class CLI < Thor
     include Thor::Actions
+    include Datalog::PublishWorktree
 
     class_option :root,
                  type: :string,
@@ -62,6 +166,36 @@ module Datalog
       exit 1 unless critical_failures.empty?
     end
 
+    desc "audit", "Report pages that would gain from newer authoring features, and content problems"
+    method_option :strict, type: :boolean, default: false, desc: "Exit 1 when the audit finds a problem"
+    method_option :format, type: :string, default: "text", enum: %w[text json markdown], desc: "Output format"
+    method_option :only, type: :string, desc: "Comma-separated checks to run, such as statements,series"
+    method_option :path, type: :string, desc: "Audit only the files under this path, such as _posts/statistics"
+    long_desc <<~DESC
+      Reads the site's pages and posts, without building or writing anything, and
+      lists two kinds of finding with the file and line of each. Opportunities are
+      content the theme's newer features would number, link or describe (statements
+      and figure numbers typed by hand, parts of a series, links to code with no
+      reproducibility block, edits with no revision entry, hand-written references).
+      Problems are front matter keys nothing reads, images without alt text, links
+      to pages the site does not build, and math switched on or off against the
+      page's content. Exit codes: 0, or 1 with --strict when there is a problem;
+      2 when the audit cannot run.
+    DESC
+    def audit
+      require_relative "audit"
+      report = Audit.new(root: site_root, only: options[:only], path: options[:path]).run
+      case options[:format]
+      when "json" then say report.to_json
+      when "markdown" then say report.to_markdown
+      else say report.to_text
+      end
+      exit 1 if options[:strict] && report.problems.any?
+    rescue Audit::Error => e
+      say_error e.message
+      exit 2
+    end
+
     desc "publish", "Build the site and deploy the _site artifacts to GitHub Pages"
     method_option :branch,
                   type: :string,
@@ -108,35 +242,30 @@ module Datalog
     end
 
     desc "update", "Update the DataLog theme and related assets to the latest version"
+    method_option :to, type: :string, default: "latest", desc: "Release tag to check out (default: latest stable)"
+    method_option :dry_run, type: :boolean, default: false, desc: "Show the update without changing files"
+    method_option :build, type: :boolean, default: false, desc: "Build the site in a temporary directory after updating"
     long_desc <<~DESC
-      Runs Bundler to update the datalog-theme dependency to the latest compatible
-      release and refreshes npm packages if a package.json file is present.
+      For a path-installed Git checkout, checks out a release, builds its script
+      bundles, installs site gems, checks for stale files and stages the submodule.
+      For a published gem, updates Bundler and the site's npm packages.
+      Exit codes: 0 already current, 2 updated, 1 failed.
     DESC
     def update
-      root = site_root
-      gemfile = gemfile_path(root)
-
-      if File.exist?(gemfile)
-        run_or_exit(:bundle, "bundle update datalog-theme", root, "Bundler could not update datalog-theme.",
-                    { "BUNDLE_GEMFILE" => gemfile })
-      else
-        say_status :skip, "No Gemfile detected—skipping Bundler update", :yellow
-      end
-
-      package_json = File.join(root, "package.json")
-      if File.exist?(package_json) && command_available?("npm")
-        # npm's exit status used to be dropped, so a failed install still ended
-        # with "Theme dependencies are up to date!".
-        run_or_exit(:npm, "npm install", root, "npm could not install the site's packages.")
-      elsif File.exist?(package_json)
-        say_status :warn, "Node.js tooling not available—skipping npm install", :yellow
-      end
-
-      say "Theme dependencies are up to date!"
+      require_relative "theme/updater"
+      status = Theme::Updater.new(root: site_root, options: options,
+                                  report: ->(message) { say(message) },
+                                  execute: ->(env, command, dir) { system(env, command, chdir: dir) },
+                                  available: ->(command) { command_available?(command) }).run
+      exit status if status == 2
+    rescue Theme::Updater::Error => e
+      say_error e.message
+      exit 1
     end
 
     class New < Thor
       include Thor::Actions
+      include Datalog::ArchiveScaffold
 
       class_option :root,
                    type: :string,
@@ -239,6 +368,14 @@ module Datalog
         say_status :create, relative_to_root(filename), :green
       end
 
+      desc "archive", "Scaffold a year, tag, category, or topic archive page"
+      method_option :type, type: :string, default: "year", desc: "Archive type: year, tag, category, or topic"
+      method_option :title, type: :string, desc: "Page title"
+      method_option :path, type: :string, desc: "URL path, such as /archives/years/"
+      def archive
+        scaffold_archive
+      end
+
       desc "notebook", "Generate a notebook landing page and starter .ipynb file"
       method_option :title, type: :string, aliases: "-t", desc: "Title for the notebook"
       method_option :language, type: :string, aliases: "-l", default: "python", desc: "Primary notebook language"
@@ -423,13 +560,15 @@ module Datalog
 
     desc "critical-css", "Write the critical CSS a production build inlines, into _includes/critical-css"
     method_option :critical, type: :array,
-                             desc: "Command that runs critical (default: node_modules/.bin/critical or npx critical@8)"
+                             desc: "Command that runs critical (default: node_modules/.bin/critical or npx critical@9)"
     def critical_css
       require_relative "critical_css"
       CriticalCss.command(site_root, options[:critical], ->(*line) { say_status(*line) })
     end
 
-    register(New, "new", "new COMMAND", "Scaffold posts, notebooks, and portfolio projects")
+    register(New, "new", "new COMMAND", "Scaffold posts, archives, notebooks, and portfolio projects")
+    register(PackagesCommand, "packages", "packages COMMAND",
+             "Read package releases from their registries into _data/package_releases.yml")
 
     private
 
@@ -522,7 +661,7 @@ module Datalog
     end
 
     def load_config(path)
-      YAML.safe_load_file(path, permitted_classes: [Date, Time]) || {}
+      SiteConfig.load(path)
     end
 
     def summarize_checks(critical, warnings)
@@ -547,70 +686,6 @@ module Datalog
       end
     end
 
-    def remote_branch?(root, branch)
-      system("git", "ls-remote", "--exit-code", "origin", "refs/heads/#{branch}", out: File::NULL, err: File::NULL,
-                                                                                  chdir: root)
-    end
-
-    def prepare_worktree(root, branch, worktree_path)
-      unless system("git", "show-ref", "--verify", "--quiet", "refs/heads/#{branch}", chdir: root)
-        say_status :info, "Creating #{branch} branch", :blue
-        if remote_branch?(root, branch)
-          system("git", "branch", branch, "origin/#{branch}", chdir: root)
-        else
-          system("git", "branch", branch, chdir: root)
-        end
-      end
-
-      say_status :git, "git worktree add --force #{worktree_path} #{branch}", :blue
-      return if system("git", "worktree", "add", "--force", worktree_path, branch, chdir: root)
-
-      say_error "Unable to create git worktree for #{branch}."
-      exit 1
-    end
-
-    def copy_site_output(root, worktree_path)
-      say_status :sync, "Copying _site to #{worktree_path}", :blue
-      FileUtils.rm_rf(Dir.glob(File.join(worktree_path, "*"),
-                               File::FNM_DOTMATCH) - [File.join(worktree_path, "."), File.join(worktree_path, ".."),
-                                                      File.join(worktree_path, ".git")])
-      Dir.glob(File.join(root, "_site", "*"), File::FNM_DOTMATCH).each do |entry|
-        next if [".", ".."].include?(File.basename(entry))
-
-        FileUtils.cp_r(entry, worktree_path, preserve: true)
-      end
-    end
-
-    # Returns whether the branch now holds the site. The exit status of commit
-    # and push used to be ignored, so a rejected push still ended as a publish.
-    def commit_and_push(worktree_path, branch, message)
-      Dir.chdir(worktree_path) do
-        system("git", "add", "--all")
-        if system("git", "diff", "--cached", "--quiet")
-          say_status :skip, "No changes to publish", :yellow
-          return true
-        end
-
-        unless system("git", "commit", "-m", message)
-          say_error "git commit failed, so nothing was published."
-          return false
-        end
-
-        say_status :git, "git push origin #{branch}", :blue
-        return true if system("git", "push", "origin", branch)
-
-        say_error "git push to #{branch} failed, so the site was not published."
-        false
-      end
-    end
-
-    def cleanup_worktree(root, worktree_path)
-      say_status :git, "git worktree remove --force #{worktree_path}", :blue
-      system("git", "worktree", "remove", "--force", worktree_path, chdir: root)
-    ensure
-      FileUtils.rm_rf(File.dirname(worktree_path)) if worktree_path && File.directory?(File.dirname(worktree_path))
-    end
-
     def say_error(message)
       say message, :red
     end

data/lib/datalog/critical_css.rb

@@ -3,9 +3,12 @@
 require "date"
 require "fileutils"
 require "jekyll"
+require "json"
+require "nokogiri"
 require "open3"
 require "tmpdir"
 require "yaml"
+require_relative "site_config"
 
 module Datalog
   # Writes the critical CSS a production build inlines. head.html inlines
@@ -14,10 +17,24 @@ module Datalog
   # rendering. Critical CSS depends on a site's own pages and styles, so the
   # theme ships those files empty and each site writes its own with
   # `datalog critical-css`.
+  #
+  # It runs critical 9, which has two engines. `render`, the default, opens
+  # the page in Playwright's Chromium at each viewport in `dimensions` and
+  # keeps the rules for what is painted there: the first screen, as critical 8
+  # measured it. `static` needs no browser: it keeps every rule the page's
+  # markup uses, which is more CSS but takes a second rather than a browser.
   class CriticalCss
     TARGETS = %w[home post default].freeze
+    ENGINES = %w[render static].freeze
     DEFAULT_DIMENSIONS = [{ "width" => 1920, "height" => 1080 }, { "width" => 375, "height" => 667 }].freeze
-    PACKAGE = "critical@8"
+    PACKAGE = "critical@9"
+    # The render engine's browser. critical 9 leaves Playwright to the site, as
+    # an optional peer, so npx is asked for both.
+    PLAYWRIGHT = "playwright@1"
+    MAJOR = 9
+    # critical 9 needs it, as critical 8 did.
+    NODE = Gem::Version.new("22.13.0")
+    STYLESHEET = "assets/css/main.css"
 
     class Error < StandardError; end
 
@@ -26,7 +43,7 @@ module Datalog
     # `datalog critical-css`. status reports a line as the command's shell
     # does; an error ends the command with exit status 1.
     def self.command(root, critical, status)
-      config = YAML.safe_load_file(File.join(root, "_config.yml"), permitted_classes: [Date, Time]) || {}
+      config = SiteConfig.load(File.join(root, "_config.yml"))
       log = ->(message) { status.call(:critical, message, :blue) }
       written = new(root, config["critical_css"], critical: critical, log: log).run
       written.each_value { |path| status.call(:write, path, :green) }
@@ -36,7 +53,8 @@ module Datalog
     end
 
     # critical: the command that runs critical, as a list of words. By default
-    # the site's own node_modules/.bin/critical, or `npx --yes critical@8`.
+    # the site's own node_modules/.bin/critical, or `npx --yes critical@9`
+    # (with Playwright for the render engine).
     def initialize(root, settings, critical: nil, log: ->(_message) {})
       @root = File.expand_path(root)
       @settings = settings || {}
@@ -50,6 +68,15 @@ module Datalog
       unless settings["enabled"] == true
         raise Error, "critical_css.enabled is not true in _config.yml, so no page would inline critical CSS"
       end
+      unless ENGINES.include?(engine)
+        raise Error, "critical_css.engine is #{engine.inspect}; it is render (the default) or static"
+      end
+
+      if settings["penthouse_options"]
+        @log.call("critical 9 has no penthouse options, so critical_css.penthouse_options is ignored")
+      end
+      command = critical_command
+      install_browser if command == npx_command && engine == "render"
 
       Dir.mktmpdir("datalog-critical") do |site_dir|
         @log.call("Building the site for production into a temporary directory")
@@ -60,8 +87,8 @@ module Datalog
             next
           end
 
-          @log.call("Extracting critical CSS for #{target} from #{page}")
-          written[target] = write(target, extract(site_dir, page))
+          @log.call("Extracting critical CSS for #{target} from #{page} (#{engine} engine)")
+          written[target] = write(target, extract(site_dir, page, command))
         end
       end
     end
@@ -110,13 +137,12 @@ module Datalog
       "default" unless html.match?(/<meta name="robots" content="noindex/)
     end
 
-    # Only the site's stylesheet: the Google Fonts stylesheet would inline
-    # @font-face rules for the font files headless Chrome is served (TrueType),
-    # and fetching it made each page take over a minute.
-    def extract(site_dir, page)
-      arguments = [page, "--base", site_dir, "--css", File.join(site_dir, "assets", "css", "main.css"),
-                   *dimension_arguments, *penthouse_arguments]
-      output, errors, status = Open3.capture3(*critical_command, *arguments, chdir: site_dir)
+    # The page goes to critical on its standard input, from the built site's
+    # root, so the stylesheet resolves there whatever the page's folder or
+    # the site's baseurl.
+    def extract(site_dir, page, command = critical_command)
+      html = page_for_critical(File.read(File.join(site_dir, page), encoding: "utf-8"))
+      output, errors, status = Open3.capture3(*command, *arguments, stdin_data: html, chdir: site_dir)
       unless status.success?
         raise Error, "critical could not extract CSS from #{page}: #{errors.strip.lines.last(5).join.strip}"
       end
@@ -135,24 +161,103 @@ module Datalog
       path
     end
 
+    # The page as critical should read it: linking the site's stylesheet and
+    # nothing else, as critical 8's --css did. The Google Fonts stylesheet
+    # would bring @font-face rules for the font files a headless browser is
+    # served, and fetching it made each page take over a minute, so its
+    # preload goes with it, as do the hints that open connections to it. The
+    # Content Security Policy goes too: it would refuse the stylesheet the
+    # render engine adds to the page to measure it.
+    UNREAD = 'link[rel~="stylesheet"], link[rel~="preload"][as="style"], link[rel~="preload"][as="font"], ' \
+             'link[rel~="preconnect"], link[rel~="dns-prefetch"], style, noscript'
+
+    def page_for_critical(html)
+      document = Nokogiri::HTML5(html)
+      document.css(UNREAD).each(&:remove)
+      document.css("meta[http-equiv]").each do |meta|
+        meta.remove if meta["http-equiv"].casecmp?("content-security-policy")
+      end
+      head = document.at_css("head") || document.root.prepend_child(document.create_element("head"))
+      head.add_child(document.create_element("link", rel: "stylesheet", href: STYLESHEET))
+      document.to_html
+    end
+
+    # The arguments critical 9's command line takes: the engine, and for the
+    # render engine the viewports, as one list ("1920x1080,375x667").
+    def arguments
+      return ["--engine", "static"] if engine == "static"
+
+      dimensions = Array(settings["dimensions"]).grep(Hash)
+      dimensions = DEFAULT_DIMENSIONS if dimensions.empty?
+      viewports = dimensions.map { |entry| "#{entry['width']}x#{entry['height']}" }
+      ["--engine", "render", "--dimensions", viewports.join(",")]
+    end
+
+    def engine
+      settings.fetch("engine", "render").to_s
+    end
+
+    # The command that runs critical: the one given, else the site's own,
+    # else npx's. The site's own must be critical 9: critical 8 takes other
+    # arguments, and every option this passes would be refused.
     def critical_command
       return @critical if @critical
 
+      check_node
       local = File.join(root, "node_modules", ".bin", Gem.win_platform? ? "critical.cmd" : "critical")
-      File.file?(local) ? [local] : ["npx", "--yes", PACKAGE]
+      return npx_command unless File.file?(local)
+
+      version = installed_version
+      if version && version.segments.first < MAJOR
+        raise Error, "This site's node_modules has critical #{version}, and `datalog critical-css` runs critical " \
+                     "#{MAJOR}, whose command line differs. Update it: npm install --save-dev critical@#{MAJOR}" \
+                     "#{' playwright' if engine == 'render'}"
+      end
+      [local]
     end
 
-    def dimension_arguments
-      dimensions = Array(settings["dimensions"]).grep(Hash)
-      dimensions = DEFAULT_DIMENSIONS if dimensions.empty?
-      dimensions.flat_map { |entry| ["--dimensions", "#{entry['width']}x#{entry['height']}"] }
+    # npx brings Playwright but not the browser it drives, which critical 8's
+    # Puppeteer downloaded as it installed. Playwright fetches it once; a later
+    # run finds it in place.
+    def install_browser
+      @log.call("Making sure Playwright's Chromium is installed for the render engine")
+      output, status = Open3.capture2e("npx", "--yes", PLAYWRIGHT, "install", "chromium")
+      return if status.success?
+
+      raise Error, "Playwright could not install Chromium: #{output.strip.lines.last(5).join.strip}"
     end
 
-    def penthouse_arguments
-      options = settings["penthouse_options"]
-      return [] unless options.is_a?(Hash)
+    def npx_command
+      return ["npx", "--yes", PACKAGE] if engine == "static"
+
+      ["npx", "--yes", "--package", PACKAGE, "--package", PLAYWRIGHT, "critical"]
+    end
+
+    def installed_version
+      manifest = File.join(root, "node_modules", "critical", "package.json")
+      return unless File.file?(manifest)
+
+      Gem::Version.new(JSON.parse(File.read(manifest))["version"].to_s)
+    rescue JSON::ParserError, ArgumentError
+      nil
+    end
+
+    # critical 9 needs Node.js 22.13; an older one fails on an import, with a
+    # message that does not say so.
+    def check_node
+      version = node_version
+      raise Error, "Node.js was not found; critical needs Node.js #{NODE} or later" unless version
+      return if Gem::Version.new(version) >= NODE
+
+      raise Error, "critical needs Node.js #{NODE} or later, and this is Node.js #{version}"
+    end
 
-      options.flat_map { |key, value| ["--penthouse-#{key}", value.to_s] }
+    # "22.13.0", or nil when there is no node to ask.
+    def node_version
+      output, status = Open3.capture2e("node", "--version")
+      status.success? ? output[/\d+\.\d+\.\d+/] : nil
+    rescue SystemCallError
+      nil
     end
 
     def page_file(site_dir, url)