Add hs2 command-line interface for Hammerspoon 2

[dmgerman]

Summary

Adds the hs2 CLI tool for scripting and interacting with Hammerspoon 2 via IPC:

• Command execution (-c), file execution, stdin (-s), and interactive REPL (-i)
• Tab completion powered by hs.moduleNames() (dynamic, no hardcoded lists)
• Proper exit codes: JS errors exit 65 (EX_DATAERR), IPC failures exit appropriately
• REPL banner documents let/const scoping behavior
• Argument passing (-a, --), quiet mode (-q), color control (-n/-N)
• Robust string escaping via JSONSerialization for tab completion queries
• MSG_TIMEOUT constant for IPC send timeouts

IPC protocol

• Registration/unregistration with per-instance isolated state (survives JSExport GC)
• Command and query message types with implicit-return and statement fallback
• Auto-reconnect on lost registration

ConsoleView fixes

• Apply colorForLogType to log entries (errors red, warnings orange)
• Remove unused selectedRows state variable
• Guard against crash on up-arrow with empty history

Note on pre-existing issues

The up-arrow crash on empty history also exists on main and is tracked in #43, with a fix in PR #44. The nonisolated(unsafe) finding on @Observable properties in Logging.swift was intentionally deferred as a separate architectural concern.

[greptile-apps]

Greptile Summary

This PR adds the hs2 CLI tool (IPC client, interactive REPL, tab completion, and file/stdin execution modes), the server-side JS IPC protocol handler, ConsoleView color fixes, and empty-history crash guard. The overall design is solid — the CFMessagePort-based IPC, per-instance isolation, and auto-reconnect logic are well implemented.

• scripts/test-hs2.sh run_error_tests() passes expected exit code 0 for JS error cases, but HSClient.swift exits with 65 (EX_DATAERR) on \"error:js\" — these three tests are inverted and always fail, and because set -e is active they abort the entire shell suite.
• The error_test.js fixture special-case in run_fixture_test has the same inverted expectation for the same reason.

Confidence Score: 4/5

Safe to merge after fixing the inverted exit-code expectations in scripts/test-hs2.sh — all production code paths are correct.

One P1 finding: the shell test script's error tests are inverted (expect exit 0, get exit 65) and abort the suite under set -e. Production code (HSClient, hs.ipc.js, ConsoleView) looks correct. The XCTest suite has the right expectations. Score is 4 because the shell script bug is a real defect that makes CI/CD misleading, not just a style issue.

scripts/test-hs2.sh — specifically run_error_tests() and the error_test.js fixture special-case in run_fixture_test

Important Files Changed

Filename	Overview
scripts/test-hs2.sh	run_error_tests() expects exit 0 for JS errors but implementation returns 65; tests are inverted and abort the suite under set -e
hs2/main.swift	Argument parsing, mode detection, and dispatch logic; well-guarded with correct exit codes
hs2/HSClient.swift	CFMessagePort IPC client with semaphore-based init and thread-safe exit code management; correct design
hs2/HSInteractiveREPL.swift	libedit REPL with IPC-driven tab completion; static mutable state is safe under single-REPL assumption
Hammerspoon 2/Modules/hs.ipc/hs.ipc.js	IPC protocol handler: registration, isolated command execution, query, and tab completion; robust with defensive error handling
Hammerspoon 2/Modules/hs.ipc/HSMessagePort.swift	CFMessagePort Swift wrapper with proper retain/release callbacks and recursion depth guard
Hammerspoon 2/Modules/hs.ipc/IPCModule.swift	IPC module with CLI install/uninstall/status helpers; symlink management is correct
Hammerspoon 2/Modules/hs.ipc/IPCProtocol.swift	Enum defining IPC message ID constants matching HSClient.swift
Hammerspoon 2/Windows/ConsoleView.swift	Applies colorForLogType to log entries, guards empty-history up-arrow crash, removes unused selectedRows state
Hammerspoon 2/Utilities/Logging.swift	nonisolated(unsafe) on @observable properties with documented rationale for CFRunLoop callback safety
Hammerspoon 2/Engine/ModuleRoot.swift	Adds hs.ipc module and moduleNames() list for dynamic tab completion
Hammerspoon 2Tests/IntegrationTests/HS2CommandTests.swift	Comprehensive XCTest suite correctly asserting exit 65 for JS errors; thorough coverage

Prompt To Fix All With AI

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

Comment:
**Error tests expect wrong exit code — will always fail and abort the suite**

`run_error_tests()` passes `0` as the expected exit code for JS errors, but `HSClient.swift` sets `EX_DATAERR` (65) whenever the server responds with `"error:js"`. This is confirmed by every assertion in `HS2CommandTests.swift` (e.g., `XCTAssertEqual(exitCode, 65, …)`). Because `set -e` is active, the first failure aborts the entire script, so `run_fixture_tests` and `run_stress_tests` never run.

```suggestion
run_error_tests() {
    echo ""
    log_info "Running error handling tests..."

    run_test "Syntax error detection" 65 \
        "$HS2_BINARY" -q -c 'invalid syntax;;'

    run_test "Runtime error detection" 65 \
        "$HS2_BINARY" -q -c 'throw new Error("test");'

    run_test "Undefined variable" 65 \
        "$HS2_BINARY" -q -c 'print(undefinedVar);'
}
```

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: 143-155

Comment:
**`error_test.js` fixture expected exit code is also inverted**

The special-case comment claims "JS errors return exit 0" but `error_test.js` throws an uncaught `Error`, which causes `HSClient` to set `EX_DATAERR` (65) and exit with that code. The fixture test will therefore always report FAIL for the correct behavior.

```suggestion
    if [[ "$test_name" == "error_test" ]]; then
        if [ $exit_code -eq 65 ]; then
            echo -e "${GREEN}PASS${NC} (JS error reported via stderr, exit 65)"
            TESTS_PASSED=$((TESTS_PASSED + 1))
            return 0
        else
            echo -e "${RED}FAIL${NC} (expected exit 65, got $exit_code)"
            TESTS_FAILED=$((TESTS_FAILED + 1))
            return 1
        fi
    fi
```

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: 90-130

Comment:
**Tab-completion sends a synchronous IPC query from main thread without re-entrancy guard**

`completionFunction` calls `client.sendToRemote(…, wantResponse: true)` synchronously. `CFMessagePortSendRequest` with a reply mode blocks the calling thread until the response arrives. If the Hammerspoon server is slow or unresponsive, the main thread stalls for up to `sendTimeout` seconds on every Tab press, freezing the REPL. Consider using a short, dedicated timeout (e.g., 0.5 s) for completion queries so a slow server doesn't make the shell feel hung.

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

---

This is a comment left during a code review.
Path: Hammerspoon 2/Modules/hs.ipc/hs.ipc.js
Line: 76-87

Comment:
**`print` sends output one-way with no delivery guarantee before client exits**

The per-instance `print` function sends via `sendMessage(…, oneWay=true)` with no acknowledgment. The client's run loop is stopped after a fixed 0.5 s delay (`stopRunLoopAfterDelay(0.5)` in `main.swift`). If the server sends multiple print messages close to the client's exit, some may be dropped. The 0.5 s window is a best-effort workaround; if a script triggers many rapid prints, the last ones could be silently lost. This is a known trade-off to avoid deadlock, but worth documenting clearly.

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

_{Reviews (1): Last reviewed commit: "Fix ConsoleView: apply log colors, remov..." | Re-trigger Greptile}

[greptile-apps]

Error tests expect wrong exit code — will always fail and abort the suite

run_error_tests() passes 0 as the expected exit code for JS errors, but HSClient.swift sets EX_DATAERR (65) whenever the server responds with "error:js". This is confirmed by every assertion in HS2CommandTests.swift (e.g., XCTAssertEqual(exitCode, 65, …)). Because set -e is active, the first failure aborts the entire script, so run_fixture_tests and run_stress_tests never run.

Suggested change

	run_error_tests() {
	echo ""
	log_info "Running error handling tests..."
	run_test "Syntax error detection" 0 \
	"$HS2_BINARY" -q -c 'invalid syntax;;'
	run_test "Runtime error detection" 0 \
	"$HS2_BINARY" -q -c 'throw new Error("test");'
	run_test "Undefined variable" 0 \
	"$HS2_BINARY" -q -c 'print(undefinedVar);'
	}
	run_error_tests() {
	echo ""
	log_info "Running error handling tests..."
	run_test "Syntax error detection" 65 \
	"$HS2_BINARY" -q -c 'invalid syntax;;'
	run_test "Runtime error detection" 65 \
	"$HS2_BINARY" -q -c 'throw new Error("test");'
	run_test "Undefined variable" 65 \
	"$HS2_BINARY" -q -c 'print(undefinedVar);'
	}

Prompt To Fix With AI

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

Comment:
**Error tests expect wrong exit code — will always fail and abort the suite**

`run_error_tests()` passes `0` as the expected exit code for JS errors, but `HSClient.swift` sets `EX_DATAERR` (65) whenever the server responds with `"error:js"`. This is confirmed by every assertion in `HS2CommandTests.swift` (e.g., `XCTAssertEqual(exitCode, 65, …)`). Because `set -e` is active, the first failure aborts the entire script, so `run_fixture_tests` and `run_stress_tests` never run.

```suggestion
run_error_tests() {
    echo ""
    log_info "Running error handling tests..."

    run_test "Syntax error detection" 65 \
        "$HS2_BINARY" -q -c 'invalid syntax;;'

    run_test "Runtime error detection" 65 \
        "$HS2_BINARY" -q -c 'throw new Error("test");'

    run_test "Undefined variable" 65 \
        "$HS2_BINARY" -q -c 'print(undefinedVar);'
}
```

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

[greptile-apps]

error_test.js fixture expected exit code is also inverted

The special-case comment claims "JS errors return exit 0" but error_test.js throws an uncaught Error, which causes HSClient to set EX_DATAERR (65) and exit with that code. The fixture test will therefore always report FAIL for the correct behavior.

Suggested change

	# Special handling for error_test.js
	# JS errors return exit 0 (IPC succeeded), errors reported via stderr
	if [[ "$test_name" == "error_test" ]]; then
	if [ $exit_code -eq 0 ]; then
	echo -e "${GREEN}PASS${NC} (JS error reported via stderr, exit 0)"
	TESTS_PASSED=$((TESTS_PASSED + 1))
	return 0
	else
	echo -e "${RED}FAIL${NC} (expected exit 0, got $exit_code)"
	TESTS_FAILED=$((TESTS_FAILED + 1))
	return 1
	fi
	fi
	if [[ "$test_name" == "error_test" ]]; then
	if [ $exit_code -eq 65 ]; then
	echo -e "${GREEN}PASS${NC} (JS error reported via stderr, exit 65)"
	TESTS_PASSED=$((TESTS_PASSED + 1))
	return 0
	else
	echo -e "${RED}FAIL${NC} (expected exit 65, got $exit_code)"
	TESTS_FAILED=$((TESTS_FAILED + 1))
	return 1
	fi
	fi

Prompt To Fix With AI

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

Comment:
**`error_test.js` fixture expected exit code is also inverted**

The special-case comment claims "JS errors return exit 0" but `error_test.js` throws an uncaught `Error`, which causes `HSClient` to set `EX_DATAERR` (65) and exit with that code. The fixture test will therefore always report FAIL for the correct behavior.

```suggestion
    if [[ "$test_name" == "error_test" ]]; then
        if [ $exit_code -eq 65 ]; then
            echo -e "${GREEN}PASS${NC} (JS error reported via stderr, exit 65)"
            TESTS_PASSED=$((TESTS_PASSED + 1))
            return 0
        else
            echo -e "${RED}FAIL${NC} (expected exit 65, got $exit_code)"
            TESTS_FAILED=$((TESTS_FAILED + 1))
            return 1
        fi
    fi
```

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

[greptile-apps]

Tab-completion sends a synchronous IPC query from main thread without re-entrancy guard

completionFunction calls client.sendToRemote(…, wantResponse: true) synchronously. CFMessagePortSendRequest with a reply mode blocks the calling thread until the response arrives. If the Hammerspoon server is slow or unresponsive, the main thread stalls for up to sendTimeout seconds on every Tab press, freezing the REPL. Consider using a short, dedicated timeout (e.g., 0.5 s) for completion queries so a slow server doesn't make the shell feel hung.

Prompt To Fix With AI

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

Comment:
**Tab-completion sends a synchronous IPC query from main thread without re-entrancy guard**

`completionFunction` calls `client.sendToRemote(…, wantResponse: true)` synchronously. `CFMessagePortSendRequest` with a reply mode blocks the calling thread until the response arrives. If the Hammerspoon server is slow or unresponsive, the main thread stalls for up to `sendTimeout` seconds on every Tab press, freezing the REPL. Consider using a short, dedicated timeout (e.g., 0.5 s) for completion queries so a slow server doesn't make the shell feel hung.

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

[greptile-apps]

print sends output one-way with no delivery guarantee before client exits

The per-instance print function sends via sendMessage(…, oneWay=true) with no acknowledgment. The client's run loop is stopped after a fixed 0.5 s delay (stopRunLoopAfterDelay(0.5) in main.swift). If the server sends multiple print messages close to the client's exit, some may be dropped. The 0.5 s window is a best-effort workaround; if a script triggers many rapid prints, the last ones could be silently lost. This is a known trade-off to avoid deadlock, but worth documenting clearly.

Prompt To Fix With AI

This is a comment left during a code review.
Path: Hammerspoon 2/Modules/hs.ipc/hs.ipc.js
Line: 76-87

Comment:
**`print` sends output one-way with no delivery guarantee before client exits**

The per-instance `print` function sends via `sendMessage(…, oneWay=true)` with no acknowledgment. The client's run loop is stopped after a fixed 0.5 s delay (`stopRunLoopAfterDelay(0.5)` in `main.swift`). If the server sends multiple print messages close to the client's exit, some may be dropped. The 0.5 s window is a best-effort workaround; if a script triggers many rapid prints, the last ones could be silently lost. This is a known trade-off to avoid deadlock, but worth documenting clearly.

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

[dmgerman]

Trying again. Sorry.