@bostonuniversity/buwp-local 0.1.0

package/PROJECT_OVERVIEW.md

@@ -0,0 +1,307 @@
+# buwp-local - Project Overview
+
+A complete **npm CLI package** for managing local WordPress development environments at Boston University. It's modeled after `@wordpress/env` (wp-env) but customized for BU's specific infrastructure needs.
+
+## Architecture
+
+### Package Structure
+
+```
+buwp-local/
+├── bin/
+│   └── buwp-local.js           # CLI entry point (commander-based)
+├── lib/
+│   ├── index.js                # Main library exports
+│   ├── config.js               # Configuration management
+│   ├── compose-generator.js    # Docker Compose generation (uses js-yaml)
+│   └── commands/
+│       ├── start.js            # Start environment
+│       ├── stop.js             # Stop environment
+│       ├── destroy.js          # Destroy environment
+│       ├── logs.js             # View logs
+│       └── config.js           # Config management
+├── package.json
+├── USAGE.md                    # User documentation
+└── README.md
+```
+
+### Key Technologies
+
+- **commander** - CLI framework
+- **js-yaml** - Docker Compose generation
+- **chalk** - Terminal colors/formatting
+- **dotenv** - Environment variable management
+
+## How It Works
+
+### 1. Configuration Management (`lib/config.js`)
+
+Loads and merges configuration from three sources (in priority order):
+1. Environment variables (`.env.local`)
+2. User config (`.buwp-local.json`)
+3. Default config
+
+Features:
+- Deep merge of configuration objects
+- Validation with detailed error messages
+- Sensitive data masking
+- Path resolution for volume mappings
+
+### 2. Docker Compose Generation (`lib/compose-generator.js`)
+
+Programmatically generates `docker-compose.yml` files based on configuration:
+- Creates services: WordPress, MariaDB, Redis, S3 proxy
+- Configures networking and volumes
+- Injects environment variables
+- Handles conditional services (can disable Redis, S3, etc.)
+- Generates volume mappings from config
+
+Generated file is placed in `.buwp-local/docker-compose.yml` (gitignored).
+
+### 3. CLI Commands (`bin/buwp-local.js` + `lib/commands/`)
+
+#### `buwp-local start [options]`
+- Loads configuration
+- Validates config
+- Generates docker-compose.yml
+- Starts Docker containers
+- Shows access URLs and next steps
+
+Options:
+- `--xdebug` - Enable Xdebug
+- `--no-s3` - Disable S3 proxy
+- `--no-redis` - Disable Redis
+
+#### `buwp-local stop`
+- Stops running containers (preserves data)
+
+#### `buwp-local destroy [options]`
+- Stops and removes containers AND volumes
+- Prompts for confirmation (unless `--force`)
+- **WARNING**: Deletes database data
+
+#### `buwp-local logs [options]`
+- View container logs
+- `-f, --follow` - Follow log output
+- `-s, --service <name>` - Show specific service logs
+
+#### `buwp-local config [options]`
+- `--init` - Create `.buwp-local.json`
+- `--validate` - Validate configuration
+- `--show` - Display resolved config (masks secrets)
+
+## Configuration File Structure
+
+### `.buwp-local.json` (committed to repo)
+
+```json
+{
+  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
+  "hostname": "wordpress.local",
+  "multisite": true,
+  "services": {
+    "redis": true,
+    "s3proxy": true,
+    "shibboleth": true
+  },
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306,
+    "redis": 6379
+  },
+  "mappings": [
+    {
+      "local": "./",
+      "container": "/var/www/html/wp-content/plugins/my-plugin"
+    }
+  ],
+  "env": {
+    "WP_DEBUG": true,
+    "XDEBUG": false
+  }
+}
+```
+
+### `.env.local` (NEVER committed - gitignored)
+
+```bash
+# Database credentials
+WORDPRESS_DB_PASSWORD=password
+DB_ROOT_PASSWORD=rootpassword
+
+# Shibboleth certificates
+SP_ENTITY_ID=https://your-entity-id
+IDP_ENTITY_ID=https://shib-test.bu.edu/idp/shibboleth
+SHIB_IDP_LOGOUT=https://shib-test.bu.edu/idp/logout.jsp
+SHIB_SP_KEY=your-private-key
+SHIB_SP_CERT=your-certificate
+
+# AWS credentials
+S3_UPLOADS_BUCKET=your-bucket
+S3_UPLOADS_REGION=us-east-1
+S3_UPLOADS_ACCESS_KEY_ID=AKIA...
+S3_UPLOADS_SECRET_ACCESS_KEY=secret...
+
+# OLAP configuration
+OLAP=your-olap
+OLAP_ACCT_NBR=123456
+OLAP_REGION=us-east-1
+```
+
+## Security Model
+
+### Current Implementation (Phase 1)
+- **Environment variables** via `.env.local` (gitignored)
+- **Config masking** when displaying configuration
+- **Clear separation** between config (committed) and secrets (local-only)
+
+### Future Enhancements (Phase 2-3)
+- macOS Keychain integration
+- Windows Credential Manager support
+- AWS SSO integration for temporary credentials
+- Encrypted credential storage
+
+## Usage Workflow
+
+### For Plugin/Theme Development
+
+1. Clone your plugin/theme repo
+2. Install: `npm install --save-dev buwp-local`
+3. Initialize: `npx buwp-local config --init`
+4. Edit `.buwp-local.json` to map current directory to WordPress location
+5. Create `.env.local` with credentials
+6. Add hostname to `/etc/hosts`
+7. Start: `npx buwp-local start`
+8. Develop with live code sync via volume mapping
+
+### For Multiple Repos
+
+Each repo can have its own `.buwp-local.json` with different:
+- Hostnames (site1.local, site2.local, etc.)
+- Port mappings (avoid conflicts)
+- Volume mappings (different plugins/themes)
+- Service configurations
+
+## Testing Results ✅
+
+Tested successfully:
+- [x] CLI entry point works
+- [x] `config --init` creates configuration file
+- [x] `config --show` displays resolved config with masking
+- [x] Help command shows all available commands
+- [x] Dependencies installed correctly
+- [x] File structure created properly
+
+## What's Ready Now
+
+### Phase 1 Complete ✅
+- [x] Full CLI infrastructure
+- [x] Configuration management system
+- [x] Docker Compose generation
+- [x] All core commands (start, stop, destroy, logs, config)
+- [x] Environment variable credential handling
+- [x] Volume mapping support
+- [x] Service toggles (enable/disable Redis, S3, etc.)
+- [x] Comprehensive documentation
+
+### Ready to Test
+You can now:
+1. Create a test project
+2. Install buwp-local as dependency
+3. Initialize configuration
+4. Add credentials to `.env.local`
+5. Run `npx buwp-local start`
+6. Develop against live WordPress environment
+
+## Next Phase Recommendations
+
+### Phase 2 Features
+1. **WP-CLI Proxy** - Run WP-CLI commands in container
+   - `npx buwp-local wp plugin list`
+   - `npx buwp-local wp db export`
+
+2. **macOS Keychain Integration**
+   - Use `security` command or `keytar` npm package
+   - Store/retrieve credentials securely
+   - Cross-platform support
+
+3. **Better Volume Sync**
+   - Watch for file changes
+   - Automatic permission fixing
+   - Better error messages for mapping issues
+
+4. **Health Checks**
+   - Wait for WordPress to be ready
+   - Database connection verification
+   - Service status checking
+
+### Phase 3 Features
+1. **Auto /etc/hosts Management** (requires sudo)
+2. **SSL Certificate Generation** (mkcert)
+3. **Preset Configurations** (common setups)
+4. **Update Management** (keep base image current)
+5. **Backup/Restore** (database snapshots)
+
+## Advantages Over Manual Docker Compose
+
+1. **Abstraction** - Users don't need to understand Docker Compose
+2. **Validation** - Config is validated before starting
+3. **Flexibility** - Easy to enable/disable services
+4. **Secrets Management** - Clear separation of config and credentials
+5. **Reproducibility** - Same environment for all team members
+6. **Version Control** - Configuration is version controlled, generated files are not
+7. **Ease of Use** - Simple commands for common tasks
+
+## Distribution Options
+
+### Option 1: Private npm Registry
+- Publish to BU's internal registry
+- `npm install @bu/wp-local`
+
+### Option 2: GitHub Packages
+- Publish to GitHub Packages
+- Scoped package: `@bu-ist/wp-local`
+
+### Option 3: Git Direct Install
+- Install from Git repo: `npm install git+https://github.com/bu-ist/buwp-local.git`
+
+### Option 4: Local Development
+- Use `npm link` for testing
+- Share via file path: `npm install file:../buwp-local`
+
+## Testing Strategy
+
+1. **Unit Tests** (add in future)
+   - Test config merging
+   - Test validation logic
+   - Test compose generation
+
+2. **Integration Tests**
+   - Test with actual Docker
+   - Test full start/stop/destroy cycle
+   - Test with different configurations
+
+3. **User Testing**
+   - Start with 2-3 developers
+   - Gather feedback on UX
+   - Iterate on configuration schema
+   - Expand to larger team
+
+## Success Metrics
+
+- **Setup Time**: < 10 minutes from clone to running environment
+- **Support Requests**: Reduced Docker-related questions
+- **Adoption Rate**: 20/20 team members using it
+- **Configuration Errors**: Caught before starting Docker
+- **Developer Satisfaction**: Positive feedback on ease of use
+
+## Current Status
+
+**Ready for initial testing!** 🎉
+
+The core functionality is complete. You can now:
+- Test it locally with real projects
+- Get feedback from a small group
+- Iterate on the configuration schema
+- Add Phase 2 features based on real usage

package/QUICK_REFERENCE.md

@@ -0,0 +1,234 @@
+# Quick Reference - New Features
+
+## Smart Initialization
+
+### Plugin Development
+```bash
+cd your-plugin-directory
+buwp-local config --init --plugin
+```
+Auto-creates: `./` → `/var/www/html/wp-content/plugins/your-plugin-directory`
+
+### Theme Development
+```bash
+cd your-theme-directory
+buwp-local config --init --theme
+```
+Auto-creates: `./` → `/var/www/html/wp-content/themes/your-theme-directory`
+
+### MU-Plugin Development
+```bash
+cd your-mu-plugin-directory
+buwp-local config --init --mu-plugin
+```
+Auto-creates: `./` → `/var/www/html/wp-content/mu-plugins/your-mu-plugin-directory`
+
+---
+
+## Multi-Project Setup
+
+### Quick Start - 3 Projects
+```bash
+# Project 1 (default ports)
+cd ~/projects/plugin-a
+buwp-local config --init --plugin
+buwp-local start
+
+# Project 2 (different ports)
+cd ~/projects/plugin-b
+buwp-local config --init --plugin
+# Edit .buwp-local.json - change http: 8081, db: 3308, redis: 6381
+buwp-local start
+
+# Project 3 (different ports)
+cd ~/projects/theme-c
+buwp-local config --init --theme
+# Edit .buwp-local.json - change http: 8082, db: 3309, redis: 6382
+buwp-local start
+```
+
+### Add Hostnames
+```bash
+sudo bash -c 'cat >> /etc/hosts << EOF
+127.0.0.1 plugin-a.local
+127.0.0.1 plugin-b.local
+127.0.0.1 theme-c.local
+EOF'
+```
+
+### Access Your Sites
+- http://plugin-a.local
+- http://plugin-b.local:8081
+- http://theme-c.local:8082
+
+---
+
+## Shared Environment (Centralized Sandbox)
+
+### Multiple Repos, One WordPress
+
+Set the **same `projectName`** in multiple repos to share one environment:
+
+```bash
+# Plugin A
+cd ~/projects/plugin-a
+buwp-local config --init --plugin
+# Edit .buwp-local.json: "projectName": "bu-sandbox"
+buwp-local start
+
+# Plugin B (joins same environment)
+cd ~/projects/plugin-b
+buwp-local config --init --plugin
+# Edit .buwp-local.json: "projectName": "bu-sandbox"  # SAME!
+buwp-local start
+
+# Both plugins now in same WordPress at http://bu-sandbox.local
+```
+
+### When to Use
+
+**Isolated (Different projectName):**
+- Solo development
+- Independent testing
+- Need clean slate
+
+**Shared (Same projectName):**
+- Integration testing
+- Team collaboration
+- Plugin interactions
+- Full-stack development
+
+See `SHARED_ENVIRONMENT_EXAMPLES.md` for detailed examples.
+
+---
+
+## Key Concepts
+
+### Project Names
+- **Auto-generated** from directory name
+- **Sanitized** for Docker (lowercase, alphanumeric + dash/underscore)
+- **Shows in Docker Desktop** for easy identification
+
+### Volume Isolation
+Each project gets its own:
+- `{projectName}_db_data` - Database
+- `{projectName}_wp_build` - WordPress files
+
+### Port Configuration
+Default ports:
+```json
+{
+  "ports": {
+    "http": 80,
+    "https": 443,
+    "db": 3306,
+    "redis": 6379
+  }
+}
+```
+
+For multiple projects, change to avoid conflicts:
+```json
+{
+  "ports": {
+    "http": 8081,
+    "https": 8444,
+    "db": 3308,
+    "redis": 6381
+  }
+}
+```
+
+---
+
+## Common Commands
+
+```bash
+# Initialize with smart mapping
+buwp-local config --init --plugin
+
+# Start project
+buwp-local start
+
+# Stop project (keeps data)
+buwp-local stop
+
+# View logs
+buwp-local logs -f
+
+# Destroy project (deletes data)
+buwp-local destroy
+
+# Show configuration
+buwp-local config --show
+
+# Validate configuration
+buwp-local config --validate
+```
+
+---
+
+## Troubleshooting
+
+### Port Already in Use
+Edit `.buwp-local.json`:
+```json
+{
+  "ports": {
+    "http": 8081,  // Change from 80
+    "db": 3308     // Change from 3306
+  }
+}
+```
+
+### Project Name Conflict
+Edit `.buwp-local.json`:
+```json
+{
+  "projectName": "my-unique-name"
+}
+```
+
+### Check Active Projects
+```bash
+docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
+```
+
+### List All Volumes
+```bash
+docker volume ls | grep -E '(db_data|wp_build)'
+```
+
+---
+
+## Best Practices
+
+✅ Use smart init flags (`--plugin`, `--theme`, `--mu-plugin`)  
+✅ Use descriptive directory names (they become project names)  
+✅ Keep `.env.local` secret (never commit)  
+✅ Assign unique ports for each project  
+✅ Document your port assignments  
+✅ Add all hostnames to `/etc/hosts`
+
+---
+
+## What's New
+
+| Feature | Before | Now |
+|---------|--------|-----|
+| **Project Naming** | All projects called "buwp-local" | Each project has unique name |
+| **Docker Desktop** | Can't distinguish projects | Clear project separation |
+| **Database** | Shared between all projects | Isolated per project |
+| **Volume Management** | Shared `db_data` and `wp_build` | Project-specific volumes |
+| **Multi-Project** | ❌ Second project overwrites first | ✅ Multiple projects run together |
+| **Configuration** | Manual path typing | Auto-generated smart mappings |
+| **Setup Time** | ~5 minutes | ~30 seconds |
+
+---
+
+## Need Help?
+
+- 📖 Full documentation: `MULTI_PROJECT_GUIDE.md`
+- 🔧 Implementation details: `IMPLEMENTATION_SUMMARY.md`
+- 📚 Usage guide: `USAGE.md`
+- ℹ️  CLI help: `buwp-local --help`