Create a plugin system

[fnando]

• stellar plugin list [--installed]: list plugins by using Github search
  (--installed will show installed plugins only)
• stellar plugin add [SOURCE]: install a plugin. SOURCE can be a local
  directory, a git url (e.g. https://github.com/user/repo.git#ref), or a
  Github user/repo#ref.
• stellar plugin remove PLUGIN: remove a plugin.
• stellar plugin update: update all plugins; must respect git refs.

Plugin structure

A plugin is a directory that has a bin/ directory and manifest.toml file.
For now, only stellar contract bindings [TYPE] plugins will be supported. For
instance, if you want to generate bindings for Ruby, you could have an
executable binary as bin/stellar-contract-bindings-ruby in your repository.

The manifest:

# define the manifest version.
manifest = "1.0"

# All fields are required.
description = "generate Python language bindings for Stellar Soroban smart contracts."
url = "https://github.com/lightsail-network/stellar-contract-bindings"
version = "0.1.0"

Reference output

$ stellar plugin list
name: lightsail-network/stellar-contract-bindings
description: generate language bindings for Stellar Soroban smart contracts.
url: https://github.com/lightsail-network/stellar-contract-bindings
installed: no

name: fnando/stellar-contract-bindings-ruby
description: generate Ruby bindings for Stellar Soroban smart contracts.
url: https://github.com/fnando/stellar-contract-bindings-ruby
installed: no

$ stellar plugin add lightsail-network/stellar-contract-bindings
❓ Are you sure you want to continue (y/n)? y
ℹ️ Installing plugin "lightsail-network/stellar-contract-bindings"
✅ Plugin was installed!
📄 For instructions, visit https://github.com/lightsail-network/stellar-contract-bindings

$ stellar plugin list --installed
name: lightsail-network/stellar-contract-bindings
description: generate language bindings for Stellar Soroban smart contracts.
url: https://github.com/lightsail-network/stellar-contract-bindings
installed: yes

$ stellar plugin update
ℹ️ Updating installed plugins
🔄 Updated "lightsail-network/stellar-contract-bindings"
✅ Done!

$ stellar plugin remove lightsail-network/stellar-contract-bindings
✅ Plugin was uninstalled!

[leighmcculloch]

Regarding refs, should we be opinionated and only support installing from tags? Or too opinionated?

For upgrades, we should probably support version selection such that one could upgrade inside v22 without getting v23.

[leighmcculloch]

Can we also explore for the js-stellar-sdk what the narrative is. e.g. I'm a js-stellar-sdk user, I'm importing it into my project, what's the shortest path / narrative I expect to get generated bindings that are compatible with my js-stellar-sdk in my current project. Then, what if I have 3 projects, some are using different versions of js-stellar-sdk, how do I navigate that?

I'm asking that question because in some ways a plugin system makes the experience of the binding generation again CLI adjacent, which presents similar problems of making sure you're using the right version vs being SDK adjacent where if you could generate with the sdk itself, somehow, then you'd naturally use a compatible version.

The best narrative for 👆🏻 may be to try and bundle it very close to or inside SDKs, although I realise there are mixed views on that.

[fnando]

Regarding refs, should we be opinionated and only support installing from tags? Or too opinionated?

I think that'd be too restrictive. I'd rather go with 2 options: refs or no ref at all (this case would always update to HEAD on the main branch). I wonder if we should keep the version on the manifest at all, given this. 🤔

Can we also explore for the js-stellar-sdk what the narrative is. e.g. I'm a js-stellar-sdk user,… The best narrative for 👆🏻 may be to try and bundle it very close to or inside SDKs, although I realise there are mixed views on that.

I think keeping bindings close to the sdk is good move, tbh. And we can expose that to the cli via this plugin system. Let's say we move TS bindings to js-stellar-sdk; we can have a binaries like stellar-contract-bindings-ts and stellar-contract-bindings-js defined on that repo. Then users would run stellar plugin add stellar/js-stellar-sdk. But that may not be the case for all sdks, and some bindings may not necessarily be implemented by the sdk maintainer.

Installing globally could lead to mismatching versions, but I don't think we should try to solve that at all. Maybe one thing we can do is adding node_modules/.bin to the search path. That'd solve the mismatching issue because it'd favor the local bin rather than the global installation. I'm not sure how other languages would play with that. 🤔

[leighmcculloch]

Another option is to install bindings into the local directories .stellar directory, and to possibly define plugins in use with a local toml file that does get committed.

But, are we building a plugin empire around something that doesn't need to be. If a user has the js-stellar-sdk installed in a project, is there a way to invoke a binary that is within it with a one-liner npx command?

[fnando]

If a user has the js-stellar-sdk installed in a project, is there a way to invoke a binary that is within it with a one-liner npx command?

Yes, that can work. But then we go back to square one, which is discoverability. Maybe all we should do is adding stellar plugin list, which would link to the proper repo and let users handle the binary installation as per the readme instructions.

$ stellar plugin list
🔎 View on GitHub: https://github.com/search?q=topic%3Astellar-cli-plugin&type=repositories

name: lightsail-network/stellar-contract-bindings
description: generate language bindings for Stellar Soroban smart contracts.
url: https://github.com/lightsail-network/stellar-contract-bindings

[leighmcculloch]

But then we go back to square one, which is discoverability

Maybe we're thinking about this the reverse way. I was thinking about this from the perspective of "I'm a stellar-cli user, how do I know I can generate bindings, how do I discover bindings I can generate."

But, bindings are all about the SDK. It's all about helping developers use an SDK more efficiently, more effectively, to interact with a contract. So a user sitting there with the SDK shouldn't even need to know about the CLI, not really. They will know about the CLI, but that coupling is actually incidental. The story is more like "I'm an SDK user, how do I know I can generate bindings for a contract that use the SDK."

[leighmcculloch]

@fnando I know you mentioned you were planning to experiment with prototyping this. Another thing we could do is, once we have the prototype, experiment with what the docs would look like for telling people how to generate bindings. I think doing some of those changes might help us to validate what the developer experience will look like.