rethocker 0.2.0 → 0.2.2

package/README.md

@@ -1,8 +1,27 @@
-# rethocker
-
-Global key interception and remapping for macOS. Intercept any key or combo system-wide, remap keys, fire shell commands, react to key sequences, and scope rules to specific apps — all from TypeScript.
-
-Requires **macOS 13+** and **Accessibility permission** (prompted automatically on first run).
+<p align="center">
+  <img src="src/assets/logo.png" width="280px" align="center" alt="rethocker logo" />
+  <h1 align="center">rethocker</h1>
+  <p align="center">
+    System-wide key interception and remapping for macOS, in TypeScript.
+  </p>
+</p>
+
+<!--- badges -->
+<p align="center">
+  <a href="https://github.com/benjamine/rethocker/actions?query=branch%3Amain"><img src="https://github.com/benjamine/rethocker/actions/workflows/publish.yml/badge.svg?branch=main" alt="rethocker CI status" /></a>
+  <a href="https://twitter.com/beneidel" rel="nofollow"><img src="https://img.shields.io/badge/created%20by-@beneidel-BACABA.svg" alt="Created by Benjamin Eidelman"></a>
+  <a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/benjamine/rethocker" alt="License"></a>
+  <a href="https://www.npmjs.com/package/rethocker" rel="nofollow"><img src="https://img.shields.io/npm/dw/rethocker.svg" alt="npm"></a>
+  <a href="https://github.com/benjamine/rethocker" rel="nofollow"><img src="https://img.shields.io/github/stars/benjamine/rethocker" alt="stars"></a>
+</p>
+
+---
+
+- Requires **macOS 13+** and **Accessibility permission** (prompted automatically on first run).
+- Built with a native daemon for low-latency key interception, and a TypeScript API for maximum flexibility and AI agent friendliness.
+- Intercept any key or key chord, with per-app scoping and advanced conditions.
+- Remap to other keys, execute shell commands, or call TypeScript handlers with full access to the API.
+- Bundled with convenient actions for common macOS tasks like window management, media control, etc..
 
 ## Install
 
@@ -14,7 +33,7 @@ brew install rethocker
 rethocker install
 ```
 
-`rethocker install` scaffolds `~/.config/rethocker/default.ts` and registers a LaunchAgent that starts on login and auto-reloads whenever you save the file.
+`rethocker install` scaffolds `~/.config/rethocker/default.ts` (where you write your own rules) and registers a LaunchAgent that starts on login and auto-reloads whenever you save the file.
 
 ```bash
 rethocker log      # live key monitor — see what rethocker captures
@@ -34,6 +53,8 @@ bun add rethocker
 ## Usage
 
 ```ts
+#!/usr/bin/env bun
+
 import { actions, Key, rethocker } from "rethocker"
 
 const rk = rethocker([
@@ -253,6 +274,8 @@ actions.window.thirdCenter()
 actions.window.thirdRight()
 actions.window.quarterTopLeft()
 actions.window.maximize()
+
+// NOTE: you can use this to compose any custom layouts
 actions.window.halfLeft("Figma")      // move specific app
 
 // App management
@@ -272,8 +295,6 @@ actions.media.volumeDown(10)
 // System
 actions.system.sleep()
 actions.system.lockScreen()
-actions.system.missionControl()
-actions.system.emptyTrash()
 
 // Run a Shortcut from the macOS Shortcuts app
 actions.shortcut("My Shortcut Name")
@@ -365,48 +386,3 @@ await rk.stop()
 // (by default rethocker keeps the event loop alive)
 rk.unref()
 ```
-
-## API reference
-
-### `rethocker(rules?, options?)` → `RethockerHandle`
-
-| Option | Type | Description |
-|---|---|---|
-| `binaryPath` | `string?` | Override the native binary path |
-
-### `RethockerHandle`
-
-| Method | Returns | Description |
-|---|---|---|
-| `add(rule \| rule[])` | `void` | Add one or more rules |
-| `remove(id)` | `void` | Remove a rule permanently |
-| `enable(id?)` | `void` | Enable a rule by ID, or all rules if no ID |
-| `disable(id?)` | `void` | Disable a rule by ID, or all rules if no ID |
-| `on(event, listener)` | `() => void` | Subscribe to an event; returns an unsubscribe function |
-| `execute(command)` | `Promise<void>` | Run a shell command immediately (accepts `string \| string[]`) |
-| `start()` | `Promise<void>` | Await daemon readiness (optional) |
-| `stop()` | `Promise<void>` | Stop the daemon |
-| `unref()` | `void` | Allow the process to exit while the daemon runs |
-| `ready` | `boolean` | Whether the daemon is ready |
-
-### Events
-
-| Event | Arguments | Description |
-|---|---|---|
-| `"ready"` | — | Daemon ready |
-| `"key"` | `KeyEvent` | Every key event (stream auto-activates on subscribe) |
-| `"accessibilityDenied"` | — | Accessibility permission not granted |
-| `"error"` | `code, message` | Native daemon error |
-| `"exit"` | `code` | Native process exited unexpectedly |
-
-### `KeyEvent`
-
-| Field | Type | Description |
-|---|---|---|
-| `type` | `"keydown" \| "keyup" \| "flags"` | Event type |
-| `keyCode` | `number` | macOS virtual key code |
-| `modifiers` | `Modifier[]` | Active modifiers |
-| `app` | `string?` | Frontmost app display name |
-| `appBundleID` | `string?` | Frontmost app bundle ID |
-| `suppressed` | `boolean` | Whether the key was consumed |
-| `ruleID` | `string?` | ID of the matched rule |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rethocker",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Intercept and remap global keys on macOS — with per-app and key-sequence support",
   "type": "module",
   "main": "src/index.ts",

package/src/cli.ts

@@ -183,26 +183,44 @@ async function cmdRunConfig(configFile: string) {
 
 // ─── Help ─────────────────────────────────────────────────────────────────────
 
-const HELP = `
-Usage: rethocker <command>
-
-Commands:
-  install     Scaffold a config file and set up a background agent that
-              starts on login and auto-reloads when the config is saved
-  uninstall   Stop the background agent and remove it (keeps your config)
-  restart     Restart the background agent
-  status      Show whether the background agent is running
-  log         Live key monitor — shows keypresses in rethocker rule syntax
-              so you can copy-paste them directly into your config
-  help        Print this help message
-
-Install via Homebrew:
-  brew tap benjamine/tap
-  brew install rethocker
-  rethocker install
+function buildHelp() {
+  const lines = [
+    "Usage: rethocker <command>",
+    "",
+    "Commands:",
+    "  install     Scaffold a config file and set up a background agent that",
+    "              starts on login and auto-reloads when the config is saved",
+    "  uninstall   Stop the background agent and remove it (keeps your config)",
+    "  restart     Restart the background agent",
+    "  status      Show whether the background agent is running",
+    "  log         Live key monitor — shows keypresses in rethocker rule syntax",
+    "              so you can copy-paste them directly into your config",
+    "  help        Print this help message",
+    "",
+  ];
+
+  if (existsSync(PLIST_FILE)) {
+    const result = run([
+      "launchctl",
+      "print",
+      `${AGENT_DOMAIN}/${AGENT_LABEL}`,
+    ]);
+    const running = result.ok;
+    lines.push(
+      `Config: ${tildeify(CONFIG_FILE)} (your rethocker rules are here)`,
+    );
+    lines.push(`Status: ${running ? "running" : "not running"}`);
+    if (!running)
+      lines.push('Run "rethocker restart" to start the background agent.');
+  } else {
+    lines.push(
+      `Config: ${tildeify(CONFIG_FILE)} (not found — run "rethocker install")`,
+    );
+  }
 
-Docs: ${GITHUB}
-`.trim();
+  lines.push("", `Docs: ${GITHUB}`);
+  return lines.join("\n");
+}
 
 // ─── Command dispatch ─────────────────────────────────────────────────────────
 
@@ -240,12 +258,12 @@ switch (subcommand) {
   case "help":
   case "--help":
   case "-h":
-    console.log(HELP);
+    console.log(buildHelp());
     break;
 
   default:
     if (subcommand) console.error(`Unknown command: "${subcommand}"\n`);
-    console.log(HELP);
+    console.log(buildHelp());
     process.exit(subcommand ? 1 : 0);
 }