jackdaw 1.0.0

data/lib/jackdaw/project.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Jackdaw
+  #
+  # Project structure management
+  #
+  # Defines the standard Jackdaw project structure and provides path helpers.
+  # All Jackdaw projects follow this convention:
+  #
+  #   my-site.site/
+  #   ├── site/
+  #   │   ├── src/           # Content files (*.md)
+  #   │   ├── templates/     # ERB templates (*.html.erb)
+  #   │   └── assets/        # Static assets (images, CSS, JS)
+  #   └── public/            # Generated output
+  #
+  # This convention-over-configuration approach eliminates the need for
+  # configuration files while maintaining clear project organization.
+  #
+  class Project
+    attr_reader :root
+
+    # Initialize a project at the given root directory
+    #
+    # @param root [String] Path to project root (defaults to current directory)
+    def initialize(root = Dir.pwd)
+      @root = File.expand_path(root)
+    end
+
+    # Path to the site directory containing all source files
+    #
+    # @return [String] Absolute path to site/
+    def site_dir
+      File.join(root, 'site')
+    end
+
+    # Path to content source directory
+    #
+    # @return [String] Absolute path to site/src/
+    def src_dir
+      File.join(site_dir, 'src')
+    end
+
+    # Path to templates directory
+    #
+    # @return [String] Absolute path to site/templates/
+    def templates_dir
+      File.join(site_dir, 'templates')
+    end
+
+    # Path to assets directory
+    #
+    # @return [String] Absolute path to site/assets/
+    def assets_dir
+      File.join(site_dir, 'assets')
+    end
+
+    # Path to output directory for generated site
+    #
+    # @return [String] Absolute path to public/
+    def output_dir
+      File.join(root, 'public')
+    end
+
+    # Check if this is a valid Jackdaw project
+    #
+    # @return [Boolean] true if site/ directory exists
+    def exists?
+      Dir.exist?(site_dir)
+    end
+
+    # Create the standard project directory structure
+    #
+    # @return [void]
+    def create!
+      dirs = [site_dir, src_dir, templates_dir, assets_dir, output_dir]
+      dirs.each { |dir| FileUtils.mkdir_p(dir) }
+    end
+  end
+end

data/lib/jackdaw/renderer.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Jackdaw
+  # Renders content using ERB templates with layouts and partials
+  class Renderer
+    attr_reader :project, :scanner
+
+    def initialize(project)
+      @project = project
+      @scanner = Scanner.new(project)
+      @template_cache = {}
+    end
+
+    # Render a content file to HTML
+    def render_content(content_file)
+      # Get the template for this content type
+      template = find_template(content_file.type)
+      raise Error, "Template not found for type: #{content_file.type}" unless template
+
+      # Build context
+      context = build_context(content_file)
+
+      # Render markdown to HTML
+      html_content = render_markdown(content_file.content)
+
+      # Render template with content
+      template_html = render_template(template, context.merge(content: html_content))
+
+      # Wrap in layout if it exists
+      render_layout(template_html, context)
+    end
+
+    # Render a partial
+    def render_partial(name, context = {})
+      partial_path = File.join(project.templates_dir, "_#{name}.html.erb")
+      raise Error, "Partial not found: #{name}" unless File.exist?(partial_path)
+
+      template = load_template(partial_path)
+      render_template(template, context)
+    end
+
+    private
+
+    def find_template(type)
+      template_path = File.join(project.templates_dir, "#{type}.html.erb")
+      File.exist?(template_path) ? load_template(template_path) : nil
+    end
+
+    def load_template(path)
+      # Cache compiled templates
+      mtime = File.mtime(path)
+      cache_key = "#{path}:#{mtime.to_i}"
+
+      @template_cache[cache_key] ||= ERB.new(File.read(path), trim_mode: '-')
+    end
+
+    def render_template(template, context)
+      binding_context = TemplateContext.new(context, self)
+      template.result(binding_context.template_binding)
+    end
+
+    def render_markdown(markdown_content)
+      Kramdown::Document.new(
+        markdown_content,
+        input: 'GFM',
+        syntax_highlighter: 'rouge',
+        syntax_highlighter_opts: {
+          line_numbers: false,
+          css_class: 'highlight'
+        }
+      ).to_html
+    end
+
+    def render_layout(content, context)
+      layout_path = File.join(project.templates_dir, 'layout.html.erb')
+      return content unless File.exist?(layout_path)
+
+      layout = load_template(layout_path)
+      render_template(layout, context.merge(content: content))
+    end
+
+    def build_context(content_file)
+      {
+        title: content_file.title,
+        date: content_file.date,
+        type: content_file.type,
+        slug: content_file.slug,
+        path: content_file.output_path,
+        excerpt: content_file.excerpt,
+        reading_time: content_file.reading_time,
+        site_name: infer_site_name,
+        all_posts: all_posts,
+        all_pages: all_pages
+      }
+    end
+
+    def infer_site_name
+      # Extract site name from folder structure (e.g., "my-blog.site" -> "my-blog")
+      project_name = File.basename(project.root)
+      project_name.sub(/\.site$/, '').tr('-', ' ').split.map(&:capitalize).join(' ')
+    end
+
+    def all_posts
+      @all_posts ||= scanner.content_files
+                            .select { |f| %w[blog post].include?(f.type) }
+                            .sort_by(&:date)
+                            .reverse
+    end
+
+    def all_pages
+      @all_pages ||= scanner.content_files
+                            .select { |f| f.type == 'page' }
+                            .sort_by(&:title)
+    end
+  end
+
+  # Template context for ERB binding
+  class TemplateContext
+    include Jackdaw::SEOHelpers
+
+    def initialize(context, renderer)
+      @context = context
+      @renderer = renderer
+
+      # Make all context variables available as instance variables
+      context.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    # Expose binding for ERB
+    def template_binding
+      binding
+    end
+
+    # Make context variables available as methods
+    def method_missing(method_name, *args)
+      if @context.key?(method_name)
+        @context[method_name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @context.key?(method_name) || super
+    end
+
+    # Render partial helper
+    def render(partial_name, local_context = {})
+      @renderer.render_partial(partial_name, @context.merge(local_context))
+    end
+  end
+end

data/lib/jackdaw/scanner.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Jackdaw
+  # Scans directories and discovers content files
+  class Scanner
+    attr_reader :project
+
+    def initialize(project)
+      @project = project
+    end
+
+    # Scan for all content files in src/ directory
+    def content_files
+      return [] unless Dir.exist?(project.src_dir)
+
+      Dir.glob(File.join(project.src_dir, '**', '*.*.md')).map do |path|
+        ContentFile.new(path, project)
+      end
+    end
+
+    # Scan for all template files in templates/ directory
+    def template_files
+      return [] unless Dir.exist?(project.templates_dir)
+
+      Dir.glob(File.join(project.templates_dir, '*.html.erb')).map do |path|
+        TemplateFile.new(path, project)
+      end
+    end
+
+    # Scan for all asset files in assets/ directory
+    def asset_files
+      return [] unless Dir.exist?(project.assets_dir)
+
+      Dir.glob(File.join(project.assets_dir, '**', '*')).reject { |p| File.directory?(p) }.map do |path|
+        AssetFile.new(path, project)
+      end
+    end
+
+    # Get all files
+    def all_files
+      content_files + template_files + asset_files
+    end
+  end
+end

data/lib/jackdaw/seo_helpers.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Jackdaw
+  # SEO meta tag helpers for templates
+  module SEOHelpers
+    # Generate Open Graph meta tags
+    def og_tags(title:, description:, url:, type: 'website', image: nil)
+      tags = []
+      tags << %(<meta property="og:title" content="#{escape_html(title)}" />)
+      tags << %(<meta property="og:description" content="#{escape_html(description)}" />)
+      tags << %(<meta property="og:url" content="#{escape_html(url)}" />)
+      tags << %(<meta property="og:type" content="#{escape_html(type)}" />)
+      tags << %(<meta property="og:image" content="#{escape_html(image)}" />) if image
+
+      tags.join("\n    ")
+    end
+
+    # Generate Twitter Card meta tags
+    def twitter_tags(title:, description:, card: 'summary', image: nil, site: nil, creator: nil)
+      tags = []
+      tags << %(<meta name="twitter:card" content="#{escape_html(card)}" />)
+      tags << %(<meta name="twitter:title" content="#{escape_html(title)}" />)
+      tags << %(<meta name="twitter:description" content="#{escape_html(description)}" />)
+      tags << %(<meta name="twitter:image" content="#{escape_html(image)}" />) if image
+      tags << %(<meta name="twitter:site" content="#{escape_html(site)}" />) if site
+      tags << %(<meta name="twitter:creator" content="#{escape_html(creator)}" />) if creator
+
+      tags.join("\n    ")
+    end
+
+    # Generate canonical link tag
+    def canonical_tag(url)
+      %(<link rel="canonical" href="#{escape_html(url)}" />)
+    end
+
+    # Generate meta description tag
+    def meta_description(description)
+      %(<meta name="description" content="#{escape_html(description)}" />)
+    end
+
+    # Generate all basic SEO tags at once
+    def seo_tags(title:, description:, url:, image: nil, type: 'website')
+      tags = []
+      tags << meta_description(description)
+      tags << canonical_tag(url)
+      tags << og_tags(title: title, description: description, url: url, type: type, image: image)
+      tags << twitter_tags(title: title, description: description, image: image)
+
+      tags.join("\n    ")
+    end
+
+    private
+
+    def escape_html(text)
+      return '' unless text
+
+      text.to_s
+          .gsub('&', '&amp;')
+          .gsub('<', '&lt;')
+          .gsub('>', '&gt;')
+          .gsub('"', '&quot;')
+          .gsub("'", '&#39;')
+    end
+  end
+end

data/lib/jackdaw/server.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Jackdaw
+  # Development server with live reload
+  class Server
+    attr_reader :project, :builder, :watcher, :port, :host
+
+    def initialize(project, options = {})
+      @project = project
+      @builder = Builder.new(project, {})
+      @port = options[:port] || 4000
+      @host = options[:host] || 'localhost'
+      @livereload = options.fetch(:livereload, true)
+      @rebuilding = false
+      @clients = []
+    end
+
+    # Start the server
+    def start
+      # Initial build
+      puts "\n#{colorize('🚀 Building site...', :magenta)}"
+      stats = builder.build
+      show_build_stats(stats)
+
+      # Setup file watcher
+      setup_watcher if @livereload
+
+      # Start Puma
+      puts "\n#{colorize("⚡️ Server running at #{colorize("http://#{host}:#{port}", :cyan)}", :bold)}"
+      puts colorize('Press Ctrl+C to stop', :magenta)
+      puts ''
+
+      Rack::Handler::Puma.run(rack_app, Port: port, Host: host, Silent: true)
+    end
+
+    def livereload?
+      @livereload
+    end
+
+    private
+
+    def rack_app
+      server = self
+      Rack::Builder.new do
+        use Rack::CommonLogger
+        use LiveReloadMiddleware, server if server.livereload?
+        run StaticFileServer.new(server.project)
+      end
+    end
+
+    def setup_watcher
+      @watcher = Watcher.new(project)
+
+      @watcher.on_change do |changes|
+        next if @rebuilding
+
+        @rebuilding = true
+        Thread.new do
+          rebuild_site(changes)
+        ensure
+          @rebuilding = false
+        end
+      end
+
+      @watcher.start
+    end
+
+    def rebuild_site(changes)
+      changed_files = changes.values.flatten.length
+      puts "\n#{colorize('🔄 Rebuilding...', :cyan)} (#{changed_files} files changed)"
+
+      stats = builder.build
+      show_build_stats(stats)
+
+      notify_reload if @livereload
+    end
+
+    def show_build_stats(stats)
+      if stats.success?
+        puts "#{colorize('✓',
+                         :green)} Built #{colorize(stats.files_built.to_s,
+                                                   :cyan)} pages in #{colorize(format('%.2fs', stats.total_time),
+                                                                               :cyan)}"
+      else
+        puts colorize("✗ Build failed with #{stats.errors.length} errors", :yellow)
+        stats.errors.each { |e| puts "  #{colorize('→', :yellow)} #{e.message}" }
+      end
+    end
+
+    def notify_reload
+      # In a real implementation, this would notify WebSocket clients
+      # For now, the LiveReloadMiddleware handles it with polling
+    end
+
+    def colorize(text, color)
+      colors = {
+        reset: "\e[0m",
+        bold: "\e[1m",
+        green: "\e[32m",
+        cyan: "\e[36m",
+        yellow: "\e[33m",
+        magenta: "\e[35m"
+      }
+      "#{colors[color]}#{text}#{colors[:reset]}"
+    end
+  end
+
+  # Static file server
+  class StaticFileServer
+    def initialize(project)
+      @project = project
+    end
+
+    def call(env)
+      path = Rack::Utils.unescape_path(env['PATH_INFO'])
+      file_path = File.join(@project.output_dir, path)
+
+      # Serve index.html for directories
+      file_path = File.join(file_path, 'index.html') if path.end_with?('/') || File.directory?(file_path)
+
+      # Add .html extension if file doesn't exist
+      unless File.exist?(file_path)
+        html_path = "#{file_path}.html"
+        file_path = html_path if File.exist?(html_path)
+      end
+
+      if File.exist?(file_path) && File.file?(file_path)
+        serve_file(file_path)
+      else
+        [404, { 'Content-Type' => 'text/html' }, ['<h1>404 Not Found</h1>']]
+      end
+    end
+
+    private
+
+    def serve_file(path)
+      content = File.read(path)
+      content_type = mime_type(path)
+
+      [200, { 'Content-Type' => content_type, 'Content-Length' => content.bytesize.to_s }, [content]]
+    end
+
+    def mime_type(path)
+      case File.extname(path)
+      when '.html' then 'text/html'
+      when '.css' then 'text/css'
+      when '.js' then 'application/javascript'
+      when '.json' then 'application/json'
+      when '.png' then 'image/png'
+      when '.jpg', '.jpeg' then 'image/jpeg'
+      when '.gif' then 'image/gif'
+      when '.svg' then 'image/svg+xml'
+      else 'text/plain'
+      end
+    end
+  end
+
+  # Live reload middleware
+  class LiveReloadMiddleware
+    RELOAD_SCRIPT = <<~JS
+      <script>
+        (function() {
+          let lastCheck = Date.now();
+          setInterval(function() {
+            fetch('/__rhes_reload_check')
+              .then(r => r.json())
+              .then(data => {
+                if (data.lastBuild > lastCheck) {
+                  console.log('Jackdaw: Reloading page...');
+                  location.reload();
+                }
+                lastCheck = Date.now();
+              })
+              .catch(() => {});
+          }, 1000);
+        })();
+      </script>
+    JS
+
+    def initialize(app, server)
+      @app = app
+      @server = server
+      @last_build = Time.now
+    end
+
+    def call(env)
+      # Handle reload check endpoint
+      if env['PATH_INFO'] == '/__rhes_reload_check'
+        return [
+          200,
+          { 'Content-Type' => 'application/json' },
+          [JSON.generate({ lastBuild: @last_build.to_f })]
+        ]
+      end
+
+      status, headers, response = @app.call(env)
+
+      # Inject reload script into HTML responses
+      if headers['Content-Type']&.include?('text/html')
+        body = ''
+        response.each { |part| body << part }
+
+        if body.include?('</body>')
+          body = body.sub('</body>', "#{RELOAD_SCRIPT}</body>")
+          @last_build = Time.now
+          headers['Content-Length'] = body.bytesize.to_s
+          response = [body]
+        end
+      end
+
+      [status, headers, response]
+    end
+  end
+end

data/lib/jackdaw/sitemap_generator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Jackdaw
+  # Generates sitemap.xml for SEO
+  class SitemapGenerator
+    attr_reader :project, :scanner
+
+    def initialize(project)
+      @project = project
+      @scanner = Scanner.new(project)
+    end
+
+    # Generate sitemap.xml
+    def generate
+      urls = all_content_urls
+
+      sitemap = <<~SITEMAP
+        <?xml version="1.0" encoding="UTF-8"?>
+        <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+          #{urls.map { |url| url_entry(url) }.join("\n")}
+        </urlset>
+      SITEMAP
+
+      File.write(File.join(project.output_dir, 'sitemap.xml'), sitemap)
+    end
+
+    private
+
+    def all_content_urls
+      scanner.content_files.map do |file|
+        {
+          path: file.output_path,
+          date: file.date,
+          type: file.type
+        }
+      end
+    end
+
+    def url_entry(url)
+      priority = calculate_priority(url[:type], url[:path])
+      changefreq = calculate_changefreq(url[:type])
+
+      <<~ENTRY.strip
+          <url>
+            <loc>#{site_url}/#{url[:path]}</loc>
+            <lastmod>#{url[:date].to_time.utc.iso8601}</lastmod>
+            <changefreq>#{changefreq}</changefreq>
+            <priority>#{priority}</priority>
+          </url>
+      ENTRY
+    end
+
+    def calculate_priority(type, path)
+      return '1.0' if path == 'index.html'
+      return '0.8' if type == 'page'
+      return '0.6' if %w[blog post article news].include?(type)
+
+      '0.5'
+    end
+
+    def calculate_changefreq(type)
+      return 'daily' if %w[blog post article news].include?(type)
+      return 'weekly' if type == 'page'
+
+      'monthly'
+    end
+
+    def site_url
+      ENV.fetch('SITE_URL', 'http://localhost:4000')
+    end
+  end
+end

data/lib/jackdaw/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Jackdaw
+  VERSION = '1.0.0'
+end

data/lib/jackdaw/watcher.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Jackdaw
+  # Watches for file changes and triggers callbacks
+  class Watcher
+    attr_reader :project, :listener
+
+    def initialize(project)
+      @project = project
+      @callbacks = []
+    end
+
+    # Register a callback to be called on file changes
+    def on_change(&block)
+      @callbacks << block
+    end
+
+    # Start watching
+    def start
+      @listener = Listen.to(project.site_dir) do |modified, added, removed|
+        notify_callbacks(modified, added, removed)
+      end
+
+      listener.start
+    end
+
+    # Stop watching
+    def stop
+      listener&.stop
+    end
+
+    private
+
+    def notify_callbacks(modified, added, removed)
+      @callbacks.each do |callback|
+        callback.call(modified: modified, added: added, removed: removed)
+      end
+    end
+  end
+end