@bostonuniversity/buwp-local 0.7.2 → 0.7.3

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,13 @@ 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.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,8 +172,51 @@ 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: 5 minutes)
+  - Runs as standalone process in terminal window
+  - Timestamped output for job processing visibility
+  - 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.
+  
+  **Implementation location:** `lib/commands/watch-jobs.js`
+  
+  **Configuration support:**
+  ```json
+  {
+    "jobWatchInterval": 60  // seconds, default 60 seconds
+  }
+  ```
+  
+  **Command syntax:**
+  ```bash
+  buwp-local watch-jobs [--interval 200] [--quiet]
+  ```
+  
+  **Technical considerations:**
+  - Requires WordPress container to be running
+  - Uses `docker compose exec` to run WP-CLI command
+  - Handles container stop/restart gracefully
+  - Minimal resource usage (sleeps between checks)
+  - Output includes timestamps for audit trail
+  
+  **Future enhancement (v0.8.0+):** If widely adopted, consider adding `--watch-jobs` flag to `start` command for automatic background execution.
+
 ### Potential Features
 
+- **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
+
 - **Database Security**
   - Check database access on db port (e.g. `localhost:3306`)
   - Consider more stringent default database passwords
@@ -207,9 +250,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/package.json

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