wytch 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61bbb9530546971a617d753468cc6213d7fc11fc64c79242ac6ba81929b48cb1
-  data.tar.gz: 59a823a9af8dc811e2deaf940eaae0b1f08c8cdb2a746fd4558d039c1de2623b
+  metadata.gz: 7aa017b3a2d6ed1b64cde7b4a73f312222d64a630a365ad71db68f4babc28ce5
+  data.tar.gz: fba837a626f3c4dfcc3525d03127ada6b62b30b367e31da4c5eef3721c7b264a
 SHA512:
-  metadata.gz: bd3d5170c33314e16a993d3fbc6bda029f42a3d09d09ae1bec03c2dbfe3a2823c56acff5feeda33cb7f90367db1ac3b6433e48d05b4422b479af4c7e7b0963e0
-  data.tar.gz: c9ead1e98b30442aabe805f98a77c95ab0d6e005c79633b03d0d0dcecf64fdfd0be3a7439a317e2fb049c89fc097ef2d68e736d58bceac0a3c6a6587611c79fd
+  metadata.gz: b70258ec6436a644dee4ecb637dc0bcad929428c7803d4272b7eef34b8bb0620b024c683a2a77f41e1235c05f5c1713b188a374bc7d050bb77a571bd924db7f0
+  data.tar.gz: 98a84928a3cf7bd5aff50e99225d6b944da43ca69a44c2bb94a10ee8bc5ba424365ca228378f2f2472757b25632f86b7b5bea0aaa458e075100e2b96f1f87985

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [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/README.md

@@ -11,7 +11,29 @@ gem install wytch
 
 ## Usage
 
-FIXME
+Generate a new site like this:
+
+```bash
+wytch new my-site
+cd my-site
+bundle install
+npm install
+```
+
+Run the development servers with:
+
+```bash
+npm run dev # Runs the vite dev server for assets
+wytch server # Runes the Wytch dev server
+```
+
+Then visit `http://localhost:6969` to see your site.
+
+Once you are ready to build for production:
+
+```bash
+wytch build # Builds assets and generates your static site in the build directory.
+```
 
 ## Development
 

data/exe/wytch

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "wytch"
+
+Wytch::CLI.start(ARGV)

data/lib/wytch/builder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+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!
+
+      Wytch.site.site_code_loader.eager_load
+      Wytch.site.load_content
+
+      FileUtils.mkdir(OUTPUT_DIR) unless Dir.exist?(OUTPUT_DIR)
+
+      Wytch.site.pages.values.each do |page|
+        build_path = File.join(OUTPUT_DIR, page.build_path)
+
+        puts "Building #{page.path} → #{build_path}"
+
+        FileUtils.mkdir_p File.dirname(build_path)
+
+        File.write build_path, page.render
+      end
+
+      copy_public_files
+      copy_vite_assets
+    end
+
+    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)
+
+      # Vite already builds to build/assets, so assets are already in place
+      puts "Vite assets ready at #{vite_output}"
+    end
+  end
+end

data/lib/wytch/cli.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+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]
+
+      # Extract site name and create module constant
+      @site_name = File.basename(name)
+      @site_module = classify(@site_name)
+
+      empty_directory(name)
+      template("Gemfile.tt", "#{name}/Gemfile")
+      template("config.rb.tt", "#{name}/config.rb")
+      template("gitignore.tt", "#{name}/.gitignore")
+
+      # Asset pipeline configuration
+      template("package.json.tt", "#{name}/package.json")
+      template("vite.config.js.tt", "#{name}/vite.config.js")
+      template("rescript.json.tt", "#{name}/rescript.json")
+
+      # Assets directory
+      empty_directory("#{name}/assets")
+      template("frontend/Main.res.tt", "#{name}/assets/Main.res")
+      template("frontend/main.css.tt", "#{name}/assets/main.css")
+
+      # Content directory
+      empty_directory("#{name}/content")
+      template("content/index.rb.tt", "#{name}/content/index.rb")
+      empty_directory("#{name}/content/posts")
+      template("content/posts/hello-world.rb.tt", "#{name}/content/posts/hello-world.rb")
+      template("content/sitemap.rb.tt", "#{name}/content/sitemap.rb")
+      template("content/feed.rb.tt", "#{name}/content/feed.rb")
+
+      # Src directory with namespaced code
+      empty_directory("#{name}/src")
+      empty_directory("#{name}/src/#{@site_name}")
+      template("src/site/page.rb.tt", "#{name}/src/#{@site_name}/page.rb")
+      template("src/site/layout.rb.tt", "#{name}/src/#{@site_name}/layout.rb")
+      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")
+
+      # Public directory for static assets
+      empty_directory("#{name}/public")
+      template("public/robots.txt.tt", "#{name}/public/robots.txt")
+
+      say "Created new Wytch site in #{name}/", :green
+      say "\nNext steps:", :green
+      say "  cd #{name}"
+      say "  bundle install"
+      say "  npm install"
+      say "\nTo start developing:"
+      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 "  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
+    end
+
+    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
+  end
+end

data/lib/wytch/content_loader.rb

@@ -0,0 +1,54 @@
+# 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 = {}
+
+      Dir.glob(File.join("**", "*.rb"), base: content_dir).each do |file_path|
+        page = load_page(file_path)
+        pages[page.path] = page
+      end
+
+      pages
+    end
+
+    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
+  end
+end

data/lib/wytch/once.rb

@@ -0,0 +1,40 @@
+# 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
+
+        @block.call
+
+        @mutex = nil
+      end
+    end
+  end
+end

data/lib/wytch/page.rb

@@ -0,0 +1,136 @@
+# 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 = {}
+      @view_class = nil
+
+      source_path = File.join(Wytch.site.content_dir, @file_path)
+
+      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"
+        "/"
+      else
+        "/#{virtual_path}"
+      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
+      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
+  end
+end

data/lib/wytch/reload_coordinator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+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
+
+      @site_code_dirty = true
+      @content_dirty = true
+
+      @start_site_code_listener = Once.new do
+        Listen.to(Wytch.site.site_code_path) do
+          @site_code_dirty = true
+        end.start
+      end
+
+      @start_content_listener = Once.new do
+        Listen.to(Wytch.site.content_dir) do
+          @content_dirty = true
+        end.start
+      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
+
+      return unless @site_code_dirty || @content_dirty
+
+      reload_lock.with_write_lock do
+        if @site_code_dirty
+          # Site code changed: reload site code then reload content
+          @site_code_dirty = false
+          Wytch.site.site_code_loader.reload
+          Wytch.site.load_content
+        elsif @content_dirty
+          # Only content changed: just reload content
+          @content_dirty = false
+          Wytch.site.load_content
+        end
+      end
+    end
+  end
+end

data/lib/wytch/server.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+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!
+
+      require "puma"
+      require "puma/server"
+
+      port = options[:port] || 6969
+      host = options[:host] || "localhost"
+
+      puts "Starting Wytch development server on http://#{host}:#{port}"
+      puts "Press Ctrl+C to stop"
+
+      server = Puma::Server.new(app)
+      server.add_tcp_listener(host, port)
+      server.run.join
+    end
+
+    private
+
+    # Builds the Rack application stack.
+    #
+    # @return [Rack::Builder] the configured Rack app
+    def app
+      base_app = lambda { |env|
+        path = env["PATH_INFO"]
+
+        # Otherwise try to serve a page
+        page = Wytch.site.pages[path]
+
+        if page
+          body = page.render
+          [
+            200,
+            {"content-type" => "text/html"},
+            [body]
+          ]
+        else
+          [
+            404,
+            {"content-type" => "text/html"},
+            ["<html><body><h1>404 Not Found</h1><p>Page not found: #{path}</p></body></html>"]
+          ]
+        end
+      }
+
+      reload_coordinator = ReloadCoordinator.new
+
+      Rack::Builder.new do
+        use Rack::Static, urls: [""], root: "public", cascade: true
+
+        run SiteCodeLoaderMiddleware.new(base_app, reload_coordinator)
+      end
+    end
+  end
+end