Spec discussion: How do we want the CLI UX to be for distinguishing a plugin's name and it's type

[aaronsteers]

Following from our conversation on this issue (#6114 (comment)), I wanted to have a formal spec guideline for dereferencing plugins by type (or not) and how that should look in new CLI commands.

As I wrote in that issue:

---

Having to declare the plugin type unless there's a naming conflict is probably the best path forward for new CLI commands.

This means taking the approach of an optional --plugin-type arg to disambiguate if needed and I've included meltano config as the reference example of this approach. The plugin type should be totally optional though, and would only have a function to (1) confirm the type is as expected if the user wants to be explicit, and (2) resolve ambiguity if two plugins of different type have the same name. (Although we should consider name collisions illegal in a future meltano version.)

We should in general be encouraging plugins to not have name collisions. They already cannot have them within a specific type, and would need to be aliased if so.

Related: in future, we're talking about reducing the total number of plugin types so that a broad category of utility plugins would have capabilities like analyzer, validator, orchestrator, etc., but those may not always be distinct plugin types. Hence, keeping extractor type out of our default CLI convention is a good thing overall. (E.g. meltano config tap-gitlab preferred over meltano config extractor tap-gitlab, and meltano lock tap-gitlab preferred over meltano lock extractor tap-gitlab.)

aj@ajs-macbook-pro aj-dataops-personal % meltano config --help 
2022-06-16T19:26:21.249476Z [info     ] Environment 'dev' is active
Usage: meltano config [OPTIONS] PLUGIN_NAME COMMAND [ARGS]...

      Display Meltano or plugin configuration.

      Read more at https://docs.meltano.com/reference/command-line-interface#config
          

Options:
  --plugin-type [extractor|loader|transform|orchestrator|transformer|file|utility|mapper|mapping|extractors|loaders|transforms|orchestrators|transformers|files|utilities|mappers|mappings]
  --format [json|env]
  --extras                        View or list only plugin extras.
  --database-uri TEXT             System database URI.
  --help                          Show this message and exit.

Commands:
  list   List all settings for the specified plugin with their names,
         environment variables, and current values.

  reset  Clear the configuration (back to defaults).
  set    Set the configurations' setting `<name>` to `<value>`.
  test   Test the configuration of a plugin.
  unset  Unset the configurations' setting called `<name>`.

[edgarrmondragon]

Thanks for starting this @aaronsteers. Here's how things are looking for meltano lock:

$ meltano lock --help
Usage: meltano lock [OPTIONS] [PLUGIN_NAME]...

  Lock plugin definitions.

      Read more at https://docs.meltano.com/reference/command-line-interface#lock
          

Options:
  --all                           Lock all the plugins of the project.
  --plugin-type [extractor|loader|transform|orchestrator|transformer|file|utility|mapper|mapping|extractors|loaders|transforms|orchestrators|transformers|files|utilities|mappers|mappings]
                                  Lock only the plugins of the given type.
  -u, --update                    Update the lock file.
  --database-uri TEXT             System database URI.
  --help                          Show this message and exit.

I like that this make the UX more intuitive, e.g.

• I want to create all plugin locks

  meltano lock --all

• I want to update all extractor locks

  meltano lock --all --update --plugin-type=extractor

• I want to update tap-github and target-snowflake

  meltano lock tap-github target-snowflake --update

[tayloramurphy]

I'm a fan of this @aaronsteers. It's always been a little odd to me that you have to supply extractor or loader when doing meltano add. Like, just figure it out please Meltano.

It looks like we already follow this pattern on invoke, config, and now lock. From searching the docs it seems like we'd need to update:

• add
• remove
• install

Any others?

Edit: add install.

[edgarrmondragon]

@tayloramurphy install is the other one with a <type> positional argument

[tayloramurphy]

@edgarrmondragon I figured that out earlier doing my speedrun! I searched for <type> in the CLI ref and didn't see it for install.