@bostonuniversity/buwp-local 0.6.3 → 0.7.0

package/ROADMAP.md

@@ -1,363 +0,0 @@
-# buwp-local Development Roadmap
-
-This is a historical document, see the current roadmap in the `docs/ROADMAP.md` file.
-
-## ✅ Phase 1: Core Infrastructure (Complete)
-
-**Status:** Shipped ✅  
-**Date:** November 2025
-
-### Features Delivered
-- [x] CLI framework with Commander.js
-- [x] Configuration management system
-- [x] Docker Compose generation with js-yaml
-- [x] Core commands: start, stop, destroy, logs, config
-- [x] Environment variable support (.env.local)
-- [x] Volume mapping for local development
-- [x] Service toggles (Redis, S3, Shibboleth)
-- [x] Configuration validation
-- [x] Comprehensive documentation
-
-### Outcome
-**20+ developers** can set up local WordPress environments with a single command.
-
----
-
-## ✅ Phase 1.5: Multi-Project Support (Complete)
-
-**Status:** Shipped ✅  
-**Date:** November 2025  
-**Trigger:** Real-world testing feedback
-
-### Features Delivered
-- [x] **Unique project names** - Based on directory name
-- [x] **Isolated volumes** - Each project gets own database and WordPress
-- [x] **Smart config initialization**
-  - [x] `--plugin` flag for plugin development
-  - [x] `--mu-plugin` flag for mu-plugin development
-  - [x] `--theme` flag for theme development
-- [x] **Auto-generated mappings** - Correct paths without manual typing
-- [x] **Multi-project documentation** - Complete usage guide
-
-### Outcome
-Developers can **run multiple projects simultaneously** with complete isolation.
-
----
-
-## 🚀 Phase 2: Developer Experience (Planned)
-
-**Status:** In Planning  
-**Timeline:** 2-4 weeks  
-**Priority:** High
-
-### Proposed Features
-
-#### 2.1 WP-CLI Proxy ⭐
-```bash
-buwp-local wp plugin list
-buwp-local wp db export backup.sql
-buwp-local wp user create testuser test@example.com
-```
-**Impact:** Direct WordPress CLI access without Docker exec  
-**Effort:** Low (2-3 days)
-
-#### 2.2 Project Listing
-```bash
-buwp-local list
-# Output:
-# ACTIVE PROJECTS:
-# ├─ bu-custom-analytics (http://bu-custom-analytics.local)
-# ├─ bu-slideshow (http://bu-slideshow.local:8081)
-# └─ responsive-framework (http://responsive-framework.local:8082)
-```
-**Impact:** Quick overview of running projects  
-**Effort:** Low (1-2 days)
-
-#### 2.3 Health Checks & Status
-```bash
-buwp-local status
-# Output:
-# Project: bu-custom-analytics
-# Status: Running
-# WordPress: Ready (v6.4)
-# Database: Connected
-# Services: wordpress, db, redis, s3proxy
-# URLs: http://bu-custom-analytics.local
-```
-**Impact:** Better visibility into project state  
-**Effort:** Medium (3-4 days)
-
-#### 2.4 Auto-Port Assignment
-```bash
-buwp-local config --init --plugin --auto-ports
-# Automatically finds available ports
-# Suggests non-conflicting port configuration
-```
-**Impact:** Eliminates port conflict errors  
-**Effort:** Medium (3-4 days)
-
-#### 2.5 Enhanced Credential Management
-- macOS Keychain integration (using `security` command)
-- Windows Credential Manager support
-- Cross-platform credential storage
-- Secure credential prompts
-
-**Impact:** Better security, easier credential management  
-**Effort:** High (5-7 days)
-
-### Team Testing Needed
-Before Phase 2 implementation, gather feedback on:
-- Which features are most valuable?
-- Pain points in current workflow?
-- Additional features needed?
-
----
-
-## 🔮 Phase 3: Advanced Features (Future)
-
-**Status:** Conceptual  
-**Timeline:** TBD  
-**Priority:** Medium
-
-### Potential Features
-
-#### 3.1 Automatic /etc/hosts Management
-```bash
-buwp-local start
-# Automatically adds hostname to /etc/hosts (requires sudo)
-# Removes on destroy
-```
-**Consideration:** Requires elevated permissions
-
-#### 3.2 SSL Certificate Generation
-```bash
-buwp-local config --ssl
-# Generates local SSL certificates with mkcert
-# Enables HTTPS without browser warnings
-```
-**Consideration:** Requires mkcert installation
-
-#### 3.3 Database Backup & Restore
-```bash
-buwp-local backup
-buwp-local restore backup-2025-11-10.sql
-buwp-local backup --auto  # Daily automatic backups
-```
-
-#### 3.4 Preset Configurations
-```bash
-buwp-local config --init --preset bu-standard
-# Loads common BU settings
-# Pre-configured services
-# Standard environment variables
-```
-
-#### 3.5 Project Templates
-```bash
-buwp-local create my-new-plugin --template bu-plugin
-# Scaffolds new plugin with BU conventions
-# Includes composer.json, phpunit.xml, etc.
-```
-
-#### 3.6 Performance Monitoring
-```bash
-buwp-local monitor
-# Real-time performance metrics
-# Query times, memory usage, cache hits
-```
-
-#### 3.7 Team Sync
-```bash
-buwp-local sync --remote bu-shared-config
-# Sync configuration with team repository
-# Share common settings across team
-```
-
-#### 3.8 Plugin/Theme Dependency Management
-```bash
-buwp-local deps install
-# Installs required plugins/themes
-# Based on .buwp-deps.json configuration
-```
-
----
-
-## 🎯 Success Metrics
-
-### Current (Phase 1-1.5)
-- ✅ Setup time: < 2 minutes (from clone to running)
-- ✅ Team adoption: 3-5 early adopters testing
-- ✅ Multi-project support: Yes
-- ✅ Documentation: Complete
-
-### Phase 2 Targets
-- Setup time: < 1 minute
-- Team adoption: 15+ active users
-- Support tickets: < 2 per week
-- Developer satisfaction: > 85% positive
-
-### Phase 3 Targets
-- Setup time: < 30 seconds
-- Team adoption: 20+ active users
-- Zero-config experience
-- Self-service onboarding
-
----
-
-## 📊 Feature Priority Matrix
-
-### High Priority (Do Next)
-1. **WP-CLI Proxy** - Frequently requested, high value
-2. **Project Listing** - Visibility into running projects
-3. **Health Checks** - Troubleshooting aid
-
-### Medium Priority (Nice to Have)
-4. **Auto-Port Assignment** - Reduces friction
-5. **Credential Management** - Better security
-6. **Database Backup** - Data safety
-
-### Low Priority (Future)
-7. **SSL Certificates** - Better local HTTPS
-8. **/etc/hosts Management** - Convenience feature
-9. **Presets & Templates** - Standardization
-10. **Team Sync** - Large team coordination
-
----
-
-## 🤝 Community Feedback Needed
-
-### Questions for Team
-1. **What's your biggest pain point** with current version?
-2. **Which Phase 2 feature** would help you most?
-3. **What's missing** from current feature set?
-4. **How often** do you work on multiple projects?
-5. **What takes the most time** in your setup process?
-
-### How to Provide Feedback
-- GitHub Issues
-- Team Slack/Chat
-- Email to maintainers
-- Quick survey (to be created)
-
----
-
-## 🛠️ Technical Debt & Maintenance
-
-### Current
-- [ ] Add unit tests for core functions
-- [ ] Add integration tests for Docker operations
-- [ ] Set up CI/CD pipeline
-- [ ] Automated version bumping
-- [ ] Changelog automation
-
-### Future
-- [ ] Error handling improvements
-- [ ] Logging system
-- [ ] Telemetry (opt-in)
-- [ ] Update checking
-- [ ] Deprecation warnings
-
----
-
-## 📈 Adoption Strategy
-
-### Phase 1 (Current)
-- ✅ Working with 3-5 early adopters
-- ✅ Gathering feedback
-- ✅ Documenting common issues
-- ✅ Iterating on UX
-
-### Phase 2 (Next 2-4 Weeks)
-- Expand to 10-15 users
-- Create video tutorials
-- Office hours / Q&A sessions
-- Document best practices from real usage
-
-### Phase 3 (1-2 Months)
-- Full team rollout (20+ developers)
-- Self-service documentation
-- Automated onboarding
-- Community support channel
-
----
-
-## 🎓 Learning & Iteration
-
-### What We Learned So Far
-1. **Multi-project support was critical** - Came from real usage
-2. **Smart init flags save time** - No manual path configuration
-3. **Good defaults matter** - Auto-generated project names work well
-4. **Documentation is key** - Comprehensive guides prevent questions
-
-### What We'll Track
-- Most used commands
-- Common error messages
-- Configuration patterns
-- Support questions
-
-### How We'll Improve
-- Quarterly feature reviews
-- User surveys
-- Usage analytics (opt-in)
-- Regular team check-ins
-
----
-
-## 🚢 Release Strategy
-
-### Semantic Versioning
-- `v0.x.x` - Beta/testing phase (current)
-- `v1.0.0` - Full production release (after team adoption)
-- `v1.x.x` - Feature additions
-- `v2.0.0` - Major changes (if needed)
-
-### Current Version
-**v0.2.0** - Multi-project support
-
-### Planned Versions
-- `v0.3.0` - Phase 2 features (WP-CLI, listing, health)
-- `v0.4.0` - Phase 2 cont. (ports, credentials)
-- `v1.0.0` - Production ready (full team rollout)
-
----
-
-## 📞 Support & Resources
-
-### Documentation
-- **Quick Start:** `README.md`
-- **Full Usage:** `USAGE.md`
-- **Multi-Project:** `MULTI_PROJECT_GUIDE.md`
-- **Quick Reference:** `QUICK_REFERENCE.md`
-- **Implementation Details:** `IMPLEMENTATION_SUMMARY.md`
-- **This Roadmap:** `ROADMAP.md`
-
-### Getting Help
-- Check documentation first
-- Search existing issues
-- Ask in team chat
-- Create GitHub issue
-- Contact maintainers
-
-### Contributing
-- Report bugs
-- Suggest features
-- Submit PRs
-- Improve documentation
-- Share usage patterns
-
----
-
-## 🎉 Conclusion
-
-We've built a **solid foundation** for BU WordPress local development. The tool now supports:
-- ✅ Easy single-project setup
-- ✅ Multi-project workflows
-- ✅ Team collaboration
-- ✅ Enterprise scalability
-
-**Next steps:**
-1. Continue gathering feedback from early adopters
-2. Prioritize Phase 2 features based on team needs
-3. Expand adoption gradually
-4. Iterate and improve based on real usage
-

package/USAGE.md

@@ -1,324 +0,0 @@
-# buwp-local Development Guide
-
-## Quick Start
-
-### 1. Install in your project
-
-```bash
-npm install --save-dev @bostonuniversity/buwp-local
-```
-
-### 2. Initialize configuration
-
-**Interactive mode (recommended):**
-```bash
-npx buwp-local init
-```
-
-The interactive setup will guide you through:
-- Project name and type (plugin, theme, mu-plugin)
-- Hostname configuration
-- Port selection
-- Service options (Redis, S3, Shibboleth)
-- Debug settings
-
-**Non-interactive mode:**
-```bash
-npx buwp-local config --init --plugin      # For plugins
-npx buwp-local config --init --mu-plugin   # For mu-plugins
-npx buwp-local config --init --theme       # For themes
-```
-
-This creates `.buwp-local.json` in your project directory.
-
-### 3. Edit configuration
-
-Edit `.buwp-local.json` to map your local repository into the container:
-
-```json
-{
-  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
-  "hostname": "myproject.local",
-  "multisite": true,
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/plugins/my-plugin"
-    }
-  ]
-}
-```
-
-### 4. Create `.env.local` for secrets
-
-Create `.env.local` (never commit this file!) or copy from the example:
-
-```bash
-cp .env.local.example .env.local
-```
-
-Then edit `.env.local` with your actual credentials:
-
-```bash
-# Database
-WORDPRESS_DB_PASSWORD=password
-DB_ROOT_PASSWORD=rootpassword
-
-# Shibboleth (if needed)
-SP_ENTITY_ID=https://your-sp-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-key-here
-SHIB_SP_CERT=your-cert-here
-
-# AWS S3 (if needed)
-S3_UPLOADS_BUCKET=your-bucket
-S3_UPLOADS_REGION=us-east-1
-S3_UPLOADS_ACCESS_KEY_ID=your-access-key
-S3_UPLOADS_SECRET_ACCESS_KEY=your-secret-key
-S3_ACCESS_RULES_TABLE=your-access-rules-table
-
-# OLAP
-OLAP=your-olap-name
-OLAP_ACCT_NBR=your-account-number
-OLAP_REGION=us-east-1
-```
-
-**Important:** Credentials are read directly from `.env.local` by Docker Compose. They are never written to the generated `docker-compose.yml` file, making it safe to review or share the generated compose file without exposing secrets.
-
-### 5. Add hostname to /etc/hosts
-
-```bash
-sudo bash -c 'echo "127.0.0.1 username.local" >> /etc/hosts'
-```
-
-### 6. Start the environment
-
-```bash
-npx buwp-local start
-```
-
-### 7. Access your site
-
-Open http://username.local or https://username.local in your browser.
-
-## Commands
-
-### Initialize configuration
-```bash
-npx buwp-local init
-
-Options:
-  --no-interactive  Use non-interactive mode with defaults
-  --plugin          Non-interactive: initialize as plugin
-  --mu-plugin       Non-interactive: initialize as mu-plugin
-  --theme           Non-interactive: initialize as theme
-  -f, --force       Overwrite existing configuration
-```
-
-The `init` command provides an interactive setup experience with:
-- **Smart defaults** - Detects project type from files
-- **Real-time validation** - Validates inputs as you type
-- **Guided workflow** - Clear prompts for all configuration options
-
-### Start environment
-```bash
-npx buwp-local start [options]
-
-Options:
-  --xdebug       Enable Xdebug
-  --no-s3        Disable S3 proxy service
-  --no-redis     Disable Redis service
-```
-
-### Stop environment
-```bash
-npx buwp-local stop
-```
-
-### View logs
-```bash
-npx buwp-local logs [options]
-
-Options:
-  -f, --follow              Follow log output
-  -s, --service <service>   Show logs for specific service
-                            (wordpress, db, s3proxy, redis)
-```
-
-### Destroy environment
-```bash
-npx buwp-local destroy [options]
-
-Options:
-  -f, --force    Skip confirmation prompt
-```
-
-### Configuration management
-```bash
-npx buwp-local config [options]
-
-Options:
-  --init        Initialize configuration file
-  --validate    Validate configuration file
-  --show        Show resolved configuration (with masked secrets)
-```
-
-## Configuration File
-
-### Basic Structure
-
-```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": [],
-  "env": {}
-}
-```
-
-### Volume Mappings
-
-Map your local code into the container:
-
-```json
-{
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/plugins/my-plugin"
-    },
-    {
-      "local": "../my-theme",
-      "container": "/var/www/html/wp-content/themes/my-theme"
-    }
-  ]
-}
-```
-
-### Custom Environment Variables
-
-```json
-{
-  "env": {
-    "WP_DEBUG": true,
-    "WP_DEBUG_LOG": true,
-    "XDEBUG": false
-  }
-}
-```
-
-### Disabling Services
-
-```json
-{
-  "services": {
-    "redis": false,
-    "s3proxy": false,
-    "shibboleth": false
-  }
-}
-```
-
-## Security Best Practices
-
-1. **Never commit `.env.local`** - This file contains secrets
-2. **Never commit `.buwp-local/`** - This directory contains generated files
-3. **Do commit `.buwp-local.json`** - This is your configuration template (no secrets)
-4. **Use environment variables for all secrets** - Credentials stay in `.env.local` and are never written to generated files
-5. **Review generated compose files** - The generated `docker-compose.yml` only contains variable references like `${WORDPRESS_DB_PASSWORD}`, not actual credentials
-6. **Copy `.env.local.example`** - Use the provided template to create your `.env.local` file
-7. **Consider using macOS Keychain** for even better security (future feature)
-
-### How Credentials Work
-
-buwp-local uses Docker Compose's native environment variable interpolation:
-
-1. **You provide** credentials in `.env.local`
-2. **buwp-local generates** `docker-compose.yml` with variable references like `${VAR_NAME}`
-3. **Docker Compose reads** `.env.local` at runtime and substitutes the values
-4. **Your secrets never** get written to any generated files
-
-This means:
-- ✅ Generated compose files are safe to review or share
-- ✅ No credentials in version control (even accidentally)
-- ✅ Industry-standard Docker Compose pattern
-- ✅ Simple and secure
-
-## File Structure
-
-When you use `buwp-local`, these files are created:
-
-```
-your-project/
-├── .buwp-local.json        # Configuration (commit this)
-├── .env.local              # Secrets (NEVER commit)
-├── .buwp-local/            # Generated files (don't commit)
-│   └── docker-compose.yml  # Generated compose file
-└── package.json            # Your project
-```
-
-## Troubleshooting
-
-### Port conflicts
-
-If you get port conflicts, you can change ports in `.buwp-local.json`:
-
-```json
-{
-  "ports": {
-    "http": 8080,
-    "https": 8443,
-    "db": 3307,
-    "redis": 6380
-  }
-}
-```
-
-### Docker not running
-
-Make sure Docker Desktop is running:
-```bash
-docker info
-```
-
-### Configuration errors
-
-Validate your configuration:
-```bash
-npx buwp-local config --validate
-```
-
-### View current configuration
-
-See the resolved configuration (with masked secrets):
-```bash
-npx buwp-local config --show
-```
-
-## WP-CLI Command
-```bash
-buwp-local wp user list
-buwp-local wp post list --format=json
-buwp-local wp plugin activate akismet
-```
-
-
-## Next Steps
-
-- [ ] Phase 2: WP-CLI proxy command
-- [ ] Phase 2: macOS Keychain integration
-- [ ] Phase 3: Automatic /etc/hosts management
-- [ ] Phase 3: SSL certificate generation