RFC: Automatic updates for completion specs generated via 'introspection'

[mschrage]

Current workflow

Suppose a developer creates a new completion spec in the autocomplete repo (optionally using one of our integrations with CLI frameworks, like cobra or commander, to automatically generate the skeleton via introspection).

When the developer updates the CLI tool source, they have two options:

1. If the spec was created manually: they must edit the spec to reflect any new changed to CLI structure.

2. If the spec was created via introspection: they need to regenerate the CLI skeleton from the updated source code and use the merge tool to incorporate any manual changes from the previous spec, like generators or custom icons.

Then the updated spec must be submitted as a PR to withfig/autocomplete for review. This process introduces a lot of friction, especially in the case where the spec can be updated automatically via introspection.

Proposal

For completion specs that are generated via introspection, we should provide a streamlined workflow that:

• Regenerates the CLI skeleton via introspection
• Runs the merge tool against the old completion spec
• Opens a new PR in withfig/autocomplete.

This workflow must be able to run in CI.

[mschrage]

My 2 cents are that this should implemented as an npm package in withfig/autocomplete-tools.

It could be invoked by running something like:

npx fig-bump-spec-pr --spec fig --executable './build/fig' --framework cobra --github-token XXX

1. This would run ./build/fig completions fig (or the relevant command based on the specified framework) to generate the new skeleton.

2. The old completion spec would be loaded using the value passed in with the --spec flag.

For a first iteration, we could just download the spec from https://raw.githubusercontent.com/withfig/autocomplete/master/src/$SPEC.ts.

3. @fedeci already implemented the merge utility.

4. We can use the octokit-plugin-create-pull-request package to create a PR (forking if necessary).

[brendanfalk]

There are three steps here:

1. Generate the spec
2. Merge the spec into existing spec
3. Push spec to withfig/autocomplete repo OR push to fig cloud

I don't think these necessarily have to be all one massive command...

• Generating the new spec is done by running a command from the CLI tool (e.g. my-cli genFigSpec)
• Merging the spec is done through a command that Federico has already created
• Personally, I think pushing the spec should just be it's own command, should be really simple.
  • All we need is 1. the new spec, 2 the spec we should update, and 3. some unique identifier that says we trust the creator of the PR.

However, rather than trying to imagine the optimal workflow ourselves, I propose we speak to our users and build a system that works best for them!

• @EvanBacon at Expo
• @kailan at Fastly
• @simoncrypta at Redwood
• @rberrelleza at Okteto

Do you guys have any thoughts here?

Our aim is to make it as easy as possible to keep Fig's completion spec in sync with your CLI tool and have the right spec distributed to users.

[kailan]

Hey @mschrage and @brendanfalk, hope you both had a great holiday! Thanks for tagging me here.

I think it's unlikely that these automatic generators would be part of the CLI tools themselves (imagine fastly genFigSpec). I was able to build and ship figly so quickly because I was able to build it separately from the CLI, which has its own product needs. I'm not sure a pull request to support a proprietary tool would go down well in every open CLI repo.

If the fastly.ts script in autocomplete were to incorporate the logic from figly, then fig could call this script and re-generate the completions either on a schedule or automatically when it notices the fastly binary has changed. This way, CLIs that export their commands (fastly help --format=json) can be supported by anyone who wants to write a translator for Fig.

[RinkiyaKeDad]

Hey folks! Speaking for Okteto CLI, this would be very helpful for us. The ideal solution for us would be some sort of automated process (GitHub action maybe?) which would generate the spec for each new Okteto CLI release and create a PR to withfig/autocomplete, which we can edit if needed. Thanks for working on this!

[fedeci]

I'm working on a gh action in these days!