sakusei 0.4.0 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51994014be2b8900d793d1954389a52a2726b54703cd60673886f7b85cfbeaa2
-  data.tar.gz: d650c71e17c76b74f770dd32cc83b45848cacd0b1f7a8f49c3d4eb98185fee50
+  metadata.gz: f8f86cb0ba1fda1a5536579ffc06db171359b7d839537bef66a7622dabed68be
+  data.tar.gz: 1eeb757166832e05c87fa8ae7d8a654a4cf2c5abab097b82e4466245d99830d1
 SHA512:
-  metadata.gz: 0c8a398207d15178355e2da253dd4e3d20e9e524a044125214e7c074f264892a5ae9749b2773cf42c4de353532d731a8798d52eb922da38f6d0e5e5185940f8c
-  data.tar.gz: 0b8970fdb542f9fe5f2b81bda13019be3893501735c62962f7a66e60c2acc8f38672ccf74fc4df08ece6b149796d84da52a4207b1ccde31793d079856c426ce7
+  metadata.gz: e6d8145acd491414bdaea711ba249557aa887a049b0d7c59788825d1b8946cb93f33a4f5e87be5b3843f2ef8703577fe34dd7c0ec7681f9b55216c897e3aad17
+  data.tar.gz: 07ead103bda8c9d269501f6384f2d42d37efaf718f66237b006a0dc2430974535696d3eb1e1fb1b46b82683afa0eed437dd6a0a590692c01b6fd53f42f0daafa

data/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "defaultMode": "auto",
+    "allow": [
+      "Bash(git *)"
+    ]
+  }
+}

data/CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+Run all tests:
+
+```bash
+bundle exec rake test
+```
+
+Run a single test file:
+
+```bash
+ruby -Ilib -Itest test/sakusei/test_builder_break_syntax.rb
+```
+
+Build and install the gem locally:
+
+```bash
+rake install
+```
+
+Build a PDF from one of the examples:
+
+```bash
+bundle exec sakusei build examples/getting-started.md
+```
+
+Live-preview a markdown file in the browser:
+
+```bash
+bundle exec sakusei-preview examples/getting-started.md
+```
+
+## Architecture
+
+Sakusei ships two CLIs:
+
+- `bin/sakusei` (Thor) — the build CLI that produces PDFs.
+- `bin/sakusei-preview` — a separate live-render binary backed by `Sakusei::PreviewServer`. Watches the source file, its `@include` partials, the active style pack, and referenced images; re-renders to HTML on change via `npx md-to-pdf --as-html` and reloads the browser tab. Loads paged.js from a CDN so `@page`/`page-break-*` rules are visible as document pages. Use this for fast iteration; use `sakusei build` for the final PDF.
+
+Both CLIs share the multi-stage build pipeline.
+
+### Build pipeline
+
+`Builder#build` in `lib/sakusei/builder.rb` runs these steps in order:
+
+1. **StylePack.discover** — walks up the directory tree from the source file, looking for `.sakusei/style_packs/<name>/` at each level. Falls back to the built-in pack at `lib/templates/default_style_pack/`.
+2. **FileResolver** — resolves `<!-- @include ./file.md -->` directives and concatenates the content.
+3. **ErbProcessor** — evaluates ERB in the markdown. Available helpers: `today(format)`, `env(name, default)`, `sh(command)`, `include_file(path)`, `image_path(relative_path)`, `document_headings(path)`.
+4. **expand_break_syntax** — expands `::break::` shorthand to `<div class="page-break"></div>`.
+5. **VueProcessor** — finds `<vue-component name="Foo" prop="value" />` tags, renders them server-side via `lib/sakusei/vue_renderer.js` using Node.js + `@vue/server-renderer` in a single batched call.
+6. **HeadingWrapper** — wraps h2/h3 headings with their immediately following content block in keep-together divs to prevent orphaned headings.
+7. **MdToPdfConverter** / **HtmlConverter** — both extend `ConverterBase` (`lib/sakusei/converter_base.rb`) and assemble the `npx md-to-pdf` command with config, stylesheets, and header/footer from the style pack. `MdToPdfConverter` runs it in a temp dir and returns the PDF path; `HtmlConverter` adds `--as-html` and returns the HTML string (used by the live preview server).
+
+`Builder#build_html` runs stages 1–6 and ends in `HtmlConverter`, sharing the pipeline with `Builder#build` so the preview matches the final PDF.
+
+`MultiFileBuilder` handles glob patterns and multiple source files, delegating to `Builder` per file and concatenating results.
+
+### Style packs
+
+A style pack is a directory containing:
+
+- `config.js` — md-to-pdf configuration (Puppeteer/Chrome options)
+- `style.css` — stylesheet applied after `lib/templates/base.css`
+- `header.html`, `footer.html` — Puppeteer page chrome injected before the markdown content
+- `components/*.vue` — Vue 3 SFCs, rendered server-side at build time (optional)
+- `package.json` — if present, npm dependencies are auto-installed on first use
+
+`lib/templates/base.css` is always applied first and provides keep-together rules for tables, code blocks, blockquotes, images, and common custom classes.
+
+Style pack discovery walks up the directory tree from the source file; a named pack can live in any ancestor's `.sakusei/` directory. The default pack in `lib/templates/default_style_pack/` is the final fallback.
+
+### Vue component system
+
+Components are referenced in markdown as `<vue-component name="MyComponent" prop="value" />`. `VueProcessor` finds all such tags in a first pass, replaces them with numbered placeholders, then sends a single JSON batch to `vue_renderer.js` via stdin. The JS renderer uses `@vue/server-renderer` to render each component and returns HTML + scoped CSS back as JSON. Scoped CSS is injected as a `<style>` block at the top of the document.
+
+Component resolution order: local `./components/<Name>.vue` → style pack `components/<Name>.vue`.
+
+Vue components support named slots via `<template #slotname>...</template>` inside the tag. Slot content is converted from Markdown to HTML before being passed to the renderer.
+
+### Tests
+
+Tests use Minitest. Fixtures live in `test/fixtures/` (markdown samples and stub style packs). `test/test_vue_renderer.js` is a standalone Node.js test for the JS renderer. The base test class `Sakusei::TestCase` provides `fixtures_dir` and a `temp_dir` that auto-cleans on teardown.

data/Gemfile.lock

@@ -0,0 +1,82 @@
+PATH
+  remote: .
+  specs:
+    sakusei (0.5.9)
+      erb (~> 4.0)
+      listen (~> 3.8)
+      thor (~> 1.2)
+      webrick (~> 1.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    cgi (0.5.1)
+    erb (4.0.3)
+      cgi (>= 0.3.3)
+    ffi (1.17.4)
+    ffi (1.17.4-arm64-darwin)
+    json (2.19.2)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    mcp (0.9.0)
+      json-schema (>= 4.1)
+    minitest (5.27.0)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    regexp_parser (2.11.3)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    thor (1.5.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webrick (1.9.2)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  rubocop (~> 1.0)
+  sakusei!
+
+BUNDLED WITH
+   2.7.2

data/bin/sakusei-preview

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'sakusei'
+require 'sakusei/preview_server'
+
+options = { open: true, paged: true }
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: sakusei-preview FILE [options]'
+
+  opts.on('-p', '--port PORT', Integer, "Port to bind (default #{Sakusei::PreviewServer::DEFAULT_PORT})") { |v| options[:port] = v }
+  opts.on('-s', '--style PACK', 'Style pack name to use') { |v| options[:style] = v }
+  opts.on('-c', '--config FILE', 'Path to md-to-pdf config file') { |v| options[:config] = v }
+  opts.on('--stylesheet FILE', 'Path to CSS stylesheet') { |v| options[:stylesheet] = v }
+  opts.on('--no-open', 'Do not open the browser automatically') { options[:open] = false }
+  opts.on('--no-paged', 'Disable paged.js pagination (show as scrolling HTML)') { options[:paged] = false }
+  opts.on('-h', '--help', 'Show this help') { puts opts; exit 0 }
+end
+
+args = parser.parse(ARGV)
+if args.empty?
+  warn parser
+  exit 1
+end
+
+source_file = Sakusei.resolve_file_extension(args.first)
+unless File.exist?(source_file)
+  warn "File not found: #{args.first}"
+  exit 1
+end
+
+begin
+  Sakusei::PreviewServer.new(source_file, options).run
+rescue Interrupt
+  exit 0
+rescue Sakusei::Error => e
+  warn "[sakusei-preview] #{e.message}"
+  exit 1
+end

data/lib/sakusei/builder.rb

@@ -7,6 +7,7 @@ require_relative 'image_path_resolver'
 require_relative 'vue_processor'
 require_relative 'heading_wrapper'
 require_relative 'md_to_pdf_converter'
+require_relative 'html_converter'
 
 module Sakusei
   class Builder
@@ -14,48 +15,64 @@ module Sakusei
       @source_file = File.expand_path(source_file)
       @options = options
       @source_dir = File.dirname(@source_file)
+      @file_resolver = nil
+    end
+
+    attr_reader :source_file, :source_dir
+
+    # Files that contributed to the most recent build (source + @include partials).
+    # Populated after #build, #build_html, or #build_processed_content runs.
+    def resolved_input_files
+      files = [@source_file]
+      files.concat(@file_resolver.resolved_files.to_a) if @file_resolver
+      files.uniq
     end
 
     def build
-      # 1. Discover and load style pack
+      style_pack, processed_content = build_processed_content
+      $stderr.puts "[sakusei] converting to PDF..."
+      output_path = generate_output_path
+      convert_to_pdf(processed_content, output_path, style_pack)
+      $stderr.puts "[sakusei] written: #{output_path}"
+      output_path
+    end
+
+    # Run the full pipeline up to (but not including) PDF conversion, then
+    # render the processed markdown to a styled HTML string via md-to-pdf --as-html.
+    # Returns [html_string, style_pack].
+    def build_html
+      style_pack, processed_content = build_processed_content
+      html = HtmlConverter.new(processed_content, style_pack, @options.merge(source_dir: @source_dir)).convert
+      [html, style_pack]
+    end
+
+    private
+
+    def build_processed_content
       $stderr.puts "[sakusei] discovering style pack..."
       style_pack = discover_style_pack
       $stderr.puts "[sakusei] style pack: #{style_pack.name} (#{style_pack.path})"
 
-      # 2. Resolve and concatenate file references
       $stderr.puts "[sakusei] resolving file includes..."
       resolved_content = resolve_files
 
-      # 3. Process ERB templates
       $stderr.puts "[sakusei] processing ERB..."
       processed_content = process_erb(resolved_content)
 
-      # 3.5. Expand shorthand syntax (e.g. ::break:: → page-break div)
       processed_content = expand_break_syntax(processed_content)
-
-      # 4. Process Vue components (if available)
       processed_content = process_vue(processed_content, style_pack)
-
-      # 4.5 Wrap h2/h3 headings with their following block to prevent orphaned headings
       processed_content = wrap_headings(processed_content)
 
-      # 5. Convert to PDF
-      $stderr.puts "[sakusei] converting to PDF..."
-      output_path = generate_output_path
-      convert_to_pdf(processed_content, output_path, style_pack)
-
-      $stderr.puts "[sakusei] written: #{output_path}"
-      output_path
+      [style_pack, processed_content]
     end
 
-    private
-
     def discover_style_pack
       StylePack.discover(@options[:source_dir] || @source_dir, @options[:style])
     end
 
     def resolve_files
-      FileResolver.new(@source_file).resolve
+      @file_resolver = FileResolver.new(@source_file)
+      @file_resolver.resolve
     end
 
     def process_erb(content)

data/lib/sakusei/cli.rb

@@ -242,26 +242,14 @@ module Sakusei
       return false if arg.nil? || arg.empty?
       return false if File.extname(arg).length > 0  # Already has an extension
 
-      %w[.md .text .markdown].any? { |ext| File.exist?(arg + ext) }
+      Sakusei::MARKDOWN_EXTENSIONS.any? { |ext| File.exist?(arg + ext) }
     end
 
     private
 
     # Resolve file by trying markdown extensions if no extension provided
     def resolve_file_extension(file)
-      return file if File.exist?(file)
-      return file if File.directory?(file)
-      return file if file.include?('*')  # Glob pattern
-      return file if File.extname(file).length > 0  # Already has extension
-
-      # Try markdown extensions
-      %w[.md .text .markdown].each do |ext|
-        path_with_ext = file + ext
-        return path_with_ext if File.exist?(path_with_ext)
-      end
-
-      # Return original if no extension found
-      file
+      Sakusei.resolve_file_extension(file)
     end
 
     def open_pdf(path)

data/lib/sakusei/converter_base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Sakusei
+  class ConverterBase
+    def initialize(content, style_pack, options = {})
+      @content    = content
+      @style_pack = style_pack
+      @options    = options
+      @source_dir = options[:source_dir]
+    end
+
+    protected
+
+    def copy_images(temp_dir)
+      return unless @source_dir
+
+      image_paths.each do |rel_path|
+        src = File.expand_path(rel_path, @source_dir)
+        next unless File.exist?(src)
+
+        dest = File.join(temp_dir, rel_path)
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(src, dest)
+      end
+    end
+
+    def image_paths
+      paths = []
+      @content.scan(/!\[[^\]]*\]\(([^)]+)\)/) { |m| paths << m[0].strip }
+      @content.scan(/src="([^"]+)"/) { |m| paths << m[0].strip }
+      paths.reject { |p| p.match?(/\A(https?:|data:|\/\/)/) || p.start_with?('/') }
+           .uniq
+    end
+
+    def page_chrome_prefix
+      return '' unless @style_pack
+      %i[header footer].map do |part|
+        path = @style_pack.public_send(part)
+        path ? File.read(path) + "\n" : ''
+      end.join
+    end
+
+    def build_command(temp_md, temp_dir, extra_flags = [])
+      cmd = ['npx', 'md-to-pdf']
+
+      config = @options[:config] || @style_pack&.config
+      cmd << '--config-file' << config if config
+
+      stylesheets = [StylePack.base_stylesheet]
+      pack_stylesheet = @options[:stylesheet] || @style_pack&.stylesheet
+      stylesheets << pack_stylesheet if pack_stylesheet
+      stylesheets.each { |s| cmd << '--stylesheet' << s }
+
+      cmd << '--basedir' << temp_dir
+      extra_flags.each { |f| cmd << f }
+      cmd << temp_md
+      cmd
+    end
+  end
+end

data/lib/sakusei/file_resolver.rb

@@ -5,6 +5,8 @@ module Sakusei
   class FileResolver
     INCLUDE_PATTERN = /<!--\s*@include\s+(\S+)\s*-->/
 
+    attr_reader :resolved_files
+
     def initialize(source_file)
       @source_file = source_file
       @source_dir = File.dirname(source_file)

data/lib/sakusei/html_converter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'tmpdir'
+require_relative 'converter_base'
+
+module Sakusei
+  # Converts markdown content to a styled HTML string by invoking
+  # `npx md-to-pdf --as-html`. Used by the live preview server.
+  class HtmlConverter < ConverterBase
+    def convert
+      Dir.mktmpdir('sakusei-html') do |temp_dir|
+        temp_md = File.join(temp_dir, 'input.md')
+        # Header/footer files are injected as @page margin chrome by PreviewServer.
+        # Don't prepend them to the body the way MdToPdfConverter does for PDF output.
+        File.write(temp_md, @content)
+
+        copy_images(temp_dir)
+
+        cmd = build_command(temp_md, temp_dir, ['--as-html'])
+        stdout, stderr, status = Open3.capture3(*cmd)
+
+        unless status.success?
+          raise Error, "HTML conversion failed: #{stderr.strip}\n#{stdout.strip}"
+        end
+
+        html_path = File.join(temp_dir, 'input.html')
+        raise Error, "md-to-pdf did not produce HTML at #{html_path}" unless File.exist?(html_path)
+
+        File.read(html_path)
+      end
+    end
+  end
+end

data/lib/sakusei/md_to_pdf_converter.rb

@@ -2,16 +2,14 @@
 
 require 'fileutils'
 require 'tmpdir'
+require_relative 'converter_base'
 
 module Sakusei
   # Converts markdown content to PDF using md-to-pdf
-  class MdToPdfConverter
+  class MdToPdfConverter < ConverterBase
     def initialize(content, output_path, style_pack, options = {})
-      @content    = content
+      super(content, style_pack, options)
       @output_path = output_path
-      @style_pack = style_pack
-      @options    = options
-      @source_dir = options[:source_dir]
     end
 
     def convert
@@ -24,7 +22,7 @@ module Sakusei
         # so md-to-pdf's HTTP server can serve them by their relative paths.
         copy_images(temp_dir)
 
-        cmd = build_command(temp_md, temp_dir)
+        cmd = build_command(temp_md, temp_dir).join(' ')
         result = system(cmd)
         raise Error, 'PDF conversion failed' unless result
 
@@ -33,65 +31,5 @@ module Sakusei
 
       @output_path
     end
-
-    private
-
-    # Scans content for relative image paths (markdown and HTML img src),
-    # and copies each referenced file into temp_dir at the same relative path.
-    def copy_images(temp_dir)
-      return unless @source_dir
-
-      image_paths.each do |rel_path|
-        src = File.expand_path(rel_path, @source_dir)
-        next unless File.exist?(src)
-
-        dest = File.join(temp_dir, rel_path)
-        FileUtils.mkdir_p(File.dirname(dest))
-        FileUtils.cp(src, dest)
-      end
-    end
-
-    # Extracts relative image paths from both markdown syntax and HTML img tags.
-    def image_paths
-      paths = []
-
-      # Markdown: ![alt](path)
-      @content.scan(/!\[[^\]]*\]\(([^)]+)\)/) { |m| paths << m[0].strip }
-
-      # HTML: src="path" (covers Vue-rendered img tags)
-      @content.scan(/src="([^"]+)"/) { |m| paths << m[0].strip }
-
-      # Filter to relative paths only (skip http, https, data URIs, absolute paths)
-      paths.reject { |p| p.match?(/\A(https?:|data:|\/\/)/) || p.start_with?('/') }
-           .uniq
-    end
-
-    def page_chrome_prefix
-      return '' unless @style_pack
-      %i[header footer].map do |part|
-        path = @style_pack.public_send(part)
-        path ? File.read(path) + "\n" : ''
-      end.join
-    end
-
-    def build_command(temp_path, temp_dir)
-      cmd = ['npx', 'md-to-pdf']
-
-      config = @options[:config] || @style_pack.config
-      cmd << '--config-file' << config if config
-
-      stylesheets = [StylePack.base_stylesheet]
-      pack_stylesheet = @options[:stylesheet] || @style_pack.stylesheet
-      stylesheets << pack_stylesheet if pack_stylesheet
-      stylesheets.each { |s| cmd << '--stylesheet' << s }
-
-      # Set basedir to temp_dir so relativePath resolves to /input.md,
-      # making image src="images/foo.jpg" resolve to http://localhost:PORT/images/foo.jpg
-      # which is served from temp_dir where we've copied the assets.
-      cmd << '--basedir' << temp_dir
-
-      cmd << temp_path
-      cmd.join(' ')
-    end
   end
 end