rakit 0.1.8 → 0.1.9

data/lib/rakit/markdown.rb

@@ -1,90 +1,241 @@
 # frozen_string_literal: true
 
-require "kramdown"
+require "pathname"
 require "fileutils"
+require "generated/rakit.markdown_pb"
+require "kramdown"
 
 module Rakit
+  # Modular document amalgamate, disaggregate, validate (009); merge (legacy); generate_pdf.
+  # Document and Section are defined in proto/rakit.markdown.proto (generated in lib/generated/rakit.markdown_pb.rb).
+  # See specs/009-markdown-modular-docs/contracts/ruby-api.md
   module Markdown
-    class << self
-      # @param source_path [String] path to markdown file
-      # @param output_path [String, nil] path for PDF; default same dir, .pdf extension
-      # @return [Hash] { success: Boolean, message: String, exit_code: Integer, stderr: String (optional) }
-      def generate_pdf(source_path, output_path = nil)
-        validated = validate_file_path(source_path)
-        unless validated
-          return { success: false, message: "Source path must exist and be a file", exit_code: 1, stderr: "" }
-        end
-        # Explicit output_path is relative to CWD (or absolute); default is same dir as source, .pdf extension
-        out_path = if output_path.to_s.strip.empty?
-          nil
-        else
-          ::File.expand_path(output_path.to_s.strip)
-        end
-        out_path ||= ::File.join(::File.dirname(validated), ::File.basename(validated, ".*") + ".pdf")
-        out_path = ::File.expand_path(out_path)
+    # Derive slug from section title: lowercase, non-alphanumerics → '-', collapse '-', trim.
+    def self.slug_from_title(title)
+      return "" if title.nil? || title.to_s.strip.empty?
+      s = title.to_s.downcase
+      s = s.gsub(/[^a-z0-9]+/, "-")
+      s = s.gsub(/-+/, "-")
+      s = s.sub(/\A-+/, "").sub(/-+\z/, "")
+      s
+    end
+
+    # Discover .md section files under root_dir, sort by path. Empty → raise.
+    def self.discover_section_paths(root_dir)
+      root = ::File.expand_path(root_dir)
+      raise ArgumentError, "root_dir does not exist: #{root_dir}" unless ::Dir.exist?(root)
+      paths = ::Dir.glob(::File.join(root, "**", "*.md")).sort
+      paths.reject! { |p| ::File.basename(p).start_with?(".") }
+      raise ArgumentError, "no section files under root_dir (at least one .md required): #{root_dir}" if paths.empty?
+      paths
+    end
+
+    def self.load_document(root_dir:)
+      path = root_dir.to_s
+      raise ArgumentError, "root_dir does not exist: #{path}" unless ::File.exist?(path)
+      raise ArgumentError, "root_dir is not a directory: #{path}" unless ::File.directory?(path)
+      full_paths = discover_section_paths(path)
+      root = ::File.expand_path(path)
+      title = ::File.basename(root)
+      sections = full_paths.map do |fp|
+        rel = Pathname.new(fp).relative_path_from(Pathname.new(root)).to_s
+        body = ::File.read(fp, encoding: "UTF-8")
+        base = ::File.basename(fp, ".md")
+        id = slug_from_title(base.sub(/\A\d+-/, "").tr("_", "-"))
+        id = "section" if id.empty?
+        Section.new(id: id, title: base, body: body, source_path: rel, sections: [])
+      end
+      Document.new(title: title, root_dir: path, sections: sections)
+    end
 
-        unless wkhtmltopdf_available?
-          msg = wkhtmltopdf_install_message
-          return { success: false, message: msg, exit_code: 1, stderr: msg }
+    def self.amalgamate(document:, output_path:)
+      raise ArgumentError, "document is required" if document.nil?
+      out = output_path.to_s
+      buf = +""
+      buf << "# #{document.title}\n\n"
+      document.sections.each do |sec|
+        buf << "## #{sec.title}\n\n"
+        buf << sec.body.strip
+        buf << "\n\n" unless sec.body.strip.empty?
+      end
+      ::File.write(out, buf, encoding: "UTF-8")
+      true
+    rescue => e
+      raise e
+    end
+
+    def self.disaggregate(markdown_path:, output_root_dir:)
+      path = markdown_path.to_s
+      raise ArgumentError, "markdown_path does not exist: #{path}" unless ::File.exist?(path)
+      raise ArgumentError, "markdown_path is not a file: #{path}" unless ::File.file?(path)
+      content = ::File.read(path, encoding: "UTF-8")
+      sections = parse_headings_to_sections(content)
+      out_root = ::File.expand_path(output_root_dir.to_s)
+      parent = ::File.dirname(out_root)
+      tmp_dir = parent + "/.rakit_disaggregate_#{Process.pid}_#{rand(1_000_000)}"
+      ::FileUtils.mkdir_p(tmp_dir)
+      begin
+        sections.each_with_index do |sec, i|
+          slug = sec[:slug].to_s.empty? ? "section" : sec[:slug]
+          fn = "#{slug}.md"
+          fn = "#{i}-#{fn}" if sections.size > 1 && slug == "section"
+          out_path = ::File.join(tmp_dir, fn)
+          ::File.write(out_path, sec[:body].to_s.strip + "\n", encoding: "UTF-8")
         end
+        ::FileUtils.rm_rf(out_root) if ::Dir.exist?(out_root)
+        ::FileUtils.mv(tmp_dir, out_root)
+      rescue => e
+        ::FileUtils.rm_rf(tmp_dir) if ::Dir.exist?(tmp_dir)
+        raise e
+      end
+      true
+    end
 
-        temp_html = nil
-        begin
-          md_content = ::File.read(validated, encoding: "UTF-8")
-          html = markdown_to_html(md_content)
-          temp_html = ::File.join(::File.dirname(out_path), ".rakit_md_#{Process.pid}_#{object_id}.html")
-          ::File.write(temp_html, html, encoding: "UTF-8")
-          ok = system("wkhtmltopdf", "-q", temp_html, out_path, out: ::File::NULL, err: ::File::NULL)
-          unless ok
-            ::File.unlink(out_path) if ::File.file?(out_path)
-            return { success: false, message: "wkhtmltopdf failed", exit_code: 1, stderr: "" }
+    # Parse markdown by headings ^#+\s+; return array of { level, title, slug, body }.
+    def self.parse_headings_to_sections(content)
+      lines = content.to_s.lines
+      heading_re = /\A(#+)\s+([^\n]*)\s*\z/
+      sections = []
+      current = { level: 0, title: nil, slug: nil, body: +"" }
+      found_any = false
+      lines.each do |line|
+        m = line.match(heading_re)
+        if m
+          found_any = true
+          level = m[1].length
+          title = m[2].strip
+          if current[:title]
+            current[:body] = current[:body].sub(/\n+\z/, "")
+            sections << { level: current[:level], title: current[:title], slug: slug_from_title(current[:title]), body: current[:body] }
           end
-          { success: true, message: "", exit_code: 0, stderr: "" }
-        rescue => e
-          ::File.unlink(out_path) if out_path && ::File.file?(out_path)
-          { success: false, message: e.message, exit_code: 1, stderr: "" }
-        ensure
-          ::File.unlink(temp_html) if temp_html && ::File.file?(temp_html)
+          current = { level: level, title: title, slug: slug_from_title(title), body: +"" }
+        else
+          current[:body] << line
         end
       end
+      current[:body] = current[:body].sub(/\n+\z/, "")
+      if current[:title] || !found_any
+        sections << { level: current[:level], title: current[:title] || "Section", slug: (current[:title] ? slug_from_title(current[:title]) : "section"), body: current[:body] }
+      end
+      sections = [{ level: 0, title: "Section", slug: "section", body: content.to_s.strip }] if sections.empty?
+      sections
+    end
 
-      # @param source_dir [String] directory to collect .md files from
-      # @param target_path [String] path to output markdown file
-      # @param create_directories [Boolean]
-      # @return [Hash] { success: Boolean, message: String, exit_code: Integer }
-      def amalgamate(source_dir, target_path, create_directories: false)
-        validated_dir = validate_dir_path(source_dir)
-        unless validated_dir
-          return { success: false, message: "Source directory must exist and be a directory", exit_code: 1 }
-        end
-        target_norm = normalize_path(target_path)
-        unless target_norm
-          return { success: false, message: "Target path is required", exit_code: 1 }
-        end
-        unless target_outside_source?(validated_dir, target_norm)
-          return { success: false, message: "Target path must be outside source directory", exit_code: 1 }
+    class << self
+      attr_accessor :validation_failures
+    end
+    self.validation_failures = []
+
+    def self.validate(root_dir:)
+      self.validation_failures = []
+      doc = load_document(root_dir: root_dir)
+      ids = []
+      doc.sections.each do |sec|
+        ids << sec.id
+      end
+      seen = {}
+      ids.each do |id|
+        if seen[id]
+          self.validation_failures << "Duplicate section id: #{id}"
+        else
+          seen[id] = true
         end
-        parent = ::File.dirname(target_norm)
-        unless ::File.directory?(parent)
-          if create_directories
-            ::FileUtils.mkdir_p(parent)
-          else
-            return { success: false, message: "Parent directory does not exist; use create_directories: true", exit_code: 1 }
-          end
+      end
+      return false if validation_failures.any?
+      true
+    rescue ArgumentError => e
+      self.validation_failures = [e.message]
+      false
+    end
+
+    # ---- Legacy API: merge (concatenate .md files) and generate_pdf ----
+
+    # Merge: collect all .md under source_dir (sorted by path), write concatenated content to target_path.
+    # Target must be outside source_dir. Returns { success:, message:, exit_code: }.
+    # @param source_dir [String] directory to collect .md files from
+    # @param target_path [String] path to output markdown file
+    # @param create_directories [Boolean] if true, create parent dirs of target_path
+    def self.merge(source_dir, target_path, create_directories: false)
+      validated_dir = validate_dir_path(source_dir)
+      unless validated_dir
+        return { success: false, message: "Source directory must exist and be a directory", exit_code: 1 }
+      end
+      target_norm = normalize_path(target_path)
+      unless target_norm
+        return { success: false, message: "Target path is required", exit_code: 1 }
+      end
+      unless target_outside_source?(validated_dir, target_norm)
+        return { success: false, message: "Target path must be outside source directory", exit_code: 1 }
+      end
+      parent = ::File.dirname(target_norm)
+      unless ::File.directory?(parent)
+        if create_directories
+          ::FileUtils.mkdir_p(parent)
+        else
+          return { success: false, message: "Parent directory does not exist; use create_directories: true", exit_code: 1 }
         end
-        begin
-          content = amalgamate_collect(validated_dir)
-          ::File.write(target_norm, content, encoding: "UTF-8")
-          { success: true, message: "", exit_code: 0 }
-        rescue => e
-          ::File.unlink(target_norm) if ::File.file?(target_norm)
-          { success: false, message: e.message, exit_code: 1 }
+      end
+      begin
+        content = merge_collect(validated_dir)
+        ::File.write(target_norm, content, encoding: "UTF-8")
+        { success: true, message: "", exit_code: 0 }
+      rescue => e
+        ::File.unlink(target_norm) if ::File.file?(target_norm)
+        { success: false, message: e.message, exit_code: 1 }
+      end
+    end
+
+    # Generate PDF from a markdown file (requires weasyprint or wkhtmltopdf on PATH; on Mac/Linux weasyprint is preferred).
+    # @param source_path [String] path to markdown file
+    # @param output_path [String, nil] path for PDF; default same dir, .pdf extension
+    # @return [Hash] { success:, message:, exit_code:, stderr: }
+    def self.generate_pdf(source_path, output_path = nil)
+      validated = validate_file_path(source_path)
+      unless validated
+        return { success: false, message: "Source path must exist and be a file", exit_code: 1, stderr: "" }
+      end
+      out_path = if output_path.to_s.strip.empty?
+        nil
+      else
+        ::File.expand_path(output_path.to_s.strip)
+      end
+      out_path ||= ::File.join(::File.dirname(validated), ::File.basename(validated, ".*") + ".pdf")
+      out_path = ::File.expand_path(out_path)
+
+      engine = pdf_engine_available?
+      unless engine
+        msg = pdf_engine_install_message
+        return { success: false, message: msg, exit_code: 1, stderr: msg }
+      end
+
+      temp_html = nil
+      begin
+        md_content = ::File.read(validated, encoding: "UTF-8")
+        html = wrap_html_for_pdf(markdown_to_html(md_content))
+        temp_html = ::File.join(::File.dirname(out_path), ".rakit_md_#{Process.pid}_#{object_id}.html")
+        ::File.write(temp_html, html, encoding: "UTF-8")
+        ok = run_pdf_engine(engine, temp_html, out_path)
+        unless ok
+          ::File.unlink(out_path) if ::File.file?(out_path)
+          return { success: false, message: "#{engine} failed", exit_code: 1, stderr: "" }
         end
+        { success: true, message: "", exit_code: 0, stderr: "" }
+      rescue => e
+        ::File.unlink(out_path) if out_path && ::File.file?(out_path)
+        { success: false, message: e.message, exit_code: 1, stderr: "" }
+      ensure
+        ::File.unlink(temp_html) if temp_html && ::File.file?(temp_html)
       end
+    end
+
+    # True if a PDF engine (weasyprint or wkhtmltopdf) is available for generate_pdf.
+    def self.pdf_available?
+      send(:pdf_engine_available?).nil? ? false : true
+    end
 
+    class << self
       private
 
-      # T004: Normalize path; return nil if nil/empty after strip.
       def normalize_path(path, base_dir = nil)
         return nil if path.nil?
         s = path.to_s.strip
@@ -92,7 +243,6 @@ module Rakit
         base_dir ? ::File.expand_path(s, base_dir) : ::File.expand_path(s)
       end
 
-      # T004: Validate path exists and is a file. Return expanded path or nil.
       def validate_file_path(path)
         norm = normalize_path(path)
         return nil unless norm
@@ -100,7 +250,6 @@ module Rakit
         norm
       end
 
-      # T004: Validate path exists and is a directory. Return expanded path or nil.
       def validate_dir_path(path)
         norm = normalize_path(path)
         return nil unless norm
@@ -108,7 +257,6 @@ module Rakit
         norm
       end
 
-      # T005: Target is outside source_dir (not equal, not under). Both should be normalized.
       def target_outside_source?(source_dir, target_path)
         src = source_dir.to_s.gsub(::File::SEPARATOR, "/").chomp("/")
         target = ::File.expand_path(target_path).to_s.gsub(::File::SEPARATOR, "/")
@@ -119,38 +267,82 @@ module Rakit
         true
       end
 
-      # T006: True if wkhtmltopdf is available.
+      def mac_or_linux?
+        RUBY_PLATFORM.include?("darwin") || RUBY_PLATFORM.include?("linux")
+      end
+
       def wkhtmltopdf_available?
-        out = `wkhtmltopdf --version 2>&1`
+        `wkhtmltopdf --version 2>&1`
+        $?.success?
+      end
+
+      def weasyprint_available?
+        `weasyprint --version 2>&1`
         $?.success?
       end
 
-      # T006: Platform-specific install message for wkhtmltopdf.
-      def wkhtmltopdf_install_message
+      # Returns :weasyprint or :wkhtmltopdf if available. On Mac/Linux prefers weasyprint.
+      def pdf_engine_available?
+        if mac_or_linux?
+          return :weasyprint if weasyprint_available?
+          return :wkhtmltopdf if wkhtmltopdf_available?
+        else
+          return :wkhtmltopdf if wkhtmltopdf_available?
+          return :weasyprint if weasyprint_available?
+        end
+        nil
+      end
+
+      def pdf_engine_install_message
         if ::Gem.win_platform?
           "Install wkhtmltopdf: choco install wkhtmltopdf"
-        elsif ::File.exist?("/usr/bin/sw_vers") || RUBY_PLATFORM.include?("darwin")
-          "Install wkhtmltopdf: brew install wkhtmltopdf"
+        elsif mac_or_linux?
+          "Install weasyprint: brew install weasyprint (macOS) or apt install weasyprint (Debian/Ubuntu). Alternatively: wkhtmltopdf."
+        else
+          "Install wkhtmltopdf or weasyprint for PDF generation."
+        end
+      end
+
+      def run_pdf_engine(engine, html_path, pdf_path)
+        case engine
+        when :weasyprint
+          system("weasyprint", "-e", "UTF-8", html_path, pdf_path, out: ::File::NULL, err: ::File::NULL)
+        when :wkhtmltopdf
+          system("wkhtmltopdf", "-q", "--encoding", "UTF-8", html_path, pdf_path, out: ::File::NULL, err: ::File::NULL)
         else
-          "Install wkhtmltopdf: e.g. apt install wkhtmltopdf or yum install wkhtmltopdf"
+          false
         end
       end
 
-      # T007: Convert markdown string to HTML. Empty input -> minimal HTML.
       def markdown_to_html(md_string)
         return "" if md_string.nil? || md_string.to_s.strip.empty?
         Kramdown::Document.new(md_string.to_s).to_html
       end
 
-      # T008: Collect all **/*.md under source_dir, sort by path, concatenate with separator. Return string.
-      AMALGAM_SEPARATOR = "\n\n"
+      def wrap_html_for_pdf(html_fragment)
+        <<~HTML
+          <!DOCTYPE html>
+          <html>
+          <head>
+          <meta charset="UTF-8">
+          <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+          <style>body { font-size: 200%; }</style>
+          </head>
+          <body>
+          #{html_fragment}
+          </body>
+          </html>
+        HTML
+      end
+
+      MERGE_SEPARATOR = "\n\n"
 
-      def amalgamate_collect(source_dir)
+      def merge_collect(source_dir)
         norm_dir = ::File.expand_path(source_dir)
         pattern = ::File.join(norm_dir, "**", "*.md")
         paths = ::Dir.glob(pattern).select { |p| ::File.file?(p) }.sort
         return "" if paths.empty?
-        paths.map { |p| ::File.read(p, encoding: "UTF-8") }.join(AMALGAM_SEPARATOR)
+        paths.map { |p| ::File.read(p, encoding: "UTF-8") }.join(MERGE_SEPARATOR)
       end
     end
   end

data/lib/rakit/shell.rb

@@ -2,7 +2,7 @@
 
 require "open3"
 require "timeout"
-require "generated/shell_pb"
+require "generated/rakit.shell_pb"
 
 module Rakit
   module Shell

data/lib/rakit/static_web_server.rb

@@ -1,28 +1,42 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "generated/static_web_server_pb"
+require "generated/rakit.static_web_server_pb"
 
 module Rakit
-  # Publish static sites into a configurable root, regenerate a root index, and control a local HTTP server (start/stop/running).
-  # CLI: +rakit static-web-server+ (start|stop|running|publish). See contracts/ruby-api.md and quickstart in specs/003-static-web-server/quickstart.md.
+  # Publish static sites into a configurable root (~/.rakit/wwwroot), regenerate a root index, and control a local HTTP server (start/stop/running).
+  # Host and port are configurable (host default 127.0.0.1, port 5099) and returned regardless of server state for URL building.
+  # CLI: +rakit static-web-server+ (start|stop|running|publish|view). See specs/003-static-web-server/contracts/ruby-api.md and specs/007-wwwroot-docs-hugo-view/contracts/ruby-api.md.
   module StaticWebServer
     SITE_NAME_REGEX = /\A[a-z0-9\-]+\z/.freeze
 
     class << self
-      # @return [String] Static root directory (default ~/.rakit/www_root). Used by publish and server lifecycle.
+      # @return [String] Static root directory (default ~/.rakit/wwwroot). Used by publish and server lifecycle.
       attr_accessor :root
-      # @return [Integer] Default port for start (default 5099). Used when no override passed to start.
+      # @return [String] Host for building URLs (default 127.0.0.1). Returned regardless of server running state.
+      attr_accessor :host
+      # @return [Integer] Default port for start (default 5099). Used when no override passed to start; returned regardless of server running state.
       attr_accessor :port
     end
 
-    self.root = ::File.expand_path("~/.rakit/www_root")
+    self.root = ::File.expand_path("~/.rakit/wwwroot")
+    self.host = "127.0.0.1"
     self.port = 5099
 
     # T005: Validate site name; raise ArgumentError before any filesystem write.
+    # Single segment (e.g. "mysite") or multi-segment path (e.g. "louparslow/rakit"); each segment must match SITE_NAME_REGEX.
     def self.validate_site_name!(site_name)
-      return if site_name.is_a?(String) && site_name.match?(SITE_NAME_REGEX)
-      raise ArgumentError, "site_name must be lowercase alphanumeric and dashes only (e.g. my-site); got: #{site_name.inspect}"
+      validate_site_path!(site_name)
+    end
+
+    def self.validate_site_path!(site_name)
+      return if site_name.nil? || site_name.to_s.empty?
+      site_name.to_s.split(::File::SEPARATOR).each do |seg|
+        next if seg.empty?
+        unless seg.match?(SITE_NAME_REGEX)
+          raise ArgumentError, "site_name segment must be lowercase alphanumeric and dashes only (e.g. my-site); got: #{seg.inspect}"
+        end
+      end
     end
 
     # T006: PID file path for start/stop/running (research: ~/.rakit/static_web_server.pid).
@@ -49,26 +63,27 @@ module Rakit
     end
 
     # Publish static content from source_directory to root/site_name (atomic copy), then regenerate root index.
-    # @param site_name [String] Must match \\A[a-z0-9\-]+\\z (lowercase, alphanumeric, dashes only).
+    # @param site_name [String] Single segment (e.g. "mysite") or path (e.g. "louparslow/rakit"); each segment must match \\A[a-z0-9\-]+\\z.
     # @param source_directory [String] Existing directory path; contents are copied (no traversal outside allowed paths).
     # @return [true] on success.
     # @raise [ArgumentError] for invalid site_name, missing/invalid source_directory, or root not writable.
     def self.publish(site_name, source_directory)
-      validate_site_name!(site_name)
+      validate_site_path!(site_name)
       src = ::File.expand_path(source_directory)
       raise ArgumentError, "source_directory does not exist: #{source_directory}" unless ::File.exist?(src)
       raise ArgumentError, "source_directory is not a directory: #{source_directory}" unless ::File.directory?(src)
 
       ensure_root
-      # Check root is writable before we do any copy (T015 / edge case).
       unless ::File.writable?(root)
         raise ArgumentError, "root directory is not writable: #{root}"
       end
 
       target = ::File.join(root, site_name)
-      temp = ::File.join(root, ".tmp_#{site_name}_#{Process.pid}_#{rand(1_000_000)}")
+      temp_name = ".tmp_#{site_name.to_s.gsub(::File::SEPARATOR, '_')}_#{Process.pid}_#{rand(1_000_000)}"
+      temp = ::File.join(root, temp_name)
       FileUtils.mkdir_p(temp)
       FileUtils.cp_r(::File.join(src, "."), temp)
+      FileUtils.mkdir_p(::File.dirname(target))
       FileUtils.rm_rf(target)
       FileUtils.mv(temp, target)
       regenerate_root_index
@@ -95,6 +110,7 @@ module Rakit
     def self.start(options = {})
       return true if running?
       ensure_root
+      regenerate_root_index  # so root / (Sites page) lists current nested sites
       p = options[:port] || port
       raise "port #{p} is already in use; change port or stop the other process" if port_in_use?(p)
       bin = server_binary
@@ -109,19 +125,23 @@ module Rakit
 
     STOP_TIMEOUT = 5
 
-    # Gracefully terminate server process; remove PID file. Fail-fast if not running.
-    # @return [true] if stopped.
-    # @raise [RuntimeError] if server was not running (no PID file or process not found).
+    # Gracefully terminate server process; remove PID file. Idempotent: if not running (no PID file or process not found), no-op and return true.
+    # @return [true] if stopped or already not running.
     def self.stop
       path = pid_file_path
-      raise "server is not running (no PID file at #{path})" unless ::File.file?(path)
+      unless ::File.file?(path)
+        return true  # already not running
+      end
       pid = ::File.read(path).strip.to_i
-      raise "server is not running (invalid PID in #{path})" if pid <= 0
+      if pid <= 0
+        ::File.delete(path) rescue nil
+        return true
+      end
       begin
         Process.getpgid(pid)
       rescue Errno::ESRCH
-        ::File.delete(path)
-        raise "server is not running (process #{pid} not found)"
+        ::File.delete(path) rescue nil
+        return true  # process already gone; treat as stopped
       end
       Process.kill(:TERM, pid)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + STOP_TIMEOUT
@@ -145,17 +165,49 @@ module Rakit
       true
     end
 
-    # T017: Write root/index.html listing all site subdirectories alphabetically with links.
+    # Open a path on the static server in the default browser. Ensures server is running (starts if not), builds URL, launches browser.
+    # @param relative_path [String] URL path (e.g. "/louparslow/rakit/" or "louparslow/rakit"); normalized to one leading slash.
+    # @return [true] on success.
+    # @raise [RuntimeError] if browser cannot be launched (e.g. headless), with message e.g. "Could not launch browser; display required?"
+    def self.view(relative_path)
+      start unless running?
+      path = relative_path.to_s.strip
+      path = "/#{path}" unless path.empty? || path.start_with?("/")
+      path = "/" if path.empty?
+      url = "http://#{host}:#{port}#{path}"
+      $stdout.puts "Opening #{url}"
+      launch_browser(url)
+      true
+    end
+
+    # T017: Write root/index.html listing all subdirectories that have index.html (or index.xml) with links.
     def self.regenerate_root_index
-      entries = Dir.entries(root).sort.select do |e|
-        e != "." && e != ".." && e != "index.html" && !e.start_with?(".") && ::File.directory?(::File.join(root, e))
-      end
+      paths = []
+      _collect_index_paths(root, "", paths)
+      paths.sort!
       html = ["<!DOCTYPE html>", "<html><head><meta charset=\"utf-8\"><title>Published sites</title></head><body>", "<h1>Published sites</h1>", "<ul>"]
-      entries.each { |name| html << "<li><a href=\"/#{name}/\">#{name}</a></li>" }
+      paths.each do |rel|
+        name = rel.chomp("/").split("/").last || rel
+        html << "<li><a href=\"/#{rel}\">#{name} (#{rel})</a></li>"
+      end
       html << "</ul></body></html>"
       ::File.write(::File.join(root, "index.html"), html.join("\n"))
     end
 
+    # Recursively find relative paths under dir (relative to root) that contain index.html or index.xml.
+    def self._collect_index_paths(dir, rel, out)
+      Dir.entries(dir).sort.each do |e|
+        next if e == "." || e == ".." || e.start_with?(".")
+        full = ::File.join(dir, e)
+        next unless ::File.directory?(full)
+        sub_rel = rel.empty? ? e : "#{rel}/#{e}"
+        index_html = ::File.join(full, "index.html")
+        index_xml = ::File.join(full, "index.xml")
+        out << "#{sub_rel}/" if ::File.file?(index_html) || ::File.file?(index_xml)
+        _collect_index_paths(full, sub_rel, out)
+      end
+    end
+
     class << self
       private
 
@@ -178,6 +230,20 @@ module Rakit
       rescue Errno::EADDRINUSE
         true
       end
+
+      def launch_browser(url)
+        cmd = case ::RbConfig::CONFIG["host_os"]
+              when /darwin|mac os/i
+                ["open", url]
+              when /mswin|mingw|windows/i
+                ["cmd", "/c", "start", "", url]
+              else
+                ["xdg-open", url]
+              end
+        system(*cmd, out: ::File::NULL, err: ::File::NULL)
+        return true if $?.success?
+        raise "Could not launch browser; display required?"
+      end
     end
   end
 end

data/lib/rakit.rb

@@ -25,6 +25,9 @@ require_relative "rakit/protobuf"
 # Defer loading so rake tasks that don't need Shell (e.g. clobber) work without google-protobuf.
 autoload :Shell, "rakit/shell"
 require_relative "rakit/static_web_server"
+require_relative "rakit/docfx"
+require_relative "rakit/hugo"
+require_relative "rakit/markdown"
 require_relative "rakit/word_count"
 require_relative "rakit/word_cloud"
 require_relative "rakit/file"