@longzai-intelligence-cli/serve-kit 0.0.0-stage → 0.0.16

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @longzai-intelligence-cli/serve-kit
 
-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.
+意图：作为 CLI 族的 `serve` 命令共享设施，以宿主声明契约、本机宿主运行时、命令装配三件套，让各工具仓以一份描述符接入本机宿主的拉起能力
+
+定位：位于 cli 工作区 packages 目录，依赖 core 的命令框架与 local-server startup 包的监听核心，发布形态为 npm 库包
+
+职能：解析监听参数并显式关闭端口共存绑定实现冲突快速失败，经端口注册表尽力登记实例档，输出就绪行并可选拉起系统浏览器，接管退出信号完成注销与优雅停机
+
+边界：不约束宿主内部装配面，应用工厂由各仓 desktop-host 槽位自持，本包只消费 `ListenCapableApp` 结构形态

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+import { ListenCapableApp, StartServerCapabilities } from "@longzai-intelligence-local-server/startup";
+import { createPortRegistry } from "@longzai-intelligence-port/registry";
+import { Command } from "@longzai-intelligence-cli/core";
+/**
+ * 宿主声明契约
+ */
+type ServeHostDescriptor = {
+  /**
+   * 域 slug，如 `issues`
+   */
+  readonly domain: string;
+  /**
+   * 缺省监听端口，声明值即各仓 desktop-host 槽位的历史缺省口
+   */
+  readonly defaultPort: number;
+  /**
+   * 端口注册表服务名，命名形态为域 slug 接 `-desktop-host` 后缀
+   */
+  readonly serviceName: string;
+  /**
+   * 生产者完整仓库名，写入端口注册表实例档作群级 join key
+   */
+  readonly producer: string;
+  /**
+   * 应用工厂，纯装配无副作用
+   *
+   * @remarks
+   *   工厂不监听端口不扫盘，返回对象满足 startup 包的 `ListenCapableApp` 结构形态
+   */
+  readonly createApp: () => ListenCapableApp | Promise<ListenCapableApp>;
+  /**
+   * 实例档能力端点声明，写入端口注册表实例档
+   */
+  readonly capabilities?: StartServerCapabilities;
+};
+/**
+ * ui 命令运行选项
+ */
+type ServeHostRunOptions = {
+  /**
+   * 监听端口覆盖值
+   *
+   * @remarks
+   *   缺省解析顺序为选项覆盖值、环境变量 `PORT`、宿主声明缺省口
+   */
+  readonly port?: number;
+  /**
+   * 绑定地址覆盖值
+   *
+   * @remarks
+   *   缺省解析顺序为选项覆盖值、环境变量 `HOST`、回环地址 `127.0.0.1`
+   */
+  readonly host?: string;
+  /**
+   * 就绪后打开系统浏览器
+   *
+   * @default false
+   */
+  readonly open?: boolean;
+  /**
+   * 端口注册表自登记开关
+   *
+   * @remarks
+   *   登记失败降级为警告不阻断宿主服务
+   * @default true
+   */
+  readonly registry?: boolean;
+  /**
+   * 端口注册表目录覆盖值
+   *
+   * @remarks
+   *   缺省走注册表自身的工作区锚定，测试环境可指向隔离目录
+   */
+  readonly registryDir?: string;
+  /**
+   * 接管退出信号开关，测试环境可关闭
+   *
+   * @default true
+   */
+  readonly handleSignals?: boolean;
+};
+/**
+ * 就绪行格式化工具
+ *
+ * @remarks
+ *   `ready url=` 前缀为本机宿主族的稳定输出形态，供人工与脚本双面识别
+ */
+/**
+ * 格式化就绪行
+ *
+ * @param host - 绑定地址
+ * @param port - 实际监听端口
+ * @param domain - 域 slug
+ * @returns 就绪行文本
+ */
+declare function formatReadyLine(host: string, port: number, domain: string): string;
+/**
+ * 系统浏览器拉起工具
+ *
+ * @remarks
+ *   打开器派发为尽力而为，失败不阻断宿主服务
+ */
+/**
+ * 按平台选取系统打开器命令
+ *
+ * @param platform - 目标平台标识，缺省取当前进程平台
+ * @returns 打开器命令名，平台不支持时为 undefined
+ */
+declare function selectSystemOpener(platform?: NodeJS.Platform): string | undefined;
+/**
+ * 就绪后在系统浏览器打开服务地址
+ *
+ * @param url - 服务地址
+ * @param opener - 打开器命令名，由调用侧经 `selectSystemOpener` 解析
+ * @returns 是否已成功派发打开器进程
+ */
+declare function openInSystemBrowser(url: string, opener: string | undefined): boolean;
+/**
+ * 监听参数解析工具
+ *
+ * @remarks
+ *   端口合法域为 0 到 65535 的整数，0 表示由系统随机分配
+ */
+/**
+ * 解析监听端口
+ *
+ * @param override - 命令选项覆盖值
+ * @param envPort - 环境变量 `PORT` 原始字符串
+ * @param defaultPort - 宿主声明缺省口
+ * @returns 生效监听端口
+ * @throws {@link Error} 当生效值不是合法端口
+ */
+declare function resolveServeHostPort(override: number | undefined, envPort: string | undefined, defaultPort: number): number;
+/**
+ * 解析绑定地址
+ *
+ * @param override - 命令选项覆盖值
+ * @param envHost - 环境变量 `HOST` 原始字符串
+ * @returns 生效绑定地址
+ */
+declare function resolveServeHostBindHost(override: string | undefined, envHost: string | undefined): string;
+/**
+ * 端口注册表实例类型，由注册表工厂返回类型推导
+ */
+type PortRegistryInstance = ReturnType<typeof createPortRegistry>;
+/**
+ * 停机处理器构造选项
+ */
+type ServeHostShutdownOptions = {
+  /**
+   * 端口注册表实例，登记降级时为 null
+   */
+  readonly registry: PortRegistryInstance | null;
+  /**
+   * 端口注册表服务名
+   */
+  readonly serviceName: string;
+  /**
+   * 宿主应用实例
+   */
+  readonly app: ListenCapableApp;
+  /**
+   * 进程出口钩子，测试环境可注入替身
+   *
+   * @default process.exit
+   */
+  readonly exit?: (code: number) => void;
+};
+/**
+ * 优雅停机处理器形态
+ */
+type ServeHostShutdown = () => void;
+/**
+ * 构造优雅停机处理器
+ *
+ * @remarks
+ *   停机次序为先注销登记再停监听再退出，注销与停听任一异常不阻断退出
+ * @param options - 停机处理器构造选项
+ * @returns 停机处理器
+ */
+declare function buildServeHostShutdown(options: ServeHostShutdownOptions): ServeHostShutdown;
+/**
+ * 拉起本机宿主并监听至退出信号
+ *
+ * @remarks
+ *   本函数在监听就绪后返回实际端口，进程存活由监听句柄维持，退出由信号处理器完成
+ * @param descriptor - 宿主声明契约
+ * @param options - 运行选项
+ * @returns 实际监听端口
+ * @throws {@link Error} 当端口非法或监听失败即端口被占用等
+ */
+declare function runServeHost(descriptor: ServeHostDescriptor, options?: ServeHostRunOptions): Promise<number>;
+/**
+ * 注册本仓 `serve` 命令
+ *
+ * @remarks
+ *   命令语义为前台拉起本机宿主，宿主就绪后命令进程驻留至退出信号
+ *   仓级运行缺省与命令选项同键合并，命令选项优先
+ * @param program - CLI 程序实例
+ * @param descriptor - 宿主声明契约
+ * @param defaultRunOptions - 仓级运行缺省，测试环境可经此注入注册表隔离目录
+ */
+declare function registerServeCommand(program: Command, descriptor: ServeHostDescriptor, defaultRunOptions?: ServeHostRunOptions): void;
+export { type ServeHostDescriptor, type ServeHostRunOptions, type ServeHostShutdownOptions, buildServeHostShutdown, formatReadyLine, openInSystemBrowser, registerServeCommand, resolveServeHostBindHost, resolveServeHostPort, runServeHost, selectSystemOpener };

package/dist/index.js

@@ -0,0 +1 @@
+import"./rolldown-runtime-BqT_7tdF.js";import{spawn as e}from"node:child_process";import{ensureError as t}from"@longzai-intelligence-error/utils";import{startServerFromEnv as n}from"@longzai-intelligence-local-server/startup";import{createPortRegistry as r}from"@longzai-intelligence-port/registry";import{defineCommand as i}from"@longzai-intelligence-cli/core";import*as a from"zod";function o(e,t,n){return`ready url=http://${e}:${t} domain=${n}`}function s(e=process.platform){if(e===`darwin`)return`open`;if(e===`linux`)return`xdg-open`}function c(t,n){if(n===void 0)return!1;try{return e(n,[t],{stdio:`ignore`}).unref(),!0}catch{return!1}}function l(e,t,n){let r=t!==void 0&&t.trim()!==``?Number(t):void 0,i=e??r??n;if(!Number.isInteger(i)||i<0||i>65535)throw Error(`监听端口非法：${String(i)}，合法域为 0 到 65535 的整数，0 表示由系统随机分配`);return i}function u(e,t){let n=t!==void 0&&t.trim()!==``?t:void 0;return e??n??`127.0.0.1`}function d(e){return()=>{(async()=>{try{e.registry!==null&&await e.registry.deregister(e.serviceName),await e.app.stop?.()}finally{(e.exit??process.exit)(0)}})()}}async function f(e,i={}){let a=l(i.port,process.env.PORT,e.defaultPort),f=u(i.host,process.env.HOST),p=await e.createApp(),m=await n({createApp:async()=>p,port:a,host:f,handleSignals:!1}),h=null;if(i.registry!==!1)try{h=r(i.registryDir===void 0?void 0:{registryDir:i.registryDir}),await h.register(e.serviceName,{port:m,host:f,pid:process.pid,startedAt:Date.now(),producer:e.producer,capabilities:e.capabilities})}catch(e){h=null,process.stderr.write(`端口注册表登记失败，已降级继续服务：${t(e).message}\n`)}if(i.handleSignals!==!1){let t=d({registry:h,serviceName:e.serviceName,app:p});process.once(`SIGINT`,t),process.once(`SIGTERM`,t)}return process.stdout.write(`${o(f,m,e.domain)}\n`),i.open===!0&&(c(`http://${f}:${m}`,s())||process.stderr.write(`当前平台不支持自动打开浏览器，请手动访问 http://${f}:${m}\n`)),m}const p=a.object({port:a.coerce.number().int().min(0).max(65535).optional(),host:a.string().min(1).optional(),open:a.boolean().optional()});function m(e,n,r={}){i(e,{name:`serve`,description:`拉起 ${n.domain} 本机宿主`,options:[{flags:`--port <number>`,description:`监听端口，缺省读环境变量 PORT 再回落宿主声明缺省口`},{flags:`--host <address>`,description:`绑定地址，缺省读环境变量 HOST 再回落回环地址`},{flags:`--open`,description:`宿主就绪后打开系统浏览器`}],schema:p,action:async e=>{try{await f(n,{...r,port:e.port,host:e.host,open:e.open})}catch(e){process.stderr.write(`宿主启动失败：${t(e).message}\n`),process.exitCode=1}}})}export{d as buildServeHostShutdown,o as formatReadyLine,c as openInSystemBrowser,m as registerServeCommand,u as resolveServeHostBindHost,l as resolveServeHostPort,f as runServeHost,s as selectSystemOpener};

package/dist/rolldown-runtime-BqT_7tdF.js

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

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@longzai-intelligence-cli/serve-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.16",
+  "description": "Longzai Intelligence CLI 本机宿主拉起共享设施包",
+  "keywords": [
+    "cli",
+    "desktop-host",
+    "longzai-intelligence",
+    "ui"
+  ],
+  "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": "lzi-bun test",
+    "test:watch": "lzi-bun test --watch",
+    "test:coverage": "lzi-bun test --coverage",
+    "lint": "lzi-lint lint",
+    "lint:fix": "lzi-lint fix",
+    "typecheck": "lzi-typecheck"
+  },
+  "dependencies": {
+    "@longzai-intelligence-cli/core": "0.0.16",
+    "@longzai-intelligence-error/utils": "^0.2.0",
+    "@longzai-intelligence-local-server/startup": "^0.0.2",
+    "@longzai-intelligence-port/registry": "^0.0.7",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "commander": "^15.0.0"
+  }
+}