@bostonuniversity/buwp-local 0.6.2 → 0.7.0

package/bin/buwp-local.js

@@ -24,6 +24,7 @@ const packageJson = JSON.parse(
 import startCommand from '../lib/commands/start.js';
 import stopCommand from '../lib/commands/stop.js';
 import destroyCommand from '../lib/commands/destroy.js';
+import updateCommand from '../lib/commands/update.js';
 import logsCommand from '../lib/commands/logs.js';
 import wpCommand from '../lib/commands/wp.js';
 import shellCommand from '../lib/commands/shell.js';
@@ -60,6 +61,13 @@ program
   .option('-f, --force', 'Skip confirmation prompt')
   .action(destroyCommand);
 
+// Update command
+program
+  .command('update')
+  .description('Update Docker images and recreate containers')
+  .option('--all', 'Update all service images (default: WordPress only)')
+  .action(updateCommand);
+
 // Logs command
 program
   .command('logs')
@@ -88,6 +96,7 @@ program
   .option('--plugin', 'Non-interactive: initialize as plugin')
   .option('--mu-plugin', 'Non-interactive: initialize as mu-plugin')
   .option('--theme', 'Non-interactive: initialize as theme')
+  .option('--sandbox', 'Non-interactive: initialize as sandbox')
   .option('-f, --force', 'Overwrite existing configuration')
   .action(initCommand);
 

package/docs/CHANGELOG.md

@@ -5,7 +5,24 @@ All notable changes to buwp-local will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.7.0]
+
+### Added
+- **`update` command** - Pull latest Docker images and recreate containers without losing data
+  - Pull WordPress image only by default (typical use case)
+  - `--all` flag to update all service images (Redis, S3 proxy, etc.)
+  - Safely applies security updates and WordPress core updates
+  - Data preserved: Database, WordPress files, volume mappings
+
+- **Non-interactive sandbox initialization** - Add `--sandbox` flag to `init` command for scripted setup of sandbox-type projects
+
+### Changed
+- **`init` command** - Now supports `--sandbox` flag for non-interactive initialization
+
+## [0.6.3]
+
+### Added
+- Documentation for volume mapping and xdebug
 
 ## [0.6.2]
 

package/docs/COMMANDS.md

@@ -115,6 +115,46 @@ npx buwp-local destroy --force
 
 ---
 
+### `update`
+
+Update Docker images and recreate containers without losing data.
+
+```bash
+npx buwp-local update [options]
+```
+
+**Options:**
+- `--all` - Update all service images (default: WordPress image only)
+
+**Examples:**
+```bash
+# Update WordPress image only (recommended)
+npx buwp-local update
+
+# Update all service images (Redis, S3 proxy, etc.)
+npx buwp-local update --all
+```
+
+**What it does:**
+- Checks if environment exists and Docker is running
+- Pulls latest Docker images from registry
+- Recreates containers with new images using `--force-recreate`
+- Loads credentials from Keychain and/or `.env.local`
+- **Preserves volumes** - Database and WordPress files untouched
+- Shows success message confirming what was preserved
+
+**Use cases:**
+- Pull latest WordPress updates without losing development work
+- Update only WordPress image (typical use case) or all services
+- Safe alternative to `destroy` when you only want to refresh images
+
+**Key difference from `stop/start`:**
+- `stop` → `start`: Reuses existing containers (no new images)
+- `update`: Pulls new images and recreates containers (gets updates)
+- `destroy`: Removes everything including volumes (fresh start)
+
+---
+
 ### `logs`
 
 View logs from Docker containers.

package/docs/GETTING_STARTED.md

@@ -183,8 +183,11 @@ npx buwp-local destroy
 ## Next Steps
 
 - **[Commands Reference](COMMANDS.md)** - Full list of available commands
+- **[Volume Mapping Patterns](VOLUME_MAPPINGS.md)** - Advanced multi-repo workflows
+- **[Xdebug Setup](XDEBUG.md)** - Configure step debugging for your pattern
 - **[Credential Management](CREDENTIALS.md)** - Detailed guide to managing secrets
 - **[Multi-Project Setup](MULTI_PROJECT.md)** - Run multiple projects simultaneously
+- **[Migration from VM Sandboxes](MIGRATION_FROM_VM.md)** - Transitioning from traditional VMs
 - **[Architecture](ARCHITECTURE.md)** - Understand how buwp-local works
 
 ## Troubleshooting

package/docs/MIGRATION_FROM_VM.md

@@ -224,7 +224,7 @@ Check volume mappings in `.buwp-local.json`:
 # Verify Keychain entries
 npx buwp-local keychain list
 
-# Or use .env.local fallback
+# Or use .env.local fallback --- this is a nice idea, but the actual command does not yet exist
 npx buwp-local keychain export > .env.local
 ```
 

package/docs/ROADMAP.md

@@ -10,7 +10,7 @@ Strategic direction and development priorities for buwp-local.
 
 **Key Features:**
 - macOS Keychain integration for secure credential storage
-- Automatic hex decoding for legacy multiline credentials
+- Automatic hex decoding for large multiline credentials like Shibboleth keys and certs
 - Credential validation on startup with interactive setup
 - Multi-project support with isolated Docker volumes
 - Smart initialization for plugins, themes, and mu-plugins
@@ -110,11 +110,12 @@ hostile.remove('127.0.0.1', config.hostname);
   - Guide users on setting up access to private registries (ghcr.io)
   - Automatic check for registry login or existing image on `start`
 
-### Planned for v0.6.2
+### Shipped in v0.6.2
 
-- ***Get spaces in volume mappings working correctly***
+- **Fix issues with spaces in paths**
   - Fix issues with spaces in host paths causing Docker errors
-  - Ensure cross-platform compatibility (Windows, macOS, Linux)
+
+### Planned for v0.6.3
 
 - **Basic docs on existing Xdebug features**
   - Quickstart guide for enabling and using Xdebug in containers
@@ -122,6 +123,35 @@ hostile.remove('127.0.0.1', config.hostname);
 - **Volume Mapping pattern guide**
   - Documentation on different volume mapping strategies for various development workflows
 
+### Shipped in v0.6.3
+
+**Focus:** Documentation refinement based on real user patterns
+
+**Key Deliverables:**
+
+1. **Volume Mapping Patterns Guide** ✅
+   - Comprehensive [VOLUME_MAPPINGS.md](VOLUME_MAPPINGS.md) documenting 3 patterns:
+     - **Pattern A:** In-Repo Development (self-contained, wp-env style)
+     - **Pattern B:** Sandbox Coordination (base camp maps multiple repos)
+     - **Pattern C:** Monolithic Sandbox (full WordPress for IDE context)
+   - Based on real user workflows discovered during initial rollout
+   - Decision trees, comparison tables, and migration guides
+   - Advanced topics: switching patterns, hybrid setups, performance considerations
+
+2. **Xdebug Configuration Guide** ✅
+   - Comprehensive [XDEBUG.md](XDEBUG.md) with pattern-specific pathMappings
+   - VSCode, PHPStorm, and Zed examples for each pattern
+   - Multi-root workspace setup for Pattern B
+   - Troubleshooting breakpoints, performance, and common issues
+
+3. **Cross-Reference Documentation** ✅
+   - Updated readme.md with links to new guides
+   - Added callouts in MULTI_PROJECT.md pointing to Pattern B
+   - Enhanced GETTING_STARTED.md next steps section
+   - Improved discoverability across documentation
+
+**Result:** Documentation now accurately reflects real-world development workflows, making it easier for new users to adopt appropriate patterns.
+
 ## Next Phase: v0.7.0 - Developer Experience
 
 **Status:** Planned  
@@ -130,7 +160,16 @@ hostile.remove('127.0.0.1', config.hostname);
 
 ### Potential Features
 
-- **Security Checks**
+- **Docker Image Update Command** 🎯 (Proposed for v0.7.0)
+  - **Problem:** Stopping and restarting containers reuses existing images; newer images aren't pulled
+  - **Solution:** Add `buwp-local update` command that:
+    - Pulls latest Docker images from registry
+    - Recreates containers with new images
+    - Preserves volumes (database, WordPress data)
+  - **Benefit:** Safe, explicit way to apply WordPress/service updates without `destroy`
+  - **Implementation:** Wrapper around `docker-compose pull && docker-compose up -d --force-recreate`
+
+- **Database Security**
   - 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.
@@ -139,8 +178,12 @@ hostile.remove('127.0.0.1', config.hostname);
   - Command to help generate Xdebug configuration for IDEs (VSCode, Zed)
   - Documentation on usage patterns
 
+- **Interactive setup assistant for adding volume mappings**
+  - Guided prompts to add common volume mappings post-initialization
+  - Suggestions based on detected project structure
+
 - **Improved Windows and Linux support**
-  - Multiplatform /etc/hosts hostname management
+  - Multiplatform /etc/hosts hostname guide
   - Evaluate credential storage solutions for non-macOS platforms (https://www.npmjs.com/package/keytar)
 
 - **Project Status & Listing**
@@ -148,10 +191,11 @@ hostile.remove('127.0.0.1', config.hostname);
   - View all running projects: `buwp-local list`
   - Quick status checks: `buwp-local status`
 
-- **Health Checks**
+- **Health Checks and Network Ports**
   - Verify services are running properly
   - Database connectivity validation
   - Clear diagnostics on failures
+  - Advice and assistance on port conflicts
 
 - **Improved Error Messages**
   - Docker startup failures → actionable solutions
@@ -164,8 +208,12 @@ hostile.remove('127.0.0.1', config.hostname);
 - **Docker Volume management assistant**
   - listing and cleanup of unused volumes
 
+- **Unit tests**
+  - Core modules (config, keychain, docker-compose)
+  - Command tests (init, start, stop, destroy, wp)
+
 ### Prioritization
-Will be informed by feedback from initial 2-3 users and actual pain points observed during rollout.
+Will be informed by feedback from initial small group of users and actual pain points observed during rollout.
 
 ---
 
@@ -174,13 +222,12 @@ Will be informed by feedback from initial 2-3 users and actual pain points obser
 **Status:** Conceptual  
 **Timeline:** TBD based on team feedback
 
-### Potential Features (Lower Priority)
+### Potential Features
 
-- **SSL Certificate Generation** - Local HTTPS with mkcert
-- **Database Backup/Restore** - Simplified snapshots and recovery
-- **Performance Monitoring** - Real-time resource usage tracking
-- **Team Configuration Sync** - Share project configurations across team
 - **Cross-Platform Support** - Windows WSL2 and Linux credential storage
+- **SSL Certificate Generation** - Local HTTPS with mkcert
+- **Real support for runnning on ports other than 443**
+- **Potential GUI from Electron or SwiftUI**
 
 **Note:** Automatic `/etc/hosts` management deferred pending user feedback. See "Lessons Learned" section above for details on the `hostile` library approach.
 
@@ -195,7 +242,7 @@ Will be informed by feedback from initial 2-3 users and actual pain points obser
 **Focus:** Robustness, clear setup, good documentation
 
 ### Stage 2: Team Rollout
-**Users:** 10-15 developers  
+**Users:** 5-10 developers  
 **Goal:** Find and fix real-world issues  
 **Release:** v0.7.0+  
 **Focus:** Developer experience, error handling