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

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @longzai-intelligence-local-server/startup
 
-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.
+桌面本地服务服务端启动助手包。为 `createApp` 工厂形态的服务入口提供标准启动方式：读 `PORT` 与 `HOST` 环境变量，零口随机监听后回读真实端口，可选自登记端口注册表，接管退出信号优雅退出。运行在被监督的后端子进程内，零 Electron 依赖。
+
+## 导出面
+
+- `startServerFromEnv`
+- `ListenCapableApp`、`ListenCapableServer`、`ListenOptions`、`StartServerFromEnvOptions`、`StartServerCapabilities` 类型
+
+## 接入配方
+
+桌面入口文件一行接入，Elysia 实例直接满足可监听形态，`createApp` 原样传入无须消费侧包装：
+
+```ts
+import { startServerFromEnv } from '@longzai-intelligence-local-server/startup';
+
+await startServerFromEnv({ createApp, serviceName: 'voice-local-server' });
+```

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import "./rolldown-runtime-BqT_7tdF.js";
+/**
+ * 监听选项形态
+ *
+ * 与 Elysia 的 listen 选项参数同构即端口与主机键，Elysia 实例无须包装即可作为可监听应用
+ */
+type ListenOptions = {
+  /**
+   * 监听端口，零值表示由系统随机分配
+   */
+  port: number;
+  /**
+   * 绑定主机
+   */
+  hostname?: string;
+};
+/**
+ * 监听后服务器实例的结构形态
+ *
+ * 同时覆盖直接携带 `port` 字段的 Elysia 形态与经 `address` 回读的 node http 形态
+ */
+type ListenCapableServer = {
+  /**
+   * 系统分配后的真实端口，零口监听时由此回读
+   */
+  port?: number;
+  /**
+   * 监听地址信息读取方法，node http 形态的回读通道
+   */
+  address?(): {
+    port: number;
+  } | string | null;
+};
+/**
+ * 可监听应用的结构形态
+ *
+ * listen 形参为 Elysia 同构的选项形态，Elysia 实例直接满足本形态无须消费侧包装
+ */
+type ListenCapableApp = {
+  /**
+   * 以选项形态开始监听
+   *
+   * @param options - 监听选项即端口与可选主机
+   */
+  listen: (options: ListenOptions) => unknown;
+  /**
+   * 监听后的服务器实例
+   */
+  server?: ListenCapableServer | null;
+  /**
+   * 优雅停止监听
+   */
+  stop?(): unknown;
+};
+/**
+ * 实例档能力端点声明
+ */
+type StartServerCapabilities = {
+  /**
+   * 健康探针端点路径
+   *
+   * @default '/api/health'
+   */
+  health?: string;
+  /**
+   * MCP 工具面端点路径
+   *
+   * @default '/mcp'
+   */
+  mcp?: string;
+};
+/**
+ * 启动助手选项
+ */
+type StartServerFromEnvOptions = {
+  /**
+   * 应用工厂，返回可监听的应用对象
+   */
+  createApp: () => ListenCapableApp | Promise<ListenCapableApp>;
+  /**
+   * 端口注册表服务名，提供时服务就绪后自登记
+   */
+  serviceName?: string;
+  /**
+   * 生产者完整仓库名，写入实例档作群级 join key
+   */
+  producer?: string;
+  /**
+   * 实例档能力端点声明
+   */
+  capabilities?: StartServerCapabilities;
+  /**
+   * 绑定主机，缺省读 `HOST` 环境变量再回落 localhost
+   */
+  host?: string;
+  /**
+   * 端口号，缺省读 `PORT` 环境变量再回落零值随机
+   */
+  port?: number;
+  /**
+   * 端口注册表目录，缺省走注册表自身的工作区锚定
+   */
+  registryDir?: string;
+  /**
+   * 是否接管退出信号，测试环境可关闭
+   *
+   * @default true
+   */
+  handleSignals?: boolean;
+};
+/**
+ * 经环境变量启动可监听应用
+ *
+ * @param options - 启动助手选项
+ * @returns 实际监听的端口号
+ */
+declare function startServerFromEnv(options: StartServerFromEnvOptions): Promise<number>;
+export { ListenCapableApp, ListenCapableServer, ListenOptions, StartServerCapabilities, StartServerFromEnvOptions, startServerFromEnv };

package/dist/index.js

@@ -0,0 +1 @@
+import"./rolldown-runtime-BqT_7tdF.js";import{createPortRegistry as e}from"@longzai-intelligence-port/registry";async function t(t){let n=t.port??Number(process.env.PORT??0),r=t.host??process.env.HOST??`localhost`,i=await t.createApp();await i.listen({port:n,hostname:r});let a=n;if(typeof i.server?.port==`number`)a=i.server.port;else{let e=i.server?.address?.();typeof e==`object`&&e&&(a=e.port)}let o=null;if(t.serviceName&&(o=e(t.registryDir?{registryDir:t.registryDir}:void 0),await o.register(t.serviceName,{port:a,host:r,pid:process.pid,startedAt:Date.now(),producer:t.producer,capabilities:t.capabilities})),t.handleSignals!==!1){let e=()=>{(async()=>{try{o&&t.serviceName&&await o.deregister(t.serviceName),await i.stop?.()}finally{process.exit(0)}})()};process.once(`SIGTERM`,e),process.once(`SIGINT`,e)}return a}export{t as startServerFromEnv};

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/startup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Longzai Intelligence 桌面本地服务服务端启动助手包",
+  "keywords": [
+    "desktop",
+    "elysia",
+    "local-server",
+    "longzai-intelligence",
+    "port-registry",
+    "startup"
+  ],
+  "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-port/registry": "^0.0.5"
+  },
+  "devDependencies": {
+    "@longzai-intelligence-testing/utils": "^0.0.3",
+    "@longzai-intelligence-vitest/config": "^0.0.12",
+    "elysia": "^1.4.29",
+    "vitest": "^4.1.4"
+  },
+  "packageManager": "bun@1.4.3"
+}