@relvehq/agent-ready 0.3.0 → 0.4.0

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

@@ -1,583 +1,583 @@
-<?php
-/**
- * Store: refined Markdown files from Relve.
- *
- * Upload contract (agreed with the Relve runner, `venture.ts --zip`): the zip
- * holds a top-level `md/` folder; inside it, `<url-path>.md` relative to the
- * site root exactly as the npm refine writes them ("/" -> md/index.md,
- * "/blog/my-post/" -> md/blog/my-post.md). `.json` sidecars and other files
- * are skipped, not errors. Entries outside `md/`, absolute paths, `..` and
- * oversized files are rejected.
- *
- * Files live in wp-content/uploads/relve-agent-ready/md/, behind an
- * .htaccess "deny all" and index.php files. They are only ever read and sent
- * as text, never included or executed.
- *
- * The validation and lookup helpers are pure and unit-tested; the class takes
- * its base directory in the constructor so tests use a temp dir.
- *
- * @package Relve_Agent_Ready
- */
-
-if ( ! defined( 'ABSPATH' ) ) {
-	exit;
-}
-
-/**
- * Refined-files store.
- */
-class Relve_AR_Store {
-
-	/** Max zip size in bytes. */
-	const MAX_ZIP_BYTES = 20971520; // 20 MB.
-
-	/** Max size of one Markdown file in bytes. */
-	const MAX_FILE_BYTES = 2097152; // 2 MB.
-
-	/** Max total uncompressed bytes written from one zip. */
-	const MAX_TOTAL_BYTES = 104857600; // 100 MB.
-
-	/** Max entries read from one zip. */
-	const MAX_ENTRIES = 20000;
-
-	/** Root folder: .../uploads/relve-agent-ready. @var string */
-	private $root;
-
-	/**
-	 * Constructor.
-	 *
-	 * @param string|null $root Root folder; default uploads/relve-agent-ready.
-	 */
-	public function __construct( $root = null ) {
-		if ( null === $root ) {
-			$uploads = wp_upload_dir( null, false );
-			$root    = trailingslashit( $uploads['basedir'] ) . 'relve-agent-ready';
-		}
-		$this->root = rtrim( str_replace( '\\', '/', (string) $root ), '/' );
-	}
-
-	/**
-	 * Root folder.
-	 *
-	 * @return string
-	 */
-	public function root() {
-		return $this->root;
-	}
-
-	/**
-	 * Folder the .md files live in.
-	 *
-	 * @return string
-	 */
-	public function md_dir() {
-		return $this->root . '/md';
-	}
-
-	// ── validation (pure) ─────────────────────────────────────────────────
-
-	/**
-	 * Classify one zip entry name.
-	 *
-	 * @param string $name Entry name as stored in the zip.
-	 * @return array { status: store|skip|reject, path: relative path under md/ (store only), reason: string }
-	 */
-	public static function validate_entry( $name ) {
-		$name = (string) $name;
-		$skip = function ( $reason ) {
-			return array(
-				'status' => 'skip',
-				'path'   => '',
-				'reason' => $reason,
-			);
-		};
-		$reject = function ( $reason ) {
-			return array(
-				'status' => 'reject',
-				'path'   => '',
-				'reason' => $reason,
-			);
-		};
-		if ( '' === $name || false !== strpos( $name, "\0" ) || preg_match( '/[\x00-\x1F\x7F]/', $name ) ) {
-			return $reject( 'bad name' );
-		}
-		if ( false !== strpos( $name, '\\' ) ) {
-			return $reject( 'backslash in path' );
-		}
-		if ( '/' === $name[0] || preg_match( '#^[A-Za-z]:#', $name ) ) {
-			return $reject( 'absolute path' );
-		}
-		$segments = explode( '/', $name );
-		foreach ( $segments as $seg ) {
-			if ( '..' === $seg || '.' === $seg ) {
-				return $reject( 'path traversal' );
-			}
-		}
-		if ( '/' === substr( $name, -1 ) ) {
-			return $skip( 'folder' );
-		}
-		if ( 'md' !== $segments[0] || count( $segments ) < 2 ) {
-			return $reject( 'outside md/' );
-		}
-		$rel = implode( '/', array_slice( $segments, 1 ) );
-		if ( strtolower( substr( $rel, -3 ) ) !== '.md' ) {
-			return $skip( 'not a .md file' );
-		}
-		foreach ( array_slice( $segments, 1 ) as $seg ) {
-			if ( '' === $seg ) {
-				return $reject( 'empty path segment' );
-			}
-			if ( '.' === $seg[0] ) {
-				return $reject( 'hidden file' );
-			}
-			if ( preg_match( '#[<>:"|?*]#', $seg ) ) {
-				return $reject( 'bad character' );
-			}
-		}
-		if ( strlen( $rel ) > 1024 ) {
-			return $reject( 'path too long' );
-		}
-		return array(
-			'status' => 'store',
-			'path'   => $rel,
-			'reason' => '',
-		);
-	}
-
-	/**
-	 * Relative file names to try for a request path, most specific first:
-	 * the full path, then the path relative to the home path.
-	 *
-	 * @param string $path      Normalised request path ("/blog/my-post", "/").
-	 * @param string $home_path Home path without trailing slash ("" or "/blog").
-	 * @return string[] e.g. array( 'blog/my-post.md', 'my-post.md' ).
-	 */
-	public static function candidates( $path, $home_path = '' ) {
-		$norm = Relve_AR_Negotiation::normalize_path( $path );
-		if ( null === $norm ) {
-			return array();
-		}
-		$list = array( self::file_for( $norm ) );
-		if ( '' !== $home_path && ( $norm === $home_path || 0 === strpos( $norm, $home_path . '/' ) ) ) {
-			$rel    = substr( $norm, strlen( $home_path ) );
-			$list[] = self::file_for( '' === $rel ? '/' : $rel );
-		}
-		return array_values( array_unique( $list ) );
-	}
-
-	/**
-	 * "/" -> "index.md", "/a/b" -> "a/b.md".
-	 *
-	 * @param string $norm Normalised path.
-	 * @return string
-	 */
-	private static function file_for( $norm ) {
-		$clean = trim( $norm, '/' );
-		return ( '' === $clean ? 'index' : $clean ) . '.md';
-	}
-
-	// ── reading ───────────────────────────────────────────────────────────
-
-	/**
-	 * Stored Markdown for a request path, or null.
-	 *
-	 * @param string $path      Normalised request path.
-	 * @param string $home_path Home path.
-	 * @return string|null
-	 */
-	public function get( $path, $home_path = '' ) {
-		foreach ( self::candidates( $path, $home_path ) as $rel ) {
-			$file = $this->md_dir() . '/' . $rel;
-			if ( ! $this->inside( $file ) || ! is_file( $file ) || ! is_readable( $file ) ) {
-				continue;
-			}
-			$size = filesize( $file );
-			if ( false === $size || $size > self::MAX_FILE_BYTES ) {
-				continue;
-			}
-			$text = file_get_contents( $file ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- local file.
-			if ( false !== $text && '' !== trim( $text ) ) {
-				return $text;
-			}
-		}
-		return null;
-	}
-
-	/**
-	 * Is $file inside the md folder (after resolving symlinks)?
-	 *
-	 * @param string $file File path.
-	 * @return bool
-	 */
-	private function inside( $file ) {
-		$real_dir = realpath( $this->md_dir() );
-		$real     = realpath( $file );
-		if ( false === $real_dir || false === $real ) {
-			return false;
-		}
-		$real_dir = rtrim( str_replace( '\\', '/', $real_dir ), '/' ) . '/';
-		return 0 === strpos( str_replace( '\\', '/', $real ), $real_dir );
-	}
-
-	/**
-	 * Number of stored .md files.
-	 *
-	 * @return int
-	 */
-	public function count() {
-		$dir = $this->md_dir();
-		if ( ! is_dir( $dir ) ) {
-			return 0;
-		}
-		$n  = 0;
-		$it = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $dir, FilesystemIterator::SKIP_DOTS ) );
-		foreach ( $it as $f ) {
-			if ( $f->isFile() && strtolower( substr( $f->getFilename(), -3 ) ) === '.md' ) {
-				++$n;
-			}
-		}
-		return $n;
-	}
-
-	// ── writing ───────────────────────────────────────────────────────────
-
-	/**
-	 * Create the folders and the protection files.
-	 *
-	 * @return bool
-	 */
-	public function ensure() {
-		foreach ( array( $this->root, $this->md_dir() ) as $dir ) {
-			if ( ! is_dir( $dir ) && ! self::mkdir_p( $dir ) ) {
-				return false;
-			}
-			if ( ! file_exists( $dir . '/index.php' ) ) {
-				file_put_contents( $dir . '/index.php', "<?php\n// Silence is golden.\n" ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
-			}
-		}
-		$htaccess = $this->root . '/.htaccess';
-		if ( ! file_exists( $htaccess ) ) {
-			$rules = "# Relve Agent Ready: refined files are served by WordPress, never directly.\n"
-				. "<IfModule mod_authz_core.c>\n\tRequire all denied\n</IfModule>\n"
-				. "<IfModule !mod_authz_core.c>\n\tOrder deny,allow\n\tDeny from all\n</IfModule>\n";
-			file_put_contents( $htaccess, $rules ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
-		}
-		return true;
-	}
-
-	/**
-	 * Write one validated file.
-	 *
-	 * @param string $rel     Relative path from validate_entry().
-	 * @param string $content Markdown.
-	 * @return bool
-	 */
-	public function put( $rel, $content ) {
-		$check = self::validate_entry( 'md/' . $rel );
-		if ( 'store' !== $check['status'] || strlen( $content ) > self::MAX_FILE_BYTES ) {
-			return false;
-		}
-		$file = $this->md_dir() . '/' . $check['path'];
-		$dir  = dirname( $file );
-		if ( ! is_dir( $dir ) && ! self::mkdir_p( $dir ) ) {
-			return false;
-		}
-		if ( ! $this->inside( $dir ) && realpath( $dir ) !== realpath( $this->md_dir() ) ) {
-			return false;
-		}
-		return false !== file_put_contents( $file, $content ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
-	}
-
-	/**
-	 * Is there a stored file at this relative path?
-	 *
-	 * @param string $rel Relative path ("blog/my-post.md").
-	 * @return bool
-	 */
-	public function exists( $rel ) {
-		$check = self::validate_entry( 'md/' . $rel );
-		if ( 'store' !== $check['status'] ) {
-			return false;
-		}
-		$file = $this->md_dir() . '/' . $check['path'];
-		return is_file( $file ) && $this->inside( $file );
-	}
-
-	/**
-	 * Delete one stored file.
-	 *
-	 * @param string $rel Relative path.
-	 * @return bool Whether a file was deleted.
-	 */
-	public function delete( $rel ) {
-		if ( ! $this->exists( $rel ) ) {
-			return false;
-		}
-		return unlink( $this->md_dir() . '/' . $rel ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink
-	}
-
-	/**
-	 * Relative file the router looks up first for a URL path (the full path,
-	 * as uploads and the npm refine name them), or null for a bad path.
-	 *
-	 * @param string $path URL path ("/blog/my-post/").
-	 * @return string|null
-	 */
-	public static function rel_for_path( $path ) {
-		$list = self::candidates( $path );
-		return $list ? $list[0] : null;
-	}
-
-	/**
-	 * Delete every stored file (keeps the folder and its protection files).
-	 *
-	 * @return void
-	 */
-	public function clear() {
-		self::rmdir_r( $this->md_dir() );
-		$this->ensure();
-	}
-
-	/**
-	 * Delete the whole root folder (uninstall).
-	 *
-	 * @return void
-	 */
-	public function delete_all() {
-		self::rmdir_r( $this->root );
-	}
-
-	/**
-	 * Import a zip: replaces the stored files with the zip's md/ files.
-	 *
-	 * @param string $zip_file Path of the uploaded zip.
-	 * @return array { ok: bool, error: string, stored: int, skipped: int, rejected: int, reasons: string[] }
-	 */
-	public function import_zip( $zip_file ) {
-		$result = array(
-			'ok'       => false,
-			'error'    => '',
-			'stored'   => 0,
-			'skipped'  => 0,
-			'rejected' => 0,
-			'reasons'  => array(),
-		);
-		$size = is_file( $zip_file ) ? filesize( $zip_file ) : false;
-		if ( false === $size || 0 === $size ) {
-			$result['error'] = 'The upload is empty or missing.';
-			return $result;
-		}
-		if ( $size > self::MAX_ZIP_BYTES ) {
-			$result['error'] = 'The zip is larger than 20 MB.';
-			return $result;
-		}
-		$files = class_exists( 'ZipArchive' ) ? $this->read_zip_archive( $zip_file, $result ) : $this->read_zip_fallback( $zip_file, $result );
-		if ( null === $files ) {
-			return $result;
-		}
-		if ( ! $files ) {
-			$result['error'] = 'No .md files under md/ were found in the zip. Existing files were kept.';
-			return $result;
-		}
-		// Replace the set: a refined run is always complete.
-		$this->clear();
-		foreach ( $files as $rel => $content ) {
-			if ( $this->put( $rel, $content ) ) {
-				++$result['stored'];
-			} else {
-				++$result['rejected'];
-				$result['reasons'][] = $rel . ': could not be written';
-			}
-		}
-		$result['ok'] = $result['stored'] > 0;
-		if ( ! $result['ok'] ) {
-			$result['error'] = 'No file could be written. Check that wp-content/uploads is writable.';
-		}
-		return $result;
-	}
-
-	/**
-	 * Count one classified entry; return the content to keep or null.
-	 *
-	 * @param array  $check   From validate_entry().
-	 * @param string $name    Entry name.
-	 * @param int    $size    Uncompressed size.
-	 * @param array  $result  Result (counts updated).
-	 * @param int    $total   Running total of accepted bytes.
-	 * @return bool Whether to read the entry.
-	 */
-	private static function accept_entry( $check, $name, $size, &$result, &$total ) {
-		if ( 'skip' === $check['status'] ) {
-			if ( 'folder' !== $check['reason'] ) {
-				++$result['skipped'];
-			}
-			return false;
-		}
-		if ( 'reject' === $check['status'] ) {
-			++$result['rejected'];
-			$result['reasons'][] = $name . ': ' . $check['reason'];
-			return false;
-		}
-		if ( $size > self::MAX_FILE_BYTES ) {
-			++$result['rejected'];
-			$result['reasons'][] = $name . ': larger than 2 MB';
-			return false;
-		}
-		if ( $total + $size > self::MAX_TOTAL_BYTES ) {
-			++$result['rejected'];
-			$result['reasons'][] = $name . ': over the 100 MB total';
-			return false;
-		}
-		$total += $size;
-		return true;
-	}
-
-	/**
-	 * Check one entry's content: size and valid UTF-8.
-	 *
-	 * @param string|false $content Content.
-	 * @param string       $name    Entry name.
-	 * @param array        $result  Result.
-	 * @return bool
-	 */
-	private static function content_ok( $content, $name, &$result ) {
-		if ( false === $content || strlen( $content ) > self::MAX_FILE_BYTES ) {
-			++$result['rejected'];
-			$result['reasons'][] = $name . ': unreadable or too large';
-			return false;
-		}
-		if ( ! preg_match( '//u', $content ) ) {
-			++$result['rejected'];
-			$result['reasons'][] = $name . ': not UTF-8 text';
-			return false;
-		}
-		return true;
-	}
-
-	/**
-	 * Read entries with ZipArchive.
-	 *
-	 * @param string $zip_file Zip.
-	 * @param array  $result   Result.
-	 * @return array|null rel => content, or null on a fatal error.
-	 */
-	private function read_zip_archive( $zip_file, &$result ) {
-		$zip = new ZipArchive();
-		if ( true !== $zip->open( $zip_file ) ) {
-			$result['error'] = 'The file is not a valid zip.';
-			return null;
-		}
-		$files = array();
-		$total = 0;
-		$count = min( $zip->numFiles, self::MAX_ENTRIES );
-		for ( $i = 0; $i < $count; $i++ ) {
-			$stat = $zip->statIndex( $i );
-			if ( ! $stat ) {
-				continue;
-			}
-			$name  = $stat['name'];
-			$check = self::validate_entry( $name );
-			if ( ! self::accept_entry( $check, $name, (int) $stat['size'], $result, $total ) ) {
-				continue;
-			}
-			$content = $zip->getFromIndex( $i, self::MAX_FILE_BYTES + 1 );
-			if ( self::content_ok( $content, $name, $result ) ) {
-				$files[ $check['path'] ] = $content;
-			}
-		}
-		if ( $zip->numFiles > self::MAX_ENTRIES ) {
-			$result['reasons'][] = 'Only the first ' . self::MAX_ENTRIES . ' entries were read.';
-		}
-		$zip->close();
-		return $files;
-	}
-
-	/**
-	 * Read entries with WordPress's unzip_file() (PclZip) when ZipArchive is
-	 * missing: extract to a temp folder, then validate every extracted path
-	 * exactly as zip entry names.
-	 *
-	 * @param string $zip_file Zip.
-	 * @param array  $result   Result.
-	 * @return array|null
-	 */
-	private function read_zip_fallback( $zip_file, &$result ) {
-		if ( ! function_exists( 'unzip_file' ) || ! function_exists( 'WP_Filesystem' ) ) {
-			require_once ABSPATH . 'wp-admin/includes/file.php';
-		}
-		if ( ! WP_Filesystem() ) {
-			$result['error'] = 'Could not access the file system to unzip.';
-			return null;
-		}
-		$tmp = $this->root . '/tmp-' . wp_generate_password( 12, false );
-		if ( ! self::mkdir_p( $tmp ) ) {
-			$result['error'] = 'Could not create a temporary folder.';
-			return null;
-		}
-		$unzipped = unzip_file( $zip_file, $tmp );
-		if ( is_wp_error( $unzipped ) ) {
-			self::rmdir_r( $tmp );
-			$result['error'] = 'The file is not a valid zip.';
-			return null;
-		}
-		$files = array();
-		$total = 0;
-		$seen  = 0;
-		$it    = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $tmp, FilesystemIterator::SKIP_DOTS ) );
-		foreach ( $it as $f ) {
-			if ( ! $f->isFile() || ++$seen > self::MAX_ENTRIES ) {
-				continue;
-			}
-			$name  = ltrim( str_replace( '\\', '/', substr( $f->getPathname(), strlen( $tmp ) ) ), '/' );
-			$check = self::validate_entry( $name );
-			if ( ! self::accept_entry( $check, $name, (int) $f->getSize(), $result, $total ) ) {
-				continue;
-			}
-			$content = file_get_contents( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
-			if ( self::content_ok( $content, $name, $result ) ) {
-				$files[ $check['path'] ] = $content;
-			}
-		}
-		self::rmdir_r( $tmp );
-		return $files;
-	}
-
-	// ── filesystem helpers ────────────────────────────────────────────────
-
-	/**
-	 * Recursive mkdir.
-	 *
-	 * @param string $dir Folder.
-	 * @return bool
-	 */
-	private static function mkdir_p( $dir ) {
-		if ( function_exists( 'wp_mkdir_p' ) ) {
-			return wp_mkdir_p( $dir );
-		}
-		return is_dir( $dir ) || mkdir( $dir, 0755, true ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_mkdir
-	}
-
-	/**
-	 * Recursive delete. Does not follow symlinks.
-	 *
-	 * @param string $dir Folder.
-	 * @return void
-	 */
-	private static function rmdir_r( $dir ) {
-		if ( ! is_dir( $dir ) || is_link( $dir ) ) {
-			return;
-		}
-		$it = new RecursiveIteratorIterator(
-			new RecursiveDirectoryIterator( $dir, FilesystemIterator::SKIP_DOTS ),
-			RecursiveIteratorIterator::CHILD_FIRST
-		);
-		foreach ( $it as $f ) {
-			if ( $f->isDir() && ! $f->isLink() ) {
-				rmdir( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir
-			} else {
-				unlink( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink
-			}
-		}
-		rmdir( $dir ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir
-	}
-}
+<?php
+/**
+ * Store: refined Markdown files from Relve.
+ *
+ * Upload contract (agreed with the Relve runner, `venture.ts --zip`): the zip
+ * holds a top-level `md/` folder; inside it, `<url-path>.md` relative to the
+ * site root exactly as the npm refine writes them ("/" -> md/index.md,
+ * "/blog/my-post/" -> md/blog/my-post.md). `.json` sidecars and other files
+ * are skipped, not errors. Entries outside `md/`, absolute paths, `..` and
+ * oversized files are rejected.
+ *
+ * Files live in wp-content/uploads/relve-agent-ready/md/, behind an
+ * .htaccess "deny all" and index.php files. They are only ever read and sent
+ * as text, never included or executed.
+ *
+ * The validation and lookup helpers are pure and unit-tested; the class takes
+ * its base directory in the constructor so tests use a temp dir.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Refined-files store.
+ */
+class Relve_AR_Store {
+
+	/** Max zip size in bytes. */
+	const MAX_ZIP_BYTES = 20971520; // 20 MB.
+
+	/** Max size of one Markdown file in bytes. */
+	const MAX_FILE_BYTES = 2097152; // 2 MB.
+
+	/** Max total uncompressed bytes written from one zip. */
+	const MAX_TOTAL_BYTES = 104857600; // 100 MB.
+
+	/** Max entries read from one zip. */
+	const MAX_ENTRIES = 20000;
+
+	/** Root folder: .../uploads/relve-agent-ready. @var string */
+	private $root;
+
+	/**
+	 * Constructor.
+	 *
+	 * @param string|null $root Root folder; default uploads/relve-agent-ready.
+	 */
+	public function __construct( $root = null ) {
+		if ( null === $root ) {
+			$uploads = wp_upload_dir( null, false );
+			$root    = trailingslashit( $uploads['basedir'] ) . 'relve-agent-ready';
+		}
+		$this->root = rtrim( str_replace( '\\', '/', (string) $root ), '/' );
+	}
+
+	/**
+	 * Root folder.
+	 *
+	 * @return string
+	 */
+	public function root() {
+		return $this->root;
+	}
+
+	/**
+	 * Folder the .md files live in.
+	 *
+	 * @return string
+	 */
+	public function md_dir() {
+		return $this->root . '/md';
+	}
+
+	// ── validation (pure) ─────────────────────────────────────────────────
+
+	/**
+	 * Classify one zip entry name.
+	 *
+	 * @param string $name Entry name as stored in the zip.
+	 * @return array { status: store|skip|reject, path: relative path under md/ (store only), reason: string }
+	 */
+	public static function validate_entry( $name ) {
+		$name = (string) $name;
+		$skip = function ( $reason ) {
+			return array(
+				'status' => 'skip',
+				'path'   => '',
+				'reason' => $reason,
+			);
+		};
+		$reject = function ( $reason ) {
+			return array(
+				'status' => 'reject',
+				'path'   => '',
+				'reason' => $reason,
+			);
+		};
+		if ( '' === $name || false !== strpos( $name, "\0" ) || preg_match( '/[\x00-\x1F\x7F]/', $name ) ) {
+			return $reject( 'bad name' );
+		}
+		if ( false !== strpos( $name, '\\' ) ) {
+			return $reject( 'backslash in path' );
+		}
+		if ( '/' === $name[0] || preg_match( '#^[A-Za-z]:#', $name ) ) {
+			return $reject( 'absolute path' );
+		}
+		$segments = explode( '/', $name );
+		foreach ( $segments as $seg ) {
+			if ( '..' === $seg || '.' === $seg ) {
+				return $reject( 'path traversal' );
+			}
+		}
+		if ( '/' === substr( $name, -1 ) ) {
+			return $skip( 'folder' );
+		}
+		if ( 'md' !== $segments[0] || count( $segments ) < 2 ) {
+			return $reject( 'outside md/' );
+		}
+		$rel = implode( '/', array_slice( $segments, 1 ) );
+		if ( strtolower( substr( $rel, -3 ) ) !== '.md' ) {
+			return $skip( 'not a .md file' );
+		}
+		foreach ( array_slice( $segments, 1 ) as $seg ) {
+			if ( '' === $seg ) {
+				return $reject( 'empty path segment' );
+			}
+			if ( '.' === $seg[0] ) {
+				return $reject( 'hidden file' );
+			}
+			if ( preg_match( '#[<>:"|?*]#', $seg ) ) {
+				return $reject( 'bad character' );
+			}
+		}
+		if ( strlen( $rel ) > 1024 ) {
+			return $reject( 'path too long' );
+		}
+		return array(
+			'status' => 'store',
+			'path'   => $rel,
+			'reason' => '',
+		);
+	}
+
+	/**
+	 * Relative file names to try for a request path, most specific first:
+	 * the full path, then the path relative to the home path.
+	 *
+	 * @param string $path      Normalised request path ("/blog/my-post", "/").
+	 * @param string $home_path Home path without trailing slash ("" or "/blog").
+	 * @return string[] e.g. array( 'blog/my-post.md', 'my-post.md' ).
+	 */
+	public static function candidates( $path, $home_path = '' ) {
+		$norm = Relve_AR_Negotiation::normalize_path( $path );
+		if ( null === $norm ) {
+			return array();
+		}
+		$list = array( self::file_for( $norm ) );
+		if ( '' !== $home_path && ( $norm === $home_path || 0 === strpos( $norm, $home_path . '/' ) ) ) {
+			$rel    = substr( $norm, strlen( $home_path ) );
+			$list[] = self::file_for( '' === $rel ? '/' : $rel );
+		}
+		return array_values( array_unique( $list ) );
+	}
+
+	/**
+	 * "/" -> "index.md", "/a/b" -> "a/b.md".
+	 *
+	 * @param string $norm Normalised path.
+	 * @return string
+	 */
+	private static function file_for( $norm ) {
+		$clean = trim( $norm, '/' );
+		return ( '' === $clean ? 'index' : $clean ) . '.md';
+	}
+
+	// ── reading ───────────────────────────────────────────────────────────
+
+	/**
+	 * Stored Markdown for a request path, or null.
+	 *
+	 * @param string $path      Normalised request path.
+	 * @param string $home_path Home path.
+	 * @return string|null
+	 */
+	public function get( $path, $home_path = '' ) {
+		foreach ( self::candidates( $path, $home_path ) as $rel ) {
+			$file = $this->md_dir() . '/' . $rel;
+			if ( ! $this->inside( $file ) || ! is_file( $file ) || ! is_readable( $file ) ) {
+				continue;
+			}
+			$size = filesize( $file );
+			if ( false === $size || $size > self::MAX_FILE_BYTES ) {
+				continue;
+			}
+			$text = file_get_contents( $file ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- local file.
+			if ( false !== $text && '' !== trim( $text ) ) {
+				return $text;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Is $file inside the md folder (after resolving symlinks)?
+	 *
+	 * @param string $file File path.
+	 * @return bool
+	 */
+	private function inside( $file ) {
+		$real_dir = realpath( $this->md_dir() );
+		$real     = realpath( $file );
+		if ( false === $real_dir || false === $real ) {
+			return false;
+		}
+		$real_dir = rtrim( str_replace( '\\', '/', $real_dir ), '/' ) . '/';
+		return 0 === strpos( str_replace( '\\', '/', $real ), $real_dir );
+	}
+
+	/**
+	 * Number of stored .md files.
+	 *
+	 * @return int
+	 */
+	public function count() {
+		$dir = $this->md_dir();
+		if ( ! is_dir( $dir ) ) {
+			return 0;
+		}
+		$n  = 0;
+		$it = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $dir, FilesystemIterator::SKIP_DOTS ) );
+		foreach ( $it as $f ) {
+			if ( $f->isFile() && strtolower( substr( $f->getFilename(), -3 ) ) === '.md' ) {
+				++$n;
+			}
+		}
+		return $n;
+	}
+
+	// ── writing ───────────────────────────────────────────────────────────
+
+	/**
+	 * Create the folders and the protection files.
+	 *
+	 * @return bool
+	 */
+	public function ensure() {
+		foreach ( array( $this->root, $this->md_dir() ) as $dir ) {
+			if ( ! is_dir( $dir ) && ! self::mkdir_p( $dir ) ) {
+				return false;
+			}
+			if ( ! file_exists( $dir . '/index.php' ) ) {
+				file_put_contents( $dir . '/index.php', "<?php\n// Silence is golden.\n" ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
+			}
+		}
+		$htaccess = $this->root . '/.htaccess';
+		if ( ! file_exists( $htaccess ) ) {
+			$rules = "# Relve Agent Ready: refined files are served by WordPress, never directly.\n"
+				. "<IfModule mod_authz_core.c>\n\tRequire all denied\n</IfModule>\n"
+				. "<IfModule !mod_authz_core.c>\n\tOrder deny,allow\n\tDeny from all\n</IfModule>\n";
+			file_put_contents( $htaccess, $rules ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
+		}
+		return true;
+	}
+
+	/**
+	 * Write one validated file.
+	 *
+	 * @param string $rel     Relative path from validate_entry().
+	 * @param string $content Markdown.
+	 * @return bool
+	 */
+	public function put( $rel, $content ) {
+		$check = self::validate_entry( 'md/' . $rel );
+		if ( 'store' !== $check['status'] || strlen( $content ) > self::MAX_FILE_BYTES ) {
+			return false;
+		}
+		$file = $this->md_dir() . '/' . $check['path'];
+		$dir  = dirname( $file );
+		if ( ! is_dir( $dir ) && ! self::mkdir_p( $dir ) ) {
+			return false;
+		}
+		if ( ! $this->inside( $dir ) && realpath( $dir ) !== realpath( $this->md_dir() ) ) {
+			return false;
+		}
+		return false !== file_put_contents( $file, $content ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
+	}
+
+	/**
+	 * Is there a stored file at this relative path?
+	 *
+	 * @param string $rel Relative path ("blog/my-post.md").
+	 * @return bool
+	 */
+	public function exists( $rel ) {
+		$check = self::validate_entry( 'md/' . $rel );
+		if ( 'store' !== $check['status'] ) {
+			return false;
+		}
+		$file = $this->md_dir() . '/' . $check['path'];
+		return is_file( $file ) && $this->inside( $file );
+	}
+
+	/**
+	 * Delete one stored file.
+	 *
+	 * @param string $rel Relative path.
+	 * @return bool Whether a file was deleted.
+	 */
+	public function delete( $rel ) {
+		if ( ! $this->exists( $rel ) ) {
+			return false;
+		}
+		return unlink( $this->md_dir() . '/' . $rel ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink
+	}
+
+	/**
+	 * Relative file the router looks up first for a URL path (the full path,
+	 * as uploads and the npm refine name them), or null for a bad path.
+	 *
+	 * @param string $path URL path ("/blog/my-post/").
+	 * @return string|null
+	 */
+	public static function rel_for_path( $path ) {
+		$list = self::candidates( $path );
+		return $list ? $list[0] : null;
+	}
+
+	/**
+	 * Delete every stored file (keeps the folder and its protection files).
+	 *
+	 * @return void
+	 */
+	public function clear() {
+		self::rmdir_r( $this->md_dir() );
+		$this->ensure();
+	}
+
+	/**
+	 * Delete the whole root folder (uninstall).
+	 *
+	 * @return void
+	 */
+	public function delete_all() {
+		self::rmdir_r( $this->root );
+	}
+
+	/**
+	 * Import a zip: replaces the stored files with the zip's md/ files.
+	 *
+	 * @param string $zip_file Path of the uploaded zip.
+	 * @return array { ok: bool, error: string, stored: int, skipped: int, rejected: int, reasons: string[] }
+	 */
+	public function import_zip( $zip_file ) {
+		$result = array(
+			'ok'       => false,
+			'error'    => '',
+			'stored'   => 0,
+			'skipped'  => 0,
+			'rejected' => 0,
+			'reasons'  => array(),
+		);
+		$size = is_file( $zip_file ) ? filesize( $zip_file ) : false;
+		if ( false === $size || 0 === $size ) {
+			$result['error'] = 'The upload is empty or missing.';
+			return $result;
+		}
+		if ( $size > self::MAX_ZIP_BYTES ) {
+			$result['error'] = 'The zip is larger than 20 MB.';
+			return $result;
+		}
+		$files = class_exists( 'ZipArchive' ) ? $this->read_zip_archive( $zip_file, $result ) : $this->read_zip_fallback( $zip_file, $result );
+		if ( null === $files ) {
+			return $result;
+		}
+		if ( ! $files ) {
+			$result['error'] = 'No .md files under md/ were found in the zip. Existing files were kept.';
+			return $result;
+		}
+		// Replace the set: a refined run is always complete.
+		$this->clear();
+		foreach ( $files as $rel => $content ) {
+			if ( $this->put( $rel, $content ) ) {
+				++$result['stored'];
+			} else {
+				++$result['rejected'];
+				$result['reasons'][] = $rel . ': could not be written';
+			}
+		}
+		$result['ok'] = $result['stored'] > 0;
+		if ( ! $result['ok'] ) {
+			$result['error'] = 'No file could be written. Check that wp-content/uploads is writable.';
+		}
+		return $result;
+	}
+
+	/**
+	 * Count one classified entry; return the content to keep or null.
+	 *
+	 * @param array  $check   From validate_entry().
+	 * @param string $name    Entry name.
+	 * @param int    $size    Uncompressed size.
+	 * @param array  $result  Result (counts updated).
+	 * @param int    $total   Running total of accepted bytes.
+	 * @return bool Whether to read the entry.
+	 */
+	private static function accept_entry( $check, $name, $size, &$result, &$total ) {
+		if ( 'skip' === $check['status'] ) {
+			if ( 'folder' !== $check['reason'] ) {
+				++$result['skipped'];
+			}
+			return false;
+		}
+		if ( 'reject' === $check['status'] ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': ' . $check['reason'];
+			return false;
+		}
+		if ( $size > self::MAX_FILE_BYTES ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': larger than 2 MB';
+			return false;
+		}
+		if ( $total + $size > self::MAX_TOTAL_BYTES ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': over the 100 MB total';
+			return false;
+		}
+		$total += $size;
+		return true;
+	}
+
+	/**
+	 * Check one entry's content: size and valid UTF-8.
+	 *
+	 * @param string|false $content Content.
+	 * @param string       $name    Entry name.
+	 * @param array        $result  Result.
+	 * @return bool
+	 */
+	private static function content_ok( $content, $name, &$result ) {
+		if ( false === $content || strlen( $content ) > self::MAX_FILE_BYTES ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': unreadable or too large';
+			return false;
+		}
+		if ( ! preg_match( '//u', $content ) ) {
+			++$result['rejected'];
+			$result['reasons'][] = $name . ': not UTF-8 text';
+			return false;
+		}
+		return true;
+	}
+
+	/**
+	 * Read entries with ZipArchive.
+	 *
+	 * @param string $zip_file Zip.
+	 * @param array  $result   Result.
+	 * @return array|null rel => content, or null on a fatal error.
+	 */
+	private function read_zip_archive( $zip_file, &$result ) {
+		$zip = new ZipArchive();
+		if ( true !== $zip->open( $zip_file ) ) {
+			$result['error'] = 'The file is not a valid zip.';
+			return null;
+		}
+		$files = array();
+		$total = 0;
+		$count = min( $zip->numFiles, self::MAX_ENTRIES );
+		for ( $i = 0; $i < $count; $i++ ) {
+			$stat = $zip->statIndex( $i );
+			if ( ! $stat ) {
+				continue;
+			}
+			$name  = $stat['name'];
+			$check = self::validate_entry( $name );
+			if ( ! self::accept_entry( $check, $name, (int) $stat['size'], $result, $total ) ) {
+				continue;
+			}
+			$content = $zip->getFromIndex( $i, self::MAX_FILE_BYTES + 1 );
+			if ( self::content_ok( $content, $name, $result ) ) {
+				$files[ $check['path'] ] = $content;
+			}
+		}
+		if ( $zip->numFiles > self::MAX_ENTRIES ) {
+			$result['reasons'][] = 'Only the first ' . self::MAX_ENTRIES . ' entries were read.';
+		}
+		$zip->close();
+		return $files;
+	}
+
+	/**
+	 * Read entries with WordPress's unzip_file() (PclZip) when ZipArchive is
+	 * missing: extract to a temp folder, then validate every extracted path
+	 * exactly as zip entry names.
+	 *
+	 * @param string $zip_file Zip.
+	 * @param array  $result   Result.
+	 * @return array|null
+	 */
+	private function read_zip_fallback( $zip_file, &$result ) {
+		if ( ! function_exists( 'unzip_file' ) || ! function_exists( 'WP_Filesystem' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/file.php';
+		}
+		if ( ! WP_Filesystem() ) {
+			$result['error'] = 'Could not access the file system to unzip.';
+			return null;
+		}
+		$tmp = $this->root . '/tmp-' . wp_generate_password( 12, false );
+		if ( ! self::mkdir_p( $tmp ) ) {
+			$result['error'] = 'Could not create a temporary folder.';
+			return null;
+		}
+		$unzipped = unzip_file( $zip_file, $tmp );
+		if ( is_wp_error( $unzipped ) ) {
+			self::rmdir_r( $tmp );
+			$result['error'] = 'The file is not a valid zip.';
+			return null;
+		}
+		$files = array();
+		$total = 0;
+		$seen  = 0;
+		$it    = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $tmp, FilesystemIterator::SKIP_DOTS ) );
+		foreach ( $it as $f ) {
+			if ( ! $f->isFile() || ++$seen > self::MAX_ENTRIES ) {
+				continue;
+			}
+			$name  = ltrim( str_replace( '\\', '/', substr( $f->getPathname(), strlen( $tmp ) ) ), '/' );
+			$check = self::validate_entry( $name );
+			if ( ! self::accept_entry( $check, $name, (int) $f->getSize(), $result, $total ) ) {
+				continue;
+			}
+			$content = file_get_contents( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
+			if ( self::content_ok( $content, $name, $result ) ) {
+				$files[ $check['path'] ] = $content;
+			}
+		}
+		self::rmdir_r( $tmp );
+		return $files;
+	}
+
+	// ── filesystem helpers ────────────────────────────────────────────────
+
+	/**
+	 * Recursive mkdir.
+	 *
+	 * @param string $dir Folder.
+	 * @return bool
+	 */
+	private static function mkdir_p( $dir ) {
+		if ( function_exists( 'wp_mkdir_p' ) ) {
+			return wp_mkdir_p( $dir );
+		}
+		return is_dir( $dir ) || mkdir( $dir, 0755, true ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_mkdir
+	}
+
+	/**
+	 * Recursive delete. Does not follow symlinks.
+	 *
+	 * @param string $dir Folder.
+	 * @return void
+	 */
+	private static function rmdir_r( $dir ) {
+		if ( ! is_dir( $dir ) || is_link( $dir ) ) {
+			return;
+		}
+		$it = new RecursiveIteratorIterator(
+			new RecursiveDirectoryIterator( $dir, FilesystemIterator::SKIP_DOTS ),
+			RecursiveIteratorIterator::CHILD_FIRST
+		);
+		foreach ( $it as $f ) {
+			if ( $f->isDir() && ! $f->isLink() ) {
+				rmdir( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir
+			} else {
+				unlink( $f->getPathname() ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink
+			}
+		}
+		rmdir( $dir ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir
+	}
+}