@gobing-ai/ts-runtime 0.3.0 → 0.3.2

package/dist/schema-validation.d.ts

@@ -1,7 +1,10 @@
+import type { FileSystem } from './file-system';
+/** A single JSON Schema validation failure — records the JSON pointer path and a human-readable message. */
 export interface JsonSchemaViolation {
     path: string;
     message: string;
 }
+/** Subset of JSON Schema 2020-12 keywords used for runtime configuration validation. */
 export interface JsonSchema {
     type?: string | string[];
     required?: string[];
@@ -15,6 +18,7 @@ export interface JsonSchema {
     $ref?: string;
     $defs?: Record<string, JsonSchema>;
 }
+/** Options for loading and validating structured configuration files (YAML/JSON with `$schema`). */
 export interface StructuredConfigLoadOptions {
     validateSchema?: boolean;
     /**
@@ -30,13 +34,25 @@ export interface StructuredConfigLoadOptions {
      * Injectable for testing.
      */
     resolve?: (specifier: string, from: string) => string;
+    /**
+     * File system used to read the config and local schema files. Defaults to the
+     * deprecated `getFs()` global; supply a {@link FileSystem} from the runtime factory
+     * (`createNodeFileSystem()`) to route reads through the factory path or to inject a
+     * virtual file system in tests.
+     */
+    fileSystem?: Pick<FileSystem, 'readFile'>;
 }
+/** Error thrown when structured config validation fails, carrying the list of {@link JsonSchemaViolation}s. */
 export declare class StructuredConfigSchemaError extends Error {
     readonly violations: readonly JsonSchemaViolation[];
     constructor(message: string, violations?: readonly JsonSchemaViolation[]);
 }
+/** Reads a config file from disk, parses it (YAML or JSON), and validates against its declared `$schema`. */
 export declare function loadStructuredConfig(path: string, options?: StructuredConfigLoadOptions): Promise<unknown>;
+/** Parses a config string (YAML or JSON) and validates against its declared `$schema` if present. */
 export declare function parseStructuredConfig(content: string, source: string, options?: StructuredConfigLoadOptions): Promise<unknown>;
+/** Extracts the `$schema` reference from a parsed config object, resolves and fetches the schema, then validates. */
 export declare function validateDeclaredJsonSchema(value: unknown, source: string, options?: StructuredConfigLoadOptions): Promise<void>;
+/** Validates a value against a {@link JsonSchema}, returning a list of {@link JsonSchemaViolation}s. Does not throw. */
 export declare function validateJsonSchema(value: unknown, schema: JsonSchema, path?: string, defs?: Record<string, JsonSchema>, seenRefs?: ReadonlySet<string>): JsonSchemaViolation[];
 //# sourceMappingURL=schema-validation.d.ts.map

package/dist/schema-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-validation.d.ts","sourceRoot":"","sources":["../src/schema-validation.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IACxC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7C;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACzD;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IAG9C,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE;gBADnD,OAAO,EAAE,MAAM,EACN,UAAU,GAAE,SAAS,mBAAmB,EAAO;CAK/D;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,2BAAgC,GAAG,OAAO,CAAC,OAAO,CAAC,CAGpH;AAED,wBAAsB,qBAAqB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,0BAA0B,CAC5C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,UAAU,EAClB,IAAI,SAAK,EACT,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAM,EACrC,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GAC1C,mBAAmB,EAAE,CAwDvB"}
+{"version":3,"file":"schema-validation.d.ts","sourceRoot":"","sources":["../src/schema-validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAUhD,4GAA4G;AAC5G,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACtC;AAED,oGAAoG;AACpG,MAAM,WAAW,2BAA2B;IACxC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7C;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACtD;;;;;OAKG;IACH,UAAU,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;CAC7C;AAED,+GAA+G;AAC/G,qBAAa,2BAA4B,SAAQ,KAAK;IAG9C,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE;gBADnD,OAAO,EAAE,MAAM,EACN,UAAU,GAAE,SAAS,mBAAmB,EAAO;CAK/D;AAED,6GAA6G;AAC7G,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,2BAAgC,GAAG,OAAO,CAAC,OAAO,CAAC,CAGpH;AAED,qGAAqG;AACrG,wBAAsB,qBAAqB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,qHAAqH;AACrH,wBAAsB,0BAA0B,CAC5C,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED,wHAAwH;AACxH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,UAAU,EAClB,IAAI,SAAK,EACT,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAM,EACrC,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GAC1C,mBAAmB,EAAE,CAwDvB"}

package/dist/schema-validation.js

@@ -1,10 +1,11 @@
 import { parse as parseYaml } from 'yaml';
 import { getFs } from './fs.js';
-import { dirnamePath, isAbsolutePath, joinPath } from './path.js';
+import { dirnamePath, getProcessCwd, isAbsolutePath, joinPath } from './path.js';
 /** Default time budget for a single remote schema fetch. */
 const REMOTE_SCHEMA_FETCH_TIMEOUT_MS = 5_000;
 /** Upper bound on a remote schema body. A timeout alone lets a slow multi-GB drip exhaust memory. */
 const REMOTE_SCHEMA_MAX_BYTES = 5 * 1024 * 1024;
+/** Error thrown when structured config validation fails, carrying the list of {@link JsonSchemaViolation}s. */
 export class StructuredConfigSchemaError extends Error {
     violations;
     constructor(message, violations = []) {
@@ -13,10 +14,12 @@ export class StructuredConfigSchemaError extends Error {
         this.name = 'StructuredConfigSchemaError';
     }
 }
+/** Reads a config file from disk, parses it (YAML or JSON), and validates against its declared `$schema`. */
 export async function loadStructuredConfig(path, options = {}) {
-    const content = await getFs().readFile(path);
+    const content = await (options.fileSystem ?? getFs()).readFile(path);
     return await parseStructuredConfig(content, path, options);
 }
+/** Parses a config string (YAML or JSON) and validates against its declared `$schema` if present. */
 export async function parseStructuredConfig(content, source, options = {}) {
     const parsed = source.endsWith('.json') ? JSON.parse(content) : parseYaml(content);
     if (options.validateSchema !== false) {
@@ -24,6 +27,7 @@ export async function parseStructuredConfig(content, source, options = {}) {
     }
     return parsed;
 }
+/** Extracts the `$schema` reference from a parsed config object, resolves and fetches the schema, then validates. */
 export async function validateDeclaredJsonSchema(value, source, options = {}) {
     if (!isObject(value))
         return;
@@ -49,6 +53,7 @@ export async function validateDeclaredJsonSchema(value, source, options = {}) {
             .join('; ')}`, violations);
     }
 }
+/** Validates a value against a {@link JsonSchema}, returning a list of {@link JsonSchemaViolation}s. Does not throw. */
 export function validateJsonSchema(value, schema, path = '', defs = {}, seenRefs = new Set()) {
     const violations = [];
     // Applicator keywords compose with their siblings (logical AND), per JSON Schema 2020-12 —
@@ -183,7 +188,7 @@ function resolvePackageSchema(specifier, source, resolve) {
     if (subpath.length === 0) {
         throw new StructuredConfigSchemaError(`Package schema ref "${specifier}" referenced by "${source}" must include a path within the package`);
     }
-    const from = isRemoteRef(source) ? process.cwd() : dirnamePath(source);
+    const from = isRemoteRef(source) ? getProcessCwd() : dirnamePath(source);
     try {
         // Resolve the package root via its always-present package.json, then join the subpath.
         // This sidesteps `exports` gating on arbitrary JSON subpaths.
@@ -211,7 +216,7 @@ async function readSchema(schemaLocation, options) {
         }
         return await readBoundedBody(response, schemaLocation);
     }
-    return await getFs().readFile(schemaLocation);
+    return await (options.fileSystem ?? getFs()).readFile(schemaLocation);
 }
 /**
  * Read a response body under a hard byte cap. `Content-Length` is a fast-path reject, but servers

package/dist/types.d.ts

@@ -1,14 +1,18 @@
 import type { Config } from './config';
+/** Identifier for the target runtime platform. */
 export type RuntimeName = 'node-bun' | 'cloudflare-workers' | 'test';
+/** Feature flags describing what a runtime platform supports (filesystem, process execution, persistent storage). */
 export interface RuntimeCapabilities {
     readonly hasFilesystem: boolean;
     readonly hasProcessExecution: boolean;
     readonly hasPersistentStorage: boolean;
 }
+/** Options passed to config loading functions, including overrides and environment variable bindings. */
 export interface LoadConfigOptions {
     overrides?: Partial<Config>;
     envBindings?: Record<string, unknown>;
 }
+/** Minimal distributed tracing context for W3C trace/span propagation. */
 export interface SpanContext {
     traceId: string;
     spanId: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,oBAAoB,GAAG,MAAM,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAC1D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,oBAAoB,GAAG,MAAM,CAAC;AAErE,qHAAqH;AACrH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CAC1C;AAED,yGAAyG;AACzG,MAAM,WAAW,iBAAiB;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAC1D"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-runtime",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
     "keywords": [
         "typescript",
@@ -35,6 +35,10 @@
         "./bun-sqlite": {
             "types": "./dist/bun-sqlite.d.ts",
             "import": "./dist/bun-sqlite.js"
+        },
+        "./plugin": {
+            "types": "./dist/plugin.d.ts",
+            "import": "./dist/plugin.js"
         }
     },
     "files": [
@@ -54,7 +58,7 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-runtime-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.3.0",
+        "@gobing-ai/ts-utils": "^0.3.2",
         "execa": "^9.5.0",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"

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;
+}