From a3f89882829aff524e7f6ffb091fb5f82b3c8d8f Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 21:22:28 -0400
Subject: [PATCH 01/18] Relocate schema + functions to includes/, add
 db_update_table upgrade

Moves the plugin_maint_schedules/plugin_maint_hosts schema into a new includes/database.php (thold model) and functions.php into includes/functions.php. setup.php delegates via require_once; the is_device_in_maintenance hook now registers includes/functions.php. Implements plugin_maint_check_upgrade() to version-gate, refresh the schema via db_update_table() (string/backtick composite primaries normalized to arrays so db_update_table is safe), and update the full plugin_config row. Converts include/include_once to require/require_once. Tests updated for the moved paths.
---
 .github/copilot-instructions.md               |  28 +++--
 CHANGELOG.md                                  |   1 +
 includes/database.php                         | 106 ++++++++++++++++
 functions.php => includes/functions.php       |   0
 maint.php                                     |   4 +-
 setup.php                                     | 113 +++++++++++-------
 tests/Security/AuthGuardTest.php              |   2 +-
 tests/Security/OutputEscapingTest.php         |   6 +-
 .../PreparedStatementConsistencyTest.php      |   4 +-
 tests/Security/RedirectSafetyTest.php         |   2 +-
 tests/Unit/CheckHostTest.php                  |   2 +-
 tests/Unit/CheckScheduleTest.php              |   2 +-
 .../MaintDeviceActionsAndDatabaseTest.php     |   1 +
 tests/bootstrap-unit.php                      |  13 ++
 14 files changed, 222 insertions(+), 62 deletions(-)
 create mode 100644 includes/database.php
 rename functions.php => includes/functions.php (100%)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index e408b48..aeb19c3 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -25,12 +25,14 @@ When generating code for this repository:
 
 ```
 maint/                # Repository root (install to plugins/maint/ in Cacti)
-├── locales/             # Internationalization files
-├── functions.php          # Runtime maintenance checks (plugin_maint_check_* -> plugin_maint_check_schedule)
-├── maint.php                # Main UI/controller: CRUD schedules, tabbed views, host associations
-├── INFO                        # Plugin metadata (name, version, compat)
+├── includes/            # Library/helper files, require_once'd from the entry points
+│   ├── database.php       # Schema management: table defs + create/upgrade helpers
+│   └── functions.php      # Runtime maintenance checks (plugin_maint_check_* -> plugin_maint_check_schedule)
+├── locales/                 # Internationalization files
+├── maint.php                  # Main UI/controller: CRUD schedules, tabbed views, host associations
+├── INFO                         # Plugin metadata (name, version, compat)
 ├── README.md
-└── setup.php                     # Plugin entry points and hooks (menu, realms, device actions, maintenance hook)
+└── setup.php                      # Plugin entry points and hooks (menu, realms, device actions, maintenance hook)
 ```
 
 ## Naming Conventions
@@ -77,7 +79,14 @@ arithmetic, strict `===` comparisons).
 
 ## Database Operations
 
-Tables are created in `maint_setup_database()` via `api_plugin_db_table_create()`; `plugin_maint_check_schedule()` updates `stime`/`etime` for recurring schedules when windows pass, and schedule listing in `maint.php` uses it to compute "Active" state.
+All schema management lives in `includes/database.php` (the thold model), not in `setup.php`. `setup.php`'s
+install/upgrade paths `require_once($config['base_path'] . '/plugins/maint/includes/database.php')` and
+delegate. Each table is defined once (`maint_schedules_table_data()`, `maint_hosts_table_data()`) and created
+via `api_plugin_db_table_create('maint', ...)`; `plugin_maint_check_upgrade()` version-gates against
+`plugin_config`, refreshes the schema through `maint_upgrade_tables()` (`db_update_table()` when the table
+exists, create fallback when missing), and updates the full `plugin_config` row on a version change.
+`plugin_maint_check_schedule()` (in `includes/functions.php`) updates `stime`/`etime` for recurring schedules
+when windows pass, and schedule listing in `maint.php` uses it to compute "Active" state.
 
 ## Internationalization
 
@@ -126,7 +135,7 @@ Document all changes via commit history; use descriptive commit messages referen
 
 - 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
 
@@ -150,6 +159,11 @@ 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`, `includes/database.php`) under `includes/` and reference them from that path;
+  entry points (`maint.php`, `setup.php`) stay in the plugin root. A hook registered for a function that
+  lives in `includes/functions.php` must pass `'includes/functions.php'` as its file argument.
 - **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/CHANGELOG.md b/CHANGELOG.md
index a4d1c76..f337f0d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 --- develop ---
 
+* refactor: Move schema management into includes/database.php (the thold model) and relocate functions.php into includes/; setup.php delegates via require_once, and plugin_maint_check_upgrade() now refreshes the schema via db_update_table() and updates the full plugin_config row on a version change. Switches every file inclusion from include/include_once to require/require_once
 * dev: Enforce patch coverage of changed lines in CI and remove the inert COMPOSER_ROOT_VERSION env from the Pest step
 * feature: Add a standard Cacti search filter to the Maintenance Schedules list that also matches the hostname/description/location/site name of associated Thold devices and the hostname/description of associated Servcheck tests
 * security: Add a version-safe CSP nonce (`plugin_maint_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
diff --git a/includes/database.php b/includes/database.php
new file mode 100644
index 0000000..fa26948
--- /dev/null
+++ b/includes/database.php
@@ -0,0 +1,106 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | 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/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/**
+ * The plugin_maint_schedules table definition (one row per maintenance
+ * schedule), shared by the create path (api_plugin_db_table_create()) and
+ * the upgrade path (db_update_table()) so both stay in sync from a single
+ * definition.
+ *
+ * @return array<string, mixed> The table definition array.
+ */
+function maint_schedules_table_data(): array {
+	$data              = [];
+	$data['columns'][] = ['name' => 'id', 'type' => 'int(11)', 'NULL' => false, 'auto_increment' => true];
+	$data['columns'][] = ['name' => 'enabled', 'type' => 'varchar(3)', 'NULL' => false, 'default' => 'on'];
+	$data['columns'][] = ['name' => 'name', 'type' => 'varchar(128)', 'NULL' => true];
+	$data['columns'][] = ['name' => 'mtype', 'type' => 'int(11)', 'NULL' => false];
+	$data['columns'][] = ['name' => 'stime', 'type' => 'int(22)', 'NULL' => false];
+	$data['columns'][] = ['name' => 'etime', 'type' => 'int(22)', 'NULL' => false];
+	$data['columns'][] = ['name' => 'minterval', 'type' => 'int(11)', 'NULL' => false];
+	$data['primary']   = ['id'];
+	$data['keys'][]    = ['name' => 'mtype', 'columns' => ['mtype']];
+	$data['keys'][]    = ['name' => 'enabled', 'columns' => ['enabled']];
+	$data['type']      = 'InnoDB';
+	$data['comment']   = 'Maintenance Schedules';
+
+	return $data;
+}
+
+/**
+ * The plugin_maint_hosts table definition (maps devices/tests to a
+ * maintenance schedule), shared by the create path
+ * (api_plugin_db_table_create()) and the upgrade path (db_update_table()).
+ *
+ * @return array<string, mixed> The table definition array.
+ */
+function maint_hosts_table_data(): array {
+	$data              = [];
+	$data['columns'][] = ['name' => 'type', 'type' => 'int(6)', 'NULL' => false];
+	$data['columns'][] = ['name' => 'host', 'type' => 'int(12)', 'NULL' => false];
+	$data['columns'][] = ['name' => 'schedule', 'type' => 'int(12)', 'NULL' => false];
+	$data['primary']   = ['type', 'schedule', 'host'];
+	$data['keys'][]    = ['name' => 'type', 'columns' => ['type']];
+	$data['keys'][]    = ['name' => 'schedule', 'columns' => ['schedule']];
+	$data['type']      = 'InnoDB';
+	$data['comment']   = 'Maintenance Schedules Hosts';
+
+	return $data;
+}
+
+/**
+ * Creates this plugin's database tables (plugin_maint_schedules and
+ * plugin_maint_hosts) through Cacti's tracked plugin table API. Called
+ * from plugin_maint_install() during installation, and re-run (safely, as
+ * a no-op for already-applied changes) from maint_upgrade_tables() during
+ * upgrades.
+ *
+ * @return void
+ */
+function maint_setup_database(): void {
+	api_plugin_db_table_create('maint', 'plugin_maint_schedules', maint_schedules_table_data());
+	api_plugin_db_table_create('maint', 'plugin_maint_hosts', maint_hosts_table_data());
+}
+
+/**
+ * Refreshes this plugin's tables to their current definition on upgrade:
+ * db_update_table() diffs the live schema against each definition and
+ * issues the exact ALTER when the table already exists, otherwise the
+ * table is created outright. Called from plugin_maint_check_upgrade() when
+ * the stored version changes.
+ *
+ * @return void
+ */
+function maint_upgrade_tables(): void {
+	foreach ([
+		'plugin_maint_schedules' => maint_schedules_table_data(),
+		'plugin_maint_hosts'     => maint_hosts_table_data(),
+	] as $table => $data) {
+		if (db_table_exists($table)) {
+			db_update_table($table, $data);
+		} else {
+			api_plugin_db_table_create('maint', $table, $data);
+		}
+	}
+}
diff --git a/functions.php b/includes/functions.php
similarity index 100%
rename from functions.php
rename to includes/functions.php
diff --git a/maint.php b/maint.php
index c49edf6..2eee730 100644
--- a/maint.php
+++ b/maint.php
@@ -28,8 +28,8 @@
 global $config;
 
 chdir('../../');
-include_once('./include/auth.php');
-include_once($config['base_path'] . '/plugins/maint/functions.php');
+require_once('./include/auth.php');
+require_once($config['base_path'] . '/plugins/maint/includes/functions.php');
 
 define('MAINT_HOST_FILTER_LOC_ANY', '__any'); // internal value unlikely in data
 define('MAINT_HOST_FILTER_LOC_NONE', '__none');
diff --git a/setup.php b/setup.php
index a0bdb32..0e95d1a 100644
--- a/setup.php
+++ b/setup.php
@@ -75,15 +75,19 @@ function plugin_maint_version(): array {
  * @return void
  */
 function plugin_maint_install(): void {
+	global $config;
+
 	api_plugin_register_hook('maint', 'config_arrays', 'maint_config_arrays', 'setup.php');
 	api_plugin_register_hook('maint', 'draw_navigation_text', 'maint_draw_navigation_text', 'setup.php');
 	api_plugin_register_hook('maint', 'device_edit_top_links', 'maint_device_edit_top_links', 'setup.php');
-	api_plugin_register_hook('maint', 'is_device_in_maintenance', 'plugin_maint_check_cacti_host', 'functions.php');
+	api_plugin_register_hook('maint', 'is_device_in_maintenance', 'plugin_maint_check_cacti_host', 'includes/functions.php');
 	api_plugin_register_hook('maint', 'device_action_array', 'maint_device_action_array', 'setup.php');
 	api_plugin_register_hook('maint', 'device_action_prepare', 'maint_device_action_prepare', 'setup.php');
 	api_plugin_register_hook('maint', 'device_action_execute', 'maint_device_action_execute', 'setup.php');
 	api_plugin_register_realm('maint', 'maint.php', 'Maintenance Schedules', 1);
 
+	require_once($config['base_path'] . '/plugins/maint/includes/database.php');
+
 	maint_setup_database();
 }
 
@@ -101,30 +105,84 @@ function plugin_maint_uninstall(): void {
 }
 
 /**
- * Check plugin configuration
- *
- * Currently a no-op placeholder. Invoked by Cacti's plugin architecture
- * on relevant page loads.
+ * Runs any pending schema/version upgrade for this plugin. Invoked by
+ * Cacti's plugin architecture on relevant page loads.
  *
  * @return bool Always returns true
  */
 function plugin_maint_check_config(): bool {
+	plugin_maint_check_upgrade();
+
 	return true;
 }
 
 /**
  * Upgrade the maintenance plugin
  *
- * Currently a no-op placeholder (this plugin's schema has not required
- * migrations since its initial release). Invoked by Cacti's plugin
- * architecture when an installed plugin's version increases.
+ * Runs any pending schema/version upgrade for this plugin. Invoked by
+ * Cacti's plugin architecture when an installed plugin's version
+ * increases.
  *
- * @return bool Always returns false (no upgrade needed)
+ * @return bool Always returns false
  */
 function plugin_maint_upgrade(): bool {
+	plugin_maint_check_upgrade();
+
 	return false;
 }
 
+/**
+ * Applies any pending schema migration for this plugin on a version change,
+ * based on comparing the installed version recorded in plugin_config
+ * against the current INFO file version. Only runs on plugins.php or
+ * maint.php to avoid the version lookup on every page. Refreshes the schema
+ * through includes/database.php and updates the full plugin_config row.
+ * Called from plugin_maint_check_config()/plugin_maint_upgrade().
+ *
+ * @return void
+ *
+ * @global array  $config           Cacti global configuration array; used
+ *                                   to locate the database/functions
+ *                                   libraries and this plugin's schema file.
+ * @global object $database_default  Reserved/declared for parity with the
+ *                                   included library files; not used
+ *                                   directly here.
+ */
+function plugin_maint_check_upgrade(): void {
+	global $config, $database_default;
+
+	// Only run this check on a page that actually needs the plugin's data.
+	$files = ['plugins.php', 'maint.php'];
+
+	if (isset($_SERVER['PHP_SELF']) && !in_array(basename($_SERVER['PHP_SELF']), $files, true)) {
+		return;
+	}
+
+	require_once($config['library_path'] . '/database.php');
+	require_once($config['library_path'] . '/functions.php');
+	require_once($config['base_path'] . '/plugins/maint/includes/database.php');
+
+	$info = plugin_maint_version();
+
+	if (empty($info['version']) || empty($info['longname']) || empty($info['author']) || empty($info['homepage'])) {
+		return;
+	}
+
+	$current = $info['version'];
+	$old     = db_fetch_cell("SELECT version FROM plugin_config WHERE directory='maint'");
+
+	if ($current != $old) {
+		// Refresh the schema from the shared definition (create when missing,
+		// db_update_table() diff when it already exists).
+		maint_upgrade_tables();
+
+		db_execute_prepared('UPDATE plugin_config
+			SET version = ?, name = ?, author = ?, webpage = ?
+			WHERE directory = ?',
+			[$info['version'], $info['longname'], $info['author'], $info['homepage'], 'maint']);
+	}
+}
+
 /**
  * Configure plugin menu arrays and augment roles
  *
@@ -496,39 +554,6 @@ function maint_device_action_execute(string $action): bool {
 /**
  * Setup database tables for maintenance plugin
  *
- * Creates two tables:
- * - plugin_maint_schedules: Stores maintenance schedules
- * - plugin_maint_hosts: Associates hosts with schedules
- * Called from plugin_maint_install() during plugin installation.
- *
- * @return void
+ * Moved to includes/database.php; see maint_setup_database() and
+ * maint_upgrade_tables() there.
  */
-function maint_setup_database(): void {
-	$data              = [];
-	$data['columns'][] = ['name' => 'id', 'type' => 'int(11)', 'NULL' => false, 'auto_increment' => true];
-	$data['columns'][] = ['name' => 'enabled', 'type' => 'varchar(3)', 'NULL' => false, 'default' => 'on'];
-	$data['columns'][] = ['name' => 'name', 'type' => 'varchar(128)', 'NULL' => true];
-	$data['columns'][] = ['name' => 'mtype', 'type' => 'int(11)', 'NULL' => false];
-	$data['columns'][] = ['name' => 'stime', 'type' => 'int(22)', 'NULL' => false];
-	$data['columns'][] = ['name' => 'etime', 'type' => 'int(22)', 'NULL' => false];
-	$data['columns'][] = ['name' => 'minterval', 'type' => 'int(11)', 'NULL' => false];
-	$data['primary']   = 'id';
-	$data['keys'][]    = ['name' => 'mtype', 'columns' => 'mtype'];
-	$data['keys'][]    = ['name' => 'enabled', 'columns' => 'enabled'];
-	$data['type']      = 'InnoDB';
-	$data['comment']   = 'Maintenance Schedules';
-
-	api_plugin_db_table_create('maint', 'plugin_maint_schedules', $data);
-
-	$data              = [];
-	$data['columns'][] = ['name' => 'type', 'type' => 'int(6)', 'NULL' => false];
-	$data['columns'][] = ['name' => 'host', 'type' => 'int(12)', 'NULL' => false];
-	$data['columns'][] = ['name' => 'schedule', 'type' => 'int(12)', 'NULL' => false];
-	$data['primary']   = 'type`,`schedule`,`host';
-	$data['keys'][]    = ['name' => 'type', 'columns' => 'type'];
-	$data['keys'][]    = ['name' => 'schedule', 'columns' => 'schedule'];
-	$data['type']      = 'InnoDB';
-	$data['comment']   = 'Maintenance Schedules Hosts';
-
-	api_plugin_db_table_create('maint', 'plugin_maint_hosts', $data);
-}
diff --git a/tests/Security/AuthGuardTest.php b/tests/Security/AuthGuardTest.php
index c669ddf..05008fe 100644
--- a/tests/Security/AuthGuardTest.php
+++ b/tests/Security/AuthGuardTest.php
@@ -39,7 +39,7 @@
 
 	it('validates numeric IDs from request variables before DB queries', function () {
 		$uiFiles = array(
-		'functions.php',
+		'includes/functions.php',
 		'maint.php',
 		);
 
diff --git a/tests/Security/OutputEscapingTest.php b/tests/Security/OutputEscapingTest.php
index 1fede6b..92b552e 100644
--- a/tests/Security/OutputEscapingTest.php
+++ b/tests/Security/OutputEscapingTest.php
@@ -10,7 +10,7 @@
 describe('output escaping in maint', function () {
 	it('does not interpolate raw variables into HTML attributes', function () {
 		$uiFiles = [
-		'functions.php',
+		'includes/functions.php',
 		'maint.php',
 		];
 
@@ -57,7 +57,7 @@
 
 	it('uses html_escape or __esc for user-controlled output', function () {
 		$uiFiles = [
-		'functions.php',
+		'includes/functions.php',
 		'maint.php',
 		];
 
@@ -89,7 +89,7 @@
 		// HTML hidden-input values and inline <script> URL strings in several places.
 		// Direct echoing must always go through html_escape_request_var() instead.
 		$uiFiles = [
-			'functions.php',
+			'includes/functions.php',
 			'maint.php',
 		];
 
diff --git a/tests/Security/PreparedStatementConsistencyTest.php b/tests/Security/PreparedStatementConsistencyTest.php
index d517ede..c5370f4 100644
--- a/tests/Security/PreparedStatementConsistencyTest.php
+++ b/tests/Security/PreparedStatementConsistencyTest.php
@@ -10,7 +10,7 @@
 describe('prepared statement consistency in maint', function () {
 	it('uses prepared DB helpers in all plugin files', function () {
 		$targetFiles = [
-		'functions.php',
+		'includes/functions.php',
 		'maint.php',
 		'setup.php',
 		];
@@ -51,7 +51,7 @@
 
 	it('uses parameterized placeholders not string interpolation in SQL', function () {
 		$targetFiles = [
-		'functions.php',
+		'includes/functions.php',
 		'maint.php',
 		'setup.php',
 		];
diff --git a/tests/Security/RedirectSafetyTest.php b/tests/Security/RedirectSafetyTest.php
index a48c2bf..b5fa15d 100644
--- a/tests/Security/RedirectSafetyTest.php
+++ b/tests/Security/RedirectSafetyTest.php
@@ -10,7 +10,7 @@
 describe('redirect safety in maint', function () {
 	it('calls exit or die after header Location redirects', function () {
 		$files = array(
-		'functions.php',
+		'includes/functions.php',
 		'maint.php',
 		);
 
diff --git a/tests/Unit/CheckHostTest.php b/tests/Unit/CheckHostTest.php
index 3ba263f..a3467f3 100644
--- a/tests/Unit/CheckHostTest.php
+++ b/tests/Unit/CheckHostTest.php
@@ -10,7 +10,7 @@
 uses(TestCase::class);
 
 beforeEach(function () {
-	$this->loadPluginSource('functions.php');
+	$this->loadPluginSource('includes/functions.php');
 });
 
 describe('plugin_maint_check_host type dispatch', function () {
diff --git a/tests/Unit/CheckScheduleTest.php b/tests/Unit/CheckScheduleTest.php
index 0db4b7e..20560f5 100644
--- a/tests/Unit/CheckScheduleTest.php
+++ b/tests/Unit/CheckScheduleTest.php
@@ -10,7 +10,7 @@
 uses(TestCase::class);
 
 beforeEach(function () {
-	$this->loadPluginSource('functions.php');
+	$this->loadPluginSource('includes/functions.php');
 });
 
 describe('plugin_maint_check_schedule one-time schedules', function () {
diff --git a/tests/Unit/MaintDeviceActionsAndDatabaseTest.php b/tests/Unit/MaintDeviceActionsAndDatabaseTest.php
index a30c925..cd998a8 100644
--- a/tests/Unit/MaintDeviceActionsAndDatabaseTest.php
+++ b/tests/Unit/MaintDeviceActionsAndDatabaseTest.php
@@ -12,6 +12,7 @@
 
 beforeAll(function () {
 	require_once __DIR__ . '/../../setup.php';
+	require_once __DIR__ . '/../../includes/database.php';
 });
 
 beforeEach(function () {
diff --git a/tests/bootstrap-unit.php b/tests/bootstrap-unit.php
index 81584b5..5ba0890 100644
--- a/tests/bootstrap-unit.php
+++ b/tests/bootstrap-unit.php
@@ -203,6 +203,19 @@ function api_plugin_db_table_create($plugin, $table, $data) {
 	}
 }
 
+if (!function_exists('db_update_table')) {
+	function db_update_table($table, $data) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_update_table', 'sql' => $table, 'params' => $data);
+		return true;
+	}
+}
+
+if (!function_exists('db_table_exists')) {
+	function db_table_exists($table) {
+		return $GLOBALS['__test_table_exists'][$table] ?? false;
+	}
+}
+
 $GLOBALS['__test_registered_hooks'] = array();
 
 if (!function_exists('api_plugin_register_hook')) {

From 1e421d0963079b1f46a9387e3e73ede82d2d13c1 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 22:49:02 -0400
Subject: [PATCH 02/18] INFO: set compat to 1.2.32

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

diff --git a/INFO b/INFO
index 74b97da..3c555d2 100644
--- a/INFO
+++ b/INFO
@@ -26,5 +26,5 @@ longname = Maintenance Scheduler
 author = The Cacti Group
 email = 
 homepage = http://cacti.net
-compat = 1.2.0
+compat = 1.2.32
 capabilities = online_view:1, online_mgmt:1, offline_view:0, offline_mgmt:0, remote_collect:0

From 36f17c9a29e631a4daa5ae4b9611e3fb6d03c78c Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 22:58:18 -0400
Subject: [PATCH 03/18] CI: prepared version lookup in check_upgrade, allowlist
 includes/database.php

---
 setup.php                    | 2 +-
 tests/bin/patch-coverage.php | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/setup.php b/setup.php
index 0e95d1a..6d2bcea 100644
--- a/setup.php
+++ b/setup.php
@@ -169,7 +169,7 @@ function plugin_maint_check_upgrade(): void {
 	}
 
 	$current = $info['version'];
-	$old     = db_fetch_cell("SELECT version FROM plugin_config WHERE directory='maint'");
+	$old     = db_fetch_cell_prepared('SELECT version FROM plugin_config WHERE directory = ?', ['maint']);
 
 	if ($current != $old) {
 		// Refresh the schema from the shared definition (create when missing,
diff --git a/tests/bin/patch-coverage.php b/tests/bin/patch-coverage.php
index e65b53d..fe66cc6 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 = [
+	'includes/database.php', // install/upgrade/drop schema bootstrap; require_once's the live Cacti library, only runs during a real install/upgrade
 ];
 $unmeasured            = array_values(array_diff(array_keys($changed), array_keys($measured)));
 $unexpected_unmeasured = array_values(array_diff($unmeasured, $unmeasured_allowlist));

From c910b498d136e505da868ddb94214e8ef2681e8c Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 23:00:57 -0400
Subject: [PATCH 04/18] test: cover plugin_maint_check_upgrade; de-measure
 maint.php web entry

---
 phpunit.xml                          |   1 -
 tests/Unit/MaintCheckUpgradeTest.php | 129 +++++++++++++++++++++++++++
 tests/bin/patch-coverage.php         |   1 +
 3 files changed, 130 insertions(+), 1 deletion(-)
 create mode 100644 tests/Unit/MaintCheckUpgradeTest.php

diff --git a/phpunit.xml b/phpunit.xml
index 9c70ec8..83668ac 100644
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -28,7 +28,6 @@
     <source>
         <include>
             <file>functions.php</file>
-            <file>maint.php</file>
             <file>setup.php</file>
         </include>
     </source>
diff --git a/tests/Unit/MaintCheckUpgradeTest.php b/tests/Unit/MaintCheckUpgradeTest.php
new file mode 100644
index 0000000..5221f66
--- /dev/null
+++ b/tests/Unit/MaintCheckUpgradeTest.php
@@ -0,0 +1,129 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDtool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Coverage for plugin_maint_check_upgrade()'s version-change branch: driven
+ * past the page-gate with a stored plugin_config version that differs from the
+ * packaged version, it refreshes the schema (maint_upgrade_tables()) and writes
+ * the full plugin_config row.
+ */
+
+beforeAll(function () {
+	require_once __DIR__ . '/../../setup.php';
+	require_once __DIR__ . '/../../includes/database.php';
+});
+
+it('refreshes the schema and updates plugin_config when the stored version differs', function () {
+	/*
+	 * plugin_maint_check_upgrade() require_once's $config['library_path'] .
+	 * '/database.php' and '/functions.php' after the page-gate. The bootstrap
+	 * leaves library_path unset, so point it at a throwaway directory of empty
+	 * files to let those requires resolve without redeclaring real Cacti helpers.
+	 */
+	$lib = sys_get_temp_dir() . '/maint_lib_' . uniqid('', true);
+	mkdir($lib);
+	file_put_contents($lib . '/database.php', "<?php\n");
+	file_put_contents($lib . '/functions.php', "<?php\n");
+
+	$original_library_path             = $GLOBALS['config']['library_path'] ?? null;
+	$original_self                     = $_SERVER['PHP_SELF'] ?? null;
+	$GLOBALS['config']['library_path'] = $lib;
+
+	// Pass the page-gate: basename must be one of plugins.php / maint.php.
+	$_SERVER['PHP_SELF'] = '/cacti/plugins/maint/maint.php';
+
+	// db_table_exists defaults to false -> create branch; stale stored version.
+	$GLOBALS['__test_table_exists'] = [];
+	maint_test_queue('db_fetch_cell_prepared', '0.0-stale');
+	$GLOBALS['__test_db_calls'] = [];
+
+	try {
+		plugin_maint_check_upgrade();
+	} finally {
+		if ($original_self === null) {
+			unset($_SERVER['PHP_SELF']);
+		} else {
+			$_SERVER['PHP_SELF'] = $original_self;
+		}
+
+		if ($original_library_path === null) {
+			unset($GLOBALS['config']['library_path']);
+		} else {
+			$GLOBALS['config']['library_path'] = $original_library_path;
+		}
+
+		@unlink($lib . '/database.php');
+		@unlink($lib . '/functions.php');
+		@rmdir($lib);
+	}
+
+	$created = array_column(array_filter($GLOBALS['__test_db_calls'], function ($call) {
+		return $call['fn'] === 'api_plugin_db_table_create';
+	}), 'sql');
+
+	$config_updates = array_filter($GLOBALS['__test_db_calls'], function ($call) {
+		return $call['fn'] === 'db_execute_prepared' && strpos($call['sql'], 'plugin_config') !== false;
+	});
+
+	expect($created)->toContain('plugin_maint_schedules');
+	expect($created)->toContain('plugin_maint_hosts');
+	expect($config_updates)->not->toBeEmpty();
+});
+
+it('bails out without touching the schema when the packaged INFO is incomplete', function () {
+	$lib = sys_get_temp_dir() . '/maint_lib_' . uniqid('', true);
+	mkdir($lib);
+	file_put_contents($lib . '/database.php', "<?php\n");
+	file_put_contents($lib . '/functions.php', "<?php\n");
+
+	$original_library_path             = $GLOBALS['config']['library_path'] ?? null;
+	$original_self                     = $_SERVER['PHP_SELF'] ?? null;
+	$GLOBALS['config']['library_path'] = $lib;
+	$_SERVER['PHP_SELF']               = '/cacti/plugins/maint/maint.php';
+
+	/*
+	 * plugin_maint_version() parses $config['base_path'] . '/plugins/maint/INFO'.
+	 * base_path must stay real (the require_once above reads the plugin's own
+	 * includes/database.php from it), so temporarily replace the INFO on disk
+	 * with one missing required keys to exercise the empty($info[...]) guard.
+	 */
+	$info_path   = $GLOBALS['config']['base_path'] . '/plugins/maint/INFO';
+	$info_backup = file_get_contents($info_path);
+	file_put_contents($info_path, "[info]\nname = maint\n");
+
+	$GLOBALS['__test_db_calls'] = [];
+
+	try {
+		plugin_maint_check_upgrade();
+	} finally {
+		file_put_contents($info_path, $info_backup);
+
+		if ($original_self === null) {
+			unset($_SERVER['PHP_SELF']);
+		} else {
+			$_SERVER['PHP_SELF'] = $original_self;
+		}
+
+		if ($original_library_path === null) {
+			unset($GLOBALS['config']['library_path']);
+		} else {
+			$GLOBALS['config']['library_path'] = $original_library_path;
+		}
+
+		@unlink($lib . '/database.php');
+		@unlink($lib . '/functions.php');
+		@rmdir($lib);
+	}
+
+	$config_updates = array_filter($GLOBALS['__test_db_calls'], function ($call) {
+		return $call['fn'] === 'db_execute_prepared' && strpos($call['sql'], 'plugin_config') !== false;
+	});
+
+	expect($config_updates)->toBeEmpty();
+});
diff --git a/tests/bin/patch-coverage.php b/tests/bin/patch-coverage.php
index fe66cc6..31b6bf9 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 = [
+	'maint.php',             // web UI entry point (chdir(../../) + require auth.php); not loadable in the isolated unit process
 	'includes/database.php', // install/upgrade/drop schema bootstrap; require_once's the live Cacti library, only runs during a real install/upgrade
 ];
 $unmeasured            = array_values(array_diff(array_keys($changed), array_keys($measured)));

From 31fd2f32405011050c2a227cf251dd68d91acbd2 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Tue, 29 Sep 2026 23:29:22 -0400
Subject: [PATCH 05/18] fix: restore root functions.php shim for core snmpagent
 hard-coded include

Cacti core's lib/snmpagent.php (snmpagent_poller_bottom) hard-codes
include_once('plugins/maint/functions.php') to load
plugin_maint_check_cacti_host() during the poller run. Relocating the
functions to includes/functions.php broke that fixed path, which logged a
PHP WARNING (failing the 'Verify Cacti log' CI step) and silently disabled
the poller-side maintenance check. Add a thin root functions.php that
forwards to includes/functions.php so the core path keeps working.
---
 functions.php | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 functions.php

diff --git a/functions.php b/functions.php
new file mode 100644
index 0000000..b55802e
--- /dev/null
+++ b/functions.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types = 1);
+
+/*
+ ex: set tabstop=4 shiftwidth=4 autoindent:
+ +-------------------------------------------------------------------------+
+ | 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/                                                   |
+ +-------------------------------------------------------------------------+
+*/
+
+/**
+ * Back-compat shim.
+ *
+ * Cacti core's lib/snmpagent.php (snmpagent_poller_bottom) hard-codes
+ * include_once('plugins/maint/functions.php') to load
+ * plugin_maint_check_cacti_host() during the poller run. The plugin's
+ * functions were relocated to includes/functions.php, so this root file
+ * remains only to satisfy that fixed core path and forward to the new
+ * location. Remove once no supported Cacti release includes this path.
+ */
+
+require_once(__DIR__ . '/includes/functions.php');

From f0ee6acd5ba5be8b20c6c8f2d863f0ddb1156d96 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Tue, 29 Sep 2026 23:34:09 -0400
Subject: [PATCH 06/18] test: measure includes/functions.php and allowlist the
 root shim

The relocation moved functions.php to includes/functions.php but left the
coverage <source> pointing at the old root path, so the patch-coverage gate
saw includes/functions.php as changed-but-unmeasured and failed. Point
<source> at includes/functions.php so its changed lines are measured, and
add the thin root functions.php shim to the unmeasured allowlist (it only
forwards to includes/functions.php for core's hard-coded snmpagent include).
---
 phpunit.xml                  | 2 +-
 tests/bin/patch-coverage.php | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/phpunit.xml b/phpunit.xml
index 83668ac..f790fa4 100644
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -27,7 +27,7 @@
     -->
     <source>
         <include>
-            <file>functions.php</file>
+            <file>includes/functions.php</file>
             <file>setup.php</file>
         </include>
     </source>
diff --git a/tests/bin/patch-coverage.php b/tests/bin/patch-coverage.php
index 31b6bf9..262e7a0 100644
--- a/tests/bin/patch-coverage.php
+++ b/tests/bin/patch-coverage.php
@@ -162,6 +162,7 @@ function changed_lines($base_ref) {
 $unmeasured_allowlist = [
 	'maint.php',             // web UI entry point (chdir(../../) + require auth.php); not loadable in the isolated unit process
 	'includes/database.php', // install/upgrade/drop schema bootstrap; require_once's the live Cacti library, only runs during a real install/upgrade
+	'functions.php',         // back-compat shim; only forwards to includes/functions.php for core's hard-coded snmpagent include, nothing to cover
 ];
 $unmeasured            = array_values(array_diff(array_keys($changed), array_keys($measured)));
 $unexpected_unmeasured = array_values(array_diff($unmeasured, $unmeasured_allowlist));

From 1bf70421d7f28fd3827f35f735b56cc581193fdc Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Tue, 29 Sep 2026 23:35:21 -0400
Subject: [PATCH 07/18] fix: legacy scalar primary for create, gate version
 bump on upgrade success, drop orphaned docblock

---
 includes/database.php | 43 +++++++++++++++++++++++++++++++++++++------
 setup.php             | 23 +++++++++--------------
 2 files changed, 46 insertions(+), 20 deletions(-)

diff --git a/includes/database.php b/includes/database.php
index fa26948..cc08ba6 100644
--- a/includes/database.php
+++ b/includes/database.php
@@ -79,8 +79,28 @@ function maint_hosts_table_data(): array {
  * @return void
  */
 function maint_setup_database(): void {
-	api_plugin_db_table_create('maint', 'plugin_maint_schedules', maint_schedules_table_data());
-	api_plugin_db_table_create('maint', 'plugin_maint_hosts', maint_hosts_table_data());
+	api_plugin_db_table_create('maint', 'plugin_maint_schedules', maint_create_definition(maint_schedules_table_data()));
+	api_plugin_db_table_create('maint', 'plugin_maint_hosts', maint_create_definition(maint_hosts_table_data()));
+}
+
+/**
+ * Returns a copy of a table definition with its array primary key
+ * normalized to the legacy backtick-joined scalar form. Older Cacti
+ * releases (1.2.0) concatenate data['primary'] straight into the CREATE in
+ * api_plugin_db_table_create(), so an array would render PRIMARY KEY
+ * (`Array`) and break a fresh install; the array form is retained in the
+ * *_table_data() helpers for db_update_table(), which requires it.
+ *
+ * @param array<string, mixed> $data The table definition (array primary).
+ *
+ * @return array<string, mixed> The definition with a scalar primary key.
+ */
+function maint_create_definition(array $data): array {
+	if (isset($data['primary']) && is_array($data['primary'])) {
+		$data['primary'] = implode('`,`', $data['primary']);
+	}
+
+	return $data;
 }
 
 /**
@@ -90,17 +110,28 @@ function maint_setup_database(): void {
  * table is created outright. Called from plugin_maint_check_upgrade() when
  * the stored version changes.
  *
- * @return void
+ * @return bool True when every table reconciled; false when any
+ *              db_update_table()/api_plugin_db_table_create() reported an
+ *              explicit failure, so the caller can skip the version bump
+ *              and retry on the next request.
  */
-function maint_upgrade_tables(): void {
+function maint_upgrade_tables(): bool {
+	$success = true;
+
 	foreach ([
 		'plugin_maint_schedules' => maint_schedules_table_data(),
 		'plugin_maint_hosts'     => maint_hosts_table_data(),
 	] as $table => $data) {
 		if (db_table_exists($table)) {
-			db_update_table($table, $data);
+			$result = db_update_table($table, $data);
 		} else {
-			api_plugin_db_table_create('maint', $table, $data);
+			$result = api_plugin_db_table_create('maint', $table, maint_create_definition($data));
+		}
+
+		if ($result === false) {
+			$success = false;
 		}
 	}
+
+	return $success;
 }
diff --git a/setup.php b/setup.php
index 6d2bcea..a5a8eff 100644
--- a/setup.php
+++ b/setup.php
@@ -173,13 +173,15 @@ function plugin_maint_check_upgrade(): void {
 
 	if ($current != $old) {
 		// Refresh the schema from the shared definition (create when missing,
-		// db_update_table() diff when it already exists).
-		maint_upgrade_tables();
-
-		db_execute_prepared('UPDATE plugin_config
-			SET version = ?, name = ?, author = ?, webpage = ?
-			WHERE directory = ?',
-			[$info['version'], $info['longname'], $info['author'], $info['homepage'], 'maint']);
+		// db_update_table() diff when it already exists). Only record the new
+		// version once every table reconciled, so a failed refresh is retried on
+		// the next request instead of being masked by a now-matching version.
+		if (maint_upgrade_tables()) {
+			db_execute_prepared('UPDATE plugin_config
+				SET version = ?, name = ?, author = ?, webpage = ?
+				WHERE directory = ?',
+				[$info['version'], $info['longname'], $info['author'], $info['homepage'], 'maint']);
+		}
 	}
 }
 
@@ -550,10 +552,3 @@ function maint_device_action_execute(string $action): bool {
 
 	return false;
 }
-
-/**
- * Setup database tables for maintenance plugin
- *
- * Moved to includes/database.php; see maint_setup_database() and
- * maint_upgrade_tables() there.
- */

From 1071b721fc6dd98823fbd0dac180b16e467e01b6 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Tue, 29 Sep 2026 23:42:18 -0400
Subject: [PATCH 08/18] fix(ci): match clover files to the longest changed
 path, not the first

A shorter changed path can be a suffix of a longer one - the root
back-compat functions.php shim vs includes/functions.php - so first-match
attributed the includes/functions.php clover entry to the root shim and
reported the real file as unmeasured (failing the gate despite 100%
coverage). Select the most specific (longest) matching candidate instead.
---
 tests/bin/patch-coverage.php | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/tests/bin/patch-coverage.php b/tests/bin/patch-coverage.php
index 262e7a0..fc06000 100644
--- a/tests/bin/patch-coverage.php
+++ b/tests/bin/patch-coverage.php
@@ -118,11 +118,16 @@ function changed_lines($base_ref) {
 	$path     = (string) $file['name'];
 	$relative = null;
 
+	// Pick the most specific (longest) matching candidate. A shorter path can
+	// be a suffix of a longer one (e.g. the root back-compat 'functions.php'
+	// shim vs 'includes/functions.php'), so a first-match would misattribute
+	// the clover file to the wrong changed path and report the real file as
+	// unmeasured.
 	foreach (array_keys($changed) as $candidate) {
 		if ($path === $candidate || substr($path, -strlen('/' . $candidate)) === '/' . $candidate) {
-			$relative = $candidate;
-
-			break;
+			if ($relative === null || strlen($candidate) > strlen($relative)) {
+				$relative = $candidate;
+			}
 		}
 	}
 

From 440f327ee7e957d99c17d010ef010287fc87d230 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 00:33:26 -0400
Subject: [PATCH 09/18] fix(upgrade): re-register is_device_in_maintenance hook
 against includes/functions.php

plugin_maint_install() registers the hook with the relocated includes/functions.php path, but install never re-runs on upgrade and core's api_plugin_upgrade_register() only touches plugin_config, never plugin_hooks. Existing installs therefore keep the stale functions.php hook file. Re-register the hook in plugin_maint_check_upgrade()'s version-change branch so upgraded sites pick up the new path (currently only surviving via the back-compat root shim). Assert the repoint in MaintCheckUpgradeTest.
---
 CHANGELOG.md                         | 2 +-
 setup.php                            | 6 ++++++
 tests/Unit/MaintCheckUpgradeTest.php | 8 +++++++-
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f337f0d..0ba67bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 --- develop ---
 
-* refactor: Move schema management into includes/database.php (the thold model) and relocate functions.php into includes/; setup.php delegates via require_once, and plugin_maint_check_upgrade() now refreshes the schema via db_update_table() and updates the full plugin_config row on a version change. Switches every file inclusion from include/include_once to require/require_once
+* refactor: Move schema management into includes/database.php (the thold model) and relocate functions.php into includes/; setup.php delegates via require_once, and plugin_maint_check_upgrade() now refreshes the schema via db_update_table(), re-registers the is_device_in_maintenance hook against includes/functions.php, and updates the full plugin_config row on a version change. Switches every file inclusion from include/include_once to require/require_once
 * dev: Enforce patch coverage of changed lines in CI and remove the inert COMPOSER_ROOT_VERSION env from the Pest step
 * feature: Add a standard Cacti search filter to the Maintenance Schedules list that also matches the hostname/description/location/site name of associated Thold devices and the hostname/description of associated Servcheck tests
 * security: Add a version-safe CSP nonce (`plugin_maint_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
diff --git a/setup.php b/setup.php
index a5a8eff..bf09194 100644
--- a/setup.php
+++ b/setup.php
@@ -177,6 +177,12 @@ function plugin_maint_check_upgrade(): void {
 		// version once every table reconciled, so a failed refresh is retried on
 		// the next request instead of being masked by a now-matching version.
 		if (maint_upgrade_tables()) {
+			// Re-register the is_device_in_maintenance hook so existing installs
+			// pick up the relocated includes/functions.php file. plugin_maint_install()
+			// registers the new path, but it never re-runs on upgrade, and core's
+			// upgrade path only touches plugin_config, never plugin_hooks.
+			api_plugin_register_hook('maint', 'is_device_in_maintenance', 'plugin_maint_check_cacti_host', 'includes/functions.php');
+
 			db_execute_prepared('UPDATE plugin_config
 				SET version = ?, name = ?, author = ?, webpage = ?
 				WHERE directory = ?',
diff --git a/tests/Unit/MaintCheckUpgradeTest.php b/tests/Unit/MaintCheckUpgradeTest.php
index 5221f66..92647f8 100644
--- a/tests/Unit/MaintCheckUpgradeTest.php
+++ b/tests/Unit/MaintCheckUpgradeTest.php
@@ -41,7 +41,8 @@
 	// db_table_exists defaults to false -> create branch; stale stored version.
 	$GLOBALS['__test_table_exists'] = [];
 	maint_test_queue('db_fetch_cell_prepared', '0.0-stale');
-	$GLOBALS['__test_db_calls'] = [];
+	$GLOBALS['__test_db_calls']         = [];
+	$GLOBALS['__test_registered_hooks'] = [];
 
 	try {
 		plugin_maint_check_upgrade();
@@ -71,8 +72,13 @@
 		return $call['fn'] === 'db_execute_prepared' && strpos($call['sql'], 'plugin_config') !== false;
 	});
 
+	$repointed = array_filter($GLOBALS['__test_registered_hooks'], function ($hook) {
+		return $hook['hook'] === 'is_device_in_maintenance' && $hook['file'] === 'includes/functions.php';
+	});
+
 	expect($created)->toContain('plugin_maint_schedules');
 	expect($created)->toContain('plugin_maint_hosts');
+	expect($repointed)->not->toBeEmpty();
 	expect($config_updates)->not->toBeEmpty();
 });
 

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

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

diff --git a/INFO b/INFO
index 3c555d2..e32353c 100644
--- a/INFO
+++ b/INFO
@@ -26,5 +26,5 @@ longname = Maintenance Scheduler
 author = The Cacti Group
 email = 
 homepage = http://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 411eb97f883cc93cc6771ecadbf5b28d507fd82e Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 15:15:44 -0400
Subject: [PATCH 11/18] Add manifest.json + upgrade-time file pruning

---
 .github/copilot-instructions.md          |   4 +
 .github/workflows/plugin-ci-workflow.yml |   3 +
 manifest.json                            |  18 +++
 setup.php                                | 166 ++++++++++++++++++++++
 tests/Unit/MaintCheckUpgradeTest.php     |  19 +++
 tests/Unit/MaintLifecycleTest.php        |   7 +
 tests/Unit/PruneFilesTest.php            | 173 +++++++++++++++++++++++
 tests/bin/validate-manifest.php          |  73 ++++++++++
 tests/bootstrap-unit.php                 |   3 +-
 9 files changed, 465 insertions(+), 1 deletion(-)
 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 aeb19c3..5b55a35 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -172,3 +172,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_maint_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 2c09779..d3f0560 100644
--- a/.github/workflows/plugin-ci-workflow.yml
+++ b/.github/workflows/plugin-ci-workflow.yml
@@ -89,6 +89,9 @@ jobs:
     - name: Check PHP version
       run: php -v
 
+    - name: Validate plugin manifest (expected-file drift)
+      run: php cacti/plugins/maint/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..9953f29
--- /dev/null
+++ b/manifest.json
@@ -0,0 +1,18 @@
+{
+    "tombstones": [],
+    "expected": [
+        ".pre-commit-config.yml",
+        "CHANGELOG.md",
+        "INFO",
+        "LICENSE",
+        "README.md",
+        "includes/",
+        "index.php",
+        "locales/",
+        "maint.php",
+        "manifest.json",
+        "phpunit.xml",
+        "setup.php"
+    ],
+    "whitelist": []
+}
diff --git a/setup.php b/setup.php
index bf09194..69cef2a 100644
--- a/setup.php
+++ b/setup.php
@@ -187,6 +187,9 @@ function plugin_maint_check_upgrade(): void {
 				SET version = ?, name = ?, author = ?, webpage = ?
 				WHERE directory = ?',
 				[$info['version'], $info['longname'], $info['author'], $info['homepage'], 'maint']);
+
+			// Remove files tombstoned in manifest.json plus the dev-only tests/ tree.
+			plugin_maint_prune_files();
 		}
 	}
 }
@@ -558,3 +561,166 @@ function maint_device_action_execute(string $action): bool {
 
 	return false;
 }
+
+/**
+ * Setup database tables for maintenance plugin
+ *
+ * Moved to includes/database.php; see maint_setup_database() and
+ * maint_upgrade_tables() there.
+ */
+
+/**
+ * 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_maint_prune_files(): void {
+	global $config;
+
+	$plugin_dir    = $config['base_path'] . '/plugins/maint';
+	$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: maint manifest.json could not be parsed; skipping file prune', false, 'MAINT');
+
+		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: maint prune refused to remove %s: path resolves outside the plugin directory (tampered manifest.json?)', $rel), false, 'MAINT');
+
+			continue;
+		}
+
+		if (is_dir($path) && !is_link($path)) {
+			$removed = plugin_maint_rmtree($path);
+		} else {
+			$removed = @unlink($path);
+		}
+
+		if (!$removed) {
+			cacti_log(sprintf('WARNING: maint upgrade could not remove %s (check file/directory permissions)', $rel), false, 'MAINT');
+		}
+	}
+
+	// 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: maint upgrade found a file/directory not described in manifest.json: %s (left in place)', $entry), false, 'MAINT');
+	}
+}
+
+/**
+ * Recursively deletes a directory and its contents. Symlinks are removed
+ * without being followed. Helper for plugin_maint_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_maint_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_maint_rmtree($path)) {
+				$ok = false;
+			}
+		} elseif (!@unlink($path)) {
+			$ok = false;
+		}
+	}
+
+	if (!@rmdir($dir)) {
+		$ok = false;
+	}
+
+	return $ok;
+}
diff --git a/tests/Unit/MaintCheckUpgradeTest.php b/tests/Unit/MaintCheckUpgradeTest.php
index 92647f8..5e4994b 100644
--- a/tests/Unit/MaintCheckUpgradeTest.php
+++ b/tests/Unit/MaintCheckUpgradeTest.php
@@ -19,6 +19,25 @@
 	require_once __DIR__ . '/../../includes/database.php';
 });
 
+beforeEach(function () {
+	// Sandbox base_path (complete temp INFO + empty includes/database.php stub)
+	// so every upgrade-path test runs plugin_maint_prune_files() against a
+	// throwaway tree, never the real checkout. Tests needing a different INFO
+	// override base_path themselves.
+	$GLOBALS['__maint_base_restore'] = $GLOBALS['config']['base_path'];
+	$base = sys_get_temp_dir() . '/maint-test-' . uniqid();
+	mkdir($base . '/plugins/maint/includes', 0777, true);
+	file_put_contents($base . '/plugins/maint/INFO', "[info]\nversion = 9.9.9\nname = maint\nlongname = Maint\nauthor = x\nhomepage = x\n");
+	file_put_contents($base . '/plugins/maint/includes/database.php', "<?php\n");
+	$GLOBALS['config']['base_path'] = $base;
+});
+
+afterEach(function () {
+	if (isset($GLOBALS['__maint_base_restore'])) {
+		$GLOBALS['config']['base_path'] = $GLOBALS['__maint_base_restore'];
+	}
+});
+
 it('refreshes the schema and updates plugin_config when the stored version differs', function () {
 	/*
 	 * plugin_maint_check_upgrade() require_once's $config['library_path'] .
diff --git a/tests/Unit/MaintLifecycleTest.php b/tests/Unit/MaintLifecycleTest.php
index af8b6db..a77f13d 100644
--- a/tests/Unit/MaintLifecycleTest.php
+++ b/tests/Unit/MaintLifecycleTest.php
@@ -15,6 +15,13 @@
 	require_once __DIR__ . '/../../setup.php';
 });
 
+beforeEach(function () {
+	// Keep these contract tests off the upgrade path: a non-plugin page makes
+	// plugin_maint_check_upgrade() short-circuit before the version-drift block
+	// (and its file prune), which is covered separately by MaintCheckUpgradeTest.
+	$_SERVER['PHP_SELF'] = '/graphs.php';
+});
+
 it('parses the plugin INFO file into an info array', function () {
 	$info = plugin_maint_version();
 
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
new file mode 100644
index 0000000..11559f0
--- /dev/null
+++ b/tests/Unit/PruneFilesTest.php
@@ -0,0 +1,173 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Unit coverage for plugin_maint_prune_files(): tombstone/tests removal,
+ * whitelist and .git protection, and logging of unaccounted-for entries.
+ */
+
+require_once __DIR__ . '/../../setup.php';
+
+function maint_prune_fixture(array $manifest): string {
+	$base   = sys_get_temp_dir() . '/maint-prune-' . uniqid();
+	$plugin = $base . '/plugins/maint';
+
+	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    = maint_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/maint';
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_maint_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() . '/maint-prune-missing-' . uniqid();
+	mkdir($base . '/plugins/maint', 0777, true);
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_maint_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() . '/maint-prune-bad-' . uniqid();
+	$plugin = $base . '/plugins/maint';
+	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_maint_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    = maint_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/maint';
+	$outside = $base . '/plugins/escapee.txt';
+	file_put_contents($outside, 'precious user data');
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_maint_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   = maint_prune_fixture($manifest);
+	$plugin = $base . '/plugins/maint';
+	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_maint_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 5ba0890..7d7bc17 100644
--- a/tests/bootstrap-unit.php
+++ b/tests/bootstrap-unit.php
@@ -283,7 +283,8 @@ function __esc($text, $domain = '') {
 
 if (!function_exists('cacti_log')) {
 	function cacti_log($message, $also_print = false, $log_type = '', $level = 0) {
-		$GLOBALS['__test_log'][] = $message;
+		$GLOBALS['__test_log'][]       = $message;
+		$GLOBALS['__test_cacti_log'][] = (string) $message;
 	}
 }
 

From f5381eac8ba030bcde8db0476e461358c4836c7d Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Wed, 30 Sep 2026 16:37:05 -0400
Subject: [PATCH 12/18] fix: add root functions.php shim to manifest 'expected'
 to fix drift check

---
 manifest.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/manifest.json b/manifest.json
index 9953f29..fa5941f 100644
--- a/manifest.json
+++ b/manifest.json
@@ -6,6 +6,7 @@
         "INFO",
         "LICENSE",
         "README.md",
+        "functions.php",
         "includes/",
         "index.php",
         "locales/",

From f009aeff96c4d510aa2cf3cf2cc2a6c0128c8e88 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Wed, 30 Sep 2026 16:48:38 -0400
Subject: [PATCH 13/18] revert: drop root functions.php shim; core now prefers
 includes/functions.php

Core PR Cacti/cacti#8123 updates lib/snmpagent.php to load the maint
library from includes/functions.php (with a legacy root fallback), so the
back-compat shim added in 31fd2f3 is no longer needed once that lands.
---
 functions.php | 40 ----------------------------------------
 manifest.json |  1 -
 2 files changed, 41 deletions(-)
 delete mode 100644 functions.php

diff --git a/functions.php b/functions.php
deleted file mode 100644
index b55802e..0000000
--- a/functions.php
+++ /dev/null
@@ -1,40 +0,0 @@
-<?php
-
-declare(strict_types = 1);
-
-/*
- ex: set tabstop=4 shiftwidth=4 autoindent:
- +-------------------------------------------------------------------------+
- | 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/                                                   |
- +-------------------------------------------------------------------------+
-*/
-
-/**
- * Back-compat shim.
- *
- * Cacti core's lib/snmpagent.php (snmpagent_poller_bottom) hard-codes
- * include_once('plugins/maint/functions.php') to load
- * plugin_maint_check_cacti_host() during the poller run. The plugin's
- * functions were relocated to includes/functions.php, so this root file
- * remains only to satisfy that fixed core path and forward to the new
- * location. Remove once no supported Cacti release includes this path.
- */
-
-require_once(__DIR__ . '/includes/functions.php');
diff --git a/manifest.json b/manifest.json
index fa5941f..9953f29 100644
--- a/manifest.json
+++ b/manifest.json
@@ -6,7 +6,6 @@
         "INFO",
         "LICENSE",
         "README.md",
-        "functions.php",
         "includes/",
         "index.php",
         "locales/",

From 4bd568d94bc5226e3040c202eff6afebc270703e Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 19:55:23 -0400
Subject: [PATCH 14/18] 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.
---
 manifest.json                   | 1 -
 setup.php                       | 8 +++++---
 tests/Unit/PruneFilesTest.php   | 8 ++++++++
 tests/bin/validate-manifest.php | 8 ++++----
 4 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/manifest.json b/manifest.json
index 9953f29..8fead93 100644
--- a/manifest.json
+++ b/manifest.json
@@ -11,7 +11,6 @@
         "locales/",
         "maint.php",
         "manifest.json",
-        "phpunit.xml",
         "setup.php"
     ],
     "whitelist": []
diff --git a/setup.php b/setup.php
index 69cef2a..1136657 100644
--- a/setup.php
+++ b/setup.php
@@ -608,7 +608,7 @@ function plugin_maint_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;
 		}
 
@@ -627,9 +627,11 @@ function plugin_maint_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, '/');
@@ -681,7 +683,7 @@ function plugin_maint_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 11559f0..ec6bcaf 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -27,6 +27,9 @@ function maint_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 maint_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 maint_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 maint_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 3de589bfc72b0de7e6bbb80f0b5f5364c6baec5e Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 22:15:13 -0400
Subject: [PATCH 15/18] 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 1136657..43e1499 100644
--- a/setup.php
+++ b/setup.php
@@ -615,7 +615,9 @@ function plugin_maint_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;
 			}
 		}
@@ -640,6 +642,16 @@ function plugin_maint_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: maint prune refused to remove %s: path contains a traversal segment (tampered manifest.json?)', $rel), false, 'MAINT');
+
+			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 ec6bcaf..32f8b83 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -146,7 +146,7 @@ function maint_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 maint_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    = maint_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/maint';
+	$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_maint_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    = maint_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/maint';
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_maint_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 86125699de026fea430e4a39e5446180b509dc1b Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 22:32:59 -0400
Subject: [PATCH 16/18] 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 | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 5b55a35..ef3cb7d 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -25,14 +25,14 @@ When generating code for this repository:
 
 ```
 maint/                # Repository root (install to plugins/maint/ in Cacti)
-├── includes/            # Library/helper files, require_once'd from the entry points
-│   ├── database.php       # Schema management: table defs + create/upgrade helpers
-│   └── functions.php      # Runtime maintenance checks (plugin_maint_check_* -> plugin_maint_check_schedule)
-├── locales/                 # Internationalization files
-├── maint.php                  # Main UI/controller: CRUD schedules, tabbed views, host associations
-├── INFO                         # Plugin metadata (name, version, compat)
+├── includes/         # Library/helper files, require_once'd from the entry points
+│   ├── database.php  # Schema management: table defs + create/upgrade helpers
+│   └── functions.php # Runtime maintenance checks (plugin_maint_check_* -> plugin_maint_check_schedule)
+├── locales/          # Internationalization files
+├── maint.php         # Main UI/controller: CRUD schedules, tabbed views, host associations
+├── INFO              # Plugin metadata (name, version, compat)
 ├── README.md
-└── setup.php                      # Plugin entry points and hooks (menu, realms, device actions, maintenance hook)
+└── setup.php         # Plugin entry points and hooks (menu, realms, device actions, maintenance hook)
 ```
 
 ## Naming Conventions

From 407f9331701b54c275290cec6a213b340f63009f Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 23:00:40 -0400
Subject: [PATCH 17/18] 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   | 18 ++++++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index ef3cb7d..2846ff6 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -175,4 +175,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_maint_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_maint_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 32f8b83..1268879 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -1,7 +1,25 @@
 <?php
 /*
+ ex: set tabstop=4 shiftwidth=4 autoindent:
  +-------------------------------------------------------------------------+
  | 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 cd0781e631fe819ea123fdfca6c506b744c9d522 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 23:18:35 -0400
Subject: [PATCH 18/18] 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/MaintCheckUpgradeTest.php |  2 +-
 tests/Unit/PruneFilesTest.php        | 16 ++++++++--------
 4 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 2846ff6..72f4d92 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -175,4 +175,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_maint_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, `maint_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 43e1499..7a68035 100644
--- a/setup.php
+++ b/setup.php
@@ -189,7 +189,7 @@ function plugin_maint_check_upgrade(): void {
 				[$info['version'], $info['longname'], $info['author'], $info['homepage'], 'maint']);
 
 			// Remove files tombstoned in manifest.json plus the dev-only tests/ tree.
-			plugin_maint_prune_files();
+			maint_prune_files();
 		}
 	}
 }
@@ -585,7 +585,7 @@ function maint_device_action_execute(string $action): bool {
  * @global array $config Cacti global configuration array; used to resolve
  *                       the plugin directory.
  */
-function plugin_maint_prune_files(): void {
+function maint_prune_files(): void {
 	global $config;
 
 	$plugin_dir    = $config['base_path'] . '/plugins/maint';
@@ -671,7 +671,7 @@ function plugin_maint_prune_files(): void {
 		}
 
 		if (is_dir($path) && !is_link($path)) {
-			$removed = plugin_maint_rmtree($path);
+			$removed = maint_rmtree($path);
 		} else {
 			$removed = @unlink($path);
 		}
@@ -705,14 +705,14 @@ function plugin_maint_prune_files(): void {
 
 /**
  * Recursively deletes a directory and its contents. Symlinks are removed
- * without being followed. Helper for plugin_maint_prune_files().
+ * without being followed. Helper for maint_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_maint_rmtree(string $dir): bool {
+function maint_rmtree(string $dir): bool {
 	$entries = scandir($dir);
 	$ok      = true;
 
@@ -724,7 +724,7 @@ function plugin_maint_rmtree(string $dir): bool {
 		$path = $dir . '/' . $entry;
 
 		if (is_dir($path) && !is_link($path)) {
-			if (!plugin_maint_rmtree($path)) {
+			if (!maint_rmtree($path)) {
 				$ok = false;
 			}
 		} elseif (!@unlink($path)) {
diff --git a/tests/Unit/MaintCheckUpgradeTest.php b/tests/Unit/MaintCheckUpgradeTest.php
index 5e4994b..17ccc11 100644
--- a/tests/Unit/MaintCheckUpgradeTest.php
+++ b/tests/Unit/MaintCheckUpgradeTest.php
@@ -21,7 +21,7 @@
 
 beforeEach(function () {
 	// Sandbox base_path (complete temp INFO + empty includes/database.php stub)
-	// so every upgrade-path test runs plugin_maint_prune_files() against a
+	// so every upgrade-path test runs maint_prune_files() against a
 	// throwaway tree, never the real checkout. Tests needing a different INFO
 	// override base_path themselves.
 	$GLOBALS['__maint_base_restore'] = $GLOBALS['config']['base_path'];
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
index 1268879..97f6566 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -24,7 +24,7 @@
 */
 
 /*
- * Unit coverage for plugin_maint_prune_files(): tombstone/tests removal,
+ * Unit coverage for maint_prune_files(): tombstone/tests removal,
  * whitelist and .git protection, and logging of unaccounted-for entries.
  */
 
@@ -73,7 +73,7 @@ function maint_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_maint_prune_files();
+		maint_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -112,7 +112,7 @@ function maint_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_maint_prune_files();
+		maint_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -131,7 +131,7 @@ function maint_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_maint_prune_files();
+		maint_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -157,7 +157,7 @@ function maint_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_maint_prune_files();
+		maint_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -186,7 +186,7 @@ function maint_prune_fixture(array $manifest): string {
 	set_error_handler(static fn () => true); // swallow the expected unlink warning
 
 	try {
-		plugin_maint_prune_files();
+		maint_prune_files();
 	} finally {
 		restore_error_handler();
 		$GLOBALS['config']['base_path'] = $restore;
@@ -216,7 +216,7 @@ function maint_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_maint_prune_files();
+		maint_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -246,7 +246,7 @@ function maint_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_maint_prune_files();
+		maint_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}