🧞 Jeannie - Your friendly site-check genie for WordPress Debugging

Granting one debug wish at a time

A TUI (Terminal User Interface) application built with Go and Bubble Tea to help technical support engineers diagnose WordPress installations efficiently.

Features

• Interactive Menu: Beautiful, easy-to-navigate menu system for all commands
• Debug Analysis: Run diagnostic checks using built-in rules
• Embedded Rules: 6 default rules included in the binary - no setup required
• Rules Management: Optionally add custom rules from GitHub repositories
• Beautiful TUI: Clean and intuitive terminal interface powered by Bubble Tea

Quick Start

Navigate to your WordPress installation root (where wp-config.php is located) and run:

cd /path/to/wordpress
jeannie-cli

This launches the interactive menu where you can choose:

• 🔍 Debug Analysis - Run diagnostic checks on your WordPress installation
• 📋 List Rules - View all available diagnostic rules
• ❌ Exit - Return to terminal

Use arrow keys or j/k to navigate, Enter to select, q to quit.

Commands

Interactive Menu (Default)

Launch the interactive menu:

jeannie-cli
# or explicitly
jeannie-cli menu

Debug Analysis

Run comprehensive diagnostic checks:

jeannie-cli check

Version

jeannie-cli version

Rules Management

List installed rules

jeannie-cli rules list

Pull rules from GitHub

jeannie-cli rules pull [repository-url]

Installation

Quick Install (Recommended)

curl -sSL https://raw.githubusercontent.com/marceltannich/jeannie-cli/main/install.sh | bash

This will:

• Download the latest binary for your OS/architecture
• Install to /usr/local/bin or ~/.jeannie/bin
• Default rules are already embedded in the binary - ready to use!

Manual Installation

Prerequisites

• Go 1.21 or higher

Build from source

go mod download
go build -o jeannie

Install

go install

Using with WordPress

Navigate to your WordPress installation root (where wp-config.php is located):

cd /path/to/wordpress
jeannie-cli

The interactive menu will launch automatically. Choose the action you want to perform.

Configuration

Set your default rules repository:

export JEANNIE_RULES_REPO="https://github.com/marceltannich/jeannie-rules"

Rules Management

Default Rules (Embedded)

Jeannie comes with 6 default rules embedded directly in the binary:

• Caching plugin detection
• Advanced cache dropin detection
• Object cache dropin detection
• High autoload entries check
• MU-plugins detection
• Debug log exposure check

No setup required - these rules work immediately after installation!

Custom Rules (Optional)

You can optionally add custom rules to extend Jeannie's capabilities:

# Pull custom rules from a repository (feature coming soon)
jeannie-cli rules pull https://github.com/your-team/custom-wp-rules

Custom rules are stored in ~/.jeannie/rules and will be merged with embedded rules. If a custom rule has the same ID as an embedded rule, the custom version takes precedence.

Rule Format

Each rule folder contains a rule.json file:

{
  "id": "caching/dropin_advanced_cache_active",
  "name": "Advanced Cache Dropin Active",
  "description": "advanced-cache.php present; WP still loads it even if the plugin is deactivated.",
  "severity": "warning",
  "fix": "remove/rename file; clear caches",
  "check_type": "file_exists_with_config",
  "target_files": ["wp-content/advanced-cache.php"],
  "evidence_format": "path=${file}, WP_CACHE=${wp_cache_value}"
}

Project Structure

jeannie/
├── main.go                 # Entry point
├── cmd/                    # CLI commands
│   ├── root.go            # Root command
│   ├── check.go           # Check command
│   ├── scan.go            # Scan command
│   └── rules.go           # Rules commands
├── embeddedrules/         # Embedded ruleset
│   └── ruleset/           # Default rules (embedded in binary)
│       ├── caching/
│       ├── database/
│       ├── plugins/
│       └── security/
├── internal/
│   ├── scanner/           # Scanning logic
│   │   └── scanner.go
│   ├── rules/             # Rules management
│   │   └── rules.go
│   └── tui/               # TUI components
│       ├── check_results.go
│       ├── scan_results.go
│       ├── rules_list.go
│       └── rules_pull.go
└── README.md

Development

Running locally

go run main.go scan .

Building

go build -o jeannie

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.