@gobing-ai/ts-runtime 0.3.0 → 0.3.2

package/dist/fs.js

@@ -1,4 +1,5 @@
 import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { findProjectRoot } from './file-system-node.js';
 import { dirnamePath, getProcessCwd, joinPath, resolvePath } from './path.js';
 let fsPromisesModule = null;
 let fsModule = null;
@@ -10,6 +11,8 @@ function nodeFs() {
     fsModule ??= import('node:fs');
     return fsModule;
 }
+/** {@link FileSystem} backed by `node:fs/promises`. Lazy-loads the module to avoid top-level import cost. */
+/** @deprecated Use createNodeFileSystem() from './file-system-node.js' instead. */
 export class NodeFileSystem {
     async readFile(path) {
         const { readFile } = await nodeFsPromises();
@@ -78,6 +81,8 @@ export class NodeFileSystem {
         return new LazyNodeLogStream(path);
     }
 }
+/** {@link SyncFileSystem} backed by `node:fs` synchronous APIs. */
+/** @deprecated Use createNodeFileSystem() from './file-system-node.js' instead — its FileSystem interface has union return types, eliminating the need for a separate sync implementation. */
 export class NodeSyncFileSystem {
     readFile(path) {
         return readFileSync(path, 'utf-8');
@@ -149,6 +154,8 @@ class LazyNodeLogStream {
     }
 }
 const CLOUDFLARE_FS_ERROR = 'FileSystem is not available on Cloudflare Workers. Use D1, KV, or R2.';
+/** {@link FileSystem} stub for Cloudflare Workers — all file operations throw. Use D1, KV, or R2 instead. */
+/** @deprecated Use createCfFileSystem() from './file-system-cf.js' instead. */
 export class CloudflareFileSystem {
     async readFile(path) {
         throw unsupportedCloudflareFs('readFile', path);
@@ -191,6 +198,8 @@ function unsupportedCloudflareFs(operation, path) {
     return new Error(`CloudflareFileSystem.${operation} failed for "${path}": ${CLOUDFLARE_FS_ERROR}`);
 }
 let activeFileSystem = new NodeFileSystem();
+/** Swaps the active global file system, returning a restore function for the previous instance. */
+/** @deprecated Use RuntimeFactory.createFileSystem() or ctx.require('fileSystem') instead. The global swap is replaced by factory-based DI. */
 export function setFileSystem(fileSystem) {
     const previous = activeFileSystem;
     activeFileSystem = fileSystem;
@@ -198,38 +207,50 @@ export function setFileSystem(fileSystem) {
         activeFileSystem = previous;
     };
 }
+/** Returns the currently active global {@link FileSystem} instance. */
+/** @deprecated Use RuntimeFactory.createFileSystem() or ctx.require('fileSystem') instead. */
 export function getFs() {
     return activeFileSystem;
 }
+/** Creates parent directories for a file path before writing. */
 export async function ensureDirForFile(path, fs = getFs()) {
     await fs.mkdir(dirnamePath(path));
 }
+/** Synchronous variant of {@link ensureDirForFile}. */
+/** @deprecated The new createNodeFileSystem() handles parent-directory creation internally. */
 export function ensureDirForFileSync(path, fs) {
     fs.mkdir(dirnamePath(path));
 }
+/** Atomically writes a file by writing to a temp path then renaming, avoiding partial writes on crash. */
 export async function atomicWriteFile(path, content, fs = getFs()) {
     await ensureDirForFile(path, fs);
     const tempPath = `${path}.${getProcessPid()}.${uniqueToken()}.tmp`;
     await fs.writeFile(tempPath, content);
     await fs.rename(tempPath, path);
 }
+/** Atomically writes a value as JSON with trailing newline. */
 export async function atomicWriteJson(path, value, fs = getFs()) {
     await atomicWriteFile(path, `${JSON.stringify(value, null, 2)}\n`, fs);
 }
+/** Reads and parses a JSON file. */
 export async function readJsonFile(path, fs = getFs()) {
     return JSON.parse(await fs.readFile(path));
 }
+/** Writes a value as JSON with 2-space indentation and trailing newline. */
 export async function writeJsonFile(path, value, fs = getFs()) {
     await fs.writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
 }
-export async function walkDir(path, fs = getFs()) {
+/** Recursively walks a directory, returning sorted paths to all files, optionally excluding entries by name. */
+export async function walkDir(path, fs = getFs(), exclude) {
     const entries = (await fs.readDir(path)).sort();
     const result = [];
     for (const entry of entries) {
+        if (exclude?.has(entry))
+            continue;
         const fullPath = joinPath(path, entry);
         const entryStat = await fs.stat(fullPath);
         if (entryStat?.isDirectory()) {
-            result.push(...(await walkDir(fullPath, fs)));
+            result.push(...(await walkDir(fullPath, fs, exclude)));
         }
         else if (entryStat?.isFile()) {
             result.push(fullPath);
@@ -237,31 +258,23 @@ export async function walkDir(path, fs = getFs()) {
     }
     return result;
 }
+/**
+ * Walks up from `startDir` looking for a `package.json` or `bun.lock` to locate the project root.
+ *
+ * @deprecated Use {@link import('./file-system-node.js').findProjectRoot} (or `createNodeFileSystem().getProjectRoot()`).
+ * This delegates to the single shared implementation.
+ */
 export function getProjectRoot(startDir = getProcessCwd()) {
-    let current = resolvePath(startDir);
-    for (let i = 0; i < 12; i++) {
-        if (hasBunFile(joinPath(current, 'bun.lock')) || hasBunFile(joinPath(current, 'package.json'))) {
-            return current;
-        }
-        const parent = dirnamePath(current);
-        if (parent === current)
-            return startDir;
-        current = parent;
-    }
-    return startDir;
+    return findProjectRoot(startDir);
 }
+/** Resolves path segments relative to the project root. */
 export function resolveProjectPath(...segments) {
     return resolvePath(getProjectRoot(), ...segments);
 }
+/** Creates a {@link LogStream} at the given path using the active file system. */
 export function createLogStream(path, fs = getFs()) {
     return fs.createLogStream(path);
 }
-function hasBunFile(path) {
-    const bun = globalThis.Bun;
-    if (bun === undefined)
-        return false;
-    return bun.file(path).size !== 0;
-}
 function getProcessPid() {
     return globalThis.process?.pid ?? 0;
 }

package/dist/index.d.ts

@@ -1,8 +1,27 @@
 export * from './config';
 export * from './context';
-export * from './fs';
+export { createRuntimeContextFromFactory } from './context';
+export type { FileStat, FileSystem } from './file-system';
+export { createCfFileSystem } from './file-system-cf';
+export { createNodeFileSystem, findProjectRoot } from './file-system-node';
+export { atomicWriteFile, atomicWriteJson, CloudflareFileSystem, createLogStream, ensureDirForFile, ensureDirForFileSync, type FileSystem as LegacyFileSystem, getFs, getProjectRoot, NodeFileSystem, NodeSyncFileSystem, readJsonFile, resolveProjectPath, type SyncFileSystem, setFileSystem, walkDir, writeJsonFile, } from './fs';
 export * from './path';
-export * from './process-executor';
+export { _resetRuntimeFactory, isCloudflareWorkerRuntime, loadRuntimeFactory } from './platform';
+export type { OutputPolicy, PipeProcess, PipeProcessOptions, ProcessEventDetail, ProcessEventSink, ProcessEvents, ProcessExecutorConfig, ProcessExitReason, ProcessOptions, ProcessResult, ProcessSignal, TracerPort, } from './process-executor';
+export { ProcessExecutor } from './process-executor';
+export { cloudflareWorkersFactory } from './runtime-cf';
+export type { RuntimeFactory } from './runtime-factory';
+export { _resetNodeFileSystem, nodeBunFactory } from './runtime-node-bun';
 export * from './schema-validation';
 export * from './types';
+export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor';
+/**
+ * @deprecated Use {@link ProcessExecutor} directly for async execution.
+ * Use `Bun.spawnSync` or `child_process.spawnSync` for sync.
+ */
+export type SyncProcessExecutor = InstanceType<typeof import('./process-executor').BunSyncProcessExecutor>;
+/**
+ * @deprecated Use {@link ProcessExecutor.runStreaming} instead.
+ */
+export type PipeProcessSpawner = InstanceType<typeof import('./process-executor').BunPipeProcessSpawner>;
 //# 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,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,MAAM,CAAC;AACrB,cAAc,QAAQ,CAAC;AACvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,UAAU,IAAI,gBAAgB,EACnC,KAAK,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,KAAK,cAAc,EACnB,aAAa,EACb,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAExG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/index.js

@@ -1,7 +1,15 @@
 export * from './config.js';
 export * from './context.js';
-export * from './fs.js';
+export { createRuntimeContextFromFactory } from './context.js';
+export { createCfFileSystem } from './file-system-cf.js';
+export { createNodeFileSystem, findProjectRoot } from './file-system-node.js';
+export { atomicWriteFile, atomicWriteJson, CloudflareFileSystem, createLogStream, ensureDirForFile, ensureDirForFileSync, getFs, getProjectRoot, NodeFileSystem, NodeSyncFileSystem, readJsonFile, resolveProjectPath, setFileSystem, walkDir, writeJsonFile, } from './fs.js';
 export * from './path.js';
-export * from './process-executor.js';
+export { _resetRuntimeFactory, isCloudflareWorkerRuntime, loadRuntimeFactory } from './platform.js';
+export { ProcessExecutor } from './process-executor.js';
+export { cloudflareWorkersFactory } from './runtime-cf.js';
+export { _resetNodeFileSystem, nodeBunFactory } from './runtime-node-bun.js';
 export * from './schema-validation.js';
 export * from './types.js';
+// ── Deprecated re-exports (backward compatibility) ──────────────────────
+export { BunPipeProcessSpawner, BunSyncProcessExecutor, NodeProcessExecutor } from './process-executor.js';

package/dist/path.d.ts

@@ -1,7 +1,19 @@
+/** Replaces Windows backslashes with forward slashes for consistent POSIX-style path handling. */
 export declare function normalizeSeparators(path: string): string;
+/** Platform-specific path segment separator (`'/'` on POSIX, `'\\'` on Windows). */
+export declare const SEP: string;
+/** Returns `true` for POSIX absolute paths and Windows drive paths (`C:/…`). */
 export declare function isAbsolutePath(path: string): boolean;
+/** Returns the parent directory of a path. Platform-independent — avoids `node:path`. */
 export declare function dirnamePath(path: string): string;
+/** Return the last segment of a path. Optionally strip a trailing extension. */
+export declare function basenamePath(p: string, ext?: string): string;
+/** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
+export declare function relativePath(from: string, to: string): string;
+/** Joins path segments with `/`, normalizing separators and collapsing redundant slashes. */
 export declare function joinPath(...segments: string[]): string;
+/** Resolves a sequence of path segments to an absolute path, collapsing `..` and `.`. */
 export declare function resolvePath(...segments: string[]): string;
+/** Returns `process.cwd()` if available, or `/` as fallback (Cloudflare Workers). */
 export declare function getProcessCwd(): string;
 //# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAIA,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAShD;AAED,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAMtD;AAED,wBAAgB,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAkBzD;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAIA,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,eAAO,MAAM,GAAG,EAAE,MACgF,CAAC;AAEnG,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAmBD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAkB7D;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAMtD;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBzD;AAED,qFAAqF;AACrF,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/path.js

@@ -1,14 +1,37 @@
 // Runtime-portable path math. Deliberately avoids `node:path` so the same logic works on
 // `cloudflare-workers` (no `node:*`) as on node-bun (ADR-008). POSIX-style separators throughout;
 // Windows drive paths (`C:/...`) are normalized and treated as absolute.
+/** Replaces Windows backslashes with forward slashes for consistent POSIX-style path handling. */
 export function normalizeSeparators(path) {
     return path.replaceAll('\\', '/');
 }
+/** Platform-specific path segment separator (`'/'` on POSIX, `'\\'` on Windows). */
+export const SEP = globalThis.process?.platform === 'win32' ? '\\' : '/';
+/** Returns `true` for POSIX absolute paths and Windows drive paths (`C:/…`). */
 export function isAbsolutePath(path) {
     return path.startsWith('/') || /^[A-Za-z]:\//.test(normalizeSeparators(path));
 }
+function splitRoot(path) {
+    const normalized = normalizeSeparators(path);
+    const drive = normalized.match(/^([A-Za-z]:)(?:\/|$)/);
+    if (drive) {
+        return { root: drive[1] ?? '', rest: normalized.slice((drive[1] ?? '').length).replace(/^\/+/, '') };
+    }
+    if (normalized.startsWith('/')) {
+        return { root: '/', rest: normalized.replace(/^\/+/, '') };
+    }
+    return { root: '', rest: normalized };
+}
+function pathParts(path) {
+    const { root, rest } = splitRoot(path);
+    return { root, parts: rest.split('/').filter(Boolean) };
+}
+/** Returns the parent directory of a path. Platform-independent — avoids `node:path`. */
 export function dirnamePath(path) {
     const input = normalizeSeparators(path);
+    const { root } = splitRoot(input);
+    if (root !== '' && input.replace(/\/+$/, '') === root)
+        return root === '/' ? '/' : `${root}/`;
     if (/^\/+$/.test(input))
         return '/';
     const normalized = input.replace(/\/+$/, '');
@@ -21,6 +44,36 @@ export function dirnamePath(path) {
         return '/';
     return normalized.slice(0, index);
 }
+/** Return the last segment of a path. Optionally strip a trailing extension. */
+export function basenamePath(p, ext) {
+    const normalized = normalizeSeparators(p).replace(/\/+$/, '');
+    const index = normalized.lastIndexOf('/');
+    let base = index < 0 ? normalized : normalized.slice(index + 1);
+    if (ext !== undefined && base !== ext && base.endsWith(ext)) {
+        base = base.slice(0, -ext.length);
+    }
+    return base;
+}
+/** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
+export function relativePath(from, to) {
+    const fromParsed = pathParts(resolvePath(from));
+    const toParsed = pathParts(resolvePath(to));
+    if (fromParsed.root.toLowerCase() !== toParsed.root.toLowerCase()) {
+        return resolvePath(to);
+    }
+    const fromParts = fromParsed.parts;
+    const toParts = toParsed.parts;
+    // Strip common prefix.
+    let i = 0;
+    const minLen = Math.min(fromParts.length, toParts.length);
+    while (i < minLen && fromParts[i] === toParts[i])
+        i++;
+    const up = fromParts.slice(i).map(() => '..');
+    const down = toParts.slice(i);
+    const result = [...up, ...down].join('/');
+    return result || '.';
+}
+/** Joins path segments with `/`, normalizing separators and collapsing redundant slashes. */
 export function joinPath(...segments) {
     const filtered = segments.filter((segment) => segment.length > 0).map(normalizeSeparators);
     if (filtered.length === 0)
@@ -29,6 +82,7 @@ export function joinPath(...segments) {
     const joined = filtered.join('/').replace(/\/+/g, '/');
     return absolute ? joined : joined.replace(/^\//, '');
 }
+/** Resolves a sequence of path segments to an absolute path, collapsing `..` and `.`. */
 export function resolvePath(...segments) {
     const candidates = segments.length === 0 ? [getProcessCwd()] : segments;
     let resolved = '';
@@ -37,19 +91,26 @@ export function resolvePath(...segments) {
             continue;
         resolved = isAbsolutePath(segment) ? segment : joinPath(resolved || getProcessCwd(), segment);
     }
+    const { root, rest } = splitRoot(resolved);
     const parts = [];
-    const absolute = isAbsolutePath(resolved);
-    for (const part of resolved.split('/')) {
+    const absolute = root !== '';
+    for (const part of rest.split('/')) {
         if (part === '' || part === '.')
             continue;
         if (part === '..') {
-            parts.pop();
+            if (parts.length > 0)
+                parts.pop();
             continue;
         }
         parts.push(part);
     }
-    return `${absolute ? '/' : ''}${parts.join('/')}` || (absolute ? '/' : '.');
+    if (!absolute)
+        return parts.join('/') || '.';
+    if (root === '/')
+        return `/${parts.join('/')}` || '/';
+    return parts.length > 0 ? `${root}/${parts.join('/')}` : `${root}/`;
 }
+/** Returns `process.cwd()` if available, or `/` as fallback (Cloudflare Workers). */
 export function getProcessCwd() {
     return globalThis.process?.cwd?.() ?? '/';
 }

package/dist/platform.d.ts

@@ -0,0 +1,12 @@
+import type { RuntimeFactory } from './runtime-factory';
+/** True when running in a Cloudflare Worker (server-tier only). */
+export declare function isCloudflareWorkerRuntime(): boolean;
+/**
+ * Lazy-load and cache the appropriate {@link RuntimeFactory} based on environment detection.
+ */
+export declare function loadRuntimeFactory(): Promise<RuntimeFactory>;
+/**
+ * Reset the cached runtime factory and name (for test isolation).
+ */
+export declare function _resetRuntimeFactory(): void;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAQxD,mEAAmE;AACnE,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAKD;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,cAAc,CAAC,CAalE;AAQD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C"}

package/dist/platform.js

@@ -0,0 +1,41 @@
+// Single authoritative source for runtime detection.
+// All other code MUST consume RuntimeFactory via loadRuntimeFactory().
+// Probe-once contract: each primitive is invoked at most once per process and
+// the result is cached in `_factory` / `_runtimeName`.
+/** True when running in a Cloudflare Worker (server-tier only). */
+export function isCloudflareWorkerRuntime() {
+    return globalThis.navigator?.userAgent?.startsWith('Cloudflare-Workers') ?? false;
+}
+let _factory;
+let _runtimeName;
+/**
+ * Lazy-load and cache the appropriate {@link RuntimeFactory} based on environment detection.
+ */
+export async function loadRuntimeFactory() {
+    if (_factory)
+        return _factory;
+    let factory;
+    if (getRuntimeName() === 'cloudflare-workers') {
+        const { cloudflareWorkersFactory } = await import('./runtime-cf.js');
+        factory = cloudflareWorkersFactory;
+    }
+    else {
+        const { nodeBunFactory } = await import('./runtime-node-bun.js');
+        factory = nodeBunFactory;
+    }
+    _factory = factory;
+    return factory;
+}
+function getRuntimeName() {
+    if (_runtimeName)
+        return _runtimeName;
+    _runtimeName = isCloudflareWorkerRuntime() ? 'cloudflare-workers' : 'node-bun';
+    return _runtimeName;
+}
+/**
+ * Reset the cached runtime factory and name (for test isolation).
+ */
+export function _resetRuntimeFactory() {
+    _factory = undefined;
+    _runtimeName = undefined;
+}

package/dist/plugin/capability-registry.d.ts

@@ -0,0 +1,35 @@
+/** Registry origin for a host capability. */
+export type CapabilityOrigin = 'builtin' | 'extension';
+/** Registry entry metadata. */
+export interface CapabilityEntry<TCapability> {
+    /** Capability implementation. */
+    capability: TCapability;
+    /** Registration origin. */
+    origin: CapabilityOrigin;
+}
+/**
+ * Generic, domain-agnostic capability registry shared by engine hosts.
+ *
+ * Stores named capabilities of an opaque type `TCapability` with replace-by-name
+ * semantics and `origin` metadata. It knows nothing about what a capability *is* —
+ * each engine supplies its own type and owns its own error types and override
+ * semantics (the registry only reports what it stores).
+ */
+export declare class CapabilityRegistry<TCapability> {
+    private readonly kind;
+    private readonly capabilities;
+    constructor(kind: string);
+    /** Register or replace a capability. */
+    register(name: string, capability: TCapability, origin?: CapabilityOrigin): void;
+    /** Return true when a capability exists. */
+    has(name: string): boolean;
+    /** Get a registered capability or throw a clear error. */
+    get(name: string): TCapability;
+    /** Get a registered entry (capability plus origin) without throwing. */
+    getEntry(name: string): CapabilityEntry<TCapability> | undefined;
+    /** List registered capability names in insertion order. */
+    list(): string[];
+    /** List registered entries (name + capability + origin) in insertion order. */
+    entries(): Array<readonly [string, CapabilityEntry<TCapability>]>;
+}
+//# sourceMappingURL=capability-registry.d.ts.map

package/dist/plugin/capability-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../src/plugin/capability-registry.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAEvD,+BAA+B;AAC/B,MAAM,WAAW,eAAe,CAAC,WAAW;IACxC,iCAAiC;IACjC,UAAU,EAAE,WAAW,CAAC;IACxB,2BAA2B;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB,CAAC,WAAW;IAG3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmD;gBAEnD,IAAI,EAAE,MAAM;IAEzC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAE,gBAA8B,GAAG,IAAI;IAI7F,4CAA4C;IAC5C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,0DAA0D;IAC1D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAQ9B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC,GAAG,SAAS;IAIhE,2DAA2D;IAC3D,IAAI,IAAI,MAAM,EAAE;IAIhB,+EAA+E;IAC/E,OAAO,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC;CAGpE"}

package/dist/plugin/capability-registry.js

@@ -0,0 +1,43 @@
+/**
+ * Generic, domain-agnostic capability registry shared by engine hosts.
+ *
+ * Stores named capabilities of an opaque type `TCapability` with replace-by-name
+ * semantics and `origin` metadata. It knows nothing about what a capability *is* —
+ * each engine supplies its own type and owns its own error types and override
+ * semantics (the registry only reports what it stores).
+ */
+export class CapabilityRegistry {
+    kind;
+    capabilities = new Map();
+    constructor(kind) {
+        this.kind = kind;
+    }
+    /** Register or replace a capability. */
+    register(name, capability, origin = 'extension') {
+        this.capabilities.set(name, { capability, origin });
+    }
+    /** Return true when a capability exists. */
+    has(name) {
+        return this.capabilities.has(name);
+    }
+    /** Get a registered capability or throw a clear error. */
+    get(name) {
+        const entry = this.capabilities.get(name);
+        if (entry === undefined) {
+            throw new Error(`Unknown ${this.kind}: ${name}`);
+        }
+        return entry.capability;
+    }
+    /** Get a registered entry (capability plus origin) without throwing. */
+    getEntry(name) {
+        return this.capabilities.get(name);
+    }
+    /** List registered capability names in insertion order. */
+    list() {
+        return [...this.capabilities.keys()];
+    }
+    /** List registered entries (name + capability + origin) in insertion order. */
+    entries() {
+        return [...this.capabilities.entries()];
+    }
+}

package/dist/plugin/extension-loader.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A single extension module reference.
+ *
+ * `kind` is an engine-defined tag the registration callback uses to route the
+ * module to the right registry — the loader itself never interprets it. `path` is
+ * the relative path as authored; the loader **derives** the import target by
+ * resolving `path` against `baseDir` *after* validating it, so the trust guard
+ * always governs the actual module that gets imported. `sourceName` identifies the
+ * declaring config for diagnostics.
+ */
+export interface ExtensionRef<TExtensionKind extends string = string> {
+    /** Engine-defined capability tag, used only by the registration callback. */
+    readonly kind: TExtensionKind;
+    /** Relative path as authored, enforced by {@link assertRelativeExtensionPath}. */
+    readonly path: string;
+    /** Absolute directory the authored `path` is resolved against. */
+    readonly baseDir: string;
+    /** Name of the config (preset, workflow, …) that declared this ref. */
+    readonly sourceName: string;
+}
+/** Options controlling extension-module loading. */
+export interface LoadExtensionsOptions {
+    /**
+     * Whether to actually import extension modules. Defaults to `false`: loading
+     * arbitrary code is a trust decision the caller must make explicitly. When refs
+     * exist and this is not `true`, loading throws **before any import**.
+     */
+    readonly allowExtensions?: boolean;
+    /** Optional sink for non-fatal warnings (e.g. capability overrides). */
+    readonly logger?: {
+        warn: (message: string) => void;
+    };
+    /**
+     * Required module loader. The generic core never performs a dynamic `import`
+     * itself — the embedder supplies the import policy (typically
+     * `(absPath) => import(absPath)`), and tests pass a stub. Keeping this explicit
+     * means the shared core has no ambient code-loading capability of its own.
+     */
+    readonly moduleLoader: (absPath: string) => Promise<Record<string, unknown>>;
+}
+/** A validated extension module export: an object carrying at least a string `name`. */
+export interface LoadedExtension {
+    /** Stable name of the contributed capability bundle. */
+    readonly name: string;
+    /** Engine-specific contribution payload (actions, evaluators, …). */
+    readonly [key: string]: unknown;
+}
+/**
+ * Import each extension module behind an explicit trust gate, validate its export,
+ * then hand it to an engine-provided registration callback.
+ *
+ * The loader is domain-agnostic: it does not know which registry a module belongs to.
+ * It enforces the trust boundary (gate + relative-path guard), validates the
+ * default/named-`extension` export shape, and delegates routing to `register`.
+ *
+ * Security invariants:
+ * - No refs → no-op.
+ * - Refs present but `allowExtensions !== true` → throws **before** any `import` or
+ *   `moduleLoader` call, so a declared extension is never silently dropped.
+ * - Every ref's authored path is re-validated by {@link assertRelativeExtensionPath}.
+ *
+ * @throws When extensions are present but `allowExtensions` is not `true`, when a path
+ *   fails the trust guard, or when a module lacks a valid `name`.
+ */
+export declare function loadExtensionModules<TExtensionKind extends string>(refs: readonly ExtensionRef<TExtensionKind>[], options: LoadExtensionsOptions, register: (ref: ExtensionRef<TExtensionKind>, extension: LoadedExtension) => void | Promise<void>): Promise<void>;
+//# sourceMappingURL=extension-loader.d.ts.map

package/dist/plugin/extension-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-loader.d.ts","sourceRoot":"","sources":["../../src/plugin/extension-loader.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY,CAAC,cAAc,SAAS,MAAM,GAAG,MAAM;IAChE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACtD;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChF;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CAAC,cAAc,SAAS,MAAM,EACpE,IAAI,EAAE,SAAS,YAAY,CAAC,cAAc,CAAC,EAAE,EAC7C,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,CAAC,GAAG,EAAE,YAAY,CAAC,cAAc,CAAC,EAAE,SAAS,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAClG,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/plugin/extension-loader.js

@@ -0,0 +1,47 @@
+import { isAbsolute, resolve } from 'node:path';
+import { assertRelativeExtensionPath } from './extension-path.js';
+/**
+ * Import each extension module behind an explicit trust gate, validate its export,
+ * then hand it to an engine-provided registration callback.
+ *
+ * The loader is domain-agnostic: it does not know which registry a module belongs to.
+ * It enforces the trust boundary (gate + relative-path guard), validates the
+ * default/named-`extension` export shape, and delegates routing to `register`.
+ *
+ * Security invariants:
+ * - No refs → no-op.
+ * - Refs present but `allowExtensions !== true` → throws **before** any `import` or
+ *   `moduleLoader` call, so a declared extension is never silently dropped.
+ * - Every ref's authored path is re-validated by {@link assertRelativeExtensionPath}.
+ *
+ * @throws When extensions are present but `allowExtensions` is not `true`, when a path
+ *   fails the trust guard, or when a module lacks a valid `name`.
+ */
+export async function loadExtensionModules(refs, options, register) {
+    if (refs.length === 0)
+        return;
+    // Fail closed before importing anything: a declared extension under a disabled gate
+    // is a hard error, never a silent drop.
+    if (options.allowExtensions !== true) {
+        const first = refs[0];
+        throw new Error(`"${first.sourceName}" declares ${first.kind} extension "${first.path}", but extensions are disabled — pass allowExtensions: true to load extension modules`);
+    }
+    for (const ref of refs) {
+        if (!isAbsolute(ref.baseDir)) {
+            throw new Error(`"${ref.sourceName}" extension baseDir "${ref.baseDir}" must be an absolute directory`);
+        }
+        // Validate the authored path, then derive the import target from it so the
+        // trust guard always governs the module actually imported — the loader never
+        // imports a caller-supplied absolute path it did not resolve itself.
+        assertRelativeExtensionPath(ref.path, { sourceName: ref.sourceName });
+        const absPath = resolve(ref.baseDir, ref.path);
+        const moduleExports = await options.moduleLoader(absPath);
+        const candidate = moduleExports.default ?? moduleExports.extension;
+        if (candidate === null ||
+            typeof candidate !== 'object' ||
+            typeof candidate.name !== 'string') {
+            throw new Error(`"${ref.sourceName}" extension "${ref.path}" must export an object with a string "name"`);
+        }
+        await register(ref, candidate);
+    }
+}

package/dist/plugin/extension-path.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Assert that an extension module path is relative and does not escape its
+ * declaring directory.
+ *
+ * Extension declarations are data, and a path that is absolute or escapes via `..`
+ * is a trust-boundary violation even when extension loading is explicitly allowed.
+ * This is a standalone validator (not a schema refinement) so the loader can enforce
+ * it at load time, independent of any engine's config schema — defense in depth.
+ *
+ * @throws When the path is absolute or contains a `..` traversal segment.
+ */
+export declare function assertRelativeExtensionPath(path: string, options?: {
+    sourceName?: string;
+}): void;
+//# sourceMappingURL=extension-path.d.ts.map

package/dist/plugin/extension-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-path.d.ts","sourceRoot":"","sources":["../../src/plugin/extension-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAQrG"}

package/dist/plugin/extension-path.js

@@ -0,0 +1,20 @@
+/**
+ * Assert that an extension module path is relative and does not escape its
+ * declaring directory.
+ *
+ * Extension declarations are data, and a path that is absolute or escapes via `..`
+ * is a trust-boundary violation even when extension loading is explicitly allowed.
+ * This is a standalone validator (not a schema refinement) so the loader can enforce
+ * it at load time, independent of any engine's config schema — defense in depth.
+ *
+ * @throws When the path is absolute or contains a `..` traversal segment.
+ */
+export function assertRelativeExtensionPath(path, options = {}) {
+    const where = options.sourceName !== undefined ? ` declared by "${options.sourceName}"` : '';
+    if (/^([/\\]|[A-Za-z]:[/\\])/.test(path)) {
+        throw new Error(`extension path "${path}"${where} must be relative (no absolute paths)`);
+    }
+    if (path.split(/[/\\]/).includes('..')) {
+        throw new Error(`extension path "${path}"${where} must not contain ".." traversal`);
+    }
+}

package/dist/plugin/index.d.ts

@@ -0,0 +1,4 @@
+export * from './capability-registry';
+export * from './extension-loader';
+export * from './extension-path';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugin/index.d.ts.map

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