wip: gate provider trace behind WP_DEBUG (#1162)

Author: superdav42

includes/Admin/UnifiedAdminMenu.php

@@ -313,6 +313,9 @@ function () {
 				'menuItems'           => self::getMenuItems(),
 				'connectorsUrl'       => self::getConnectorsUrl(),
 				'connectorsAvailable' => self::hasNativeConnectorsPage() || self::hasGutenbergConnectorsPage() ? '1' : '',
+				// Provider trace is a debug-only feature. The JS settings page reads
+				// this flag to show or hide the Provider Trace tab.
+				'wpDebug'             => defined( 'WP_DEBUG' ) && WP_DEBUG ? '1' : '',
 				// Feature flags — mirrors Features::all() so JS can gate UI sections
 				// without waiting for the /settings REST response.
 				'features'            => Features::all(),

includes/Bootstrap/CliHandler.php

@@ -13,6 +13,7 @@
 use GratisAiAgent\CLI\BenchmarkCommand;
 use GratisAiAgent\CLI\CliCommand;
 use GratisAiAgent\CLI\TraceCommand;
+use GratisAiAgent\Models\ProviderTrace;
 use WP_CLI;
 use XWP\DI\Decorators\Action;
 use XWP\DI\Decorators\Handler;
@@ -44,16 +45,24 @@
 final class CliHandler {
 
 	/**
-	 * Command-to-class map used to derive both primary and alias registrations.
+	 * Commands always registered regardless of WP_DEBUG.
 	 *
 	 * @var array<string,class-string>
 	 */
 	private const COMMANDS = array(
 		'prompt'    => CliCommand::class,
-		'trace'     => TraceCommand::class,
 		'benchmark' => BenchmarkCommand::class,
 	);
 
+	/**
+	 * Commands only registered when WP_DEBUG is active.
+	 *
+	 * @var array<string,class-string>
+	 */
+	private const DEBUG_COMMANDS = array(
+		'trace' => TraceCommand::class,
+	);
+
 	/**
 	 * Primary and alias root namespaces under which every subcommand is exposed.
 	 *
@@ -67,11 +76,20 @@ final class CliHandler {
 	 * Hooked on `cli_init` — guaranteed to fire only when WP-CLI is active,
 	 * which removes the need for the legacy `defined('WP_CLI')` guard that
 	 * used to live in the plugin bootstrap file.
+	 *
+	 * Debug-only commands (e.g. `trace`) are only registered when WP_DEBUG
+	 * is defined and truthy, matching the REST and UI availability gates.
 	 */
 	#[Action( tag: 'cli_init', priority: 10 )]
 	public function register_commands(): void {
+		$commands = self::COMMANDS;
+
+		if ( ProviderTrace::is_debug_mode() ) {
+			$commands = array_merge( $commands, self::DEBUG_COMMANDS );
+		}
+
 		foreach ( self::NAMESPACES as $ns ) {
-			foreach ( self::COMMANDS as $sub => $class ) {
+			foreach ( $commands as $sub => $class ) {
 				WP_CLI::add_command( "{$ns} {$sub}", $class );
 			}
 		}

includes/Bootstrap/HttpTraceHandler.php

@@ -19,6 +19,7 @@
 namespace GratisAiAgent\Bootstrap;
 
 use GratisAiAgent\Core\ProviderTraceLogger;
+use GratisAiAgent\Models\ProviderTrace;
 use XWP\DI\Decorators\Filter;
 use XWP\DI\Decorators\Handler;
 
@@ -32,6 +33,10 @@
  * CTX_GLOBAL ensures the filters are active in every request context — AI
  * calls can originate from admin (manual runs), REST (webhook triggers), CLI,
  * and cron (scheduled tasks).
+ *
+ * Both filter callbacks are no-ops when WP_DEBUG is not active. The DI
+ * container always instantiates this handler, but the actual recording never
+ * happens on production sites where WP_DEBUG is false or undefined.
  */
 #[Handler(
 	container: 'gratis-ai-agent',
@@ -44,7 +49,8 @@ final class HttpTraceHandler {
 	 * Capture outgoing request details before the HTTP call is made.
 	 *
 	 * Returns `$preempt` unchanged — this filter is used only for its
-	 * side-effect of recording in-flight request metadata.
+	 * side-effect of recording in-flight request metadata. No-op when
+	 * WP_DEBUG is not active.
 	 *
 	 * @param false|array<string,mixed>|\WP_Error $preempt     A preemptive return value. Default false.
 	 * @param array<string,mixed>                 $parsed_args HTTP request arguments.
@@ -53,14 +59,18 @@ final class HttpTraceHandler {
 	 */
 	#[Filter( tag: 'pre_http_request', priority: 10 )]
 	public function on_pre_http_request( mixed $preempt, array $parsed_args, string $url ): mixed {
+		if ( ! ProviderTrace::is_debug_mode() ) {
+			return $preempt;
+		}
 		return ProviderTraceLogger::on_pre_http_request( $preempt, $parsed_args, $url );
 	}
 
 	/**
 	 * Capture response details and write a trace record.
 	 *
 	 * Returns `$response` unchanged — this filter is used only for its
-	 * side-effect of persisting the completed trace row.
+	 * side-effect of persisting the completed trace row. No-op when
+	 * WP_DEBUG is not active.
 	 *
 	 * @param array<string,mixed> $response    HTTP response array.
 	 * @param array<string,mixed> $parsed_args HTTP request arguments.
@@ -69,6 +79,9 @@ public function on_pre_http_request( mixed $preempt, array $parsed_args, string
 	 */
 	#[Filter( tag: 'http_response', priority: 10 )]
 	public function on_http_response( array $response, array $parsed_args, string $url ): array {
+		if ( ! ProviderTrace::is_debug_mode() ) {
+			return $response;
+		}
 		return ProviderTraceLogger::on_http_response( $response, $parsed_args, $url );
 	}
 }

includes/Models/ProviderTrace.php

@@ -74,18 +74,40 @@ public static function get_schema( string $charset ): string {
 		) {$charset};";
 	}
 
+	/**
+	 * Whether the provider trace feature is available on this installation.
+	 *
+	 * Provider tracing is a debug-only feature. It captures raw HTTP request
+	 * and response bodies from LLM provider calls, which may contain prompt
+	 * content and model outputs. Availability is therefore gated on WP_DEBUG
+	 * so the feature is never active on production sites.
+	 *
+	 * @return bool True only when the WP_DEBUG constant is defined and truthy.
+	 */
+	public static function is_debug_mode(): bool {
+		return defined( 'WP_DEBUG' ) && (bool) WP_DEBUG;
+	}
+
 	/**
 	 * Check whether provider tracing is enabled.
 	 *
-	 * Checks the filter first, then the option.
+	 * Returns false immediately when WP_DEBUG is not active — tracing is a
+	 * debug-only feature and must never run on production. When WP_DEBUG is
+	 * set, checks the filter first, then the stored option.
 	 *
 	 * @return bool
 	 */
 	public static function is_enabled(): bool {
+		// Provider trace is a debug-only feature.
+		if ( ! self::is_debug_mode() ) {
+			return false;
+		}
+
 		/**
 		 * Filter to enable/disable provider trace logging.
 		 *
 		 * Allows enabling tracing environmentally without touching settings.
+		 * Only evaluated when WP_DEBUG is active.
 		 *
 		 * @param bool|null $enabled Null to defer to the option, true/false to override.
 		 */

includes/REST/TraceController.php

@@ -45,11 +45,18 @@
 final class TraceController extends XWP_REST_Controller {
 
 	/**
-	 * Permission check — admin only.
+	 * Permission check — admin only, and only when WP_DEBUG is active.
+	 *
+	 * Provider tracing is a debug-only feature. The REST endpoints are
+	 * unavailable (return 403) on any site where WP_DEBUG is not defined
+	 * or is false, regardless of the user's role.
 	 *
 	 * @return bool
 	 */
 	public function check_permission(): bool {
+		if ( ! ProviderTrace::is_debug_mode() ) {
+			return false;
+		}
 		return current_user_can( 'manage_options' );
 	}
 

src/settings-page/settings-app.js

@@ -361,6 +361,9 @@ export default function SettingsApp() {
 		( p ) => p.id === local.default_provider
 	);
 
+	// Provider trace is a debug-only feature — only show the tab when
+	// WP_DEBUG is active (communicated from PHP via gratisAiAgentData.wpDebug).
+	const isWpDebug = !! window.gratisAiAgentData?.wpDebug;
 	// Feature flags injected by PHP (UnifiedAdminMenu::enqueueAssets).
 	// Fall back to all-enabled when the global is absent (e.g. unit tests).
 	const features = window.gratisAiAgentData?.features ?? {
@@ -415,11 +418,16 @@ export default function SettingsApp() {
 			title: __( 'Usage', 'gratis-ai-agent' ),
 			className: 'gratis-ai-agent-settings-tab',
 		},
-		{
-			name: 'provider-trace',
-			title: __( 'Provider Trace', 'gratis-ai-agent' ),
-			className: 'gratis-ai-agent-settings-tab',
-		},
+		// Only visible when WP_DEBUG is active.
+		...( isWpDebug
+			? [
+					{
+						name: 'provider-trace',
+						title: __( 'Provider Trace', 'gratis-ai-agent' ),
+						className: 'gratis-ai-agent-settings-tab',
+					},
+			  ]
+			: [] ),
 		{
 			name: 'advanced',
 			title: __( 'Advanced', 'gratis-ai-agent' ),