<?php
/**
 * Agentic Abilities Registration API
 *
 * Public functions for registering agentic abilities.
 * This API allows both WP-Agentic-Admin and third-party plugins
 * to register abilities that the AI assistant can use.
 *
 * @license GPL-2.0-or-later
 * @package AgenticAdmin
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Global storage for registered agentic abilities.
 *
 * @var array
 */
global $agentic_admin_abilities;
$agentic_admin_abilities = array();

/**
 * Register a agentic ability.
 *
 * This function registers an ability with both the WordPress Abilities API
 * (for backend execution) and stores the JS configuration for frontend use.
 *
 * @since 0.1.0
 *
 * @param string $id         Unique ability identifier (e.g., 'agentic-admin/cache-flush').
 * @param array  $php_args   PHP configuration for the WordPress Abilities API.
 *                           See wp_register_ability() for available options.
 * @param array  $js_args    Optional. JavaScript configuration for the chat interface.
 *                           - keywords:            (array)  Words/phrases that trigger this ability.
 *                           - initialMessage:      (string) Message shown while ability executes.
 *                           - requiresConfirmation:(bool)   Whether to show confirmation modal.
 *                           - confirmationMessage: (string) Custom confirmation message.
 * @return bool True on success, false on failure.
 */
function agentic_admin_register_ability( string $id, array $php_args, array $js_args = array() ): bool {
	global $agentic_admin_abilities;

	// Validate ID format.
	if ( empty( $id ) || ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $id ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			esc_html(
				sprintf(
					/* translators: %s: ability ID */
					__( 'Invalid ability ID format: %s. Must be in format "namespace/ability-name".', 'agentic-admin' ),
					$id
				)
			),
			'1.0.0'
		);
		return false;
	}

	// Register with WordPress Abilities API if available.
	if ( function_exists( 'wp_register_ability' ) ) {
		wp_register_ability( $id, $php_args );
	}

	// Store JS configuration for later use.
	$agentic_admin_abilities[ $id ] = array(
		'id'  => $id,
		'php' => $php_args,
		'js'  => wp_parse_args(
			$js_args,
			array(
				'keywords'             => array(),
				'initialMessage'       => __( 'Working on it...', 'agentic-admin' ),
				'requiresConfirmation' => false,
				'confirmationMessage'  => '',
			)
		),
	);

	return true;
}

/**
 * Unregister a agentic ability.
 *
 * @since 0.1.0
 *
 * @param string $id Ability identifier.
 * @return bool True if ability was unregistered, false if it didn't exist.
 */
function agentic_admin_unregister_ability( string $id ): bool {
	global $agentic_admin_abilities;

	if ( ! isset( $agentic_admin_abilities[ $id ] ) ) {
		return false;
	}

	unset( $agentic_admin_abilities[ $id ] );

	// Also unregister from WordPress Abilities API if available.
	if ( function_exists( 'wp_unregister_ability' ) ) {
		wp_unregister_ability( $id );
	}

	return true;
}

/**
 * Get all registered agentic abilities.
 *
 * @since 0.1.0
 *
 * @return array Array of registered abilities.
 */
function agentic_admin_get_abilities(): array {
	global $agentic_admin_abilities;
	return $agentic_admin_abilities ?? array();
}

/**
 * Get a specific agentic ability.
 *
 * @since 0.1.0
 *
 * @param string $id Ability identifier.
 * @return array|null Ability configuration or null if not found.
 */
function agentic_admin_get_ability( string $id ): ?array {
	global $agentic_admin_abilities;
	return $agentic_admin_abilities[ $id ] ?? null;
}

/**
 * Get JS configurations for all registered abilities.
 *
 * This is used to pass ability configurations to the frontend.
 * Includes annotations from PHP config for operation type display.
 *
 * @since 0.1.0
 *
 * @return array Array of JS configurations keyed by ability ID.
 */
function agentic_admin_get_abilities_js_config(): array {
	global $agentic_admin_abilities;

	$js_configs = array();

	foreach ( $agentic_admin_abilities as $id => $ability ) {
		$js_config = $ability['js'];

		// Include annotations from PHP config for operation type display.
		if ( isset( $ability['php']['meta']['annotations'] ) ) {
			$js_config['annotations'] = $ability['php']['meta']['annotations'];
		}

		// Include label and description from PHP config.
		if ( isset( $ability['php']['label'] ) ) {
			$js_config['phpLabel'] = $ability['php']['label'];
		}
		if ( isset( $ability['php']['description'] ) ) {
			$js_config['description'] = $ability['php']['description'];
		}

		// Include input_schema so JS clients can validate inputs.
		if ( isset( $ability['php']['input_schema'] ) ) {
			$js_config['inputSchema'] = $ability['php']['input_schema'];
		}

		$js_configs[ $id ] = $js_config;
	}

	return $js_configs;
}

/**
 * Check if a agentic ability is registered.
 *
 * @since 0.1.0
 *
 * @param string $id Ability identifier.
 * @return bool True if ability exists.
 */
function agentic_admin_ability_exists( string $id ): bool {
	global $agentic_admin_abilities;
	return isset( $agentic_admin_abilities[ $id ] );
}