Desktop & CLI Apps Standards

Overview

This standard covers desktop applications and CLI tools — PowerShell-based WinForms apps, .NET native utilities, and system-level tools. These projects have unique constraints: no web dependencies, local-only execution, system API access, and distribution as standalone binaries.

Prerequisites: General Standards (file structures, Git, a11y, privacy).

What this covers:

• PowerShell WinForms GUI applications
• .NET console and desktop tools
• Standalone EXE distribution (PS2EXE, native compilation)
• System monitoring and management utilities
• Game optimization tools (config file manipulation, system tweaks)

Tech Stack (2026)

Why PowerShell + WinForms:

• Zero dependencies on target machines — PowerShell is pre-installed on all modern Windows
• WinForms provides native Windows UI without additional runtimes
• PS2EXE compiles to a standalone ~86KB EXE with no external runtime
• Direct access to Windows APIs (WMI, registry, file system) without P/Invoke wrappers

When to use .NET instead:

• Cross-platform requirements (use Avalonia or MAUI)
• Complex threading or async operations
• Need for a proper compiler/language (C# type safety)
• Performance-sensitive applications

Project Scaffolding

File Structure (PowerShell Desktop App)

project-root/
├── src/
│   ├── Main.ps1                  # Application entry point
│   ├── Forms/                    # WinForms UI definitions
│   │   ├── MainForm.ps1          # Primary window
│   │   ├── SettingsDialog.ps1    # Settings UI
│   │   └── AboutDialog.ps1       # About dialog
│   ├── Services/                 # Business logic modules
│   │   ├── OptimizationEngine.ps1
│   │   ├── BackupManager.ps1
│   │   └── SystemDetection.ps1
│   ├── Utils/                    # Pure utility functions
│   │   ├── ConfigParser.ps1      # INI/config file parsing
│   │   ├── RegistryHelper.ps1    # Registry operations
│   │   └── Logging.ps1           # Application logging
│   └── Types/                    # Custom PS classes and enums
├── tests/
│   └── Pester/                   # Pester unit tests
├── scripts/
│   ├── build.ps1                 # Build script (PS2EXE compilation)
│   └── sign.ps1                  # Code signing script
├── assets/
│   ├── icon.ico                  # Application icon
│   └── banner.png                # GUI banner image
├── .github/
│   └── workflows/                # CI/CD (GitHub Actions + Pester)
├── README.md
├── PRIVACY.md                    # Privacy policy (required for store submission)
└── SECURITY.md                   # For sensitive system tools

Build Pipeline (PS2EXE)

# scripts/build.ps1
$params = @{
    InputFile  = 'src/Main.ps1'
    OutputFile = "dist/MyApp-$($env:APP_VERSION).exe"
    Arguments  = '-sta'                    # Single-threaded apartment
    ErrorAction = 'Stop'
    NoConsole  = $false                    # Console for CLI, $true for GUI-only
}
PS2EXE\Invoke-PS2EXE @params

# Sign the executable
signtool sign /fd SHA256 /a /f cert.pfx /p $env:CERT_PASSWORD /tr http://timestamp.digicert.com $params.OutputFile

Architecture & Design Patterns

WinForms GUI Architecture

Main.ps1 (Entry Point)
├── [STAThread] — required for WinForms
├── Application.EnableVisualStyles()
├── Application.SetCompatibleTextRenderingDefault(false)
├── Privacy consent check (first-run dialog)
└── Application.Run(MainForm)

MainForm.ps1
├── TabControl (for multi-feature apps)
│   ├── Dashboard Tab — hero action + status cards + log
│   ├── Settings Tab — config comparison grid
│   ├── Advanced Tab — detailed options
│   └── Backups Tab — backup list + restore
├── Event handlers (button clicks, selection changes)
├── Background workers (for long-running operations)
└── Error handling (try/catch on all operations)

Key WinForms Patterns

• TabControl for organizing multiple features (see Arc Optimizer’s 7-tab layout)
• DataGridView for tabular data (settings comparison, backup lists)
• DoEvents for UI responsiveness during long operations (WMI queries, file scans)
• Color-coded status — green (success/ok), red (error), orange (attention needed)
• System theme detection — read Windows Registry for dark/light mode preference

System Detection Pattern (PowerShell)

function Get-GPUInfo {
    $gpu = Get-WmiObject Win32_VideoController | Where-Object { $_.Name -match 'NVIDIA|AMD|Intel' } | Select-Object -First 1
    return @{
        Name = $gpu.Name
        DriverVersion = $gpu.DriverVersion
        VRAM = [math]::Round($gpu.AdapterRAM / 1GB, 1)
    }
}

Performance Standards

Privacy & Security

Mandatory Practices

• Zero network calls — No telemetry, no analytics, no update checks (unless explicitly a network-dependent tool)
• Privacy consent dialog — First run: explain what the tool modifies, get explicit consent
• Local-only operation — All data processed on-device, never transmitted
• Rollback capability — Every modification creates a timestamped backup (.bak) with one-click restore
• No registry writes (unless core to the tool’s function)
• File permissions — Set config files to read-only after modification to prevent game/app reverting changes

Distribution Security

• Code signing — Sign the EXE with a digital certificate to prevent SmartScreen warnings
• SHA256 checksums — Publish checksums for every release
• VirusTotal scan — Run before release distribution (false positives are common for PS2EXE)
• GitHub Releases — Primary distribution channel

Review & Shipping Checklist

• Privacy consent dialog implemented
• All operations wrapped in try/catch with user-visible error messages
• Backup/restore mechanism verified (create, list, restore, verify)
• Keyboard navigation tested (Tab, Enter, Escape, Ctrl+shortcuts)
• Screen reader tested (AccessibleName and AccessibleRole set on all controls)
• Dark/light theme detection and application
• Standalone EXE build tested on clean Windows VM (no PowerShell modules pre-installed)
• VirusTotal scan clean (or false positive reported/documented)
• GitHub release with checksums
• README with usage instructions, system requirements, and privacy statement
• EXE size within target

Trends to Watch (2026+)

• PowerShell 7+ cross-platform adoption for Linux/macOS support
• .NET AOT compilation producing smaller, faster binaries without runtime dependency
• Windows Package Manager (winget) for distribution
• System-level AI integration — Desktop Copilot, Windows Copilot hooks for app control
• Security hardening — Windows 11 increasing SmartScreen and executable validation

Project Templates

• Arc Optimizer — Reference: PowerShell WinForms app with zero dependencies, system detection, backup management
• OpenClaw WinHealth — Reference: System monitoring CLI + desktop tool

References

• Arc Optimizer project page — Full production-grade desktop app architecture
• OpenClaw Windows Health Monitor project page — System monitoring patterns
• External: PowerShell Documentation, WinForms Best Practices, PS2EXE Project