feat(completions): Update winget-completions.nu for winget v1.11.510

[hcoona]

Winget Completions Update Summary

Overview

Successfully updated the winget-completions.nu file for Windows Package Manager v1.11.510.

Changes Made

1. Gathered Complete Documentation

• Collected help information for all winget commands and subcommands
• Stored in winget-help-dumps/ folder for future reference
• Reviewed current NuShell custom completions documentation

2. Major Updates

New Commands Added

• winget pin - Manage package pins (with subcommands: add, remove, list, reset)
• winget download - Downloads the installer from a given package
• winget configure - Configures the system into a desired state (mentioned but not fully implemented)
• winget repair - Repairs the selected package (mentioned but not fully implemented)
• winget dscv3 - DSC v3 resource commands (mentioned but not fully implemented)

Enhanced Existing Commands

All commands now include the full set of global options:

• --wait - Prompts before exiting
• --logs / --open-logs - Open logs location
• --verbose / --verbose-logs - Enable verbose logging
• --nowarn / --ignore-warnings - Suppress warnings
• --disable-interactivity - Disable interactive prompts
• --proxy - Set proxy for execution
• --no-proxy - Disable proxy for execution

New Options in Install/Upgrade Commands

• --architecture (-a) - Select architecture
• --installer-type - Select installer type
• --custom - Additional arguments for installer
• --ignore-security-hash - Ignore hash check failures
• --allow-reboot - Allow system reboots
• --skip-dependencies - Skip dependency processing
• --ignore-local-archive-malware-scan - Ignore malware scans
• --dependency-source - Source for dependencies
• --no-upgrade - Skip upgrades if already installed
• --authentication-mode - Authentication preference
• --authentication-account - Account for authentication
• --rename (-r) - Rename executable (portable)
• --uninstall-previous - Uninstall old version during upgrade

Enhanced List/Search Commands

• --cmd / --command - Filter by command
• --upgrade-available - Show only upgradable packages
• --unknown / --include-unknown - Include packages with unknown versions
• --pinned / --include-pinned - Include pinned packages
• --versions - Show available versions

Enhanced Uninstall Command

• --product-code - Filter by product code
• --all / --all-versions - Uninstall all versions
• --purge - Delete all package files
• --preserve - Retain created files

Source Management Updates

• Added --trust-level option for source add
• Added --explicit flag for source add

3. Improved Completion Functions

Updated Completers

• nu-complete winget sources - Lists available package sources
• nu-complete winget scope - user/machine scope options
• nu-complete winget locale - BCP47 locale codes
• nu-complete winget architecture - x86, x64, arm, arm64, neutral
• nu-complete winget installer-type - All installer types
• nu-complete winget authentication-mode - silent, silentPreferred, interactive
• nu-complete winget source-type - Microsoft.PreIndexed.Package, Microsoft.Rest
• nu-complete winget trust-level - none, trusted

New Completers

• nu-complete winget installed packages - Caches installed packages for uninstall completions
• nu-complete winget search packages - Placeholder for search package completions

4. Syntax Improvements

• Updated to use modern NuShell syntax
• Proper use of @ for attaching completers to type annotations
• Consistent parameter naming and descriptions
• Added all command aliases (e.g., winget add, winget view, winget find, etc.)

5. Documentation

• All parameters now have clear, concise descriptions
• Maintained consistency with official winget help text
• Added comments for better code organization

Files Created

winget-help-dumps/ - Directory containing all winget help outputs

• winget.txt - Main command help
• install.txt - Install command help
• show.txt - Show command help
• search.txt - Search command help
• list.txt - List command help
• upgrade.txt - Upgrade command help
• uninstall.txt - Uninstall command help
• source.txt - Source command help
• source-add.txt - Source add subcommand help
• source-list.txt - Source list subcommand help
• export.txt - Export command help
• import.txt - Import command help
• hash.txt - Hash command help
• validate.txt - Validate command help
• pin.txt - Pin command help
• download.txt - Download command help
• settings.txt - Settings command help
• features.txt - Features command help

Testing

• ✅ File syntax validated with NuShell
• ✅ Commands properly export
• ✅ Completions load without errors

Breaking Changes

Removed Structured Data Output Functions

The following custom functions that parsed winget output into structured NuShell tables have been removed:

1. winget source list - Previously returned parsed table with Name and Argument columns

   • Old behavior: winget source list returned a structured table
   • New behavior: Now uses extern declaration, returns raw winget CLI output
   • Migration: Users relying on structured output need to parse manually or use | detect columns

2. winget search - Previously returned parsed table with name, id, version, match, source columns

   • Old behavior: winget search <query> returned a structured table with --raw flag to disable parsing
   • New behavior: Now uses extern declaration, always returns raw winget CLI output
   • Migration: Use | detect columns or custom parsing to get structured data

3. winget list - Previously returned parsed table with name, id, version, available, source columns

   • Old behavior: winget list returned a structured table with --raw flag to disable parsing
   • New behavior: Now uses extern declaration, always returns raw winget CLI output
   • Migration: Use | detect columns or custom parsing to get structured data

4. winget upgrades (internal function) - Previously parsed upgrade list into structured data

   • This internal function has been removed entirely

Removed Helper Functions

• nu-complete winget flagify - Internal helper for building command flags
• nu-complete winget trimLoadingSymbol - Internal helper for cleaning winget output

Rationale for Changes

The structured output functions were removed because:

• Fragility: Parsing CLI text output is brittle and breaks when winget changes output format
• Maintenance burden: Requires constant updates to match winget's output changes
• Complexity: Added significant code complexity for parsing logic
• NuShell improvements: Modern NuShell has better built-in parsing tools like detect columns
• Focus: The primary purpose of this file is completions, not output parsing

Migration Guide

If you relied on the structured output:

# Old way (no longer works):
let packages = winget search vscode

# New way (recommended):
let packages = winget search vscode | detect columns --guess

# Alternative with lines and parse:
let packages = winget search vscode 
   | lines 
   | skip 2  # Skip header lines
   | parse "{name} {id} {version} {match} {source}"

Recent Improvements (Based on Cargo/Eza Completions)

Code Quality Enhancements

1. Enhanced Documentation

   • Added detailed header comment describing winget's purpose
   • Included winget version (v1.11.510) in the header
   • Added @category package-manager annotations to all main commands
   • Added @example annotations with practical use cases for key commands:
     • winget install - 3 examples (by name, specific version, silent install)
     • winget show - 2 examples (package info, available versions)
     • winget search - 2 examples (basic search, exact ID search)
     • winget list - 3 examples (all packages, upgrades, by source)
     • winget upgrade - 3 examples (show upgrades, upgrade all, specific package)
     • winget uninstall - 2 examples (by name, by ID)

2. Improved Completion Functions

   • All completion functions maintain simple, clean list format
   • Proper caching for expensive operations (installed packages)
   • Efficient parsing of winget output

3. Better Code Organization

   • More descriptive multi-line comments for complex commands
   • Consistent formatting across all extern declarations
   • Clearer separation between completion functions and command definitions

Notes

• Some commands (configure, repair, dscv3) were mentioned in help but not fully documented - basic extern declarations can be added if needed
• The file is now fully compatible with winget v1.11.510
• All global options are consistently available across all commands
• Completion functions use caching where appropriate to improve performance
• All commands now use extern declarations for consistency and maintainability

[fdncred]

1. This is so much text it makes me think it's all AI generated, which I'm not a super fan of unless there is a lot of human involvement and testing.

2. Now uses extern declaration, returns raw winget CLI output

I'm not a fan of having raw winget cli output. This is supposed to be a nushell script. if detect columns works great, as indicated in all this text, then it should be used to format the output in nushell tables.

[hcoona]

Hi @fdncred,

Thanks a lot for the feedback! I really appreciate you taking the time to review this in detail.

1. This is so much text it makes me think it's all AI generated, which I'm not a super fan of unless there is a lot of human involvement and testing.

I completely understand your concern. AI-generated code can sometimes miss the intention or lack quality, especially without sufficient human review. I admit that this PR was initially generated by AI, but I manually verified it by comparing the previous and current implementations. In this case, it was a very clear and well-defined change, so it was easy for AI to understand my intention: mapping help messages to completions.

I’ve tested the new version on two of my own PCs, and in my main usage scenarios (such as list --update-available, upgrade, and search), it has worked reliably so far.

I hope this helps address your concern.

2. Now uses extern declaration, returns raw winget CLI output

I'm not a fan of having raw winget cli output. This is supposed to be a nushell script. if detect columns works great, as indicated in all this text, then it should be used to format the output in nushell tables.

I agree that ideally, the output should be nicely formatted in Nushell tables. However, parsing raw winget CLI output is extremely difficult because it’s not machine-readable: the separators are inconsistent, and some cells may be empty, which breaks any structured parsing logic or makes it too complex.

Microsoft’s PowerShell implementation faced the same issue. They avoid parsing the CLI output either. Their solution was to bypass the CLI entirely and instead call the underlying COM/WinRT interface directly.

Given that limitation, I believe returning the raw CLI output is currently the most pragmatic and maintainable approach. If winget ever provides a structured output format in the future (e.g., JSON or XML), I’d be happy to revisit this and add proper Nushell formatting then.

Thanks again for the constructive discussion!

[hcoona]

@fdncred kindly ping for your feedback.

[fdncred]

I understand your points about winget not supporting a structured output format, shame on them. But I'm not inclined to land a version of this that removes the nushell tables. Seems like regex could be used here to make the tables or maybe there's some other way based on how powershell does it?

[hcoona]

Hi @fdncred,

Thanks for clarifying — I see the core issue now is whether this completion should keep parsing into Nushell tables. Let me show you why I was hesitant to say “let’s just regex it,” using the exact output shape from the screenshot I tested with.

The data itself looks like a table, but it’s only visually aligned. In the screenshot the gaps between columns aren’t consistent. On the line with Microsoft Azure Storage Explorer version 1.39.1 there’s only 1 space between the name and the id. On the line with Visual Studio Enterprise 2022 there’s only 1 space between the id and the version. So we can’t rely on “2+ spaces = new column”.

Some rows contain values that “look like” other columns. The name Microsoft Azure Storage Explorer version 1.39.1 already includes something that looks like a version, but it’s part of the name, not the Version column.

Some Version cells are not “plain versions”. On the Visual Studio Enterprise 2022 line the Version value is < 17.14.18, so we have to handle symbols and extra spacing, not just x.y.z.

And all of this can change with terminal width.

Because of all that, my takeaway is: we can write a regex that works on this screenshot, but we can’t write a simple, stable regex that works on “arbitrary winget output on arbitrary user machines” — which is what we want for completions.

That’s also why I mentioned PowerShell earlier: Microsoft’s own PowerShell integration doesn’t try to parse the CLI text output either — they skip the CLI and talk directly to the COM/WinRT layer underneath, because that’s the only place where the data is actually structured. In other words, even the people closest to winget decided “parsing the pretty console output” is the wrong abstraction.

So that’s the reasoning behind my proposal: in Nushell, unless we also go to a structured source (like PS did), returning the raw CLI output is the most honest and the least fragile thing we can do right now. If/when winget gives us JSON/XML, I’m 100% on board with tables.