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-expression implicit return: The REPL needs 1+1 to print 2 without requiring return. Implicit return is only used for single-line code with no semicolons. Multiline code and multi-statement code go through the statement path to avoid JavaScript Automatic Semicolon Insertion (ASI) bugs and early-return issues.
• Synchronous IPC in tab completion: The readline completion callback makes a blocking sendToRemote call. CFMessagePortSendRequest spins the calling thread's run loop internally, but this is safe because the main thread has no CFRunLoop sources registered. A 1-second timeout (vs 4s default) keeps tab completion responsive.
• Named constants for timeouts: DEFAULT_TIMEOUT (4.0s) for commands, completionTimeout (1.0s) for tab completion. No hardcoded values.
• Self-building test script: scripts/test-hs2.sh builds the project before testing to guarantee it tests the current code. Tests validate output content, not just exit codes.
• REPL banner: Documents that globalThis.x = 42 is needed for persistent bindings, since all declarations (var/let/const) are function-scoped inside new Function().

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 the hs2 CLI tool — a well-designed CFMessagePort IPC client with a libedit REPL, tab completion, and exit-code semantics — alongside the server-side hs.ipc module and JS protocol handler. The ConsoleView refactor introduces a few minor regressions: auto-scroll silently fails when entries are filtered, the command echo was removed from the log, and the Autocomplete log-level option remains in the picker despite autocomplete no longer being available in the console.

Confidence Score: 5/5

Safe to merge; all remaining findings are P2 quality and behavior suggestions.

No P0 or P1 defects found. The core IPC protocol, client lifecycle, and REPL are sound. The ConsoleView regressions are minor and don't block functionality.

Hammerspoon 2/Windows/ConsoleView.swift has three P2 issues (auto-scroll, echo, autocomplete picker) worth addressing post-merge.

Important Files Changed

Filename	Overview
hs2/main.swift	Entry point: argument parsing, mode detection, IPC client lifecycle — logic is clear and well-structured.
hs2/HSClient.swift	CFMessagePort IPC client using a dedicated run loop thread with DispatchSemaphore synchronization — design is sound.
hs2/HSInteractiveREPL.swift	libedit-based REPL with synchronous tab-completion IPC; minor inaccuracy in a timeout comment.
Hammerspoon 2/Windows/ConsoleView.swift	Console simplified: auto-scroll regression when entries are filtered, command echo removed, Autocomplete level shown despite no autocomplete entries.
Hammerspoon 2/Modules/hs.ipc/HSMessagePort.swift	New CFMessagePort Swift wrapper with retain/release context, recursion guard, and proper cleanup.
Hammerspoon 2/Modules/hs.ipc/IPCModule.swift	IPC module: local/remote port creation, CLI install/uninstall helpers; broken-symlink edge case in cliInstall.
Hammerspoon 2/Modules/hs.ipc/hs.ipc.js	JS-side IPC protocol handler with defensive error handling, instance isolation, and implicit-return heuristic for single-expression eval.
Hammerspoon 2/Engine/ModuleRoot.swift	Adds moduleNames() via ObjC runtime introspection and exposes hs.ipc module — clean and self-maintaining.
Hammerspoon 2/Utilities/Logging.swift	Adds synchronous logging on main thread and nonisolated(unsafe) for CFRunLoop-callback safety; tradeoffs are documented.
scripts/test-hs2.sh	Self-building shell test script; comprehensive coverage of basic, error, fixture, and stress cases.

Comments Outside Diff (1)

1. Hammerspoon 2/Modules/hs.ipc/IPCModule.swift, line 912-939 ([link](https://github.com/cmsj/hammerspoon2/blob/bdc67cb0cc1f5738a591f0b049678347618d86f5/Hammerspoon 2/Modules/hs.ipc/IPCModule.swift#L912-L939))

   Broken symlink causes a misleading install failure

   FileManager.fileExists(atPath:) follows symlinks and returns false when the target doesn't exist (broken symlink). If a stale broken symlink already sits at binaryDest, fileExists returns false, the code enters the else branch, and createSymbolicLink throws an "already exists" error whose message doesn't explain that a broken symlink is the culprit. Using fm.destinationOfSymbolicLink(atPath:) (which succeeds for broken links) to check for any pre-existing link before attempting creation would give a clearer error and avoid the misleading failure.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: Hammerspoon 2/Modules/hs.ipc/IPCModule.swift
   Line: 912-939
   
   Comment:
   **Broken symlink causes a misleading install failure**
   
   `FileManager.fileExists(atPath:)` follows symlinks and returns `false` when the target doesn't exist (broken symlink). If a stale broken symlink already sits at `binaryDest`, `fileExists` returns `false`, the code enters the `else` branch, and `createSymbolicLink` throws an "already exists" error whose message doesn't explain that a broken symlink is the culprit. Using `fm.destinationOfSymbolicLink(atPath:)` (which succeeds for broken links) to check for *any* pre-existing link before attempting creation would give a clearer error and avoid the misleading failure.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: Hammerspoon 2/Windows/ConsoleView.swift
Line: 61-63

Comment:
**Auto-scroll misses filtered entries**

`proxy.scrollTo(logs.entries.last?.id)` scrolls to the last entry in the *unfiltered* `logs.entries` array. When the user has an active search string or a `minimumLogLevel` that hides the newest entry, `ForEach` won't contain that ID and `scrollTo` silently does nothing. The old `"logBottom"` sentinel lived inside the same VStack as the filtered entries and was always reachable.

```suggestion
                .onChange(of: logs.entries) {
                    let visible = logs.entries.filter {
                        $0.logType.rawValue >= minimumLogLevel.rawValue &&
                        (searchString.isEmpty || $0.msg.contains(searchString))
                    }
                    proxy.scrollTo(visible.last?.id)
                }
```

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/Windows/ConsoleView.swift
Line: 99-113

Comment:
**Command echo removed from console log**

The previous `handleSubmit()` called `AKInfo("> \(evalString)")` before evaluating, giving users a persistent record of submitted commands interleaved with their output. The new `onSubmit` block omits this. If the removal is intentional (e.g., to reduce noise), a brief comment would clarify intent; otherwise this is a silent behavioral regression.

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/Windows/ConsoleView.swift
Line: 117-121

Comment:
**`Autocomplete` level in picker but no autocomplete entries are produced**

Tab completion was removed from `ConsoleView` in this PR, so `HammerspoonLogType.Autocomplete` entries will never appear. The previous code filtered it out of the Picker with `.filter { $0 != .Autocomplete }`. Now that it's selectable, a user who picks "Autocomplete" as the minimum log level will see a blank console with no obvious explanation.

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: 107-110

Comment:
**Incorrect worst-case timeout in comment**

The comment says "blocks for up to sendTimeout + recvTimeout (default 8s total)", but this call passes `completionTimeout` (1.0 s) as the custom timeout for both send and recv, so the actual worst-case block is 2.0 s, not 8 s.

```suggestion
        // Note: if Hammerspoon is unresponsive, this blocks for up to
        // completionTimeout × 2 = 2s (1s send + 1s recv).
```

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/IPCModule.swift
Line: 912-939

Comment:
**Broken symlink causes a misleading install failure**

`FileManager.fileExists(atPath:)` follows symlinks and returns `false` when the target doesn't exist (broken symlink). If a stale broken symlink already sits at `binaryDest`, `fileExists` returns `false`, the code enters the `else` branch, and `createSymbolicLink` throws an "already exists" error whose message doesn't explain that a broken symlink is the culprit. Using `fm.destinationOfSymbolicLink(atPath:)` (which succeeds for broken links) to check for *any* pre-existing link before attempting creation would give a clearer error and avoid the misleading failure.

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

_{Reviews (1): Last reviewed commit: "Extract timeout constants, avoid hardcod..." | Re-trigger Greptile}

[greptile-apps]

Auto-scroll misses filtered entries

proxy.scrollTo(logs.entries.last?.id) scrolls to the last entry in the unfiltered logs.entries array. When the user has an active search string or a minimumLogLevel that hides the newest entry, ForEach won't contain that ID and scrollTo silently does nothing. The old "logBottom" sentinel lived inside the same VStack as the filtered entries and was always reachable.

Suggested change

	.onChange(of: logs.entries) {
	proxy.scrollTo("logBottom", anchor: .bottom)
	proxy.scrollTo(logs.entries.last?.id)
	}
	.onChange(of: logs.entries) {
	let visible = logs.entries.filter {
	$0.logType.rawValue >= minimumLogLevel.rawValue &&
	(searchString.isEmpty || $0.msg.contains(searchString))
	}
	proxy.scrollTo(visible.last?.id)
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: Hammerspoon 2/Windows/ConsoleView.swift
Line: 61-63

Comment:
**Auto-scroll misses filtered entries**

`proxy.scrollTo(logs.entries.last?.id)` scrolls to the last entry in the *unfiltered* `logs.entries` array. When the user has an active search string or a `minimumLogLevel` that hides the newest entry, `ForEach` won't contain that ID and `scrollTo` silently does nothing. The old `"logBottom"` sentinel lived inside the same VStack as the filtered entries and was always reachable.

```suggestion
                .onChange(of: logs.entries) {
                    let visible = logs.entries.filter {
                        $0.logType.rawValue >= minimumLogLevel.rawValue &&
                        (searchString.isEmpty || $0.msg.contains(searchString))
                    }
                    proxy.scrollTo(visible.last?.id)
                }
```

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

[greptile-apps]

Command echo removed from console log

The previous handleSubmit() called AKInfo("> \(evalString)") before evaluating, giving users a persistent record of submitted commands interleaved with their output. The new onSubmit block omits this. If the removal is intentional (e.g., to reduce noise), a brief comment would clarify intent; otherwise this is a silent behavioral regression.

Prompt To Fix With AI

This is a comment left during a code review.
Path: Hammerspoon 2/Windows/ConsoleView.swift
Line: 99-113

Comment:
**Command echo removed from console log**

The previous `handleSubmit()` called `AKInfo("> \(evalString)")` before evaluating, giving users a persistent record of submitted commands interleaved with their output. The new `onSubmit` block omits this. If the removal is intentional (e.g., to reduce noise), a brief comment would clarify intent; otherwise this is a silent behavioral regression.

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

[greptile-apps]

Autocomplete level in picker but no autocomplete entries are produced

Tab completion was removed from ConsoleView in this PR, so HammerspoonLogType.Autocomplete entries will never appear. The previous code filtered it out of the Picker with .filter { $0 != .Autocomplete }. Now that it's selectable, a user who picks "Autocomplete" as the minimum log level will see a blank console with no obvious explanation.

Prompt To Fix With AI

This is a comment left during a code review.
Path: Hammerspoon 2/Windows/ConsoleView.swift
Line: 117-121

Comment:
**`Autocomplete` level in picker but no autocomplete entries are produced**

Tab completion was removed from `ConsoleView` in this PR, so `HammerspoonLogType.Autocomplete` entries will never appear. The previous code filtered it out of the Picker with `.filter { $0 != .Autocomplete }`. Now that it's selectable, a user who picks "Autocomplete" as the minimum log level will see a blank console with no obvious explanation.

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

[greptile-apps]

Incorrect worst-case timeout in comment

The comment says "blocks for up to sendTimeout + recvTimeout (default 8s total)", but this call passes completionTimeout (1.0 s) as the custom timeout for both send and recv, so the actual worst-case block is 2.0 s, not 8 s.

Suggested change

	// nothing to re-enter. The IPC run loop for receiving messages lives on a
	// separate thread (hs2-ipc-client).
	// Note: if Hammerspoon is unresponsive, this blocks for up to sendTimeout +
	// recvTimeout (default 8s total).
	// Note: if Hammerspoon is unresponsive, this blocks for up to
	// completionTimeout × 2 = 2s (1s send + 1s recv).

Prompt To Fix With AI

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

Comment:
**Incorrect worst-case timeout in comment**

The comment says "blocks for up to sendTimeout + recvTimeout (default 8s total)", but this call passes `completionTimeout` (1.0 s) as the custom timeout for both send and recv, so the actual worst-case block is 2.0 s, not 8 s.

```suggestion
        // Note: if Hammerspoon is unresponsive, this blocks for up to
        // completionTimeout × 2 = 2s (1s send + 1s recv).
```

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