app-it-windows

# app-it-windows - Make a project launchable on Windows (beta) **Windows beta: scaffolded, untested on real hardware, maintainer wanted.** The macOS `app-it` lane is proven. This Windows sibling mirrors the contract with Windows primitives, but every runtime behavior that needs a real Windows desktop must be marked deferred: `this needs a Windows maintainer - see docs/WINDOWS.md`. ## Non-Negotiables 1. Run `templates/inspect.ps1` first and read the output before editing. 2. Trust disk over docs. Verify project type, scripts, ports, and desktop signals from files. 3. Build everything a Mac or CI can build; never claim Windows runtime behavior works unless it was verified on real Windows hardware. 4. Prefer the WPF + WebView2 host. Edge `--app=` is a fallback, not the default. 5. Keep Windows visibly beta in every report and user-facing summary. 6. Copy shipped templates and customize through `scripts\app-it.config.json`. Do not re-derive launcher patterns. 7. Verify build/lint/config checks, then list hardware-only checks as deferred. ## Reference Map Open only what the inspection or chosen path needs: - `references/maintainer-contract.md` - what a Mac can produce, what must be deferred, and the exact Windows-maintainer phrase. - `references/inspection-and-strategies.md` - project inspection, toolchain probes, strategy tree, W-Native, W-Edge, W-Static, W-Multi, B, and D. - `references/generated-files.md` - template roster, allowed target files, config JSON, package scripts, and Start Menu destination. - `references/wrapper-host.md` - WebView2 host, lifecycle, Job Object ownership, single-instance behavior, and wrapper argument contract. - `references/verification.md` - buildable checks, Windows-only checks, and deferred rows. - `references/report-template.md` - exact beta report format. ## Templates Templates live next to this file in `templates/`. Copy them into the target project and keep their contracts intact: ```text templates/ wrapper-windows/ desktop-build.ps1 desktop-install.ps1 desktop-quit.ps1 inspect.ps1 run-template.ps1 run-template-edge.ps1 desktop-icons.ps1 placeholder-icon-gen.ps1 PSScriptAnalyzerSettings.psd1 app-it.config.example.json ``` The comments inside templates encode Windows traps: PATH augmentation, WebView2/.NET prerequisites, free-port probing, Job Object ownership, Start Menu shortcuts, SmartScreen, and icon-cache behavior. Read the matching reference before changing launcher internals. ## Workflow ### 1. Inspect Run the bundled probe from the target project root: ```powershell pwsh -File path\to\plugins\app-it-windows\skills\app-it-windows\templates\inspect.ps1 ``` Read `references/inspection-and-strategies.md` before deciding project shape, ports, existing desktop tooling, names, icons, or strategy. ### 2. Decide For each user-facing app: ```text Existing Electron/Tauri/NW.js Windows target? yes -> Strategy B no -> native desktop requirement beyond web shell? yes -> Strategy D no -> .NET 8 buildable and WebView2 expected? no -> W-Edge fallback yes -> static built bundle, no server? yes -> W-Static no -> cohabiting frontend + backend? yes -> W-Multi no -> W-Native (default) ``` WebView2 is Chromium, so File System Access and other Chromium APIs are reasons to prefer the WPF host, not reasons for a polyfill. ### 3. Build Touch as little project surface as possible. Copy the selected templates, write `scripts\app-it.config.json`, add `desktop:*` package scripts, and generate the `.ico`/published output when tooling is present. Read `references/generated-files.md` before editing scripts/config/docs, and `references/wrapper-host.md` before changing the host or PowerShell lifecycle. ### 4. Verify On macOS, only claim buildable evidence: .NET publish when available, PowerShell lint when available, manifest/config parse, and placeholder icon round-trip in Windows CI. Everything involving a real window, Taskbar identity, tray Quit, Start Menu icon cache, SmartScreen, DPI, or Job Object tree reaping stays deferred with the maintainer phrase. Read `references/verification.md` before reporting results. ### 5. Report Use `references/report-template.md` inline and in `docs\desktop-launcher.app-it-report.md`. Keep beta wording visible, separate build/lint evidence from runtime unknowns, and append decision history. Stage files only when the local convention or user request asks for it. Do not commit unless asked. ## Quick Defaults - Install destination: `%APPDATA%\Microsoft\Windows\Start Menu\Programs\app-it\`. - Runtime state: `%LOCALAPPDATA%\app-it\<slug>\`. - Bundle ID/key prefix: `com.user.<slug>`. - Default strategy: W-Native when .NET 8 can build and WebView2 is expected. - Fallback: W-Edge only when host prerequisites are unavailable. - Icon sizes: `16, 32, 48, 64, 128, 256`. - First-run signing stance: unsigned; SmartScreen click-through documented. ## Stop Signs Stop and mark deferred or blocked when only Windows hardware can decide, when the required build toolchain is missing and no fallback fits, when a port cannot be made env-driven, when a template needed for the selected strategy is absent, or when the requested claim would imply real Windows runtime verification that has not happened.