@bostonuniversity/buwp-local 0.6.2 → 0.7.0

package/docs/XDEBUG.md

@@ -0,0 +1,429 @@
+# Xdebug Setup Guide
+
+Xdebug configuration depends on your [volume mapping pattern](VOLUME_MAPPINGS.md). The key principle: **pathMappings must match your volume mappings exactly**.
+
+## Quick Start
+
+1. **Enable Xdebug** in `.buwp-local.json`:
+```json
+"env": {
+  "XDEBUG": true
+}
+```
+
+2. **Restart environment** to apply changes:
+```bash
+npx buwp-local stop
+npx buwp-local start
+```
+
+3. **Configure pathMappings** using the pattern-specific examples below.
+
+---
+
+## Pattern A: In-Repo Development
+
+**Scenario:** buwp-local lives inside your plugin/theme repo (like wp-env).
+
+**Volume mapping:**
+```json
+"mappings": [
+  {
+    "local": ".",
+    "container": "/var/www/html/wp-content/plugins/bu-navigation"
+  }
+]
+```
+
+### VSCode Configuration
+
+Create `.vscode/launch.json` in your plugin/theme repo:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Listen for Xdebug (Pattern A)",
+      "type": "php",
+      "request": "launch",
+      "port": 9003,
+      "pathMappings": {
+        "/var/www/html/wp-content/plugins/bu-navigation": "${workspaceRoot}"
+      }
+    }
+  ]
+}
+```
+
+### PHPStorm Configuration
+
+1. Go to **Run → Edit Configurations**
+2. Add **PHP Remote Debug** configuration
+3. Set **Server** configuration:
+   - Host: `localhost`
+   - Port: `9003`
+   - Debugger: `Xdebug`
+4. Add **Path mapping**:
+   - Local: `/path/to/bu-navigation` (your repo root)
+   - Remote: `/var/www/html/wp-content/plugins/bu-navigation`
+
+### Zed Configuration
+
+Create `.zed/tasks.json`:
+
+```json
+{
+  "xdebug": {
+    "type": "php",
+    "pathMappings": {
+      "/var/www/html/wp-content/plugins/bu-navigation": "."
+    }
+  }
+}
+```
+
+---
+
+## Pattern B: Sandbox Coordination
+
+**Scenario:** Base camp directory maps multiple plugin/theme repos.
+
+**Volume mapping:**
+```json
+"mappings": [
+  {
+    "local": "/Users/jaydub/projects/bu-navigation",
+    "container": "/var/www/html/wp-content/plugins/bu-navigation"
+  },
+  {
+    "local": "/Users/jaydub/projects/bu-slideshow",
+    "container": "/var/www/html/wp-content/plugins/bu-slideshow"
+  }
+]
+```
+
+### VSCode Multi-Root Workspace
+
+Create a **workspace file** (e.g., `bu-plugins.code-workspace`) to include all repos:
+
+```json
+{
+  "folders": [
+    { "path": "../bu-navigation" },
+    { "path": "../bu-slideshow" }
+  ],
+  "settings": {},
+  "launch": {
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "name": "Listen for Xdebug (Pattern B)",
+        "type": "php",
+        "request": "launch",
+        "port": 9003,
+        "pathMappings": {
+          "/var/www/html/wp-content/plugins/bu-navigation": "${workspaceFolder:bu-navigation}",
+          "/var/www/html/wp-content/plugins/bu-slideshow": "${workspaceFolder:bu-slideshow}"
+        }
+      }
+    ]
+  }
+}
+```
+
+**Usage:**
+1. Open the `.code-workspace` file in VSCode
+2. All mapped repos will be available in the sidebar
+3. Set breakpoints in any repo
+4. Start debugging with F5
+
+### PHPStorm Multi-Module Setup
+
+1. Open PHPStorm, go to **File → Project Structure**
+2. Add each repo as a **Module**
+3. Configure **Run → Edit Configurations → PHP Remote Debug**
+4. Add path mappings for each repo:
+   - `/Users/jaydub/projects/bu-navigation` → `/var/www/html/wp-content/plugins/bu-navigation`
+   - `/Users/jaydub/projects/bu-slideshow` → `/var/www/html/wp-content/plugins/bu-slideshow`
+
+### Zed Workspace
+
+Zed doesn't have multi-root workspace concept. Open each repo separately and configure individually (Pattern A style for each).
+
+---
+
+## Pattern C: Monolithic Sandbox
+
+**Scenario:** Base camp maps entire WordPress installation for complete IDE context.
+
+**Volume mapping:**
+```json
+"mappings": [
+  {
+    "local": "/Users/jaydub/wordpress-builds/bu-prod",
+    "container": "/var/www/html"
+  }
+]
+```
+
+### VSCode Configuration
+
+Create `.vscode/launch.json` in your WordPress build directory:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Listen for Xdebug (Pattern C)",
+      "type": "php",
+      "request": "launch",
+      "port": 9003,
+      "pathMappings": {
+        "/var/www/html": "${workspaceRoot}"
+      }
+    }
+  ]
+}
+```
+
+**Advantages:**
+- Single path mapping (simpler)
+- Full WordPress context in IDE
+- Go-to-definition works across all code
+- Autocomplete for WordPress core
+
+**Trade-offs:**
+- Slower volume performance on macOS
+- Larger IDE project (may be slower)
+- Must manage entire WordPress build
+
+### PHPStorm Configuration
+
+1. Open the WordPress build directory as your project root
+2. Configure **PHP Remote Debug**
+3. Add single path mapping:
+   - Local: `/Users/jaydub/wordpress-builds/bu-prod`
+   - Remote: `/var/www/html`
+
+### Zed Configuration
+
+Create `.zed/tasks.json` in WordPress root:
+
+```json
+{
+  "xdebug": {
+    "type": "php",
+    "pathMappings": {
+      "/var/www/html": "."
+    }
+  }
+}
+```
+
+---
+
+## Common Setup Steps (All Patterns)
+
+### Install PHP Debug Extension (VSCode)
+
+1. Open VSCode Extensions (Cmd+Shift+X)
+2. Search for "PHP Debug"
+3. Install: https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
+
+### Start Debugging
+
+1. **Set breakpoint** in your PHP file (click left gutter)
+2. **Start debug listener** (F5 or Run → Start Debugging)
+3. **Trigger code** in browser (reload page, submit form, etc.)
+4. **Debugger pauses** at breakpoint
+
+### Verify Xdebug is Running
+
+```bash
+# Check Xdebug is loaded
+npx buwp-local wp eval 'phpinfo();' | grep -i xdebug
+
+# Or via shell
+npx buwp-local shell
+php -v  # Should show "with Xdebug"
+```
+
+---
+
+## Alternative: VSCode Remote Container Debugging
+
+An alternative to volume mapping is to use VSCode's **Dev Containers** extension to open the entire WordPress container directly in VSCode.  PhpStorm also has a similar feature (Zed does not currently support this).
+
+### How It Works
+
+Instead of syncing code via volume mappings, you open VSCode **inside the container** and edit/debug directly there:
+
+1. Start buwp-local (any pattern, even without volume mappings)
+2. Right-click the running container in VSCode Docker explorer
+3. Select "Attach Visual Studio Code"
+4. VSCode opens inside the container with full filesystem access
+5. Set breakpoints and debug the entire build
+
+### When to Use This
+
+- ✅ Experimental edits (don't need to persist locally)
+- ✅ Full WordPress core context needed (like Pattern C)
+- ✅ Stepping through entire codebase quickly
+- ✅ Learning/exploring the build
+
+### Setup
+
+1. **Install Remote Containers Extension** (if not already installed)
+   - Open VSCode Extensions (Cmd+Shift+X)
+   - Search for "Remote - Containers"
+   - Install: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
+
+2. **Start your environment**
+   ```bash
+   npx buwp-local start
+   ```
+
+3. **Open container in VSCode**
+   - Click **Containers** (sidebar)
+   - Open the buwp-local project in the Containers list
+   - Right-click on the WordPress container → **Attach Visual Studio Code**
+
+4. **Install Extensions and Configure Debugging in container**
+    - Install PHP Debug extension inside the container VSCode
+    - Create `.vscode/launch.json` with pathMappings as needed (usually just `/var/www/html` to `.`)
+
+### Advantages vs Volume Mapping
+
+| Aspect | Volume Mapping | Remote Container |
+|--------|---|---|
+| **IDE Context** | Pattern-dependent | Full codebase always |
+| **Persistence** | Changes stay local | Temporary only |
+| **Performance** | Fast (local) | Slower (Docker I/O) |
+| **Best For** | Production code changes | Experimental debugging |
+
+### When NOT to Use This
+
+- ❌ Changes you need to keep locally (use volume mapping instead)
+
+---
+
+## Troubleshooting
+
+### Breakpoints Not Hit
+
+**Check pathMappings match your volume mappings:**
+
+```bash
+# View your volume mappings
+npx buwp-local config --show
+
+# Ensure pathMappings in launch.json match exactly
+```
+
+**Common mistakes:**
+- Pattern A: Using `/var/www/html` instead of full plugin path
+- Pattern B: Missing mappings for some repos
+- Pattern C: Wrong workspace root
+
+### "Cannot Find File" Errors
+
+**VSCode shows:** "Could not find file /var/www/html/..."
+
+**Solution:** Your local file path doesn't match the pathMapping. Check:
+1. Is VSCode workspace root correct?
+2. Does `${workspaceRoot}` resolve to the right path?
+3. For Pattern B, are you using multi-root workspace?
+
+### Performance Issues
+
+**Xdebug can slow page loads significantly.**
+
+**Solutions:**
+- Disable Xdebug when not actively debugging
+- Use conditional breakpoints sparingly
+- Pattern C is slower than A/B due to larger volume mapping
+
+### Port Already in Use
+
+**Error:** "Port 9003 already in use"
+
+**Solution:**
+```bash
+# Find process using port 9003
+lsof -i :9003
+
+# Kill if needed
+kill -9 <PID>
+
+# Or change Xdebug port in launch.json and container config
+```
+
+---
+
+## Advanced Configuration
+
+### Conditional Breakpoints
+
+Right-click breakpoint in VSCode → Edit Breakpoint → Add expression:
+
+```php
+$post_id === 123
+```
+
+### Step Debugging WP-CLI Commands
+
+```bash
+# Enable Xdebug for CLI
+npx buwp-local wp --allow-root eval 'xdebug_break();'
+
+# Or set environment variable
+npx buwp-local shell
+export XDEBUG_SESSION=1
+wp plugin list
+```
+
+### Remote Debugging from Browser
+
+Install Xdebug browser extension:
+- Chrome: [Xdebug Helper](https://chrome.google.com/webstore/detail/xdebug-helper)
+- Firefox: [Xdebug Helper](https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/)
+
+Click extension icon → Enable debugging → Reload page.
+
+---
+
+## Pattern-Specific Tips
+
+### Pattern A (In-Repo)
+- ✅ Simplest pathMapping setup
+- ❌ No WordPress core debugging
+- 💡 Use [php-stubs/wordpress-stubs](https://github.com/php-stubs/wordpress-stubs) for autocomplete
+
+### Pattern B (Sandbox)
+- ✅ Debug multiple repos simultaneously
+- ⚠️ Requires multi-root workspace in VSCode
+- 💡 Create `.code-workspace` file for team to share
+
+### Pattern C (Monolithic)
+- ✅ Debug WordPress core, plugins, themes all together
+- ✅ Full IDE context (go-to-definition everywhere)
+- ⚠️ Larger project, slower performance on macOS
+- 💡 Use sparse checkout to reduce repo size
+
+---
+
+## Related Documentation
+
+- **[VOLUME_MAPPINGS.md](VOLUME_MAPPINGS.md)** - Complete guide to volume mapping patterns
+- **[GETTING_STARTED.md](GETTING_STARTED.md)** - Initial setup guide
+- **[COMMANDS.md](COMMANDS.md)** - CLI reference
+
+---
+
+## References
+
+- [Xdebug Documentation](https://xdebug.org/docs/)
+- [VSCode PHP Debugging](https://code.visualstudio.com/docs/languages/php)
+- [PHPStorm Xdebug Guide](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html)

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) (except maybe not, please fix)\n'));
+    console.log(chalk.yellow('  - Delete all volumes (including database data)\n'));
 
     rl.question(chalk.red('Are you sure you want to continue? (yes/no): '), (answer) => {
       rl.close();

package/lib/commands/init.js

@@ -9,6 +9,17 @@ import fs from 'fs';
 import os from 'os';
 import { initConfig, CONFIG_FILE_NAME } from '../config.js';
 
+/**
+ * Container path templates for project types
+ * Defines where each project type maps to in the WordPress container
+ */
+const MAPPING_TEMPLATES = {
+  'plugin': '/var/www/html/wp-content/plugins/{name}',
+  'mu-plugin': '/var/www/html/wp-content/mu-plugins/{name}',
+  'theme': '/var/www/html/wp-content/themes/{name}',
+  'sandbox': null  // Sandbox has no default mapping
+};
+
 /**
  * Detect project type from package.json or directory structure
  * @param {string} projectPath - Path to project directory
@@ -84,6 +95,7 @@ async function initCommand(options) {
     if (options.plugin) initOptions.plugin = true;
     if (options.muPlugin) initOptions.muPlugin = true;
     if (options.theme) initOptions.theme = true;
+    if (options.sandbox) initOptions.sandbox = true;
     
     const configPath = initConfig(projectPath, initOptions);
     console.log(chalk.green(`✅ Created configuration file: ${configPath}\n`));
@@ -101,11 +113,26 @@ async function initCommand(options) {
     console.log(chalk.cyan(`ℹ️  Detected project type: ${detectedType}\n`));
   }
   
-  // Determine default project type index
-  let defaultTypeIndex = 0;
-  if (detectedType === 'plugin') defaultTypeIndex = 0;
-  else if (detectedType === 'mu-plugin') defaultTypeIndex = 1;
-  else if (detectedType === 'theme') defaultTypeIndex = 2;
+  // Define project type choices
+  const projectTypeChoices = [
+    { title: 'Plugin', value: 'plugin', description: 'WordPress plugin development' },
+    { title: 'MU Plugin', value: 'mu-plugin', description: 'Must-use plugin development' },
+    { title: 'Theme', value: 'theme', description: 'WordPress theme development' },
+    { title: 'Sandbox', value: 'sandbox', description: 'Base WordPress environment (add code mappings later)' }
+  ];
+  
+  // Determine default project type with priority: CLI flag > detected type > default
+  const typeFromFlag = options.plugin ? 'plugin' 
+    : options.muPlugin ? 'mu-plugin'
+    : options.theme ? 'theme'
+    : options.sandbox ? 'sandbox'
+    : null;
+
+  const preferredType = typeFromFlag || detectedType || 'plugin';
+
+  const defaultTypeIndex = projectTypeChoices.findIndex(
+    choice => choice.value === preferredType
+  );
   
   const questions = [
     {
@@ -119,13 +146,7 @@ async function initCommand(options) {
       type: 'select',
       name: 'projectType',
       message: 'Project type',
-      choices: [
-        { title: 'Plugin', value: 'plugin', description: 'WordPress plugin development' },
-        { title: 'MU Plugin', value: 'mu-plugin', description: 'Must-use plugin development' },
-        { title: 'Theme', value: 'theme', description: 'WordPress theme development' },
-        { title: 'Sandbox', value: 'sandbox', description: 'Base WordPress environment (add code mappings later)' },
-        { title: 'Custom', value: 'custom', description: 'Custom mapping configuration' }
-      ],
+      choices: projectTypeChoices,
       initial: defaultTypeIndex
     },
     {
@@ -245,31 +266,12 @@ async function initCommand(options) {
     }
   };
   
-  // Add mapping based on project type
-  if (answers.projectType === 'plugin') {
-    config.mappings.push({
-      local: './',
-      container: `/var/www/html/wp-content/plugins/${answers.projectName}`
-    });
-  } else if (answers.projectType === 'mu-plugin') {
-    config.mappings.push({
-      local: './',
-      container: `/var/www/html/wp-content/mu-plugins/${answers.projectName}`
-    });
-  } else if (answers.projectType === 'theme') {
-    config.mappings.push({
-      local: './',
-      container: `/var/www/html/wp-content/themes/${answers.projectName}`
-    });
-  } else if (answers.projectType === 'sandbox') {
-    // Sandbox type: no initial mappings
-    // User can add mappings manually to config.mappings array
-  } else {
-    // Custom type
+  // Add mapping based on project type using template
+  const template = MAPPING_TEMPLATES[answers.projectType];
+  if (template) {
     config.mappings.push({
       local: './',
-      container: '/var/www/html/wp-content/plugins/my-plugin',
-      comment: 'Customize this mapping for your project'
+      container: template.replace('{name}', answers.projectName)
     });
   }
   

package/lib/commands/update.js

@@ -0,0 +1,113 @@
+/**
+ * Update command - Updates Docker images and recreates containers
+ */
+
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { loadConfig, loadKeychainCredentials, createSecureTempEnvFile, secureDeleteTempEnvFile, ENV_FILE_NAME } from '../config.js';
+
+async function updateCommand(options = {}) {
+  console.log(chalk.blue('🔄 Updating Docker images...\n'));
+
+  try {
+    const projectPath = process.cwd();
+    const composePath = path.join(projectPath, '.buwp-local', 'docker-compose.yml');
+    const composeDir = path.dirname(composePath);
+    const envFilePath = path.join(projectPath, ENV_FILE_NAME);
+
+    // Check if docker-compose.yml exists
+    if (!fs.existsSync(composePath)) {
+      console.log(chalk.yellow('⚠️  No environment found.'));
+      console.log(chalk.gray('Run "buwp-local start" to create an environment.\n'));
+      return;
+    }
+
+    // Load config to get project name
+    const config = loadConfig(projectPath);
+    const projectName = config.projectName || 'buwp-local';
+
+    // Check if Docker is running
+    try {
+      execSync('docker info', { stdio: 'ignore' });
+    } catch (err) {
+      console.error(chalk.red('❌ Docker is not running'));
+      console.log(chalk.gray('Please start Docker Desktop and try again.\n'));
+      process.exit(1);
+    }
+
+    // Determine which services to pull
+    const pullAll = options.all || false;
+    const imageFilter = pullAll ? '' : 'wordpress';
+    
+    // Step 1: Pull images (WordPress only by default, or all with --all flag)
+    console.log(chalk.cyan(pullAll ? '📥 Pulling all Docker images...' : '📥 Pulling WordPress image...'));
+    try {
+      execSync(
+        `docker compose -p ${projectName} -f "${composePath}" pull ${imageFilter}`,
+        {
+          cwd: composeDir,
+          stdio: 'inherit'
+        }
+      );
+    } catch (err) {
+      console.error(chalk.red('\n❌ Failed to pull Docker images'));
+      console.log(chalk.gray('Check your Docker registry credentials and network connection.\n'));
+      process.exit(1);
+    }
+
+    // Step 2: Recreate containers with new images (preserves volumes)
+    // Need to pass environment variables just like start command does
+    console.log(chalk.cyan('\n🔨 Recreating containers with new images...'));
+    
+    // Load keychain credentials and create secure temp env file if available
+    let tempEnvPath = null;
+    const finalKeychainCredentials = loadKeychainCredentials();
+    const keychainCredCount = Object.keys(finalKeychainCredentials).length;
+    
+    if (keychainCredCount > 0) {
+      try {
+        tempEnvPath = createSecureTempEnvFile(finalKeychainCredentials, projectName);
+      } catch (err) {
+        console.warn(chalk.yellow(`⚠️  Could not load keychain credentials: ${err.message}`));
+      }
+    }
+    
+    // Build env-file flags
+    const envFileFlag = fs.existsSync(envFilePath) ? `--env-file ${envFilePath}` : '';
+    const tempEnvFileFlag = tempEnvPath ? `--env-file ${tempEnvPath}` : '';
+    
+    try {
+      execSync(
+        `docker compose -p ${projectName} ${tempEnvFileFlag} ${envFileFlag} -f "${composePath}" up -d --force-recreate`,
+        {
+          cwd: composeDir,
+          stdio: 'inherit'
+        }
+      );
+    } catch (err) {
+      console.error(chalk.red('\n❌ Failed to recreate containers'));
+      process.exit(1);
+    } finally {
+      // Always clean up temp env file
+      if (tempEnvPath) {
+        secureDeleteTempEnvFile(tempEnvPath);
+      }
+    }
+
+    // Success message
+    console.log(chalk.green('\n✅ Update complete!\n'));
+    console.log(chalk.gray('Preserved:'));
+    console.log(chalk.gray('  ✓ Database and WordPress data'));
+    console.log(chalk.gray('  ✓ Volume mappings and configuration\n'));
+    console.log(chalk.cyan('Access your site at:'));
+    console.log(chalk.white(`  https://${config.hostname}\n`));
+
+  } catch (err) {
+    console.error(chalk.red('\n❌ Error:'), err.message);
+    process.exit(1);
+  }
+}
+
+export default updateCommand;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@bostonuniversity/buwp-local",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Local WordPress development environment for Boston University projects",
   "type": "module",
   "main": "lib/index.js",
   "bin": {
-    "buwp-local": "./bin/buwp-local.js"
+    "buwp-local": "bin/buwp-local.js"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",

package/readme.md

@@ -99,7 +99,10 @@ Your local WordPress site should now be accessible at the hostname you configure
 
 - 📘 [Getting Started Guide](docs/GETTING_STARTED.md)
 - 📖 [Command Reference](docs/COMMANDS.md)
+- 🗺️ [Volume Mapping Patterns](docs/VOLUME_MAPPINGS.md) - Flexible development workflows
+- 🐛 [Xdebug Setup](docs/XDEBUG.md) - Step debugging configuration
 - 🔐 [Credential Management](docs/CREDENTIALS.md)
+- 🔄 [Migration from VM Sandboxes](docs/MIGRATION_FROM_VM.md)
 - 🏗️ [Architecture](docs/ARCHITECTURE.md) (for contributors)
 
 ## Features