Skip to content

Refactor completions as native runtime functions - #721

Merged
DannyBen merged 10 commits into
dev-2.0.0from
refactor/completions
Aug 19, 2026
Merged

Refactor completions as native runtime functions#721
DannyBen merged 10 commits into
dev-2.0.0from
refactor/completions

Conversation

@DannyBen

@DannyBen DannyBen commented Aug 18, 2026

Copy link
Copy Markdown
Member

⚠️ This is a breaking change intended for the 2.0.0 release.

cc #657


This PR replaces Bashly's Completely-based completion generation with native runtime completion functions embedded in the generated Bash script.

The generated CLI therefore remains the single source of truth for command, argument, and flag behavior. Shell completion wrappers can remain small and static while automatically reflecting changes made to the CLI.

Philosophy

  1. Follow the runtime completion approach used by Go's Cobra framework.
  2. Optionally generate a hidden yourcli __complete command that returns the valid candidates for an incomplete command line.
  3. Keep shell-specific wrappers small and static. They only pass the shell's completion words to yourcli __complete and consume its response.
  4. Generate or install these wrappers through bashly add completions, starting with Bash and potentially extending to Zsh and Fish.

Advantages

  • The generated script is the single source of truth for both CLI behavior and completion candidates.
  • Completion data no longer needs to be generated and maintained as a separate artifact.
  • Installed shell wrappers automatically reflect CLI changes, without needing to be regenerated or reinstalled.
  • Completion behavior can honor Bashly directives such as conflicts, repeatable values, and allowed values.
  • Completely is no longer required as a runtime dependency.

Disadvantages

  • Generated scripts are larger because they include the runtime completion functions.
  • Each completion request invokes the generated CLI, adding some startup overhead compared with a fully static completion script.

TODO

  • Initial prototype implementation
  • Complete native completion behavior
    • Commands
    • Arguments
    • Flags
  • Establish runtime completion test architecture
  • Remove the Completely integration and dependency
    • Remove bashly completions --install since it needs Completely
  • Add a setting to enable completion generation
    • Update JSON schema
  • Remove bashly add completions in favor of internal native function generation
  • Revisit the completions directive in bashly.yml
  • Examples
  • Complete runtime completion coverage
  • All tests pass
  • Migration guide
  • Documentation

@DannyBen DannyBen added enhancement New feature or request breaking-change This is not backwards compatible labels Aug 18, 2026
@DannyBen DannyBen added this to the 2.0.0 milestone Aug 18, 2026
@DannyBen DannyBen self-assigned this Aug 18, 2026
@DannyBen
DannyBen marked this pull request as ready for review August 19, 2026 10:18
@DannyBen
DannyBen merged commit 751c1f1 into dev-2.0.0 Aug 19, 2026
8 checks passed
@DannyBen
DannyBen deleted the refactor/completions branch August 19, 2026 11:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking-change This is not backwards compatible enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant