🛠️ CV AI Debug Assistant

AI-powered WordPress error debugging, right inside your dashboard.

Stop tailing debug.log over FTP. See your errors, get an instant AI-written fix, and survive a total site crash with a hardened emergency rescue console — all in one lightweight plugin.

---

✨ Why this exists

Every agency has lived this: a client site goes white-screen, wp-admin is unreachable, and someone's SSHing in with one hand while explaining to the client on the phone with the other.

CV AI Debug Assistant was built to remove that panic:

• See the real error the moment it happens, from inside wp-admin.
• Get an AI-written, plain-English explanation and fix — not a wall of stack trace.
• If the site is completely down, a standalone, password-protected rescue page still shows you the last errors — no working WordPress required.

---

📸 Screenshots

Dashboard — grouped errors, one-click AI fixes Duplicate warnings collapse into a single entry with an occurrence badge, and every log line gets an Ask AI button. The AI's answer is grounded in your actual WordPress version, PHP version, and active theme, so fixes aren't generic guesses.

Emergency Rescue — works even when WordPress doesn't A standalone page, completely independent of WordPress core, protected by a hashed password with brute-force lockout built in. The full stack trace — file, line number, call chain — the moment wp-admin itself is the thing that's broken.

---

🚀 Features

🧠 AI-powered fixes	One click sends an error to OpenAI and gets back a concise, actionable explanation — enriched with your site's WordPress version, PHP version, and active theme for more relevant answers.
🗂️ Duplicate error grouping	The same warning firing 200 times shows up once, with a ×200 badge — not 200 lines of noise.
⚡ Fast on huge logs	Reads log files in reverse 8KB chunks with a safety cap, so even a 500MB debug.log loads instantly instead of timing out.
🚨 Emergency Rescue page	A standalone PHP file, independent of WordPress core, so you can view recent errors even during a full site outage or database failure.
🔒 Hashed rescue password	Stored with password_hash() / verified with password_verify() — never plaintext, on disk or in the database.
🛑 Brute-force lockout	5 failed rescue-page login attempts locks that IP out for 15 minutes — tracked in a self-contained file, no database required.
🕵️ Not indexable	The rescue page ships with noindex, nofollow headers and a bundled .htaccess blocking direct access to its config files.
📋 One-click environment report	Copies a support-ticket-ready summary (WP/PHP/MySQL version, theme, memory limits) to your clipboard — no more manually gathering site details for support tickets.
🔁 Safe auto-migration	Upgrading from an older version automatically (and safely) migrates legacy settings — no manual cleanup, no surprise resets.

---

📦 Installation

1. Download the latest release (or clone this repo) into wp-content/plugins/.
2. Activate CV AI Debug Assistant from the Plugins screen.
3. Go to CV AI Debug in the sidebar.
4. Add your OpenAI API Key.
5. Make sure the following are set in wp-config.php so the plugin has a log to read:

   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   define( 'WP_DEBUG_DISPLAY', false );

6. Set a Rescue Password and bookmark the Emergency Rescue URL shown on the settings page — this is your lifeline if the site ever goes down.

---

🖥️ Usage

• Daily debugging: open CV AI Debug, scan the grouped error list, click Ask AI on anything you don't immediately recognize.
• Support tickets: click Copy System Environment and paste straight into a ticket or Slack thread.
• Site is down / wp-admin unreachable: open your bookmarked Emergency Rescue URL, enter your Rescue Password, and read the last errors directly — no working WordPress install required.

---

🔐 Security notes

This plugin handles two things that deserve care: your OpenAI API key, and access to your server's error logs (which can contain sensitive stack trace data). It's built with that in mind:

• The Rescue Password is never stored or transmitted in plaintext — only a password_hash() digest, both in the database and in the standalone config file.
• The Emergency Rescue page regenerates the session ID on login (prevents session fixation) and locks out an IP after 5 failed attempts for 15 minutes.
• The Emergency Rescue page is marked noindex, nofollow, noarchive and its internal config/lockout files are blocked from direct HTTP access via a bundled .htaccess (Apache) — a location block should be added manually on Nginx.
• Only non-sensitive environment data (WP/PHP version, theme name) is ever sent to OpenAI as context — never file paths, credentials, or API keys.
• If you're upgrading from a version older than 1.1.0, your existing Rescue Password is automatically migrated to a secure hash — you don't need to re-set it.

Found a security issue? Please open a private report rather than a public issue — see Security Policy below.

---

📦 Releasing a new version

Releases are fully automated. Once a version bump is committed, you never manually zip or upload anything — pushing a matching Git tag does the rest.

1. Bump the version in two places so they agree with each other:

• Version: header in cv-ai-debug-assistant.php
• Stable tag: in readme.txt

2. Commit and push as normal:

git add .
git commit -m "Release 1.0.0"
git push

3. Create and push a tag matching the version, prefixed with v:

git tag v1.0.0
git push origin v1.0.0

That tag push triggers .github/workflows/release.yml, which automatically:

• ✅ Verifies the tag (v1.0.0), the plugin header (Version: 1.0.0), and readme.txt (Stable tag: 1.0.0) all agree — and fails loudly if any of them are out of sync, before anything gets published.
• 📦 Builds a clean installable ZIP, stripped of everything repo-only (.github/, .gitignore, README.md, LICENSE, dev/build config files, etc.) — just the files WordPress needs.
• 🚀 Creates a GitHub Release titled CV AI Debug Assistant v1.0.0, with auto-generated release notes from the commits since the last tag.
• 📎 Uploads cv-ai-debug-assistant.zip as a downloadable Release Asset and marks it the Latest release — which also means GitHub tracks and displays its download count.

If the version check fails, delete the bad tag, fix the mismatch, and re-tag:

git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
# fix the version numbers, commit, then re-tag

---

🗂️ Project structure

cv-ai-debug-assistant/
├── .github/
│   └── workflows/
│       └── release.yml           # Tag a version -> auto-builds & publishes a GitHub Release
├── cv-ai-debug-assistant.php     # Plugin bootstrap: hooks, version, activation/upgrade migration
├── emergency-log-view.php        # Standalone emergency rescue page (works without WP core)
├── rescue-config.php             # Hashed rescue password, auto-managed — do not edit by hand
├── .htaccess                     # Blocks direct HTTP access to sensitive standalone files
├── readme.txt                    # WordPress.org-format plugin readme
├── README.md                     # You are here
├── LICENSE                       # GPLv2
├── .gitignore
├── includes/
│   ├── admin-menu.php            # Dashboard UI: settings, log view, grouping, env report
│   ├── class-ai-handler.php      # OpenAI request handling + system prompt
│   └── class-log-reader.php      # Efficient chunked debug.log reader
├── assets/
│   └── script.js                 # Dashboard interactivity (Ask AI, etc.)
└── screenshots/                  # Images used in this README

Note: .github/, README.md, LICENSE, and .gitignore are repository-only files — the automated release workflow strips them out, so they never end up in the installable plugin ZIP.

---

⚙️ Requirements

• WordPress 5.0+
• PHP 7.4+
• An OpenAI API key for the AI explanation feature (the log viewer and Emergency Rescue page work without one)

---

🗺️ Roadmap

• Severity filtering (Fatal / Warning / Notice / Deprecated) and search over log entries
• "Diff since last deploy" view — only show errors added since the log was last cleared
• Optional Slack/email alerting on new fatal errors

Have an idea? Open an issue — this is a tool built by an agency, for agencies, so practical day-to-day suggestions are especially welcome.

---

🔒 Security Policy

If you discover a security vulnerability, please email support@cvinfotech.com instead of opening a public issue. We'll acknowledge within 48 hours and credit you in the changelog once a fix ships, unless you'd prefer otherwise.

---

📄 Changelog

See readme.txt for the full version history, or the highlights below:

1.2.0 — Automatic secure migration of legacy rescue passwords, per-IP rescue-page lockout, bundled .htaccess hardening. 1.1.0 — Hashed rescue password, session regeneration, no-index headers, chunked log reads, duplicate error grouping, environment-aware AI prompts, copy-to-clipboard environment report. 1.0.0 — Initial release.

---

📜 License

GPLv2 or later — see LICENSE.

---

Built and maintained by CV Infotech