<?php
/**
 * Module 4: the generated llms.txt document and the route that serves it.
 *
 * @package PressRoost\AIVE
 */

namespace PressRoost\AIVE\Modules;

use PressRoost\AIVE\Llms\LlmsCache;
use PressRoost\AIVE\Llms\LlmsDocument;
use PressRoost\AIVE\Llms\LlmsOwnership;
use PressRoost\AIVE\Llms\LlmsSelection;
use PressRoost\AIVE\ModuleInterface;
use PressRoost\AIVE\Utils\Helpers;
use WP;
use WP_Post;
use WP_Query;

/**
 * Serves a server-generated `llms.txt` at the site root, or yields.
 *
 * What this module promises and what it does not, stated first because the gap
 * is where every misunderstanding about llms.txt lives:
 *
 * - It promises a **plain-text inventory of eligible public content**, generated
 *   on the server, at the exact site-root route and nowhere else.
 * - It promises **no duplication**: where a physical file or a positively
 *   detected supported plugin owns the feature, AIVE yields to WordPress's
 *   normal 404 rather than publishing a second document. See `LlmsOwnership`,
 *   which owns that decision.
 * - It promises **nothing** about crawling, indexing, citations, ranking or
 *   model use, and nothing about whether another owner's file is valid or even
 *   reachable. A file in the web root is served by the web server before PHP
 *   runs, so its public response is outside anything this module can observe.
 *
 * Four gates run in order on every request, all evaluated per request rather
 * than at hook-registration time so that an administrator can watch a saved
 * setting take effect: the route test, the enable setting, site visibility, and
 * ownership. The cache is only reached after all four pass, which is what stops
 * a document generated while AIVE owned the route from being served after
 * something else took it over.
 *
 * ## The route
 *
 * One rewrite rule, `^llms\.txt/?$`, mapped to one query var. Both have to agree
 * before the handler does anything: the query var is public, because WordPress
 * only carries a rewritten var into the query when it is, so on its own it
 * would let `/?aive_llms_txt=1` claim the home page. Requiring that WordPress
 * also parsed the request path as exactly `llms.txt` is what closes that, and is
 * why no near path, archive, feed or query parameter can make this module
 * answer for another URL.
 *
 * Serving happens on `template_redirect` at priority 1 - before
 * `redirect_canonical` and before any template is chosen - and ends the request,
 * so no theme output can follow the document.
 *
 * The route depends on WordPress rewrite rules, so it needs a permalink
 * structure other than Plain. Activation flushes the rules; a site upgraded by
 * overwriting plugin files fires no activation hook, so `reconcile_route()`
 * repairs the stored rules once per build from an admin request.
 *
 * No asset is enqueued and no JavaScript is produced, on any request.
 *
 * @since 1.4.0
 */
final class LlmsTxt implements ModuleInterface {

	/**
	 * Module slug, which also keys `enable_llms_txt` in settings.
	 *
	 * @since 1.4.0
	 * @var string
	 */
	public const SLUG = 'llms_txt';

	/**
	 * The request path this module answers for, relative to the site root.
	 *
	 * @since 1.4.0
	 * @var string
	 */
	public const ROUTE = 'llms.txt';

	/**
	 * Query var the rewrite rule sets.
	 *
	 * @since 1.4.0
	 * @var string
	 */
	public const QUERY_VAR = 'aive_llms_txt';

	/**
	 * The one rewrite rule this module registers.
	 *
	 * One optional trailing slash is accepted, and nothing else: no prefix, no
	 * suffix, no case variation and no second path.
	 *
	 * @since 1.4.0
	 * @var string
	 */
	public const REWRITE_REGEX = '^llms\.txt/?$';

	/**
	 * Priority at which the module answers on `template_redirect`.
	 *
	 * @since 1.4.0
	 * @var int
	 */
	public const SERVE_PRIORITY = 1;

	/**
	 * Option recording the build whose route has been reconciled.
	 *
	 * Inside the `aive_` prefix, so `uninstall.php` removes it with everything
	 * else the plugin owns.
	 *
	 * @since 1.4.0
	 * @var string
	 */
	public const ROUTE_BUILD_OPTION = 'aive_llms_route_build';

	/**
	 * Returns the module slug.
	 *
	 * @since 1.4.0
	 *
	 * @return string Module slug.
	 */
	public function slug() {
		return self::SLUG;
	}

	/**
	 * Attaches the module's WordPress hooks.
	 *
	 * The route is registered unconditionally, and the enable setting is read
	 * inside the handler. Registering the rule only when the module is enabled
	 * would make the stored rewrite rules depend on a setting, so switching the
	 * module on would silently need a permalink flush before it worked.
	 *
	 * The invalidation set covers every input the cache key carries. It is
	 * belt-and-braces by design - a change to any of these already moves the key
	 * - but deleting the entry keeps the options table from holding twelve hours
	 * of unreachable rows.
	 *
	 * @since 1.4.0
	 *
	 * @return void
	 */
	public function register_hooks() {
		add_action( 'init', array( $this, 'register_route' ) );

		/*
		 * Registered immediately as well when `init` has already fired, which is
		 * what an activation request does: WordPress includes the plugin file
		 * during `activate_plugin()`, long after `init`, so the `init` callback
		 * above would not run in that request and the rule would be missing from
		 * the very flush that activation performs. Observed on a fresh install
		 * of the packaged candidate, not theorised. This mirrors the reason
		 * `Core::register_module()` hooks a late-registered module immediately:
		 * registration order must not change behaviour.
		 */
		if ( did_action( 'init' ) ) {
			$this->register_route();
		}

		add_filter( 'query_vars', array( $this, 'register_query_var' ) );
		add_action( 'template_redirect', array( $this, 'maybe_serve' ), self::SERVE_PRIORITY );
		add_action( 'admin_init', array( $this, 'reconcile_route' ) );

		/*
		 * Content: any change to a potentially includable record. Each of these
		 * hooks passes arguments `flush_all()` does not declare, which PHP
		 * ignores.
		 */
		foreach ( array( 'save_post', 'edit_post', 'before_delete_post', 'deleted_post', 'trashed_post', 'untrashed_post' ) as $hook ) {
			add_action( $hook, array( LlmsCache::class, 'flush_all' ) );
		}

		add_action( 'transition_post_status', array( $this, 'flush_on_transition' ), 10, 3 );

		/*
		 * Site, settings, visibility, presentation and ownership inputs. The
		 * last two entries are the supported plugins' own option names, which is
		 * the hook evidence available for an ownership change.
		 */
		$site_wide = array(
			'add_option_' . Helpers::OPTION_KEY,
			'update_option_' . Helpers::OPTION_KEY,
			'delete_option_' . Helpers::OPTION_KEY,
			'add_option_blog_public',
			'update_option_blog_public',
			'update_option_blogname',
			'update_option_blogdescription',
			'update_option_home',
			'update_option_siteurl',
			'update_option_show_on_front',
			'update_option_page_on_front',
			'update_option_page_for_posts',
			'update_option_permalink_structure',
			'update_option_active_plugins',
			'update_site_option_active_sitewide_plugins',
			'activated_plugin',
			'deactivated_plugin',
			'update_option_wpseo',
			'add_option_wpseo',
			'update_option_rank_math_modules',
			'add_option_rank_math_modules',
		);

		foreach ( $site_wide as $hook ) {
			add_action( $hook, array( LlmsCache::class, 'flush_all' ) );
		}
	}

	/**
	 * Registers the one rewrite rule this module owns.
	 *
	 * Added at the top of the rule set so that a permalink structure which would
	 * otherwise interpret `llms.txt` as a page name cannot shadow it.
	 *
	 * @since 1.4.0
	 *
	 * @return void
	 */
	public function register_route() {
		add_rewrite_rule(
			self::REWRITE_REGEX,
			'index.php?' . self::QUERY_VAR . '=1',
			'top'
		);
	}

	/**
	 * Adds the module's query var to the public query vars.
	 *
	 * WordPress carries a rewritten query var into `WP::$query_vars` only when
	 * the var is public, so this registration is what makes the rewrite rule
	 * mean anything. `is_route_request()` is what keeps the var from being
	 * usable as a way to request the document at another URL.
	 *
	 * @since 1.4.0
	 *
	 * @param array<int, string>|mixed $vars Registered public query vars.
	 * @return array<int, string> Query vars including this module's.
	 */
	public function register_query_var( $vars ) {
		$vars = is_array( $vars ) ? $vars : array();

		if ( ! in_array( self::QUERY_VAR, $vars, true ) ) {
			$vars[] = self::QUERY_VAR;
		}

		return $vars;
	}

	/**
	 * Repairs the stored rewrite rules once per build, from an admin request.
	 *
	 * Activation flushes the rules, but an upgrade that overwrites plugin files
	 * fires no activation hook, so a site updated that way would carry a rule
	 * set that predates this module and the route would quietly 404. The repair
	 * is bounded to one soft flush per build: the recorded build is written
	 * whether or not a flush was needed, so a site whose rules are filtered by
	 * something else cannot be made to flush on every admin request.
	 *
	 * A site using the Plain permalink structure has no rewrite rules at all.
	 * There is nothing to repair there and nothing is attempted: the route needs
	 * a permalink structure, which the settings screen states.
	 *
	 * @since 1.4.0
	 *
	 * @return void
	 */
	public function reconcile_route() {
		$build    = defined( 'AIVE_VERSION' ) ? (string) AIVE_VERSION : '';
		$recorded = get_option( self::ROUTE_BUILD_OPTION, '' );

		if ( is_string( $recorded ) && $recorded === $build ) {
			return;
		}

		$rules = get_option( 'rewrite_rules' );

		if ( is_array( $rules ) && array() !== $rules && ! array_key_exists( self::REWRITE_REGEX, $rules ) ) {
			// Soft flush: rewrites the stored rules and never touches .htaccess.
			flush_rewrite_rules( false );
		}

		update_option( self::ROUTE_BUILD_OPTION, $build, false );
	}

	/**
	 * Serves the document, or yields, when this request is the route.
	 *
	 * Ends the request on success. Nothing may print after a text/plain body,
	 * and `template_redirect` is the last hook before WordPress chooses a
	 * template, so exiting here is what guarantees the response is the document
	 * and nothing else.
	 *
	 * @since 1.4.0
	 *
	 * @return void
	 */
	public function maybe_serve() {
		if ( ! self::is_route_request() ) {
			return;
		}

		$response = self::response();

		if ( null === $response ) {
			self::yield_to_404();

			return;
		}

		status_header( 200 );

		foreach ( $response['headers'] as $name => $value ) {
			header( $name . ': ' . $value );
		}

		// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- A text/plain response body, not markup. Every interpolated value has passed LlmsText::normalize(), LlmsText::escape() or LlmsText::url(); an HTML escaper here would corrupt the document it is meant to protect.
		echo $response['body'];

		exit;
	}

	/**
	 * Returns the response AIVE would send for the route, or null to yield.
	 *
	 * Separated from `maybe_serve()` so that the decision and the document are
	 * observable without ending a process.
	 *
	 * @since 1.4.0
	 *
	 * @return array{status: int, headers: array<string, string>, body: string}|null Response, or null when AIVE must not serve.
	 */
	public static function response() {
		if ( ! Helpers::is_module_enabled( self::SLUG ) ) {
			return null;
		}

		$ownership = LlmsOwnership::detect();

		if ( ! LlmsOwnership::allows_serving( $ownership ) ) {
			return null;
		}

		return array(
			'status'  => 200,
			'headers' => array(
				'Content-Type'           => 'text/plain; charset=UTF-8',
				'X-Content-Type-Options' => 'nosniff',
			),
			'body'    => self::document( $ownership ),
		);
	}

	/**
	 * Returns the generated document, from cache when the state is unchanged.
	 *
	 * @since 1.4.0
	 *
	 * @param array<string, mixed>|null $ownership Decision from LlmsOwnership::detect(), or null to detect it.
	 * @return string The document, LF-terminated.
	 */
	public static function document( $ownership = null ) {
		$ownership = is_array( $ownership ) ? $ownership : LlmsOwnership::detect();

		$site      = LlmsDocument::site();
		$selection = LlmsSelection::selection();
		$key       = LlmsCache::key( $site, $selection, $ownership );
		$cached    = LlmsCache::get( $key );

		if ( null !== $cached ) {
			return $cached;
		}

		return LlmsCache::set( $key, LlmsDocument::render( $site, $selection ) );
	}

	/**
	 * Reports whether the current request is this module's exact route.
	 *
	 * Both conditions are required, and each closes a different hole. The parsed
	 * request path has to be exactly `llms.txt`, which is what stops a public
	 * query parameter from claiming another URL. The query var has to be set,
	 * which is what stops this module from answering for a path some other
	 * plugin's rewrite rule routed to itself.
	 *
	 * @since 1.4.0
	 *
	 * @return bool True when this request is the route.
	 */
	public static function is_route_request() {
		if ( is_admin() || wp_doing_ajax() || wp_doing_cron() ) {
			return false;
		}

		if ( defined( 'REST_REQUEST' ) && REST_REQUEST ) {
			return false;
		}

		if ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) {
			return false;
		}

		$wp = isset( $GLOBALS['wp'] ) ? $GLOBALS['wp'] : null;

		if ( ! $wp instanceof WP ) {
			return false;
		}

		$path = isset( $wp->request ) && is_string( $wp->request ) ? trim( $wp->request, '/' ) : '';

		if ( self::ROUTE !== $path ) {
			return false;
		}

		$requested = isset( $wp->query_vars[ self::QUERY_VAR ] ) ? $wp->query_vars[ self::QUERY_VAR ] : null;

		if ( null === $requested || ! is_scalar( $requested ) ) {
			return false;
		}

		$requested = (string) $requested;

		return '' !== $requested && '0' !== $requested;
	}

	/**
	 * Returns the state the settings screen reports.
	 *
	 * One call, so the screen and the public response cannot disagree about who
	 * owns the route or why.
	 *
	 * @since 1.4.0
	 *
	 * @return array{enabled: bool, serving: bool, ownership: array<string, mixed>, mode: string} Current state.
	 */
	public static function state() {
		$enabled   = Helpers::is_module_enabled( self::SLUG );
		$ownership = LlmsOwnership::detect();

		return array(
			'enabled'   => $enabled,
			'serving'   => $enabled && LlmsOwnership::allows_serving( $ownership ),
			'ownership' => $ownership,
			'mode'      => array() === LlmsSelection::stored_ids() ? 'automatic' : 'selected',
		);
	}

	/**
	 * Hands the request back to WordPress as an ordinary 404.
	 *
	 * Not a redirect, not an empty 200 and not a public explanation of who owns
	 * the route: the response a client gets when AIVE does not own the document
	 * is the response it would get if this module were not installed. Returning
	 * rather than exiting is what lets the theme's own 404 template render.
	 *
	 * @since 1.4.0
	 *
	 * @return void
	 */
	private static function yield_to_404() {
		$query = isset( $GLOBALS['wp_query'] ) ? $GLOBALS['wp_query'] : null;

		if ( $query instanceof WP_Query ) {
			$query->set_404();
		}

		status_header( 404 );
		nocache_headers();
	}

	/**
	 * Clears the cached document when a record's status changes.
	 *
	 * `transition_post_status` covers the one case the save hooks can miss: a
	 * status change made by code that does not go through `wp_update_post()`.
	 *
	 * @since 1.4.0
	 *
	 * @param string       $new_status New post status.
	 * @param string       $old_status Previous post status.
	 * @param WP_Post|null $post       Post that changed.
	 * @return void
	 */
	public function flush_on_transition( $new_status, $old_status, $post = null ) {
		if ( $post instanceof WP_Post ) {
			LlmsCache::flush_all();
		}
	}
}