dontsleep 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80681d16f63de71323f7c06ccaa0ac303281a92f6328e0bdd0ec1365249aba39
+  data.tar.gz: cce2043955e99caf1b6da08f29cc7547c250febc89368df3b6b9207b620e45a5
+SHA512:
+  metadata.gz: 687a3a4adb246381321e6649145039c773e01044d1cd53452c88d12c4470c9fe4c7d96ae7b410452c63daf227177d1d6a4a72d54641a6c50fd86a44071e2293d
+  data.tar.gz: dd61512c3bbc18301ae3500dc020bd9c2bf4ebdc70d6dbf953ffd6b45b2f6ba80bdf30c29c79d1243663fb2959982d7eeeefb3946196415c5b340a11e17925c4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andreas Freier
+
+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,75 @@
+# dontsleep
+
+Keep your Mac awake by moving the mouse a couple of pixels.
+
+macOS decides you're "idle" when the mouse and keyboard have been still for a
+while — and then it sleeps, killing your SSH sessions, your builds, your
+downloads, and whatever else was patiently running. `dontsleep` prevents that
+by nudging the cursor **2 pixels** now and then: invisible to you, convincing
+to the operating system.
+
+> **macOS only.** The gem depends on `rumouse`, which drives the mouse through
+> macOS' Core Graphics events. On other platforms it installs fine but refuses
+> to run, with a clear message. (Linux/Windows support: open an issue or send
+> a patch — we'd love that.)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "dontsleep"
+```
+
+or simply:
+
+```sh
+gem install dontsleep
+```
+
+Requires macOS and a Ruby ≥ 2.5 with the `ffi` gem (pulled in automatically).
+You will need to grant your terminal **Accessibility** permission under
+*System Settings → Privacy & Security → Accessibility* — that's macOS asking
+nicely that an app may move the mouse. It asks once.
+
+## Usage
+
+The executable does the job:
+
+```sh
+dontsleep                    # 2px nudge every 60s, runs until you press Ctrl-C
+dontsleep --minutes 120      # …and stops itself after 2 hours
+dontsleep --interval 30      # more frequent, smaller heartbeats
+dontsleep --wander           # old-school mode: teleport to a random spot —
+                             # for unattended machines you're not touching
+dontsleep --quiet            # no heartbeat dots
+```
+
+From Ruby:
+
+```ruby
+require "dontsleep"
+Dontsleep.start(minutes: 60)   # e.g. wrapped around a long build
+```
+
+A `.` is printed with each nudge, so you can see it's alive. Ctrl-C always
+stops it cleanly.
+
+## Why a nudge and not a wander?
+
+The original idea — move the mouse to a random position — works, but every
+minute it *yanks your cursor away* from wherever you're actually clicking.
+A 2-pixel ping-pong (right, left, down, up…) resets the idle timer while
+staying out of your way. `--wander` keeps the classic behavior for machines
+you've left alone.
+
+## Development
+
+```sh
+bundle exec rake        # run tests
+bundle exec rake build  # build the gem
+```
+
+## License
+
+[MIT](LICENSE.txt) — do whatever you like, no warranty, as with all
+small utilities.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/exe/dontsleep

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "dontsleep"
+
+if Dontsleep.on_mac?
+  args = ARGV.dup
+  interval = 60
+  minutes = nil
+  wander = false
+  nudge = 2
+  quiet = false
+
+  while (a = args.shift)
+    case a
+    when "--interval" then interval = args.shift.to_f
+    when "--minutes" then minutes = args.shift.to_i
+    when "--nudge" then nudge = args.shift.to_i
+    when "--wander" then wander = true
+    when "--quiet" then quiet = true
+    when "-h", "--help"
+      puts <<~HELP
+        dontsleep — keep your Mac awake by moving the mouse a little.
+
+        Options:
+          --interval N   seconds between moves (default 60)
+          --minutes N    stop automatically after N minutes (default: run until Ctrl-C)
+          --nudge N      pixels to move (default 2)
+          --wander       teleport to a random spot instead (for unattended machines)
+          --quiet        no heartbeat output
+      HELP
+      exit 0
+    else
+      warn "unknown option: #{a} (see --help)"
+      exit 1
+    end
+  end
+
+  Dontsleep.start(interval: interval, nudge: nudge, minutes: minutes, wander: wander, quiet: quiet)
+else
+  warn "dontsleep only works on macOS (this is #{RbConfig::CONFIG["host_os"]})."
+  exit 1
+end

data/lib/dontsleep/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Dontsleep
+  VERSION = "0.1.0"
+end

data/lib/dontsleep.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "dontsleep/version"
+
+# rumouse (and its ffi dependency) only exists where it can be built —
+# effectively macOS. Keep the require lenient so the gem *installs and loads*
+# anywhere; on other platforms `Dontsleep.start` (and the executable) refuse
+# with a clear message before the mouse is ever needed.
+begin
+  if RbConfig::CONFIG["host_os"] =~ /darwin/
+    require "rumouse"
+  else
+    # Don't even try to load rumouse off-macOS: on Linux it probes X11
+    # libraries and dies with an ugly stack trace. Refuse cleanly instead.
+    module RuMouse
+      def initialize
+        raise Dontsleep::Error,
+              "rumouse could not be loaded — dontsleep needs macOS (and the ffi gem)"
+      end
+    end
+  end
+rescue LoadError
+  module RuMouse
+    def initialize
+      raise Dontsleep::Error,
+            "rumouse could not be loaded — dontsleep needs macOS (and the ffi gem)"
+    end
+  end
+end
+
+# Dontsleep keeps a macOS machine awake by nudging the cursor a couple of
+# pixels now and then, so the system never considers you idle — while your
+# SSH sessions, builds, and downloads keep going through your breaks.
+#
+#   Dontsleep.start                 # 2px ping-pong nudge, every 60s, until Ctrl-C
+#   Dontsleep.start(minutes: 120)   # stop automatically after 120 minutes
+#   Dontsleep.start(wander: true)   # old-school: teleport to a random spot (unattended boxes)
+module Dontsleep
+  class Error < StandardError; end
+
+  def self.start(interval: 60, nudge: 2, minutes: nil, wander: false, quiet: false)
+    raise Error, "dontsleep only supports macOS" unless on_mac?
+
+    mouse = build_mouse
+    deadline = minutes ? Time.now + minutes * 60 : nil
+    positive = true
+
+    until (deadline && Time.now > deadline)
+      real_sleep(interval)
+      move_mouse(mouse, nudge: nudge, wander: wander, positive: positive)
+      positive = !positive # +2, −2, +2, −2 … on one fixed axis: pure ping-pong,
+      # zero drift — the cursor jitters in place instead of walking away
+      print(".") { $stdout.flush } unless quiet
+    end
+    puts
+    "stopped (auto-stop)"
+  rescue Interrupt
+    puts
+    "stopped (goodbye)"
+  end
+
+  def self.on_mac?
+    RbConfig::CONFIG["host_os"] =~ /darwin/ ? true : false
+  end
+
+  # Indirection points so tests can run the loop on a fake mouse / fake clock.
+  def self.build_mouse
+    RuMouse.new
+  end
+
+  def self.real_sleep(seconds)
+    sleep(seconds)
+  end
+
+  def self.move_mouse(mouse, nudge:, wander:, positive:)
+    if wander
+      mouse.move(100 + rand(200), 100 + rand(200))
+    else
+      pos = mouse.position
+      delta = positive ? nudge : -nudge
+      mouse.move(pos[:x] + delta, pos[:y]) # fixed axis (x): the twitch is invisible
+    end
+  end
+end

data/test/test_dontsleep.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "rbconfig"
+require "dontsleep/version"
+require "dontsleep"
+
+# A mouse double: records moves, reports its current position.
+class FakeMouse
+  attr_reader :moves
+
+  def initialize
+    @pos = { x: 500.0, y: 300.0 }
+    @moves = []
+  end
+
+  def position
+    @pos
+  end
+
+  def move(x, y)
+    @pos = { x: x, y: y }
+    @moves << { x: x, y: y }
+  end
+end
+
+# Run N ticks of the *real* move_mouse decision logic against a fake mouse.
+# Mirrors Dontsleep.start's loop: the sign flips every tick on one fixed axis.
+def drive_ticks(mouse, n, wander: false, nudge: 2)
+  positive = true
+  n.times do
+    Dontsleep.move_mouse(mouse, nudge: nudge, wander: wander, positive: positive)
+    positive = !positive
+  end
+end
+class DontsleepTest < Minitest::Test
+  def test_nudge_cancels_out_over_many_ticks
+    mouse = FakeMouse.new
+    start = { x: 500.0, y: 300.0 }
+    drive_ticks(mouse, 1000) # ~16 hours of ticking
+    assert_in_delta start[:x], mouse.position[:x], 2.0 # at most one step off
+    assert_equal start[:y], mouse.position[:y]         # y never moves at all
+  end
+
+  def test_wander_stays_in_its_rectangle
+    mouse = FakeMouse.new
+    drive_ticks(mouse, 50, wander: true)
+    mouse.moves.each do |m|
+      assert_operator m[:x], :>=, 100
+      assert_operator m[:x], :<=, 300
+      assert_operator m[:y], :>=, 100
+      assert_operator m[:y], :<=, 300
+    end
+  end
+
+  def test_platform_guard_is_a_boolean
+    assert [true, false].include?(Dontsleep.on_mac?)
+  end
+
+  # Exercise the real loop with a fake mouse and no waiting.
+  def test_start_loop_auto_stops
+    fake = FakeMouse.new
+    Dontsleep.define_singleton_method(:build_mouse) { fake }
+    Dontsleep.define_singleton_method(:real_sleep) { |_s| }
+    Dontsleep.define_singleton_method(:on_mac?) { true }
+
+    result = Dontsleep.start(interval: 1, minutes: 0.001, quiet: true)
+
+    assert_equal "stopped (auto-stop)", result
+    assert_operator fake.moves.length, :>=, 1
+  ensure
+    # restore the real implementations for any later tests / runs
+    Dontsleep.singleton_class.class_eval <<~RUBY
+      def self.build_mouse
+        RuMouse.new
+      end
+
+      def self.real_sleep(seconds)
+        sleep(seconds)
+      end
+
+      def self.on_mac?
+        RbConfig::CONFIG["host_os"] =~ /darwin/ ? true : false
+      end
+    RUBY
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: dontsleep
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andreas Freier
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rumouse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.7
+description: Prevents macOS sleep — and the broken SSH sessions, builds and downloads
+  that come with it — by nudging the cursor. macOS only.
+email:
+- andreas.freier@googlemail.com
+executables:
+- dontsleep
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/dontsleep
+- lib/dontsleep.rb
+- lib/dontsleep/version.rb
+- test/test_dontsleep.rb
+homepage: https://github.com/andreasfreier/dontsleep
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/andreasfreier/dontsleep
+  source_code_uri: https://github.com/andreasfreier/dontsleep
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.15
+signing_key:
+specification_version: 4
+summary: Keep your Mac awake by moving the mouse a couple of pixels.
+test_files: []