caffeine/README.md

# 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.