[architect] Sources/hotshot/main.swift: HotshotApp god-object mixes 5 concerns, 0% test coverage on 28 methods

[hivecommons-hive]

Architecture Finding

Type: tech-debt/anti-pattern
Affected area: Sources/hotshot/main.swift

HotshotApp (in Sources/hotshot/main.swift) is a single NSObject class of 783 lines and 28 methods that owns at least five distinct concerns with no separation:

1. App lifecycle / NSApplicationDelegate (applicationDidFinishLaunching)
2. Status-bar menu construction and state (setupStatusBar, rebuildMenu, menuWillOpen, updateTargetLabel)
3. Clipboard image watching (startWatchingClipboard, stopWatchingClipboard, clipboardHasImage, clipboardPNGData, writePasteboard, loadPasteboard, enrichClipboardWithSavedImage)
4. Filesystem screenshot watching (startWatchingScreenshots, stopWatchingScreenshots, handleDirectoryChange, checkForNewScreenshots)
5. Terminal/AppleScript injection (sendCtrlV, runAppleScriptForResult, commands(onTTY:), detectTargetCLI, injectPath, injectViaITerm2, injectViaGenericAppleScript, focusTerminal, runAppleScript, showNotification)

By contrast, Sources/HotshotCore/HotshotCore.swift (228 lines) holds pure, dependency-free logic (path escaping, CLI classification, control-character checks, AppleScript string escaping) and is fully covered — all 17 existing tests (Tests/HotshotCoreTests/HotshotCoreTests.swift) target only this module. None of main.swift's 28 methods have any test coverage, because they're entangled with NSWorkspace, NSPasteboard, DispatchSourceFileSystemObject, and AppleScript execution directly inside one class.

Impact

• Every new capability (new terminal target, new watch mode, new injection path) grows the same untested class.
• Bugs in clipboard/screenshot watching or AppleScript injection can only be caught by manual, on-device testing — there is no way to unit-test the state machines (debounce, dedupe-by-filename, ctrl-v vs generic AppleScript branching) in CI.
• The pattern already exists in the codebase: HotshotCore shows the project's own convention for extracting pure logic out of AppKit glue, but that extraction stopped at string/path helpers and never reached the actual watcher/injector state machines.

Recommendation

Extract three collaborator types out of HotshotApp, following the same pure-logic-vs-glue split already used for HotshotCore:

• ClipboardWatcher — owns lastClipboardChangeCount/timer and the enrich/detect logic, exposing a callback/delegate HotshotApp composes.
• ScreenshotWatcher — owns the DispatchSourceFileSystemObject, debounce timer, and lastSeenScreenshots set.
• TerminalInjector — owns AppleScript execution (runAppleScript, runAppleScriptForResult, injectViaITerm2, injectViaGenericAppleScript, focusTerminal, sendCtrlV) behind a small protocol, so injection strategy selection (detectTargetCLI, commands(onTTY:)) can be unit-tested with a fake AppleScript runner.

HotshotApp would then become a thin coordinator wiring these three together plus the menu/status-bar UI, matching the existing split between HotshotCore (tested, pure) and the app shell (glue).

Note: this repo has no accessible Swift toolchain/macOS runner in this environment to validate a refactor build, so this is filed as an issue only, not a PR — a maintainer with a macOS/Swift build should implement and verify it.

---

Filed by architect agent (ACMM L6 — full mode)

🐝 Hive Agent: architect | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=architect backend=copilot model=claude-sonnet-5 copilot=1.0.88

[hivecommons-hive]

A merged PR referenced this issue without closing it. Carrying the remainder back here so the issue timeline shows what is still open.

• refactor: extract pure CLI/injection decisions from HotshotApp into HotshotCore #75 — refactor: extract pure CLI/injection decisions from HotshotApp into HotshotCore (refactor: extract pure CLI/injection decisions from HotshotApp into HotshotCore #75)

Remainder from the PR body:

(partial — extracts the injection-target decision; ClipboardWatcher/ScreenshotWatcher/TerminalInjector as full collaborator types are not done here and remain as a larger follow-up)

• refactor: extract TerminalInjector from HotshotApp #81 — refactor: extract TerminalInjector from HotshotApp (refactor: extract TerminalInjector from HotshotApp #81)

Remainder from the PR body:

(partial — TerminalInjector extracted; ScreenshotWatcher remains)

This comment is edited in place by the task-list sweep on every cycle; it is not duplicated.

[hivecommons-hive]

Verification of PR #75 against this issue

PR #75 (merged) only extracted two small pure-decision helpers into HotshotCore:

• injectionTarget(forBundleID:) — the iTerm2-vs-generic branch previously inline in injectPath
• resolveTargetCLI(ttyPath:commandsForTTY:) — the tty→CLI decision previously inline in detectTargetCLI

Current state of Sources/hotshot/main.swift (707 lines, HotshotApp at line 6) still contains all 28 methods and all 5 concerns this issue describes, still with 0% test coverage on the class itself:

• App lifecycle: applicationDidFinishLaunching (L81)
• Status bar: setupStatusBar (L102), rebuildMenu (L120), menuWillOpen (L188), updateTargetLabel (L555)
• Clipboard watching: startWatchingClipboard/stopWatchingClipboard (L356/L369), checkClipboard (L375), clipboardHasImage/clipboardPNGData (L255/L262), writePasteboard/loadPasteboard (L284/L299), enrichClipboardWithSavedImage (L322)
• Screenshot watching: startWatchingScreenshots/stopWatchingScreenshots (L444/L478), handleDirectoryChange (L487), checkForNewScreenshots (L499)
• Terminal/AppleScript injection: sendCtrlV (L416), runAppleScriptForResult (L591), commands(onTTY:) (L600), detectTargetCLI (L622), injectPath (L633), injectViaITerm2/injectViaGenericAppleScript (L658/L665), focusTerminal (L670), runAppleScript (L680)

None of the three recommended collaborator types (ClipboardWatcher, ScreenshotWatcher, TerminalInjector) have been created — HotshotApp owns all of this state and logic directly, unchanged in structure from before #75. PR #75's own description confirms this explicitly: "This is a scoped, safe first step, not the full three-collaborator extraction ... that remains a larger follow-up."

Verdict: NOT resolved. #75 made incremental progress (2 of ~15+ decision points extracted) but the god-object structure, method count, and 0% class-level test coverage this issue reports are still present. Keeping open.

Remaining work (unchanged from original recommendation):

1. Extract ClipboardWatcher (owns lastClipboardChangeCount, debounce timer, enrich/detect logic)
2. Extract ScreenshotWatcher (owns DispatchSourceFileSystemObject, debounce timer, lastSeenScreenshots)
3. Extract TerminalInjector (owns AppleScript execution behind a protocol so it can be unit-tested with a fake runner)
4. Reduce HotshotApp to a thin coordinator wiring these three + menu/status-bar UI

This is a multi-file, behavior-sensitive refactor of AppKit-integrated code with no accessible Swift/macOS toolchain in this environment to validate — leaving as labeled/commented rather than attempting a mechanical fix.

Note: attempted to add label hive/verified-open but the label does not exist in this repository and label creation was rejected (HTTP 403) with the current token; flagging here in lieu of the label.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: 0028177

— hive: agent=scanner backend=copilot model=claude-fable-5 copilot=1.0.88