@bostonuniversity/buwp-local 0.7.4 → 0.7.6

package/docs/ARCHITECTURE.md

@@ -465,78 +465,16 @@ This architecture provides clean boundaries:
 
 | Concern | Location | Update Mechanism |
 |---------|----------|------------------|
-| WordPress core | Docker image | `buwp-local update` |
-| BU plugins | Docker image | `buwp-local update` |
-| BU theme | Docker image | `buwp-local update` |
+| WordPress core | Docker image | `docker pull` |
+| BU plugins | Docker image | `docker pull` |
+| BU theme | Docker image | `docker pull` |
 | **Your plugin** | **Local filesystem** | **Your editor** |
 | **Your theme** | **Local filesystem** | **Your editor** |
-| Database | Docker volume (db_data) | Persists across updates |
-| **Uploads** | **S3 bucket** | **Via s3proxy** |
+| Database | Docker volume | Persists across updates |
+| Uploads | Docker volume | Persists across updates |
 
 Updates to WordPress never touch your development code. Updates to your code never require rebuilding WordPress.
 
-### S3 Upload Architecture
-
-A critical design decision enables safe WordPress core updates: **all media uploads are stored in S3, not in the container filesystem**.
-
-```
-WordPress Upload Flow:
-┌──────────────┐
-│   User       │ Uploads file via WP admin
-└──────┬───────┘
-       │
-       ↓
-┌──────────────────────────────────┐
-│  WordPress Container             │
-│                                  │
-│  BU S3 Uploads Plugin            │
-│  (intercepts upload)             │
-└──────┬───────────────────────────┘
-       │
-       ↓
-┌──────────────────────────────────┐
-│  s3proxy Container               │
-│  (AWS SigV4 authentication)      │
-└──────┬───────────────────────────┘
-       │
-       ↓
-┌──────────────────────────────────┐
-│  S3 Bucket                       │
-│  (permanent storage)             │
-└──────────────────────────────────┘
-```
-
-**Key Configuration** (from `compose-generator.js`):
-
-```javascript
-if (config.services.s3proxy) {
-  wpConfigExtra += "define('S3_UPLOADS_AUTOENABLE', true);\n";
-  wpConfigExtra += "define('S3_UPLOADS_DISABLE_REPLACE_UPLOAD_URL', true);\n";
-}
-```
-
-**What this means for updates:**
-
-The `wp_build` volume contains **zero user data**:
-- ✅ WordPress core files (disposable - from image)
-- ✅ BU plugins/themes (disposable - from image)
-- ❌ **No media uploads** (in S3 bucket)
-- ❌ **No database** (separate db_data volume)
-- ❌ **No custom code** (mapped from host filesystem)
-
-**Result:** The `wp_build` volume is purely infrastructure and can be safely wiped during updates to refresh WordPress core files.
-
-```bash
-# This is safe because:
-# - Database preserved (db_data volume)
-# - Uploads preserved (S3 bucket)  
-# - Your code preserved (local filesystem)
-npx buwp-local update  # Wipes wp_build, recreates from image
-```
-
-**Contrast with traditional WordPress:**
-In a standard WordPress installation, `wp-content/uploads/` contains irreplaceable user media files. In buwp-local, that directory is empty or contains only regenerable thumbnails/cache.
-
 For detailed migration guidance, see [MIGRATION_FROM_VM.md](MIGRATION_FROM_VM.md).
 
 ## Security Model

package/docs/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.6]
+
+### Fixed
+- **`update` command now regenerates docker-compose.yml** - Config changes in `.buwp-local.json` are now applied during `update`, not just during `start`
+- Ports, services, volume mappings, and other config changes now take effect when running `npx buwp-local update`
+- Previously, config changes were silently ignored during update, requiring `stop` + `start` to apply
+
+### Changed
+- `update` command now follows same pattern as `start` command for compose file generation
+- Improved user feedback showing compose file regeneration step
+
+## [0.7.5]
+
+### Added
+- Init template updated with `WP_ENVIRONMENT_TYPE=local` by default
+- Provides standardized environment detection for plugins/themes
+
 ## [0.7.4]
 
 ### Changed

package/docs/COMMANDS.md

@@ -141,6 +141,7 @@ npx buwp-local update --preserve-wpbuild
 
 **What it does:**
 - Checks if environment exists and Docker is running
+- **Regenerates docker-compose.yml from current `.buwp-local.json` config** (applies config changes)
 - Pulls latest Docker images from registry
 - **Removes wp_build volume** to get fresh WordPress core files (unless `--preserve-wpbuild`)
 - Recreates containers with new images

package/docs/GETTING_STARTED.md

@@ -93,6 +93,8 @@ sudo bash -c 'echo "127.0.0.1 username-myproject.local" >> /etc/hosts'
 
 Replace `username-myproject.local` with the hostname you chose in step 4.
 
+The `init` command will also display this command for you to run.
+
 ### 6. Start Your Environment
 
 Start the Docker containers:

package/docs/MIGRATION_FROM_VM.md

@@ -198,6 +198,9 @@ npx buwp-local start
 ```bash
 # Check Docker Desktop is running
 docker info
+
+# Check port conflicts
+npx buwp-local start --verbose
 ```
 
 ### Code changes not appearing
@@ -221,7 +224,7 @@ Check volume mappings in `.buwp-local.json`:
 # Verify Keychain entries
 npx buwp-local keychain list
 
-# Or use .env.local fallback --- this is a nice idea, but the actual command does not yet exist
+# Or use .env.local fallback
 npx buwp-local keychain export > .env.local
 ```
 

package/docs/ROADMAP.md

@@ -218,6 +218,25 @@ hostile.remove('127.0.0.1', config.hostname);
   
   **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).
 
+### Shipped in v0.7.5
+- **Init Template updated with WP_ENVIRONMENT_TYPE** ✅
+  - New projects set `WP_ENVIRONMENT_TYPE=local` by default
+  - Provides standardized environment detection for plugins/themes
+  - Can be overridden to simulate staging/production if needed
+
+### Shipped in v0.7.6
+- **Update Command Config Regeneration** ✅
+  - `update` command now regenerates docker-compose.yml from current `.buwp-local.json` config
+  - Config changes (ports, services, volume mappings, etc.) are now applied during `update`
+  - Fixes bug where config changes were silently ignored, requiring `stop` + `start` to apply
+  - Follows same pattern as `start` command for consistent behavior
+  
+  **Problem:** User edited `.buwp-local.json` config (changed ports from 8080/8443 to 80/443), ran `npx buwp-local update`, but ports stayed at old values. Some settings updated (hostname) while others didn't, causing confusion.
+  
+  **Root Cause:** Update command reused existing docker-compose.yml file instead of regenerating from current config like `start` command does.
+  
+  **Solution:** Added compose file regeneration step to `update` command before pulling images. Now matches `start` command pattern and ensures config changes take effect.
+
 ### Potential Features
 
 - **Ability to add custom WORDPRESS_CONFIG_EXTRA environment variables**
@@ -227,6 +246,11 @@ hostile.remove('127.0.0.1', config.hostname);
   - Commands to export credentials to JSON file
   - Useful for migrating between machines or sharing setup
 
+- **Command to generate a valid super-user**
+  - Consider adding a buwp-local command like `create-super-user` with a prompt that defaults to the current system username that can be used to create a valid WordPress super user tied to the current developer's BU account.
+  - This would be especially helpful for new users who are not familiar with WP CLI or need a quick way to get admin access without manually running WP CLI commands.
+  - One concern is that we don't want the primary command namespace to get too crowded with niche commands, perhaps we could have a "utils" command group for less commonly used commands like this, e.g. `buwp-local utils create-super-user`?
+
 - **Advanced Port Binding Configuration**
   - Optional config to override localhost-only binding for database/Redis
   - For advanced users who need network access to services
@@ -325,54 +349,6 @@ Will be informed by feedback from initial small group of users and actual pain p
 ### Quality
 - Standardized help for all CLI commands
 
-### Code Structure
-
-#### Refactor credential handling to avoid duplication
-Suggested refactor:
-```javascript
-// lib/docker-helpers.js (new file)
-export function prepareDockerComposeEnv(projectPath, projectName) {
-  const credentials = loadKeychainCredentials();
-  let tempEnvPath = null;
-  
-  if (Object.keys(credentials).length > 0) {
-    try {
-      tempEnvPath = createSecureTempEnvFile(credentials, projectName);
-    } catch (err) {
-      console.warn(chalk.yellow(`⚠️  Could not load keychain credentials: ${err.message}`));
-    }
-  }
-  
-  const envFilePath = path.join(projectPath, ENV_FILE_NAME);
-  const envFileFlag = fs.existsSync(envFilePath) ? `--env-file ${envFilePath}` : '';
-  const tempEnvFileFlag = tempEnvPath ? `--env-file ${tempEnvPath}` : '';
-  
-  return {
-    flags: `${tempEnvFileFlag} ${envFileFlag}`.trim(),
-    tempEnvPath,
-    cleanup: () => tempEnvPath && secureDeleteTempEnvFile(tempEnvPath)
-  };
-}
-```
-
-#### Centralize volume naming logic
-
-Suggested refactor:
-```javascript
-// lib/volume-naming.js (new file)
-export function getVolumeNames(projectName) {
-  return {
-    db: `${projectName}_db_data`,
-    wp: `${projectName}_wp_build`
-  };
-}
-
-// Or simpler - just add to config.js
-export function getWpVolumeName(projectName) {
-  return `${projectName}_wp_build`;
-}
-```
-
 ---
 
 ## Decision Framework

package/lib/commands/init.js

@@ -262,6 +262,7 @@ async function initCommand(options) {
     mappings: [],
     env: {
       WP_DEBUG: true,
+      WP_ENVIRONMENT_TYPE: 'local',
       XDEBUG: answers.xdebug || false
     }
   };

package/lib/commands/update.js

@@ -7,17 +7,17 @@ import { execSync } from 'child_process';
 import path from 'path';
 import fs from 'fs';
 import { loadConfig, loadKeychainCredentials, createSecureTempEnvFile, secureDeleteTempEnvFile, ENV_FILE_NAME } from '../config.js';
+import { generateComposeFile } from '../compose-generator.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);
+    const composePath = path.join(projectPath, '.buwp-local', 'docker-compose.yml');
 
-    // Check if docker-compose.yml exists
+    // Check if docker-compose.yml exists (indicates environment was previously started)
     if (!fs.existsSync(composePath)) {
       console.log(chalk.yellow('⚠️  No environment found.'));
       console.log(chalk.gray('Run "buwp-local start" to create an environment.\n'));
@@ -28,6 +28,14 @@ async function updateCommand(options = {}) {
     const config = loadConfig(projectPath);
     const projectName = config.projectName || 'buwp-local';
 
+    // Regenerate docker-compose.yml from current config
+    // This ensures any config changes are applied during update
+    console.log(chalk.gray('Regenerating docker-compose.yml from current config...'));
+    const newComposePath = generateComposeFile(config, projectPath);
+    console.log(chalk.green(`✓ Generated ${newComposePath}\n`));
+    
+    const composeDir = path.dirname(composePath);
+
     // Check if Docker is running
     try {
       execSync('docker info', { stdio: 'ignore' });

package/lib/config.js

@@ -228,6 +228,7 @@ function initConfig(projectPath = process.cwd(), options = {}) {
     mappings: [],
     env: {
       WP_DEBUG: true,
+      WP_ENVIRONMENT_TYPE: 'local',
       XDEBUG: false
     }
   };

package/lib/index.js

@@ -15,17 +15,3 @@ export const generateComposeFile = composeGenerator.generateComposeFile;
 export const CONFIG_FILE_NAME = config.CONFIG_FILE_NAME;
 export const ENV_FILE_NAME = config.ENV_FILE_NAME;
 export const DEFAULT_CONFIG = config.DEFAULT_CONFIG;
-
-// Keychain exports
-export const setCredential = keychain.setCredential;
-export const getCredential = keychain.getCredential;
-export const hasCredential = keychain.hasCredential;
-export const listCredentials = keychain.listCredentials;
-export const clearAllCredentials = keychain.clearAllCredentials;
-export const isPlatformSupported = keychain.isPlatformSupported;
-export const isMultilineCredential = keychain.isMultilineCredential;
-export const parseCredentialsFile = keychain.parseCredentialsFile;
-export const CREDENTIAL_KEYS = keychain.CREDENTIAL_KEYS;
-export const CREDENTIAL_GROUPS = keychain.CREDENTIAL_GROUPS;
-export const CREDENTIAL_DESCRIPTIONS = keychain.CREDENTIAL_DESCRIPTIONS;
-export const MULTILINE_CREDENTIALS = keychain.MULTILINE_CREDENTIALS;

package/package.json

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

package/readme.md

@@ -113,3 +113,4 @@ Your local WordPress site should now be accessible at the hostname you configure
 - ✅ Smart initialization for plugins, themes, and mu-plugins
 - ✅ Volume mapping for live code sync
 - ✅ Xdebug support for step debugging
+- ✅ WordPress environment detection (`WP_ENVIRONMENT_TYPE` set to `local`)

package/.buwp-local.example.json

@@ -1,27 +0,0 @@
-{
-  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
-  "hostname": "wordpress.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/plugins/my-plugin",
-      "comment": "Map current directory to a plugin location"
-    }
-  ],
-  "env": {
-    "WP_DEBUG": true,
-    "XDEBUG": false
-  }
-}

package/.env.local.example

@@ -1,26 +0,0 @@
-# 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/docs/archive/IMPLEMENTATION_NOTES_V0.5.0_PHASE3.md

@@ -1,240 +0,0 @@
-# v0.5.0 Phase 3: Hybrid Secure Temp File Integration
-
-## Overview
-Completed implementation of credential loading from macOS keychain into Docker Compose via secure temporary environment files. This is the final integration step of v0.5.0 keychain feature.
-
-## What Was Implemented
-
-### 1. **Credential Loading Functions** (`lib/config.js`)
-
-Added three new exported functions:
-
-#### `loadKeychainCredentials()`
-- Retrieves all 15 stored credentials from macOS keychain
-- Returns empty object on non-macOS platforms (graceful degradation)
-- Checks `isPlatformSupported()` before attempting keychain access
-- Iterates through `CREDENTIAL_KEYS` constant to load each credential
-
-#### `createSecureTempEnvFile(credentials, projectName)`
-- Creates `/tmp/.buwp-local-{projectName}-{timestamp}.env` file
-- Uses atomic file creation with exclusive write flag (`'wx'`)
-- Sets restrictive permissions to user read/write only (`0o600`)
-- Properly escapes multiline credentials:
-  - Backslashes: `\\` → `\\\\\\\\`
-  - Double quotes: `"` → `\"`
-  - Newlines: `\n` → `\\n`
-- Ensures shell interpretation works correctly for complex values (SHIB_SP_KEY, SHIB_SP_CERT)
-- Returns path to created temp file
-
-#### `secureDeleteTempEnvFile(filePath)`
-- Overwrites file content with zeros before deletion (defense against forensic recovery)
-- Unlinks file after secure overwrite
-- Returns boolean success status
-- Non-fatal errors - logs warnings but doesn't throw (temp files are ephemeral)
-
-### 2. **Start Command Integration** (`lib/commands/start.js`)
-
-Updated `startCommand()` function to:
-
-1. **Import new functions** from config.js
-2. **Load keychain credentials** after generating compose file:
-   ```javascript
-   const keychainCredentials = loadKeychainCredentials();
-   const keychainCredCount = Object.keys(keychainCredentials).length;
-   ```
-
-3. **Create secure temp file** if credentials available:
-   ```javascript
-   if (keychainCredCount > 0) {
-     tempEnvPath = createSecureTempEnvFile(keychainCredentials, projectName);
-   }
-   ```
-
-4. **Layer environment files** in Docker Compose command:
-   ```bash
-   docker compose -p {projectName} --env-file {tempEnvFile} --env-file {.env.local} -f {composePath} up -d
-   ```
-
-5. **Ensure cleanup** with try/finally block:
-   - Cleanup happens even if Docker Compose fails
-   - Temp file securely deleted after containers start
-
-### 3. **Credential Precedence**
-
-Docker Compose loads env files left-to-right with later files overriding earlier ones:
-
-```
-Keychain Credentials (--env-file /tmp/.buwp-local-*.env)
-    ↓ [overridden by]
-.env.local Project Overrides (--env-file .env.local)
-    ↓ [overridden by]
-docker-compose.yml Environment Defaults
-```
-
-**Precedence Order (highest to lowest):**
-1. `.env.local` - Project-specific credential overrides
-2. Keychain - Global default credentials (all 15 keys)
-3. docker-compose.yml - Hardcoded defaults
-
-## Security Architecture
-
-### Threat Model: Process List Visibility
-**Original concern:** Won't credentials be visible in `ps auxe`?
-
-**Answer:** No. With this approach:
-- Docker command shows: `docker compose --env-file /tmp/.buwp-local-test-project-1234567890.env ...`
-- Credentials are in the file, NOT in the process command line
-- Process list shows only the file path (which is harmless)
-
-### Threat Model: Filesystem Exposure
-**Risk:** Brief window where unencrypted credentials are on disk
-
-**Mitigations:**
-1. **Atomic creation** - File created exclusively with perms set atomically (no TOCTOU window)
-2. **Restrictive permissions** - `0o600` (user read/write only, no group/others access)
-3. **Ephemeral location** - `/tmp` directory (typically in-memory on modern systems, auto-cleaned)
-4. **Secure deletion** - Overwrite with zeros before unlinking (prevents forensic recovery)
-5. **Short lifetime** - File exists only during `docker compose up` command (~1-2 seconds)
-6. **Guaranteed cleanup** - try/finally ensures deletion even if Docker fails
-
-### Why Not Process Environment Variables?
-- **Worse security:** All env vars visible in `ps auxe` output to any user on system
-- **Less stable:** Large multiline values (40+ lines) cause issues
-- **Less standard:** Breaks Docker Compose file-based patterns
-
-### Why Not Store Credentials in .env.local?
-- **Already doing this** - `.env.local` is still supported and takes precedence
-- **One-time setup** - Keychain eliminates need to copy credentials to every project
-- **Secure storage** - Keychain uses macOS Secure Enclave on newer Macs
-
-## Integration Flow
-
-```
-1. Start command runs
-   ↓
-2. Load config from .buwp-local.json
-   ↓
-3. Load keychain credentials (15 total)
-   ↓
-4. Create temp env file (/tmp/.buwp-local-{project}-{timestamp}.env)
-   - Atomic creation with 0o600 permissions
-   - Properly escaped multiline values
-   ↓
-5. Build Docker Compose command with layered env files
-   - --env-file /tmp/.buwp-local-{project}-{timestamp}.env
-   - --env-file .env.local (if exists)
-   ↓
-6. Execute Docker Compose up
-   ↓
-7. Clean up temp file (try/finally)
-   - Overwrite with zeros
-   - Unlink
-   ↓
-8. Success message + usage tips
-```
-
-## Credentials Loaded
-
-All 15 credentials from keychain are available:
-
-**Database (2):**
-- WORDPRESS_DB_PASSWORD
-- DB_ROOT_PASSWORD
-
-**Shibboleth (5):**
-- SP_ENTITY_ID
-- IDP_ENTITY_ID
-- SHIB_IDP_LOGOUT
-- SHIB_SP_KEY (40+ lines)
-- SHIB_SP_CERT (24+ lines)
-
-**S3 (5):**
-- S3_UPLOADS_BUCKET
-- S3_UPLOADS_REGION
-- S3_UPLOADS_ACCESS_KEY_ID
-- S3_UPLOADS_SECRET_ACCESS_KEY
-- S3_ACCESS_RULES_TABLE
-
-**OLAP (3):**
-- OLAP
-- OLAP_ACCT_NBR
-- OLAP_REGION
-
-## Testing Results
-
-Automated integration test verification:
-
-✓ Load 15 credentials from keychain
-✓ Create secure temp env file with 0o600 permissions
-✓ Format env file with proper KEY="VALUE" quoting
-✓ Handle multiline value escaping correctly
-✓ Overwrite file with zeros before deletion
-✓ Securely delete temp file
-
-All tests passed successfully.
-
-## Version Update
-
-Updated package.json version:
-- Previous: v0.4.1
-- Current: v0.5.0
-
-## Code Quality
-
-All code passes ESLint checks with no errors or warnings.
-
-## Next Steps
-
-Possible future enhancements (not in v0.5.0 scope):
-
-1. **Phase 4: Init Command Enhancements**
-   - Auto-populate `buwp-local setup --file` from existing `.env` files
-   - Suggest keychain import during `init` command
-
-2. **Phase 5: Global Registry**
-   - `~/.buwp-local/registry.json` tracking which projects have credentials
-   - Dashboard showing all stored credentials across projects
-
-3. **Phase 6: Cross-Platform Support**
-   - Windows DPAPI support (via `credential` PowerShell module)
-   - Linux pass/secretservice support
-   - Fallback to encrypted `.buwp-local/.env.encrypted` files
-
-## Architecture Summary
-
-**Hybrid Secure Temp File Approach:**
-- **Security:** Process list hidden + filesystem defenses
-- **Stability:** Aligns with Docker Compose standard patterns
-- **Usability:** Intuitive file-based precedence and override mechanism
-- **Compatibility:** Maintains existing `.env.local` behavior
-
-**Key Decision Rationale:**
-Process list visibility is worse attack vector than brief filesystem window with defense-in-depth mitigations (atomic creation, 600 perms, /tmp location, overwrite-before-delete).
-
-## Files Modified
-
-1. `lib/config.js` (+80 lines)
-   - Added keychain import
-   - Added 3 new exported functions
-   - No breaking changes to existing exports
-
-2. `lib/commands/start.js` (+25 lines)
-   - Updated imports to include 3 new functions
-   - Added credential loading logic
-   - Added temp file creation and cleanup
-   - No breaking changes to command interface
-
-3. `package.json`
-   - Updated version to 0.5.0
-
-## Status Summary
-
-**v0.5.0 Completion Status:**
-- ✅ Phase 1: Keychain core module (v0.5.0)
-- ✅ Phase 2: JSON bulk import (v0.5.0)
-- ✅ Phase 3: Hybrid secure temp file integration (v0.5.0) ← COMPLETED THIS SESSION
-- ⏭️ Phase 4: Init command enhancements (v0.6.0)
-- ⏭️ Phase 5: Global registry (v0.7.0)
-- ⏭️ Phase 6: Cross-platform support (v1.0.0+)
-
-**v0.5.0 is now feature-complete and ready for testing.**

package/docs/archive/IMPLEMENTATION_SUMMARY.md

@@ -1,385 +0,0 @@
-# Implementation Summary - Multi-Project Support
-
-## What We Built
-
-Successfully implemented **three major features** requested from real-world usage feedback:
-
-### 1. ✅ Unique Docker Compose Project Names
-**Problem Solved:** Multiple repos using buwp-local would conflict in Docker Desktop and overwrite each other.
-
-**Solution Implemented:**
-- Auto-generate project name from directory name
-- Pass `-p {projectName}` flag to all docker-compose commands
-- Projects now show separately in Docker Desktop
-- Multiple instances can run simultaneously
-
-**Technical Changes:**
-- Added `projectName` field to config (defaults to directory basename)
-- Added `getProjectName()` and `sanitizeProjectName()` functions in `config.js`
-- Updated `start.js`, `stop.js`, `destroy.js`, `logs.js` to use `-p` flag
-
-### 2. ✅ Isolated Volumes Per Project
-**Problem Solved:** All projects shared the same database and WordPress volumes, causing conflicts.
-
-**Solution Implemented:**
-- Volume names prefixed with project name: `{projectName}_db_data`, `{projectName}_wp_build`
-- Each project gets completely isolated storage
-- No cross-contamination between projects
-
-**Technical Changes:**
-- Modified `generateComposeConfig()` to create project-specific volume names
-- Updated `generateDbService()` to accept `dbVolumeName` parameter
-- Updated `generateWordPressService()` to accept `wpVolumeName` parameter
-- Volume names dynamically generated based on `config.projectName`
-
-### 3. ✅ Smart Configuration Initialization
-**Problem Solved:** Users had to manually figure out and type correct container paths for plugins/themes/mu-plugins.
-
-**Solution Implemented:**
-- New CLI flags: `--plugin`, `--mu-plugin`, `--theme`
-- Auto-detects directory name
-- Auto-generates correct mapping path
-- Sets sensible defaults (project name, hostname)
-
-**Technical Changes:**
-- Modified `initConfig()` to accept `options` parameter with plugin/muPlugin/theme flags
-- Updated config command to pass initialization type to `initConfig()`
-- Added CLI options in `bin/buwp-local.js` for `--plugin`, `--mu-plugin`, `--theme`
-- Auto-generates hostname as `{projectName}.local`
-
----
-
-## Files Modified
-
-### Core Library Files
-1. **`lib/config.js`**
-   - Added `projectName` to DEFAULT_CONFIG
-   - Added project name auto-detection in `loadConfig()`
-   - Added `getProjectName()` function
-   - Added `sanitizeProjectName()` function
-   - Modified `initConfig()` to support smart initialization options
-   - Auto-generates project-specific mappings based on type
-
-2. **`lib/compose-generator.js`**
-   - Modified `generateComposeConfig()` to use project-specific volume names
-   - Updated `generateDbService()` with `dbVolumeName` parameter
-   - Updated `generateWordPressService()` with `wpVolumeName` parameter
-   - Dynamic volume naming: `{projectName}_db_data` and `{projectName}_wp_build`
-
-### Command Files
-3. **`lib/commands/start.js`**
-   - Added project name to docker-compose command: `-p ${projectName}`
-   - Display project name in success message
-
-4. **`lib/commands/stop.js`**
-   - Import `loadConfig` to get project name
-   - Added `-p ${projectName}` flag to docker-compose command
-
-5. **`lib/commands/destroy.js`**
-   - Import `loadConfig` to get project name
-   - Added `-p ${projectName}` flag to docker-compose command
-   - Show project name in confirmation prompt
-
-6. **`lib/commands/logs.js`**
-   - Import `loadConfig` to get project name
-   - Added `-p ${projectName}` flag to docker-compose command
-
-7. **`lib/commands/config.js`**
-   - Added logic to handle `--plugin`, `--mu-plugin`, `--theme` flags
-   - Pass initialization options to `initConfig()`
-   - Display appropriate messages for each initialization type
-   - Updated help text with new flags
-
-### CLI Entry Point
-8. **`bin/buwp-local.js`**
-   - Added `--plugin`, `--mu-plugin`, `--theme` options to config command
-   - Updated command descriptions
-
----
-
-## Testing Results
-
-### ✅ Smart Initialization Tested
-```bash
-# Plugin
-cd /tmp/test-plugin
-buwp-local config --init --plugin
-# ✓ Created: ./var/www/html/wp-content/plugins/test-plugin mapping
-
-# Theme
-cd /tmp/my-custom-theme
-buwp-local config --init --theme
-# ✓ Created: ./var/www/html/wp-content/themes/my-custom-theme mapping
-
-# MU-Plugin
-cd /tmp/bu-navigation
-buwp-local config --init --mu-plugin
-# ✓ Created: ./var/www/html/wp-content/mu-plugins/bu-navigation mapping
-```
-
-### ✅ Project Name Auto-Detection Tested
-- Directory name correctly extracted
-- Project name properly sanitized
-- Hostname auto-generated from project name
-- Config display shows project name
-
-### ✅ Volume Isolation Verified
-- Generated compose files show unique volume names
-- Volume names include project identifier
-- No conflicts between projects
-
----
-
-## Configuration Schema Changes
-
-### New Field: `projectName`
-
-```json
-{
-  "projectName": "my-plugin-name",  // NEW - auto-generated from directory
-  "image": "ghcr.io/bu-ist/bu-wp-docker-mod_shib:arm64-latest",
-  "hostname": "my-plugin-name.local",  // Auto-generated from projectName
-  "multisite": true,
-  // ... rest of config
-}
-```
-
-### Smart Mapping Examples
-
-**Plugin Init:**
-```json
-{
-  "projectName": "bu-custom-analytics",
-  "hostname": "bu-custom-analytics.local",
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/plugins/bu-custom-analytics"
-    }
-  ]
-}
-```
-
-**Theme Init:**
-```json
-{
-  "projectName": "responsive-framework",
-  "hostname": "responsive-framework.local",
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/themes/responsive-framework"
-    }
-  ]
-}
-```
-
-**MU-Plugin Init:**
-```json
-{
-  "projectName": "bu-navigation",
-  "hostname": "bu-navigation.local",
-  "mappings": [
-    {
-      "local": "./",
-      "container": "/var/www/html/wp-content/mu-plugins/bu-navigation"
-    }
-  ]
-}
-```
-
----
-
-## Usage Examples
-
-### Single Project (Original Workflow)
-```bash
-cd ~/projects/my-plugin
-buwp-local config --init --plugin
-# Edit .env.local with credentials
-buwp-local start
-# Access at http://my-plugin.local
-```
-
-### Multiple Projects (New Capability)
-```bash
-# Project A - Plugin
-cd ~/projects/bu-custom-analytics
-buwp-local config --init --plugin
-buwp-local start  # Runs on port 80
-
-# Project B - Another Plugin (different ports)
-cd ~/projects/bu-slideshow
-buwp-local config --init --plugin
-# Edit .buwp-local.json - change ports to 8081/8444/3308/6381
-buwp-local start  # Runs on port 8081
-
-# Project C - Theme
-cd ~/projects/responsive-framework
-buwp-local config --init --theme
-# Edit .buwp-local.json - change ports to 8082/8445/3309/6382
-buwp-local start  # Runs on port 8082
-
-# All three running simultaneously with separate databases!
-```
-
-### Docker Desktop View
-```
-Projects:
-├─ bu-custom-analytics
-├─ bu-slideshow
-└─ responsive-framework
-
-Volumes:
-├─ bu-custom-analytics_db_data
-├─ bu-custom-analytics_wp_build
-├─ bu-slideshow_db_data
-├─ bu-slideshow_wp_build
-├─ responsive-framework_db_data
-└─ responsive-framework_wp_build
-```
-
----
-
-## Benefits Delivered
-
-### For Individual Developers
-- ✅ Work on multiple projects simultaneously
-- ✅ Each project has isolated database
-- ✅ Fast setup with smart init flags
-- ✅ No manual path configuration needed
-- ✅ Clear project organization in Docker Desktop
-
-### For Teams
-- ✅ Standardized setup process
-- ✅ Less room for configuration errors
-- ✅ Easy onboarding with simple commands
-- ✅ Scalable to 20+ developers
-- ✅ Each developer can run multiple projects
-
-### For Project Management
-- ✅ Easy to see which projects are running
-- ✅ No accidental database overwrites
-- ✅ Clear volume organization
-- ✅ Predictable naming conventions
-
----
-
-## Backwards Compatibility
-
-### Migration Path
-Existing projects without `projectName` will:
-1. Auto-generate project name from directory
-2. Create new volumes with project-specific names
-3. Need to run `destroy` then `start` to migrate
-
-### Recommendation for Existing Users
-```bash
-# In each existing project:
-buwp-local destroy -f  # Removes old shared volumes
-buwp-local start       # Creates new isolated volumes
-```
-
----
-
-## Documentation Created
-
-### New Documents
-1. **`MULTI_PROJECT_GUIDE.md`** - Comprehensive guide for multi-project workflows
-   - Feature explanations
-   - Usage examples
-   - Troubleshooting
-   - Best practices
-   - Migration guide
-
-### Updated Documents
-- Configuration examples now include `projectName`
-- CLI help text shows new flags
-- Command descriptions updated
-
----
-
-## Next Steps & Future Enhancements
-
-### Immediate (Ready to Use)
-- ✅ All features tested and working
-- ✅ Documentation complete
-- ✅ Ready for team rollout
-
-### Phase 2 Suggestions (Based on Usage)
-1. **Project Listing Command**
-   ```bash
-   buwp-local list  # Show all active buwp-local projects
-   ```
-
-2. **Port Auto-Assignment**
-   - Automatically find available ports
-   - Suggest ports in `config --init`
-
-3. **Preset Configurations**
-   ```bash
-   buwp-local config --init --plugin --preset bu-standard
-   # Loads common settings for BU projects
-   ```
-
-4. **Project Templates**
-   ```bash
-   buwp-local config --init --template bu-plugin
-   # Includes common dependencies, settings, etc.
-   ```
-
-5. **Health Status Command**
-   ```bash
-   buwp-local status
-   # Shows status of current project
-   # - Running containers
-   # - Port mappings
-   # - Volume sizes
-   # - WordPress version
-   ```
-
----
-
-## Technical Achievements
-
-### Clean Implementation
-- ✅ Minimal changes to existing code
-- ✅ Backwards compatible (with migration)
-- ✅ Consistent naming conventions
-- ✅ Clear function parameters
-- ✅ Comprehensive error handling
-
-### Code Quality
-- ✅ JSDoc comments maintained
-- ✅ Functions remain single-responsibility
-- ✅ No breaking changes to public API
-- ✅ Easy to test and debug
-
-### User Experience
-- ✅ Intuitive flag names
-- ✅ Helpful feedback messages
-- ✅ Clear error messages
-- ✅ Sensible defaults
-- ✅ No required manual configuration
-
----
-
-## Summary
-
-**All three requested features successfully implemented:**
-1. ✅ Unique project names for Docker Desktop identification
-2. ✅ Isolated volumes per project for data separation
-3. ✅ Smart config init with auto-mapping
-
-**Testing confirms:**
-- Multiple projects run simultaneously ✅
-- Projects remain isolated ✅
-- Smart initialization works correctly ✅
-- All commands use project names properly ✅
-
-**Ready for:**
-- ✅ Team rollout
-- ✅ Real-world usage
-- ✅ Multi-project workflows
-
-The tool now fully supports the enterprise multi-project development workflow needed for a team of 20+ developers!

package/docs/archive/KEYCHAIN_IMPLEMENTATION.md

@@ -1,140 +0,0 @@
-# Keychain Integration - Implementation Summary
-
-## Overview
-
-Successfully implemented macOS Keychain integration for secure credential storage in buwp-local v0.5.0. This allows users to store credentials once and have them automatically available across all projects.
-
-## Files Created
-
-### 1. `lib/keychain.js` - Core Keychain Module
-**Functions:**
-- `setCredential(key, value)` - Store credential in keychain
-- `getCredential(key)` - Retrieve credential from keychain
-- `hasCredential(key)` - Check if credential exists
-- `deleteCredential(key)` - Remove credential
-- `listCredentials()` - Get all stored credential keys
-- `clearAllCredentials()` - Remove all buwp-local credentials
-- `isPlatformSupported()` - Check for macOS platform
-
-**Constants:**
-- `CREDENTIAL_KEYS` - All 15 credential keys
-- `CREDENTIAL_GROUPS` - Organized by category (database, shibboleth, s3, olap)
-- `CREDENTIAL_DESCRIPTIONS` - Human-readable descriptions for prompts
-
-**Implementation Details:**
-- Uses macOS `security` command via `execSync`
-- Service name: `buwp-local`
-- Uses `-U` flag to update existing credentials instead of duplicating
-- Graceful error handling with user-friendly messages
-
-### 2. `lib/commands/keychain.js` - CLI Command Handler
-**Subcommands:**
-- `setup` - Interactive setup for all credentials
-- `set <key> [value]` - Set individual credential
-- `get <key>` - Retrieve credential (masked display)
-- `list` - Show all stored credentials by group
-- `clear` - Remove all credentials (with confirmation)
-- `status` - Show platform support and credential status
-
-**Features:**
-- Interactive prompts using `prompts` package
-- Grouped credential display (database, shibboleth, s3, olap)
-- Existing credential detection with overwrite warnings
-- Force flag support for automation
-- macOS keychain access warning at start of setup
-
-## Files Modified
-
-### 3. `bin/buwp-local.js`
-- Added import for `keychainCommand`
-- Registered `keychain` command with subcommands
-- Added `-f, --force` option support
-
-### 4. `lib/index.js`
-- Exported all keychain functions
-- Exported credential schema constants
-
-## Usage Examples
-
-### First-Time Setup
-```bash
-# Interactive setup (all credentials)
-buwp-local keychain setup
-
-# Set individual credential
-buwp-local keychain set WORDPRESS_DB_PASSWORD mypassword
-
-# Check status
-buwp-local keychain status
-```
-
-### Managing Credentials
-```bash
-# List stored credentials
-buwp-local keychain list
-
-# Get credential value (masked)
-buwp-local keychain get WORDPRESS_DB_PASSWORD
-
-# Clear all credentials
-buwp-local keychain clear
-# Or skip confirmation:
-buwp-local keychain clear --force
-```
-
-## Testing Results
-
-✅ All functions tested and working:
-- Platform detection (macOS supported ✓)
-- Set credential via command line
-- Get credential with masking (test*****word)
-- List credentials by group
-- Clear all credentials
-- Linting passes cleanly
-
-## User Experience
-
-### Warnings & Messages
-- **Platform check**: Non-macOS users see clear message about .env.local fallback
-- **Keychain access**: Users warned about macOS permission prompt before setup
-- **Overwrite protection**: Warns when overwriting existing credentials
-- **Grouped display**: Credentials organized by functional category
-
-### Security Features
-- Credentials never displayed in full (masked in `get` command)
-- Stored securely in macOS keychain (encrypted by OS)
-- Individual credential deletion supported
-- Bulk clear with confirmation (unless --force)
-
-## Design Decisions
-
-1. **Full credential set required** - `setup` prompts for all 15 credentials to ensure complete stack functionality
-2. **Warning before overwrite** - Users must confirm when updating existing credentials (unless --force)
-3. **Sparse error messages** - Simple, clear error reporting without over-engineering
-4. **macOS-only for now** - Platform detection with graceful fallback to .env.local on other systems
-
-## Next Steps (v0.5.0 continued)
-
-**Remaining work:**
-1. Update `start.js` to load credentials from keychain
-2. Update `init.js` to detect keychain credentials
-3. Implement credential resolution priority: `.env.local` → keychain → defaults
-4. Create global registry (`~/.buwp-local/registry.json`)
-5. Update documentation
-
-**Future enhancements (v0.6.0+):**
-- Cross-platform support (Windows Credential Manager, Linux Secret Service)
-- Project-specific credential overrides
-- Credential import/export
-- Team credential sharing mechanisms
-
-## Benefits Delivered
-
-✅ **One-time setup** - Enter credentials once, use across all projects  
-✅ **Secure storage** - Leverages macOS keychain encryption  
-✅ **Simple CLI** - Intuitive subcommands for all operations  
-✅ **Backward compatible** - .env.local still works as override  
-✅ **Developer friendly** - Clear messages and helpful status command  
-✅ **Production ready** - Fully tested and linted
-
-This implementation solves the multi-repo credential fatigue problem while maintaining backward compatibility and providing a secure, native macOS integration.

package/docs/archive/macos-keychain-notes.md

@@ -1,11 +0,0 @@
-It's often convenient to store a password in the macOS system keychain and retrieve it inside a shell script.
-
-Here's the bash command for setting a password:
-
-security add-generic-password -s "Keychain item name here" -a "username here" -p
-Then enter your password when prompted.
-
-After you run this once, you can retrieve the password in a script like this:
-
-PASSWORD=`security find-generic-password -s "Keychain item name here" -a "username here" -w`
-You can then use $PASSWORD whenever you need the password in your script.