How microsoft/winget-command-not-found works
1. What this repository is
- This repo builds a PowerShell 7.4+ module named Microsoft.WinGet.CommandNotFound.
- Its job is to act as a feedback provider / command-line predictor plugin: when PowerShell cannot find a native command, it suggests matching WinGet packages that could satisfy that command.
2. Primary architectural boundary
- The core boundary is between PowerShell’s feedback/prediction subsystem and the Windows Package Manager (WinGet).
- The module does not implement a shell itself; it plugs into PowerShell’s Subsystem Plugin Model and returns suggestions back to the shell UI/PSReadLine.
3. Module packaging and runtime surface
- src/Microsoft.WinGet.CommandNotFound.csproj builds the managed implementation targeting .NET 8 / net8.0.
- src/Microsoft.WinGet.CommandNotFound.psd1 is the PowerShell module manifest used for loading/importing the built artifact.
- The README’s import path (src/bin/<Configuration>/net8.0) indicates the build produces a loadable PowerShell module assembly plus manifest.
4. Core feedback/prediction component
- src/WinGetCommandNotFoundFeedbackPredictor.cs is the main managed entry point implied by the repo.
- This class is the bridge that PowerShell calls when a command-not-found event occurs, and it is where package suggestions are likely assembled and returned to the shell.
5. Suggestion flow
- The runtime flow is: PowerShell detects a missing native command → feedback provider/predictor is invoked → module queries WinGet/package metadata → suggestions are returned to PowerShell/PSReadLine.
- The output is advisory only: it helps the user discover installable packages, but it does not install anything automatically.
6. Environment and compatibility gating
- src/ValidateOS.psm1 indicates a PowerShell-side validation layer, likely used to ensure the host OS/environment is supported before the predictor is activated.
- This is an important boundary because the feature depends on specific PowerShell versions and experimental features (PSFeedbackProvider, PSCommandNotFoundSuggestion).
7. Resource handling / allocation control
- src/PooledPowerShellObjectPolicy.cs suggests the module uses an object-pooling strategy for PowerShell-related objects.
- That points to a performance-oriented internal layer to reduce repeated allocations while generating suggestions.
8. Build and packaging pipeline
- build.ps1 and Microsoft.WinGet.CommandNotFound.build.ps1 are the build orchestration scripts.
- The README shows the build is scripted rather than purely MSBuild-driven, and supports bootstrapping plus Debug/Release outputs.
- NuGet.config indicates dependency restore is part of the build pipeline.
9. Supporting tooling
- tools/helper.psm1 is shared PowerShell tooling for build/release or repository automation.
- The .config/tsaoptions.json and .github policy files are repo governance and automation, not runtime architecture, but they shape CI, issue handling, and release hygiene.
10. External dependencies that matter architecturally
- PowerShell 7.4+ is the host runtime because the module depends on IFeedbackProvider.
- PSReadLine 2.2.6+ is required for the command-line prediction UI to display the suggestions.
- WinGet is the external package intelligence source the module consults to map a missing command to installable packages.
11. Diagramming guidance
- A good architecture diagram should show:
- PowerShell host / PSReadLine on one side
- This module as the plugin layer in the middle
- WinGet as the external package data source on the other side
- A separate support path for OS validation and build/packaging artifacts
- The repo is therefore best represented as a PowerShell plugin module with a small managed core and a thin PowerShell support layer, not as a standalone application.
Main entry points: WinGetCommandNotFoundFeedbackPredictor.cs Feedback predictor · Microsoft.WinGet.CommandNotFound.build.ps1 Module build · build.ps1 Build script · Microsoft.WinGet.CommandNotFound.psd1 Module manifest
Components 14
Runtime path
PowerShell command-not-found feedback flow and suggestion generation
- PowerShell 7.4+ · Shell host that invokes feedback providers when commands are missing
- PSReadLine · Displays command-line suggestions to the user
- Module manifest · PowerShell module entrypoint and import metadata
src/Microsoft.WinGet.CommandNotFound.psd1 - Feedback predictor · Main managed entrypoint that returns WinGet-based suggestions
src/WinGetCommandNotFoundFeedbackPredictor.cs - OS check · Validates host/environment compatibility before activation
src/ValidateOS.psm1 - Object pool · Pools PowerShell-related objects to reduce repeated allocations
src/PooledPowerShellObjectPolicy.cs - WinGet · External package intelligence used to match commands to installable packages
Build path
Scripts and project files that produce the loadable module
- Module project · Targets .NET 8 and builds the managed module implementation
src/Microsoft.WinGet.CommandNotFound.csproj - Build script · Top-level build and bootstrapping entrypoint
build.ps1 - Module build · Repo-specific build and packaging logic for the module
Microsoft.WinGet.CommandNotFound.build.ps1 - Helper tools · Reusable PowerShell functions for build and release automation
tools/helper.psm1 - NuGet config · Dependency restore configuration used by the build
NuGet.config
Repo governance
CI, issue handling, and policy automation
- Release CI · Automated build and release pipeline definition
.pipelines/releaseBuild.yml - GitHub policy · Issue and triage automation plus repository templates
.github
Connections 13
- PowerShell 7.4+ → Module manifest: imports · PowerShell loads the module through its manifest
- Module manifest → Feedback predictor: wires · Manifest exposes the managed predictor implementation
- PowerShell 7.4+ → PSReadLine: renders · Suggestions are surfaced in the command-line UI
- Feedback predictor → OS check: checks · Activation is gated by OS and feature compatibility
- Feedback predictor → Object pool: uses · Prediction flow reuses pooled PowerShell objects
- Feedback predictor → WinGet: queries · Looks up packages that could satisfy the missing command
- Feedback predictor → PSReadLine: returns · Hands suggested commands back to the shell prediction path
- Build script → Module project: builds · Main build entrypoint compiles the managed project
- Build script → Module build: orchestrates · Build script delegates repo-specific packaging steps
- Module build → Helper tools: reuses · Packaging script shares helper functions
- Module build → NuGet config: restores · Build uses NuGet restore configuration
- Release CI → Build script: runs · CI invokes the scripted build path
- GitHub policy → Release CI: governs · Repo policy and templates support automation and release hygiene