Shell Completions

Shell Completions

Shell completions in Numan provide command-line productivity by generating scripts that enable tab-completion for subcommands and flags across various shell environments. This feature was implemented as part of the Phase 7 "Polish, CI, Distribution" milestone to enhance the daily-driver experience of the CLI.

The system leverages clap_complete to derive completion logic directly from the central Cli definition, ensuring that all available commands—such as init, install, activate, and nupm—are accurately represented in the generated output.

Architecture and Implementation

Numan uses a declarative approach to completion generation. The architecture relies on the clap derive macros defined in src/cli.rs, which provide the metadata required for the generation engine.

Core Components

Component	Responsibility
Cli / Commands	The central command definition in src/cli.rs used as the source of truth for all metadata.
src/cmd/completions.rs	The subcommand handler that processes the user's requested shell and prints the script to stdout.
clap_complete	The underlying library that translates the Cli structure into shell-specific syntax.

Generation Logic Flow

The generation process starts with a user invoking the numan completions <shell> command. The CLI identifies the target shell and utilizes the Cli::command() factory to generate the script.

flowchart TD
    User[User Input] --> CMD[numan completions shell]
    CMD --> Handler[completions::execute]
    Handler --> Factory[Cli::command]
    Factory --> Gen[clap_complete::generate]
    Gen --> Output[STDOUT / Shell Script]
    Output --> Disk[Redirect to File]

Loading

The workflow for completion generation involves mapping the high-level Cli definition to a specific Shell variant and writing the resulting bytes to the standard output stream.

Supported Shells and Installation

Numan supports the major shell environments used across Linux, macOS, and Windows. Users typically redirect the command output to a specific file in their shell's completion directory.

Installation Commands

Shell	Command to Install
Bash	numan completions bash > ~/.local/share/bash-completion/completions/numan
Zsh	numan completions zsh > ~/.zfunc/_numan
Fish	numan completions fish > ~/.config/fish/completions/numan.fish
PowerShell	numan completions powershell | Out-File -Encoding utf8 $PROFILE

Implementation Example

The execute function in the completions module demonstrates how the Shell variant is used to generate output.

pub fn execute(shell: Shell) -> Result<()> {
    let mut cmd = Cli::command();
    let name = "numan";
    generate(shell, &mut cmd, name, &mut std::io::stdout());
    Ok(())
}

Validation and Testing

The integrity of generated completions is verified through integration tests that ensure all core subcommands are present in the output. The test suite validates that the scripts are non-empty and contain key command strings.

Completion Verification Test

#[test]
fn bash_completions_include_core_commands() {
    let mut cmd = Cli::command();
    let mut buf = Vec::new();
    generate(Shell::Bash, &mut cmd, "numan", &mut buf);
    let script = String::from_utf8(buf).expect("valid utf-8");
    for needle in [
        "numan",
        "init",
        "install",
        "activate",
        "completions",
        "nupm",
    ] {
        assert!(
            script.contains(needle),
            "bash completion script missing '{needle}'"
        );
    }
}

Summary

Shell completions are a critical part of Numan's distribution and polish phase. By integrating directly with the Cli parser, Numan ensures that the shell-side experience remains in sync with the actual binary capabilities, covering everything from basic package installation to complex nupm interoperability commands.