<?php
/**
 * BuddyBoss Tools — public function API.
 *
 * @package BuddyBoss\Tools
 * @since 1.0.0
 */

defined( 'ABSPATH' ) || exit;

/**
 * Register a migration source.
 *
 * Called by each `migration/{vendor}/{vendor}.php` bootstrap file. The
 * registered source becomes a card in the Migration Tools grid; its `group`
 * metadata determines which section heading the card sits under (forums,
 * courses, communities, etc.).
 *
 * @since 1.0.0
 *
 * @param string $source_id Unique source id (e.g. "forums-phpbb").
 * @param array  $args      Source metadata. See BB_Tools_Migration_Registry::register().
 * @return bool True on success.
 */
function bb_tools_register_migration_source( $source_id, array $args ) {
	return BB_Tools_Migration_Registry::instance()->register( $source_id, $args );
}

/**
 * Get all registered migration sources.
 *
 * @since 1.0.0
 *
 * @return array<string, array<string, mixed>>
 */
function bb_tools_get_migration_sources() {
	return BB_Tools_Migration_Registry::instance()->all();
}

/**
 * Look up a single migration source by id.
 *
 * @since 1.0.0
 *
 * @param string $source_id The source id (e.g. "forums-phpbb").
 * @return array<string, mixed>|null Source args or null if not registered.
 */
function bb_tools_get_migration_source( $source_id ) {
	return BB_Tools_Migration_Registry::instance()->get_by_id( $source_id );
}

/**
 * Check whether the current user may run BuddyBoss Tools operations.
 *
 * Tools actions — sample-data import/clear, forum migration (which submits
 * external database credentials), and profile-type import — are destructive or
 * infrastructure-level, so they default to the site-administrator capability
 * `manage_options`. Site owners can widen or narrow this via the
 * `bb_tools_required_capability` filter; e.g. return `bp_moderate` to let a
 * delegated community-moderator role run Tools. The resolved capability is
 * checked with `current_user_can()`, which correctly maps BuddyBoss meta caps
 * (like `bp_moderate`) as well as core WordPress capabilities.
 *
 * @since 1.0.0
 *
 * @return bool True if the current user has the required capability.
 */
function bb_tools_current_user_can() {

	/**
	 * Filters the capability required to run BuddyBoss Tools operations.
	 *
	 * @since 1.0.0
	 *
	 * @param string $capability Capability name. Default 'manage_options'.
	 */
	$capability = apply_filters( 'bb_tools_required_capability', 'manage_options' );

	return current_user_can( $capability );
}