From 18cf60c2a49138c9c296db9e6eeeff750b96a092 Mon Sep 17 00:00:00 2001 From: Marcus Quinn <6428977+marcusquinn@users.noreply.github.com> Date: Wed, 22 Apr 2026 09:57:41 +0100 Subject: [PATCH] fix: correct case-sensitive require_once paths and add AGENTS.md (#14) * fix: correct case-sensitive require_once paths and add AGENTS.md for AI guidance - Fix includes/plugin.php -> includes/Plugin.php in main plugin file - Fix includes/core.php -> includes/Core.php in includes/Plugin.php (Linux case-sensitive filesystems fail silently on macOS; runtime bug on production) - Fix .ai-workflows/folder-structure.md: update class files to PascalCase, remove references to non-existent admin/ subdirectories (images/, partials/, settings/, tools/) that caused read:file_not_found errors in AI sessions - Add AGENTS.md with authoritative file map to reduce AI agent errors: edit:not_read_first, bash:other, edit:edit_stale_read, read:file_not_found Resolves #13 * fix: markdown formatting in AGENTS.md (Codacy MD022/MD032) --- .ai-workflows/folder-structure.md | 19 ++--- AGENTS.md | 101 +++++++++++++++++++++++ includes/Plugin.php | 2 +- wp-fix-plugin-does-not-exist-notices.php | 2 +- 4 files changed, 111 insertions(+), 13 deletions(-) create mode 100644 AGENTS.md diff --git a/.ai-workflows/folder-structure.md b/.ai-workflows/folder-structure.md index e63e665..8bc2cdf 100644 --- a/.ai-workflows/folder-structure.md +++ b/.ai-workflows/folder-structure.md @@ -16,10 +16,6 @@ This document outlines the folder structure of the plugin and explains the purpo - **admin/css/** - Admin-specific CSS files - **admin/js/** - Admin-specific JavaScript files -- **admin/images/** - Admin-specific images -- **admin/partials/** - Admin-specific template partials -- **admin/settings/** - Admin settings functionality -- **admin/tools/** - Admin tools functionality - **admin/lib/** - Admin-specific library files and helper functions - **admin/lib/admin.php** - Admin class for handling admin-specific functionality - **admin/lib/modal.php** - Modal class for handling the update source selector modal @@ -28,13 +24,14 @@ This document outlines the folder structure of the plugin and explains the purpo The `includes/` directory contains the core plugin functionality: -- **includes/core.php** - Core class for handling the main plugin functionality -- **includes/plugin.php** - Main plugin class that initializes all components -- **includes/updater.php** - Updater class for handling plugin updates +- **includes/Core.php** - Core class for handling the main plugin functionality +- **includes/Plugin.php** - Main plugin class that initializes all components +- **includes/Updater.php** - Updater class for handling plugin updates ## File Naming Conventions -- All PHP files in the `includes/` directory use lowercase filenames +- PHP class files in the `includes/` directory use PascalCase filenames matching the class name (e.g., `Core.php`, `Plugin.php`, `Updater.php`) +- PHP files in `admin/lib/` use lowercase filenames (e.g., `admin.php`, `modal.php`) - All directories use lowercase names - JavaScript and CSS files use kebab-case (e.g., `update-source-selector.js`) @@ -50,10 +47,10 @@ The `includes/` directory contains the core plugin functionality: When referring to files or directories in AI conversations, use the following format: -- **@includes/plugin.php** - Main plugin class -- **@includes/core.php** - Core functionality +- **@includes/Plugin.php** - Main plugin class +- **@includes/Core.php** - Core functionality - **@admin/lib/admin.php** - Admin functionality - **@admin/lib/modal.php** - Modal functionality -- **@includes/updater.php** - Updater functionality +- **@includes/Updater.php** - Updater functionality - **@admin/js/update-source-selector.js** - Update source selector JavaScript - **@admin/css/update-source-selector.css** - Update source selector CSS diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dde51ff --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,101 @@ +# AGENTS.md — AI Agent Guide for wp-fix-plugin-does-not-exist-notices + +This file provides precise, verified guidance for AI agents working in this repository. Read it before editing any file to avoid `read:file_not_found` and `edit:not_read_first` errors. + +## Repository Purpose + +**Fix 'Plugin file does not exist' Notices** — a WordPress plugin that detects active plugins whose files are missing, adds them to the Plugins list with a "Remove Notice" action link, and safely removes their database references. + +- GitHub: `wpallstars/wp-fix-plugin-does-not-exist-notices` +- Namespace: `WPALLSTARS\FixPluginDoesNotExistNotices` +- Text domain: `wp-fix-plugin-does-not-exist-notices` +- Current version: see `wp-fix-plugin-does-not-exist-notices.php` header + +## Exact File Map (authoritative — verified against git ls-files) + +**CRITICAL**: PHP class files in `includes/` use PascalCase. The docs and `require_once` paths must match exactly. On Linux (case-sensitive), wrong case = fatal error. + +``` +wp-fix-plugin-does-not-exist-notices.php # Plugin entry point — sets Version, requires includes/Plugin.php +includes/Plugin.php # Main Plugin class — loads dependencies, inits components +includes/Core.php # Core class — all WordPress hooks and plugin logic +includes/Updater.php # Updater class — handles Git Updater / WP.org update sources +admin/lib/admin.php # Admin\Admin class — admin page rendering, enqueues +admin/lib/modal.php # Admin\Modal class — update source selector modal +admin/css/admin-styles.css # General admin styles +admin/css/update-source-selector.css # Styles for the update source modal +admin/js/admin-scripts.js # General admin JS +admin/js/update-source-selector.js # JS for the update source modal +languages/wp-fix-plugin-does-not-exist-notices.pot # Translation template +build.sh # Build/release script +scripts/deploy-local.sh # Local deployment helper +composer.json # Composer config (no vendor/ committed) +README.md # Developer readme +readme.txt # WordPress.org readme (keep in sync with README.md) +CHANGELOG.md # Changelog (keep in sync with README.md and readme.txt) +``` + +**Directories that DO NOT exist** (do not attempt to read or create files here): + +- `admin/images/` — does not exist +- `admin/partials/` — does not exist +- `admin/settings/` — does not exist +- `admin/tools/` — does not exist +- `vendor/` — not committed; loaded at runtime if present + +## Before Editing Any File + +1. Read the file first: `Read includes/Core.php` — not `includes/core.php` (wrong case fails). +2. Re-read the file if another tool call may have modified it since your last read. +3. Verify the file path with `git ls-files ''` when uncertain. + +## Version Management + +Version appears in **four places** — all must be updated together: + +1. `wp-fix-plugin-does-not-exist-notices.php` — `Version:` header and `new Plugin(__FILE__, 'X.Y.Z')` +2. `includes/Plugin.php` — no direct version constant; version passed via constructor +3. `readme.txt` — `Stable tag:` and changelog section +4. `CHANGELOG.md` — top entry + +`README.md` changelog section must also stay in sync with `CHANGELOG.md`. + +## Common Tasks + +### Fix a bug in core plugin logic + +Edit `includes/Core.php`. All WordPress hooks are registered in the constructor. + +### Change admin UI or settings + +Edit `admin/lib/admin.php` (Admin class) and/or `admin/lib/modal.php` (Modal class). +CSS: `admin/css/admin-styles.css` or `admin/css/update-source-selector.css`. +JS: `admin/js/admin-scripts.js` or `admin/js/update-source-selector.js`. + +### Bump version for a release + +1. Update version in `wp-fix-plugin-does-not-exist-notices.php` (both header and constructor call). +2. Update `Stable tag:` in `readme.txt`. +3. Add changelog entry to `readme.txt`, `CHANGELOG.md`, and `README.md`. + +### Add or fix update source logic + +Edit `includes/Updater.php`. + +## Git Workflow + +- Branch naming: `feature/`, `fix/`, `patch/`, `refactor/` prefixes +- One branch per issue; one PR per issue +- Push to both `github` and `gitea` remotes +- Do not include version numbers in branch names during development + +## AI Workflow Documentation + +Extended guidance is in `.ai-workflows/`: + +- `folder-structure.md` — directory layout with correct filenames +- `git-workflow.md` — branching, commit messages, remote management +- `feature-development.md` — feature development process +- `bug-fixing.md` — bug investigation and fix process +- `release-process.md` — full release checklist including Git Updater notes +- `dev-prefs-memory.md` — persistent developer preferences diff --git a/includes/Plugin.php b/includes/Plugin.php index d5735c7..de70a93 100644 --- a/includes/Plugin.php +++ b/includes/Plugin.php @@ -110,7 +110,7 @@ class Plugin { } // Load required files - require_once $this->plugin_dir . 'includes/core.php'; + require_once $this->plugin_dir . 'includes/Core.php'; require_once $this->plugin_dir . 'admin/lib/admin.php'; require_once $this->plugin_dir . 'admin/lib/modal.php'; } diff --git a/wp-fix-plugin-does-not-exist-notices.php b/wp-fix-plugin-does-not-exist-notices.php index 8b6c84c..dc6e0f8 100644 --- a/wp-fix-plugin-does-not-exist-notices.php +++ b/wp-fix-plugin-does-not-exist-notices.php @@ -32,7 +32,7 @@ if (!defined('WPINC')) { } // Load the main plugin class -require_once plugin_dir_path(__FILE__) . 'includes/plugin.php'; +require_once plugin_dir_path(__FILE__) . 'includes/Plugin.php'; // Initialize the plugin // This is a test change for our new workflow