<?php
/** Manual-only change request for existing WordPress terms. */

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

function wpagent_ability_update_term(): array {
	return array(
		'label'               => __( 'Term-Änderung prüfen', 'wp-agent-companion' ),
		'description'         => __( 'Nimmt keine Remote-Änderung an bestehenden Termen vor, weil WordPress keine atomare Compare-and-Write-Operation gegen parallele Verwaltungsänderungen bereitstellt. Speichere die Änderung im WordPress-Backend.', 'wp-agent-companion' ),
		'category'            => 'wp-agent',
		'input_schema'        => array(
			'type'                 => 'object',
			'properties'           => array(
				'term_id'             => array( 'type' => 'integer', 'minimum' => 1 ),
				'taxonomy'            => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 32, 'pattern' => '^[a-z0-9_-]+$' ),
				'expected_state_hash' => array( 'type' => 'string', 'pattern' => '^[a-f0-9]{64}$' ),
				'name'                => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 200 ),
				'slug'                => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 200 ),
				'parent'              => array( 'type' => 'integer', 'minimum' => 0 ),
				'description'         => array( 'type' => 'string', 'maxLength' => 5000 ),
			),
			'required'             => array( 'term_id', 'taxonomy', 'expected_state_hash' ),
			'additionalProperties' => false,
		),
		'output_schema'       => array( 'type' => 'object', 'properties' => array(), 'additionalProperties' => false ),
		'execute_callback'    => 'wpagent_exec_update_term',
		'permission_callback' => 'wpagent_perm_edit_posts',
		'meta'                => array( 'show_in_rest' => true, 'annotations' => array( 'readonly' => false, 'destructive' => false, 'idempotent' => false, 'manual_only' => true ) ),
	);
}

/** @return WP_Error */
function wpagent_term_manual_update_only(): WP_Error {
	return new WP_Error(
		'wpagent_term_update_manual_write_required',
		__( 'WordPress stellt für bestehende Terme keine nachweisbar atomare Compare-and-Write-Operation bereit. WPAgently ändert diesen Term deshalb nicht. Speichere die Änderung im WordPress-Backend und lies den Term anschließend neu.', 'wp-agent-companion' ),
		array( 'status' => 409, 'manual_only' => true )
	);
}

/** @return WP_Error */
function wpagent_wc_shipping_class_manual_update_only(): WP_Error {
	return new WP_Error(
		'wpagent_wc_shipping_class_requires_specialized_update',
		__( 'WooCommerce-Versandklassen müssen über die spezielle Versandklassen-Ability aktualisiert werden. Sie prüft Sperre, Konfliktzustand und Read-back. Der generische Term-Pfad nimmt keine Änderung vor.', 'wp-agent-companion' ),
		array( 'status' => 409, 'manual_only' => true )
	);
}

/** @return WP_Error */
function wpagent_exec_update_term( $input ) {
	// A state hash plus an application-owned lock cannot make wp_update_term()
	// conditional against concurrent wp-admin or direct provider writes.
	if ( is_array( $input ) && 'product_shipping_class' === ( $input['taxonomy'] ?? '' ) ) {
		return wpagent_wc_shipping_class_manual_update_only();
	}
	return wpagent_term_manual_update_only();
}
