Add hs2 command-line interface for Hammerspoon 2

[dmgerman]

Summary

The hs2 CLI enables scripting and automation of Hammerspoon 2 from the terminal, matching the hs CLI from the original Hammerspoon. Users can execute JavaScript one-liners, run script files, pipe code via stdin, or use an interactive REPL with tab completion.

Why

Hammerspoon's power comes from scriptability. Without a CLI, users can only interact through the GUI console. The CLI enables shell scripting integration (hs2 -c '...' && ...), editor tooling, and faster iteration during development.

Key design decisions

• Non-zero exit on JS errors (exit 65): Shell scripting requires reliable exit codes. JS evaluation errors set EX_DATAERR while still executing remaining commands in multi-command mode, so -c a -c b -c c runs all three but exits non-zero if any failed.
• Dynamic module list: Tab completion queries hs.moduleNames() at runtime, which derives the list from the ModuleRootAPI protocol properties via ObjC runtime introspection. No hardcoded lists to maintain.
• Single-line implicit return: The REPL needs 1+1 to print 2 without requiring return. But JavaScript Automatic Semicolon Insertion (ASI) breaks this for multiline code, so implicit return is only used for single-line input.
• Synchronous IPC in tab completion: The readline completion callback makes a blocking sendToRemote call. This is safe because the IPC run loop runs on a dedicated thread (hs2-ipc-client), not on the main thread where readline blocks.
• Self-building test script: scripts/test-hs2.sh builds the project before testing to guarantee it tests the current code, not a stale binary.

ConsoleView fixes

Fixes three bugs in the in-app console: log entries now display colored by type, unused state removed, and up-arrow no longer crashes on empty history.

Not addressed

The nonisolated(unsafe) finding on @Observable properties in Logging.swift is a separate architectural concern. The up-arrow crash also exists on main — tracked in #43, fixed in PR #44.

[greptile-apps]

Greptile Summary

This PR adds an hs2 command-line interface for Hammerspoon 2, mirroring the original hs CLI. It enables shell scripting integration, REPL usage with tab completion, file and stdin execution modes, and proper exit codes for JS errors. The PR also fixes three bugs in ConsoleView (log colouring, empty-history crash, unused state) and introduces a dynamic module-name lookup via ObjC runtime introspection.

Key changes:

• New hs2 target: main.swift (arg parsing), HSClient.swift (IPC thread management), HSInteractiveREPL.swift (libedit REPL)
• hs.ipc module: JS handler (hs.ipc.js), IPCModule.swift (CLI install/uninstall), HSMessagePort.swift (CFMessagePort wrapper)
• ModuleRoot.swift: moduleNames() uses protocol_copyPropertyList instead of a hardcoded list
• Integration tests (HS2CommandTests.swift) and shell test script (scripts/test-hs2.sh)

Issues found:

• The REPL banner gives incorrect advice about variable persistence
• Tab completion can block the main thread for up to 8 seconds
• A comment about run-loop re-entry is technically inaccurate
• Shell test helpers only verify exit codes, not output content

Confidence Score: 3/5

The PR is mostly safe to merge but has a user-facing correctness bug in the REPL hint and a potential UX freeze in tab completion that should be addressed.

Score of 3 reflects: the core IPC machinery (CFRunLoop threading, semaphore synchronization, retain/release memory management) is implemented correctly; the ConsoleView bug fixes are clean; the dynamic moduleNames() approach is elegant. Points deducted for the incorrect 'var persistence' banner message (users following this hint will get a confusing ReferenceError), the tab-completion blocking issue (up to 8-second freeze), and test scripts that only check exit codes and not output content.

hs2/HSClient.swift (incorrect REPL persistence hint in getBanner()); hs2/HSInteractiveREPL.swift (blocking completion call and inaccurate comment); scripts/test-hs2.sh (output content not verified)

Important Files Changed

Filename	Overview
hs2/main.swift	CLI entry point with complete arg parsing, proper sysexits.h exit codes, conflict detection between -s/-c/file modes, and an NSWorkspace-based Hammerspoon running check
hs2/HSClient.swift	IPC client using a dedicated CFRunLoop thread with DispatchSemaphore init synchronization; REPL banner gives incorrect persistence hint for var declarations inside new Function() bodies
hs2/HSInteractiveREPL.swift	libedit REPL with JSON-safe tab completion; blocking IPC call in readline callback can freeze the UI for up to 2×timeout (8 s default); comment about run-loop re-entry is technically inaccurate
Hammerspoon 2/Modules/hs.ipc/hs.ipc.js	JS IPC handler with implicit-return heuristic for single-line REPL input (SyntaxError fallback); dual storage in __ipcRemotePorts prevents GC of remote port objects; error path correctly returns error:js
Hammerspoon 2/Modules/hs.ipc/IPCModule.swift	IPC module with CLI install/uninstall/status helpers; validates symlinks against current bundle before removal; rolls back binary symlink if man-page creation fails
Hammerspoon 2/Modules/hs.ipc/HSMessagePort.swift	CFMessagePort Swift wrapper with @mainactor isolation, correct retain/release CFMessagePortContext callbacks, and recursion-depth guard; @preconcurrency @unsafe imports suppress Swift 6 warnings
Hammerspoon 2/Windows/ConsoleView.swift	Bug fixes: log entries now colored by type via colorForLogType; empty-history guard prevents up-arrow crash; unused state removed
Hammerspoon 2/Engine/ModuleRoot.swift	moduleNames() uses protocol_copyPropertyList on ModuleRootAPI to return only declared properties (not methods), staying automatically in sync when modules are added or removed
scripts/test-hs2.sh	Self-building integration test script; run_test/run_fixture_test verify exit codes only — incorrect output content would go undetected unless the process exits non-zero
Hammerspoon 2Tests/IntegrationTests/HS2CommandTests.swift	Comprehensive XCTest integration suite covering basic execution, multi-command error recovery with exit 65, file/stdin modes, concurrent hs2 process stress tests, and output content verification

Prompt To Fix All With AI

This is a comment left during a code review.
Path: hs2/HSClient.swift
Line: 361-365

Comment:
**Incorrect REPL persistence hint**

The banner tells users to *"Use 'var' for persistent bindings (let/const are scoped per entry)"*, but this advice is wrong. In `hs.ipc.js` every REPL entry is evaluated via `new Function('_cli', 'print', code)`. Variables declared with `var` inside a `new Function` body are **local to that function call** — they are not added to the JS global object and do not survive to the next entry. Neither `let` nor `const` nor `var` persist across entries.

The only way to create persistent state is an implicit-global assignment in non-strict mode (e.g. `x = 5`, which writes directly to `globalThis`) or mutating an existing global object.

A user who follows the banner's advice by typing `var counter = 0` and then `counter++` in the next entry will receive:
```
ReferenceError: Can't find variable: counter
```
which directly contradicts the hint.

Suggested fix:
```suggestion
        let hint = "Persistent state: assign without var/let/const (e.g. x = 5) or use globalThis.x = 0"
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: hs2/HSInteractiveREPL.swift
Line: 103-127

Comment:
**Tab completion can freeze the terminal for up to 2× timeout**

`client.sendToRemote(..., wantResponse: true)` calls `CFMessagePortSendRequest` internally, which spins the **calling thread's** run loop until the reply arrives. With `sendTimeout = recvTimeout = 4.0` (the default), this means the readline prompt is completely unresponsive for up to **8 seconds** whenever Hammerspoon is slow or temporarily unresponsive. There is no user-visible feedback during this freeze.

Consider passing a much shorter timeout for completion queries (e.g. 500 ms) so that tab-press failures are invisible to the user:
```swift
// Use a short timeout so a slow Hammerspoon doesn't freeze readline
if let responseData = client.sendToRemote(message, msgID: MSGID_QUERY,
                                          sendTimeout: 0.5, recvTimeout: 0.5),
```
Note: `sendToRemote` would need to accept per-call timeout parameters to support this, or a separate helper could be added.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: hs2/HSInteractiveREPL.swift
Line: 98-102

Comment:
**Misleading comment about run-loop re-entry**

The comment says the `sendToRemote` call "does not re-enter the main thread's run loop." This is inaccurate. `CFMessagePortSendRequest` with `wantResponse: true` *does* spin the **calling thread's** run loop (via an internal `CFRunLoopRunInMode`) while waiting for the synchronous reply. Since the completion callback fires on the main thread, the main thread's run loop *is* re-entered briefly.

The point that matters for deadlock safety (that the `hs2-ipc-client` thread never needs to dispatch back to the main thread to deliver the reply) is correct but stated inaccurately. Suggested correction:
```suggestion
        // This is a synchronous IPC call from the readline callback (main thread).
        // CFMessagePortSendRequest briefly runs the main thread's run loop to receive
        // the reply. This is safe from deadlock because the IPC run loop on
        // hs2-ipc-client delivers the reply via a Mach port — it never needs to
        // call back onto the main thread.
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: scripts/test-hs2.sh
Line: 114-141

Comment:
**`run_test` verifies exit codes only, not output content**

Tests such as "Simple print", "Math operations", and "Function definition" would pass even if `print()` were silently broken, as long as the process exits 0. For example:
```bash
run_test "Simple print" 0 \
    "$HS2_BINARY" -q -c 'print("test")'
```
This only checks that the exit code is 0, not that `"test"` was actually printed.

The Swift `HS2CommandTests.swift` suite does check output content, so coverage is not zero. But for the shell script to serve as a meaningful regression guard, consider adding an optional `expected_output` parameter to `run_test` and using `grep` or exact comparison for the tests that care about specific values.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "Document threading model for synchronous..." | Re-trigger Greptile}

[greptile-apps]

Incorrect REPL persistence hint

The banner tells users to "Use 'var' for persistent bindings (let/const are scoped per entry)", but this advice is wrong. In hs.ipc.js every REPL entry is evaluated via new Function('_cli', 'print', code). Variables declared with var inside a new Function body are local to that function call — they are not added to the JS global object and do not survive to the next entry. Neither let nor const nor var persist across entries.

The only way to create persistent state is an implicit-global assignment in non-strict mode (e.g. x = 5, which writes directly to globalThis) or mutating an existing global object.

A user who follows the banner's advice by typing var counter = 0 and then counter++ in the next entry will receive:

ReferenceError: Can't find variable: counter

which directly contradicts the hint.

Suggested fix:

Suggested change

	let hint = "Use 'var' for persistent bindings (let/const are scoped per entry)"
	if useColors {
	return "\(colorBanner)Hammerspoon 2 REPL\(colorReset)\n\(hint)\n"
	} else {
	return "Hammerspoon 2 REPL\n\(hint)\n"
	let hint = "Persistent state: assign without var/let/const (e.g. x = 5) or use globalThis.x = 0"

Prompt To Fix With AI

This is a comment left during a code review.
Path: hs2/HSClient.swift
Line: 361-365

Comment:
**Incorrect REPL persistence hint**

The banner tells users to *"Use 'var' for persistent bindings (let/const are scoped per entry)"*, but this advice is wrong. In `hs.ipc.js` every REPL entry is evaluated via `new Function('_cli', 'print', code)`. Variables declared with `var` inside a `new Function` body are **local to that function call** — they are not added to the JS global object and do not survive to the next entry. Neither `let` nor `const` nor `var` persist across entries.

The only way to create persistent state is an implicit-global assignment in non-strict mode (e.g. `x = 5`, which writes directly to `globalThis`) or mutating an existing global object.

A user who follows the banner's advice by typing `var counter = 0` and then `counter++` in the next entry will receive:
```
ReferenceError: Can't find variable: counter
```
which directly contradicts the hint.

Suggested fix:
```suggestion
        let hint = "Persistent state: assign without var/let/const (e.g. x = 5) or use globalThis.x = 0"
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Tab completion can freeze the terminal for up to 2× timeout

client.sendToRemote(..., wantResponse: true) calls CFMessagePortSendRequest internally, which spins the calling thread's run loop until the reply arrives. With sendTimeout = recvTimeout = 4.0 (the default), this means the readline prompt is completely unresponsive for up to 8 seconds whenever Hammerspoon is slow or temporarily unresponsive. There is no user-visible feedback during this freeze.

Consider passing a much shorter timeout for completion queries (e.g. 500 ms) so that tab-press failures are invisible to the user:

// Use a short timeout so a slow Hammerspoon doesn't freeze readline
if let responseData = client.sendToRemote(message, msgID: MSGID_QUERY,
                                          sendTimeout: 0.5, recvTimeout: 0.5),

Note: sendToRemote would need to accept per-call timeout parameters to support this, or a separate helper could be added.

Prompt To Fix With AI

This is a comment left during a code review.
Path: hs2/HSInteractiveREPL.swift
Line: 103-127

Comment:
**Tab completion can freeze the terminal for up to 2× timeout**

`client.sendToRemote(..., wantResponse: true)` calls `CFMessagePortSendRequest` internally, which spins the **calling thread's** run loop until the reply arrives. With `sendTimeout = recvTimeout = 4.0` (the default), this means the readline prompt is completely unresponsive for up to **8 seconds** whenever Hammerspoon is slow or temporarily unresponsive. There is no user-visible feedback during this freeze.

Consider passing a much shorter timeout for completion queries (e.g. 500 ms) so that tab-press failures are invisible to the user:
```swift
// Use a short timeout so a slow Hammerspoon doesn't freeze readline
if let responseData = client.sendToRemote(message, msgID: MSGID_QUERY,
                                          sendTimeout: 0.5, recvTimeout: 0.5),
```
Note: `sendToRemote` would need to accept per-call timeout parameters to support this, or a separate helper could be added.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Misleading comment about run-loop re-entry

The comment says the sendToRemote call "does not re-enter the main thread's run loop." This is inaccurate. CFMessagePortSendRequest with wantResponse: true does spin the calling thread's run loop (via an internal CFRunLoopRunInMode) while waiting for the synchronous reply. Since the completion callback fires on the main thread, the main thread's run loop is re-entered briefly.

The point that matters for deadlock safety (that the hs2-ipc-client thread never needs to dispatch back to the main thread to deliver the reply) is correct but stated inaccurately. Suggested correction:

Suggested change

	// Query Hammerspoon for completions.
	// This is a synchronous IPC call from the readline callback, which runs on the
	// main thread. This is safe because the IPC run loop lives on a separate thread
	// (hs2-ipc-client) — the sendToRemote call blocks waiting for a response but
	// does not re-enter the main thread's run loop.
	// This is a synchronous IPC call from the readline callback (main thread).
	// CFMessagePortSendRequest briefly runs the main thread's run loop to receive
	// the reply. This is safe from deadlock because the IPC run loop on
	// hs2-ipc-client delivers the reply via a Mach port — it never needs to
	// call back onto the main thread.

Prompt To Fix With AI

This is a comment left during a code review.
Path: hs2/HSInteractiveREPL.swift
Line: 98-102

Comment:
**Misleading comment about run-loop re-entry**

The comment says the `sendToRemote` call "does not re-enter the main thread's run loop." This is inaccurate. `CFMessagePortSendRequest` with `wantResponse: true` *does* spin the **calling thread's** run loop (via an internal `CFRunLoopRunInMode`) while waiting for the synchronous reply. Since the completion callback fires on the main thread, the main thread's run loop *is* re-entered briefly.

The point that matters for deadlock safety (that the `hs2-ipc-client` thread never needs to dispatch back to the main thread to deliver the reply) is correct but stated inaccurately. Suggested correction:
```suggestion
        // This is a synchronous IPC call from the readline callback (main thread).
        // CFMessagePortSendRequest briefly runs the main thread's run loop to receive
        // the reply. This is safe from deadlock because the IPC run loop on
        // hs2-ipc-client delivers the reply via a Mach port — it never needs to
        // call back onto the main thread.
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

run_test verifies exit codes only, not output content

Tests such as "Simple print", "Math operations", and "Function definition" would pass even if print() were silently broken, as long as the process exits 0. For example:

run_test "Simple print" 0 \
    "$HS2_BINARY" -q -c 'print("test")'

This only checks that the exit code is 0, not that "test" was actually printed.

The Swift HS2CommandTests.swift suite does check output content, so coverage is not zero. But for the shell script to serve as a meaningful regression guard, consider adding an optional expected_output parameter to run_test and using grep or exact comparison for the tests that care about specific values.

Prompt To Fix With AI

This is a comment left during a code review.
Path: scripts/test-hs2.sh
Line: 114-141

Comment:
**`run_test` verifies exit codes only, not output content**

Tests such as "Simple print", "Math operations", and "Function definition" would pass even if `print()` were silently broken, as long as the process exits 0. For example:
```bash
run_test "Simple print" 0 \
    "$HS2_BINARY" -q -c 'print("test")'
```
This only checks that the exit code is 0, not that `"test"` was actually printed.

The Swift `HS2CommandTests.swift` suite does check output content, so coverage is not zero. But for the shell script to serve as a meaningful regression guard, consider adding an optional `expected_output` parameter to `run_test` and using `grep` or exact comparison for the tests that care about specific values.

How can I resolve this? If you propose a fix, please make it concise.

[dmgerman]

One more attempt...