<?php

declare(strict_types=1);

/**
 * 本文件属于 DBErp 进销存系统。
 *
 * 版权所有 © 2026 北京珑大钜商科技有限公司。保留所有权利。
 *
 * 未经官方授权，不得删除、篡改或隐藏本文件中的版权声明、产品标识与来源信息。
 * 商业授权、官方更新与技术支持服务，请以珑大官方支持中心记录为准。
 *
 * @link https://support.loongdom.cn
 * @see  https://www.dberp.com.cn
 */

namespace App\Tools;

use App\Tools\Contracts\Tool;
use App\Tools\Exceptions\DuplicateToolMappedNameException;
use App\Tools\Exceptions\DuplicateToolRegistrationException;
use App\Tools\Exceptions\ToolNotRegisteredException;
use App\Tools\Support\ToolMappedName;

/**
 * 显式 Tool 注册表。发现 API 只暴露 metadata；执行必须走 ToolExecutor。
 */
final class ToolRegistry
{
    /**
     * @var array<string, Tool>
     */
    private array $tools = [];

    public function register(Tool $tool): void
    {
        $name = $tool->metadata()->name;

        if (isset($this->tools[$name])) {
            throw DuplicateToolRegistrationException::forName($name);
        }

        $mapped = ToolMappedName::protocolName($name);

        if (ToolMappedName::isReserved($mapped)) {
            throw DuplicateToolMappedNameException::reserved($name, $mapped);
        }

        foreach ($this->tools as $existingName => $existing) {
            if (ToolMappedName::protocolName($existingName) === $mapped) {
                throw DuplicateToolMappedNameException::collision($existingName, $name, $mapped);
            }
        }

        $this->tools[$name] = $tool;
    }

    public function has(string $name): bool
    {
        return isset($this->tools[$name]);
    }

    public function get(string $name): ToolMetadata
    {
        return $this->metadata($name);
    }

    public function metadata(string $name): ToolMetadata
    {
        if (! isset($this->tools[$name])) {
            throw ToolNotRegisteredException::forName($name);
        }

        return $this->tools[$name]->metadata();
    }

    /**
     * @return list<ToolMetadata>
     */
    public function all(): array
    {
        return array_values(array_map(
            static fn (Tool $tool): ToolMetadata => $tool->metadata(),
            $this->tools,
        ));
    }

    /**
     * 仅供 ToolExecutor 解析实现。外部消费者禁止把 Registry 当执行入口。
     */
    public function resolveForExecution(string $name): ?Tool
    {
        return $this->tools[$name] ?? null;
    }
}
