@bostonuniversity/buwp-local 0.5.2 → 0.6.0

package/docs/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+### Added
+- Credential validation on `start` command with interactive setup prompt
+- Documentation consolidation in `docs/` directory
+- Comprehensive guides: GETTING_STARTED.md, COMMANDS.md, CREDENTIALS.md, MULTI_PROJECT.md, ARCHITECTURE.md
+
+## [0.5.3]
+
+### Fixed
+- Fixed newline escaping in `createSecureTempEnvFile()` to properly handle multiline credentials
+- Changed regex from `/\\n/g` to `/\n/g` to escape actual newline characters instead of literal backslash-n strings
+
+### Changed
+- Improved temp env file generation to correctly format multiline values for Docker Compose
+
+## [0.5.2]
+
+### Added
+- Automatic hex decoding for legacy multiline credentials in Keychain
+- `isHexEncoded()` helper function to detect hex-encoded credential values
+- Transparent decoding of Shibboleth certificates and keys stored as hex strings
+
+### Fixed
+- SHIB_SP_KEY and SHIB_SP_CERT now properly decode from hex format when retrieved from Keychain
+- Credentials that were stored as "2d2d2d2d2d..." now correctly appear as "-----BEGIN..."
+
+## [0.5.1]
+
+### Added
+- Source file deletion prompt after successful Keychain import
+- `promptToDeleteSourceFile()` function for secure cleanup of plaintext credential files
+- Security improvement to reduce attack surface by removing credential files after import
+
+### Changed
+- `keychain setup` command now prompts to delete source JSON file after successful import
+- Enhanced security workflow for credential management
+
+## [0.5.0]
+
+### Added
+- **macOS Keychain integration** for secure credential storage
+- `keychain` command group with subcommands:
+  - `setup --file <path>` - Import credentials from JSON file
+  - `get <name>` - Retrieve specific credential
+  - `set <name> <value>` - Update or create credential
+  - `delete <name>` - Remove credential
+  - `list` - Show all stored credentials
+  - `test` - Verify Keychain access
+- Hybrid credential loading: `.env.local` overrides Keychain
+- Secure temporary environment file generation with 0600 permissions
+- Automatic cleanup of temporary credential files
+
+### Changed
+- Credential loading now checks `.env.local` first, then falls back to Keychain
+- Enhanced security model with encrypted credential storage
+- Improved documentation for credential management workflows
+
+### Security
+- Credentials no longer require plaintext `.env.local` files in every project
+- Global credential storage in macOS Keychain with encryption
+- Temporary files used for Docker Compose with strict permissions
+
+## [0.4.0]
+
+### Added
+- Interactive `init` command with guided setup wizard
+- Smart project type detection (plugin, theme, mu-plugin, sandbox)
+- Real-time input validation during interactive setup
+- Automatic volume mapping generation based on project type
+- Non-interactive mode with `--plugin`, `--mu-plugin`, `--theme` flags
+
+### Changed
+- Replaced `config --init` with dedicated `init` command
+- Enhanced user experience with prompts library
+- Improved default value suggestions
+
+## [0.3.0]
+
+### Added
+- Multi-project support with unique project names
+- Isolated Docker volumes per project (`{projectName}_db_data`, `{projectName}_wp_build`)
+- Automatic project name generation from directory name
+- Support for running multiple projects simultaneously
+- Shared environment strategy (same projectName across repos)
+
+### Changed
+- Docker Compose now uses `--project-name` flag for isolation
+- Volume names include project identifier
+- Container names prefixed with project name
+
+### Fixed
+- Port conflicts between multiple running projects
+- Database conflicts when running multiple instances
+
+## [0.2.0]
+
+### Added
+- `wp` command for WP-CLI proxy
+- Support for all WP-CLI commands via pass-through
+- `logs` command with service filtering
+- `--follow` flag for real-time log streaming
+- Configuration validation with `config --validate`
+- Configuration display with `config --show` (credentials masked)
+
+### Changed
+- Improved error messages for Docker failures
+- Enhanced logging output with timestamps
+- Better handling of missing Docker dependencies
+
+## [0.1.0]
+
+### Added
+- Initial release of buwp-local CLI tool
+- Basic Docker Compose generation and management
+- `start`, `stop`, `destroy` commands
+- Configuration file support (`.buwp-local.json`)
+- Environment variable support (`.env.local`)
+- Service toggles for Redis, S3 proxy, Shibboleth
+- Port configuration (HTTP, HTTPS, database, Redis)
+- Volume mappings for local code
+- Support for BU WordPress Docker image
+- MySQL 8.0 database service
+- Redis cache service (optional)
+- S3 proxy service (optional)
+- Shibboleth SSO integration (optional)
+
+### Documentation
+- Basic README with quickstart guide
+- Usage documentation with examples
+- Configuration reference
+- Environment variable documentation
+
+---
+
+## Version History
+
+- **0.5.x** - Keychain integration and credential management enhancements
+- **0.4.x** - Interactive initialization and improved UX
+- **0.3.x** - Multi-project support and isolation
+- **0.2.x** - WP-CLI integration and enhanced commands
+- **0.1.x** - Initial release with core functionality

package/docs/COMMANDS.md

@@ -0,0 +1,462 @@
+# Command Reference
+
+Complete reference for all `buwp-local` CLI commands.
+
+## Core Commands
+
+### `init`
+
+Initialize a new project configuration with an interactive assistant.
+
+```bash
+npx buwp-local init [options]
+```
+
+**Options:**
+- `--no-interactive` - Use non-interactive mode with defaults
+- `--plugin` - Non-interactive: initialize as plugin project
+- `--mu-plugin` - Non-interactive: initialize as mu-plugin project
+- `--theme` - Non-interactive: initialize as theme project
+- `-f, --force` - Overwrite existing configuration file
+
+**Examples:**
+```bash
+# Interactive mode (recommended)
+npx buwp-local init
+
+# Non-interactive modes
+npx buwp-local init --plugin
+npx buwp-local init --mu-plugin --force
+npx buwp-local init --theme --no-interactive
+```
+
+**What it does:**
+- Creates `.buwp-local.json` configuration file
+- Auto-detects project type from directory structure
+- Generates hostname from directory name
+- Creates appropriate volume mappings for plugin/theme/mu-plugin types
+- Configures services (Redis, S3, Shibboleth)
+- Sets up port mappings
+
+---
+
+### `start`
+
+Start the Docker Compose environment for your project.
+
+```bash
+npx buwp-local start [options]
+```
+
+**Options:**
+- `--xdebug` - Enable Xdebug for debugging
+
+**Examples:**
+```bash
+# Standard start
+npx buwp-local start
+
+# Start with Xdebug enabled
+npx buwp-local start --xdebug
+```
+
+**What it does:**
+- Validates credentials (Keychain or `.env.local`)
+- Prompts for credential setup if missing
+- Generates Docker Compose configuration
+- Creates secure temporary environment file
+- Starts Docker containers
+- Shows service URLs and status
+
+---
+
+### `stop`
+
+Stop all running containers for the current project.
+
+```bash
+npx buwp-local stop
+```
+
+**What it does:**
+- Stops all Docker containers
+- Preserves volumes (database and WordPress files remain intact)
+- Cleans up temporary environment files
+
+---
+
+### `destroy`
+
+Destroy the entire environment including volumes.
+
+```bash
+npx buwp-local destroy [options]
+```
+
+**Options:**
+- `-f, --force` - Skip confirmation prompt
+
+**Examples:**
+```bash
+# With confirmation prompt
+npx buwp-local destroy
+
+# Force destroy without confirmation
+npx buwp-local destroy --force
+```
+
+**What it does:**
+- Stops all containers
+- Removes all containers
+- **Deletes all volumes** (database and WordPress files are lost!)
+- Cleans up temporary files
+
+**⚠️ Warning:** This permanently deletes your local database and WordPress installation. Cannot be undone.
+
+---
+
+### `logs`
+
+View logs from Docker containers.
+
+```bash
+npx buwp-local logs
+```
+
+**Options:**
+- `-f, --follow` - Follow log output
+
+**Examples:**
+```bash
+# View all logs
+npx buwp-local logs
+
+# Follow logs in real-time
+npx buwp-local logs --follow
+```
+
+---
+
+### `config`
+
+Manage project configuration.
+
+```bash
+npx buwp-local config [options]
+```
+
+**Options:**
+- `--init` - Initialize new configuration file (legacy, use `init` instead)
+- `--validate` - Validate existing configuration file
+- `--show` - Display resolved configuration with masked secrets
+
+**Examples:**
+```bash
+# Validate configuration
+npx buwp-local config --validate
+
+# Show current configuration (credentials masked)
+npx buwp-local config --show
+```
+
+**What it does:**
+- `--validate`: Checks `.buwp-local.json` for errors
+- `--show`: Displays merged configuration (file + environment variables) with secrets masked
+
+---
+
+### `wp`
+
+Run WP-CLI commands inside the WordPress container.
+
+```bash
+npx buwp-local wp <wp-cli-command> [args...]
+```
+
+**Examples:**
+```bash
+# User management
+npx buwp-local wp user list
+npx buwp-local wp user create username user@bu.edu --role=administrator
+npx buwp-local wp super-admin add username@bu.edu
+
+# Plugin management
+npx buwp-local wp plugin list
+npx buwp-local wp plugin activate akismet
+npx buwp-local wp plugin deactivate hello
+
+# Post management
+npx buwp-local wp post list
+npx buwp-local wp post create --post_title="Test Post" --post_status=publish
+
+# Database operations
+npx buwp-local wp db export backup.sql
+npx buwp-local wp db query "SELECT * FROM wp_users LIMIT 5"
+
+# Cache operations
+npx buwp-local wp cache flush
+npx buwp-local wp transient delete --all
+
+# Site management
+npx buwp-local wp site-manager snapshot-pull \
+  --source=https://www.bu.edu/admissions/ \
+  --destination=http://myproject.local/admissions
+```
+
+**What it does:**
+- Executes WP-CLI commands inside the running WordPress container
+- Passes through all arguments and options
+- Requires containers to be running (`start` first)
+
+**Full WP-CLI documentation:** https://developer.wordpress.org/cli/commands/
+
+---
+
+## Credential Management
+
+### `keychain setup`
+
+Import credentials into macOS Keychain from a JSON file.
+
+```bash
+npx buwp-local keychain setup --file <path-to-json>
+```
+
+Can also be used interactively by omitting the `--file` option, but shibboleth-related credentials that are multiline have to be provided via external files.
+
+**Options:**
+- `--file <path>` - Path to credentials JSON file (required)
+
+**Example:**
+```bash
+npx buwp-local keychain setup --file ~/Downloads/buwp-local-credentials.json
+```
+
+**What it does:**
+- Reads credentials from JSON file
+- Stores each credential securely in macOS Keychain
+- Validates credential format
+- Prompts to delete source file after import (security best practice)
+- Credentials become available to all buwp-local projects
+
+**JSON file format:**
+```json
+{
+  "WORDPRESS_DB_PASSWORD": "password",
+  "DB_ROOT_PASSWORD": "rootpassword",
+  "SP_ENTITY_ID": "https://your-sp-entity-id",
+  "SHIB_SP_KEY": "-----BEGIN PRIVATE KEY-----\n...",
+  "SHIB_SP_CERT": "-----BEGIN CERTIFICATE-----\n...",
+  "S3_UPLOADS_BUCKET": "your-bucket",
+  "S3_UPLOADS_ACCESS_KEY_ID": "your-access-key",
+  "S3_UPLOADS_SECRET_ACCESS_KEY": "your-secret-key"
+}
+```
+
+---
+
+### `keychain get`
+
+Retrieve a specific credential from macOS Keychain.
+
+```bash
+npx buwp-local keychain get <credential-name>
+```
+
+**Example:**
+```bash
+npx buwp-local keychain get WORDPRESS_DB_PASSWORD
+npx buwp-local keychain get S3_UPLOADS_BUCKET
+```
+
+**What it does:**
+- Fetches the specified credential from Keychain
+- Displays the value (use with caution in shared terminals)
+- Returns error if credential not found
+
+---
+
+### `keychain set`
+
+Set a single credential in macOS Keychain.
+
+```bash
+npx buwp-local keychain set <credential-name> <value>
+```
+
+**Example:**
+```bash
+npx buwp-local keychain set WORDPRESS_DB_PASSWORD "new-password"
+npx buwp-local keychain set S3_UPLOADS_BUCKET "my-bucket"
+```
+
+**What it does:**
+- Stores or updates a credential in Keychain
+- Creates new entry if it doesn't exist
+- Updates existing entry if it does
+
+---
+
+### `keychain delete`
+
+Delete a credential from macOS Keychain.
+
+```bash
+npx buwp-local keychain delete <credential-name>
+```
+
+**Example:**
+```bash
+npx buwp-local keychain delete WORDPRESS_DB_PASSWORD
+```
+
+**What it does:**
+- Removes the specified credential from Keychain
+- Prompts for confirmation before deletion
+
+---
+
+### `keychain list`
+
+List all stored credentials in macOS Keychain.
+
+```bash
+npx buwp-local keychain list
+```
+
+**What it does:**
+- Displays all credential names (not values) stored in Keychain
+- Shows which of the 15 credential types are configured
+- Useful for auditing what's stored
+
+---
+
+### `keychain status`
+
+Test Keychain access and credential loading.
+
+```bash
+npx buwp-local keychain status
+```
+
+**What it does:**
+- Verifies Keychain is accessible
+- Tests reading sample credentials
+- Reports any permission or access issues
+- Useful for troubleshooting Keychain integration
+
+---
+
+### `keychain clear`
+
+Clear all stored credentials from macOS Keychain.
+
+```bash
+npx buwp-local keychain clear [--force]
+```
+
+**What it does:**
+- Deletes all 15 buwp-local credentials from Keychain
+- Prompts for confirmation unless `--force` is used
+
+---
+
+## Global Options
+
+These options work with all commands:
+
+- `-h, --help` - Display help for command
+- `-v, --version` - Display version number
+
+**Examples:**
+```bash
+npx buwp-local --version
+npx buwp-local start --help
+npx buwp-local keychain --help
+```
+
+---
+
+## Environment Variables
+
+Commands respect these environment variables:
+
+- `BUWP_CONFIG_FILE` - Path to config file (default: `.buwp-local.json`)
+- `BUWP_ENV_FILE` - Path to environment file (default: `.env.local`)
+- `NODE_ENV` - Node environment (`development`, `production`)
+
+**Example:**
+```bash
+BUWP_CONFIG_FILE=.buwp-local.staging.json npx buwp-local start
+```
+
+---
+
+## Exit Codes
+
+Commands return standard exit codes:
+
+- `0` - Success
+- `1` - General error
+- `2` - Configuration error
+- `3` - Docker error
+- `4` - Credential error
+
+Use in scripts:
+```bash
+npx buwp-local start
+if [ $? -eq 0 ]; then
+  echo "Started successfully"
+else
+  echo "Failed to start"
+fi
+```
+
+---
+
+## Tips & Best Practices
+
+### Running Multiple Projects
+
+Each project is isolated by its `projectName`. You can run multiple projects simultaneously:
+
+```bash
+cd ~/project-a && npx buwp-local start
+cd ~/project-b && npx buwp-local start
+# Both running at the same time!
+```
+
+See [Multi-Project Setup](MULTI_PROJECT.md) for details (upcoming).
+
+### Debugging
+
+Enable Xdebug and configure your IDE:
+
+```bash
+npx buwp-local start --xdebug
+```
+
+Xdebug connects on port 9003 by default.
+
+### WP-CLI Shortcuts
+
+Create shell aliases for common commands:
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+alias buwp='npx buwp-local'
+alias buwp-wp='npx buwp-local wp'
+
+# Then use:
+buwp start
+buwp-wp plugin list
+```
+
+---
+
+## See Also
+
+- [Getting Started](GETTING_STARTED.md) - Initial setup guide
+- [Credentials Management](CREDENTIALS.md) - Detailed credential guide
+- [Multi-Project Setup](MULTI_PROJECT.md) - Running multiple projects
+- [Architecture](ARCHITECTURE.md) - How buwp-local works