From 3ccfab473cd159b7d0243e6166f87dec99bb28ca Mon Sep 17 00:00:00 2001 From: Alvin Ashcraft <73072+alvinashcraft@users.noreply.github.com> Date: Sun, 3 May 2026 15:48:37 -0400 Subject: [PATCH 1/7] Update winapp CLI skill --- docs/README.skills.md | 2 +- skills/winapp-cli/SKILL.md | 76 +++++++++++++++++++++++++++++--------- 2 files changed, 60 insertions(+), 18 deletions(-) diff --git a/docs/README.skills.md b/docs/README.skills.md index 830360abb..4b90cc85b 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -350,7 +350,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [web-design-reviewer](../skills/web-design-reviewer/SKILL.md)
`gh skills install github/awesome-copilot web-design-reviewer` | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` | | [webapp-testing](../skills/webapp-testing/SKILL.md)
`gh skills install github/awesome-copilot webapp-testing` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `assets/test-helper.js` | | [what-context-needed](../skills/what-context-needed/SKILL.md)
`gh skills install github/awesome-copilot what-context-needed` | Ask Copilot what files it needs to see before answering a question | None | -| [winapp-cli](../skills/winapp-cli/SKILL.md)
`gh skills install github/awesome-copilot winapp-cli` | Windows App Development CLI (winapp) for building, packaging, and deploying Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml, manage development certificates, add package identity for debugging, sign packages, publish to the Microsoft Store, create external catalogs, or access Windows SDK build tools. Supports .NET (csproj), C++, Electron, Rust, Tauri, and cross-platform frameworks targeting Windows. | None | +| [winapp-cli](../skills/winapp-cli/SKILL.md)
`gh skills install github/awesome-copilot winapp-cli` | Windows App Development CLI (winapp) for building, packaging, deploying, debugging, and UI-automating Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml (including from SVG assets), manage development certificates (generate, install, inspect via `cert info`, export public keys), add package identity for debugging, run apps as packaged via loose-layout registration (`winapp run`), unregister sideloaded dev packages, sign packages, publish to the Microsoft Store, create external catalogs (CodeIntegrityExternal.cat for TrustedLaunch sparse packages), automate Windows UI interactions (list windows, inspect elements, click) via Microsoft UI Automation, or access Windows SDK build tools. Supports .NET (csproj), C++, Electron, Rust, Tauri, Flutter, and cross-platform frameworks targeting Windows. | None | | [winmd-api-search](../skills/winmd-api-search/SKILL.md)
`gh skills install github/awesome-copilot winmd-api-search` | Find and explore Windows desktop APIs. Use when building features that need platform capabilities — camera, file access, notifications, UI controls, AI/ML, sensors, networking, etc. Discovers the right API for a task and retrieves full type details (methods, properties, events, enumeration values). | `LICENSE.txt`
`scripts/Invoke-WinMdQuery.ps1`
`scripts/Update-WinMdCache.ps1`
`scripts/cache-generator` | | [winui3-migration-guide](../skills/winui3-migration-guide/SKILL.md)
`gh skills install github/awesome-copilot winui3-migration-guide` | UWP-to-WinUI 3 migration reference. Maps legacy UWP APIs to correct Windows App SDK equivalents with before/after code snippets. Covers namespace changes, threading (CoreDispatcher to DispatcherQueue), windowing (CoreWindow to AppWindow), dialogs, pickers, sharing, printing, background tasks, and the most common Copilot code generation mistakes. | None | | [workiq-copilot](../skills/workiq-copilot/SKILL.md)
`gh skills install github/awesome-copilot workiq-copilot` | Guides the Copilot CLI on how to use the WorkIQ CLI/MCP server to query Microsoft 365 Copilot data (emails, meetings, docs, Teams, people) for live context, summaries, and recommendations. | None | diff --git a/skills/winapp-cli/SKILL.md b/skills/winapp-cli/SKILL.md index 146946260..56e1e2552 100644 --- a/skills/winapp-cli/SKILL.md +++ b/skills/winapp-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: winapp-cli -description: 'Windows App Development CLI (winapp) for building, packaging, and deploying Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml, manage development certificates, add package identity for debugging, sign packages, publish to the Microsoft Store, create external catalogs, or access Windows SDK build tools. Supports .NET (csproj), C++, Electron, Rust, Tauri, and cross-platform frameworks targeting Windows.' +description: 'Windows App Development CLI (winapp) for building, packaging, deploying, debugging, and UI-automating Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml (including from SVG assets), manage development certificates (generate, install, inspect via `cert info`, export public keys), add package identity for debugging, run apps as packaged via loose-layout registration (`winapp run`), unregister sideloaded dev packages, sign packages, publish to the Microsoft Store, create external catalogs (CodeIntegrityExternal.cat for TrustedLaunch sparse packages), automate Windows UI interactions (list windows, inspect elements, click) via Microsoft UI Automation, or access Windows SDK build tools. Supports .NET (csproj), C++, Electron, Rust, Tauri, Flutter, and cross-platform frameworks targeting Windows.' --- # Windows App Development CLI @@ -12,18 +12,22 @@ The Windows App Development CLI (`winapp`) is a command-line interface for manag Use this skill when you need to: - Initialize a Windows app project with SDK setup, manifests, and certificates -- Create MSIX packages from application directories -- Generate or manage AppxManifest.xml files -- Create and install development certificates for signing +- Create MSIX packages from application directories (with automatic WinRT component discovery) +- Generate or manage AppxManifest.xml files (including asset generation from SVG sources) +- Create, install, and inspect development certificates for signing (including `cert info` and `.cer` public-key export) - Add package identity for debugging Windows APIs +- Run an app as a packaged application via loose-layout registration with `winapp run` (great for IDE F5 / debug workflows) +- Unregister sideloaded dev packages installed by `run` or `create-debug-identity` +- Automate UI interactions on Windows apps (list windows, inspect element trees, click, search, wait-for) via Microsoft UI Automation with `winapp ui` - Sign MSIX packages or executables - Access Windows SDK build tools from any framework -- Build Windows apps using cross-platform frameworks (Electron, Rust, Tauri, Qt) +- Build Windows apps using cross-platform frameworks (Electron, Rust, Tauri, Flutter, Qt) - Set up CI/CD pipelines for Windows app deployment - Access Windows APIs that require package identity (notifications, Windows AI, shell integration) - Publish apps to the Microsoft Store via `winapp store` -- Create external catalogs for asset management +- Generate external catalogs (`CodeIntegrityExternal.cat`) for TrustedLaunch sparse packages - Set up .NET (csproj) projects with Windows App SDK via NuGet +- Import typed JS/TS functions from `@microsoft/winappcli` in Node.js/Electron projects (programmatic npm API) ## Prerequisites @@ -42,35 +46,73 @@ Initialize a directory with required assets (manifest, certificates, libraries) ### 2. MSIX Packaging (`winapp pack`) -Create MSIX packages from prepared directories with optional signing, certificate generation, and self-contained deployment bundling. +Create MSIX packages from prepared directories with optional signing, certificate generation, and self-contained deployment bundling. Automatically discovers and registers third-party WinRT components from `.winmd` files during packaging (v0.2.1+), preserves existing PRI resources, and validates executable architecture. ### 3. Package Identity for Debugging (`winapp create-debug-identity`) -Add temporary package identity to executables for debugging Windows APIs that require identity (notifications, Windows AI, shell integration) without full packaging. +Add temporary (sparse) package identity to executables for debugging Windows APIs that require identity (notifications, Windows AI, shell integration) without full packaging. -### 4. Manifest Management (`winapp manifest`) +### 4. Run as Packaged App (`winapp run`) — v0.3.0+ -Generate AppxManifest.xml files and update image assets from source images, automatically creating all required sizes and aspect ratios. Supports manifest placeholders for dynamic content and qualified names in AppxManifest for flexible app identity definitions. +Pack a folder using a loose layout and launch the application as a packaged app, making it easy to debug from any IDE (e.g., VS Code F5) without producing a full MSIX. Supports `--` passthrough for application arguments (v0.3.1+): -### 5. Certificate Management (`winapp cert`) +```bash +winapp run .\bin\Debug\net10.0-windows10.0.26100.0\win-x64 --manifest .\appxmanifest.xml -- --my-flag value +``` + +### 5. Unregister Dev Packages (`winapp unregister`) + +Remove sideloaded development packages registered by `winapp run` or `winapp create-debug-identity`. Uses segment-aware path containment and a two-pass classify-then-remove loop (v0.3.1+) to avoid sibling-directory misclassification and accidental removal of unrelated packages. + +### 6. UI Automation (`winapp ui`) — v0.3.0+ + +A command group for programmatic interaction with Windows applications via Microsoft UI Automation (UIA). Useful for end-to-end testing, scripting, and AI-agent driven UI workflows. + +Common subcommands: + +- `winapp ui list-windows` — enumerate top-level windows +- `winapp ui inspect` — inspect the UI element tree (supports `--interactive` to collapse non-interactive ancestors and surface them via `ancestorPath`, plus `--ancestors` for ancestor chains) +- `winapp ui click` — click an element by selector +- `winapp ui search` / `winapp ui wait-for` — locate or wait for elements +- `winapp ui get-focused` — get the currently focused element + +All `ui` subcommands support `--json` for machine-readable output. **Note:** the v0.3.1 release reshaped the `ui --json` envelope (see Limitations). -Generate development certificates and install them to the local machine store for signing packages. +### 7. Manifest Management (`winapp manifest`) -### 6. Package Signing (`winapp sign`) +Generate `AppxManifest.xml` files and update image assets from source images, automatically creating all required sizes and aspect ratios. Supports manifest placeholders for dynamic content and qualified names in `AppxManifest.xml` for flexible app identity definitions. The `manifest update-assets` command accepts SVG sources (v0.2.1+), converting them to bitmaps for all required asset sizes. + +### 8. Certificate Management (`winapp cert`) + +Generate development certificates and install them to the local machine store for signing packages. Additional capabilities (v0.2.1+): + +- `winapp cert info --password ` — display subject, issuer, and validity for a PFX certificate +- `--export-cer` flag on `cert generate` — export the public key as a `.cer` file +- `--json` output on `cert generate` and `cert info` — for scripting and tool integration + +### 9. Package Signing (`winapp sign`) Sign MSIX packages and executables with PFX certificates, with optional timestamp server support. -### 7. SDK Build Tools Access (`winapp tool`) +### 10. SDK Build Tools Access (`winapp tool`) Run Windows SDK build tools with properly configured paths from any framework or build system. -### 8. Microsoft Store Integration (`winapp store`) +### 11. Microsoft Store Integration (`winapp store`) Run Microsoft Store Developer CLI commands directly from winapp, enabling store submission, package validation, and publishing workflows without leaving the CLI. -### 9. External Catalog Creation (`winapp create-external-catalog`) +### 12. External Catalog Creation (`winapp create-external-catalog`) -Create external catalogs to streamline asset management for developers, separating catalog data from the main package. +Generate `CodeIntegrityExternal.cat` for TrustedLaunch sparse packages, separating catalog data from the main package. + +### 13. Programmatic npm API (Node.js/Electron) — v0.2.1+ + +All `winapp` commands are exposed as typed JS/TS functions from the `@microsoft/winappcli` npm package, with auto-generated exports kept in sync with the CLI: + +```ts +import { init, packageApp, certGenerate } from '@microsoft/winappcli'; +``` ## Usage Examples From 31447ff2af33a70f17634456ee9690c46668ed6e Mon Sep 17 00:00:00 2001 From: Alvin Ashcraft <73072+alvinashcraft@users.noreply.github.com> Date: Sun, 3 May 2026 16:47:05 -0400 Subject: [PATCH 2/7] Updated skill for winapp cli based on review --- skills/winapp-cli/SKILL.md | 40 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/skills/winapp-cli/SKILL.md b/skills/winapp-cli/SKILL.md index 56e1e2552..f20d6f2b1 100644 --- a/skills/winapp-cli/SKILL.md +++ b/skills/winapp-cli/SKILL.md @@ -66,7 +66,7 @@ Remove sideloaded development packages registered by `winapp run` or `winapp cre ### 6. UI Automation (`winapp ui`) — v0.3.0+ -A command group for programmatic interaction with Windows applications via Microsoft UI Automation (UIA). Useful for end-to-end testing, scripting, and AI-agent driven UI workflows. +A command group for programmatic interaction with Windows applications via Microsoft UI Automation (UIA). Useful for end-to-end testing, scripting, and AI-agent-driven UI workflows. Common subcommands: @@ -76,7 +76,42 @@ Common subcommands: - `winapp ui search` / `winapp ui wait-for` — locate or wait for elements - `winapp ui get-focused` — get the currently focused element -All `ui` subcommands support `--json` for machine-readable output. **Note:** the v0.3.1 release reshaped the `ui --json` envelope (see Limitations). +All `ui` subcommands support `--json` for machine-readable output. + +#### `ui --json` envelope (v0.3.1+) — breaking change + +The v0.3.1 release reshaped the JSON envelopes. Generate parsers against these shapes (not the pre-0.3.1 flat shapes): + +- **`ui inspect --json`** — elements are nested under windows; the top-level shape is: + + ```json + { + "depth": 0, + "interactive": false, + "hideDisabled": false, + "hideOffscreen": false, + "windows": [ + { + "hwnd": "0x...", + "title": "...", + "className": "...", + "elementCount": 0, + "elements": [ + { "selector": "...", "name": "...", "controlType": "...", "children": [ ... ] } + ] + } + ] + } + ``` + + Pre-0.3.1 the shape was a flat `{ "elements": [...] }` list. Per-element `id`, `depth`, `parentSelector`, and `windowHandle` fields have been removed — `selector` is the public handle for an element. + +- **`ui inspect --ancestors --json`** — ancestors are now nested as a parent → child chain keyed by `Depth=i` (previously emitted as sibling roots). +- **`ui get-focused --json`** — emits an envelope, not a bare value: + - No focus: `{ "hasFocus": false }` + - With focus: `{ "hasFocus": true, "element": { ... } }` + - Pre-0.3.1 emitted bare `null` when nothing was focused. +- **`ui search --json` / `ui wait-for --json`** — the internal `id`, `parentSelector`, and `windowHandle` fields are scrubbed from results, both at the top level and inside any nested `invokableAncestor`. Don't rely on them. ### 7. Manifest Management (`winapp manifest`) @@ -223,6 +258,7 @@ winapp update --setup-sdks preview - `winapp init` no longer auto-generates a certificate (v0.2.0+); run `winapp cert generate` explicitly - .NET (csproj) projects skip `winapp.yaml`; SDK packages are configured in the project file directly - winapp CLI uses the NuGet global cache for packages (not `%userprofile%/.winapp/packages`) +- `winapp ui --json` envelopes were reshaped in v0.3.1 (see [`ui --json` envelope](#ui---json-envelope-v031--breaking-change)) — pre-0.3.1 parsers will break - winapp CLI is in public preview and subject to change ## Windows APIs Enabled by Package Identity From caf06ab3f193558bfb2f99c3ca35c908a86c3140 Mon Sep 17 00:00:00 2001 From: Alvin Ashcraft <73072+alvinashcraft@users.noreply.github.com> Date: Sun, 3 May 2026 17:08:37 -0400 Subject: [PATCH 3/7] Updates to tighten up skill for winappcli --- docs/README.skills.md | 2 +- skills/winapp-cli/SKILL.md | 47 +++----------- .../winapp-cli/references/ui-json-envelope.md | 64 +++++++++++++++++++ 3 files changed, 74 insertions(+), 39 deletions(-) create mode 100644 skills/winapp-cli/references/ui-json-envelope.md diff --git a/docs/README.skills.md b/docs/README.skills.md index 4b90cc85b..2afd70490 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -350,7 +350,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [web-design-reviewer](../skills/web-design-reviewer/SKILL.md)
`gh skills install github/awesome-copilot web-design-reviewer` | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` | | [webapp-testing](../skills/webapp-testing/SKILL.md)
`gh skills install github/awesome-copilot webapp-testing` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `assets/test-helper.js` | | [what-context-needed](../skills/what-context-needed/SKILL.md)
`gh skills install github/awesome-copilot what-context-needed` | Ask Copilot what files it needs to see before answering a question | None | -| [winapp-cli](../skills/winapp-cli/SKILL.md)
`gh skills install github/awesome-copilot winapp-cli` | Windows App Development CLI (winapp) for building, packaging, deploying, debugging, and UI-automating Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml (including from SVG assets), manage development certificates (generate, install, inspect via `cert info`, export public keys), add package identity for debugging, run apps as packaged via loose-layout registration (`winapp run`), unregister sideloaded dev packages, sign packages, publish to the Microsoft Store, create external catalogs (CodeIntegrityExternal.cat for TrustedLaunch sparse packages), automate Windows UI interactions (list windows, inspect elements, click) via Microsoft UI Automation, or access Windows SDK build tools. Supports .NET (csproj), C++, Electron, Rust, Tauri, Flutter, and cross-platform frameworks targeting Windows. | None | +| [winapp-cli](../skills/winapp-cli/SKILL.md)
`gh skills install github/awesome-copilot winapp-cli` | Windows App Development CLI (winapp) for building, packaging, signing, debugging, and UI-automating Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, manage AppxManifest.xml or development certificates, run an app as packaged for debugging, automate Windows UI via Microsoft UI Automation, publish to the Microsoft Store, or access Windows SDK build tools. Covers commands like init, pack, run, unregister, manifest, cert, sign, store, ui, and tool. Supports .NET (csproj), C++, Electron, Rust, Tauri, Flutter, and other Windows frameworks. | `references/ui-json-envelope.md` | | [winmd-api-search](../skills/winmd-api-search/SKILL.md)
`gh skills install github/awesome-copilot winmd-api-search` | Find and explore Windows desktop APIs. Use when building features that need platform capabilities — camera, file access, notifications, UI controls, AI/ML, sensors, networking, etc. Discovers the right API for a task and retrieves full type details (methods, properties, events, enumeration values). | `LICENSE.txt`
`scripts/Invoke-WinMdQuery.ps1`
`scripts/Update-WinMdCache.ps1`
`scripts/cache-generator` | | [winui3-migration-guide](../skills/winui3-migration-guide/SKILL.md)
`gh skills install github/awesome-copilot winui3-migration-guide` | UWP-to-WinUI 3 migration reference. Maps legacy UWP APIs to correct Windows App SDK equivalents with before/after code snippets. Covers namespace changes, threading (CoreDispatcher to DispatcherQueue), windowing (CoreWindow to AppWindow), dialogs, pickers, sharing, printing, background tasks, and the most common Copilot code generation mistakes. | None | | [workiq-copilot](../skills/workiq-copilot/SKILL.md)
`gh skills install github/awesome-copilot workiq-copilot` | Guides the Copilot CLI on how to use the WorkIQ CLI/MCP server to query Microsoft 365 Copilot data (emails, meetings, docs, Teams, people) for live context, summaries, and recommendations. | None | diff --git a/skills/winapp-cli/SKILL.md b/skills/winapp-cli/SKILL.md index f20d6f2b1..79689d8f0 100644 --- a/skills/winapp-cli/SKILL.md +++ b/skills/winapp-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: winapp-cli -description: 'Windows App Development CLI (winapp) for building, packaging, deploying, debugging, and UI-automating Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml (including from SVG assets), manage development certificates (generate, install, inspect via `cert info`, export public keys), add package identity for debugging, run apps as packaged via loose-layout registration (`winapp run`), unregister sideloaded dev packages, sign packages, publish to the Microsoft Store, create external catalogs (CodeIntegrityExternal.cat for TrustedLaunch sparse packages), automate Windows UI interactions (list windows, inspect elements, click) via Microsoft UI Automation, or access Windows SDK build tools. Supports .NET (csproj), C++, Electron, Rust, Tauri, Flutter, and cross-platform frameworks targeting Windows.' +description: 'Windows App Development CLI (winapp) for building, packaging, signing, debugging, and UI-automating Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, manage AppxManifest.xml or development certificates, run an app as packaged for debugging, automate Windows UI via Microsoft UI Automation, publish to the Microsoft Store, or access Windows SDK build tools. Covers commands like init, pack, run, unregister, manifest, cert, sign, store, ui, and tool. Supports .NET (csproj), C++, Electron, Rust, Tauri, Flutter, and other Windows frameworks.' --- # Windows App Development CLI @@ -76,42 +76,7 @@ Common subcommands: - `winapp ui search` / `winapp ui wait-for` — locate or wait for elements - `winapp ui get-focused` — get the currently focused element -All `ui` subcommands support `--json` for machine-readable output. - -#### `ui --json` envelope (v0.3.1+) — breaking change - -The v0.3.1 release reshaped the JSON envelopes. Generate parsers against these shapes (not the pre-0.3.1 flat shapes): - -- **`ui inspect --json`** — elements are nested under windows; the top-level shape is: - - ```json - { - "depth": 0, - "interactive": false, - "hideDisabled": false, - "hideOffscreen": false, - "windows": [ - { - "hwnd": "0x...", - "title": "...", - "className": "...", - "elementCount": 0, - "elements": [ - { "selector": "...", "name": "...", "controlType": "...", "children": [ ... ] } - ] - } - ] - } - ``` - - Pre-0.3.1 the shape was a flat `{ "elements": [...] }` list. Per-element `id`, `depth`, `parentSelector`, and `windowHandle` fields have been removed — `selector` is the public handle for an element. - -- **`ui inspect --ancestors --json`** — ancestors are now nested as a parent → child chain keyed by `Depth=i` (previously emitted as sibling roots). -- **`ui get-focused --json`** — emits an envelope, not a bare value: - - No focus: `{ "hasFocus": false }` - - With focus: `{ "hasFocus": true, "element": { ... } }` - - Pre-0.3.1 emitted bare `null` when nothing was focused. -- **`ui search --json` / `ui wait-for --json`** — the internal `id`, `parentSelector`, and `windowHandle` fields are scrubbed from results, both at the top level and inside any nested `invokableAncestor`. Don't rely on them. +All `ui` subcommands support `--json` for machine-readable output. The envelope shape changed in v0.3.1 — see [`references/ui-json-envelope.md`](./references/ui-json-envelope.md) before writing parsers. ### 7. Manifest Management (`winapp manifest`) @@ -258,9 +223,15 @@ winapp update --setup-sdks preview - `winapp init` no longer auto-generates a certificate (v0.2.0+); run `winapp cert generate` explicitly - .NET (csproj) projects skip `winapp.yaml`; SDK packages are configured in the project file directly - winapp CLI uses the NuGet global cache for packages (not `%userprofile%/.winapp/packages`) -- `winapp ui --json` envelopes were reshaped in v0.3.1 (see [`ui --json` envelope](#ui---json-envelope-v031--breaking-change)) — pre-0.3.1 parsers will break - winapp CLI is in public preview and subject to change +## Gotchas + +- **`winapp ui --json` envelope reshaped in v0.3.1** — `ui inspect`, `ui get-focused`, `ui search`, and `ui wait-for` use new shapes; per-element `id`/`parentSelector`/`windowHandle` are gone (use `selector`). Full schemas: [`references/ui-json-envelope.md`](./references/ui-json-envelope.md). +- **`winapp init` no longer auto-generates a certificate** (v0.2.0+) — run `winapp cert generate` explicitly when you need a dev cert. +- **`.NET (csproj)` projects skip `winapp.yaml`** — SDK packages are configured in the project file directly. +- **Re-run `create-debug-identity` after manifest changes** — package identity is bound to the manifest at registration time. + ## Windows APIs Enabled by Package Identity Package identity unlocks access to powerful Windows APIs: diff --git a/skills/winapp-cli/references/ui-json-envelope.md b/skills/winapp-cli/references/ui-json-envelope.md new file mode 100644 index 000000000..c501cfa71 --- /dev/null +++ b/skills/winapp-cli/references/ui-json-envelope.md @@ -0,0 +1,64 @@ +# `winapp ui --json` envelope (v0.3.1+) + +The `--json` output for the `winapp ui` command group was reshaped in v0.3.1. +Generate parsers against these shapes — pre-0.3.1 parsers will silently break +because most fields were renamed, removed, or moved into envelopes. + +## `ui inspect --json` + +Top-level shape (elements are now nested under `windows[]`, not flat): + +```json +{ + "depth": 0, + "interactive": false, + "hideDisabled": false, + "hideOffscreen": false, + "windows": [ + { + "hwnd": "0x...", + "title": "...", + "className": "...", + "elementCount": 0, + "elements": [ + { + "selector": "...", + "name": "...", + "controlType": "...", + "children": [ ... ] + } + ] + } + ] +} +``` + +Pre-0.3.1 the shape was `{ "elements": [...] }`. Per-element `id`, `depth`, +`parentSelector`, and `windowHandle` fields have been **removed** — `selector` +is the public handle. + +## `ui inspect --ancestors --json` + +Ancestors are now nested as a parent → child chain keyed by `Depth=i` +(previously emitted as sibling roots). + +## `ui inspect --interactive` + +Non-interactive ancestors are collapsed and surfaced as `ancestorPath` on +surviving descendants. `+more` markers indicate truncated subtrees in both +text and JSON modes. + +## `ui get-focused --json` + +Always emits an envelope (never a bare value): + +- No focus: `{ "hasFocus": false }` +- With focus: `{ "hasFocus": true, "element": { ... } }` + +Pre-0.3.1 emitted bare `null` when nothing was focused. + +## `ui search --json` / `ui wait-for --json` + +The internal `id`, `parentSelector`, and `windowHandle` fields are scrubbed +from results, both at the top level and inside any nested +`invokableAncestor`. Don't depend on them. From 7fd4f96ddb88de165fff912014ad45ab052451c0 Mon Sep 17 00:00:00 2001 From: Alvin Ashcraft <73072+alvinashcraft@users.noreply.github.com> Date: Sun, 3 May 2026 17:14:00 -0400 Subject: [PATCH 4/7] Tighten skill to reduce token use --- skills/winapp-cli/SKILL.md | 280 +++++++------------------------------ 1 file changed, 48 insertions(+), 232 deletions(-) diff --git a/skills/winapp-cli/SKILL.md b/skills/winapp-cli/SKILL.md index 79689d8f0..b2395e5dc 100644 --- a/skills/winapp-cli/SKILL.md +++ b/skills/winapp-cli/SKILL.md @@ -5,262 +5,78 @@ description: 'Windows App Development CLI (winapp) for building, packaging, sign # Windows App Development CLI -The Windows App Development CLI (`winapp`) is a command-line interface for managing Windows SDKs, MSIX packaging, generating app identity, manifests, certificates, and using build tools with any app framework. It bridges the gap between cross-platform development and Windows-native capabilities. - -## When to Use This Skill - -Use this skill when you need to: - -- Initialize a Windows app project with SDK setup, manifests, and certificates -- Create MSIX packages from application directories (with automatic WinRT component discovery) -- Generate or manage AppxManifest.xml files (including asset generation from SVG sources) -- Create, install, and inspect development certificates for signing (including `cert info` and `.cer` public-key export) -- Add package identity for debugging Windows APIs -- Run an app as a packaged application via loose-layout registration with `winapp run` (great for IDE F5 / debug workflows) -- Unregister sideloaded dev packages installed by `run` or `create-debug-identity` -- Automate UI interactions on Windows apps (list windows, inspect element trees, click, search, wait-for) via Microsoft UI Automation with `winapp ui` -- Sign MSIX packages or executables -- Access Windows SDK build tools from any framework -- Build Windows apps using cross-platform frameworks (Electron, Rust, Tauri, Flutter, Qt) -- Set up CI/CD pipelines for Windows app deployment -- Access Windows APIs that require package identity (notifications, Windows AI, shell integration) -- Publish apps to the Microsoft Store via `winapp store` -- Generate external catalogs (`CodeIntegrityExternal.cat`) for TrustedLaunch sparse packages -- Set up .NET (csproj) projects with Windows App SDK via NuGet -- Import typed JS/TS functions from `@microsoft/winappcli` in Node.js/Electron projects (programmatic npm API) +`winapp` manages Windows SDKs, MSIX packaging, app identity, manifests, certificates, signing, store publishing, and UI automation for any framework targeting Windows (.NET/csproj, C++, Electron, Rust, Tauri, Flutter, etc.). Public preview — subject to change. ## Prerequisites - Windows 10 or later -- winapp CLI installed via one of these methods: - - **WinGet**: `winget install Microsoft.WinAppCli --source winget` - - **NPM** (for Electron): `npm install @microsoft/winappcli --save-dev` - - **GitHub Actions/Azure DevOps**: Use [setup-WinAppCli](https://github.com/microsoft/setup-WinAppCli) action - - **Manual**: Download from [GitHub Releases](https://github.com/microsoft/WinAppCli/releases/latest) - -## Core Capabilities - -### 1. Project Initialization (`winapp init`) - -Initialize a directory with required assets (manifest, certificates, libraries) for building a modern Windows app. Supports SDK installation modes: `stable`, `preview`, `experimental`, or `none`. - -### 2. MSIX Packaging (`winapp pack`) - -Create MSIX packages from prepared directories with optional signing, certificate generation, and self-contained deployment bundling. Automatically discovers and registers third-party WinRT components from `.winmd` files during packaging (v0.2.1+), preserves existing PRI resources, and validates executable architecture. - -### 3. Package Identity for Debugging (`winapp create-debug-identity`) - -Add temporary (sparse) package identity to executables for debugging Windows APIs that require identity (notifications, Windows AI, shell integration) without full packaging. - -### 4. Run as Packaged App (`winapp run`) — v0.3.0+ - -Pack a folder using a loose layout and launch the application as a packaged app, making it easy to debug from any IDE (e.g., VS Code F5) without producing a full MSIX. Supports `--` passthrough for application arguments (v0.3.1+): - -```bash -winapp run .\bin\Debug\net10.0-windows10.0.26100.0\win-x64 --manifest .\appxmanifest.xml -- --my-flag value -``` - -### 5. Unregister Dev Packages (`winapp unregister`) - -Remove sideloaded development packages registered by `winapp run` or `winapp create-debug-identity`. Uses segment-aware path containment and a two-pass classify-then-remove loop (v0.3.1+) to avoid sibling-directory misclassification and accidental removal of unrelated packages. - -### 6. UI Automation (`winapp ui`) — v0.3.0+ - -A command group for programmatic interaction with Windows applications via Microsoft UI Automation (UIA). Useful for end-to-end testing, scripting, and AI-agent-driven UI workflows. - -Common subcommands: - -- `winapp ui list-windows` — enumerate top-level windows -- `winapp ui inspect` — inspect the UI element tree (supports `--interactive` to collapse non-interactive ancestors and surface them via `ancestorPath`, plus `--ancestors` for ancestor chains) -- `winapp ui click` — click an element by selector -- `winapp ui search` / `winapp ui wait-for` — locate or wait for elements -- `winapp ui get-focused` — get the currently focused element - -All `ui` subcommands support `--json` for machine-readable output. The envelope shape changed in v0.3.1 — see [`references/ui-json-envelope.md`](./references/ui-json-envelope.md) before writing parsers. - -### 7. Manifest Management (`winapp manifest`) - -Generate `AppxManifest.xml` files and update image assets from source images, automatically creating all required sizes and aspect ratios. Supports manifest placeholders for dynamic content and qualified names in `AppxManifest.xml` for flexible app identity definitions. The `manifest update-assets` command accepts SVG sources (v0.2.1+), converting them to bitmaps for all required asset sizes. - -### 8. Certificate Management (`winapp cert`) - -Generate development certificates and install them to the local machine store for signing packages. Additional capabilities (v0.2.1+): - -- `winapp cert info --password ` — display subject, issuer, and validity for a PFX certificate -- `--export-cer` flag on `cert generate` — export the public key as a `.cer` file -- `--json` output on `cert generate` and `cert info` — for scripting and tool integration - -### 9. Package Signing (`winapp sign`) - -Sign MSIX packages and executables with PFX certificates, with optional timestamp server support. - -### 10. SDK Build Tools Access (`winapp tool`) - -Run Windows SDK build tools with properly configured paths from any framework or build system. - -### 11. Microsoft Store Integration (`winapp store`) - -Run Microsoft Store Developer CLI commands directly from winapp, enabling store submission, package validation, and publishing workflows without leaving the CLI. - -### 12. External Catalog Creation (`winapp create-external-catalog`) - -Generate `CodeIntegrityExternal.cat` for TrustedLaunch sparse packages, separating catalog data from the main package. - -### 13. Programmatic npm API (Node.js/Electron) — v0.2.1+ - -All `winapp` commands are exposed as typed JS/TS functions from the `@microsoft/winappcli` npm package, with auto-generated exports kept in sync with the CLI: - -```ts -import { init, packageApp, certGenerate } from '@microsoft/winappcli'; -``` - -## Usage Examples - -### Example 1: Initialize and Package a Windows App +- Install via one of: + - WinGet: `winget install Microsoft.WinAppCli --source winget` + - npm (Electron/Node): `npm install @microsoft/winappcli --save-dev` + - CI: [`setup-WinAppCli`](https://github.com/microsoft/setup-WinAppCli) GitHub Action + - Manual: [GitHub Releases](https://github.com/microsoft/WinAppCli/releases/latest) + +## Commands + +| Command | Purpose | +| ------- | ------- | +| `init` | Initialize project: SDKs (`stable`/`preview`/`experimental`/`none`), manifest, `winapp.yaml`. **`.csproj` projects skip `winapp.yaml`** and use NuGet directly. **Does not auto-generate a cert** (v0.2.0+). | +| `restore` / `update` | Restore or update SDK package versions (`--setup-sdks preview` for preview SDKs). | +| `pack ` | Build MSIX. Flags: `--generate-cert`, `--cert --cert-password`, `--self-contained` (bundles WinAppSDK runtime), `--output`. Auto-discovers third-party WinRT components from `.winmd` (v0.2.1+). | +| `run [-- ]` | Pack as loose layout and launch as packaged app — ideal for IDE F5 debugging without producing an MSIX. Supports `--` arg passthrough (v0.3.1+). (v0.3.0+) | +| `create-debug-identity ` | Add sparse package identity to an exe so it can call identity-gated APIs (notifications, Windows AI, shell integration) without full packaging. | +| `unregister` | Remove sideloaded dev packages registered by `run` / `create-debug-identity`. | +| `manifest` | Generate `AppxManifest.xml`; supports placeholders and qualified names. `manifest update-assets ` generates all required icon sizes from one source (PNG **or SVG**, v0.2.1+). | +| `cert generate` / `install` / `info` | Manage dev certs. `cert info --password ` shows subject/issuer/validity. `--export-cer` exports the public key. `--json` available on `generate` and `info`. (v0.2.1+) | +| `sign --cert ` | Sign MSIX or exe; optional timestamp server. | +| `tool` | Run Windows SDK build tools with paths configured. | +| `store` | Run Microsoft Store Developer CLI for store submission/validation/publishing. | +| `create-external-catalog` | Generate `CodeIntegrityExternal.cat` for TrustedLaunch sparse packages. | +| `ui list-windows` / `inspect` / `click` / `search` / `wait-for` / `get-focused` | UI automation via Microsoft UI Automation. All support `--json`. **Envelope changed in v0.3.1** — see [`references/ui-json-envelope.md`](./references/ui-json-envelope.md). (v0.3.0+) | +| `node create-addon` / `add-electron-debug-identity` / `clear-electron-debug-identity` | Electron/Node helpers. All commands also exposed as typed JS/TS functions from `@microsoft/winappcli` (v0.2.1+). | + +CI tip: pass `--no-prompt` to skip interactive prompts. + +## Quick start ```bash -# Initialize workspace with defaults +# .NET / generic: init, generate dev cert, build, package winapp init -# Note: init no longer auto-generates a certificate (v0.2.0+). Generate one explicitly: winapp cert generate - -# Build your application (framework-specific) -# ... - -# Create signed MSIX package winapp pack ./build-output --generate-cert --output MyApp.msix -``` - -### Example 2: Debug with Package Identity -```bash -# Add debug identity to executable for testing Windows APIs +# Debug a built exe with package identity (no MSIX) winapp create-debug-identity ./bin/MyApp.exe - -# Run your app - it now has package identity ./bin/MyApp.exe -``` -### Example 3: CI/CD Pipeline Setup +# Run as packaged app for F5 debugging, with app args after `--` +winapp run ./bin/Debug/net10.0-windows10.0.26100.0/win-x64 \ + --manifest ./appxmanifest.xml -- --my-flag value -```yaml -# GitHub Actions example -- name: Setup winapp CLI - uses: microsoft/setup-WinAppCli@v1 - -- name: Initialize and Package - run: | - winapp init --no-prompt - winapp pack ./build-output --output MyApp.msix -``` - -### Example 4: Electron App Integration - -```bash -# Install via npm -npm install @microsoft/winappcli --save-dev - -# Initialize and add debug identity for Electron +# Electron npx winapp init npx winapp node add-electron-debug-identity - -# Package for distribution npx winapp pack ./out --output MyElectronApp.msix ``` -## Guidelines - -1. **Run `winapp init` first** - Always initialize your project before using other commands to ensure SDK setup and manifest are configured. Note: as of v0.2.0, `winapp init` no longer generates a development certificate automatically. Run `winapp cert generate` explicitly when you need to sign with a dev certificate. -2. **Re-run `create-debug-identity` after manifest changes** - Package identity must be recreated whenever AppxManifest.xml is modified. -3. **Use `--no-prompt` for CI/CD** - Prevents interactive prompts in automated pipelines by using default values. -4. **Use `winapp restore` for shared projects** - Recreates the exact environment state defined in `winapp.yaml` across machines. -5. **Generate assets from a single image** - Use `winapp manifest update-assets` with one logo to generate all required icon sizes. - -## Common Patterns - -### Pattern: Initialize New Project - -```bash -cd my-project -winapp init -# Creates: AppxManifest.xml, SDK configuration, winapp.yaml -# Note: .NET (csproj) projects skip winapp.yaml and configure NuGet packages in the .csproj directly - -# Generate a dev signing certificate explicitly (no longer done by init) -winapp cert generate -``` - -### Pattern: Package with Existing Certificate - -```bash -winapp pack ./build-output --cert ./mycert.pfx --cert-password secret --output MyApp.msix -``` - -### Pattern: Self-Contained Deployment - -```bash -# Bundle Windows App SDK runtime with the package -winapp pack ./my-app --self-contained --generate-cert -``` - -### Pattern: Update Package Versions - -```bash -# Update to latest stable SDKs -winapp update - -# Or update to preview SDKs -winapp update --setup-sdks preview -``` - -## Limitations - -- Windows 10 or later required (Windows-only CLI) -- Package identity debugging requires re-running `create-debug-identity` after any manifest changes -- Self-contained deployment increases package size by bundling the Windows App SDK runtime -- Development certificates are for testing only; production requires trusted certificates -- Some Windows APIs require specific capability declarations in the manifest -- `winapp init` no longer auto-generates a certificate (v0.2.0+); run `winapp cert generate` explicitly -- .NET (csproj) projects skip `winapp.yaml`; SDK packages are configured in the project file directly -- winapp CLI uses the NuGet global cache for packages (not `%userprofile%/.winapp/packages`) -- winapp CLI is in public preview and subject to change - ## Gotchas -- **`winapp ui --json` envelope reshaped in v0.3.1** — `ui inspect`, `ui get-focused`, `ui search`, and `ui wait-for` use new shapes; per-element `id`/`parentSelector`/`windowHandle` are gone (use `selector`). Full schemas: [`references/ui-json-envelope.md`](./references/ui-json-envelope.md). -- **`winapp init` no longer auto-generates a certificate** (v0.2.0+) — run `winapp cert generate` explicitly when you need a dev cert. -- **`.NET (csproj)` projects skip `winapp.yaml`** — SDK packages are configured in the project file directly. -- **Re-run `create-debug-identity` after manifest changes** — package identity is bound to the manifest at registration time. - -## Windows APIs Enabled by Package Identity - -Package identity unlocks access to powerful Windows APIs: - -| API Category | Examples | -| ------------ | -------- | -| **Notifications** | Interactive native notifications, notification management | -| **Windows AI** | On-device LLM, text/image AI APIs (Phi Silica, Windows ML) | -| **Shell Integration** | Explorer, Taskbar, Share sheet integration | -| **Protocol Handlers** | Custom URI schemes (`yourapp://`) | -| **Device Access** | Camera, microphone, location (with consent) | -| **Background Tasks** | Run when app is closed | -| **File Associations** | Open file types with your app | +- **`winapp ui --json` envelope reshaped in v0.3.1** — `ui inspect`, `ui get-focused`, `ui search`, and `ui wait-for` use new shapes; per-element `id` / `parentSelector` / `windowHandle` are removed (use `selector`). Full schemas in [`references/ui-json-envelope.md`](./references/ui-json-envelope.md). +- **`winapp init` no longer auto-generates a certificate** (v0.2.0+) — run `winapp cert generate` explicitly. The old `--no-cert` flag was removed. +- **`.csproj` projects skip `winapp.yaml`** — SDK packages live in the project file. Hybrid setups need adjustment. +- **NuGet global cache, not `%userprofile%/.winapp/packages`** (v0.2.0+) — scripts depending on the old folder will break. +- **Re-run `create-debug-identity` after any manifest change** — identity is bound at registration time. ## Troubleshooting -| Issue | Solution | -| ----- | -------- | -| Certificate not trusted | Run `winapp cert install ` to install to local machine store | -| Package identity not working | Run `winapp create-debug-identity` after any manifest changes | -| SDK not found | Run `winapp restore` or `winapp update` to ensure SDKs are installed | -| Signing fails | Verify certificate password and ensure cert is not expired | +| Issue | Fix | +| ----- | --- | +| Certificate not trusted | `winapp cert install ` to add to local machine store | +| Identity-gated API fails | Re-run `create-debug-identity` after manifest changes | +| SDK not found | `winapp restore` or `winapp update` | +| `register`/`unregister` errors | v0.3.1 maps `0x800704EC`→Developer Mode and `0x80073CFB`→package conflict (with actionable hint) | ## References -- [GitHub Repository](https://github.com/microsoft/WinAppCli) -- [Full CLI Documentation](https://github.com/microsoft/WinAppCli/blob/main/docs/usage.md) -- [.NET Project Guide](https://github.com/microsoft/WinAppCli/blob/main/docs/guides/dotnet.md) -- [Sample Applications](https://github.com/microsoft/WinAppCli/tree/main/samples) -- [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/) -- [MSIX Packaging Overview](https://learn.microsoft.com/windows/msix/overview) -- [Package Identity Overview](https://learn.microsoft.com/windows/apps/desktop/modernize/package-identity-overview) +- [winapp CLI repo](https://github.com/microsoft/WinAppCli) · [Full usage docs](https://github.com/microsoft/WinAppCli/blob/main/docs/usage.md) · [.NET guide](https://github.com/microsoft/WinAppCli/blob/main/docs/guides/dotnet.md) · [Samples](https://github.com/microsoft/WinAppCli/tree/main/samples) +- [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/) · [MSIX overview](https://learn.microsoft.com/windows/msix/overview) · [Package identity overview](https://learn.microsoft.com/windows/apps/desktop/modernize/package-identity-overview) From 02f9caf894a80f85a54d3d4ceddb346f391c4041 Mon Sep 17 00:00:00 2001 From: Alvin Ashcraft <73072+alvinashcraft@users.noreply.github.com> Date: Sun, 3 May 2026 17:16:22 -0400 Subject: [PATCH 5/7] Update to use steps --- skills/winapp-cli/SKILL.md | 75 +++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 21 deletions(-) diff --git a/skills/winapp-cli/SKILL.md b/skills/winapp-cli/SKILL.md index b2395e5dc..d544722a5 100644 --- a/skills/winapp-cli/SKILL.md +++ b/skills/winapp-cli/SKILL.md @@ -37,27 +37,60 @@ description: 'Windows App Development CLI (winapp) for building, packaging, sign CI tip: pass `--no-prompt` to skip interactive prompts. -## Quick start - -```bash -# .NET / generic: init, generate dev cert, build, package -winapp init -winapp cert generate -winapp pack ./build-output --generate-cert --output MyApp.msix - -# Debug a built exe with package identity (no MSIX) -winapp create-debug-identity ./bin/MyApp.exe -./bin/MyApp.exe - -# Run as packaged app for F5 debugging, with app args after `--` -winapp run ./bin/Debug/net10.0-windows10.0.26100.0/win-x64 \ - --manifest ./appxmanifest.xml -- --my-flag value - -# Electron -npx winapp init -npx winapp node add-electron-debug-identity -npx winapp pack ./out --output MyElectronApp.msix -``` +## Workflow + +Standard init → package flow: + +1. **Initialize the project** in your app folder. Sets up SDK refs, manifest, and `winapp.yaml` (`.csproj` projects skip the YAML and configure NuGet directly). + + ```bash + winapp init # add --no-prompt in CI + ``` + +2. **Generate a dev signing certificate** — required for sideloading. `init` no longer creates one (v0.2.0+). + + ```bash + winapp cert generate + ``` + +3. **Build your app** with the framework's own toolchain (`dotnet build`, `npm run build`, `cargo build`, etc.). +4. **Package as MSIX**, signing with the dev cert (or supply your own with `--cert --cert-password`). + + ```bash + winapp pack ./build-output --generate-cert --output MyApp.msix + ``` + +5. **(Optional) Sign with a production cert** before distribution. + + ```bash + winapp sign MyApp.msix --cert ./prod.pfx --cert-password $env:CERT_PWD + ``` + +6. **(Optional) Submit to the Microsoft Store** with `winapp store …` (wraps the Store Developer CLI). + +### Alternate flows + +- **Debug identity-gated APIs without packaging** (notifications, Windows AI, shell): + + ```bash + winapp create-debug-identity ./bin/MyApp.exe + ./bin/MyApp.exe + ``` + +- **Run as packaged app for IDE F5** (loose layout; app args after `--`): + + ```bash + winapp run ./bin/Debug/net10.0-windows10.0.26100.0/win-x64 \ + --manifest ./appxmanifest.xml -- --my-flag value + ``` + +- **Electron**: + + ```bash + npx winapp init + npx winapp node add-electron-debug-identity + npx winapp pack ./out --output MyElectronApp.msix + ``` ## Gotchas From 31bc1330f2de8463c93d005952daa51ad4fd45cb Mon Sep 17 00:00:00 2001 From: Alvin Ashcraft <73072+alvinashcraft@users.noreply.github.com> Date: Sun, 3 May 2026 17:33:09 -0400 Subject: [PATCH 6/7] Updates from review comments --- skills/winapp-cli/SKILL.md | 15 +++++----- .../winapp-cli/references/ui-json-envelope.md | 29 +++++++++++++++++-- 2 files changed, 34 insertions(+), 10 deletions(-) diff --git a/skills/winapp-cli/SKILL.md b/skills/winapp-cli/SKILL.md index d544722a5..537b49a00 100644 --- a/skills/winapp-cli/SKILL.md +++ b/skills/winapp-cli/SKILL.md @@ -32,7 +32,7 @@ description: 'Windows App Development CLI (winapp) for building, packaging, sign | `tool` | Run Windows SDK build tools with paths configured. | | `store` | Run Microsoft Store Developer CLI for store submission/validation/publishing. | | `create-external-catalog` | Generate `CodeIntegrityExternal.cat` for TrustedLaunch sparse packages. | -| `ui list-windows` / `inspect` / `click` / `search` / `wait-for` / `get-focused` | UI automation via Microsoft UI Automation. All support `--json`. **Envelope changed in v0.3.1** — see [`references/ui-json-envelope.md`](./references/ui-json-envelope.md). (v0.3.0+) | +| `ui list-windows` / `inspect` / `click` / `search` / `wait-for` / `get-focused` | UI automation via Microsoft UI Automation. All support `--json`. **JSON envelopes for `inspect`, `get-focused`, `search`, and `wait-for` changed in v0.3.1** — see [`references/ui-json-envelope.md`](./references/ui-json-envelope.md) (other `ui` subcommands keep their pre-0.3.1 output). (v0.3.0+) | | `node create-addon` / `add-electron-debug-identity` / `clear-electron-debug-identity` | Electron/Node helpers. All commands also exposed as typed JS/TS functions from `@microsoft/winappcli` (v0.2.1+). | CI tip: pass `--no-prompt` to skip interactive prompts. @@ -47,20 +47,20 @@ Standard init → package flow: winapp init # add --no-prompt in CI ``` -2. **Generate a dev signing certificate** — required for sideloading. `init` no longer creates one (v0.2.0+). +2. **Generate a dev signing certificate** — required for sideloading. `init` no longer creates one for non-`.csproj` projects (v0.2.0+). Pin the output path so later steps can reference it. ```bash - winapp cert generate + winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx --install ``` 3. **Build your app** with the framework's own toolchain (`dotnet build`, `npm run build`, `cargo build`, etc.). -4. **Package as MSIX**, signing with the dev cert (or supply your own with `--cert --cert-password`). +4. **Package as MSIX**, signing with the cert from step 2. ```bash - winapp pack ./build-output --generate-cert --output MyApp.msix + winapp pack ./build-output --cert ./mycert.pfx --cert-password password --output MyApp.msix ``` -5. **(Optional) Sign with a production cert** before distribution. +5. **(Optional) Re-sign with a production cert** before distribution. ```bash winapp sign MyApp.msix --cert ./prod.pfx --cert-password $env:CERT_PWD @@ -107,7 +107,8 @@ Standard init → package flow: | Certificate not trusted | `winapp cert install ` to add to local machine store | | Identity-gated API fails | Re-run `create-debug-identity` after manifest changes | | SDK not found | `winapp restore` or `winapp update` | -| `register`/`unregister` errors | v0.3.1 maps `0x800704EC`→Developer Mode and `0x80073CFB`→package conflict (with actionable hint) | +| `run` / `create-debug-identity` registration error `0x800704EC` | Developer Mode is off — enable it in **Settings → Privacy & security → For developers** (or `Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Name AllowDevelopmentWithoutDevLicense -Value 1`), then retry | +| `run` / `create-debug-identity` registration error `0x80073CFB` | Package already registered with a conflicting identity — run `winapp unregister` (or `winapp unregister --force` if registered from a different project tree), then retry | ## References diff --git a/skills/winapp-cli/references/ui-json-envelope.md b/skills/winapp-cli/references/ui-json-envelope.md index c501cfa71..3b6832fa6 100644 --- a/skills/winapp-cli/references/ui-json-envelope.md +++ b/skills/winapp-cli/references/ui-json-envelope.md @@ -59,6 +59,29 @@ Pre-0.3.1 emitted bare `null` when nothing was focused. ## `ui search --json` / `ui wait-for --json` -The internal `id`, `parentSelector`, and `windowHandle` fields are scrubbed -from results, both at the top level and inside any nested -`invokableAncestor`. Don't depend on them. +Both commands return matching elements using the same element shape as +`ui inspect` (so `selector`, `name`, `controlType`, `children`, etc.). +Each match may also include an `invokableAncestor` field — itself an +element-shaped object — pointing to the nearest invokable parent +(useful when a search hits a non-invokable element like a label inside +a button). + +```json +[ + { + "selector": "btn-save-c3d4", + "name": "Save", + "controlType": "Button", + "children": [ ... ], + "invokableAncestor": { + "selector": "btn-save-c3d4", + "name": "Save", + "controlType": "Button" + } + } +] +``` + +The internal `id`, `parentSelector`, and `windowHandle` fields are +**scrubbed** from results — both at the top level and inside any nested +`invokableAncestor`. Don't depend on them; use `selector` as the handle. From 94fd4a3a328ce0dbe082c329917d2d3dad49dbf3 Mon Sep 17 00:00:00 2001 From: Alvin Ashcraft <73072+alvinashcraft@users.noreply.github.com> Date: Sun, 3 May 2026 17:38:14 -0400 Subject: [PATCH 7/7] Fix spellcheck in build --- skills/winapp-cli/references/ui-json-envelope.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/winapp-cli/references/ui-json-envelope.md b/skills/winapp-cli/references/ui-json-envelope.md index 3b6832fa6..f07c2d1e5 100644 --- a/skills/winapp-cli/references/ui-json-envelope.md +++ b/skills/winapp-cli/references/ui-json-envelope.md @@ -62,9 +62,9 @@ Pre-0.3.1 emitted bare `null` when nothing was focused. Both commands return matching elements using the same element shape as `ui inspect` (so `selector`, `name`, `controlType`, `children`, etc.). Each match may also include an `invokableAncestor` field — itself an -element-shaped object — pointing to the nearest invokable parent -(useful when a search hits a non-invokable element like a label inside -a button). +element-shaped object — pointing to the nearest parent that supports +`InvokePattern` (useful when a search hits a non-invokable element +like a label inside a button). ```json [