@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/types/vite/index.d.ts

@@ -1,37 +1,84 @@
 import type { IncomingMessage, Server, ServerResponse } from 'node:http';
 import { MINIAPP_PLATFORM_VALUES, type MiniappPlatform } from '../miniapp-manifest/schema';
+/**
+ * {@link miniappManifest} 返回的 Vite 插件契约。
+ *
+ * @remarks
+ * 业务项目只需把 `miniappManifest()` 放入 `vite.config.ts` 的 `plugins` 数组，通常不需要直接构造该接口，
+ * 也不应手动调用这些 Vite hook。该接口不包含小程序声明；目标平台、权限、窗口、游戏绑定和 Companion
+ * 等配置统一来自距离 Vite `root` 最近的 `package.json#heybox`。
+ */
 export interface MiniappManifestPlugin {
+    /** 固定为 `heybox-miniapp-manifest`，同一份 Vite 配置必须且只能注册一个实例。 */
     name: string;
+    /** 校验资源基准路径，并向 Vite 注入 SDK 版本和开发期日志开关。 */
     config: (config: MiniappManifestUserConfig, env?: {
         command: 'build' | 'serve';
     }) => MiniappManifestUserConfig | void;
+    /** 记录 Vite 根目录、输出目录、运行命令和开发期 HMR 地址。 */
     configResolved: (resolved: MiniappManifestResolvedConfig) => void;
+    /** 为 `hb-sdk dev` 注册本机调试能力；生产构建不会创建开发服务。 */
     configureServer: (server: MiniappManifestDevServer) => void;
-    /** Rollup 在构建失败后仍会跑 closeBundle；用 buildEnd 记录真实错误，避免二次校验掩盖原因。 */
+    /** 保留 Rollup/Vite 已报告的构建错误，避免产物校验用二次错误掩盖原始原因。 */
     buildEnd: (error?: Error) => void;
+    /** 向入口 HTML 注入 Runtime Gate 和平台 CSP；serve 时还会加入受限的 HMR 与日志调试支持。 */
     transformIndexHtml: (html: string) => string;
+    /** serve 关闭时直接完成；生产构建结束时校验单页产物并写入 Manifest 和 Companion 归档。 */
     closeBundle: (this: MiniappManifestPluginContext) => Promise<void>;
 }
+/**
+ * {@link MiniappManifestPlugin.configureServer} 消费的最小 Vite 开发服务形状。
+ *
+ * @remarks
+ * 这是插件返回值暴露的 hook 类型，不是 `miniappManifest()` 的配置项。业务项目应让 Vite 创建并传入服务实例。
+ */
 export interface MiniappManifestDevServer {
+    /** Vite 底层 HTTP 服务；middleware mode 或尚未监听时可能为空。 */
     httpServer?: Server | null;
+    /** Vite 配置重载入口；插件会在重载期间保留当前本地调试快照。 */
     restart?: (forceOptimize?: boolean) => Promise<void>;
+    /** 用于挂载 `hb-sdk dev` 本机调试中间件的 Connect middleware 容器。 */
     middlewares: {
         use: (handler: (request: IncomingMessage, response: ServerResponse, next: () => void) => void) => void;
     };
 }
+/**
+ * {@link MiniappManifestPlugin.config} 读取和返回的最小 Vite 用户配置形状。
+ *
+ * @remarks
+ * 该接口描述 Vite hook 数据，不是插件 options；`miniappManifest()` 必须无参调用。小程序声明请写入
+ * `package.json#heybox`，不要写入 Vite 配置。
+ */
 export interface MiniappManifestUserConfig {
+    /**
+     * Vite 资源基准路径。省略时插件返回 `./`；显式配置只接受空字符串或 `./`，以便版本目录内相对加载资源。
+     */
     base?: string;
+    /** 插件返回给 Vite 的编译期常量；业务项目无需通过该接口传入或覆盖。 */
     define?: Record<string, string>;
 }
+/** {@link MiniappManifestPlugin.closeBundle} 使用的最小 Rollup 插件上下文。 */
 export interface MiniappManifestPluginContext {
+    /** 输出缺少迁移期声明等非阻断构建警告。 */
     warn: (message: string) => void;
 }
+/**
+ * {@link MiniappManifestPlugin.configResolved} 消费的最小 Vite 已解析配置形状。
+ *
+ * @remarks
+ * 这是 Vite 传给插件的 hook 数据，不是应用作者需要创建的 options。插件从中确定项目根目录、输出目录、
+ * serve/build 分支和 HMR WebSocket 白名单。
+ */
 export interface MiniappManifestResolvedConfig {
+    /** Vite 项目根目录；小程序配置从该目录向上找到的最近 `package.json` 读取。 */
     root: string;
+    /** `serve` 只准备本地调试，`build` 还会校验产物并生成 `manifest.json`。 */
     command: 'build' | 'serve';
+    /** Vite 构建输出目录；Manifest 和 Companion 归档写入该目录。 */
     build: {
         outDir: string;
     };
+    /** 开发服务网络配置，用于收窄注入 HTML 的 HMR WebSocket CSP。 */
     server: {
         host?: string | boolean;
         https?: boolean | Record<string, unknown>;
@@ -43,12 +90,123 @@ export interface MiniappManifestResolvedConfig {
             protocol?: 'ws' | 'wss';
         };
     };
+    /** 已解析插件列表；存在时用于拒绝重复注册 `miniappManifest()`。 */
     plugins?: readonly {
         name?: string;
     }[];
 }
 export { MINIAPP_PLATFORM_VALUES };
 export type { MiniappPlatform };
+/**
+ * `hb-sdk dev` 为本地 Companion 产物访问注入的进程环境变量名。
+ *
+ * @remarks
+ * 该变量由 CLI 管理，不是项目配置项。应用代码不应读取、设置、记录或转发它的值。
+ */
 export declare const HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = "HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN";
+/**
+ * `hb-sdk dev` 为本地小程序 Manifest 访问注入的进程环境变量名。
+ *
+ * @remarks
+ * 该变量由 CLI 管理，不是项目配置项。应用代码不应读取、设置、记录或转发它的值。
+ */
 export declare const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = "HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN";
+/**
+ * 创建工坊小程序使用的 Vite 插件。
+ *
+ * @returns 可直接加入 Vite `plugins` 数组的
+ * [MiniappManifestPlugin](/reference/symbols/vite/interfaces/MiniappManifestPlugin)。插件固定名为
+ * `heybox-miniapp-manifest`，并提供 `config`、`configResolved`、`configureServer`、`buildEnd`、
+ * `transformIndexHtml`、`closeBundle` hooks；这些 hooks 由 Vite 调用，应用代码不应手动调用。
+ * @throws `Error` `config` 阶段发现 Vite `base` 不是 `''` 或 `'./'`，或无法解析当前 SDK 版本时抛出。
+ * @throws `Error` `configResolved` 阶段发现已解析插件列表中 `miniappManifest()` 数量不是一个时抛出。
+ * @throws `Error` HTML 缺少 `<head>`，包含 `meta refresh`、`<base>`、禁止的 resource hint，或资源 URL
+ * 不符合小程序 HTML 策略时，`transformIndexHtml` / 生产产物复检抛出。
+ * @throws `Error` 生产构建无法读取或解析最近的 `package.json`，`version`、`heybox.platforms`、
+ * `heybox.permissions`、`heybox.window`、`heybox.bindAppIds` 或 `heybox.companions` 声明非法时抛出。
+ * @throws `Error` 生产 `build.outDir` 缺少根 `index.html`、递归发现额外 HTML，或 Companion 权限、
+ * 目标平台、来源目录、归档结构、入口二进制不符合约束时抛出；更早的 Rollup/Vite 错误会原样优先重抛。
+ *
+ * @remarks
+ * 该函数必须从 `@heybox/hb-sdk/vite` 导入，在 `vite.config.ts` 中无参调用且只注册一次；它不是
+ * iframe 业务代码 API，也没有 options 对象。小程序声明统一来自从 Vite `root` 向上找到的最近一个
+ * `package.json`，插件只读取和规范化，不会改写源文件：
+ *
+ * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
+ *   `0.0.0`；
+ * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序；
+ * - `heybox.permissions`：严格权限对象；未知权限/字段或错误类型会失败，`enabled: false` 项不写入
+ *   Manifest。旧版本缺失声明时可能警告，新硬切版本会失败；
+ * - `heybox.window`：可选的新 PC 开窗初值、最小尺寸和 `resizable` 声明；省略时不写该字段；
+ * - `heybox.bindAppIds`：可选的最多 20 个正 int32 字符串 App ID；校验、去重并按数值排序，空数组
+ *   在本地产物中等同不写；
+ * - `heybox.companions`：可选的受管桌面程序声明；`source` 相对上述 `package.json` 所在目录解析，
+ *   必须同时声明启用的 `companion` 权限和匹配的 Windows/macOS 目标平台。
+ *
+ * 产物中的 `sdkVersion` 来自当前实际安装的 `@heybox/hb-sdk`，不是项目可配置字段。Vite options、页面
+ * 代码和普通环境变量不能覆盖上述 package 声明；插件也不会联网确认 App ID、平台批准或远端版本状态。
+ *
+ * Hook 行为如下：
+ *
+ * - `config`：省略 `base` 时补为 `'./'`，显式值只接受 `''` / `'./'`；注入 SDK 构建版本，且仅
+ *   `vite serve` 注入开发日志编译常量；
+ * - `configResolved`：确认插件唯一性，记录真实 `root`、`build.outDir`、`serve|build` 命令和精确 HMR
+ *   WebSocket 地址；直接 `vite build` 使用该实际 `outDir`，`hb-sdk build` 则由 CLI 固定为 `dist/`；
+ * - `configureServer`：为 `hb-sdk dev` 注册设备日志、本地小程序 Manifest 与 Companion Manifest/ZIP
+ *   中间件；敏感路由只接受数值 loopback socket/Host、`GET|HEAD` 和 CLI 注入的独立短期令牌，快照在
+ *   配置重载时按 digest 保留，并在服务真正关闭时清理；
+ * - `transformIndexHtml`：校验 HTML URL/标签策略，注入 Runtime Gate；默认注入平台 CSP，serve 时
+ *   `connect-src` 只开放解析出的 HMR WebSocket，并额外注入调试日志 bootstrap；
+ * - `buildEnd`：记住更早的 Rollup/Vite 错误，避免 `closeBundle` 的二次产物错误遮盖根因；
+ * - `closeBundle`：serve 时直接完成；build 时复检最终 HTML，要求整个输出树只有根 `index.html`，再于
+ *   `build.outDir` 写入 `manifest.json`，并把 Companion 目录打包成
+ *   `companions/<alias>/<target>.zip`，记录 size、SHA-256、固定入口与 args。
+ *
+ * HTML 策略会隔离业务 script/modulepreload，直到父 Runtime Gate 以 namespace、版本、nonce、source
+ * 以及 referrer 可确定时的 origin 完成探测；失败时显示只能在小黑盒 App 内打开的安全页。策略拒绝自动跳转、`<base>`、危险
+ * resource hints 和不受支持的外部 URL，并按标签只允许相对 URL、明确允许的 `data:` / `blob:` 或
+ * 小黑盒官方 HTTPS 资源。开发者自行提供的 CSP 会保留；插件管理的 CSP marker 可重复转换而不会叠加。
+ *
+ * 平台 CSP 默认始终保留，直接 `vite build` / `hb-sdk build` 不会因项目声明
+ * `heybox.permissions.network.useOfficialDomain` 而跳过。只有官方 `hb-sdk dev` 或
+ * `hb-sdk remote deploy` 将当前版本的 `network` 声明与远端批准结果求交并确认最终启用后，才会
+ * 建立 verified 上下文供插件读取内部
+ * `HB_SDK_RUNTIME_PERMISSION_CONTEXT` + `HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN` 组合跳过平台 CSP；单独设置
+ * 任一值无效。0.8 兼容期对完全缺失权限声明的项目仍按迁移规则处理；`useOfficialDomain` 不参与
+ * CSP 跳过决定。Runtime Gate、HTML 校验和 Manifest 生成始终保留。
+ *
+ * `HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN`、`HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN`、
+ * `HB_SDK_SKIP_COMPANIONS` 以及上述 CSP 上下文均是 CLI/发布链路内部开关，不是项目配置项。它们在
+ * 插件创建时捕获；开发服务配置重载只会从同一服务的内存快照恢复 CLI 令牌。业务代码和 Vite 配置
+ * 不应手工设置、读取、记录或转发令牌值。正式声明必须继续写在 `package.json#heybox`，内部环境变量
+ * 不能替代声明校验。
+ *
+ * `manifest.json` 是 release pipeline 元数据，不是部署后供页面 fetch 的 CDN 资源。发布链路使用
+ * [isValidVersion](/reference/symbols/miniapp-publish/functions/isValidVersion) 复核版本、
+ * [resolveMiniappManifestPlatforms](/reference/symbols/miniapp-publish/functions/resolveMiniappManifestPlatforms)
+ * 解析平台硬切规则、
+ * [parseMiniappBindAppIds](/reference/symbols/miniapp-publish/functions/parseMiniappBindAppIds) 复核游戏绑定，
+ * 并通过 [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile) 将根
+ * `manifest.json` 排除出普通 CDN 文件。Web/Companion 上传预算由
+ * [validateUploadTotalSize](/reference/symbols/miniapp-publish/functions/validateUploadTotalSize) 等发布 helper
+ * 独立校验，不能用插件成功代替 deploy 预检。
+ *
+ * @example
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * import { miniappManifest } from '@heybox/hb-sdk/vite'
+ * import { defineConfig } from 'vite'
+ *
+ * export default defineConfig({
+ *   // base 省略时 miniappManifest() 会补为 './'
+ *   plugins: [vue(), miniappManifest()],
+ * })
+ * ```
+ *
+ * @see [MiniappManifestPlugin](/reference/symbols/vite/interfaces/MiniappManifestPlugin) 返回插件及各 hook 类型。
+ * @see [安装](/guide/installation) Vite 接入、相对资源路径和构建命令。
+ * @see [权限声明](/guide/permissions) `heybox.permissions` 严格 schema 与迁移规则。
+ * @see [窗口尺寸与可缩放性](/guide/window-size) `heybox.window` 字段与 Host 消费语义。
+ * @see [受管桌面程序](/guide/companion) Companion 声明、归档和本地联调边界。
+ */
 export declare function miniappManifest(): MiniappManifestPlugin;