feat(zsh): support support space-separated completion

[cristiand391]

This PR adds support for space-separated commands.

See this blog for how state is kept between comp function calls:
https://www.dolthub.com/blog/2021-11-15-zsh-completions-with-subcommands/

zsh completion docs: https://zsh.sourceforge.io/Doc/Release/Completion-System.html
see also this guide: https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org#intro

NEW

1. zsh will suggest hardcoded values for flags that have options set (https://github.com/salesforcecli/plugin-data/blob/355f2a846cf6fea17614417afbea44c51ca0ade4/src/commands/data/query.ts#L80)
2. comp will suggest the short-name of the flag when only one - is present on the current line(<command> -<tab>).
3. flags that have multiple prop set to true will be suggested even if it's already present on the current line (https://github.com/salesforcecli/plugin-deploy-retrieve/blob/c09b83a48f763df053a6209e84648aafc5419709/src/commands/deploy/metadata.ts#L80)

cotopics

A cotopic is an id that is both a command and a topic, a few examples from the sf cli:
data query -> data query resume
deploy -> deploy functions|metadata
logout -> logout functions|org

When a cotopic is present on the current line and you press tab, it will suggest the next valid topics/commands:
sf deploy <tab> ⬇️

sf deploy
completions
functions  -- Deploy a Salesforce Function to an org from your local project.
metadata   -- Commands to deploy metadata to a Salesforce org.

but if a - is present after the cotopic pressing tab will suggest flags only valid to it:
sf data query -<tab> 🔽

sf data query -
option
--api-version          -- Override the api version used for api requests made by this command
--async                -- Use Bulk API 2.0, but don't wait for the job to complete.
--bulk             -b  -- Use Bulk API 2.0 to run the query.
--file             -f  -- File that contains the SOQL query.
--json                 -- Format output as json.
--query            -q  -- SOQL query to execute.
--result-format    -r  -- Format to display the results; the --json flag overrides this flag.
--target-org       -o  -- Username or alias of the target org.
--use-tooling-api  -t  -- Use Tooling API so you can run queries on Tooling API objects.
--wait             -w  -- Time to wait for the command to finish, in minutes.

@W-12069114@

Release notes

BREAKING CHANGE

plugin-autocomplete will default to the autocomplete for the space separator if the CLI supports it.

If you still want to use the autocomplet for colon-separated commands you can set the OCLIF_AUTOCOMPLETE_TOPIC_SEPARATOR env var to colon.
https://github.com/oclif/plugin-autocomplete/#topic-separator

Features

New zsh autocomplete for oclif CLIs using space as a topic separator.

This implementation includes the following new features:

• Flag value completion for those that define a known set of options
• Flags with multiple: true set will be suggested in autocompletion even if it's already been used.
• Suggest short flag name if - is present on the current line

[cristiand391]

can't link to zsh docs so I'll leave chunks related to the code that are searchable here:
https://zsh.sourceforge.io/Doc/Release/Completion-System.html

A function calling _arguments with at least one action containing a ‘->string’ must therefore declare appropriate local parameters:

[cristiand391]

sf data query --json -<tab>

line[1] is the last word on the current line, if it matches any valid command of the cotopic it will suggest flags valid to that command.

*) is the "default" block of the switch statement, if line[1] doesn't match any valid command of the cotopic then keep suggesting flags of the cotopic.

[mshanemc]

QA notes:

This is really, really cool!

I had to ask for setup help. After running sfdx autocomplete and source ~/.zshrc I'd get the new behavior (or I thought I used to). This time, I had to either open a new terminal OR run some other commands to get the updates.

👎🏻 I don't get autocomplete for colons. So if I type sfdx force:or and TAB I get nothing. Not sure if that's WAD or not. I think you'd either want the colons to complete OR you modify their input to turn the colons into spaces and then work from there?
👎🏻 sfdx force org TAB. I was going to do an org open, but it's not there. I expected aliases to be there
✅ command and flag summaries appear

👎🏻 sfdx org list TAB. It shows additional commands--I'd like to see an indicator that org list itself is a command I could run. Maybe if it showed [ENTER] in the first column and the summary of the org list command?

✅ adding a non-multiple flag prevents it from appearing in the next autocomplete list
✅ putting a -- when there's only one flag remaining automatically completes that remaining flag
🏆 original autocomplete puts = after flags that take values. I'm glad this one does't
👎🏻 --help doesn't autocomplete
💡 [beyond the scope of this WI] I'd prefer autocomplete flag summaries to look like the do in help.FLAGS section. Those show requiredness, defaults, options, min/max. I think it would be more useful to the user. Same with whether it takes a value or is a boolean. Maybe list required flags first, then a divider, then the optional flags
✅ multiple flags remain in the choices after using one
💡 this sounds hard, but if we know the flag relationships/exclusive/dependsOn/exactlyOne/etc, this could be even more helpful. wouldn't want it just for zsh though.
✅ provides completions when varArgs are sprinkled insfdx force org create --durationdays 4 username=foo --
😮 that it completes option flags!!! (sfdx force org create --type ) will add the s and finish the option when it gets enough letters to do so. Cool.

[cristiand391]

👎🏻 I don't get autocomplete for colons. So if I type sfdx force:or and TAB I get nothing. Not sure if that's WAD or not. I think you'd either want the colons to complete OR you modify their input to turn the colons into spaces and then work from there?

it's possible on zsh but not sure about bash/powershell, logged this WI to check once powershell comp is finished. I'll keep an eye on user feedback too.

👎🏻 sfdx force org TAB. I was going to do an org open, but it's not there. I expected aliases to be there

✅ fixed.
Caveat:
Aliases that diverge from a valid topic will have a generic description since it's not possible to determine a valid description for it. Example:

alias1 = `force:org:open`

both `force` and `force:org` are valid topics and have their description so the plugin can just append `open` to it.

alias2 = `force:alias:list`

`force` exists as a topic but not `force:alias`, will add the missing topic and set its description to "force alias commands"

➜  plugin-auth git:(phale/restructure-auth) sfdx force a
completions
alias      -- force alias commands
analytics  -- force analytics commands
apex       -- work with Apex code
auth       -- force auth commands

👎🏻 sfdx org list TAB. It shows additional commands--I'd like to see an indicator that org list itself is a command I could run. Maybe if it showed [ENTER] in the first column and the summary of the org list command?

I haven't found a way to do this with the current zsh comp utilities.
If you type - after the command zsh will start suggesting flags instead of the next valid commands:

but yep, unless users already knows it is a command they may skip it.

💡 [beyond the scope of this WI] I'd prefer autocomplete flag summaries to look like the do in help.FLAGS section. Those show requiredness, defaults, options, min/max. I think it would be more useful to the user. Same with whether it takes a value or is a boolean. Maybe list required flags first, then a divider, then the optional flags

zsh has comp utilities for this, see Grouping Options section here:
https://zsh.sourceforge.io/Doc/Release/Completion-System.html
I'm not sure about bash/powershell, logged this WI

👎🏻 --help doesn't autocomplete

✅ fixed.

[cristiand391]

@mshanemc major bump intentional, make sure to squash merge the PR and mark it as a breaking change (I think GHA does this? or is the pjson bump enough?).

[mshanemc]

QA Notes

✅ after running the autocomplete command and opening a new terminal, I get completions for aliased commands (test with force org list

✅ --help is in the flags list

✅ ran OCLIF_AUTOCOMPLETE_TOPIC_SEPARATOR=colon sfdx autocomplete, opened a new terminal, and then validated the behaviors from the original QA using colons.
⏫ this turned our really nice. I like that we support both and the users can decide.

⚠️ using colon will give you the 'old" zsh completions experience, without all the fancy tricks that are added when you use spaces. We just want to make sure people know that.