TokenCoffeeWin

TokenCoffeeWin is a Windows-focused port of Token Coffee. It is intentionally a separate repository from the Swift/macOS app.

The implementation uses .NET and Avalonia so the dashboard can be developed and screenshot-checked on macOS while still publishing a Windows tray app.

Current Status

This is a working MVP scaffold, not full feature parity with the macOS app yet. See PLAN.md for the remaining parity checklist and done criteria.

• macOS development harness runs as a normal Avalonia window.
• Windows builds are publishable from macOS with the Windows target framework and win-x64 runtime.
• Demo/evidence mode renders a deterministic quota dashboard.
• The dashboard follows Avalonia's effective theme, so Windows can use the OS light/dark app mode. --theme light|dark|system can force a theme for local evidence.
• Real Codex device-code sign-in and usage fetch code is present.
• Sign-in lifecycle handling for cancellation, completion refresh, and abandoned-login retry has local model tests.
• A Debug-only mock Codex auth mode captures local sign-in and cancel UI evidence without touching the live service.
• Expired sign-in and empty usage-refresh errors have local model tests and user-facing fallback text.
• Codex device-code request, pending poll, token exchange, and auth-token storage have local fake-service client tests.
• Codex token refresh, unauthorized retry, and rejected refresh-token cleanup have local client tests.
• The non-Windows JSON dev token store has local persistence/deletion tests, including logout cleanup.
• Runtime demo mode can be toggled from the app menu while preserving and restoring live quota/auth display state.
• Forecasting uses a C# port of the macOS app's TokenUsageForecast-style projection, including cycle-run segment/corridor data used by the graph.
• The demo graph renders day bands, over-limit shading, forecast corridor fill, and low/high forecast segment lines.
• The tray and in-panel menus share actions for Open/Close, About, Log in/Log out, Export Forecast Diagnostics, Enable/Disable Demo Mode, and Quit.
• Tray menu labels, enabled states, active/off icon choice, and power-mode tooltip text have local presentation tests.
• The tray panel placement math is locally tested to clamp the dashboard inside the screen working area.
• On Windows, the borderless dashboard can be dragged from non-button areas and restores its last saved position on the next launch.
• Windows power requests are isolated behind a Windows-only controller, with local tests for Off/System/Display request mapping.
• Preferred power mode is persisted locally.
• AppModel tests cover preferred power mode load/save and panel-open quota refresh throttling.
• Demo forecast diagnostics can be exported from the command line.
• iCloud/CloudKit sync is intentionally absent; Windows v1 is local-only.
• Current friend-test/v1 zip builds are intentionally unsigned. Windows SmartScreen warnings are expected.

Requirements

• .NET 10 SDK
• regionshot on PATH for local screenshot evidence

No Windows license, Visual Studio license, CrossOver license, VM, or paid cloud runner is required for local development.

Local Run

scripts/run-demo.sh

This runs the macOS development harness with deterministic demo data.

Screenshot Evidence

scripts/capture-local-demo.sh

The script builds the app, launches forced-light and forced-dark demo runs, captures the frontmost Avalonia window with RegionShot, and writes artifacts to:

artifacts/evidence/macos-dev/

Current scripted outputs:

artifacts/evidence/macos-dev/demo-dashboard.png
artifacts/evidence/macos-dev/demo-dashboard-dark.png
artifacts/evidence/macos-dev/signin-needs-signin.png
artifacts/evidence/macos-dev/signin-device-code.png
artifacts/evidence/macos-dev/signin-cancelled.png

Use ScreenCaptureKit window capture for Avalonia. RegionShot visible-window capture can include background pixels for this app surface.

Sign-In Smoke Evidence

scripts/capture-signin-smoke.sh

This Debug local harness uses --mock-codex-auth to avoid the live Codex service, enters the device-code screen, presses Cancel, and captures the returned needs-sign-in state.

Forecast Diagnostics

scripts/export-demo-diagnostics.sh

The script writes:

artifacts/evidence/macos-dev/demo-diagnostics.json

The app menu action writes forecast diagnostics to the default local diagnostics folder. On Windows that path is:

%LocalAppData%\TokenCoffee\Diagnostics\TokenCoffee-ForecastDiagnostics-YYYYMMDD-HHMMSS.json

Test

scripts/test.sh

Windows Package

scripts/package-windows.sh

The script publishes and verifies a self-contained unsigned win-x64 build, recreates the zip from scratch, and writes:

dist/TokenCoffeeWin-win-x64.zip

The zip includes README-Windows.txt with run instructions and the short friend-test checklist. Package verification checks required runtime files, the packaged README, and an exact match between the publish directory and zip entries. Friends can test that zip on real Windows machines. See FRIEND_TESTING.md.

Use RELEASE_CHECKLIST.md before treating a zip as release-ready. Accepted proof is tracked in EVIDENCE.md.

Windows friend evidence packets should follow artifacts/evidence/windows-friend/README.md and can be checked with:

scripts/verify-windows-evidence.sh artifacts/evidence/windows-friend/YYYY-MM-DD-description