From 90fc94e4b92ee39bc7c59c7075fb11553fdbeb3e Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 17:50:53 -0400
Subject: [PATCH 01/15] Manage schema via api_plugin_db_table_create() +
 db_update_table()

Replace the raw CREATE TABLE install and the version-gated ALTER TABLE upgrade migrations for graph_exports/graph_exports_tasks with the plugin schema API: a single *_table_data() definition per table, api_plugin_db_table_create() on install, and db_update_table() (else create) on upgrade. The one historical column rename is kept as a guarded pre-step since db_update_table() can not rename. Tests and copilot-instructions updated to the new pattern.
---
 .github/copilot-instructions.md               |  26 +-
 CHANGELOG.md                                  |   1 +
 setup.php                                     | 243 +++++++++---------
 tests/Integration/GexportInstallHooksTest.php |  10 +-
 tests/Unit/GexportSetupTableTest.php          |  25 +-
 tests/bootstrap-unit.php                      |   8 +
 6 files changed, 166 insertions(+), 147 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 23d9f84..fbb7460 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -164,7 +164,7 @@ Document all changes in `CHANGELOG.md`; use descriptive commit messages referenc
 
 - Translatable strings are managed with GNU gettext via `locales/build_gettext.sh`. `locales/po/cacti.pot` is the source template; Weblate owns syncing the per-language `.po`/`.mo` files from it.
 - **Never commit the per-language `.po` or compiled `.mo` files** (`locales/po/*.po`, `locales/LC_MESSAGES/*.mo`) in a plugin PR. Weblate is the sole owner of those catalogs, and regenerating them here produces spurious diffs and merge conflicts. `locales/po/cacti.pot` is the ONLY translation artifact a PR may add or modify.
-- When a pull request adds or changes a string wrapped in `__()`/`__n()`/`__esc()`/`__x()`/`__xn()`/`__gettext()`, run `locales/build_gettext.sh` before pushing and stage `locales/po/cacti.pot` only. `build_gettext.sh` also rewrites the `.po`/`.mo` files as a side effect; revert those before committing (`git checkout -- locales/po/*.po locales/LC_MESSAGES`), or run only the `xgettext` step that targets `cacti.pot`.
+- When a pull request adds or changes a string wrapped in `__()`/`__n()`/`__esc()`/`__x()`/`__xn()`/`__gettext()`, run `locales/build_gettext.sh` before pushing and stage `locales/po/cacti.pot` only. `build_gettext.sh` also rewrites the `.po`/`.mo` files as a side effect; revert those before committing (`git checkout -- locales/po/*.po locales/LC_MESSAGES`), or run only the `xgettext` step that targets `cacti.pot`.
 
 ## References
 
@@ -189,10 +189,26 @@ 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.
-- **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
-  from both the install AND upgrade paths.
+- **Plugin schema management.** Own every plugin-created table through Cacti core's schema API in
+  `lib/plugins.php`; never use raw `CREATE TABLE`/`ALTER TABLE` for a plugin-owned table.
+  - Define each table once in a `*_table_data()` helper that returns the Cacti table-definition
+    array (`columns`/`primary`/`keys`/`type`/`comment`). Both the install and upgrade paths consume
+    that single definition so they can never drift.
+  - **Install:** create every table with
+    `api_plugin_db_table_create('<plugin>', '<table>', <table>_table_data())`.
+  - **Upgrade:** refresh each table from the same definition — `db_update_table('<table>', <table>_table_data())`
+    when the table already exists (it diffs the live schema and issues the exact combined `ALTER`),
+    otherwise `api_plugin_db_table_create()` to create it. Do **not** hand-write
+    `db_column_exists()`/`db_index_exists()` guards around `ALTER TABLE`. The one exception is a true
+    column **rename**, which `db_update_table()` cannot express: keep a guarded
+    `ALTER TABLE ... CHANGE COLUMN` as a pre-step immediately before the refresh.
+  - Avoid `api_plugin_db_add_column()`, `api_plugin_db_add_index()`, and `api_plugin_db_drop_*()` for
+    this plugin's own tables — the create + `db_update_table()` pair already covers new columns,
+    indexes, and type changes. Those helpers are only appropriate when modifying a **non-plugin**
+    Cacti core table (for example adding a column to `host`).
+- **Plugin upgrade bookkeeping.** When the stored version differs from the INFO version, update the
+  whole `plugin_config` record, not just `version`:
+  `db_execute_prepared('UPDATE plugin_config SET version = ?, name = ?, author = ?, webpage = ? WHERE directory = ?', [$info['version'], $info['longname'], $info['author'], $info['homepage'], $info['name']])`.
 - **PHPDoc shape.** Every function gets a PHPDoc block: a one-line description, a blank comment
   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
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e351c68..f84135c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 --- 2.1 ---
 
+- refactor: Manage the graph_exports/graph_exports_tasks schema through Cacti's plugin table API - create with api_plugin_db_table_create() and refresh existing tables with db_update_table() from a single shared definition, replacing the raw CREATE TABLE/version-gated ALTER TABLE migrations (the one column rename is kept as a pre-step since db_update_table() can not rename)
 - dev: Enforce patch coverage of changed lines in CI and remove the inert COMPOSER_ROOT_VERSION env from the Pest step
 - security: Add a version-safe CSP nonce (`plugin_gexport_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 d248364..47f2e04 100644
--- a/setup.php
+++ b/setup.php
@@ -179,67 +179,33 @@ function gexport_check_upgrade() {
 			api_plugin_enable_hooks('gexport');
 		}
 
-		if (cacti_version_compare($old,'1.4.1', '<')) {
-			if (db_column_exists('graph_exports','export_index_key_path')) {
-				db_execute('ALTER TABLE graph_exports
-					CHANGE COLUMN `export_index_key_path` `export_private_key_path` varchar(255)');
-			}
+		// db_update_table() diffs by column name and can not rename, so preserve
+		// this historical rename (and its data) before the schema refresh below.
+		if (db_column_exists('graph_exports', 'export_index_key_path')) {
+			db_execute('ALTER TABLE graph_exports
+				CHANGE COLUMN `export_index_key_path` `export_private_key_path` varchar(255)');
 		}
 
-		if (cacti_version_compare($old,'1.4','<')) {
-			gexport_create_table_tasks();
-
-			if (!db_column_exists('graph_exports','export_threads')) {
-				db_execute('ALTER TABLE graph_exports
-					ADD COLUMN `export_threads` int(10) DEFAULT \'0\'');
-			}
-
-			if (!db_column_exists('graph_exports','export_args')) {
-				db_execute('ALTER TABLE graph_exports
-					ADD COLUMN `export_args` char(25) DEFAULT \'-zav\'');
-			}
-
-			if (!db_column_exists('graph_exports','export_clear')) {
-				db_execute('ALTER TABLE graph_exports
-					ADD COLUMN `export_clear` char(3) DEFAULT \'\'');
-			}
-
-			if (!db_column_exists('graph_exports','export_thumbs')) {
-				db_execute('ALTER TABLE graph_exports
-					ADD COLUMN `export_thumbs` char(3) DEFAULT \'on\'');
-			}
-
-			if (!db_index_exists('graph_exports_tasks','status')) {
-				db_execute('ALTER TABLE graph_exports_tasks
-					ADD KEY `status` (`status`)');
-			}
-
-			if (!db_index_exists('graph_exports_tasks','pid')) {
-				db_execute('ALTER TABLE graph_exports_tasks
-					ADD KEY `pid` (`pid`)');
-			}
-
-			if (!db_index_exists('graph_exports_tasks','start_time')) {
-				db_execute('ALTER TABLE graph_exports_tasks
-					ADD KEY `start_time` (`start_time`)');
+		// Refresh each table to its current definition: db_update_table() diffs the
+		// live schema and issues the exact ALTER (columns, indexes, engine) needed;
+		// create it outright when it does not exist yet.
+		$tables = [
+			'graph_exports'       => gexport_graph_exports_table_data(),
+			'graph_exports_tasks' => gexport_graph_exports_tasks_table_data(),
+		];
+
+		foreach ($tables as $table => $data) {
+			if (db_table_exists($table)) {
+				db_update_table($table, $data);
+			} else {
+				api_plugin_db_table_create('gexport', $table, $data);
 			}
 		}
 
-		if (cacti_version_compare($old,'1.3','<')) {
-			db_execute('ALTER TABLE graph_exports
-				MODIFY column export_user VARCHAR(40) DEFAULT \'\'');
-		}
-
-		db_execute("UPDATE plugin_config
-			SET version='$current'
-			WHERE directory='gexport'");
-
-		db_execute("UPDATE plugin_config SET
-			version='" . $info['version'] . "',
-			name='" . $info['longname'] . "',
-			author='" . $info['author'] . "',
-			webpage='" . $info['homepage'] . "'
-			WHERE directory='" . $info['name'] . "' ");
+		db_execute_prepared('UPDATE plugin_config
+			SET version = ?, name = ?, author = ?, webpage = ?
+			WHERE directory = ?',
+			[$info['version'], $info['longname'], $info['author'], $info['homepage'], $info['name']]);
 	}
 }
 
@@ -280,94 +246,117 @@ function gexport_setup_table() {
 	return true;
 }
 
+/**
+ * The graph_exports table definition (each configured export job's
+ * settings and last-run status), 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 source.
+ *
+ * @return array<string, mixed> The table definition array.
+ */
+function gexport_graph_exports_table_data(): array {
+	$data               = [];
+	$data['columns'][]  = ['name' => 'id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'auto_increment' => true];
+	$data['columns'][]  = ['name' => 'name', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_type', 'type' => 'varchar(12)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'enabled', 'type' => 'char(3)', 'NULL' => true, 'default' => 'on'];
+	$data['columns'][]  = ['name' => 'export_presentation', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_effective_user', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_expand_hosts', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_theme', 'type' => 'varchar(20)', 'NULL' => true, 'default' => 'modern'];
+	$data['columns'][]  = ['name' => 'graph_tree', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'graph_site', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'graph_height', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '100'];
+	$data['columns'][]  = ['name' => 'graph_width', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '300'];
+	$data['columns'][]  = ['name' => 'graph_thumbnails', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'graph_columns', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '2'];
+	$data['columns'][]  = ['name' => 'graph_perpage', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '50'];
+	$data['columns'][]  = ['name' => 'graph_max', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '2000'];
+	$data['columns'][]  = ['name' => 'export_clear', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_thumbs', 'type' => 'char(3)', 'NULL' => true, 'default' => 'on'];
+	$data['columns'][]  = ['name' => 'export_args', 'type' => 'char(25)', 'NULL' => true, 'default' => '-zav'];
+	$data['columns'][]  = ['name' => 'export_directory', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_temp_directory', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_timing', 'type' => 'varchar(20)', 'NULL' => true, 'default' => 'disabled'];
+	$data['columns'][]  = ['name' => 'export_skip', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_hourly', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_daily', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_threads', 'type' => 'int(10)', 'NULL' => true, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_sanitize_remote', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_host', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_port', 'type' => 'varchar(5)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_passive', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_user', 'type' => 'varchar(40)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_password', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_private_key_path', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'status', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_pid', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => null];
+	$data['columns'][]  = ['name' => 'next_start', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_checked', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_started', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_ended', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_errored', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_runtime', 'type' => 'double', 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'last_error', 'type' => 'varchar(255)', 'NULL' => true, 'default' => null];
+	$data['columns'][]  = ['name' => 'total_graphs', 'type' => 'double', 'NULL' => true, 'default' => '0'];
+	$data['primary']    = 'id';
+	$data['type']       = 'InnoDB';
+	$data['comment']    = 'Stores Graph Export Settings for Cacti';
+
+	return $data;
+}
+
 /**
  * Creates the graph_exports table (holding each configured export job's
- * settings and last-run status), if it doesn't already exist. Called
+ * settings and last-run status) via the tracked plugin table API. Called
  * from gexport_setup_table() during installation.
  *
  * @return bool Always returns true.
  */
 function gexport_create_table() {
-	if (!db_table_exists('graph_exports')) {
-		db_execute("CREATE TABLE `graph_exports` (
-			`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
-			`name` varchar(64) DEFAULT '',
-			`export_type` varchar(12) DEFAULT '',
-			`enabled` char(3) DEFAULT 'on',
-			`export_presentation` varchar(20) DEFAULT '',
-			`export_effective_user` int(10) unsigned DEFAULT '0',
-			`export_expand_hosts` char(3) DEFAULT '',
-			`export_theme` varchar(20) DEFAULT 'modern',
-			`graph_tree` varchar(255) DEFAULT '',
-			`graph_site` varchar(255) DEFAULT '',
-			`graph_height` int(10) unsigned DEFAULT '100',
-			`graph_width` int(10) unsigned DEFAULT '300',
-			`graph_thumbnails` char(3) DEFAULT '',
-			`graph_columns` int(10) unsigned DEFAULT '2',
-			`graph_perpage` int(10) unsigned DEFAULT '50',
-			`graph_max` int(10) unsigned DEFAULT '2000',
-			`export_clear` char(3) DEFAULT '',
-			`export_thumbs` char(3) DEFAULT 'on',
-			`export_args` char(25) DEFAULT '-zav',
-			`export_directory` varchar(255) DEFAULT '',
-			`export_temp_directory` varchar(255) DEFAULT '',
-			`export_timing` varchar(20) DEFAULT 'disabled',
-			`export_skip` int(10) unsigned DEFAULT '0',
-			`export_hourly` varchar(20) DEFAULT '',
-			`export_daily` varchar(20) DEFAULT '',
-			`export_threads` int(10) DEFAULT '0',
-			`export_sanitize_remote` char(3) DEFAULT '',
-			`export_host` varchar(64) DEFAULT '',
-			`export_port` varchar(5) DEFAULT '',
-			`export_passive` char(3) DEFAULT '',
-			`export_user` varchar(40) DEFAULT '',
-			`export_password` varchar(64) DEFAULT '',
-			`export_private_key_path` varchar(255) DEFAULT '',
-			`status` int(10) unsigned DEFAULT '0',
-			`export_pid` int(10) unsigned DEFAULT NULL,
-			`next_start` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
-			`last_checked` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
-			`last_started` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
-			`last_ended` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
-			`last_errored` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
-			`last_runtime` double NOT NULL DEFAULT '0',
-			`last_error` varchar(255) DEFAULT NULL,
-			`total_graphs` double DEFAULT '0',
-			PRIMARY KEY (`id`))
-			ENGINE=InnoDB
-			COMMENT='Stores Graph Export Settings for Cacti'");
-	}
+	api_plugin_db_table_create('gexport', 'graph_exports', gexport_graph_exports_table_data());
 
 	return true;
 }
 
+/**
+ * The graph_exports_tasks table definition (per-graph worker tasks for an
+ * in-progress export job), 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 source.
+ *
+ * @return array<string, mixed> The table definition array.
+ */
+function gexport_graph_exports_tasks_table_data(): array {
+	$data               = [];
+	$data['columns'][]  = ['name' => 'id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'auto_increment' => true];
+	$data['columns'][]  = ['name' => 'local_graph_id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'pid', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'user', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'folder', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'status', 'type' => 'int(1)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'start_time', 'type' => 'int(1)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['primary']    = 'id';
+	$data['keys'][]     = ['name' => 'status', 'columns' => ['status']];
+	$data['keys'][]     = ['name' => 'pid', 'columns' => ['pid']];
+	$data['keys'][]     = ['name' => 'start_time', 'columns' => ['start_time']];
+	$data['type']       = 'InnoDB';
+	$data['comment']    = 'Stores Graph Export Tasks for Cacti';
+
+	return $data;
+}
+
 /**
  * Creates the graph_exports_tasks table (holding per-graph worker tasks
- * for an in-progress export job), if it doesn't already exist. Called
- * from gexport_setup_table() during installation and
- * gexport_check_upgrade() when upgrading from a version that predates
- * this table.
+ * for an in-progress export job) via the tracked plugin table API. Called
+ * from gexport_setup_table() during installation and gexport_check_upgrade()
+ * when upgrading from a version that predates this table.
  *
  * @return bool Always returns true.
  */
 function gexport_create_table_tasks() {
-	if (!db_table_exists('graph_exports_tasks')) {
-		db_execute("CREATE TABLE `graph_exports_tasks` (
-			`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
-			`local_graph_id` int(10) unsigned NOT NULL DEFAULT '0',
-			`export_id` int(10) unsigned NOT NULL DEFAULT '0',
-			`pid` int(10) unsigned NOT NULL DEFAULT '0',
-			`user` int(10) unsigned NOT NULL DEFAULT '0',
-			`folder` varchar(255) DEFAULT '',
-			`status` int(1) unsigned NOT NULL DEFAULT '0',
-			`start_time` int(1) unsigned NOT NULL DEFAULT '0',
-			PRIMARY KEY (`id`),
-			KEY `status` (`status`),
-			KEY `pid` (`pid`),
-			KEY `start_time` (`start_time`))
-			ENGINE=InnoDB
-			COMMENT='Stores Graph Export Tasks for Cacti'");
-	}
+	api_plugin_db_table_create('gexport', 'graph_exports_tasks', gexport_graph_exports_tasks_table_data());
 
 	return true;
 }
diff --git a/tests/Integration/GexportInstallHooksTest.php b/tests/Integration/GexportInstallHooksTest.php
index 34b91ee..aad97b0 100644
--- a/tests/Integration/GexportInstallHooksTest.php
+++ b/tests/Integration/GexportInstallHooksTest.php
@@ -53,7 +53,13 @@
 	expect($GLOBALS['__test_registered_realms'])->toHaveCount(1);
 	expect($GLOBALS['__test_registered_realms'][0]['file'])->toBe('gexport.php');
 
-	$sql = implode("\n", array_column($GLOBALS['__test_db_calls'], 'sql'));
+	$tables = array_column(
+		array_filter($GLOBALS['__test_db_calls'], function ($call) {
+			return $call['fn'] === 'api_plugin_db_table_create';
+		}),
+		'table'
+	);
 
-	expect($sql)->toContain('graph_exports');
+	expect($tables)->toContain('graph_exports')
+		->and($tables)->toContain('graph_exports_tasks');
 });
diff --git a/tests/Unit/GexportSetupTableTest.php b/tests/Unit/GexportSetupTableTest.php
index a63f2e9..9d1a2a9 100644
--- a/tests/Unit/GexportSetupTableTest.php
+++ b/tests/Unit/GexportSetupTableTest.php
@@ -33,28 +33,27 @@
 	$GLOBALS['__test_db_calls'] = array();
 });
 
-it('creates both tables when neither exists', function () {
-	gexport_test_mock_db('db_table_exists', 'graph_exports_tasks', false);
-	gexport_test_mock_db('db_table_exists', 'graph_exports', false);
-
+it('creates both tables via the tracked plugin table API', function () {
 	expect(gexport_setup_table())->toBeTrue();
 
-	$sql = implode("\n", array_column($GLOBALS['__test_db_calls'], 'sql'));
+	$tables = array_column(
+		array_filter($GLOBALS['__test_db_calls'], function ($call) {
+			return $call['fn'] === 'api_plugin_db_table_create';
+		}),
+		'table'
+	);
 
-	expect($sql)->toContain('CREATE TABLE `graph_exports`');
-	expect($sql)->toContain('CREATE TABLE `graph_exports_tasks`');
+	expect($tables)->toContain('graph_exports')
+		->and($tables)->toContain('graph_exports_tasks');
 });
 
-it('does not recreate a table that already exists', function () {
-	gexport_test_mock_db('db_table_exists', 'graph_exports_tasks', true);
-	gexport_test_mock_db('db_table_exists', 'graph_exports', true);
-
+it('never emits a raw CREATE TABLE statement', function () {
 	gexport_create_table();
 	gexport_create_table_tasks();
 
-	$creates = array_filter($GLOBALS['__test_db_calls'], function ($call) {
+	$raw = array_filter($GLOBALS['__test_db_calls'], function ($call) {
 		return $call['fn'] === 'db_execute' && stripos($call['sql'], 'CREATE TABLE') !== false;
 	});
 
-	expect($creates)->toBeEmpty();
+	expect($raw)->toBeEmpty();
 });
diff --git a/tests/bootstrap-unit.php b/tests/bootstrap-unit.php
index 59daa48..9e0c132 100644
--- a/tests/bootstrap-unit.php
+++ b/tests/bootstrap-unit.php
@@ -188,6 +188,13 @@ function db_table_exists($table) {
 	}
 }
 
+if (!function_exists('db_update_table')) {
+	function db_update_table($table, $data, $removecolumns = false, $log = true, $db_conn = false) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'db_update_table', 'table' => $table, 'data' => $data);
+		return true;
+	}
+}
+
 if (!function_exists('api_plugin_db_add_column')) {
 	function api_plugin_db_add_column($plugin, $table, $data) {
 		return true;
@@ -196,6 +203,7 @@ function api_plugin_db_add_column($plugin, $table, $data) {
 
 if (!function_exists('api_plugin_db_table_create')) {
 	function api_plugin_db_table_create($plugin, $table, $data) {
+		$GLOBALS['__test_db_calls'][] = array('fn' => 'api_plugin_db_table_create', 'plugin' => $plugin, 'table' => $table, 'data' => $data);
 		return true;
 	}
 }

From 743db057e0bce6006fe9bb64ba374d755e418f2b Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 17:52:25 -0400
Subject: [PATCH 02/15] Use array primary keys so db_update_table() PK diff
 does not fatal on existing tables

---
 setup.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/setup.php b/setup.php
index 47f2e04..136ec13 100644
--- a/setup.php
+++ b/setup.php
@@ -299,7 +299,7 @@ function gexport_graph_exports_table_data(): array {
 	$data['columns'][]  = ['name' => 'last_runtime', 'type' => 'double', 'NULL' => false, 'default' => '0'];
 	$data['columns'][]  = ['name' => 'last_error', 'type' => 'varchar(255)', 'NULL' => true, 'default' => null];
 	$data['columns'][]  = ['name' => 'total_graphs', 'type' => 'double', 'NULL' => true, 'default' => '0'];
-	$data['primary']    = 'id';
+	$data['primary']    = ['id'];
 	$data['type']       = 'InnoDB';
 	$data['comment']    = 'Stores Graph Export Settings for Cacti';
 
@@ -337,7 +337,7 @@ function gexport_graph_exports_tasks_table_data(): array {
 	$data['columns'][]  = ['name' => 'folder', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
 	$data['columns'][]  = ['name' => 'status', 'type' => 'int(1)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
 	$data['columns'][]  = ['name' => 'start_time', 'type' => 'int(1)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
-	$data['primary']    = 'id';
+	$data['primary']    = ['id'];
 	$data['keys'][]     = ['name' => 'status', 'columns' => ['status']];
 	$data['keys'][]     = ['name' => 'pid', 'columns' => ['pid']];
 	$data['keys'][]     = ['name' => 'start_time', 'columns' => ['start_time']];

From 1c5e2b5a27aa0b8d31cc882b0ffe83fd044f6a62 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 18:14:30 -0400
Subject: [PATCH 03/15] Move schema functions into includes/database.php (thold
 model)

All table definitions and the create/upgrade/drop helpers now live in includes/database.php (with the Cacti copyright header); setup.php's install/uninstall/upgrade paths include it and delegate. Behavior is unchanged - api_plugin_db_table_create() on install, db_update_table()-else-create refresh on upgrade.
---
 .github/copilot-instructions.md      |   4 +-
 CHANGELOG.md                         |   2 +-
 includes/database.php                | 212 +++++++++++++++++++++++++++
 setup.php                            | 179 ++--------------------
 tests/Unit/GexportSetupTableTest.php |   1 +
 5 files changed, 231 insertions(+), 167 deletions(-)
 create mode 100644 includes/database.php

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index fbb7460..18e84b9 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -190,7 +190,9 @@ existing code or adding new code, not just in dedicated cleanup passes:
   final argument, except when deliberately comparing against a literal, untranslated Cacti-core
   label.
 - **Plugin schema management.** Own every plugin-created table through Cacti core's schema API in
-  `lib/plugins.php`; never use raw `CREATE TABLE`/`ALTER TABLE` for a plugin-owned table.
+  `lib/plugins.php`; never use raw `CREATE TABLE`/`ALTER TABLE` for a plugin-owned table. Keep all of
+  these schema functions in the plugin's `includes/database.php`, included from `setup.php`'s
+  install/upgrade paths (the thold model).
   - Define each table once in a `*_table_data()` helper that returns the Cacti table-definition
     array (`columns`/`primary`/`keys`/`type`/`comment`). Both the install and upgrade paths consume
     that single definition so they can never drift.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f84135c..7ebba37 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 --- 2.1 ---
 
-- refactor: Manage the graph_exports/graph_exports_tasks schema through Cacti's plugin table API - create with api_plugin_db_table_create() and refresh existing tables with db_update_table() from a single shared definition, replacing the raw CREATE TABLE/version-gated ALTER TABLE migrations (the one column rename is kept as a pre-step since db_update_table() can not rename)
+- refactor: Move all schema management into includes/database.php (the thold model) and manage the graph_exports/graph_exports_tasks schema through Cacti's plugin table API - create with api_plugin_db_table_create() and refresh existing tables with db_update_table() from a single shared definition, replacing the raw CREATE TABLE/version-gated ALTER TABLE migrations (the one column rename is kept as a pre-step since db_update_table() can not rename)
 - dev: Enforce patch coverage of changed lines in CI and remove the inert COMPOSER_ROOT_VERSION env from the Pest step
 - security: Add a version-safe CSP nonce (`plugin_gexport_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..aa36c74
--- /dev/null
+++ b/includes/database.php
@@ -0,0 +1,212 @@
+<?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 graph_exports table definition (each configured export job's
+ * settings and last-run status), 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 source.
+ *
+ * @return array<string, mixed> The table definition array.
+ */
+function gexport_graph_exports_table_data(): array {
+	$data               = [];
+	$data['columns'][]  = ['name' => 'id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'auto_increment' => true];
+	$data['columns'][]  = ['name' => 'name', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_type', 'type' => 'varchar(12)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'enabled', 'type' => 'char(3)', 'NULL' => true, 'default' => 'on'];
+	$data['columns'][]  = ['name' => 'export_presentation', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_effective_user', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_expand_hosts', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_theme', 'type' => 'varchar(20)', 'NULL' => true, 'default' => 'modern'];
+	$data['columns'][]  = ['name' => 'graph_tree', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'graph_site', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'graph_height', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '100'];
+	$data['columns'][]  = ['name' => 'graph_width', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '300'];
+	$data['columns'][]  = ['name' => 'graph_thumbnails', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'graph_columns', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '2'];
+	$data['columns'][]  = ['name' => 'graph_perpage', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '50'];
+	$data['columns'][]  = ['name' => 'graph_max', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '2000'];
+	$data['columns'][]  = ['name' => 'export_clear', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_thumbs', 'type' => 'char(3)', 'NULL' => true, 'default' => 'on'];
+	$data['columns'][]  = ['name' => 'export_args', 'type' => 'char(25)', 'NULL' => true, 'default' => '-zav'];
+	$data['columns'][]  = ['name' => 'export_directory', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_temp_directory', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_timing', 'type' => 'varchar(20)', 'NULL' => true, 'default' => 'disabled'];
+	$data['columns'][]  = ['name' => 'export_skip', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_hourly', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_daily', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_threads', 'type' => 'int(10)', 'NULL' => true, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_sanitize_remote', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_host', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_port', 'type' => 'varchar(5)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_passive', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_user', 'type' => 'varchar(40)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_password', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'export_private_key_path', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'status', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_pid', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => null];
+	$data['columns'][]  = ['name' => 'next_start', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_checked', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_started', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_ended', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_errored', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
+	$data['columns'][]  = ['name' => 'last_runtime', 'type' => 'double', 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'last_error', 'type' => 'varchar(255)', 'NULL' => true, 'default' => null];
+	$data['columns'][]  = ['name' => 'total_graphs', 'type' => 'double', 'NULL' => true, 'default' => '0'];
+	$data['primary']    = ['id'];
+	$data['type']       = 'InnoDB';
+	$data['comment']    = 'Stores Graph Export Settings for Cacti';
+
+	return $data;
+}
+
+/**
+ * The graph_exports_tasks table definition (per-graph worker tasks for an
+ * in-progress export job), 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 source.
+ *
+ * @return array<string, mixed> The table definition array.
+ */
+function gexport_graph_exports_tasks_table_data(): array {
+	$data               = [];
+	$data['columns'][]  = ['name' => 'id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'auto_increment' => true];
+	$data['columns'][]  = ['name' => 'local_graph_id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'export_id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'pid', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'user', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'folder', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
+	$data['columns'][]  = ['name' => 'status', 'type' => 'int(1)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['columns'][]  = ['name' => 'start_time', 'type' => 'int(1)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
+	$data['primary']    = ['id'];
+	$data['keys'][]     = ['name' => 'status', 'columns' => ['status']];
+	$data['keys'][]     = ['name' => 'pid', 'columns' => ['pid']];
+	$data['keys'][]     = ['name' => 'start_time', 'columns' => ['start_time']];
+	$data['type']       = 'InnoDB';
+	$data['comment']    = 'Stores Graph Export Tasks for Cacti';
+
+	return $data;
+}
+
+/**
+ * Creates every table this plugin owns via the tracked plugin table API
+ * (idempotent, so it is safe to call on both install and upgrade). Called
+ * from plugin_gexport_install() during installation.
+ *
+ * @return bool Always returns true.
+ *
+ * @global array  $config           Cacti global configuration array; used
+ *                                 to load database.php.
+ * @global object $database_default Reserved/declared for parity with other
+ *                                 database-touching functions; not used
+ *                                 directly here.
+ */
+function gexport_setup_table() {
+	global $config, $database_default;
+	include_once($config['library_path'] . '/database.php');
+
+	gexport_create_table();
+	gexport_create_table_tasks();
+
+	return true;
+}
+
+/**
+ * Creates the graph_exports table (holding each configured export job's
+ * settings and last-run status) via the tracked plugin table API. Called
+ * from gexport_setup_table() during installation.
+ *
+ * @return bool Always returns true.
+ */
+function gexport_create_table() {
+	api_plugin_db_table_create('gexport', 'graph_exports', gexport_graph_exports_table_data());
+
+	return true;
+}
+
+/**
+ * Creates the graph_exports_tasks table (holding per-graph worker tasks
+ * for an in-progress export job) via the tracked plugin table API. Called
+ * from gexport_setup_table() during installation.
+ *
+ * @return bool Always returns true.
+ */
+function gexport_create_table_tasks() {
+	api_plugin_db_table_create('gexport', 'graph_exports_tasks', gexport_graph_exports_tasks_table_data());
+
+	return true;
+}
+
+/**
+ * Refreshes this plugin's tables to their current definition on upgrade:
+ * db_update_table() diffs the live schema against the definition and issues
+ * the exact ALTER (columns, indexes, engine) when the table already exists,
+ * otherwise the table is created outright. A true column rename (which
+ * db_update_table() can not express) is applied as a guarded pre-step first.
+ * Called from gexport_check_upgrade() when the stored version changes.
+ *
+ * @return void
+ *
+ * @global array  $config           Cacti global configuration array; used
+ *                                 to load database.php.
+ * @global object $database_default Reserved/declared for parity with other
+ *                                 database-touching functions; not used
+ *                                 directly here.
+ */
+function gexport_upgrade_tables() {
+	global $config, $database_default;
+	include_once($config['library_path'] . '/database.php');
+
+	// db_update_table() diffs by column name and can not rename, so preserve
+	// this historical rename (and its data) before the schema refresh below.
+	if (db_column_exists('graph_exports', 'export_index_key_path')) {
+		db_execute('ALTER TABLE graph_exports
+			CHANGE COLUMN `export_index_key_path` `export_private_key_path` varchar(255)');
+	}
+
+	$tables = [
+		'graph_exports'       => gexport_graph_exports_table_data(),
+		'graph_exports_tasks' => gexport_graph_exports_tasks_table_data(),
+	];
+
+	foreach ($tables as $table => $data) {
+		if (db_table_exists($table)) {
+			db_update_table($table, $data);
+		} else {
+			api_plugin_db_table_create('gexport', $table, $data);
+		}
+	}
+}
+
+/**
+ * Drops every table this plugin owns. Called from plugin_gexport_uninstall()
+ * when an administrator uninstalls the plugin.
+ *
+ * @return void
+ */
+function gexport_drop_tables() {
+	db_execute('DROP TABLE IF EXISTS graph_exports');
+	db_execute('DROP TABLE IF EXISTS graph_exports_tasks');
+}
diff --git a/setup.php b/setup.php
index 136ec13..587f047 100644
--- a/setup.php
+++ b/setup.php
@@ -48,6 +48,8 @@ function plugin_gexport_csp_nonce(): string {
  * @return void
  */
 function plugin_gexport_install() {
+	global $config;
+
 	// graph setup all arrays needed for automation
 	api_plugin_register_hook('gexport', 'config_arrays',        'gexport_config_arrays',        'setup.php');
 	api_plugin_register_hook('gexport', 'draw_navigation_text', 'gexport_draw_navigation_text', 'setup.php');
@@ -55,6 +57,8 @@ function plugin_gexport_install() {
 
 	api_plugin_register_realm('gexport', 'gexport.php', __('Export Cacti Graphs Settings', 'gexport'), 1);
 
+	include_once($config['base_path'] . '/plugins/gexport/includes/database.php');
+
 	gexport_setup_table();
 }
 
@@ -67,8 +71,11 @@ function plugin_gexport_install() {
  * @return bool Always returns true.
  */
 function plugin_gexport_uninstall() {
-	db_execute('DROP TABLE graph_exports');
-	db_execute('DROP TABLE graph_exports_tasks');
+	global $config;
+
+	include_once($config['base_path'] . '/plugins/gexport/includes/database.php');
+
+	gexport_drop_tables();
 
 	return true;
 }
@@ -154,6 +161,7 @@ function gexport_check_upgrade() {
 
 	include_once($config['library_path'] . '/database.php');
 	include_once($config['library_path'] . '/functions.php');
+	include_once($config['base_path'] . '/plugins/gexport/includes/database.php');
 
 	// Let's only run this check if we are on a page that actually needs the data
 	$files = ['plugins.php', 'gexport.php'];
@@ -179,28 +187,10 @@ function gexport_check_upgrade() {
 			api_plugin_enable_hooks('gexport');
 		}
 
-		// db_update_table() diffs by column name and can not rename, so preserve
-		// this historical rename (and its data) before the schema refresh below.
-		if (db_column_exists('graph_exports', 'export_index_key_path')) {
-			db_execute('ALTER TABLE graph_exports
-				CHANGE COLUMN `export_index_key_path` `export_private_key_path` varchar(255)');
-		}
-
-		// Refresh each table to its current definition: db_update_table() diffs the
-		// live schema and issues the exact ALTER (columns, indexes, engine) needed;
-		// create it outright when it does not exist yet.
-		$tables = [
-			'graph_exports'       => gexport_graph_exports_table_data(),
-			'graph_exports_tasks' => gexport_graph_exports_tasks_table_data(),
-		];
-
-		foreach ($tables as $table => $data) {
-			if (db_table_exists($table)) {
-				db_update_table($table, $data);
-			} else {
-				api_plugin_db_table_create('gexport', $table, $data);
-			}
-		}
+		// db_update_table() diffs the live schema against each table definition
+		// and issues the exact ALTER (or creates the table when missing); the one
+		// column rename is applied as a guarded pre-step inside this helper.
+		gexport_upgrade_tables();
 
 		db_execute_prepared('UPDATE plugin_config
 			SET version = ?, name = ?, author = ?, webpage = ?
@@ -220,147 +210,6 @@ function gexport_check_dependencies() {
 	return true;
 }
 
-/**
- * Creates this plugin's graph_exports (export configuration) and
- * graph_exports_tasks (per-export worker task) database tables, if they
- * don't already exist. Called from plugin_gexport_install() during
- * plugin installation.
- *
- * @return bool Always returns true.
- *
- * @global array  $config           Cacti global configuration array;
- *                                   used to load database.php.
- * @global object $database_default Cacti's default database connection
- *                                   handle (unused directly here;
- *                                   declared for parity with other
- *                                   database-touching functions in this
- *                                   file).
- */
-function gexport_setup_table() {
-	global $config, $database_default;
-	include_once($config['library_path'] . '/database.php');
-
-	gexport_create_table();
-	gexport_create_table_tasks();
-
-	return true;
-}
-
-/**
- * The graph_exports table definition (each configured export job's
- * settings and last-run status), 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 source.
- *
- * @return array<string, mixed> The table definition array.
- */
-function gexport_graph_exports_table_data(): array {
-	$data               = [];
-	$data['columns'][]  = ['name' => 'id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'auto_increment' => true];
-	$data['columns'][]  = ['name' => 'name', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_type', 'type' => 'varchar(12)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'enabled', 'type' => 'char(3)', 'NULL' => true, 'default' => 'on'];
-	$data['columns'][]  = ['name' => 'export_presentation', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_effective_user', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'export_expand_hosts', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_theme', 'type' => 'varchar(20)', 'NULL' => true, 'default' => 'modern'];
-	$data['columns'][]  = ['name' => 'graph_tree', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'graph_site', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'graph_height', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '100'];
-	$data['columns'][]  = ['name' => 'graph_width', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '300'];
-	$data['columns'][]  = ['name' => 'graph_thumbnails', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'graph_columns', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '2'];
-	$data['columns'][]  = ['name' => 'graph_perpage', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '50'];
-	$data['columns'][]  = ['name' => 'graph_max', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '2000'];
-	$data['columns'][]  = ['name' => 'export_clear', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_thumbs', 'type' => 'char(3)', 'NULL' => true, 'default' => 'on'];
-	$data['columns'][]  = ['name' => 'export_args', 'type' => 'char(25)', 'NULL' => true, 'default' => '-zav'];
-	$data['columns'][]  = ['name' => 'export_directory', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_temp_directory', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_timing', 'type' => 'varchar(20)', 'NULL' => true, 'default' => 'disabled'];
-	$data['columns'][]  = ['name' => 'export_skip', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'export_hourly', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_daily', 'type' => 'varchar(20)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_threads', 'type' => 'int(10)', 'NULL' => true, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'export_sanitize_remote', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_host', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_port', 'type' => 'varchar(5)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_passive', 'type' => 'char(3)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_user', 'type' => 'varchar(40)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_password', 'type' => 'varchar(64)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'export_private_key_path', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'status', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'export_pid', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => true, 'default' => null];
-	$data['columns'][]  = ['name' => 'next_start', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
-	$data['columns'][]  = ['name' => 'last_checked', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
-	$data['columns'][]  = ['name' => 'last_started', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
-	$data['columns'][]  = ['name' => 'last_ended', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
-	$data['columns'][]  = ['name' => 'last_errored', 'type' => 'timestamp', 'NULL' => false, 'default' => '0000-00-00 00:00:00'];
-	$data['columns'][]  = ['name' => 'last_runtime', 'type' => 'double', 'NULL' => false, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'last_error', 'type' => 'varchar(255)', 'NULL' => true, 'default' => null];
-	$data['columns'][]  = ['name' => 'total_graphs', 'type' => 'double', 'NULL' => true, 'default' => '0'];
-	$data['primary']    = ['id'];
-	$data['type']       = 'InnoDB';
-	$data['comment']    = 'Stores Graph Export Settings for Cacti';
-
-	return $data;
-}
-
-/**
- * Creates the graph_exports table (holding each configured export job's
- * settings and last-run status) via the tracked plugin table API. Called
- * from gexport_setup_table() during installation.
- *
- * @return bool Always returns true.
- */
-function gexport_create_table() {
-	api_plugin_db_table_create('gexport', 'graph_exports', gexport_graph_exports_table_data());
-
-	return true;
-}
-
-/**
- * The graph_exports_tasks table definition (per-graph worker tasks for an
- * in-progress export job), 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 source.
- *
- * @return array<string, mixed> The table definition array.
- */
-function gexport_graph_exports_tasks_table_data(): array {
-	$data               = [];
-	$data['columns'][]  = ['name' => 'id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'auto_increment' => true];
-	$data['columns'][]  = ['name' => 'local_graph_id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'export_id', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'pid', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'user', 'type' => 'int(10)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'folder', 'type' => 'varchar(255)', 'NULL' => true, 'default' => ''];
-	$data['columns'][]  = ['name' => 'status', 'type' => 'int(1)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
-	$data['columns'][]  = ['name' => 'start_time', 'type' => 'int(1)', 'unsigned' => true, 'NULL' => false, 'default' => '0'];
-	$data['primary']    = ['id'];
-	$data['keys'][]     = ['name' => 'status', 'columns' => ['status']];
-	$data['keys'][]     = ['name' => 'pid', 'columns' => ['pid']];
-	$data['keys'][]     = ['name' => 'start_time', 'columns' => ['start_time']];
-	$data['type']       = 'InnoDB';
-	$data['comment']    = 'Stores Graph Export Tasks for Cacti';
-
-	return $data;
-}
-
-/**
- * Creates the graph_exports_tasks table (holding per-graph worker tasks
- * for an in-progress export job) via the tracked plugin table API. Called
- * from gexport_setup_table() during installation and gexport_check_upgrade()
- * when upgrading from a version that predates this table.
- *
- * @return bool Always returns true.
- */
-function gexport_create_table_tasks() {
-	api_plugin_db_table_create('gexport', 'graph_exports_tasks', gexport_graph_exports_tasks_table_data());
-
-	return true;
-}
-
 /**
  * Hook implementation for Cacti's 'config_arrays' filter. Triggers this
  * plugin's database upgrade check, discovers available Cacti themes,
diff --git a/tests/Unit/GexportSetupTableTest.php b/tests/Unit/GexportSetupTableTest.php
index 9d1a2a9..3062e77 100644
--- a/tests/Unit/GexportSetupTableTest.php
+++ b/tests/Unit/GexportSetupTableTest.php
@@ -16,6 +16,7 @@
 
 beforeAll(function () {
 	require_once __DIR__ . '/../../setup.php';
+	require_once __DIR__ . '/../../includes/database.php';
 
 	$stubLibraryPath = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'gexport-test-lib-stub';
 

From 6b1021eee83e0fbc7a48534d3f5b235fd894a02c Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Tue, 29 Sep 2026 18:39:23 -0400
Subject: [PATCH 04/15] Use require/require_once and move library files into
 includes/

Switches every file inclusion from include/include_once to require/require_once for fail-fast consistency, and relocates the functions.php and gexport_security.php library files into includes/ (updating all references across setup.php, gexport.php, poller_export.php, and the tests). export_graph_monitor_tasks() now resolves poller_export.php via __DIR__/../ since functions.php moved down a directory.
---
 .github/copilot-instructions.md               | 24 ++++++++++++-------
 CHANGELOG.md                                  |  1 +
 gexport.php                                   |  8 +++----
 includes/database.php                         |  4 ++--
 functions.php => includes/functions.php       |  2 +-
 .../gexport_security.php                      |  0
 poller_export.php                             | 14 +++++------
 setup.php                                     | 10 ++++----
 .../BulkActionOutputSecurityTest.php          |  2 +-
 tests/Integration/GexportInstallHooksTest.php |  2 +-
 tests/Unit/ExportMessageMappingTest.php       |  2 +-
 tests/Unit/GexportCalcNextStartTest.php       |  2 +-
 tests/Unit/GexportLifecycleTest.php           |  2 +-
 tests/Unit/GexportSecurityHelpersTest.php     |  2 +-
 tests/Unit/GexportSetupTableTest.php          |  2 +-
 15 files changed, 43 insertions(+), 34 deletions(-)
 rename functions.php => includes/functions.php (99%)
 rename gexport_security.php => includes/gexport_security.php (100%)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 18e84b9..c81c4cf 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -26,14 +26,17 @@ When generating code for this repository:
 
 ```
 gexport/               # Repository root (install to plugins/gexport/ in Cacti)
-├── locales/             # Internationalization files
-├── functions.php          # Export engine: run_export(), exporter(), rsync/scp helpers
-├── gexport.php              # Main export definition administration UI
-├── poller_export.php         # Background export runner (CLI, spawned from poller_bottom)
-├── website.template            # HTML template used for exported site view
-├── INFO                          # Plugin metadata (name, version, compat)
+├── includes/            # Library/helper files, require_once'd from the entry points
+│   ├── database.php       # Schema management: *_table_data() + create/upgrade/drop helpers
+│   ├── functions.php        # Export engine: run_export(), exporter(), rsync/scp helpers
+│   └── gexport_security.php   # Bulk-action normalization and output-escaping helpers
+├── locales/                     # Internationalization files
+├── gexport.php                    # Main export definition administration UI
+├── poller_export.php                # Background export runner (CLI, spawned from poller_bottom)
+├── website.template                   # HTML template used for exported site view
+├── INFO                                 # Plugin metadata (name, version, compat)
 ├── README.md
-└── setup.php                      # Plugin install/uninstall/upgrade hooks
+└── setup.php                              # Plugin install/uninstall/upgrade hooks
 ```
 
 ## Naming Conventions
@@ -131,7 +134,7 @@ api_plugin_register_realm('gexport', 'gexport.php', __('Export Cacti Graphs Sett
 `gexport_poller_bottom()` only fires on `poller_id == 1` and only spawns `poller_export.php` in the background if at least one `graph_exports` row is `enabled='on'`; keep new export-triggering logic behind the same guard to avoid running exports on every poller cycle needlessly.
 
 ### Export Engine Conventions
-Logging inside the export engine uses a family of small helpers — `export_fatal()`, `export_warn()`, `export_note()`, `export_log()`, `export_debug()` — keep using the matching severity helper rather than calling `cacti_log()` directly from within `functions.php`.
+Logging inside the export engine uses a family of small helpers ΓÇö `export_fatal()`, `export_warn()`, `export_note()`, `export_log()`, `export_debug()` ΓÇö keep using the matching severity helper rather than calling `cacti_log()` directly from within `includes/functions.php`.
 
 ## Best Practices
 
@@ -189,6 +192,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`, `gexport_security.php`, `includes/database.php`) under `includes/` and
+  reference them from that path; entry points (`gexport.php`, `poller_export.php`, `setup.php`) stay
+  in the plugin root.
 - **Plugin schema management.** Own every plugin-created table through Cacti core's schema API in
   `lib/plugins.php`; never use raw `CREATE TABLE`/`ALTER TABLE` for a plugin-owned table. Keep all of
   these schema functions in the plugin's `includes/database.php`, included from `setup.php`'s
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7ebba37..b7a2f7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 --- 2.1 ---
 
+- refactor: Move the functions.php and gexport_security.php library files into includes/ and switch every file inclusion from include/include_once to require/require_once for fail-fast consistency (references updated across setup.php, gexport.php, poller_export.php, and the test suite)
 - refactor: Move all schema management into includes/database.php (the thold model) and manage the graph_exports/graph_exports_tasks schema through Cacti's plugin table API - create with api_plugin_db_table_create() and refresh existing tables with db_update_table() from a single shared definition, replacing the raw CREATE TABLE/version-gated ALTER TABLE migrations (the one column rename is kept as a pre-step since db_update_table() can not rename)
 - dev: Enforce patch coverage of changed lines in CI and remove the inert COMPOSER_ROOT_VERSION env from the Pest step
 - security: Add a version-safe CSP nonce (`plugin_gexport_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/gexport.php b/gexport.php
index cb40630..30596f9 100644
--- a/gexport.php
+++ b/gexport.php
@@ -23,9 +23,9 @@
 */
 
 chdir('../../');
-include('./include/auth.php');
-include_once('./plugins/gexport/functions.php');
-include_once('./plugins/gexport/gexport_security.php');
+require('./include/auth.php');
+require_once('./plugins/gexport/includes/functions.php');
+require_once('./plugins/gexport/includes/gexport_security.php');
 
 $export_actions = [
 	'1' => __('Delete', 'gexport'),
@@ -415,7 +415,7 @@ function export_disable($export_id) {
 function export_runnow($export_id) {
 	global $config;
 
-	include_once('./lib/poller.php');
+	require_once('./lib/poller.php');
 
 	$status = db_fetch_row_prepared('SELECT status, enabled FROM graph_exports WHERE id = ?', [$export_id]);
 	$status = is_array($status) ? $status : [];
diff --git a/includes/database.php b/includes/database.php
index aa36c74..f6f1735 100644
--- a/includes/database.php
+++ b/includes/database.php
@@ -125,7 +125,7 @@ function gexport_graph_exports_tasks_table_data(): array {
  */
 function gexport_setup_table() {
 	global $config, $database_default;
-	include_once($config['library_path'] . '/database.php');
+	require_once($config['library_path'] . '/database.php');
 
 	gexport_create_table();
 	gexport_create_table_tasks();
@@ -177,7 +177,7 @@ function gexport_create_table_tasks() {
  */
 function gexport_upgrade_tables() {
 	global $config, $database_default;
-	include_once($config['library_path'] . '/database.php');
+	require_once($config['library_path'] . '/database.php');
 
 	// db_update_table() diffs by column name and can not rename, so preserve
 	// this historical rename (and its data) before the schema refresh below.
diff --git a/functions.php b/includes/functions.php
similarity index 99%
rename from functions.php
rename to includes/functions.php
index ef983d4..87a6fc1 100644
--- a/functions.php
+++ b/includes/functions.php
@@ -1182,7 +1182,7 @@ function export_graph_monitor_tasks($export) {
 	global $debug;
 
 	$max_threads = $export['export_threads'];
-	$script_file = __DIR__ . '/poller_export.php';
+	$script_file = __DIR__ . '/../poller_export.php';
 	$script_php  = read_config_option('path_php_binary');
 
 	$spawn_time = new DateTime();
diff --git a/gexport_security.php b/includes/gexport_security.php
similarity index 100%
rename from gexport_security.php
rename to includes/gexport_security.php
diff --git a/poller_export.php b/poller_export.php
index 93eac34..3cabee2 100644
--- a/poller_export.php
+++ b/poller_export.php
@@ -31,16 +31,16 @@
 	chdir('../../');
 }
 
-include('./include/cli_check.php');
-include_once($config['base_path'] . '/lib/poller.php');
-include_once($config['base_path'] . '/lib/data_query.php');
-include_once($config['base_path'] . '/plugins/gexport/functions.php');
-include_once($config['base_path'] . '/lib/rrd.php');
+require('./include/cli_check.php');
+require_once($config['base_path'] . '/lib/poller.php');
+require_once($config['base_path'] . '/lib/data_query.php');
+require_once($config['base_path'] . '/plugins/gexport/includes/functions.php');
+require_once($config['base_path'] . '/lib/rrd.php');
 
 /* poller_export.php runs outside the web UI and does not load setup.php, which
  * defines the CSP nonce helper used by functions.php; ensure it is available. */
 if (!function_exists('plugin_gexport_csp_nonce')) {
-	include_once($config['base_path'] . '/plugins/gexport/setup.php');
+	require_once($config['base_path'] . '/plugins/gexport/setup.php');
 }
 
 /* Let PHP Run Just as Long as It Has To */
@@ -125,7 +125,7 @@ function display_version() {
 	global $config;
 
 	if (!function_exists('plugin_gexport_version')) {
-		include_once($config['base_path'] . '/plugins/gexport/setup.php');
+		require_once($config['base_path'] . '/plugins/gexport/setup.php');
 	}
 
 	$info = plugin_gexport_version();
diff --git a/setup.php b/setup.php
index 587f047..52fa006 100644
--- a/setup.php
+++ b/setup.php
@@ -57,7 +57,7 @@ function plugin_gexport_install() {
 
 	api_plugin_register_realm('gexport', 'gexport.php', __('Export Cacti Graphs Settings', 'gexport'), 1);
 
-	include_once($config['base_path'] . '/plugins/gexport/includes/database.php');
+	require_once($config['base_path'] . '/plugins/gexport/includes/database.php');
 
 	gexport_setup_table();
 }
@@ -73,7 +73,7 @@ function plugin_gexport_install() {
 function plugin_gexport_uninstall() {
 	global $config;
 
-	include_once($config['base_path'] . '/plugins/gexport/includes/database.php');
+	require_once($config['base_path'] . '/plugins/gexport/includes/database.php');
 
 	gexport_drop_tables();
 
@@ -159,9 +159,9 @@ function gexport_poller_bottom() {
 function gexport_check_upgrade() {
 	global $config, $database_default;
 
-	include_once($config['library_path'] . '/database.php');
-	include_once($config['library_path'] . '/functions.php');
-	include_once($config['base_path'] . '/plugins/gexport/includes/database.php');
+	require_once($config['library_path'] . '/database.php');
+	require_once($config['library_path'] . '/functions.php');
+	require_once($config['base_path'] . '/plugins/gexport/includes/database.php');
 
 	// Let's only run this check if we are on a page that actually needs the data
 	$files = ['plugins.php', 'gexport.php'];
diff --git a/tests/Integration/BulkActionOutputSecurityTest.php b/tests/Integration/BulkActionOutputSecurityTest.php
index d041e7a..7d5ed39 100644
--- a/tests/Integration/BulkActionOutputSecurityTest.php
+++ b/tests/Integration/BulkActionOutputSecurityTest.php
@@ -21,7 +21,7 @@
 }
 
 it('includes the gexport_security helper file', function () use ($contents) {
-	expect($contents)->toContain("include_once('./plugins/gexport/gexport_security.php');");
+	expect($contents)->toContain("require_once('./plugins/gexport/includes/gexport_security.php');");
 });
 
 it('normalizes the bulk action from the request before use', function () use ($contents) {
diff --git a/tests/Integration/GexportInstallHooksTest.php b/tests/Integration/GexportInstallHooksTest.php
index aad97b0..e1efffb 100644
--- a/tests/Integration/GexportInstallHooksTest.php
+++ b/tests/Integration/GexportInstallHooksTest.php
@@ -10,7 +10,7 @@
  * and the realm the plugin depends on at runtime are actually registered,
  * together with the tables it needs, in a single end-to-end pass.
  *
- * gexport_setup_table() include_once()s Cacti core's database.php via
+ * gexport_setup_table() require_once()s Cacti core's database.php via
  * $config['library_path'], so that is pointed at a throwaway empty stub
  * file for the duration of this test.
  */
diff --git a/tests/Unit/ExportMessageMappingTest.php b/tests/Unit/ExportMessageMappingTest.php
index cad853d..18d902c 100644
--- a/tests/Unit/ExportMessageMappingTest.php
+++ b/tests/Unit/ExportMessageMappingTest.php
@@ -13,7 +13,7 @@
  */
 
 beforeAll(function () {
-	require_once __DIR__ . '/../../functions.php';
+	require_once __DIR__ . '/../../includes/functions.php';
 });
 
 it('maps rsync success', function () {
diff --git a/tests/Unit/GexportCalcNextStartTest.php b/tests/Unit/GexportCalcNextStartTest.php
index c630482..7aeef70 100644
--- a/tests/Unit/GexportCalcNextStartTest.php
+++ b/tests/Unit/GexportCalcNextStartTest.php
@@ -12,7 +12,7 @@
  */
 
 beforeAll(function () {
-	require_once __DIR__ . '/../../functions.php';
+	require_once __DIR__ . '/../../includes/functions.php';
 });
 
 beforeEach(function () {
diff --git a/tests/Unit/GexportLifecycleTest.php b/tests/Unit/GexportLifecycleTest.php
index 7b9501d..8329b38 100644
--- a/tests/Unit/GexportLifecycleTest.php
+++ b/tests/Unit/GexportLifecycleTest.php
@@ -11,7 +11,7 @@
  * gexport_check_dependencies(), and gexport_check_upgrade()'s page-guard,
  * already-current, and version-drift branches.
  *
- * gexport_check_upgrade() include_once()s Cacti core's database.php/
+ * gexport_check_upgrade() require_once()s Cacti core's database.php/
  * functions.php via $config['library_path'], so that is pointed at
  * throwaway empty stub files for the duration of these tests.
  */
diff --git a/tests/Unit/GexportSecurityHelpersTest.php b/tests/Unit/GexportSecurityHelpersTest.php
index fe2428f..2ae1459 100644
--- a/tests/Unit/GexportSecurityHelpersTest.php
+++ b/tests/Unit/GexportSecurityHelpersTest.php
@@ -13,7 +13,7 @@
  */
 
 beforeAll(function () {
-	require_once __DIR__ . '/../../gexport_security.php';
+	require_once __DIR__ . '/../../includes/gexport_security.php';
 });
 
 it('normalizes a valid low bound bulk action', function () {
diff --git a/tests/Unit/GexportSetupTableTest.php b/tests/Unit/GexportSetupTableTest.php
index 3062e77..249b87a 100644
--- a/tests/Unit/GexportSetupTableTest.php
+++ b/tests/Unit/GexportSetupTableTest.php
@@ -9,7 +9,7 @@
  * Unit coverage for gexport_setup_table(), gexport_create_table(), and
  * gexport_create_table_tasks() in setup.php.
  *
- * gexport_setup_table() include_once()s Cacti core's database.php via
+ * gexport_setup_table() require_once()s Cacti core's database.php via
  * $config['library_path'], so that is pointed at a throwaway empty stub
  * file for the duration of these tests.
  */

From 9b56f5e21e63f1385ac656e0834cd11e63ef9774 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Tue, 29 Sep 2026 21:21:50 -0400
Subject: [PATCH 05/15] Regenerate cacti.pot after moving library files into
 includes/

The gettext location comments (--add-location=file) and entry ordering in
locales/po/cacti.pot are derived from the sorted list of scanned PHP files.
Moving functions.php and gexport_security.php into includes/ reordered those
references, so regenerate the template to match. No translatable strings were
added or removed (msgid set is unchanged); only source-location comments and
ordering differ.
---
 locales/po/cacti.pot | 402 +++++++++++++++++++++----------------------
 1 file changed, 201 insertions(+), 201 deletions(-)

diff --git a/locales/po/cacti.pot b/locales/po/cacti.pot
index c620c4f..17975e4 100644
--- a/locales/po/cacti.pot
+++ b/locales/po/cacti.pot
@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Cacti \n"
 "Report-Msgid-Bugs-To: developers@cacti.net\n"
-"POT-Creation-Date: 2026-09-28 16:05-0400\n"
+"POT-Creation-Date: 2026-09-29 21:21-0400\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: Cacti Developers <developers@cacti.net>>\n"
 "Language-Team: Cacti Developers <developers@cacti.net>\n"
@@ -18,206 +18,6 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"
 
-#: functions.php
-msgid "Success"
-msgstr ""
-
-#: functions.php
-msgid "Syntax or usage error"
-msgstr ""
-
-#: functions.php
-msgid "Protocol incompatibility"
-msgstr ""
-
-#: functions.php
-msgid "Errors selecting input/output files, dirs"
-msgstr ""
-
-#: functions.php
-msgid "Requested action not supported: an attempt was made to manipulate 64-bit files on a platform that cannot support them; or an option was specified that is supported by the client and not by the server."
-msgstr ""
-
-#: functions.php
-msgid "Error starting client-server protocol"
-msgstr ""
-
-#: functions.php
-msgid "Daemon unable to append to log-file"
-msgstr ""
-
-#: functions.php
-msgid "Error in socket I/O"
-msgstr ""
-
-#: functions.php
-msgid "Error in file I/O"
-msgstr ""
-
-#: functions.php
-msgid "Error in rsync protocol data stream"
-msgstr ""
-
-#: functions.php
-msgid "Errors with program diagnostics"
-msgstr ""
-
-#: functions.php
-msgid "Error in IPC code"
-msgstr ""
-
-#: functions.php
-msgid "Received SIGUSR1 or SIGINT"
-msgstr ""
-
-#: functions.php
-msgid "Some error returned by waitpid()"
-msgstr ""
-
-#: functions.php
-msgid "Error allocating core memory buffers"
-msgstr ""
-
-#: functions.php
-msgid "Partial transfer due to error"
-msgstr ""
-
-#: functions.php
-msgid "Partial transfer due to vanished source files"
-msgstr ""
-
-#: functions.php
-msgid "The --max-delete limit stopped deletions"
-msgstr ""
-
-#: functions.php
-msgid "Timeout in data send/receive"
-msgstr ""
-
-#: functions.php
-msgid "Timeout waiting for daemon connection"
-msgstr ""
-
-#: functions.php
-msgid "Unknown error "
-msgstr ""
-
-#: functions.php
-msgid "Operation was successful"
-msgstr ""
-
-#: functions.php
-msgid "General error in file copy"
-msgstr ""
-
-#: functions.php
-msgid "Destination is not directory, but it should be"
-msgstr ""
-
-#: functions.php
-msgid "Maximum symlink level exceeded"
-msgstr ""
-
-#: functions.php
-msgid "Connecting to host failed."
-msgstr ""
-
-#: functions.php
-msgid "Connection broken"
-msgstr ""
-
-#: functions.php
-msgid "File does not exist"
-msgstr ""
-
-#: functions.php
-msgid "No permission to access file."
-msgstr ""
-
-#: functions.php
-msgid "General error in sftp protocol"
-msgstr ""
-
-#: functions.php
-msgid "File transfer protocol mismatch"
-msgstr ""
-
-#: functions.php
-msgid "No file matches a given criteria"
-msgstr ""
-
-#: functions.php
-msgid "Host not allowed to connect"
-msgstr ""
-
-#: functions.php
-msgid "General error in ssh protocol"
-msgstr ""
-
-#: functions.php
-msgid "Key exchange failed"
-msgstr ""
-
-#: functions.php
-msgid "Reserved"
-msgstr ""
-
-#: functions.php
-msgid "MAC error"
-msgstr ""
-
-#: functions.php
-msgid "Compression error"
-msgstr ""
-
-#: functions.php
-msgid "Service not available"
-msgstr ""
-
-#: functions.php
-msgid "Protocol version not supported"
-msgstr ""
-
-#: functions.php
-msgid "Host key not verifiable"
-msgstr ""
-
-#: functions.php
-msgid "Connection failed"
-msgstr ""
-
-#: functions.php
-msgid "Disconnected by application"
-msgstr ""
-
-#: functions.php
-msgid "Too many connections"
-msgstr ""
-
-#: functions.php
-msgid "Authentication cancelled by user"
-msgstr ""
-
-#: functions.php
-msgid "No more authentication methods available"
-msgstr ""
-
-#: functions.php
-msgid "Invalid user name"
-msgstr ""
-
-#: functions.php
-msgid "Non Query Based"
-msgstr ""
-
-#: functions.php
-msgid "Graph Templates"
-msgstr ""
-
-#: functions.php
-msgid "Data Queries"
-msgstr ""
-
 #: gexport.php
 msgid "Delete"
 msgstr ""
@@ -536,6 +336,206 @@ msgstr ""
 msgid "No Graph Export Definitions"
 msgstr ""
 
+#: includes/functions.php
+msgid "Success"
+msgstr ""
+
+#: includes/functions.php
+msgid "Syntax or usage error"
+msgstr ""
+
+#: includes/functions.php
+msgid "Protocol incompatibility"
+msgstr ""
+
+#: includes/functions.php
+msgid "Errors selecting input/output files, dirs"
+msgstr ""
+
+#: includes/functions.php
+msgid "Requested action not supported: an attempt was made to manipulate 64-bit files on a platform that cannot support them; or an option was specified that is supported by the client and not by the server."
+msgstr ""
+
+#: includes/functions.php
+msgid "Error starting client-server protocol"
+msgstr ""
+
+#: includes/functions.php
+msgid "Daemon unable to append to log-file"
+msgstr ""
+
+#: includes/functions.php
+msgid "Error in socket I/O"
+msgstr ""
+
+#: includes/functions.php
+msgid "Error in file I/O"
+msgstr ""
+
+#: includes/functions.php
+msgid "Error in rsync protocol data stream"
+msgstr ""
+
+#: includes/functions.php
+msgid "Errors with program diagnostics"
+msgstr ""
+
+#: includes/functions.php
+msgid "Error in IPC code"
+msgstr ""
+
+#: includes/functions.php
+msgid "Received SIGUSR1 or SIGINT"
+msgstr ""
+
+#: includes/functions.php
+msgid "Some error returned by waitpid()"
+msgstr ""
+
+#: includes/functions.php
+msgid "Error allocating core memory buffers"
+msgstr ""
+
+#: includes/functions.php
+msgid "Partial transfer due to error"
+msgstr ""
+
+#: includes/functions.php
+msgid "Partial transfer due to vanished source files"
+msgstr ""
+
+#: includes/functions.php
+msgid "The --max-delete limit stopped deletions"
+msgstr ""
+
+#: includes/functions.php
+msgid "Timeout in data send/receive"
+msgstr ""
+
+#: includes/functions.php
+msgid "Timeout waiting for daemon connection"
+msgstr ""
+
+#: includes/functions.php
+msgid "Unknown error "
+msgstr ""
+
+#: includes/functions.php
+msgid "Operation was successful"
+msgstr ""
+
+#: includes/functions.php
+msgid "General error in file copy"
+msgstr ""
+
+#: includes/functions.php
+msgid "Destination is not directory, but it should be"
+msgstr ""
+
+#: includes/functions.php
+msgid "Maximum symlink level exceeded"
+msgstr ""
+
+#: includes/functions.php
+msgid "Connecting to host failed."
+msgstr ""
+
+#: includes/functions.php
+msgid "Connection broken"
+msgstr ""
+
+#: includes/functions.php
+msgid "File does not exist"
+msgstr ""
+
+#: includes/functions.php
+msgid "No permission to access file."
+msgstr ""
+
+#: includes/functions.php
+msgid "General error in sftp protocol"
+msgstr ""
+
+#: includes/functions.php
+msgid "File transfer protocol mismatch"
+msgstr ""
+
+#: includes/functions.php
+msgid "No file matches a given criteria"
+msgstr ""
+
+#: includes/functions.php
+msgid "Host not allowed to connect"
+msgstr ""
+
+#: includes/functions.php
+msgid "General error in ssh protocol"
+msgstr ""
+
+#: includes/functions.php
+msgid "Key exchange failed"
+msgstr ""
+
+#: includes/functions.php
+msgid "Reserved"
+msgstr ""
+
+#: includes/functions.php
+msgid "MAC error"
+msgstr ""
+
+#: includes/functions.php
+msgid "Compression error"
+msgstr ""
+
+#: includes/functions.php
+msgid "Service not available"
+msgstr ""
+
+#: includes/functions.php
+msgid "Protocol version not supported"
+msgstr ""
+
+#: includes/functions.php
+msgid "Host key not verifiable"
+msgstr ""
+
+#: includes/functions.php
+msgid "Connection failed"
+msgstr ""
+
+#: includes/functions.php
+msgid "Disconnected by application"
+msgstr ""
+
+#: includes/functions.php
+msgid "Too many connections"
+msgstr ""
+
+#: includes/functions.php
+msgid "Authentication cancelled by user"
+msgstr ""
+
+#: includes/functions.php
+msgid "No more authentication methods available"
+msgstr ""
+
+#: includes/functions.php
+msgid "Invalid user name"
+msgstr ""
+
+#: includes/functions.php
+msgid "Non Query Based"
+msgstr ""
+
+#: includes/functions.php
+msgid "Graph Templates"
+msgstr ""
+
+#: includes/functions.php
+msgid "Data Queries"
+msgstr ""
+
 #: setup.php
 msgid "Export Cacti Graphs Settings"
 msgstr ""

From 0452ee82046db45e2062b41539ea9cca910c5515 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Tue, 29 Sep 2026 21:55:14 -0400
Subject: [PATCH 06/15] Fix CI: instrument plugin sources with xdebug and close
 patch-coverage gaps

The Enforce-coverage gate failed because pcov auto-scopes to the Composer
root (cacti/) and skips cacti/plugins/, so no plugin source was instrumented.
The coverage <source> set also still referenced the pre-move functions.php /
gexport_security.php paths and omitted the new includes/database.php.

- Switch the setup-php coverage driver from pcov to xdebug (matches the
  ci/coverage-xdebug rollout) so this plugin's own sources are measured.
- Point the coverage <source> set at includes/functions.php and
  includes/gexport_security.php and add includes/database.php.
- Update the stale GexportLifecycleTest assertion: the upgrade path now writes
  plugin_config via db_execute_prepared (not db_execute), and add a test that
  exercises gexport_upgrade_tables()'s legacy-column rename pre-step and the
  db_update_table() refresh branch (the previously-uncovered changed lines).
  Route the db_column_exists() test stub through the fixture layer so the
  rename branch can be driven.
- Allowlist the entry points gexport.php (web UI) and poller_export.php (CLI),
  which cannot load in the isolated unit process, in tests/bin/patch-coverage.php.
---
 .github/workflows/plugin-ci-workflow.yml |  2 +-
 phpunit.xml                              |  5 +++--
 tests/Unit/GexportLifecycleTest.php      |  4 ++--
 tests/Unit/GexportSetupTableTest.php     | 22 ++++++++++++++++++++++
 tests/bin/patch-coverage.php             |  6 ++++++
 tests/bootstrap-unit.php                 |  2 +-
 6 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/plugin-ci-workflow.yml b/.github/workflows/plugin-ci-workflow.yml
index c49783e..bc7b2a0 100644
--- a/.github/workflows/plugin-ci-workflow.yml
+++ b/.github/workflows/plugin-ci-workflow.yml
@@ -83,7 +83,7 @@ jobs:
       with:
         php-version: ${{ matrix.php }}
         extensions: intl, mysql, gd, ldap, gmp, xml, curl, json, mbstring, snmp
-        coverage: pcov
+        coverage: xdebug
         ini-values: "post_max_size=256M, max_execution_time=60, date.timezone=America/New_York"
 
     - name: Check PHP version
diff --git a/phpunit.xml b/phpunit.xml
index c3bfb78..a9564a1 100644
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -28,8 +28,9 @@
     <source>
         <include>
             <file>setup.php</file>
-            <file>functions.php</file>
-            <file>gexport_security.php</file>
+            <file>includes/database.php</file>
+            <file>includes/functions.php</file>
+            <file>includes/gexport_security.php</file>
         </include>
     </source>
 </phpunit>
diff --git a/tests/Unit/GexportLifecycleTest.php b/tests/Unit/GexportLifecycleTest.php
index 8329b38..7974799 100644
--- a/tests/Unit/GexportLifecycleTest.php
+++ b/tests/Unit/GexportLifecycleTest.php
@@ -83,8 +83,8 @@
 	expect($GLOBALS['__test_enabled_hooks_calls'])->toBe(array('gexport'));
 
 	$updates = array_values(array_filter($GLOBALS['__test_db_calls'], function ($call) {
-		return $call['fn'] === 'db_execute' && stripos($call['sql'], "UPDATE plugin_config") !== false;
+		return $call['fn'] === 'db_execute_prepared' && stripos($call['sql'], 'UPDATE plugin_config') !== false;
 	}));
 
-	expect($updates)->not->toBeEmpty();
+	expect($updates)->toHaveCount(1);
 });
diff --git a/tests/Unit/GexportSetupTableTest.php b/tests/Unit/GexportSetupTableTest.php
index 249b87a..0ffddd7 100644
--- a/tests/Unit/GexportSetupTableTest.php
+++ b/tests/Unit/GexportSetupTableTest.php
@@ -58,3 +58,25 @@
 
 	expect($raw)->toBeEmpty();
 });
+
+it('renames the legacy key-path column and refreshes existing tables on upgrade', function () {
+	// Legacy column still present and both tables already exist, so the guarded
+	// rename pre-step fires and each table is refreshed via db_update_table().
+	gexport_test_mock_db('db_column_exists', 'export_index_key_path', true);
+	gexport_test_mock_db('db_table_exists', 'graph_exports', true);
+
+	gexport_upgrade_tables();
+
+	$alters = array_filter($GLOBALS['__test_db_calls'], function ($call) {
+		return $call['fn'] === 'db_execute' && stripos($call['sql'], 'CHANGE COLUMN') !== false;
+	});
+
+	expect($alters)->not->toBeEmpty();
+
+	$refreshed = array_column(array_filter($GLOBALS['__test_db_calls'], function ($call) {
+		return $call['fn'] === 'db_update_table';
+	}), 'table');
+
+	expect($refreshed)->toContain('graph_exports')
+		->and($refreshed)->toContain('graph_exports_tasks');
+});
diff --git a/tests/bin/patch-coverage.php b/tests/bin/patch-coverage.php
index e65b53d..5d473cb 100644
--- a/tests/bin/patch-coverage.php
+++ b/tests/bin/patch-coverage.php
@@ -160,6 +160,12 @@ function changed_lines($base_ref) {
  * Empty by default; add entries per repository as the need arises.
  */
 $unmeasured_allowlist = [
+	// Web UI / CLI entry points: each does a top-level chdir + require of
+	// include/auth.php or include/cli_check.php and dispatches on request/CLI
+	// args, so it cannot be loaded into the isolated unit process. Only the
+	// extracted helpers (includes/*.php) are unit-tested and measured.
+	'gexport.php',
+	'poller_export.php',
 ];
 $unmeasured            = array_values(array_diff(array_keys($changed), array_keys($measured)));
 $unexpected_unmeasured = array_values(array_diff($unmeasured, $unmeasured_allowlist));
diff --git a/tests/bootstrap-unit.php b/tests/bootstrap-unit.php
index 9e0c132..53096a0 100644
--- a/tests/bootstrap-unit.php
+++ b/tests/bootstrap-unit.php
@@ -178,7 +178,7 @@ function db_index_exists($table, $index) {
 
 if (!function_exists('db_column_exists')) {
 	function db_column_exists($table, $column) {
-		return false;
+		return gexport_test_db_result('db_column_exists', $table . '.' . $column, array(), false);
 	}
 }
 

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

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

diff --git a/INFO b/INFO
index 4bc9e9d..abfe942 100644
--- a/INFO
+++ b/INFO
@@ -26,5 +26,5 @@ longname = Graph Export Package for Cacti
 author = The Cacti Group
 email = 
 homepage = http://www.cacti.net
-compat = 1.2.15
+compat = 1.2.32
 capabilities = online_view:1, online_mgmt:1, offline_view:0, offline_mgmt:0, remote_collect:0

From 6dcb3a8ff0813c7a46058b294b2e90b98fb37b59 Mon Sep 17 00:00:00 2001
From: TheWitness <thewitness@cacti.net>
Date: Tue, 29 Sep 2026 23:30:31 -0400
Subject: [PATCH 08/15] fix: set canonical DEFAULT '' on
 export_private_key_path rename (db_update_table on 1.2.x does not reconcile
 column defaults)

---
 includes/database.php | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/includes/database.php b/includes/database.php
index f6f1735..b352fbd 100644
--- a/includes/database.php
+++ b/includes/database.php
@@ -181,9 +181,11 @@ function gexport_upgrade_tables() {
 
 	// db_update_table() diffs by column name and can not rename, so preserve
 	// this historical rename (and its data) before the schema refresh below.
+	// Cacti 1.2.x's db_update_table() does not reconcile column defaults, so the
+	// rename must set the canonical DEFAULT '' itself to avoid leaving DEFAULT NULL.
 	if (db_column_exists('graph_exports', 'export_index_key_path')) {
-		db_execute('ALTER TABLE graph_exports
-			CHANGE COLUMN `export_index_key_path` `export_private_key_path` varchar(255)');
+		db_execute("ALTER TABLE graph_exports
+			CHANGE COLUMN `export_index_key_path` `export_private_key_path` varchar(255) DEFAULT ''");
 	}
 
 	$tables = [

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

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

diff --git a/INFO b/INFO
index abfe942..54f9795 100644
--- a/INFO
+++ b/INFO
@@ -26,5 +26,5 @@ longname = Graph Export Package for Cacti
 author = The Cacti Group
 email = 
 homepage = http://www.cacti.net
-compat = 1.2.32
+compat = 1.2.29
 capabilities = online_view:1, online_mgmt:1, offline_view:0, offline_mgmt:0, remote_collect:0

From 7be9845423bca720ce15ec5fa3cfc5f3a85e2edb Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 15:21:53 -0400
Subject: [PATCH 10/15] Add manifest.json + upgrade-time file pruning

---
 .github/copilot-instructions.md          |   4 +
 .github/workflows/plugin-ci-workflow.yml |   3 +
 manifest.json                            |  18 +++
 setup.php                                | 159 +++++++++++++++++++++
 tests/Unit/GexportLifecycleTest.php      |  19 +++
 tests/Unit/PruneFilesTest.php            | 173 +++++++++++++++++++++++
 tests/bin/validate-manifest.php          |  73 ++++++++++
 tests/bootstrap-unit.php                 |   2 +
 8 files changed, 451 insertions(+)
 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 c81c4cf..c1805c1 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -223,3 +223,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_gexport_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 bc7b2a0..d5fcdde 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/gexport/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..b70018a
--- /dev/null
+++ b/manifest.json
@@ -0,0 +1,18 @@
+{
+    "tombstones": [],
+    "expected": [
+        "CHANGELOG.md",
+        "INFO",
+        "LICENSE",
+        "README.md",
+        "gexport.php",
+        "includes/",
+        "locales/",
+        "manifest.json",
+        "phpunit.xml",
+        "poller_export.php",
+        "setup.php",
+        "website.template"
+    ],
+    "whitelist": []
+}
diff --git a/setup.php b/setup.php
index 52fa006..3626581 100644
--- a/setup.php
+++ b/setup.php
@@ -196,6 +196,9 @@ function gexport_check_upgrade() {
 			SET version = ?, name = ?, author = ?, webpage = ?
 			WHERE directory = ?',
 			[$info['version'], $info['longname'], $info['author'], $info['homepage'], $info['name']]);
+
+		// Remove files tombstoned in manifest.json plus the dev-only tests/ tree.
+		plugin_gexport_prune_files();
 	}
 }
 
@@ -627,3 +630,159 @@ function gexport_draw_navigation_text($nav) {
 
 	return $nav;
 }
+
+/**
+ * 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_gexport_prune_files(): void {
+	global $config;
+
+	$plugin_dir    = $config['base_path'] . '/plugins/gexport';
+	$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: gexport manifest.json could not be parsed; skipping file prune', false, 'GEXPORT');
+
+		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: gexport prune refused to remove %s: path resolves outside the plugin directory (tampered manifest.json?)', $rel), false, 'GEXPORT');
+
+			continue;
+		}
+
+		if (is_dir($path) && !is_link($path)) {
+			$removed = plugin_gexport_rmtree($path);
+		} else {
+			$removed = @unlink($path);
+		}
+
+		if (!$removed) {
+			cacti_log(sprintf('WARNING: gexport upgrade could not remove %s (check file/directory permissions)', $rel), false, 'GEXPORT');
+		}
+	}
+
+	// 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: gexport upgrade found a file/directory not described in manifest.json: %s (left in place)', $entry), false, 'GEXPORT');
+	}
+}
+
+/**
+ * Recursively deletes a directory and its contents. Symlinks are removed
+ * without being followed. Helper for plugin_gexport_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_gexport_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_gexport_rmtree($path)) {
+				$ok = false;
+			}
+		} elseif (!@unlink($path)) {
+			$ok = false;
+		}
+	}
+
+	if (!@rmdir($dir)) {
+		$ok = false;
+	}
+
+	return $ok;
+}
diff --git a/tests/Unit/GexportLifecycleTest.php b/tests/Unit/GexportLifecycleTest.php
index 7974799..c196da8 100644
--- a/tests/Unit/GexportLifecycleTest.php
+++ b/tests/Unit/GexportLifecycleTest.php
@@ -18,6 +18,9 @@
 
 beforeAll(function () {
 	require_once __DIR__ . '/../../setup.php';
+	// Define gexport_upgrade_tables() from the real checkout so check_upgrade()
+	// can run while base_path is sandboxed for the prune.
+	require_once __DIR__ . '/../../includes/database.php';
 
 	$stubLibraryPath = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'gexport-test-lib-stub';
 
@@ -36,6 +39,22 @@
 	$GLOBALS['__test_db_calls']            = array();
 	$GLOBALS['__test_enabled_hooks_calls'] = array();
 	test_set_current_page('gexport.php');
+
+	// Sandbox base_path (temp INFO + empty includes/database.php stub) so any
+	// upgrade-path test runs plugin_gexport_prune_files() against a throwaway
+	// tree, never the real checkout.
+	$GLOBALS['__gexport_base_restore'] = $GLOBALS['config']['base_path'];
+	$base = sys_get_temp_dir() . '/gexport-test-' . uniqid();
+	mkdir($base . '/plugins/gexport/includes', 0777, true);
+	file_put_contents($base . '/plugins/gexport/INFO', "[info]\nversion = 9.9.9\nname = gexport\nlongname = Graph Export\nauthor = x\nhomepage = x\n");
+	file_put_contents($base . '/plugins/gexport/includes/database.php', "<?php\n");
+	$GLOBALS['config']['base_path'] = $base;
+});
+
+afterEach(function () {
+	if (isset($GLOBALS['__gexport_base_restore'])) {
+		$GLOBALS['config']['base_path'] = $GLOBALS['__gexport_base_restore'];
+	}
 });
 
 it('reports the config as always valid', function () {
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
new file mode 100644
index 0000000..c7a248c
--- /dev/null
+++ b/tests/Unit/PruneFilesTest.php
@@ -0,0 +1,173 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+*/
+
+/*
+ * Unit coverage for plugin_gexport_prune_files(): tombstone/tests removal,
+ * whitelist and .git protection, and logging of unaccounted-for entries.
+ */
+
+require_once __DIR__ . '/../../setup.php';
+
+function gexport_prune_fixture(array $manifest): string {
+	$base   = sys_get_temp_dir() . '/gexport-prune-' . uniqid();
+	$plugin = $base . '/plugins/gexport';
+
+	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    = gexport_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/gexport';
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_gexport_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() . '/gexport-prune-missing-' . uniqid();
+	mkdir($base . '/plugins/gexport', 0777, true);
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_gexport_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() . '/gexport-prune-bad-' . uniqid();
+	$plugin = $base . '/plugins/gexport';
+	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_gexport_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    = gexport_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/gexport';
+	$outside = $base . '/plugins/escapee.txt';
+	file_put_contents($outside, 'precious user data');
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_gexport_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   = gexport_prune_fixture($manifest);
+	$plugin = $base . '/plugins/gexport';
+	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_gexport_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 53096a0..9214edc 100644
--- a/tests/bootstrap-unit.php
+++ b/tests/bootstrap-unit.php
@@ -323,6 +323,8 @@ function __esc($text, $domain = '') {
 
 if (!function_exists('cacti_log')) {
 	function cacti_log($message, $also_print = false, $log_type = '', $level = 0) {
+		$args = func_get_args();
+		$GLOBALS["__test_cacti_log"][] = isset($args[0]) ? (string) $args[0] : "";
 	}
 }
 

From e22b078f0851e414f1ddccb001585fdd2ee2bc52 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 19:48:51 -0400
Subject: [PATCH 11/15] 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 b70018a..eab11e6 100644
--- a/manifest.json
+++ b/manifest.json
@@ -9,7 +9,6 @@
         "includes/",
         "locales/",
         "manifest.json",
-        "phpunit.xml",
         "poller_export.php",
         "setup.php",
         "website.template"
diff --git a/setup.php b/setup.php
index 3626581..258fed5 100644
--- a/setup.php
+++ b/setup.php
@@ -670,7 +670,7 @@ function plugin_gexport_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;
 		}
 
@@ -689,9 +689,11 @@ function plugin_gexport_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, '/');
@@ -743,7 +745,7 @@ function plugin_gexport_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 c7a248c..8782707 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -27,6 +27,9 @@ function gexport_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 gexport_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 gexport_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 gexport_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 d230e0982fc3fa5c888dc572529aace7bc8b399a Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 22:15:32 -0400
Subject: [PATCH 12/15] 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 258fed5..c9ef0f5 100644
--- a/setup.php
+++ b/setup.php
@@ -677,7 +677,9 @@ function plugin_gexport_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;
 			}
 		}
@@ -702,6 +704,16 @@ function plugin_gexport_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: gexport prune refused to remove %s: path contains a traversal segment (tampered manifest.json?)', $rel), false, 'GEXPORT');
+
+			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 8782707..e581a28 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -146,7 +146,7 @@ function gexport_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 gexport_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    = gexport_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/gexport';
+	$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_gexport_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    = gexport_prune_fixture($manifest);
+	$plugin  = $base . '/plugins/gexport';
+	$restore = $GLOBALS['config']['base_path'];
+
+	$GLOBALS['config']['base_path'] = $base;
+
+	try {
+		plugin_gexport_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 1193f3d9406f35b8f8801ba0eca6c43e2b4d96cf Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 22:33:01 -0400
Subject: [PATCH 13/15] 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 | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index c1805c1..5a04e58 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -25,18 +25,18 @@ When generating code for this repository:
 ## Project Structure
 
 ```
-gexport/               # Repository root (install to plugins/gexport/ in Cacti)
-├── includes/            # Library/helper files, require_once'd from the entry points
-│   ├── database.php       # Schema management: *_table_data() + create/upgrade/drop helpers
+gexport/                     # Repository root (install to plugins/gexport/ in Cacti)
+├── includes/                # Library/helper files, require_once'd from the entry points
+│   ├── database.php         # Schema management: *_table_data() + create/upgrade/drop helpers
 │   ├── functions.php        # Export engine: run_export(), exporter(), rsync/scp helpers
-│   └── gexport_security.php   # Bulk-action normalization and output-escaping helpers
-├── locales/                     # Internationalization files
-├── gexport.php                    # Main export definition administration UI
-├── poller_export.php                # Background export runner (CLI, spawned from poller_bottom)
-├── website.template                   # HTML template used for exported site view
-├── INFO                                 # Plugin metadata (name, version, compat)
+│   └── gexport_security.php # Bulk-action normalization and output-escaping helpers
+├── locales/                 # Internationalization files
+├── gexport.php              # Main export definition administration UI
+├── poller_export.php        # Background export runner (CLI, spawned from poller_bottom)
+├── website.template         # HTML template used for exported site view
+├── INFO                     # Plugin metadata (name, version, compat)
 ├── README.md
-└── setup.php                              # Plugin install/uninstall/upgrade hooks
+└── setup.php                # Plugin install/uninstall/upgrade hooks
 ```
 
 ## Naming Conventions

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

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

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 5a04e58..578c910 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -226,4 +226,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_gexport_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_gexport_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 e581a28..4dddc7b 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -2,6 +2,23 @@
 /*
  +-------------------------------------------------------------------------+
  | Copyright (C) 2004-2026 The Cacti Group                                 |
+ |                                                                         |
+ | This program is free software; you can redistribute it and/or           |
+ | modify it under the terms of the GNU General Public License             |
+ | as published by the Free Software Foundation; either version 2          |
+ | of the License, or (at your option) any later version.                  |
+ |                                                                         |
+ | This program is distributed in the hope that it will be useful,         |
+ | but WITHOUT ANY WARRANTY; without even the implied warranty of          |
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           |
+ | GNU General Public License for more details.                            |
+ +-------------------------------------------------------------------------+
+ | Cacti: The Complete RRDTool-based Graphing Solution                     |
+ +-------------------------------------------------------------------------+
+ | This code is designed, written, and maintained by the Cacti Group. See  |
+ | about.php and/or the AUTHORS file for specific developer information.   |
+ +-------------------------------------------------------------------------+
+ | http://www.cacti.net/                                                   |
  +-------------------------------------------------------------------------+
 */
 

From 66a603fdbafed28fa31952f8bee4f356161166f6 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@users.noreply.github.com>
Date: Wed, 30 Sep 2026 23:18:38 -0400
Subject: [PATCH 15/15] 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/GexportLifecycleTest.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 578c910..e5aebde 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -226,4 +226,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_gexport_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, `gexport_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 c9ef0f5..503d6ce 100644
--- a/setup.php
+++ b/setup.php
@@ -198,7 +198,7 @@ function gexport_check_upgrade() {
 			[$info['version'], $info['longname'], $info['author'], $info['homepage'], $info['name']]);
 
 		// Remove files tombstoned in manifest.json plus the dev-only tests/ tree.
-		plugin_gexport_prune_files();
+		gexport_prune_files();
 	}
 }
 
@@ -647,7 +647,7 @@ function gexport_draw_navigation_text($nav) {
  * @global array $config Cacti global configuration array; used to resolve
  *                       the plugin directory.
  */
-function plugin_gexport_prune_files(): void {
+function gexport_prune_files(): void {
 	global $config;
 
 	$plugin_dir    = $config['base_path'] . '/plugins/gexport';
@@ -733,7 +733,7 @@ function plugin_gexport_prune_files(): void {
 		}
 
 		if (is_dir($path) && !is_link($path)) {
-			$removed = plugin_gexport_rmtree($path);
+			$removed = gexport_rmtree($path);
 		} else {
 			$removed = @unlink($path);
 		}
@@ -767,14 +767,14 @@ function plugin_gexport_prune_files(): void {
 
 /**
  * Recursively deletes a directory and its contents. Symlinks are removed
- * without being followed. Helper for plugin_gexport_prune_files().
+ * without being followed. Helper for gexport_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_gexport_rmtree(string $dir): bool {
+function gexport_rmtree(string $dir): bool {
 	$entries = scandir($dir);
 	$ok      = true;
 
@@ -786,7 +786,7 @@ function plugin_gexport_rmtree(string $dir): bool {
 		$path = $dir . '/' . $entry;
 
 		if (is_dir($path) && !is_link($path)) {
-			if (!plugin_gexport_rmtree($path)) {
+			if (!gexport_rmtree($path)) {
 				$ok = false;
 			}
 		} elseif (!@unlink($path)) {
diff --git a/tests/Unit/GexportLifecycleTest.php b/tests/Unit/GexportLifecycleTest.php
index c196da8..18f69eb 100644
--- a/tests/Unit/GexportLifecycleTest.php
+++ b/tests/Unit/GexportLifecycleTest.php
@@ -41,7 +41,7 @@
 	test_set_current_page('gexport.php');
 
 	// Sandbox base_path (temp INFO + empty includes/database.php stub) so any
-	// upgrade-path test runs plugin_gexport_prune_files() against a throwaway
+	// upgrade-path test runs gexport_prune_files() against a throwaway
 	// tree, never the real checkout.
 	$GLOBALS['__gexport_base_restore'] = $GLOBALS['config']['base_path'];
 	$base = sys_get_temp_dir() . '/gexport-test-' . uniqid();
diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php
index 4dddc7b..374f509 100644
--- a/tests/Unit/PruneFilesTest.php
+++ b/tests/Unit/PruneFilesTest.php
@@ -23,7 +23,7 @@
 */
 
 /*
- * Unit coverage for plugin_gexport_prune_files(): tombstone/tests removal,
+ * Unit coverage for gexport_prune_files(): tombstone/tests removal,
  * whitelist and .git protection, and logging of unaccounted-for entries.
  */
 
@@ -72,7 +72,7 @@ function gexport_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_gexport_prune_files();
+		gexport_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -111,7 +111,7 @@ function gexport_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_gexport_prune_files();
+		gexport_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -130,7 +130,7 @@ function gexport_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_gexport_prune_files();
+		gexport_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -156,7 +156,7 @@ function gexport_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_gexport_prune_files();
+		gexport_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -185,7 +185,7 @@ function gexport_prune_fixture(array $manifest): string {
 	set_error_handler(static fn () => true); // swallow the expected unlink warning
 
 	try {
-		plugin_gexport_prune_files();
+		gexport_prune_files();
 	} finally {
 		restore_error_handler();
 		$GLOBALS['config']['base_path'] = $restore;
@@ -215,7 +215,7 @@ function gexport_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_gexport_prune_files();
+		gexport_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}
@@ -245,7 +245,7 @@ function gexport_prune_fixture(array $manifest): string {
 	$GLOBALS['config']['base_path'] = $base;
 
 	try {
-		plugin_gexport_prune_files();
+		gexport_prune_files();
 	} finally {
 		$GLOBALS['config']['base_path'] = $restore;
 	}