crush-sandbox 0.5.2

package/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to Crush Sandbox
+
+Thank you for your interest in contributing! We welcome contributions from everyone.
+
+## How to Contribute
+
+### Reporting Issues
+
+If you find a bug or have a feature request:
+
+1. Check existing [issues](https://github.com/wireless25/crush-sandbox/issues) to avoid duplicates
+2. Use the [issue template](https://github.com/wireless25/crush-sandbox/issues/new) if available
+3. Include:
+   - Steps to reproduce
+   - Expected behavior
+   - Actual behavior
+   - Environment information (macOS version, Docker version)
+
+### Submitting Pull Requests
+
+1. Fork the repository
+2. Create a branch for your changes:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. Make your changes
+4. Test thoroughly:
+   - Run `bash -n docker-sandbox-crush` to check syntax
+   - Test all commands: `./docker-sandbox-crush run`, `clean`, `install`
+   - Test with flags: `--version`, `--shell`, `--force`
+5. Commit your changes with clear messages
+6. Push to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+7. Open a pull request
+
+### Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/wireless25/crush-sandbox.git
+   cd crush-sandbox
+   ```
+
+2. Make the script executable:
+   ```bash
+   chmod +x docker-sandbox-crush
+   ```
+
+3. Test your changes:
+   ```bash
+   # Test help
+   ./docker-sandbox-crush
+
+   # Test version
+   ./docker-sandbox-crush --version
+
+   # Test syntax
+   bash -n docker-sandbox-crush
+   ```
+
+### Code Style
+
+- Follow existing bash conventions in the script
+- Use 4 spaces for indentation
+- Add comments for complex logic
+- Keep functions small and focused
+- Use descriptive variable names
+
+### Testing
+
+Since there are no automated tests, manual testing is essential:
+
+- Test on macOS (primary target)
+- Verify Docker Desktop is running
+- Test with multiple workspace directories
+- Test container reuse
+- Test cache persistence
+- Test with `--shell` flag for debugging
+
+### Documentation
+
+- Update README.md if you change user-facing behavior
+- Update AGENTS.md if you change internal architecture
+- Keep changelog for version changes
+
+## Guidelines
+
+### Do
+
+- Write clear, concise commit messages
+- Test your changes thoroughly
+- Update documentation
+- Be respectful and constructive
+
+### Don't
+
+- Make breaking changes without discussion
+- Add dependencies without justification
+- Change the project scope significantly without agreement
+- Commit sensitive information
+
+## Getting Help
+
+If you need help:
+1. Check the [README](README.md)
+2. Review existing issues and pull requests
+3. Ask questions in a new issue with the "question" label
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,515 @@
+# Crush Sandbox
+
+A lightweight bash wrapper that runs the [Crush CLI](https://github.com/charmbracelet/crush) in a Docker sandbox with persistent package manager caches. Perfect for isolating your development environment while keeping tools and dependencies cached per workspace.
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **macOS** (primary target)
+- **Docker Desktop** installed and running
+
+### Installation
+
+#### One-command installation (recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/wireless25/crush-sandbox/main/docker-sandbox-crush | sudo tee /usr/local/bin/crush-sandbox > /dev/null
+sudo chmod +x /usr/local/bin/crush-sandbox
+ln -s /usr/local/bin/crush-sandbox /usr/local/bin/crushbox
+```
+
+#### Manual installation
+
+1. Download the script:
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/wireless25/crush-sandbox/main/docker-sandbox-crush -o docker-sandbox-crush
+   ```
+
+2. Make it executable:
+   ```bash
+   chmod +x docker-sandbox-crush
+   ```
+
+3. Move it to your PATH:
+   ```bash
+   sudo mv docker-sandbox-crush /usr/local/bin/crush-sandbox
+   ```
+
+#### Install using the script itself
+
+If you've cloned the repository, you can use the built-in install command:
+
+```bash
+./docker-sandbox-crush install
+```
+
+This will:
+- Validate Docker is available
+- Install the script to `/usr/local/bin/crush-sandbox`
+- Create a `crushbox` alias symlink
+- Display version information for installed tools
+
+**Note:** gitleaks Docker image will be pulled automatically on first use for credential scanning. No additional installation is required.
+
+## ✨ Features
+
+- **Workspace isolation**: Each workspace directory gets its own sandbox container
+- **Persistent caches**: npm and pnpm caches persist per workspace for faster subsequent runs
+- **Automatic Crush CLI installation**: Crush CLI is installed automatically on first use
+- **Git config injection**: Your Git user.name and user.email are passed into the container
+- **Container reuse**: Containers are stopped but not removed, enabling fast restarts
+- **Debugging support**: Use `--shell` flag to get an interactive shell instead of Crush CLI
+- **Configuration support**: Automatically mounts and merges Crush configuration from host
+
+## ⚙️ Configuration
+
+The Docker sandbox automatically provides Crush CLI configuration:
+
+### Configuration Sources
+
+**Host configuration** (global defaults):
+- `~/.config/crush/`
+
+**Workspace configuration** (workspace-specific):
+- `.crush.json` or `crush.json` (relative to workspace root)
+
+If you maintain global Crush config with commands, skills, or settings, this will be mounted into the container. Any workspace-specific config will override these settings.
+Config files in the workspace are mounted into the container with the rest of the code and take precedence over host config by default in Crush. Make sure to configure your skills
+and commands accordingly. If you want to use global configured skills, add the `/tmp/crush-config/merged/skills` path to the skills option in the config (global on host or in workspace) to make Crush pick them up.
+
+**Example to include skills from global host in the config**:
+```json
+{
+  "$schema": "https://charm.land/crush.json",
+  "options": {
+    "skills_paths": [
+      "~/.config/crush/skills",
+      "/tmp/crush-config/merged/skills"
+    ]
+  }
+}
+```
+
+With this configuration, you can still use `crush` on your host machine with the same setup.
+
+### Configuration Merge Behavior
+
+1. Host configuration is copied to the container
+2. Workspace configuration is mounted with the workspace, **overwriting** host config (Crush default behavior)
+3. Host configuration is available at `/tmp/crush-config/merged` inside the container
+4. `CRUSH_GLOBAL_CONFIG` environment variable is set to this location
+
+This means workspace-specific settings always override global defaults.
+
+### Security
+
+- All configuration mounts are **read-only** (`:ro` flag)
+- The container cannot modify your host configuration files
+
+### Configuration Control Flags
+
+You can control configuration behavior with these flags:
+
+| Flag | Description |
+|------|-------------|
+| `--no-host-config` | Skip mounting host Crush config directory |
+
+**Examples**:
+
+```bash
+# Skip host configuration
+crush-sandbox run --no-host-config
+# Or use alias:
+crushbox run --no-host-config
+```
+
+### Configuration Directory Structure Example
+
+```
+~/.config/crush/                    # Host configuration (global)
+├── crush.json                     # Main Crush config
+└── skills                         # Skills directory
+└── commands                       # Commands directory
+```
+
+If you have a `crush.json` or `.crush.json` already in the workspace root, this will take precedence over the `.config/crush/` directory by Crush CLI's own behavior.
+
+## 📖 Usage
+
+### Start Crush CLI in a sandbox
+
+Navigate to your workspace directory and run:
+
+```bash
+crush-sandbox run
+```
+
+Or use the alias:
+
+```bash
+crushbox run
+```
+
+This will:
+1. Create (or reuse) a sandbox container for your workspace
+2. Mount your workspace at the same absolute path
+3. Install Crush CLI if not already installed
+4. Install pnpm for package management
+5. Start the Crush CLI
+
+### Start a debug shell
+
+If you need to debug or run manual commands:
+
+```bash
+crush-sandbox run --shell
+```
+
+Or with the alias:
+
+```bash
+crushbox run --shell
+```
+
+This gives you an interactive shell in the sandbox container instead of running Crush CLI.
+
+### Clean up the sandbox
+
+To remove the container and cache volume for the current workspace:
+
+```bash
+crush-sandbox clean
+```
+
+Or with the alias:
+
+```bash
+crushbox clean
+```
+
+Add `--force` to skip confirmation:
+
+```bash
+crush-sandbox clean --force
+```
+
+### Show version
+
+```bash
+crush-sandbox --version
+```
+
+### Update to latest version
+
+```bash
+crush-sandbox update
+```
+
+This will:
+- Check for the latest version on GitHub
+- Compare with your current version
+- Prompt for confirmation if a newer version is available
+- Download and replace the script automatically
+- Validate the downloaded script before installing
+
+### Get help
+
+```bash
+crush-sandbox --help
+```
+
+## 🔒 Security
+
+### Security Overview
+
+The docker-sandbox-crush tool implements several security controls to make AI-assisted development safe(er). However, the tool requires you to follow certain security practices to ensure safe operation.
+Crush asks for your permission before performing any operation, but if you use `--yolo` mode or use it programmatically with `crush run` in a ralph loop, you must be aware of the security implications.
+
+### Read-Write Workspace Access
+
+The Crush agent inside the container has **full read-write access** to your workspace files. This is intentional and necessary for the agent to:
+
+- Read and modify source code files
+- Run build commands and tests
+- Create new files and directories
+- Install packages and dependencies
+- Execute git operations
+
+**Security Implications:**
+
+1. **Trust the AI agent**: The agent can modify any file in your workspace
+2. **Credential exposure risk**: Never store secrets (API keys, passwords, tokens) in your workspace files
+3. **Review all changes**: Always review agent-generated changes
+4. **Use version control**: Git provides a safety net - you can revert any unwanted changes
+
+**Best Practices:**
+
+- Store credentials in:
+  - Environment variables
+  - Secret management tools
+  - CI/CD pipeline secrets (GitHub Actions Secrets, GitLab CI Variables)
+  - `.env` files that are gitignored
+- Never commit credentials to git
+- Use `.gitignore` to exclude files with secrets
+- Rotate credentials if they were ever committed accidentally
+
+### Git Branch Protection for Production
+
+When planning to use `--yolo` mode or use it programmatically with `crush run`, you should configure git branch protection to prevent direct pushes to production branches. This ensures:
+
+- All agent-generated code goes through a pull request process
+- Code review is required before merging
+- CI/CD checks must pass before merging
+- Unauthorized direct commits are blocked
+
+### What the Agent Can and Cannot Do
+
+#### Capabilities
+
+The Crush agent inside the sandbox container can:
+
+✅ **Read and write workspace files**
+- Full access to all files in the mounted workspace
+- Can create, modify, delete any file
+- Can execute any command within the workspace
+
+✅ **Run commands and scripts**
+- Execute build commands (npm build, cargo build, etc.)
+- Run tests (npm test, pytest, etc.)
+- Install packages (npm install, pip install, etc.)
+
+✅ **Make git operations**
+- Create commits
+- Create branches
+- Stage files
+- Push to remote repositories
+
+✅ **Access network resources**
+- Download dependencies from npm, PyPI, etc.
+- Make HTTP requests (if in code)
+- Clone other git repositories
+
+#### Limitations
+
+The Crush agent cannot:
+
+❌ **Access files outside the workspace**
+- Container is limited to mounted workspace directory
+- Cannot access your home directory (except workspace subdirectories)
+- Cannot access system files or other projects
+
+❌ **Run with elevated privileges**
+- Container runs as non-root user
+- Cannot install system packages globally
+- Cannot modify Docker host
+
+❌ **Escalate privileges**
+- Docker capabilities are dropped (except CHOWN and DAC_OVERRIDE)
+- Cannot gain root access
+- Cannot modify container configuration
+
+❌ **Access host resources directly**
+- No direct access to host network
+- No access to host filesystem beyond workspace
+- Cannot interact with other containers
+
+#### Security Controls in Place
+
+The tool implements these security controls:
+
+1. **Resource limits** - Prevents resource exhaustion attacks:
+   - Memory limited to 4GB
+   - CPU limited to 2 cores
+   - Process count limited to 100 PIDs
+
+2. **Non-root user** - Limits attack surface:
+   - Container runs as your UID/GID
+   - Cannot perform privileged operations
+
+3. **Capability dropping** - Reduces Linux capabilities:
+   - All capabilities dropped by default
+   - CHOWN and DAC_OVERRIDE added back (required for cache and workspace access)
+
+4. **Credential scanning** - Warns about exposed secrets:
+   - Scans workspace with gitleaks before starting
+   - gitleaks is automatically installed when you run `crush-sandbox run --cred-scan`
+   - Prompts you to continue or abort if credentials detected
+   - Can be bypassed with `--no-cred-scan` flag (use with caution)
+
+5. **Workspace isolation** - Prevents cross-project contamination:
+   - Each workspace has its own container
+   - Caches are per-workspace
+   - No shared state between workspaces
+
+## 🔧 How It Works
+
+### Workspace Isolation
+
+Each workspace directory (your current working directory) gets its own:
+- **Container**: Named `crush-sandbox-<hash>` where `<hash>` is derived from your workspace path
+- **Cache volume**: Named `crush-cache-<hash>` for persistent package manager caches
+
+This means different projects have completely isolated sandbox environments.
+
+### Container Lifecycle
+
+1. **Create**: Container is created from `node:18-alpine` base image
+2. **Configure**: Workspace and cache volumes are mounted, environment variables are set
+3. **Start**: Container is started
+4. **Use**: Crush CLI or shell runs inside the container
+5. **Stop**: Container is stopped when you exit (kept for reuse)
+
+Containers are **not removed** automatically, so subsequent starts are instant.
+
+### Cache Persistence
+
+The cache volume stores:
+- **npm cache**: `/workspace-cache/npm`
+- **pnpm store**: `/workspace-cache/pnpm/store`
+- **pnpm cache**: `/workspace-cache/pnpm/cache`
+
+This means:
+- Packages downloaded once stay cached
+- Switching workspaces switches cache volumes
+- Faster installs after the first run
+
+### Automatic Tool Installation
+
+On container startup:
+1. **Crush CLI**: Installed via `npm install -g @charmland/crush` (cached after first install)
+2. **pnpm**: Installed via `npm install -g pnpm` (uses npm cache)
+
+Installation happens automatically and silently on every container start, with fast-path checks to skip re-installation.
+
+## 📋 Examples
+
+### Typical workflow
+
+```bash
+# Navigate to your project
+cd ~/projects/my-app
+
+# Start Crush CLI in sandbox
+crush-sandbox run
+# Or use alias:
+# crushbox run
+
+# ... work with Crush CLI ...
+
+# When done, Crush CLI exits and container stops
+# Next time, container is reused (instant start)
+```
+
+### Using with different workspaces
+
+```bash
+cd ~/projects/project-a
+crush-sandbox run  # Uses crush-sandbox-<hash-a>
+
+cd ~/projects/project-b
+crush-sandbox run  # Uses crush-sandbox-<hash-b>
+```
+
+Each workspace has its own isolated environment.
+
+### Debugging setup issues
+
+```bash
+# Get a shell to check installation
+crush-sandbox run --shell
+# Or:
+crushbox run --shell
+
+# Inside the container:
+which crush          # Check if Crush CLI is installed
+pnpm --version       # Check pnpm version
+npm --version        # Check npm version
+```
+
+## 🐛 Troubleshooting
+
+### "docker daemon is not running or not accessible"
+
+**Problem**: Docker Desktop is not running.
+
+**Solution**: Start Docker Desktop and wait for it to be ready. Verify with:
+```bash
+docker info
+```
+
+### "Git user.name and user.email not configured"
+
+**Problem**: Git user configuration is missing.
+
+**Solution**: This is a warning, not an error. Add to `~/.gitconfig` if Crush CLI needs git operations:
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+### Crush CLI not working in container
+
+**Problem**: Crush CLI installation failed.
+
+**Solution**: Run with `--shell` flag to debug:
+```bash
+crush-sandbox run --shell
+# Then manually install:
+npm install -g @charmland/crush
+```
+
+### Cache not persisting
+
+**Problem**: Packages are re-downloaded every time.
+
+**Solution**: Verify cache volume exists:
+```bash
+docker volume ls | grep crush-cache
+```
+
+Check if volume is mounted:
+```bash
+docker inspect <container-name> | grep Mounts
+```
+
+### "Cannot write to /usr/local/bin" during install
+
+**Problem**: No write permissions to `/usr/local/bin`.
+
+**Solution**: Run with sudo:
+```bash
+sudo ./docker-sandbox-crush install
+```
+
+Or choose a different installation directory in your PATH.
+
+### Container name changes unexpectedly
+
+**Problem**: Different containers for the same project.
+
+**Solution**: Ensure you're in the same workspace directory. Container names are based on the current working directory (`pwd`).
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 🙋 Support
+
+If you encounter issues or have questions:
+1. Check the [Troubleshooting](#-troubleshooting) section above
+2. Search existing [GitHub Issues](https://github.com/wireless25/crush-sandbox/issues)
+3. [Open a new issue](https://github.com/wireless25/crush-sandbox/issues/new) with details
+
+## 🔗 Related
+
+- [Crush CLI](https://github.com/charmbracelet/crush) - The AI-powered CLI assistant
+- [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop) - Container runtime
+
+---
+
+Made with ❤️ for developers who love isolated environments