<?php
/**
 * Fix Applier - executes AEO fixes on the WordPress site.
 *
 * Handles three safe fix types, each applied to the site only when the user
 * explicitly chooses to apply it from the inbox:
 * - robots.txt: Add/modify AI bot rules
 * - llms.txt: Generate and write the file to site root
 * - Schema: Inject FAQ/Organization JSON-LD via wp_head
 *
 * Each fix stores a backup before modifying, enabling undo.
 * All fixes are additive/reversible by design.
 *
 * @package Aiadvisors
 */

namespace Aiadvisors;

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

class Fixer {

	/**
	 * Apply a fix based on its type.
	 *
	 * @param string $type   Fix type (robots_txt, llms_txt, faq_schema, org_schema).
	 * @param array  $action Full action data from the platform.
	 * @return array Result with success boolean and message.
	 */
	public function apply( $type, $action ) {
		switch ( $type ) {
			case 'robots_txt':
				return $this->apply_robots_txt( $action );
			case 'llms_txt':
				return $this->apply_llms_txt( $action );
			case 'faq_schema':
				return $this->apply_faq_schema( $action );
			case 'org_schema':
				return $this->apply_org_schema( $action );
			case 'heading_rewrite':
				return $this->apply_heading_rewrite( $action );
			case 'meta_description':
				return $this->apply_meta_description( $action );
			case 'blog_draft':
				return $this->apply_blog_draft( $action );
			default:
				return array(
					'success' => false,
					'message' => "Unknown fix type: $type",
				);
		}
	}

	/**
	 * Undo a previously applied fix.
	 *
	 * @param string $type   Fix type.
	 * @param array  $action Action data (for context).
	 * @return array Result with success boolean and message.
	 */
	public function undo( $type, $action = array() ) {
		switch ( $type ) {
			case 'robots_txt':
				return $this->undo_robots_txt();
			case 'llms_txt':
				return $this->undo_llms_txt();
			case 'faq_schema':
				return $this->undo_faq_schema( $action );
			case 'org_schema':
				return $this->undo_org_schema();
			case 'heading_rewrite':
				return $this->undo_heading_rewrite( $action );
			case 'meta_description':
				return $this->undo_meta_description( $action );
			case 'blog_draft':
				return $this->undo_blog_draft( $action );
			default:
				return array(
					'success' => false,
					'message' => "Unknown fix type: $type",
				);
		}
	}

	// ═══ robots.txt ═══

	/**
	 * Apply robots.txt rules for AI bots.
	 * Adds rules to allow search crawlers and block training crawlers.
	 */
	private function apply_robots_txt( $action ) {
		// WordPress can only manage robots.txt through the `robots_txt` filter
		// (see output_robots), and that filter runs only when WordPress actually
		// serves /robots.txt. It does NOT run when a physical robots.txt sits at
		// the web root (the web server returns that file directly) or when pretty
		// permalinks are off (the rewrite that routes /robots.txt into WordPress
		// isn't active). Detect both and fail honestly rather than report a
		// success the visitor — and the platform — would never actually see.
		if ( file_exists( trailingslashit( ABSPATH ) . 'robots.txt' ) ) {
			return array(
				'success' => false,
				'message' => 'A physical robots.txt exists at your site root, so WordPress cannot manage it. Remove or edit that file directly, then try again.',
			);
		}

		if ( '' === (string) get_option( 'permalink_structure', '' ) ) {
			return array(
				'success' => false,
				'message' => 'WordPress can serve a dynamic robots.txt only with pretty permalinks enabled. Set Settings → Permalinks to any option other than "Plain", then re-apply.',
			);
		}

		// Prefer a ruleset supplied by the platform; fall back to the built-in
		// AI bot rules. sanitize_textarea_field keeps newlines but strips tags.
		$payload = $action['payload'] ?? array();
		$rules   = ( ! empty( $payload['rules'] ) && is_string( $payload['rules'] ) )
			? "\n" . sanitize_textarea_field( $payload['rules'] ) . "\n"
			: $this->build_robots_rules();

		// Store rules in an option and serve them through WordPress's
		// `robots_txt` filter (see output_robots). This avoids writing a
		// physical file to the web root and reverts cleanly on undo.
		update_option( 'aiadvisors_robots_rules', $rules, false );
		return array(
			'success' => true,
			'message' => 'AI bot rules added to robots.txt.',
		);
	}

	/**
	 * Build the AI bot rules block appended to robots.txt output.
	 */
	private function build_robots_rules() {
		// AI search crawlers to ALLOW (they drive traffic back).
		$allow_bots = array( 'ChatGPT-User', 'OAI-SearchBot', 'Claude-User', 'Claude-SearchBot', 'PerplexityBot' );
		// AI training crawlers to BLOCK (they use content without attribution).
		$block_bots = array( 'GPTBot', 'ClaudeBot', 'anthropic-ai', 'Google-Extended', 'CCBot', 'Meta-ExternalAgent', 'Bytespider', 'Applebot-Extended' );

		$rules  = "\n# AI-Advisors: AI Bot Rules\n";
		$rules .= "# Search/retrieval crawlers - ALLOW (they drive AI citations)\n";
		foreach ( $allow_bots as $bot ) {
			$rules .= "User-agent: $bot\nAllow: /\n\n";
		}
		$rules .= "# Training crawlers - BLOCK (they use content without attribution)\n";
		foreach ( $block_bots as $bot ) {
			$rules .= "User-agent: $bot\nDisallow: /\n\n";
		}
		$rules .= "# End AI-Advisors rules\n";

		return $rules;
	}

	/**
	 * Undo robots.txt changes by removing the stored rules.
	 */
	private function undo_robots_txt() {
		if ( get_option( 'aiadvisors_robots_rules' ) === false ) {
			return array(
				'success' => false,
				'message' => 'No AI bot rules are currently active.',
			);
		}
		delete_option( 'aiadvisors_robots_rules' );
		return array(
			'success' => true,
			'message' => 'AI bot rules removed from robots.txt.',
		);
	}

	/**
	 * Append stored AI bot rules to the WordPress virtual robots.txt.
	 * Hooked to the `robots_txt` filter.
	 *
	 * @param string $output    Current robots.txt content.
	 * @param bool   $is_public Whether the site is public.
	 * @return string
	 */
	public static function output_robots( $output, $is_public ) {
		$rules = get_option( 'aiadvisors_robots_rules' );
		if ( $rules && $is_public ) {
			$output .= $rules;
		}
		return $output;
	}

	/**
	 * Register the robots_txt filter when AI bot rules are active.
	 * Called on plugin init.
	 */
	public static function register_robots_output() {
		if ( get_option( 'aiadvisors_robots_rules' ) ) {
			add_filter( 'robots_txt', array( __CLASS__, 'output_robots' ), 10, 2 );
		}
	}

	// ═══ llms.txt ═══

	/**
	 * Generate and write llms.txt to the site root.
	 */
	private function apply_llms_txt( $action ) {
		$payload = $action['payload'] ?? array();

		// Platform content (sanitized to plain text) or auto-generated locally.
		if ( ! empty( $payload['content'] ) ) {
			$content = sanitize_textarea_field( (string) $payload['content'] );
		} else {
			$content = $this->generate_llms_content();
		}

		// Cap size — this is a small text descriptor, not a content store.
		$max_bytes = 256 * 1024; // 256 KB
		if ( strlen( $content ) > $max_bytes ) {
			$content = substr( $content, 0, $max_bytes );
		}

		$fs = self::filesystem();
		if ( ! $fs ) {
			return array(
				'success' => false,
				'message' => 'Could not access the filesystem to write llms.txt.',
			);
		}

		$llms_file = trailingslashit( ABSPATH ) . 'llms.txt';

		// Back up existing content ('' marks "did not previously exist"). Only on
		// the first apply — a second apply must not overwrite the original backup
		// with our own output, or undo would restore plugin content instead of the
		// file the user started with.
		if ( false === get_option( 'aiadvisors_llms_backup', false ) ) {
			update_option( 'aiadvisors_llms_backup', $fs->exists( $llms_file ) ? $fs->get_contents( $llms_file ) : '', false );
		}

		if ( ! $fs->put_contents( $llms_file, $content, FS_CHMOD_FILE ) ) {
			return array(
				'success' => false,
				'message' => 'Failed to write llms.txt. Check file permissions.',
			);
		}

		return array(
			'success' => true,
			'message' => 'llms.txt created at site root.',
		);
	}

	/**
	 * Generate llms.txt content from WordPress site data.
	 */
	private function generate_llms_content() {
		$site_name = get_bloginfo( 'name' );
		$site_desc = get_bloginfo( 'description' );
		$site_url  = home_url( '/' );

		$content  = "# {$site_name}\n\n";
		$content .= "> {$site_desc}\n\n";
		$content .= "## About\n\n";
		$content .= "{$site_name} ({$site_url})\n";
		if ( ! empty( $site_desc ) ) {
			$content .= "{$site_desc}\n";
		}
		$content .= "\n## Key Pages\n\n";

		// Add top-level pages.
		$pages = get_pages(
			array(
				'sort_column' => 'menu_order',
				'number'      => 20,
				'parent'      => 0,
			)
		);

		foreach ( $pages as $page ) {
			$url      = get_permalink( $page->ID );
			$title    = $page->post_title;
			$content .= "- [{$title}]({$url})\n";
		}

		// Add recent blog posts.
		$posts = get_posts(
			array(
				'numberposts' => 10,
				'post_status' => 'publish',
				'orderby'     => 'date',
				'order'       => 'DESC',
			)
		);

		if ( ! empty( $posts ) ) {
			$content .= "\n## Recent Articles\n\n";
			foreach ( $posts as $post ) {
				$url      = get_permalink( $post->ID );
				$title    = $post->post_title;
				$content .= "- [{$title}]({$url})\n";
			}
		}

		$content .= "\n---\nGenerated by AI-Advisors WordPress Plugin\n";

		return $content;
	}

	/**
	 * Undo llms.txt by restoring backup or removing file.
	 */
	private function undo_llms_txt() {
		$fs = self::filesystem();
		if ( ! $fs ) {
			return array(
				'success' => false,
				'message' => 'Could not access the filesystem.',
			);
		}

		$backup    = get_option( 'aiadvisors_llms_backup' );
		$llms_file = trailingslashit( ABSPATH ) . 'llms.txt';

		if ( $backup === false ) {
			// No backup - just remove the file if it carries our marker.
			if ( $fs->exists( $llms_file ) && strpos( (string) $fs->get_contents( $llms_file ), 'AI-Advisors' ) !== false ) {
				$fs->delete( $llms_file );
				return array(
					'success' => true,
					'message' => 'llms.txt removed.',
				);
			}
			return array(
				'success' => false,
				'message' => 'No llms.txt backup found.',
			);
		}

		if ( $backup === '' ) {
			// File didn't exist before - remove it.
			if ( $fs->exists( $llms_file ) ) {
				$fs->delete( $llms_file );
			}
		} else {
			$fs->put_contents( $llms_file, $backup, FS_CHMOD_FILE );
		}

		delete_option( 'aiadvisors_llms_backup' );
		return array(
			'success' => true,
			'message' => 'llms.txt restored to previous state.',
		);
	}

	/**
	 * Inline-only KSES allowlist for headings / FAQ answers — strips
	 * <script>, event handlers, and block/closing tags that could break
	 * out of their container.
	 *
	 * @return array
	 */
	private static function inline_kses_allowed() {
		return array(
			'a'      => array(
				'href'   => array(),
				'title'  => array(),
				'rel'    => array(),
				'target' => array(),
			),
			'strong' => array(),
			'b'      => array(),
			'em'     => array(),
			'i'      => array(),
			'span'   => array(),
			'code'   => array(),
			'br'     => array(),
			'sup'    => array(),
			'sub'    => array(),
		);
	}

	/**
	 * Initialize and return the WP_Filesystem instance, or null if
	 * filesystem access is unavailable (e.g. requires FTP credentials).
	 *
	 * @return \WP_Filesystem_Base|null
	 */
	private static function filesystem() {
		global $wp_filesystem;
		if ( ! function_exists( 'WP_Filesystem' ) ) {
			require_once ABSPATH . 'wp-admin/includes/file.php';
		}
		if ( ! WP_Filesystem() ) {
			return null;
		}
		return $wp_filesystem;
	}

	// ═══ Schema (FAQ) ═══

	/**
	 * Inject FAQ schema JSON-LD site-wide or per-page via wp_head.
	 */
	private function apply_faq_schema( $action ) {
		$payload = $action['payload'] ?? array();

		// If platform sends specific FAQ Q&As, use them.
		if ( ! empty( $payload['questions'] ) && is_array( $payload['questions'] ) ) {
			$faq_data = $payload['questions'];
		} else {
			// No specific FAQs sent - skip.
			return array(
				'success' => false,
				'message' => 'No FAQ data provided by the platform.',
			);
		}

		// Build FAQPage JSON-LD.
		$schema = array(
			'@context'   => 'https://schema.org',
			'@type'      => 'FAQPage',
			'mainEntity' => array(),
		);

		foreach ( $faq_data as $qa ) {
			if ( ! is_array( $qa ) ) {
				continue;
			}
			// Sanitize platform-supplied text before storing. Questions are
			// plain text; answers may keep limited inline formatting. This is
			// defense-in-depth on top of the JSON_HEX_* output encoding.
			$question = sanitize_text_field( $qa['q'] ?? $qa['question'] ?? '' );
			$answer   = wp_kses( $qa['a'] ?? $qa['answer'] ?? '', self::inline_kses_allowed() );
			if ( $question === '' || $answer === '' ) {
				continue;
			}
			$schema['mainEntity'][] = array(
				'@type'          => 'Question',
				'name'           => $question,
				'acceptedAnswer' => array(
					'@type' => 'Answer',
					'text'  => $answer,
				),
			);
		}

		if ( empty( $schema['mainEntity'] ) ) {
			return array(
				'success' => false,
				'message' => 'No valid FAQ data provided by the platform.',
			);
		}

		// FAQPage markup must describe FAQs that actually appear on the page it
		// renders on — Google treats blanket site-wide FAQPage (on search pages,
		// 404s, unrelated posts) as invalid. Store it against a specific post
		// when the platform names one; otherwise scope it to the homepage.
		// output_schemas() enforces where it is emitted.
		$post_id = $this->resolve_post_id( $payload );

		if ( $post_id ) {
			// update_post_meta() unslashes its value (recursively, for arrays), so
			// slash to preserve backslashes in question/answer text.
			update_post_meta( $post_id, '_aiadvisors_faq_schema', wp_slash( $schema ) );
			// Flag the existence of per-page FAQ markup so register_schema_output()
			// hooks wp_head without querying every post's meta on each request.
			update_option( 'aiadvisors_has_page_faq', 1 );
			$where = sprintf( ' on "%s"', get_the_title( $post_id ) );
		} else {
			update_option( 'aiadvisors_faq_schema', $schema, false );
			$where = ' on your homepage';
		}

		// Ensure the wp_head hook is registered.
		if ( ! has_action( 'wp_head', array( __CLASS__, 'output_schemas' ) ) ) {
			add_action( 'wp_head', array( __CLASS__, 'output_schemas' ), 1 );
		}

		return array(
			'success' => true,
			'message' => sprintf( 'FAQ schema injected%s (%d Q&As).', $where, count( $schema['mainEntity'] ) ),
		);
	}

	/**
	 * Remove FAQ schema.
	 */
	private function undo_faq_schema( $action = array() ) {
		$payload = $action['payload'] ?? array();
		$post_id = $this->resolve_post_id( $payload );

		// An action that targeted a specific post only ever touches that post's
		// meta — never the homepage-scoped option, which a different action owns.
		if ( $post_id ) {
			if ( get_post_meta( $post_id, '_aiadvisors_faq_schema', true ) ) {
				delete_post_meta( $post_id, '_aiadvisors_faq_schema' );
				self::maybe_clear_page_faq_flag();
				return array(
					'success' => true,
					'message' => 'FAQ schema removed from the page.',
				);
			}
			return array(
				'success' => false,
				'message' => 'No FAQ schema found on the target page.',
			);
		}

		delete_option( 'aiadvisors_faq_schema' );
		return array(
			'success' => true,
			'message' => 'FAQ schema removed.',
		);
	}

	/**
	 * Drop the aiadvisors_has_page_faq flag once no post carries per-page FAQ
	 * meta, so register_schema_output() stops hooking wp_head for nothing.
	 */
	private static function maybe_clear_page_faq_flag() {
		global $wpdb;

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- One-off COUNT on core postmeta to decide whether to unhook wp_head; runs only on FAQ-schema undo and is not meaningfully cacheable.
		$remaining = (int) $wpdb->get_var(
			"SELECT COUNT(*) FROM {$wpdb->postmeta} WHERE meta_key = '_aiadvisors_faq_schema'"
		);
		if ( 0 === $remaining ) {
			delete_option( 'aiadvisors_has_page_faq' );
		}
	}

	// ═══ Schema (Organization) ═══

	/**
	 * Inject Organization schema JSON-LD site-wide.
	 */
	private function apply_org_schema( $action ) {
		$payload = $action['payload'] ?? array();

		// Allowlist the schema type to known Organization-family types.
		$allowed_types = array(
			'Organization',
			'Corporation',
			'LocalBusiness',
			'OnlineBusiness',
			'NGO',
			'EducationalOrganization',
			'GovernmentOrganization',
			'NewsMediaOrganization',
			'Project',
		);
		$type          = isset( $payload['type'] ) ? sanitize_text_field( $payload['type'] ) : 'Organization';
		if ( ! in_array( $type, $allowed_types, true ) ) {
			$type = 'Organization';
		}

		$schema = array(
			'@context'    => 'https://schema.org',
			'@type'       => $type,
			'name'        => isset( $payload['name'] ) ? sanitize_text_field( $payload['name'] ) : get_bloginfo( 'name' ),
			'url'         => isset( $payload['url'] ) ? esc_url_raw( $payload['url'] ) : home_url( '/' ),
			'description' => isset( $payload['description'] ) ? sanitize_text_field( $payload['description'] ) : get_bloginfo( 'description' ),
		);

		if ( ! empty( $payload['logo'] ) ) {
			$logo = esc_url_raw( $payload['logo'] );
			if ( $logo ) {
				$schema['logo'] = $logo;
			}
		}

		if ( ! empty( $payload['sameAs'] ) ) {
			// Force to an array of validated URLs.
			$same_as = array_filter( array_map( 'esc_url_raw', (array) $payload['sameAs'] ) );
			if ( ! empty( $same_as ) ) {
				$schema['sameAs'] = array_values( $same_as );
			}
		}

		if ( ! empty( $payload['email'] ) ) {
			$email = sanitize_email( $payload['email'] );
			if ( $email ) {
				$schema['email'] = $email;
			}
		}

		// Store schema data.
		update_option( 'aiadvisors_org_schema', $schema, false );

		// Ensure the wp_head hook is registered.
		if ( ! has_action( 'wp_head', array( __CLASS__, 'output_schemas' ) ) ) {
			add_action( 'wp_head', array( __CLASS__, 'output_schemas' ), 1 );
		}

		return array(
			'success' => true,
			'message' => 'Organization schema injected.',
		);
	}

	/**
	 * Remove Organization schema.
	 */
	private function undo_org_schema() {
		delete_option( 'aiadvisors_org_schema' );
		return array(
			'success' => true,
			'message' => 'Organization schema removed.',
		);
	}

	// ═══ Heading Rewrites ═══

	/**
	 * Apply heading rewrites to a post as a pending revision.
	 *
	 * Expects payload.post_url or payload.post_id to identify the post,
	 * and payload.rewrites as an array of { original, replacement } pairs.
	 */
	private function apply_heading_rewrite( $action ) {
		$payload  = $action['payload'] ?? array();
		$rewrites = $payload['rewrites'] ?? array();

		if ( empty( $rewrites ) ) {
			return array(
				'success' => false,
				'message' => 'No heading rewrites provided.',
			);
		}

		// Find the post.
		$post_id = $this->resolve_post_id( $payload );
		if ( ! $post_id ) {
			return array(
				'success' => false,
				'message' => 'Could not find the target post.',
			);
		}

		$post = get_post( $post_id );
		if ( ! $post ) {
			return array(
				'success' => false,
				'message' => 'Post not found.',
			);
		}

		// Backup original content on the first apply only — metadata_exists guards
		// against a second rewrite overwriting the original with our own output.
		// update_post_meta() unslashes its value, so slash to preserve backslashes.
		$created_backup = ! metadata_exists( 'post', $post_id, '_aiadvisors_content_backup' );
		if ( $created_backup ) {
			update_post_meta( $post_id, '_aiadvisors_content_backup', wp_slash( $post->post_content ) );
		}

		// Apply rewrites to content.
		$content = $post->post_content;
		$applied = 0;

		foreach ( $rewrites as $rewrite ) {
			if ( ! is_array( $rewrite ) ) {
				continue;
			}
			$original = $rewrite['original'] ?? '';
			// Sanitize platform HTML to an inline allowlist: strips <script>,
			// event handlers, and stray closing/block tags so the replacement
			// cannot break out of the heading or inject script into the post
			// (the acting admin may have unfiltered_html, so wp_update_post's
			// implicit KSES is not guaranteed to run).
			$replacement = wp_kses( $rewrite['replacement'] ?? '', self::inline_kses_allowed() );
			if ( empty( $original ) || empty( $replacement ) ) {
				continue;
			}

			// Match heading tags containing the original text.
			$pattern = '/(<h[1-6][^>]*>)\s*' . preg_quote( $original, '/' ) . '\s*(<\/h[1-6]>)/i';
			// Use a callback so $replacement is inserted literally — preg_replace
			// would interpret $N / \N backreference sequences in platform content.
			$new_content = preg_replace_callback(
				$pattern,
				static function ( $m ) use ( $replacement ) {
					return $m[1] . $replacement . $m[2];
				},
				$content,
				1,
				$count
			);

			if ( $count > 0 ) {
				$content = $new_content;
				++$applied;
			}
		}

		if ( $applied === 0 ) {
			// Only remove the backup if THIS call created it — a prior successful
			// rewrite may own it, and its undo must still be able to restore.
			if ( $created_backup ) {
				delete_post_meta( $post_id, '_aiadvisors_content_backup' );
			}
			return array(
				'success' => false,
				'message' => 'No matching headings found in the post content.',
			);
		}

		// Save as a revision (update post content). wp_update_post() runs
		// wp_unslash() on its input, so slash first or backslashes in the content
		// (code blocks, LaTeX, the replacement text) get silently stripped.
		wp_update_post(
			wp_slash(
				array(
					'ID'           => $post_id,
					'post_content' => $content,
				)
			)
		);

		update_post_meta( $post_id, '_aiadvisors_heading_rewrite_applied', true );

		return array(
			'success' => true,
			'message' => sprintf( '%d heading(s) rewritten on "%s".', $applied, $post->post_title ),
			'post_id' => $post_id,
		);
	}

	/**
	 * Undo heading rewrites by restoring backed-up content.
	 */
	private function undo_heading_rewrite( $action ) {
		$payload = $action['payload'] ?? array();
		$post_id = $this->resolve_post_id( $payload );

		if ( ! $post_id ) {
			return array(
				'success' => false,
				'message' => 'Could not find the target post.',
			);
		}

		$backup = get_post_meta( $post_id, '_aiadvisors_content_backup', true );
		if ( empty( $backup ) ) {
			return array(
				'success' => false,
				'message' => 'No content backup found for this post.',
			);
		}

		// wp_update_post() unslashes its input; slash the backup so restored
		// content keeps any backslashes it originally contained.
		wp_update_post(
			wp_slash(
				array(
					'ID'           => $post_id,
					'post_content' => $backup,
				)
			)
		);

		delete_post_meta( $post_id, '_aiadvisors_content_backup' );
		delete_post_meta( $post_id, '_aiadvisors_heading_rewrite_applied' );

		return array(
			'success' => true,
			'message' => 'Heading rewrites undone.',
		);
	}

	// ═══ Meta Descriptions ═══

	/**
	 * Update a post's meta description.
	 *
	 * Detects Yoast SEO, Rank Math, or falls back to native WP.
	 * Expects payload.post_url or payload.post_id and payload.meta_description.
	 */
	private function apply_meta_description( $action ) {
		$payload   = $action['payload'] ?? array();
		$meta_desc = $payload['meta_description'] ?? '';

		if ( empty( $meta_desc ) ) {
			return array(
				'success' => false,
				'message' => 'No meta description provided.',
			);
		}

		$post_id = $this->resolve_post_id( $payload );
		if ( ! $post_id || ! get_post( $post_id ) ) {
			return array(
				'success' => false,
				'message' => 'Could not find the target post.',
			);
		}

		// Detect SEO plugin and get the right meta key.
		$meta_key = $this->get_meta_description_key();

		// Backup current value on the first apply only, so undo restores the
		// user's original description rather than a previously-applied one.
		// update_post_meta() unslashes its input, so slash to round-trip intact.
		$current = get_post_meta( $post_id, $meta_key, true );
		if ( ! metadata_exists( 'post', $post_id, '_aiadvisors_metadesc_backup' ) ) {
			update_post_meta( $post_id, '_aiadvisors_metadesc_backup', wp_slash( $current ) );
			update_post_meta( $post_id, '_aiadvisors_metadesc_key', $meta_key );
		}

		// Set the new description.
		update_post_meta( $post_id, $meta_key, wp_slash( sanitize_text_field( $meta_desc ) ) );

		$plugin_name = $this->detect_seo_plugin();

		return array(
			'success' => true,
			'message' => sprintf( 'Meta description updated on "%s" (via %s).', get_the_title( $post_id ), $plugin_name ?: 'WordPress' ),
			'post_id' => $post_id,
		);
	}

	/**
	 * Undo meta description update.
	 */
	private function undo_meta_description( $action ) {
		$payload = $action['payload'] ?? array();
		$post_id = $this->resolve_post_id( $payload );

		if ( ! $post_id ) {
			return array(
				'success' => false,
				'message' => 'Could not find the target post.',
			);
		}

		$backup   = get_post_meta( $post_id, '_aiadvisors_metadesc_backup', true );
		$meta_key = get_post_meta( $post_id, '_aiadvisors_metadesc_key', true );

		if ( empty( $meta_key ) ) {
			return array(
				'success' => false,
				'message' => 'No meta description backup found.',
			);
		}

		update_post_meta( $post_id, $meta_key, wp_slash( $backup ) );
		delete_post_meta( $post_id, '_aiadvisors_metadesc_backup' );
		delete_post_meta( $post_id, '_aiadvisors_metadesc_key' );

		return array(
			'success' => true,
			'message' => 'Meta description restored.',
		);
	}

	/**
	 * Detect which SEO plugin is active and return the meta key it uses.
	 */
	private function get_meta_description_key() {
		if ( $this->detect_seo_plugin() === 'Yoast SEO' ) {
			return '_yoast_wpseo_metadesc';
		}
		if ( $this->detect_seo_plugin() === 'Rank Math' ) {
			return 'rank_math_description';
		}
		// Fallback: standard WP meta or SEO Framework.
		return '_aiadvisors_meta_description';
	}

	/**
	 * Detect the active SEO plugin.
	 */
	private function detect_seo_plugin() {
		// is_plugin_active() lives in wp-admin/includes/plugin.php, which is not
		// always loaded in AJAX/cron contexts.
		if ( ! function_exists( 'is_plugin_active' ) ) {
			require_once ABSPATH . 'wp-admin/includes/plugin.php';
		}
		if ( defined( 'WPSEO_VERSION' ) || is_plugin_active( 'wordpress-seo/wp-seo.php' ) ) {
			return 'Yoast SEO';
		}
		if ( defined( 'RANK_MATH_VERSION' ) || is_plugin_active( 'seo-by-rank-math/rank-math.php' ) ) {
			return 'Rank Math';
		}
		if ( defined( 'THE_SEO_FRAMEWORK_VERSION' ) ) {
			return 'The SEO Framework';
		}
		return null;
	}

	// ═══ Blog Drafts ═══

	/**
	 * Create a blog post draft from platform-provided content.
	 *
	 * Expects payload with: title, content (HTML), excerpt, categories, tags.
	 * Creates a draft post assigned to the current admin user.
	 */
	private function apply_blog_draft( $action ) {
		$payload = $action['payload'] ?? array();
		$title   = $payload['title'] ?? '';
		$content = $payload['content'] ?? '';

		if ( empty( $title ) ) {
			return array(
				'success' => false,
				'message' => 'No blog post title provided.',
			);
		}

		if ( empty( $content ) ) {
			return array(
				'success' => false,
				'message' => 'No blog post content provided.',
			);
		}

		// Create the draft post.
		$post_data = array(
			'post_title'   => sanitize_text_field( $title ),
			'post_content' => wp_kses_post( $content ),
			'post_status'  => 'draft',
			'post_type'    => 'post',
			'post_author'  => get_current_user_id() ?: 1,
		);

		if ( ! empty( $payload['excerpt'] ) ) {
			$post_data['post_excerpt'] = sanitize_textarea_field( $payload['excerpt'] );
		}

		// wp_insert_post() unslashes its input; slash the whole array so the
		// title, content, and excerpt keep any backslashes they contain.
		$post_id = wp_insert_post( wp_slash( $post_data ), true );

		if ( is_wp_error( $post_id ) ) {
			return array(
				'success' => false,
				'message' => 'Failed to create draft: ' . $post_id->get_error_message(),
			);
		}

		// Assign categories if provided.
		if ( ! empty( $payload['categories'] ) && is_array( $payload['categories'] ) ) {
			$cat_ids = array();
			foreach ( $payload['categories'] as $cat_name ) {
				$term = term_exists( $cat_name, 'category' );
				if ( $term ) {
					$cat_ids[] = (int) $term['term_id'];
				} else {
					$new_term = wp_insert_term( sanitize_text_field( $cat_name ), 'category' );
					if ( ! is_wp_error( $new_term ) ) {
						$cat_ids[] = $new_term['term_id'];
					}
				}
			}
			if ( ! empty( $cat_ids ) ) {
				wp_set_post_categories( $post_id, $cat_ids );
			}
		}

		// Assign tags if provided.
		if ( ! empty( $payload['tags'] ) && is_array( $payload['tags'] ) ) {
			wp_set_post_tags( $post_id, array_map( 'sanitize_text_field', $payload['tags'] ) );
		}

		// Set meta description if provided.
		if ( ! empty( $payload['meta_description'] ) ) {
			$meta_key = $this->get_meta_description_key();
			update_post_meta( $post_id, $meta_key, sanitize_text_field( $payload['meta_description'] ) );
		}

		// Mark as AI-Advisors generated for tracking.
		update_post_meta( $post_id, '_aiadvisors_draft', true );
		update_post_meta( $post_id, '_aiadvisors_draft_source', 'content_intelligence' );

		$edit_link = get_edit_post_link( $post_id, 'raw' );

		return array(
			'success'   => true,
			'message'   => sprintf( 'Blog draft created: "%s". Edit it in WordPress.', $title ),
			'post_id'   => $post_id,
			'edit_link' => $edit_link,
		);
	}

	/**
	 * Undo blog draft by moving to trash.
	 */
	private function undo_blog_draft( $action ) {
		$payload = $action['payload'] ?? array();
		$post_id = $payload['post_id'] ?? null;

		// Try to find by title if no post_id stored.
		if ( ! $post_id && ! empty( $payload['title'] ) ) {
			$found = get_posts(
				array(
					'post_type'   => 'post',
					'post_status' => 'draft',
					'title'       => $payload['title'],
					'numberposts' => 1,
					// phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- Draft lookup by the plugin's own private meta key; runs only on blog-draft undo, not on any hot path.
					'meta_key'    => '_aiadvisors_draft',
					// phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_value -- Paired with the meta_key lookup above.
					'meta_value'  => '1',
				)
			);
			if ( ! empty( $found ) ) {
				$post_id = $found[0]->ID;
			}
		}

		if ( ! $post_id ) {
			return array(
				'success' => false,
				'message' => 'Could not find the draft post to remove.',
			);
		}

		wp_trash_post( $post_id );
		return array(
			'success' => true,
			'message' => 'Draft moved to trash.',
		);
	}

	// ═══ Helpers ═══

	/**
	 * Resolve a WordPress post ID from action payload.
	 *
	 * Supports: payload.post_id (direct), payload.post_url (URL lookup),
	 * or payload.url_path (path lookup).
	 *
	 * @param array $payload Action payload.
	 * @return int|null Post ID or null.
	 */
	private function resolve_post_id( $payload ) {
		// Direct post ID.
		if ( ! empty( $payload['post_id'] ) ) {
			return (int) $payload['post_id'];
		}

		// URL or path lookup.
		$url = $payload['post_url'] ?? $payload['url_path'] ?? '';
		if ( empty( $url ) ) {
			return null;
		}

		// Try url_to_postid (works for permalinks).
		$post_id = url_to_postid( $url );
		if ( $post_id > 0 ) {
			return $post_id;
		}

		// Try with home_url prefix if just a path.
		if ( strpos( $url, 'http' ) !== 0 ) {
			$full_url = home_url( $url );
			$post_id  = url_to_postid( $full_url );
			if ( $post_id > 0 ) {
				return $post_id;
			}
		}

		// Try by slug as last resort.
		$path = trim( wp_parse_url( $url, PHP_URL_PATH ) ?: $url, '/' );
		$slug = basename( $path );
		if ( ! empty( $slug ) ) {
			$found = get_posts(
				array(
					'name'        => $slug,
					'post_type'   => array( 'post', 'page' ),
					'post_status' => 'publish',
					'numberposts' => 1,
				)
			);
			if ( ! empty( $found ) ) {
				return $found[0]->ID;
			}
		}

		return null;
	}

	// ═══ Schema Output ═══

	/**
	 * Output all stored schemas in wp_head.
	 * Called via add_action('wp_head', ...).
	 */
	public static function output_schemas() {
		// Never emit structured data on error or search pages — the markup would
		// not describe real content there.
		if ( is_404() || is_search() ) {
			return;
		}

		$schemas = array();

		// FAQ: prefer per-page markup stored on the current post; otherwise the
		// homepage-scoped option. Emit it only on the page it actually describes,
		// never blanket across the whole site.
		$faq = null;
		if ( is_singular() ) {
			$page_faq = get_post_meta( get_queried_object_id(), '_aiadvisors_faq_schema', true );
			if ( is_array( $page_faq ) && ! empty( $page_faq ) ) {
				$faq = $page_faq;
			}
		}
		if ( null === $faq && is_front_page() ) {
			$site_faq = get_option( 'aiadvisors_faq_schema' );
			if ( is_array( $site_faq ) && ! empty( $site_faq ) ) {
				$faq = $site_faq;
			}
		}
		if ( $faq ) {
			$schemas[] = $faq;
		}

		// Organization: a site-wide identity claim, valid on any normal page.
		$org = get_option( 'aiadvisors_org_schema' );
		if ( $org && is_array( $org ) ) {
			$schemas[] = $org;
		}

		foreach ( $schemas as $schema ) {
			// Encode for a <script> context: JSON_HEX_TAG/AMP/QUOT/APOS escape
			// <, >, &, ", ' as \uXXXX so a value can never close the script tag
			// or break out of the JSON-LD block. Do NOT use JSON_UNESCAPED_SLASHES
			// here — unescaped "/" reintroduces the </script> breakout vector.
			$json = wp_json_encode(
				$schema,
				JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_QUOT | JSON_HEX_APOS | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT
			);
			if ( $json ) {
				echo "\n<!-- AI-Advisors Schema -->\n";
				echo '<script type="application/ld+json">' . $json . '</script>' . "\n"; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- JSON_HEX_* encoded above
			}
		}
	}

	/**
	 * Register the wp_head hook for schema output (called on plugin init).
	 */
	public static function register_schema_output() {
		$has_faq      = get_option( 'aiadvisors_faq_schema' );
		$has_org      = get_option( 'aiadvisors_org_schema' );
		$has_page_faq = get_option( 'aiadvisors_has_page_faq' );

		if ( $has_faq || $has_org || $has_page_faq ) {
			add_action( 'wp_head', array( __CLASS__, 'output_schemas' ), 1 );
		}
	}
}