From b8359e236e831d8bc10bb128872c22c8ac81e7df Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 21:14:15 -0400
Subject: [PATCH 01/12] Move functions.php into includes/ and use
 require/require_once

Relocates the functions.php helper library into includes/ (updating cycle.php's reference and the moved file's own setup.php include to ../setup.php) and switches every file inclusion from include/include_once to require/require_once for fail-fast consistency. This plugin has no database schema, so there is no includes/database.php.
---
 .github/copilot-instructions.md         | 21 +++++++++++++--------
 cycle.php                               | 16 ++++++++--------
 functions.php => includes/functions.php |  2 +-
 3 files changed, 22 insertions(+), 17 deletions(-)
 rename functions.php => includes/functions.php (99%)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 2c273fa..a444561 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -25,14 +25,15 @@ When generating code for this repository:
 
 ```
 cycle/                # Repository root (install to plugins/cycle/ in Cacti)
-├── images/              # UI icons
-├── locales/                # Internationalization files
-├── cycle.js                   # Client-side graph rotation logic
-├── cycle.php                    # Main cycle viewer/administration UI
-├── functions.php                   # Shared helper functions
-├── INFO                               # Plugin metadata (name, version, compat)
+├── includes/            # Library/helper files, require_once'd from the entry points
+│   └── functions.php      # Shared helper functions
+├── images/                  # UI icons
+├── locales/                   # Internationalization files
+├── cycle.js                     # Client-side graph rotation logic
+├── cycle.php                      # Main cycle viewer/administration UI
+├── INFO                             # Plugin metadata (name, version, compat)
 ├── README.md
-└── setup.php                            # Plugin install/uninstall/upgrade hooks
+└── setup.php                          # Plugin install/uninstall/upgrade hooks
 ```
 
 ## Naming Conventions
@@ -143,7 +144,7 @@ Document all changes in `CHANGELOG.md`; use descriptive commit messages referenc
 
 - Translatable strings are managed with GNU gettext via `locales/build_gettext.sh`. `locales/po/cacti.pot` is the source template; Weblate owns syncing the per-language `.po`/`.mo` files from it.
 - **Never commit the per-language `.po` or compiled `.mo` files** (`locales/po/*.po`, `locales/LC_MESSAGES/*.mo`) in a plugin PR. Weblate is the sole owner of those catalogs, and regenerating them here produces spurious diffs and merge conflicts. `locales/po/cacti.pot` is the ONLY translation artifact a PR may add or modify.
-- When a pull request adds or changes a string wrapped in `__()`/`__n()`/`__esc()`/`__x()`/`__xn()`/`__gettext()`, run `locales/build_gettext.sh` before pushing and stage `locales/po/cacti.pot` only. `build_gettext.sh` also rewrites the `.po`/`.mo` files as a side effect; revert those before committing (`git checkout -- locales/po/*.po locales/LC_MESSAGES`), or run only the `xgettext` step that targets `cacti.pot`.
+- When a pull request adds or changes a string wrapped in `__()`/`__n()`/`__esc()`/`__x()`/`__xn()`/`__gettext()`, run `locales/build_gettext.sh` before pushing and stage `locales/po/cacti.pot` only. `build_gettext.sh` also rewrites the `.po`/`.mo` files as a side effect; revert those before committing (`git checkout -- locales/po/*.po locales/LC_MESSAGES`), or run only the `xgettext` step that targets `cacti.pot`.
 
 ## References
 
@@ -168,6 +169,10 @@ existing code or adding new code, not just in dedicated cleanup passes:
 - **i18n text domain.** Every `__()`/`__esc()` call must include this plugin's text domain as the
   final argument, except when deliberately comparing against a literal, untranslated Cacti-core
   label.
+- **File inclusion uses `require`/`require_once`.** Always use `require`/`require_once` (never
+  `include`/`include_once`) so a missing dependency fails fast and loudly. Keep library/helper files
+  (e.g. `functions.php`) under `includes/` and reference them from that path; entry points
+  (`cycle.php`, `setup.php`) stay in the plugin root.
 - **Plugin table-creation API.** Use `api_plugin_db_table_create()`/`api_plugin_db_add_column()`
   (from Cacti core's `lib/plugins.php`) instead of raw `CREATE TABLE`/`ALTER TABLE ... ADD COLUMN`.
   Both are idempotent (safe no-ops when already applied), so the same call can run unconditionally
diff --git a/cycle.php b/cycle.php
index 37b94c1..ba2942e 100644
--- a/cycle.php
+++ b/cycle.php
@@ -26,14 +26,14 @@
 
 chdir('../../');
 
-include_once('./include/auth.php');
-include_once('./lib/time.php');
-include_once('./lib/html_tree.php');
-include_once('./lib/api_graph.php');
-include_once('./lib/api_tree.php');
-include_once('./lib/utility.php');
-include_once('./lib/api_data_source.php');
-include_once('./plugins/cycle/functions.php');
+require_once('./include/auth.php');
+require_once('./lib/time.php');
+require_once('./lib/html_tree.php');
+require_once('./lib/api_graph.php');
+require_once('./lib/api_tree.php');
+require_once('./lib/utility.php');
+require_once('./lib/api_data_source.php');
+require_once('./plugins/cycle/includes/functions.php');
 
 set_default_action();
 
diff --git a/functions.php b/includes/functions.php
similarity index 99%
rename from functions.php
rename to includes/functions.php
index b7fd8b2..4b7b700 100644
--- a/functions.php
+++ b/includes/functions.php
@@ -22,7 +22,7 @@
  +-------------------------------------------------------------------------+
 */
 
-include_once(__DIR__ . '/setup.php');
+require_once(__DIR__ . '/../setup.php');
 
 $graphs_ppage = [
 	1   => __('%d Graph', 1, 'cycle'),

From cdf029e28a46e746169a52d89f8c1010fe79d1c6 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 22:27:31 -0400
Subject: [PATCH 02/12] CI: allowlist unmeasured cycle.php web entry point in
 patch-coverage

---
 tests/bin/patch-coverage.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tests/bin/patch-coverage.php b/tests/bin/patch-coverage.php
index e65b53d..5b176c4 100644
--- a/tests/bin/patch-coverage.php
+++ b/tests/bin/patch-coverage.php
@@ -160,6 +160,7 @@ function changed_lines($base_ref) {
  * Empty by default; add entries per repository as the need arises.
  */
 $unmeasured_allowlist = [
+	'cycle.php', // web UI entry point (chdir(../..) + require auth.php); not loadable in the isolated unit process
 ];
 $unmeasured            = array_values(array_diff(array_keys($changed), array_keys($measured)));
 $unexpected_unmeasured = array_values(array_diff($unmeasured, $unmeasured_allowlist));

From 00cc3b1d6dbe415144cf42045c3a4a9f696af6ec Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 22:28:32 -0400
Subject: [PATCH 03/12] i18n: regenerate cacti.pot for functions.php ->
 includes/functions.php move

---
 locales/po/cacti.pot | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/locales/po/cacti.pot b/locales/po/cacti.pot
index 996019c..0d45bd1 100644
--- a/locales/po/cacti.pot
+++ b/locales/po/cacti.pot
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Cacti \n"
 "Report-Msgid-Bugs-To: developers@cacti.net\n"
-"POT-Creation-Date: 2026-09-28 16:05-0400\n"
+"POT-Creation-Date: 2026-09-29 22:28-0400\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: Cacti Developers <developers@cacti.net>>\n"
 "Language-Team: Cacti Developers <developers@cacti.net>\n"
@@ -141,22 +141,22 @@ msgstr ""
 msgid "Cycle Graphs"
 msgstr ""
 
-#: functions.php setup.php
+#: includes/functions.php setup.php
 #, php-format
 msgid "%d Graph"
 msgstr ""
 
-#: functions.php setup.php
+#: includes/functions.php setup.php
 #, php-format
 msgid "%d Graphs"
 msgstr ""
 
-#: functions.php setup.php
+#: includes/functions.php setup.php
 #, php-format
 msgid "%d Column"
 msgstr ""
 
-#: functions.php setup.php
+#: includes/functions.php setup.php
 #, php-format
 msgid "%d Columns"
 msgstr ""

From fb9305fd00ae97e97d53862e8d52c92ccb4575d6 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 22:48:59 -0400
Subject: [PATCH 04/12] INFO: set compat to 1.2.32

---
 INFO | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/INFO b/INFO
index cd8fde6..3203864 100644
--- a/INFO
+++ b/INFO
@@ -26,5 +26,5 @@ longname = Cycle Graphs
 author = The Cacti Group
 email = 
 homepage = http://www.cacti.net
-compat = 1.1.22
+compat = 1.2.32
 capabilities = online_view:1, online_mgmt:1, offline_view:0, offline_mgmt:0, remote_collect:0

From 50a398c75a3c9d9c27e92ca60da60c93b3a98328 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Tue, 29 Sep 2026 23:28:54 -0400
Subject: [PATCH 05/12] docs: changelog entry for includes/functions.php
 relocation and require sweep

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 577ba13..c1ca5a8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # ChangeLog
 
 --- develop ---
+* dev: Relocate `functions.php` to `includes/functions.php` and convert every `include`/`include_once` to `require`/`require_once` for fail-fast loading
 * dev: Enforce patch coverage of changed lines in CI and remove the inert COMPOSER_ROOT_VERSION env from the Pest step
 * security: Add a version-safe CSP nonce (`plugin_cycle_csp_nonce()`) to every inline `<script>` tag so pages stay compatible with Cacti's Content-Security-Policy nonce enforcement, while falling back cleanly on older Cacti releases that lack the `CactiSecureHeaders` class
 * issue: PHPStan level 8 typing pass and null-safety hardening for a malformed/missing plugin INFO file

From edfeee348db9fc29c20691dd2e275665c51763f4 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 10:54:14 -0400
Subject: [PATCH 06/12] INFO: back off compat to 1.2.29

---
 INFO | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/INFO b/INFO
index 3203864..d475f57 100644
--- a/INFO
+++ b/INFO
@@ -26,5 +26,5 @@ longname = Cycle Graphs
 author = The Cacti Group
 email = 
 homepage = http://www.cacti.net
-compat = 1.2.32
+compat = 1.2.29
 capabilities = online_view:1, online_mgmt:1, offline_view:0, offline_mgmt:0, remote_collect:0

From 3ece56018d2e6850f9cc518ffe4ff60a229516db Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 15:00:16 -0400
Subject: [PATCH 07/12] Add manifest.json + upgrade-time file pruning

---
 .github/copilot-instructions.md          |   4 +
 .github/workflows/plugin-ci-workflow.yml |   3 +
 manifest.json                            |  21 +++
 setup.php                                | 160 +++++++++++++++++++++
 tests/Unit/CycleLifecycleTest.php        |  16 ++-
 tests/Unit/PruneFilesTest.php            | 173 +++++++++++++++++++++++
 tests/bin/validate-manifest.php          |  73 ++++++++++
 tests/bootstrap-unit.php                 |   2 +
 8 files changed, 450 insertions(+), 2 deletions(-)
 create mode 100644 manifest.json
 create mode 100644 tests/Unit/PruneFilesTest.php
 create mode 100644 tests/bin/validate-manifest.php

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index a444561..99eae0d 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -181,3 +181,7 @@ existing code or adding new code, not just in dedicated cleanup passes:
   line, `@param` lines, a blank comment line, then `@return`. Infer parameter/return types from
   actual usage; don't change the function's real type-hints in the same pass (let static analysis
   flag mismatches separately). Skip vendored third-party library files.
+
+## File manifest & upgrade pruning
+
+The plugin ships a root `manifest.json` with three arrays: `tombstones` (files/directories older versions shipped that have since moved or been removed), `expected` (the top-level files and directories that ship today, directories written with a trailing `/`), and `whitelist` (paths holding user data that must never be touched). Keep `expected` current: CI runs `tests/bin/validate-manifest.php`, which fails on any drift between `expected` and the real top-level tree (it ignores `tests/`, `.git*`, and whitelisted paths). Custom customer CSS/theme files belong in `expected`, and stylesheets live in `css/` (not `themes/`). On upgrade, `plugin_cycle_prune_files()` deletes the tombstoned paths and the dev-only `tests/` tree, leaves `whitelist` and `.git*` alone, and logs (without removing) any top-level entry the manifest does not account for. As a safety measure it refuses any tombstone that resolves outside the plugin directory (a tampered manifest.json) and logs a warning for any file or directory it cannot remove. When you move or delete a shipped file, add its old path to `tombstones` and update `expected` in the same change.
diff --git a/.github/workflows/plugin-ci-workflow.yml b/.github/workflows/plugin-ci-workflow.yml
index 456367b..32308a5 100644
--- a/.github/workflows/plugin-ci-workflow.yml
+++ b/.github/workflows/plugin-ci-workflow.yml
@@ -87,6 +87,9 @@ jobs:
     
     - name: Check PHP version
       run: php -v
+
+    - name: Validate plugin manifest (expected-file drift)
+      run: php cacti/plugins/cycle/tests/bin/validate-manifest.php
     
     - name: Run apt-get update
       run: sudo apt-get update
diff --git a/manifest.json b/manifest.json
new file mode 100644
index 0000000..a6d1b85
--- /dev/null
+++ b/manifest.json
@@ -0,0 +1,21 @@
+{
+    "tombstones": [],
+    "expected": [
+        ".mdl_style.rb",
+        ".mdlrc",
+        "CHANGELOG.md",
+        "INFO",
+        "LICENSE",
+        "README.md",
+        "cycle.php",
+        "images/",
+        "includes/",
+        "index.php",
+        "js/",
+        "locales/",
+        "manifest.json",
+        "phpunit.xml",
+        "setup.php"
+    ],
+    "whitelist": []
+}
diff --git a/setup.php b/setup.php
index 5e48d25..3459691 100644
--- a/setup.php
+++ b/setup.php
@@ -180,6 +180,9 @@ function cycle_check_upgrade(): void {
 			SET name = ?, author = ?, webpage = ?, version = ?
 			WHERE id = ?',
 			[$info['longname'], $info['author'], $info['homepage'], $info['version'], $id]);
+
+		// Remove files tombstoned in manifest.json plus the dev-only tests/ tree.
+		plugin_cycle_prune_files();
 	}
 }
 
@@ -543,4 +546,161 @@ function cycle_draw_navigation_text($nav) {
  */
 function cycle_api_graph_save($save): void {
 }
+
+/**
+ * Removes files and directories that a previous version of this plugin
+ * shipped but that have since moved or been deleted, using the tombstone
+ * and whitelist lists in manifest.json. Whitelisted (user-data) paths and
+ * any VCS metadata (.git*) are never touched; the dev-only tests/ tree is
+ * removed. Any path that resolves outside the plugin directory (a tampered
+ * manifest.json) is refused, and any file/directory that cannot be removed
+ * (e.g. read-only) is reported to the Cacti log. Any top-level entry that is
+ * neither expected nor a tombstone nor whitelisted is logged to the Cacti
+ * log and left in place. Called on a plugin version change.
+ *
+ * @return void
+ *
+ * @global array $config Cacti global configuration array; used to resolve
+ *                       the plugin directory.
+ */
+function plugin_cycle_prune_files(): void {
+	global $config;
+
+	$plugin_dir    = $config['base_path'] . '/plugins/cycle';
+	$manifest_path = $plugin_dir . '/manifest.json';
+
+	if (!is_readable($manifest_path)) {
+		return;
+	}
+
+	$manifest = json_decode((string) file_get_contents($manifest_path), true);
+
+	if (!is_array($manifest)) {
+		cacti_log('WARNING: cycle manifest.json could not be parsed; skipping file prune', false, 'CYCLE');
+
+		return;
+	}
+
+	$tombstones = isset($manifest['tombstones']) && is_array($manifest['tombstones']) ? $manifest['tombstones'] : [];
+	$expected   = isset($manifest['expected'])   && is_array($manifest['expected'])   ? $manifest['expected']   : [];
+	$whitelist  = isset($manifest['whitelist'])  && is_array($manifest['whitelist'])  ? $manifest['whitelist']  : [];
+
+	$protected = function (string $rel) use ($whitelist): bool {
+		if (strncmp($rel, '.git', 4) === 0) {
+			return true;
+		}
+
+		foreach ($whitelist as $entry) {
+			$entry = trim((string) $entry, '/');
+
+			if ($entry !== '' && ($rel === $entry || strncmp($rel, $entry . '/', strlen($entry) + 1) === 0)) {
+				return true;
+			}
+		}
+
+		return false;
+	};
+
+	// Security: resolve the plugin directory so a tampered manifest.json
+	// cannot steer the prune outside of it.
+	$plugin_real = realpath($plugin_dir);
+
+	// Remove tombstoned (moved/deleted) paths plus the dev-only tests/ tree.
+	$remove   = $tombstones;
+	$remove[] = 'tests/';
+
+	foreach ($remove as $rel) {
+		$rel = trim((string) $rel, '/');
+
+		if ($rel === '' || $protected($rel)) {
+			continue;
+		}
+
+		$path = $plugin_dir . '/' . $rel;
+
+		if (!is_link($path) && !file_exists($path)) {
+			continue;
+		}
+
+		// Refuse any path that, after resolving symlinks and ../ segments,
+		// escapes the plugin directory (protects user data from a tampered
+		// manifest.json).
+		$anchor = is_link($path) ? dirname($path) : $path;
+		$real   = realpath($anchor);
+
+		if ($real === false || ($real !== $plugin_real && strncmp($real, $plugin_real . DIRECTORY_SEPARATOR, strlen((string) $plugin_real) + 1) !== 0)) {
+			cacti_log(sprintf('WARNING: cycle prune refused to remove %s: path resolves outside the plugin directory (tampered manifest.json?)', $rel), false, 'CYCLE');
+
+			continue;
+		}
+
+		if (is_dir($path) && !is_link($path)) {
+			$removed = plugin_cycle_rmtree($path);
+		} else {
+			$removed = @unlink($path);
+		}
+
+		if (!$removed) {
+			cacti_log(sprintf('WARNING: cycle upgrade could not remove %s (check file/directory permissions)', $rel), false, 'CYCLE');
+		}
+	}
+
+	// Surface any top-level entry the manifest does not account for.
+	$known = [];
+
+	foreach (array_merge($expected, $tombstones) as $entry) {
+		$top = explode('/', trim((string) $entry, '/'))[0];
+
+		if ($top !== '') {
+			$known[$top] = true;
+		}
+	}
+
+	$entries = scandir($plugin_dir);
+
+	foreach (($entries !== false ? $entries : []) as $entry) {
+		if ($entry === '.' || $entry === '..' || $entry === 'tests' || $protected($entry) || isset($known[$entry])) {
+			continue;
+		}
+
+		cacti_log(sprintf('WARNING: cycle upgrade found a file/directory not described in manifest.json: %s (left in place)', $entry), false, 'CYCLE');
+	}
+}
+
+/**
+ * Recursively deletes a directory and its contents. Symlinks are removed
+ * without being followed. Helper for plugin_cycle_prune_files().
+ *
+ * @param string $dir Absolute path to the directory to remove.
+ *
+ * @return bool True if the directory and everything under it was removed;
+ *              false if any entry could not be deleted.
+ */
+function plugin_cycle_rmtree(string $dir): bool {
+	$entries = scandir($dir);
+	$ok      = true;
+
+	foreach (($entries !== false ? $entries : []) as $entry) {
+		if ($entry === '.' || $entry === '..') {
+			continue;
+		}
+
+		$path = $dir . '/' . $entry;
+
+		if (is_dir($path) && !is_link($path)) {
+			if (!plugin_cycle_rmtree($path)) {
+				$ok = false;
+			}
+		} elseif (!@unlink($path)) {
+			$ok = false;
+		}
+	}
+
+	if (!@rmdir($dir)) {
+		$ok = false;
+	}
+
+	return $ok;
+}
+
 ?>
diff --git a/tests/Unit/CycleLifecycleTest.php b/tests/Unit/CycleLifecycleTest.php
index 5f1595a..2917a76 100644
--- a/tests/Unit/CycleLifecycleTest.php
+++ b/tests/Unit/CycleLifecycleTest.php
@@ -56,13 +56,25 @@
 });
 
 it('re-registers hooks and updates plugin_config when an installed plugin version drifts', function () {
-	$info = plugin_cycle_version();
+	$realBase = $GLOBALS['config']['base_path'];
+	$info     = plugin_cycle_version();
 
 	cycle_test_mock_db('db_fetch_row', 'plugin_config', array('version' => '0.0.0', 'status' => '1'));
 	cycle_test_mock_db('db_fetch_cell', 'plugin_realms', '5');
 	cycle_test_mock_db('db_fetch_cell', 'plugin_config', '42');
 
-	cycle_check_upgrade();
+	// Sandbox base_path (a copy of the real INFO keeps the asserted params
+	// identical) so the upgrade-time prune runs against a throwaway tree.
+	$base = sys_get_temp_dir() . '/cycle-upg-' . uniqid();
+	mkdir($base . '/plugins/cycle', 0777, true);
+	copy($realBase . '/plugins/cycle/INFO', $base . '/plugins/cycle/INFO');
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		cycle_check_upgrade();
+	} finally {
+		$GLOBALS['config']['base_path'] = $realBase;
+	}
 
 	expect($GLOBALS['__test_registered_hooks'])->not->toBeEmpty();
 	expect($GLOBALS['__test_registered_realms'])->not->toBeEmpty();
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
new file mode 100644
index 0000000..27c3e5a
--- /dev/null
+++ b/tests/Unit/PruneFilesTest.php
@@ -0,0 +1,173 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Unit coverage for plugin_cycle_prune_files(): tombstone/tests removal,
+ * whitelist and .git protection, and logging of unaccounted-for entries.
+ */
+
+require_once __DIR__ . '/../../setup.php';
+
+function cycle_prune_fixture(array $manifest): string {
+	$base   = sys_get_temp_dir() . '/cycle-prune-' . uniqid();
+	$plugin = $base . '/plugins/cycle';
+
+	mkdir($plugin . '/include', 0777, true);
+	file_put_contents($plugin . '/include/old.php', "<?php\n");
+	mkdir($plugin . '/tests/Unit', 0777, true);
+	file_put_contents($plugin . '/tests/Unit/SomeTest.php', "<?php\n");
+	mkdir($plugin . '/userdata', 0777, true);
+	file_put_contents($plugin . '/userdata/keep.dat', 'keep');
+	mkdir($plugin . '/includes', 0777, true);
+	file_put_contents($plugin . '/INFO', "[info]\n");
+	file_put_contents($plugin . '/setup.php', "<?php\n");
+	file_put_contents($plugin . '/oldfile.php', "<?php\n");
+	file_put_contents($plugin . '/stray.php', "<?php\n");
+	mkdir($plugin . '/.git', 0777, true);
+	file_put_contents($plugin . '/.git/config', '');
+	file_put_contents($plugin . '/manifest.json', json_encode($manifest));
+
+	return $base;
+}
+
+beforeEach(function () {
+	$GLOBALS['__test_cacti_log'] = [];
+});
+
+it('removes tombstoned paths and the tests/ tree, keeps whitelist/.git/expected, logs strays', function () {
+	$manifest = [
+		'tombstones' => ['include/', 'oldfile.php', 'userdata/', 'gone.png'],
+		'expected'   => ['INFO', 'setup.php', 'includes/', 'manifest.json'],
+		'whitelist'  => ['userdata/'],
+	];
+
+	$base    = cycle_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/cycle';
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_cycle_prune_files();
+	} finally {
+		$GLOBALS['config']['base_path'] = $restore;
+	}
+
+	// Tombstone and the dev-only tests/ tree are gone.
+	expect(is_dir($plugin . '/include'))->toBeFalse();
+	expect(is_dir($plugin . '/tests'))->toBeFalse();
+	expect(is_file($plugin . '/oldfile.php'))->toBeFalse();
+
+	// Whitelisted user data, VCS metadata, and expected files are untouched.
+	// (userdata/ is even listed as a tombstone, but the whitelist wins.)
+	expect(is_file($plugin . '/userdata/keep.dat'))->toBeTrue();
+	expect(is_dir($plugin . '/.git'))->toBeTrue();
+	expect(is_file($plugin . '/INFO'))->toBeTrue();
+	expect(is_dir($plugin . '/includes'))->toBeTrue();
+
+	// An unexpected, non-whitelisted stray is left in place but logged.
+	expect(is_file($plugin . '/stray.php'))->toBeTrue();
+
+	$logged = implode("\n", $GLOBALS['__test_cacti_log']);
+	expect($logged)->toContain('stray.php');
+	expect($logged)->not->toContain('userdata');
+	expect($logged)->not->toContain('.git');
+});
+
+it('is a safe no-op when the manifest is missing', function () {
+	$base    = sys_get_temp_dir() . '/cycle-prune-missing-' . uniqid();
+	mkdir($base . '/plugins/cycle', 0777, true);
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_cycle_prune_files();
+	} finally {
+		$GLOBALS['config']['base_path'] = $restore;
+	}
+
+	expect($GLOBALS['__test_cacti_log'])->toBe([]);
+});
+
+it('logs and skips pruning when the manifest is malformed', function () {
+	$base   = sys_get_temp_dir() . '/cycle-prune-bad-' . uniqid();
+	$plugin = $base . '/plugins/cycle';
+	mkdir($plugin, 0777, true);
+	file_put_contents($plugin . '/manifest.json', 'not json');
+	mkdir($plugin . '/tests', 0777, true);
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_cycle_prune_files();
+	} finally {
+		$GLOBALS['config']['base_path'] = $restore;
+	}
+
+	// A malformed manifest must not delete anything.
+	expect(is_dir($plugin . '/tests'))->toBeTrue();
+	expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('could not be parsed');
+});
+
+it('refuses to remove a tombstone that resolves outside the plugin directory', function () {
+	$manifest = [
+		'tombstones' => ['../escapee.txt'],
+		'expected'   => ['manifest.json'],
+		'whitelist'  => [],
+	];
+
+	$base    = cycle_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/cycle';
+	$outside = $base . '/plugins/escapee.txt';
+	file_put_contents($outside, 'precious user data');
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_cycle_prune_files();
+	} finally {
+		$GLOBALS['config']['base_path'] = $restore;
+	}
+
+	// The out-of-tree file is untouched and the refusal is logged.
+	expect(is_file($outside))->toBeTrue();
+	expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('outside the plugin directory');
+});
+
+it('warns when a tombstoned path cannot be removed', function () {
+	$manifest = [
+		'tombstones' => ['locked/'],
+		'expected'   => ['manifest.json'],
+		'whitelist'  => [],
+	];
+
+	$base   = cycle_prune_fixture($manifest);
+	$plugin = $base . '/plugins/cycle';
+	mkdir($plugin . '/locked/sub', 0777, true);
+	file_put_contents($plugin . '/locked/sub/data', 'x');
+	chmod($plugin . '/locked/sub', 0500); // read-only dir: its child cannot be unlinked
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	set_error_handler(static fn () => true); // swallow the expected unlink warning
+
+	try {
+		plugin_cycle_prune_files();
+	} finally {
+		restore_error_handler();
+		$GLOBALS['config']['base_path'] = $restore;
+		@chmod($plugin . '/locked/sub', 0700);
+	}
+
+	expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('could not remove');
+})->skip(function () {
+	return function_exists('posix_getuid') && posix_getuid() === 0;
+}, 'permission checks are bypassed for the root user');
diff --git a/tests/bin/validate-manifest.php b/tests/bin/validate-manifest.php
new file mode 100644
index 0000000..aa9858b
--- /dev/null
+++ b/tests/bin/validate-manifest.php
@@ -0,0 +1,73 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+ | Validates that manifest.json's "expected" array matches the plugin's    |
+ | actual top-level tree, so the manifest that drives upgrade-time pruning  |
+ | cannot silently drift. tests/, .git* and whitelisted (user-data) paths  |
+ | are intentionally excluded. Exits non-zero on any drift.                |
+ +-------------------------------------------------------------------------+
+*/
+
+$root         = dirname(__DIR__, 2);
+$manifestPath = $root . '/manifest.json';
+
+if (!is_readable($manifestPath)) {
+	fwrite(STDERR, "manifest.json not found at plugin root\n");
+	exit(1);
+}
+
+$manifest = json_decode((string) file_get_contents($manifestPath), true);
+
+if (!is_array($manifest) || !isset($manifest['expected']) || !is_array($manifest['expected'])) {
+	fwrite(STDERR, "manifest.json is missing a valid 'expected' array\n");
+	exit(1);
+}
+
+$whitelist    = isset($manifest['whitelist']) && is_array($manifest['whitelist']) ? $manifest['whitelist'] : [];
+$whitelistTop = [];
+
+foreach ($whitelist as $entry) {
+	$entry = trim((string) $entry, '/');
+
+	if ($entry !== '') {
+		$whitelistTop[explode('/', $entry)[0]] = true;
+	}
+}
+
+$actual = [];
+
+foreach (scandir($root) as $entry) {
+	if ($entry === '.' || $entry === '..' || $entry === 'tests') {
+		continue;
+	}
+
+	if (strncmp($entry, '.git', 4) === 0 || isset($whitelistTop[$entry])) {
+		continue;
+	}
+
+	$actual[] = is_dir($root . '/' . $entry) ? $entry . '/' : $entry;
+}
+
+$expected = $manifest['expected'];
+sort($actual);
+sort($expected);
+
+$missing = array_values(array_diff($expected, $actual));
+$extra   = array_values(array_diff($actual, $expected));
+
+if ($missing === [] && $extra === []) {
+	echo "manifest.json 'expected' matches the plugin tree.\n";
+	exit(0);
+}
+
+if ($missing !== []) {
+	fwrite(STDERR, "manifest.json lists 'expected' entries that are missing on disk:\n  " . implode("\n  ", $missing) . "\n");
+}
+
+if ($extra !== []) {
+	fwrite(STDERR, "Plugin tree has top-level entries not in manifest.json 'expected'\n(add them to 'expected', or record them under 'tombstones'/'whitelist'):\n  " . implode("\n  ", $extra) . "\n");
+}
+
+exit(1);
diff --git a/tests/bootstrap-unit.php b/tests/bootstrap-unit.php
index bc17aee..598883b 100644
--- a/tests/bootstrap-unit.php
+++ b/tests/bootstrap-unit.php
@@ -257,6 +257,8 @@ function __esc($text, $domain = '') {
 
 if (!function_exists('cacti_log')) {
 	function cacti_log($message, $also_print = false, $log_type = '', $level = 0) {
+		$args = func_get_args();
+		$GLOBALS["__test_cacti_log"][] = isset($args[0]) ? (string) $args[0] : "";
 	}
 }
 

From 642b138fc9e681bc87c928eb2c0aa1de7c452193 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 19:53:57 -0400
Subject: [PATCH 08/12] Prune phpunit.xml on upgrade and ignore markdown-lint
 configs

phpunit.xml ships in the repo for CI but is a dev-only test artifact, so it
is removed from manifest.json 'expected', pruned from installs on upgrade
(like tests/), and excluded from the manifest drift check.

The retired markdown-lint configs (.mdlrc, .md_style.rb) are deleted, and
.md* is now ignored like .git*: protected from pruning and excluded from
drift if it reappears.
---
 .mdlrc                          | 24 ------------------------
 manifest.json                   |  3 ---
 setup.php                       |  8 +++++---
 tests/Unit/PruneFilesTest.php   |  8 ++++++++
 tests/bin/validate-manifest.php |  8 ++++----
 5 files changed, 17 insertions(+), 34 deletions(-)
 delete mode 100644 .mdlrc

diff --git a/.mdlrc b/.mdlrc
deleted file mode 100644
index 42c9b1d..0000000
--- a/.mdlrc
+++ /dev/null
@@ -1,24 +0,0 @@
-# +-------------------------------------------------------------------------+
-# | Copyright (C) 2004-2025 The Cacti Group                                 |
-# |                                                                         |
-# | 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.                            |
-# +-------------------------------------------------------------------------+
-# | Cacti: The Complete RRDtool-based Graphing Solution                     |
-# +-------------------------------------------------------------------------+
-# | This code is designed, written, and maintained by the Cacti Group. See  |
-# | about.php and/or the AUTHORS file for specific developer information.   |
-# +-------------------------------------------------------------------------+
-# | http://www.cacti.net/                                                   |
-# +-------------------------------------------------------------------------+
-
-# mdl cli configuration
-style ".mdl_style.rb"
-verbose false
diff --git a/manifest.json b/manifest.json
index a6d1b85..58a9633 100644
--- a/manifest.json
+++ b/manifest.json
@@ -1,8 +1,6 @@
 {
     "tombstones": [],
     "expected": [
-        ".mdl_style.rb",
-        ".mdlrc",
         "CHANGELOG.md",
         "INFO",
         "LICENSE",
@@ -14,7 +12,6 @@
         "js/",
         "locales/",
         "manifest.json",
-        "phpunit.xml",
         "setup.php"
     ],
     "whitelist": []
diff --git a/setup.php b/setup.php
index 8977199..55e37c4 100644
--- a/setup.php
+++ b/setup.php
@@ -594,7 +594,7 @@ function plugin_cycle_prune_files(): void {
 	$whitelist  = isset($manifest['whitelist'])  && is_array($manifest['whitelist'])  ? $manifest['whitelist']  : [];
 
 	$protected = function (string $rel) use ($whitelist): bool {
-		if (strncmp($rel, '.git', 4) === 0) {
+		if (strncmp($rel, '.git', 4) === 0 || strncmp($rel, '.md', 3) === 0) {
 			return true;
 		}
 
@@ -613,9 +613,11 @@ function plugin_cycle_prune_files(): void {
 	// cannot steer the prune outside of it.
 	$plugin_real = realpath($plugin_dir);
 
-	// Remove tombstoned (moved/deleted) paths plus the dev-only tests/ tree.
+	// Remove tombstoned (moved/deleted) paths plus the dev-only tests/
+	// tree and the phpunit.xml test configuration.
 	$remove   = $tombstones;
 	$remove[] = 'tests/';
+	$remove[] = 'phpunit.xml';
 
 	foreach ($remove as $rel) {
 		$rel = trim((string) $rel, '/');
@@ -667,7 +669,7 @@ function plugin_cycle_prune_files(): void {
 	$entries = scandir($plugin_dir);
 
 	foreach (($entries !== false ? $entries : []) as $entry) {
-		if ($entry === '.' || $entry === '..' || $entry === 'tests' || $protected($entry) || isset($known[$entry])) {
+		if ($entry === '.' || $entry === '..' || $entry === 'tests' || $entry === 'phpunit.xml' || $protected($entry) || isset($known[$entry])) {
 			continue;
 		}
 
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
index 27c3e5a..0549ea1 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -27,6 +27,9 @@ function cycle_prune_fixture(array $manifest): string {
 	file_put_contents($plugin . '/setup.php', "<?php\n");
 	file_put_contents($plugin . '/oldfile.php', "<?php\n");
 	file_put_contents($plugin . '/stray.php', "<?php\n");
+	file_put_contents($plugin . '/phpunit.xml', '');
+	file_put_contents($plugin . '/.mdlrc', '');
+	file_put_contents($plugin . '/.md_style.rb', '');
 	mkdir($plugin . '/.git', 0777, true);
 	file_put_contents($plugin . '/.git/config', '');
 	file_put_contents($plugin . '/manifest.json', json_encode($manifest));
@@ -61,6 +64,7 @@ function cycle_prune_fixture(array $manifest): string {
 	expect(is_dir($plugin . '/include'))->toBeFalse();
 	expect(is_dir($plugin . '/tests'))->toBeFalse();
 	expect(is_file($plugin . '/oldfile.php'))->toBeFalse();
+	expect(is_file($plugin . '/phpunit.xml'))->toBeFalse();
 
 	// Whitelisted user data, VCS metadata, and expected files are untouched.
 	// (userdata/ is even listed as a tombstone, but the whitelist wins.)
@@ -68,6 +72,8 @@ function cycle_prune_fixture(array $manifest): string {
 	expect(is_dir($plugin . '/.git'))->toBeTrue();
 	expect(is_file($plugin . '/INFO'))->toBeTrue();
 	expect(is_dir($plugin . '/includes'))->toBeTrue();
+	expect(is_file($plugin . '/.mdlrc'))->toBeTrue();
+	expect(is_file($plugin . '/.md_style.rb'))->toBeTrue();
 
 	// An unexpected, non-whitelisted stray is left in place but logged.
 	expect(is_file($plugin . '/stray.php'))->toBeTrue();
@@ -76,6 +82,8 @@ function cycle_prune_fixture(array $manifest): string {
 	expect($logged)->toContain('stray.php');
 	expect($logged)->not->toContain('userdata');
 	expect($logged)->not->toContain('.git');
+	expect($logged)->not->toContain('.mdlrc');
+	expect($logged)->not->toContain('.md_style.rb');
 });
 
 it('is a safe no-op when the manifest is missing', function () {
diff --git a/tests/bin/validate-manifest.php b/tests/bin/validate-manifest.php
index aa9858b..c54fab5 100644
--- a/tests/bin/validate-manifest.php
+++ b/tests/bin/validate-manifest.php
@@ -5,8 +5,8 @@
  +-------------------------------------------------------------------------+
  | Validates that manifest.json's "expected" array matches the plugin's    |
  | actual top-level tree, so the manifest that drives upgrade-time pruning  |
- | cannot silently drift. tests/, .git* and whitelisted (user-data) paths  |
- | are intentionally excluded. Exits non-zero on any drift.                |
+ | cannot silently drift. tests/, phpunit.xml, .git* and .md* are          |
+ | excluded, as are whitelisted (user-data) paths. Non-zero exit on drift. |
  +-------------------------------------------------------------------------+
 */
 
@@ -39,11 +39,11 @@
 $actual = [];
 
 foreach (scandir($root) as $entry) {
-	if ($entry === '.' || $entry === '..' || $entry === 'tests') {
+	if ($entry === '.' || $entry === '..' || $entry === 'tests' || $entry === 'phpunit.xml') {
 		continue;
 	}
 
-	if (strncmp($entry, '.git', 4) === 0 || isset($whitelistTop[$entry])) {
+	if (strncmp($entry, '.git', 4) === 0 || strncmp($entry, '.md', 3) === 0 || isset($whitelistTop[$entry])) {
 		continue;
 	}
 

From 3b1f5b214bfd7062e6ca1bbed2ff3ffe25bef200 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 22:13:55 -0400
Subject: [PATCH 09/12] Harden prune against tampered-manifest path traversal

The upgrade-time prune now rejects any tombstone containing '.'/'..' segments
(which could escape the plugin directory or resolve to its root) and treats
ancestors of whitelist entries as protected, so a tombstone on a parent
directory can no longer delete a whitelisted file beneath it.
---
 setup.php                     | 14 ++++++++-
 tests/Unit/PruneFilesTest.php | 59 ++++++++++++++++++++++++++++++++++-
 2 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/setup.php b/setup.php
index 55e37c4..b30fa0c 100644
--- a/setup.php
+++ b/setup.php
@@ -601,7 +601,9 @@ function plugin_cycle_prune_files(): void {
 		foreach ($whitelist as $entry) {
 			$entry = trim((string) $entry, '/');
 
-			if ($entry !== '' && ($rel === $entry || strncmp($rel, $entry . '/', strlen($entry) + 1) === 0)) {
+			if ($entry !== '' && ($rel === $entry
+				|| strncmp($rel, $entry . '/', strlen($entry) + 1) === 0
+				|| strncmp($entry, $rel . '/', strlen($rel) + 1) === 0)) {
 				return true;
 			}
 		}
@@ -626,6 +628,16 @@ function plugin_cycle_prune_files(): void {
 			continue;
 		}
 
+		// A tombstone must never contain '.'/'..' segments; a tampered manifest
+		// could use them to escape the plugin directory or target its root.
+		$segments = explode('/', $rel);
+
+		if (in_array('.', $segments, true) || in_array('..', $segments, true)) {
+			cacti_log(sprintf('WARNING: cycle prune refused to remove %s: path contains a traversal segment (tampered manifest.json?)', $rel), false, 'CYCLE');
+
+			continue;
+		}
+
 		$path = $plugin_dir . '/' . $rel;
 
 		if (!is_link($path) && !file_exists($path)) {
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
index 0549ea1..6cb534e 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -146,7 +146,7 @@ function cycle_prune_fixture(array $manifest): string {
 
 	// The out-of-tree file is untouched and the refusal is logged.
 	expect(is_file($outside))->toBeTrue();
-	expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('outside the plugin directory');
+	expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('a traversal segment');
 });
 
 it('warns when a tombstoned path cannot be removed', function () {
@@ -179,3 +179,60 @@ function cycle_prune_fixture(array $manifest): string {
 })->skip(function () {
 	return function_exists('posix_getuid') && posix_getuid() === 0;
 }, 'permission checks are bypassed for the root user');
+
+it('refuses a tombstone that escapes through a symlinked directory', function () {
+	$manifest = [
+		'tombstones' => ['escdir/secret.txt'],
+		'expected'   => ['manifest.json'],
+		'whitelist'  => [],
+	];
+
+	$base    = cycle_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/cycle';
+	$outside = $base . '/outside';
+	mkdir($outside, 0777, true);
+	file_put_contents($outside . '/secret.txt', 'precious user data');
+	@symlink($outside, $plugin . '/escdir');
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_cycle_prune_files();
+	} finally {
+		$GLOBALS['config']['base_path'] = $restore;
+	}
+
+	// The out-of-tree file reached through the symlink is untouched and logged.
+	expect(is_file($outside . '/secret.txt'))->toBeTrue();
+	expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('outside the plugin directory');
+})->skip(function () {
+	$probe = sys_get_temp_dir() . '/.prune-symlink-probe-' . uniqid();
+	$ok = @symlink(__FILE__, $probe);
+	@unlink($probe);
+
+	return $ok === false;
+}, 'symlinks are not supported on this filesystem');
+
+it('protects a whitelisted file from a tombstone on its parent directory', function () {
+	$manifest = [
+		'tombstones' => ['userdata/'],
+		'expected'   => ['manifest.json'],
+		'whitelist'  => ['userdata/keep.dat'],
+	];
+
+	$base    = cycle_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/cycle';
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_cycle_prune_files();
+	} finally {
+		$GLOBALS['config']['base_path'] = $restore;
+	}
+
+	// A whitelisted file shields its parent directory from a tombstone.
+	expect(is_file($plugin . '/userdata/keep.dat'))->toBeTrue();
+});

From 5ed1bbbf852ec8b074d25bb873694985ed56782c Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 22:32:52 -0400
Subject: [PATCH 10/12] docs: align the Project Structure comment column

The trailing '# ...' comments in the Project Structure block drifted further
right down the tree; align them all to a single column.
---
 .github/copilot-instructions.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 99eae0d..40b688d 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -25,15 +25,15 @@ When generating code for this repository:
 
 ```
 cycle/                # Repository root (install to plugins/cycle/ in Cacti)
-├── includes/            # Library/helper files, require_once'd from the entry points
-│   └── functions.php      # Shared helper functions
-├── images/                  # UI icons
-├── locales/                   # Internationalization files
-├── cycle.js                     # Client-side graph rotation logic
-├── cycle.php                      # Main cycle viewer/administration UI
-├── INFO                             # Plugin metadata (name, version, compat)
+├── includes/         # Library/helper files, require_once'd from the entry points
+│   └── functions.php # Shared helper functions
+├── images/           # UI icons
+├── locales/          # Internationalization files
+├── cycle.js          # Client-side graph rotation logic
+├── cycle.php         # Main cycle viewer/administration UI
+├── INFO              # Plugin metadata (name, version, compat)
 ├── README.md
-└── setup.php                          # Plugin install/uninstall/upgrade hooks
+└── setup.php         # Plugin install/uninstall/upgrade hooks
 ```
 
 ## Naming Conventions

From 31e74d09e0544ca4cf671ecd063feb3860f8610f Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 23:00:31 -0400
Subject: [PATCH 11/12] docs/tests: standardize test header and correct
 manifest-contract notes

- Use the full license header (from the plugin's own setup.php) in
  tests/Unit/PruneFilesTest.php instead of the abbreviated copyright banner.
- Document that the manifest drift check and the upgrade-time prune also
  handle phpunit.xml and .md* files, matching the implemented behavior.
---
 .github/copilot-instructions.md |  2 +-
 tests/Unit/PruneFilesTest.php   | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 40b688d..46ca518 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -184,4 +184,4 @@ existing code or adding new code, not just in dedicated cleanup passes:
 
 ## File manifest & upgrade pruning
 
-The plugin ships a root `manifest.json` with three arrays: `tombstones` (files/directories older versions shipped that have since moved or been removed), `expected` (the top-level files and directories that ship today, directories written with a trailing `/`), and `whitelist` (paths holding user data that must never be touched). Keep `expected` current: CI runs `tests/bin/validate-manifest.php`, which fails on any drift between `expected` and the real top-level tree (it ignores `tests/`, `.git*`, and whitelisted paths). Custom customer CSS/theme files belong in `expected`, and stylesheets live in `css/` (not `themes/`). On upgrade, `plugin_cycle_prune_files()` deletes the tombstoned paths and the dev-only `tests/` tree, leaves `whitelist` and `.git*` alone, and logs (without removing) any top-level entry the manifest does not account for. As a safety measure it refuses any tombstone that resolves outside the plugin directory (a tampered manifest.json) and logs a warning for any file or directory it cannot remove. When you move or delete a shipped file, add its old path to `tombstones` and update `expected` in the same change.
+The plugin ships a root `manifest.json` with three arrays: `tombstones` (files/directories older versions shipped that have since moved or been removed), `expected` (the top-level files and directories that ship today, directories written with a trailing `/`), and `whitelist` (paths holding user data that must never be touched). Keep `expected` current: CI runs `tests/bin/validate-manifest.php`, which fails on any drift between `expected` and the real top-level tree (it ignores `tests/`, `phpunit.xml`, `.git*`, `.md*`, and whitelisted paths). Custom customer CSS/theme files belong in `expected`, and stylesheets live in `css/` (not `themes/`). On upgrade, `plugin_cycle_prune_files()` deletes the tombstoned paths, the dev-only `tests/` tree, and the `phpunit.xml` test config, leaves `whitelist`, `.git*`, and `.md*` alone, and logs (without removing) any top-level entry the manifest does not account for. As a safety measure it refuses any tombstone that resolves outside the plugin directory (a tampered manifest.json) and logs a warning for any file or directory it cannot remove. When you move or delete a shipped file, add its old path to `tombstones` and update `expected` in the same change.
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
index 6cb534e..91c5cf6 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -2,6 +2,23 @@
 /*
  +-------------------------------------------------------------------------+
  | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | 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.                            |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDTool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | This code is designed, written, and maintained by the Cacti Group. See  |
+ | about.php and/or the AUTHORS file for specific developer information.   |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
  +-------------------------------------------------------------------------+
 */
 

From ade3c21d9b54609e3f12ff2bf4e7b9fb169315c5 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 23:18:26 -0400
Subject: [PATCH 12/12] refactor: rename prune helpers to the plugin-slug
 function prefix

The repository naming contract reserves the plugin_<name>_ prefix for plugin
lifecycle / hook-registration functions; all other functions use the plain
<name>_ prefix. Rename the internal upgrade helpers accordingly:

  plugin_<name>_prune_files() -> <name>_prune_files()
  plugin_<name>_rmtree()      -> <name>_rmtree()

The call site, unit tests, and the copilot-instructions.md references are
updated to match. No behavioral change.
---
 .github/copilot-instructions.md |  2 +-
 setup.php                       | 12 ++++++------
 tests/Unit/PruneFilesTest.php   | 16 ++++++++--------
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 46ca518..0cb66d4 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -184,4 +184,4 @@ existing code or adding new code, not just in dedicated cleanup passes:
 
 ## File manifest & upgrade pruning
 
-The plugin ships a root `manifest.json` with three arrays: `tombstones` (files/directories older versions shipped that have since moved or been removed), `expected` (the top-level files and directories that ship today, directories written with a trailing `/`), and `whitelist` (paths holding user data that must never be touched). Keep `expected` current: CI runs `tests/bin/validate-manifest.php`, which fails on any drift between `expected` and the real top-level tree (it ignores `tests/`, `phpunit.xml`, `.git*`, `.md*`, and whitelisted paths). Custom customer CSS/theme files belong in `expected`, and stylesheets live in `css/` (not `themes/`). On upgrade, `plugin_cycle_prune_files()` deletes the tombstoned paths, the dev-only `tests/` tree, and the `phpunit.xml` test config, leaves `whitelist`, `.git*`, and `.md*` alone, and logs (without removing) any top-level entry the manifest does not account for. As a safety measure it refuses any tombstone that resolves outside the plugin directory (a tampered manifest.json) and logs a warning for any file or directory it cannot remove. When you move or delete a shipped file, add its old path to `tombstones` and update `expected` in the same change.
+The plugin ships a root `manifest.json` with three arrays: `tombstones` (files/directories older versions shipped that have since moved or been removed), `expected` (the top-level files and directories that ship today, directories written with a trailing `/`), and `whitelist` (paths holding user data that must never be touched). Keep `expected` current: CI runs `tests/bin/validate-manifest.php`, which fails on any drift between `expected` and the real top-level tree (it ignores `tests/`, `phpunit.xml`, `.git*`, `.md*`, and whitelisted paths). Custom customer CSS/theme files belong in `expected`, and stylesheets live in `css/` (not `themes/`). On upgrade, `cycle_prune_files()` deletes the tombstoned paths, the dev-only `tests/` tree, and the `phpunit.xml` test config, leaves `whitelist`, `.git*`, and `.md*` alone, and logs (without removing) any top-level entry the manifest does not account for. As a safety measure it refuses any tombstone that resolves outside the plugin directory (a tampered manifest.json) and logs a warning for any file or directory it cannot remove. When you move or delete a shipped file, add its old path to `tombstones` and update `expected` in the same change.
diff --git a/setup.php b/setup.php
index b30fa0c..f950c53 100644
--- a/setup.php
+++ b/setup.php
@@ -182,7 +182,7 @@ function cycle_check_upgrade(): void {
 			[$info['longname'], $info['author'], $info['homepage'], $info['version'], $id]);
 
 		// Remove files tombstoned in manifest.json plus the dev-only tests/ tree.
-		plugin_cycle_prune_files();
+		cycle_prune_files();
 	}
 }
 
@@ -571,7 +571,7 @@ function cycle_api_graph_save($save): void {
  * @global array $config Cacti global configuration array; used to resolve
  *                       the plugin directory.
  */
-function plugin_cycle_prune_files(): void {
+function cycle_prune_files(): void {
 	global $config;
 
 	$plugin_dir    = $config['base_path'] . '/plugins/cycle';
@@ -657,7 +657,7 @@ function plugin_cycle_prune_files(): void {
 		}
 
 		if (is_dir($path) && !is_link($path)) {
-			$removed = plugin_cycle_rmtree($path);
+			$removed = cycle_rmtree($path);
 		} else {
 			$removed = @unlink($path);
 		}
@@ -691,14 +691,14 @@ function plugin_cycle_prune_files(): void {
 
 /**
  * Recursively deletes a directory and its contents. Symlinks are removed
- * without being followed. Helper for plugin_cycle_prune_files().
+ * without being followed. Helper for cycle_prune_files().
  *
  * @param string $dir Absolute path to the directory to remove.
  *
  * @return bool True if the directory and everything under it was removed;
  *              false if any entry could not be deleted.
  */
-function plugin_cycle_rmtree(string $dir): bool {
+function cycle_rmtree(string $dir): bool {
 	$entries = scandir($dir);
 	$ok      = true;
 
@@ -710,7 +710,7 @@ function plugin_cycle_rmtree(string $dir): bool {
 		$path = $dir . '/' . $entry;
 
 		if (is_dir($path) && !is_link($path)) {
-			if (!plugin_cycle_rmtree($path)) {
+			if (!cycle_rmtree($path)) {
 				$ok = false;
 			}
 		} elseif (!@unlink($path)) {
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
index 91c5cf6..84aab06 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -23,7 +23,7 @@
 */
 
 /*
- * Unit coverage for plugin_cycle_prune_files(): tombstone/tests removal,
+ * Unit coverage for cycle_prune_files(): tombstone/tests removal,
  * whitelist and .git protection, and logging of unaccounted-for entries.
  */
 
@@ -72,7 +72,7 @@ function cycle_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_cycle_prune_files();
+		cycle_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -111,7 +111,7 @@ function cycle_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_cycle_prune_files();
+		cycle_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -130,7 +130,7 @@ function cycle_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_cycle_prune_files();
+		cycle_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -156,7 +156,7 @@ function cycle_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_cycle_prune_files();
+		cycle_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -185,7 +185,7 @@ function cycle_prune_fixture(array $manifest): string {
 	set_error_handler(static fn () => true); // swallow the expected unlink warning
 
 	try {
-		plugin_cycle_prune_files();
+		cycle_prune_files();
 	} finally {
 		restore_error_handler();
 		$GLOBALS['config']['base_path'] = $restore;
@@ -215,7 +215,7 @@ function cycle_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_cycle_prune_files();
+		cycle_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -245,7 +245,7 @@ function cycle_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_cycle_prune_files();
+		cycle_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}