<?php
/**
 * WordPress Runtime Detector
 *
 * Detects WordPress runtime capabilities and version information.
 *
 * @package AIPT\Core\Services
 * @since 2.6.0
 */

namespace AIPT\Core\Services;

/**
 * Detects WordPress runtime capabilities and version information
 *
 * Provides static methods to check for WordPress features and APIs
 * available at runtime.
 *
 * @since 2.6.0
 */
final class WordPressRuntimeDetector {

	/**
	 * Checks if WordPress Connectors API is available
	 *
	 * The Connectors API was introduced in WordPress 7.0 and provides
	 * a unified interface for connecting to external services.
	 *
	 * @since 2.6.0
	 *
	 * @return bool True if Connectors API functions exist, false otherwise.
	 */
	public static function supportsConnectorsApi(): bool {
		return function_exists( 'wp_get_connector' ) && function_exists( 'wp_is_connector_registered' );
	}

	/**
	 * Checks if WordPress AI Client API is available
	 *
	 * The AI Client API was introduced in WordPress 7.0 and provides
	 * a unified interface for AI operations.
	 *
	 * @since 2.6.0
	 *
	 * @return bool True if AI Client API functions exist, false otherwise.
	 */
	public static function supportsAiClient(): bool {
		return function_exists( 'wp_ai_client_prompt' ) && function_exists( 'wp_supports_ai' );
	}

	/**
	 * Checks if AI features are enabled for the current WordPress request.
	 *
	 * Uses a dynamic call so WordPress Plugin Check can keep the plugin's
	 * minimum WP version below the version where the AI API was introduced.
	 *
	 * @since 2.6.0
	 *
	 * @return bool True when AI is supported or the API is unavailable.
	 */
	public static function supportsAi(): bool {
		if ( ! function_exists( 'wp_supports_ai' ) ) {
			return true;
		}

		return (bool) call_user_func( 'wp_supports_ai' );
	}

	/**
	 * Gets the WordPress AI client prompt builder when available.
	 *
	 * @since 2.6.0
	 *
	 * @return object|null Prompt builder instance, or null when unavailable.
	 */
	public static function getAiClientPrompt(): ?object {
		if ( ! function_exists( 'wp_ai_client_prompt' ) ) {
			return null;
		}

		return call_user_func( 'wp_ai_client_prompt' );
	}

	/**
	 * Checks if the WordPress Abilities API is available.
	 *
	 * @since 2.6.0
	 *
	 * @return bool True if abilities can be registered.
	 */
	public static function supportsAbilitiesApi(): bool {
		return function_exists( 'wp_register_ability' );
	}

	/**
	 * Register an ability category when the API is available.
	 *
	 * @since 2.6.0
	 *
	 * @param string $category Category slug.
	 * @param array  $args     Category arguments.
	 * @return void
	 */
	public static function registerAbilityCategory( string $category, array $args ): void {
		if ( ! function_exists( 'wp_register_ability_category' ) ) {
			return;
		}

		call_user_func( 'wp_register_ability_category', $category, $args );
	}

	/**
	 * Register an ability when the API is available.
	 *
	 * @since 2.6.0
	 *
	 * @param string $name Ability name.
	 * @param array  $args Ability arguments.
	 * @return void
	 */
	public static function registerAbility( string $name, array $args ): void {
		if ( ! self::supportsAbilitiesApi() ) {
			return;
		}

		call_user_func( 'wp_register_ability', $name, $args );
	}

	/**
	 * Checks if WordPress Abilities API with MCP metadata is available
	 *
	 * The Abilities API was introduced in WordPress 6.9. This method checks
	 * for both the API functions and WordPress 7.0+ for full MCP metadata support.
	 *
	 * @since 2.6.0
	 *
	 * @return bool True if Abilities API exists and WP version is 7.0+, false otherwise.
	 */
	public static function supportsAbilitiesMcpMeta(): bool {
		return function_exists( 'wp_register_ability' ) && version_compare( (string) get_bloginfo( 'version' ), '7.0', '>=' );
	}

	/**
	 * Gets the current WordPress version
	 *
	 * @since 2.6.0
	 *
	 * @return string The current WordPress version string.
	 */
	public static function currentWpVersion(): string {
		return (string) get_bloginfo( 'version' );
	}
}
