Skip to content

armgit / Vvveb

Public Imported from GitHub
0

Powerful and easy to use cms to build websites, blogs or ecommerce stores.

114 KB
Raw Blame
<?php

/**
 * Vvveb
 *
 * Copyright (C) 2022  Ziadin Givan
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 */

namespace Vvveb\Controller;

use Throwable;
use function Vvveb\config;
use function Vvveb\humanReadable;
use function Vvveb\rrmdir;
use function Vvveb\sanitizeFileName;
use function Vvveb\slugify;
use Vvveb\System\Cache;
use Vvveb\System\Db;
use Vvveb\System\Event;
use Vvveb\System\MCP;
use Vvveb\System\Session;
use Vvveb\System\Sites;
use Vvveb\System\Sqlp\Sqlp;
use Vvveb\System\Traits\Media as MediaLibraryTrait;
use function Vvveb\url;

// Routine-failure taxonomy (must load before the editor so FsError can extend it)
require_once __DIR__ . '/../tool_error.php';
// Integrated str_replace_editor filesystem tool
require_once __DIR__ . '/../str_replace_editor.php';

#[\AllowDynamicProperties]
class Index extends Base {
	use MediaLibraryTrait;

	/** @var string Media library root for the file cores below. */
	protected string $dirMedia = DIR_MEDIA;

	/** @var string MCP protocol version */
	private string $version = '2025-11-25';

	/** @var int Maximum bytes returned for a single file read */
	private const READ_MAX_BYTES = 5242880; // 5MB

	/** @var int Maximum bytes written in a single write call */
	private const WRITE_MAX_BYTES = 4194304; // 4MB

	/** @var int Maximum combined stdout+stderr bytes returned by bash */
	private const BASH_MAX_OUTPUT = 262144; // 256KB

	/** @var int Maximum decoded bytes accepted by media upload (also capped by the server upload_max_filesize) */
	private const MEDIA_UPLOAD_MAX_BYTES = 4194304; // 4MB

	/** Directories never traversed by grep/glob */
	private const SKIP_DIRS = ['.git', '.svn', 'node_modules'];

	/**
	 * Map of coding harness tool names to controller methods.
	 * Tools defined in tools.php that are not listed here fall back to
	 * their execute_callback (if callable).
	 *
	 * @var array<string, string>
	 */
	private array $toolHandlers = [
		'crud'               => 'toolCrud',
		'crud_models'        => 'toolCrudModels',
		'admin'              => 'toolAdmin',
		'media'              => 'toolMedia',
		'read'               => 'toolRead', //fallback for str_replace_editor
		'write'              => 'toolWrite', //fallback for str_replace_editor
		'glob'               => 'toolGlob', //fallback for disabled bash
		'grep'               => 'toolGrep', //fallback for disabled bash
		'bash'               => 'toolBash', //if shell exec available
		'bash_sub'           => 'toolBashSub', //falback if shell exec not available
		'powershell'         => 'toolPowershell', //only available on windows
		'str_replace_editor' => 'toolStrReplaceEditor',
		'database_query'     => 'toolDatabaseRunQuery',
	];

	/**
	 * Initializes session from MCP session header.
	 */
	public function __construct() {
		$headers   = getallheaders();
		$sessionId = $headers['Mcp-Session-Id'] ?? $_SERVER['Mcp-Session-Id'] ?? null;

		if ($sessionId) {
			$this->session  = Session::getInstance(['id' => $sessionId, 'use_cookies' => 0]);
		}

		$disable            = MCP :: disabledTools();
		$this->toolHandlers = array_diff_key($this->toolHandlers, array_flip($disable));
	}

	/**
	 * List available tools.
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return array{tools: mixed}
	 */
	public function tools_list(array $params): array {
		$cache = Cache::getInstance();
		$self  = $this;
		//version the key on the registry sources: a schema or handler deploy
		//must surface immediately instead of lingering for the 3-day TTL. A
		//stale tools-list previously hid a newly added tool for days while
		//the files were already correct.
		$toolsKey = 'tools-list-' . md5((string)@filemtime(__DIR__ . '/../tools.php') . "\n" . implode(',', array_keys($this->toolHandlers)) . "\n" . (config('mcp.tools.db_write', false) === true ? 'w1' : 'w0'));
		$tools    = $cache->cache(APP, $toolsKey, function() use ($self) {
			$tools = \Vvveb\System\MCP::annotateTools(include (__DIR__ . '/../tools.php'));

			$tools = array_values(array_filter(
				$tools,
				fn ($tool) => isset($this->toolHandlers[$tool['name'] ?? ''])
			));

			//hide the coding harness tools entirely when disabled
			if (config('mcp.tools.enabled', true) !== true) {
				$tools = array_values(array_filter(
					$tools,
					fn ($tool) => !isset($this->toolHandlers[$tool['name'] ?? ''])
				));
			}

			[$tools] = Event :: trigger('MCP', 'tools/list', $tools);

			return $tools;
		}, 259200);

		return ['tools' => $tools];
	}

	/**
	 * Execute a tool call.
	 *
	 * Dispatches to the matching coding harness tool handler (read, write,
	 * bash, glob, grep, database_run_query, str_replace_editor ...) or falls back to the
	 * tool's execute_callback when one is registered. Results are wrapped in
	 * an MCP tool result envelope; thrown errors are converted to isError
	 * results instead of protocol errors.
	 *
	 * @param string               $method JSON-RPC method (always "tools/call")
	 * @param array<string, mixed> $params {name: string, arguments: array}
	 *
	 * @return array{content: array<int, mixed>, isError: bool, structuredContent?: mixed}
	 */
	public function tools_call(string $method, array $params): array {
		$name      = $params['name'] ?? '';
		$arguments = $params['arguments'] ?? [];

		if ($name === '') {
			return $this->errorResult('Missing tool name');
		}

		//master switch for the coding harness tool set
		if (config('mcp.tools.enabled', true) !== true) {
			return $this->errorResult('Coding tools are disabled (config mcp.tools.enabled)');
		}

		$arguments = is_array($arguments) ? $arguments : [];

		try {
			//resolve tool definition from the registry
			$tool = null;

			foreach ($this->tools_list([])['tools'] as $toolDef) {
				if (($toolDef['name'] ?? null) === $name) {
					$tool = $toolDef;
					break;
				}
			}

			if ($tool === null) {
				return $this->errorResult("Unknown tool: $name");
			}

			$this->validateRequiredArgs($name, $arguments, $tool);

			//dispatch to dedicated handler or registered callback
			if (isset($this->toolHandlers[$name]) && method_exists($this, $this->toolHandlers[$name])) {
				$result = $this->{$this->toolHandlers[$name]}($arguments);
			} elseif (!empty($tool['execute_callback']) && is_callable($tool['execute_callback'])) {
				$result = $tool['execute_callback']($arguments);
			} else {
				return $this->errorResult("No handler registered for tool: $name");
			}

			return $this->textResult($result);
		} catch (Throwable $e) {
			//Routine tool failures (missing file, bad args, unknown model)
			//are answers, not crashes: the model gets the message alone and
			//nothing is logged, so agent trial-and-error doesn't flood the
			//server log. Only unexpected failures (IO/DB/environment/coding
			//bugs) log with traces under DEBUG. (This also drops a literal
			//'\n' separator bug - single quotes never escape.)
			$routine = $e instanceof \McpToolError || $e instanceof \InvalidArgumentException;

			if (DEBUG && !$routine) {
				error_log('mcp tools/call ' . $name . ' failed: ' . $e::class . ': ' . $e->getMessage() . "\n" . $e->getTraceAsString());
			}

			return $this->errorResult(self::trimToolError($e->getMessage() ?: $e::class));
		}
	}

	/* -----------------------------------------------------------------
	 * Coding harness tools
	 * ----------------------------------------------------------------- */

	/**
	 * read tool: return file contents with line numbers, optionally sliced.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{content: string, totalLines: int}
	 */
	public function toolRead(array $args): array {
		$path    = $this->resolvePath((string)($args['path'] ?? ''));
		$offset  = max(1, (int)($args['offset'] ?? 1));
		$limit   = max(1, min(10000, (int)($args['limit'] ?? 2000)));

		if (!is_file($path)) {
			throw new \McpToolError("File not found: {$args['path']}");
		}

		$size = filesize($path);

		if ($size > self::READ_MAX_BYTES) {
			throw new \McpToolError('File exceeds max readable size (' . self::READ_MAX_BYTES . ' bytes): ' . $size);
		}

		$content = file_get_contents($path);

		if ($content === false) {
			throw new \RuntimeException("Failed reading file: {$args['path']}");
		}

		if (str_contains($content, "\0")) {
			throw new \McpToolError('File appears to be binary and cannot be displayed as text');
		}

		$lines = preg_split('/(\r\n|\n|\r)/', $content);
		$total = count($lines);
		$slice = array_slice($lines, $offset - 1, $limit);

		$output = '';

		foreach ($slice as $i => $line) {
			$output .= sprintf("%6d\t%s\n", $offset + $i, $line);
		}

		if ($total > $offset - 1 + count($slice)) {
			$output .= "\n[Output truncated to $limit lines starting at line $offset. Total lines: $total. "
				. 'Use offset/limit parameters to read more.]';
		}

		return ['content' => $output, 'totalLines' => $total];
	}

	/**
	 * write tool: create or overwrite a file, creating parent directories.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{success: bool, bytes: int, created: bool}
	 */
	public function toolWrite(array $args): array {
		//target may not exist yet, only its parent directory has to
		$path    = $this->resolvePath((string)($args['path'] ?? ''), false);
		$content = (string)($args['content'] ?? '');

		if (strlen($content) > self::WRITE_MAX_BYTES) {
			throw new \RuntimeException('Content exceeds max write size (' . self::WRITE_MAX_BYTES . ' bytes)');
		}

		$created = !is_file($path);
		$dir     = dirname($path);

		if (!is_dir($dir) && !@mkdir($dir, 0755, true)) {
			throw new \RuntimeException("Failed creating directory: $dir");
		}

		if (@file_put_contents($path, $content) === false) {
			throw new \RuntimeException("Failed writing file: {$args['path']}");
		}

		@chmod($path, 0664 & ~umask());

		return ['success' => true, 'bytes' => strlen($content), 'created' => $created];
	}

	/**
	 * bash tool: execute a shell command with timeout and output caps.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{stdout: string, stderr: string, exitCode: int, timedOut: bool}
	 */
	public function toolBash(array $args): array {
		$command = trim((string)($args['command'] ?? ''));

		if ($command === '') {
			throw new \InvalidArgumentException('command must not be empty');
		}

		// bash is the native tool (proc_open). If shell_exec/proc_open are disabled,
		// transparently fall back to the pure-PHP bash_sub (BashBox) so callers
		// still get a result. bash_sub remains a distinct pure-PHP tool.
		if (!MCP :: isShellAvailable()) {
			$fallback = $this->toolBashSub($args);
			// keep native bash response shape but indicate fallback
			$fallback['engine'] .= ' (fallback from bash)';

			return $fallback;
		}

		$timeout = max(1, min(120, (int)($args['timeout'] ?? 30)));
		$cwd     = isset($args['cwd']) && $args['cwd'] !== ''
			? $this->resolvePath((string)$args['cwd'], true)
			: $this->toolRoot();

		$descriptors = [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']];
		$process     = proc_open('exec /bin/bash -lc ' . escapeshellarg($command), $descriptors, $pipes, $cwd);

		if (!is_resource($process)) {
			throw new \RuntimeException('proc_open() failed — check that bash exists and open_basedir allows execution');
		}

		stream_set_blocking($pipes[1], false);
		stream_set_blocking($pipes[2], false);
		fclose($pipes[0]);

		$deadline  = microtime(true) + $timeout;
		$stdout    = '';
		$stderr    = '';
		$timedOut  = false;
		$truncated = false;

		while (true) {
			$read   = [$pipes[1], $pipes[2]];
			$write  = null;
			$except = null;

			if (stream_select($read, $write, $except, 0, 200000) === false) {
				break;
			}

			foreach ($read as $stream) {
				$data = fread($stream, 65536);

				if ($data === false || $data === '') {
					continue;
				}

				if ($stream === $pipes[1]) {
					$stdout .= $data;
				} else {
					$stderr .= $data;
				}
			}

			$status = proc_get_status($process);

			if (strlen($stdout) + strlen($stderr) > self::BASH_MAX_OUTPUT) {
				$truncated = true;
				proc_terminate($process, 9);
				break;
			}

			if (!$status['running']) {
				break;
			}

			if (microtime(true) > $deadline) {
				$timedOut = true;
				proc_terminate($process, 9);
				break;
			}
		}

		//drain what's left in the pipes after the process ended
		while (($line = fgets($pipes[1])) !== false) {
			$stdout .= $line;
		}

		while (($line = fgets($pipes[2])) !== false) {
			$stderr .= $line;
		}

		fclose($pipes[1]);
		fclose($pipes[2]);

		$exitCode = proc_close($process);

		if ($timedOut) {
			$exitCode = $exitCode ?: 124; // 124 = timeout convention
		}

		if ($truncated) {
			$stdout = mb_strcut($stdout, 0, self::BASH_MAX_OUTPUT / 2);
			$stderr = mb_strcut($stderr, 0, self::BASH_MAX_OUTPUT / 2);
			$stdout .= '\n[output truncated]';
		}

		return ['stdout' => $stdout, 'stderr' => $stderr, 'exitCode' => (int)$exitCode, 'timedOut' => $timedOut];
	}

	/**
	 * bash_sub tool: sandboxed pure-PHP bash via BashBox (shipfastlabs/bashbox).
	 *
	 * Used when php shell_exec/proc_open are disabled. Every command is a PHP class,
	 * filesystem is virtualised via ReadWriteFs sandboxed to toolRoot(). No proc_open/exec/shell_exec
	 * is invoked. Falls back to native bash if BashBox is not installed but shell is available.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{stdout: string, stderr: string, exitCode: int, timedOut: bool, engine: string, truncated?: bool}
	 */
	public function toolBashSub(array $args): array {
		$command = trim((string)($args['command'] ?? ''));
		if ($command === '') {
			throw new \InvalidArgumentException('command must not be empty');
		}
		$timeout = max(1, min(120, (int)($args['timeout'] ?? 30)));
		$cwdHost = isset($args['cwd']) && $args['cwd'] !== '' ? $this->resolvePath((string)$args['cwd'], true) : $this->toolRoot();
		$root    = $this->toolRoot();
		// virtual cwd is sandbox-relative, ReadWriteFs maps "/" -> $root
		$virtualCwd = '/' . ltrim(substr($cwdHost, strlen($root)), '/');
		if ($virtualCwd === '/') {
			$virtualCwd = '/';
		}
		$shellAvailable = MCP :: isShellAvailable();
		// If BashBox not available, gracefully fall back to native bash when possible
		if (!class_exists('\\BashBox\\Bash')) {
			if ($shellAvailable) {
				$fallback           = $this->toolBash($args);
				$fallback['engine'] = 'native (bashbox missing)';

				return $fallback;
			}

			throw new \RuntimeException('BashBox not installed (shipfastlabs/bashbox) and native shell is disabled. Run: composer require shipfastlabs/bashbox');
		}

		try {
			$fs = new \BashBox\Filesystem\ReadWriteFs($root);
		} catch (\Throwable $e) {
			throw new \RuntimeException('Failed to init BashBox filesystem: ' . $e->getMessage(), 0, $e);
		}
		$limits = new \BashBox\Limits(
			maxOutputSize: self::BASH_MAX_OUTPUT,
			maxCommandCount: 10000,
			maxLoopIterations: 10000,
			maxStringLength: self::BASH_MAX_OUTPUT,
		);
		$bashOptions = new \BashBox\BashOptions(
			fs: $fs,
			cwd: $virtualCwd,
			limits: $limits,
		);
		$bash        = new \BashBox\Bash($bashOptions);
		$execOptions = new \BashBox\ExecOptions(cwd: $virtualCwd);

		// BashBox has no timeout; enforce via maxCommandCount/limits. We still respect $timeout for API parity.
		try {
			$result = $bash->exec($command, $execOptions);
		} catch (\Throwable $e) {
			return [
				'stdout'   => '',
				'stderr'   => 'bashbox error: ' . $e->getMessage(),
				'exitCode' => 127,
				'timedOut' => false,
				'engine'   => 'bashbox',
			];
		}
		$stdout    = $result->stdout;
		$stderr    = $result->stderr;
		$exitCode  = $result->exitCode;
		$truncated = false;
		if (strlen($stdout) + strlen($stderr) > self::BASH_MAX_OUTPUT) {
			$stdout = mb_strcut($stdout, 0, (int)(self::BASH_MAX_OUTPUT / 2));
			$stderr = mb_strcut($stderr, 0, (int)(self::BASH_MAX_OUTPUT / 2));
			$stdout .= "\n[output truncated]";
			$truncated = true;
		}

		return [
			'stdout'    => $stdout,
			'stderr'    => $stderr,
			'exitCode'  => $exitCode,
			'timedOut'  => false,
			'engine'    => $shellAvailable ? 'bashbox (shell available, pure PHP)' : 'bashbox',
			'truncated' => $truncated,
		];
	}

	/**
	 * powershell tool: execute a PowerShell command (Windows-only).
	 *
	 * Native counterpart to bash for Windows servers where /bin/bash is
	 * unavailable. Prefers pwsh.exe (PowerShell 7+) and falls back to the
	 * inbox powershell.exe (Windows PowerShell 5.1). Uses a polling read
	 * loop instead of stream_select() which is socket-only on Windows.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{stdout: string, stderr: string, exitCode: int, timedOut: bool, engine: string}
	 */
	public function toolPowershell(array $args): array {
		$command = trim((string)($args['command'] ?? ''));

		if ($command === '') {
			throw new \InvalidArgumentException('command must not be empty');
		}

		if (!MCP :: isShellAvailable()) {
			throw new \RuntimeException('Native shell execution is disabled (proc_open/shell_exec disabled) — powershell tool requires proc_open');
		}

		$powershell = $this->findPowershell();

		if ($powershell === null) {
			throw new \RuntimeException('No PowerShell executable found (looked for pwsh/powershell). On Windows PowerShell is built in; on Linux/macOS install PowerShell 7 (pwsh) to use this tool.');
		}

		$timeout = max(1, min(120, (int)($args['timeout'] ?? 30)));
		$cwd     = isset($args['cwd']) && $args['cwd'] !== ''
			? $this->resolvePath((string)$args['cwd'], true)
			: $this->toolRoot();

		$shellCommand = '"' . $powershell . '" -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command ' . escapeshellarg($command);

		$descriptors = [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']];
		$process     = proc_open($shellCommand, $descriptors, $pipes, $cwd);

		if (!is_resource($process)) {
			throw new \RuntimeException('proc_open() failed — check that PowerShell exists and open_basedir allows execution');
		}

		stream_set_blocking($pipes[1], false);
		stream_set_blocking($pipes[2], false);
		fclose($pipes[0]);

		$deadline  = microtime(true) + $timeout;
		$stdout    = '';
		$stderr    = '';
		$timedOut  = false;
		$truncated = false;

		//polling loop (no stream_select — on Windows it only supports sockets).
		while (true) {
			$outChunk = fread($pipes[1], 65536);
			$errChunk = fread($pipes[2], 65536);

			if ($outChunk !== false && $outChunk !== '') {
				$stdout .= $outChunk;
			}

			if ($errChunk !== false && $errChunk !== '') {
				$stderr .= $errChunk;
			}

			$status = proc_get_status($process);

			if (strlen($stdout) + strlen($stderr) > self::BASH_MAX_OUTPUT) {
				$truncated = true;
				proc_terminate($process, 9);
				break;
			}

			if (!$status['running']) {
				break;
			}

			if (microtime(true) > $deadline) {
				$timedOut = true;
				proc_terminate($process, 9);
				break;
			}

			usleep(100000); // 100ms poll interval
		}

		//drain what's left in the pipes after the process ended
		while (($line = fgets($pipes[1])) !== false) {
			$stdout .= $line;
		}

		while (($line = fgets($pipes[2])) !== false) {
			$stderr .= $line;
		}

		fclose($pipes[1]);
		fclose($pipes[2]);

		$exitCode = proc_close($process);

		if ($timedOut) {
			$exitCode = $exitCode ?: 124; // 124 = timeout convention
		}

		if ($truncated) {
			$stdout = mb_strcut($stdout, 0, self::BASH_MAX_OUTPUT / 2);
			$stderr = mb_strcut($stderr, 0, self::BASH_MAX_OUTPUT / 2);
			$stdout .= '\n[output truncated]';
		}

		return [
			'stdout'   => $stdout,
			'stderr'   => $stderr,
			'exitCode' => (int)$exitCode,
			'timedOut' => $timedOut,
			'engine'   => basename(str_replace('\\', '/', $powershell)),
		];
	}

	/**
	 * Whether the server OS is Windows.
	 */
	private function isWindows(): bool {
		return PHP_OS_FAMILY === 'Windows' || DIRECTORY_SEPARATOR === '\\';
	}

	/**
	 * Locate a PowerShell executable.
	 *
	 * On Windows prefers pwsh.exe (PowerShell 7+) then falls back to the
	 * inbox powershell.exe (5.1). On other systems looks for pwsh/powershell
	 * (PowerShell Core). Returns the full path when resolvable via where/command -v,
	 * otherwise the bare executable name on Windows (resolved via PATH by proc_open)
	 * or null when nothing is available.
	 */
	private function findPowershell(): ?string {
		$candidates = $this->isWindows()
			? ['pwsh.exe', 'powershell.exe']
			: ['pwsh', 'powershell'];

		$disabled     = array_filter(array_map('trim', explode(',', (string)ini_get('disable_functions'))));
		$disabled     = array_map('strtolower', $disabled);
		$canShellExec = function_exists('shell_exec') && !in_array('shell_exec', $disabled, true);

		if ($canShellExec) {
			$finder  = $this->isWindows() ? 'where' : 'command -v';
			$devNull = $this->isWindows() ? 'NUL' : '/dev/null';

			foreach ($candidates as $bin) {
				$out   = trim((string)@$this->shellExecQuiet("$finder $bin 2>$devNull"));
				$first = strtok($out, "\r\n");

				if ($first !== false && trim($first) !== '') {
					return trim($first);
				}
			}
		}

		//shell_exec unavailable or lookup failed: on Windows fall back to the
		//inbox executable name and let proc_open resolve it via PATH.
		if ($this->isWindows()) {
			return 'powershell.exe';
		}

		return null;
	}

	/**
	 * Quiet shell_exec wrapper (suppressed errors, always returns string).
	 *
	 * @param string $command
	 */
	private function shellExecQuiet(string $command): string {
		$result = @shell_exec($command);

		return is_string($result) ? $result : '';
	}

	/**
	 * glob tool: find files by pattern relative to the site root.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{matches: list<string>, count: int}
	 */
	public function toolGlob(array $args): array {
		$pattern = (string)($args['pattern'] ?? '');
		$limit   = max(1, min(5000, (int)($args['limit'] ?? 500)));

		if ($pattern === '') {
			throw new \InvalidArgumentException('pattern must not be empty');
		}

		$root = $this->toolRoot();

		//normalize to a root-relative body. Absolute patterns must already
		//sit inside the sandbox (rejected, never remapped); anything else is
		//relative to the site root.
		if ($pattern[0] === '/') {
			if ($pattern !== $root && !str_starts_with($pattern, $root . '/')) {
				throw new \McpToolError('Pattern resolves outside the site root');
			}
			$body = ltrim(substr($pattern, strlen($root)), '/');
		} else {
			$body = ltrim(str_replace('\\', '/', $pattern), '/');
		}

		//leading ./ segments are noise for matching (relative hits never
		//carry them) but would break the recursive regex anchor
		$body = preg_replace('#^(?:\./)+#', '', $body);

		//only the static leading segments (no wildcard chars) locate the
		//search base - the old realpath(dirname($target)) check broke on any
		//wildcard (dirname('public/**/*') is not a real path) and rejected
		//every relative pattern. '..' climbs above the root are rejected;
		//deeper '..' collapse lexically exactly like resolvePath().
		$segments  = $body === '' ? [] : explode('/', $body);
		$canonical = [];

		foreach ($segments as $seg) {
			if (strpbrk($seg, '*?[{') !== false) {
				break;
			}
			if ($seg === '' || $seg === '.') {
				continue;
			}
			if ($seg === '..') {
				if (!$canonical) {
					throw new \McpToolError('Pattern resolves outside the site root');
				}
				array_pop($canonical);
				continue;
			}
			$canonical[] = $seg;
		}

		$baseAbs = $root . ($canonical ? '/' . implode('/', $canonical) : '');

		//existing bases must really live inside the sandbox (symlink check)
		$realBase = realpath($baseAbs);

		if ($realBase !== false && $realBase !== $root && !str_starts_with($realBase, $root . '/')) {
			throw new \McpToolError('Pattern resolves outside the site root');
		}

		$results = [];

		//native glob() treats a double star as a single-level star, so
		//double-star patterns walk recursively and match per file instead.
		if (str_contains($body, '**')) {
			$results = $this->globRecursive($realBase !== false ? $realBase : $baseAbs, $root, $body, $limit);
		} else {
			$matches = is_dir($baseAbs) ? (glob($root . '/' . $body, GLOB_BRACE | GLOB_NOSORT) ?: []) : [];
			sort($matches);

			foreach ($matches as $match) {
				if (count($results) >= $limit) {
					break;
				}
				//per-match containment: a symlinked match must not escape
				$real = realpath($match);

				if ($real === false || ($real !== $root && !str_starts_with($real, $root . '/'))) {
					continue;
				}
				$results[] = ltrim(substr($real, strlen($root)), '/');
			}
		}

		return ['matches' => $results, 'count' => count($results)];
	}

	/**
	 * Recursive double-star glob: walk $walkRoot and match each file's
	 * root-relative path against the glob body (a double star spans zero or
	 * more directories).
	 *
	 * @param string $walkRoot existing search base, already sandbox-checked
	 * @param string $root
	 * @param string $body
	 * @param int    $limit
	 *
	 * @return list<string> root-relative matches, sorted, capped at $limit
	 */
	private function globRecursive(string $walkRoot, string $root, string $body, int $limit): array {
		$results = [];

		if (!is_dir($walkRoot)) {
			return $results;
		}

		$regex     = $this->globPatternToRegex($body);
		$prefixLen = strlen($root) + 1;
		$iterator  = new \RecursiveIteratorIterator(
			new \RecursiveCallbackFilterIterator(
				new \RecursiveDirectoryIterator($walkRoot, \FilesystemIterator::SKIP_DOTS),
				fn ($current) => !$current->isDir() || !in_array($current->getFilename(), self::SKIP_DIRS, true)
			),
			\RecursiveIteratorIterator::LEAVES_ONLY
		);
		$scanned = 0;

		foreach ($iterator as $file) {
			if (!$file instanceof \SplFileInfo || !$file->isFile()) {
				continue;
			}
			if (++$scanned > 50000) {
				break; // runaway guard on huge trees; limit already caps output
			}
			$rel = str_replace('\\', '/', substr($file->getPathname(), $prefixLen));

			if (!preg_match($regex, $rel)) {
				continue;
			}
			$results[] = $rel;

			if (count($results) >= $limit) {
				break;
			}
		}
		sort($results);

		return $results;
	}

	/**
	 * Translate a glob body to a PCRE pattern over /-separated relative
	 * paths: a double star plus slash spans zero or more directories, a
	 * single star never crosses /.
	 *
	 * @param string $glob
	 */
	private function globPatternToRegex(string $glob): string {
		$out = '';
		$len = strlen($glob);
		$i   = 0;

		while ($i < $len) {
			$c = $glob[$i];

			if ($c === '*') {
				$run = 0;

				while (($glob[$i] ?? '') === '*') {
					$run++;
					$i++;
				}
				if ($run >= 2 && ($glob[$i] ?? '') === '/') {
					$i++;
					$out .= '(.*/)?';
				} elseif ($run >= 2) {
					$out .= '.*';
				} else {
					$out .= '[^/]*';
				}
			} elseif ($c === '?') {
				$out .= '[^/]';
				$i++;
			} elseif ($c === '[') {
				//copy the character class through, translating [!...] to [^...]
				$cls = '[';
				$i++;

				if (($glob[$i] ?? '') === '!') {
					$cls .= '^';
					$i++;
				}
				while ($i < $len && $glob[$i] !== ']') {
					$cls .= $glob[$i] === '\\' ? '\\\\' : $glob[$i];
					$i++;
				}
				$cls .= ']';
				$i++;
				$out .= $cls;
			} elseif ($c === '{') {
				//{a,b} alternation: split top-level commas, recurse per branch
				$depth = 1;
				$j     = $i + 1;
				$alts  = [''];

				while ($j < $len && $depth > 0) {
					$ch = $glob[$j];

					if ($ch === '{') {
						$depth++;
						$alts[count($alts) - 1] .= $ch;
					} elseif ($ch === '}') {
						$depth--;

						if ($depth > 0) {
							$alts[count($alts) - 1] .= $ch;
						}
					} elseif ($ch === ',' && $depth === 1) {
						$alts[] = '';
					} else {
						$alts[count($alts) - 1] .= $ch;
					}
					$j++;
				}
				if ($depth === 0) {
					$parts = [];

					foreach ($alts as $alt) {
						$parts[] = substr($this->globPatternToRegex($alt), 2, -2);
					}
					$out .= '(?:' . implode('|', $parts) . ')';
					$i = $j;
				} else {
					$out .= preg_quote($c, '@');
					$i++;
				}
			} else {
				$out .= preg_quote($c, '@');
				$i++;
			}
		}

		return '@^' . $out . '$@';
	}

	/**
	 * grep tool: recursive regex search over text files.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{matches: list<array{file: string, line: int, text: string}>, count: int, truncated: bool}
	 */
	public function toolGrep(array $args): array {
		$pattern    = (string)($args['pattern'] ?? '');
		$searchPath = (string)($args['path'] ?? '.');
		$include    = (string)($args['include'] ?? '*');
		$ignoreCase = !empty($args['ignoreCase']);
		$maxResults = max(1, min(1000, (int)($args['maxResults'] ?? 200)));

		if ($pattern === '') {
			throw new \InvalidArgumentException('pattern must not be empty');
		}

		$regex = '@' . str_replace('@', '\\@', $pattern) . '@' . ($ignoreCase ? 'i' : '');

		if (@preg_match($regex, '') === false) {
			throw new \InvalidArgumentException("Invalid PCRE pattern: $pattern");
		}

		$path      = $this->resolvePath($searchPath);
		$root      = $this->toolRoot();
		$matches   = [];
		$count     = 0;
		$truncated = false;

		$iterator = is_dir($path)
			? new \RecursiveIteratorIterator(
				new \RecursiveCallbackFilterIterator(
					new \RecursiveDirectoryIterator($path, \FilesystemIterator::SKIP_DOTS),
					fn ($current) => !$current->isDir() || !in_array($current->getFilename(), self::SKIP_DIRS, true)
				),
				\RecursiveIteratorIterator::LEAVES_ONLY
			)
			: [$spl = new \SplFileInfo($path)];

		foreach ($iterator as $file) {
			if (!$file instanceof \SplFileInfo || !$file->isFile()) {
				continue;
			}

			if ($include !== '*' && !fnmatch($include, $file->getFilename())) {
				continue;
			}

			if ($file->getSize() > 524288) { // skip files over 512KB
				continue;
			}

			$contents = @file_get_contents($file->getPathname());

			if ($contents === false || str_contains($contents, "\0")) {
				continue;
			}

			$lines = preg_split('/\r\n|\n|\r/', $contents);

			foreach ($lines as $i => $line) {
				if (@preg_match($regex, $line)) {
					$count++;

					if ($count <= $maxResults) {
						$matches[] = [
							'file' => ltrim(str_replace('\\', '/', substr($file->getPathname(), strlen($root))), '/'),
							'line' => $i + 1,
							'text' => mb_strcut($line, 0, 500),
						];
					}
				}
			}

			if ($count >= $maxResults * 10) { // hard stop once far past the cap
				$truncated = true;
				break;
			}
		}

		return ['matches' => $matches, 'count' => $count, 'truncated' => $count > $maxResults];
	}

	/**
	 * database_run_query tool: run SQL with prepared params against the site DB.
	 *
	 * Read-only statements are always allowed; write statements require config
	 * key mcp.tools.db_write. SELECTs without LIMIT are capped automatically.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array<string, mixed>
	 */
	public function toolDatabaseRunQuery(array $args): array {
		$query   = trim((string)($args['query'] ?? ''));
		$params  = is_array($args['params'] ?? null) ? $args['params'] : [];
		$maxRows = max(1, min(10000, (int)($args['maxRows'] ?? 1000)));

		if ($query === '') {
			throw new \InvalidArgumentException('query must not be empty');
		}

		//the driver binds :named placeholders; translate positional '?' marks
		//(outside quoted strings) into :p1, :p2 ... so users can pass a plain
		//array of values
		if ($params) {
			$out      = '';
			$inSingle = false;
			$inDouble = false;
			$index    = 0;

			foreach (str_split($query) as $char) {
				if ($char === "'" && !$inDouble) {
					$inSingle = !$inSingle;
				} elseif ($char === '"' && !$inSingle) {
					$inDouble = !$inDouble;
				}

				if ($char === '?' && !$inSingle && !$inDouble) {
					$index++;
					$out .= ':p' . $index;
					continue;
				}

				$out .= $char;
			}

			$query  = $out;
			$bind   = [];

			foreach ($params as $i => $value) {
				$bind['p' . ($i + 1)] = $value;
			}

			$params = $bind;
		}

		//strip comments before checking statement type
		$stmtType = self::statementType($query);

		$readOnlyTypes = ['SELECT', 'SHOW', 'DESCRIBE', 'DESC', 'EXPLAIN'];
		$isReadOnly    = in_array($stmtType, $readOnlyTypes, true)
			|| ($stmtType === 'WITH' && !self::containsWriteKeyword($query));

		if (!$isReadOnly && config('mcp.tools.db_write', false) !== true) {
			throw new \McpToolError("Writes are disabled - enable mcp.tools.db_write to allow $stmtType queries.");
		}

		$db = Db::getInstance();

		if (!$db) {
			throw new \RuntimeException('Database not available');
		}

		if ($stmtType === 'SELECT' && !stripos($query, ' LIMIT ')) {
			//cap unbounded selects so a missing LIMIT cannot exhaust memory;
			//an explicit LIMIT set by the caller is respected as-is
			$query = rtrim($query, "; \t\r\n") . ' LIMIT ' . $maxRows;
		}

		$stmt = $db->execute($query, $params);

		if ($stmt === null) {
			throw new \RuntimeException('Query failed');
		}

		if (in_array($stmtType, $readOnlyTypes, true) || $stmtType === 'WITH') {
			$rows       = $db->fetchAll($stmt);
			$rowCount   = count($rows);
			$truncated  = $rowCount > $maxRows;

			if ($truncated) {
				$rows = array_slice($rows, 0, $maxRows);
			}

			return ['rows' => $rows, 'rowCount' => $rowCount, 'truncated' => $truncated];
		}

		return [
			'affectedRows' => (int)($db->affected_rows ?? 0),
			'insertId'     => (int)($db->insert_id ?? 0),
			'success'      => true,
		];
	}

	/**
	 * crud tool: map CRUD operations to admin SQL models.
	 *
	 * The model name maps to admin/sql/<engine>/<model>.sql (e.g. product,
	 * user, post, order) and the operation maps to one of its procedures
	 * (get, getAll, add, edit, delete). Reads are always allowed; writes
	 * require config key mcp.tools.db_write, mirroring the database_query tool.
	 *
	 * @param mixed                $result
	 * @param mixed                $columns
	 * @param array<string, mixed> $args
	 *
	 * @return array{model: string, operation: string, result: mixed}
	 */
	/**
	 * Project result rows down to the requested columns (PHP-side: the
	 * procedures always SELECT wide). Applies recursively to nested row
	 * lists (e.g. post_content) so bodies can be dropped while names stay;
	 * scalars like counts pass through untouched. Unknown columns yield an
	 * explicit error naming real keys instead of silent empty rows.
	 * Pure, tested.
	 *
	 * @param mixed $result  Model result.
	 * @param mixed $columns Wanted column names (validated as list of strings inside).
	 *
	 * @throws \InvalidArgumentException On unknown columns.
	 *
	 * @return mixed Projected result.
	 */
	private static function crudSelectColumns(mixed $result, mixed $columns): mixed {
		if (!is_array($columns) || !array_is_list($columns)) {
			throw new \InvalidArgumentException("Invalid columns for tool 'crud': must be a list of column names.");
		}
		if ($columns === [] || !is_array($result)) {
			return $result;
		}
		foreach ($columns as $column) {
			if (!is_string($column) || !preg_match('/^[a-z][a-z0-9_]*$/', $column)) {
				throw new \InvalidArgumentException("Invalid columns entry for tool 'crud': each must match [a-z][a-z0-9_]*.");
			}
		}
		//top-level scalars (count, totals) always pass: they describe the
		//query, not the rows. Nested levels project strictly. $matched
		//records any column hit so unknown names error instead of silently
		//emptying (scalar passthrough alone must not count as a hit).
		$matched = false;
		$project = function($rows, bool $top = false) use (&$project, $columns, &$matched) {
			if (!is_array($rows)) {
				return $rows;
			}
			if (array_is_list($rows)) {
				return array_map(fn ($row) => $project($row, false), $rows);
			}
			//associative row: project known keys, recurse into nested lists
			//(empty projected rows drop out so unknown keys vanish)
			$out = [];
			foreach ($rows as $key => $value) {
				if (is_array($value)) {
					$nested = $project($value, false);
					if (array_is_list($nested)) {
						$nested = array_values(array_filter($nested, fn ($row) => $row !== [] && $row !== null));
					}
					if ($nested !== [] || in_array($key, $columns, true)) {
						$out[$key] = $nested;
					}
				} elseif ($top || in_array($key, $columns, true)) {
					if (in_array($key, $columns, true)) {
						$matched = true;
					}
					$out[$key] = $value;
				}
			}

			return $out;
		};
		$projected = $project($result, true);
		//no column hit anywhere, yet row data existed: unknown names
		$hasRows = function($rows) use (&$hasRows): bool {
			if (!is_array($rows)) {
				return false;
			}
			if (array_is_list($rows)) {
				foreach ($rows as $row) {
					if ($hasRows($row)) {
						return true;
					}
				}

				return false;
			}

			return true;
		};
		$flatten = function($rows) use (&$flatten): array {
			if (!is_array($rows)) {
				return [];
			}
			if (array_is_list($rows)) {
				$keys = [];
				foreach ($rows as $row) {
					$keys = array_merge($keys, $flatten($row));
				}

				return array_values(array_unique($keys));
			}
			$keys = [];
			foreach ($rows as $key => $value) {
				$keys[] = $key;
				$keys   = array_merge($keys, $flatten($value));
			}

			return array_values(array_unique($keys));
		};
		if (!$matched && $hasRows($result)) {
			throw new \InvalidArgumentException("Unknown columns for tool 'crud' (" . implode(', ', $columns) . '). Available keys include: ' . implode(', ', array_slice($flatten($result), 0, 12)) . '. Check table columns via database_query DESCRIBE.');
		}

		return $projected;
	}

	/**
	 * @param array<string, mixed> $args
	 *
	 * @return array{model: string, operation: string, result: mixed}
	 */
	public function toolCrud(array $args): array {
		$operation = trim((string)($args['operation'] ?? ''));
		$params    = $args['params'] ?? [];
		$model     = self::crudNormalizeModel((string)($args['model'] ?? ''));
		$columns   = $args['columns'] ?? [];

		if ($columns !== [] && (!is_array($columns) || !array_is_list($columns))) {
			throw new \InvalidArgumentException("Invalid columns for tool 'crud': must be a list of column names.");
		}

		$allowedOps = ['get', 'getAll', 'add', 'edit', 'delete'];

		if (!in_array($operation, $allowedOps, true)) {
			throw new \InvalidArgumentException("Invalid operation '$operation' for tool 'crud'. Allowed: " . implode(', ', $allowedOps));
		}

		if (!is_array($params)) {
			throw new \InvalidArgumentException("Invalid params for tool 'crud'. params must be an object with key/value pairs.");
		}

		$sqlFile = self::crudModelFile($model);

		if ($sqlFile === null) {
			throw new \McpToolError("Unknown model: '$model'. Available models: " . implode(', ', self::crudModels()));
		}

		$procedures = array_keys(self::crudProcedures($sqlFile, false));

		if ($procedures === []) {
			throw new \McpToolError("No procedures found in model '$model'.");
		}

		if (!in_array($operation, $procedures, true)) {
			throw new \McpToolError("Operation '$operation' not available for model '$model'. Available operations: " . implode(', ', $procedures));
		}

		//normalize wrong formats
		if (isset($params[$model . '_content'])) {
			if (!array_is_list($params[$model . '_content'])) {
				if (isset($params[$model . '_content']['content'])) {
					$params[$model . '_content'] = [$params[$model . '_content']];
				} else {
					//some models add extra keys like item
					$first = array_first($params[$model . '_content']);
					if (isset($first['content'])) {
						$params[$model . '_content'] = [$first];
					}
				}
			}
			foreach ($params[$model . '_content'] as &$content) {
				if (!isset($content['slug']) && isset($content['name'])) {
					$content['slug'] = slugify($content['name']);
				}
				if (is_array($content)) {
					$content += ['language_id' => $this->global['language_id']];
				}
			}
		}

		if (($model === 'post' || $model === 'product') && !isset($params['site_id'])) {
			$params['site_id'] = [$this->global['site_id']];
		}

		if ($operation == 'getAll') {
			$params += ['start' => 0, 'limit' => 5];
		}

		if ($operation == 'add') {
			foreach ($params as $param => &$value) {
				//content expects a multi language array if only one language is provided add to list
				if (str_ends_with($param, '_content')) {
					if (!array_is_list($value)) {
						$value = [$value];
					}

					foreach ($value as &$row) {
						if (is_array($row) && !isset($row['slug']) && isset($row['name'])) {
							$row['slug'] = slugify($row['name']);
						}
					}
					unset($row);
				}
			}
		}
		//normalize wrong formats - end

		$procParams = self::crudProcedures($sqlFile, false)[$operation] ?? [];
		$params     = self::crudCoerceArrayParams($procParams, $params);

		//fail fast with the calling convention: add/edit nest the record
		//under the first ARRAY parameter (usually the model name), never as
		//flat fields. Without this a flat call dies deep in SQL with a
		//cryptic error; the message below carries a working example instead.
		//Runs before the db_write gate so agents get the shape fix first.
		$shapeError = self::crudCheckRecordParam($model, $operation, $procParams, $params);

		if ($shapeError !== null) {
			throw new \InvalidArgumentException($shapeError);
		}

		//fail fast with guidance: missing must-supply params, misshapen
		//rows and unknown row keys are rejected here, before the db_write
		//gate, so agents get actionable errors instead of deep SQL failures.
		$detailParams  = self::crudProcedures($sqlFile)[$operation] ?? [];
		$validateError = self::crudValidateParams($model, $operation, $detailParams, $params);

		if ($validateError !== null) {
			throw new \InvalidArgumentException($validateError);
		}

		if (in_array($operation, ['add', 'edit', 'delete'], true) && config('mcp.tools.db_write', false) !== true) {
			throw new \McpToolError("Writes are disabled - enable mcp.tools.db_write to allow $operation on model $model.");
		}

		$modelObj = \Vvveb\model($model);

		if (!method_exists($modelObj, $operation)) {
			throw new \McpToolError("Operation '$operation' not available for model '$model'.");
		}

		if (isset($params[$model])) {
			$params[$model] += $this->global;
		}

		$params += $this->global;

		$result = $modelObj->{$operation}($params);

		if ($columns !== [] && in_array($operation, ['get', 'getAll'], true)) {
			$result = self::crudSelectColumns($result, $columns);
		}

		return ['model' => $model, 'operation' => $operation, 'result' => $result ?? []];
	}

	/**
	 * crud_models tool: discover available CRUD models and their procedures.
	 *
	 * Without a model argument lists every model with its procedure names and
	 * which of them are callable through the crud tool. With a model argument
	 * returns each procedure with its IN parameters and crud-callability, so
	 * agents know exactly what params an operation accepts. Read-only.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array<string, mixed>
	 */
	public function toolCrudModels(array $args): array {
		$rawModel = trim((string)($args['model'] ?? ''));

		if ($rawModel === '') {
			$models = [];

			foreach (self::crudModels() as $name) {
				$sqlFile    = self::crudModelFile($name);
				$procedures = $sqlFile ? array_keys(self::crudProcedures($sqlFile, false)) : [];
				$models[]   = [
					'model'      => $name,
					'crud'       => array_values(array_intersect(['get', 'getAll', 'add', 'edit', 'delete'], $procedures)),
					'procedures' => $procedures,
				];
			}

			return ['models' => $models, 'count' => count($models)];
		}

		$model   = self::crudNormalizeModel($rawModel);
		$sqlFile = self::crudModelFile($model);

		if ($sqlFile === null) {
			throw new \McpToolError("Unknown model: '$model'. Available models: " . implode(', ', self::crudModels()));
		}

		$crudOps    = ['get', 'getAll', 'add', 'edit', 'delete'];
		$procedures = [];

		foreach (self::crudProcedures($sqlFile) as $name => $params) {
			foreach ($params as &$entry) {
				//internal validation aid, never part of the tool schema
				unset($entry['columns']);
			}
			unset($entry);

			$procedures[] = ['name' => $name, 'crud' => in_array($name, $crudOps, true), 'params' => $params];
		}

		return ['model' => $model, 'procedures' => $procedures];
	}

	/**
	 * Normalize a user supplied model name (trim, CamelCase to snake_case).
	 *
	 * @param string $rawModel
	 *
	 * @throws \InvalidArgumentException on empty or malformed names
	 */
	private static function crudNormalizeModel(string $rawModel): string {
		//accept CamelCase too (ProductOption -> product_option)
		$model = strtolower((string)preg_replace('/(?<!^)[A-Z]/', '_$0', trim($rawModel)));

		if ($model === '' || !preg_match('/^[a-z][a-z0-9_]*$/', $model)) {
			throw new \InvalidArgumentException("Invalid model name: '$rawModel'");
		}

		return $model;
	}

	/**
	 * Resolve the .sql definition file for a normalized model name.
	 *
	 * Uses the current DB engine directory with fallback to the canonical
	 * mysqli definitions. Returns null when the model does not exist.
	 *
	 * @param string $model
	 */
	private static function crudModelFile(string $model): ?string {
		$engine  = defined('DB_ENGINE') ? DB_ENGINE : 'mysqli';
		$sqlFile = DIR_ROOT . '/admin/sql/' . $engine . '/' . $model . '.sql';

		if (is_file($sqlFile)) {
			return $sqlFile;
		}

		$sqlFile = DIR_ROOT . '/admin/sql/mysqli/' . $model . '.sql';

		return is_file($sqlFile) ? $sqlFile : null;
	}

	/**
	 * Parse procedure names and IN params from a .sql definition file.
	 *
	 * With $detail, each IN param also reports whether it is must-supply
	 * (`required`) and, for ROW/ROWS record params, the accepted field names
	 * (`fields`). required is derived from the procedure body: a param used
	 * in unconditional SQL must be supplied, while @IF-guarded, loop-tolerant
	 * (@EACH) or unreferenced params are safely omittable. fields are the
	 *
	 * @FILTER table columns minus auto-increment keys and keys the procedure
	 * injects itself (e.g. post_id via @result.post).
	 *
	 * @param string $sqlFile
	 * @param bool   $detail
	 *
	 * @return array<string, list<array{name: string, type: string, required?: bool, fields?: list<string>, required_fields?: list<string>, columns?: list<string>}>> procedure name to IN params
	 */
	private static function crudProcedures(string $sqlFile, bool $detail = true): array {
		static $cache = [];

		$cacheKey = $sqlFile . ($detail ? '#detail' : '');

		if (isset($cache[$cacheKey])) {
			return $cache[$cacheKey];
		}

		$procedures = [];
		$content    = (string)@file_get_contents($sqlFile);

		//SqlP strips -- comments before parsing; do the same so comment
		//text never counts as a parameter reference.
		$stripped = (string)preg_replace('/(--.*)\s+/', '', $content);

		//declaration headers contain no nested parens, and the trailing
		//\s*BEGIN anchor disambiguates the header's closing paren.
		//The body runs to the first END not followed by @ (same as SqlP).
		if (preg_match_all('/(CREATE\s+)?PROCEDURE\s+([A-Za-z0-9_]+)\s*\((.*?)\)\s*BEGIN\s*(.*?)\s*END(?!\s*@)/is', $stripped, $blocks, PREG_SET_ORDER)) {
			foreach ($blocks as $block) {
				$params = [];

				if (preg_match_all('/\bIN\s+([A-Za-z0-9_]+)\s+([A-Za-z0-9_]+)/i', $block[3], $matches, PREG_SET_ORDER)) {
					foreach ($matches as $match) {
						$entry = ['name' => $match[1], 'type' => strtoupper($match[2])];

						if ($detail) {
							$entry['required'] = self::crudParamRequired($match[1], $block[4]);
							$fieldInfo         = self::crudParamFields($match[1], $entry['type'], $block[4]);

							if ($fieldInfo !== null) {
								$entry['fields'] = $fieldInfo['fields'];

								if ($fieldInfo['required_fields'] !== []) {
									$entry['required_fields'] = $fieldInfo['required_fields'];
								}

								//internal only: lenient edit checks need every table
								//column, never emitted (stripped in toolCrudModels)
								$entry['columns'] = $fieldInfo['columns'];
							}
						}

						$params[] = $entry;
					}
				}

				$procedures[$block[2]] = $params;
			}
		}

		return $cache[$sqlFile . ($detail ? '#detail' : '')] = $procedures;
	}

	/**
	 * Whether an IN param must be supplied: referenced in unconditional SQL.
	 *
	 * Params used only inside @IF guards, tolerant @EACH loops or @FILTER
	 * preprocessing (or not referenced at all) are safely omittable.
	 * :ret aliases from `:ret = @FILTER(:param, ...)` count as the param.
	 *
	 * @param string $param
	 * @param string $body
	 */
	private static function crudParamRequired(string $param, string $body): bool {
		$flow = [$param];

		if (preg_match_all('/:([A-Za-z0-9_\.]+)\s*=\s*@FILTER\s*\(\s*:([A-Za-z0-9_\.]+)\b/', $body, $m)) {
			foreach ($m[2] as $i => $data) {
				if ($data === $param) {
					$flow[] = $m[1][$i];
				}
			}
		}

		$probe = $body;

		//peel nested @IF...END @IF blocks (innermost first)
		do {
			$probe = (string)preg_replace('/@IF\b(?:(?!@IF).)*?END @IF/s', '', $probe, -1, $count);
		} while ($count > 0);

		/**
		 * @EACH headers are tolerant (isset + is_array guard), @FILTER
		 * calls are preprocessing - neither proves the param is needed
		 */
		$probe = (string)preg_replace('/@EACH\s*\(\s*:[^)]+\)/', '', $probe);
		$probe = (string)preg_replace('/:[A-Za-z0-9_\.]+\s*=\s*@FILTER\s*\([^()]*\)/', '', $probe);
		$probe = (string)preg_replace('/@FILTER\s*\([^()]*\)/', '', $probe);

		foreach ($flow as $var) {
			if (preg_match('/:' . preg_quote($var, '/') . '(?!\w)/', $probe)) {
				return true;
			}
		}

		return false;
	}

	/**
	 * Accepted field names for a ROW/ROWS record param, or null.
	 *
	 * Tables come from @FILTER calls on the param (following renames) or,
	 * failing that, the INSERT target of its @EACH loop. Fields are table
	 * columns minus auto-increment keys and keys the procedure injects
	 * itself (siblings of @KEYS in INSERT column lists, e.g. post_id).
	 * Emitted only when the data is row-shaped (direct @KEYS/@LIST or a
	 * row-valued @EACH loop), so flat id lists never get fields.
	 *
	 * @param string $param
	 * @param string $type
	 * @param string $body
	 *
	 * @return array{fields: list<string>, required_fields: list<string>, columns: list<string>}|null
	 *                                                                                                null when no table resolves; required_fields lists fields with
	 *                                                                                                no usable default, i.e. omitting them fails the INSERT.
	 */
	private static function crudParamFields(string $param, string $type, string $body): ?array {
		$flow = [$param];

		if (preg_match_all('/:([A-Za-z0-9_\.]+)\s*=\s*@FILTER\s*\(\s*:([A-Za-z0-9_\.]+)\b/', $body, $m)) {
			foreach ($m[2] as $i => $data) {
				if ($data === $param) {
					$flow[] = $m[1][$i];
				}
			}
		}

		$tables = [];

		if (preg_match_all('/@FILTER\s*\(\s*:([A-Za-z0-9_\.]+)\s*,\s*([A-Za-z_]+)/', $body, $fm, PREG_SET_ORDER)) {
			foreach ($fm as $f) {
				//dotted children (:order.products) belong to sub-lists, not this param
				if (in_array($f[1], $flow, true) && !in_array($f[2], $tables, true)) {
					$tables[] = $f[2];
				}
			}
		}

		$rowShaped  = false;
		$loopTables = [];

		foreach ($flow as $var) {
			if (preg_match('/@(KEYS|LIST)\s*\(\s*:' . preg_quote($var, '/') . '(?!\w)/', $body)) {
				$rowShaped = true;

				break;
			}
		}

		foreach (explode(';', $body) as $stmt) {
			if (!preg_match('/@EACH\s*\(\s*:([A-Za-z0-9_\.]+)\s*\)/', $stmt, $em) || !in_array($em[1], $flow, true)) {
				continue;
			}

			$hasKeys = (bool)preg_match('/@KEYS\s*\(\s*:each(?!\w)/', $stmt);
			$hasList = (bool)preg_match('/@LIST\s*\(\s*:each(?!\w)/', $stmt) && (bool)preg_match('/:each\.\w+/', $stmt);

			if ($hasKeys || $hasList) {
				$rowShaped = true;

				if (preg_match('/INSERT\s+INTO\s+["`]?([A-Za-z_][\w]*)["`]?/i', $stmt, $im) && !in_array($im[1], $loopTables, true)) {
					$loopTables[] = $im[1];
				}
			}
		}

		if (!$rowShaped) {
			return null;
		}

		if (!$tables && $loopTables) {
			$tables = $loopTables;
		}

		if (!$tables) {
			return null;
		}

		//columns the procedure supplies itself: siblings of @KEYS(...)
		//in INSERT column lists - rows must not (re)supply them
		$extras = [];

		if (preg_match_all('/\(\s*@KEYS\s*\([^)]+\)([^()]*)\)/', $body, $km, PREG_SET_ORDER)) {
			foreach ($km as $k) {
				if (preg_match_all('/[`"]?([A-Za-z_][\w]*)[`"]?/', $k[1], $cm)) {
					foreach ($cm[1] as $col) {
						$extras[$col] = true;
					}
				}
			}
		}

		$fields         = [];
		$requiredFields = [];
		$columns        = [];

		foreach ($tables as $table) {
			foreach (self::crudTableColumns($table) as $name => $col) {
				if (!in_array($name, $columns, true)) {
					$columns[] = $name;
				}

				if (isset($extras[$name]) || self::crudIsAutoColumn($col)) {
					continue;
				}

				if (!in_array($name, $fields, true)) {
					$fields[] = $name;

					if (self::crudIsRequiredColumn($col)) {
						$requiredFields[] = $name;
					}
				}
			}
		}

		return $fields === [] ? null : ['fields' => $fields, 'required_fields' => $requiredFields, 'columns' => $columns];
	}

	/**
	 * Live column metadata for a table, keyed by column name.
	 *
	 * Same source @FILTER enforces against, so listed fields can never
	 * disagree with filtering. Empty when the table is unavailable.
	 *
	 * @param string $table
	 *
	 * @return array<string, array<string, mixed>>
	 */
	private static function crudTableColumns(string $table): array {
		static $cache = [];

		if (array_key_exists($table, $cache)) {
			return $cache[$table];
		}

		$columns = [];

		try {
			$prefix = defined('DB_PREFIX') ? DB_PREFIX : 'vvveb_';
			$meta   = Db::getInstance()->getColumnsMeta($prefix . $table);

			if (is_array($meta)) {
				foreach ($meta as $key => $col) {
					if (is_array($col)) {
						$columns[$col['name'] ?? $key] = $col;
					}
				}
			}
		} catch (\Throwable) {
			//uninstalled plugin tables and the like: no fields
		}

		return $cache[$table] = $columns;
	}

	/**
	 * Whether a metadata column is auto-assigned on insert (and agents
	 * must therefore not supply it): mysqli EXTRA flag, pgsql serial
	 * nextval() defaults, sqlite INTEGER PRIMARY KEY rowid aliases
	 * (nullable, default-less INT columns).
	 *
	 * @param array<string, mixed> $col
	 */
	private static function crudIsAutoColumn(array $col): bool {
		//mysqli INFORMATION_SCHEMA EXTRA flag
		if (($col['e'] ?? '') === 'auto_increment') {
			return true;
		}

		//pgsql serial columns default to nextval(...)
		if (str_starts_with((string)($col['d'] ?? ''), 'nextval')) {
			return true;
		}

		//sqlite getColumnsMeta() exposes no pk/extra flags: an INTEGER
		//PRIMARY KEY is a rowid alias (auto-assigned, pragma notnull = 0).
		//Nullable default-less INTs also match, which is harmless - omitting
		//a nullable column is always safe.
		if (defined('DB_ENGINE') && DB_ENGINE === 'sqlite') {
			$type     = strtoupper((string)($col['t'] ?? ''));
			$default  = $col['d'] ?? null;

			return str_contains($type, 'INT') && ($col['n'] ?? 1) == 0 && ($default === null || $default === '');
		}

		return false;
	}

	/**
	 * Whether omitting the column fails the INSERT: NOT NULL with no
	 * usable default (any non-null default, including '' or 0, fills the
	 * column safely). Nullability flags differ per driver (YES/NO strings
	 * vs sqlite pragma 0/1), normalized here.
	 *
	 * @param array<string, mixed> $col
	 */
	private static function crudIsRequiredColumn(array $col): bool {
		$n = $col['n'] ?? null;

		if (defined('DB_ENGINE') && DB_ENGINE === 'sqlite') {
			$nullable = ($n == 0);
		} else {
			$nullable = in_array($n, ['YES', 'yes', true, 1, '1'], true);
		}

		if ($nullable) {
			return false;
		}

		return !array_key_exists('d', $col) || $col['d'] === null;
	}

	/**
	 * Wrap scalar values for declared ARRAY IN params in a one-item list, so
	 * delete with {"post_id": 5} or a single taxonomy id just works instead
	 * of failing inside SQL iteration. A single row object for a ROWS list
	 * param wraps the same way (one assoc becomes a one-row list). Arrays
	 * and objects pass through untouched; only real scalars are wrapped.
	 *
	 * @param list<array{name: string, type: string}> $procParams
	 * @param array<array-key, mixed>                 $params
	 *
	 * @return array<string, mixed>
	 */
	private static function crudCoerceArrayParams(array $procParams, array $params): array {
		foreach ($procParams as $p) {
			$name = $p['name'];

			if (!isset($params[$name])) {
				continue;
			}

			$type = strtoupper($p['type']);

			if ($type === 'ARRAY' && is_scalar($params[$name])) {
				$params[$name] = [$params[$name]];
			} elseif ($type === 'ROWS' && is_array($params[$name]) && !array_is_list($params[$name])) {
				$params[$name] = [$params[$name]];
			}
		}

		return $params;
	}

	/**
	 * Validate params against the procedure contract before any write.
	 *
	 * Missing must-supply params, misshapen rows and unknown row keys are
	 * rejected here with guidance instead of dying deep in SQL (silent
	 *
	 * @FILTER drops, NULL-bound filters) or corrupting data (stale ids in
	 * auto-managed keys). Unknown keys on edit rows are checked leniently
	 * against all table columns, since echoing keys back is harmless there;
	 * on add only accepted fields pass. Row required_fields apply to add
	 * only - edits merge, so partial rows are fine. Returns a guidance
	 * message when the call must not proceed, null otherwise.
	 *
	 * @param string                                                                                                                                  $model
	 * @param string                                                                                                                                  $operation
	 * @param list<array{name: string, type: string, required?: bool, fields?: list<string>, required_fields?: list<string>, columns?: list<string>}> $procParams
	 * @param array<array-key, mixed>                                                                                                                 $params
	 */
	private static function crudValidateParams(string $model, string $operation, array $procParams, array $params): ?string {
		foreach ($procParams as $p) {
			$name = $p['name'];

			if ($name === '' || empty($p['required'])) {
				continue;
			}

			if (!array_key_exists($name, $params) || $params[$name] === null || $params[$name] === '') {
				return "Missing required param '$name' for crud $operation on model '$model'. " .
					'Omit optional params you have no value for instead of sending empty strings; ' .
					"call crud_models with {\"model\":\"$model\"} for the full contract.";
			}
		}

		foreach ($procParams as $p) {
			$name = $p['name'];
			$type = strtoupper($p['type']);

			if ($name === '' || ($type !== 'ROW' && $type !== 'ROWS') || !array_key_exists($name, $params)) {
				continue;
			}

			$value = $params[$name];

			if (!is_array($value)) {
				$want = $type === 'ROWS' ? 'a list of row objects' : 'a single row object';

				return "Invalid '$name' for crud $operation on model '$model': must be $want, got " . gettype($value) . '. ' .
					"Call crud_models with {\"model\":\"$model\"} for the full contract.";
			}

			if ($type === 'ROW' && array_is_list($value)) {
				return "Invalid '$name' for crud $operation on model '$model': must be a single row object, not a list. " .
					"Call crud_models with {\"model\":\"$model\"} for the full contract.";
			}

			$rows   = $type === 'ROWS' ? array_values($value) : [$value];
			$fields = $p['fields'] ?? null;
			$strict = $operation === 'add';
			$known  = $strict ? $fields : ($p['columns'] ?? $fields);

			foreach ($rows as $row) {
				if (!is_array($row)) {
					return "Invalid '$name' for crud $operation on model '$model': each row must be an object. " .
						"Call crud_models with {\"model\":\"$model\"} for the full contract.";
				}

				if (is_array($known)) {
					foreach (array_keys($row) as $key) {
						if (is_string($key) && !in_array($key, $known, true)) {
							return self::crudUnknownFieldMessage($model, $operation, $name, (string)$key, $known, $fields, $p['columns'] ?? $fields);
						}
					}
				}

				if ($strict && !empty($p['required_fields'])) {
					$absent = array_diff($p['required_fields'], array_keys($row));

					//the tool slugifies name into slug on add, so a
					//missing slug is satisfied by a present name
					if ($absent !== [] && in_array('slug', $absent, true) && !empty($row['name'])) {
						$absent = array_diff($absent, ['slug']);
					}

					if ($absent !== []) {
						return "Missing required field(s) '" . implode(', ', $absent) . "' in '$name' rows for crud $operation on model '$model'. " .
							'Accepted fields: ' . implode(', ', (array)$fields) . '. ' .
							"Call crud_models with {\"model\":\"$model\"} for the full contract.";
					}
				}
			}
		}

		return null;
	}

	/**
	 * Guidance message for an unknown row key: auto-managed keys must be
	 * omitted, otherwise suggest the closest accepted field.
	 *
	 * @param string            $model
	 * @param string            $operation
	 * @param string            $param
	 * @param string            $key
	 * @param list<string>|null $known
	 * @param list<string>|null $fields
	 * @param list<string>|null $columns
	 */
	private static function crudUnknownFieldMessage(string $model, string $operation, string $param, string $key, ?array $known, ?array $fields, ?array $columns = null): string {
		if (is_array($fields) && !in_array($key, $fields, true) && in_array($key, $columns ?? [], true)) {
			return "Invalid field '$key' in '$param' rows for crud $operation on model '$model': auto-managed keys must be omitted, the procedure supplies them. " .
				'Accepted fields: ' . implode(', ', $fields) . '. ' .
				"Call crud_models with {\"model\":\"$model\"} for the full contract.";
		}

		$best     = null;
		$bestDist = 4;

		if (is_array($known)) {
			foreach ($known as $candidate) {
				$dist = levenshtein($key, (string)$candidate);

				if ($dist < $bestDist) {
					$bestDist = $dist;
					$best     = $candidate;
				}
			}
		}

		$hint = ($best !== null) ? " Did you mean '$best'?" : '';
		$list = is_array($known) ? (' Accepted fields: ' . implode(', ', $known) . '.') : '';

		return "Unknown field '$key' in '$param' rows for crud $operation on model '$model'." . $hint . $list . ' ' .
			"Call crud_models with {\"model\":\"$model\"} for the full contract.";
	}

	/**
	 * Verify the add/edit record shape: the record must sit under the first
	 * ARRAY IN parameter (conventionally the model name: post, product,
	 * currency, ...; exceptions like filter->attribute or
	 * order_shipment->shipment follow the same rule via their own first
	 * ARRAY param). Returns a guidance message with a working example when
	 * the shape is wrong, null when the call may proceed. Read operations
	 * and procedures without ARRAY params are never rejected here.
	 *
	 * @param string                                  $model
	 * @param string                                  $operation
	 * @param list<array{name: string, type: string}> $procParams
	 * @param array<array-key, mixed>                 $params
	 */
	private static function crudCheckRecordParam(string $model, string $operation, array $procParams, array $params): ?string {
		if (!in_array($operation, ['add', 'edit'], true)) {
			return null;
		}

		//record params are typed ROW (single) or ROWS (list); some older
		//models type the record ARRAY, in which case scalar id lists
		//(taxonomy_item_id, site_id, ...) must not match - they end in _id
		$recordKey = null;

		foreach ($procParams as $p) {
			$type = strtoupper($p['type']);
			$name = $p['name'];

			if ($name === '' || ($type !== 'ROW' && $type !== 'ROWS' && $type !== 'ARRAY')) {
				continue;
			}

			if ($type === 'ARRAY' && preg_match('/_id$/', $name)) {
				continue;
			}

			$recordKey = $name;

			break;
		}

		if ($recordKey === null || (isset($params[$recordKey]) && is_array($params[$recordKey]))) {
			return null;
		}

		$example = ['model' => $model, 'operation' => $operation, 'params' => [$recordKey => ['slug' => 'hello', 'status' => 1]]];

		foreach ($procParams as $p) {
			if ($p['name'] === $model . '_content') {
				$example['params'][$model . '_content'] = [['name' => 'Hello', 'content' => '...', 'language_id' => 1]];

				break;
			}
		}

		return "Invalid params for crud $operation on model '$model': the record must be nested under the '$recordKey' key, not passed as flat fields. " .
			'Example: ' . json_encode($example) . '. ' .
				"Use crud_models with {\"model\":\"$model\"} for every accepted parameter (language_id/site_id default to 1); " .
				"record field names are table columns - inspect them read-only via database_query, e.g. {\"query\":\"DESCRIBE $model\"}.";
	}

	/**
	 * List available CRUD model names (basenames of admin/sql/mysqli/*.sql).
	 *
	 * @return list<string>
	 */
	private static function crudModels(): array {
		$models = [];

		foreach (glob(DIR_ROOT . '/admin/sql/mysqli/*.sql') ?: [] as $file) {
			$models[] = basename($file, '.sql');
		}

		sort($models);

		return $models;
	}

	/**
	 * admin tool: unified dispatcher for subsystem CRUD stubs.
	 *
	 * Routes to the themes/plugins/media/cron/cache stubs by target, passing
	 * all other arguments through. Keeps the tool registry small while each
	 * stub keeps its own per-operation validation.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array<string, mixed>
	 */
	public function toolAdmin(array $args): array {
		$target = trim((string)($args['target'] ?? ''));

		//media stays callable here as a deprecated alias (top-level media
		//tool is advertised instead); the admin schema no longer lists it.
		$stubs = [
			'themes'  => 'toolThemes',
			'plugins' => 'toolPlugins',
			'media'   => 'toolMedia',
			'cron'    => 'toolCron',
			'cache'   => 'toolCache',
		];

		if (!isset($stubs[$target])) {
			throw new \InvalidArgumentException("Invalid target '$target' for tool 'admin'. Allowed: " . implode(', ', array_keys($stubs)));
		}

		$method = $stubs[$target];
		$result = $this->$method($args);

		return ['target' => $target] + $result;
	}

	/**
	 * Search the marketplace feed for themes or plugins.
	 *
	 * @param class-string         $class     Themes/Plugins extension class
	 * @param string               $kind      theme|plugin (selects slug argument and result key)
	 * @param array<string, mixed> $args
	 * @param array<string, mixed> $installed locally installed items keyed by slug
	 *
	 * @return array<string, mixed>
	 */
	private function marketSearch(string $class, string $kind, array $args, array $installed): array {
		$listKey = $kind . 's'; // themes|plugins
		$query   = [];

		foreach (['search', 'category'] as $key) {
			$value = trim((string)($args[$key] ?? ''));

			if ($value !== '') {
				$query[$key] = $value;
			}
		}

		$slug = trim((string)($args[$kind] ?? ''));

		if ($slug !== '') {
			$query['slug'] = $slug;
		}

		$query['start'] = max(1, (int)($args['start'] ?? 1));
		$query['limit'] = max(1, min(50, (int)($args['limit'] ?? 10)));

		$result = $class::getMarketList($query);

		if ($result === []) {
			throw new \RuntimeException('Error contacting the marketplace feed');
		}

		$items = $result[$listKey] ?? [];

		foreach ($items as &$item) {
			$item['installed'] = isset($installed[$item['slug'] ?? '']);
		}
		unset($item);

		return ['operation' => 'market', $listKey => $items, 'count' => $result['count'] ?? count($items)];
	}

	/**
	 * Install a theme or plugin from the marketplace by slug.
	 *
	 * Mirrors the admin Market controllers: look the slug up in the market
	 * feed, download the zip, install it and clear the list cache. Requires
	 * config key mcp.tools.db_write.
	 *
	 * @param class-string $class  Themes/Plugins extension class
	 * @param string       $kind   theme|plugin
	 * @param string       $slug
	 * @param int          $siteId
	 *
	 * @return array<string, mixed>
	 */
	private function marketInstall(string $class, string $kind, string $slug, int $siteId): array {
		if (config('mcp.tools.db_write', false) !== true) {
			throw new \McpToolError("Writes are disabled - enable mcp.tools.db_write to allow install on $kind $slug.");
		}

		$listKey = $kind . 's'; // themes|plugins
		$list    = $class::getMarketList(['slug' => $slug]);

		if ($list === []) {
			throw new \RuntimeException('Error contacting the marketplace feed');
		}

		$items = $list[$listKey] ?? [];

		if (!$items || !isset($items[0])) {
			throw new \RuntimeException("Extension '$slug' not found in the marketplace");
		}

		$info = $items[0];

		if (empty($info['download_link'])) {
			throw new \RuntimeException("Extension '$slug' has no download link in the marketplace");
		}

		$downloadLink = $class::marketUrl() . $info['download_link'];
		$tempFile     = $class::download($downloadLink);

		if (!$tempFile) {
			throw new \RuntimeException("Error downloading '$slug' from $downloadLink");
		}

		try {
			//themes skip zip validation like the admin theme market controller
			$installed = $kind === 'theme' ? $class::install($tempFile, $slug, false) : $class::install($tempFile, $slug);

			if (!$installed) {
				throw new \RuntimeException("Error installing '$slug'");
			}

			\Vvveb\System\CacheManager::clearObjectCache('vvveb', "{$listKey}_list_$siteId");
		} finally {
			@unlink($tempFile);
		}

		return ['operation' => 'install', $kind => $slug, 'name' => $info['name'] ?? $slug, 'success' => true];
	}

	/**
	 * Slim extension rows for list operations: slug, name and description
	 * only. Full headers (author, license, version, paths) stay available
	 * through the get operation. Map keys preserved. Pure, tested.
	 *
	 * @param array<array-key, mixed> $items
	 *
	 * @return array<string, array{slug: string, name: string, description: string, active?: bool}>
	 */
	private static function slimExtensionList(array $items): array {
		$out = [];
		foreach ($items as $slug => $item) {
			if (!is_array($item)) {
				continue;
			}
			$slug = (string)($item['slug'] ?? $slug);
			$row  = [
				'slug'        => $slug,
				'name'        => (string)($item['name'] ?? $slug),
				'description' => (string)($item['description'] ?? ''),
			];
			if (!empty($item['active'])) {
				$row['active'] = true;
			}
			$out[$slug] = $row;
		}

		return $out;
	}

	/**
	 * Themes stub (via admin tool): CRUD for CMS themes (public/themes/<slug>).
	 *
	 * Thin wrappers around Themes::getList and Sites::setTheme: list/get are
	 * always allowed; activate/delete require config key mcp.tools.db_write.
	 * Delete refuses the active theme.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array<string, mixed>
	 */
	private function toolThemes(array $args): array {
		$operation = trim((string)($args['operation'] ?? ''));
		$rawTheme  = trim((string)($args['theme'] ?? ''));
		$siteId    = (int)($args['site_id'] ?? $this->global['site_id'] ?? 1);

		$allowedOps = ['list', 'get', 'market', 'activate', 'install', 'delete'];

		if (!in_array($operation, $allowedOps, true)) {
			throw new \InvalidArgumentException("Invalid operation '$operation' for tool 'themes'. Allowed: " . implode(', ', $allowedOps));
		}

		if (in_array($operation, ['get', 'activate', 'install', 'delete'], true) && $rawTheme === '') {
			throw new \InvalidArgumentException("Missing required argument 'theme' for tool 'themes' operation '$operation'");
		}

		if ($rawTheme !== '' && !preg_match('/^[A-Za-z0-9_-]+$/', $rawTheme)) {
			throw new \InvalidArgumentException("Invalid theme name: '$rawTheme'");
		}

		$theme   = \Vvveb\sanitizeFileName(basename($rawTheme));
		$themes  = \Vvveb\System\Extensions\Themes::getList($siteId, false);
		$active  = \Vvveb\System\Sites::getTheme($siteId);

		if ($operation === 'list') {
			$slim = self::slimExtensionList($themes);

			return ['operation' => $operation, 'themes' => $slim, 'active' => $active, 'count' => count($slim)];
		}

		if (in_array($operation, ['get', 'activate', 'delete'], true) && !isset($themes[$theme])) {
			throw new \McpToolError("Unknown theme: '$theme'. Available themes: " . implode(', ', array_keys($themes)));
		}

		if ($operation === 'get') {
			return ['operation' => $operation, 'theme' => $theme, 'info' => $themes[$theme], 'active' => $active];
		}

		if ($operation === 'market') {
			return $this->marketSearch(\Vvveb\System\Extensions\Themes::class, 'theme', $args, $themes);
		}

		if (config('mcp.tools.db_write', false) !== true) {
			throw new \McpToolError("Writes are disabled - enable mcp.tools.db_write to allow $operation on theme $theme.");
		}

		if ($operation === 'activate') {
			if (!\Vvveb\System\Sites::setTheme($siteId, $theme, 'index.html')) {
				throw new \RuntimeException("Error activating theme '$theme'");
			}

			\Vvveb\System\CacheManager::clearObjectCache('site');
			\Vvveb\System\CacheManager::clearFrontend();
			\Vvveb\System\CacheManager::clearCompiledFiles();
			\Vvveb\System\CacheManager::clearPageCache();

			return ['operation' => $operation, 'theme' => $theme, 'active' => $theme, 'success' => true];
		}

		if ($operation === 'install') {
			return $this->marketInstall(\Vvveb\System\Extensions\Themes::class, 'theme', $theme, $siteId);
		}

		if ($theme === $active) {
			throw new \McpToolError("Refusing to delete the active theme '$theme'. Activate another theme first.");
		}

		$dir = DIR_THEMES . $theme;

		if (!is_dir($dir) || !rrmdir($dir)) {
			throw new \RuntimeException("Error removing theme '$theme'");
		}

		\Vvveb\System\Extensions\Themes::clearThemesCache($siteId);

		return ['operation' => $operation, 'theme' => $theme, 'success' => true];
	}

	/**
	 * Plugins stub (via admin tool): CRUD for CMS plugins (plugins/<slug>).
	 *
	 * Thin wrappers around Plugins::getList/activate/deactivate/uninstall:
	 * list/get are always allowed; activate/deactivate/uninstall require
	 * config key mcp.tools.db_write.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array<string, mixed>
	 */
	private function toolPlugins(array $args): array {
		$operation = trim((string)($args['operation'] ?? ''));
		$plugin    = trim((string)($args['plugin'] ?? ''));
		$category  = trim((string)($args['category'] ?? ''));
		$siteId    = (int)($args['site_id'] ?? $this->global['site_id'] ?? 1);

		$allowedOps = ['list', 'get', 'market', 'activate', 'deactivate', 'install', 'uninstall'];

		if (!in_array($operation, $allowedOps, true)) {
			throw new \InvalidArgumentException("Invalid operation '$operation' for tool 'plugins'. Allowed: " . implode(', ', $allowedOps));
		}

		if (!in_array($operation, ['list', 'market'], true) && $plugin === '') {
			throw new \InvalidArgumentException("Missing required argument 'plugin' for tool 'plugins' operation '$operation'");
		}

		if ($plugin !== '' && !preg_match('/^[A-Za-z0-9_-]+$/', $plugin)) {
			throw new \InvalidArgumentException("Invalid plugin name: '$plugin'");
		}

		$plugins = \Vvveb\System\Extensions\Plugins::getList($siteId, $category !== '' ? $category : false, false);

		if ($operation === 'list') {
			$slim = self::slimExtensionList($plugins);

			return ['operation' => $operation, 'plugins' => $slim, 'count' => count($slim)];
		}

		if (!in_array($operation, ['market', 'install'], true) && !isset($plugins[$plugin])) {
			throw new \McpToolError("Unknown plugin: '$plugin'. Available plugins: " . implode(', ', array_keys($plugins)));
		}

		if ($operation === 'get') {
			return ['operation' => $operation, 'plugin' => $plugin, 'info' => $plugins[$plugin]];
		}

		if ($operation === 'market') {
			return $this->marketSearch(\Vvveb\System\Extensions\Plugins::class, 'plugin', $args, $plugins);
		}

		if (config('mcp.tools.db_write', false) !== true) {
			throw new \McpToolError("Writes are disabled - enable mcp.tools.db_write to allow $operation on plugin $plugin.");
		}

		if ($operation === 'install') {
			return $this->marketInstall(\Vvveb\System\Extensions\Plugins::class, 'plugin', $plugin, $siteId);
		}

		if ($operation === 'activate') {
			if (!\Vvveb\System\Extensions\Plugins::activate($plugin, $siteId)) {
				throw new \RuntimeException("Error activating plugin '$plugin'");
			}

			\Vvveb\System\CacheManager::clearObjectCache('admin-menu');
			\Vvveb\System\CacheManager::clearCompiledFiles();
			\Vvveb\System\CacheManager::clearPageCache();

			return ['operation' => $operation, 'plugin' => $plugin, 'success' => true];
		}

		if ($operation === 'deactivate') {
			if (!\Vvveb\System\Extensions\Plugins::deactivate($plugin, $siteId)) {
				throw new \RuntimeException("Error deactivating plugin '$plugin'");
			}

			\Vvveb\System\CacheManager::clearObjectCache('admin-menu');
			\Vvveb\System\CacheManager::clearCompiledFiles();
			\Vvveb\System\CacheManager::clearPageCache();

			return ['operation' => $operation, 'plugin' => $plugin, 'success' => true];
		}

		if (!\Vvveb\System\Extensions\Plugins::uninstall($plugin, $siteId)) {
			throw new \RuntimeException("Error removing plugin '$plugin'");
		}

		return ['operation' => $operation, 'plugin' => $plugin, 'success' => true];
	}

	/**
	 * Normalize caller-supplied media metadata into model rows.
	 *
	 * Accepts a single flat row (e.g. `['caption' => 'x']`), a list of
	 * rows, or a language-keyed map (e.g. `[1 => ['caption' => 'x']]`)
	 * and returns a list of rows each carrying a language_id and a name
	 * default derived from the file base name via humanReadable.
	 *
	 * @param string                  $file    Media-relative file path.
	 * @param array<array-key, mixed> $content Raw metadata.
	 *
	 * @return list<array<string, mixed>> Normalized rows.
	 */
	private function normalizeMediaContentRows(string $file, array $content): array {
		$languageId  = $this->global['language_id'] ?? $this->global['default_language_id'] ?? 1;
		$defaultName = humanReadable((string)pathinfo(str_replace('\\', '/', $file), PATHINFO_FILENAME));

		$isRowList = false;

		foreach ($content as $value) {
			if (is_array($value)) {
				$isRowList = true;

				break;
			}
		}

		if ($isRowList) {
			$rows = [];

			foreach ($content as $key => $row) {
				if (!is_array($row)) {
					continue;
				}

				if (!isset($row['language_id'])) {
					$row['language_id'] = (is_int($key) && $key > 0 && $key < 10000) ? $key : $languageId;
				}

				if (!isset($row['name']) || $row['name'] === '') {
					$row['name'] = $defaultName;
				}

				$rows[] = $row;
			}

			if ($rows !== []) {
				return $rows;
			}
		}

		if (!$isRowList) {
			$row = $content;

			if (!isset($row['language_id'])) {
				$row['language_id'] = $languageId;
			}

			if (!isset($row['name']) || $row['name'] === '') {
				$row['name'] = $defaultName;
			}

			return [$row];
		}

		return [['name' => $defaultName, 'language_id' => $languageId]];
	}

	/**
	 * Upsert a media library metadata record by file path.
	 *
	 * Shared by the save operation and uploads carrying metadata. New
	 * records fall back to the file base name run through humanReadable
	 * when the caller supplies no explicit name.
	 *
	 * @param string               $file    Media-relative file path.
	 * @param array<string, mixed> $content Metadata key/value pairs.
	 * @param string|null          $type    MIME type for new records.
	 *
	 * @return mixed[] Model result.
	 */
	private function upsertMediaContentRecord(string $file, array $content, ?string $type = null): array {
		$media    = \Vvveb\model('media_content');
		$existing = $media->get(['file' => $file] + $this->global);
		$rows     = $this->normalizeMediaContentRows($file, $content);

		if ($existing) {
			$result = $media->edit(['media_id' => $existing['media_id'], 'media_content' => $rows, 'media' => []]);
		} else {
			$mediaRow = ['file' => $file];

			if ($type !== null && $type !== '') {
				$mediaRow['type'] = $type;
			}

			$result = $media->add(['media' => $mediaRow, 'media_content' => $rows]);
		}

		return $result ?? [];
	}

	/**
	 * Cap for decoded upload bytes: the lower of the MCP cap and the server
	 * upload_max_filesize, checked on the base64 length before allocating.
	 */
	private function mediaUploadByteCap(): int {
		try {
			$serverMax = \Vvveb\parseQuantity((string)ini_get('upload_max_filesize'));
		} catch (\Throwable $e) {
			$serverMax = 0;
		}

		if ($serverMax > 0) {
			return min(self::MEDIA_UPLOAD_MAX_BYTES, (int)$serverMax);
		}

		return self::MEDIA_UPLOAD_MAX_BYTES;
	}

	/**
	 * Store a base64 upload: decode to temp, run the shared file core for
	 * the full validation chain, then register the library metadata record
	 * (file base name via humanReadable, caller content merged on top).
	 *
	 * @param array<string, mixed> $args Tool arguments.
	 *
	 * @return mixed[] Upload result plus metadata record result.
	 */
	private function toolMediaUpload(array $args): array {
		$fileName = trim((string)($args['file_name'] ?? ''));
		$data     = (string)($args['data'] ?? '');
		$path     = trim((string)($args['path'] ?? ''));

		if ($fileName === '') {
			throw new \InvalidArgumentException("Missing required argument 'file_name' for tool 'media' operation 'upload'");
		}

		if ($data === '') {
			throw new \InvalidArgumentException("Missing required argument 'data' (base64 file bytes) for tool 'media' operation 'upload'");
		}

		$cap = $this->mediaUploadByteCap();

		if ((int)(strlen($data) * 3 / 4) > $cap) {
			throw new \McpToolError('Upload exceeds the media tool cap, use a smaller file or url import.');
		}

		$bytes = base64_decode($data, true);

		if ($bytes === false) {
			throw new \InvalidArgumentException("Invalid argument 'data' for tool 'media' operation 'upload': not valid base64");
		}

		if (strlen($bytes) > $cap) {
			throw new \McpToolError('Upload exceeds the media tool cap, use a smaller file or url import.');
		}

		$tmp = tempnam(sys_get_temp_dir(), 'mcp-upload-');

		if ($tmp === false || file_put_contents($tmp, $bytes) === false) {
			@unlink((string)$tmp);

			throw new \RuntimeException('Could not stage upload for processing.');
		}

		$byteLen = strlen($bytes);
		unset($bytes, $data);

		try {
			$stored = $this->storeMediaFile($tmp, $fileName, $path, [
				'overwrite' => (bool)($args['overwrite'] ?? false),
				'size'      => $byteLen,
			]);
		} finally {
			@unlink($tmp);
		}

		if (!$stored['success']) {
			return $stored;
		}

		$content = $args['media_content'] ?? null;

		if (is_array($content) && $content !== []) {
			$stored['record'] = $this->upsertMediaContentRecord($stored['file'], $content);
		} else {
			$stored['record'] = $this->createMediaRecord($stored['file']);
		}

		return $stored;
	}

	/**
	 * Fetch a remote file by URL into the media library: download with
	 * redirect/SSRF/size/type guards to temp, then run the exact same tail
	 * as upload (storeMediaFile validation chain plus metadata record).
	 * Sits behind the media db_write gate like upload.
	 *
	 * @param array<string, mixed> $args Tool arguments.
	 *
	 * @return mixed[] Stored-file result plus source info and optional record.
	 */
	private function toolMediaFetch(array $args): array {
		$url      = trim((string)($args['url'] ?? ''));
		$path     = trim((string)($args['path'] ?? ''));
		$given    = trim((string)($args['file_name'] ?? ''));

		if ($url === '') {
			throw new \InvalidArgumentException("Missing required argument 'url' for tool 'media' operation 'fetch'");
		}

		$storedCap   = $this->mediaUploadByteCap();
		$transferCap = $storedCap * 4;
		$dl          = $this->mediaFetchDownload($url, $transferCap, $storedCap);

		$fileName = self::mediaFetchFileName($given !== '' ? $given : null, $dl['url'], $dl['contentType']);

		//a missing sub-path used to die later in storeMediaFile with a bare
		//'Invalid upload!': create it here so fetch names its own folder
		$this->ensureMediaPath($path);

		try {
			$stored = $this->storeMediaFile($dl['tmp'], $fileName, $path, [
				'overwrite' => (bool)($args['overwrite'] ?? false),
				'size'      => $dl['size'],
			]);
		} finally {
			@unlink($dl['tmp']);
		}

		if (!$stored['success']) {
			return $stored + ['source_url' => $dl['url']];
		}

		$stored['source_url']   = $dl['url'];
		$stored['content_type'] = $dl['contentType'];

		if (!empty($dl['note'])) {
			$stored['note'] = $dl['note'];
		}

		$content = $args['media_content'] ?? null;

		if (is_array($content) && $content !== []) {
			$stored['record'] = $this->upsertMediaContentRecord($stored['file'], $content, $dl['contentType']);
		} else {
			$stored['record'] = $this->createMediaRecord($stored['file'], $dl['contentType']);
		}

		return $stored;
	}

	/**
	 * Create a missing media sub-path for fetch (nested, sandboxed).
	 * storeMediaFile only realpaths existing dirs, so without this a
	 * first-time folder fails with a bare 'Invalid upload!'. Throws
	 * McpToolError with the actual reason. Pure filesystem, tested.
	 *
	 * @param string $path
	 */
	private function ensureMediaPath(string $path): void {
		$path = trim(str_replace('\\', '/', $path), '/');

		if ($path === '') {
			return;
		}

		$mediaDir = rtrim($this->dirMedia, DS) . DS;
		$current  = $mediaDir;

		foreach (explode('/', $path) as $segment) {
			$segment = sanitizeFileName($segment);

			if ($segment === '' || $segment === '.' || $segment === '..') {
				throw new \McpToolError("Media fetch refused: invalid path '$path'.");
			}

			$current .= $segment . DS;

			if (!is_dir($current) && !@mkdir($current, 0755)) {
				throw new \McpToolError("Media fetch cannot create folder '$path'.");
			}
		}

		$real = realpath($mediaDir . str_replace('/', DS, $path));

		if ($real === false || !str_starts_with(rtrim($real, DS) . DS, $mediaDir)) {
			throw new \McpToolError("Media fetch refused: path '$path' escapes the media library.");
		}
	}

	/**
	 * Derive the library file name for a fetch: explicit file_name wins,
	 * else the URL path basename, with the extension mapped from the
	 * response Content-Type when missing. Pure (no IO) for testability.
	 *
	 * @param ?string $given
	 * @param string  $url
	 * @param string  $contentType
	 */
	private static function mediaFetchFileName(?string $given, string $url, string $contentType): string {
		if ($given !== null && $given !== '') {
			return $given;
		}

		$base = (string)(basename((string)parse_url($url, PHP_URL_PATH)) ?: '');
		$base = trim(urldecode($base));

		if ($base === '' || $base === '.' || str_contains($base, "\0")) {
			$base = 'fetch';
		}

		if (!str_contains(pathinfo($base, PATHINFO_BASENAME), '.')) {
			$map = [
				'image/jpeg' => '.jpg', 'image/png' => '.png', 'image/gif' => '.gif',
				'image/webp' => '.webp', 'image/svg+xml' => '.svg', 'image/avif' => '.avif',
				'image/bmp'  => '.bmp', 'image/x-icon' => '.ico',
			];
			$base .= $map[strtolower(trim($contentType))] ?? '';
		}

		return $base;
	}

	/**
	 * Downscale an oversized raster image to fit the stored cap instead
	 * of refusing it. Returns [tmp, size, note]. GIFs refuse (resizing
	 * flattens animation, silently destroying intent); vectors and
	 * non-images never reach here. Pure filesystem + resizer, tested.
	 *
	 * @param string $tmp
	 * @param string $type
	 * @param int    $cap
	 * @param string $url
	 *
	 * @return array{0: string, 1: int, 2: string|null}
	 */
	private function mediaFetchFitImage(string $tmp, string $type, int $cap, string $url): array {
		if ($type === 'image/gif') {
			@unlink($tmp);

			throw new \McpToolError("Media fetch of '$url' exceeds the media tool cap and is animated GIF - resize would flatten it, use a smaller file.");
		}

		$maxDim = 2048;

		try {
			$configured = config('mcp.tools.image_max_dim', 2048);
			if (is_numeric($configured) && (int)$configured >= 256) {
				$maxDim = min(4096, (int)$configured);
			}
		} catch (\Throwable $e) {
		}

		$info = @getimagesize($tmp);
		if (!is_array($info) || $info[0] <= 0 || $info[1] <= 0) {
			@unlink($tmp);

			throw new \McpToolError("Media fetch of '$url' exceeds the media tool cap, use a smaller file.");
		}

		[$w, $h] = [(int)$info[0], (int)$info[1]];

		//already small enough in pixels: same-dim quality pass instead of
		//a pointless upscale (tiny noisy files can still exceed the cap)
		$small = max($w, $h) <= $maxDim;

		if ($w * $h > 50000000) {
			@unlink($tmp);

			throw new \McpToolError("Media fetch of '$url' is {$w}x{$h}px, too many pixels to process safely - use a smaller file.");
		}

		$out = $tmp . '.fit';

		try {
			if ($small) {
				$tw      = $w;
				$th      = $h;
				$quality = 70;
			} else {
				$tw      = $w >= $h ? $maxDim : 0;
				$th      = $w >= $h ? 0 : $maxDim;
				$quality = 82;
			}
			if (!\Vvveb\System\Images::resize($tmp, $out, $tw, $th, 'r', $quality)) {
				@unlink($tmp);

				throw new \McpToolError("Media fetch of '$url' exceeds the media tool cap, use a smaller file.");
			}
			$newSize = filesize($out) ?: 0;
			if ($newSize <= 0 || $newSize > $cap) {
				@unlink($tmp);
				@unlink($out);

				throw new \McpToolError("Media fetch of '$url' still exceeds the media tool cap after resize, use a smaller file.");
			}
		} catch (\McpToolError $e) {
			throw $e;
		} catch (\Throwable $e) {
			@unlink($tmp);
			@unlink($out);

			throw new \McpToolError("Media fetch of '$url' exceeds the media tool cap, use a smaller file.");
		}

		@unlink($tmp);
		$note = "Resized {$w}x{$h} to fit the media tool cap.";

		try {
			$fit = @getimagesize($out);
			if (is_array($fit)) {
				$note = "Resized {$w}x{$h} to {$fit[0]}x{$fit[1]} to fit the media tool cap.";
			}
		} catch (\Throwable $e) {
		}

		return [$out, $newSize, $note];
	}

	/**
	 * Download a URL to temp for media fetch, with the guards upload gets
	 * plus web ones: per-hop SSRF validation (DNS-rebinding safe via
	 * CURLOPT_RESOLVE pinning, like Vvveb\download), manual redirect chain
	 * (max 4, each hop re-validated), Content-Length pre-check and an
	 * in-transfer cap, connect/total timeouts, and an image Content-Type
	 * allowlist. All routine failures throw McpToolError (no log flood).
	 *
	 * A test seam: config mcp.tools.fetch_allow_private (default false)
	 * skips the private-IP refusal so the suite can run a local fixture
	 * server. Never enable outside tests.
	 *
	 * @param string $url
	 * @param int    $transferCap
	 * @param int    $storedCap
	 *
	 * @return array{tmp: string, url: string, contentType: string, size: int, note: string|null}
	 */
	private function mediaFetchDownload(string $url, int $transferCap, int $storedCap): array {
		if (!function_exists('curl_init')) {
			throw new \McpToolError("Media fetch needs the curl extension to download '$url'.");
		}

		$allowPrivate = config('mcp.tools.fetch_allow_private', false) === true;
		$current      = $url;

		for ($hop = 0; $hop <= 4; $hop++) {
			$ips = \Vvveb\validateUrl($current);

			if (!$ips && !$allowPrivate) {
				throw new \McpToolError("Media fetch refused '$current': URL must be public http(s) on port 80/443 with no private or reserved IP.");
			}

			$tmp = tempnam(sys_get_temp_dir(), 'mcp-fetch-');

			if ($tmp === false) {
				throw new \RuntimeException('Could not stage fetch for processing.');
			}

			$fh = fopen($tmp, 'w');

			if ($fh === false) {
				@unlink($tmp);

				throw new \RuntimeException('Could not stage fetch for processing.');
			}

			$headers = [];
			$ch      = curl_init($current);
			curl_setopt($ch, CURLOPT_FILE, $fh);
			curl_setopt($ch, CURLOPT_FOLLOWLOCATION, false);
			//no FAILONERROR: error bodies are inspected below (bot-check
			//detection needs the bytes); status is checked explicitly
			curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
			curl_setopt($ch, CURLOPT_TIMEOUT, 15);
			curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT'] ?? 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36');
			curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: image/avif,image/webp,image/apng,image/*,*/*;q=0.8', 'Accept-Language: en-US,en;q=0.9']);
			curl_setopt($ch, CURLOPT_HEADERFUNCTION, function($ch, $line) use (&$headers) {
				$parts = explode(':', $line, 2);

				if (count($parts) === 2) {
					$headers[strtolower(trim($parts[0]))] = trim($parts[1]);
				}

				return strlen($line);
			});
			//transfer cap is 4x the stored cap: oversized images finish
			//downloading so they can be resized below; absurd transfers
			//still abort here before eating memory
			curl_setopt($ch, CURLOPT_NOPROGRESS, false);
			curl_setopt($ch, CURLOPT_PROGRESSFUNCTION, fn ($ch, $dlTotal, $dlNow) => $dlNow > $transferCap ? 1 : 0);

			if ($ips) {
				curl_setopt($ch, CURLOPT_RESOLVE, $ips);
			}

			$ok    = curl_exec($ch);
			$code  = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
			$errno = curl_errno($ch);
			fclose($fh);

			//aborted by the progress cap (CURLE_ABORTED_BY_CALLBACK): the
			//transfer itself was fine, the file is just too big
			if (!$ok && $errno === 42) {
				@unlink($tmp);

				throw new \McpToolError('Fetched file exceeds the media tool cap, use a smaller file.');
			}

			//manual redirect: re-validate the next hop from scratch
			if ($ok && in_array($code, [301, 302, 303, 307, 308], true) && isset($headers['location'])) {
				@unlink($tmp);
				$next = trim($headers['location']);

				if ($next === '') {
					throw new \McpToolError("Media fetch of '$url' got an empty redirect.");
				}

				//resolve relative Location against the current URL (core,
				//RFC 3986: plain string-append gets directory resolution wrong)
				if (!preg_match('#^https?://#i', $next)) {
					$next = \Vvveb\resolveUrl($current, $next);
				}

				$current = $next;

				continue;
			}

			if (!$ok || $code !== 200) {
				$head = (string)@file_get_contents($tmp, false, null, 0, 4096);
				@unlink($tmp);
				if (\Vvveb\isChallengePage($head)) {
					throw new \McpToolError("Media fetch of '$url' is blocked by a bot check (HTTP $code) no script can pass - open the URL in your browser and upload the file, or choose another source.");
				}

				throw new \McpToolError("Media fetch of '$url' failed (HTTP $code).");
			}

			$size = filesize($tmp) ?: 0;

			if ($size <= 0) {
				@unlink($tmp);

				throw new \McpToolError('Fetched file is empty, use another source.');
			}

			$type    = strtolower(trim(explode(';', $headers['content-type'] ?? '')[0]));
			$allowed = ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml', 'image/avif', 'image/bmp', 'image/x-icon'];

			if (!in_array($type, $allowed, true)) {
				@unlink($tmp);

				throw new \McpToolError("Media fetch of '$url' refused: Content-Type '$type' is not a supported image type.");
			}

			$fitNote = null;

			if ($size > $storedCap) {
				[$tmp, $size, $fitNote] = $this->mediaFetchFitImage($tmp, $type, $storedCap, $url);
			}

			return ['tmp' => $tmp, 'url' => $current, 'contentType' => $type, 'size' => $size, 'note' => $fitNote];
		}

		@unlink($tmp);

		throw new \McpToolError("Media fetch of '$url' gave up after too many redirects.");
	}

	/**
	 * media tool: media library metadata and file operations.
	 *
	 * Top-level since its parameter set dwarfs the other admin stubs; also
	 * reachable via the admin tool (target media) as a deprecated alias.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{operation: string, result: mixed}
	 */
	public function toolMedia(array $args): array {
		$operation = trim((string)($args['operation'] ?? ''));
		$file      = trim((string)($args['file'] ?? ''));
		$content   = $args['content'] ?? null;
		$params    = $args['params'] ?? [];

		//scan/search report root-relative paths with a leading slash: strip
		//it back here so file args round-trip into DB lookups and stored
		//rows verbatim (stored format has no leading slash)
		foreach (['file', 'path', 'newfile'] as $slashKey) {
			if (isset($args[$slashKey]) && is_string($args[$slashKey])) {
				$args[$slashKey] = ltrim(trim($args[$slashKey]), '/');
			}
		}

		$file = (string)($args['file'] ?? '');

		$allowedOps = ['list', 'get', 'save', 'delete', 'upload', 'fetch', 'mkdir', 'rename', 'scan'];

		if (!in_array($operation, $allowedOps, true)) {
			throw new \InvalidArgumentException("Invalid operation '$operation' for tool 'media'. Allowed: " . implode(', ', $allowedOps));
		}

		if ($operation === 'scan') {
			$scanPath   = trim((string)($args['path'] ?? ''));
			$scanLevels = isset($args['levels']) ? max(1, min(3, (int)$args['levels'])) : 1;
			$scanSearch = trim((string)($args['search'] ?? ''));
			$scanLimit  = isset($args['limit']) ? max(1, min(200, (int)$args['limit'])) : 200;
			$scanStart  = isset($args['start']) ? max(0, (int)$args['start']) : 0;

			return ['operation' => $operation, 'result' => $this->listMedia($scanPath, $scanLevels, $scanSearch, '', $scanLimit, $scanStart)];
		}

		if (!is_array($params)) {
			throw new \InvalidArgumentException("Invalid params for tool 'media'. params must be an object with key/value pairs.");
		}

		$media = \Vvveb\model('media_content');

		if ($operation === 'list') {
			$result = $media->getAll($params + $this->global);

			return ['operation' => $operation, 'result' => $result ?? []];
		}

		if (in_array($operation, ['get', 'save'], true) && $file === '') {
			throw new \InvalidArgumentException("Missing required argument 'file' for tool 'media' operation '$operation'");
		}

		if ($operation === 'get') {
			$result = $media->getContent(['file' => $file] + $this->global);

			return ['operation' => $operation, 'result' => $result ?? []];
		}

		if (config('mcp.tools.db_write', false) !== true) {
			throw new \McpToolError("Writes are disabled - enable mcp.tools.db_write to allow $operation on media.");
		}

		if ($operation === 'upload') {
			return ['operation' => $operation, 'result' => $this->toolMediaUpload($args)];
		}

		if ($operation === 'fetch') {
			return ['operation' => $operation, 'result' => $this->toolMediaFetch($args)];
		}

		if ($operation === 'mkdir') {
			$folder = trim((string)($args['folder'] ?? ''));
			$path   = trim((string)($args['path'] ?? ''));

			if ($folder === '') {
				throw new \InvalidArgumentException("Missing required argument 'folder' for tool 'media' operation 'mkdir'");
			}

			return ['operation' => $operation, 'result' => $this->createMediaFolder($path, $folder)];
		}

		if ($operation === 'rename') {
			$newfile = trim((string)($args['newfile'] ?? ''));
			$newname = trim((string)($args['newname'] ?? ''));

			if ($file === '') {
				throw new \InvalidArgumentException("Missing required argument 'file' for tool 'media' operation 'rename'");
			}

			if ($newfile === '' && $newname === '') {
				throw new \InvalidArgumentException("Missing required argument 'newfile' or 'newname' for tool 'media' operation 'rename'");
			}

			return ['operation' => $operation, 'result' => $this->renameMediaFile($file, $newfile, $newname, (bool)($args['duplicate'] ?? false))];
		}

		if ($operation === 'save') {
			if (!is_array($content) || $content === []) {
				throw new \InvalidArgumentException("Missing required argument 'content' for tool 'media' operation 'save'");
			}

			return ['operation' => $operation, 'result' => $this->upsertMediaContentRecord($file, $content)];
		}

		$mediaId = $args['media_id'] ?? null;

		if ($mediaId === null && $file === '') {
			throw new \InvalidArgumentException("Missing required argument 'media_id' or 'file' for tool 'media' operation 'delete'");
		}

		$options = [];

		if ($mediaId !== null) {
			$options['media_id'] = [(int)$mediaId];
		}

		if ($file !== '') {
			$options['file'] = [$file];
		}

		$result = $media->delete($options + $this->global);

		return ['operation' => $operation, 'result' => $result ?? []];
	}

	/**
	 * Cron stub (via admin tool): CRUD for CMS cron jobs.
	 *
	 * list is always allowed; run/run_all execute job callbacks and require
	 * config key mcp.tools.db_write.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array<string, mixed>
	 */
	private function toolCron(array $args): array {
		$operation = trim((string)($args['operation'] ?? ''));
		$job       = trim((string)($args['job'] ?? ''));

		$allowedOps = ['list', 'run', 'run_all'];

		if (!in_array($operation, $allowedOps, true)) {
			throw new \InvalidArgumentException("Invalid operation '$operation' for tool 'cron'. Allowed: " . implode(', ', $allowedOps));
		}

		$jobs = [];

		foreach (\Vvveb\System\Cron::getCrons() as $priorities) {
			foreach ($priorities as $group) {
				foreach (array_keys($group) as $name) {
					$jobs[] = $name;
				}
			}
		}

		if ($operation === 'list') {
			return ['operation' => $operation, 'jobs' => $jobs, 'count' => count($jobs)];
		}

		if (config('mcp.tools.db_write', false) !== true) {
			throw new \McpToolError("Writes are disabled - enable mcp.tools.db_write to allow $operation on cron.");
		}

		if ($operation === 'run') {
			if ($job === '') {
				throw new \InvalidArgumentException("Missing required argument 'job' for tool 'cron' operation 'run'");
			}

			if (!preg_match('/^[A-Za-z0-9_.-]+$/', $job)) {
				throw new \InvalidArgumentException("Invalid cron job name: '$job'");
			}

			if (!in_array($job, $jobs, true)) {
				throw new \McpToolError("Unknown cron job: '$job'. Available jobs: " . implode(', ', $jobs));
			}

			return ['operation' => $operation, 'job' => $job, 'result' => \Vvveb\System\Cron::run($job)];
		}

		return ['operation' => $operation, 'result' => \Vvveb\System\Cron::runAll()];
	}

	/**
	 * Cache stub (via admin tool): CRUD for CMS caches (mirrors admin Tools/Cache).
	 *
	 * Single clear operation with a target selector; requires config key
	 * mcp.tools.db_write.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return array{operation: string, scope: string, success: bool}
	 */
	private function toolCache(array $args): array {
		$operation = trim((string)($args['operation'] ?? ''));
		$scope     = trim((string)($args['scope'] ?? 'all'));

		if ($operation !== 'clear') {
			throw new \InvalidArgumentException("Invalid operation '$operation' for tool 'cache'. Allowed: clear");
		}

		$scopes = ['all', 'template', 'page', 'database', 'frontend', 'image', 'model'];

		if (!in_array($scope, $scopes, true)) {
			throw new \InvalidArgumentException("Invalid scope '$scope' for cache. Allowed: " . implode(', ', $scopes));
		}

		if (config('mcp.tools.db_write', false) !== true) {
			throw new \McpToolError("Writes are disabled - enable mcp.tools.db_write to allow $operation on cache $scope.");
		}

		$host = trim((string)($args['host'] ?? ''));

		$success = match ($scope) {
			'all'      => \Vvveb\System\CacheManager::delete(),
			'template' => \Vvveb\System\CacheManager::clearCompiledFiles(),
			'page'     => \Vvveb\System\CacheManager::clearPageCache($host !== '' ? $host : null),
			'database' => \Vvveb\System\CacheManager::clearObjectCache(),
			'frontend' => \Vvveb\System\CacheManager::clearFrontend(),
			'image'    => \Vvveb\System\CacheManager::clearImageCache(),
			'model'    => \Vvveb\System\CacheManager::clearModelCache(),
		};

		return ['operation' => $operation, 'scope' => $scope, 'success' => (bool)$success];
	}

	/**
	 * str_replace_editor tool: unified filesystem editor (view/create/edit — multi-edit only).
	 *
	 * Wraps the native PHP StrReplaceEditor (mcp/str_replace_editor.php) with sandbox-aware
	 * path resolution via resolvePath()/toolRoot(). All paths are sandboxed inside the
	 * installation root. Only view, create and edit (multi-edit via edits[]) are exposed;
	 * single str_replace/insert are removed in favor of the unified multi-edit.
	 *
	 * @param array<string, mixed> $args
	 *
	 * @return string|array<string, mixed>
	 */
	public function toolStrReplaceEditor(array $args): mixed {
		$command = (string)($args['command'] ?? '');
		$rawPath = (string)($args['path'] ?? '');

		if ($command === '') {
			throw new \InvalidArgumentException("Missing required argument 'command' for tool 'str_replace_editor'");
		}
		if ($rawPath === '') {
			throw new \InvalidArgumentException("Missing required argument 'path' for tool 'str_replace_editor'");
		}
		if (!in_array($command, ['view', 'create', 'edit'], true)) {
			throw new \InvalidArgumentException("Invalid command '$command' for str_replace_editor. Allowed: view, create, edit");
		}

		// Resolve path inside sandbox. `create` may target a non-existing file, so mustExist=false.
		// `view` may target a directory; others require a file. resolvePath validates sandbox escape.
		$mustExist = $command !== 'create';
		$resolved  = $this->resolvePath($rawPath, $mustExist);

		// StrReplaceEditor expects an absolute path that passes its own resolveTarget check.
		// $resolved is already absolute (toolRoot + normalized relative) and sandbox-validated.
		$cwd    = $this->toolRoot();
		$editor = new \StrReplaceEditor(null, $cwd);

		$execArgs         = $args;
		$execArgs['path'] = $resolved;

		// Delegate to the native editor. It returns a formatted string (file view or success+diff).
		return $editor->execute($execArgs);
	}

	/* -----------------------------------------------------------------
	 * Tool helpers
	 * ----------------------------------------------------------------- */

	/**
	 * Sandbox root for file tools (defaults to the installation root).
	 */
	private function toolRoot(): string {
		$root = config('mcp.tools.root', DIR_ROOT);
		$real = realpath($root);

		return $real !== false ? rtrim($real, '/') : rtrim(DIR_ROOT, '/');
	}

	/**
	 * Resolve a user supplied path inside the sandbox root.
	 *
	 * @param string $path      Relative or absolute path
	 * @param bool   $mustExist Require the resolved path to exist
	 *
	 * @return string Absolute real path inside the sandbox
	 */
	private function resolvePath(string $path, bool $mustExist = true): string {
		if ($path === '') {
			throw new \McpToolError('Empty path');
		}

		$root = $this->toolRoot();
		if ($path[0] === '/' && ($path === $root || str_starts_with($path, $root . '/'))) {
			$path = substr($path, strlen($root));
		}

		//paths are always interpreted relative to the sandbox root; absolute
		//looking paths (/etc/passwd) simply map to <root>/etc/passwd which is
		//safer than honoring filesystem absolute paths
		$relative = ltrim(str_replace('\\', '/', $path), '/');

		//lexically normalize the path against the sandbox root; resolves '..'
		//and '.' segments without requiring any segment to exist
		$canonical = [];

		foreach (explode('/', trim($relative, '/')) as $segment) {
			if ($segment === '' || $segment === '.') {
				continue;
			}

			if ($segment === '..') {
				array_pop($canonical);
				continue;
			}

			$canonical[] = $segment;
		}

		$resolved = $root . '/' . implode('/', $canonical);

		//existing files must really live inside the sandbox (symlink check)
		if (file_exists($resolved)) {
			$real = realpath($resolved);

			if ($real !== false && !str_starts_with($real, $root)) {
				throw new \McpToolError("Path escapes the site root sandbox: $path");
			}
		} elseif ($mustExist) {
			throw new \McpToolError("File or directory not found: $path");
		}

		return $resolved;
	}

	/**
	 * Validate arguments against the tool inputSchema required list.
	 *
	 * @param string               $name
	 * @param array<string, mixed> $arguments
	 * @param array<string, mixed> $tool
	 *
	 * @return void
	 */
	private function validateRequiredArgs(string $name, array $arguments, array $tool): void {
		$required = $tool['inputSchema']['required'] ?? [];

		foreach ((array)$required as $field) {
			if (!isset($arguments[$field]) || $arguments[$field] === '') {
				throw new \InvalidArgumentException("Missing required argument '$field' for tool '$name'");
			}
		}
	}

	/**
	 * Wrap a handler result into an MCP tool result envelope.
	 *
	 * @param mixed $result
	 *
	 * @return array{content: array<int, mixed>, isError: false, structuredContent?: mixed}
	 */
	private function textResult($result): array {
		//compact encoding: pretty whitespace costs ~25% on every result
		//with zero information (humans format on read, agents never do)
		$flags = JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE;

		if (is_string($result)) {
			$text = $result;
		} elseif ($this->isAckShape($result)) {
			//pure acknowledgements (mkdir/rename): one message line for
			//content, full detail stays in structuredContent
			$text = (string)($result['message'] ?? '');
		} else {
			$text = (string)json_encode($result, $flags);
		}

		$out = [
			'content' => [['type' => 'text', 'text' => $text]],
			'isError' => false,
		];

		if (!is_string($result)) {
			$out['structuredContent'] = $result;
		}

		return $out;
	}

	/**
	 * Pure-ack shape: exactly success + message, nothing the caller needs
	 * verbatim (mkdir/rename confirmations). Anything richer stays whole.
	 *
	 * @param mixed $result
	 */
	private function isAckShape(mixed $result): bool {
		if (!is_array($result)) {
			return false;
		}

		$keys = array_keys($result);

		return count($keys) === 2 && in_array('success', $keys, true) && in_array('message', $keys, true);
	}

	/**
	 * Cap an error message for the model: some failures (DB driver dumps)
	 * run to many kilobytes, and a long error never helps the caller more
	 * than its head does. Full detail stays in the server log via DEBUG.
	 *
	 * @param string $message
	 * @param int    $max
	 */
	private static function trimToolError(string $message, int $max = 2000): string {
		if (function_exists('mb_strlen') && function_exists('mb_substr')) {
			if (mb_strlen($message) > $max) {
				return mb_substr($message, 0, $max) . '… [error truncated, see server log]';
			}

			return $message;
		}

		return strlen($message) > $max ? substr($message, 0, $max) . '… [error truncated, see server log]' : $message;
	}

	/**
	 * Build an MCP error tool result.
	 *
	 * @param string $message
	 *
	 * @return array{content: array<int, mixed>, isError: true}
	 */
	private function errorResult(string $message): array {
		return [
			'content' => [['type' => 'text', 'text' => $message]],
			'isError' => true,
		];
	}

	/**
	 * Detect the leading SQL statement type ignoring comments.
	 *
	 * @param string $query
	 */
	private static function statementType(string $query): string {
		$clean = preg_replace('/^\s*(--[^\n]*|#[^\n]*|\/\*.*?\*\/)+/s', '', $query) ?? $query;

		if (preg_match('/^\s*([a-zA-Z]+)/', $clean, $m)) {
			return strtoupper($m[1]);
		}

		return '';
	}

	/**
	 * Check whether a WITH (CTE) query contains write statements.
	 *
	 * @param string $query
	 */
	private static function containsWriteKeyword(string $query): bool {
		return (bool)preg_match('/\b(INSERT|UPDATE|DELETE|REPLACE|MERGE|ALTER|CREATE|DROP|TRUNCATE|RENAME|GRANT|REVOKE|CALL|LOAD|HANDLER|DO|SET)\b/i', $query);
	}

	/**
	 * Execute a registered admin action (admin-execute-action tool).
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return array{success: bool, data?: mixed, error?: string}
	 */
	public function admin_execute_action(array $params): array {
		$name = $params['action_name'] ?? '';
		$args = $params['parameters'] ?? [];

		if ($name === '') {
			return ['success' => false, 'error' => 'Missing action_name'];
		}

		try {
			[$result] = \Vvveb\System\Event::trigger('MCP', 'admin/execute', $args, $name);

			return ['success' => true, 'data' => $result];
		} catch (Throwable $e) {
			return ['success' => false, 'error' => $e->getMessage()];
		}
	}

	/**
	 * List available prompts.
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return array{prompts: array<int, array<string, mixed>>, nextCursor: string}
	 */
	public function prompts_list(array $params): array {
		return [
			'prompts' => [
				[
					'name'        => 'code_review',
					'title'       => 'Request Code Review',
					'description' => 'Asks the LLM to analyze code quality and suggest improvements',
					'arguments'   => [
						[
							'name'        => 'code',
							'description' => 'The code to review',
							'required'    => true
						]
					],
					'icons' => [
						[
							'src'      => 'https://example.com/review-icon.svg',
							'mimeType' => 'image/svg+xml',
							'sizes'    => [
								'any'
							]
						]
					]
				]
			],
			'nextCursor' => 'next-page-cursor'
		];
	}

	/**
	 * Get a specific prompt.
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return array{description: string, messages: array<int, array<string, mixed>>}
	 */
	public function prompts_get(array $params): array {
		return [
			'description' => 'Code review prompt',
			'messages'    => [
				[
					'role'    => 'user',
					'content' => [
						'type' => 'text',
						'text' => 'Please review this Python code:
		def hello():
			print(\'world\')'
					]
				]
			]
		];
	}

	/**
	 * Handle notifications/initialized event.
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return void
	 */
	public function notifications_initialized(array $params): void {}

	/**
	 * Handle delete event.
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return void
	 */
	public function delete(array $params): void {}

	/**
	 * List available resources.
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return array{resources: array<int, mixed>}
	 */
	public function resources_list(array $params): array {
		return ['resources' => []];
	}

	/**
	 * Read a resource.
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return void
	 */
	public function resources_read(array $params): void {}

	/**
	 * Server discovery endpoint.
	 *
	 * @param array<string, mixed> $params
	 *
	 * @return void
	 */
	public function server_discover(array $params): void {}

	/**
	 * Initialize the MCP session and return capabilities.
	 *
	 * @return array{protocolVersion: string, capabilities: array<string, mixed>, serverInfo: array{name: string, version: string}}
	 */
	public function initialize(): array {
		$this->session  = Session::getInstance();
		$sessionId      = $this->session->sessionId();
		header("Mcp-Session-Id: $sessionId");

		return [
			'protocolVersion' => $this->version,
			'capabilities'    => [
				'tools' => [
					'listChanged' => false
				],
				'resources' => [
					'subscribe'   => false,
					'listChanged' => false
				],
				'prompts' => [
					'listChanged' => false
				]
			],
			'serverInfo' => [
				'name'    => 'Vvveb',
				'version' => V_VERSION
			]
		];
	}

	/**
	 * Main MCP index action: parse JSON-RPC request and dispatch to handler.
	 *
	 * @return void
	 */
	public function index(): void {
		$rawInput = file_get_contents('php://input');
		$input    = [];

		if (($input = json_decode($rawInput, true)) === null) {
			$this->notFound('Parse error', -32700);
		}

		$this->response->output = false;

		$result = [];
		if (isset($input['method']) && ($method = $input['method'])) {
			$params = $input['params'] ?? [];

			switch ($method) {
				case 'initialize':
					$result = $this->initialize();
					break;
				case 'tools/list':
					$result = $this->tools_list($params);
					break;
				case 'notifications/initialized':
					$this->notifications_initialized($params);
					$result = null;
					break;
				case 'resources/list':
					$result = $this->resources_list($params);
					break;
				case 'prompts/list':
					$result = $this->prompts_list($params);
					break;
				case 'tools/call':
					$result = $this->tools_call($method, $params);
					break;
				case 'server/discover':
					$this->server_discover($params);
					$result = null;
					break;
				default:
					if (!function_exists($method)) {
						$this->notFound('Method not found', -32601);
					}
			}
		} else {
			$this->notFound('Invalid Request', -32600);
		}

		$id = (int)($this->session->get('id') ?? 0);

		$output = [
			'jsonrpc' => '2.0',
			'id'      => $id,
			'result'  => $result
		];

		$this->session->set('id', ++$id);

		echo json_encode($output, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

		/*
		$this->response->setType('json');
		$this->response->output = true;
		$this->response->output($output);
		 */
	}
}