wytch 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 662c7632994e850e71fce70842f153b11d7e56f8877df6156094c070213a68a6
-  data.tar.gz: 546b863eb417cd7ada91d725a1def5662aae4182e9c53762ab98758c574f103b
+  metadata.gz: 0437b28a3f15b9b8c8b038d704007549d041d037a06423bdc5e7e707d2f0406a
+  data.tar.gz: d3c6f678b5146c515096c32a0ef61bef367b6af875df257455699db790019223
 SHA512:
-  metadata.gz: 9a8a7bc87f19981aa54f33132f5cb5e9adf7799c380187f2b5db8a0756feab7f2c6e158eeaeeaef2d6bccb95188f8ff5e561e66b5bf4c8dda70df56859f8c137
-  data.tar.gz: ac6aae6cf98f82c74dd1b11ba1d814d03cbbb9b9ab85c6c2f738fc300632ff99602c571e436554e58b11aa7d47fb94c99f9532e41eb77116ccd7fe37a9a56dca
+  metadata.gz: 1c9b98d2db33c4b4b1ae078ce992d1d8ff7965b5ace303cfa8f49148c52cd0f4564c1d36b2ddad6a46e548e27914bc70b8488aaf5ad51a009a084a037c710a1a
+  data.tar.gz: cbfefe11f6b4b6a74534cb150b136f90d370f71a11e8be5ca3f21e926292272233c1a723d96b11fc1b374239257205c3d71c0c3bcae8cb8bda2f5659585add88

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.4.0] - 2025-12-7
+
+- Move sitemap generation to Wytch core (`Wytch::SitemapView` and `Wytch::SitemapHelper`)
+
+## [0.3.0] - 2025-12-7
+
+- Add YARD documentation to all classes and methods
+- Add UTF-8 charset meta tag to generated site layouts
+- Fix index page building to `build/index.html` instead of `build/index/index.html`
+- Update CLI output to reflect single-command build process
+
+## [0.2.0] - 2025-12-7
+
+- Add Vite integration for asset pipeline (CSS, ReScript)
+- Add blog scaffolding with posts, sitemap, and Atom feed
+- Add Layout component for consistent page structure
+- `wytch build` now automatically runs `npm run build` for assets
+- Add static file serving from `public/` directory
+- Add hot-reloading for site code and content during development
+- Add documentation (README usage guide)
+
 ## [0.1.0] - 2025-10-29
 
 - Initial release

data/lib/wytch/builder.rb

@@ -3,9 +3,29 @@
 require "fileutils"
 
 module Wytch
+  # Builds the static site by rendering all pages to the output directory.
+  #
+  # The Builder is responsible for the production build process:
+  # 1. Loading site configuration and content
+  # 2. Rendering each page to HTML
+  # 3. Copying static files from public/
+  # 4. Integrating Vite-built assets
+  #
+  # @example Building via CLI
+  #   $ wytch build
+  #
+  # @example Building programmatically
+  #   Wytch::Builder.new.build
   class Builder
+    # @return [String] the output directory for built files
     OUTPUT_DIR = "build"
 
+    # Builds the entire site.
+    #
+    # Sets RACK_ENV to "production", loads the site configuration,
+    # renders all pages to HTML files, and copies static assets.
+    #
+    # @return [void]
     def build
       ENV["RACK_ENV"] = "production"
       Site.load!
@@ -31,12 +51,19 @@ module Wytch
 
     private
 
+    # Copies files from public/ to the output directory.
+    #
+    # @return [void]
     def copy_public_files
       return unless Dir.exist?("public")
 
       FileUtils.cp_r "public/.", OUTPUT_DIR, verbose: true
     end
 
+    # Reports on Vite assets in the output directory.
+    # Vite builds directly to build/assets, so no copying is needed.
+    #
+    # @return [void]
     def copy_vite_assets
       vite_output = File.join(OUTPUT_DIR, "assets")
       return unless Dir.exist?(vite_output)

data/lib/wytch/cli.rb

@@ -3,15 +3,36 @@
 require "thor"
 
 module Wytch
+  # Command-line interface for Wytch.
+  #
+  # Provides commands for creating, developing, and building Wytch sites.
+  #
+  # @example
+  #   $ wytch new my-site     # Create a new site
+  #   $ wytch server          # Start development server
+  #   $ wytch build           # Build for production
   class CLI < Thor
     include Thor::Actions
 
+    # Returns the path to template files used by the generator.
+    #
+    # @return [String] path to templates directory
     def self.source_root
       File.expand_path("templates", __dir__)
     end
 
     desc "new NAME", "Create a new Wytch site"
     method_option :local, type: :boolean, default: false, desc: "Use local Wytch gem for development"
+    # Creates a new Wytch site with the given name.
+    #
+    # Generates a complete site structure including:
+    # - Configuration files (Gemfile, config.rb, package.json, etc.)
+    # - Content directory with sample pages
+    # - Source directory with views and layouts
+    # - Asset pipeline setup (Vite, ReScript, Tailwind)
+    #
+    # @param name [String] the name/directory for the new site
+    # @return [void]
     def new(name)
       @local_wytch_path = File.expand_path("../..", __dir__) if options[:local]
 
@@ -50,8 +71,6 @@ module Wytch
       template("src/site/home_view.rb.tt", "#{name}/src/#{@site_name}/home_view.rb")
       template("src/site/post_view.rb.tt", "#{name}/src/#{@site_name}/post_view.rb")
       template("src/site/post_helpers.rb.tt", "#{name}/src/#{@site_name}/post_helpers.rb")
-      template("src/site/sitemap_view.rb.tt", "#{name}/src/#{@site_name}/sitemap_view.rb")
-      template("src/site/sitemap_helper.rb.tt", "#{name}/src/#{@site_name}/sitemap_helper.rb")
       template("src/site/feed_view.rb.tt", "#{name}/src/#{@site_name}/feed_view.rb")
       template("src/site/feed_helper.rb.tt", "#{name}/src/#{@site_name}/feed_helper.rb")
 
@@ -68,18 +87,26 @@ module Wytch
       say "  npm run dev       # Start Vite dev server (Terminal 1)"
       say "  wytch server      # Start Wytch dev server (Terminal 2)"
       say "\nTo build for production:"
-      say "  npm run build     # Build assets with Vite"
-      say "  wytch build       # Build static site"
+      say "  wytch build       # Build assets and static site to build/"
     end
 
     desc "server", "Start a development server"
     method_option :port, type: :numeric, default: 6969, aliases: "-p", desc: "Port to run the server on"
     method_option :host, type: :string, default: "localhost", aliases: "-h", desc: "Host to bind the server to"
+    # Starts the development server with hot reloading.
+    #
+    # @return [void]
     def server
       Server.new(options).start
     end
 
     desc "build", "Build the static site"
+    # Builds the site for production.
+    #
+    # First runs `npm run build` to compile assets with Vite,
+    # then renders all pages to static HTML in the build/ directory.
+    #
+    # @return [void]
     def build
       system("npm run build") || abort("Asset build failed")
       Builder.new.build
@@ -87,6 +114,10 @@ module Wytch
 
     private
 
+    # Converts a snake_case name to PascalCase.
+    #
+    # @param name [String] the name to classify
+    # @return [String] the PascalCase version
     def classify(name)
       name.split("_").map(&:capitalize).join
     end

data/lib/wytch/content_loader.rb

@@ -1,7 +1,21 @@
 # frozen_string_literal: true
 
 module Wytch
+  # Discovers and loads content files into Page objects.
+  #
+  # The ContentLoader scans the content directory for Ruby files and
+  # instantiates Page objects for each one. It uses the configured
+  # page_class from the Site.
+  #
+  # @see Wytch::Site#content_dir
+  # @see Wytch::Site#page_class
   class ContentLoader
+    # Loads all content files and returns a hash of pages.
+    #
+    # Scans the content directory recursively for .rb files,
+    # creates a Page instance for each, and returns them keyed by path.
+    #
+    # @return [Hash{String => Page}] pages keyed by their URL path
     def load_content
       pages = {}
 
@@ -15,14 +29,24 @@ module Wytch
 
     private
 
+    # Creates a Page instance from a content file.
+    #
+    # @param file_path [String] path to the content file, relative to content_dir
+    # @return [Page] the loaded page
     def load_page(file_path)
       page_class.new(file_path:)
     end
 
+    # Returns the configured page class.
+    #
+    # @return [Class] the page class to instantiate
     def page_class
       Object.const_get(Wytch.site.page_class)
     end
 
+    # Returns the content directory path.
+    #
+    # @return [String] the content directory
     def content_dir
       Wytch.site.content_dir
     end

data/lib/wytch/once.rb

@@ -1,12 +1,32 @@
 # frozen_string_literal: true
 
 module Wytch
+  # A thread-safe utility for executing a block exactly once.
+  #
+  # Once ensures that a given block of code is executed only one time,
+  # even when called from multiple threads. After the first execution,
+  # subsequent calls are no-ops.
+  #
+  # @example
+  #   setup = Once.new { puts "Initializing..." }
+  #   setup.call  # prints "Initializing..."
+  #   setup.call  # does nothing
+  #   setup.call  # does nothing
   class Once
+    # Creates a new Once instance with the given block.
+    #
+    # @yield the block to execute once
     def initialize(&block)
       @block = block
       @mutex = Mutex.new
     end
 
+    # Executes the block if it hasn't been executed yet.
+    #
+    # Thread-safe: if multiple threads call this simultaneously,
+    # only one will execute the block.
+    #
+    # @return [void]
     def call
       @mutex&.synchronize do
         return unless @mutex

data/lib/wytch/page.rb

@@ -1,7 +1,33 @@
 # frozen_string_literal: true
 
 module Wytch
+  # Represents a single page in a Wytch site.
+  #
+  # Pages are defined by Ruby content files in the content directory. Each content
+  # file is evaluated in the context of a Page instance, allowing it to set metadata
+  # and configure the view class.
+  #
+  # @example A typical content file (content/about.rb)
+  #   view MySite::AboutView
+  #   add MySite::PageHelpers
+  #
+  #   @metadata[:title] = "About Us"
+  #   @metadata[:description] = "Learn more about our company"
+  #
+  # @example Accessing page data in a view
+  #   class MySite::AboutView < Phlex::HTML
+  #     def initialize(page)
+  #       @page = page
+  #     end
+  #
+  #     def view_template
+  #       h1 { @page.metadata[:title] }
+  #     end
+  #   end
   class Page
+    # Creates a new page by loading and evaluating a content file.
+    #
+    # @param file_path [String] path to the content file, relative to the content directory
     def initialize(file_path:)
       @file_path = file_path
       @metadata = {}
@@ -12,12 +38,19 @@ module Wytch
       instance_eval File.read(source_path), source_path
     end
 
+    # @return [Hash] arbitrary metadata set by the content file
     attr_reader :metadata
 
+    # Renders the page using its configured view class.
+    #
+    # @return [String] the rendered HTML
     def render
       @view_class.new(self).call
     end
 
+    # Returns the URL path for this page.
+    #
+    # @return [String] the URL path (e.g., "/" for index, "/about" for about.rb)
     def path
       if virtual_path == "index"
         "/"
@@ -26,34 +59,76 @@ module Wytch
       end
     end
 
+    # Returns the virtual path derived from the file path.
+    #
+    # @return [String] the path without directory prefix or .rb suffix
     def virtual_path
       @file_path.delete_prefix("#{Wytch.site.content_dir}/").delete_suffix(".rb")
     end
 
+    # Returns the output file path for the built page.
+    #
+    # @return [String] the build path (e.g., "about/index.html")
     def build_path
-      "#{virtual_path}/index.html"
+      if virtual_path == "index"
+        "index.html"
+      else
+        "#{virtual_path}/index.html"
+      end
     end
 
+    # Extends this page instance with a helper module.
+    # Called from content files to add helper methods.
+    #
+    # @param helper_module [Module] the module to extend this page with
+    # @return [void]
+    #
+    # @example
+    #   add MySite::PostHelpers
     def add(helper_module)
       extend helper_module
     end
 
+    # Sets the view class for rendering this page.
+    # Called from content files to specify which Phlex view to use.
+    #
+    # @param view_class [Class] a Phlex view class that accepts the page in its initializer
+    # @return [void]
+    #
+    # @example
+    #   view MySite::PostView
     def view(view_class)
       @view_class = view_class
     end
 
+    # Whether this page should be included in the sitemap.
+    # Override in subclasses to exclude pages.
+    #
+    # @return [Boolean] true by default
     def include_in_sitemap?
       true
     end
 
+    # The last modification date for sitemap generation.
+    # Override in subclasses to provide actual dates.
+    #
+    # @return [Date, Time, nil] the last modified date, or nil if unknown
     def last_modified
       nil
     end
 
+    # The change frequency hint for sitemap generation.
+    # Override in subclasses to provide hints like "daily", "weekly", etc.
+    #
+    # @return [String, nil] the change frequency, or nil if unknown
     def change_frequency
       nil
     end
 
+    # The priority hint for sitemap generation.
+    # Override in subclasses to provide a value between 0.0 and 1.0.
+    #
+    # @return [Float, nil] the priority, or nil if unknown
     def priority
       nil
     end

data/lib/wytch/reload_coordinator.rb

@@ -4,9 +4,21 @@ require "concurrent/atomic/read_write_lock"
 require "listen"
 
 module Wytch
+  # Coordinates hot reloading of site code and content during development.
+  #
+  # The ReloadCoordinator watches the site code and content directories for
+  # changes using the Listen gem. When files change, it marks the appropriate
+  # component as dirty and reloads it on the next request.
+  #
+  # It uses a read-write lock to ensure thread-safe reloading while allowing
+  # concurrent reads during page rendering.
+  #
+  # @see Wytch::SiteCodeLoaderMiddleware
   class ReloadCoordinator
+    # @return [Concurrent::ReadWriteLock] lock for coordinating reloads
     attr_reader :reload_lock
 
+    # Creates a new ReloadCoordinator and sets up file watchers.
     def initialize
       @reload_lock = Concurrent::ReadWriteLock.new
 
@@ -26,6 +38,13 @@ module Wytch
       end
     end
 
+    # Reloads site code and/or content if changes have been detected.
+    #
+    # Starts file listeners on first call. If site code has changed, reloads
+    # both site code (via Zeitwerk) and content. If only content has changed,
+    # reloads just the content.
+    #
+    # @return [void]
     def reload!
       @start_site_code_listener&.call
       @start_content_listener&.call

data/lib/wytch/server.rb

@@ -3,13 +3,38 @@
 require "rack"
 
 module Wytch
+  # Development server for Wytch sites.
+  #
+  # The Server provides a local development environment with:
+  # - Hot reloading of site code and content
+  # - Static file serving from public/
+  # - Page rendering on each request
+  #
+  # @example Starting via CLI
+  #   $ wytch server
+  #   $ wytch server --port 3000 --host 0.0.0.0
+  #
+  # @example Starting programmatically
+  #   Wytch::Server.new(port: 3000).start
   class Server
+    # @return [Hash] server options (port, host)
     attr_reader :options
 
+    # Creates a new server instance.
+    #
+    # @param options [Hash] server options
+    # @option options [Integer] :port the port to listen on (default: 6969)
+    # @option options [String] :host the host to bind to (default: "localhost")
     def initialize(options = {})
       @options = options
     end
 
+    # Starts the development server.
+    #
+    # Loads the site configuration, starts file watchers for hot reloading,
+    # and begins serving requests. This method blocks until the server is stopped.
+    #
+    # @return [void]
     def start
       ENV["RACK_ENV"] = "development"
       Site.load!
@@ -30,6 +55,9 @@ module Wytch
 
     private
 
+    # Builds the Rack application stack.
+    #
+    # @return [Rack::Builder] the configured Rack app
     def app
       base_app = lambda { |env|
         path = env["PATH_INFO"]

data/lib/wytch/site.rb

@@ -1,7 +1,24 @@
 # frozen_string_literal: true
 
 module Wytch
+  # Holds the configuration and state for a Wytch site.
+  #
+  # The Site class is the central configuration point for Wytch. It manages
+  # the content directory, site code loading, page class, and the collection
+  # of all pages.
+  #
+  # @example Configuring a site in config.rb
+  #   Wytch.configure do |site|
+  #     site.page_class = "MySite::Page"
+  #     site.base_url = "https://example.com"
+  #     site.content_dir = "pages"  # default is "content"
+  #   end
+  #
+  # @see Wytch.configure
   class Site
+    # Loads the site configuration from config.rb in the current directory.
+    #
+    # @return [void]
     def self.load!
       if File.exist?(config_file = File.join(Dir.pwd, "config.rb"))
         load config_file
@@ -10,6 +27,7 @@ module Wytch
       end
     end
 
+    # Creates a new Site with default configuration.
     def initialize
       @inflections = {}
       @content_dir = "content"
@@ -19,13 +37,38 @@ module Wytch
       @base_url = nil
     end
 
+    # @return [Hash] custom inflections for Zeitwerk autoloading
     attr_reader :inflections
+
+    # @!attribute content_dir
+    #   @return [String] directory containing content files (default: "content")
+    # @!attribute site_code_path
+    #   @return [String] directory containing site Ruby code (default: "src")
+    # @!attribute page_class
+    #   @return [String] fully qualified class name for pages (default: "Wytch::Page")
+    # @!attribute pages
+    #   @return [Hash{String => Page}] all loaded pages, keyed by path
+    # @!attribute base_url
+    #   @return [String, nil] base URL for the site (used in sitemaps, feeds, etc.)
     attr_accessor :content_dir, :site_code_path, :page_class, :pages, :base_url
 
+    # Adds custom inflections for Zeitwerk autoloading.
+    #
+    # @param inflections_hash [Hash{String => String}] mapping of file names to class names
+    # @return [void]
+    #
+    # @example
+    #   site.inflect("api" => "API", "html_parser" => "HTMLParser")
     def inflect(inflections_hash)
       @inflections.merge!(inflections_hash)
     end
 
+    # Returns the Zeitwerk loader for site code.
+    #
+    # The loader is configured to watch the site_code_path directory and
+    # supports hot reloading during development.
+    #
+    # @return [Zeitwerk::Loader] the configured loader
     def site_code_loader
       @site_code_loader ||= begin
         loader = Zeitwerk::Loader.new
@@ -37,10 +80,16 @@ module Wytch
       end
     end
 
+    # Returns the content loader instance.
+    #
+    # @return [ContentLoader] the loader for content files
     def content_loader
       @content_loader ||= ContentLoader.new
     end
 
+    # Loads all content files and populates the pages hash.
+    #
+    # @return [Hash{String => Page}] all loaded pages
     def load_content
       @pages = content_loader.load_content
     end

data/lib/wytch/site_code_loader_middleware.rb

@@ -1,12 +1,31 @@
 # frozen_string_literal: true
 
 module Wytch
+  # Rack middleware that triggers hot reloading before each request.
+  #
+  # This middleware wraps the base application and coordinates with the
+  # ReloadCoordinator to ensure site code and content are reloaded when
+  # files change. It acquires a read lock during request processing to
+  # prevent reloads from interfering with rendering.
+  #
+  # @see Wytch::ReloadCoordinator
   class SiteCodeLoaderMiddleware
+    # Creates a new middleware instance.
+    #
+    # @param app [#call] the Rack application to wrap
+    # @param coordinator [ReloadCoordinator] the reload coordinator
     def initialize(app, coordinator)
       @app = app
       @coordinator = coordinator
     end
 
+    # Handles a Rack request.
+    #
+    # Triggers a reload check, then processes the request while holding
+    # a read lock to prevent concurrent reloads.
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Array] the Rack response tuple
     def call(env)
       @coordinator.reload!
 

data/lib/wytch/sitemap_helper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Wytch
+  # Helper module for sitemap pages.
+  #
+  # This module provides methods to configure a page as a sitemap.
+  # It sets the correct path, build path, and excludes the sitemap
+  # itself from appearing in the sitemap.
+  #
+  # @example Using in a content file (content/sitemap.rb)
+  #   view Wytch::SitemapView
+  #   add Wytch::SitemapHelper
+  module SitemapHelper
+    # Returns the URL path for the sitemap.
+    #
+    # @return [String] "/sitemap.xml"
+    def path
+      "/sitemap.xml"
+    end
+
+    # Returns the build path for the sitemap.
+    #
+    # @return [String] "sitemap.xml"
+    def build_path
+      "sitemap.xml"
+    end
+
+    # Excludes the sitemap from appearing in the sitemap.
+    #
+    # @return [Boolean] false
+    def include_in_sitemap?
+      false
+    end
+  end
+end

data/lib/wytch/sitemap_view.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Wytch
+  # Generates an XML sitemap for the site.
+  #
+  # This view renders a sitemap.xml file listing all pages that have
+  # `include_in_sitemap?` returning true.
+  #
+  # @example Using in a content file (content/sitemap.rb)
+  #   view Wytch::SitemapView
+  #   add Wytch::SitemapHelper
+  class SitemapView
+    # Creates a new sitemap view.
+    #
+    # @param page [Page] the page object (not used but required for interface)
+    def initialize(page)
+      @page = page
+    end
+
+    # Renders the sitemap XML.
+    #
+    # @return [String] XML sitemap content
+    def call
+      require "builder"
+
+      xml = ::Builder::XmlMarkup.new(indent: 2)
+      xml.instruct! :xml, version: "1.0", encoding: "UTF-8"
+      xml.urlset xmlns: "http://www.sitemaps.org/schemas/sitemap/0.9" do
+        Wytch.site.pages.values.each do |page|
+          next unless page.include_in_sitemap?
+          xml.url do
+            xml.loc "#{Wytch.site.base_url}#{page.path}"
+            xml.lastmod page.last_modified if page.last_modified
+            xml.changefreq page.change_frequency if page.change_frequency
+            xml.priority page.priority if page.priority
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wytch/templates/content/sitemap.rb.tt

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 
-add <%= @site_module %>::SitemapHelper
-view <%= @site_module %>::SitemapView
+add Wytch::SitemapHelper
+view Wytch::SitemapView

data/lib/wytch/templates/src/site/layout.rb.tt

@@ -11,6 +11,7 @@ module <%= @site_module %>
 
       html do
         head do
+          meta charset: "utf-8"
           title { @page.metadata[:title] }
           meta name: "description", content: @page.metadata[:description] if @page.metadata[:description]
           meta name: "viewport", content: "width=device-width, initial-scale=1.0"