typst-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ffc46a6af771ebebfbe1754e08bc1e113cd0dd8bb3f2cc2f7ec50d364e7ece8
+  data.tar.gz: 393e6e688947174901bf6acb044d884462122b33e02c700b4d5cbed79699fc97
+SHA512:
+  metadata.gz: e55317c039f546f59937c1026cfda8597df9908a481cc5783c7e8607226f7d79b80858befddb7594c1b223a00f0d73fb7d8f9765193e45a8786bb1054386a858
+  data.tar.gz: f310751f2756d97a75dba555046a2f54f6be863e5e8531abdb82007a4700e896a1beffb7bc71092680a538dd5e000d852a4da7771df4d3cb8033e43c79bfd855

data/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Swappable Typst compilation backends: a `:cli` backend (shells out to the
+  Typst executable, the original behavior) and a `:gem` backend (uses the
+  `typst` RubyGem to compile in-process when installed), selected
+  automatically via `TypstRails::Backends::Registry` or set explicitly with
+  `TypstRails.configure { |c| c.backend = :gem }`. Custom backends can be
+  registered for other compilation strategies.
+- Docker-based end-to-end tests (`e2e-docker/`, `rake e2e:docker`) covering
+  the backend auto-detection matrix (CLI-only, gem-only, both, neither) and a
+  fresh `gem build` + `gem install` smoke test, independent of the local dev
+  environment.
+- Comprehensive YARD documentation for all public APIs
+- Enhanced gemspec metadata with bug tracker and documentation URIs
+- MFA requirement for RubyGems publishing
+- CHANGELOG.md following Keep a Changelog format
+- SECURITY.md with security reporting process
+
+### Changed
+- Improved module and class documentation with examples
+- Enhanced gemspec description with clearer value proposition
+- Updated author email to commercial@durableprogramming.com
+
+### Fixed
+- `Backends::Cli#available?` raised `NoMethodError` when the gem was loaded
+  via a bare `require "typst_rails/renderer"`, because `executable_path` read
+  `TypstRails.configuration` without checking that the top-level module was
+  loaded. Safe navigation did not help: the method itself was undefined. The
+  fault was masked wherever the `typst` gem is installed, since the `:gem`
+  backend is selected first and `Cli#available?` is never reached.
+- `TypstRails.configuration.typst_executable_path` is now actually used by
+  the CLI backend when compiling (previously ignored, so the setting had no
+  effect).
+
+## [0.1.0] - 2024-01-XX (Initial Release)
+
+### Added
+- Core Typst rendering functionality via `TypstRails::Renderer`
+- Automatic framework detection for Rails, Rage, and Sinatra
+- Rails integration with `.typ` template handler
+- Sinatra helper methods for Typst rendering
+- Rage framework integration
+- Standalone Ruby support (no framework required)
+- Helper methods for text escaping, HTML/Markdown conversion, and URL encoding
+- Comprehensive test suite with unit and E2E tests
+- Code coverage reporting with SimpleCov
+- RuboCop configuration for code quality
+- Support for ERB preprocessing in Typst templates
+- Automatic data binding from Rails view contexts
+- JSON-based data passing to Typst templates
+- Error handling with detailed error messages
+- Temporary file management with automatic cleanup
+
+### Security
+- Input validation for template source size (10MB limit)
+- Safe handling of temporary files with proper cleanup
+- Argument validation for all public methods
+
+[Unreleased]: https://github.com/durable-oss/typst-rails/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/durable-oss/typst-rails/releases/tag/v0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Durable Programming Team
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,264 @@
+# Typst Rails
+
+[![CI](https://github.com/durable-oss/typst-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/durable-oss/typst-rails/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/typst-rails.svg)](https://rubygems.org/gems/typst-rails)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](MIT-LICENSE)
+
+`TypstRails` provides helpers for using [Typst](https://typst.app/) typesetting system with Ruby applications. Generate high-quality PDFs from Typst templates with seamless framework integration for Rails, Rage, and Sinatra. TypstRails can be used with either the typst gem or with a typst CLI.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'typst-rails'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install typst-rails
+```
+
+# Rails Usage
+
+`.typ` templates are automatically registered and work just like ERB templates:
+
+```ruby
+# app/controllers/reports_controller.rb
+class ReportsController < ApplicationController
+  def monthly
+    @title = "Monthly Report"
+    @author = "Durable Systems Inc."
+
+    respond_to do |format|
+      format.pdf { render template: "reports/monthly" }
+    end
+  end
+end
+```
+
+```typst
+<%# app/views/reports/monthly.typ %>
+<% data = { title: @title, author: @author } %>
+#let data = json("typst_data.json")
+
+= #data.title
+
+Author: #data.author
+
+Generated on <%= Time.now.strftime("%Y-%m-%d") %>
+```
+
+### Rage Integration
+
+Rage support is automatically enabled when the Rage framework is detected. Template integration follows Rage's conventions.
+
+### Sinatra Integration
+
+When Sinatra is detected, a `typst` helper method is available:
+
+```ruby
+require 'sinatra'
+require 'typst_rails'
+
+get '/report.pdf' do
+  typst 'templates/report.typ', {
+    title: "Monthly Report",
+    author: "Durable Systems Inc."
+  }
+end
+```
+
+### Helpers
+
+The gem provides several helper methods for working with Typst templates:
+
+#### Text Escaping
+
+```ruby
+escape_typst("Price: $100")  # => "Price: \\$100"
+escape_typst("Hello #world") # => "Hello \\#world"
+```
+
+#### HTML to Markdown/Typst Conversion
+
+```ruby
+# Convert HTML to Markdown
+html_to_markdown("<h1>Title</h1><p>Content</p>")
+# => "# Title\n\nContent"
+
+# Convert HTML directly to Typst
+html_to_typst("<h1>Title</h1>")
+# => "= Title\n\n"
+
+# Sanitize HTML before conversion
+sanitize_html('<script>alert("xss")</script><p>Safe</p>')
+# => "<p>Safe</p>"
+```
+
+#### Markdown Conversion
+
+```ruby
+# Convert Markdown to Typst syntax
+markdown_to_typst("# Title\n## Subtitle")
+# => "= Title\n== Subtitle"
+
+# Include external Markdown files
+include_markdown("./content.md")
+# Reads and converts the file to Typst syntax
+```
+
+#### URL Encoding
+
+```ruby
+url_encode("hello world") # => "hello+world"
+```
+
+These helpers are available in:
+- ERB templates (Rails) - use directly: `<%= escape_typst(@text) %>`
+- Plain Ruby code - include `TypstRails::Helpers` module
+- The renderer includes these helpers automatically
+
+### Configuration
+
+```ruby
+TypstRails.configure do |config|
+  config.typst_executable_path = "/custom/path/to/typst"
+  config.default_root_path = Rails.root.join("app", "assets", "typst")
+end
+```
+
+### Compilation Backends
+
+`TypstRails` compiles documents through a pluggable backend. Two backends ship
+with the gem:
+
+- **`:cli`** shells out to the `typst` executable. This is the original
+  approach and requires Typst to be [installed separately](https://typst.app/docs/tutorial/setup/)
+  and available on `PATH`.
+- **`:gem`** uses the [`typst`](https://rubygems.org/gems/typst) RubyGem, a
+  native extension that compiles in-process—no subprocess or separate Typst
+  install required. Add it to your Gemfile to enable it:
+
+  ```ruby
+  gem "typst"
+  ```
+
+By default (`config.backend = :auto`), TypstRails prefers the `typst` gem
+when it's installed and falls back to the CLI otherwise. Force a specific
+backend if you need to:
+
+```ruby
+TypstRails.configure do |config|
+  config.backend = :gem # or :cli
+end
+```
+
+You can also register your own backend—for example, to compile against a
+remote Typst service:
+
+```ruby
+class MyRemoteBackend < TypstRails::Backends::Base
+  def available?
+    true
+  end
+
+  def compile(typ_path, root_dir)
+    # ... return PDF bytes, or raise TypstRails::Error on failure
+  end
+end
+
+TypstRails::Backends::Registry.register(:my_remote, MyRemoteBackend.new)
+TypstRails.configure { |config| config.backend = :my_remote }
+```
+
+## Testing
+
+The gem includes comprehensive testing at multiple levels:
+
+### Unit Tests
+
+Run the unit test suite:
+
+```bash
+bundle exec rake test
+```
+
+Tests cover:
+- Framework detection (Rails, Rage, Sinatra)
+- Core renderer functionality
+- Error handling and edge cases
+- All helper methods
+- Input validation and defensive programming
+
+### End-to-End Tests
+
+**Requires Typst to be installed.**
+
+The E2E tests process real ERB templates using all helpers and compile them with Typst to generate actual PDFs:
+
+```bash
+# Run E2E tests
+bundle exec rake e2e
+
+# Run all tests (unit + E2E)
+bundle exec rake test_all
+
+# Clean up generated test outputs
+bundle exec rake clean_e2e
+```
+
+E2E tests verify:
+- Text escaping with real Typst special characters
+- HTML to Typst conversion with actual compilation
+- Markdown to Typst syntax transformation
+- External Markdown file inclusion
+- Complex real-world templates with multiple helpers
+
+See [e2e-tests/README.md](e2e-tests/README.md) for detailed documentation.
+
+### Docker End-to-End Tests
+
+**Requires Docker.**
+
+Verifies backend auto-detection (`:cli` vs `:gem`) across isolated container
+environments, and that the gem works correctly when built and installed like
+a real release rather than loaded from the working tree:
+
+```bash
+bundle exec rake e2e:docker
+```
+
+See [e2e-docker/README.md](e2e-docker/README.md) for detailed documentation.
+
+### Code Coverage
+
+```bash
+bundle exec rake test
+# Coverage report will be in coverage/index.html
+open coverage/index.html
+```
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests (note: currently, the gem has a basic structure and tests will be expanded with functionality). You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/durable-oss/typst-rails](https://github.com/durable-oss/typst-rails). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](https://www.contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/lib/tasks/typst_rails/tasks.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# desc "Explaining what the task does"
+# task :typst_rails do
+#   # Task goes here
+# end

data/lib/typst_rails/backends/base.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TypstRails
+  module Backends
+    # Abstract interface for a Typst compilation backend.
+    #
+    # A backend is responsible for turning a Typst source file (plus a root
+    # directory for relative imports) into PDF bytes. Subclasses implement
+    # {#available?} and {#compile}.
+    #
+    # @abstract
+    class Base
+      # @return [Boolean] whether this backend can be used in the current environment
+      #   (e.g. the `typst` executable is on PATH, or the `typst` gem is loaded)
+      def available?
+        raise NotImplementedError, "#{self.class} must implement #available?"
+      end
+
+      # Compiles a Typst source file to PDF.
+      #
+      # @param typ_path [String] path to the .typ source file to compile
+      # @param root_dir [String] root directory for resolving relative imports
+      # @return [String] binary PDF data
+      # @raise [TypstRails::Error] if compilation fails
+      def compile(typ_path, root_dir)
+        raise NotImplementedError, "#{self.class} must implement #compile"
+      end
+    end
+  end
+end

data/lib/typst_rails/backends/cli.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "open3"
+require "typst_rails/backends/base"
+
+module TypstRails
+  module Backends
+    # Compiles Typst documents by shelling out to the `typst` CLI executable.
+    #
+    # This is the original TypstRails backend and remains the default when the
+    # `typst` gem is not installed. It requires Typst to be installed separately
+    # and available on PATH (or at {TypstRails::Configuration#typst_executable_path}).
+    #
+    # @example
+    #   backend = TypstRails::Backends::Cli.new
+    #   backend.available? #=> true, if `typst` is on PATH
+    #   pdf_data = backend.compile("/tmp/doc.typ", "/tmp")
+    class Cli < Base
+      # @param executable_path [String, nil] path to (or name of) the Typst executable.
+      #   Defaults to {TypstRails::Configuration#typst_executable_path}, falling back to "typst".
+      def initialize(executable_path: nil)
+        super()
+        @executable_path = executable_path
+      end
+
+      # @return [Boolean] whether the configured Typst executable can be found
+      def available?
+        return true if File.exist?(executable_path)
+
+        system("which #{executable_path} > /dev/null 2>&1") == true
+      end
+
+      # @see Base#compile
+      def compile(typ_path, root_dir)
+        output_pdf_path = File.join(root_dir, "#{File.basename(typ_path, ".typ")}_output.pdf")
+        cmd = [executable_path, "compile", "--root", root_dir, typ_path, output_pdf_path]
+
+        begin
+          _stdout_str, stderr_str, status = Open3.capture3(*cmd)
+        rescue Errno::ENOENT => e
+          raise Error, "Typst executable not found. Please ensure Typst is installed and in your PATH. (#{e.message})"
+        rescue StandardError => e
+          raise Error, "Failed to execute Typst compiler: #{e.message}"
+        end
+
+        raise_compilation_failure(cmd, stderr_str) unless status.success?
+        read_compiled_pdf(output_pdf_path)
+      ensure
+        safe_unlink(output_pdf_path)
+      end
+
+      private
+
+      # The safe-navigation operator does not help here: TypstRails.configuration
+      # raises NoMethodError when the top-level TypstRails module has not been
+      # loaded, which happens when "typst_rails/renderer" is required on its own.
+      def executable_path
+        @executable_path || configured_executable_path || "typst"
+      end
+
+      def configured_executable_path
+        return nil unless TypstRails.respond_to?(:configuration)
+
+        TypstRails.configuration&.typst_executable_path
+      end
+
+      def read_compiled_pdf(output_pdf_path)
+        raise Error, "Typst compilation succeeded but output file was not created" unless File.exist?(output_pdf_path)
+
+        pdf_data = File.binread(output_pdf_path)
+        raise Error, "Typst compilation produced an empty PDF" if pdf_data.empty?
+
+        pdf_data
+      end
+
+      def raise_compilation_failure(cmd, stderr_str)
+        error_message = "Typst compilation failed.\n"
+        error_message += "Command: #{cmd.join(" ")}\n"
+        error_message += "Stderr: #{stderr_str}" unless stderr_str.empty?
+        raise Error, error_message
+      end
+
+      def safe_unlink(path)
+        File.unlink(path) if path && File.exist?(path)
+      rescue StandardError => e
+        warn "TypstRails: Failed to clean up temp PDF file: #{e.message}"
+      end
+    end
+  end
+end

data/lib/typst_rails/backends/gem.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "typst_rails/backends/base"
+
+module TypstRails
+  module Backends
+    # Compiles Typst documents in-process using the `typst` RubyGem
+    # (https://rubygems.org/gems/typst), a native extension that embeds the
+    # Typst compiler.
+    #
+    # This avoids the cost of spawning a subprocess for every render and does
+    # not require a separately installed `typst` executable. It is used
+    # automatically when the `typst` gem is available; add it to your Gemfile
+    # to opt in:
+    #
+    #   gem "typst"
+    #
+    # @example
+    #   backend = TypstRails::Backends::Gem.new
+    #   backend.available? #=> true, if the `typst` gem is loaded
+    #   pdf_data = backend.compile("/tmp/doc.typ", "/tmp")
+    class Gem < Base
+      # @return [Boolean] whether the `typst` gem is installed and loadable
+      def available?
+        return true if defined?(::Typst::Pdf)
+
+        begin
+          require "typst"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # @see Base#compile
+      def compile(typ_path, root_dir)
+        ::Typst::Pdf.new(file: typ_path, root: root_dir).compiled.document
+      rescue StandardError => e
+        raise Error, "Typst compilation failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/typst_rails/backends/registry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "typst_rails/backends/base"
+
+module TypstRails
+  module Backends
+    # Registry of available Typst compilation backends, and resolver that
+    # picks the right one to use for a given configuration.
+    #
+    # Backends are tried in registration order; the first one whose
+    # {Base#available?} returns true wins. This lets TypstRails prefer the
+    # `typst` gem (fast, in-process) when it's installed, and fall back to
+    # shelling out to the `typst` CLI otherwise.
+    #
+    # @example Registering a custom backend
+    #   TypstRails::Backends::Registry.register(:my_backend, MyBackend.new)
+    #   TypstRails.configure { |c| c.backend = :my_backend }
+    module Registry
+      class << self
+        # @return [Hash{Symbol => Base}]
+        def backends
+          @backends ||= {}
+        end
+
+        # @return [Array<Symbol>] backend names in resolution priority order
+        def priority
+          @priority ||= []
+        end
+
+        # Registers a backend under the given name.
+        #
+        # @param name [Symbol] the backend's identifier (e.g. :gem, :cli)
+        # @param backend [Base] the backend instance
+        # @param priority [Boolean] whether to append this name to the auto-detection order
+        # @return [void]
+        def register(name, backend, priority: true)
+          backends[name.to_sym] = backend
+          self.priority << name.to_sym if priority && !self.priority.include?(name.to_sym)
+        end
+
+        # Resolves which backend to use.
+        #
+        # @param preference [Symbol, Base, nil] an explicit backend name, a backend
+        #   instance, or nil/:auto to pick the first available backend in priority order
+        # @return [Base] the resolved backend
+        # @raise [TypstRails::Error] if no backend is available
+        def resolve(preference = :auto)
+          return preference if preference.is_a?(Base)
+          return fetch_named_backend(preference) if preference && preference != :auto
+
+          auto_detect
+        end
+
+        # Clears all registered backends. Primarily useful for tests.
+        # @return [void]
+        def reset!
+          @backends = {}
+          @priority = []
+        end
+
+        private
+
+        def fetch_named_backend(name)
+          backend = backends[name.to_sym]
+          raise Error, "Unknown Typst backend: #{name.inspect}" unless backend
+
+          backend
+        end
+
+        def auto_detect
+          priority.each do |name|
+            backend = backends[name]
+            return backend if backend&.available?
+          end
+
+          raise Error, "No Typst backend is available. Install the `typst` gem, or " \
+                       "install the Typst CLI and ensure it is on PATH."
+        end
+      end
+    end
+  end
+end

data/lib/typst_rails/backends.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "typst_rails/backends/base"
+require "typst_rails/backends/registry"
+require "typst_rails/backends/cli"
+require "typst_rails/backends/gem"
+
+module TypstRails
+  module Backends
+    # The `typst` gem, when installed, compiles in-process and is preferred
+    # over shelling out. The CLI backend is always registered as a fallback.
+    Registry.register(:gem, Gem.new)
+    Registry.register(:cli, Cli.new)
+  end
+end

data/lib/typst_rails/framework_detection.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module TypstRails
+  # Detects which web framework (if any) is currently loaded
+  module FrameworkDetection
+    def self.rails?
+      defined?(::Rails) && ::Rails.respond_to?(:application)
+    end
+
+    def self.rage?
+      defined?(::Rage::Application)
+    end
+
+    def self.sinatra?
+      defined?(::Sinatra::Base)
+    end
+
+    def self.detected_framework
+      return :rails if rails?
+      return :rage if rage?
+      return :sinatra if sinatra?
+
+      nil
+    end
+  end
+end