Initial portable Caffeine implementation

README.md

@@ -0,0 +1,119 @@
+# Portable Caffeine (PowerShell 5.1 + Embedded C#)
+
+Portable Windows implementation of the Zhorn Software Caffeine utility, built as a single `caffeine.ps1` script with embedded C# (`WinForms` + Win32 API calls).
+
+## What It Does
+
+Prevents sleep/idle by either:
+
+- Sending periodic key pulses (default `F15`)
+- Using `SetThreadExecutionState` (`-stes`)
+
+It also includes a tray icon app, status dialog, timers, rule-based activation, and single-instance app control commands.
+
+## Files
+
+- `caffeine.ps1`: main portable app
+- `run-caffeine.bat`: launcher that runs with `-ExecutionPolicy Bypass -STA`
+
+## Requirements
+
+- Windows
+- Windows PowerShell 5.1
+- Desktop session (uses `System.Windows.Forms` + tray icon)
+
+## Quick Start
+
+Run with the batch launcher:
+
+```bat
+run-caffeine.bat -showdlg -notify
+```
+
+Or directly:
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -STA -File .\caffeine.ps1 -showdlg -notify
+```
+
+## Execution Policy Note
+
+If PowerShell blocks script execution, use the launcher (`run-caffeine.bat`) or run:
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -STA -File .\caffeine.ps1
+```
+
+Optional:
+
+```powershell
+Unblock-File .\caffeine.ps1
+```
+
+## Supported Features / Switches
+
+Core:
+
+- `-on` / `-off`
+- `-activefor:N`
+- `-inactivefor:N`
+- `-exitafter:N`
+- `-lock`
+- `-notify`
+- `-showdlg`
+- `-ontaskbar`
+- `-replace`
+
+Single-instance app commands:
+
+- `-appexit`
+- `-appon`
+- `-appoff`
+- `-apptoggle`
+- `-apptoggleshowdlg`
+
+Activity methods:
+
+- Default F15 key pulse
+- `-useshift`
+- `-leftshift`
+- `-key:NN` / `-keypress:NN`
+- `-keyshift[:NN]`
+- `-stes`
+- `-allowss`
+
+Conditional activation:
+
+- `-watchwindow:TEXT`
+- `-activeperiods:RANGES`
+- `-activehours:RANGES` (alias)
+- `-onac`
+- `-cpu:N`
+
+Tray / icon behavior:
+
+- Custom coffee-cup tray icon (active/inactive variants)
+- `-nohicon` keeps the same tray icon in both states
+- Double-click tray icon toggles active/inactive
+
+Compatibility:
+
+- `-allowlocal` is recognized (compatibility flag)
+
+## Examples
+
+```bat
+run-caffeine.bat -showdlg -notify
+run-caffeine.bat -activefor:30
+run-caffeine.bat -watchwindow:Notepad -on
+run-caffeine.bat -activeperiods:08:00-12:00,13:00-17:00
+run-caffeine.bat -stes -allowss
+run-caffeine.bat -apptoggle
+run-caffeine.bat -replace -off
+```
+
+## Notes
+
+- This project is intended to be portable (no install required).
+- The implementation targets Windows PowerShell 5.1 and Windows desktop APIs.
+- Exact visual/behavioral parity with the original Zhorn Caffeine may differ slightly in some edge cases.

run-caffeine.bat

@@ -0,0 +1,13 @@
+@echo off
+setlocal
+
+set "SCRIPT_DIR=%~dp0"
+set "PS_SCRIPT=%SCRIPT_DIR%caffeine.ps1"
+
+if not exist "%PS_SCRIPT%" (
+  echo Could not find "%PS_SCRIPT%".
+  exit /b 1
+)
+
+powershell.exe -NoProfile -ExecutionPolicy Bypass -STA -File "%PS_SCRIPT%" %*
+exit /b %ERRORLEVEL%