completion 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 284727bae15655feaebf3d8757241257db50b763122a31cadc654d5319d7a2bf
+  data.tar.gz: e3e0ec43c86bcbc334cba971bfe019bd822c3a64ed03577cfc0a6a804d9a0834
+SHA512:
+  metadata.gz: 29ebeaf86a358ff8dd761326b06f7d718e9919f80c2b0d1d2a359d103032ef081101da49a46ac6808915703a8f30d8b06508c3e07ca65b7690414e9d8eab6ed4
+  data.tar.gz: 071a5afaffb9ee016b327434b7d87d19d57d8b0e1ae81cf823ca0b1aea0a66b26b2396f0177c992ece283bf4b31f97b4fbad1cebbb7911994cd6f0245ba83d38

checksums.yaml.gz.sig

@@ -0,0 +1 @@
+�0�6�[�cJgTL\��-gˆN���g���17�k(�Ƭ��^?����P�=�p�5o���c���8�s�(n��}X�:�w)�9�����+��MMk��];f]_G�L�n���}9G>T�Gzl3c�H���[z

data/bin/completion

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../lib/completion/command"
+
+Completion::Command.call

data/bin/completion-completion

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../lib/completion/command"
+
+Completion::Command.complete

data/guides/getting-started/readme.md

@@ -0,0 +1,161 @@
+# Getting Started
+
+This guide explains how to install and use `completion` to add shell completion adapters for command-line tools.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add completion
+~~~
+
+Or install it yourself as:
+
+~~~ bash
+$ gem install completion
+~~~
+
+The command line executable is named `completion`:
+
+~~~ bash
+$ completion --help
+~~~
+
+## Core Concepts
+
+`completion` installs shell adapter scripts. The adapters do not run the command being completed. Instead, they call a dedicated completion executable named `completion-<command>`.
+
+For example, a command named `falcon` should provide:
+
+~~~ text
+falcon
+completion-falcon
+~~~
+
+When the shell asks for completions for `falcon`, the installed adapter calls `completion-falcon` with the command-line arguments up to the cursor.
+
+This convention also works for commands invoked by path:
+
+~~~ text
+falcon          -> completion-falcon
+bin/falcon      -> bin/completion-falcon
+./bin/falcon    -> ./bin/completion-falcon
+/path/falcon    -> /path/completion-falcon
+~~~
+
+## Installing a Generic Adapter
+
+Install a generic adapter for the current shell:
+
+~~~ bash
+$ completion install
+~~~
+
+The shell is detected from `ENV["SHELL"]`. The generic adapter checks whether a matching `completion-<command>` executable exists before handling completion for a command.
+
+You can specify the shell explicitly:
+
+~~~ bash
+$ completion install --shell fish
+~~~
+
+Supported shells are:
+
+- `bash`
+- `fish`
+- `zsh`
+
+## Installing a Command Adapter
+
+Install an adapter for a specific command:
+
+~~~ bash
+$ completion install --command falcon
+~~~
+
+This installs completion support only for `falcon`.
+
+You can specify the shell and adapter directory explicitly:
+
+~~~ bash
+$ completion install --shell zsh --directory ~/.zsh/completions --command falcon
+~~~
+
+## Installed Files
+
+Installation writes a small adapter script and shared shell helpers.
+
+For Bash and Zsh, shared helpers are installed in the completion directory:
+
+~~~ text
+completion.bash
+completion.zsh
+~~~
+
+For Fish, shared helpers are installed as autoloaded functions:
+
+~~~ text
+~/.config/fish/functions/__completion_complete.fish
+~/.config/fish/functions/__completion_register.fish
+~/.config/fish/functions/__completion_register_default.fish
+~/.config/fish/functions/__completion_resolve.fish
+~/.config/fish/functions/__completion_supported.fish
+~~~
+
+Fish command adapters are installed into:
+
+~~~ text
+~/.config/fish/completions
+~~~
+
+## Generating an Adapter
+
+You can generate an adapter script without installing it:
+
+~~~ bash
+$ completion generate --shell zsh --command falcon
+~~~
+
+Omit `--command` to generate the generic adapter:
+
+~~~ bash
+$ completion generate --shell zsh
+~~~
+
+## Providing a Completion Executable
+
+The completion executable should print completion candidates to standard output.
+
+Commands built with `samovar` can use `Command.complete`:
+
+~~~ ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/my/application"
+
+My::Application.complete
+~~~
+
+Completion candidates use tab-separated fields:
+
+~~~ text
+type	value	description	key=value
+~~~
+
+The first three fields are always the completion type, value, and description. Additional fields are optional metadata entries.
+
+## Testing
+
+You can test the completion executable directly:
+
+~~~ bash
+$ completion-falcon ""
+~~~
+
+You can also generate an adapter and inspect it:
+
+~~~ bash
+$ completion generate --shell fish --command falcon
+~~~

data/lib/completion/command/generate.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "samovar"
+
+require_relative "../shell"
+require_relative "../shell/bash"
+require_relative "../shell/fish"
+require_relative "../shell/zsh"
+
+module Completion
+	module Command
+		# Generate shell completion adapter scripts.
+		class Generate < Samovar::Command
+			self.description = "Generate shell completion adapter scripts."
+			
+			options do
+				option "--shell <name>", "The shell to generate completions for.", default: Shell.method(:default_shell), completions: ["bash", "zsh", "fish"]
+				option "--command <name>", "The command executable to complete."
+			end
+			
+			# Print the generated shell adapter script.
+			# 
+			# @returns [void]
+			def call
+				output.puts Shell.script(shell: @options[:shell], executable: @options[:command])
+			end
+		end
+	end
+end

data/lib/completion/command/install.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "fileutils"
+require "samovar"
+
+require_relative "../shell"
+require_relative "../shell/bash"
+require_relative "../shell/fish"
+require_relative "../shell/zsh"
+
+module Completion
+	module Command
+		# Install a shell completion adapter script to a user-local completion directory.
+		class Install < Samovar::Command
+			self.description = "Install a shell completion adapter script."
+			
+			options do
+				option "--shell <name>", "The shell to install completions for.", default: Shell.method(:default_shell), completions: ["bash", "zsh", "fish"]
+				option "--directory <path>", "The completion directory to install into."
+				option "--command <name>", "The command executable to complete."
+			end
+			
+			# Install the generated shell adapter script.
+			# 
+			# @returns [void]
+			def call
+				shell = @options[:shell]
+				directory = @options[:directory] || Shell.default_directory(shell)
+				path = File.join(directory, Shell.file_name(shell, @options[:command]))
+				script = Shell.script(shell: shell, executable: @options[:command])
+				
+				FileUtils.mkdir_p(directory)
+				shared_paths = install_shared(shell, directory)
+				File.write(path, script)
+				
+				output.puts(shared_paths)
+				output.puts path
+			end
+			
+			private
+			
+			def install_shared(shell, directory)
+				if shell == "fish"
+					return install_fish_function(Shell.default_function_directory)
+				end
+				
+				shared_path = File.join(directory, Shell.shared_file_name(shell))
+				
+				File.write(shared_path, Shell.shared_script(shell: shell))
+				
+				return [shared_path]
+			end
+			
+			def install_fish_function(directory)
+				FileUtils.mkdir_p(directory)
+				
+				return Shell::Fish.shared_functions.collect do |file_name, script|
+					path = File.join(directory, file_name)
+					File.write(path, script)
+					path
+				end
+			end
+		end
+	end
+end

data/lib/completion/command/top.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "samovar"
+
+unless defined?(Completion::Command) && Completion::Command.respond_to?(:call)
+	require_relative "../command"
+end
+
+require_relative "generate"
+require_relative "install"
+
+module Completion
+	module Command
+		# The completion command-line interface.
+		class Top < Samovar::Command
+			self.description = "Install and generate shell completion adapter scripts."
+			
+			options do
+				option "-h/--help", "Print out help information."
+			end
+			
+			nested :command, {
+				"install" => Install,
+				"generate" => Generate,
+			}, default: "generate"
+			
+			# Execute the selected completion sub-command.
+			# 
+			# @returns [Object | Nil] The sub-command result.
+			def call
+				if @options[:help]
+					self.print_usage
+				else
+					@command.call
+				end
+			end
+		end
+	end
+end

data/lib/completion/command.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Completion
+	# Command-line entry points for the completion executable.
+	module Command
+		# Parse and execute the top-level completion command.
+		# 
+		# @parameter arguments [Array] The arguments to forward to the top-level command.
+		# @returns [Object | Nil] The command result.
+		def self.call(...)
+			Top.call(...)
+		end
+		
+		# Complete the top-level completion command.
+		# 
+		# @parameter arguments [Array] The arguments to forward to the top-level command.
+		# @returns [Samovar::Completion::Result] The completion result.
+		def self.complete(...)
+			Top.complete(...)
+		end
+	end
+end
+
+require_relative "command/top"

data/lib/completion/shell/bash.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Completion
+	module Shell
+		# Bash completion adapter generation.
+		module Bash
+			# Generate a Bash completion adapter script.
+			# 
+			# @parameter executable [String | Nil] The command executable, or nil for the generic adapter.
+			# @returns [String] The generated Bash script.
+			def self.script(executable)
+				command = Shell.command_name(executable)
+				
+				if executable
+					return <<~SCRIPT
+						_completion_source="${BASH_SOURCE[0]}"
+						if [[ "$_completion_source" == */* ]]; then
+							_completion_directory="${_completion_source%/*}"
+						else
+							_completion_directory="."
+						fi
+						source "${_completion_directory}/completion.bash"
+						__completion_register #{command}
+					SCRIPT
+				end
+				
+				<<~SCRIPT
+					_completion_source="${BASH_SOURCE[0]}"
+					if [[ "$_completion_source" == */* ]]; then
+						_completion_directory="${_completion_source%/*}"
+					else
+						_completion_directory="."
+					fi
+					source "${_completion_directory}/completion.bash"
+					__completion_register_default
+				SCRIPT
+			end
+			
+			# Generate the shared Bash helper script.
+			# 
+			# @returns [String] The generated Bash helper script.
+			def self.shared_script
+				<<~SCRIPT
+					__completion_resolve() {
+						local command="$1"
+						local basename="${command##*/}"
+						
+						if [[ "$command" == */* ]]; then
+							printf "%s\\n" "${command%/*}/completion-${basename}"
+						else
+							printf "%s\\n" "completion-${basename}"
+						fi
+					}
+					
+					__completion_complete() {
+						local command="${COMP_WORDS[0]}"
+						local completer="$(__completion_resolve "$command")"
+						
+						[[ -x "$completer" ]] || return 0
+						
+						local argv=("${COMP_WORDS[@]:1:COMP_CWORD}")
+						COMPREPLY=()
+						
+						while IFS=$'\\t' read -r type value description metadata; do
+							case "$type" in
+								path)
+									while IFS= read -r completion; do
+										COMPREPLY+=("$completion")
+									done < <(compgen -f -- "$value")
+									;;
+								directory)
+									while IFS= read -r completion; do
+										COMPREPLY+=("$completion")
+									done < <(compgen -d -- "$value")
+									;;
+								executable)
+									while IFS= read -r completion; do
+										COMPREPLY+=("$completion")
+									done < <(compgen -c -- "$value")
+									;;
+								delegate)
+									if [[ "$metadata" == *index=* ]]; then
+										local index="${metadata##*index=}"
+										index="${index%%$'\\t'*}"
+										local offset=$((index + 1))
+										COMP_WORDS=("${COMP_WORDS[@]:$offset}")
+										COMP_CWORD=$((COMP_CWORD - offset))
+										
+										if declare -F _completion_loader >/dev/null; then
+											_completion_loader "${COMP_WORDS[0]}" >/dev/null 2>&1 || true
+										fi
+										
+										local specification
+										specification="$(complete -p "${COMP_WORDS[0]}" 2>/dev/null || true)"
+										
+										if [[ "$specification" =~ -F[[:space:]]+([^[:space:]]+) ]]; then
+											"${BASH_REMATCH[1]}"
+										fi
+									fi
+									;;
+								*)
+									COMPREPLY+=("$value")
+									;;
+							esac
+						done < <("$completer" "${argv[@]}")
+					}
+					
+					__completion_register() {
+						complete -F __completion_complete "$1"
+					}
+					
+					__completion_register_default() {
+						complete -D -o bashdefault -o default -F __completion_complete 2>/dev/null || true
+					}
+				SCRIPT
+			end
+		end
+	end
+end

data/lib/completion/shell/fish.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Completion
+	module Shell
+		# Fish completion adapter generation.
+		module Fish
+			# Generate a Fish completion adapter script.
+			# 
+			# @parameter executable [String | Nil] The command executable, or nil for the generic adapter.
+			# @returns [String] The generated Fish script.
+			def self.script(executable)
+				command = Shell.command_name(executable)
+				
+				if executable
+					return <<~SCRIPT
+						__completion_register #{command}
+					SCRIPT
+				end
+				
+				<<~SCRIPT
+					__completion_register_default
+				SCRIPT
+			end
+			
+			# Get the shared Fish helper function files.
+			# 
+			# @returns [Hash] The helper file names and scripts.
+			def self.shared_functions
+				{
+					"__completion_complete.fish" => complete_function,
+					"__completion_register.fish" => register_function,
+					"__completion_register_default.fish" => register_default_function,
+					"__completion_resolve.fish" => resolve_function,
+					"__completion_supported.fish" => supported_function,
+				}
+			end
+			
+			# Generate the Fish completion function.
+			# 
+			# @returns [String] The generated Fish function script.
+			def self.complete_function
+				<<~SCRIPT
+					function __completion_complete --description 'Complete commands with adjacent completion executables'
+						set -l argv (commandline -opc)
+						set -e argv[1]
+						set -l current (commandline -ct)
+						
+						if test -n "$current"
+							set -a argv $current
+						else
+							set -a argv ""
+						end
+						
+						set -l completer (__completion_resolve)
+						$completer $argv | while read -l line
+							set -l fields (string split (printf "\\t") -- $line)
+							set -l type $fields[1]
+							set -l value $fields[2]
+							set -l description $fields[3]
+							set -l metadata $fields[4..-1]
+							
+							switch "$type"
+								case path
+									__fish_complete_path "$value"
+								case directory
+									__fish_complete_directories "$value"
+								case executable
+									complete -C "$value"
+								case delegate
+									set -l index
+									for field in $metadata
+										switch "$field"
+											case "index=*"
+												set index (string replace "index=" "" -- "$field")
+										end
+									end
+									
+									if test -n "$index"
+										set -l start (math $index + 1)
+										set -l delegated $argv[$start..-1]
+										complete -C (string join " " -- (string escape -- $delegated))
+									end
+								case "*"
+									echo "$value	$description"
+							end
+						end
+					end
+				SCRIPT
+			end
+			
+			# Generate the Fish command registration function.
+			# 
+			# @returns [String] The generated Fish function script.
+			def self.register_function
+				<<~SCRIPT
+					function __completion_register --description 'Register command completion'
+						complete -c $argv[1] -f -a "(__completion_complete)"
+					end
+				SCRIPT
+			end
+			
+			# Generate the Fish generic registration function.
+			# 
+			# @returns [String] The generated Fish function script.
+			def self.register_default_function
+				<<~SCRIPT
+					function __completion_register_default --description 'Register generic completion'
+						complete -c "*" -n "__completion_supported" -f -a "(__completion_complete)"
+					end
+				SCRIPT
+			end
+			
+			# Generate the Fish completion command resolver function.
+			# 
+			# @returns [String] The generated Fish function script.
+			def self.resolve_function
+				<<~SCRIPT
+					function __completion_resolve --description 'Resolve completion command'
+						set -l argv (commandline -opc)
+						set -l command $argv[1]
+						set -l basename (basename "$command")
+						
+						if string match -q "*/*" "$command"
+							echo (dirname "$command")/completion-$basename
+						else
+							echo completion-$basename
+						end
+					end
+				SCRIPT
+			end
+			
+			# Generate the Fish support detection function.
+			# 
+			# @returns [String] The generated Fish function script.
+			def self.supported_function
+				<<~SCRIPT
+					function __completion_supported --description 'Check completion support'
+						set -l completer (__completion_resolve)
+						test -x "$completer"
+					end
+				SCRIPT
+			end
+		end
+	end
+end

data/lib/completion/shell/zsh.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Completion
+	module Shell
+		# Zsh completion adapter generation.
+		module Zsh
+			# Generate a Zsh completion adapter script.
+			# 
+			# @parameter executable [String | Nil] The command executable, or nil for the generic adapter.
+			# @returns [String] The generated Zsh script.
+			def self.script(executable)
+				command = Shell.command_name(executable)
+				
+				if executable
+					return <<~SCRIPT
+						#compdef #{command}
+						
+						local _completion_source="${(%):-%x}"
+						local _completion_directory="${_completion_source:h}"
+						source "${_completion_directory}/completion.zsh"
+						__completion_complete "$@"
+					SCRIPT
+				end
+				
+				<<~SCRIPT
+					#compdef -default-
+					
+					local _completion_source="${(%):-%x}"
+					local _completion_directory="${_completion_source:h}"
+					source "${_completion_directory}/completion.zsh"
+					__completion_register_default
+					__completion_complete default "$@"
+				SCRIPT
+			end
+			
+			# Generate the shared Zsh helper script.
+			# 
+			# @returns [String] The generated Zsh helper script.
+			def self.shared_script
+				<<~SCRIPT
+					__completion_resolve() {
+						local command="$1"
+						local basename="${command:t}"
+						
+						if [[ "$command" == */* ]]; then
+							printf "%s\\n" "${command:h}/completion-${basename}"
+						else
+							printf "%s\\n" "completion-${basename}"
+						fi
+					}
+					
+					__completion_complete() {
+						local fallback="$1"
+						if [[ "$fallback" == "default" ]]; then
+							shift
+						else
+							fallback=""
+						fi
+						
+						local command="${words[1]}"
+						local completer="$(__completion_resolve "$command")"
+						
+						if [[ ! -x "$completer" ]]; then
+							if [[ "$fallback" == "default" ]]; then
+								_default "$@"
+							fi
+							
+							return
+						fi
+						
+						local -a argv
+						argv=("${(@)words[2,CURRENT]}")
+						
+						local -a completions
+						local paths=false
+						local directories=false
+						local executables=false
+						while IFS=$'\\t' read -r type value description metadata; do
+							case "$type" in
+								path)
+									paths=true
+									;;
+								directory)
+									directories=true
+									;;
+								executable)
+									executables=true
+									;;
+								delegate)
+									if [[ "$metadata" == *index=* ]]; then
+										local index="${metadata##*index=}"
+										index="${index%%$'\\t'*}"
+										words=("${(@)words[$((index + 2)),-1]}")
+										CURRENT=$((CURRENT - index - 1))
+										_normal
+										return
+									fi
+									;;
+								*)
+									completions+=("${value}:${description}")
+									;;
+							esac
+						done < <("$completer" "${argv[@]}")
+						
+						if [[ "$paths" == true ]]; then
+							_path_files
+						fi
+						
+						if [[ "$directories" == true ]]; then
+							_files -/
+						fi
+						
+						if [[ "$executables" == true ]]; then
+							_path_commands
+						fi
+						
+						_describe 'completion' completions
+					}
+					
+					__completion_register_default() {
+						(( $+functions[compdef] )) && compdef _completion -default-
+					}
+				SCRIPT
+			end
+		end
+	end
+end

data/lib/completion/shell.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Completion
+	# Shell adapter generation helpers.
+	module Shell
+		# Extract a shell name from a path.
+		# 
+		# @parameter path [String | Nil] The shell path.
+		# @returns [String] The shell name.
+		def self.shell_name(path)
+			File.basename(path.to_s)
+		end
+		
+		# Detect the current shell from the environment.
+		# 
+		# @returns [String] The detected shell name.
+		def self.default_shell
+			shell_name(ENV["SHELL"])
+		end
+		
+		# Get the default completion directory for a shell.
+		# 
+		# @parameter shell [String] The shell name.
+		# @returns [String] The default completion directory.
+		def self.default_directory(shell)
+			case shell
+			when "bash"
+				File.expand_path("~/.local/share/bash-completion/completions")
+			when "fish"
+				File.expand_path("~/.config/fish/completions")
+			when "zsh"
+				File.expand_path("~/.zsh/completions")
+			else
+				raise ArgumentError, "Unsupported shell: #{shell.inspect}"
+			end
+		end
+		
+		# Get the default Fish function directory.
+		# 
+		# @returns [String] The default Fish function directory.
+		def self.default_function_directory
+			File.expand_path("~/.config/fish/functions")
+		end
+		
+		# Get the installed adapter file name for a shell.
+		# 
+		# @parameter shell [String] The shell name.
+		# @parameter executable [String | Nil] The command executable, or nil for the generic adapter.
+		# @returns [String] The adapter file name.
+		def self.file_name(shell, executable = nil)
+			command = executable || "completion"
+			
+			case shell
+			when "bash"
+				command
+			when "fish"
+				"#{command}.fish"
+			when "zsh"
+				"_#{command}"
+			else
+				raise ArgumentError, "Unsupported shell: #{shell.inspect}"
+			end
+		end
+		
+		# Get the installed shared helper file name for a shell.
+		# 
+		# @parameter shell [String] The shell name.
+		# @returns [String] The shared helper file name.
+		def self.shared_file_name(shell)
+			case shell
+			when "bash"
+				"completion.bash"
+			when "zsh"
+				"completion.zsh"
+			else
+				raise ArgumentError, "Unsupported shell: #{shell.inspect}"
+			end
+		end
+		
+		# Generate a shell adapter script.
+		# 
+		# @parameter shell [String | Symbol] The shell name.
+		# @parameter executable [String | Nil] The command executable, or nil for the generic adapter.
+		# @returns [String] The generated adapter script.
+		def self.script(shell:, executable: nil)
+			case shell.to_sym
+			when :bash
+				Bash.script(executable)
+			when :fish
+				Fish.script(executable)
+			when :zsh
+				Zsh.script(executable)
+			else
+				raise ArgumentError, "Unsupported shell: #{shell.inspect}"
+			end
+		end
+		
+		# Generate a shared shell helper script.
+		# 
+		# @parameter shell [String | Symbol] The shell name.
+		# @returns [String] The generated shared helper script.
+		def self.shared_script(shell:)
+			case shell.to_sym
+			when :bash
+				Bash.shared_script
+			when :zsh
+				Zsh.shared_script
+			else
+				raise ArgumentError, "Unsupported shell: #{shell.inspect}"
+			end
+		end
+		
+		# Get the command name from an executable path.
+		# 
+		# @parameter executable [String | Nil] The executable path, or nil for the generic adapter.
+		# @returns [String] The command name.
+		def self.command_name(executable)
+			File.basename(executable || "completion")
+		end
+	end
+end

data/lib/completion/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Completion
+	VERSION = "0.0.1"
+end

data/lib/completion.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "completion/version"
+require_relative "completion/shell"
+require_relative "completion/shell/bash"
+require_relative "completion/shell/fish"
+require_relative "completion/shell/zsh"
+
+# Shell completion adapter generation and installation.
+module Completion
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2026, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,63 @@
+# Completion
+
+Completion installs shell adapter scripts for command-line tools which expose a dedicated completion executable. It provides small per-command or generic shell shims, plus shared shell helpers for Bash, Fish, and Zsh.
+
+[![Development Status](https://github.com/socketry/completion/workflows/Test/badge.svg)](https://github.com/socketry/completion/actions?workflow=Test)
+
+## Motivation
+
+Shell completion is useful, but each shell has different installation paths, script conventions, and interfaces for native path, directory, executable, and delegated completion. This gem provides a small command-line tool for installing those adapters consistently.
+
+The command being completed is expected to provide a companion executable named `completion-<command>`. For example, `falcon` can expose completions using `completion-falcon`. This keeps completion support explicit and avoids running arbitrary commands just to discover whether they support completion.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/completion/) for more details.
+
+  - [Getting Started](https://socketry.github.io/completion/guides/getting-started/index) - This guide explains how to install and use `completion` to add shell completion adapters for command-line tools.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/completion/releases/index) for all releases.
+
+### v0.0.1
+
+  - Initial release.
+
+## See Also
+
+  - [Samovar](https://github.com/socketry/samovar) provides the command completion interface used by Samovar-based commands.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.0.1
+
+  - Initial release.

data.tar.gz.sig

@@ -0,0 +1,3 @@
+R�thbh M��&�o8��x����L��q���|��eD��JK֢������z+H����!�Aw�̫��7�
\p��k��9
+���ӈ4)T�H�!IJ�?�j�|�V���3݃T��qs<�DZ.:^Kk7���ə��#�{,���&�-:_����[E��M��((8ݱ���[�
+Ѡ6�+CN��sy��+���7�]ސ��)��Hׯ�

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: completion
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: samovar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+executables:
+- completion
+- completion-completion
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/completion
+- bin/completion-completion
+- guides/getting-started/readme.md
+- lib/completion.rb
+- lib/completion/command.rb
+- lib/completion/command/generate.rb
+- lib/completion/command/install.rb
+- lib/completion/command/top.rb
+- lib/completion/shell.rb
+- lib/completion/shell/bash.rb
+- lib/completion/shell/fish.rb
+- lib/completion/shell/zsh.rb
+- lib/completion/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/completion
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/completion/
+  source_code_uri: https://github.com/socketry/completion.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Command-line completion adapter installation.
+test_files: []