hs.hotkey: guard bind() against a callback-less no-op hotkey

[muescha]

Context / question

While reading through hs.hotkey I noticed that bind() happily creates and
enables a hotkey even when no function callback is given at all — e.g.
bind(mods, key, null, null) or bind(mods, key, null, null, null). Since bind() enables immediately, the result is a hotkey that claims the key combination
(swallowing it from other apps) but runs nothing — a silent no-op.

I'm genuinely not sure whether that's intended or just an edge case that never came up. Guarding against it in bind() seemed sensible, but I may well be missing a reason it's allowed — I'm completely fine if this PR is dismissed and rejected.

What this PR does

bind() returns null (and logs an error) unless at least one of them is a function:

• callbackPressed,
• callbackReleased, or
• callbackRepeat

create() is deliberately left permissive, so the "build now, assign callbacks later via properties" pattern still works.

(Side note: the message toast is shown just before a callback fires, so a
message-only hotkey never shows its message either — which is partly why a
callback-less hotkey feels like a mistake rather than a use case.)

Example

console.log("before")
var cmdAltH = hs.hotkey.bind(["cmd", "alt"], "h", null, null)
console.log("after")

Log:

2026-09-07 02:02:33 - JavaScript: before
2026-09-07 02:02:33 - Debug: Loading module: hotkey
2026-09-07 02:02:33 - Garbage: Init of hs.hotkey: 56E59F07-19D2-4DCC-A69E-FA93690642FE
2026-09-07 02:02:33 - Error: hs.hotkey.bind: at least one of callbackPressed, callbackReleased, or callbackRepeat must be a function
2026-09-07 02:02:33 - JavaScript: after

bind() logs the error and returns null without throwing, so the surrounding
script keeps running.

Changes

• Guard in bind() requiring ≥1 function callback.
• Updated the two bindSpec message tests to pass a callback (a message-only spec is now rejected under this rule).
• New tests: bind with no callbacks → null; create with no callbacks still succeeds.

Notes

• Docs (api.json / HTML / TS) intentionally not regenerated here; the updated bind() docstring flags that a docs refresh is owed.
• If the current behaviour is by design, closing this PR is totally fine.
• Related: hs.hotkey: make released optional and unify callback handling #208 (also touches hs.hotkey); minor rebase possible depending on merge order.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR prevents hs.hotkey.bind() from immediately enabling a hotkey that has no functional callbacks.

• Requires at least one pressed, released, or repeat callback.
• Leaves create() permissive for deferred callback assignment.
• Updates bindSpec tests and adds coverage for callback-less bind() and create() calls.

Confidence Score: 4/5

The implementation appears safe to merge, with a non-blocking documentation refresh needed to expose the new API constraint.

The guard follows existing callback validation conventions, bindSpec safely handles a null result, and tests cover both rejection by bind and continued permissiveness in create; only the checked-in API documentation remains inconsistent.

Files Needing Attention: Hammerspoon 2/Modules/hs.hotkey/HSHotkeyModule.swift

Important Files Changed

Filename	Overview
Hammerspoon 2/Modules/hs.hotkey/HSHotkeyModule.swift	Adds the callback-presence guard and source documentation, but the corresponding checked-in API documentation remains stale.
Hammerspoon 2Tests/IntegrationTests/HSHotkeyIntegrationTests.swift	Updates message tests to provide callbacks and verifies the intended distinction between bind() and create().

Prompt To Fix All With AI

### Issue 1
Hammerspoon 2/Modules/hs.hotkey/HSHotkeyModule.swift:23
**API Documentation Is Stale**

The runtime now rejects callback-less `bind()` calls, but the checked-in API documentation still permits each callback to be null and describes null only as a generic binding failure. Regenerate or update the non-HTML API artifacts so users can discover the new requirement instead of encountering an unexplained compatibility change.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "hs.hotkey: require at least one callback..." | Re-trigger Greptile}