@bostonuniversity/buwp-local 0.6.0 → 0.6.1

package/docs/ARCHITECTURE.md

@@ -383,6 +383,153 @@ npx buwp-local wp user create username user@bu.edu
 
 **Module:** `lib/commands/wp.js`
 
+## Architectural Advantages
+
+### Why Docker + Volume Mappings Over VM Sandboxes
+
+Traditional VM sandbox environments face a fundamental architectural limitation: **WordPress core and developer code share the same filesystem**. This creates a destructive update cycle.
+
+#### The VM Sandbox Problem
+
+```
+┌───────────────────────────────────────┐
+│           VM Filesystem               │
+│                                       │
+│  /var/www/html/                       │
+│    ├── wp-admin/      (WordPress core)│
+│    ├── wp-includes/   (WordPress core)│
+│    └── wp-content/                    │
+│         ├── plugins/                  │
+│         │   └── my-plugin/  ← Your code
+│         └── themes/                   │
+│              └── my-theme/   ← Your code
+│                                       │
+│  ALL IN ONE PLACE = Problem!          │
+└───────────────────────────────────────┘
+
+To update WordPress → Must rebuild entire VM
+Rebuild entire VM → Your code gets overwritten
+```
+
+**Consequences:**
+- Monthly rebuild schedules required
+- Developers must backup code before rebuilds
+- Team-wide coordination overhead
+- All-or-nothing updates (everyone updates together)
+- Risk of losing work if backup/restore fails
+
+#### The buwp-local Solution
+
+Docker's **volume mapping architecture** creates a clean separation:
+
+```
+┌─────────────────────────────────┐
+│    Your Mac's Filesystem        │  ← Developer code lives here
+│                                 │     (permanent, survives updates)
+│  ~/projects/my-plugin/          │
+│    ├── my-plugin.php            │
+│    ├── includes/                │
+│    └── assets/                  │
+└────────────┬────────────────────┘
+             │ Volume mapping (bind mount)
+             ↓
+┌─────────────────────────────────┐
+│      Docker Container           │  ← WordPress core lives here
+│                                 │     (disposable, updates don't affect code)
+│  /var/www/html/                 │
+│    ├── wp-admin/    (from image)│
+│    ├── wp-includes/ (from image)│
+│    └── wp-content/              │
+│         └── plugins/            │
+│              └── my-plugin/ ──┐ │  (mapped from Mac)
+│                                │ │
+│  SEPARATED = No conflicts!     │ │
+└────────────────────────────────┴─┘
+```
+
+**Technical Benefits:**
+
+1. **Persistent Code** - Your code lives on the host filesystem, not in the container. Destroy and recreate containers as much as you want—code never changes.
+
+2. **Independent Updates** - Pull new WordPress images (`docker pull`) without affecting your development code. Update on your schedule, not a team calendar.
+
+3. **Instant Rollback** - Switch between WordPress versions by changing the image tag. Your code stays constant while you test different WordPress versions.
+
+4. **Zero Coordination** - Each developer controls their own environment. No rebuild meetings, no freeze periods, no waiting for others.
+
+5. **Safe Testing** - Test breaking changes in WordPress without risk. If something goes wrong, recreate the container—your code was never in danger.
+
+#### Workflow Comparison
+
+**VM Sandbox Workflow:**
+```
+Week 1-3: Develop in VM
+Week 4: Monthly rebuild
+  1. Backup your code manually
+  2. Coordinate with team
+  3. Wait for new VM image
+  4. Restore code manually
+  5. Re-test everything
+  6. Hope nothing broke
+Time lost: 2-4 hours + coordination overhead
+```
+
+**buwp-local Workflow:**
+```
+Anytime: New WordPress version available
+  1. docker pull ghcr.io/bu-ist/buwp:latest
+  2. npx buwp-local start
+  3. Test (your code unchanged)
+Time: 2 minutes
+```
+
+#### Real-World Example
+
+**Scenario:** 6-week plugin development project. WordPress update lands in week 3.
+
+**VM Approach:**
+- Wait for scheduled monthly rebuild (week 4)
+- Backup your work
+- Rebuild overwrites everything
+- Restore and re-test
+- **Impact:** 2-4 hours lost, risk of data loss
+
+**buwp-local Approach:**
+- Pull new image when convenient (any time in week 3-6)
+- Containers recreate with new WordPress version
+- Your code untouched on local filesystem
+- **Impact:** 2 minutes, zero risk
+
+### Separation of Concerns
+
+This architecture provides clean boundaries:
+
+| Concern | Location | Update Mechanism |
+|---------|----------|------------------|
+| WordPress core | Docker image | `docker pull` |
+| BU plugins | Docker image | `docker pull` |
+| BU theme | Docker image | `docker pull` |
+| **Your plugin** | **Local filesystem** | **Your editor** |
+| **Your theme** | **Local filesystem** | **Your editor** |
+| Database | Docker volume | Persists across updates |
+| Uploads | Docker volume | Persists across updates |
+
+Updates to WordPress never touch your development code. Updates to your code never require rebuilding WordPress.
+
+### Additional Architectural Benefits
+
+1. **Live Reload** - File changes sync instantly via volume mappings. Save in your editor, refresh browser, see changes.
+
+2. **IDE Integration** - Use any editor (VS Code, PHPStorm, Sublime) with full IDE features (autocomplete, debugging, git integration).
+
+3. **Version Control** - Your code is already on the host filesystem where git lives. No special workflows to commit from inside VMs.
+
+4. **Multiple Projects** - Run multiple projects simultaneously, each with isolated environments. No VM resource conflicts.
+
+5. **Portable Configuration** - Commit `.buwp-local.json` to version control. Teammates get identical environments with one command.
+
+For detailed migration guidance, see [MIGRATION_FROM_VM.md](MIGRATION_FROM_VM.md).
+
 ## Security Model
 
 ### Credential Security

package/docs/MIGRATION_FROM_VM.md

@@ -0,0 +1,237 @@
+# Migration from VM Sandboxes
+
+This guide explains the architectural advantages of buwp-local compared to traditional VM sandbox environments and provides practical migration advice.
+
+## Difficulties with VM Sandboxes
+
+1. DV01 sandboxes are very slow.
+2. The shared server is a single point of failure, and stability issues impact all developers.
+3. Reliance on SFTP for code editing is becoming outdated and hard to support.
+4. VM Sandboxes need periodic updates. 
+
+## The VM Sandbox Updates Problem
+
+In traditional VM-based development environments:
+
+1. **Monthly rebuild cycles** - VM sandboxes must be periodically replaced with fresh builds to keep WordPress core, plugins, and infrastructure up to date
+3. **Manual preservation** - Developers must manually back up their work before each rebuild and restore it afterward
+4. **Coordination overhead** - Team-wide rebuild schedules require coordination and can interrupt active development
+5. **All-or-nothing updates** - The entire team must update together, regardless of individual project needs
+
+## How buwp-local Solves This
+
+buwp-local uses **Docker's volume mapping architecture** to fundamentally separate concerns:
+
+```
+┌─────────────────────────────────────┐
+│      Your Local Filesystem          │
+│  (Your code lives here permanently) │
+│                                     │
+│  /path/to/your-plugin/              │
+│    ├── plugin.php                   │
+│    ├── includes/                    │
+│    └── assets/                      │
+└─────────────┬───────────────────────┘
+              │ Volume mapping
+              ↓
+┌─────────────────────────────────────┐
+│       Docker Container              │
+│   (WordPress core lives here)       │
+│                                     │
+│  /var/www/html/                     │
+│    ├── wp-admin/ (from image)       │
+│    ├── wp-includes/ (from image)    │
+│    └── wp-content/                  │
+│         └── plugins/                │
+│              └── your-plugin/ ←──── │ (mapped from local)
+└─────────────────────────────────────┘
+```
+
+### Key Architectural Differences
+
+| Aspect | VM Sandbox | buwp-local |
+|--------|------------|------------|
+| **Code location** | Inside VM filesystem | Your local filesystem |
+| **WordPress core** | Inside VM filesystem | Inside disposable container |
+| **Update mechanism** | Deploy entire WP build | Pull new Docker image |
+| **Your code** | Overwritten on rebuild | Always preserved |
+| **Update schedule** | Team-wide coordination | Individual developer choice |
+
+## Advantages
+
+### 1. Persistent Code
+
+Your development work lives on your Mac's filesystem. Even if you destroy and recreate containers hundreds of times, your code remains untouched.
+
+```bash
+# This destroys the container but NOT your code
+npx buwp-local destroy
+
+# Start fresh - your code is still there
+npx buwp-local start
+```
+
+### 2. Individual Update Schedules
+
+Only those plugin and themes that you explicitly map into the container are fixed to the working code in your local filesystem. All of the other code resources from the BU WordPress build come from the container and can be updated independently.
+
+Update WordPress whenever it makes sense for YOUR project:
+
+```bash
+# You in January: Pull latest image
+docker pull ghcr.io/bu-ist/buwp:latest
+
+# Colleague in February: Still working on older version
+# No problem - they update when ready
+```
+
+### 3. Instant Version Switching
+
+Test different WordPress versions without losing work:
+
+```yaml
+# .buwp-local.json
+{
+  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-wp5-8"  # Stable version
+}
+```
+
+```yaml
+# Switch to test new features
+{
+  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-wp6-0"  # Release candidate
+}
+```
+
+Your code stays the same - only the WordPress version changes.
+
+### 4. No Rebuild Coordination
+
+Every developer controls their own environment:
+
+- No team-wide rebuild meetings
+- No "freeze" periods before rebuilds
+- No coordination overhead
+- No waiting for others
+
+
+---
+
+## What Changes in Your Workflow
+
+### Before (VM Sandbox)
+
+```
+1. Connect to VM via SSH SFTP
+2. Edit code in VM filesystem
+3. Test changes in VM's WordPress (dv01 is slow!)
+4. Before monthly rebuild: Back up your changes
+5. After rebuild: Restore changes and pray
+6. Repeat monthly
+```
+
+### After (buwp-local)
+
+```
+1. Edit code in your favorite local editor
+2. Changes instantly sync to container
+3. Test changes at http://yourproject.local
+4. When WordPress update available: docker pull
+5. That's it - your code was never touched
+```
+
+## Frequently Asked Questions
+
+### "What if I need the old VM for something?"
+
+Keep it! buwp-local and VM sandboxes can coexist. Use buwp-local for active development and VMs for other purposes.
+
+### "What about database snapshots?"
+
+buwp-local includes the same `wp site-manager snapshot-pull` command as production. Pull from production/staging anytime:
+
+```bash
+npx buwp-local wp site-manager snapshot-pull --source=https://www.bu.edu/site/
+```
+
+### "Can I share my environment with teammates?"
+
+Your `.buwp-local.json` configuration can be committed to version control. Teammates run:
+
+```bash
+git clone your-repo
+npm install
+npx buwp-local start
+```
+
+Everyone gets an identical environment with their own isolated containers.
+
+### "What happens to my database when I update?"
+
+Docker volumes persist your database across container updates:
+
+```bash
+# Your database lives in a named volume
+docker volume ls | grep wordpress-db
+
+# It survives container recreation
+npx buwp-local destroy  # Removes container
+npx buwp-local start    # Database still intact
+```
+
+### "How do I completely start fresh?"
+
+```bash
+# Remove everything including database (this is notional, the actual command does not yet support the --volumes flag)
+npx buwp-local destroy --volumes
+
+# Or keep database, just refresh WordPress
+npx buwp-local stop
+docker pull ghcr.io/bu-ist/bu-wordpress:new-tag
+npx buwp-local start
+```
+
+## Troubleshooting
+
+### Container won't start
+
+```bash
+# Check Docker Desktop is running
+docker info
+
+# Check port conflicts
+npx buwp-local start --verbose
+```
+
+### Code changes not appearing
+
+Check volume mappings in `.buwp-local.json`:
+
+```json
+{
+  "volumeMappings": [
+    {
+      "localPath": "./",
+      "containerPath": "/var/www/html/wp-content/plugins/your-plugin"
+    }
+  ]
+}
+```
+
+### Credentials not loading
+
+```bash
+# Verify Keychain entries
+npx buwp-local keychain list
+
+# Or use .env.local fallback
+npx buwp-local keychain export > .env.local
+```
+
+See [CREDENTIALS.md](CREDENTIALS.md) for detailed credential management.
+
+## Additional Resources
+
+- [Getting Started Guide](GETTING_STARTED.md) - Step-by-step setup
+- [Command Reference](COMMANDS.md) - Complete CLI documentation
+- [Architecture Guide](ARCHITECTURE.md) - Technical deep-dive

package/docs/ROADMAP.md

@@ -19,11 +19,8 @@ Strategic direction and development priorities for buwp-local.
 
 ---
 
-## Current Phase: v0.6.0 - Quality & Robustness
+## v0.6.0 - Quality & Robustness
 **Status:** Shipped  
-
-**Status:** In Progress  
-**Target Date:** December 2024  
 **Focus:** Foundation improvements before team rollout
 
 ### Features in Development
@@ -104,28 +101,43 @@ hostile.remove('127.0.0.1', config.hostname);
 
 ---
 
+## Incremental Functional Improvements: v0.6.1
+**Status:** Currently Ongoing
+**Focus:** Enhancements based on initial user experience
+
+- **Container Registry Assistance**
+  - Guide users on setting up access to private registries (ghcr.io)
+  - Automatic check for registry login or existing image on `start`
+
+- **Basic docs on existing Xdebug features**
+  - Quickstart guide for enabling and using Xdebug in containers
+
+- **Volume Mapping pattern guide**
+  - Documentation on different volume mapping strategies for various development workflows
+
 ## Next Phase: v0.7.0 - Developer Experience
 
 **Status:** Planned  
-**Timeline:** January 2025 (after team onboarding feedback)  
+**Timeline:** After team onboarding feedback  
 **Focus:** Ease of use and visibility
 
 ### Potential Features
 
-- **Xdebug Integration**
-  - Enable Xdebug in containers
-  - Documentation for IDE setup
-  - Configuration options in `.buwp-local.json`
-
 - **Security Checks**
   - Check database access on db port (e.g. `localhost:3306`)
   - Consider more stringent default database passwords
+  - The database can have restricted content in it, so we need to ensure that users are aware of this and take appropriate measures.
+
+- **Xdebug Integration**
+  - Command to help generate Xdebug configuration for IDEs (VSCode, Zed)
+  - Documentation on usage patterns
 
 - **Improved Windows and Linux support**
   - Multiplatform /etc/hosts hostname management
-  - Evaluate credential storage solutions for non-macOS platforms
+  - Evaluate credential storage solutions for non-macOS platforms (https://www.npmjs.com/package/keytar)
 
 - **Project Status & Listing**
+  - Central tracking of all buwp-local projects in `~/.buwp-local/projects.json`
   - View all running projects: `buwp-local list`
   - Quick status checks: `buwp-local status`
 
@@ -139,6 +151,12 @@ hostile.remove('127.0.0.1', config.hostname);
   - Credential issues → clear next steps
   - Port conflicts → suggest alternatives
 
+- **Multi project experience**
+  - There is a problem when starting a new project when an existing project exists in docker but is stopped. When starting the new project, docker first starts the container for the stopped project for unknown reasons. If the new project uses the same ports, this causes conflicts. Need to investigate and resolve, projects should be isolated and not interfere with each other.
+
+- **Docker Volume management assistant**
+  - listing and cleanup of unused volumes
+
 ### Prioritization
 Will be informed by feedback from initial 2-3 users and actual pain points observed during rollout.
 
@@ -163,19 +181,19 @@ Will be informed by feedback from initial 2-3 users and actual pain points obser
 
 ## Roadmap by User Stage
 
-### Stage 1: Initial Users (Now)
+### Stage 1: Initial Users
 **Users:** 1-3 developers  
 **Goal:** Validate core functionality  
 **Release:** v0.6.0  
 **Focus:** Robustness, clear setup, good documentation
 
-### Stage 2: Team Rollout (Q1 2025)
+### Stage 2: Team Rollout
 **Users:** 10-15 developers  
 **Goal:** Find and fix real-world issues  
 **Release:** v0.7.0+  
 **Focus:** Developer experience, error handling
 
-### Stage 3: Broader Adoption (Q2 2025+)
+### Stage 3: Broader Adoption
 **Users:** 20+ developers  
 **Goal:** Self-service onboarding  
 **Release:** v1.0.0+  
@@ -196,9 +214,7 @@ Will be informed by feedback from initial 2-3 users and actual pain points obser
 - Video tutorials for setup
 
 ### Quality
-- Standardized error handling across commands
-- Centralized logging system
-- Better validation for edge cases
+- Standardized help for all CLI commands
 
 ---
 
@@ -213,35 +229,9 @@ Features will be prioritized based on:
 
 ---
 
-## How to Use This Roadmap
-
-**For Users:**
-- See what's coming and when
-- Understand current release focus
-- Provide feedback on priorities
-
-**For Contributors:**
-- Clear phases and timeline
-- See future enhancement opportunities
-- Link to technical details in [ARCHITECTURE.md](ARCHITECTURE.md)
-
----
-
 ## Technical Details
 
 For detailed information about planned features, implementation approaches, and architecture decisions, see:
 
 - **[ARCHITECTURE.md](ARCHITECTURE.md)** - Planned Features section
 - **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
-
----
-
-## Feedback
-
-Have ideas for the roadmap? Questions about priorities?
-
-- **Early users:** Direct feedback via chat/email
-- **GitHub issues:** Feature requests and suggestions
-- **Team meetings:** Quarterly roadmap reviews
-
-Current focus: Getting v0.6.0 stable and ready for initial rollout to 2-3 users. 🚀

package/lib/commands/destroy.js

@@ -85,7 +85,7 @@ function confirmDestroy(projectName) {
     console.log(chalk.yellow(`This will destroy project: ${chalk.bold(projectName)}`));
     console.log(chalk.yellow('  - Stop all containers'));
     console.log(chalk.yellow('  - Remove all containers'));
-    console.log(chalk.yellow('  - Delete all volumes (including database data)\n'));
+    console.log(chalk.yellow('  - Delete all volumes (including database data) (except maybe not, please fix)\n'));
 
     rl.question(chalk.red('Are you sure you want to continue? (yes/no): '), (answer) => {
       rl.close();

package/lib/commands/start.js

@@ -137,6 +137,34 @@ async function promptCredentialSetup(missingCreds) {
   return shouldSetup;
 }
 
+// Check if image is accessible
+async function checkImageAccess(imageName) {
+  try {
+    // Try to inspect image locally
+    execSync(`docker image inspect ${imageName}`, { stdio: 'pipe' });
+    return true; // Image exists locally
+  } catch {
+    // Image doesn't exist, try to pull
+    try {
+      console.log(chalk.gray(`Checking access to ${imageName}...`));
+      execSync(`docker pull ${imageName}`, { stdio: 'pipe' });
+      return true;
+    } catch (pullError) {
+      if (pullError.message.includes('unauthorized') || 
+          pullError.message.includes('denied')) {
+        console.log(chalk.yellow('\n⚠️  Cannot access container image\n'));
+        console.log('The BU WordPress image requires GitHub Packages authentication.\n');
+        console.log('Run this command to authenticate:\n');
+        console.log(chalk.cyan('  docker login ghcr.io\n'));
+        console.log('You will need a GitHub personal access token with "read:packages" scope.');
+        console.log('See: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry\n');
+        return false;
+      }
+      throw pullError; // Other error, let it surface
+    }
+  }
+}
+
 async function startCommand(options) {
   console.log(chalk.blue('🚀 Starting BU WordPress local environment...\n'));
 
@@ -204,6 +232,18 @@ async function startCommand(options) {
       console.log(chalk.green('✓ Required credentials validated\n'));
     }
 
+    // Check image accessibility
+    console.log(chalk.gray('Checking container image access...'));
+    const imageAccessible = await checkImageAccess(config.image);
+
+    if (!imageAccessible) {
+      console.log(chalk.red('\n❌ Cannot proceed without access to container image.'));
+      console.log(chalk.gray('Please authenticate with GitHub Packages and try again.\n'));
+      process.exit(1);
+    }
+
+    console.log(chalk.green('✓ Container image accessible\n'));
+
     // Check /etc/hosts for hostname entry
     if (!hasShownHostsWarning(projectPath)) {
       const hostsCheck = checkHostsFile(config.hostname);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bostonuniversity/buwp-local",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Local WordPress development environment for Boston University projects",
   "type": "module",
   "main": "lib/index.js",

package/readme.md

@@ -4,6 +4,15 @@ This repository contains resources and instructions for setting up a local WordP
 
 The package can be installed in a specific repo for development of that one package, or standalone for more general use, mapping local code into the container as needed.
 
+> **Why buwp-local over VM sandboxes?**
+> 
+> Traditional VM sandboxes require **monthly rebuilds that wipe your development code**. With buwp-local's Docker architecture, your code lives on your local filesystem while only WordPress core updates. This means:
+> - ✅ **Keep your work** - No more monthly rebuild cycles that erase local changes
+> - ✅ **Update independently** - Pull WordPress updates on your schedule, not a global calendar
+> - ✅ **Instant rollback** - Switch between WordPress versions without losing work
+> 
+> Learn more: [Migration from VM Sandboxes](docs/MIGRATION_FROM_VM.md)
+
 ## Quickstart for plugin or theme development
 
 1. **Install Docker**: Make sure you have [Docker Desktop](https://www.docker.com/products/docker-desktop) installed and running on your machine.