/**
 * scalar-assets.ts — 本地 Scalar 资产自动检测、安装与路由注册
 *
 * 封装 @scalar/api-reference 包的完整生命周期：
 *   - 本地包检测（基于用户项目根目录的模块解析）
 *   - 自动包管理器识别（npm / pnpm / yarn / bun）
 *   - 首次启动自动安装（execSync，输出对用户可见）
 *   - 文件内容读取与内存缓存
 *   - 本地静态路由注册（GET /_vext/scalar.js）
 *
 * 设计原则：
 *   - 本地优先，零 CDN 依赖（openapi.enabled: true 时强制本地服务）
 *   - 用户配置 scalar.cdnUrl 时完全跳过（尊重显式配置）
 *   - 安装失败时抛出明确错误（不静默降级回 CDN）
 *
 * @module lib/openapi/scalar-assets
 * @changelog
 *   - v0.2.2: 初始版本（本地资产自动安装 + 本地路由注册）
 */
import type { VextApp } from "../../types/app.js";
/**
 * 注册本地 Scalar 资产路由（自动安装 + 本地服务，无 CDN 回退）
 *
 * 执行流程：
 *   1. 用户配置了 cdnUrl → 立即返回 null（不干预用户配置）
 *   2. 本地包已安装 → 读取文件 → 注册路由 → 返回本地路由路径
 *   3. 本地包未安装 → 自动安装 → 读取文件 → 注册路由 → 返回本地路由路径
 *   4. 任意步骤失败 → throw Error（含具体原因 + 手动修复命令）
 *
 * @param app                  VextApp 实例
 * @param userConfiguredCdnUrl 用户在 scalar.cdnUrl 中配置的地址（若存在则跳过）
 * @returns 本地路由路径（'/_vext/scalar.js'）或 null（用户已配置 cdnUrl）
 * @throws  包安装失败 / 文件读取失败时
 */
export declare function registerScalarAssets(app: VextApp, userConfiguredCdnUrl?: string): string | null;