@bostonuniversity/buwp-local 0.6.3 → 0.7.1

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/ARCHITECTURE.md

@@ -442,9 +442,9 @@ Docker's **volume mapping architecture** creates a clean separation:
 │    └── wp-content/              │
 │         └── plugins/            │
 │              └── my-plugin/ ──┐ │  (mapped from Mac)
-│                                │ │
-│  SEPARATED = No conflicts!     │ │
-└────────────────────────────────┴─┘
+│                               │ │
+│  SEPARATED = No conflicts!    │ │
+└───────────────────────────────┴─┘
 ```
 
 **Technical Benefits:**
@@ -459,47 +459,6 @@ Docker's **volume mapping architecture** creates a clean separation:
 
 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:
@@ -516,18 +475,6 @@ This architecture provides clean boundaries:
 
 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

package/docs/CHANGELOG.md

@@ -5,6 +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).
 
+## [0.7.1]
+
+Documentation only release.
+
+## [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

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/MIGRATION_FROM_VM.md

@@ -198,9 +198,6 @@ npx buwp-local start
 ```bash
 # Check Docker Desktop is running
 docker info
-
-# Check port conflicts
-npx buwp-local start --verbose
 ```
 
 ### Code changes not appearing
@@ -224,7 +221,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

@@ -102,7 +102,7 @@ hostile.remove('127.0.0.1', config.hostname);
 ---
 
 ## Incremental Functional Improvements: v0.6.x
-**Status:** Currently Ongoing
+**Status:** Shipped
 **Focus:** Enhancements based on initial user experience
 
 ### Shipped in v0.6.1
@@ -115,7 +115,7 @@ hostile.remove('127.0.0.1', config.hostname);
 - **Fix issues with spaces in paths**
   - Fix issues with spaces in host paths causing Docker errors
 
-### Planned for v0.6.3
+### Shipped for v0.6.3
 
 - **Basic docs on existing Xdebug features**
   - Quickstart guide for enabling and using Xdebug in containers
@@ -123,10 +123,6 @@ 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** ✅
@@ -152,12 +148,24 @@ hostile.remove('127.0.0.1', config.hostname);
 
 **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
+## Next Phase: v0.7.x - Developer Experience
 
-**Status:** Planned  
-**Timeline:** After team onboarding feedback  
+**Status:** Ongoing 
 **Focus:** Ease of use and visibility
 
+### Shipped in v0.7.0
+- **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`
+
+### Shipped in v0.7.1
+- **Documentation Improvements**
+
 ### Potential Features
 
 - **Database Security**
@@ -169,6 +177,10 @@ 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 guide
   - Evaluate credential storage solutions for non-macOS platforms (https://www.npmjs.com/package/keytar)
@@ -195,6 +207,10 @@ 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 small group of users and actual pain points observed during rollout.
 
@@ -209,7 +225,8 @@ Will be informed by feedback from initial small group of users and actual pain p
 
 - **Cross-Platform Support** - Windows WSL2 and Linux credential storage
 - **SSL Certificate Generation** - Local HTTPS with mkcert
-- **Performance Monitoring** -
+- **Real support for running 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.
 

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.3",
+  "version": "0.7.1",
   "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/.buwp-local.json

@@ -1,22 +0,0 @@
-{
-  "projectName": "buwp-local",
-  "image": "bu-wordpress:latest",
-  "hostname": "jaydub.local",
-  "multisite": true,
-  "services": {
-    "redis": true,
-    "s3proxy": true,
-    "shibboleth": true
-  },
-  "ports": {
-    "http": 80,
-    "https": 443,
-    "db": 3306,
-    "redis": 6379
-  },
-  "mappings": [],
-  "env": {
-    "WP_DEBUG": true,
-    "XDEBUG": false
-  }
-}