@gobing-ai/ts-runtime 0.3.1 → 0.3.3

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/process-executor.d.ts

@@ -1,31 +1,31 @@
+/** Controls how stdout/stderr is captured: buffered in memory or streamed to the caller's terminal. */
 export type OutputPolicy = {
     mode: 'buffered';
 } | {
     mode: 'stream';
     isTTY?: boolean;
 };
+/** Shared configuration for a process executor (default timeout, output buffering, output policy). */
 export interface ProcessExecutorConfig {
     defaultTimeout?: number;
     defaultMaxOutput?: number;
     output?: OutputPolicy;
+    events?: ProcessEventSink;
+    tracer?: TracerPort;
 }
+/** Options for spawning a child process. */
 export interface ProcessOptions {
     command: string;
     args?: string[];
     cwd?: string;
-    /**
-     * Environment forwarded verbatim to the child process. Caller-controlled — when launching an
-     * untrusted command, pass an explicit allowlist rather than the parent's full environment, so
-     * inherited secrets are not leaked into the subprocess.
-     */
     env?: Record<string, string>;
     timeout?: number;
-    /** Maximum output buffer size in bytes (maps to execa `maxBuffer`). */
     maxOutput?: number;
     label?: string;
     rejectOnError?: boolean;
     forceBuffered?: boolean;
 }
+/** Result of a completed child process, including exit code, captured output, and duration. */
 export interface ProcessResult {
     command: string;
     args: string[];
@@ -35,19 +35,46 @@ export interface ProcessResult {
     signal?: string;
     durationMs: number;
 }
-export interface ProcessExecutor {
-    run(options: ProcessOptions): Promise<ProcessResult>;
+/** Reason a process completion event was emitted. */
+export type ProcessExitReason = 'exit' | 'signal' | 'timeout' | 'error';
+/** Payload emitted for process execution observability. */
+export interface ProcessEventDetail {
+    command: string;
+    args: string[];
+    exitCode: number | null;
+    signal?: string;
+    durationMs: number;
+    reason: ProcessExitReason;
+    timestamp: string;
+    label?: string;
+    error?: string;
 }
-export interface SyncProcessExecutor {
-    runSync(options: Omit<ProcessOptions, 'timeout'>): ProcessResult;
+/** Zero-dependency structural event sink for process observability. */
+export interface ProcessEventSink {
+    emit(event: 'process.started' | 'process.exited', detail: ProcessEventDetail): void;
+}
+/** Typed process event map, consumable by `EventBus<ProcessEvents>` in higher layers. */
+export type ProcessEvents = {
+    'process.started': (detail: ProcessEventDetail) => void;
+    'process.exited': (detail: ProcessEventDetail) => void;
+};
+/** Minimal structural tracing port; concrete adapters live above `ts-runtime`. */
+export interface TracerPort {
+    traceAsync<T>(name: string, fn: (span: unknown) => Promise<T>): Promise<T>;
 }
+/** Options for spawning a long-running interactive process. */
 export interface PipeProcessOptions {
     command: string;
     args?: string[];
     cwd?: string;
-    /** Forwarded verbatim to the child — pass an allowlist for untrusted commands (see {@link ProcessOptions.env}). */
     env?: Record<string, string>;
+    label?: string;
 }
+/** Signal values accepted by subprocess kill. */
+type BunSubprocess = ReturnType<typeof Bun.spawn>;
+/** Signal values accepted by subprocess kill (e.g. 'SIGTERM', 'SIGKILL'). */
+export type ProcessSignal = Parameters<BunSubprocess['kill']>[0];
+/** Handle to a running pipe process with streaming stdout/stderr and stdin write support. */
 export interface PipeProcess {
     readonly pid: number | null;
     readonly stdout: ReadableStream<Uint8Array> | null;
@@ -57,21 +84,52 @@ export interface PipeProcess {
     endStdin(): void;
     kill(signal?: ProcessSignal): void;
 }
-export interface PipeProcessSpawner {
-    spawn(options: PipeProcessOptions): PipeProcess;
-}
-export declare class NodeProcessExecutor implements ProcessExecutor {
+/**
+ * Runtime-agnostic process executor wrapping `execa`.
+ *
+ * Every invocation supports timeout enforcement, output capture, and
+ * configurable output policy (buffered vs streamed).
+ */
+export declare class ProcessExecutor {
     private readonly config;
     constructor(config?: ProcessExecutorConfig);
+    /**
+     * Run a command, buffered by default. Returns a structured {@link ProcessResult}.
+     * Does NOT throw on non-zero exit codes unless `rejectOnError` is set.
+     */
     run(options: ProcessOptions): Promise<ProcessResult>;
+    private runUntraced;
+    /**
+     * Spawn a long-running interactive process with streaming I/O.
+     *
+     * Uses `Bun.spawn` for bidirectional pipe communication (stdin write,
+     * stdout/stderr as ReadableStreams). Returns a {@link PipeProcess} handle.
+     */
+    runStreaming(options: PipeProcessOptions): PipeProcess;
+    private trace;
+    private emitExitedFromResult;
+    private emitProcessEvent;
 }
-export declare class BunSyncProcessExecutor implements SyncProcessExecutor {
+/**
+ * @deprecated Use {@link ProcessExecutor} directly.
+ * This subclass is kept for backward compatibility.
+ */
+export declare class NodeProcessExecutor extends ProcessExecutor {
+}
+/**
+ * @deprecated Use `Bun.spawnSync` or `child_process.spawnSync` directly.
+ * Synchronous process execution is no longer recommended from ts-runtime.
+ * This class is kept for backward compatibility.
+ */
+export declare class BunSyncProcessExecutor {
     runSync(options: Omit<ProcessOptions, 'timeout'>): ProcessResult;
 }
-export declare class BunPipeProcessSpawner implements PipeProcessSpawner {
+/**
+ * @deprecated Use {@link ProcessExecutor.runStreaming} instead.
+ * This class is kept for backward compatibility.
+ */
+export declare class BunPipeProcessSpawner {
     spawn(options: PipeProcessOptions): PipeProcess;
 }
-type BunSubprocess = ReturnType<typeof Bun.spawn>;
-type ProcessSignal = Parameters<BunSubprocess['kill']>[0];
 export {};
 //# sourceMappingURL=process-executor.d.ts.map

package/dist/process-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-executor.d.ts","sourceRoot":"","sources":["../src/process-executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"process-executor.d.ts","sourceRoot":"","sources":["../src/process-executor.ts"],"names":[],"mappings":"AAKA,uGAAuG;AACvG,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtF,sGAAsG;AACtG,MAAM,WAAW,qBAAqB;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;CACvB;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAExE,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC7B,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,gBAAgB,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACvF;AAED,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG;IACxB,iBAAiB,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACxD,gBAAgB,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC1D,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACvB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9E;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,iDAAiD;AACjD,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AAElD,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjE,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAC7C,QAAQ,IAAI,IAAI,CAAC;IACjB,IAAI,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CACtC;AAID;;;;;GAKG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;gBAEnC,MAAM,GAAE,qBAA0B;IAI9C;;;OAGG;IACG,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;YAI5C,WAAW;IAiEzB;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW;YA2CxC,KAAK;IAKnB,OAAO,CAAC,oBAAoB;IA0B5B,OAAO,CAAC,gBAAgB;CAG3B;AAyGD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;CAAG;AAE3D;;;;GAIG;AACH,qBAAa,sBAAsB;IAC/B,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,aAAa;CA2BnE;AAED;;;GAGG;AACH,qBAAa,qBAAqB;IAC9B,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW;CAWlD"}