README

One ring to rule them all - Manage your Pantheon hosting environment directly from WordPress.

Ash Nazg integrates the Pantheon Public API into your WordPress admin dashboard. Toggle between SFTP and Git mode, view debug logs, manage addons, trigger workflows, and monitor your Pantheon environment—all without leaving WordPress.

Why "Ash Nazg"?

The name comes from the One Ring inscription in Tolkien's works. Just as the One Ring unified power, this plugin unifies your workflow by bringing Pantheon platform management into the one place you're already working: WordPress admin.

Features

Dashboard & Monitoring

View your Pantheon environment status, site information, and connection mode at a glance. Monitor 26+ API endpoints with live status indicators showing which Pantheon features are available. Toggle between SFTP and Git mode with automatic verification.

Features:

• Auto-detect environment (dev/test/live/multidev/local)
• Real-time API endpoint testing with status indicators (green checkmarks, red X's)
• Site and environment information from Pantheon API
• SFTP/Git mode toggle with automatic polling verification
• Inline site label editing with pencil icon
• Smart caching with "last checked" timestamps and one-click refresh

Development

Manage code deployment, upstream updates, multidev environments, and uncommitted changes from a single interface. All development operations accessible from one page regardless of your current environment.

Code Deployment:

• Deploy code from dev to test or test to live
• Side-by-side panels with environment sync detection
• Optional "sync content from live" for test→live deployments
• Change detection disables buttons when environments are in sync
• Deployment notes with workflow monitoring

Upstream Updates:

• Detect available upstream updates per environment
• Per-environment filtering (only shows updates not yet applied)
• One-click apply with workflow monitoring
• Automatic cache invalidation after updates

Multidev Management:

• Create new multidev environments from dev
• Merge multidev into dev or merge dev into multidev
• Delete multidev environments with confirmation
• Environment status and branch information display

Uncommitted Changes:

• View git diffstat in SFTP mode
• Commit SFTP changes with commit message
• File count and change type display
• Recent commits history

Backups

Create, restore, and download backups for any environment. Manage backups across all environments from a single interface.

Features:

• Environment dropdown selector for backup creation
• Create backups: all, code only, database only, or files only
• Configurable retention period (1-365 days)
• List backups from all environments with visual separation
• Restore backups with destructive operation warnings
• Download backups via signed URLs (code/database/files)
• Collapsible backup sets to reduce vertical space
• Workflow monitoring for long-running operations

Clone Content

Copy database and/or files between environments with automatic URL search-replace for WordPress.

Features:

• Source and target environment dropdown selectors
• Clone database, files, or both
• Automatic WordPress URL search-replace (from_url → to_url)
• Environment initialization validation
• Destructive operation warnings with confirmation modals
• Multi-workflow monitoring (polls both DB and files simultaneously)
• Automatic cache clearing after successful clones

Debug Logs

View and clear WordPress debug logs without SSH access. Automatically switches to SFTP mode if needed to access log files on Pantheon's read-only Git filesystem.

Features:

• Fetch and display debug.log contents
• One-click log clearing with automatic mode switching
• Skips SFTP switching on local environments
• File stat cache clearing for accurate deletion verification

Addons

Enable or disable Pantheon site addons (Redis object caching, Apache Solr search) directly from WordPress admin.

Features:

• Toggle Redis object cache addon
• Toggle Apache Solr search addon
• Persistent state tracking in WordPress options
• Automatic cache clearing after changes

Workflows

Trigger Pantheon workflows from WordPress, including Object Cache Pro installation via scaffold_extensions workflow.

Features:

• Trigger Object Cache Pro installation (scaffold_extensions workflow)
• Environment validation (dev/multidev only)
• Workflow status retrieval and monitoring
• Additional workflow types as discovered

Domains (Multisite Only)

For WordPress multisite installations, automatically add custom domains to Pantheon when new subsites are created.

Features:

• Automatic domain addition on subsite creation
• Hooks into wp_initialize_site (WP 5.1+) and wpmu_new_blog (legacy)
• Skips local environments automatically
• Adds domains to live environment by default
• Admin notices for success/failure via transients
• Synchronous operation (no workflow polling)

Settings

Configure machine token authentication, view/clear session tokens, and manage plugin settings. Tokens stored securely in Pantheon Secrets (production) or WordPress options (local development fallback).

Features:

• Per-user machine token configuration (v0.4.0+)
• Pantheon Secrets integration with user ID suffix
• Encrypted token storage (AES-256-CBC) for database fallback
• Migration from global to per-user tokens
• Session token viewing and manual clearing
• Auto-clears invalid tokens on 401/403 errors
• Development fallback for local environments

Delete Site (Debug Mode Only)

Demonstration feature showing full Pantheon API capabilities. Only visible when ?debug=1 query parameter is present.

Features:

• Big red DELETE SITE button
• Menu item: "⚠️ DO NOT CLICK" (red background)
• Type "DELETE" to enable button
• Two-stage confirmation (modal + JavaScript alert)
• "Whew! That was a close one!" message on cancellation
• Fully functional - actually deletes site via Pantheon API
• Redirects to Pantheon dashboard after deletion

Excluded for Security

This plugin does not provide access to:

• Organization or user management (beyond what's displayed)
• Billing information or plan changes
• Token generation/revocation (only usage)
• Unrestricted site deletion (only via debug mode)

Requirements

• Must be hosted on Pantheon (plugin uses Pantheon-specific environment variables and Secrets API)
• WordPress 5.0 or higher
• PHP 7.4 or higher
• Pantheon machine token (per-user, v0.4.0+) stored in Pantheon Secrets (how to create)
• User with manage_options capability in WordPress

Installation

Via Composer (Recommended)

composer require jazzsequence/ash-nazg

Activate the plugin through the WordPress admin or via WP-CLI:

wp plugin activate ash-nazg

From GitHub Release

1. Download the latest release ZIP file from GitHub Releases
2. Upload the ZIP file through WordPress Admin > Plugins > Add New > Upload Plugin
3. Activate the plugin
4. Navigate to Ash Nazg in the WordPress admin menu

Configuration

Setting Up Your Pantheon Machine Token

Version 0.4.0+ introduces per-user machine tokens. Each WordPress admin can have their own Pantheon machine token for better security and audit trails.

1. Create a machine token:

   • Log into your Pantheon Dashboard
   • Go to Account > Machine Tokens
   • Create a new machine token
   • Copy the token (you'll only see it once!)

2. Find your WordPress user ID:

   • Navigate to Ash Nazg > Settings in the WordPress admin
   • Your user ID is displayed prominently in the settings page
   • You'll need this ID for the next step

3. Store the token (Recommended: Pantheon Secrets):

   We highly recommend using Pantheon Secrets to securely store your machine token. Each user has their own secret with their user ID as a suffix:

   terminus secret:set <site> ash_nazg_machine_token_1 YOUR_TOKEN --scope=user,web

   Replace 1 with your WordPress user ID (e.g., ash_nazg_machine_token_1, ash_nazg_machine_token_42, etc.).

   The plugin will retrieve your token using pantheon_get_secret('ash_nazg_machine_token_{user_id}').

   Alternative: WordPress Database

   You can also configure the token in Ash Nazg > Settings in the WordPress admin. The token will be encrypted with AES-256-CBC using WordPress salts before being stored in the database. This is less secure than Pantheon Secrets but provides a local development fallback.

4. Verify setup:

   • Navigate to Ash Nazg in your WordPress admin menu
   • The plugin will auto-detect your Pantheon environment variables
   • If your token is configured correctly, you'll see environment information on the dashboard

Migrating from v0.3.x to v0.4.0

If you're upgrading from a previous version with a site-wide global token, the plugin will show a migration notice with instructions:

• Global database token: Click "Migrate to My Account" to copy and encrypt the token to your user account
• Global Pantheon Secret: Follow the terminus command instructions to set your per-user secret

The global token will be deleted after migration. Other admins will need to set up their own tokens.

Development

This plugin is under active development. See CLAUDE.md for technical architecture and development guidelines.

Architecture

• Functional programming with Pantheon\AshNazg namespace
• Traditional WordPress admin interface using Pantheon Design System (PDS Core)
• API-first approach using api.pantheon.io
• Secure credential storage via Pantheon Secrets (recommended) or WordPress database

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Follow Pantheon WordPress Coding Standards
4. Write PHPUnit tests for new functionality
5. Test in a Pantheon environment
6. Submit a pull request

Development Setup

# Clone the repository
git clone https://github.com/jazzsequence/ash-nazg.git
cd ash-nazg

# Install dependencies
composer install
npm install  # or yarn install

# Run all checks (lint + tests) - recommended before committing
composer check

# Run all linting (PHP syntax + coding standards)
composer lint

# Run PHP syntax check only
composer lint:php

# Run coding standards checks only
composer lint:phpcs
# or
composer phpcs

# Auto-fix coding standards issues
composer phpcbf

# Run tests only
composer test

# Install test environment (for WordPress integration tests)
composer test:install

# Run Playwright E2E tests (future)
npm test

Development Dependencies

• Composer:

  • pantheon-systems/pantheon-wp-coding-standards - Coding standards
  • pantheon-systems/wpunit-helpers - WordPress testing helpers
  • phpunit/phpunit - PHP testing framework

• npm/yarn:

  • Pantheon Design System (PDS Core) - UI components

Future Improvements

• Accessibility audit (WCAG compliance)
• JavaScript bundling and minification
• Playwright E2E tests

FAQ

Is this an official Pantheon plugin?

No, this is a Hackathon 2026 project built by Chris Reynolds, Senior Developer Advocate at Pantheon. It was built independently and is not officially supported by Pantheon.

Will this work with other hosting providers?

No, this plugin only works on Pantheon. It relies on:

• Pantheon environment variables ($_ENV['PANTHEON_SITE'], etc.)
• Pantheon Secrets API for credential storage
• Pantheon-specific infrastructure

Does this require a specific Pantheon plan?

The Pantheon API is available to all Pantheon customers. Some features may vary based on your plan level (e.g., multidev availability).

Is my machine token secure?

Yes, especially if using Pantheon Secrets. Starting with v0.4.0, each WordPress admin has their own machine token for better security and audit trails.

Pantheon Secrets (Recommended): Tokens stored in Pantheon Secrets are encrypted and retrieved at runtime using pantheon_get_secret(). This is the most secure option.

Database Storage (Fallback): Tokens stored in the WordPress database are encrypted with AES-256-CBC using WordPress salts (v0.4.0+). While encrypted, this is less secure than Pantheon Secrets. We highly recommend using Pantheon Secrets for production environments.

What permissions does this plugin grant WordPress admins?

WordPress users with manage_options capability can:

• View environment status and information
• Toggle SFTP/Git mode
• Deploy code and apply upstream updates
• Create/manage backups and multidev environments

WordPress admins cannot (via this plugin):

• Manage Pantheon users or organizations
• Access billing information
• Generate or revoke machine tokens
• Delete sites (except via debug mode demonstration feature)

Support

• Issues: Report bugs on GitHub Issues
• Documentation: See CLAUDE.md for technical architecture and development guidelines
• Pantheon API: Official API Documentation
• Pantheon Secrets: Pantheon Secrets Guide

License

This plugin is licensed under the GPL v2 or later.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

Credits

Developed with the power of the Pantheon Public API.

Named after Tolkien's One Ring inscription: "Ash nazg durbatulûk, ash nazg gimbatul, ash nazg thrakatulûk, agh burzum-ishi krimpatul" - One ring to rule them all, one ring to find them, one ring to bring them all, and in the darkness bind them.

Changelog

0.5.0 - Current Release

• Environment Metrics Visualization: New "Metrics" admin page showing traffic and performance analytics
• Chart.js Integration: Interactive line charts with Pantheon Design System colors and styling
• Multiple Time Periods: View metrics for 7 days, 28 days, 12 weeks, or 12 months
• Three Chart Types: Pages Served, Unique Visits, and Cache Performance (hits vs misses)
• Summary Statistics: Overall totals and average cache hit ratio with per-chart breakdowns
• Refresh Functionality: Clear cache and reload current metrics data
• Responsive Design: Mobile-friendly charts with smooth curves and hover interactions
• Debug Panels: Expandable API request/response panels for troubleshooting
• Comprehensive Tests: 24 PHPUnit tests for metrics API and UI components
• Chart.js in libs/: Renamed vendor directory to libs for better clarity

0.4.0

• Per-User Token Storage: Machine tokens now stored per-user instead of site-wide
• Token Encryption: AES-256-CBC encryption for database-stored tokens using WordPress salts
• Pantheon Secrets Integration: Per-user secret keys with user ID suffix (ash_nazg_machine_token_{user_id})
• Migration System: Backward-compatible migration from global to per-user tokens
• Migration UI: Admin notice with progressive nag (1 week → 24 hours) and settings page migration button
• Per-User Session Tokens: Separate session token caching per user for better audit trails
• Security Enhancement: Better security and audit trails with individual token revocation
• User ID Display: Prominent user ID display in settings for Pantheon Secrets setup
• PHPUnit Tests: Comprehensive test suite for user token functionality

0.3.2

• Bug Fixes: Clear logs false negative with clearstatcache(), SFTP mode switching on local environments
• API Endpoint Testing: Corrected upstream-updates endpoint path in dashboard testing
• Version Bump: Browser cache busting for modal.js and other JavaScript files

0.3.0 - Major Feature Release

• Code Deployment: Deploy to test/live environments with panel-based UI and sync content option
• Multidev Management: Create, merge, and delete multidev environments
• Backup Management: Create, list, restore, and download backups from any environment
• Clone Content: Copy database and/or files between environments with automatic URL search-replace
• Domain Management: Automatic domain addition for WordPress multisite subsites
• Delete Site: Demonstration feature (debug mode only) with big red button
• Build Pipeline: SASS compilation with Pantheon Design System integration
• PDS Integration: Fonts, design tokens, foundations, and branded Pantheon header
• Upstream Updates: Detection and filtering per environment
• Workflow Monitoring: Polling for long-running operations with progress modals

0.2.0 - Development Workflow

• SFTP/Git Mode Toggle: Switch connection modes with automatic verification
• Environment State Management: Persistent tracking in WordPress options
• Automatic Mode Switching: Auto-switch to SFTP for file operations
• Debug Log Viewer: View, fetch, and clear debug.log files without SSH
• JavaScript Organization: Separate files with proper enqueuing
• CSS Organization: Utility classes system, no inline styles
• Comprehensive Testing: API, state management, and AJAX test suites

0.1.0 - Initial Release

• Pantheon API client with authentication
• Dashboard with environment detection and API endpoint testing
• Site addons management (Redis, Solr)
• Workflows integration (Object Cache Pro installation)
• Smart caching with timestamps
• Settings page with machine token configuration
• WordPress coding standards and PHPUnit testing infrastructure