<?php
/**
 * Ability: wp-agent/set-alt-text
 *
 * Setzt den Alt-Text eines vorhandenen Medienbeitrags (Meta
 * _wp_attachment_image_alt) und verifiziert per Re-Read, analog zum
 * Schreiben-lesen-verified-Muster aus set-seo-meta.php. Ein leerer
 * String ist ein gültiger Zielwert (bewusst kein Leer-Verbot wie bei
 * wp-agent/upload-media): so lässt sich ein fehlerhafter Alt-Text auch
 * gezielt wieder leeren.
 *
 * @package WPAgentCompanion
 */

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

function wpagent_ability_set_alt_text(): array {
	return array(
		'label'               => __( 'Alt-Text setzen', 'wp-agent-companion' ),
		'description'         => __( 'Setzt den Alt-Text eines vorhandenen Medienbeitrags (_wp_attachment_image_alt) und verifiziert per Re-Read. Ein leerer String ist ein gültiger Zielwert.', 'wp-agent-companion' ),
		'category'            => 'wp-agent',
		'input_schema'        => array(
			'type'       => 'object',
			'properties' => array(
				'attachment_id' => array( 'type' => 'integer' ),
				'alt'           => array( 'type' => 'string' ),
			),
			'required'   => array( 'attachment_id', 'alt' ),
		),
		'output_schema'       => array(
			'type'       => 'object',
			'properties' => array(
				'attachment_id' => array( 'type' => 'integer' ),
				'alt'           => array( 'type' => 'string' ),
				'verified'      => array( 'type' => 'boolean' ),
			),
		),
		'execute_callback'    => 'wpagent_exec_set_alt_text',
		'permission_callback' => 'wpagent_perm_edit_posts',
		'meta'                => array(
			'show_in_rest' => true,
			'annotations'  => array(
				'readonly'    => false,
				'destructive' => false,
				'idempotent'  => true,
			),
		),
	);
}

/**
 * @param mixed $input
 * @return array|WP_Error
 */
function wpagent_exec_set_alt_text( $input ) {
	$input         = is_array( $input ) ? $input : array();
	$attachment_id = (int) ( $input['attachment_id'] ?? 0 );
	$alt           = (string) ( $input['alt'] ?? '' );

	$attachment = get_post( $attachment_id );
	if ( ! $attachment || 'attachment' !== $attachment->post_type ) {
		return new WP_Error( 'wpagent_no_media', __( 'Medienbeitrag nicht gefunden.', 'wp-agent-companion' ), array( 'status' => 404 ) );
	}
	// current_user_can( 'edit_post', ... ) löst über WordPress' eigene
	// Meta-Capability-Zuordnung auch für post_type=attachment auf (dieselbe
	// Familie wie edit_posts/edit_others_posts, keine eigene Attachment-
	// Capability), analog zum Fein-Check in get-post.php/update-post.php.
	if ( ! current_user_can( 'edit_post', $attachment_id ) ) {
		return new WP_Error( 'wpagent_forbidden', __( 'Keine Berechtigung.', 'wp-agent-companion' ), array( 'status' => 403 ) );
	}

	update_post_meta( $attachment_id, '_wp_attachment_image_alt', $alt );

	$fresh    = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
	$verified = ( (string) $fresh === $alt );

	return array(
		'attachment_id' => $attachment_id,
		'alt'           => (string) $fresh,
		'verified'      => $verified,
	);
}
