diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..bf4b709 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,341 @@ +# Linux Workspace - Project Documentation + +## Overview + +**Linux Workspace** is a comprehensive shell configuration and utility toolkit designed to quickly configure new Linux machines with development tools, environment initialization, and useful utility scripts. It provides a modular, source-able bootstrap system for both bash and fish shells. + +This is a **dotfiles & configuration management system** combined with a rich collection of utility scripts for system administration, development workflows, and daily convenience tasks. + +## Quick Start + +### Installation + +```bash +# Clone the repository +git clone ~/linux-workspace + +# Run the installer +cd ~/linux-workspace +./install.sh +``` + +The installer automatically: + +- Detects the workspace directory location +- Adds sourcing configuration to `~/.bashrc` +- Creates Fish shell configuration at `~/.config/fish/conf.d/lws.fish` + +### Manual Installation + +Add to your `~/.bashrc`: + +```bash +source /path/to/linux-workspace/bashrc +``` + +## Project Structure + +### Root Files + +- [bashrc](bashrc) - Main bootstrap file that initializes the entire workspace +- [fishrc](fishrc) - Fish shell configuration entry point +- [functions.sh](functions.sh) - Core utility functions used throughout the system +- [install.sh](install.sh) - Installation script for automated setup +- [.editorconfig](.editorconfig) - EditorConfig formatting standards + +### Key Directories + +#### [bin/](bin/) - Utility Scripts & Tools (45+ scripts) + +Collection of executable shell and Python scripts for various tasks: + +**Docker & Containers:** + +- [dcm](bin/dcm) - Advanced Docker Compose manager with dependency and health check features +- [docker-bridge](bin/docker-bridge), [docker-noroot](bin/docker-noroot) - Docker helpers + +**Development Tools:** + +- [gws](bin/gws) - Gradle wrapper shortcuts for Kotlin development +- [git-dif1](bin/git-dif1), [git-swl](bin/git-swl), [git-reset-master](bin/git-reset-master) - Git workflow utilities + +**System Utilities:** + +- [network-bandwidth](bin/network-bandwidth), [myip](bin/myip), [weather](bin/weather) - System info +- [lock-screen](bin/lock-screen), [suspend.sh](bin/suspend.sh), [battery](bin/battery) - System control +- [cs.sh](bin/cs.sh), [cheatsheet](bin/cheatsheet) - Cheatsheet lookup tools + +**Cloud & Infrastructure:** + +- [aws-login](bin/aws-login) - AWS authentication helper +- [vpn-home.sh](bin/vpn-home.sh) - VPN configuration + +**Remote Tools:** + +- [xmosh](bin/xmosh), [xcat](bin/xcat), [xvim](bin/xvim) - Remote execution helpers + +#### [rc/](rc/) - Shell Configuration Modules (23 files) + +Modular initialization scripts loaded during shell startup: + +**Core Setup:** + +- [01-init.fish](rc/01-init.fish) - Fish shell initialization +- [01-path.sh](rc/01-path.sh) - PATH initialization +- [02-aliases.sh](rc/02-aliases.sh) - Common command aliases +- [env.sh](rc/env.sh) - Environment variables (PAGER, EDITOR, MANPAGER) +- [bash-prompt.sh](rc/bash-prompt.sh) - Colored bash prompt + +**Language/Framework Initialization:** + +- [nvm.sh](rc/nvm.sh) - Node Version Manager +- [pyenv.sh](rc/pyenv.sh) - Python environment manager +- [cargo.sh](rc/cargo.sh) - Rust Cargo +- [dotnet.sh](rc/dotnet.sh) - .NET runtime +- [sdkman.sh](rc/sdkman.sh) - SDKMAN Java/Kotlin tooling +- [linuxbrew.sh](rc/linuxbrew.sh) - Homebrew for Linux + +**Development Tools:** + +- [ssh-agent.sh](rc/ssh-agent.sh) - SSH agent with WSL support +- [git-prompt.sh](rc/git-prompt.sh) - Git prompt decoration +- [direnv.sh](rc/direnv.sh) - Directory environment switching +- [docker.sh](rc/docker.sh) - Docker initialization +- [kubernetes.sh](rc/kubernetes.sh) - kubectl/k8s setup +- [claude-code.sh](rc/claude-code.sh) - Claude Code integration + +**Other Tools:** + +- [gocryptfs.sh](rc/gocryptfs.sh) - Encrypted filesystem +- [thefuck.sh](rc/thefuck.sh) - Command correction +- [enhancd.sh](rc/enhancd.sh) - Directory navigation enhancement + +#### [install/](install/) - Installation Scripts (24 files) + +Automated setup scripts for various tools: + +**Development:** + +- [git-prompt.sh](install/git-prompt.sh), [awscli.sh](install/awscli.sh) +- [docker-ce.sh](install/docker-ce.sh), [docker-compose-2.sh](install/docker-compose-2.sh) +- [go-tools.sh](install/go-tools.sh), [rust.sh](install/rust.sh) +- [npm.sh](install/npm.sh), [uv.sh](install/uv.sh) + +**Services:** + +- [k3s.sh](install/k3s.sh) - Lightweight Kubernetes +- [lazygit.sh](install/lazygit.sh) - Git UI +- [syncthing.sh](install/syncthing.sh) - File synchronization + +**Applications:** + +- [packages.sh](install/packages.sh) - Debian packages +- [sublime.sh](install/sublime.sh), [vivaldi.sh](install/vivaldi.sh) +- [pwsh.sh](install/pwsh.sh) - PowerShell + +#### [scripts/](scripts/) - Helper Scripts (16 files) + +Administrative and one-off scripts: + +- [git-config.sh](scripts/git-config.sh) - Git user/email configuration +- [bash-template.sh](scripts/bash-template.sh) - Script template +- [gnome-configuration.sh](scripts/gnome-configuration.sh) - GNOME settings automation +- [gradle-init-kotlin.sh](scripts/gradle-init-kotlin.sh) - Gradle Kotlin project setup +- [update-desktop-apps.sh](scripts/update-desktop-apps.sh) - Application updates + +#### [doc/](doc/) - Documentation (21 files) + +Reference guides and cheatsheets: + +- [bash.md](doc/bash.md) - Bash scripting guide +- [git.md](doc/git.md) - Git workflows +- [vim.md](doc/vim.md) - Vim editor tips +- [cheatsheet.md](doc/cheatsheet.md) - General commands +- [fzf.md](doc/fzf.md) - Fuzzy finder +- [kotlin-coding-guideline.md](doc/kotlin-coding-guideline.md) - Kotlin style guide +- [gnome.md](doc/gnome.md) - GNOME customization + +#### [conf/](conf/) - Configuration Files + +- [gnome-shortcuts.conf](conf/gnome-shortcuts.conf) - Keyboard shortcuts +- [gradle.properties](conf/gradle.properties) - Gradle build config +- [wsl.conf](conf/wsl.conf) - WSL settings +- [wg-home.conf](conf/wg-home.conf) - WireGuard VPN +- [packages.txt](conf/packages.txt) - Recommended Debian packages +- [applications/](conf/applications/) - Application configs +- [dircolors/](conf/dircolors/) - Directory coloring schemes +- [vim/](conf/vim/) - Vim configurations + +#### [src/](src/) - Source Projects + +- [battery/](src/battery/) - Python project for reading notebook battery information + +## Key Features + +### Bootstrap System + +- **Single-entry point**: [bashrc](bashrc) sources [functions.sh](functions.sh) and loads all `.sh` files from `rc/` +- **Modular design**: Each tool has its own configuration file +- **Performance optimization**: `LWS_FAST=1` environment variable for fast initialization +- **Debug mode**: `LWS_DEBUG=1` for troubleshooting +- **Reloadable**: `reload-workspace` alias to refresh configuration + +### Core Functions + +The [functions.sh](functions.sh) file provides essential utilities: + +- `append_path()`, `prepend_path()` - PATH manipulation with duplicate prevention +- `source_directory()`, `source_directory_sh()` - Smart recursive sourcing +- `is_fast_init()`, `is_slow_init()` - Performance-based initialization +- `can_run()`, `is_alias()` - Command availability checks +- `is_wsl()` - Windows Subsystem for Linux detection +- `xlog()` - Conditional debug logging + +### Common Aliases + +Defined in [rc/02-aliases.sh](rc/02-aliases.sh): + +- Directory: `ll`, `la` (enhanced listing) +- Docker: `dc` (docker-compose), `dcl` (logs) +- Navigation: `..`, `...`, `....`, `cdd` (Downloads) +- Time: `now`, `nowsql`, `sqldate` +- Kubernetes: `kl`, `kld`, `klg` +- System: `ssha` (ssh-agent) + +### SSH Agent Integration + +The [rc/ssh-agent.sh](rc/ssh-agent.sh) module provides: + +- **WSL-aware**: Special handling for Windows Subsystem for Linux +- **Multi-key support**: Checks for both id_ecdsa and id_rsa +- **Auto-start**: Automatically starts ssh-agent if not running +- **Keychain fallback**: Uses keychain for non-WSL systems + +### Docker Integration + +The [bin/dcm](bin/dcm) script offers advanced Docker Compose management: + +- Service dependency tracking +- Health check polling (HTTP, TCP, Redis, etc.) +- Parallel builds +- Logging filtering +- Service startup orchestration + +### Gradle Integration + +The [bin/gws](bin/gws) tool provides shortcuts for common Gradle tasks: + +- Build shortcuts: `c` (clean), `b` (build), `t` (test) +- Combined: `cb` (clean+build), `cbt` (clean+build+test) +- Skip options: `-nd` (no detekt), `-nt` (no tests) +- Java-specific: `jar` (shadowJar), `br` (bootRun) + +## Environment Variables + +### Core Variables + +- `$LWS` - Root directory of Linux Workspace +- `$WORKSPACE` - Alias for LWS + +### Configuration Flags + +- `LWS_DEBUG=1` - Enable debug logging +- `LWS_FAST=1` - Fast initialization (skip slow tools) + +### Tool Customization + +- `DC`, `DCF` - Docker Compose customization +- `EDITOR` - Default text editor +- `PAGER` - Default pager (less) + +## Important Commands + +- `reload-workspace` - Reload all configurations +- `clws` - Change directory to workspace +- `dcm` - Docker Compose manager +- `gws` - Gradle wrapper shortcuts + +## Configuration Strategy + +The project uses an **environment-first** approach: + +1. **Staged initialization**: Tools load based on `LWS_FAST` flag +2. **Conditional loading**: Tools only initialize if directories exist +3. **WSL detection**: Special paths and behaviors for Windows Subsystem for Linux +4. **Path deduplication**: Removes duplicate PATH entries +5. **EditorConfig standardization**: Consistent coding standards + +## Use Cases + +1. **Rapid environment setup** for new Linux machines +2. **Consistent shell configuration** across multiple systems +3. **Development tool management** (Node, Python, Rust, Go, Java) +4. **Docker/Kubernetes workflows** with helper utilities +5. **Git workflow automation** +6. **System administration** utilities and scripts +7. **Personal workspace customization** with modular components + +## Customization + +### Adding New Modules + +1. Create a new `.sh` file in [rc/](rc/) +2. Add your configuration or aliases +3. Reload with `reload-workspace` + +### Adding New Scripts + +1. Create executable script in [bin/](bin/) +2. Make it executable: `chmod +x bin/yourscript` +3. Script is automatically available in PATH + +### Disabling Modules + +Move unwanted modules from [rc/](rc/) to [rc.available/](rc.available/) + +## Dependencies + +The workspace intelligently detects and initializes available tools: + +- **Required**: bash, git +- **Optional**: docker, kubectl, nvm, pyenv, cargo, direnv, etc. +- **Detection**: Each module checks for tool availability before initialization + +## WSL Support + +Special handling for Windows Subsystem for Linux: + +- SSH agent integration with Windows +- Path adjustments for Windows interoperability +- WSL-specific configurations in [conf/wsl.conf](conf/wsl.conf) + +## Performance + +- **Fast mode**: Set `LWS_FAST=1` to skip heavy initializations +- **Lazy loading**: Tools only load when directories exist +- **Optimized PATH**: Deduplication prevents PATH bloat + +## Contributing + +This is a personal workspace configuration, but improvements are welcome: + +1. Follow existing naming conventions +2. Keep scripts modular and self-contained +3. Test on fresh installations +4. Document new features in appropriate [doc/](doc/) files + +## License + +Personal project - use and modify as needed for your own workspace. + +## Recent Changes + +- Installation script improvements +- Enhanced `ll` and `la` aliases +- SSH agent fixes for WSL +- Fish shell integration +- Addition of new tools (Claude Code, Gemini CLI) + +## Support + +For issues or questions, refer to the documentation in [doc/](doc/) or examine the relevant configuration files in [rc/](rc/).