@longzai-intelligence-vite/plugins 0.0.0-stage → 0.0.1

package/src/dist-manifest.plugin.ts

@@ -0,0 +1,239 @@
+/**
+ * 产物版本清单写入 vite 插件
+ */
+
+import type { Plugin } from 'vite';
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import * as z from 'zod';
+
+/**
+ * 包定义 schema，`name` 与 `version` 作为产物版本清单的真源
+ */
+const PkgSchema = z.object({
+  /**
+   * 包名
+   */
+  name: z.string(),
+
+  /**
+   * 版本号
+   */
+  version: z.string(),
+});
+
+/**
+ * 产物版本清单形态，字段与升级域解析服务的 zod 校验同构
+ */
+export type DistManifest = {
+  /**
+   * 包名
+   */
+  name: string;
+
+  /**
+   * 版本号
+   */
+  version: string;
+
+  /**
+   * 构建时刻的 ISO 时间戳
+   */
+  builtAt: string;
+
+  /**
+   * 构建时所在提交的短哈希，非 git 环境省略该键
+   */
+  gitCommit?: string;
+};
+
+/**
+ * 清单组装入参形态
+ */
+export type ComposeDistManifestInput = {
+  /**
+   * 包定义文件路径，缺省取进程工作目录下 `package.json`
+   *
+   * @default `path.join(process.cwd(), 'package.json')`
+   */
+  pkgPath?: string;
+
+  /**
+   * 提交短哈希推导函数，测试可注入桩替身
+   *
+   * @default `resolveGitCommit`
+   */
+  resolveCommit?: () => string;
+};
+
+/**
+ * 插件选项形态
+ */
+export type DistManifestPluginOptions = {
+  /**
+   * 包定义文件路径，缺省取插件工厂调用时进程工作目录下 `package.json`
+   *
+   * @default `path.join(process.cwd(), 'package.json')`
+   */
+  pkgPath?: string;
+
+  /**
+   * 写入产物目录的清单文件名
+   *
+   * @default `manifest.json`
+   */
+  manifestFileName?: string;
+};
+
+/**
+ * 推导当前提交短哈希
+ *
+ * @param cwd - git 仓库工作目录，缺省取进程工作目录
+ * @returns 七位短哈希，非 git 环境或执行失败时为空文本
+ */
+export function resolveGitCommit(cwd: string = process.cwd()): string {
+  try {
+    return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd,
+      encoding: 'utf-8',
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 组装产物版本清单
+ *
+ * @remarks
+ *   字段与写盘形态对齐发布脚本的清单约定，桌面宿主的升级域解析服务按产物目录内清单文件展示当前版本与构建时间，
+ *   治理沿革自 git-reviewer 仓 issue 0048，统一方案正本见本仓 `docs/ledgers/lzi-vite-adoption/`
+ * @param input - 清单组装入参，路径与哈希推导均可注入
+ * @returns 清单对象
+ */
+export function composeDistManifest(input: ComposeDistManifestInput = {}): DistManifest {
+  /**
+   * 包定义文件路径
+   */
+  const pkgPath = input.pkgPath ?? path.join(process.cwd(), 'package.json');
+
+  /**
+   * 本包定义，`name` 与 `version` 取自真源文件
+   */
+  const pkg = PkgSchema.parse(JSON.parse(readFileSync(pkgPath, 'utf-8')));
+
+  /**
+   * 提交短哈希推导函数
+   */
+  const resolveCommit = input.resolveCommit ?? resolveGitCommit;
+
+  /**
+   * 清单内容
+   */
+  const manifest: DistManifest = {
+    name: pkg.name,
+    version: pkg.version,
+    builtAt: new Date().toISOString(),
+  };
+
+  /**
+   * 当前提交短哈希
+   */
+  const gitCommit = resolveCommit();
+
+  if (gitCommit !== '') {
+    manifest.gitCommit = gitCommit;
+  }
+
+  return manifest;
+}
+
+/**
+ * 写盘入参形态
+ */
+export type WriteDistManifestInput = {
+  /**
+   * 产物目录绝对路径
+   */
+  outDir: string;
+
+  /**
+   * 包定义文件路径
+   *
+   * @default `path.join(process.cwd(), 'package.json')`
+   */
+  pkgPath?: string;
+
+  /**
+   * 清单文件名
+   *
+   * @default `manifest.json`
+   */
+  manifestFileName?: string;
+};
+
+/**
+ * 向产物目录写入版本清单
+ *
+ * @remarks
+ *   插件 `closeBundle` 钩子的写盘正体，独立导出以便消费方与测试直接复用
+ * @param input - 写盘入参
+ */
+export function writeDistManifest(input: WriteDistManifestInput): void {
+  /**
+   * 清单文件名
+   */
+  const manifestFileName = input.manifestFileName ?? 'manifest.json';
+
+  writeFileSync(
+    path.join(input.outDir, manifestFileName),
+    `${JSON.stringify(composeDistManifest({ pkgPath: input.pkgPath }), null, 2)}\n`,
+    'utf-8',
+  );
+}
+
+/**
+ * 产物版本清单写入插件工厂
+ *
+ * @remarks
+ *   构建收尾把清单写入产物目录，开发邻接解析层与打包基线均从该清单取版本与构建时间，
+ *   目录缺清单时界面将显示版本未知，产物目录经 `configResolved` 取解析后 `outDir` 以尊重命令行覆写
+ * @param options - 插件选项，包定义路径与清单文件名可覆写
+ * @returns vite 插件实例
+ */
+export function distManifestPlugin(options: DistManifestPluginOptions = {}): Plugin {
+  /**
+   * 包定义文件路径
+   */
+  const pkgPath = options.pkgPath ?? path.join(process.cwd(), 'package.json');
+
+  /**
+   * 清单文件名
+   */
+  const manifestFileName = options.manifestFileName ?? 'manifest.json';
+
+  /**
+   * 包定义在工厂期完成解析，配置装载期即暴露包定义缺失或形态错误
+   */
+  PkgSchema.parse(JSON.parse(readFileSync(pkgPath, 'utf-8')));
+
+  /**
+   * 解析后的产物目录，绝对路径
+   */
+  let resolvedOutDir = path.resolve(process.cwd(), 'dist');
+
+  return {
+    name: 'longzai-intelligence-dist-manifest',
+    apply: 'build',
+
+    configResolved(config) {
+      resolvedOutDir = config.build.outDir;
+    },
+
+    closeBundle() {
+      writeDistManifest({ outDir: resolvedOutDir, pkgPath, manifestFileName });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Vite 统一插件库入口
+ *
+ * 承载产物版本清单写入插件、端口发现插件与代理目标解析工具，
+ * 统一方案正本见本仓 `docs/ledgers/lzi-vite-adoption/`
+ */
+export {
+  composeDistManifest,
+  distManifestPlugin,
+  resolveGitCommit,
+  writeDistManifest,
+} from './dist-manifest.plugin.js';
+
+export type {
+  ComposeDistManifestInput,
+  DistManifest,
+  DistManifestPluginOptions,
+  WriteDistManifestInput,
+} from './dist-manifest.plugin.js';
+
+export { portDiscovery } from './port-discovery.plugin.js';
+
+export type { PortDiscoveryOptions } from './port-discovery.plugin.js';
+
+export { resolveProxyTarget } from './proxy-target.utils.js';

package/src/port-discovery.plugin.ts

@@ -0,0 +1,392 @@
+/**
+ * Vite 端口发现插件
+ *
+ * 在 vite dev server 启动时自动从注册表发现后端服务端口，并将前端自身端口写入注册表，
+ * 自 dev-tools 仓 `packages/vite-plugin` 承接迁入，统一方案正本见本仓 `docs/ledgers/lzi-vite-adoption/`
+ */
+
+import type { PortRegistryOptions, ServicePortInfo } from '@longzai-intelligence-port/registry';
+import type { Plugin, ViteDevServer } from 'vite';
+
+import { createPortRegistry } from '@longzai-intelligence-port/registry';
+
+/**
+ * 插件配置选项
+ */
+export type PortDiscoveryOptions = {
+  /**
+   * 要发现的后端服务名称，如 `data-server`
+   */
+  serviceName?: string;
+
+  /**
+   * 前端自身注册为的服务名称，如 `data-web`
+   */
+  registerAs?: string;
+
+  /**
+   * 等待后端服务的超时时间，单位毫秒
+   *
+   * @default 30000
+   */
+  timeout?: number;
+
+  /**
+   * 轮询间隔，单位毫秒
+   *
+   * @default 1000
+   */
+  pollInterval?: number;
+
+  /**
+   * 注册表配置选项
+   */
+  registryOptions?: PortRegistryOptions;
+};
+
+/**
+ * 默认超时时间，单位毫秒
+ */
+const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * 默认轮询间隔，单位毫秒
+ */
+const DEFAULT_POLL_INTERVAL = 1000;
+
+/**
+ * 从 vite dev server 获取实际监听端口
+ *
+ * @param server - vite dev server 实例
+ * @returns 实际监听端口号
+ */
+const getServerPort = (server: ViteDevServer): number => {
+  /**
+   * httpServer 地址信息
+   */
+  const address = server.httpServer?.address();
+  if (address && typeof address === 'object') {
+    return address.port;
+  }
+  return server.config.server.port ?? 5173;
+};
+
+/**
+ * 从 vite dev server 获取实际监听主机
+ *
+ * @param server - vite dev server 实例
+ * @returns 实际监听主机地址
+ */
+const getServerHost = (server: ViteDevServer): string => {
+  /**
+   * httpServer 地址信息
+   */
+  const address = server.httpServer?.address();
+  if (address && typeof address === 'object') {
+    return address.address || 'localhost';
+  }
+  return 'localhost';
+};
+
+/**
+ * 判断未知值是否为代理配置形态，结构守卫替代断言
+ *
+ * @param value - vite `server.config.proxy` 条目，类型面不透明
+ * @returns 是则收窄为可读取服务标识与目标地址的记录
+ */
+function isProxyLike(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * 判断代理条目是否需要更新目标，按自定义标头或未绑定端口特征识别
+ *
+ * @param proxyItem - vite proxy 配置条目，经结构守卫收窄
+ * @param serviceName - 后端服务名
+ * @returns 是否应更新
+ */
+const shouldUpdateProxy = (proxyItem: unknown, serviceName: string): boolean => {
+  /**
+   * 结构守卫后的代理配置对象
+   */
+  if (!isProxyLike(proxyItem)) {
+    return false;
+  }
+
+  /**
+   * 检查自定义标头中是否包含服务标识
+   */
+  if (proxyItem['x-service'] === serviceName) {
+    return true;
+  }
+
+  /**
+   * 检查代理目标是否为未绑定端口形态
+   */
+  if (typeof proxyItem.target === 'string') {
+    return proxyItem.target.includes('localhost:0') || proxyItem.target.includes('127.0.0.1:0');
+  }
+  return false;
+};
+
+/**
+ * 更新代理配置中的目标地址
+ *
+ * @remarks
+ *   遍历 `server.proxy` 中的全部代理项，将匹配后端服务特征的 `target` 替换为新地址
+ * @param server - vite dev server 实例
+ * @param serviceName - 后端服务名称
+ * @param newTarget - 新的代理目标地址
+ */
+const updateProxyTarget = (server: ViteDevServer, serviceName: string, newTarget: string): void => {
+  /**
+   * 代理配置
+   */
+  const proxyConfig = server.config.server.proxy;
+  if (!proxyConfig) return;
+
+  for (const [, proxyItem] of Object.entries(proxyConfig)) {
+    if (typeof proxyItem === 'object' && proxyItem !== null && 'target' in proxyItem) {
+      /**
+       * 当前代理目标
+       */
+      const currentTarget = String(proxyItem.target);
+      if (currentTarget.includes(serviceName) || shouldUpdateProxy(proxyItem, serviceName)) {
+        proxyItem.target = newTarget;
+
+        /**
+         * WebSocket 代理同步更新
+         */
+        if (proxyItem.ws) {
+          proxyItem.target = newTarget;
+        }
+        server.config.logger.info(`[端口发现] 代理目标已更新: ${serviceName} -> ${newTarget}`);
+      }
+    }
+  }
+};
+
+/**
+ * 轮询等待后端服务端口
+ *
+ * @remarks
+ *   每隔 `pollInterval` 毫秒检查一次注册表，超时后输出警告但不阻止启动
+ * @param serviceName - 后端服务名称
+ * @param registry - 端口注册表实例
+ * @param timeout - 超时时间，单位毫秒
+ * @param pollInterval - 轮询间隔，单位毫秒
+ * @returns 服务端口信息或 null
+ */
+const pollForService = async (
+  serviceName: string,
+  registry: ReturnType<typeof createPortRegistry>,
+  timeout: number,
+  pollInterval: number,
+): Promise<ServicePortInfo | null> => {
+  /**
+   * 开始时间
+   */
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeout) {
+    /**
+     * 尝试解析服务
+     */
+    const info = await registry.resolve(serviceName);
+    if (info) {
+      return info;
+    }
+
+    /**
+     * 等待下一次轮询
+     */
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+
+  return null;
+};
+
+/**
+ * 创建 vite 端口发现插件
+ *
+ * @remarks
+ *   在 dev server 启动时自动从注册表发现后端服务端口，并将前端自身端口写入注册表，
+ *   后端端口变化经注册表 `watch` 自动同步代理目标
+ * @param options - 插件配置选项
+ * @returns vite 插件实例
+ */
+const portDiscovery = (options?: PortDiscoveryOptions): Plugin => {
+  /**
+   * 要发现的后端服务名称
+   */
+  const serviceName = options?.serviceName;
+
+  /**
+   * 前端自身注册为的服务名称
+   */
+  const registerAs = options?.registerAs;
+
+  /**
+   * 超时时间
+   */
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+
+  /**
+   * 轮询间隔
+   */
+  const pollInterval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL;
+
+  /**
+   * 注册表配置选项
+   */
+  const registryOptions = options?.registryOptions;
+
+  /**
+   * 端口注册表实例
+   */
+  let registry: ReturnType<typeof createPortRegistry> | null = null;
+
+  /**
+   * watch 取消监听函数
+   */
+  let unwatch: (() => void) | null = null;
+
+  return {
+    name: 'longzai-intelligence-port-discovery',
+
+    apply: 'serve',
+
+    configureServer: async (server: ViteDevServer) => {
+      registry = createPortRegistry(registryOptions);
+
+      /**
+       * 获取 vite dev server 的实际端口和主机
+       */
+      const port = getServerPort(server);
+
+      /**
+       * 获取 vite dev server 的实际主机地址
+       */
+      const host = getServerHost(server);
+
+      /**
+       * 如果配置了 `registerAs`，将前端端口注册到端口注册表
+       */
+      if (registerAs) {
+        await registry.register(registerAs, {
+          port,
+          host: host === '::' ? 'localhost' : host,
+          pid: process.pid,
+          startedAt: Date.now(),
+        });
+        server.config.logger.info(
+          `[端口发现] 前端服务已注册: ${registerAs} -> http://${host}:${port}`,
+        );
+      }
+
+      /**
+       * 如果配置了 `serviceName`，从端口注册表轮询等待后端端口
+       */
+      if (serviceName) {
+        server.config.logger.info(`[端口发现] 正在等待后端服务: ${serviceName}...`);
+
+        /**
+         * 轮询等待后端服务
+         */
+        const info = await pollForService(serviceName, registry, timeout, pollInterval);
+
+        if (info) {
+          /**
+           * 后端服务主机地址
+           */
+          const backendHost = info.host === '0.0.0.0' ? 'localhost' : info.host;
+
+          /**
+           * 后端服务目标地址
+           */
+          const newTarget = `http://${backendHost}:${info.port}`;
+          server.config.logger.info(`[端口发现] 后端服务已发现: ${serviceName} -> ${newTarget}`);
+          updateProxyTarget(server, serviceName, newTarget);
+        } else {
+          server.config.logger.warn(
+            `[端口发现] 等待后端服务超时: ${serviceName}，已等待 ${timeout}ms，代理目标可能不正确`,
+          );
+        }
+
+        /**
+         * 设置 watch 监听后端端口变化，自动更新代理目标
+         */
+        unwatch = registry.watch(serviceName, (updatedInfo) => {
+          if (updatedInfo) {
+            /**
+             * 更新后的主机地址
+             */
+            const updatedHost = updatedInfo.host === '0.0.0.0' ? 'localhost' : updatedInfo.host;
+
+            /**
+             * 更新后的目标地址
+             */
+            const updatedTarget = `http://${updatedHost}:${updatedInfo.port}`;
+            server.config.logger.info(
+              `[端口发现] 后端服务端口变化: ${serviceName} -> ${updatedTarget}`,
+            );
+            updateProxyTarget(server, serviceName, updatedTarget);
+          } else {
+            server.config.logger.warn(`[端口发现] 后端服务已下线: ${serviceName}`);
+          }
+        });
+      }
+
+      /**
+       * 进程退出时自动注销前端端口
+       */
+      if (registerAs) {
+        /**
+         * 闭包外快照，消除闭包内非空断言
+         */
+        const httpServer = server.httpServer;
+
+        /**
+         * 注册表快照，闭包外非空收敛
+         */
+        const activeRegistry = registry;
+
+        /**
+         * 原始 close 方法绑定
+         */
+        const originalClose = httpServer?.close.bind(httpServer);
+        if (originalClose && httpServer && activeRegistry) {
+          httpServer.close = function (cb?: (err?: Error) => void) {
+            activeRegistry.deregister(registerAs).catch(() => {});
+
+            /**
+             * vite `httpServer.close` 重载返回面在闭包包装处不可统一，
+             * 以宽类型透传原始返回值，运行时行为不变，承接自 dev-tools 既有形态
+             */
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @longzai-intelligence-oxlint/typescript-eslint-plugin/consistent-type-assertions
+            return originalClose(cb) as any;
+          };
+        }
+      }
+    },
+
+    closeBundle: async () => {
+      /**
+       * 取消 watch 监听
+       */
+      if (unwatch) {
+        unwatch();
+        unwatch = null;
+      }
+
+      /**
+       * 注销前端端口
+       */
+      if (registry && registerAs) {
+        await registry.deregister(registerAs).catch(() => {});
+      }
+    },
+  };
+};
+
+export { portDiscovery };