tokra 0.0.1.pre.1

data/lib/tokra/native.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Tokra
+  # Native Rust bindings for tao (windowing) and wry (WebView).
+  #
+  # These classes are thin wrappers around the Rust FFI layer.
+  # All application logic should remain in Ruby; these are "dumb pipes"
+  # for platform-native operations only.
+  #
+  # ## Thread Safety
+  #
+  # EventLoop, Window, and WebView are main-thread-only types. They use
+  # Tauri's pattern of `unsafe impl Send` with the invariant that all
+  # access happens on the main thread via the event loop callback.
+  #
+  # Only Proxy is genuinely Send-safe and can be shared with Worker Ractors.
+  #
+  # @example Basic usage
+  #   event_loop = Tokra::Native::EventLoop.new
+  #   proxy = event_loop.create_proxy
+  #
+  #   window = Tokra::Native::Window.new(event_loop)
+  #   window.set_title("My App")
+  #   window.set_size(800, 600)
+  #
+  #   ipc_handler = Ractor.shareable_proc { |msg| puts msg }
+  #   webview = Tokra::Native::WebView.new(window, "https://example.com", ipc_handler, proxy)
+  #
+  #   event_loop.run do |event|
+  #     case event
+  #     when Tokra::Native::IpcEvent
+  #       puts "IPC: #{event.message}"
+  #     when Tokra::Native::WakeUpEvent
+  #       puts "Wake: #{event.payload}"
+  #     when Tokra::Native::WindowCloseEvent
+  #       puts "Goodbye!"
+  #     end
+  #   end
+  #
+  # @see Tokra::Native::EventLoop
+  # @see Tokra::Native::Window
+  # @see Tokra::Native::WebView
+  # @see Tokra::Native::Proxy
+  module Native
+    # Native classes defined in Rust extension:
+    #
+    # - EventLoop: Main thread event loop
+    #   - .new -> EventLoop
+    #   - #create_proxy -> Proxy (must call before #run)
+    #   - #run(callback) -> never returns
+    #
+    # - Window: Native window
+    #   - .new(event_loop) -> Window
+    #   - #set_title(string)
+    #   - #set_size(width, height)
+    #   - #id -> String
+    #
+    # - WebView: WebKit/WebView2 webview
+    #   - .new(window, url, ipc_callback, proxy) -> WebView
+    #   - #eval(js_string)
+    #
+    # - Proxy: Thread-safe handle (genuinely Send-safe)
+    #   - #wake_up(payload) - Send wake event to main thread
+    #
+    # - IpcEvent: Event fired when WebView sends IPC message
+    #   - #message -> String
+    #
+    # - WakeUpEvent: Event fired when Proxy#wake_up is called
+    #   - #payload -> String
+    #
+    # - WindowCloseEvent: Event fired when window close is requested
+  end
+end

data/lib/tokra/rack/handler.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "uri"
+require "stringio"
+
+module Rack # :nodoc:
+  module Handler # :nodoc:
+    # Tokra Rack Handler - Bridge between tokra:// custom protocol and Rack apps.
+    #
+    # This allows any Rack application (Rails, Roda, Sinatra, etc.) to run inside
+    # a Tokra desktop window without a TCP server. The WebView makes requests to
+    # +tokra://localhost/path+ and this handler translates them to Rack calls.
+    #
+    # == Usage
+    #
+    # The simplest way to run a Rack app in a desktop window:
+    #
+    #   Rack::Handler::Tokra.run(MyRodaApp)
+    #
+    # With options:
+    #
+    #   Rack::Handler::Tokra.run(MyRodaApp, title: "My App", width: 800, height: 600)
+    #
+    # This follows the standard Rack handler interface, so it works with +rackup+:
+    #
+    #   rackup -s tokra config.ru
+    #
+    class Tokra
+      MAX_REDIRECTS = 10 # :nodoc:
+
+      # Default window configuration
+      DEFAULT_OPTIONS = {
+        title: "Tokra",
+        width: 800.0,
+        height: 600.0,
+      }.freeze
+
+      class << self
+        # Run a Rack application in a Tokra desktop window.
+        #
+        # This is the primary entry point, handling all wiring automatically:
+        # - Creates the event loop, proxy, window, and webview
+        # - Registers the tokra:// protocol handler
+        # - Dispatches HTTP requests to the Rack app
+        # - Runs the event loop until the window closes
+        #
+        # +app+ is any Rack application (responds to #call).
+        # +options+ may include:
+        # - +:title+ - Window title (default: "Tokra")
+        # - +:width+ - Window width in pixels (default: 800)
+        # - +:height+ - Window height in pixels (default: 600)
+        #
+        # == Example
+        #
+        #   class MyApp < Roda
+        #     route { |r| r.root { "Hello" } }
+        #   end
+        #
+        #   Rack::Handler::Tokra.run(MyApp.freeze.app)
+        #
+        def run(app, **options)
+          opts = DEFAULT_OPTIONS.merge(options)
+
+          # Create Tokra components
+          event_loop = ::Tokra::Native::EventLoop.new
+          proxy = event_loop.create_proxy
+
+          window = ::Tokra::Native::Window.new(event_loop)
+          window.set_title(opts[:title])
+          window.set_size(opts[:width].to_f, opts[:height].to_f)
+
+          # Create the handler
+          handler = new(app, proxy)
+
+          # Create WebView with tokra:// protocol
+          ::Tokra::Native::WebView.new_with_protocol(window, proxy)
+
+          # Run the event loop, dispatching HTTP requests to the Rack app
+          event_loop.run(
+            lambda { |event|
+              handler.call(event) if event.is_a?(::Tokra::Native::HttpRequestEvent)
+            }
+          )
+        end
+      end
+
+      # Create a new Rack handler.
+      #
+      # +app+ is any Rack application (responds to #call).
+      # +proxy+ is the Tokra::Native::Proxy for responding to requests.
+      #
+      # Note: For most use cases, prefer +Rack::Handler::Tokra.run(app)+
+      # which handles all setup automatically.
+      def initialize(app, proxy)
+        @app = app
+        @proxy = proxy
+      end
+
+      # Handle an HTTP request event from the custom protocol.
+      #
+      # This method:
+      # 1. Translates the HttpRequestEvent into a Rack environment
+      # 2. Calls the Rack app
+      # 3. Follows redirects internally (WKWebView doesn't follow redirects for custom protocols)
+      # 4. Sends the final response back through the protocol
+      def call(event)
+        uri = URI.parse(event.uri)
+        env = build_env(uri, event.method, event.body)
+
+        # Follow redirects internally (WKWebView doesn't follow for custom protocols)
+        redirect_count = 0
+        cookies = nil
+
+        loop do
+          status, headers, body = @app.call(env)
+
+          # Check for redirect (3xx with Location header)
+          if (300..399).cover?(status) && headers["location"]
+            body.close if body.respond_to?(:close)
+
+            redirect_count += 1
+            if redirect_count > MAX_REDIRECTS
+              break respond_with_error(event.request_id, 508, "Too many redirects")
+            end
+
+            # Capture Set-Cookie for the next request (flash/sessions need this)
+            cookies = headers["set-cookie"] if headers["set-cookie"]
+
+            # Follow the redirect with GET (PRG pattern)
+            new_uri = URI.parse(headers["location"])
+            env = build_env(new_uri, "GET", "", cookies)
+            next
+          end
+
+          # Send the response
+          header_pairs = headers.map { |k, v| [k.to_s, v.to_s] }
+
+          body_str = String.new
+          body.each { |chunk| body_str << chunk }
+          body.close if body.respond_to?(:close)
+
+          @proxy.respond(event.request_id, status, header_pairs, body_str)
+          break
+        end
+      end
+
+      private def build_env(uri, method, body, cookies = nil)
+        env = {
+          "REQUEST_METHOD" => method,
+          "SCRIPT_NAME" => "",
+          "PATH_INFO" => uri.path.empty? ? "/" : uri.path,
+          "QUERY_STRING" => uri.query || "",
+          "SERVER_NAME" => uri.host || "localhost",
+          "SERVER_PORT" => (uri.port || 80).to_s,
+          "rack.version" => [2, 0],
+          "rack.url_scheme" => "tokra",
+          "rack.input" => StringIO.new(body),
+          "rack.errors" => $stderr,
+          "rack.multithread" => false,
+          "rack.multiprocess" => false,
+          "rack.run_once" => false,
+        }
+        env["HTTP_COOKIE"] = cookies if cookies
+        env
+      end
+
+      private def respond_with_error(request_id, status, message)
+        @proxy.respond(request_id, status, [["content-type", "text/plain"]], message)
+      end
+    end
+  end
+end

data/lib/tokra/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Tokra
+  # TODO: Document me.
+  VERSION = "0.0.1.pre.1"
+end

data/lib/tokra.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "tokra/version"
+require_relative "tokra/native"
+require_relative "tokra/tokra"
+require_relative "tokra/rack/handler"
+
+# Tokra is a port of Tauri to Ruby.
+module Tokra
+  # TODO: Document me.
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/mise.toml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[tools]
+ruby = "4.0.1"
+python = "3.12"
+pre-commit = "latest"
+rust = "1.93.0"

data/rustfmt.toml

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+edition = "2021"

data/sig/tokra.rbs

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module Tokra
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/tasks/lint.rake

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rubocop/rake_task"
+require "rubycritic/rake_task"
+require "inch/rake"
+
+RuboCop::RakeTask.new
+
+# Run rubycritic in a shell to prevent it from exiting the rake process
+task :rubycritic do
+  sh "bundle exec rubycritic --no-browser exe lib sig"
+end
+
+Inch::Rake::Suggest.new("doc:suggest", "exe/**/*.rb", "lib/**/*.rb", "sig/**/*.rbs") do |suggest|
+  suggest.args << ""
+end
+
+namespace :reuse do
+  desc "Run the REUSE Tool to confirm REUSE compliance"
+  task :lint do
+    sh "reuse lint"
+  end
+
+  desc "Add SPDX headers to files missing them (per AGENTS.md standards)"
+  task :fix do
+    copyright = "Kerrick Long <me@kerricklong.com>"
+
+    # Code files: AGPL-3.0-or-later
+    code_extensions = %w[rb rbs rs rake gemspec rbs toml yml yaml json lock].freeze
+    code_license = "AGPL-3.0-or-later"
+
+    # Documentation files: CC-BY-SA-4.0
+    doc_extensions = %w[md txt].freeze
+    doc_license = "CC-BY-SA-4.0"
+
+    # Find files missing headers (listed after "no copyright and licensing" message)
+    puts "Checking for files missing REUSE headers..."
+    output = `reuse lint 2>&1`
+    in_missing_section = false
+    missing_files = output.lines.filter_map do |line|
+      in_missing_section = true if line.include?("no copyright and licensing")
+      in_missing_section = false if line.start_with?("# ") && !line.include?("copyright")
+      next unless in_missing_section
+
+      line.match(/^\* (.+)/)&.[](1)
+    end
+
+    if missing_files.empty?
+      puts "All files have REUSE headers!"
+    else
+      missing_files.each do |file|
+        ext = File.extname(file).delete(".")
+        license = if code_extensions.include?(ext)
+          code_license
+        elsif doc_extensions.include?(ext)
+          doc_license
+        else
+          puts "  Skipping #{file} (unknown extension: .#{ext})"
+          next
+        end
+
+        puts "  Annotating #{file} with #{license}"
+        sh "reuse annotate --license #{license} --copyright '#{copyright}' --skip-existing '#{file}'", verbose: false
+      end
+    end
+  end
+
+  desc "Normalize Ruby files: frozen_string_literal at top, SPDX in #--/#++ block"
+  task :normalize_ruby do
+    ruby_extensions = %w[rb rake gemspec].freeze
+    ruby_files = Dir.glob("**/*.{#{ruby_extensions.join(',')}}")
+      .reject { |f| f.start_with?("vendor/", "tmp/", ".") }
+
+    fixed_count = 0
+    ruby_files.each do |file|
+      content = File.read(file)
+      original = content.dup
+
+      # Skip if no SPDX header
+      next unless content.match?(/# SPDX-/)
+
+      # Extract components
+      frozen = content.match?(/^# frozen_string_literal: true/)
+      spdx_match = content.match(/(# SPDX-FileCopyrightText:[^\n]+\n(?:#[^\n]*\n)*# SPDX-License-Identifier:[^\n]+\n)/m)
+      next unless spdx_match
+
+      spdx_block = spdx_match[1]
+
+      # Remove existing frozen_string_literal and SPDX block (and any #--/#+++)
+      cleaned = content
+        .sub(/^# frozen_string_literal: true\n+/, "")
+        .sub(/^#--\s*\n/, "")
+        .sub(spdx_block, "")
+        .sub(/^#\+\+\s*\n/, "")
+        .sub(/\A\n+/, "") # Remove leading blank lines
+
+      # Rebuild file in correct order: frozen, blank, #--, SPDX, #++, rest
+      new_content = ""
+      new_content += "# frozen_string_literal: true\n\n" if frozen
+      new_content += "#--\n#{spdx_block}#++\n\n"
+      new_content += cleaned.sub(/\A\n+/, "") # Ensure no double blank lines
+
+      if new_content != original
+        File.write(file, new_content)
+        puts "  Normalized #{file}"
+        fixed_count += 1
+      end
+    end
+
+    puts fixed_count.zero? ? "All Ruby files properly normalized!" : "Fixed #{fixed_count} files."
+  end
+end
+task(:reuse) { Rake::Task["reuse:lint"].invoke }
+
+namespace :lint do
+  task :safe_rdoc_coverage do
+    sh "bundle exec rake rdoc:coverage"
+  end
+
+  task docs: %w[rdoc:coverage rubycritic reuse:lint]
+  task code: %w[rubocop rubycritic lint:rust]
+  task licenses: %w[reuse:lint]
+  task all: %w[docs code licenses]
+
+  namespace :fix do
+    desc "Auto-fix RuboCop offenses (most aggressive)"
+    task :rubocop do
+      sh "bundle exec rubocop --autocorrect-all"
+    end
+
+    desc "Add SPDX headers and normalize Ruby file structure"
+    task reuse: %w[reuse:fix reuse:normalize_ruby]
+
+    desc "Run all auto-fix tasks"
+    task all: %w[lint:fix:rubocop lint:fix:reuse rust:fmt:fix]
+  end
+end
+
+desc "Run all lint auto-fix tasks"
+task("lint:fix") { Rake::Task["lint:fix:all"].invoke }
+
+# Aliases for convenience
+task "rubocop:autocorrect_all" => "lint:fix:rubocop"
+
+desc "Run all lint tasks"
+task(:lint) { Rake::Task["lint:all"].invoke }

data/tasks/rust.rake

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+class ClippyExceptions
+  def self.load(path) = new.tap { |e| e.instance_eval(File.read(path)) }
+  def allow(path, line:, reason:) = list << "#{path}:#{line}"
+  def to_a = list
+  def list = @list ||= []
+end
+
+namespace :rust do
+  desc "Check Rust formatting with cargo fmt"
+  task :fmt do
+    sh "cargo fmt --check"
+  end
+
+  namespace :fmt do
+    desc "Auto-fix Rust formatting with cargo fmt"
+    task :fix do
+      sh "cargo fmt"
+    end
+  end
+
+  desc "Run Clippy with strict settings (configured in Cargo.toml)"
+  task :clippy do
+    sh "cargo clippy -- -D warnings"
+  end
+
+  desc "Fast type checking with cargo check"
+  task :check do
+    sh "cargo check"
+  end
+
+  desc "Forbid #[allow(clippy::...)] except approved exceptions"
+  task :no_allows do
+    exceptions = ClippyExceptions.load(File.expand_path("../clippy_exceptions.rb", __dir__))
+
+    violations = Dir.glob("ext/**/*.rs")
+      .reject { |f| f.include?("/target/") }
+      .flat_map { |file| File.readlines(file).map.with_index(1) { |line, n| [file, n, line] } }
+      .select { |_, _, line| line.include?("#[allow(clippy::") }
+      .reject { |file, n, _| exceptions.to_a.any? { |ex| "#{file}:#{n}".start_with?(ex) } }
+      .map { |file, n, line| "  #{file}:#{n}: #{line.strip}" }
+
+    abort <<~ERROR if violations.any?
+      ❌ Unapproved #[allow(clippy::...)] found:
+      #{violations.join("\n")}
+
+      Add to clippy_exceptions.rb with justification if truly unavoidable.
+    ERROR
+
+    puts "✅ No unapproved Clippy allows found"
+  end
+end
+
+namespace :lint do
+  desc "Run all Rust linting (clippy + fmt check + no unapproved allows)"
+  task rust: %w[rust:clippy rust:fmt rust:no_allows]
+end

data/tasks/steep.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+desc "Run Steep type checker"
+task :steep do
+  sh "bundle exec steep check"
+end

data/tasks/test.rake

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "minitest/test_task"
+
+# Clear the default test task created by Minitest::TestTask if it exists
+Rake::Task["test"].clear if Rake::Task.task_defined?("test")
+
+desc "Run all tests (Rust first, then Ruby)"
+task test: %w[test:rust test:ruby]
+
+namespace :test do
+  desc "Run Rust tests (requires compile)"
+  task rust: :compile do
+    sh "cargo test"
+  end
+
+  # Create a specific Minitest task for Ruby tests
+  Minitest::TestTask.create(:ruby) do |t|
+    t.test_globs = ["test/**/*.rb", "examples/**/test_*.rb"]
+  end
+end

data/test_native.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# !/usr/bin/env ruby
+
+# Basic smoke test for Tokra native extension
+
+require_relative "lib/tokra"
+
+puts "Tokra v#{Tokra::VERSION}"
+puts "Testing native extension load..."
+
+# Test that the module and classes are defined
+raise "Missing Tokra::Native" unless defined?(Tokra::Native)
+raise "Missing EventLoop" unless defined?(Tokra::Native::EventLoop)
+raise "Missing Window" unless defined?(Tokra::Native::Window)
+raise "Missing WebView" unless defined?(Tokra::Native::WebView)
+raise "Missing Proxy" unless defined?(Tokra::Native::Proxy)
+raise "Missing IpcEvent" unless defined?(Tokra::Native::IpcEvent)
+raise "Missing WakeUpEvent" unless defined?(Tokra::Native::WakeUpEvent)
+raise "Missing WindowCloseEvent" unless defined?(Tokra::Native::WindowCloseEvent)
+
+puts "✓ Native extension loaded successfully!"
+puts ""
+puts "Available classes:"
+puts "  Tokra::Native::EventLoop"
+puts "  Tokra::Native::Window"
+puts "  Tokra::Native::WebView"
+puts "  Tokra::Native::Proxy"
+puts "  Tokra::Native::IpcEvent"
+puts "  Tokra::Native::WakeUpEvent"
+puts "  Tokra::Native::WindowCloseEvent"