# Developer Experience

[← Team Workflows](Team-Workflows.md) | [Home](Home.md) | [Configuration Management →](Configuration-Management.md)

---

## Table of Contents

- [Overview](#overview)
- [Shell Completions](#shell-completions)
  - [Bash Completion](#bash-completion)
  - [Zsh Completion](#zsh-completion)
    - [Tier 1 — Primary (Script Execution)](#tier-1--primary-script-execution)
    - [Tier 2 — Namespaced Management](#tier-2--namespaced-management)
    - [Color scheme](#color-scheme)
    - [Hierarchical navigation](#hierarchical-navigation)
    - [Dual interface (flags vs subcommands)](#dual-interface-flags-vs-subcommands)
    - [Customization (advanced users)](#customization-advanced-users)
    - [Comparison with other shells](#comparison-with-other-shells)
    - [Tips and tricks (power users)](#tips-and-tricks-power-users)
    - [Troubleshooting](#troubleshooting)
  - [Fish Completion](#fish-completion)
  - [Custom Completions](#custom-completions)
- [Editor Integration](#editor-integration)
- [Automatic Linting](#automatic-linting)
- [Smart Aliases](#smart-aliases)
- [Productivity Features](#productivity-features)
- [Customization](#customization)
- [Next Steps](#next-steps)

## Overview

DotRun is designed with developer experience in mind:

- **Shell Completions**: Tab completion for all commands
- **Editor Support**: Integration with popular editors
- **Automatic Validation**: ShellCheck linting on save
- **Smart Features**: Aliases, shortcuts, and productivity tools
- **Customizable**: Adapt to your workflow

## Shell Completions

### Bash Completion

Enable tab completion in Bash:

```bash
# Add to ~/.bashrc
source ~/.config/dotrun/completions/drun-completion.bash

# Features:
# - Script name completion
# - Category completion
# - Option completion
# - Subcommand completion
```

Usage examples:

```bash
dr <TAB>                 # List all scripts
dr git/<TAB>             # List scripts in git category
dr deploy/prod<TAB>      # Complete to deploy/production
dr --<TAB>               # List all options
```

### Zsh Completion

This section documents the DotRun v3.1.0 Zsh completion experience. It's designed to make script discovery and management fast and predictable through a two-tier, namespace-based model with intuitive color cues and consistent navigation.

#### Overview: Two-tier namespace-based system

- Tier 1 (Primary): Optimized for running scripts quickly. You get folders, scripts, and a small set of special commands. No noise.
- Tier 2 (Namespaced Management): Organized by command type. Use flags or subcommands to access management commands for scripts, aliases, config, and collections.

This makes "run things" the default and "manage things" discoverable but out of your way.

---

#### Tier 1 — Primary (Script Execution)

When you type `dr <TAB>`, completion shows:

- Folders: yellow, with a trailing slash to indicate deeper navigation
- Scripts: cyan, no .sh extension
- Special commands: green (help, -l, -L, -h, --help)
- Hint: dark gray (a discoverability nudge for Tier 2)

Example (visual — comments indicate colors):

```bash
# dr <TAB>

apps/                                                       # yellow (fg=33) folder
services/                                                   # yellow (fg=33) folder
deploy                                                      # cyan   (fg=36) script (no .sh)
test                                                        # cyan   (fg=36) script (no .sh)
help                                                        # green  (fg=32) special
-l                                                          # green  (fg=32) special (list)
-L                                                          # green  (fg=32) special (list:details)
-h                                                          # green  (fg=32) special (help)
--help                                                      # green  (fg=32) special (help)
(hint: -s/scripts, -a/aliases, -c/config, -col/collections) # dark gray (fg=90)
```

Notes:

- Trailing slash "/" means you can keep navigating into folders.
- Scripts appear without ".sh" to keep the surface clean.
- Special commands are always visible; they don't pollute script listings.

Real-world usage examples:

```bash
# List available scripts quickly
dr -l

# Get details (e.g., descriptions) for scripts
dr -L

# Run a script at a path
dr apps/backend/build

# Navigate into a folder and discover scripts
dr services/<TAB>
# services/:
# api/         # yellow
# payments/    # yellow
# migrate      # cyan
# restart      # cyan
```

---

#### Tier 2 — Namespaced Management

Tier 2 groups management operations by type. You can enter Tier 2 with either flags or subcommands (dual interface).

- Scripts: `dr -s <TAB>` or `dr scripts <TAB>`
  - set, move, rename, docs
  - Colored green (fg=32) because they are management commands closely tied to execution

- Aliases: `dr -a <TAB>` or `dr aliases <TAB>`
  - set, list, remove, reload
  - Colored purple (fg=35)

- Config: `dr -c <TAB>` or `dr config <TAB>`
  - set, get, list, edit, unset, reload
  - Colored red (fg=31)

- Collections: `dr -col <TAB>` or `dr collections <TAB>`
  - add, list, list:details, sync, update
  - Uses default completion color in v3.1.0 (no dedicated color)

Examples (visual):

```bash
# Scripts namespace
dr -s <TAB>
# add     # green  (fg=32)
# edit    # green  (fg=32)
# move    # green  (fg=32)
# rename  # green  (fg=32)
# list    # green  (fg=32)
# help    # green  (fg=32)

# Aliases namespace
dr aliases <TAB>
# init    # purple (fg=35)
# add     # purple (fg=35)
# list    # purple (fg=35)
# edit    # purple (fg=35)
# remove  # purple (fg=35)
# reload  # purple (fg=35)

# Config namespace
dr -c <TAB>
# init    # red    (fg=31)
# set     # red    (fg=31)
# get     # red    (fg=31)
# list    # red    (fg=31)
# edit    # red    (fg=31)
# unset   # red    (fg=31)
# reload  # red    (fg=31)

# Collections namespace
dr -col <TAB>
# list
# list:details
# remove
```

Real-world flows:

```bash
# Add a new script, then open it in your editor
dr -s set build

# Move / rename scripts
dr scripts move old/path/build new/path/build
dr scripts rename old-name new-name

# Initialize and manage aliases
dr -a init
dr aliases add deploy "dr services/api/deploy"
dr -a list
dr -a edit deploy

# Configure defaults and reload
dr -c init
dr -c set default_env production
dr -c get default_env
dr -c reload

# Explore and prune collections
dr collections list
dr collections list:details
dr collections remove legacy-set
```

---

#### Color scheme

DotRun v3.1.0 completion uses the following colors consistently:

- Green (fg=32): Special + Script management
- Yellow (fg=33): Folders with trailing slash "/"
- Cyan (fg=36): Scripts without ".sh"
- Purple (fg=35): Alias commands
- Red (fg=31): Config commands
- Dark Gray (fg=90): Hint text

Visual reference:

```bash
# Green   (fg=32)  -> help, -l, -L, -h, --help; scripts namespace management
# Yellow  (fg=33)  -> apps/, services/, ...
# Cyan    (fg=36)  -> deploy, test, build, migrate, ...
# Purple  (fg=35)  -> aliases: add, edit, remove, reload, ...
# Red     (fg=31)  -> config: set, get, list, edit, ...
# DarkGray(fg=90)  -> (hint: -s/scripts, -a/aliases, -c/config, -col/collections)
```

---

#### Hierarchical navigation

Directories are navigable, and completion keeps you oriented:

```bash
# Discover top-level content
dr <TAB>
# apps/   services/   deploy   test   help   -l   -L   -h   --help
# (hint: -s/scripts, -a/aliases, -c/config, -col/collections)

# Dive into services/
dr services/<TAB>
# api/   payments/   migrate   restart

# One more level
dr services/api/<TAB>
# seed  migrate  start  stop

# Run immediately once discovered
dr services/api/start
```

Key behaviors:

- Trailing slash "/" indicates more levels.
- Scripts always appear extensionless.
- Completion is context-aware: once you're inside a folder, only valid children appear.

---

#### Dual interface (flags vs subcommands)

DotRun supports both short/long flag style and subcommand style for Tier 2. Choose what fits your workflow.

Parity mappings:

- Scripts: -s == scripts
- Aliases: -a == aliases
- Config: -c == config
- Collections: -col == collections

Equivalent examples:

```bash
dr -s set build
dr scripts set build

dr -a list
dr aliases list

dr -c set default_env production
dr config set default_env production

dr -col list:details
dr collections list:details
```

Guidance:

- Flags are compact and fast for habitual users.
- Subcommands are explicit and self-documenting for teams and new contributors.

---

#### Customization (advanced users)

Zsh completion is highly configurable. Below are safe, optional tweaks that play nicely with DotRun's UX.

Enable menu selection and richer matching:

```bash
# ~/.zshrc
autoload -Uz compinit
compinit
zmodload zsh/complist

# Arrow-key menu selection
zstyle ':completion:*' menu select

# Case-insensitive + smart separators (., _, -) matching
zstyle ':completion:*' matcher-list \
  'm:{a-z}={A-Z}' \
  'r:|[._-]=* r:|=*'

# Group results by type and show descriptions with subtle formatting
zstyle ':completion:*' group-name ''
zstyle ':completion:*:descriptions' format '%F{yellow}-- %d --%f'
```

Optional: Adjust list colors to align with your terminal theme:

```bash
# Example: retain clear grouping without overpowering your theme
# (Leave DotRun's semantic colors intact; this only affects general list rendering.)
zstyle ':completion:*' list-colors ''
```

Shell aliases for personal ergonomics:

```bash
# Prefer flags
alias drs='dr -s'
alias dra='dr -a'
alias drc='dr -c'
alias drcol='dr -col'

# Or prefer subcommands
alias drs='dr scripts'
alias dra='dr aliases'
alias drc='dr config'
alias drcol='dr collections'
```

Note:

- We recommend keeping DotRun's semantic color scheme; the above zstyles are optional quality-of-life improvements.
- If you use a completion framework (Oh My Zsh, zinit, etc.), put these after its initialization so they aren't overridden.

---

#### Comparison with other shells

- Bash
  - Pros: Ubiquitous; basic completion support.
  - Cons: Less expressive UI (no menu-select by default), weaker hint/description formatting, limited colorization vs Zsh.
  - Recommendation: Works, but Zsh provides a better, more discoverable UX for DotRun v3.1.0.

- Fish
  - Pros: Very user-friendly suggestions and inline hints.
  - Cons: Different completion model; requires a separate completion script. Color semantics may not match Zsh exactly.
  - Recommendation: Good experience, but Zsh remains the reference implementation for DotRun's namespace UI and color semantics.

---

#### Tips and tricks (power users)

- Type-ahead narrowing: Start typing path segments and use "/" to filter only folders, e.g., `dr s/a/<TAB>` to focus on services/api.
- Rapid list + run: `dr -L` to recall details, then up-arrow and complete the script name.
- Bulk rename with preview: Use `dr -s list` to confirm, then `dr -s rename` with completion to avoid typos.
- Edit what you just ran: `fc` (Zsh's "fix command") pairs well if you ran `dr -s edit` and want to tweak.
- Combine with fzf (optional): `dr -l | fzf | xargs -I{} dr {}` if you like fuzzy pickers outside of completion.
- Partial separators: With the matcher-list above, `dr srvapi mg` can still complete to `services/api/migrate`.

---

#### Troubleshooting

- Completions don't appear for `dr`
  - Ensure compinit is initialized:
    ```bash
    autoload -Uz compinit && compinit
    ```
  - Restart shell or re-source config:
    ```bash
    exec zsh
    # or
    source ~/.zshrc
    ```
  - Check `dr` is on PATH:
    ```bash
    command -v dr
    ```

- Colors or descriptions look off
  - Terminal must support ANSI colors; verify `$TERM` (e.g., `xterm-256color`).
  - Remove conflicting zstyles and test again:
    ```bash
    grep -n "zstyle" ~/.zshrc
    ```
  - If using a theme/framework, ensure your zstyles load after it.

- Tier 2 commands not showing
  - Verify version:
    ```bash
    dr --version # should be 3.1.0+
    ```
  - Try a fresh compinit to clear stale caches:
    ```bash
    rm -f ~/.zcompdump* && compinit
    ```

- Hierarchical navigation missing trailing "/"
  - Check that your completion isn't forcing file-like display overrides via `list-colors`.
  - Test in a clean shell:
    ```bash
    ZDOTDIR="$(mktemp -d)" zsh -f
    autoload -Uz compinit && compinit
    # then try `dr <TAB>` again
    ```

- Conflicts with other completion systems
  - Ensure only one completion provider initializes for `dr`. If multiple frameworks are installed, prefer a single source of compinit.
  - Confirm the completion function is discoverable:
    ```bash
    # Commonly the function is named `_dr` in $fpath
    print -l $fpath | while read -r p; do [[ -f "$p/_dr" ]] && echo "$p/_dr"; done
    ```

- Nothing completes inside a folder that you know exists
  - Confirm the folder exists in your scripts root and has read permissions.
  - If your repo changed, reload your environment or run `rehash`:
    ```bash
    rehash
    ```

### Fish Completion

Fish shell automatic completion:

```bash
# Completions auto-loaded from:
# ~/.config/fish/completions/dr.fish

# Features:
# - Real-time suggestions
# - Syntax highlighting
# - Description preview
```

Fish usage:

```bash
dr <TAB>                 # Visual completion menu
dr --help<TAB>           # Shows option description
dr deploy/<TAB>          # Category-aware completion
```

### Custom Completions

Add custom completion logic:

```bash
# In completion file
_dr_custom_complete() {
  local cur="${COMP_WORDS[COMP_CWORD]}"

  # Add dynamic completions
  if [[ "$cur" == "project:"* ]]; then
    COMPREPLY=($(compgen -W "$(ls ~/projects)" -- "${cur#project:}"))
  fi
}
```

## Editor Integration

### VS Code

Create VS Code tasks:

```json
// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "DotRun: List Scripts",
      "type": "shell",
      "command": "dr -L",
      "problemMatcher": []
    },
    {
      "label": "DotRun: Run Script",
      "type": "shell",
      "command": "dr ${input:scriptName}",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "scriptName",
      "type": "promptString",
      "description": "Script name to run"
    }
  ]
}
```

VS Code snippets:

```json
// snippets/dotrun.json
{
  "DotRun Script": {
    "prefix": "dr-script",
    "body": [
      "#!/usr/bin/env bash",
      "### DOC",
      "# ${1:Script Name} - ${2:Brief description}",
      "#",
      "# ${3:Detailed description}",
      "#",
      "# Usage: dr ${TM_FILENAME_BASE} ${4:[options]}",
      "#",
      "# Examples:",
      "#   dr ${TM_FILENAME_BASE}",
      "### DOC",
      "",
      "set -euo pipefail",
      "",
      "$0"
    ]
  }
}
```

### Vim/Neovim

Vim integration:

```vim
" ~/.vimrc or ~/.config/nvim/init.vim

" Run current script with DotRun
nnoremap <leader>dr :!dr %:t:r<CR>

" Edit DotRun script
command! -nargs=1 DRunEdit :e ~/.config/dotrun/bin/<args>

" List DotRun scripts
command! DRunList :!dr -L

" Create new script
function! DRunNew(name)
    execute '!dr set ' . a:name
    execute 'e ~/.config/dotrun/bin/' . a:name
endfunction
command! -nargs=1 DRunNew :call DRunNew(<q-args>)
```

### Emacs

Emacs configuration:

```elisp
;; ~/.emacs.d/init.el

;; DotRun mode
(defun dr-run-script ()
  "Run current script with DotRun"
  (interactive)
  (shell-command
    (concat "dr " (file-name-base (buffer-file-name)))))

(defun dr-list-scripts ()
  "List all DotRun scripts"
  (interactive)
  (shell-command "dr -L"))

;; Keybindings
(global-set-key (kbd "C-c d r") 'dr-run-script)
(global-set-key (kbd "C-c d l") 'dr-list-scripts)
```

## Automatic Linting

### ShellCheck Integration

DotRun automatically runs ShellCheck:

```bash
# Automatic linting on:
dr set newscript # After creation/editing
dr lint          # Manual lint all scripts
```

Configure linting:

```bash
# Disable linting
export DR_NO_LINT=1

# Custom ShellCheck options
export SHELLCHECK_OPTS="-e SC2034 -e SC2154"

# Lint specific severity
export DR_LINT_LEVEL="error" # error, warning, info, style
```

### Custom Linters

Add custom validation:

```bash
# ~/.config/dotrun/hooks/pre-save
#!/usr/bin/env bash

# Check for common issues
check_script() {
  local script="$1"

  # Must have documentation
  if ! grep -q "^### DOC" "$script"; then
    echo "Error: Missing ### DOC section"
    return 1
  fi

  # Check for hardcoded paths
  if grep -q "/home/$(whoami)" "$script"; then
    echo "Warning: Hardcoded home path detected"
  fi

  # Verify shebang
  if ! head -1 "$script" | grep -q "^#!/usr/bin/env"; then
    echo "Warning: Use #!/usr/bin/env for portability"
  fi
}

check_script "$1"
```

## Smart Aliases

### Alias Management

DotRun includes alias management:

```bash
# Add alias
dr alias add gc "git commit -m"

# List aliases
dr alias list

# Remove alias
dr alias rm gc

# Export aliases
dr alias export >~/.aliases
```

### Category-based Aliases

Organize aliases by category:

```bash
# Git aliases
dr alias add git/st "git status"
dr alias add git/co "git checkout"
dr alias add git/cm "git commit -m"

# Docker aliases
dr alias add docker/ps "docker ps --format 'table {{.Names}}\t{{.Status}}'"
dr alias add docker/clean "docker system prune -af"

# List by category
dr alias list git/
```

### Smart Alias Features

Advanced alias capabilities:

```bash
# Aliases with functions
dr alias add mkcd 'f() { mkdir -p "$1" && cd "$1"; }; f'

# Aliases with completion
dr alias add proj 'cd ~/projects/$1' --complete-dirs

# Conditional aliases
dr alias add update 'if [[ "$OSTYPE" == "darwin"* ]]; then brew update; else sudo apt update; fi'
```

## Productivity Features

### Quick Commands

Built-in productivity commands:

```bash
# Quick navigation
dr cd git  # cd ~/.config/dotrun/bin/git
dr cd docs # cd ~/.config/dotrun/docs

# Quick creation
dr quick deploy-fix # Create and edit immediately

# Batch operations
dr lint --all # Lint all scripts
dr test --all # Run all test scripts
```

### Script Templates

Use templates for common patterns:

```bash
# List templates
dr template list

# Create from template
dr set api/newservice --template=rest-api

# Create custom template
dr template create mytemplate

# Share templates
dr template export mytemplate >mytemplate.sh
```

### Workflow Automation

Automate common workflows:

```bash
# Git workflow
dr workflow git-feature "feature-name"
# Creates branch, sets up PR template, etc.

# Release workflow
dr workflow release "1.2.3"
# Tags, builds, deploys, notifies

# Daily workflow
dr workflow daily
# Updates repos, cleans temp files, backs up
```

### Integration Hooks

Hook into DotRun events:

```bash
# ~/.config/dotrun/hooks/post-add
#!/usr/bin/env bash
# Run after adding new script

script="$1"
echo "New script created: $script"

# Auto-commit
cd ~/.config/dotrun
git add "bin/$script"
git commit -m "Add: $script"

# Notify team
slack-notify "#dev-scripts" "New script added: $script"
```

## Customization

### Configuration File

Create a DotRun configuration:

```bash
# ~/.config/dotrun/config
DR_DEFAULT_EDITOR="code"
DR_DEFAULT_SHELL="bash"
DR_COMPLETION_STYLE="verbose"
DR_LINT_ON_SAVE=true
DR_AUTO_COMMIT=true
DR_TEMPLATE_DIR="$HOME/.config/dotrun/my-templates"
```

### Custom Commands

Add custom subcommands:

```bash
# ~/.config/dotrun/commands/stats
#!/usr/bin/env bash
# Show script statistics

echo "DotRun Statistics:"
echo "=================="
echo "Total scripts: $(find ~/.config/dotrun/bin -type f | wc -l)"
echo "Categories: $(find ~/.config/dotrun/bin -type d -mindepth 1 | wc -l)"
echo "Documentation: $(find ~/.config/dotrun/docs -name "*.md" | wc -l)"

# Make executable
chmod +x ~/.config/dotrun/commands/stats

# Use: dr stats
```

### Themes and Colors

Customize output colors:

```bash
# ~/.config/dotrun/theme
DR_COLOR_SUCCESS="32"  # Green
DR_COLOR_ERROR="31"    # Red
DR_COLOR_WARNING="33"  # Yellow
DR_COLOR_INFO="34"     # Blue
DR_COLOR_HEADER="35"   # Magenta
DR_COLOR_CATEGORY="36" # Cyan

# Unicode symbols
DR_SYMBOL_SUCCESS="✓"
DR_SYMBOL_ERROR="✗"
DR_SYMBOL_WARNING="⚠"
DR_SYMBOL_INFO="ℹ"
```

### Plugins

Create DotRun plugins:

```bash
# ~/.config/dotrun/plugins/git-integration.sh

# Auto-detect git repos
dr_git_detect() {
  if [[ -d .git ]]; then
    export DR_GIT_REPO=$(basename "$PWD")
    export DR_GIT_BRANCH=$(git branch --show-current)
  fi
}

# Add to prompt
PROMPT_COMMAND="dr_git_detect; $PROMPT_COMMAND"

# Context-aware scripts
dr() {
  if [[ -n "$DR_GIT_REPO" && "$1" == "commit" ]]; then
    command dr git/quick-commit "${@:2}"
  else
    command dr "$@"
  fi
}
```

## Next Steps

Enhance your DotRun experience:

1. **Configure Environment**: Set up [Configuration Management](Configuration-Management.md)
2. **Manage Aliases**: Learn [Alias Management](Alias-Management.md)
3. **Team Setup**: Configure [Team Collaboration](Team-Collaboration.md)
4. **Browse Examples**: See [Example Scripts](Script-Examples.md)
5. **Troubleshooting**: Check [Troubleshooting Guide](Troubleshooting.md)

---

[← Team Collaboration](Team-Collaboration.md) | [Configuration Management →](Configuration-Management.md) | [Top ↑](#developer-experience)