feat(auto-complete): add shell script output command

[AmirSa12]

*Issue number of the reported bug or feature request: #137 and #112 *

Describe your changes
adding a script command to @stricli/auto-complete.
The new command prints a shell completion script to stdout instead of installing it directly into a shell configuration file.

Testing performed

simply run node packages/auto-complete/dist/bin/cli.js script --shell zsh --command "my-cli" my-cli
supports zsh, powershell, fish and bash

Additional context
This is intentionally scoped to script generation only. It does not change stricli's completion proposal logic and does not modify @stricli/core and uses @bomb.sh/tab only for shell script generation.

I havent added the install --zsh
let me know what you think @molisani

[molisani]

Correct me if I'm wrong, but the tab script that this generates still assumes that the executable is <command> complete -- [...inputs]¹ right? Stricli apps won't work with that out of the box.

Footnotes

1. bash script source, https://github.com/bombshell-dev/tab/blob/7f664740573b3500e8e4749d21fa7cfff98dd716/src/bash.ts#L45 ↩

[AmirSa12]

@molisani yes, you are right, it does not make existing stricli apps support tab’s <command> complete -- ... protocol automatically, and I added that logic manually in a demo.

What I'm thinking about is an opt-in helper like runWithAutoComplete(app, argv, context) that would intercept the complete -- , and thats to avoid changing anything inside the core package. and then users would print or source the scripts via npx @stricli/auto-complete script --shell zsh

Conceptually, this is what I am trying to do:

import { proposeCompletions, run, type Application } from "@stricli/core";
import { emitCompletions, ShellCompDirective } from "@bomb.sh/tab";

export async function runWithAutoComplete(app, argv, context) {
  if (argv[0] === "complete" && argv[1] === "--") {
    const proposals = await proposeCompletions(app, argv.slice(2), context);

    emitCompletions(
      proposals.map((p) => ({
        value: p.completion,
        description: p.brief,
      })),
      ShellCompDirective.ShellCompDirectiveNoFileComp,
    );

    return;
  }

  await run(app, argv, context);
}

[molisani]

Would it be possible to change or customize the "subcommand" that the tab shell script expects? For example, could it be <command> --complete [...inputs] instead of <command> complete -- [...inputs]?

[AmirSa12]

@molisani That's actually a solid idea. I'm experimenting this. I'll keep you posted.

[AmirSa12]

Okay, I have experimented this, and we are good with custom entry points.
but, how do you think we should approach this? what's the mental model you have in mind? did you suggest that because having, for example, --complete is not part of the app's public route tree here in this case?
I'm happy to push this forward to the finish line.

[molisani]

Conceptually, I like having the commands be entirely application-defined. That still allows for sharing/reusing individual commands (like the current install/uninstall commands from the @stricli/auto-complete package), but by design they're composed before the application itself is fully composed. As a result, a single command can't read in a whole application as input (without forcing some really awkward patterns).

I have a work-in-progress branch to implement "integrations", which rewrites the --help/--version functionality as standalone units that can be customized. While I'm not planning to support --complete on a first pass, I'm designing the API such that it could be implemented as a follow-up. The branch is public, but it's not quite ready for a public PR and I'm still iterating on a few details with my colleagues. It should be ready soon.

[AmirSa12]

that makes sense, I see the issue with modeling this as a normal command now...

so for now, I can keep this PR focused on script output only, which addresses issue number #112. please let me know your thoughts on that and the new script command. users would print the shell script via npx @stricli/auto-complete script --shell zsh.

On the tab side, I can still make the generated completion entrypoint configurable so that way stricli could choose something like --complete. and once the new API is ready, we can continue working on the autocomplete feature in a separate PR if things go well.

would be happy to know your thoughts. thanks!