feat: shell completions

Author: lucatume

README.md

@@ -20,6 +20,7 @@ The slic (**S**tellarWP **L**ocal **I**nteractive **C**ontainers) CLI command pr
 * [Advanced topics](#advanced-topics)
     * [Defaults for your project with `slic.json`](/docs/slicjson.md)
     * [Managing PHP Versions](#managing-php-versions)
+    * [Shell Completion](#shell-completion)
     * [Making composer installs faster](#making-composer-installs-faster)
     * [Changing your composer version](#changing-your-composer-version)
     * [Customizing `slic`'s `.env` file](#customizing-slics-env-file)
@@ -844,6 +845,98 @@ To reset slic to the default PHP version (7.4):
 slic php-version reset
 ```
 
+### Shell Completion
+
+`slic` provides tab completion for bash, zsh, and fish shells. This makes it faster to use `slic` by allowing you to press Tab to autocomplete commands, targets, branches, and options.
+
+#### Quick Installation
+
+The easiest way to set up completions is:
+
+```bash
+slic completion install
+```
+
+This auto-detects your shell and installs the appropriate completion script. You'll be prompted to confirm before any files are modified.
+
+#### What Gets Completed
+
+Once installed, you can tab-complete:
+
+- **Commands**: `slic <TAB>` shows all available commands
+- **Targets**: `slic use <TAB>` shows all valid plugins/themes
+- **Subcommands**: `slic stack <TAB>` shows `list`, `stop`, `info`
+- **Git branches**: `slic worktree add <TAB>` shows available branches
+- **Stack paths**: `slic --stack=<TAB>` shows registered stack paths
+- **Toggle options**: `slic xdebug <TAB>` shows `on`, `off`, `status`, etc.
+- **PHP versions**: `slic php-version set <TAB>` shows `7.4`, `8.0`, `8.1`, `8.2`, `8.3`
+
+#### Manual Installation
+
+If you prefer manual installation or the automatic installation doesn't work:
+
+**Bash** - Add to `~/.bashrc` or `~/.bash_profile`:
+
+```bash
+# slic completions
+if command -v slic &> /dev/null; then
+    _slic_path=$(command -v slic)
+    if [[ -L "$_slic_path" ]]; then
+        _slic_path=$(realpath "$_slic_path" 2>/dev/null || readlink -f "$_slic_path" 2>/dev/null || readlink "$_slic_path")
+    fi
+    source "$(dirname "$_slic_path")/completions/bash/slic.bash"
+    unset _slic_path
+fi
+```
+
+**Zsh** - Add to `~/.zshrc`:
+
+```zsh
+# slic completions
+if command -v slic &> /dev/null; then
+    _slic_path=$(command -v slic)
+    if [[ -L "$_slic_path" ]]; then
+        _slic_path=$(realpath "$_slic_path" 2>/dev/null || readlink -f "$_slic_path" 2>/dev/null || readlink "$_slic_path")
+    fi
+    fpath=("$(dirname "$_slic_path")/completions/zsh" $fpath)
+    autoload -Uz compinit && compinit
+    unset _slic_path
+fi
+```
+
+**Fish** - Create a symlink:
+
+```fish
+mkdir -p ~/.config/fish/completions
+ln -sf /path/to/slic/completions/fish/slic.fish ~/.config/fish/completions/slic.fish
+```
+
+#### Other Completion Commands
+
+```bash
+# Show installation instructions for your shell
+slic completion
+
+# Display the completion script content (for inspection or manual setup)
+slic completion show [bash|zsh|fish]
+
+# Clear the completion cache (useful if completions seem stale)
+slic completion cache-clear
+```
+
+#### How It Works
+
+The completion system uses a two-layer architecture:
+
+1. **Shell scripts** (bash/zsh/fish) - Thin wrappers that capture the command line context
+2. **PHP backend** - Generates completions dynamically based on your slic configuration
+
+Completions are cached for performance:
+- Commands list: 24 hours
+- Targets: 5 minutes
+- Git branches: 2 minutes
+- Stack paths: 1 minute
+
 ### Making composer installs faster
 
 By default, `slic` caches composer dependencies within the container

changelog.md

@@ -9,25 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Breaking Change - The `slic here` command will now create a new stack for the current path instead of changing the context of the previously only stack to the path.
 - Breaking Change - The `XDK` configuration variable (`slic` by default) is now used as **root** for each stack IDE key. An `XDK` of `slic` will create stack IDE keys like `slic_<stack_hash>` and not just `slic` as it was before.
+- Extend `-y, --yes` flag support for all commands that might require confirmation
 
 ### Added
-- Multi-path support with a 1:1 mapping between stacks and paths.
-- Interactive Terminal User Interface (TUI) for the `slic use` command. Running `slic use` without arguments now opens an interactive selection menu with fuzzy search and current selection indicator.
+- Multiple, isolated Docker Compose projects per path 
 - Git worktree multi-stack support for concurrent development workflows
-- New `slic worktree` command with subcommands:
-  - `slic worktree add <branch>` - Create a new git worktree with dedicated stack
-  - `slic worktree list` - List all worktrees and their stacks
-  - `slic worktree remove <branch>` - Remove a worktree and its stack
-  - `slic worktree sync` - Synchronize git worktrees with slic registry
-- Automatic worktree detection and registration prompts
-- Isolated Docker Compose projects per worktree with unique XDebug ports
-- Worktree-specific environment variables (SLIC_IS_WORKTREE, SLIC_WORKTREE_FULL_PATH, SLIC_WORKTREE_CONTAINER_PATH)
-- `slic stack list` command to display all registered stacks with their status, target paths, and ports
-- `slic stack stop [<stack>]` command to stop a specific stack. If no stack is provided and multiple exist, prompts user to choose one
-- `slic stack stop all` command to stop all registered stacks at once. Always prompts for confirmation, shows list of stacks being stopped, continues even if one stack fails, and displays comprehensive summary with success/failure counts. Works from any directory
-- `slic stack info [<stack>]` command to display detailed information about a specific stack including container status, ports, and configuration
-- Global `--stack=<path>` flag to target specific stacks. This allows running commands against any registered stack without changing the current working directory
-- `-y, --yes` flag support for `slic stack stop all` command to skip confirmation prompt, enabling use in non-interactive environments like CI pipelines and automation scripts
+- New `slic worktree` command leveraging dedicated stacks for each worktree
+- Interactive Terminal User Interface (TUI) for the `slic use` command. Running `slic use` without arguments now opens an interactive selection menu with fuzzy search and current selection indicator.
+- New `slic completion` command with subcommands to install bash/zsh/fish completions
+- Shell completion support for bash, zsh, and fish shells with dynamic completions for commands, targets, git branches, stack paths, and options
 
 # [2.1.2] - 2025-11-13
 - Change - GitHub Actions workflows now use native ARM64 runners (`ubuntu-24.04-arm`) instead of QEMU emulation for multi-platform builds, to reduce build times.

completions/bash/slic.bash

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Bash completion script for slic
+#
+# This script provides tab completion for the slic CLI tool.
+# It delegates completion generation to a PHP script.
+#
+# Installation:
+#   Add this to ~/.bashrc or ~/.bash_profile:
+#   source /path/to/slic/completions/bash/slic.bash
+#
+# Or use: slic completion install bash
+
+_slic_completions() {
+    local cur prev words cword
+    _init_completion || return
+
+    # Get the directory where slic is installed
+    local slic_cmd
+    slic_cmd=$(command -v slic 2>/dev/null)
+
+    if [[ -z "$slic_cmd" ]]; then
+        return 0
+    fi
+
+    # Resolve symlinks to get the actual slic directory
+    if [[ -L "$slic_cmd" ]]; then
+        # Try realpath first (more portable), then readlink -f (GNU), then readlink (basic)
+        slic_cmd=$(realpath "$slic_cmd" 2>/dev/null || readlink -f "$slic_cmd" 2>/dev/null || readlink "$slic_cmd" 2>/dev/null)
+    fi
+
+    local slic_dir
+    slic_dir=$(dirname "$slic_cmd")
+
+    # Call the PHP completion script
+    local completions
+    completions=$(php "${slic_dir}/src/completions/complete.php" \
+        --line="${COMP_LINE}" \
+        --point="${COMP_POINT}" \
+        --words="${COMP_WORDS[*]}" \
+        --cword="${COMP_CWORD}" 2>/dev/null)
+
+    # Convert space-separated completions to array
+    if [[ -n "$completions" ]]; then
+        COMPREPLY=($(compgen -W "$completions" -- "$cur"))
+    fi
+}
+
+# Register the completion function for slic
+complete -F _slic_completions slic

completions/fish/slic.fish

@@ -0,0 +1,41 @@
+# Fish completion script for slic
+#
+# This script provides tab completion for the slic CLI tool.
+# It delegates completion generation to a PHP script.
+#
+# Installation:
+#   Copy or symlink this file to ~/.config/fish/completions/slic.fish
+#   Or use: slic completion install fish
+
+function __slic_completions
+    # Find the slic command
+    set -l slic_cmd (command -v slic 2>/dev/null)
+
+    if test -z "$slic_cmd"
+        return 0
+    end
+
+    # Resolve symlinks to get the actual slic directory
+    if test -L "$slic_cmd"
+        set slic_cmd (realpath "$slic_cmd" 2>/dev/null; or readlink -f "$slic_cmd" 2>/dev/null; or readlink "$slic_cmd" 2>/dev/null)
+    end
+
+    set -l slic_dir (dirname "$slic_cmd")
+
+    # Get the current command line tokens (already completed)
+    set -l tokens (commandline -opc)
+
+    # Get the current token being typed
+    set -l current (commandline -ct)
+
+    # Call the PHP completion script
+    php "$slic_dir/src/completions/complete.php" \
+        --shell=fish \
+        --words="$tokens" \
+        --current="$current" 2>/dev/null
+end
+
+# Register completions for slic command
+# -f: don't complete files
+# -a: provide completions from the function
+complete -c slic -f -a "(__slic_completions)"

completions/zsh/_slic

@@ -0,0 +1,65 @@
+#compdef slic
+# Zsh completion script for slic
+#
+# This script provides tab completion for the slic CLI tool.
+# It delegates completion generation to a PHP script.
+#
+# Installation:
+#   Add this to ~/.zshrc:
+#   fpath=(/path/to/slic/completions/zsh $fpath)
+#   autoload -Uz compinit && compinit
+#
+# Or use: slic completion install zsh
+
+_slic() {
+    local slic_cmd slic_dir completions
+
+    # Find the slic command
+    slic_cmd=$(command -v slic 2>/dev/null)
+
+    if [[ -z "$slic_cmd" ]]; then
+        return 0
+    fi
+
+    # Resolve symlinks to get the actual slic directory
+    if [[ -L "$slic_cmd" ]]; then
+        # macOS uses readlink differently than GNU
+        if [[ "$OSTYPE" == "darwin"* ]]; then
+            # On macOS, try to use greadlink if available, otherwise use a while loop
+            if command -v greadlink >/dev/null 2>&1; then
+                slic_cmd=$(greadlink -f "$slic_cmd")
+            else
+                # Follow symlinks manually with protection against circular links
+                local iterations=0
+                local max_iterations=10
+                while [[ -L "$slic_cmd" ]] && (( iterations < max_iterations )); do
+                    local link_target
+                    link_target=$(readlink "$slic_cmd")
+                    if [[ "$link_target" == /* ]]; then
+                        slic_cmd="$link_target"
+                    else
+                        slic_cmd="$(dirname "$slic_cmd")/$link_target"
+                    fi
+                    (( iterations++ ))
+                done
+            fi
+        else
+            slic_cmd=$(readlink -f "$slic_cmd" 2>/dev/null)
+        fi
+    fi
+
+    slic_dir=$(dirname "$slic_cmd")
+
+    # Call the PHP completion script
+    completions=($(php "${slic_dir}/src/completions/complete.php" \
+        --line="${BUFFER}" \
+        --point="${CURSOR}" \
+        --words="${words[*]}" \
+        --cword="${CURRENT}" 2>/dev/null))
+
+    if [[ ${#completions[@]} -gt 0 ]]; then
+        _describe 'slic commands' completions
+    fi
+}
+
+_slic "$@"