stockshark 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8dcf3f23451283338c0ab09bcf73a1d218b40864ec1238950d65ac40698aab17
+  data.tar.gz: ac7a4ca6772c90c1f989a4f4fa42d756896570c6bc2ff55495a2bb724a0869f4
+SHA512:
+  metadata.gz: 8a03cbc0c0e94c066a22278f369f132414020a18f04bb2dddc39259a2b773c4f352f2ef75c6680dc20448255a121b5a3777ab6b20bbae6254520cefaf8cb534e
+  data.tar.gz: d1329f806ead3a46f7afc6f6270c9c53785797e7487faca0ab5b9b643cb230e3056c802ddb456d8d967cfbd5bf9963c71f6bfa57efb745ba274a1a48032eb559

data/.gitignore

@@ -0,0 +1,6 @@
+/.bundle/
+/Gemfile.lock
+/pkg/
+/spec/reports/
+/spec/examples.txt
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--color

data/.ruby-version

@@ -0,0 +1 @@
+3.4.8

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake', '~> 13.4'
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.88'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phil
+
+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,104 @@
+# Stockshark
+
+A small, dependency-free Ruby wrapper for talking to a UCI-speaking chess
+engine (Stockfish, or anything else that implements the protocol) over
+stdin/stdout/stderr pipes: start it, hand it a FEN, get back a structured
+evaluation (centipawns or mate score, best move, principal variation, depth
+reached). No chess rules engine, no board representation, no opinions about
+perspective or move classification — just the UCI protocol, cleanly
+wrapped.
+
+## Installation
+
+```
+bundle add stockshark
+```
+
+Or add it to your Gemfile directly:
+
+```ruby
+gem "stockshark"
+```
+
+## Usage
+
+```ruby
+engine = Stockshark::Engine.new
+result = engine.analyze(fen: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", depth: 18)
+
+result.best_move        # => "e2e4"
+result.depth            # => 18
+result.lines.first.pv   # => ["e2e4", "e7e5"]
+engine.quit
+```
+
+Pass `movetime_ms:` instead of `depth:` for a time-bounded search, and
+`multipv:` to get more than one ranked line back (`result.lines` is sorted
+by rank, so `lines.first` is always the primary line).
+
+## Configuration
+
+```ruby
+configuration = Stockshark::Configuration.new(threads: 4, hash_mb: 128)
+engine = Stockshark::Engine.new(configuration)
+```
+
+Every option also has an environment variable default (see
+`lib/stockshark/configuration.rb`) — deliberately named `STOCKFISH_*`, not
+`STOCKSHARK_*`, since they configure the actual engine binary being
+launched rather than this library:
+
+- **`STOCKFISH_PATH`** (default `stockfish`) — path to the engine binary,
+  resolved via `$PATH` if not absolute.
+- **`STOCKFISH_THREADS`** (default `1`) — UCI `Threads`.
+- **`STOCKFISH_HASH`** (default `16`) — UCI `Hash`, transposition table
+  size in MB.
+- **`STOCKFISH_MAX_ANALYZE_MS`** (default `30000`) — how long the engine
+  is given to respond before `Stockshark::TimeoutError` is raised.
+
+## Errors
+
+All raised errors descend from `Stockshark::Error`:
+
+- `Stockshark::EngineNotFoundError` — the configured binary doesn't exist,
+  isn't executable, or couldn't be spawned.
+- `Stockshark::TimeoutError` — the engine didn't respond within the
+  configured deadline.
+- `Stockshark::CrashedError` — the engine process exited mid-conversation.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then:
+
+```
+bundle exec rspec                 # fake-engine suite, no binary required
+bundle exec rspec --tag stockfish  # also runs the real-engine integration spec
+```
+
+The `--tag stockfish` run needs an actual Stockfish binary on `$PATH` (or
+pointed to via `STOCKFISH_PATH`) — it's skipped automatically otherwise
+(see `spec/support/stockfish_availability.rb`). Install one with:
+
+```
+brew install stockfish        # macOS
+apt install stockfish         # Debian/Ubuntu
+```
+
+or download a build from [stockfishchess.org/download](https://stockfishchess.org/download).
+
+Run `bin/console` for an interactive prompt with the gem already loaded.
+
+To install this gem onto your local machine, run `bundle exec rake
+install`. To release a new version, bump the version in
+`lib/stockshark/version.rb`, then run `bundle exec rake release`, which
+tags the version, pushes the commit and tag, and pushes the `.gem` file to
+rubygems.org.
+
+## License
+
+MIT — see `LICENSE.txt`.
+
+---
+
+Built by [TrueFlux](https://trueflux.agency).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "stockshark"
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/lib/stockshark/configuration.rb

@@ -0,0 +1,25 @@
+module Stockshark
+  # Environment-driven configuration — nothing here is ever a hardcoded,
+  # machine-specific path. Every value has a sensible default so the
+  # library works out of the box locally, but production is expected to
+  # set these explicitly (particularly STOCKFISH_PATH, since "stockfish"
+  # resolving via $PATH isn't guaranteed on every deploy target). Env var
+  # names stay STOCKFISH_* (not STOCKSHARK_*) deliberately — they configure
+  # the actual Stockfish (or Stockfish-compatible) binary being launched,
+  # which is a separate thing from what this gem happens to be called.
+  class Configuration
+    attr_accessor :path, :threads, :hash_mb, :max_analyze_ms
+
+    def initialize(
+      path: ENV.fetch("STOCKFISH_PATH", "stockfish"),
+      threads: Integer(ENV.fetch("STOCKFISH_THREADS", 1)),
+      hash_mb: Integer(ENV.fetch("STOCKFISH_HASH", 16)),
+      max_analyze_ms: Integer(ENV.fetch("STOCKFISH_MAX_ANALYZE_MS", 30_000))
+    )
+      @path = path
+      @threads = threads
+      @hash_mb = hash_mb
+      @max_analyze_ms = max_analyze_ms
+    end
+  end
+end

data/lib/stockshark/crashed_error.rb

@@ -0,0 +1,4 @@
+module Stockshark
+  # The engine process exited (or was killed) mid-conversation.
+  class CrashedError < Error; end
+end

data/lib/stockshark/engine.rb

@@ -0,0 +1,124 @@
+module Stockshark
+  # The public façade for talking to a UCI engine — the only class most
+  # callers should ever need to touch. Hides process management (Process)
+  # and protocol parsing (UciProtocol) entirely: callers only ever see
+  # "give me a FEN and a depth/movetime, get back an evaluation."
+  class Engine
+    # One multipv rank's worth of a search result: its own score (exactly
+    # one of score_cp/score_mate is ever set, matching UCI itself — an
+    # engine never reports both for the same line) and principal variation.
+    Line = Struct.new(:multipv, :score_cp, :score_mate, :pv, keyword_init: true)
+
+    # The full result of one #analyze call: the move the engine would
+    # actually play, the deepest ply reached, and one Line per multipv
+    # rank requested (ranks are 1-indexed and sorted, so lines.first is
+    # always the primary/best line). Raw and side-to-move-relative —
+    # unopinionated about which color that was.
+    AnalysisResult = Struct.new(:best_move, :depth, :lines, keyword_init: true)
+
+    attr_reader :name
+
+    def initialize(configuration = Stockshark::Configuration.new, process: nil)
+      @configuration = configuration
+      @process = process || Stockshark::Process.new(configuration.path)
+      @multipv = 1
+      handshake
+    end
+
+    def analyze(fen:, depth: nil, movetime_ms: nil, multipv: 1)
+      raise ArgumentError, "must give depth or movetime_ms" unless depth || movetime_ms
+
+      set_multipv(multipv)
+      send_line("position fen #{fen}")
+      send_line(depth ? "go depth #{depth}" : "go movetime #{movetime_ms}")
+
+      collect_result(search_timeout(movetime_ms))
+    end
+
+    # Safe to call more than once, and safe to call even if the engine was
+    # never fully brought up (e.g. handshake itself failed).
+    def quit
+      @process.stop
+    end
+
+    private
+
+    def handshake
+      send_line("uci")
+      await("uciok") { |message| @name = Stockshark::UciProtocol.parse_id(message)&.fetch(:name) || @name }
+
+      send_line("setoption name Threads value #{@configuration.threads}")
+      send_line("setoption name Hash value #{@configuration.hash_mb}")
+      send_line("isready")
+      await("readyok")
+
+      send_line("ucinewgame")
+    end
+
+    def set_multipv(multipv)
+      return if multipv == @multipv
+
+      send_line("setoption name MultiPV value #{multipv}")
+      @multipv = multipv
+    end
+
+    def send_line(line)
+      @process.write_line(line)
+    end
+
+    # Reads lines (via the configured handshake timeout) until `stop_line`
+    # is seen, yielding every line along the way so the caller can pick up
+    # anything useful (like "id name ...") that appears before it.
+    def await(stop_line)
+      deadline = Time.now + (@configuration.max_analyze_ms / 1000.0)
+      loop do
+        message = read(deadline)
+        yield message if block_given?
+        return if message == stop_line
+      end
+    end
+
+    def collect_result(timeout)
+      deadline = Time.now + timeout
+      latest_by_rank = {}
+      max_depth = 0
+
+      loop do
+        message = read(deadline)
+
+        if (info = Stockshark::UciProtocol.parse_info(message))
+          latest_by_rank[info[:multipv]] = info
+          max_depth = [ max_depth, info[:depth] ].max
+        elsif (best = Stockshark::UciProtocol.parse_bestmove(message))
+          lines = latest_by_rank.sort.map do |_, info|
+            Line.new(multipv: info[:multipv], score_cp: info[:score_cp], score_mate: info[:score_mate], pv: info[:pv])
+          end
+          return AnalysisResult.new(best_move: best[:best_move], depth: max_depth, lines: lines)
+        end
+      end
+    end
+
+    # Blocks until a line arrives on stdout or `deadline` passes, skipping
+    # (but not erroring on) stderr activity — Process already drains it
+    # continuously in the background, this just isn't interested in its
+    # content, only in not being blocked by it.
+    def read(deadline)
+      loop do
+        remaining = deadline - Time.now
+        raise Stockshark::TimeoutError, "engine did not respond in time" if remaining <= 0
+        raise Stockshark::CrashedError, "engine process exited unexpectedly" unless @process.alive?
+
+        entry = @process.read_line(timeout: remaining)
+        next if entry.nil?
+        next if entry[:stream] == :stderr
+
+        return entry[:line]
+      end
+    end
+
+    def search_timeout(movetime_ms)
+      base = movetime_ms ? movetime_ms / 1000.0 : 0
+      base + (@configuration.max_analyze_ms / 1000.0)
+    end
+  end
+end

data/lib/stockshark/engine_not_found_error.rb

@@ -0,0 +1,5 @@
+module Stockshark
+  # The configured engine binary doesn't exist, isn't executable, or
+  # couldn't be spawned for some other OS-level reason.
+  class EngineNotFoundError < Error; end
+end

data/lib/stockshark/error.rb

@@ -0,0 +1,6 @@
+module Stockshark
+  # Base class for every error this library raises. Callers that only care
+  # that "something went wrong talking to the engine" can rescue this one
+  # class rather than enumerate every specific failure mode.
+  class Error < StandardError; end
+end

data/lib/stockshark/process.rb

@@ -0,0 +1,81 @@
+require "open3"
+
+module Stockshark
+  # Raw OS process lifecycle for a UCI-speaking engine — spawns it, writes
+  # lines to its stdin, and continuously drains stdout *and* stderr from
+  # dedicated reader threads so neither pipe can ever fill up and block the
+  # child. Draining stderr matters here specifically because the engine
+  # path is operator-configurable: nothing guarantees the binary behind it
+  # is a "pure" build that never writes to stderr, and if it did while
+  # nobody was reading that pipe, the child would block writing to it and
+  # every read on stdout would hang right along with it.
+  #
+  # Zero chess/UCI knowledge on purpose — Engine owns the protocol, this
+  # only owns "a subprocess and its pipes."
+  class Process
+    def initialize(path)
+      @stdin, stdout, stderr, @wait_thread = Open3.popen3(path)
+      @queue = Queue.new
+      @readers = [ reader_thread(stdout, :stdout), reader_thread(stderr, :stderr) ]
+    rescue Errno::ENOENT, Errno::EACCES => e
+      raise Stockshark::EngineNotFoundError, "could not start engine at #{path.inspect}: #{e.message}"
+    end
+
+    def write_line(line)
+      raise Stockshark::CrashedError, "engine process is not running" unless alive?
+
+      @stdin.puts(line)
+    rescue Errno::EPIPE, IOError => e
+      raise Stockshark::CrashedError, "could not write to engine: #{e.message}"
+    end
+
+    # Pops the next available line from either stream, tagged with which
+    # one it came from, waiting at most `timeout` seconds. Returns nil on
+    # timeout — never raises Timeout::Error, deliberately: cancellation
+    # here is just "give up waiting on the queue," not "interrupt whatever
+    # is actually blocking," which is what makes Ruby's Timeout.timeout
+    # unsafe to wrap around real IO.
+    def read_line(timeout:)
+      @queue.pop(timeout: timeout)
+    end
+
+    def alive?
+      @wait_thread.alive?
+    end
+
+    # Safe to call more than once, and safe to call after the process has
+    # already died on its own.
+    def stop
+      return unless alive?
+
+      begin
+        @stdin.puts("quit")
+      rescue Errno::EPIPE, IOError
+        # already gone — nothing left to say goodbye to.
+      end
+
+      unless @wait_thread.join(0.5)
+        ::Process.kill("KILL", @wait_thread.pid)
+        @wait_thread.join
+      end
+    ensure
+      @readers.each(&:kill)
+      @stdin.close unless @stdin.closed?
+    end
+
+    private
+
+    def reader_thread(io, tag)
+      Thread.new do
+        loop do
+          line = io.gets
+          break if line.nil?
+
+          @queue << { stream: tag, line: line.chomp }
+        end
+      rescue IOError
+        # stream closed out from under us during shutdown — fine.
+      end
+    end
+  end
+end

data/lib/stockshark/timeout_error.rb

@@ -0,0 +1,7 @@
+module Stockshark
+  # The engine didn't respond within the configured deadline — either a
+  # genuinely wedged search, or a process that's alive but not speaking
+  # UCI back (e.g. an unexpected build writing diagnostics to stderr and
+  # never reaching readyok/bestmove on stdout).
+  class TimeoutError < Error; end
+end

data/lib/stockshark/uci_protocol.rb

@@ -0,0 +1,53 @@
+module Stockshark
+  # Pure parsing of UCI protocol text into structured Ruby data. No IO, no
+  # process — every method here is a plain string in, hash/nil out, which
+  # is what makes it trivially unit-testable without ever spawning a real
+  # engine. Scores are returned exactly as the engine reports them:
+  # relative to whichever side is to move in the position that was
+  # analyzed. Flipping that to a fixed perspective is a game-aware decision
+  # this module deliberately knows nothing about — that's up to whatever
+  # calls this gem.
+  module UciProtocol
+    module_function
+
+    # "id name Stockfish 16" => { name: "Stockfish 16" }
+    # "id author ..." and any other id line => nil (not what we need).
+    def parse_id(line)
+      match = line.match(/\Aid name (?<name>.+)\z/)
+      return nil unless match
+
+      { name: match[:name] }
+    end
+
+    # "bestmove e2e4 ponder e7e5" => { best_move: "e2e4", ponder: "e7e5" }
+    def parse_bestmove(line)
+      match = line.match(/\Abestmove (?<best_move>\S+)(?: ponder (?<ponder>\S+))?/)
+      return nil unless match
+
+      { best_move: match[:best_move], ponder: match[:ponder] }
+    end
+
+    # "info depth 20 seldepth 28 multipv 1 score cp 34 nodes 12345 pv e2e4 e7e5 g1f3"
+    #   => { depth: 20, multipv: 1, score_cp: 34, score_mate: nil, pv: ["e2e4", "e7e5", "g1f3"] }
+    # "info depth 12 multipv 2 score mate -3 pv ... "
+    #   => { depth: 12, multipv: 2, score_cp: nil, score_mate: -3, pv: [...] }
+    # Returns nil for info lines that don't carry a scored principal
+    # variation (plain "info string ..." diagnostics, "info currmove ...",
+    # etc.) — callers should just skip those.
+    def parse_info(line)
+      return nil unless line.start_with?("info ") && line.include?(" pv ")
+
+      depth = line[/\bdepth (\d+)/, 1]
+      pv = line[/ pv (.+)\z/, 1]
+      return nil unless depth && pv
+
+      {
+        depth: depth.to_i,
+        multipv: (line[/\bmultipv (\d+)/, 1] || "1").to_i,
+        score_cp: line[/\bscore cp (-?\d+)/, 1]&.to_i,
+        score_mate: line[/\bscore mate (-?\d+)/, 1]&.to_i,
+        pv: pv.split(" ")
+      }
+    end
+  end
+end

data/lib/stockshark/version.rb

@@ -0,0 +1,3 @@
+module Stockshark
+  VERSION = "0.1.0"
+end

data/lib/stockshark.rb

@@ -0,0 +1,20 @@
+require_relative "stockshark/version"
+require_relative "stockshark/error"
+require_relative "stockshark/engine_not_found_error"
+require_relative "stockshark/timeout_error"
+require_relative "stockshark/crashed_error"
+require_relative "stockshark/configuration"
+require_relative "stockshark/process"
+require_relative "stockshark/uci_protocol"
+require_relative "stockshark/engine"
+
+# Stockshark::Engine talks to a UCI chess engine (Stockfish, or anything
+# else that speaks the protocol) over stdin/stdout/stderr pipes. Plain Ruby,
+# stdlib only (Open3) — no chess rules engine, no board representation, no
+# opinions about evaluation perspective or move classification, so it stays
+# usable by anything that just needs "FEN in, evaluation out" regardless of
+# what it's built on top of. No autoloader here (unlike when this lived
+# inside a Rails app under Zeitwerk), so every file is required explicitly
+# above, in dependency order.
+module Stockshark
+end

data/stockshark.gemspec

@@ -0,0 +1,28 @@
+require_relative 'lib/stockshark/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'stockshark'
+  spec.version = Stockshark::VERSION
+  spec.authors = ['Phil Brockwell']
+  spec.email = ['phil@trueflux.agency']
+
+  spec.summary = 'A small, dependency-free Ruby wrapper for talking to a UCI chess engine.'
+  spec.description = <<~DESC
+    Stockshark drives any UCI-speaking chess engine (Stockfish, or anything
+    else that implements the protocol) over stdin/stdout/stderr pipes: start
+    it, hand it a FEN, get back a structured evaluation (centipawns or mate
+    score, best move, principal variation, depth reached). No chess rules
+    engine, no board representation, no opinions about perspective or move
+    classification — just the UCI protocol, cleanly wrapped.
+  DESC
+  spec.homepage = 'https://github.com/TrueFlux/stockshark'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+                  .reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  spec.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: stockshark
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Phil Brockwell
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Stockshark drives any UCI-speaking chess engine (Stockfish, or anything
+  else that implements the protocol) over stdin/stdout/stderr pipes: start
+  it, hand it a FEN, get back a structured evaluation (centipawns or mate
+  score, best move, principal variation, depth reached). No chess rules
+  engine, no board representation, no opinions about perspective or move
+  classification — just the UCI protocol, cleanly wrapped.
+email:
+- phil@trueflux.agency
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/stockshark.rb
+- lib/stockshark/configuration.rb
+- lib/stockshark/crashed_error.rb
+- lib/stockshark/engine.rb
+- lib/stockshark/engine_not_found_error.rb
+- lib/stockshark/error.rb
+- lib/stockshark/process.rb
+- lib/stockshark/timeout_error.rb
+- lib/stockshark/uci_protocol.rb
+- lib/stockshark/version.rb
+- stockshark.gemspec
+homepage: https://github.com/TrueFlux/stockshark
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/TrueFlux/stockshark
+  source_code_uri: https://github.com/TrueFlux/stockshark
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A small, dependency-free Ruby wrapper for talking to a UCI chess engine.
+test_files: []