@relvehq/agent-ready 0.0.0-stage → 0.2.1

package/dist/wp/relve-agent-ready/includes/class-relve-ar-router.php

@@ -0,0 +1,421 @@
+<?php
+/**
+ * Router: when to answer with Markdown, and with what.
+ *
+ *   do_parse_request (filter, priority 1), before WordPress parses the URL:
+ *     - detect the request (Relve_AR_Negotiation::detect): `.md` suffix,
+ *       `?format=md`, Accept, or llms.txt; GET/HEAD only
+ *     - llms.txt: answered right here
+ *     - excluded path: `.md` / `?format=md` get a plain 404, Accept goes on
+ *     - `.md`: REQUEST_URI is rewritten without the suffix, so WordPress
+ *       resolves the post as usual (no rewrite rules involved, works with any
+ *       permalink structure and never reaches WordPress's 404 for ".md")
+ *   template_redirect (priority 1), after the main query, before
+ *   redirect_canonical:
+ *     - a published, public, non-password post/page of an enabled type, the
+ *       posts front page or a category / tag / author archive -> Markdown
+ *       (a stored refined file first, else built from WordPress data)
+ *     - anything else: Accept requests carry on untouched; `.md` and
+ *       `?format=md` get a plain-text 404
+ *
+ * Nothing at all happens while the "Enabled" setting is off.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Front-end request handling.
+ */
+class Relve_AR_Router {
+
+	/** Detection for the current request, set in do_parse_request. @var array|null */
+	private static $detection = null;
+
+	/** Settings for the current request. @var array|null */
+	private static $settings = null;
+
+	/**
+	 * Register hooks.
+	 *
+	 * @return void
+	 */
+	public static function init() {
+		add_filter( 'do_parse_request', array( __CLASS__, 'on_parse_request' ), 1, 1 );
+		add_action( 'template_redirect', array( __CLASS__, 'on_template_redirect' ), 1 );
+		add_filter( 'rocket_cache_reject_uri', array( __CLASS__, 'rocket_reject_uri' ) );
+	}
+
+	// ── paths ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Path of home_url() without trailing slash: "" or e.g. "/blog".
+	 *
+	 * @return string
+	 */
+	public static function home_path() {
+		$path = (string) wp_parse_url( home_url(), PHP_URL_PATH );
+		return rtrim( $path, '/' );
+	}
+
+	/**
+	 * scheme://host[:port] of home_url().
+	 *
+	 * @return string
+	 */
+	public static function home_origin() {
+		$p = wp_parse_url( home_url() );
+		if ( ! is_array( $p ) || empty( $p['host'] ) ) {
+			return '';
+		}
+		return ( isset( $p['scheme'] ) ? $p['scheme'] : 'https' ) . '://' . $p['host'] . ( isset( $p['port'] ) ? ':' . $p['port'] : '' );
+	}
+
+	/**
+	 * Static prefix of the permalink structure ("/blog" for
+	 * "/blog/%postname%/"), "" when there is none.
+	 *
+	 * @return string
+	 */
+	public static function permalink_prefix() {
+		global $wp_rewrite;
+		$front = ( $wp_rewrite && isset( $wp_rewrite->front ) ) ? (string) $wp_rewrite->front : '/';
+		if ( false !== strpos( $front, '%' ) ) {
+			return '';
+		}
+		$front = rtrim( $front, '/' );
+		return null === Relve_AR_Negotiation::normalize_path( '' === $front ? '/' : $front ) ? '' : $front;
+	}
+
+	/**
+	 * Paths llms.txt is answered at: "<home path>/llms.txt", plus
+	 * "<home path><permalink prefix>/llms.txt" when posts live under a static
+	 * prefix such as "/blog" (a site whose home is the root but whose blog is
+	 * routed to WordPress under /blog). Empty when the plugin should not
+	 * answer llms.txt.
+	 *
+	 * @param array $settings Settings.
+	 * @return string[]
+	 */
+	public static function llms_paths( $settings ) {
+		if ( ! Relve_AR_Llms::should_serve( $settings['llms_mode'], Relve_AR_Llms::yoast_serves(), Relve_AR_Llms::physical_file_exists() ) ) {
+			return array();
+		}
+		$home  = self::home_path();
+		$paths = array( $home . '/llms.txt' );
+		$pre   = self::permalink_prefix();
+		if ( '' !== $pre ) {
+			$paths[] = $home . $pre . '/llms.txt';
+		}
+		return array_values( array_unique( $paths ) );
+	}
+
+	// ── hooks ─────────────────────────────────────────────────────────────
+
+	/**
+	 * do_parse_request: detect, answer llms.txt, strip ".md" for WordPress.
+	 *
+	 * @param bool $do Whether WordPress should parse the request.
+	 * @return bool
+	 */
+	public static function on_parse_request( $do ) {
+		self::$detection = null;
+		if ( ! $do || is_admin() || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
+			return $do;
+		}
+		$settings = Relve_AR_Settings::get();
+		if ( ! $settings['enabled'] ) {
+			return $do;
+		}
+		$method = isset( $_SERVER['REQUEST_METHOD'] ) ? strtoupper( sanitize_text_field( wp_unslash( $_SERVER['REQUEST_METHOD'] ) ) ) : 'GET';
+		if ( 'GET' !== $method && 'HEAD' !== $method ) {
+			return $do;
+		}
+		$uri    = isset( $_SERVER['REQUEST_URI'] ) ? wp_unslash( $_SERVER['REQUEST_URI'] ) : '/'; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- only matched, never output.
+		$accept = isset( $_SERVER['HTTP_ACCEPT'] ) ? wp_unslash( $_SERVER['HTTP_ACCEPT'] ) : ''; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- only parsed.
+		$home   = self::home_path();
+
+		$d = Relve_AR_Negotiation::detect( $method, (string) $uri, (string) $accept, $home, self::llms_paths( $settings ) );
+		if ( ! $d['markdown'] ) {
+			return $do;
+		}
+
+		if ( $d['llms'] ) {
+			self::serve_llms( $settings, $method );
+			exit;
+		}
+
+		if ( Relve_AR_Negotiation::is_excluded( $d['path'], $settings['excluded'], $home ) ) {
+			if ( 'accept' === $d['via'] ) {
+				return $do;
+			}
+			self::no_page_cache();
+			Relve_AR_Response::send( Relve_AR_Response::plain( 404, $method ) );
+			exit;
+		}
+
+		if ( 'suffix' === $d['via'] && null !== $d['uri'] ) {
+			$_SERVER['REQUEST_URI'] = wp_slash( $d['uri'] );
+			if ( ! empty( $_SERVER['PATH_INFO'] ) ) {
+				$_SERVER['PATH_INFO'] = self::strip_md_from_path_info( wp_unslash( $_SERVER['PATH_INFO'] ) ); // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized
+			}
+		}
+
+		self::$detection = $d;
+		self::$settings  = $settings;
+		return $do;
+	}
+
+	/**
+	 * PATH_INFO without a trailing ".md" (some servers set it).
+	 *
+	 * @param string $path_info PATH_INFO.
+	 * @return string
+	 */
+	private static function strip_md_from_path_info( $path_info ) {
+		$lower = strtolower( $path_info );
+		if ( '/index.md' === substr( $lower, -9 ) ) {
+			return substr( $path_info, 0, -8 );
+		}
+		if ( '.md' === substr( $lower, -3 ) ) {
+			return substr( $path_info, 0, -3 );
+		}
+		return $path_info;
+	}
+
+	/**
+	 * template_redirect: serve the Markdown, or step aside.
+	 *
+	 * @return void
+	 */
+	public static function on_template_redirect() {
+		if ( null === self::$detection ) {
+			return;
+		}
+		$d        = self::$detection;
+		$settings = self::$settings;
+		$method   = isset( $_SERVER['REQUEST_METHOD'] ) ? strtoupper( sanitize_text_field( wp_unslash( $_SERVER['REQUEST_METHOD'] ) ) ) : 'GET';
+		$inm      = isset( $_SERVER['HTTP_IF_NONE_MATCH'] ) ? wp_unslash( $_SERVER['HTTP_IF_NONE_MATCH'] ) : null; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- compared only.
+		$negotiated = ( 'accept' === $d['via'] );
+
+		$target = self::resolve_target( $settings );
+		if ( null === $target ) {
+			if ( $negotiated ) {
+				return; // WordPress serves its normal response.
+			}
+			self::no_page_cache();
+			Relve_AR_Response::send( Relve_AR_Response::plain( 404, $method ) );
+			exit;
+		}
+
+		try {
+			$source = 'native';
+			$store  = new Relve_AR_Store();
+			$stored = $store->get( $d['path'], self::home_path() );
+			if ( null !== $stored ) {
+				$source = 'stored';
+				$body   = Relve_AR_Markdown_Builder::for_stored( $stored, $target['canonical'], isset( $target['post'] ) ? $target['post'] : null, $target['title'] );
+			} elseif ( 'post' === $target['kind'] ) {
+				$body = Relve_AR_Markdown_Builder::for_post( $target['post'], $target['canonical'] );
+			} else {
+				$body = Relve_AR_Markdown_Builder::for_archive( $target['kind'], $target['id'], $target['canonical'] );
+			}
+		} catch ( Throwable $e ) {
+			$body = null;
+		}
+		if ( null === $body ) {
+			if ( $negotiated ) {
+				return; // An agent asking by Accept is never worse off than a browser.
+			}
+			self::no_page_cache();
+			Relve_AR_Response::send( Relve_AR_Response::plain( 500, $method ) );
+			exit;
+		}
+
+		self::no_page_cache();
+		Relve_AR_Response::send(
+			Relve_AR_Response::build(
+				$body,
+				array(
+					'method'        => $method,
+					'if_none_match' => $inm,
+					'canonical'     => $target['canonical'],
+					'cache_control' => Relve_AR_Response::cache_control_for( $d['via'] ),
+					'source'        => $source,
+				)
+			)
+		);
+		exit;
+	}
+
+	/**
+	 * What the main query resolved to, if it is something we serve.
+	 *
+	 * @param array $settings Settings.
+	 * @return array|null { kind: post|home|category|post_tag|author, post?, id, canonical, title }
+	 */
+	public static function resolve_target( $settings ) {
+		if ( is_404() || is_feed() || is_search() || is_preview() || is_embed() || is_robots() || is_trackback() || is_attachment() ) {
+			return null;
+		}
+		$types = (array) $settings['post_types'];
+		if ( is_singular() ) {
+			$post = get_queried_object();
+			if ( ! self::servable_post( $post, $types ) ) {
+				return null;
+			}
+			$canonical = get_permalink( $post );
+			if ( ! $canonical ) {
+				return null;
+			}
+			return array(
+				'kind'      => 'post',
+				'post'      => $post,
+				'id'        => $post->ID,
+				'canonical' => $canonical,
+				'title'     => '',
+			);
+		}
+		if ( ! in_array( 'post', $types, true ) ) {
+			return null; // Lists of posts need posts enabled.
+		}
+		if ( is_home() ) {
+			$page      = (int) get_option( 'page_for_posts' );
+			$canonical = ( 'page' === get_option( 'show_on_front' ) && $page ) ? get_permalink( $page ) : home_url( '/' );
+			return array(
+				'kind'      => 'home',
+				'id'        => 0,
+				'canonical' => $canonical,
+				'title'     => html_entity_decode( get_bloginfo( 'name' ), ENT_QUOTES, 'UTF-8' ),
+			);
+		}
+		if ( is_category() || is_tag() ) {
+			$term = get_queried_object();
+			if ( ! $term || ! isset( $term->term_id ) ) {
+				return null;
+			}
+			$link = get_term_link( $term );
+			if ( is_wp_error( $link ) ) {
+				return null;
+			}
+			return array(
+				'kind'      => is_category() ? 'category' : 'post_tag',
+				'id'        => (int) $term->term_id,
+				'canonical' => $link,
+				'title'     => html_entity_decode( $term->name, ENT_QUOTES, 'UTF-8' ),
+			);
+		}
+		if ( is_author() ) {
+			$user = get_queried_object();
+			if ( ! $user || ! isset( $user->ID ) ) {
+				return null;
+			}
+			return array(
+				'kind'      => 'author',
+				'id'        => (int) $user->ID,
+				'canonical' => get_author_posts_url( $user->ID ),
+				'title'     => html_entity_decode( (string) $user->display_name, ENT_QUOTES, 'UTF-8' ),
+			);
+		}
+		return null;
+	}
+
+	/**
+	 * Published, public, not password-protected, of an enabled type.
+	 *
+	 * @param mixed    $post  Queried object.
+	 * @param string[] $types Enabled post types.
+	 * @return bool
+	 */
+	public static function servable_post( $post, $types ) {
+		if ( ! ( $post instanceof WP_Post ) ) {
+			return false;
+		}
+		if ( 'publish' !== $post->post_status || '' !== (string) $post->post_password ) {
+			return false;
+		}
+		if ( ! in_array( $post->post_type, (array) $types, true ) || ! is_post_type_viewable( $post->post_type ) ) {
+			return false;
+		}
+		return true;
+	}
+
+	/**
+	 * Answer llms.txt.
+	 *
+	 * @param array  $settings Settings.
+	 * @param string $method   GET or HEAD.
+	 * @return void
+	 */
+	private static function serve_llms( $settings, $method ) {
+		$inm  = isset( $_SERVER['HTTP_IF_NONE_MATCH'] ) ? wp_unslash( $_SERVER['HTTP_IF_NONE_MATCH'] ) : null; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- compared only.
+		$body = Relve_AR_Llms::generate( $settings );
+		self::no_page_cache();
+		Relve_AR_Response::send(
+			Relve_AR_Response::build(
+				$body,
+				array(
+					'method'        => $method,
+					'if_none_match' => $inm,
+					'canonical'     => null, // llms.txt is meant to be found and read.
+					'noindex'       => false,
+					'content_type'  => Relve_AR_Response::TEXT_CONTENT_TYPE,
+					'cache_control' => Relve_AR_Response::cache_control_for( 'llms' ),
+					'source'        => 'llms',
+				)
+			)
+		);
+	}
+
+	// ── caches ────────────────────────────────────────────────────────────
+
+	/**
+	 * Tell page caches not to store this response as the page.
+	 *
+	 * @return void
+	 */
+	public static function no_page_cache() {
+		if ( ! defined( 'DONOTCACHEPAGE' ) ) {
+			define( 'DONOTCACHEPAGE', true ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedConstantFound -- shared page-cache convention.
+		}
+		add_filter( 'do_rocket_generate_caching_files', '__return_false', 999 );
+		do_action( 'litespeed_control_set_nocache', 'relve-agent-ready: markdown response' ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- LiteSpeed Cache's hook.
+	}
+
+	/**
+	 * WP Rocket: never cache ".md" URLs or llms.txt.
+	 *
+	 * @param mixed $uris Reject patterns.
+	 * @return array
+	 */
+	public static function rocket_reject_uri( $uris ) {
+		$uris   = is_array( $uris ) ? $uris : array();
+		$uris[] = '/(.+)\.md';
+		$uris[] = '/(.*)llms\.txt';
+		return array_values( array_unique( $uris ) );
+	}
+
+	/**
+	 * Regenerate WP Rocket's config so the reject list is current.
+	 *
+	 * @return void
+	 */
+	public static function refresh_rocket() {
+		if ( function_exists( 'rocket_generate_config_file' ) ) {
+			rocket_generate_config_file();
+		}
+	}
+
+	/**
+	 * Reset per-request state (tests).
+	 *
+	 * @return void
+	 */
+	public static function reset() {
+		self::$detection = null;
+		self::$settings  = null;
+	}
+}

package/dist/wp/relve-agent-ready/includes/class-relve-ar-settings.php

@@ -0,0 +1,115 @@
+<?php
+/**
+ * Settings: one option array, `relve_agent_ready`.
+ *
+ *   enabled         bool      default false (installing changes nothing)
+ *   post_types      string[]  default post, page
+ *   excluded_paths  string    one path prefix per line
+ *   llms_mode       string    auto|on|off, default auto
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Settings access and sanitising.
+ */
+class Relve_AR_Settings {
+
+	const OPTION = 'relve_agent_ready';
+
+	/** Paths never worth serving as Markdown (segment-aware prefixes). */
+	const DEFAULT_EXCLUDED = "/wp-admin\n/wp-login.php\n/wp-json\n/wp-content\n/wp-includes\n/feed\n/cart\n/checkout\n/my-account\n/account";
+
+	/**
+	 * Defaults.
+	 *
+	 * @return array
+	 */
+	public static function defaults() {
+		return array(
+			'enabled'        => false,
+			'post_types'     => array( 'post', 'page' ),
+			'excluded_paths' => self::DEFAULT_EXCLUDED,
+			'llms_mode'      => 'auto',
+		);
+	}
+
+	/**
+	 * Current settings merged over the defaults, plus "excluded" as a list.
+	 *
+	 * @return array
+	 */
+	public static function get() {
+		$stored = get_option( self::OPTION, array() );
+		$s      = array_merge( self::defaults(), is_array( $stored ) ? $stored : array() );
+		$s['enabled']    = (bool) $s['enabled'];
+		$s['post_types'] = array_values( array_filter( (array) $s['post_types'], 'is_string' ) );
+		$s['excluded']   = self::lines( $s['excluded_paths'] );
+		return $s;
+	}
+
+	/**
+	 * Split the excluded-paths text into prefixes.
+	 *
+	 * @param string $text Text.
+	 * @return string[]
+	 */
+	public static function lines( $text ) {
+		$out = array();
+		foreach ( preg_split( '/\r\n|\r|\n/', (string) $text ) as $line ) {
+			$line = trim( $line );
+			if ( '' !== $line ) {
+				$out[] = $line;
+			}
+		}
+		return $out;
+	}
+
+	/**
+	 * Sanitise a submitted settings array (register_setting callback).
+	 *
+	 * @param mixed $input Raw input.
+	 * @return array
+	 */
+	public static function sanitize( $input ) {
+		$input = is_array( $input ) ? $input : array();
+		$out   = self::defaults();
+
+		$out['enabled'] = ! empty( $input['enabled'] );
+
+		$public = function_exists( 'get_post_types' ) ? get_post_types( array( 'public' => true ) ) : array( 'post' => 'post', 'page' => 'page' );
+		$types  = array();
+		foreach ( (array) ( isset( $input['post_types'] ) ? $input['post_types'] : array() ) as $t ) {
+			$t = sanitize_key( (string) $t );
+			if ( 'attachment' !== $t && isset( $public[ $t ] ) ) {
+				$types[] = $t;
+			}
+		}
+		$out['post_types'] = array_values( array_unique( $types ) );
+
+		$paths = array();
+		foreach ( self::lines( isset( $input['excluded_paths'] ) ? (string) $input['excluded_paths'] : '' ) as $line ) {
+			$line = sanitize_text_field( $line );
+			$line = preg_replace( '#[^A-Za-z0-9/_.~%@!$&\'()*+,;=:-]#', '', $line );
+			if ( '' === $line ) {
+				continue;
+			}
+			if ( '/' !== $line[0] ) {
+				$line = '/' . $line;
+			}
+			$paths[] = $line;
+			if ( count( $paths ) >= 200 ) {
+				break;
+			}
+		}
+		$out['excluded_paths'] = implode( "\n", array_unique( $paths ) );
+
+		$mode             = isset( $input['llms_mode'] ) ? (string) $input['llms_mode'] : 'auto';
+		$out['llms_mode'] = in_array( $mode, array( 'auto', 'on', 'off' ), true ) ? $mode : 'auto';
+		return $out;
+	}
+}