@mearl/daemon-core 2.0.0

package/README.md

@@ -0,0 +1,86 @@
+# @mearl/daemon-core
+
+Mearl 各 Node 包共享的守护进程生命周期原语：进程存活探测、JSON 记录注册表、日志滚动，以及一个 detached 守护进程管理器。
+
+把 `cloud-server`、`cloud-connector`、`native-host` 里原本各写一份、容易彼此漂移的 daemon 逻辑（`isAlive`、原子读写注册表、日志滚动、按 key 派生路径）收敛到这一处，确保「写方」和「读方」对**记录位置与格式**始终一致。
+
+> 仅供 monorepo 内部使用（Node-only）。`cloud-server` / `cloud-connector` 以普通依赖引入（运行时从 npm 解析），`native-host` 在打包时直接内联。
+
+## API
+
+### 进程存活
+
+```typescript
+isAlive(pid: number | undefined | null): boolean
+```
+
+用 signal-0 探测进程是否存活（`EPERM` 视为存活——进程存在但属于他人）。
+
+### 路径派生（多实例）
+
+```typescript
+DAEMON_HOME                                 // ~/.mearl
+hashKey(key: string): string                // sha256(key) 前 16 位十六进制
+keyedDir(subdir: string): string            // ~/.mearl/<subdir>
+keyedConfigFile(subdir, key): string        // ~/.mearl/<subdir>/<hash>.json
+keyedLogFile(subdir, key): string           // ~/.mearl/<subdir>/<hash>.log
+```
+
+多实例子系统（如按 `serverUrl` 区分的连接器）用这些 helper 派生每实例的文件路径。**所有读写方都必须经由它们派生路径**，这样彼此才不会对记录位置产生分歧。
+
+### 记录注册表
+
+```typescript
+interface DaemonRecord { pid: number; startedAt?: string; [k: string]: unknown }
+
+ensureDir(dir: string): void
+writeRecord(file: string, record: DaemonRecord): void   // 临时文件 + rename 原子写
+readRecord<T>(file: string): T | null
+removeRecord(file: string): void
+listRecordFiles(dir: string): string[]                  // 目录下所有 *.json 绝对路径
+readLiveRecords<T>(dir: string): T[]                    // 读取存活记录，并顺带清理死记录
+```
+
+### 守护进程管理器
+
+```typescript
+createDaemon(opts: CreateDaemonOptions): Daemon
+```
+
+围绕一对 `(configFile, logFile)` 构建单实例守护进程管理器。模型：`start()` 以 `--foreground` detached 方式重新拉起消费方自己的 CLI；子进程运行实际服务，就绪后把自己的 pid 写入 `configFile`，父进程轮询 `record.pid === child.pid` 确认其已起来（而非死亡或卡住）。多实例子系统按实例 key 派生 `configFile`/`logFile`，为每个实例各创建一个管理器。
+
+```typescript
+interface CreateDaemonOptions {
+  name: string;            // 日志标签，如 'CloudServer' / 'CloudConnector'
+  scriptPath: string;      // 可重新拉起的 CLI 脚本绝对路径（消费方打包后的 cli.js）
+  configFile: string;      // 本实例的 JSON 记录文件（由前台子进程写入）
+  logFile: string;         // 本实例的日志文件
+  foregroundArgs?: string[];   // 追加在 `--foreground` 之后的 argv
+  readyTimeoutMs?: number;     // 等待子进程写记录的超时（默认 15000ms）
+  formatInfo?: (record: DaemonRecord) => string | null;  // 起来后额外打印的信息
+}
+
+interface Daemon {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  restart(): Promise<void>;
+  status(): void;
+  logs(lines?: number): void;
+  running(): DaemonRecord | null;
+}
+```
+
+> `scriptPath` 必须是消费方自己的 `cli.js`：用打包进 cli 入口的某个模块里的 `fileURLToPath(import.meta.url)` 计算。daemon-core 自身被独立解析时，它的 `import.meta.url` 指向 daemon-core，而不是 cli。
+
+### 日志
+
+```typescript
+rotateLogIfNeeded(logFile: string, maxBytes?: number): void  // 超限则滚动为 <log>.1，默认 5MB
+tailFile(logFile: string, lines: number): string
+```
+
+## 使用方
+
+- **cloud-server** —— `createDaemon`（单实例，`~/.mearl/cloud-server.json`）
+- **cloud-connector** —— `createDaemon`（多实例，按 `serverUrl` 区分，`~/.mearl/connectors/<hash>.json`）+ `readLiveRecords` 列举
+- **native-host** —— 仅用原语（`isAlive` / `keyedConfigFile` / `readRecord` / `readLiveRecords` 等）读取连接器共享注册表，以发现/接管/列举连接器

package/dist/daemon.d.ts

@@ -0,0 +1,42 @@
+import { type DaemonRecord } from './registry.js';
+export interface CreateDaemonOptions {
+    /** Label used in log lines, e.g. `CloudServer` / `CloudConnector`. */
+    name: string;
+    /**
+     * Absolute path to the re-spawnable CLI script (the consumer's bundled
+     * `cli.js`). The daemon re-launches it as `node <scriptPath> --foreground …`,
+     * so the consumer's CLI must run the instance in-process when it sees
+     * `--foreground`. Compute it with `fileURLToPath(import.meta.url)` from a
+     * module that is bundled INTO the cli entry.
+     */
+    scriptPath: string;
+    /** Path to this instance's JSON record file (written by the foreground child). */
+    configFile: string;
+    /** Path to this instance's log file (the detached child's stdout/stderr). */
+    logFile: string;
+    /** argv appended after `--foreground` when spawning the detached child. */
+    foregroundArgs?: string[];
+    /** How long to wait for the child to write its record. Default 15000ms. */
+    readyTimeoutMs?: number;
+    /** Extra lines to print once the instance is up/queried (e.g. a connect hint). */
+    formatInfo?: (record: DaemonRecord) => string | null;
+}
+export interface Daemon {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    status(): void;
+    logs(lines?: number): void;
+    /** Current record if a live instance exists, else null. */
+    running(): DaemonRecord | null;
+}
+/**
+ * Build a single-instance daemon manager around a `(configFile, logFile)` pair.
+ *
+ * The model: `start()` spawns the consumer's CLI detached with `--foreground`;
+ * that child runs the actual service and, once ready, writes its own pid into
+ * `configFile`. The parent polls for `record.pid === child.pid` to confirm the
+ * child came up (vs. died or hung). Multi-instance subsystems create one manager
+ * per instance, deriving `configFile`/`logFile` from the instance key.
+ */
+export declare function createDaemon(opts: CreateDaemonOptions): Daemon;

package/dist/daemon.js

@@ -0,0 +1,131 @@
+import { spawn } from 'node:child_process';
+import { openSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { isAlive } from './process.js';
+import { ensureDir, readRecord, removeRecord } from './registry.js';
+import { rotateLogIfNeeded, tailFile } from './log.js';
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Build a single-instance daemon manager around a `(configFile, logFile)` pair.
+ *
+ * The model: `start()` spawns the consumer's CLI detached with `--foreground`;
+ * that child runs the actual service and, once ready, writes its own pid into
+ * `configFile`. The parent polls for `record.pid === child.pid` to confirm the
+ * child came up (vs. died or hung). Multi-instance subsystems create one manager
+ * per instance, deriving `configFile`/`logFile` from the instance key.
+ */
+export function createDaemon(opts) {
+    const { name, scriptPath, configFile, logFile, foregroundArgs = [], readyTimeoutMs = 15_000, formatInfo, } = opts;
+    const tag = `[${name}]`;
+    function running() {
+        const rec = readRecord(configFile);
+        return rec && isAlive(rec.pid) ? rec : null;
+    }
+    function printInfo(rec) {
+        const extra = formatInfo?.(rec);
+        if (extra)
+            console.log(extra);
+    }
+    async function start() {
+        const live = running();
+        if (live) {
+            console.log(`${tag} Already running (pid ${live.pid})`);
+            printInfo(live);
+            return;
+        }
+        // Clear any stale record left by a crashed run before spawning a new child.
+        removeRecord(configFile);
+        ensureDir(dirname(configFile));
+        ensureDir(dirname(logFile));
+        rotateLogIfNeeded(logFile);
+        const logFd = openSync(logFile, 'a');
+        const child = spawn(process.execPath, [scriptPath, '--foreground', ...foregroundArgs], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env: process.env,
+            windowsHide: true,
+        });
+        child.unref();
+        // Wait until the child writes its own pid into the record (i.e. it is ready),
+        // or until it dies / we time out.
+        const deadline = Date.now() + readyTimeoutMs;
+        while (Date.now() < deadline) {
+            if (!isAlive(child.pid)) {
+                console.error(`${tag} Failed to start. Recent log:`);
+                const log = tailFile(logFile, 20);
+                if (log)
+                    console.error(log);
+                console.error(`(full log: ${logFile})`);
+                process.exitCode = 1;
+                return;
+            }
+            const rec = readRecord(configFile);
+            if (rec && rec.pid === child.pid) {
+                console.log(`${tag} Started in background (pid ${child.pid})`);
+                console.log(`${tag} Logs: ${logFile}`);
+                printInfo(rec);
+                return;
+            }
+            await sleep(200);
+        }
+        console.error(`${tag} Start timed out after ${Math.round(readyTimeoutMs / 1000)}s. Check the log: ${logFile}`);
+        process.exitCode = 1;
+    }
+    async function stop() {
+        const rec = readRecord(configFile);
+        if (!rec || !isAlive(rec.pid)) {
+            console.log(`${tag} Not running`);
+            removeRecord(configFile);
+            return;
+        }
+        const pid = rec.pid;
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch (error) {
+            console.error(`${tag} Failed to stop pid ${pid}:`, error.message);
+            process.exitCode = 1;
+            return;
+        }
+        const deadline = Date.now() + 5_000;
+        while (Date.now() < deadline && isAlive(pid)) {
+            await sleep(150);
+        }
+        if (isAlive(pid)) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // ignore
+            }
+        }
+        removeRecord(configFile);
+        console.log(`${tag} Stopped (pid ${pid})`);
+    }
+    async function restart() {
+        await stop();
+        await start();
+    }
+    function status() {
+        const rec = running();
+        if (!rec) {
+            console.log(`${tag} Status: stopped`);
+            return;
+        }
+        console.log(`${tag} Status: running`);
+        console.log(`  pid:        ${rec.pid}`);
+        if (rec.startedAt)
+            console.log(`  started at: ${rec.startedAt}`);
+        console.log(`  log:        ${logFile}`);
+        printInfo(rec);
+    }
+    function logs(lines = 50) {
+        const log = tailFile(logFile, lines);
+        if (log)
+            console.log(log);
+        console.log(`\n(log file: ${logFile} — follow with: tail -f "${logFile}")`);
+    }
+    return { start, stop, restart, status, logs, running };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './process.js';
+export * from './paths.js';
+export * from './registry.js';
+export * from './log.js';
+export * from './daemon.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './process.js';
+export * from './paths.js';
+export * from './registry.js';
+export * from './log.js';
+export * from './daemon.js';

package/dist/log.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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
+ * can't rotate itself mid-run. Best-effort: a failure here must not block startup.
+ */
+export declare function rotateLogIfNeeded(logFile: string, maxBytes?: number): void;
+/** Return the trailing `lines` lines of a log file (empty string if absent). */
+export declare function tailFile(logFile: string, lines: number): string;

package/dist/log.js

@@ -0,0 +1,32 @@
+import { existsSync, statSync, renameSync, readFileSync } from 'node:fs';
+/** Rotate the log when it grows past this size (keeps one `.1` backup). */
+const DEFAULT_MAX_LOG_BYTES = 5 * 1024 * 1024;
+/**
+ * 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
+ * can't rotate itself mid-run. Best-effort: a failure here must not block startup.
+ */
+export function rotateLogIfNeeded(logFile, maxBytes = DEFAULT_MAX_LOG_BYTES) {
+    try {
+        if (!existsSync(logFile))
+            return;
+        if (statSync(logFile).size < maxBytes)
+            return;
+        renameSync(logFile, `${logFile}.1`);
+    }
+    catch {
+        // ignore
+    }
+}
+/** Return the trailing `lines` lines of a log file (empty string if absent). */
+export function tailFile(logFile, lines) {
+    try {
+        if (!existsSync(logFile))
+            return '';
+        const content = readFileSync(logFile, 'utf-8');
+        return content.split('\n').slice(-lines).join('\n').trim();
+    }
+    catch {
+        return '';
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,15 @@
+/** Root directory for all mearl daemon runtime files (configs / logs). */
+export declare const DAEMON_HOME: string;
+/**
+ * Stable short hash of an arbitrary instance key (e.g. a server URL). Used to
+ * derive per-instance file names for multi-instance subsystems. Both the writer
+ * (the daemon process) and any reader (another manager) MUST derive the path
+ * through these helpers so the two never disagree on where a record lives.
+ */
+export declare function hashKey(key: string): string;
+/** Directory holding per-instance files for a subsystem, e.g. `connectors`. */
+export declare function keyedDir(subdir: string): string;
+/** Per-instance JSON record path: ~/.mearl/<subdir>/<hash>.json */
+export declare function keyedConfigFile(subdir: string, key: string): string;
+/** Per-instance log path: ~/.mearl/<subdir>/<hash>.log */
+export declare function keyedLogFile(subdir: string, key: string): string;

package/dist/paths.js

@@ -0,0 +1,26 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+/** Root directory for all mearl daemon runtime files (configs / logs). */
+export const DAEMON_HOME = join(homedir(), '.mearl');
+/**
+ * Stable short hash of an arbitrary instance key (e.g. a server URL). Used to
+ * derive per-instance file names for multi-instance subsystems. Both the writer
+ * (the daemon process) and any reader (another manager) MUST derive the path
+ * through these helpers so the two never disagree on where a record lives.
+ */
+export function hashKey(key) {
+    return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+/** Directory holding per-instance files for a subsystem, e.g. `connectors`. */
+export function keyedDir(subdir) {
+    return join(DAEMON_HOME, subdir);
+}
+/** Per-instance JSON record path: ~/.mearl/<subdir>/<hash>.json */
+export function keyedConfigFile(subdir, key) {
+    return join(keyedDir(subdir), `${hashKey(key)}.json`);
+}
+/** Per-instance log path: ~/.mearl/<subdir>/<hash>.log */
+export function keyedLogFile(subdir, key) {
+    return join(keyedDir(subdir), `${hashKey(key)}.log`);
+}

package/dist/process.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export declare function isAlive(pid: number | undefined | null): boolean;

package/dist/process.js

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export function isAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,23 @@
+/** Base shape every daemon record shares; subsystems extend it with their own fields. */
+export interface DaemonRecord {
+    pid: number;
+    startedAt?: string;
+    [key: string]: unknown;
+}
+export declare function ensureDir(dir: string): void;
+/**
+ * Atomically write a record: serialise to a temp file then rename over the
+ * target, so a concurrent reader never observes a half-written file. The temp
+ * name is pid-scoped so two writers don't clobber each other's temp file.
+ */
+export declare function writeRecord(file: string, record: DaemonRecord): void;
+export declare function readRecord<T extends DaemonRecord = DaemonRecord>(file: string): T | null;
+export declare function removeRecord(file: string): void;
+/** Absolute paths of every `*.json` record file in a directory. */
+export declare function listRecordFiles(dir: string): string[];
+/**
+ * Read every record in a directory whose process is still alive, pruning files
+ * whose pid is dead (or whose contents are corrupt) as a side effect. This is
+ * the canonical way to list a multi-instance subsystem's live records.
+ */
+export declare function readLiveRecords<T extends DaemonRecord = DaemonRecord>(dir: string): T[];

package/dist/registry.js

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync, readdirSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isAlive } from './process.js';
+export function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Atomically write a record: serialise to a temp file then rename over the
+ * target, so a concurrent reader never observes a half-written file. The temp
+ * name is pid-scoped so two writers don't clobber each other's temp file.
+ */
+export function writeRecord(file, record) {
+    ensureDir(dirname(file));
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(record));
+        renameSync(tmp, file);
+    }
+    catch (error) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // ignore
+        }
+        throw error;
+    }
+}
+export function readRecord(file) {
+    try {
+        if (!existsSync(file))
+            return null;
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        return parsed && typeof parsed.pid === 'number' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function removeRecord(file) {
+    try {
+        rmSync(file, { force: true });
+    }
+    catch {
+        // ignore
+    }
+}
+/** Absolute paths of every `*.json` record file in a directory. */
+export function listRecordFiles(dir) {
+    try {
+        return readdirSync(dir)
+            .filter(name => name.endsWith('.json'))
+            .map(name => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read every record in a directory whose process is still alive, pruning files
+ * whose pid is dead (or whose contents are corrupt) as a side effect. This is
+ * the canonical way to list a multi-instance subsystem's live records.
+ */
+export function readLiveRecords(dir) {
+    const out = [];
+    for (const file of listRecordFiles(dir)) {
+        const rec = readRecord(file);
+        if (rec && isAlive(rec.pid)) {
+            out.push(rec);
+        }
+        else {
+            removeRecord(file);
+        }
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mearl/daemon-core",
+  "version": "2.0.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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mearl",
+    "daemon"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}