hunter-mate 0.1.2 → 0.1.3

package/dist/index.js

@@ -1,79 +1,54 @@
 #!/usr/bin/env node
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-require("dotenv/config");
-const commander_1 = require("commander");
-const chalk_1 = __importDefault(require("chalk"));
-const sentry_1 = require("./sentry");
-const login_1 = require("./commands/login");
-const logout_1 = require("./commands/logout");
-const status_1 = require("./commands/status");
-const config_1 = require("./commands/config");
-const search_1 = require("./commands/search");
-const job_1 = require("./commands/job");
-const update_1 = require("./commands/update");
-const extension_1 = require("./commands/extension");
-const report_1 = require("./commands/report");
-const record_1 = require("./commands/record");
-const cache_1 = require("./commands/cache");
+import 'dotenv/config';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { initSentry } from './sentry.js';
+import { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { statusCommand } from './commands/status.js';
+import { configCommand } from './commands/config.js';
+import { searchCommand } from './commands/search.js';
+import { jobCommand } from './commands/job.js';
+import { updateCommand } from './commands/update.js';
+import { extensionCommand } from './commands/extension.js';
+import { reportCommand } from './commands/report.js';
+import { recordCommand } from './commands/record.js';
+import { cacheCommand } from './commands/cache.js';
 // 对应 ChromePilot 的新命令（环境管理 / 运维 / 扩展管理）
-const init_1 = require("./commands/init");
-const install_1 = require("./commands/install");
-const server_1 = require("./commands/server");
-const doctor_1 = require("./commands/doctor");
-const extras_1 = require("./commands/extras");
-const ops_1 = require("./commands/ops");
-const addons_1 = require("./commands/addons");
-const i18n_1 = require("./i18n");
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-const { version: CLI_VERSION } = require('../package.json');
-(0, sentry_1.initSentry)();
-const program = new commander_1.Command();
+import { initCommand } from './commands/init.js';
+import { installCommand } from './commands/install.js';
+import { startCommand, stopCommand } from './commands/server.js';
+import { doctorCommand } from './commands/doctor.js';
+import { reloadCommand, openExtCommand, purgeCommand } from './commands/extras.js';
+import { recordingsCommand, adapterCommand, memoryCommand, traceCommand, autofixCommand } from './commands/ops.js';
+import { pluginCommand, skillCommand, externalCommand } from './commands/addons.js';
+import { i18n } from './i18n/index.js';
+import { initCliLogger, flushCliLogger, getCliLogger } from './logger.js';
+import packageJson from '../package.json' with { type: 'json' };
+const CLI_VERSION = packageJson.version;
+initSentry();
+// patchConsole + patchStreams:把业务代码里的 console.error/warn 统一转发到 logger-kit,
+// 避免两套日志写法。AGENTS.md §11。
+initCliLogger({ patchConsole: true, patchStreams: true }).catch(() => {
+    // 日志初始化失败不影响主流程
+});
+const program = new Command();
 program
     .name('hunter-mate')
-    .description(i18n_1.i18n.t('cli.description') + '（已对齐 ChromePilot: init/install/start/stop/status/recordings/control/adapter/run/memory/trace/autofix/external/plugin/skill/open-ext/doctor/reload）')
+    .description(i18n.t('cli.description') + '（已对齐 ChromePilot: init/install/start/stop/status/recordings/control/adapter/run/memory/trace/autofix/external/plugin/skill/open-ext/doctor/reload）+ purge|reset|uninstall')
     .version(CLI_VERSION)
-    .option('--lang <lang>', i18n_1.i18n.t('cli.langOption'), 'zh-CN')
+    .option('--lang <lang>', i18n.t('cli.langOption'), 'zh-CN')
     .hook('preAction', async (thisCommand) => {
     const lang = thisCommand.opts().lang;
     if (lang)
-        i18n_1.i18n.setLocale(lang);
+        i18n.setLocale(lang);
+    // 日志:command start
+    try {
+        getCliLogger().info('command:start', { command: thisCommand.name(), args: thisCommand.args });
+    }
+    catch {
+        // logger 未就绪时忽略
+    }
     // ADR-005 运行时一致性自动检测 + CLI 自更新(每次使用触发,版本判断):
     // 1) CLI 自更新: 节流 1h 对比 npm registry,落后自动 npm install -g(下一条命令生效);
     //    dev 软链模式(wrapper 指向 hc-hw worktree dist)自动跳过。
@@ -86,50 +61,60 @@ program
     if (name === 'update' || name === 'start' || name === 'stop')
         return;
     try {
-        const { maybeCliSelfUpdate } = await Promise.resolve().then(() => __importStar(require('./updater')));
+        const { maybeCliSelfUpdate } = await import('./updater.js');
         const upd = await maybeCliSelfUpdate();
         for (const line of upd.logs)
-            console.log(chalk_1.default.gray(`  [auto-update] ${line}`));
+            console.log(chalk.gray(`  [auto-update] ${line}`));
     }
     catch {
         /* CLI 自更新检测永不阻塞主命令 */
     }
     try {
-        const { ensureRuntimeConsistency } = await Promise.resolve().then(() => __importStar(require('./version')));
+        const { ensureRuntimeConsistency } = await import('./version.js');
         const report = await ensureRuntimeConsistency({});
         if (report.performed.length) {
             for (const line of report.performed)
-                console.log(chalk_1.default.gray(`  [auto-update] ${line}`));
+                console.log(chalk.gray(`  [auto-update] ${line}`));
         }
     }
     catch {
         /* 一致性检测永不阻塞主命令 */
     }
+})
+    .hook('postAction', async (thisCommand) => {
+    try {
+        getCliLogger().info('command:end', { command: thisCommand.name() });
+        await flushCliLogger();
+    }
+    catch {
+        // 日志发送失败不影响主流程
+    }
 });
-program.addCommand(init_1.initCommand);
-program.addCommand(install_1.installCommand);
-program.addCommand(server_1.startCommand);
-program.addCommand(server_1.stopCommand);
-program.addCommand(login_1.loginCommand);
-program.addCommand(logout_1.logoutCommand);
-program.addCommand(status_1.statusCommand);
-program.addCommand(config_1.configCommand);
-program.addCommand(search_1.searchCommand);
-program.addCommand(job_1.jobCommand);
-program.addCommand(update_1.updateCommand);
-program.addCommand(extension_1.extensionCommand);
-program.addCommand(ops_1.recordingsCommand);
-program.addCommand(ops_1.adapterCommand);
-program.addCommand(ops_1.memoryCommand);
-program.addCommand(ops_1.traceCommand);
-program.addCommand(ops_1.autofixCommand);
-program.addCommand(addons_1.externalCommand);
-program.addCommand(addons_1.pluginCommand);
-program.addCommand(addons_1.skillCommand);
-program.addCommand(extras_1.openExtCommand);
-program.addCommand(doctor_1.doctorCommand);
-program.addCommand(extras_1.reloadCommand);
-program.addCommand(report_1.reportCommand);
-program.addCommand(record_1.recordCommand);
-program.addCommand(cache_1.cacheCommand);
+program.addCommand(initCommand);
+program.addCommand(installCommand);
+program.addCommand(startCommand);
+program.addCommand(stopCommand);
+program.addCommand(loginCommand);
+program.addCommand(logoutCommand);
+program.addCommand(statusCommand);
+program.addCommand(configCommand);
+program.addCommand(searchCommand);
+program.addCommand(jobCommand);
+program.addCommand(updateCommand);
+program.addCommand(extensionCommand);
+program.addCommand(recordingsCommand);
+program.addCommand(adapterCommand);
+program.addCommand(memoryCommand);
+program.addCommand(traceCommand);
+program.addCommand(autofixCommand);
+program.addCommand(externalCommand);
+program.addCommand(pluginCommand);
+program.addCommand(skillCommand);
+program.addCommand(openExtCommand);
+program.addCommand(doctorCommand);
+program.addCommand(reloadCommand);
+program.addCommand(purgeCommand);
+program.addCommand(reportCommand);
+program.addCommand(recordCommand);
+program.addCommand(cacheCommand);
 program.parse();

package/dist/index.ps1

@@ -0,0 +1,3 @@
+# Generated by scripts/postbuild-shim.mjs; do not edit by hand.
+$basedir = Split-Path $MyInvocation.MyCommand.Definition -Parent
+& "$basedir\index.js" @args

package/dist/keychain.js

@@ -1,49 +1,14 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.saveToken = saveToken;
-exports.getToken = getToken;
-exports.deleteToken = deleteToken;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
+import * as fs from 'fs';
+import * as path from 'path';
 const SERVICE = 'hunter-mate';
 const ACCOUNT = 'user';
 const HOME = process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
 const TOKEN_FILE = path.join(HOME, '.hunter-mate', 'token.json');
 function fallbackSave(token) {
     fs.mkdirSync(path.dirname(TOKEN_FILE), { recursive: true });
+    // POSIX 上 mode 0o600 强制 owner-only;Windows NTFS 上 mode bit 被忽略,
+    // 由用户目录 ACL 兜底(%USERPROFILE%\.hunter-mate 默认只有当前用户可访问)。
+    // 真正安全的 Windows 路径是走 keytar(Windows Credential Manager)→ setPassword。
     fs.writeFileSync(TOKEN_FILE, JSON.stringify({ token }), { mode: 0o600 });
 }
 function fallbackGet() {
@@ -68,7 +33,7 @@ async function getKeytar() {
     if (process.platform === 'linux')
         return null;
     try {
-        const mod = await Promise.resolve().then(() => __importStar(require('keytar')));
+        const mod = await import('keytar');
         // ESM/CJS 混用：部分导出在 default 上
         return mod.setPassword ? mod : mod.default || null;
     }
@@ -76,7 +41,7 @@ async function getKeytar() {
         return null;
     }
 }
-async function saveToken(token) {
+export async function saveToken(token) {
     const keytar = await getKeytar();
     if (keytar) {
         try {
@@ -89,7 +54,7 @@ async function saveToken(token) {
     }
     fallbackSave(token);
 }
-async function getToken() {
+export async function getToken() {
     const keytar = await getKeytar();
     if (keytar) {
         try {
@@ -103,7 +68,7 @@ async function getToken() {
     }
     return fallbackGet();
 }
-async function deleteToken() {
+export async function deleteToken() {
     const keytar = await getKeytar();
     if (keytar) {
         try {

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+import { Logger } from "@chromepilot/logger-kit/client";
+export declare function getCliLogger(): Logger;
+export declare function initCliLogger(options?: {
+    patchConsole?: boolean;
+    patchStreams?: boolean;
+}): Promise<Logger>;
+export declare function flushCliLogger(): Promise<void>;

package/dist/logger.js

@@ -0,0 +1,80 @@
+import { Logger, createHttpTransport } from "@chromepilot/logger-kit/client";
+import { PersistentLogQueue } from "@chromepilot/logger-kit/queue-node";
+import { loadConfig } from "./config.js";
+import { getToken } from "./keychain.js";
+import path from "node:path";
+let logger = null;
+let queue = null;
+let drainTimer = null;
+const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    log: () => { },
+    patchConsole: () => { },
+    patchProcessStreams: () => { },
+    flush: async () => { },
+    drainPersistent: async () => null,
+};
+export function getCliLogger() {
+    if (!logger) {
+        // 未显式初始化时返回 noop(测试/单工具命令兼容);主入口 index.ts 会先 init
+        return noopLogger;
+    }
+    return logger;
+}
+function homeDir() {
+    return process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || ".";
+}
+export async function initCliLogger(options) {
+    const cfg = loadConfig();
+    const serverUrl = cfg.serverUrl.replace(/\/$/, "");
+    const token = await getToken();
+    // 持久化队列:server 不可达时落盘 ~/.hunter-mate/logs-pending.jsonl
+    queue = new PersistentLogQueue({
+        filePath: path.join(homeDir(), ".hunter-mate", "logs-pending.jsonl"),
+        maxBytes: 4 * 1024 * 1024,
+    });
+    await queue.load();
+    const transport = await createHttpTransport({
+        serverUrl,
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+    });
+    logger = new Logger({
+        context: "cli",
+        sessionId: () => process.env.HM_SESSION_ID || `cli-${process.pid}`,
+        send: transport,
+        flushIntervalMs: 1000,
+        maxBufferSize: 50,
+        persistentQueue: queue,
+    });
+    // 后台定时器:每 5s 尝试 drain(server 恢复后补发)
+    if (drainTimer)
+        clearInterval(drainTimer);
+    drainTimer = setInterval(() => {
+        if (queue && queue.size() > 0) {
+            queue.drain(transport).catch(() => { });
+        }
+    }, 5000);
+    drainTimer.unref?.();
+    if (options?.patchConsole !== false) {
+        logger.patchConsole();
+    }
+    if (options?.patchStreams !== false) {
+        logger.patchProcessStreams();
+    }
+    return logger;
+}
+export async function flushCliLogger() {
+    await logger?.flush();
+    if (queue && queue.size() > 0) {
+        const cfg = loadConfig();
+        const token = await getToken();
+        const transport = await createHttpTransport({
+            serverUrl: cfg.serverUrl.replace(/\/$/, ""),
+            headers: token ? { Authorization: `Bearer ${token}` } : {},
+        });
+        await queue.drain(transport).catch(() => { });
+    }
+}

package/dist/native-check.d.ts

@@ -0,0 +1,6 @@
+import { type NativeModuleStatus } from "@chromepilot/kit";
+export type { NativeModuleStatus };
+export declare const checkNativeModules: () => {
+    ok: boolean;
+    modules: NativeModuleStatus[];
+};

package/dist/native-check.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createNativeChecker } from "@chromepilot/kit";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function locateServerEntryDir() {
+    const candidates = [
+        path.resolve(__dirname, "../../server/dist"),
+        path.resolve(__dirname, "../../server/src"),
+    ];
+    for (const dir of candidates) {
+        if (fs.existsSync(path.join(dir, "main.js")) || fs.existsSync(path.join(dir, "main.ts"))) {
+            return dir;
+        }
+    }
+    return null;
+}
+const checker = createNativeChecker({
+    probeDir: () => locateServerEntryDir(),
+    skipDetail: "未找到 server 入口(packages/server/dist|src)，跳过原生模块检查",
+    rebuildHint: (moduleName, compiledLabel) => `二选一：① 切回 ${compiledLabel} 的 node 再运行；② 用当前 node 重编译：pnpm rebuild -r ${moduleName}（重编后重启 server）`,
+});
+export const checkNativeModules = checker.checkNativeModules;

package/dist/sentry.js

@@ -1,10 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Sentry = void 0;
-exports.initSentry = initSentry;
-const kit_1 = require("@chromepilot/kit");
-Object.defineProperty(exports, "Sentry", { enumerable: true, get: function () { return kit_1.Sentry; } });
+import { initSentryFromEnv, Sentry } from '@chromepilot/kit';
 /** Sentry 初始化:通用骨架来自 @chromepilot/kit(HM_ 前缀 env 读取) */
-function initSentry() {
-    return (0, kit_1.initSentryFromEnv)('HM');
+export function initSentry() {
+    return initSentryFromEnv('HM');
 }
+export { Sentry };

package/dist/updater.js

@@ -1,42 +1,3 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.markUpdateChecked = exports.shouldCheckUpdate = exports.updateCheckIntervalMs = exports.npmSelfUpdate = exports.npmLatestVersion = void 0;
-exports.computeDevLinked = computeDevLinked;
-exports.isDevLinked = isDevLinked;
-exports.maybeCliSelfUpdate = maybeCliSelfUpdate;
 /**
  * CLI 自动更新(使用态)— 通用实现来自 @chromepilot/kit createCliUpdater。
  *
@@ -50,9 +11,11 @@ exports.maybeCliSelfUpdate = maybeCliSelfUpdate;
  * - HUNTER_MATE_UPDATE_CHECK_INTERVAL_MS 覆盖节流间隔(默认 3600000)
  * - HUNTER_MATE_DEV=1                    强制视为 dev 模式(测试用)
  */
-const path = __importStar(require("path"));
-const kit_1 = require("@chromepilot/kit");
-const version_1 = require("./version");
+import * as path from 'path';
+import { fileURLToPath } from 'node:url';
+import { createCliUpdater } from '@chromepilot/kit';
+import { readInstalledVersions } from './version.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const HOME = () => process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
 const ROOT = () => path.join(HOME(), '.hunter-mate');
 /**
@@ -60,30 +23,30 @@ const ROOT = () => path.join(HOME(), '.hunter-mate');
  * 包根路径含 /worktrees/ 段(hc-hw local worktree 布局)或 HUNTER_MATE_DEV=1。
  * 注意:GitHub Release 二进制安装(~/.hunter-mate/bin)不属于 dev 模式。
  */
-function computeDevLinked(pkgRoot) {
+export function computeDevLinked(pkgRoot) {
     if (process.env.HUNTER_MATE_DEV === '1')
         return true;
     return path.normalize(pkgRoot).includes(`${path.sep}worktrees${path.sep}`);
 }
-function isDevLinked() {
+export function isDevLinked() {
     return computeDevLinked(path.join(__dirname, '..'));
 }
-const updater = (0, kit_1.createCliUpdater)({
+const updater = createCliUpdater({
     npmPackage: 'hunter-mate',
     envPrefix: 'HUNTER_MATE',
     stateDir: ROOT,
-    getInstalledVersion: () => (0, version_1.readInstalledVersions)().cli,
+    getInstalledVersion: () => readInstalledVersions().cli,
     isDev: isDevLinked,
 });
 // ---------------------------------------------------------------------------
 // 兼容导出(调用方零改动)
 // ---------------------------------------------------------------------------
-exports.npmLatestVersion = updater.npmLatestVersion;
-exports.npmSelfUpdate = updater.npmSelfUpdate;
-exports.updateCheckIntervalMs = updater.updateCheckIntervalMs;
-exports.shouldCheckUpdate = updater.shouldCheckUpdate;
-exports.markUpdateChecked = updater.markUpdateChecked;
+export const npmLatestVersion = updater.npmLatestVersion;
+export const npmSelfUpdate = updater.npmSelfUpdate;
+export const updateCheckIntervalMs = updater.updateCheckIntervalMs;
+export const shouldCheckUpdate = updater.shouldCheckUpdate;
+export const markUpdateChecked = updater.markUpdateChecked;
 /** preAction 集成入口:返回日志行数组,永不 throw */
-async function maybeCliSelfUpdate() {
+export async function maybeCliSelfUpdate() {
     return updater.autoCliUpdate();
 }

package/dist/utils/proc.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Result of an attempted graceful termination.
+ *
+ * - `graceful`: the target acknowledged the signal and exited on its own
+ *   before the grace deadline.
+ * - `forced`: we had to escalate to `SIGKILL` / `taskkill /F` after the
+ *   deadline elapsed.
+ * - `esrch`: no such PID; the process was already gone (success).
+ * - `error`: an unexpected failure happened (e.g. permission denied on
+ *   `taskkill`). Caller should inspect stderr.
+ */
+export type KillOutcome = "graceful" | "forced" | "esrch" | "error";
+/**
+ * Synchronous variant — useful for `stop` commands that cannot easily be
+ * turned into async functions. Returns `true` iff the first signal
+ * attempt appeared to succeed (status 0 from `taskkill`, or `SIGTERM`
+ * delivered without throwing on POSIX).
+ */
+export declare function killGracefullySync(pid: number): boolean;
+/**
+ * Async graceful termination.
+ *
+ * On Windows, `process.kill(pid, 'SIGTERM')` is a no-op (Node only supports
+ * `SIGKILL`/`SIGINT`/`SIGQUIT`/etc as process-group signals on POSIX).
+ * `taskkill /pid <pid> /T` without `/F` sends WM_CLOSE to GUI children and
+ * CTRL_BREAK to console children — which NestJS + Next.js turn into a
+ * graceful shutdown through `enableShutdownHooks()`. If the process is
+ * still alive after `graceMs`, we escalate to `/F` (force).
+ *
+ * On POSIX we send SIGTERM, wait `graceMs`, then SIGKILL as a last resort.
+ *
+ * The polling interval (200ms) is intentionally short so the function
+ * returns promptly when the child exits but does not busy-spin.
+ */
+export declare function killGracefully(pid: number, graceMs?: number): Promise<KillOutcome>;

package/dist/utils/proc.js

@@ -0,0 +1,81 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Synchronous variant — useful for `stop` commands that cannot easily be
+ * turned into async functions. Returns `true` iff the first signal
+ * attempt appeared to succeed (status 0 from `taskkill`, or `SIGTERM`
+ * delivered without throwing on POSIX).
+ */
+export function killGracefullySync(pid) {
+    if (process.platform === "win32") {
+        return (spawnSync("taskkill", ["/pid", String(pid), "/T"], { encoding: "utf-8" })
+            .status === 0);
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Async graceful termination.
+ *
+ * On Windows, `process.kill(pid, 'SIGTERM')` is a no-op (Node only supports
+ * `SIGKILL`/`SIGINT`/`SIGQUIT`/etc as process-group signals on POSIX).
+ * `taskkill /pid <pid> /T` without `/F` sends WM_CLOSE to GUI children and
+ * CTRL_BREAK to console children — which NestJS + Next.js turn into a
+ * graceful shutdown through `enableShutdownHooks()`. If the process is
+ * still alive after `graceMs`, we escalate to `/F` (force).
+ *
+ * On POSIX we send SIGTERM, wait `graceMs`, then SIGKILL as a last resort.
+ *
+ * The polling interval (200ms) is intentionally short so the function
+ * returns promptly when the child exits but does not busy-spin.
+ */
+export async function killGracefully(pid, graceMs = 5000) {
+    const deadline = Date.now() + graceMs;
+    const pollGone = async () => {
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 200));
+            try {
+                process.kill(pid, 0);
+            }
+            catch {
+                return true;
+            }
+        }
+        return false;
+    };
+    if (process.platform === "win32") {
+        const r1 = spawnSync("taskkill", ["/pid", String(pid), "/T"], {
+            encoding: "utf-8",
+        });
+        if (r1.status === 0)
+            return "graceful";
+        const out = `${r1.stdout ?? ""}${r1.stderr ?? ""}`;
+        if (/not found|找不到|0x.*找不到/i.test(out))
+            return "esrch";
+        if (await pollGone())
+            return "graceful";
+        const r2 = spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { encoding: "utf-8" });
+        return r2.status === 0 ? "forced" : "error";
+    }
+    // POSIX path
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (err) {
+        const e = err;
+        return e.code === "ESRCH" ? "esrch" : "error";
+    }
+    if (await pollGone())
+        return "graceful";
+    try {
+        process.kill(pid, "SIGKILL");
+        return "forced";
+    }
+    catch {
+        return "error";
+    }
+}