Add --bring to surface specific windows by HWND, process, or pattern

[djdarcy]

Summary

Add a --bring command to surface specific windows by HWND, process name, or fnmatch pattern — with optional --topmost to pin them above other windows.

Motivation

Currently --filter targets windows by pattern but still runs through the full enumeration/scoring pipeline. Users need a quick, surgical way to bring a specific window forward — especially when they already know the HWND or process name. This is a common workflow when a window is lost off-screen or buried under others.

Proposed Behavior

Targeting

wingather --bring 0x1234              # by HWND (hex or decimal)
wingather --bring notepad.exe         # by process name (fnmatch)
wingather --bring "*Untitled*"        # by title pattern (fnmatch)

Confirmation for Multiple Matches

When --bring matches more than one window, display the list and prompt for confirmation:

Found 3 windows matching "chrome*":
  1. 0x001A2B  chrome.exe    "GitHub - Google Chrome"
  2. 0x001A3C  chrome.exe    "Stack Overflow - Google Chrome"
  3. 0x001A4D  chrome.exe    "New Tab - Google Chrome"

Bring all 3 to foreground? [Y/n]

Single match: act immediately, no prompt.

Actions

• Default: center + bring_to_front (one-time z-order raise)
• --topmost: center + bring_to_front + SetWindowPos(HWND_TOPMOST) (sticky pin)

Foreground vs TOPMOST

Action	Behavior	Persistence	Use Case
bring_to_front	One-time z-order raise	Gone when user clicks elsewhere	"Show me this window"
TOPMOST	Sticky pin above all non-TOPMOST	Stays until explicitly cleared	"Keep this visible"

--topmost should be opt-in since the user is intentionally selecting windows, not reacting to threats.

Interaction with Other Flags

• --dry-run compatibility would be nice but is not required for phase 1. Could be a phase 2 addition showing what would be brought forward without acting.
• --bring should bypass the full scoring pipeline — no need to enumerate all windows, flag suspicious, etc. Just find the target(s) and act.

Phase 1

• --bring <target> accepting HWND (numeric), process name, or fnmatch pattern
• Confirmation prompt when multiple windows match (Y/n)
• Default action: center + bring_to_front
• --topmost modifier for sticky pin
• Single match: act immediately

Phase 2 (future)

• --dry-run support for --bring (preview without acting)
• Regex support in addition to fnmatch
• Multiple --bring arguments (--bring notepad.exe --bring calc.exe)