add spec for #1620

doc/specs/#1620 - Installer selector on multiple matches.md

@@ -0,0 +1,270 @@
+---
+author: Darshan Rander @SirusCodes
+created on: 2022-10-29
+last updated: 2022-11-11
+issue id: 1620
+---
+
+# Spec Title
+
+For [#1620](https://github.com/microsoft/winget-cli/issues/1620)
+
+## Abstract
+
+Currently, the winget.exe client simply lists all the matches and if the user wants to install the app they need to re-run the command with Id.
+
+The UX can be improved here by giving users an option to select the package instead of asking them to re-run the command with Id.
+
+This can be extended to `upgrade`, `show` and `uninstall` commands.
+
+## Inspiration
+
+Whenever I use Winget to install any application there are high chances that there are name collisions with other names and I get multiple suggestions in the table and it's annoying to copy the ID and rerun the command. I guess this is the case for a lot of others as well.
+
+## Solution Design
+
+If we find multiple packages then the user should get a selector.
+
+> It should not be shown if `--diable-interactivity` is set.
+
+### Settings
+
+The user needs to **opt-in** to this feature.
+
+Winget can use `--prompt` and `--no-prompt` flags to enable and disable it respectively.
+
+The user can change the default setting to always show the prompt by -
+
+```pwsh
+"packageDisambiguation": "prompt"
+```
+
+and disable it by -
+
+```pwsh
+"packageDisambiguation": "no-prompt"
+```
+
+### Valid inputs
+
+- Number - It should match with a _row number_ (0 will exit the selector)
+- Text - It should match either the package _Name_ or _Id_
+
+#### Flags
+
+- `--more` or `-m` flag - It should be used to show more n number of results.
+- `--id` - Filter results by id
+- `--name` - Filter results by name
+- `--moniker` - Filter results by the moniker
+- `--tag` - Filter results by tag
+- `--cmd` or `--command` - Filter results by command
+- `-s` or `--source` - Find the package using the specified source
+- `-e` or `--exact` - Find the package using exact match
+
+### Invalid inputs
+
+If a user enters an invalid value it should show an error asking the user for input again,
+
+Example: `1ab`
+
+```pwsh
+Invalid input, please enter row number, or package name or id.
+```
+
+If a user enters a number that is out of the shown list then they get an error to enter numbers that are in the list.
+
+Example: `23` in the list of `20`` entries
+
+```pwsh
+Please enter row number which are present in entries above.
+```
+
+### Number of results
+
+We can use `-n` or `--number` flags to customize the number of packages listed in the prompt. As there is already a user setting for it, we don't need to add any special settings for it.
+
+If the number of packages is more than allowed it should show a text saying how many more packages are available
+
+```pwsh
+...
+ 20  Example Example.Example20 winget
+
+There are 6 more packages available. Use -m or --more to see more.
+Please select a row number or refine the search by package name or ID.
+>
+```
+
+If a user enters the package name or ID then we should scan the whole list including the ones which are not shown to the user.
+
+If the user enters a number then it should be in the range of the list shown to the user and the user cannot use `-m` or `--more` flags with other queries or flags.
+
+The `--more` flag will show the user the hidden items and increases the range of input they can have.
+
+```pwsh
+...
+ 20  Example Example.Example20 winget
+
+There are 6 more packages available. Use -m or --more to see more.
+Please select a row number or refine the search by package name or ID.
+> -m
+ 21  Example Example.Example21 winget
+ ...
+ 26  Example Example.Example26 winget
+Please select a row number or refine the search by package name or ID.
+>
+```
+
+### Refine the search
+
+A user can search results by entering text input. The text input should be compared with the Name and ID in the result.
+
+If a user enters a Name or ID and we found only an exact match then start installing the package else we should show the new refined list to the user.
+
+The text input is said to be invalid only if it doesn't match any of the names or IDs. The user will see an error for invalid input and will be asked to retry.
+
+If the user enters the name/ID and source or only source and there isn't any source then the user will see an error message which says that cannot find the package with the source.
+
+The first query will fetch package details from the indexed database and further refinements will be made to the result from the initial query.
+
+### Tab completion
+
+The Tab completion would complete the package name/ID and cycle through the package ID on `Tab` press and reverse cycle through it on `Tab` + `Shift`.
+
+## UI/UX Design
+
+This is how the prompt should look like...
+
+```pwsh
+> winget install Example
+Multiple packages found matching.
+ Number Name       Id                   Source
+-------------------------------------------
+   1    Example    Example.Example1     msstore
+   2    Example    Example.Example2     winget
+...
+   20   Example20  Example.Example20    msstore
+There are 8 more packages.
+
+Please select a row number, or enter package name or ID to refine search...
+> _
+```
+
+If a user enters a row number between 1-20 then install the package
+
+```pwsh
+Please select a row number, or enter package name or ID to refine search...
+> 2
+Downloading Example (Example.Example2)...
+```
+
+If a user enters an invalid input.
+
+```pwsh
+Please select a row number, or enter package name or ID to refine search...
+> 23
+Please enter row number which are present in entries above.
+>
+```
+
+If the user enters a name or ID then we should refine the list.
+
+```pwsh
+...
+Please select a row number, or enter package name or ID to refine search...
+> Example
+
+Refined the search to Name/ID with `Example` in it.
+Number Name       Id                   Source
+-------------------------------------------
+   1   Example    Example.Example1     msstore
+   2   Example    Example.Example2     winget
+   3   Example    Example.Example22    msstore
+
+Please select a row number, or enter package name or ID to refine search...
+> _
+```
+
+A user can use flags (example `--source`)
+
+Now we only have a package with ID `Example.Example2` in the list because of the queries the user wrote.
+
+```pwsh
+Refined the search to Name/ID with `Example` in it.
+Number Name       Id                   Source
+-------------------------------------------
+   1   Example    Example.Example1     msstore
+   2   Example    Example.Example2     winget
+   3   Example    Example.Example22    msstore
+
+Please select a row number, or enter package name or ID to refine search...
+> --source winget
+Downloading Example (Example.Example2)...
+```
+
+If a query matches nothing then exit the CLI with the message that the query couldn't find any result.
+
+```pwsh
+Number Name       Id                   Source
+-------------------------------------------
+   1   Example    Example.Example1     msstore
+   2   Example2   Example.Example2     winget
+...
+   20  Example20  Example.Example20    msstore
+There are 8 more packages.
+
+Please select a row number, or enter package name or ID to refine search...
+> Example --source winget
+No package found matching input criteria
+```
+
+## Capabilities
+
+### Accessibility
+
+The screen reader read the text properly as it reads the current implementation.
+
+### Security
+
+It should not have any security issues.
+
+### Reliability
+
+The user might enter the number incorrectly in rush and might need to kill the running installation process and restart it.
+
+### Compatibility
+
+This won't work in MinQTTY. It's a [known issue](https://github.com/git-for-windows/build-extra/blob/main/ReleaseNotes.md?rgh-link-date=2022-10-21T03%3A13%3A26Z#known-issues) in Git-for-windows.
+
+### Performance, Power, and Efficiency
+
+## Potential Issues
+
+It should not be shown if `--diable-interactivity` is set.
+
+There should be no effect of the `--silent` flag on the selector.
+
+Having the `upgrade` command included in this would conflict with [#2627](https://github.com/microsoft/winget-cli/issues/2627)
+
+For example - `winget upgrade Microsoft` might have a match with hundreds of packages and use might not want to see this prompt. Tho this is an opt-in feature but there might be a clash if a user has opted in from settings.
+
+## Future considerations
+
+Currently, Winget does not support installing multiple packages in a single command.
+
+For Example -
+
+```pswh
+winget install Powershell Git
+```
+
+The above command will not install anything.
+
+If this is ever supported, potential considerations include having _multiple_, _range_ and _not_ selectors.
+
+- multiple selector (1 3): A **space** separated number should install packages of that number.
+- range selector (1-3): A **hyphen** separated number should install all the packages including the start and end numbers.
+- not selector (^2): A number with a **carat** symbol should install all packages except the number marked with a carat symbol.
+
+## Resources
+
+- [winget#301 (comment)](https://github.com/microsoft/winget-cli/issues/301#issuecomment-940172239) a snapshot from the [yay](https://github.com/Jguer/yay).