rethocker 0.0.1 → 0.1.0

package/src/rethocker.ts

@@ -0,0 +1,125 @@
+/**
+ * rethocker() — the main entry point.
+ *
+ * Wires together the daemon, rule engine, and rule registration into
+ * the public RethockerHandle interface.
+ */
+
+import { join } from "node:path";
+import { createDaemon } from "./daemon.ts";
+import { registerRule } from "./register-rule.ts";
+import type {
+  RethockerHandle,
+  RethockerOptions,
+  RethockerRule,
+} from "./rule-types.ts";
+import type { RethockerEvents, RuleHandle, SequenceHandle } from "./types.ts";
+
+export type {
+  HandlerRule,
+  RemapRule,
+  RethockerHandle,
+  RethockerOptions,
+  RethockerRule,
+  ShellRule,
+} from "./rule-types.ts";
+
+/**
+ * Create a rethocker instance with an optional initial set of rules.
+ * The native daemon starts automatically in the background.
+ *
+ * @example
+ * const rk = rethocker([
+ *   { key: "capsLock",        remap: "escape" },
+ *   { key: "Cmd+Shift+Space", execute: "open -a 'Alfred 5'" },
+ *   { key: "Ctrl+J Ctrl+K",  handler: () => console.log("sequence!"), consume: true },
+ * ])
+ *
+ * rk.on("accessibilityDenied", () => { ... })
+ * rk.disable()   // pause all rules
+ * rk.enable()    // resume all rules
+ */
+export function rethocker(
+  rules: RethockerRule | RethockerRule[] = [],
+  options: RethockerOptions = {},
+): RethockerHandle {
+  const binaryPath =
+    options.binaryPath ??
+    join(import.meta.dir, "..", "bin", "rethocker-native");
+
+  const daemon = createDaemon(binaryPath);
+
+  // ─── 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 */
+  });
+
+  function add(toAdd: RethockerRule | RethockerRule[]): void {
+    const list = Array.isArray(toAdd) ? toAdd : [toAdd];
+    for (const rule of list) {
+      const handle = registerRule(daemon.send, daemon.emitter, rule);
+      handles.set(handle.id, handle);
+    }
+  }
+
+  add(rules);
+
+  return {
+    add,
+
+    remove(id: string): void {
+      handles.get(id)?.remove();
+      handles.delete(id);
+    },
+
+    enable(id?: string): void {
+      if (id !== undefined) {
+        handles.get(id)?.enable();
+      } else {
+        for (const h of handles.values()) h.enable();
+      }
+    },
+
+    disable(id?: string): void {
+      if (id !== undefined) {
+        handles.get(id)?.disable();
+      } else {
+        for (const h of handles.values()) h.disable();
+      }
+    },
+
+    on<K extends keyof RethockerEvents>(
+      event: K,
+      listener: (...args: RethockerEvents[K]) => void,
+    ): () => void {
+      daemon.emitter.on(event, listener);
+      if (event === "key") daemon.send({ cmd: "listen_all", enabled: true });
+      return () => {
+        daemon.emitter.off(event, listener);
+        if (event === "key" && daemon.emitter.listenerCount("key") === 0) {
+          daemon.send({ cmd: "listen_all", enabled: false });
+        }
+      };
+    },
+
+    async execute(command: string | string[]): Promise<void> {
+      const cmd = Array.isArray(command) ? command.join(" && ") : command;
+      const proc = Bun.spawn(["/bin/sh", "-c", cmd], {
+        stdout: "inherit",
+        stderr: "inherit",
+      });
+      await proc.exited;
+    },
+
+    start: () => daemon.start(),
+    stop: () => daemon.stop(),
+    unref: () => daemon.unref(),
+    get ready() {
+      return daemon.ready;
+    },
+  };
+}

package/src/rule-engine.ts

@@ -0,0 +1,101 @@
+/**
+ * Rule engine — low-level rule/sequence registration and handle creation.
+ *
+ * Knows how to translate typed rule objects into IPC commands (via `send`),
+ * and wires up emitter listeners for intercept/handler patterns.
+ * Has no knowledge of the high-level string-based rule syntax.
+ */
+
+import type { TypedEmitter } from "./daemon.ts";
+import type {
+  KeyCombo,
+  KeyEvent,
+  RuleAction,
+  RuleHandle,
+  RuleOptions,
+  SequenceHandle,
+  SequenceOptions,
+} from "./types.ts";
+import { DEFAULT_SEQUENCE_TIMEOUT_MS } from "./types.ts";
+
+let _seq = 0;
+export function genID(prefix: string) {
+  return `${prefix}_${Date.now()}_${++_seq}`;
+}
+
+function makeHandle(
+  id: string,
+  send: (obj: Record<string, unknown>) => void,
+  removeCmd: string,
+  toggleCmd: string,
+): RuleHandle {
+  return {
+    id,
+    remove: () => send({ cmd: removeCmd, id }),
+    enable: () => send({ cmd: toggleCmd, id, enabled: true }),
+    disable: () => send({ cmd: toggleCmd, id, enabled: false }),
+  };
+}
+
+export function addRule(
+  send: (obj: Record<string, unknown>) => void,
+  trigger: KeyCombo,
+  action: RuleAction,
+  opts: RuleOptions = {},
+): RuleHandle {
+  const id = opts.id ?? genID("rule");
+  send({
+    cmd: "add_rule",
+    id,
+    trigger,
+    action,
+    conditions: opts.conditions ?? {},
+    onKeyUp: opts.onKeyUp ?? false,
+    enabled: !(opts.disabled ?? false),
+  });
+  return makeHandle(id, send, "remove_rule", "set_rule_enabled");
+}
+
+export function addSequence(
+  send: (obj: Record<string, unknown>) => void,
+  steps: KeyCombo[],
+  action: RuleAction,
+  opts: SequenceOptions = {},
+): SequenceHandle {
+  const id = opts.id ?? genID("seq");
+  send({
+    cmd: "add_sequence",
+    id,
+    steps,
+    action,
+    timeoutMs: opts.timeoutMs ?? DEFAULT_SEQUENCE_TIMEOUT_MS,
+    consume: opts.consume ?? false,
+    conditions: opts.conditions ?? {},
+    enabled: !(opts.disabled ?? false),
+  });
+  return makeHandle(id, send, "remove_sequence", "set_sequence_enabled");
+}
+
+export function intercept(
+  send: (obj: Record<string, unknown>) => void,
+  emitter: TypedEmitter,
+  trigger: KeyCombo,
+  handler: (e: KeyEvent) => void,
+  opts: RuleOptions = {},
+): RuleHandle {
+  const eventID = genID("intercept");
+  const handle = addRule(send, trigger, { type: "emit", eventID }, opts);
+  emitter.on("event", (eid, ruleID) => {
+    if (eid === eventID) {
+      handler({
+        type: "keydown",
+        keyCode: trigger.keyCode,
+        modifiers: trigger.modifiers ?? [],
+        ruleID,
+        eventID,
+        suppressed: true,
+      });
+    }
+  });
+  return handle;
+}

package/src/rule-types.ts

@@ -0,0 +1,169 @@
+/**
+ * Public-facing rule type definitions for the high-level rethocker() API.
+ *
+ * Three discriminated variants — TypeScript narrows to the correct set of
+ * fields based on which discriminant key is present, giving users precise
+ * autocomplete for each rule type.
+ */
+
+import type { KeyEvent, RethockerEvents, RuleConditions } from "./types.ts";
+
+// ─── Rule variants ────────────────────────────────────────────────────────────
+
+/** Common fields available on every rule. */
+interface RuleBase {
+  /**
+   * The key or key sequence that triggers this rule.
+   *
+   * Single key:  `"escape"` | `"Cmd+A"` | `"Cmd+Shift+K"`
+   * Sequence:    `"Cmd+R T"` | `"Ctrl+J Ctrl+K"` (space-separated steps)
+   *
+   * Modifier names are case-insensitive: Cmd, Shift, Alt/Opt/Option, Ctrl/Control, Fn
+   * Key names match the `Key` constant (also case-insensitive).
+   * Common aliases: esc, enter, backspace, del, caps
+   */
+  key: string;
+  /** Optional stable ID. Auto-generated if omitted. */
+  id?: string;
+  /**
+   * Restrict this rule to fire only when one of these apps is frontmost.
+   *
+   * Pass a bundle ID (contains a dot) or a display name (prefix match,
+   * case-insensitive). Multiple values are OR-ed.
+   *
+   * Auto-detection: `"com.figma.Desktop"` → bundle ID, `"Figma"` → display name.
+   *
+   * @example
+   * app: "com.figma.Desktop"
+   * app: "Terminal"
+   * app: ["Safari", "Chrome", "Firefox"]
+   */
+  app?: string | string[];
+  /** Advanced: full condition control. Merged with `app` if both provided. */
+  conditions?: RuleConditions;
+  /** Start the rule disabled. */
+  disabled?: boolean;
+}
+
+/** Remap a key to a different key. */
+export interface RemapRule extends RuleBase {
+  /**
+   * The key to emit instead. Same syntax as `key`:
+   * `"escape"` | `"Cmd+Enter"` etc.
+   */
+  remap: string;
+  execute?: never;
+  handler?: never;
+  consume?: never;
+  sequenceTimeoutMs?: never;
+}
+
+/** Run a shell command (or multiple) when the key fires. The key is consumed. */
+export interface ShellRule extends RuleBase {
+  /**
+   * Shell command to run (via `/bin/sh -c`).
+   * Pass an array to run multiple commands sequentially — they are joined with `&&`.
+   *
+   * @example
+   * execute: actions.window.halfLeft()
+   * execute: [actions.window.halfLeft(), actions.app.focus("Slack")]
+   */
+  execute: string | string[];
+  /**
+   * For sequences: consume all intermediate key events so they never reach
+   * the active app. Single-key execute rules always consume the trigger key.
+   * @default false
+   */
+  consume?: boolean;
+  /**
+   * For sequences: max ms between consecutive steps.
+   * @default DEFAULT_SEQUENCE_TIMEOUT_MS (5000)
+   */
+  sequenceTimeoutMs?: number;
+  remap?: never;
+  handler?: never;
+}
+
+/** Call a TypeScript handler when the key fires. The key is consumed. */
+export interface HandlerRule extends RuleBase {
+  /** Called when the key fires. */
+  handler: (event: KeyEvent) => void;
+  /**
+   * For sequences: consume all intermediate key events.
+   * @default false
+   */
+  consume?: boolean;
+  /**
+   * For sequences: max ms between consecutive steps.
+   * @default DEFAULT_SEQUENCE_TIMEOUT_MS (5000)
+   */
+  sequenceTimeoutMs?: number;
+  remap?: never;
+  execute?: never;
+}
+
+export type RethockerRule = RemapRule | ShellRule | HandlerRule;
+
+// ─── Public handle ────────────────────────────────────────────────────────────
+
+export interface RethockerHandle {
+  /** Add one or more rules. */
+  add(rules: RethockerRule | RethockerRule[]): void;
+  /** Remove a rule permanently by ID. */
+  remove(id: string): void;
+  /**
+   * Enable rules.
+   * - No argument: enable all rules on this handle.
+   * - With id: enable a specific rule by ID.
+   */
+  enable(id?: string): void;
+  /**
+   * Disable rules without removing them.
+   * - No argument: disable all rules on this handle.
+   * - With id: disable a specific rule by ID.
+   */
+  disable(id?: string): void;
+  /**
+   * Subscribe to an event. Returns an unsubscribe function.
+   * Subscribing to `"key"` automatically activates the key stream.
+   */
+  on<K extends keyof RethockerEvents>(
+    event: K,
+    listener: (...args: RethockerEvents[K]) => void,
+  ): () => void;
+  /**
+   * Run a shell command (or multiple) immediately, outside of any rule.
+   * Accepts the same value as the `execute` field on a rule.
+   * Returns a promise that resolves when the command exits.
+   *
+   * @example
+   * await rk.execute(actions.media.playPause())
+   * await rk.execute([actions.window.halfLeft(), actions.app.focus("Slack")])
+   *
+   * // Inside a handler:
+   * { key: "Ctrl+J", handler: async () => { await rk.execute(actions.system.sleep()) } }
+   */
+  execute(command: string | string[]): Promise<void>;
+
+  /** Stop the native daemon and clean up. */
+  stop(): Promise<void>;
+  /**
+   * Allow the process to exit while the daemon is running.
+   * By default rethocker keeps the event loop alive.
+   */
+  unref(): void;
+  /**
+   * Await daemon readiness. Optional — the daemon starts automatically.
+   * Useful for explicitly handling startup errors.
+   */
+  start(): Promise<void>;
+  /** Whether the daemon is running and ready. */
+  readonly ready: boolean;
+}
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+export interface RethockerOptions {
+  /** Override the path to the native binary. Defaults to the bundled binary. */
+  binaryPath?: string;
+}

package/src/scripts/debug-keys.ts

@@ -0,0 +1,45 @@
+/**
+ * Key code explorer: prints every key event with its keyCode, modifiers,
+ * and the currently active app.
+ *
+ * Useful for discovering key codes and verifying app conditions before
+ * writing rules.
+ *
+ * Note on device discrimination: CGEventTap does not expose which physical
+ * keyboard generated an event. Use key codes to distinguish devices — numpad
+ * keys have dedicated codes (Numpad0–Numpad9, NumpadEnter, etc.) that differ
+ * from the main keyboard, so "NumpadEnter" and "return" are already distinct.
+ *
+ * Run with:
+ *   bun src/scripts/debug-keys.ts
+ */
+
+import type { KeyEvent } from "../index.ts";
+import { rethocker } from "../index.ts";
+
+const rk = rethocker();
+
+rk.on("accessibilityDenied", () => {
+  console.error(
+    "Accessibility permission required.\n" +
+      "Go to System Settings → Privacy & Security → Accessibility\n" +
+      "and enable this terminal / app.",
+  );
+});
+
+await rk.start();
+console.log("Press any key (Ctrl+C to quit):\n");
+
+rk.on("key", ({ type, keyCode, modifiers, app, appBundleID }: KeyEvent) => {
+  const parts: string[] = [
+    `${type.padEnd(7)}  keyCode: ${String(keyCode).padEnd(4)}`,
+  ];
+
+  if (modifiers.length > 0) {
+    parts.push(`mods: [${modifiers.join(", ")}]`);
+  }
+
+  if (app) parts.push(`app: ${app}${appBundleID ? ` (${appBundleID})` : ""}`);
+
+  console.log(parts.join("  "));
+});

package/src/scripts/example.ts

@@ -0,0 +1,74 @@
+/**
+ * Example: rethocker capabilities showcase
+ *
+ * Run with:
+ *   bun src/scripts/example.ts
+ *
+ * Requires Accessibility permission on first run.
+ * macOS will prompt automatically.
+ */
+
+import { actions, Key, rethocker } from "../index.ts";
+
+const rk = rethocker([
+  // ── Remap Caps Lock → Escape ──────────────────────────────────────────────
+  //
+  // Caps Lock fires a special "flagsChanged" event (not a normal keydown),
+  // but rethocker handles it transparently — this just works.
+  {
+    key: "capsLock",
+    remap: "escape",
+  },
+  {
+    // you can also remap chords
+    key: "Ctrl+H E",
+    // or remap to a chord, use `Key` for autocomplete and typesafety
+    remap: `h e l l o Shift+n1 n1 ${Key.delete}`,
+  },
+  {
+    key: `${Key.brightnessDown} ${Key.brightnessUp}`,
+    /**
+     * install zwussh first:
+     *  brew tap benjamine/homebrew-tap
+     *  brew install zwuush
+     */
+    execute: "zwuush https://benjamine.github.io/zwuush/wow.mov",
+  },
+  {
+    key: "Cmd+R T",
+    sequenceTimeoutMs: 10_000,
+    // optionally include or exclude specific apps (by bundle identifier).
+    app: ["!com.google.Chrome", "!com.apple.Safari"],
+    // optionally consume the key event so it doesn't reach the app
+    consume: true,
+    // execute: `osascript -e 'display notification "Cmd+R → T sequence detected" with title "rethocker"'`,
+    handler: async () => {
+      // using a custom handler allows for more complex actions, e.g. multiple commands, async/await, etc.
+      await rk.execute(actions.window.halfTop());
+      // actions. provide quick access to common OSX tasks like window management
+    },
+  },
+]);
+
+rk.on("accessibilityDenied", () => {
+  console.error(
+    "Accessibility permission required.\n" +
+      "Go to System Settings → Privacy & Security → Accessibility\n" +
+      "and enable this terminal / app.",
+  );
+});
+
+rk.on("error", (code, message) => {
+  console.error(`[rethocker error] ${code}: ${message}`);
+});
+
+rk.on("exit", (code) => {
+  console.error(
+    `Native daemon exited unexpectedly (code ${code}). Restarting...`,
+  );
+  rk.start().catch(console.error);
+});
+
+console.log("rethocker running. Press Ctrl+C to quit.");
+console.log("  • Caps Lock → Escape");
+console.log("  • Cmd+R then T (within 10s, consumed) → macOS notification");