@mearl/daemon-core 2.20.6 → 2.22.0

package/README.md

@@ -12,9 +12,12 @@ Mearl 各 Node 包共享的守护进程生命周期原语：进程存活探测
 
 ```typescript
 isAlive(pid: number | undefined | null): boolean
+isProcessGroupAlive(group: number): boolean
 ```
 
-用 signal-0 探测进程是否存活（`EPERM` 视为存活——进程存在但属于他人）。
+用 signal-0 探测进程是否存活（`EPERM` 视为存活——进程存在但属于他人）。Linux 同时读取 `/proc/<pid>/stat`，将已退出、尚未回收的 zombie 和 dead 状态视为已停止；主线程退出但仍有其他线程时，以及无法读取状态时，保守视为存活。
+
+POSIX 进程组检查包含根进程退出后仍存活的后代。Linux 只有在两次检查得到相同的已退出成员及创建身份时，才确认组内执行已停止；活跃后代、成员变化和权限或读取失败都会保留清理未确认状态。Windows 不使用 POSIX 进程组检查。
 
 ### 路径派生（多实例）
 

package/dist/command.d.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+export interface SpawnCommand {
+    command: string;
+    args: string[];
+}
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface RunCommandOptions {
+    capture?: boolean;
+    /** 显示并捕获输出，同时继承 stdin 以保留安装器交互。 */
+    tee?: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+export type CommandRunner = (command: string, args: string[], options?: RunCommandOptions) => Promise<CommandResult>;
+export declare function isExecutable(filePath: string, platform?: NodeJS.Platform): boolean;
+export declare function executableNames(name: string, platform?: NodeJS.Platform): string[];
+export interface VersionManagerExecutableCandidateOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    readdirSync?: typeof fs.readdirSync;
+}
+export declare function versionManagerExecutableCandidates(home: string, names: string[], options?: VersionManagerExecutableCandidateOptions): string[];
+export declare function resolveSpawnCommand(executable: string, args: string[], platform?: NodeJS.Platform, commandInterpreter?: string | undefined): SpawnCommand;
+export declare function prependCommandPath(command: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function prependNodePath(env?: NodeJS.ProcessEnv, nodeExecutable?: string): NodeJS.ProcessEnv;
+export declare function prependPathDirectory(directory: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function findExecutable(name: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    existsSync?: (filePath: string) => boolean;
+    platform?: NodeJS.Platform;
+    extraDirectories?: string[];
+}): string | null;
+export declare const runCommand: CommandRunner;

package/dist/command.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+const MAX_CAPTURE_LENGTH = 1_000_000;
+export function isExecutable(filePath, platform = process.platform) {
+    try {
+        fs.accessSync(filePath, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function executableNames(name, platform = process.platform) {
+    return platform === 'win32' ? [`${name}.cmd`, `${name}.exe`, name] : [name];
+}
+export function versionManagerExecutableCandidates(home, names, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const readdirSync = options.readdirSync ?? fs.readdirSync;
+    const fnmDefaultRoot = env.XDG_DATA_HOME
+        ? path.join(env.XDG_DATA_HOME, 'fnm')
+        : platform === 'darwin'
+            ? path.join(home, 'Library', 'Application Support', 'fnm')
+            : platform === 'win32' && env.APPDATA
+                ? path.join(env.APPDATA, 'fnm')
+                : path.join(home, '.local', 'share', 'fnm');
+    const roots = [
+        path.join(env.NVM_DIR || path.join(home, '.nvm'), 'versions', 'node'),
+        path.join(env.FNM_DIR || fnmDefaultRoot, 'node-versions'),
+        path.join(home, '.fnm', 'node-versions'),
+    ].filter((root, index, all) => all.indexOf(root) === index);
+    return roots.flatMap(root => {
+        try {
+            return readdirSync(root, { withFileTypes: true })
+                .filter(entry => entry.isDirectory())
+                .sort((left, right) => right.name.localeCompare(left.name, undefined, { numeric: true }))
+                .flatMap(entry => names.flatMap(name => [
+                path.join(root, entry.name, 'bin', name),
+                path.join(root, entry.name, 'installation', 'bin', name),
+            ]));
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function resolveSpawnCommand(executable, args, platform = process.platform, commandInterpreter = process.env.ComSpec) {
+    if (platform === 'win32' && /\.(?:cmd|bat)$/i.test(executable)) {
+        return {
+            command: commandInterpreter || 'cmd.exe',
+            args: ['/d', '/s', '/c', executable, ...args],
+        };
+    }
+    return { command: executable, args };
+}
+export function prependCommandPath(command, env = process.env) {
+    if (!path.isAbsolute(command))
+        return env;
+    return prependPathDirectory(path.dirname(command), env);
+}
+export function prependNodePath(env = process.env, nodeExecutable = process.execPath) {
+    return prependPathDirectory(path.dirname(nodeExecutable), env);
+}
+export function prependPathDirectory(directory, env = process.env) {
+    const pathKey = Object.keys(env).find(key => key.toLowerCase() === 'path') || 'PATH';
+    const inherited = env[pathKey] || '';
+    const entries = inherited.split(path.delimiter).filter(Boolean);
+    if (entries.includes(directory))
+        return env;
+    return { ...env, [pathKey]: [directory, ...entries].join(path.delimiter) };
+}
+export function findExecutable(name, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const existsSync = options.existsSync ?? (candidate => isExecutable(candidate, platform));
+    const pathKey = Object.keys(env).find(key => key.toLowerCase() === 'path') || 'PATH';
+    const directories = [
+        ...(options.extraDirectories ?? []),
+        ...(env[pathKey] ?? '').split(path.delimiter).filter(Boolean),
+    ];
+    for (const directory of directories) {
+        for (const executableName of executableNames(name, platform)) {
+            const candidate = path.join(directory, executableName);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+export const runCommand = (command, args, options = {}) => new Promise((resolve, reject) => {
+    const capture = options.capture === true || options.tee === true;
+    const launch = resolveSpawnCommand(command, args);
+    const child = spawn(launch.command, launch.args, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: capture ? [options.tee ? 'inherit' : 'ignore', 'pipe', 'pipe'] : 'inherit',
+        windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const append = (current, chunk) => options.tee
+        ? (current + chunk).slice(-MAX_CAPTURE_LENGTH)
+        : current.length >= MAX_CAPTURE_LENGTH
+            ? current
+            : (current + chunk).slice(0, MAX_CAPTURE_LENGTH);
+    const finish = (error, code = 1) => {
+        if (settled)
+            return;
+        settled = true;
+        if (timer)
+            clearTimeout(timer);
+        if (error)
+            reject(error);
+        else
+            resolve({ code, stdout, stderr });
+    };
+    const timer = options.timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => {
+            child.kill('SIGTERM');
+            finish(new Error(`Command timed out after ${options.timeoutMs}ms`));
+        }, options.timeoutMs);
+    if (capture) {
+        child.stdout?.setEncoding('utf8').on('data', (chunk) => {
+            stdout = append(stdout, chunk);
+            if (options.tee)
+                process.stdout.write(chunk);
+        });
+        child.stderr?.setEncoding('utf8').on('data', (chunk) => {
+            stderr = append(stderr, chunk);
+            if (options.tee)
+                process.stderr.write(chunk);
+        });
+    }
+    child.once('error', error => finish(error));
+    child.once('close', code => finish(undefined, code ?? 1));
+});

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from './paths.js';
 export * from './registry.js';
 export * from './log.js';
 export * from './daemon.js';
+export * from './command.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export * from './paths.js';
 export * from './registry.js';
 export * from './log.js';
 export * from './daemon.js';
+export * from './command.js';

package/dist/log.d.ts

@@ -1,3 +1,5 @@
+/** Keep recent diagnostics and every log with a corresponding daemon record. */
+export declare function pruneOrphanLogs(directory: string, retentionMs?: number): void;
 /**
  * Rotate `<log>` to `<log>.1` if it has grown past the limit. Meant to be called
  * before each (re)start, since a detached child appends to an inherited fd and

package/dist/log.js

@@ -1,6 +1,28 @@
-import { existsSync, statSync, renameSync, readFileSync } from 'node:fs';
+import { existsSync, statSync, renameSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
 /** Rotate the log when it grows past this size (keeps one `.1` backup). */
 const DEFAULT_MAX_LOG_BYTES = 5 * 1024 * 1024;
+/** Keep recent diagnostics and every log with a corresponding daemon record. */
+export function pruneOrphanLogs(directory, retentionMs = 7 * 86400_000) {
+    try {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const match = /^([a-f0-9]{16})\.log(?:\.1)?$/.exec(entry.name);
+            if (!entry.isFile() || !match || existsSync(join(directory, `${match[1]}.json`)))
+                continue;
+            const file = join(directory, entry.name);
+            try {
+                if (Date.now() - statSync(file).mtimeMs >= retentionMs)
+                    rmSync(file, { force: true });
+            }
+            catch {
+                // Another host may have reclaimed the same orphan.
+            }
+        }
+    }
+    catch {
+        // Diagnostic cleanup must not prevent starting a browser.
+    }
+}
 /**
  * Rotate `<log>` to `<log>.1` if it has grown past the limit. Meant to be called
  * before each (re)start, since a detached child appends to an inherited fd and

package/dist/process.d.ts

@@ -1,8 +1,16 @@
+/** OS creation identity distinguishes an owner from an unrelated process reusing its pid. */
+export declare function processIdentity(pid: number): string | undefined;
+export declare function isProcessOwnerAlive(owner: {
+    pid: number;
+    processIdentity?: unknown;
+}): boolean;
 /**
  * Whether a process with the given pid is currently alive.
  *
- * Uses the signal-0 probe, which never actually delivers a signal — it only
- * performs the kernel's permission/existence checks. EPERM means the process
- * exists but is owned by another user, so it still counts as alive.
+ * Signal 0 checks existence without delivering a signal. Linux zombies retain
+ * their pid until reaped, so procfs distinguishes them from executable owners.
+ * Unavailable inspection and EPERM remain conservatively alive.
  */
 export declare function isAlive(pid: number | undefined | null): boolean;
+/** POSIX group liveness includes live descendants after their original owner exits. */
+export declare function isProcessGroupAlive(group: number): boolean;

package/dist/process.js

@@ -1,18 +1,140 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+function linuxProcessStat(pid) {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const end = stat.lastIndexOf(')');
+    const fields = stat
+        .slice(end + 2)
+        .trim()
+        .split(/\s+/);
+    const group = Number(fields[2]);
+    const threads = Number(fields[17]);
+    if (end < 0 ||
+        !/^[A-Za-z]$/.test(fields[0]) ||
+        !Number.isSafeInteger(group) ||
+        group < 0 ||
+        !Number.isSafeInteger(threads) ||
+        threads < 0 ||
+        !/^\d+$/.test(fields[19] ?? ''))
+        throw new Error('Invalid Linux process stat');
+    return { state: fields[0], group, threads, identity: fields[19] };
+}
+function linuxProcessExited({ state, threads }) {
+    // A terminated thread-group leader may still have executable sibling threads.
+    return threads <= 1 && (state === 'Z' || state === 'X' || state === 'x');
+}
+/** OS creation identity distinguishes an owner from an unrelated process reusing its pid. */
+export function processIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return undefined;
+    try {
+        if (process.platform === 'linux') {
+            return linuxProcessStat(pid).identity;
+        }
+        const result = process.platform === 'win32'
+            ? spawnSync('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CreationDate.ToUniversalTime().Ticks`,
+            ], { encoding: 'utf8', timeout: 2000, windowsHide: true })
+            : spawnSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+                encoding: 'utf8',
+                timeout: 2000,
+            });
+        return result.status === 0 ? result.stdout.trim() || undefined : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isProcessOwnerAlive(owner) {
+    if (!isAlive(owner.pid))
+        return false;
+    if (typeof owner.processIdentity !== 'string')
+        return true;
+    const current = processIdentity(owner.pid);
+    return current === undefined || current === owner.processIdentity;
+}
 /**
  * Whether a process with the given pid is currently alive.
  *
- * Uses the signal-0 probe, which never actually delivers a signal — it only
- * performs the kernel's permission/existence checks. EPERM means the process
- * exists but is owned by another user, so it still counts as alive.
+ * Signal 0 checks existence without delivering a signal. Linux zombies retain
+ * their pid until reaped, so procfs distinguishes them from executable owners.
+ * Unavailable inspection and EPERM remain conservatively alive.
  */
 export function isAlive(pid) {
-    if (!pid || pid <= 0)
+    if (!Number.isSafeInteger(pid) || !pid || pid <= 0)
         return false;
     try {
         process.kill(pid, 0);
+        if (process.platform === 'linux') {
+            try {
+                return !linuxProcessExited(linuxProcessStat(pid));
+            }
+            catch {
+                return true;
+            }
+        }
         return true;
     }
     catch (error) {
         return error.code === 'EPERM';
     }
 }
+/** POSIX group liveness includes live descendants after their original owner exits. */
+export function isProcessGroupAlive(group) {
+    if (!Number.isSafeInteger(group) || group < 1)
+        return false;
+    if (process.platform === 'win32')
+        return true;
+    const probe = () => {
+        try {
+            process.kill(-group, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === 'ESRCH' ? false : undefined;
+        }
+    };
+    const present = probe();
+    if (present !== true)
+        return present !== false;
+    if (process.platform !== 'linux')
+        return true;
+    const exitedMembers = () => {
+        const members = new Set();
+        try {
+            for (const name of readdirSync('/proc')) {
+                if (!/^\d+$/.test(name))
+                    continue;
+                try {
+                    const stat = linuxProcessStat(Number(name));
+                    if (stat.group !== group)
+                        continue;
+                    if (!linuxProcessExited(stat))
+                        return undefined;
+                    members.add(`${name}:${stat.identity}`);
+                }
+                catch (error) {
+                    if (!['ENOENT', 'ESRCH'].includes(error.code ?? ''))
+                        return undefined;
+                }
+            }
+            return members;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // Stable exited membership excludes a child forked while the first scan was in progress.
+    const first = exitedMembers();
+    if (!first)
+        return true;
+    const second = exitedMembers();
+    if (!second)
+        return true;
+    if (first.size && first.size === second.size && [...first].every(pid => second.has(pid)))
+        return false;
+    return probe() !== false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/daemon-core",
-  "version": "2.20.6",
+  "version": "2.22.0",
   "description": "Shared Node daemon lifecycle primitives for Mearl — process liveness, JSON record registry, log rotation, and a detached daemon manager",
   "type": "module",
   "main": "dist/index.js",