@longzai-intelligence-local-server/supervisor 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @longzai-intelligence-local-server/supervisor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+桌面本地后端服务进程监督器包。在宿主进程内监督本地后端子进程的完整生命周期：绑零口保留端口、启动、健康轮询、崩溃自动重启、优雅停机与端口注册表登记注销。零 Electron 依赖，Electron 主进程与 CLI 与 TUI 与协调宿主等 Bun 运行时均可直接消费。
+
+## 导出面
+
+- `createLocalServerService` 工厂与 `LocalServerService` 类
+- `resolveLocalServerConfig` 配置解析器与 `LocalServerConfig`、`ResolvedLocalServerConfig`、`LocalServerCapabilities` 配置类型
+- `ServerOperationResult`、`ServerRuntimeStatus`、`StatusChangeCallback` 运行时类型
+
+## 接入配方
+
+服务名按 `<scope>-local-server` 命名，入口路径必须显式解析并经存在性校验快速失败，禁止依赖运行时相对路径：
+
+```ts
+import { createLocalServerService } from '@longzai-intelligence-local-server/supervisor';
+
+const manager = createLocalServerService({
+  serviceName: 'voice-local-server',
+  entryPath: resolve(appRoot, '../server/src/desktop-entry.ts'),
+});
+
+await manager.start();
+const baseUrl = manager.getBaseUrl();
+```
+
+端口缺省零值即绑零口取系统分配口，就绪后自动登记端口注册表，消费方经 `getBaseUrl` 取真实基址。Electron 主进程需要把四通道挂到 `ipcMain` 时，另接 `@longzai-intelligence-local-server/handlers` 包。

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+import "./rolldown-runtime-BqT_7tdF.js";
+/**
+ * 本地服务监督器配置定义
+ */
+/**
+ * 实例档能力端点声明
+ *
+ * 健康端点缺省沿用配置的 `healthPath`，MCP 端点为可选显式声明
+ */
+type LocalServerCapabilities = {
+  /**
+   * 健康探针端点路径
+   *
+   * @default 沿用 `healthPath` 即 `/api/health`
+   */
+  health?: string;
+  /**
+   * MCP 工具面端点路径
+   *
+   * @default '/mcp'
+   */
+  mcp?: string;
+};
+/**
+ * 本地服务监督器配置
+ *
+ * 必填项为服务名与服务入口，入口经存在性校验快速失败，
+ * 端口缺省零值即绑零口保留惯用法取系统分配口
+ */
+type LocalServerConfig = {
+  /**
+   * 端口注册表服务名，如 `voice-local-server`
+   */
+  serviceName: string;
+  /**
+   * 生产者完整仓库名，写入实例档作群级 join key
+   */
+  producer?: string;
+  /**
+   * 实例档能力端点声明，健康端点缺省沿用 `healthPath`
+   */
+  capabilities?: LocalServerCapabilities;
+  /**
+   * 服务入口路径，相对 `cwd` 或绝对路径均可
+   */
+  entryPath: string;
+  /**
+   * 子进程工作目录
+   *
+   * @default 当前进程工作目录
+   */
+  cwd?: string;
+  /**
+   * 绑定主机
+   *
+   * @default localhost
+   */
+  host?: string;
+  /**
+   * 端口号，零值表示由系统分配
+   *
+   * @default 0
+   */
+  port?: number;
+  /**
+   * 健康检查路径
+   *
+   * @default /api/health
+   */
+  healthPath?: string;
+  /**
+   * 健康检查总超时毫秒数
+   *
+   * @default 30000
+   */
+  healthTimeout?: number;
+  /**
+   * 健康检查轮询间隔毫秒数
+   *
+   * @default 500
+   */
+  healthInterval?: number;
+  /**
+   * 崩溃后最大自动重启次数
+   *
+   * @default 3
+   */
+  maxRestartAttempts?: number;
+  /**
+   * 优雅关闭超时毫秒数，超时后升级为强制杀死
+   *
+   * @default 5000
+   */
+  shutdownTimeout?: number;
+  /**
+   * 子进程启动命令
+   *
+   * @default bun
+   */
+  spawnCommand?: string;
+  /**
+   * 子进程命令参数前缀，置于入口路径之前
+   *
+   * @default ['run']
+   */
+  spawnArgsPrefix?: string[];
+  /**
+   * 端口注册表目录，缺省走注册表自身的工作区锚定
+   */
+  registryDir?: string;
+  /**
+   * 追加注入子进程的环境变量
+   */
+  env?: Record<string, string>;
+};
+/**
+ * 解析后的完整配置形态
+ */
+type ResolvedLocalServerConfig = Required<Pick<LocalServerConfig, 'serviceName' | 'entryPath' | 'host' | 'port' | 'healthPath' | 'healthTimeout' | 'healthInterval' | 'maxRestartAttempts' | 'shutdownTimeout' | 'spawnCommand' | 'spawnArgsPrefix'>> & Partial<Pick<LocalServerConfig, 'cwd' | 'registryDir' | 'env' | 'producer' | 'capabilities'>>;
+/**
+ * 解析配置并落入默认值
+ *
+ * @param config - 使用方传入的配置
+ * @returns 填充默认值后的完整配置
+ */
+declare function resolveLocalServerConfig(config: LocalServerConfig): ResolvedLocalServerConfig;
+/**
+ * 启停操作结果
+ */
+type ServerOperationResult = {
+  /**
+   * 操作是否成功
+   */
+  success: boolean;
+  /**
+   * 失败时的错误描述
+   */
+  error?: string;
+};
+/**
+ * 状态变更回调
+ */
+type StatusChangeCallback = (status: ServerRuntimeStatus) => void;
+/**
+ * 本地服务监督器类
+ */
+declare class LocalServerService {
+  /**
+   * 模块日志器
+   */
+  private static readonly logger;
+  /**
+   * 解析后的完整配置
+   */
+  private readonly config;
+  /**
+   * 子进程实例
+   */
+  private child;
+  /**
+   * 当前重启次数
+   */
+  private restartAttempts;
+  /**
+   * 当前服务器状态
+   */
+  private status;
+  /**
+   * 生效端口号，配置为零值时为系统分配的保留端口
+   */
+  private activePort;
+  /**
+   * 端口注册表实例，懒初始化
+   */
+  private portRegistry;
+  /**
+   * 状态变更回调
+   */
+  private onStatusChange?;
+  /**
+   * 停止意图标记
+   *
+   * @remarks
+   *   `stop` 发出后置真，子进程随之以信号退出时不再按崩溃处理，`start` 重新拉起时复位
+   */
+  private stopRequested;
+  /**
+   * 创建本地服务监督器实例
+   *
+   * @param config - 监督器配置
+   */
+  constructor(config: LocalServerConfig);
+  /**
+   * 设置状态变更回调
+   *
+   * @param callback - 状态变更回调函数
+   */
+  setStatusCallback(callback: StatusChangeCallback): void;
+  /**
+   * 获取当前服务器状态
+   *
+   * @returns 当前服务器状态
+   */
+  getStatus(): ServerRuntimeStatus;
+  /**
+   * 获取本地服务真实基址
+   *
+   * @returns 服务运行中的基址串，未就绪时为 null
+   */
+  getBaseUrl(): string | null;
+  /**
+   * 启动本地服务
+   *
+   * 入口存在性校验失败或健康检查超时均返回失败结果
+   *
+   * @returns 启动结果
+   */
+  start(): Promise<ServerOperationResult>;
+  /**
+   * 停止本地服务
+   *
+   * 先注销端口注册表，再优雅关闭子进程，超时升级为强制杀死
+   *
+   * @returns 停止结果
+   */
+  stop(): Promise<ServerOperationResult>;
+  /**
+   * 等待健康检查通过
+   *
+   * @param port - 生效端口号
+   * @returns 是否在超时前转为健康
+   */
+  private waitForHealth;
+  /**
+   * 处理服务器崩溃并尝试自动重启
+   */
+  private handleCrash;
+  /**
+   * 绑零口保留一个系统分配端口
+   *
+   * @returns 系统分配的保留端口号
+   * @throws {@link Error} 当保留监听失败时抛出
+   */
+  private reserveEphemeralPort;
+  /**
+   * 取端口注册表实例
+   *
+   * @returns 端口注册表实例
+   */
+  private registry;
+  /**
+   * 将本地服务端口登记进端口注册表
+   *
+   * @param port - 生效端口号
+   */
+  private registerServicePort;
+  /**
+   * 将本地服务端口从端口注册表注销
+   */
+  private deregisterServicePort;
+  /**
+   * 更新状态并通知回调
+   *
+   * @param status - 新状态
+   */
+  private updateStatus;
+}
+/**
+ * 服务器运行时状态
+ */
+type ServerRuntimeStatus = 'running' | 'stopped' | 'starting' | 'error';
+/**
+ * 创建本地服务监督器实例
+ *
+ * @param config - 监督器配置
+ * @returns 监督器实例
+ */
+declare function createLocalServerService(config: LocalServerConfig): LocalServerService;
+export { type LocalServerCapabilities, type LocalServerConfig, LocalServerService, type ResolvedLocalServerConfig, type ServerOperationResult, type ServerRuntimeStatus, type StatusChangeCallback, createLocalServerService, resolveLocalServerConfig };

package/dist/index.js

@@ -0,0 +1 @@
+import"./rolldown-runtime-BqT_7tdF.js";import{createNodeLogger as e}from"@longzai-intelligence-logger/node";import{createPortRegistry as t}from"@longzai-intelligence-port/registry";import{spawn as n}from"node:child_process";import{existsSync as r}from"node:fs";import*as i from"node:net";import{resolve as a}from"node:path";function o(e){return{serviceName:e.serviceName,producer:e.producer,capabilities:e.capabilities,entryPath:e.entryPath,cwd:e.cwd,host:e.host??`localhost`,port:e.port??0,healthPath:e.healthPath??`/api/health`,healthTimeout:e.healthTimeout??3e4,healthInterval:e.healthInterval??500,maxRestartAttempts:e.maxRestartAttempts??3,shutdownTimeout:e.shutdownTimeout??5e3,spawnCommand:e.spawnCommand??`bun`,spawnArgsPrefix:e.spawnArgsPrefix??[`run`],registryDir:e.registryDir,env:e.env}}var s=class s{static logger=e(`@longzai-intelligence-local-server/supervisor`);config;child=null;restartAttempts=0;status=`stopped`;activePort=null;portRegistry=null;onStatusChange;stopRequested=!1;constructor(e){this.config=o(e)}setStatusCallback(e){this.onStatusChange=e}getStatus(){return this.status}getBaseUrl(){return this.status!==`running`||this.activePort===null?null:`http://${this.config.host}:${this.activePort}`}async start(){if(this.child)return{success:!0};this.stopRequested=!1,this.updateStatus(`starting`);try{let e=a(this.config.cwd??process.cwd(),this.config.entryPath);if(!r(e))return this.updateStatus(`error`),{success:!1,error:`服务入口不存在: ${e}`};let t=this.config.port>0?this.config.port:await this.reserveEphemeralPort();return this.activePort=t,this.child=n(this.config.spawnCommand,[...this.config.spawnArgsPrefix,e],{cwd:this.config.cwd??process.cwd(),env:{...process.env,...this.config.env,HOST:this.config.host,PORT:String(t)},stdio:[`ignore`,`pipe`,`pipe`]}),this.child.on(`exit`,e=>{this.child=null,e!==0&&!this.stopRequested&&this.status!==`stopped`&&this.handleCrash()}),await this.waitForHealth(t)?(this.restartAttempts=0,await this.registerServicePort(t),this.updateStatus(`running`),{success:!0}):(await this.stop(),{success:!1,error:`Server health check failed`})}catch(e){return this.updateStatus(`error`),{success:!1,error:String(e)}}}async stop(){if(this.stopRequested=!0,!this.child)return this.updateStatus(`stopped`),await this.deregisterServicePort(),{success:!0};try{await this.deregisterServicePort(),this.child.kill(`SIGTERM`);let e=setTimeout(()=>{this.child&&this.child.kill(`SIGKILL`)},this.config.shutdownTimeout);return await new Promise(e=>{this.child?this.child.once(`exit`,()=>e()):e()}),clearTimeout(e),this.child=null,this.activePort=null,this.updateStatus(`stopped`),{success:!0}}catch(e){return this.child=null,this.activePort=null,this.updateStatus(`error`),{success:!1,error:String(e)}}}async waitForHealth(e){let t=Date.now(),n=`http://${this.config.host}:${e}${this.config.healthPath}`;for(;Date.now()-t<this.config.healthTimeout;){try{if((await fetch(n)).ok)return!0}catch{}await c(this.config.healthInterval)}return!1}async handleCrash(){this.restartAttempts>=this.config.maxRestartAttempts?(this.updateStatus(`error`),s.logger.error(`[LocalServer] Max restart attempts reached`)):(this.restartAttempts++,this.updateStatus(`starting`),s.logger.info(`[LocalServer] Restarting attempt ${this.restartAttempts}`),(await this.start()).success||this.updateStatus(`error`))}reserveEphemeralPort(){return new Promise((e,t)=>{let n=i.createServer();n.once(`error`,e=>{t(e)}),n.listen(0,this.config.host,()=>{let t=n.address(),r=typeof t==`object`&&t?t.port:0;n.close(()=>{e(r)})})})}registry(){return this.portRegistry??=t(this.config.registryDir?{registryDir:this.config.registryDir}:void 0),this.portRegistry}async registerServicePort(e){try{await this.registry().register(this.config.serviceName,{port:e,host:this.config.host,pid:this.child?.pid??process.pid,startedAt:Date.now(),producer:this.config.producer,capabilities:{health:this.config.capabilities?.health??this.config.healthPath,mcp:this.config.capabilities?.mcp}})}catch(e){s.logger.error(`[LocalServer] 端口注册失败`,e)}}async deregisterServicePort(){try{await this.registry().deregister(this.config.serviceName)}catch(e){s.logger.error(`[LocalServer] 端口注销失败`,e)}}updateStatus(e){this.status=e,this.onStatusChange?.(e)}};function c(e){return new Promise(t=>{setTimeout(t,e)})}function l(e){return new s(e)}export{s as LocalServerService,l as createLocalServerService,o as resolveLocalServerConfig};

package/dist/rolldown-runtime-BqT_7tdF.js

@@ -0,0 +1 @@
+import"node:module";export{};

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@longzai-intelligence-local-server/supervisor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Longzai Intelligence 桌面本地后端服务进程监督器包",
+  "keywords": [
+    "desktop",
+    "local-server",
+    "longzai-intelligence",
+    "port-registry",
+    "process",
+    "supervisor"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "dev": "lzi-builder --watch",
+    "clean": "lzi-dev-tools clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "lzi-lint lint",
+    "lint:fix": "lzi-lint fix",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json"
+  },
+  "dependencies": {
+    "@longzai-intelligence-logger/node": "^0.1.8",
+    "@longzai-intelligence-port/registry": "^0.0.5"
+  },
+  "devDependencies": {
+    "@longzai-intelligence-testing/utils": "^0.0.3",
+    "@longzai-intelligence-vitest/config": "^0.0.12",
+    "vitest": "^4.1.4"
+  },
+  "packageManager": "bun@1.4.3"
+}