kino 0.1.0

data/ext/kino/src/test_support.rs

@@ -0,0 +1,82 @@
+//! Test-only natives proving the Phase 0 primitives: blocking channel takes
+//! under `without_gvl`, UBF interruptibility, and ractor-safe method calls.
+//! Exposed as `Kino::Native::_test_*`; not part of the public API.
+
+use std::collections::HashMap;
+
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::OnceLock;
+
+use parking_lot::Mutex;
+
+use crate::gvl;
+
+struct TestChannel {
+    tx: Mutex<Option<flume::Sender<String>>>,
+    rx: flume::Receiver<String>,
+    interrupted: AtomicBool,
+}
+
+static CHANNELS: OnceLock<Mutex<HashMap<u64, &'static TestChannel>>> = OnceLock::new();
+static NEXT_ID: AtomicU64 = AtomicU64::new(1);
+
+fn channels() -> &'static Mutex<HashMap<u64, &'static TestChannel>> {
+    CHANNELS.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+fn lookup(ruby: &magnus::Ruby, id: u64) -> Result<&'static TestChannel, magnus::Error> {
+    channels().lock().get(&id).copied().ok_or_else(|| {
+        magnus::Error::new(
+            ruby.exception_arg_error(),
+            format!("unknown test channel {id}"),
+        )
+    })
+}
+
+pub fn create(depth: usize) -> u64 {
+    let (tx, rx) = flume::bounded(depth);
+    let chan = Box::leak(Box::new(TestChannel {
+        tx: Mutex::new(Some(tx)),
+        rx,
+        interrupted: AtomicBool::new(false),
+    }));
+    let id = NEXT_ID.fetch_add(1, Ordering::Relaxed);
+    channels().lock().insert(id, chan);
+    id
+}
+
+pub fn push(ruby: &magnus::Ruby, id: u64, value: String) -> Result<(), magnus::Error> {
+    let chan = lookup(ruby, id)?;
+    let guard = chan.tx.lock();
+    let Some(tx) = guard.as_ref() else {
+        return Err(magnus::Error::new(
+            ruby.exception_runtime_error(),
+            "test channel is closed",
+        ));
+    };
+    tx.try_send(value).map_err(|e| {
+        magnus::Error::new(ruby.exception_runtime_error(), format!("push failed: {e}"))
+    })
+}
+
+/// Blocking take, GVL released, interruptible. nil = closed or interrupted
+/// (the VM delivers any pending interrupt right after we return to Ruby).
+pub fn take(ruby: &magnus::Ruby, id: u64) -> Result<Option<String>, magnus::Error> {
+    let chan = lookup(ruby, id)?;
+    chan.interrupted.store(false, Ordering::SeqCst);
+
+    let taken = gvl::interruptible(&chan.interrupted, || {
+        match chan.rx.recv_timeout(crate::queue::TICK) {
+            Ok(v) => Some(Some(v)),
+            Err(flume::RecvTimeoutError::Timeout) => None,
+            Err(flume::RecvTimeoutError::Disconnected) => Some(None),
+        }
+    });
+    Ok(taken.flatten())
+}
+
+pub fn close(ruby: &magnus::Ruby, id: u64) -> Result<(), magnus::Error> {
+    let chan = lookup(ruby, id)?;
+    chan.tx.lock().take();
+    Ok(())
+}

data/ext/kino/src/timer.rs

@@ -0,0 +1,57 @@
+//! High-resolution sleep for worker code. MRI's own `sleep` parks the
+//! thread on the VM timer, whose wakeups inside non-main ractors are
+//! observably coarse (≈+2.5 ms on Linux). This path instead releases the
+//! GVL and uses the OS timer directly (std::thread::sleep → nanosleep),
+//! which is microsecond-accurate regardless of which ractor calls it.
+//!
+//! Only one bounded chunk is slept per call: the caller (Kino.sleep in
+//! Ruby) loops, so pending VM interrupts are processed between chunks and
+//! Thread#kill / shutdown stay responsive within one tick.
+
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::{Duration, Instant};
+
+use magnus::{Error, Ruby};
+
+use crate::gvl::{self, Ubf};
+
+/// Sleep up to `seconds` (capped at one interrupt tick), GVL released.
+/// Returns the seconds actually remaining after this chunk (0.0 = done),
+/// so the Ruby loop knows when to stop.
+pub fn sleep_chunk(ruby: &Ruby, seconds: f64) -> Result<f64, Error> {
+    if !seconds.is_finite() || seconds < 0.0 {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "sleep duration must be a non-negative number",
+        ));
+    }
+
+    let requested = Duration::from_secs_f64(seconds);
+    let chunk = requested.min(crate::queue::TICK);
+    let deadline = Instant::now() + chunk;
+
+    let interrupted = AtomicBool::new(false);
+    gvl::without_gvl(
+        || {
+            // std::thread::sleep retries on EINTR, so the UBF can't cut a
+            // sleep short: the flag is only observed once the chunk ends.
+            // That bounds interrupt latency at one chunk, which is why the
+            // chunk is capped at TICK above.
+            while !interrupted.load(Ordering::Relaxed) {
+                let now = Instant::now();
+                if now >= deadline {
+                    break;
+                }
+                std::thread::sleep(deadline - now);
+            }
+        },
+        Some(Ubf {
+            func: gvl::ubf_interrupt,
+            data: &interrupted as *const _ as *mut c_void,
+        }),
+    );
+
+    let remaining = requested.saturating_sub(chunk);
+    Ok(remaining.as_secs_f64())
+}

data/ext/kino/src/tls.rs

@@ -0,0 +1,96 @@
+//! rustls acceptor construction. Cert/key inputs are either file paths or
+//! inline PEM (detected by the `-----BEGIN` marker), so test fixtures never
+//! need temp files.
+
+use std::io::BufReader;
+use std::sync::Arc;
+
+use tokio_rustls::rustls::pki_types::{CertificateDer, PrivateKeyDer};
+use tokio_rustls::rustls::ServerConfig;
+use tokio_rustls::TlsAcceptor;
+
+fn pem_bytes(input: &str) -> Result<Vec<u8>, String> {
+    if input.contains("-----BEGIN") {
+        Ok(input.as_bytes().to_vec())
+    } else {
+        std::fs::read(input).map_err(|e| format!("cannot read {input}: {e}"))
+    }
+}
+
+pub fn build_acceptor(cert: &str, key: &str) -> Result<TlsAcceptor, String> {
+    let cert_pem = pem_bytes(cert)?;
+    let key_pem = pem_bytes(key)?;
+
+    let certs: Vec<CertificateDer> = rustls_pemfile::certs(&mut BufReader::new(&cert_pem[..]))
+        .collect::<Result<_, _>>()
+        .map_err(|e| format!("invalid certificate PEM: {e}"))?;
+    if certs.is_empty() {
+        return Err("no certificates found in PEM".to_string());
+    }
+
+    let key: PrivateKeyDer = rustls_pemfile::private_key(&mut BufReader::new(&key_pem[..]))
+        .map_err(|e| format!("invalid private key PEM: {e}"))?
+        .ok_or_else(|| "no private key found in PEM".to_string())?;
+
+    let mut config = ServerConfig::builder()
+        .with_no_client_auth()
+        .with_single_cert(certs, key)
+        .map_err(|e| format!("TLS config rejected: {e}"))?;
+    config.alpn_protocols = vec![b"http/1.1".to_vec()];
+
+    Ok(TlsAcceptor::from(Arc::new(config)))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::build_acceptor;
+
+    const CERT: &str = "-----BEGIN CERTIFICATE-----
+MIIBfjCCASWgAwIBAgIUTs9+cVJSzJjy4TSi9YLEd+i4KiIwCgYIKoZIzj0EAwIw
+FDESMBAGA1UEAwwJbG9jYWxob3N0MCAXDTI2MDYxMDE3MjUzNVoYDzIxMjYwNTE3
+MTcyNTM1WjAUMRIwEAYDVQQDDAlsb2NhbGhvc3QwWTATBgcqhkjOPQIBBggqhkjO
+PQMBBwNCAAQCgKc2l0PwJW5CAWzp8uW8iIIaGaPkWJ2lRijROyX9v7f8aSQlb6kE
+wKhI8kG8SbeUc+zbKkzGgRXNaZHY/mAao1MwUTAdBgNVHQ4EFgQUsHZa6iIl6Xho
++EWK6t2Fy9sWAnYwHwYDVR0jBBgwFoAUsHZa6iIl6Xho+EWK6t2Fy9sWAnYwDwYD
+VR0TAQH/BAUwAwEB/zAKBggqhkjOPQQDAgNHADBEAiBZM27gueoioJ9YPb+310NI
+vdrY8C5A0QufP/Y1Bm0OrgIgQz+pJX47iTdoINM49gX/6ekLZgmfjwzilJK37E4z
+gw8=
+-----END CERTIFICATE-----";
+
+    const KEY: &str = "-----BEGIN PRIVATE KEY-----
+MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgSlcfB39H6lv5IqYe
+Q+daLGVt9Bf/i5bf+OnLUKcaZYahRANCAAQCgKc2l0PwJW5CAWzp8uW8iIIaGaPk
+WJ2lRijROyX9v7f8aSQlb6kEwKhI8kG8SbeUc+zbKkzGgRXNaZHY/mAa
+-----END PRIVATE KEY-----";
+
+    #[test]
+    fn inline_pem_builds_an_acceptor() {
+        assert!(build_acceptor(CERT, KEY).is_ok());
+    }
+
+    #[test]
+    fn missing_file_paths_error_without_panicking() {
+        let err = build_acceptor("/nonexistent/cert.pem", "/nonexistent/key.pem")
+            .err().expect("missing files");
+        assert!(err.contains("cannot read"));
+    }
+
+    #[test]
+    fn pem_without_certificates_is_rejected() {
+        let err = build_acceptor(KEY, KEY).err().expect("a key is not a cert");
+        assert!(err.contains("no certificates found"));
+    }
+
+    #[test]
+    fn pem_without_a_key_is_rejected() {
+        let err = build_acceptor(CERT, CERT).err().expect("a cert is not a key");
+        assert!(err.contains("no private key found"));
+    }
+
+    #[test]
+    fn mismatched_cert_and_garbage_key_are_rejected() {
+        let err = build_acceptor(CERT, "-----BEGIN PRIVATE KEY-----\ngarbage\n-----END PRIVATE KEY-----")
+            .err().expect("garbage key");
+        assert!(!err.is_empty());
+    }
+}

data/lib/kino/check.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Kino
+  # The shareability doctor behind `kino --check`: explains WHY an app
+  # can't run in :ractor mode, instead of leaving you to decode
+  # Ractor::IsolationError one ivar at a time.
+  #
+  # The walk is strictly non-mutating: Ractor.make_shareable would freeze
+  # the user's object graph, so we never call it. Instead we recurse into
+  # whatever Ractor.shareable? rejects and name the leaves: instance
+  # variables by path, proc captures by variable name and definition site,
+  # and the class-ivar trap that bites class-style apps (a Class is always
+  # "shareable", but reading its unshareable ivars from a worker ractor
+  # raises on the first request).
+  module Check
+    # Stop after this many findings: the first few name the problem.
+    MAX_FINDINGS = 20
+    # Walk budget, so a pathological object graph cannot hang the check.
+    MAX_NODES = 5_000
+
+    # One named blocker: a path into the object graph plus what is wrong
+    # there.
+    Finding = Struct.new(:path, :message) do
+      # @return [String] "path — message", as printed by the CLI
+      def to_s
+        "#{path} — #{message}"
+      end
+    end
+
+    module_function
+
+    # @param app [#call] a Rack application (or a Class/Module used as one)
+    # @return [Hash] +{shareable: Boolean, findings: Array<Finding>}+
+    def report(app)
+      findings = []
+      seen = {}.compare_by_identity
+      budget = {nodes: 0}
+
+      if app.is_a?(Module)
+        # Classes/modules pass Ractor.shareable? unconditionally, but their
+        # unshareable class-level state is main-ractor-only at runtime.
+        scan_module(app, "app (#{app.inspect})", findings)
+        {shareable: findings.empty?, findings: findings}
+      elsif Ractor.shareable?(app)
+        {shareable: true, findings: []}
+      else
+        walk(app, "app", findings, seen, budget)
+        findings << Finding.new(path: "app", message: unshareable_note(app)) if findings.empty?
+        {shareable: false, findings: findings}
+      end
+    end
+
+    # Pretty-printed report; returns true when the app is ractor-ready.
+    # @param app [#call] a Rack application
+    # @param io [IO] where to print
+    # @return [Boolean]
+    def print_report(app, io: $stdout)
+      result = report(app)
+      if result[:shareable]
+        io.puts CLI.paint("32", "check: app is Ractor-shareable — mode :ractor will work", io: io)
+        true
+      else
+        io.puts CLI.red("check: app is NOT Ractor-shareable", io: io)
+        result[:findings].each { |finding| io.puts "  - #{finding}" }
+        io.puts dim_hint(io)
+        false
+      end
+    end
+
+    def dim_hint(io)
+      CLI.dim(
+        "  hints: freeze config at boot; build endpoints with " \
+        "Ractor.shareable_proc; keep per-worker resources in " \
+        "Ractor.store_if_absent; or run mode :threaded.",
+        io: io
+      )
+    end
+
+    # Recurse into an unshareable object and name its blockers. Shareable
+    # objects return immediately, so callers never need their own guard.
+    def walk(obj, path, findings, seen, budget)
+      return if Ractor.shareable?(obj)
+      return if findings.size >= MAX_FINDINGS
+      return if seen[obj]
+      seen[obj] = true
+      return if (budget[:nodes] += 1) > MAX_NODES
+
+      case obj
+      when Proc
+        scan_proc(obj, path, findings, seen, budget)
+      when Hash
+        scan_ivars(obj, path, findings, seen, budget)
+        obj.each do |key, value|
+          walk(key, "#{path} key #{key.inspect}", findings, seen, budget)
+          walk(value, "#{path}[#{key.inspect}]", findings, seen, budget)
+        end
+        report_leaf(obj, path, findings)
+      when Array
+        scan_ivars(obj, path, findings, seen, budget)
+        obj.each_with_index do |value, index|
+          walk(value, "#{path}[#{index}]", findings, seen, budget)
+        end
+        report_leaf(obj, path, findings)
+      else
+        scan_ivars(obj, path, findings, seen, budget)
+        report_leaf(obj, path, findings)
+      end
+    end
+
+    # A finding is recorded only for leaves: unshareable objects whose
+    # innards gave us nothing more specific to point at.
+    def report_leaf(obj, path, findings)
+      return if obj.instance_variables.any? || obj.is_a?(Proc)
+      return if (obj.is_a?(Hash) || obj.is_a?(Array)) && !obj.frozen?
+
+      findings << Finding.new(path: path, message: unshareable_note(obj))
+    end
+
+    def scan_ivars(obj, path, findings, seen, budget)
+      obj.instance_variables.each do |name|
+        value = obj.instance_variable_get(name)
+        next if Ractor.shareable?(value)
+
+        findings << Finding.new(
+          path: "#{path}.#{name}",
+          message: unshareable_note(value)
+        )
+        walk(value, "#{path}.#{name}", findings, seen, budget)
+        break if findings.size >= MAX_FINDINGS
+      end
+      unless obj.frozen? || obj.is_a?(Proc) || obj.is_a?(Module)
+        findings << Finding.new(path: path, message: "#{obj.class} instance is not frozen")
+      end
+    end
+
+    def scan_proc(proc_obj, path, findings, seen, budget)
+      where = proc_obj.source_location&.join(":") || "native"
+      binding = begin
+        proc_obj.binding
+      rescue
+        nil
+      end
+      return unless binding
+
+      receiver = binding.receiver
+      unless Ractor.shareable?(receiver)
+        findings << Finding.new(
+          path: "#{path} (Proc at #{where})",
+          message: "self is not shareable: #{brief(receiver)} — use Ractor.shareable_proc"
+        )
+      end
+      binding.local_variables.each do |name|
+        value = binding.local_variable_get(name)
+        next if Ractor.shareable?(value)
+
+        findings << Finding.new(
+          path: "#{path} (Proc at #{where})",
+          message: "captures `#{name}` = #{brief(value)} (unshareable)"
+        )
+        walk(value, "#{path} capture `#{name}`", findings, seen, budget)
+        break if findings.size >= MAX_FINDINGS
+      end
+    end
+
+    def scan_module(mod, path, findings)
+      mod.instance_variables.each do |name|
+        value = mod.instance_variable_get(name)
+        next if Ractor.shareable?(value)
+
+        findings << Finding.new(
+          path: "#{path}.#{name}",
+          message: "class-level ivar holds #{brief(value)} — classes pass " \
+                   "Ractor.shareable?, but reading this from a worker ractor " \
+                   "raises Ractor::IsolationError on the first request"
+        )
+        break if findings.size >= MAX_FINDINGS
+      end
+    end
+
+    def unshareable_note(obj)
+      if obj.frozen?
+        "#{brief(obj)} is frozen but holds unshareable contents"
+      else
+        "#{brief(obj)} is not frozen"
+      end
+    end
+
+    def brief(obj)
+      inspected = obj.inspect
+      inspected = "#{inspected[0, 60]}..." if inspected.size > 60
+      "#{inspected} (#{obj.class})"
+    rescue
+      "#<#{obj.class}>"
+    end
+
+    private_class_method :dim_hint, :walk, :report_leaf, :scan_ivars,
+      :scan_proc, :scan_module, :unshareable_note, :brief
+  end
+end

data/lib/kino/cli.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "version"
+
+module Kino
+  # The `kino` executable (CLI.start) plus startup presentation shared with
+  # Server.run: the banner, ANSI styling, and the exit credit. Nothing here
+  # is part of the serving API. (The native layer has a twin of `paint` in
+  # style.rs for the few places Rust writes to the terminal.)
+  #
+  # This file deliberately loads no native code: `require "kino"` happens
+  # inside the actions that need it, so --help and --version stay instant.
+  module CLI
+    # The plain banner art: "Kino" in TheDraw's Mindbenders font; {motd}
+    # adds the original three-tone shading.
+    MOTD = <<~BANNER
+      ggg    .o
+      $$$_,o$$P aaa $$$eea,.   .,aaa,.
+      %$$`4eP'  $$$ $$$``$$$% $$$```$$$
+      $$$--`$$o ggg $$$---$$$ $$$---$$$
+      $$$ ░ $$$ $$$ $$$ ░ $$$ $$$ ░ $$$
+      $$$---$$$ $$$ $$$---$$$ $$$---$$$
+      $$$   $$$ $$' $$$   $$$ ^$$aaaS$'
+    BANNER
+
+    # Tone stencil aligned with MOTD, character by character: 1 bright
+    # white, 2 light gray, 3 dark gray; spaces follow the art.
+    MOTD_TONES = <<~BANNER
+      111    11
+      111111111 111 11111111   1111111
+      11111111  111 111111111 111111111
+      111331111 111 111333111 111333111
+      111 3 322 122 111 3 322 112 3 122
+      111333322 223 111333223 123333223
+      112   233 333 222   333 122233332
+    BANNER
+
+    # The basic-palette SGR code for each stencil tone.
+    TONE_SGR = {"1" => "97", "2" => "37", "3" => "90"}.freeze
+
+    private_constant :MOTD_TONES, :TONE_SGR
+
+    module_function
+
+    # True when output to `io` may use ANSI styling.
+    # @param io [IO]
+    # @return [Boolean]
+    def color?(io = $stdout)
+      io.tty? && ENV["NO_COLOR"].nil? && ENV["TERM"] != "dumb"
+    end
+
+    # Wrap `text` in an SGR code ("1" bold, "31" red, "38;5;N" 256-color),
+    # resetting at the end; plain when `io` is not a color terminal.
+    #
+    # @param code [String] an SGR code
+    # @param text [String]
+    # @param io [IO] the stream the text is destined for (gates coloring)
+    # @return [String]
+    def paint(code, text, io: $stdout)
+      color?(io) ? "\e[#{code}m#{text}\e[0m" : text
+    end
+
+    # Startup-output styling, same gray family as the banner.
+    # @return [String]
+    def dim(text, io: $stdout)
+      paint("38;5;243", text, io: io)
+    end
+
+    # Bold styling for headings and the Action!/Fin. bookends.
+    # @return [String]
+    def bold(text, io: $stdout)
+      paint("1", text, io: io)
+    end
+
+    # Errors are red (gated on stderr unless another io is given).
+    # @return [String]
+    def red(text, io: $stderr)
+      paint("91", text, io: io)
+    end
+
+    # The banner with its three-tone shading applied per character.
+    # @param color [Boolean]
+    # @return [String]
+    def motd(color: color?)
+      return MOTD unless color
+
+      MOTD.lines.zip(MOTD_TONES.lines).map do |art, tones|
+        current = nil
+        line = art.chomp.each_char.with_index.map { |char, i|
+          sgr = TONE_SGR[tones.to_s[i]]
+          if char != " " && sgr && sgr != current
+            current = sgr
+            "\e[#{sgr}m#{char}"
+          else
+            char
+          end
+        }.join
+        "#{line}\e[0m\n"
+      end.join
+    end
+
+    # One-line stats dump (the SIGUSR1 handler's output).
+    # @param stats [Hash{Symbol => Object}] see {Kino::Server#stats}
+    # @return [String]
+    def stats_line(stats)
+      dim("Kino stats: #{stats.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}")
+    end
+
+    # The two banner halves around Server#start: credits before, the ready
+    # block plus a bold "Action!" after, once mode and port are known.
+    # Server.run is the one caller; the kino CLI funnels into it.
+    # @return [void]
+    def opening_credits
+      puts motd
+      puts dim("\nKino #{VERSION} presents:")
+    end
+
+    # @param server [Kino::Server] a started server
+    # @return [void]
+    def action!(server)
+      puts dim("- mode:      #{server.mode}")
+      puts dim("- listening: http#{"s" if server.tls?}://#{server.bind}:#{server.port}")
+      puts dim("- Ctrl-C to drain and stop")
+      puts "\n#{bold("Action!")}\n\n"
+    end
+
+    # Roll credits when the process ends: normal exit or crash (at_exit
+    # also runs after an uncaught exception; only a force-exit skips it).
+    # @return [void]
+    def fin_at_exit
+      return if @fin_registered
+
+      @fin_registered = true
+      at_exit { $stdout.puts bold("\nFin.\n") }
+    end
+
+    # The `kino` executable: parse flags, then init/check/serve. Returns
+    # the process exit status (exe/kino passes it to Kernel#exit), except
+    # for -v and -h, which print and exit in place per optparse convention.
+    #
+    # @param argv [Array<String>] command-line arguments (consumed)
+    # @return [Integer] process exit status
+    def start(argv)
+      options = {overrides: {}}
+      parser = option_parser(options)
+      parser.parse!(argv)
+
+      return write_sample(options[:init_path]) if options[:init_path]
+
+      config = resolve_config(options)
+
+      # Precedence for the rackup file: positional arg > `rackup` in config > config.ru
+      rackup_file = argv.first || config[:rackup] || "config.ru"
+      unless File.exist?(rackup_file)
+        warn red("Kino: #{rackup_file} not found")
+        puts
+        print_help(parser)
+        return 1
+      end
+
+      ENV["RACK_ENV"] ||= config[:environment] if config[:environment]
+
+      app = Rack::Builder.parse_file(rackup_file)
+      app = app.first if app.is_a?(Array) # rack < 3 compat
+
+      return Check.print_report(app) ? 0 : 1 if options[:check]
+
+      serve(app, config)
+      0
+    end
+
+    # Bun-style colored help, generated from the parser's own switch list
+    # so it can never drift from the real options.
+    def print_help(parser)
+      puts "#{bold("Kino")}#{dim(": high-performance Ractor web server for Ruby")}"
+      puts
+      puts "#{bold("Usage:")} kino #{paint("36",
+        "[options]")} #{paint("36",
+          "[rackup file]")}#{dim("   (default: config.ru)")}"
+      puts
+      puts bold("Options:")
+      parser.top.list.each do |switch|
+        next unless switch.is_a?(OptionParser::Switch) && switch.desc.any?
+
+        flags = [*switch.short, *switch.long].join(", ")
+        flags += " #{switch.arg.strip}" if switch.arg
+        puts "  #{paint("36", flags.ljust(24))} #{dim(switch.desc.join(" "))}"
+      end
+      puts
+      puts bold("Examples:")
+      puts "  #{paint("36", "kino --init")}#{dim("              write a documented kino.rb")}"
+      puts "  #{paint("36", "kino")}#{dim("                     serve config.ru on :9292")}"
+      puts "  #{paint("36", "kino --check app.ru")}#{dim("      explain Ractor-shareability")}"
+    end
+
+    def option_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: kino [options] [rackup file (default: config.ru)]"
+        opts.on("-C", "--config FILE", "Config file (default: kino.rb if present)") { |v| options[:config_file] = v }
+        opts.on("--init [PATH]", "Write a commented sample config (default: kino.rb) and exit") do |v|
+          options[:init_path] = v || "kino.rb"
+        end
+        opts.on("--check", "Load the app and report Ractor-shareability, then exit") { options[:check] = true }
+        opts.on("-b", "--bind HOST", "Bind address") { |v| options[:overrides][:bind] = v }
+        opts.on("-p", "--port PORT", Integer, "Port") { |v| options[:overrides][:port] = v }
+        opts.on("-w", "--workers COUNT", Integer, "Worker count") { |v| options[:overrides][:workers] = v }
+        opts.on("-t", "--threads COUNT", Integer, "Threads per worker") { |v| options[:overrides][:threads] = v }
+        opts.on("-m", "--mode MODE", "auto | ractor | threaded") { |v| options[:overrides][:mode] = v.to_sym }
+        opts.on("-v", "--version") do
+          puts "kino #{VERSION}"
+          exit
+        end
+        opts.on_tail("-h", "--help", "Show this help") do
+          print_help(opts)
+          exit
+        end
+      end
+    end
+
+    def write_sample(path)
+      require "kino"
+      Configuration.write_sample(path)
+      puts "Kino: wrote sample config to #{path}"
+      0
+    rescue Kino::Error => e
+      warn red("kino: #{e.message}")
+      1
+    end
+
+    # Resolve the full configuration once: file + CLI flag overrides.
+    def resolve_config(options)
+      require "kino"
+      require "rack"
+
+      config_file = options[:config_file]
+      config_file ||= ("kino.rb" if File.exist?("kino.rb"))
+
+      config = Configuration.new
+      config.load_file(config_file) if config_file
+      config.merge!(options[:overrides])
+      # Default port 9292 when neither the file nor a flag chose one.
+      config.set(:port, 9292) unless config.set?(:port)
+      config
+    end
+
+    def serve(app, config)
+      Server.run(app, **config.server_options)
+    end
+
+    private_class_method :print_help, :option_parser, :write_sample,
+      :resolve_config, :serve
+  end
+end