From a8b8fa5acb5a6e6fd6d291e6d409470d84a337aa Mon Sep 17 00:00:00 2001 From: dezween Date: Sun, 12 Jul 2026 04:02:20 +0300 Subject: [PATCH] docs: refresh README for roaming, add CHANGELOG and MIT license --- CHANGELOG.md | 33 ++++++++++++++++ LICENSE | 21 ++++++++++ README.md | 107 +++++++++++++++++++++++++++++++++++++++------------ 3 files changed, 136 insertions(+), 25 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 LICENSE diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..377070f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,33 @@ +# Changelog + +All notable changes to this project are documented here. The format is based on +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project +adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2026-07-12 + +### Added + +- Realistic random cursor roaming: on each interval the cursor glides over a + series of small steps to a fresh uniform-random point within the main + display, bounded to the screen (never off-screen, no drift) and interruptible + mid-glide. +- `-interval` flag (Go duration, default `10s`) and `-quiet` flag (raise the log + level so only warnings and errors print). +- Structured logging via `log/slog`; a startup Accessibility-permission + preflight warning. +- Makefile targets `build` / `run` / `start` / `stop` / `status` / `clean`, with + an `INTERVAL` override (e.g. `make start INTERVAL=3s`). +- Hexagonal (ports & adapters) architecture: a pure domain movement planner, + `Pointer` / `Keeper` ports, `KeeperService`, and a CoreGraphics `CGPointer` + adapter behind `//go:build darwin`. +- Continuous integration (build / lint / test) on macOS; strict golangci-lint; + domain and service unit-test coverage at 100%. +- Prebuilt `sysmon-darwin-arm64` binary attached to the release. + +### Notes + +- The runtime binary has zero third-party dependencies (standard library only). +- macOS on Apple Silicon; requires Accessibility permission to deliver events. + +[1.0.0]: https://github.com/dezween/sysmon/releases/tag/v1.0.0 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9914303 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 dezween + +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. diff --git a/README.md b/README.md index f1dc530..f4486da 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,109 @@ # sysmon -A small Go utility for macOS: it keeps the system "active" by posting a real -mouse-move event every N seconds (which resets the idle timer and prevents the -machine from going idle / into the screensaver). The cursor stays effectively in -place. +[![CI](https://github.com/dezween/sysmon/actions/workflows/ci.yml/badge.svg)](https://github.com/dezween/sysmon/actions/workflows/ci.yml) +![Go](https://img.shields.io/badge/go-1.26-00ADD8?logo=go&logoColor=white) +![Platform](https://img.shields.io/badge/platform-macOS%20arm64-lightgrey?logo=apple) +![Release](https://img.shields.io/badge/release-v1.0.0-brightgreen) +![License](https://img.shields.io/badge/license-MIT-blue) -## Build +A tiny, zero-dependency macOS utility that keeps the machine "active": every +`-interval` it moves the cursor realistically at random across the screen -- a +smooth, human-like glide to a fresh random point -- which resets the system idle +timer so the screen does not sleep and presence status stays active. + +- Realistic random roaming (not a teleport): a multi-step glide to a new random + on-screen point, bounded to the display, no drift, interruptible mid-move. +- Configurable interval, quiet mode, clean SIGINT/SIGTERM shutdown, near-zero + idle CPU. +- Standard-library-only runtime; hexagonal (ports & adapters) architecture. + +## Requirements + +- macOS on Apple Silicon (arm64); Xcode Command Line Tools + (`xcode-select --install`) for cgo. +- **Accessibility permission** for the terminal (or app) you launch it from: + System Settings -> Privacy & Security -> Accessibility. Without it, macOS + silently drops the synthetic mouse events; sysmon warns about this at startup. + +## Install + +### Download the release + +Grab `sysmon-darwin-arm64` from the +[latest release](https://github.com/dezween/sysmon/releases/latest): ```sh -go build -o sysmon . +chmod +x sysmon-darwin-arm64 +xattr -d com.apple.quarantine sysmon-darwin-arm64 # clear Gatekeeper quarantine +./sysmon-darwin-arm64 -interval 10s ``` -You need the Xcode Command Line Tools (`xcode-select --install`) -- it uses cgo -and the ApplicationServices framework. +### Build from source -## Run +```sh +make build # builds ./sysmon from ./cmd/sysmon +``` -Normal run (with logs): +## Usage + +Foreground (Ctrl+C to quit): ```sh -./sysmon +make run # or: make run INTERVAL=3s ``` -Custom interval: +Background (no window): ```sh -./sysmon -interval 30s +make start # default interval 10s +make start INTERVAL=3s +make status +make stop ``` -In the background, with no output (there is no window -- it is a console -program): +Directly: ```sh -nohup ./sysmon -quiet >/dev/null 2>&1 & +./sysmon -interval 30s # every 30s +./sysmon -quiet -interval 10s # suppress routine logs ``` -Stop the background process: +Flags: `-interval` (Go duration, default `10s`, must be > 0) and `-quiet` +(raise the log level so only warnings and errors print). -```sh -pkill -f sysmon +## How it works + +On each tick the cursor glides over a series of small steps to a new uniformly +random point within the main display, posting real `MouseMoved` events via +CoreGraphics. Between ticks it sleeps on a `time.Ticker`, so idle CPU is +effectively zero and the process is battery friendly. + +## Architecture + +Hexagonal (ports & adapters): + +``` +cmd/sysmon entry point: flags, dependency injection, signal handling +internal/activity/ + domain pure movement planner + Interval (no cgo/os; GOOS=linux-buildable) + port Pointer / Keeper interfaces (+ generated mock) + service KeeperService -- the roam loop + adapter CGPointer -- CoreGraphics, //go:build darwin ``` -## Permissions (important) +The runtime binary depends only on the standard library. Tests use testify + +go.uber.org/mock + `testing/synctest`. + +## Development + +```sh +make build +go test -race ./... +golangci-lint run ./... +``` -macOS requires permission to post system events. On first run the system will -ask you to add the **terminal** (Terminal.app / iTerm) that `sysmon` is launched -from to: +CI runs build / lint / test on macOS for every push and pull request. -**System Settings -> Privacy & Security -> Accessibility** +## License -Without this permission the mouse event will not be delivered. +MIT -- see [LICENSE](LICENSE).