Zsh Starship Config - npm Installer

Modern Zsh + Starship + Nerd Fonts setup via npm

A robust and feature-rich CLI installer that provides a complete Zsh, Starship, tmux, and development environment setup with advanced features like rollback, configuration management, and dry-run modes.

Features

• ✨ Comprehensive Installation: Zsh, Oh My Zsh, Starship, tmux, Nerd Fonts, eza, and modern tools
• 🎨 9 Tmux Themes: cobalt, green, blue, purple, orange, red, nord, everforest, gruvbox, cream
• 🔄 Rollback System: Undo changes if something goes wrong
• 💾 Backup Management: Automatic backups before modifications
• 🔧 Configuration Management: Persistent configuration with CLI and interactive modes
• 🎯 Dry-run Mode: Preview changes without applying them
• 📊 Status Monitoring: Real-time system health and component status
• 🎨 Clipboard Support: Native OSC 52 clipboard for Linux/Wayland with mouse support

Installation

Quick Install

# Install globally via npm
npm install -g @jaggerxtrm/xzsc

# Run installer
zsc install

Install Specific Components

# Install only Zsh and Starship
zsc install --only zsh --only starship

# Install tmux themes only
zsc install --only tmuxThemes

# Install with custom options
zsc install --font-type nerd --shell zsh

Usage

Basic Commands

# Show help
zsc help

# Show version
zsc --version

# Check installation status
zsc status

# Apply tmux theme
zsc theme nord

# Auto-detect session and apply theme
zsc theme --auto

# List available themes
zsc theme --list

# Manage configuration
zsc config --list

Advanced Usage

Dry-run Mode (Preview Changes)

# Preview installation without applying changes
zsc install --dry-run

# Preview theme application
zsc theme cobalt --preview

# Preview update
zsc update --dry-run

Component Filtering

# Install everything except fonts
zsc install --exclude fonts

# Update only specific components
zsc update --only starship --only tmux

# Update multiple specific components
zsc update tmux themes eza

Configuration Management

# Interactive configuration
zsc config

# Get configuration value
zsc config --get components.zsh.enabled

# Set configuration value
zsc config --set preferences.autoUpdate false

# List all configuration
zsc config --list

# Reset to defaults
zsc config --reset

# Export configuration
zsc config --export my-config.json

Backup and Rollback

# Create backup
zsc backup

# List rollback points
zsc rollback --list

# Rollback last change
zsc rollback

# Rollback multiple steps
zsc rollback --step 2

# Dry-run rollback
zsc rollback --dry-run

Component Reference

Available Components

| Component | Description | Dependencies | |-----------|-------------|--------------| | zsh | Zsh shell and configuration | - | | ohMyZsh | Oh My Zsh framework | zsh | | plugins | Zsh plugins (autosuggestions, syntax-highlighting, etc.) | zsh, ohMyZsh | | starship | Starship prompt | - | | fonts | Nerd Fonts installation | - | | tmux | Tmux terminal multiplexer | - | | tmuxPlugins | Tmux plugins via TPM | tmux | | tmuxThemes | Tmux color themes | tmux | | eza | Modern ls replacement | - | | tools | Modern tools (bat, ripgrep, fd, zoxide, fzf) | - | | statusline | Claude Code status line configuration | starship | | zshrc | Zsh configuration file | zsh, ohMyZsh, starship | | hooks | Git hooks and automation | zsh |

Aliases

You can use aliases instead of component names:

• all - All components
• full - All components (same as all)
• minimal - zsh, starship, fonts, zshrc
• dev - All components (same as all)
• basic - zsh, ohMyZsh, plugins, starship, fonts, zshrc

Tmux Themes

Available Themes

| Theme | Description | Auto-trigger | |--------|-------------|--------------| | cobalt | Blue/gray professional theme | - | | green | Green development theme | dev, code | | blue | Blue research theme | research, doc | | purple | Purple calm theme | - | | orange | Orange warning theme | debug, test | | red | Red urgent theme | prod, urgent | | nord | Nord dark theme | - | | everforest | Everforest green theme | - | | gruvbox | Gruvbox retro theme | - | | cream | Cream light theme | - |

Auto-Theming

When you create tmux sessions, the theme is automatically applied based on the session name:

• dev*, code* → green theme
• research*, doc* → blue theme
• debug*, test* → orange theme
• prod*, urgent* → red theme

Tmux Configuration

The installer automatically configures tmux with:

• Native clipboard (OSC 52): Works over SSH, no external tools needed
• Enhanced tmux-yank: Improved copy/paste with mouse support
• 9 themes: Pre-configured color themes
• Dual status bar: Current path and keybind cheatsheet
• TPM plugins: tmux-sensible, tmux-resurrect, tmux-continuum
• Auto reload: Configuration automatically reloaded after changes

Configuration

Configuration File

Configuration is stored in ~/.zsc/config.json:

{
  "version": "1.0.0",
  "components": {
    "zsh": {
      "enabled": true,
      "shell": "zsh",
      "configPath": "~/.zshrc",
      "plugins": ["zsh-autosuggestions", "zsh-syntax-highlighting", "zsh-history-substring-search"]
    },
    "starship": {
      "enabled": true,
      "configPath": "~/.config/starship.toml",
      "binaryPath": "~/.local/bin/starship"
    },
    "tmux": {
      "enabled": true,
      "configPath": "~/.tmux.conf",
      "themePath": "~/.tmux/themes.sh",
      "plugins": ["tmux-sensible", "tmux-resurrect", "tmux-continuum"],
      "tpmPath": "~/.tmux/plugins/tpm"
    }
  },
  "preferences": {
    "autoUpdate": true,
    "checkForUpdates": true,
    "createBackups": true,
    "backupPrefix": "backup",
    "keepBackups": 5,
    "parallelInstall": false
  },
  "paths": {
    "cacheDir": "~/.zsc/cache",
    "logsDir": "~/.zsc/logs",
    "backupDir": "~/.zsc/backups"
  }
}

Configuration Options

| Option | Default | Description | |--------|----------|-------------| | autoUpdate | true | Automatically check for updates | | createBackups | true | Create backups before modifications | | keepBackups | 5 | Number of backups to keep | | backupPrefix | 'backup' | Prefix for backup files | | parallelInstall | false | Run installations in parallel |

Advanced Features

Dry-run Mode

Preview changes without applying them:

# Preview installation
zsc install --dry-run

# Preview theme application
zsc theme nord --preview

# Preview update
zsc update --dry-run

Dry-run mode shows:

• What would be installed/updated
• Files that would be created/modified
• Commands that would be executed
• Configuration changes that would be made

Rollback System

Undo changes if something goes wrong:

# List available rollback points
zsc rollback --list

# Rollback last change
zsc rollback

# Rollback multiple changes
zsc rollback --step 3

# Dry-run rollback
zsc rollback --dry-run

Rollback features:

• Multi-step rollback support
• Automatic backup creation before changes
• Rollback point tracking
• Safe restoration with verification

Backup Management

Create and manage backups:

# Create manual backup
zsc backup

# Backup with options
zsc backup --output ~/backups --compress

# Include data files in backup
zsc backup --include-data

# View backup statistics
zsc status

Examples

Complete Installation

# Full installation with all defaults
zsc install

# Non-interactive mode (for scripts/Docker)
zsc install --yes

# Verbose installation
zsc install --verbose

Selective Installation

# Minimal installation
zsc install minimal

# Install development tools only
zsc install tools

# Install tmux setup only
zsc install tmux tmuxPlugins tmuxThemes

# Exclude specific components
zsc install --exclude fonts

Update Workflow

# Update all installed components
zsc update

# Update specific components
zsc update starship tmux

# Update with backup creation
zsc update --yes

# Update in dry-run mode
zsc update --dry-run

Theme Management

# Apply specific theme to current session
zsc theme nord

# Apply theme to specific session
zsc theme cobalt myproject

# Auto-detect session
zsc theme --auto

# List all themes
zsc theme --list

# Preview theme without applying
zsc theme everforest --preview

Configuration Management

# Interactive configuration
zsc config

# Get specific configuration
zsc config --get preferences.autoUpdate

# Set specific configuration
zsc config --set preferences.parallelInstall true

# Delete configuration value
zsc config --delete components.tmux.enabled

# Export configuration
zsc config --export ~/zsc-config-backup.json

# Reset to defaults
zsc config --reset

Status Monitoring

# Show all status
zsc status

# Show specific component status
zsc status --only tmux

# Export status as JSON
zsc status --json

# Export status to file
zsc status --export ~/zsc-status.json

Error Recovery

# Check what failed
zsc status

# Rollback last changes
zsc rollback

# Retry installation with different options
zsc install --yes --verbose

Troubleshooting

Installation Issues

Issue: Permission denied errors

# Solution: Run with appropriate permissions or use sudo
sudo zsc install

# Or check file permissions
ls -la ~/.zshrc ~/.config/

Issue: Dependencies not found

# Solution: Check what's missing
zsc status

# Install missing dependencies
zsc install --only <missing-component>

Issue: Theme not applying

# Solution: Check tmux is running
echo $TMUX

# Check theme script exists
ls -la ~/.tmux/themes.sh

# Verify tmux configuration
tmux show-options -g | grep theme

Clipboard Issues

Issue: Clipboard not working over SSH

# Solution: OSC 52 clipboard works over SSH, verify:
# 1. Terminal setting: "set -s set-clipboard on"
# 2. Tmux config: "set -g set-clipboard on"
# 3. Check tmux-yank is installed: ls ~/.tmux/plugins/tpm/

Issue: tmux-yank not installing via TPM

# Manual install of tmux-yank
cd ~/.tmux/plugins/tpm
git clone https://github.com/tmux-plugins/tmux-yank

# Reload tmux config
tmux source-file ~/.tmux.conf

Rollback Issues

Issue: Rollback not working

# Check available rollback points
zsc rollback --list

# Verify rollback files exist
ls -la ~/.zsc/backups/

# Force rollback to specific point
zsc rollback --step 1 --force

Migration from Shell Script

If you're currently using the shell script installer (install.sh), here's how to migrate:

Before Migration

1. Backup current configuration:

zsc backup --output ~/migration-backup --compress

2. Check current installation:

zsc status

3. Uninstall shell-based components (if desired):

# Review what's installed
zsc status --json > current-config.json

Migration Process

# Fresh install with npm installer
zsc install

# This will:
# - Detect existing components
# - Update configuration
# - Preserve your customizations
# - Install missing components

After Migration

1. Verify installation:

zsc status

# Test core functionality
zsh -c 'echo $ZSH_VERSION'
starship --version
tmux -V

2. Test themes:

# List available themes
zsc theme --list

# Apply a theme
zsc theme nord

# Test clipboard
# Select text in tmux with mouse, press v to enter copy mode, press y to copy
# Paste with p in normal mode

3. Configuration sync:

# Review your configuration
zsc config --list

# Adjust if needed
zsc config --set preferences.autoUpdate false

System Requirements

Minimum Requirements

• OS: Linux or macOS
• Shell: Zsh (bash and fish support planned)
• Node.js: v14.0.0 or higher
• Package Manager: npm, yarn, or pnpm
• Disk Space: ~100 MB for installation
• Permissions: Ability to install system packages

Supported Distributions

• Fedora: 35+ ✅
• Ubuntu/Debian: All LTS versions ✅
• Arch Linux: Tested ✅
• WSL: Full support with clipboard enhancements ✅

Optional Dependencies

For enhanced features, the following are optional but recommended:

• git: For version control and some features
• curl: For downloading resources
• tmux: For terminal multiplexing (optional but recommended)

Development

Project Structure

xzsc/
├── bin/
│   └── zsc.js              # Main CLI entry point
├── src/
│   ├── commands/              # Command handlers
│   │   ├── install.js
│   │   ├── update.js
│   │   ├── status.js
│   │   ├── theme.js
│   │   ├── config.js
│   │   ├── rollback.js
│   │   └── backup.js
│   └── utils/                 # Utility modules
│       ├── logger.js           # Logging with spinners
│       ├── error-handler.js    # Error handling & retry
│       ├── config-manager.js    # Configuration persistence
│       ├── component-manager.js # Component orchestration
│       ├── downloader.js       # File downloads
│       ├── backup.js          # Backup & restore
│       ├── paths.js           # Path management
│       └── system.js          # System detection
├── data/
│   ├── tmux.conf            # Tmux configuration
│   ├── starship.toml         # Starship prompt config
│   ├── themes.sh             # Tmux theme scripts
│   ├── zshrc                # Zsh configuration
│   └── ...                  # Other data files
├── scripts/
│   └── ...                  # Helper scripts
├── tests/
│   ├── setup.js             # Test setup utilities
│   ├── logger.test.js        # Logger unit tests
│   ├── error-handler.test.js # ErrorHandler unit tests
│   ├── manual-test.js        # Manual CLI tests
│   └── test-planning.md    # Test planning
├── package.json
├── jest.config.js
└── README.md

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test -- logger.test.js

Contributing

Development Setup

# Clone repository
git clone https://github.com/Jaggerxtrm/xzsc.git
cd xzsc

# Install dependencies
npm install

# Run tests
npm test

# Link for development
npm link

Code Style

• Use consistent formatting
• Follow existing patterns
• Add tests for new features
• Update documentation

Submitting Changes

1. Create feature branch: git checkout -b feature/your-feature
2. Make changes and test: npm test
3. Commit changes: git commit -m "feat: your feature"
4. Push to GitHub: git push origin feature/your-feature
5. Create Pull Request

License

MIT License - Free to use and modify

Changelog

See CHANGELOG.md for version history and changes.

Support

• GitHub Issues: https://github.com/Jaggerxtrm/xzsc/issues
• Documentation: https://github.com/Jaggerxtrm/xzsc/wiki
• Discussions: https://github.com/Jaggerxtrm/xzsc/discussions

Acknowledgments

• Starship: https://starship.rs
• Oh My Zsh: https://ohmyz.sh/
• Tmux: https://github.com/tmux/tmux-wiki
• Nerd Fonts: https://www.nerdfonts.com/
• Tmux-yank: https://github.com/tmux-plugins/tmux-yank

Built with ❤️ for the developer community