@excitedjs/dreamux-utils 0.3.4 → 0.4.0-beta.142

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export * from './fs.js';
 export * from './completion-body.js';
 export * from './socket-budget.js';
 export * from './turn-render.js';
+export * from './supervised-child.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -4,4 +4,5 @@ export * from './fs.js';
 export * from './completion-body.js';
 export * from './socket-budget.js';
 export * from './turn-render.js';
+export * from './supervised-child.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC"}

package/dist/supervised-child.d.ts

@@ -0,0 +1,49 @@
+import { type ChildProcess, type ForkOptions, type SpawnOptions } from 'node:child_process';
+export interface SupervisedChildExit {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
+export type SupervisedChildLaunch = {
+    kind: 'spawn';
+    command: string;
+    args?: readonly string[];
+    options?: Omit<SpawnOptions, 'detached'>;
+} | {
+    kind: 'fork';
+    modulePath: string;
+    args?: readonly string[];
+    options?: Omit<ForkOptions, 'detached'>;
+};
+export interface SupervisedChildOptions {
+    stopTimeoutMs?: number;
+    pollIntervalMs?: number;
+}
+type ExitHandler = (exit: SupervisedChildExit) => void;
+type ErrorHandler = (error: Error) => void;
+/**
+ * Neutral owner for one detached child process group. Domain wrappers keep
+ * readiness probes, transports, and cleanup policy; this class owns only
+ * launch, unexpected-exit observation, and two-stage group termination.
+ */
+export declare class SupervisedChild {
+    private readonly launch;
+    private readonly options;
+    private child_;
+    private pid_;
+    private stopping;
+    private stopPromise;
+    private readonly exitHandlers;
+    private readonly errorHandlers;
+    constructor(launch: SupervisedChildLaunch, options?: SupervisedChildOptions);
+    get child(): ChildProcess | null;
+    get pid(): number | null;
+    onExit(handler: ExitHandler): () => void;
+    onError(handler: ErrorHandler): () => void;
+    start(): Promise<ChildProcess>;
+    stop(): Promise<void>;
+    private doStop;
+    private notifyExit;
+    private notifyError;
+}
+export {};
+//# sourceMappingURL=supervised-child.d.ts.map

package/dist/supervised-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervised-child.d.ts","sourceRoot":"","sources":["../src/supervised-child.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;CAC1C,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;CACzC,CAAC;AAEN,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,KAAK,WAAW,GAAG,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAC;AACvD,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,eAAe;IASxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;gBAGtC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,GAAE,sBAA2B;IAGvD,IAAI,KAAK,IAAI,YAAY,GAAG,IAAI,CAE/B;IAED,IAAI,GAAG,IAAI,MAAM,GAAG,IAAI,CAEvB;IAED,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,IAAI;IAKxC,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI;IAKpC,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC;IAuCpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAKP,MAAM;IAmBpB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,WAAW;CASpB"}

package/dist/supervised-child.js

@@ -0,0 +1,151 @@
+import { fork, spawn, } from 'node:child_process';
+import { isProcessAlive, killProcessGroup } from './os.js';
+/**
+ * Neutral owner for one detached child process group. Domain wrappers keep
+ * readiness probes, transports, and cleanup policy; this class owns only
+ * launch, unexpected-exit observation, and two-stage group termination.
+ */
+export class SupervisedChild {
+    launch;
+    options;
+    child_ = null;
+    pid_ = null;
+    stopping = false;
+    stopPromise = null;
+    exitHandlers = new Set();
+    errorHandlers = new Set();
+    constructor(launch, options = {}) {
+        this.launch = launch;
+        this.options = options;
+    }
+    get child() {
+        return this.child_;
+    }
+    get pid() {
+        return this.pid_;
+    }
+    onExit(handler) {
+        this.exitHandlers.add(handler);
+        return () => this.exitHandlers.delete(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    async start() {
+        if (this.child_ !== null) {
+            throw new Error('SupervisedChild.start: already started');
+        }
+        if (this.stopping) {
+            throw new Error('SupervisedChild.start: already stopped');
+        }
+        const child = launchChild(this.launch);
+        this.child_ = child;
+        // Node assigns pid synchronously for a successfully launched child. Publish
+        // it before the first await so a concurrent stop can never miss the group.
+        if (child.pid !== undefined)
+            this.pid_ = child.pid;
+        child.on('error', (error) => this.notifyError(error));
+        child.once('exit', (code, signal) => {
+            if (this.stopping)
+                return;
+            this.notifyExit({ code, signal });
+        });
+        try {
+            await waitForSpawn(child);
+        }
+        catch (error) {
+            this.child_ = null;
+            this.pid_ = null;
+            throw error;
+        }
+        if (child.pid === undefined) {
+            this.child_ = null;
+            this.pid_ = null;
+            throw new Error('supervised child spawned without a pid');
+        }
+        this.pid_ = child.pid;
+        if (this.stopping) {
+            await this.stopPromise;
+            throw new Error('SupervisedChild.start: stopped during start');
+        }
+        return child;
+    }
+    stop() {
+        this.stopPromise ??= this.doStop();
+        return this.stopPromise;
+    }
+    async doStop() {
+        this.stopping = true;
+        const pid = this.pid_;
+        if (pid !== null) {
+            if (isProcessAlive(pid)) {
+                killProcessGroup(pid, 'SIGTERM');
+                const deadline = Date.now() + (this.options.stopTimeoutMs ?? 1_000);
+                const pollIntervalMs = this.options.pollIntervalMs ?? 25;
+                while (Date.now() < deadline) {
+                    if (!isProcessAlive(pid))
+                        break;
+                    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+                }
+            }
+            // Always signal the group: a grandchild may outlive an exited leader.
+            killProcessGroup(pid, 'SIGKILL');
+        }
+        this.child_ = null;
+    }
+    notifyExit(exit) {
+        for (const handler of this.exitHandlers) {
+            try {
+                handler(exit);
+            }
+            catch {
+                // Observers must not poison child-process event dispatch.
+            }
+        }
+    }
+    notifyError(error) {
+        for (const handler of this.errorHandlers) {
+            try {
+                handler(error);
+            }
+            catch {
+                // Observers must not poison child-process event dispatch.
+            }
+        }
+    }
+}
+function launchChild(launch) {
+    if (launch.kind === 'fork') {
+        return fork(launch.modulePath, [...(launch.args ?? [])], {
+            ...launch.options,
+            detached: true,
+        });
+    }
+    return spawn(launch.command, [...(launch.args ?? [])], {
+        ...launch.options,
+        detached: true,
+    });
+}
+async function waitForSpawn(child) {
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const onError = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            child.off('spawn', onSpawn);
+            reject(error);
+        };
+        const onSpawn = () => {
+            if (settled)
+                return;
+            settled = true;
+            child.off('error', onError);
+            resolve();
+        };
+        child.once('error', onError);
+        child.once('spawn', onSpawn);
+    });
+}
+//# sourceMappingURL=supervised-child.js.map

package/dist/supervised-child.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervised-child.js","sourceRoot":"","sources":["../src/supervised-child.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@excitedjs/dreamux-utils",
-  "version": "0.3.4",
+  "version": "0.4.0-beta.142",
   "description": "Pure shared utilities for Dreamux providers and host: neutral config-validation primitives, OS/filesystem helpers, completion-body resolution, and inbound-turn render helpers. Depends on @excitedjs/dreamux-types only, never on @excitedjs/dreamux core (issue excitedjs/dreamux#209).",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@excitedjs/dreamux-types": "0.7.0"
+    "@excitedjs/dreamux-types": "0.8.0-beta.142"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",