feat: add winapp find-api — local Windows/WinRT API metadata search (port of winmd)

[Jaylyn Barbee (Jaylyn-Barbee)]

Description

Adds winapp find-api — a fully local, offline search over the Windows/WinRT API surface a project can actually see, resolved from its own restored NuGet/SDK packages. It answers "does this type exist, what's on it, and did I spell this property right?" from the real metadata instead of from memory.

This is the port of the winmd tool out of microsoft/win-dev-skills (src/tools/winmd-cli/) and into winapp, per #652 — but not a 1:1 copy. The query engine (metadata parsing, XML-doc extraction, scoring, near-miss suggestions) came over largely intact; the surface around it was reworked to fit winapp conventions and to fix real defects found along the way.

Why it matters to users: the answer is grounded in your project's referenced metadata, so it's correct for your package versions rather than for whatever version the model was trained on. It also fails loudly — check-property exits non-zero on a miss, so it can gate a step instead of just printing advice. And it works before a project exists (--project sdk), so it's useful during scaffolding, not only after restore.

Usage Example

# Search the API surface your project can see
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect a type; filter down long member lists
winapp find-api members Microsoft.UI.Xaml.Controls.TabView
winapp find-api members Microsoft.UI.Xaml.Window --filter Appear

# Validate before you write code — exits non-zero if a property doesn't exist
winapp find-api check-property TextBox Icon

# Batch: many subjects in one call
winapp find-api check-property TabView TabItems SelectedItem IsAddTabButtonVisible
winapp find-api members TabView NavigationView CommandBar
winapp find-api "acrylic" "mica" "backdrop"

# No project? Query the machine-wide Windows SDK scope
winapp find-api "app notification" --project sdk

# Structured output for agents
winapp find-api enums Microsoft.UI.Xaml.Controls.Symbol --json

Related Issue

Closes #652
Closes #774
Closes #796

Type of Change

• ✨ New feature

Checklist

• New tests added for new functionality (if applicable)
• Tested locally on Windows
• Main README.md updated (if applicable)
• docs/usage.md updated (if CLI commands changed)
• Language-specific guides updated (if applicable) — n/a
• Sample projects updated to reflect changes (if applicable) — n/a
• Agent skill templates updated — note these now live in plugins/winapp/skills/ (winapp-find-api/SKILL.md) and plugins/winapp/agents/, not docs/fragments/skills/

Additional Notes

What's new versus the winmd tool this ports from. The query core is at parity by design; these are the deltas worth reviewing:

• Batched lookups. search, members, enums, and check-property each accept several subjects in one call. This is the biggest change in how the command gets used — five property checks go from five calls to one, and the combined output is ~60% smaller than the five separate responses. Two API contracts here are worth explicit scrutiny because they're hard to change later: (1) a single subject returns the original payload shape in both text and --json — the { count, results } envelope only appears for two or more subjects, so existing single-subject callers are unaffected; (2) a batch exits 0 only if every subject resolved and was found. check-property batches N properties against one type (type first) — the dotted Type.Property multi-type form was considered and rejected as too implicit.
• Machine-wide SDK scope (--project sdk). The original could only answer against an indexed project. Previously, a projectless query would get silently answered from some unrelated indexed project — that's now impossible; you either get the SDK scope or an explicit error.
• Result attribution. Every scoped result reports which index answered it (Project: <name> (<dir>) in text, scope/projectName/projectDir in --json). Without this you can't tell a wrong-project answer from a right one.
• Path-keyed project manifests. Two projects with the same name in one solution used to collide in the cache and return each other's results. Fixed.
• --filter on members/enums. The original had --filter for namespace prefixes only. Guidance is deliberately asymmetric: filter long member lists, dump enums whole — a filtered enum lookup usually costs more than just reading all the values.
• Parallelized winmd indexing, which the original did not do at all.
• Three verbs shipped hidden (types, namespaces, projects). Still fully callable, just not surfaced in help or the CLI schema — they overlap with search/packages and were adding noise to the command surface without earning it.
• Compact check-property batch output — one line per confirmed property, full detail (near-miss suggestions, attached-property forms, other declaring types) only on a miss, which is the case where you actually need it.

Scoped out, tracked separately. Search and ranking quality are unchanged from the ported implementation — this PR does not claim to find APIs better than winmd did, only to make it cheaper to call, honest about which index answered, and usable outside a project. A check-file verb — validate every API reference in a file you just wrote, before building — is filed as #743.

Testing. 319/319 targeted find-api, CLI-schema, and help tests pass. Beyond unit tests, reference resolution and property reporting are verified end to end against real dotnet new/dotnet build fixtures — a multi-project solution (App -> Middle -> Leaf), a project with a System.* PackageReference, and a library with init, set, and get-only properties — by running the built CLI and asserting on its --json output. End-to-end verified against samples/winui-app.

Note for reviewers on diff size. This branch contains the initial port as well as the changes above, so the diff is large. The files that carry the design decisions are Commands/FindApiShared.cs, Commands/FindApiVerbs.cs, and plugins/winapp/skills/winapp-find-api/SKILL.md.

Follow-up for #652. Once this lands, the old winmd references in microsoft/win-dev-skills (src/tools/winmd-cli/ plus the skills/docs pointing at it) should be removed so there's no duplicated implementation across the two repos.

[github-actions]

Build Metrics Report

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	44.51 MB	46.13 MB	📈 +1.62 MB (+3.64%)
CLI (x64)	44.47 MB	46.04 MB	📈 +1.56 MB (+3.52%)
MSIX (ARM64)	18.41 MB	19.05 MB	📈 +657.1 KB (+3.49%)
MSIX (x64)	19.51 MB	20.19 MB	📈 +687.7 KB (+3.44%)
NPM Package	38.30 MB	39.63 MB	📈 +1.33 MB (+3.48%)
NuGet Package	38.43 MB	39.76 MB	📈 +1.33 MB (+3.47%)

Test Results

✅ 5804 passed, 18 skipped out of 5822 tests in 1025.7s (+396 tests, +262.4s vs. baseline)

Test Coverage

✅ 87.3% line coverage, 80.7% branch coverage · ⚠️ -0.9% vs. baseline

CLI Startup Time

63ms median (x64, winapp --version) · ✅ no change vs. baseline

Try This Build

Installs the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 744

Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 744

Run winapp-pr with no arguments to pick from a list of open PRs.

---

Updated 2026-09-11 02:28:34 UTC · commit b293d3a · workflow run

[Jaylyn Barbee (Jaylyn-Barbee)]

Re: the Generic catch clause findings

Reviewed all 10 remaining bot findings individually. Each is an intentional graceful-degradation path, not an oversight, so I'm resolving them rather than narrowing the catches.

The design principle: find-api reads a local, regenerable metadata cache. A corrupt, partially-written, or concurrently-rewritten cache file must degrade the result, never crash the CLI. Narrowing these to IOException/JsonException would convert current graceful degradation into hard failures on the exceptions those sites can genuinely see (UnauthorizedAccessException, NotSupportedException, InvalidOperationException from JsonSerializer, etc.).

Site	Behavior on failure
PathSafety.cs:240	Best-effort temp cleanup, then throw; — the original error is preserved and rethrown. Swallowing a cleanup failure here is required to avoid masking the real one.
ApiCacheBuilder.cs:334	Atomic write fails -> falls back to a plain write.
ApiCacheBuilder.cs:438	SDK-discovery subprocess fails -> returns null, caller handles it.
ApiMetadataService.cs:266	Already catch (Exception ex) with LogWarning; auto-indexing is explicitly best-effort.
ApiMetadataService.cs:428	Already catch (Exception ex) with LogWarning, returns ResolvedScope.Failed(...).
ApiMetadataService.cs:446	Corrupt manifest -> null (treated as "no cache", triggers re-index).
ApiQueryEngine.cs:330	Unreadable package meta -> reports that package as meta-unreadable instead of failing the whole listing.
ApiQueryEngine.cs:361	Stats aggregation skips an unreadable package rather than aborting.
ApiQueryEngine.cs:636, 648	Deserialize -> null on a corrupt cache file.

Note that ApiMetadataService.cs:266 and :428 already catch a typed Exception and log it — the rule flags them regardless of the logging.

The LINQ findings from the same review were addressed in 88c025c (8 of 11). Three were declined on merit and called out there: Scoring.IsFuzzySubsequence is a stateful sequential scan with an early return (not a projection), and ApiQueryEngine.cs:245/543 use a side-effecting seen.Add(...) predicate that would depend on mutation during lazy enumeration.

[Nikola Metulev (nmetulev)]

🤖 AI-generated review (winappcli pr-review skill) — verify before acting.

Thanks for the fixes. I’ve narrowed this to the changes that matter most: useful package-based discovery, clear first use, and trustworthy answers. No term aliases, generated tutorials, or universal NuGet catalog are requested.

1. Show usage for bare find-api

winapp find-api currently errors and exits 1. Please show short usage and examples instead; keep errors for genuinely malformed arguments. Entering the command should help someone discover how to use it.

2. Search package descriptions and meaningful words

winapp find-api "text generation" finds nothing, although the package describes LanguageModel as providing text generation and embeddings.

Meanwhile, llm matches letters inside scroLLMode and returns scrolling APIs:

Current unrelated results

Please search the available type/member descriptions and improve identifier-word matching while preserving exact lookup. A package-only prototype improved useful first-three results from 15/28 queries to 24/28, including 5/11 to 9/11 on held-out queries.

There is no requirement to recognize “Phi Silica” or “LLM” when those terms are absent from package information. An honest miss is better than unrelated matches.

3. Keep answers concise without losing important meaning

Show a few strong matches with their purpose, owning package/version, and the matching member signature when relevant. Keep filtered drill-down. Emit coverage warnings once, and do not count a framework plus its runtime-specific restore entry as two frameworks.

These remaining correctness cases should also be addressed:

Current behavior	Requested change	Why
A metadata file named in the restore inventory disappears; refresh succeeds, then InfoBar is “not found” without explaining the missing file.	Mark coverage incomplete and recommend restore.	Missing evidence is not evidence that the API is absent.
Getter-only attached Level gets the same green confirmation as writable Count; structured writability is omitted.	Label the read-only case and provide writable: false.	Finding a property does not make assignment valid.
Rename Before.csproj to After.csproj, restore and refresh; the tool still offers both projects.	Ignore or remove the obsolete manifest.	A normal rename should not leave a phantom project that blocks queries.

Current outputs for these three cases

4. Preserve the local-read safety boundary

Repository-selected paths still have routes around the checks: an assembly name such as ..\redirect\Poison reaches file enumeration; external lockfile paths bypass reparse checks; and the direct assets path checks its parent rather than the final file.

Please require a literal assembly filename and validate repository-supplied paths, including the final assets file, before reading them. A local metadata query must not follow a repository-selected link to an unintended location or network share.

Source: assembly name · external paths · assets file.

These paths were reconfirmed in current source. Earlier traversal used loopback SMB; no credential capture or exfiltration was performed.

5. V1 proposal: separately cached latest-stable SDK discovery

This is a feature addition, not a defect in local-only lookup. An older project already has LanguageModel but lacks GenerateStructuredJsonResponseAsync; a newer SDK contains it.

Please allow discovery in a cached latest-stable Windows App SDK catalog, clearly separate from project references:

GenerateStructuredJsonResponseAsync
  Project index (AI 1.8.53): no matching member
  SDK catalog (Windows App SDK 2.4.0 / AI 2.4.4): found

The same lookup against older and newer restored projects

The experiment acquired about 175 MB of selected SDK/API packages and produced a roughly 4.9 MB metadata cache. Make the initial download explicit and reuse the cache; do not modify the project or install a runtime. “Found in version X” must not imply a minimum version, compilation success, or device compatibility.

Images show rendered captures of actual command output from 9fdb3af1, not native terminal-window screenshots. Paths are shortened and excerpts labeled. Fixed generic-substitution, XML-reader, restore-ownership and npm-documentation findings have been removed.

[Jaylyn Barbee (Jaylyn-Barbee)]

2. Search package descriptions and meaningful words

winapp find-api "text generation" finds nothing, although the package describes LanguageModel as providing text generation and embeddings.

Microsoft.WindowsAppSDK.AI ships no XML documentation at all (verified for 1.8.53), so LanguageModel has no summary to search. But we did make some changes to search to improve the experience as called out in the rest of issue 2.

Everything else from that review has been fixed.

[Nikola Metulev (nmetulev)]

🤖 AI-generated review clarification (winappcli pr-review skill) — verify before acting.

Jaylyn Barbee (@Jaylyn-Barbee)

You're right about AI 1.8.53: it has no API XML documentation. Our example used
AI 2.4.4, which includes metadata/Microsoft.Windows.AI.Text.xml and this
LanguageModel summary:

Provides text generation and embedding operations backed by a language model.

I should have made that version distinction explicit in the review.

This is also a useful example of why searching a latest-SDK catalog alongside
project references could help. It serves two different cases:

Search	What the newer catalog adds	What the project check should say
text generation	A description that identifies LanguageModel.	The type and response-generation methods already exist in AI 1.8.53. Don't recommend an upgrade just because the description came from 2.4.4.
GenerateStructuredJsonResponseAsync	A member absent from AI 1.8.53.	Found in the newer catalog, not in the current references.

The proposal is to discover with both sources, then use the referenced metadata
for current-project signatures and presence. Keep the newer description's source
visible rather than treating it as documentation shipped with the older version.
That does not imply behavior is identical across versions.

This remains entirely package-derived: no aliases, invented documentation or
automatic project updates. Thanks for the search and help improvements already
landed; the separately cached latest-SDK lookup remains a feature proposal, not
a claim that the local-only lookup should find text its packages never supplied.

[Jaylyn Barbee (Jaylyn-Barbee)]

The proposal is to discover with both sources, then use the referenced metadata for current-project signatures and presence. Keep the newer description's source visible rather than treating it as documentation shipped with the older version. That does not imply behavior is identical across versions.

This remains entirely package-derived: no aliases, invented documentation or automatic project updates. Thanks for the search and help improvements already landed; the separately cached latest-SDK lookup remains a feature proposal, not a claim that the local-only lookup should find text its packages never supplied.

So this will be resolved by follow up issue #832, if I am understanding correctly?