rethocker 0.2.1 → 0.2.3

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([

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "rethocker",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Intercept and remap global keys on macOS — with per-app and key-sequence support",
   "type": "module",
   "main": "src/index.ts",
   "module": "src/index.ts",
   "types": "src/index.ts",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/benjamine/rethocker.git"
+  },
   "os": [
     "darwin"
   ],

package/src/actions.ts

@@ -71,7 +71,7 @@ tell application "Finder"
 end tell
 set screenW to item 3 of screenBounds
 set screenH to item 4 of screenBounds
-set menuBarH to 30
+set menuBarH to item 2 of screenBounds
 set pos to ${posExpr}
 set sz to ${sizeExpr}
 ${targetBlock}

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);
 }
 

package/src/daemon.ts

@@ -11,6 +11,7 @@
  */
 
 import { EventEmitter } from "node:events";
+import { existsSync } from "node:fs";
 import type { KeyEvent, RethockerEvents } from "./types.ts";
 
 // ─── Typed EventEmitter (internal, never exported) ────────────────────────────
@@ -67,9 +68,33 @@ export function createDaemon(binaryPath: string): Daemon {
     [];
   let startPromise: Promise<void> | null = null;
 
+  // ─── Rule registry (for replay on daemon restart) ─────────────────────────
+  // Stores the JSON payload of every active add_rule / add_sequence command,
+  // keyed by rule ID. Updated on remove and set_enabled so replayed rules
+  // reflect the current state (not the original registration state).
+
+  const ruleRegistry = new Map<string, Record<string, unknown>>();
+  let listenAllEnabled = false;
+  let isFirstStart = true;
+
+  function trackSend(obj: Record<string, unknown>): void {
+    const cmd = obj.cmd as string | undefined;
+    if (cmd === "add_rule" || cmd === "add_sequence") {
+      ruleRegistry.set(obj.id as string, obj);
+    } else if (cmd === "remove_rule" || cmd === "remove_sequence") {
+      ruleRegistry.delete(obj.id as string);
+    } else if (cmd === "set_rule_enabled" || cmd === "set_sequence_enabled") {
+      const stored = ruleRegistry.get(obj.id as string);
+      if (stored) stored.enabled = obj.enabled;
+    } else if (cmd === "listen_all") {
+      listenAllEnabled = obj.enabled as boolean;
+    }
+  }
+
   // ─── Send / queue ─────────────────────────────────────────────────────────
 
   function send(obj: Record<string, unknown>): void {
+    trackSend(obj);
     const line = `${JSON.stringify(obj)}\n`;
     if (!_ready) {
       sendQueue.push(line);
@@ -79,6 +104,19 @@ export function createDaemon(binaryPath: string): Daemon {
   }
 
   function flushQueue(): void {
+    // On restart (not the first start), replay all registered rules first so
+    // the new daemon instance is back in the same state as before the crash.
+    if (!isFirstStart) {
+      for (const payload of ruleRegistry.values()) {
+        proc?.stdin.write(`${JSON.stringify(payload)}\n`);
+      }
+      if (listenAllEnabled) {
+        proc?.stdin.write(
+          `${JSON.stringify({ cmd: "listen_all", enabled: true })}\n`,
+        );
+      }
+    }
+    isFirstStart = false;
     for (const line of sendQueue) proc?.stdin.write(line);
     sendQueue = [];
   }
@@ -192,6 +230,19 @@ export function createDaemon(binaryPath: string): Daemon {
         },
       });
 
+      if (!existsSync(binaryPath)) {
+        const err = new Error(
+          `rethocker-native binary not found at: ${binaryPath}\n` +
+            `  If installed via Homebrew, try: brew reinstall rethocker\n` +
+            `  If installed via npm/bun, try: bun add rethocker\n` +
+            `  You can also override the path with: rethocker(rules, { binaryPath: "..." })`,
+        );
+        clearTimeout(timeout);
+        reject(err);
+        startPromise = null;
+        return;
+      }
+
       proc = Bun.spawn({
         cmd: [binaryPath],
         stdin: "pipe",

package/src/register-rule.ts

@@ -39,6 +39,7 @@ function toAppCondition(value: string): AppCondition {
 
 function buildConditions(rule: {
   app?: string | string[];
+  textInput?: boolean;
   conditions?: RuleConditions;
 }): RuleConditions | undefined {
   const base = rule.conditions ?? {};
@@ -49,10 +50,15 @@ function buildConditions(rule: {
       ? [...(base.activeApp ?? []), ...[rule.app].flat().map(toAppCondition)]
       : base.activeApp;
 
-  const merged: RuleConditions = { ...base, activeApp };
+  // textInput shorthand merges into conditions (rule-level wins over conditions)
+  const textInput = rule.textInput ?? base.textInput;
+
+  const merged: RuleConditions = { ...base, activeApp, textInput };
 
   const hasAny =
-    merged.activeApp !== undefined || merged.runningApps !== undefined;
+    merged.activeApp !== undefined ||
+    merged.runningApps !== undefined ||
+    merged.textInput !== undefined;
 
   return hasAny ? merged : undefined;
 }
@@ -158,7 +164,7 @@ function registerHandler(
     },
   );
 
-  emitter.on("sequence", (seqRuleID, eid) => {
+  const listener = (seqRuleID: string, eid: string | undefined) => {
     if (eid === eventID) {
       const event: KeyEvent = {
         type: "keydown",
@@ -170,7 +176,13 @@ function registerHandler(
       };
       rule.handler(event);
     }
-  });
+  };
+  emitter.on("sequence", listener);
+  const originalRemove = handle.remove;
+  handle.remove = () => {
+    emitter.off("sequence", listener);
+    originalRemove();
+  };
 
   return handle;
 }

package/src/rethocker.ts

@@ -58,10 +58,14 @@ export function rethocker(
   // ─── Rule handles ─────────────────────────────────────────────────────────
   const handles = new Map<string, RuleHandle | SequenceHandle>();
 
-  // Start daemon in background; errors surface via rk.on("error") or await rk.start()
-  // Silent — errors surface via rk.on("error") or await rk.start()
-  daemon.start().catch((_e: unknown) => {
-    /* intentional */
+  // Start daemon in background. If there's an error listener registered,
+  // startup errors are forwarded to it. Otherwise they're silently swallowed
+  // (call await rk.start() to catch them explicitly as a rejected promise).
+  daemon.start().catch((e: unknown) => {
+    if (daemon.emitter.listenerCount("error") > 0) {
+      const message = e instanceof Error ? e.message : String(e);
+      daemon.emitter.emit("error", "startup_failed", message);
+    }
   });
 
   function add(toAdd: RethockerRule | RethockerRule[]): void {

package/src/rule-engine.ts

@@ -85,7 +85,7 @@ export function intercept(
 ): RuleHandle {
   const eventID = genID("intercept");
   const handle = addRule(send, trigger, { type: "emit", eventID }, opts);
-  emitter.on("event", (eid, ruleID) => {
+  const listener = (eid: string, ruleID: string) => {
     if (eid === eventID) {
       handler({
         type: "keydown",
@@ -96,6 +96,12 @@ export function intercept(
         suppressed: true,
       });
     }
-  });
+  };
+  emitter.on("event", listener);
+  const originalRemove = handle.remove;
+  handle.remove = () => {
+    emitter.off("event", listener);
+    originalRemove();
+  };
   return handle;
 }

package/src/rule-types.ts

@@ -39,7 +39,18 @@ interface RuleBase {
    * app: ["Safari", "Chrome", "Firefox"]
    */
   app?: string | string[];
-  /** Advanced: full condition control. Merged with `app` if both provided. */
+  /**
+   * Restrict this rule based on whether a text input field is focused.
+   * - `true`  → fire only when a text field IS focused
+   * - `false` → fire only when NO text field is focused
+   * Omit to fire regardless of text input state.
+   *
+   * @example
+   * // Only fire when NOT in a text field (safe global shortcut)
+   * { key: "Ctrl+J", handler: () => {}, textInput: false }
+   */
+  textInput?: boolean;
+  /** Advanced: full condition control. Merged with `app` and `textInput` if both provided. */
   conditions?: RuleConditions;
   /** Start the rule disabled. */
   disabled?: boolean;

package/src/types.ts

@@ -50,6 +50,15 @@ export interface RuleConditions {
    * Items are OR-ed; omit to not care.
    */
   runningApps?: AppCondition[];
+  /**
+   * Restrict this rule based on whether a text input field is focused.
+   * - `true`  → fire only when a text field IS focused
+   * - `false` → fire only when NO text field is focused
+   * Omit to fire regardless of text input state.
+   *
+   * Uses the macOS Accessibility API (cached at 50ms TTL).
+   */
+  textInput?: boolean;
 }
 
 // ─── Actions ─────────────────────────────────────────────────────────────────