claudepod 1.0.2 → 1.1.0

package/.devcontainer/setup-zsh.sh

@@ -4,12 +4,39 @@
 
 set -euo pipefail
 
+# Clear npm prefix environment variables that conflict with NVM
+unset npm_config_prefix 2>/dev/null || true
+unset NPM_CONFIG_PREFIX 2>/dev/null || true
+
 echo "🐚 Setting up enhanced ZSH configuration..."
 
+# State tracking directory  
+STATE_DIR="/workspace/.devcontainer/state"
+
+# Function to create state marker
+create_state_marker() {
+    local component="$1"
+    local method="${2:-unknown}"
+    
+    mkdir -p "$STATE_DIR"
+    echo "$(date '+%Y-%m-%d %H:%M:%S') - $method" > "$STATE_DIR/${component}.installed"
+    chown -R node:node "$STATE_DIR"
+}
+
+# Function to check if component is already installed
+is_component_installed() {
+    local component="$1"
+    
+    [ -f "$STATE_DIR/${component}.installed" ]
+}
+
 # Variables
 ZSH_CUSTOM="${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}"
 NODE_USER="node"
 
+# Source shell configuration modules
+source "/workspace/.devcontainer/scripts/shell/zsh-config.sh"
+
 # Function to install ZSH plugin
 install_zsh_plugin() {
     local plugin_name="$1"
@@ -42,206 +69,15 @@ install_powerlevel10k() {
     fi
 }
 
-# Function to create enhanced .zshrc
-create_zshrc() {
-    echo "📝 Creating enhanced .zshrc configuration..."
-    
-    # Backup existing .zshrc if it exists
-    if [ -f "$HOME/.zshrc" ]; then
-        cp "$HOME/.zshrc" "$HOME/.zshrc.backup.$(date +%s)" 2>/dev/null || true
-    fi
-    
-    cat > "$HOME/.zshrc" << 'EOF'
-# ClaudePod ZSH Configuration
-# Path to your oh-my-zsh installation
-export ZSH="$HOME/.oh-my-zsh"
-
-# Set name of the theme to load
-ZSH_THEME="powerlevel10k/powerlevel10k"
-
-# Enable Powerlevel10k instant prompt. Should stay close to the top of ~/.zshrc.
-if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
-  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
-fi
-
-# Disable P10k configuration wizard
-export POWERLEVEL9K_DISABLE_CONFIGURATION_WIZARD=true
-
-# ZSH Configuration
-CASE_SENSITIVE="false"
-HYPHEN_INSENSITIVE="true"
-DISABLE_AUTO_UPDATE="false"
-DISABLE_UPDATE_PROMPT="true"
-export UPDATE_ZSH_DAYS=7
-DISABLE_MAGIC_FUNCTIONS="false"
-DISABLE_LS_COLORS="false"
-DISABLE_AUTO_TITLE="false"
-ENABLE_CORRECTION="true"
-COMPLETION_WAITING_DOTS="true"
-DISABLE_UNTRACKED_FILES_DIRTY="false"
-HIST_STAMPS="yyyy-mm-dd"
-
-# ZSH Plugins
-plugins=(
-  git
-  docker
-  docker-compose
-  node
-  npm
-  python
-  pip
-  vscode
-  zsh-syntax-highlighting
-  zsh-autosuggestions
-  zsh-completions
-  fast-syntax-highlighting
-  history-substring-search
-  colored-man-pages
-  command-not-found
-  extract
-  z
-)
-
-# Load Oh My Zsh
-source $ZSH/oh-my-zsh.sh
-
-# User configuration
-export LANG=en_US.UTF-8
-export EDITOR='code'
-export ARCHFLAGS="-arch x86_64"
-
-# History configuration
-HISTSIZE=50000
-SAVEHIST=50000
-setopt HIST_EXPIRE_DUPS_FIRST
-setopt HIST_IGNORE_DUPS
-setopt HIST_IGNORE_ALL_DUPS
-setopt HIST_IGNORE_SPACE
-setopt HIST_FIND_NO_DUPS
-setopt HIST_SAVE_NO_DUPS
-setopt HIST_BEEP
-setopt SHARE_HISTORY
-
-# Path configuration
-export PATH="$HOME/.local/bin:$PATH"
-export PATH="/usr/local/share/npm-global/bin:$PATH"
-
-# Node.js/NVM configuration
-export NVM_DIR="/usr/local/share/nvm"
-[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
-[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
-
-# Python configuration
-if command -v python3 &> /dev/null; then
-    alias python=python3
-    alias pip=pip3
-fi
+# ZSH configuration is now handled by focused generator functions:
+# - generate_zsh_basic_config(): Basic ZSH settings, plugins, history  
+# - generate_zsh_aliases(): All alias definitions
+# - generate_zsh_functions(): Shell utility functions
+# - generate_zsh_welcome(): Welcome message and final configuration
+# - create_zshrc(): Main orchestrator function  
+# See: /workspace/.devcontainer/scripts/shell/zsh-config.sh
 
-# ClaudePod aliases
-alias ll='ls -alF'
-alias la='ls -A'
-alias l='ls -CF'
-alias gs='git status'
-alias gd='git diff'
-alias gc='git commit'
-alias gco='git checkout'
-alias gp='git push'
-alias gl='git log --oneline --graph --decorate'
-alias ga='git add'
-alias gb='git branch'
-alias gm='git merge'
-alias gr='git rebase'
-alias gf='git fetch'
-alias gpl='git pull'
-
-# Development aliases
-alias c='code .'
-alias cls='clear'
-alias h='history'
-alias ..='cd ..'
-alias ...='cd ../..'
-alias ....='cd ../../..'
-alias ~='cd ~'
-
-# Claude Code aliases
-alias claude='claude --model sonnet --dangerously-skip-permissions'
-alias claude-help='claude --help'
-alias claude-mcp='claude mcp list'
-alias claude-version='claude --version'
-
-# Docker aliases (if docker is available)
-if command -v docker &> /dev/null; then
-    alias d='docker'
-    alias dc='docker-compose'
-    alias dps='docker ps'
-    alias dpsa='docker ps -a'
-    alias di='docker images'
-    alias drm='docker rm'
-    alias drmi='docker rmi'
-fi
-
-# Useful functions
-# Extract various archive formats
-extract() {
-    if [ -f $1 ]; then
-        case $1 in
-            *.tar.bz2)   tar xjf $1     ;;
-            *.tar.gz)    tar xzf $1     ;;
-            *.bz2)       bunzip2 $1     ;;
-            *.rar)       unrar e $1     ;;
-            *.gz)        gunzip $1      ;;
-            *.tar)       tar xf $1      ;;
-            *.tbz2)      tar xjf $1     ;;
-            *.tgz)       tar xzf $1     ;;
-            *.zip)       unzip $1       ;;
-            *.Z)         uncompress $1  ;;
-            *.7z)        7z x $1        ;;
-            *)           echo "'$1' cannot be extracted via extract()" ;;
-        esac
-    else
-        echo "'$1' is not a valid file"
-    fi
-}
-
-# Create directory and cd into it
-mkcd() {
-    mkdir -p "$1" && cd "$1"
-}
-
-# Find process by name
-findp() {
-    ps aux | grep -v grep | grep "$1"
-}
-
-# Quick HTTP server
-serve() {
-    local port="${1:-8000}"
-    python3 -m http.server "$port"
-}
-
-# Load Powerlevel10k configuration
-if [[ -r ~/.p10k.zsh ]]; then
-  source ~/.p10k.zsh
-fi
-
-# Auto-suggestions configuration
-ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#666666"
-ZSH_AUTOSUGGEST_STRATEGY=(history completion)
-ZSH_AUTOSUGGEST_USE_ASYNC=true
-
-# Syntax highlighting configuration
-ZSH_HIGHLIGHT_HIGHLIGHTERS=(main brackets pattern)
-
-# Welcome message
-if [[ -n "$ZSH_VERSION" && -z "$VSCODE_RESOLVING_ENVIRONMENT" ]]; then
-    echo "🚀 Welcome to ClaudePod!"
-    echo "💡 Type 'claude' to start using Claude Code"
-    echo "📋 Run 'claude mcp list' to see available MCP servers"
-fi
-EOF
-
-    echo "✅ Enhanced .zshrc created"
-}
+# Note: The actual create_zshrc() function is now imported from the module above
 
 # Function to create Powerlevel10k configuration
 create_p10k_config() {
@@ -336,6 +172,18 @@ EOF
 
 # Main setup function
 main() {
+    # Check if ZSH setup is already complete
+    if is_component_installed "zsh-setup"; then
+        echo "✅ ZSH enhancement already complete (marker found)"
+        if [ -f "$HOME/.zshrc" ] && [ -d "$HOME/.oh-my-zsh/custom/themes/powerlevel10k" ]; then
+            echo "✓ .zshrc and Powerlevel10k theme verified"
+            return 0
+        else
+            echo "⚠️  Marker exists but files missing, re-running setup..."
+            rm -f "$STATE_DIR/zsh-setup.installed"
+        fi
+    fi
+    
     echo "🐚 Starting ZSH enhancement setup..."
     
     # Ensure we're running as the correct user
@@ -350,9 +198,9 @@ main() {
         exit 1
     fi
     
-    # Suppress NVM errors during this process
+    # Source NVM for this process
     export NVM_DIR="/usr/local/share/nvm"
-    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" 2>/dev/null || true
+    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
     
     # Install Powerlevel10k theme
     install_powerlevel10k
@@ -377,9 +225,10 @@ main() {
         sudo chsh -s /usr/bin/zsh "$NODE_USER" || echo "⚠️  Could not change default shell"
     fi
     
+    create_state_marker "zsh-setup" "plugins+theme+config"
     echo "✅ ZSH enhancement setup complete!"
     echo "💡 Restart your terminal or run 'source ~/.zshrc' to apply changes"
 }
 
 # Execute main function
-main
+main

package/README.md

@@ -1,140 +1,151 @@
-# ClaudePod DevContainer Package
+# ClaudePod
 
-A fully configured DevContainer optimized for Claude Code development with MCP servers, modern development tools, and persistent configuration. Easily add this development environment to any project with one command.
+A complete development container that sets up Claude Code with 8 powerful MCP servers, modern dev tools, and persistent configurations. Drop it into any project and get a production-ready AI development environment in minutes.
 
-## 🚀 Quick Setup
+## What's Inside
+
+**Claude Code CLI** with native binary installation and optimized configuration  
+**8 MCP Servers** providing 100+ specialized tools for code analysis, documentation search, task management, and more  
+**Modern Stack** - Node.js 20, Python 3.13, Git with delta, GitHub CLI  
+**Smart Persistence** - Your Claude config, shell history, and npm cache survive container rebuilds  
+**Enhanced Terminal** - Powerlevel10k with quiet mode and useful git aliases  
+
+## Quick Start
+
+### Using NPM Package
+
+ClaudePod is available as an npm package at [npmjs.com/package/claudepod](https://www.npmjs.com/package/claudepod):
 
 ```bash
-# Install in any project directory
+# Drop into any project
+cd your-project
 npx claudepod-devcontainer
 
-# Start the container
+# Fire it up
 devpod up .
+devpod ssh <workspace-name> --ide vscode  # <workspace-name> is usually your project folder name
 
-# Connect with VS Code
-devpod ssh <workspace-name> --ide vscode
+# Start coding with Claude
+claude
+```
+
+### Cloning from Repository
+
+```bash
+# Clone the repository
+git clone https://github.com/AnExiledDev/ClaudePod.git
+cd ClaudePod
+
+# Copy .devcontainer to your project
+cp -r .devcontainer /path/to/your-project/
+cd /path/to/your-project
+
+# Fire it up
+devpod up .
+devpod ssh <workspace-name> --ide vscode  # <workspace-name> is usually your project folder name
 
 # Start coding with Claude
 claude
 ```
 
-## ✨ What You Get
+That's it. No configuration files to edit, no API keys to hunt down. Everything works out of the box.
 
-### 🛠️ Development Stack
-- **Node.js 20** (via NVM) + npm/npx
-- **Python 3.13** with pipx, uv/uvx, and common tools  
-- **Git** with git-delta for beautiful diffs
-- **GitHub CLI** for repository operations
-- **Claude Code CLI** with optimized tool configuration
+## The MCP Servers
+
+ClaudePod ships with 8 MCP servers that turn Claude into a powerhouse:
 
-### 🔌 MCP Servers (Pre-configured)
 - **Serena** - Advanced code analysis and semantic search
 - **DeepWiki** - GitHub repository documentation search  
 - **TaskMaster AI** - AI-powered project management
-- **Sequential Thinking** - Structured problem-solving
-- **GitHub MCP** - Complete GitHub API integration (requires API key)
-- **Tavily Search** - Web search capabilities (requires API key)
-- **Ref.Tools** - Documentation tools (requires API key)
-
-### ⚡ Productivity Features
-- **Optimized tool configuration** - 79 essential tools pre-allowed (51% reduction from 161 total)
-- **Zero permission prompts** for common development workflows
-- **Intelligent tool selection** - Prioritizes powerful MCP tools over basic built-ins
-- **Shell aliases** - `gs`, `gd`, `gc`, `gp`, `gl` for git operations
-- **Persistent storage** - Claude config and shell history survive rebuilds
-- **VS Code extensions** - Pre-configured for remote development
-
-## 📋 Requirements
-
-1. **DevPod** installed and configured
-2. **VS Code** with Remote Development Extension Pack:
-   ```bash
-   code --install-extension ms-vscode-remote.vscode-remote-extensionpack
-   ```
-
-## 🔧 Usage
-
-### Install in Existing Project
-```bash
-cd my-existing-project
-npx claudepod-devcontainer
-devpod up .
-```
+- **Sequential Thinking** - Structured problem-solving workflows
+- **ccusage** - Claude Code usage analytics and cost tracking
+- **SearXNG Enhanced** - Web search with content scraping
+- **GitHub MCP** - Complete GitHub API integration (API key optional)
+- **Tavily + Ref.Tools** - Web search and documentation tools (API keys optional)
 
-### New Project Setup
-```bash
-mkdir new-project && cd new-project
-npx claudepod-devcontainer
-devpod up .
-```
+**Tool Permissions**: When Claude first starts, it will ask permission to use these MCP tools. You can deny or allow specific tools based on your needs - this helps manage the large number of available tools (100+). Future versions will make this easier to configure.
 
-### First-Time Container Setup
-```bash
-# Inside the container
-./scripts/setup-env.sh  # Optional environment setup
-claude login           # Authenticate with Claude
-claude                 # Start development
-```
+## Requirements
+
+- **[DevPod](https://devpod.sh/)** installed and configured - the container development platform
+- **VS Code** with Remote Development extensions
+- That's literally it
 
-## 🎯 Quick Commands
+## Container Details
+
+**Base**: Ubuntu 22.04  
+**User**: node (1000:1000)  
+**Workspace**: `/workspace` (your project files)  
+**Persistent**: Claude config, shell history, npm cache  
+
+Your files stay exactly where they are. ClaudePod only adds a `.devcontainer/` directory.
+
+## Handy Commands
 
 ```bash
-# Claude Code (with MCP servers, no permission prompts)
-claude                    # Start Claude 
-claude mcp list          # List available MCP servers
-
-# Git (with aliases and delta highlighting)
-gs                       # git status
-gd                       # git diff 
-gc -m "message"          # git commit
-gp                       # git push
-gl                       # git log --oneline --graph
-
-# Python development
-uvx <package>            # Run packages without installing
-uv add <package>         # Add dependencies
-
-# Health check
-./scripts/health-check.sh # Verify everything works
+# Claude with statusline and MCP servers
+claude
+
+# Git shortcuts (with beautiful diffs)
+gs    # git status
+gd    # git diff
+gc    # git commit
+gp    # git push
+gl    # git log --oneline --graph
+
+# Python without the pain
+uvx <package>     # Run packages without installing
+uv add <package>  # Add dependencies  
+
+# Quick info
+claudepod_info    # Show status and commands
 ```
 
-## 🔑 Optional API Keys
+## Optional Upgrades
+
+**Web search is already included** via the built-in SearXNG server - no limits, no API keys required. But you can add more integrations:
 
-Add these to your environment for enhanced features:
+```bash
+cp .devcontainer/.env.example .devcontainer/.env
+# Edit .devcontainer/.env with your keys
+```
 
 ```bash
 # GitHub integration (recommended)
-export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token"
+GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token
 
-# Web search capabilities  
-export TAVILY_API_KEY="tvly-your-key"
+# Additional web search via Tavily (optional - SearXNG already provides unlimited search)
+TAVILY_API_KEY=tvly-your-key
 
 # Documentation tools
-export REF_TOOLS_API_KEY="your-key"
+REF_TOOLS_API_KEY=your-key
 ```
 
-## 📁 What Gets Installed
+## Customization & Pitfalls
 
-```
-your-project/
-├── .devcontainer/
-│   ├── devcontainer.json    # Container configuration
-│   ├── post-create.sh       # Development tools setup  
-│   └── post-start.sh        # MCP server installation
-└── (your existing files remain unchanged)
-```
+### The Good News
+ClaudePod is designed to be unbreakable. It uses smart configuration templates that preserve your customizations across container rebuilds.
 
-## 🏗️ Container Architecture
+### Common Gotchas
 
-- **Base**: Ubuntu 22.04
-- **User**: `node` (uid: 1000, gid: 1000)
-- **Workspace**: `/workspace` (your project files)
-- **Persistent Data**: Claude config, shell history, npm cache
-- **Network**: Host network for optimal development server performance
+**Override Flags** - ClaudePod has environment variables like `OVERRIDE_CLAUDE_SETTINGS=true` that can overwrite your customizations. Only use these if you want to reset to defaults.
 
-## 🔧 Customization
+**Port Conflicts** - If you run services on ports 8080, 3000, or 5000 locally, add port forwarding rules to avoid conflicts:
 
-After installation, you can modify `.devcontainer/devcontainer.json`:
+```json
+{
+  "forwardPorts": [3001, 8081, 5001],
+  "portsAttributes": {
+    "3001": { "label": "Your App" }
+  }
+}
+```
+
+**Configuration Complexity** - ClaudePod has many layers (devcontainer.json, .env, MCP templates, tool configs). Stick to editing `.devcontainer/.env` for most customizations.
+
+### Safe Customization
+
+Edit `.devcontainer/devcontainer.json` after installation:
 
 ```json
 {
@@ -145,45 +156,83 @@ After installation, you can modify `.devcontainer/devcontainer.json`:
     "vscode": {
       "extensions": ["your.extension.id"]
     }
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/aws-cli:1": {}
   }
 }
 ```
 
-## 🩺 Troubleshooting
+## Troubleshooting
 
+**Container won't start?**
 ```bash
-# Container not starting?
-devpod delete <workspace> && devpod up .
+devpod delete <workspace> && devpod up .  # <workspace> is your project folder name
+# Don't worry - this preserves your ClaudePod configuration and project files
+```
 
-# Claude not authenticated?
+**Claude authentication issues?**
+```bash
 claude login
+```
 
-# MCP servers not working?
+**MCP servers missing?**
+```bash
 claude mcp list
-claude mcp remove <server> && claude mcp add <server>
+# If empty, restart the container
+```
 
-# Check container health
-./scripts/health-check.sh
+**npm permission errors?**
+```bash
+# Inside container - fix npm permissions
+sudo chown -R node:node /home/node/.npm
+sudo chown -R node:node /home/node/.local
 ```
 
-## 📚 Documentation
+**Configuration got overwritten?**
+Look in `.devcontainer/config/backups/` - ClaudePod automatically backs up your configs before making changes.
 
-After installation, see:
-- `CLAUDE.md` - Complete container documentation
-- `examples/` - Configuration examples
-- `scripts/` - Helper scripts and utilities
+## Architecture
 
-## 🤝 Team Usage
+ClaudePod uses a two-phase setup:
+1. **post-create.sh** - Installs Claude Code, dev tools, and creates base configurations
+2. **post-start.sh** - Installs MCP servers and validates everything works
+
+The setup is idempotent - you can rebuild containers without losing your customizations (unless you use override flags).
+
+## Team Usage
+
+Perfect for teams who want consistent environments:
 
-Each team member runs:
 ```bash
+# Team member 1 sets up the project
 cd shared-project
-npx claudepod-devcontainer  # Installs .devcontainer
-devpod up .                 # Starts identical environment
+npx claudepod-devcontainer
+git add .devcontainer/ && git commit -m "Add ClaudePod"
+
+# Everyone else just runs
+devpod up .
 ```
 
-Perfect for ensuring consistent development environments across your team!
+Each developer gets an identical environment with the same Claude configuration, MCP servers, and tools.
+
+## What Gets Added
+
+```
+your-project/
+├── .devcontainer/
+│   ├── devcontainer.json           # Main container config
+│   ├── post-create.sh             # Tool installation
+│   ├── post-start.sh              # MCP server setup
+│   ├── .env.example               # API key template
+│   ├── config/
+│   │   ├── claude/                # Claude Code templates
+│   │   ├── serena/                # Serena config
+│   │   └── taskmaster/            # TaskMaster config
+│   └── scripts/                   # Modular setup scripts
+└── (your files stay exactly the same)
+```
 
 ---
 
-**Ready to supercharge your development with AI!** 🚀
+**Ready to code with AI superpowers?** ClaudePod turns any project into an AI-native development environment.