@bostonuniversity/buwp-local 0.5.0 → 0.5.1

package/lib/commands/init.js

@@ -294,16 +294,16 @@ async function initCommand(options) {
   
   // Show next steps
   console.log(chalk.cyan('📝 Next steps:'));
-  console.log(chalk.gray('  1. Create .env.local with your credentials'));
+  console.log(chalk.gray('  1. Check keychain credentials or add .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('  4. Run: npx 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('  3. Run: npx buwp-local start'));
   }
   
   console.log(chalk.gray(`\n  Then access: https://${answers.hostname}\n`));

package/lib/commands/start.js

@@ -102,7 +102,6 @@ async function startCommand(options) {
     console.log(chalk.green('\n✅ Environment started successfully!\n'));
     console.log(chalk.cyan(`Project: ${projectName}`));
     console.log(chalk.cyan('Access your site at:'));
-    console.log(chalk.white(`  http://${config.hostname}`));
     console.log(chalk.white(`  https://${config.hostname}\n`));
     
     console.log(chalk.gray('Useful commands:'));

package/lib/config.js

@@ -286,7 +286,7 @@ function sanitizeProjectName(name) {
 
 /**
  * Load credentials from macOS keychain
- * Returns all 15 credentials if available, with platform and keychain support checks
+ * Returns all available credentials if present, with platform and keychain support checks
  * @returns {object} Credentials object or empty object if not supported
  */
 export function loadKeychainCredentials() {
@@ -322,10 +322,11 @@ export function createSecureTempEnvFile(credentials, projectName) {
   // Build env file content with proper escaping for multiline values
   const lines = Object.entries(credentials).map(([key, value]) => {
     // Escape special characters in values
+    // Order matters: backslashes first, then quotes, then newlines
     const escaped = String(value)
-      .replace(/\\\\/g, '\\\\\\\\')  // Escape backslashes first
-      .replace(/"/g, '\\"')      // Escape double quotes
-      .replace(/\\n/g, '\\\\n');   // Escape newlines for shell
+      .replace(/\\/g, '\\\\')      // Escape backslashes first (\ -> \\)
+      .replace(/"/g, '\\"')        // Escape double quotes (" -> \")
+      .replace(/\n/g, '\\n');      // Escape actual newlines (\n -> \n literal in file)
     
     return `${key}="${escaped}"`;
   });

package/lib/keychain.js

@@ -237,8 +237,6 @@ export function deleteCredential(key) {
     if (!err.message.includes('could not be found')) {
       throw new Error(`Failed to delete credential from keychain: ${err.message}`);
     }
-
-    console.log("foobar");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bostonuniversity/buwp-local",
-  "version": "0.5.0",
+  "version": "0.5.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 start",
+    "buwp-local": "node bin/buwp-local.js",
     "lint": "eslint ."
   },
   "keywords": [

package/readme.md

@@ -1,3 +1,82 @@
 # BU WordPress Local Development
 
 This repository contains resources and instructions for setting up a local WordPress development environment for Boston University projects. It uses the BU WordPress container image and provides the additional resoures needed to run it locally with Docker.
+
+
+## Quickstart for plugin or theme development
+
+1. **Install Docker**: Make sure you have [Docker Desktop](https://www.docker.com/products/docker-desktop) installed and running on your machine.
+
+2. Login to GitHub Packages to access the BU WordPress Docker image (you will need a GitHub access token with `read:packages` scope):
+
+   ```bash
+   echo YOUR_GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
+   ```
+
+3. **Install buwp-local CLI**: Install the `buwp-local` CLI tool in your project directory:
+
+   ```bash
+   npm install @bostonuniversity/buwp-local --save-dev
+   ```
+
+4. **One time credential keychain setup**: Install credentials in the macOS Keychain for secure storage (optional, macOS only right now):
+
+    First, download a credentials JSON file through ssh from the dev server:
+
+    ```bash
+    scp user@devserver:/path/to/buwp-local-credentials.json ~/Downloads/
+    ```
+
+    Then run the setup command:
+
+    ```bash
+    npx buwp-local keychain setup --file ~/Downloads/buwp-local-credentials.json
+    ```
+
+    This will store all necessary credentials in your Keychain for future use, for this project and any other buwp-local projects (Keychain is global). (The global Keychain can also be overridden by `.env.local` files in each project.)
+
+5. **Initialize your project**: Run the interactive setup to create your `.buwp-local.json` configuration file:
+
+    ```bash
+    npx buwp-local init
+    ```
+
+    This will guide you through setting up your project name, hostname, port mappings, volume mappings, and service options.
+
+6. **Setup local hostname**: Add your project's local hostname (e.g. `myproject.local`) to your `/etc/hosts` file
+
+7. **Start your local environment**:
+
+    ```bash
+    npx buwp-local start
+    ```
+
+    This will read your configuration, load credentials from Keychain (or `.env.local` if present), and start the Docker containers for your WordPress project.
+
+Your local WordPress site should now be accessible at the hostname you configured (e.g. `http://myproject.local`).
+
+## Basic Local setup
+
+
+1. **Setup local user**: Create a local WordPress user and add it to the super admin role:
+
+    If running with Shibboleth enabled, you can set up a local WordPress user with super admin privileges:
+
+    Create the user:
+    ```bash
+    npx buwp-local wp user create username username@bu.edu --role=administrator
+    ```
+
+    Promote to super admin:
+    ```bash
+    npx buwp-local wp super-admin add username@bu.edu
+    ```
+2. Pull snapshot site content:
+
+    You can pull a snapshot of the production or staging site database and media files into your local environment for testing and development.
+
+    ```bash
+    npx buwp-local wp site-manager snapshot-pull --source=https://www.bu.edu/admissions/ --destination=http://myproject.local/admissions
+    ```
+
+    This will download the latest snapshot from the specified source and import it into your local WordPress environment.

package/.buwp-local.json

@@ -1,22 +0,0 @@
-{
-  "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/plan-environmentBasedCredentials.prompt.md

@@ -1,57 +0,0 @@
-## 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.