@bostonuniversity/buwp-local 0.3.0 → 0.4.1

package/.buwp-local.json

@@ -0,0 +1,22 @@
+{
+  "projectName": "buwp-local",
+  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-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
+  }
+}

package/.env.local.example

@@ -0,0 +1,26 @@
+# BU WordPress Local Development Environment Variables
+# Copy this file to .env.local and fill in your actual credentials
+# NEVER commit .env.local to version control!
+
+# Database Credentials
+WORDPRESS_DB_PASSWORD=password
+DB_ROOT_PASSWORD=rootpassword
+
+# Shibboleth Configuration (if enabled)
+SP_ENTITY_ID=https://your-sp-entity-id
+IDP_ENTITY_ID=https://shib-test.bu.edu/idp/shibboleth
+SHIB_IDP_LOGOUT=https://shib-test.bu.edu/idp/logout.jsp
+SHIB_SP_KEY=your-private-key-here
+SHIB_SP_CERT=your-certificate-here
+
+# AWS S3 Configuration (if enabled)
+S3_UPLOADS_BUCKET=your-bucket-name
+S3_UPLOADS_REGION=us-east-1
+S3_UPLOADS_ACCESS_KEY_ID=AKIA...
+S3_UPLOADS_SECRET_ACCESS_KEY=your-secret-key
+S3_ACCESS_RULES_TABLE=your-access-rules-table
+
+# OLAP Configuration (if using S3 Object Lambda)
+OLAP=your-olap-name
+OLAP_ACCT_NBR=123456789
+OLAP_REGION=us-east-1

package/USAGE.md

@@ -10,14 +10,23 @@ npm install --save-dev @bostonuniversity/buwp-local
 
 ### 2. Initialize configuration
 
+**Interactive mode (recommended):**
 ```bash
-npx buwp-local config --init
+npx buwp-local init
 ```
 
+The interactive setup will guide you through:
+- Project name and type (plugin, theme, mu-plugin)
+- Hostname configuration
+- Port selection
+- Service options (Redis, S3, Shibboleth)
+- Debug settings
+
+**Non-interactive mode:**
 ```bash
-buwp-local config --init --plugin      # For plugins
-buwp-local config --init --mu-plugin   # For mu-plugins
-buwp-local config --init --theme       # For themes
+npx buwp-local config --init --plugin      # For plugins
+npx buwp-local config --init --mu-plugin   # For mu-plugins
+npx buwp-local config --init --theme       # For themes
 ```
 
 This creates `.buwp-local.json` in your project directory.
@@ -42,7 +51,13 @@ Edit `.buwp-local.json` to map your local repository into the container:
 
 ### 4. Create `.env.local` for secrets
 
-Create `.env.local` (never commit this file!):
+Create `.env.local` (never commit this file!) or copy from the example:
+
+```bash
+cp .env.local.example .env.local
+```
+
+Then edit `.env.local` with your actual credentials:
 
 ```bash
 # Database
@@ -61,6 +76,7 @@ S3_UPLOADS_BUCKET=your-bucket
 S3_UPLOADS_REGION=us-east-1
 S3_UPLOADS_ACCESS_KEY_ID=your-access-key
 S3_UPLOADS_SECRET_ACCESS_KEY=your-secret-key
+S3_ACCESS_RULES_TABLE=your-access-rules-table
 
 # OLAP
 OLAP=your-olap-name
@@ -68,6 +84,8 @@ OLAP_ACCT_NBR=your-account-number
 OLAP_REGION=us-east-1
 ```
 
+**Important:** Credentials are read directly from `.env.local` by Docker Compose. They are never written to the generated `docker-compose.yml` file, making it safe to review or share the generated compose file without exposing secrets.
+
 ### 5. Add hostname to /etc/hosts
 
 ```bash
@@ -86,6 +104,23 @@ Open http://username.local or https://username.local in your browser.
 
 ## Commands
 
+### Initialize configuration
+```bash
+npx buwp-local init
+
+Options:
+  --no-interactive  Use non-interactive mode with defaults
+  --plugin          Non-interactive: initialize as plugin
+  --mu-plugin       Non-interactive: initialize as mu-plugin
+  --theme           Non-interactive: initialize as theme
+  -f, --force       Overwrite existing configuration
+```
+
+The `init` command provides an interactive setup experience with:
+- **Smart defaults** - Detects project type from files
+- **Real-time validation** - Validates inputs as you type
+- **Guided workflow** - Clear prompts for all configuration options
+
 ### Start environment
 ```bash
 npx buwp-local start [options]
@@ -200,10 +235,27 @@ Map your local code into the container:
 ## Security Best Practices
 
 1. **Never commit `.env.local`** - This file contains secrets
-2. **Never commit `.buwp-local/`** - This contains generated files
-3. **Do commit `.buwp-local.json`** - This is your configuration template
-4. **Use environment variables for all secrets**
-5. **Consider using macOS Keychain** for even better security (see docs)
+2. **Never commit `.buwp-local/`** - This directory contains generated files
+3. **Do commit `.buwp-local.json`** - This is your configuration template (no secrets)
+4. **Use environment variables for all secrets** - Credentials stay in `.env.local` and are never written to generated files
+5. **Review generated compose files** - The generated `docker-compose.yml` only contains variable references like `${WORDPRESS_DB_PASSWORD}`, not actual credentials
+6. **Copy `.env.local.example`** - Use the provided template to create your `.env.local` file
+7. **Consider using macOS Keychain** for even better security (future feature)
+
+### How Credentials Work
+
+buwp-local uses Docker Compose's native environment variable interpolation:
+
+1. **You provide** credentials in `.env.local`
+2. **buwp-local generates** `docker-compose.yml` with variable references like `${VAR_NAME}`
+3. **Docker Compose reads** `.env.local` at runtime and substitutes the values
+4. **Your secrets never** get written to any generated files
+
+This means:
+- ✅ Generated compose files are safe to review or share
+- ✅ No credentials in version control (even accidentally)
+- ✅ Industry-standard Docker Compose pattern
+- ✅ Simple and secure
 
 ## File Structure
 

package/bin/buwp-local.js

@@ -28,6 +28,7 @@ import logsCommand from '../lib/commands/logs.js';
 import wpCommand from '../lib/commands/wp.js';
 import shellCommand from '../lib/commands/shell.js';
 import configCommand from '../lib/commands/config.js';
+import initCommand from '../lib/commands/init.js';
 
 const program = new Command();
 
@@ -78,6 +79,17 @@ program
   .option('--show', 'Show resolved configuration')
   .action(configCommand);
 
+// Init command (interactive configuration)
+program
+  .command('init')
+  .description('Initialize configuration interactively')
+  .option('--no-interactive', 'Use non-interactive mode with defaults')
+  .option('--plugin', 'Non-interactive: initialize as plugin')
+  .option('--mu-plugin', 'Non-interactive: initialize as mu-plugin')
+  .option('--theme', 'Non-interactive: initialize as theme')
+  .option('-f, --force', 'Overwrite existing configuration')
+  .action(initCommand);
+
 // WP-CLI proxy command
 program
   .command('wp <args...>')

package/lib/commands/init.js

@@ -0,0 +1,312 @@
+/**
+ * Init command - Interactive configuration initialization
+ */
+
+import prompts from 'prompts';
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { initConfig, CONFIG_FILE_NAME } from '../config.js';
+
+/**
+ * Detect project type from package.json or directory structure
+ * @param {string} projectPath - Path to project directory
+ * @returns {string|null} Detected project type or null
+ */
+function detectProjectType(projectPath) {
+  // Check package.json for hints
+  const packageJsonPath = path.join(projectPath, 'package.json');
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      
+      // Check keywords
+      if (pkg.keywords) {
+        if (pkg.keywords.includes('wordpress-plugin')) return 'plugin';
+        if (pkg.keywords.includes('wordpress-theme')) return 'theme';
+        if (pkg.keywords.includes('wordpress-muplugin')) return 'mu-plugin';
+      }
+      
+      // Check name patterns
+      if (pkg.name) {
+        if (pkg.name.includes('-plugin')) return 'plugin';
+        if (pkg.name.includes('-theme')) return 'theme';
+        if (pkg.name.includes('mu-')) return 'mu-plugin';
+      }
+    } catch (err) {
+      // Ignore errors reading package.json
+    }
+  }
+  
+  // Check for common WordPress files
+  if (fs.existsSync(path.join(projectPath, 'style.css'))) {
+    const styleContent = fs.readFileSync(path.join(projectPath, 'style.css'), 'utf8');
+    if (styleContent.includes('Theme Name:')) return 'theme';
+  }
+  
+  // Check for plugin header
+  const phpFiles = fs.readdirSync(projectPath).filter(f => f.endsWith('.php'));
+  for (const phpFile of phpFiles) {
+    const content = fs.readFileSync(path.join(projectPath, phpFile), 'utf8');
+    if (content.includes('Plugin Name:')) return 'plugin';
+  }
+  
+  return null; // Could not detect
+}
+
+/**
+ * Interactive initialization command
+ * @param {object} options - Command options
+ */
+async function initCommand(options) {
+  const projectPath = process.cwd();
+  const configPath = path.join(projectPath, CONFIG_FILE_NAME);
+  
+  const userName = os.userInfo().username;
+  
+  console.log(chalk.blue(`👋 Hello, ${userName}! Let's set up your WordPress local development environment.\n`));
+
+  // Check if config already exists
+  if (fs.existsSync(configPath) && !options.force) {
+    console.log(chalk.yellow(`⚠️  Configuration file already exists: ${configPath}`));
+    console.log(chalk.gray('Use --force to overwrite.\n'));
+    return;
+  }
+  
+  // Check if we should use interactive mode
+  const isInteractive = options.interactive !== false && process.stdin.isTTY;
+  
+  if (!isInteractive) {
+    // Fall back to non-interactive mode
+    console.log(chalk.gray('Non-interactive mode: using defaults\n'));
+    const initOptions = {};
+    if (options.plugin) initOptions.plugin = true;
+    if (options.muPlugin) initOptions.muPlugin = true;
+    if (options.theme) initOptions.theme = true;
+    
+    const configPath = initConfig(projectPath, initOptions);
+    console.log(chalk.green(`✅ Created configuration file: ${configPath}\n`));
+    return;
+  }
+  
+  // Interactive mode
+  console.log(chalk.blue('🚀 Interactive configuration setup\n'));
+  console.log(chalk.gray('Press Ctrl+C to cancel at any time\n'));
+  
+  const detectedName = path.basename(projectPath);
+  const detectedType = detectProjectType(projectPath);
+  
+  if (detectedType) {
+    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;
+  
+  const questions = [
+    {
+      type: 'text',
+      name: 'projectName',
+      message: 'Project name',
+      initial: detectedName,
+      validate: value => value.trim().length > 0 || 'Project name is required'
+    },
+    {
+      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' }
+      ],
+      initial: defaultTypeIndex
+    },
+    {
+      type: 'text',
+      name: 'hostname',
+      message: 'Hostname',
+      initial: (prev, values) => {
+        // For sandbox, use just username.local; for other types include project name
+        if (values.projectType === 'sandbox') {
+          return `${userName}.local`;
+        }
+        return `${userName}-${values.projectName}.local`;
+      },
+      validate: value => {
+        if (!value.trim()) return 'Hostname is required';
+        if (!value.includes('.')) return 'Hostname should include a domain (e.g., .local)';
+        return true;
+      }
+    },
+    {
+      type: 'text',
+      name: 'image',
+      message: 'WordPress Docker image',
+      initial: 'ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest',
+      validate: value => {
+        if (!value.trim()) return 'Image name is required';
+        return true;
+      }
+    },
+    {
+      type: 'text',
+      name: 'httpPort',
+      message: 'HTTP port (default: 80)',
+      initial: '80',
+      validate: value => {
+        const port = parseInt(value);
+        if (isNaN(port) || port < 1 || port > 65535) return 'Port must be a number between 1 and 65535';
+        return true;
+      }
+    },
+    {
+      type: 'text',
+      name: 'httpsPort',
+      message: 'HTTPS port (default: 443)',
+      initial: '443',
+      validate: value => {
+        const port = parseInt(value);
+        if (isNaN(port) || port < 1 || port > 65535) return 'Port must be a number between 1 and 65535';
+        return true;
+      }
+    },
+    {
+      type: 'text',
+      name: 'dbPort',
+      message: 'Database port (default: 3306)',
+      initial: '3306',
+      validate: value => {
+        const port = parseInt(value);
+        if (isNaN(port) || port < 1 || port > 65535) return 'Port must be a number between 1 and 65535';
+        return true;
+      }
+    },
+    {
+      type: 'confirm',
+      name: 'redis',
+      message: 'Enable Redis?',
+      initial: true
+    },
+    {
+      type: 'confirm',
+      name: 's3proxy',
+      message: 'Enable S3 proxy?',
+      initial: true
+    },
+    {
+      type: 'confirm',
+      name: 'shibboleth',
+      message: 'Enable Shibboleth?',
+      initial: true
+    },
+    {
+      type: 'confirm',
+      name: 'xdebug',
+      message: 'Enable Xdebug by default?',
+      initial: false
+    }
+  ];
+  
+  const answers = await prompts(questions, {
+    onCancel: () => {
+      console.log(chalk.yellow('\n⚠️  Setup cancelled\n'));
+      process.exit(0);
+    }
+  });
+  
+  // Build configuration object
+  const config = {
+    projectName: answers.projectName,
+    image: answers.image,
+    hostname: answers.hostname,
+    multisite: true,
+    services: {
+      redis: answers.redis || false,
+      s3proxy: answers.s3proxy || false,
+      shibboleth: answers.shibboleth || false
+    },
+    ports: {
+      http: parseInt(answers.httpPort),
+      https: parseInt(answers.httpsPort),
+      db: parseInt(answers.dbPort),
+      redis: 6379
+    },
+    mappings: [],
+    env: {
+      WP_DEBUG: true,
+      XDEBUG: answers.xdebug || false
+    }
+  };
+  
+  // 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
+    config.mappings.push({
+      local: './',
+      container: '/var/www/html/wp-content/plugins/my-plugin',
+      comment: 'Customize this mapping for your project'
+    });
+  }
+  
+  // Write configuration file
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  
+  console.log(chalk.green(`\n✅ Created configuration file: ${configPath}\n`));
+  
+  // Show summary
+  console.log(chalk.cyan('📋 Configuration summary:'));
+  console.log(chalk.gray(`  Project: ${answers.projectName}`));
+  console.log(chalk.gray(`  Type: ${answers.projectType}`));
+  console.log(chalk.gray(`  Hostname: ${answers.hostname}`));
+  console.log(chalk.gray(`  Image: ${answers.image}`));
+  console.log(chalk.gray(`  HTTP port: ${answers.httpPort}`));
+  console.log(chalk.gray(`  HTTPS port: ${answers.httpsPort}`));
+  console.log(chalk.gray(`  Services: ${[
+    answers.redis && 'Redis',
+    answers.s3proxy && 'S3',
+    answers.shibboleth && 'Shibboleth'
+  ].filter(Boolean).join(', ') || 'None'}\n`));
+  
+  // Show next steps
+  console.log(chalk.cyan('📝 Next steps:'));
+  console.log(chalk.gray('  1. Create .env.local with your credentials'));
+  console.log(chalk.gray(`  2. Add to /etc/hosts: 127.0.0.1 ${answers.hostname}`));
+  
+  if (answers.projectType === 'sandbox') {
+    console.log(chalk.gray('  3. Edit .buwp-local.json and add volume mappings to the mappings array'));
+    console.log(chalk.gray('  4. Run: buwp-local start'));
+    console.log(chalk.gray(`\n  Example mapping for .buwp-local.json mappings array:`));
+    console.log(chalk.gray(`  { "local": "/path/to/plugin", "container": "/var/www/html/wp-content/plugins/my-plugin" }`));
+  } else {
+    console.log(chalk.gray('  3. Run: buwp-local start'));
+  }
+  
+  console.log(chalk.gray(`\n  Then access: https://${answers.hostname}\n`));
+}
+
+export default initCommand;

package/lib/commands/start.js

@@ -5,7 +5,8 @@
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import path from 'path';
-import { loadConfig, validateConfig } from '../config.js';
+import fs from 'fs';
+import { loadConfig, validateConfig, ENV_FILE_NAME } from '../config.js';
 import { generateComposeFile } from '../compose-generator.js';
 
 async function startCommand(options) {
@@ -60,9 +61,13 @@ async function startCommand(options) {
     const composeDir = path.dirname(composePath);
     const projectName = config.projectName || 'buwp-local';
     
+    // Check if .env.local exists and build env-file flag
+    const envFilePath = path.join(projectPath, ENV_FILE_NAME);
+    const envFileFlag = fs.existsSync(envFilePath) ? `--env-file ${envFilePath}` : '';
+    
     try {
       execSync(
-        `docker compose -p ${projectName} -f ${composePath} up -d`,
+        `docker compose -p ${projectName} ${envFileFlag} -f ${composePath} up -d`,
         { 
           cwd: composeDir,
           stdio: 'inherit'

package/lib/compose-generator.js

@@ -57,9 +57,6 @@ function generateComposeConfig(config) {
  * @returns {object} Database service config
  */
 function generateDbService(config, dbVolumeName) {
-  const dbPassword = config.db?.password || 'password';
-  const rootPassword = config.db?.rootPassword || 'rootpassword';
-
   return {
     image: 'mariadb:latest',
     restart: 'always',
@@ -67,8 +64,8 @@ function generateDbService(config, dbVolumeName) {
     environment: {
       MYSQL_DATABASE: 'wordpress',
       MYSQL_USER: 'wordpress',
-      MYSQL_PASSWORD: dbPassword,
-      MYSQL_ROOT_PASSWORD: rootPassword
+      MYSQL_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}',
+      MYSQL_ROOT_PASSWORD: '${DB_ROOT_PASSWORD:-rootpassword}'
     },
     ports: [`${config.ports.db}:3306`],
     networks: ['wp-network']
@@ -91,7 +88,7 @@ function generateWordPressService(config, wpVolumeName) {
   const environment = {
     WORDPRESS_DB_HOST: 'db:3306',
     WORDPRESS_DB_USER: 'wordpress',
-    WORDPRESS_DB_PASSWORD: config.db?.password || 'password',
+    WORDPRESS_DB_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}',
     WORDPRESS_DB_NAME: 'wordpress',
     WORDPRESS_DEBUG: config.env?.WP_DEBUG || '0',
     SERVER_NAME: config.hostname,
@@ -104,11 +101,11 @@ function generateWordPressService(config, wpVolumeName) {
 
   // Add Shibboleth config if enabled
   if (config.services.shibboleth) {
-    environment.SP_ENTITY_ID = config.shibboleth?.entityId || '';
-    environment.IDP_ENTITY_ID = config.shibboleth?.idpEntityId || '';
-    environment.SHIB_IDP_LOGOUT = config.shibboleth?.idpLogout || '';
-    environment.SHIB_SP_KEY = config.shibboleth?.spKey || '';
-    environment.SHIB_SP_CERT = config.shibboleth?.spCert || '';
+    environment.SP_ENTITY_ID = '${SP_ENTITY_ID:-}';
+    environment.IDP_ENTITY_ID = '${IDP_ENTITY_ID:-}';
+    environment.SHIB_IDP_LOGOUT = '${SHIB_IDP_LOGOUT:-}';
+    environment.SHIB_SP_KEY = '${SHIB_SP_KEY:-}';
+    environment.SHIB_SP_CERT = '${SHIB_SP_CERT:-}';
   }
 
   // Add S3 config if enabled
@@ -130,12 +127,12 @@ function generateWordPressService(config, wpVolumeName) {
     wpConfigExtra += "define('SUBDOMAIN_INSTALL', false);\n";
   }
 
-  if (config.services.s3proxy && config.s3) {
-    wpConfigExtra += `define('S3_UPLOADS_BUCKET', '${config.s3.bucket || ''}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_REGION', '${config.s3.region || 'us-east-1'}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_KEY', '${config.s3.accessKeyId || ''}');\n`;
-    wpConfigExtra += `define('S3_UPLOADS_SECRET', '${config.s3.secretAccessKey || ''}');\n`;
-    wpConfigExtra += `define('ACCESS_RULES_TABLE', '${config.s3.accessRulesTable || ''}');\n`;
+  if (config.services.s3proxy) {
+    wpConfigExtra += "define('S3_UPLOADS_BUCKET', '${S3_UPLOADS_BUCKET}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_REGION', '${S3_UPLOADS_REGION:-us-east-1}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_KEY', '${S3_UPLOADS_ACCESS_KEY_ID}');\n";
+    wpConfigExtra += "define('S3_UPLOADS_SECRET', '${S3_UPLOADS_SECRET_ACCESS_KEY}');\n";
+    wpConfigExtra += "define('ACCESS_RULES_TABLE', '${S3_ACCESS_RULES_TABLE}');\n";
     wpConfigExtra += "define('S3_UPLOADS_OBJECT_ACL', null);\n";
     wpConfigExtra += "define('S3_UPLOADS_AUTOENABLE', true);\n";
     wpConfigExtra += "define('S3_UPLOADS_DISABLE_REPLACE_UPLOAD_URL', true);\n";
@@ -183,14 +180,10 @@ function generateWordPressService(config, wpVolumeName) {
 
 /**
  * Generate S3 proxy service configuration
- * @param {object} config - buwp-local configuration
+ * @param {object} _config - buwp-local configuration (unused - env vars used instead)
  * @returns {object} S3 proxy service config
  */
-function generateS3ProxyService(config) {
-  const region = config.olap?.region || config.s3?.region || 'us-east-1';
-  const olapName = config.olap?.name || '';
-  const olapAcctNbr = config.olap?.accountNumber || '';
-
+function generateS3ProxyService(_config) {
   return {
     image: 'public.ecr.aws/bostonuniversity-nonprod/aws-sigv4-proxy',
     restart: 'always',
@@ -199,16 +192,16 @@ function generateS3ProxyService(config) {
       '--name',
       's3-object-lambda',
       '--region',
-      region,
+      '${OLAP_REGION:-us-east-1}',
       '--no-verify-ssl',
       '--host',
-      `${olapName}-${olapAcctNbr}.s3-object-lambda.${region}.amazonaws.com`
+      '${OLAP}-${OLAP_ACCT_NBR}.s3-object-lambda.${OLAP_REGION:-us-east-1}.amazonaws.com'
     ],
     environment: {
       healthcheck_path: '/s3proxy-healthcheck',
-      AWS_ACCESS_KEY_ID: config.s3?.accessKeyId || '',
-      AWS_SECRET_ACCESS_KEY: config.s3?.secretAccessKey || '',
-      REGION: region
+      AWS_ACCESS_KEY_ID: '${S3_UPLOADS_ACCESS_KEY_ID}',
+      AWS_SECRET_ACCESS_KEY: '${S3_UPLOADS_SECRET_ACCESS_KEY}',
+      REGION: '${S3_UPLOADS_REGION:-us-east-1}'
     },
     networks: ['wp-network']
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bostonuniversity/buwp-local",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Local WordPress development environment for Boston University projects",
   "type": "module",
   "main": "lib/index.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "buwp-local": "node bin/buwp-local.js config --init --mu-plugin",
+    "buwp-local": "node bin/buwp-local.js start",
     "lint": "eslint ."
   },
   "keywords": [
@@ -28,9 +28,11 @@
     "js-yaml": "^4.1.0",
     "chalk": "^4.1.2",
     "commander": "^11.0.0",
-    "dotenv": "^16.3.1"
+    "dotenv": "^16.3.1",
+    "prompts": "^2.4.2"
   },
   "devDependencies": {
+    "@types/prompts": "^2.4.9",
     "eslint": "^8.50.0"
   }
 }

package/plan-environmentBasedCredentials.prompt.md

@@ -0,0 +1,57 @@
+## Plan: Environment-Based Credentials Migration (v0.4.1)
+
+We've successfully shipped v0.4.0 with interactive init, sandbox support, configurable Docker images, and smart hostname defaults. The codebase is in excellent shape with real-world testing validated in both plugin and sandbox scenarios.
+
+**Current Problem:** Credentials (database passwords, AWS keys, Shibboleth certs) are currently being read from the config/environment and then **written directly into the generated `docker-compose.yml`**. This means sensitive data sits in a generated file, which isn't ideal for security.
+
+**Better Approach:** Use Docker Compose's native environment variable interpolation (`${VAR_NAME}`) so credentials stay in `.env.local` and never get written to the compose file.
+
+### Steps
+
+1. **Update `compose-generator.js` to use environment variable references**
+   - Database service: Change from `MYSQL_PASSWORD: dbPassword` to `MYSQL_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}'`
+   - WordPress service: Change from `WORDPRESS_DB_PASSWORD: config.db?.password` to `WORDPRESS_DB_PASSWORD: '${WORDPRESS_DB_PASSWORD:-password}'`
+   - S3 proxy service: Change from `AWS_ACCESS_KEY_ID: config.s3?.accessKeyId` to `AWS_ACCESS_KEY_ID: '${S3_UPLOADS_ACCESS_KEY_ID}'`
+   - WordPress `WORDPRESS_CONFIG_EXTRA`: Change from injecting actual S3 keys to using `${S3_UPLOADS_ACCESS_KEY_ID}` references
+
+2. **Update `start.js` to pass `.env.local` to docker compose**
+   - Add `--env-file` flag to `docker compose up` command
+   - Ensure `.env.local` path is correctly resolved relative to project
+
+3. **Update config loading to remove credential reading**
+   - Keep `extractEnvVars()` for backward compatibility but mark as deprecated
+   - Config validation no longer needs to check for credential presence in config object
+   - Document that credentials should only live in `.env.local`
+
+4. **Update documentation**
+   - `USAGE.md` - Clarify that `.env.local` is the source of truth for credentials
+   - Add example showing compose file will have `${VAR}` references
+   - Security best practices section emphasizes this approach
+
+5. **Test migration path**
+   - Verify existing projects with credentials in config still work (backward compat)
+   - Test new projects using only `.env.local`
+   - Verify generated compose file contains variable references, not actual values
+   - Ensure `docker compose` properly reads `.env.local`
+
+### Further Considerations
+
+1. **Backward compatibility**: Should we warn users if credentials exist in config? Or silently prefer `.env.local`?
+2. **`.env.local` template**: Should we create `.env.local.example` during `init` command?
+3. **Validation**: Should `config --validate` check that `.env.local` exists and has required variables?
+
+---
+
+**Why This Matters:**
+- **Security**: Credentials never written to files, only referenced
+- **Git safety**: Generated compose files are safe to accidentally commit (no secrets)
+- **Best practices**: Aligns with Docker Compose's standard env var pattern
+- **Simplicity**: Reduces complexity in config merging logic
+
+**Effort Estimate:** Low-Medium (4-6 hours)
+- Compose generation changes: ~2 hours
+- Start command changes: ~1 hour  
+- Documentation: ~1 hour
+- Testing: ~1-2 hours
+
+**Ready to proceed?** This sets up a cleaner foundation before tackling Phase 2 features like keychain integration.

package/SHARED_ENVIRONMENT_EXAMPLES.md

@@ -1,578 +0,0 @@
-# Shared Environment - Practical Examples
-
-## Example 1: Team Integration Sandbox
-
-### Scenario
-A team of 4 developers working on BU's WordPress site needs a shared local environment with:
-- Custom theme (responsive-framework)
-- Navigation plugin (bu-navigation)  
-- Analytics plugin (bu-custom-analytics)
-- Slideshow plugin (bu-slideshow)
-
-### Setup
-
-**Step 1: Create Primary Configuration Repo**
-```bash
-mkdir -p ~/projects/bu-team-sandbox
-cd ~/projects/bu-team-sandbox
-
-# Initialize
-buwp-local config --init
-
-# Edit .buwp-local.json:
-{
-  "projectName": "bu-team-sandbox",
-  "hostname": "buteam.local",
-  "multisite": true,
-  "services": {
-    "redis": true,
-    "s3proxy": true,
-    "shibboleth": true
-  },
-  "ports": {
-    "http": 80,
-    "https": 443,
-    "db": 3306,
-    "redis": 6379
-  },
-  "mappings": [],
-  "env": {
-    "WP_DEBUG": true,
-    "WP_DEBUG_LOG": true,
-    "XDEBUG": false
-  }
-}
-
-# Create .env.local with credentials
-# Start environment
-buwp-local start
-```
-
-**Step 2: Each Developer Adds Their Repo**
-
-**Developer 1 - Theme:**
-```bash
-cd ~/projects/responsive-framework
-buwp-local config --init --theme
-
-# Edit .buwp-local.json to join shared sandbox:
-{
-  "projectName": "bu-team-sandbox",  # SHARED!
-  "hostname": "buteam.local",
-  "multisite": true,
-  "services": {
-    "redis": true,
-    "s3proxy": true,
-    "shibboleth": true
-  },
-  "ports": {
-    "http": 80,
-    "https": 443,
-    "db": 3306,
-    "redis": 6379
-  },
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/themes/responsive-framework"
-    }
-  ],
-  "env": {
-    "WP_DEBUG": true
-  }
-}
-
-# Symlink shared credentials
-ln -s ~/projects/bu-team-sandbox/.env.local .env.local
-
-# Add theme to shared environment
-buwp-local start
-```
-
-**Developer 2 - Navigation Plugin:**
-```bash
-cd ~/projects/bu-navigation
-buwp-local config --init --plugin
-
-# Edit .buwp-local.json (same projectName):
-{
-  "projectName": "bu-team-sandbox",
-  "hostname": "buteam.local",
-  # ... same ports/services ...
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/plugins/bu-navigation"
-    }
-  ]
-}
-
-ln -s ~/projects/bu-team-sandbox/.env.local .env.local
-buwp-local start
-```
-
-**Developers 3 & 4 repeat for their plugins...**
-
-**Result:**
-- All 4 developers access http://buteam.local
-- All plugins and theme are active
-- Shared database with realistic test data
-- Each developer's file changes are live
-
----
-
-## Example 2: Solo Developer - Isolated + Shared
-
-### Scenario
-One developer working on `bu-custom-analytics` needs:
-- **Isolated environment** for feature development
-- **Shared environment** for integration testing with other plugins
-
-### Setup
-
-**Isolated Configuration** (`.buwp-local.json`):
-```json
-{
-  "projectName": "bu-custom-analytics",
-  "hostname": "analytics.local",
-  "multisite": true,
-  "services": {
-    "redis": true,
-    "s3proxy": false,
-    "shibboleth": false
-  },
-  "ports": {
-    "http": 80,
-    "https": 443,
-    "db": 3306,
-    "redis": 6379
-  },
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/plugins/bu-custom-analytics"
-    }
-  ],
-  "env": {
-    "WP_DEBUG": true,
-    "XDEBUG": true
-  }
-}
-```
-
-**Shared Configuration** (`.buwp-local.shared.json`):
-```json
-{
-  "projectName": "bu-integration",
-  "hostname": "buint.local",
-  "multisite": true,
-  "services": {
-    "redis": true,
-    "s3proxy": true,
-    "shibboleth": true
-  },
-  "ports": {
-    "http": 8080,
-    "https": 8443,
-    "db": 3307,
-    "redis": 6380
-  },
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/plugins/bu-custom-analytics"
-    }
-  ],
-  "env": {
-    "WP_DEBUG": true,
-    "XDEBUG": false
-  }
-}
-```
-
-### Workflow
-
-**Morning - Feature Development (Isolated):**
-```bash
-cd ~/projects/bu-custom-analytics
-
-# Use isolated config (default)
-buwp-local start
-
-# Develop at http://analytics.local
-# Fast, isolated, clean environment
-# Debug with Xdebug enabled
-```
-
-**Afternoon - Integration Testing (Shared):**
-```bash
-cd ~/projects/bu-custom-analytics
-
-# Stop isolated
-buwp-local stop
-
-# Switch to shared config
-cp .buwp-local.shared.json .buwp-local.json
-
-# Join shared integration environment
-buwp-local start
-
-# Test at http://buint.local:8080
-# Now running with other plugins/theme
-# Test interactions and integration points
-```
-
-**End of Day - Back to Isolated:**
-```bash
-# Restore isolated config
-git checkout .buwp-local.json
-
-# Back to isolated for tomorrow
-buwp-local destroy  # Clean up shared
-buwp-local start    # Start fresh isolated
-```
-
----
-
-## Example 3: Multi-Environment Matrix
-
-### Scenario
-Testing plugin compatibility across different configurations:
-- Modern stack (latest everything)
-- Legacy stack (older versions)
-- Production replica
-
-### Setup
-
-**Create 3 Separate Environments:**
-
-**Environment 1: Modern Stack**
-```bash
-cd ~/projects/bu-custom-analytics
-
-# .buwp-local.modern.json:
-{
-  "projectName": "modern-stack",
-  "hostname": "modern.local",
-  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
-  # ... modern settings ...
-}
-
-cp .buwp-local.modern.json .buwp-local.json
-buwp-local start
-# Test at http://modern.local
-```
-
-**Environment 2: Legacy Stack**
-```bash
-# .buwp-local.legacy.json:
-{
-  "projectName": "legacy-stack",
-  "hostname": "legacy.local",
-  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:legacy-tag",
-  "ports": {
-    "http": 8081,
-    "db": 3307
-  }
-  # ... legacy settings ...
-}
-
-cp .buwp-local.legacy.json .buwp-local.json
-buwp-local start
-# Test at http://legacy.local:8081
-```
-
-**Environment 3: Production Replica**
-```bash
-# .buwp-local.prod.json:
-{
-  "projectName": "prod-replica",
-  "hostname": "prodlocal.local",
-  "ports": {
-    "http": 8082,
-    "db": 3308
-  }
-  # ... production-like settings ...
-}
-
-cp .buwp-local.prod.json .buwp-local.json
-buwp-local start
-# Test at http://prodlocal.local:8082
-```
-
-**Result:**
-- All 3 environments running simultaneously
-- Same plugin code in all 3
-- Different WordPress/PHP versions
-- Test compatibility across configurations
-
----
-
-## Example 4: Department-Wide Shared Sandbox
-
-### Scenario
-Marketing department (10 people) needs shared sandbox with:
-- Content editors
-- Designers  
-- Developers
-- QA testers
-
-### Setup
-
-**Central Configuration Repository:**
-```bash
-# Shared repo that everyone clones
-git clone https://github.com/bu-ist/bu-marketing-sandbox.git
-cd bu-marketing-sandbox
-
-# .buwp-local.json:
-{
-  "projectName": "bu-marketing",
-  "hostname": "marketing.local",
-  "multisite": true,
-  "services": {
-    "redis": true,
-    "s3proxy": true,
-    "shibboleth": true
-  },
-  "ports": {
-    "http": 80,
-    "https": 443,
-    "db": 3306,
-    "redis": 6379
-  },
-  "mappings": [
-    {
-      "local": "../responsive-framework",
-      "container": "/var/www/html/wp-content/themes/responsive-framework"
-    },
-    {
-      "local": "../bu-slideshow",
-      "container": "/var/www/html/wp-content/plugins/bu-slideshow"
-    },
-    {
-      "local": "../bu-analytics",
-      "container": "/var/www/html/wp-content/plugins/bu-analytics"
-    }
-  ],
-  "env": {
-    "WP_DEBUG": false  # Production-like for QA
-  }
-}
-
-# .env.local (shared credentials via 1Password/LastPass)
-# Includes test user accounts for all team members
-```
-
-**Each Team Member:**
-```bash
-# Clone central config
-git clone https://github.com/bu-ist/bu-marketing-sandbox.git ~/projects/bu-marketing-sandbox
-
-# Clone the repos to develop
-cd ~/projects
-git clone https://github.com/bu-ist/responsive-framework.git
-git clone https://github.com/bu-ist/bu-slideshow.git
-git clone https://github.com/bu-ist/bu-analytics.git
-
-# Start shared environment
-cd ~/projects/bu-marketing-sandbox
-# Add .env.local with shared credentials
-buwp-local start
-
-# Access http://marketing.local
-# All team members work in same environment
-```
-
-**Benefits:**
-- Designers see live changes to theme
-- Developers see plugin interactions
-- Content editors have realistic environment
-- QA tests actual configuration
-- Everyone shares same database with test content
-
----
-
-## Example 5: Feature Branch Testing
-
-### Scenario  
-Test a feature branch alongside main branch:
-- `main` branch in production-like environment
-- `feature/new-ui` branch in test environment
-
-### Setup
-
-**Main Branch Environment:**
-```bash
-cd ~/projects/bu-custom-analytics
-git checkout main
-
-# .buwp-local.json (default):
-{
-  "projectName": "bu-analytics-main",
-  "hostname": "analytics-main.local",
-  "ports": {
-    "http": 80,
-    "db": 3306
-  },
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/plugins/bu-custom-analytics"
-    }
-  ]
-}
-
-buwp-local start
-# Test main at http://analytics-main.local
-```
-
-**Feature Branch Environment:**
-```bash
-cd ~/projects/bu-custom-analytics
-git checkout feature/new-ui
-
-# Change projectName in .buwp-local.json:
-{
-  "projectName": "bu-analytics-feature",
-  "hostname": "analytics-feature.local",
-  "ports": {
-    "http": 8080,
-    "db": 3307
-  },
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/plugins/bu-custom-analytics"
-    }
-  ]
-}
-
-buwp-local start
-# Test feature at http://analytics-feature.local:8080
-```
-
-**Result:**
-- Both branches running simultaneously
-- Compare behavior side-by-side
-- Separate databases for each
-- No branch switching needed
-
----
-
-## Tips for Shared Environments
-
-### 1. Use Configuration Management
-```bash
-# Store configs in version control
-~/projects/
-├── bu-team-sandbox/           # Primary config repo
-│   ├── .buwp-local.json
-│   ├── .env.local.example
-│   └── README.md
-├── plugin-a/
-│   ├── .buwp-local.json       # Points to shared
-│   └── .env.local -> ../bu-team-sandbox/.env.local
-└── plugin-b/
-    ├── .buwp-local.json       # Points to shared
-    └── .env.local -> ../bu-team-sandbox/.env.local
-```
-
-### 2. Document Your Shared Environments
-Create a team wiki page:
-```markdown
-# Team Shared Environments
-
-## bu-team-sandbox
-- **URL:** http://buteam.local
-- **Purpose:** Integration testing
-- **Includes:** theme + all plugins
-- **Managed by:** @teamlead
-- **Config repo:** github.com/bu-ist/bu-team-sandbox
-
-## bu-staging-replica
-- **URL:** http://bustaging.local:8080  
-- **Purpose:** Pre-production testing
-- **Includes:** Production plugins only
-- **Managed by:** @qa-lead
-```
-
-### 3. Use Consistent Naming
-```bash
-# Good naming convention:
-bu-team-sandbox      # Team shared environment
-bu-integration       # Integration testing
-bu-staging-replica   # Staging mirror
-bu-prod-replica      # Production mirror
-
-# Avoid:
-sandbox
-test
-local
-dev
-```
-
-### 4. Regular Cleanup
-```bash
-# Weekly: Clean shared environments
-buwp-local destroy
-buwp-local start
-# Fresh start with clean database
-```
-
-### 5. Backup Shared Databases
-```bash
-# Before major changes:
-docker exec bu-team-sandbox-db-1 mysqldump -u wordpress -ppassword wordpress > backup-$(date +%Y%m%d).sql
-
-# Restore if needed:
-docker exec -i bu-team-sandbox-db-1 mysql -u wordpress -ppassword wordpress < backup-20251110.sql
-```
-
----
-
-## Troubleshooting Common Issues
-
-### Issue: "Port already in use"
-**Cause:** Another shared environment using same ports  
-**Solution:** Use different ports in shared config:
-```json
-{
-  "ports": {
-    "http": 8081,
-    "db": 3307
-  }
-}
-```
-
-### Issue: "My changes don't appear"
-**Cause:** Wrong repo's mapping is active  
-**Solution:** Check which repo last ran `start`:
-```bash
-docker compose -p bu-team-sandbox ps
-# See which volumes are mounted
-```
-
-### Issue: "Database has wrong data"
-**Cause:** Another developer made changes  
-**Solution:** Communicate or use separate environments
-
-### Issue: "Config out of sync"
-**Cause:** Repos have different settings  
-**Solution:** Use symlinks or central config repo
-
----
-
-## Summary
-
-Shared environments enable:
-- ✅ Team collaboration on integrated stack
-- ✅ Integration testing without deploy
-- ✅ Multiple development strategies
-- ✅ Flexible workflows (solo + team)
-- ✅ Realistic production-like testing
-
-Use the right tool for the job:
-- **Isolated** = Solo development, fast iteration
-- **Shared** = Integration, team collaboration
-- **Both** = Maximum flexibility