caffeine/tasks/todo.md

Portable Caffeine Clone (PowerShell 5.1 + Embedded C#)

Plan

• Confirm feature parity target from https://www.zhornsoftware.co.uk/caffeine/ (current switches + tray behavior)
• Define implementation architecture (single script, embedded C# helpers, tray UI, single-instance IPC)
• Implement command-line parsing and normalized parameter model
• Implement activity engine (F15/Shift/custom key, key up vs keypress, STES, allow screensaver)
• Implement conditional activation rules (-watchwindow, -activeperiods/-activehours, -onac, -cpu)
• Implement timers (-exitafter, -activefor, -inactivefor) and state transitions
• Implement tray app UX (double-click toggle, active/inactive menu, timed menu, revert-to-parameters, about, exit)
• Implement single-instance behavior and remote app commands (-appexit, -appon, -appoff, -apptoggle, -apptoggleshowdlg, -replace)
• Implement notifications (-notify) and optional status dialog (-showdlg, -ontaskbar)
• Verify script loads/parses and document limitations from non-Windows validation environment

Progress Notes

• Initial scope confirmed from Zhorn feature list (includes v1.98-era switches like -activeperiods and -notify).
• Implemented caffeine.ps1 as a portable single-script app with embedded C# WinForms runtime.
• Added single-instance IPC via hidden window + WM_COPYDATA for -app* commands and -replace.
• Added conditional activation (-watchwindow, -activeperiods, -activehours, -onac, -cpu) and timers (-activefor, -inactivefor, -exitafter).
• Added activity methods (default F15 key pulse, Shift variants/custom keys, -stes, -allowss) and tray/status UX.
• Updated tray icons to custom coffee-cup active/inactive variants (with -nohicon preserving the same icon in both states).
• Added build-caffeine-exe.ps1 to extract embedded C# from caffeine.ps1 and compile dist\PortableCaffeine.exe with csc.exe.
• Added a Main() entry point to the embedded PortableCaffeine.Program class so the same source compiles directly as an EXE.
• Added sign-caffeine-exe.ps1 (PowerShell + embedded C# helper) to create/reuse a self-signed code-signing cert, optionally trust it (CurrentUser/LocalMachine), and sign the compiled EXE.
• Static review patch: fixed ambiguous Timer type and prevented -app* switches from starting a new instance when no instance is running.

Review

• Runtime verification is still pending because this environment is macOS and does not have pwsh installed, so I could not run a PowerShell parser check or Windows UI/API smoke test here.
• EXE build verification is also pending in this environment (no Windows .NET Framework csc.exe available here).
• Self-signed certificate creation/trust-store installation/signing verification is also pending in this environment (requires Windows cert stores and Set-AuthenticodeSignature).
• The implementation is intended for Windows PowerShell 5.1 (STA) and relies on System.Windows.Forms, user32.dll, and kernel32.dll.