<?php
/**
 * @package Hafenstudios\Kurato
 */

namespace Hafenstudios\Kurato\Cockpit;

defined( 'ABSPATH' ) || exit;

/**
 * Die Connector-Rolle kurato_agent (COCKPIT-API.md, Bauplan Kap. 4.3).
 *
 * Caps: read, hs_view_contacts, hs_manage_contacts. Ausdruecklich NICHT
 * hs_send_mails (Kampagnen-Versand) und NICHT hs_manage_settings (Einstellungen)
 * - beides bleibt Inhaber-Sache. Die bestehenden kurato/v1-Controller pruefen
 * diese Caps bereits; es kommt nur die Rolle hinzu.
 *
 * Anlage idempotent beim Aktivieren und selbstheilend (ensure()).
 */
class CockpitRole {

	public const ROLE = 'kurato_agent';

	/**
	 * Die Capabilities der Rolle.
	 *
	 * @return array<string, bool>
	 */
	public static function capabilities(): array {
		return array(
			'read'               => true,
			'hs_view_contacts'   => true,
			'hs_manage_contacts' => true,
		);
	}

	/**
	 * Legt die Rolle an bzw. bringt ihre Caps in den Sollzustand. Idempotent.
	 *
	 * @return void
	 */
	public static function install(): void {
		$role = get_role( self::ROLE );
		if ( ! $role ) {
			add_role( self::ROLE, __( 'Kurato-Agent', 'kurato' ), self::capabilities() );
			return;
		}

		// Bestandsrolle: fehlende Caps ergaenzen, unerwuenschte entfernen
		// (haelt den Rechteschnitt auch nach Aenderungen sauber).
		foreach ( self::capabilities() as $cap => $grant ) {
			$role->add_cap( $cap );
		}
		foreach ( array( 'hs_send_mails', 'hs_manage_settings' ) as $forbidden ) {
			$role->remove_cap( $forbidden );
		}
	}

	/**
	 * Selbstheilung: legt die Rolle neu an, falls sie fehlt.
	 *
	 * @return void
	 */
	public static function ensure(): void {
		if ( ! get_role( self::ROLE ) ) {
			self::install();
		}
	}

	/**
	 * Entfernt die Rolle (nur bei vollstaendiger Deinstallation).
	 *
	 * @return void
	 */
	public static function remove(): void {
		remove_role( self::ROLE );
	}
}
