@gobing-ai/ts-runtime 0.3.1 → 0.3.3

package/src/config.ts

@@ -2,6 +2,7 @@ import { deepMerge } from '@gobing-ai/ts-utils';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { type ZodIssue, z } from 'zod';
 
+/** Zod schema for the application configuration object, providing defaults for app, database, and logging sections. */
 export const configSchema = z.object({
     app: z
         .object({
@@ -26,6 +27,7 @@ export const configSchema = z.object({
         .default({ level: 'info', console: true, file: false, json: false }),
 });
 
+/** Inferred TypeScript type of a validated configuration object, derived from {@link configSchema}. */
 export type Config = z.output<typeof configSchema>;
 
 const ENV_INTERPOLATION_RE = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
@@ -64,6 +66,7 @@ export function stringifyYamlObject(value: Record<string, unknown>): string {
     return stringifyYaml(value);
 }
 
+/** Error thrown when configuration validation fails, carrying the Zod validation issues for diagnostics. */
 export class ConfigLoadError extends Error {
     readonly issues: ZodIssue[];
 
@@ -77,27 +80,36 @@ export class ConfigLoadError extends Error {
 // These accessors read `process.env` directly and are node-bun only (ADR-008). On
 // `cloudflare-workers` there is no `process`; inject config explicitly rather than calling these.
 
+/** Returns the value of `process.env.NODE_ENV`, or `"development"` as default. Node/Bun only. */
 export function getNodeEnv(): string {
     return process.env.NODE_ENV ?? 'development';
 }
-
+/** Returns `true` when `NODE_ENV` is `"test"`. Node/Bun only. */
 export function isTestEnv(): boolean {
     return getNodeEnv() === 'test';
 }
 
+/** Returns `process.env` as a plain object. Node/Bun only. */
 export function getProcessEnv(): Record<string, string | undefined> {
     return process.env;
 }
 
+/** Returns `process.env.DATABASE_URL`, or `undefined` if not set. Node/Bun only. */
 export function getDatabaseUrl(): string | undefined {
     return process.env.DATABASE_URL;
 }
 
+/** Returns the user's home directory (`HOME`, falling back to `USERPROFILE` on Windows), or `undefined` if unset. Node/Bun only. */
+export function getHomeDir(): string | undefined {
+    return process.env.HOME ?? process.env.USERPROFILE;
+}
+
 /** Node-bun only: interpolates `${VAR}` from `process.env` (see note above). */
 export function interpolateEnv(value: string): string {
     return value.replace(ENV_INTERPOLATION_RE, (_match, name: string) => process.env[name] ?? `\${${name}}`);
 }
 
+/** Recursively interpolates `${VAR}` environment variables in all string leaves of a nested object or array. Node/Bun only. */
 export function interpolateTree(value: unknown): unknown {
     if (typeof value === 'string') return interpolateEnv(value);
     if (Array.isArray(value)) return value.map(interpolateTree);
@@ -106,7 +118,7 @@ export function interpolateTree(value: unknown): unknown {
     }
     return value;
 }
-
+/** Interpolates env vars, merges overrides, validates against {@link configSchema}, and returns a frozen {@link Config}. */
 export function buildConfigFromObject(
     raw: Record<string, unknown>,
     options: { overrides?: Partial<Config> } = {},
@@ -121,7 +133,7 @@ export function buildConfigFromObject(
     }
     return deepFreeze(result.data);
 }
-
+/** Parses a YAML configuration string into a raw object, throwing {@link ConfigLoadError} on failure. */
 export function parseConfigYaml(yamlText: string): Record<string, unknown> {
     try {
         return parseYamlObject(yamlText);
@@ -130,7 +142,7 @@ export function parseConfigYaml(yamlText: string): Record<string, unknown> {
         throw new ConfigLoadError(`Config YAML parsing failed: ${(error as Error).message}`);
     }
 }
-
+/** Parses YAML text and builds a validated {@link Config}, equivalent to `buildConfigFromObject(parseConfigYaml(…))`. */
 export function buildConfigFromYaml(yamlText: string, options: { overrides?: Partial<Config> } = {}): Config {
     return buildConfigFromObject(parseConfigYaml(yamlText), options);
 }

package/src/context.ts

@@ -1,17 +1,23 @@
 import type { Config } from './config';
 import { buildConfigFromObject } from './config';
-import type { FileSystem } from './fs';
-import { getFs } from './fs';
+import type { FileSystem } from './file-system';
+import { createNodeFileSystem } from './file-system-node';
+import { loadRuntimeFactory } from './platform';
+import type { ProcessExecutor as ProcessExecutorService } from './process-executor';
+import { ProcessExecutor } from './process-executor';
 import type { RuntimeCapabilities, RuntimeName } from './types';
-
+/** Execution scope of a runtime context — determines service lifecycle and availability. */
 export type RuntimeScope = 'process' | 'server-request' | 'scheduled-event' | 'test';
 
+/** Map of named services available to a runtime context, including the required `config` and `fileSystem`. */
 export interface RuntimeServiceMap {
     config: Config;
     fileSystem: FileSystem;
+    processExecutor?: ProcessExecutorService;
     [serviceName: string]: unknown;
 }
 
+/** Options for constructing a {@link RuntimeContext}. */
 export interface RuntimeContextOptions<TServices extends RuntimeServiceMap = RuntimeServiceMap> {
     scope?: RuntimeScope;
     runtimeName?: RuntimeName;
@@ -19,6 +25,7 @@ export interface RuntimeContextOptions<TServices extends RuntimeServiceMap = Run
     services?: Partial<TServices>;
 }
 
+/** Injectable service container scoped to a runtime environment (process, request, event, or test). */
 export class RuntimeContext<TServices extends RuntimeServiceMap = RuntimeServiceMap> {
     readonly scope: RuntimeScope;
     readonly runtimeName: RuntimeName;
@@ -37,7 +44,13 @@ export class RuntimeContext<TServices extends RuntimeServiceMap = RuntimeService
             } satisfies RuntimeCapabilities);
 
         this.register('config', (options.services?.config ?? buildConfigFromObject({})) as TServices['config']);
-        this.register('fileSystem', (options.services?.fileSystem ?? getFs()) as TServices['fileSystem']);
+        this.register(
+            'fileSystem',
+            (options.services?.fileSystem ?? createNodeFileSystem()) as TServices['fileSystem'],
+        );
+        if (this.capabilities.hasProcessExecution && options.services?.processExecutor === undefined) {
+            this.register('processExecutor', new ProcessExecutor() as TServices['processExecutor']);
+        }
 
         for (const [key, value] of Object.entries(options.services ?? {})) {
             if (value !== undefined) {
@@ -88,6 +101,47 @@ function isDisposable(value: unknown): value is { dispose(): void | Promise<void
     return typeof value === 'object' && value !== null && 'dispose' in value && typeof value.dispose === 'function';
 }
 
+/**
+ * Create a {@link RuntimeContext} wired to the auto-detected runtime factory.
+ *
+ * Loads the platform-specific factory via {@link loadRuntimeFactory},
+ * auto-wires FileSystem, ProcessExecutor, and Config, then returns a
+ * ready-to-use context. Call this at the entry point of any app or worker.
+ *
+ * @example
+ * ```ts
+ * const ctx = await createRuntimeContextFromFactory();
+ * const fs = ctx.require('fileSystem');
+ * const config = ctx.require('config');
+ * ```
+ */
+export async function createRuntimeContextFromFactory<TServices extends RuntimeServiceMap = RuntimeServiceMap>(
+    options?: RuntimeContextOptions<TServices>,
+): Promise<RuntimeContext<TServices>> {
+    const factory = await loadRuntimeFactory();
+    const config = await factory.loadConfig();
+    const fileSystem = factory.createFileSystem();
+    const processExecutor = factory.capabilities.hasProcessExecution ? factory.createProcessExecutor() : undefined;
+
+    return new RuntimeContext<TServices>({
+        scope: 'process',
+        runtimeName: factory.runtimeName,
+        capabilities: factory.capabilities,
+        services: {
+            config,
+            fileSystem,
+            ...(processExecutor !== undefined ? { processExecutor } : {}),
+            ...options?.services,
+        },
+    } as RuntimeContextOptions<TServices>);
+}
+
+/**
+ * @deprecated Use {@link createRuntimeContextFromFactory} instead —
+ * it auto-detects the platform and wires the correct services from the factory.
+ * This function is kept for backward compatibility with synchronous callers
+ * that manually configure services.
+ */
 export function createRuntimeContext<TServices extends RuntimeServiceMap = RuntimeServiceMap>(
     options: RuntimeContextOptions<TServices> = {},
 ): RuntimeContext<TServices> {

package/src/file-system-cf.ts

@@ -0,0 +1,74 @@
+/**
+ * Cloudflare Workers {@link FileSystem} stub.
+ *
+ * CF Workers have only an ephemeral, per-request virtual filesystem.
+ * Persistent file operations are not available. This stub throws clear
+ * errors directing developers to use D1, KV, or R2 instead.
+ *
+ * Non-mutating operations (`resolve`, `getProjectRoot`) return
+ * Worker-appropriate values without throwing.
+ *
+ * Note: Cloudflare Workers with `nodejs_compat` + `compatibility_date >= 2025-09-01`
+ * DO expose `node:fs` as an ephemeral, per-request virtual filesystem.
+ * We deliberately do NOT use it — the ephemeral nature means files written
+ * in one request silently vanish in the next. Throwing with guidance toward
+ * D1/KV/R2 is better DX than silent data loss.
+ */
+
+import type { FileSystem } from './file-system';
+
+const UNSUPPORTED = 'FileSystem is not available on Cloudflare Workers. Use D1, KV, or R2 for persistent storage.';
+
+/**
+ * Create a Cloudflare Workers {@link FileSystem} stub.
+ *
+ * `resolve()` and `getProjectRoot()` work as path utilities.
+ * All other methods throw with guidance toward CF-native storage.
+ */
+export function createCfFileSystem(): FileSystem {
+    return {
+        getProjectRoot: () => '/bundle',
+
+        resolve: (...segments: string[]) => {
+            const joined = segments.join('/').replaceAll(/\/+/g, '/');
+            return joined.startsWith('/') ? joined : `/${joined}`;
+        },
+
+        exists: (_path: string) => false,
+
+        readFile: (_path: string): never => {
+            throw new Error(`FileSystem.readFile: ${UNSUPPORTED}`);
+        },
+
+        writeFile: (_path: string, _content: string): never => {
+            throw new Error(`FileSystem.writeFile: ${UNSUPPORTED}`);
+        },
+
+        appendFile: (_path: string, _content: string): never => {
+            throw new Error(`FileSystem.appendFile: ${UNSUPPORTED}`);
+        },
+
+        ensureDir: (_path: string): void => {
+            // No-op: CF Workers virtual filesystem handles directory
+            // creation internally when files are written.
+        },
+
+        readDir: (_path: string): never => {
+            throw new Error(`FileSystem.readDir: ${UNSUPPORTED}`);
+        },
+
+        deleteFile: (_path: string): never => {
+            throw new Error(`FileSystem.deleteFile: ${UNSUPPORTED}`);
+        },
+
+        createWriteStream: (_path: string): never => {
+            throw new Error(`FileSystem.createWriteStream: ${UNSUPPORTED}`);
+        },
+
+        copy: (_src: string, _dest: string): never => {
+            throw new Error(`FileSystem.copy: ${UNSUPPORTED}`);
+        },
+
+        stat: (_path: string) => null,
+    };
+}

package/src/file-system-node.ts

@@ -0,0 +1,122 @@
+/**
+ * `node:fs`-backed {@link FileSystem} implementation for Bun/Node.js.
+ *
+ * This is the production implementation for local development, VPS, and
+ * any environment with a real filesystem. Tests should inject a virtual
+ * file system.
+ *
+ * The implementation uses `node:fs` sync APIs by default. Bun polyfills
+ * `node:fs` fully, so this works on both runtimes without a Bun-specific
+ * variant.
+ */
+
+import {
+    appendFileSync,
+    cpSync,
+    createWriteStream,
+    existsSync,
+    mkdirSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    statSync,
+    writeFileSync,
+} from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+
+import type { FileSystem } from './file-system';
+
+/**
+ * Create a {@link FileSystem} backed by `node:fs`.
+ *
+ * @param root - Project root directory (default: walks up from `process.cwd()` looking for `bun.lock` or `package.json`).
+ */
+export function createNodeFileSystem(root?: string): FileSystem {
+    const projectRoot = root ?? findProjectRoot(process.cwd());
+
+    return {
+        getProjectRoot: () => projectRoot,
+
+        resolve: (...segments: string[]) => resolvePath(projectRoot, ...segments),
+
+        exists: (path: string) => existsSync(path),
+
+        readFile: (path: string) => readFileSync(path, 'utf-8'),
+
+        writeFile: (path: string, content: string) => {
+            ensureParentDir(path);
+            writeFileSync(path, content, 'utf-8');
+        },
+
+        appendFile: (path: string, content: string) => {
+            ensureParentDir(path);
+            appendFileSync(path, content, 'utf-8');
+        },
+
+        ensureDir: (path: string) => {
+            mkdirSync(path, { recursive: true });
+        },
+
+        readDir: (path: string) => readdirSync(path),
+
+        deleteFile: (path: string) => {
+            rmSync(path, { recursive: true, force: true });
+        },
+
+        createWriteStream: (path: string) => {
+            ensureParentDir(path);
+            return createWriteStream(path, { flags: 'a' });
+        },
+
+        copy: (src: string, dest: string) => {
+            cpSync(src, dest, { recursive: true });
+        },
+
+        stat: (path: string) => {
+            try {
+                const s = statSync(path);
+                return {
+                    isFile: () => s.isFile(),
+                    isDirectory: () => s.isDirectory(),
+                    size: s.size,
+                    mtimeMs: s.mtimeMs,
+                };
+            } catch {
+                return null;
+            }
+        },
+    };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function ensureParentDir(filePath: string): void {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+
+/**
+ * Find the project root by walking up from `startDir` looking for a `bun.lock`
+ * or `package.json` marker. Uses `existsSync`, so it works on both Node and Bun.
+ *
+ * This is the single project-root discovery implementation; the deprecated
+ * {@link import('./fs').getProjectRoot} delegates here.
+ *
+ * @internal — exported for reuse by config loading.
+ */
+export function findProjectRoot(startDir: string): string {
+    let dir = resolvePath(startDir);
+    const root = resolvePath('/');
+    while (dir !== root) {
+        if (existsSync(resolvePath(dir, 'bun.lock')) || existsSync(resolvePath(dir, 'package.json'))) {
+            return dir;
+        }
+        const parent = resolvePath(dir, '..');
+        if (parent === dir) break;
+        dir = parent;
+    }
+    // Fallback: return the directory we started from.
+    return startDir;
+}

package/src/file-system.ts

@@ -0,0 +1,55 @@
+/** Portable file stat subset. */
+export interface FileStat {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    size: number;
+    mtimeMs: number;
+}
+
+/**
+ * Runtime-agnostic file system abstraction.
+ *
+ * Bun/Node backend uses `node:fs`. Cloudflare Workers backend provides stubs
+ * that throw clear "not available" errors, directing developers to use D1,
+ * KV, or R2 for persistent storage.
+ *
+ * All code outside `packages/runtime/src/file-system*.ts` MUST use this
+ * interface — never import `node:fs` or call `Bun.write`/`Bun.file` directly.
+ */
+export interface FileSystem {
+    /** Check whether a path exists. */
+    exists(path: string): boolean | Promise<boolean>;
+
+    /** Read file contents as UTF-8 string. Throws if not found. */
+    readFile(path: string): string | Promise<string>;
+
+    /** Write file contents, creating parent directories as needed. */
+    writeFile(path: string, content: string): void | Promise<void>;
+
+    /** Append content to a file, creating it if it doesn't exist. */
+    appendFile(path: string, content: string): void | Promise<void>;
+
+    /** Ensure a directory exists, creating it (and parents) recursively if needed. */
+    ensureDir(path: string): void | Promise<void>;
+
+    /** List directory entries (names only, not full paths). */
+    readDir(path: string): string[] | Promise<string[]>;
+
+    /** Delete a file or directory recursively. */
+    deleteFile(path: string): void | Promise<void>;
+
+    /** Recursively copy a file or directory. */
+    copy(src: string, dest: string): void | Promise<void>;
+
+    /** Get file or directory stats. Returns `null` if the path doesn't exist. */
+    stat(path: string): FileStat | null | Promise<FileStat | null>;
+
+    /** Create a writable stream for append-only output (Node/Bun only). Throws on CF Workers. */
+    createWriteStream(path: string): { write(chunk: string): void; end(): void };
+
+    /** Resolve path segments relative to the project root. */
+    resolve(...segments: string[]): string;
+
+    /** Get the project root directory path. */
+    getProjectRoot(): string;
+}

package/src/fs.ts

@@ -1,6 +1,8 @@
 import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { findProjectRoot } from './file-system-node';
 import { dirnamePath, getProcessCwd, joinPath, resolvePath } from './path';
 
+/** Portable file stat interface — mirrors the subset of `node:fs.Stats` used by the runtime. */
 export interface FileStat {
     isFile(): boolean;
     isDirectory(): boolean;
@@ -8,11 +10,13 @@ export interface FileStat {
     mtimeMs: number;
 }
 
+/** Write-only append stream for log output. */
 export interface LogStream {
     write(chunk: string): void;
     end(): void;
 }
 
+/** @deprecated Use {@link import('./file-system').FileSystem} instead — the new interface has union return types and does not require a separate SyncFileSystem. */
 export interface FileSystem {
     readFile(path: string): Promise<string>;
     writeFile(path: string, content: string): Promise<void>;
@@ -28,6 +32,7 @@ export interface FileSystem {
     createLogStream(path: string): LogStream;
 }
 
+/** @deprecated Use {@link import('./file-system').FileSystem} instead — its union return types make a separate sync interface unnecessary. */
 export interface SyncFileSystem {
     readFile(path: string): string;
     writeFile(path: string, content: string): void;
@@ -54,6 +59,8 @@ function nodeFs(): Promise<NodeFs> {
     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' instead. */
 export class NodeFileSystem implements FileSystem {
     async readFile(path: string): Promise<string> {
         const { readFile } = await nodeFsPromises();
@@ -132,6 +139,8 @@ export class NodeFileSystem implements FileSystem {
     }
 }
 
+/** {@link SyncFileSystem} backed by `node:fs` synchronous APIs. */
+/** @deprecated Use createNodeFileSystem() from './file-system-node' instead — its FileSystem interface has union return types, eliminating the need for a separate sync implementation. */
 export class NodeSyncFileSystem implements SyncFileSystem {
     readFile(path: string): string {
         return readFileSync(path, 'utf-8');
@@ -214,6 +223,8 @@ class LazyNodeLogStream implements LogStream {
 
 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' instead. */
 export class CloudflareFileSystem implements FileSystem {
     async readFile(path: string): Promise<string> {
         throw unsupportedCloudflareFs('readFile', path);
@@ -270,6 +281,8 @@ function unsupportedCloudflareFs(operation: string, path: string): Error {
 
 let activeFileSystem: FileSystem = 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: FileSystem): () => void {
     const previous = activeFileSystem;
     activeFileSystem = fileSystem;
@@ -278,18 +291,24 @@ export function setFileSystem(fileSystem: FileSystem): () => void {
     };
 }
 
+/** Returns the currently active global {@link FileSystem} instance. */
+/** @deprecated Use RuntimeFactory.createFileSystem() or ctx.require('fileSystem') instead. */
 export function getFs(): FileSystem {
     return activeFileSystem;
 }
 
+/** Creates parent directories for a file path before writing. */
 export async function ensureDirForFile(path: string, fs = getFs()): Promise<void> {
     await fs.mkdir(dirnamePath(path));
 }
 
+/** Synchronous variant of {@link ensureDirForFile}. */
+/** @deprecated The new createNodeFileSystem() handles parent-directory creation internally. */
 export function ensureDirForFileSync(path: string, fs: SyncFileSystem): void {
     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: string, content: string, fs = getFs()): Promise<void> {
     await ensureDirForFile(path, fs);
     const tempPath = `${path}.${getProcessPid()}.${uniqueToken()}.tmp`;
@@ -297,26 +316,31 @@ export async function atomicWriteFile(path: string, content: string, fs = getFs(
     await fs.rename(tempPath, path);
 }
 
+/** Atomically writes a value as JSON with trailing newline. */
 export async function atomicWriteJson(path: string, value: unknown, fs = getFs()): Promise<void> {
     await atomicWriteFile(path, `${JSON.stringify(value, null, 2)}\n`, fs);
 }
 
+/** Reads and parses a JSON file. */
 export async function readJsonFile<T = unknown>(path: string, fs = getFs()): Promise<T> {
     return JSON.parse(await fs.readFile(path)) as T;
 }
 
+/** Writes a value as JSON with 2-space indentation and trailing newline. */
 export async function writeJsonFile(path: string, value: unknown, fs = getFs()): Promise<void> {
     await fs.writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
 }
 
-export async function walkDir(path: string, fs = getFs()): Promise<string[]> {
+/** Recursively walks a directory, returning sorted paths to all files, optionally excluding entries by name. */
+export async function walkDir(path: string, fs = getFs(), exclude?: Set<string>): Promise<string[]> {
     const entries = (await fs.readDir(path)).sort();
     const result: string[] = [];
     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);
         }
@@ -324,33 +348,26 @@ export async function walkDir(path: string, fs = getFs()): Promise<string[]> {
     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').findProjectRoot} (or `createNodeFileSystem().getProjectRoot()`).
+ * This delegates to the single shared implementation.
+ */
 export function getProjectRoot(startDir = getProcessCwd()): string {
-    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: string[]): string {
     return resolvePath(getProjectRoot(), ...segments);
 }
 
+/** Creates a {@link LogStream} at the given path using the active file system. */
 export function createLogStream(path: string, fs = getFs()): LogStream {
     return fs.createLogStream(path);
 }
 
-function hasBunFile(path: string): boolean {
-    const bun = (globalThis as { Bun?: { file: (path: string) => { size: number } } }).Bun;
-    if (bun === undefined) return false;
-    return bun.file(path).size !== 0;
-}
-
 function getProcessPid(): number {
     return (globalThis as { process?: { pid?: number } }).process?.pid ?? 0;
 }

package/src/index.ts

@@ -1,7 +1,62 @@
 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';
+
+// ── Deprecated re-exports (backward compatibility) ──────────────────────
+
+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>;