@relvehq/agent-ready 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,334 @@
+<?php
+/**
+ * Negotiation: does this request want Markdown, and for which path?
+ *
+ * PHP port of @relvehq/agent-ready core/accept.ts and core/detect.ts. Keep the
+ * two in step: the cases in tests/run.php mirror test/detect.test.ts.
+ *
+ * Accept rule: serve Markdown only when `text/markdown` is listed explicitly
+ * and its q-value is greater than or equal to the q-value that applies to
+ * `text/html`. Ties go to Markdown. Wildcards never select Markdown on their
+ * own, but they count towards HTML's q-value. The user agent is never an
+ * input (choosing by user agent is cloaking).
+ *
+ * Three ways to ask, in order of precedence: a `.md` suffix, `?format=md`
+ * (also `format=markdown`), the Accept header. Plus the llms.txt path(s).
+ * Only GET and HEAD are ever considered.
+ *
+ * Pure PHP: no WordPress calls, so it is unit-testable without WordPress.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Accept negotiation and request detection.
+ */
+class Relve_AR_Negotiation {
+
+	/** Longer Accept headers are treated as absent (HTML). */
+	const MAX_ACCEPT_LENGTH = 4096;
+
+	/** Longer paths are never Markdown requests. */
+	const MAX_PATH_LENGTH = 1024;
+
+	/**
+	 * Which format does this Accept header prefer?
+	 *
+	 * @param string|null $accept The Accept header, or null when absent.
+	 * @return string "markdown" or "html".
+	 */
+	public static function choose_format( $accept ) {
+		if ( ! is_string( $accept ) || '' === $accept || strlen( $accept ) > self::MAX_ACCEPT_LENGTH ) {
+			return 'html';
+		}
+		$ranges     = self::parse_accept( $accept );
+		$markdown_q = self::explicit_q( $ranges, 'text', 'markdown' );
+		if ( null === $markdown_q || $markdown_q <= 0 ) {
+			return 'html';
+		}
+		return $markdown_q >= self::html_q( $ranges ) ? 'markdown' : 'html';
+	}
+
+	/**
+	 * Parse an Accept header into media ranges.
+	 *
+	 * @param string $accept Header value.
+	 * @return array[] List of array( 'type' => , 'subtype' => , 'q' => float ).
+	 */
+	public static function parse_accept( $accept ) {
+		$ranges = array();
+		foreach ( explode( ',', $accept ) as $part ) {
+			$params     = explode( ';', $part );
+			$media_type = strtolower( trim( (string) array_shift( $params ) ) );
+			$bits       = explode( '/', $media_type );
+			if ( count( $bits ) !== 2 || '' === $bits[0] || '' === $bits[1] ) {
+				continue;
+			}
+			$q = 1.0;
+			foreach ( $params as $param ) {
+				$kv   = explode( '=', $param );
+				$name = strtolower( trim( $kv[0] ) );
+				if ( 'q' !== $name ) {
+					continue;
+				}
+				$value = isset( $kv[1] ) ? trim( $kv[1] ) : '';
+				$q     = self::parse_q( $value );
+			}
+			$ranges[] = array(
+				'type'    => $bits[0],
+				'subtype' => $bits[1],
+				'q'       => $q,
+			);
+		}
+		return $ranges;
+	}
+
+	/**
+	 * RFC 9110 qvalue. Malformed means unacceptable (0), never preferred.
+	 *
+	 * @param string $value Raw q value.
+	 * @return float
+	 */
+	public static function parse_q( $value ) {
+		if ( ! preg_match( '/^(0(\.\d{0,3})?|1(\.0{0,3})?)$/', $value ) ) {
+			return 0.0;
+		}
+		return (float) $value;
+	}
+
+	/**
+	 * Highest q given to exactly type/subtype, or null if not listed.
+	 *
+	 * @param array[] $ranges  Parsed ranges.
+	 * @param string  $type    Type.
+	 * @param string  $subtype Subtype.
+	 * @return float|null
+	 */
+	private static function explicit_q( $ranges, $type, $subtype ) {
+		$best = null;
+		foreach ( $ranges as $r ) {
+			if ( $r['type'] === $type && $r['subtype'] === $subtype ) {
+				$best = max( null === $best ? 0.0 : $best, $r['q'] );
+			}
+		}
+		return $best;
+	}
+
+	/**
+	 * The q that applies to text/html: text/html, then text/*, then *\/*.
+	 *
+	 * @param array[] $ranges Parsed ranges.
+	 * @return float
+	 */
+	private static function html_q( $ranges ) {
+		foreach ( array( array( 'text', 'html' ), array( 'text', '*' ), array( '*', '*' ) ) as $pair ) {
+			$q = self::explicit_q( $ranges, $pair[0], $pair[1] );
+			if ( null !== $q ) {
+				return $q;
+			}
+		}
+		return 0.0;
+	}
+
+	/**
+	 * Leading slash, no trailing slash, no query or hash. Null for anything
+	 * that is not a plain path (traversal, backslashes, "//host", too long).
+	 *
+	 * @param mixed $raw Path.
+	 * @return string|null
+	 */
+	public static function normalize_path( $raw ) {
+		if ( ! is_string( $raw ) ) {
+			return null;
+		}
+		$path = explode( '#', explode( '?', $raw, 2 )[0], 2 )[0];
+		if ( '' === $path || '/' !== $path[0] || strlen( $path ) > self::MAX_PATH_LENGTH ) {
+			return null;
+		}
+		if ( false !== strpos( $path, '..' ) || false !== strpos( $path, '\\' ) || preg_match( '#//.#', $path ) ) {
+			return null;
+		}
+		$trimmed = rtrim( $path, '/' );
+		return '' === $trimmed ? '/' : $trimmed;
+	}
+
+	/**
+	 * "/x.md" -> "/x"; "<home>/index.md" -> "<home>/" ("/" when home is the
+	 * root); null when not a .md URL or a dotfile ("/.md", "/docs/.md").
+	 *
+	 * @param string $pathname  Request path.
+	 * @param string $home_path Home path without trailing slash ("" or "/blog").
+	 * @return string|null
+	 */
+	public static function strip_md_suffix( $pathname, $home_path = '' ) {
+		$lower = strtolower( $pathname );
+		if ( substr( $lower, -3 ) !== '.md' ) {
+			return null;
+		}
+		if ( strtolower( $home_path . '/index.md' ) === $lower ) {
+			return $home_path . '/';
+		}
+		$base = substr( $pathname, 0, -3 );
+		if ( '' === $base || '/' === substr( $base, -1 ) ) {
+			return null;
+		}
+		return $base;
+	}
+
+	/**
+	 * "/x" -> "/x.md"; the home path -> "<home>/index.md".
+	 *
+	 * @param string $path      Normalised path.
+	 * @param string $home_path Home path without trailing slash.
+	 * @return string
+	 */
+	public static function md_url_path( $path, $home_path = '' ) {
+		$path = rtrim( $path, '/' );
+		if ( '' === $path || $path === $home_path ) {
+			return $home_path . '/index.md';
+		}
+		return $path . '.md';
+	}
+
+	/**
+	 * Detect a Markdown request.
+	 *
+	 * @param string   $method     HTTP method.
+	 * @param string   $uri        Raw REQUEST_URI (path plus query).
+	 * @param string   $accept     Accept header ('' when absent).
+	 * @param string   $home_path  Home path without trailing slash.
+	 * @param string[] $llms_paths Paths llms.txt is answered at (empty = none).
+	 * @return array {
+	 *     @type bool        $markdown Is this a Markdown request?
+	 *     @type string|null $via      suffix|query|accept|llms, null when not.
+	 *     @type string      $path     Normalised page path without ".md".
+	 *     @type bool        $llms     Is this the llms.txt request?
+	 *     @type string|null $uri      REQUEST_URI for WordPress to parse (".md" and format removed), null to keep.
+	 * }
+	 */
+	public static function detect( $method, $uri, $accept, $home_path = '', $llms_paths = array() ) {
+		$no = array(
+			'markdown' => false,
+			'via'      => null,
+			'path'     => '/',
+			'llms'     => false,
+			'uri'      => null,
+		);
+		$method = strtoupper( (string) $method );
+		if ( 'GET' !== $method && 'HEAD' !== $method ) {
+			return $no;
+		}
+		$uri      = (string) $uri;
+		$parts    = explode( '?', $uri, 2 );
+		$pathname = explode( '#', $parts[0], 2 )[0];
+		$query    = isset( $parts[1] ) ? explode( '#', $parts[1], 2 )[0] : '';
+
+		$format = '';
+		$kept   = array();
+		if ( '' !== $query ) {
+			foreach ( explode( '&', $query ) as $pair ) {
+				if ( '' === $pair ) {
+					continue;
+				}
+				$kv   = explode( '=', $pair, 2 );
+				$name = urldecode( $kv[0] );
+				if ( 'format' === $name ) {
+					$format = strtolower( urldecode( isset( $kv[1] ) ? $kv[1] : '' ) );
+					continue;
+				}
+				$kept[] = $pair;
+			}
+		}
+		$search = $kept ? '?' . implode( '&', $kept ) : '';
+
+		if ( in_array( $pathname, (array) $llms_paths, true ) ) {
+			return array(
+				'markdown' => true,
+				'via'      => 'llms',
+				'path'     => $pathname,
+				'llms'     => true,
+				'uri'      => null,
+			);
+		}
+
+		$stripped = self::strip_md_suffix( $pathname, $home_path );
+		if ( null !== $stripped ) {
+			$path = self::normalize_path( $stripped );
+			if ( null === $path ) {
+				return $no;
+			}
+			// WordPress parses the path without ".md". Keep the slash a
+			// "<home>/index.md" mapped to, so the home path itself parses.
+			$wp_path = ( '/' === substr( $stripped, -1 ) ) ? ( '/' === $path ? '/' : $path . '/' ) : $path;
+			return array(
+				'markdown' => true,
+				'via'      => 'suffix',
+				'path'     => $path,
+				'llms'     => false,
+				'uri'      => $wp_path . $search,
+			);
+		}
+
+		$path = self::normalize_path( $pathname );
+		if ( null === $path ) {
+			return $no;
+		}
+		if ( 'md' === $format || 'markdown' === $format ) {
+			return array(
+				'markdown' => true,
+				'via'      => 'query',
+				'path'     => $path,
+				'llms'     => false,
+				'uri'      => $pathname . $search,
+			);
+		}
+		if ( 'markdown' === self::choose_format( $accept ) ) {
+			return array(
+				'markdown' => true,
+				'via'      => 'accept',
+				'path'     => $path,
+				'llms'     => false,
+				'uri'      => null,
+			);
+		}
+		$no['path'] = $path;
+		return $no;
+	}
+
+	/**
+	 * Segment-aware prefix match, like the package's isExcluded: "/cart"
+	 * excludes "/cart" and "/cart/x", not "/cartoon". Rules are matched
+	 * against the full path and the path relative to the home path.
+	 *
+	 * @param string   $path      Normalised path.
+	 * @param string[] $rules     Path prefixes.
+	 * @param string   $home_path Home path without trailing slash.
+	 * @return bool
+	 */
+	public static function is_excluded( $path, $rules, $home_path = '' ) {
+		$candidates = array( $path );
+		if ( '' !== $home_path && ( $path === $home_path || 0 === strpos( $path, $home_path . '/' ) ) ) {
+			$rel          = substr( $path, strlen( $home_path ) );
+			$candidates[] = '' === $rel ? '/' : $rel;
+		}
+		foreach ( (array) $rules as $rule ) {
+			$p = rtrim( trim( (string) $rule ), '/' );
+			if ( '' === $p ) {
+				continue;
+			}
+			if ( '/' !== $p[0] ) {
+				$p = '/' . $p;
+			}
+			foreach ( $candidates as $c ) {
+				if ( $c === $p || 0 === strpos( $c, $p . '/' ) ) {
+					return true;
+				}
+			}
+		}
+		return false;
+	}
+}

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

@@ -0,0 +1,226 @@
+<?php
+/**
+ * Response: headers, ETag / 304, Cache-Control, token estimate.
+ *
+ * PHP port of @relvehq/agent-ready core/respond.ts and the adapters' header
+ * choices. build() is pure (an array in, an array out) so it is unit-tested;
+ * send() writes it with header() and echo.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Builds and sends Markdown / llms.txt / 404 responses.
+ */
+class Relve_AR_Response {
+
+	const MARKDOWN_CONTENT_TYPE = 'text/markdown; charset=utf-8';
+	const TEXT_CONTENT_TYPE     = 'text/plain; charset=utf-8';
+
+	/** `.md`, `?format=md` and llms.txt: their own URLs, safe for shared caches. */
+	const CACHE_CONTROL = 'public, s-maxage=300, stale-while-revalidate=86400';
+
+	/** Negotiated by Accept on the page's own URL: never in a shared cache. */
+	const NEGOTIATED_CACHE_CONTROL = 'private, max-age=300';
+
+	/**
+	 * Cache-Control for a request that asked via $via.
+	 *
+	 * @param string $via suffix|query|accept|llms.
+	 * @return string
+	 */
+	public static function cache_control_for( $via ) {
+		return 'accept' === $via ? self::NEGOTIATED_CACHE_CONTROL : self::CACHE_CONTROL;
+	}
+
+	/**
+	 * Rough token count, as the package: ceil(length / 4), where length is
+	 * the JavaScript string length (UTF-16 code units).
+	 *
+	 * @param string $text Text.
+	 * @return int
+	 */
+	public static function estimate_tokens( $text ) {
+		return (int) ceil( self::utf16_length( $text ) / 4 );
+	}
+
+	/**
+	 * Length in UTF-16 code units (what JavaScript's .length counts).
+	 *
+	 * @param string $text UTF-8 text.
+	 * @return int
+	 */
+	public static function utf16_length( $text ) {
+		$text  = (string) $text;
+		$chars = preg_match_all( '/./su', $text );
+		if ( false === $chars ) {
+			return strlen( $text ); // Not valid UTF-8: count bytes.
+		}
+		$astral = preg_match_all( '/[\x{10000}-\x{10FFFF}]/u', $text );
+		return $chars + (int) $astral;
+	}
+
+	/**
+	 * Strong ETag: first 32 hex chars of SHA-256(body).
+	 *
+	 * @param string $body Body.
+	 * @return string
+	 */
+	public static function etag_for( $body ) {
+		return '"' . substr( hash( 'sha256', (string) $body ), 0, 32 ) . '"';
+	}
+
+	/**
+	 * ETag for a body. A `generated_at:` front-matter line is left out of the
+	 * hash (it changes every time) and the ETag is then weak, as the package.
+	 *
+	 * @param string $body Body.
+	 * @return string
+	 */
+	public static function etag_for_body( $body ) {
+		$stable = preg_replace( '/^generated_at:.*\n?/m', '', (string) $body, 1 );
+		return $stable === $body ? self::etag_for( $body ) : 'W/' . self::etag_for( $stable );
+	}
+
+	/**
+	 * RFC 9110 weak comparison; "*" matches any current representation.
+	 *
+	 * @param string|null $header If-None-Match value.
+	 * @param string      $etag   Our ETag.
+	 * @return bool
+	 */
+	public static function if_none_match_hits( $header, $etag ) {
+		if ( ! is_string( $header ) || '' === $header ) {
+			return false;
+		}
+		$bare = preg_replace( '#^W/#', '', $etag );
+		foreach ( explode( ',', $header ) as $raw ) {
+			$t = trim( $raw );
+			if ( '*' === $t || preg_replace( '#^W/#', '', $t ) === $bare ) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/**
+	 * Build a Markdown (or llms.txt) response.
+	 *
+	 * @param string $body Body.
+	 * @param array  $args {
+	 *     @type string      $method        GET or HEAD.
+	 *     @type string|null $if_none_match If-None-Match header.
+	 *     @type string|null $canonical     Absolute canonical URL; null leaves Link out.
+	 *     @type string      $cache_control Cache-Control.
+	 *     @type string      $content_type  Content-Type (default text/markdown).
+	 *     @type string      $source        x-agent-ready-source value.
+	 *     @type bool        $noindex       Send X-Robots-Tag: noindex (default true).
+	 *     @type int|null    $tokens        Token count (default: estimated from body).
+	 * }
+	 * @return array { status: int, headers: array<string,string>, body: string }
+	 */
+	public static function build( $body, $args ) {
+		$args = array_merge(
+			array(
+				'method'        => 'GET',
+				'if_none_match' => null,
+				'canonical'     => null,
+				'cache_control' => self::CACHE_CONTROL,
+				'content_type'  => self::MARKDOWN_CONTENT_TYPE,
+				'source'        => 'native',
+				'noindex'       => true,
+				'tokens'        => null,
+			),
+			(array) $args
+		);
+		$body   = (string) $body;
+		$etag   = self::etag_for_body( $body );
+		$tokens = null === $args['tokens'] ? self::estimate_tokens( $body ) : (int) $args['tokens'];
+
+		$headers = array( 'Content-Type' => $args['content_type'] );
+		$headers['Vary'] = 'Accept';
+		if ( $args['canonical'] ) {
+			$headers['Link'] = '<' . $args['canonical'] . '>; rel="canonical"';
+		}
+		if ( $args['noindex'] ) {
+			$headers['X-Robots-Tag'] = 'noindex';
+		}
+		$headers['x-markdown-tokens']    = (string) $tokens;
+		$headers['Cache-Control']        = $args['cache_control'];
+		$headers['ETag']                 = $etag;
+		$headers['x-agent-ready-source'] = $args['source'];
+
+		if ( self::if_none_match_hits( $args['if_none_match'], $etag ) ) {
+			unset( $headers['Content-Type'] );
+			return array(
+				'status'  => 304,
+				'headers' => $headers,
+				'body'    => '',
+			);
+		}
+		$headers['Content-Length'] = (string) strlen( $body );
+		return array(
+			'status'  => 200,
+			'headers' => $headers,
+			'body'    => 'HEAD' === strtoupper( (string) $args['method'] ) ? '' : $body,
+		);
+	}
+
+	/**
+	 * A plain-text error (the 404 for `.md` / `?format=md` with nothing to serve).
+	 *
+	 * @param int         $status    Status code.
+	 * @param string      $method    GET or HEAD.
+	 * @param string|null $canonical Canonical URL of the page, if known.
+	 * @return array
+	 */
+	public static function plain( $status, $method = 'GET', $canonical = null ) {
+		$body    = "No Markdown version of this page is available.\n";
+		$headers = array(
+			'Content-Type'  => self::TEXT_CONTENT_TYPE,
+			'Cache-Control' => 'no-store',
+			'Vary'          => 'Accept',
+			'X-Robots-Tag'  => 'noindex',
+		);
+		if ( $canonical ) {
+			$headers['Link'] = '<' . $canonical . '>; rel="canonical"';
+		}
+		$headers['Content-Length'] = (string) strlen( $body );
+		return array(
+			'status'  => (int) $status,
+			'headers' => $headers,
+			'body'    => 'HEAD' === strtoupper( (string) $method ) ? '' : $body,
+		);
+	}
+
+	/**
+	 * Write a built response. Removes headers WordPress already queued that
+	 * do not belong on Markdown (HTML Link headers, no-cache from nocache_headers()).
+	 * The caller exits afterwards.
+	 *
+	 * @param array $response From build() or plain().
+	 * @return void
+	 */
+	public static function send( $response ) {
+		if ( ! headers_sent() ) {
+			foreach ( array( 'Link', 'X-Pingback', 'Expires', 'Pragma', 'Last-Modified', 'Cache-Control', 'Content-Type', 'X-Robots-Tag' ) as $name ) {
+				header_remove( $name );
+			}
+			if ( function_exists( 'status_header' ) ) {
+				status_header( $response['status'] );
+			} else {
+				http_response_code( $response['status'] );
+			}
+			foreach ( $response['headers'] as $name => $value ) {
+				header( $name . ': ' . $value, true );
+			}
+		}
+		if ( '' !== $response['body'] ) {
+			echo $response['body']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- text/markdown or text/plain body, never HTML.
+		}
+	}
+}