@bostonuniversity/buwp-local 0.7.2 → 0.7.4

package/bin/buwp-local.js

@@ -27,6 +27,7 @@ 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 watchJobsCommand from '../lib/commands/watch-jobs.js';
 import shellCommand from '../lib/commands/shell.js';
 import configCommand from '../lib/commands/config.js';
 import initCommand from '../lib/commands/init.js';
@@ -108,6 +109,14 @@ program
   .allowUnknownOption()
   .action(wpCommand);
 
+// Watch Jobs command
+program
+  .command('watch-jobs')
+  .description('Watch and automatically process site-manager jobs')
+  .option('--interval <seconds>', `Polling interval in seconds (default: 300, min: 30)`)
+  .option('--quiet', 'Suppress output unless jobs are found')
+  .action(watchJobsCommand);
+
 // Shell command
 program
   .command('shell')

package/docs/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.4]
+
+### Changed
+- **Localhost-Only Port Binding for Database & Redis**
+- Database and Redis services now bind to `127.0.0.1` instead of `0.0.0.0` for improved security and local development isolation
+
+## [0.7.3]
+
+### Added
+- `watch-jobs` command for automatic processing of site-manager jobs at regular intervals
+- Configurable polling interval with `--interval` flag (default: 60 seconds, minimum: 10 seconds), and through `jobWatchInterval` in configuration file
+- `--quiet` flag to suppress routine output for long-running background use
+
 ## [0.7.2]
 
 ### Breaking Changes

package/docs/COMMANDS.md

@@ -421,6 +421,82 @@ npx buwp-local keychain clear [--force]
 
 ---
 
+### `watch-jobs`
+
+Watch for and automatically process site-manager jobs at regular intervals.
+
+```bash
+npx buwp-local watch-jobs [options]
+```
+
+**Options:**
+- `--interval <seconds>` - Polling interval in seconds (default: 60, min: 10)
+- `--quiet` - Suppress all routine output (for long-running background use)
+
+**Examples:**
+```bash
+# Watch with default 1 minute interval
+npx buwp-local watch-jobs
+
+# Watch with custom 2 minute interval
+npx buwp-local watch-jobs --interval 120
+
+# Quiet mode (silent operation, check web UI for job status)
+npx buwp-local watch-jobs --quiet
+
+# Quiet mode with short interval for active monitoring
+npx buwp-local watch-jobs --interval 20 --quiet
+```
+
+**What it does:**
+- Runs `wp site-manager process-jobs` inside the WordPress container at configured intervals
+- **Default mode**: Shows timestamped output for all checks and job results
+- **Quiet mode**: Silently processes jobs (check site-manager web UI for status)
+- Continues running until stopped (Ctrl+C)
+- Mirrors production cron/EventBridge behavior locally
+
+**Use cases:**
+- Automatic processing of jobs created via web UI
+
+**Configuration:**
+
+Optionally configure default interval in `.buwp-local.json`:
+```json
+{
+  "projectName": "my-project",
+  "jobWatchInterval": 200
+}
+```
+
+Command-line `--interval` flag overrides config file setting.
+
+**Requirements:**
+- WordPress container must be running (`start` first)
+- Site-manager plugin must be installed and activated
+
+**Quiet mode behavior:**
+- **Startup**: Shows configuration banner
+- **Routine operation**: Completely silent - no output for checks or job processing
+- **Critical errors**: Shows only failures requiring intervention (Docker stopped, environment missing)
+- **Job status**: Check site-manager plugin web UI to see job results and history
+- **Best for**: Long-running background monitoring (hours/days) without terminal noise
+
+**Error handling:**
+- **Default mode**: Shows all errors and warnings with timestamps
+- **Quiet mode**: Silently retries transient errors (container restarts), only shows critical failures
+- Graceful shutdown on SIGINT/SIGTERM
+
+**Tips:**
+- Run in separate terminal window for visibility
+- Use **default mode** during active development to see what's happening
+- Use **quiet mode** for set-it-and-forget-it background monitoring
+- Reduce interval during active testing (e.g., `--interval 60`)
+- Increase interval for background monitoring (e.g., `--interval 600`)
+
+**⚠️ Note:** This is a development tool. Production environments should continue using cron/AWS EventBridge for job processing.
+
+---
+
 ## Global Options
 
 These options work with all commands:

package/docs/ROADMAP.md

@@ -172,12 +172,65 @@ hostile.remove('127.0.0.1', config.hostname);
   - Update command now properly releases volume locks before deletion
   - Added `--preserve-wpbuild` flag for opt-out of WordPress volume refresh
 
+### Shipped in v0.7.3
+
+- **Job Watcher Command** ✅
+  - New `watch-jobs` command to periodically run `wp site-manager process-jobs`
+  - Configurable polling interval (default: 60 seconds)
+  - Runs as standalone process in terminal window
+  - Timestamped output for job processing visibility
+  - True quiet mode for long-running background monitoring
+  - Graceful shutdown (Ctrl+C)
+  
+  **Problem:** Production environments use cron/AWS EventBridge to automatically process site-manager jobs (content migration, deployments). Local developers currently must manually run `npx buwp-local wp site-manager process-jobs` to see queued jobs complete.
+  
+  **Solution:** Standalone `watch-jobs` command that runs indefinitely, polling for jobs at configurable intervals. Mirrors production behavior without requiring cron setup. Enables developers to use the site-manager web UI for content operations and see jobs complete automatically.
+
+### Shipped in v0.7.4
+
+- **Localhost-Only Port Binding for Database & Redis** ✅
+  - Bind database (3306) and Redis (6379) ports to 127.0.0.1 only
+  - Prevents network exposure of confidential database content
+  - HTTP/HTTPS remain on all interfaces (0.0.0.0) for device testing
+  - Local database tools (TablePlus, Sequel Pro, etc.) still work perfectly
+  
+  **Security Problem:** Default Docker port binding (`3306:3306`) exposes database on all network interfaces (0.0.0.0), including public WiFi. Confidential data accessible to anyone on the network.
+  
+  **Solution:** Explicit localhost binding (`127.0.0.1:3306:3306`) restricts access to the laptop only. Network isolation provides defense-in-depth beyond password protection.
+  
+  **Implementation:**
+  ```javascript
+  // Database - localhost only (network isolated)
+  ports: [`127.0.0.1:${config.ports.db}:3306`]
+  
+  // Redis - localhost only (session data protected)
+  ports: [`127.0.0.1:${config.ports.redis}:6379`]
+  
+  // HTTP/HTTPS - all interfaces (device testing enabled)
+  ports: [`${config.ports.http}:80`, `${config.ports.https}:443`]
+  ```
+  
+  **Benefits:**
+  - Coffee shop/airport WiFi cannot reach database
+  - Brute-force attacks prevented by network isolation
+  - Zero performance impact
+  - Industry best practice (matching Laravel Sail, wp-env)
+  
+  **Breaking Change Note:** Existing projects will need `buwp-local update` or restart to apply new port bindings. Database access from phones/tablets/other computers will no longer work (rare use case).
+
 ### Potential Features
 
-- **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.
+- **Ability to add custom WORDPRESS_CONFIG_EXTRA environment variables**
+  - Support for adding custom WP config snippets via env vars
+
+- **Credential Export**
+  - Commands to export credentials to JSON file
+  - Useful for migrating between machines or sharing setup
+
+- **Advanced Port Binding Configuration**
+  - Optional config to override localhost-only binding for database/Redis
+  - For advanced users who need network access to services
+  - Example: `"portBindings": { "db": "0.0.0.0", "redis": "127.0.0.1" }`
 
 - **Xdebug Integration**
   - Command to help generate Xdebug configuration for IDEs (VSCode, Zed)
@@ -207,9 +260,6 @@ 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
 

package/lib/commands/watch-jobs.js

@@ -0,0 +1,192 @@
+/**
+ * Watch Jobs command - Periodically process site-manager jobs
+ * Mirrors production cron/EventBridge behavior for local development
+ */
+
+import chalk from 'chalk';
+import { execSync, exec } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { loadConfig } from '../config.js';
+
+const DEFAULT_INTERVAL = 60; // 1 minute in seconds
+const MIN_INTERVAL = 10; // Minimum 10 seconds
+
+/**
+ * Format timestamp for log output
+ */
+function timestamp() {
+  const now = new Date();
+  return now.toLocaleString('en-US', {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false
+  }).replace(',', '');
+}
+
+/**
+ * Check if container is running
+ */
+function isContainerRunning(projectName, composePath) {
+  try {
+    const result = execSync(
+      `docker compose -p ${projectName} -f "${composePath}" ps --status running --services`,
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }
+    );
+    return result.includes('wordpress');
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Process site-manager jobs
+ */
+async function processJobs(projectName, composePath, quiet) {
+  return new Promise((resolve) => {
+    const composeDir = path.dirname(composePath);
+    const command = `docker compose -p ${projectName} -f "${composePath}" exec -T wordpress wp site-manager process-jobs`;
+
+    if (!quiet) {
+      console.log(chalk.gray(`[${timestamp()}] Checking for jobs...`));
+    }
+
+    exec(command, { cwd: composeDir }, (error, stdout, stderr) => {
+      if (error) {
+        // In quiet mode, silently retry on transient errors (container might restart)
+        // Only verbose mode shows these errors
+        if (!quiet) {
+          if (stderr.includes('container') || stderr.includes('not running')) {
+            console.log(chalk.yellow(`[${timestamp()}] ⚠️  Container not running. Waiting...`));
+          } else {
+            console.log(chalk.red(`[${timestamp()}] ❌ Error executing command:`));
+            console.log(chalk.red(stderr || error.message));
+          }
+        }
+        resolve(false);
+        return;
+      }
+
+      const output = stdout.trim();
+      
+      // Check if jobs were found and processed
+      if (output && output.length > 0) {
+        // In quiet mode, suppress all output (user checks web UI for job status)
+        // In verbose mode, show full job output
+        if (!quiet) {
+          console.log(chalk.green(`[${timestamp()}] ✓ Processing jobs:`));
+          console.log(output);
+        }
+        resolve(true);
+      } else if (!quiet) {
+        // No jobs found - only show in verbose mode
+        console.log(chalk.gray(`[${timestamp()}] No jobs found.`));
+        resolve(false);
+      } else {
+        // Quiet mode and no jobs - silent
+        resolve(false);
+      }
+    });
+  });
+}
+
+/**
+ * Watch jobs command
+ */
+async function watchJobsCommand(options) {
+  try {
+    const projectPath = process.cwd();
+    const composePath = path.join(projectPath, '.buwp-local', 'docker-compose.yml');
+
+    // Check if docker-compose.yml exists
+    if (!fs.existsSync(composePath)) {
+      console.log(chalk.yellow('⚠️  No running environment found.'));
+      console.log(chalk.gray('Run "buwp-local start" to create an environment.\n'));
+      return;
+    }
+
+    // Load config to get project name and optional interval setting
+    const config = loadConfig(projectPath);
+    const projectName = config.projectName || 'buwp-local';
+
+    // Determine interval (priority: CLI flag > config file > default)
+    let interval = DEFAULT_INTERVAL;
+    if (options.interval) {
+      interval = parseInt(options.interval, 10);
+      if (isNaN(interval) || interval < MIN_INTERVAL) {
+        console.log(chalk.red(`❌ Invalid interval. Minimum is ${MIN_INTERVAL} seconds.`));
+        process.exit(1);
+      }
+    } else if (config.jobWatchInterval) {
+      interval = config.jobWatchInterval;
+      if (interval < MIN_INTERVAL) {
+        console.log(chalk.yellow(`⚠️  Config interval too low. Using minimum: ${MIN_INTERVAL}s`));
+        interval = MIN_INTERVAL;
+      }
+    }
+
+    const quiet = options.quiet || false;
+
+    // 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('Start Docker Desktop and try again.'));
+      process.exit(1);
+    }
+
+    // Check if container is running initially
+    if (!isContainerRunning(projectName, composePath)) {
+      console.log(chalk.yellow('⚠️  WordPress container is not running.'));
+      console.log(chalk.gray('Run "buwp-local start" first, then try again.\n'));
+      return;
+    }
+
+    // Display startup message
+    console.log(chalk.cyan('🔍 Watching for site-manager jobs...'));
+    console.log(chalk.gray(`   Interval: ${interval}s`));
+    console.log(chalk.gray(`   Project: ${projectName}`));
+    console.log(chalk.gray(`   Mode: ${quiet ? 'quiet' : 'verbose'}`));
+    console.log(chalk.gray('\nPress Ctrl+C to stop\n'));
+
+    // Set up graceful shutdown
+    let isShuttingDown = false;
+    const shutdown = () => {
+      if (isShuttingDown) return;
+      isShuttingDown = true;
+      console.log(chalk.cyan('\n\n👋 Stopping job watcher...'));
+      process.exit(0);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+
+    // Main watch loop
+    const watch = async () => {
+      // Check if we should stop
+      if (isShuttingDown) return;
+
+      // Process jobs
+      await processJobs(projectName, composePath, quiet);
+
+      // Schedule next check
+      if (!isShuttingDown) {
+        setTimeout(watch, interval * 1000);
+      }
+    };
+
+    // Start watching
+    await watch();
+
+  } catch (err) {
+    console.error(chalk.red('\n❌ Error:'), err.message);
+    process.exit(1);
+  }
+}
+
+export default watchJobsCommand;

package/lib/compose-generator.js

@@ -66,7 +66,7 @@ function generateDbService(config, dbVolumeName) {
       MYSQL_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}',
       MYSQL_ROOT_PASSWORD: '${DB_ROOT_PASSWORD:-rootpassword}'
     },
-    ports: [`${config.ports.db}:3306`],
+    ports: [`127.0.0.1:${config.ports.db}:3306`],
     networks: ['wp-network']
   };
 }
@@ -212,7 +212,7 @@ function generateRedisService(config) {
   return {
     image: 'redis:alpine',
     restart: 'always',
-    ports: [`${config.ports.redis}:6379`],
+    ports: [`127.0.0.1:${config.ports.redis}:6379`],
     networks: ['wp-network']
   };
 }

package/package.json

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