Import current workspace

README.md

@@ -0,0 +1,204 @@
+# 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`
+- `build-caffeine-exe.ps1`: extracts embedded C# and compiles a standalone `.exe`
+- `sign-caffeine-exe.ps1`: creates/reuses a self-signed code-signing cert, optionally trusts it, and signs the `.exe`
+
+## 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
+```
+
+## Compile To EXE (Windows)
+
+You can build a standalone executable from the embedded C# code in `caffeine.ps1`:
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\build-caffeine-exe.ps1
+```
+
+Output (default):
+
+- `dist\PortableCaffeine.exe`
+
+Useful options:
+
+```powershell
+# Keep the extracted .cs file used for compilation
+.\build-caffeine-exe.ps1 -KeepExtractedSource
+
+# Build a console-targeted EXE instead of WinExe
+.\build-caffeine-exe.ps1 -ConsoleTarget
+
+# Custom output name/path
+.\build-caffeine-exe.ps1 -OutputDir .\out -ExeName Caffeine.exe
+```
+
+Notes:
+
+- The build script looks for `.NET Framework` `csc.exe` on Windows (Framework64 first, then Framework).
+- The compiled EXE uses the same tray UI, switches, and behavior as the PowerShell-hosted version.
+
+## Self-Signed Code Signing (Dev/Test)
+
+You can sign the compiled EXE with a locally generated self-signed code-signing certificate.
+
+Default behavior:
+
+- Reuses an existing cert matching the configured subject (if present)
+- Otherwise creates a new self-signed code-signing cert
+- Exports the public cert to `dist\PortableCaffeine-dev-signing.cer`
+- Installs trust in `CurrentUser\Root` and `CurrentUser\TrustedPublisher`
+- Signs `dist\PortableCaffeine.exe` with `Set-AuthenticodeSignature`
+
+Command:
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\sign-caffeine-exe.ps1
+```
+
+Machine-wide trust (all users, requires admin):
+
+```powershell
+# Run PowerShell as Administrator
+.\sign-caffeine-exe.ps1 -TrustScope LocalMachine
+```
+
+Notes on admin requirements:
+
+- `CurrentUser` trust/store operations do not require admin.
+- `LocalMachine` trust (`Root` / `TrustedPublisher`) requires an elevated PowerShell session.
+- Creating the private key in `LocalMachine\My` also requires admin (`-PrivateKeyStoreScope LocalMachine`).
+
+Useful options:
+
+```powershell
+# Force creation of a new self-signed certificate instead of reusing an existing one
+.\sign-caffeine-exe.ps1 -ForceNewCertificate
+
+# Sign without installing trust stores (signature will be present but likely untrusted)
+.\sign-caffeine-exe.ps1 -TrustScope None
+
+# Export a PFX (password required)
+.\sign-caffeine-exe.ps1 -PfxExportPath .\dist\PortableCaffeine-dev-signing.pfx -PfxPassword (Read-Host -AsSecureString)
+
+# Use a timestamp server (optional)
+.\sign-caffeine-exe.ps1 -TimestampServer http://timestamp.digicert.com
+```
+
+Security note:
+
+- Trusting a self-signed certificate in `Root` makes your machine trust anything signed by that certificate.
+- Use a dedicated dev/test certificate, protect the private key, and remove trust when no longer needed.
+- This is suitable for local/internal testing, not a substitute for a public CA-issued code-signing certificate.
+
+## 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.