@mearl/daemon-core 3.0.0-beta.4 → 3.0.0-beta.7

package/dist/command.d.ts

@@ -41,6 +41,8 @@ export declare function resolveSpawnCommand(executable: string, args: string[],
 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;
+/** npm exec's package selector belongs to its invocation, not nested package runners. */
+export declare function npmExecEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function findExecutable(name: string, options?: {
     env?: NodeJS.ProcessEnv;
     existsSync?: (filePath: string) => boolean;

package/dist/command.js

@@ -118,6 +118,10 @@ export function prependPathDirectory(directory, env = process.env) {
         return env;
     return { ...env, [pathKey]: [directory, ...entries].join(path.delimiter) };
 }
+/** npm exec's package selector belongs to its invocation, not nested package runners. */
+export function npmExecEnvironment(env = process.env) {
+    return Object.fromEntries(Object.entries(env).filter(([key]) => key.toLowerCase() !== 'npm_config_package'));
+}
 export function findExecutable(name, options = {}) {
     const env = options.env ?? process.env;
     const platform = options.platform ?? process.platform;

package/dist/node-capabilities.d.ts

@@ -14,6 +14,7 @@ export declare class NodeCapabilityRegistry<Host extends object = object> {
     get revision(): string | undefined;
     get installationRevision(): string | undefined;
     get<T extends NodeCapabilityHandler>(name: string): T | undefined;
+    entries(prefix?: string): Array<[string, NodeCapabilityHandler]>;
     require<T extends NodeCapabilityHandler>(name: string): T;
     refresh(): Promise<string | undefined>;
     private readSelection;

package/dist/node-capabilities.js

@@ -1,12 +1,13 @@
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { Script } from 'node:vm';
+import { isDeepStrictEqual } from 'node:util';
 import { constants } from 'node:fs';
 import { lstat, open } from 'node:fs/promises';
 import { join } from 'node:path';
 import { DAEMON_HOME } from './paths.js';
-import { verifyNodeCapabilityActivation, MAX_NODE_SELECTION_BYTES } from '@mearl/preset';
-const MAX_SELECTION_BYTES = MAX_NODE_SELECTION_BYTES + 128;
+import { verifyCapabilityActivation, MAX_CAPABILITY_SELECTION_BYTES } from '@mearl/preset';
+const MAX_SELECTION_BYTES = MAX_CAPABILITY_SELECTION_BYTES + 128;
 const handlerName = /^[a-z][a-zA-Z0-9_.-]{0,127}$/;
 async function readBoundedFile(file, limit) {
     const stat = await lstat(file);
@@ -50,6 +51,9 @@ export class NodeCapabilityRegistry {
     get revision() { return this.active?.snapshot.revision; }
     get installationRevision() { return this.active?.snapshot.installationRevision; }
     get(name) { return this.active && Object.hasOwn(this.active.handlers, name) ? this.active.handlers[name] : undefined; }
+    entries(prefix = "") {
+        return Object.entries(this.active?.handlers ?? {}).filter(([name]) => name.startsWith(prefix));
+    }
     require(name) {
         const handler = this.get(name);
         if (!handler)
@@ -84,7 +88,7 @@ export class NodeCapabilityRegistry {
                 return undefined;
             throw error;
         }
-        return verifyNodeCapabilityActivation(JSON.parse(bytes.toString('utf8')));
+        return verifyCapabilityActivation(JSON.parse(bytes.toString('utf8')));
     }
     async load(snapshot) {
         if (!snapshot) {
@@ -104,7 +108,7 @@ export class NodeCapabilityRegistry {
         const pointer = join(this.directory, 'active-node.json');
         const bytes = await readBoundedFile(pointer, MAX_SELECTION_BYTES);
         const requested = JSON.parse(bytes.toString('utf8'));
-        const current = await verifyNodeCapabilityActivation(requested).catch(() => undefined);
+        const current = await verifyCapabilityActivation(requested).catch(() => undefined);
         if (current && (current.revision !== failed?.revision || current.installationRevision !== failed?.installationRevision)) {
             try {
                 await this.load(current);
@@ -117,7 +121,7 @@ export class NodeCapabilityRegistry {
         const record = JSON.parse((await readBoundedFile(join(this.directory, 'rollback.json'), MAX_SELECTION_BYTES + 256)).toString('utf8'));
         if (record.candidate !== requested.installationRevision || !record.previous)
             return;
-        const previous = await verifyNodeCapabilityActivation(record.previous);
+        const previous = await verifyCapabilityActivation(record.previous);
         const expected = createHash('sha256').update(bytes).digest('hex');
         await this.prepareSelection(previous, async () => {
             const current = await readBoundedFile(pointer, MAX_SELECTION_BYTES);
@@ -138,6 +142,12 @@ export class NodeCapabilityRegistry {
         }
         const modules = new Map();
         for (const [id, resource] of entries) {
+            const previous = this.active?.snapshot.modules[id];
+            const reusable = this.active?.modules.get(id);
+            if (reusable && previous?.sha256 === resource.sha256 && previous.byteLength === resource.byteLength && isDeepStrictEqual(previous.config ?? {}, resource.config ?? {})) {
+                modules.set(id, reusable);
+                continue;
+            }
             const bytes = resources.get(id);
             // CommonJS wrappers can be reclaimed after their active and in-flight handlers are released.
             const module = { exports: {} };
@@ -163,7 +173,7 @@ export class NodeCapabilityRegistry {
         const current = await guard();
         if (!current)
             throw new Error('Node capability selection changed while preparing modules');
-        this.active = { snapshot: current, handlers: Object.freeze(handlers) };
+        this.active = { snapshot: current, handlers: Object.freeze(handlers), modules };
         return snapshot.revision;
     }
 }

package/dist/page-runtimes.d.ts

@@ -0,0 +1,27 @@
+import { type PageRuntimeBinding } from '@mearl/preset/bundles';
+export interface PageRuntimeOwner {
+    browser: string;
+    target: string;
+    pid?: number;
+    processIdentity?: string;
+}
+export declare const MAX_NODE_PAGE_CACHE_BYTES: number;
+export declare function capabilityDirectory(): string;
+/** Browser references survive host restarts; unavailable remote browsers retain their exact code. */
+export declare class NodePageRuntimeStore {
+    private readonly quota;
+    private readonly root;
+    private readonly index;
+    constructor(directory?: string, quota?: number);
+    resolve(binding: PageRuntimeBinding, provide?: (binding: PageRuntimeBinding) => string | undefined, owner?: PageRuntimeOwner): string;
+    release(owner: PageRuntimeOwner): void;
+    retain(owner: PageRuntimeOwner, binding?: PageRuntimeBinding): void;
+    /** A live target inventory is authoritative after a disconnected host lost close events. */
+    reconcile(browser: string, targets: ReadonlySet<string>): void;
+    private key;
+    private mutate;
+    private collect;
+    private read;
+    private write;
+    private verify;
+}

package/dist/page-runtimes.js

@@ -0,0 +1,163 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DAEMON_HOME } from './paths.js';
+import { isProcessOwnerAlive } from './process.js';
+import { withRecordLock } from './registry.js';
+import { MAX_PAGE_RUNTIME_BYTES } from '@mearl/preset/bundles';
+const sha256 = /^[a-f0-9]{64}$/;
+export const MAX_NODE_PAGE_CACHE_BYTES = 64 * 1024 * 1024;
+export function capabilityDirectory() { return process.env.MEARL_CAPABILITY_DIR || join(DAEMON_HOME, 'capabilities'); }
+/** Browser references survive host restarts; unavailable remote browsers retain their exact code. */
+export class NodePageRuntimeStore {
+    quota;
+    root;
+    index;
+    constructor(directory = capabilityDirectory(), quota = MAX_NODE_PAGE_CACHE_BYTES) {
+        this.quota = quota;
+        this.root = join(directory, 'page-runtimes');
+        this.index = join(this.root, 'references.json');
+    }
+    resolve(binding, provide, owner) {
+        if (!/^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/.test(binding.id) || !sha256.test(binding.sha256))
+            throw new Error('Invalid page runtime binding');
+        return this.mutate(references => {
+            const file = join(this.root, `${binding.sha256}.cjs`);
+            let source;
+            if (existsSync(file))
+                source = this.verify(binding, this.read(file, MAX_PAGE_RUNTIME_BYTES));
+            else {
+                const provided = provide?.(binding);
+                if (typeof provided !== 'string' || !provided.trim())
+                    throw new Error(`Required page runtime is not installed: ${binding.id}@${binding.sha256}`);
+                const bytes = Buffer.from(provided);
+                source = this.verify(binding, bytes);
+                this.collect(references, bytes.byteLength, 1);
+                this.write(file, bytes);
+            }
+            if (owner) {
+                if (!sha256.test(owner.browser) || !owner.target || owner.target.length > 256)
+                    throw new Error('Invalid page runtime owner');
+                const key = this.key(owner);
+                const previous = references.owners[key];
+                if (!previous && Object.keys(references.owners).length >= 4096)
+                    throw new Error('Page runtime reference limit exceeded');
+                references.owners[key] = { ...owner, digests: [...new Set([...(previous?.digests ?? []), binding.sha256])] };
+            }
+            return source;
+        });
+    }
+    release(owner) {
+        if (!existsSync(this.index))
+            return;
+        this.mutate(references => { delete references.owners[this.key(owner)]; this.collect(references); });
+    }
+    retain(owner, binding) {
+        if (!existsSync(this.index))
+            return;
+        this.mutate(references => {
+            const previous = references.owners[this.key(owner)];
+            if (previous && binding && previous.digests.includes(binding.sha256))
+                previous.digests = [binding.sha256];
+            else if (!binding)
+                delete references.owners[this.key(owner)];
+            this.collect(references);
+        });
+    }
+    /** A live target inventory is authoritative after a disconnected host lost close events. */
+    reconcile(browser, targets) {
+        if (!existsSync(this.index))
+            return;
+        this.mutate(references => {
+            for (const [key, owner] of Object.entries(references.owners))
+                if (owner.browser === browser && !targets.has(owner.target))
+                    delete references.owners[key];
+            this.collect(references);
+        });
+    }
+    key(owner) { return createHash('sha256').update(JSON.stringify([owner.browser, owner.target])).digest('hex'); }
+    mutate(action) {
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        return withRecordLock(this.index, () => {
+            const references = existsSync(this.index) ? JSON.parse(this.read(this.index, 4 * 1024 * 1024).toString('utf8')) : { owners: {} };
+            if (!references || !references.owners || typeof references.owners !== 'object' || Array.isArray(references.owners) || Object.keys(references.owners).length > 4096)
+                throw new Error('Invalid page runtime reference index');
+            const liveness = new Map();
+            for (const [key, owner] of Object.entries(references.owners)) {
+                if (!owner || !sha256.test(owner.browser) || typeof owner.target !== 'string' || !Array.isArray(owner.digests) || owner.digests.length > 256 || owner.digests.some(digest => typeof digest !== 'string' || !sha256.test(digest)))
+                    throw new Error('Invalid page runtime reference');
+                if (owner.pid !== undefined) {
+                    const identity = JSON.stringify([owner.pid, owner.processIdentity]);
+                    if (!liveness.has(identity))
+                        liveness.set(identity, isProcessOwnerAlive({ pid: owner.pid, processIdentity: owner.processIdentity }));
+                    if (!liveness.get(identity))
+                        delete references.owners[key];
+                }
+            }
+            const result = action(references);
+            const bytes = Buffer.from(JSON.stringify(references));
+            if (bytes.byteLength > 4 * 1024 * 1024)
+                throw new Error('Page runtime reference index exceeds 4 MiB');
+            this.write(this.index, bytes);
+            return result;
+        });
+    }
+    collect(references, requiredBytes = 0, requiredEntries = 0) {
+        const protectedDigests = new Set(Object.values(references.owners).flatMap(owner => owner.digests));
+        const files = readdirSync(this.root).filter(name => /^[a-f0-9]{64}\.cjs$/.test(name)).map(name => ({ file: join(this.root, name), digest: name.slice(0, 64), info: statSync(join(this.root, name)) }));
+        let total = files.reduce((sum, file) => sum + file.info.size, 0);
+        let entries = files.length;
+        for (const file of files.sort((a, b) => a.info.mtimeMs - b.info.mtimeMs)) {
+            if (protectedDigests.has(file.digest))
+                continue;
+            // Explicit release/reconciliation reclaims unreferenced objects; insertions evict as needed.
+            if (requiredBytes && total + requiredBytes <= this.quota && entries + requiredEntries <= 256)
+                break;
+            unlinkSync(file.file);
+            total -= file.info.size;
+            entries--;
+        }
+        if (total + requiredBytes > this.quota || entries + requiredEntries > 256)
+            throw new Error('Page runtime cache is full of active browser references');
+    }
+    read(file, maximum) {
+        const handle = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const stat = fstatSync(handle);
+            if (!stat.isFile() || stat.size > maximum)
+                throw new Error('Stored page runtime exceeds its limit');
+            const bytes = Buffer.alloc(maximum + 1);
+            let length = 0;
+            while (length < bytes.length) {
+                const count = readSync(handle, bytes, length, bytes.length - length, null);
+                if (!count)
+                    break;
+                length += count;
+            }
+            if (length > maximum)
+                throw new Error('Stored page runtime exceeds its limit');
+            return bytes.subarray(0, length);
+        }
+        finally {
+            closeSync(handle);
+        }
+    }
+    write(file, bytes) {
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(temporary, bytes, { mode: 0o600, flag: 'wx' });
+            renameSync(temporary, file);
+        }
+        finally {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* Atomic replacement consumed the temporary file. */ }
+        }
+    }
+    verify(binding, bytes) {
+        if (bytes.byteLength > MAX_PAGE_RUNTIME_BYTES || createHash('sha256').update(bytes).digest('hex') !== binding.sha256)
+            throw new Error('Page runtime integrity check failed');
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/daemon-core",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.7",
   "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",
@@ -13,6 +13,10 @@
     "./capabilities": {
       "types": "./dist/node-capabilities.d.ts",
       "import": "./dist/node-capabilities.js"
+    },
+    "./page-runtimes": {
+      "types": "./dist/page-runtimes.d.ts",
+      "import": "./dist/page-runtimes.js"
     }
   },
   "files": [
@@ -25,7 +29,7 @@
   ],
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
@@ -35,11 +39,11 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@mearl/preset": "3.0.0-beta.4"
+    "@mearl/preset": "3.0.0-beta.7"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/F-loat/mearl.git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
     "directory": "packages/daemon-core"
   },
   "scripts": {