@gobing-ai/ts-runtime 0.1.0

package/README.md

@@ -0,0 +1,288 @@
+# @gobing-ai/ts-runtime
+
+Runtime abstraction layer — environment detection, file system, process execution, configuration, and context management. Works on Bun/Node and Cloudflare Workers.
+
+## Overview
+
+`ts-runtime` decouples application code from platform specifics. Instead of importing `node:fs` or `node:child_process` directly, consumers go through interfaces (`FileSystem`, `ProcessExecutor`) that resolve to the correct implementation at startup based on `RuntimeContext`.
+
+**Key abstractions:**
+
+| Concept | Interface | Bun/Node impl | Cloudflare impl |
+|---------|-----------|---------------|-----------------|
+| File system | `FileSystem` | `NodeFileSystem` | `CloudflareFileSystem` (stub) |
+| Process execution | `ProcessExecutor` | `NodeProcessExecutor` | — |
+| Configuration | `Config` (Zod schema) | YAML + env vars | YAML + env vars |
+| Context | `RuntimeContext` | service locator | service locator |
+| Tracing | `SpanContext` | `{ traceId, spanId }` | `{ traceId, spanId }` |
+
+## Architecture
+
+```mermaid
+classDiagram
+    class RuntimeFactory {
+        <<interface>>
+        +RuntimeName runtimeName
+        +RuntimeCapabilities capabilities
+        +createFileSystem() FileSystem
+        +loadConfig() Promise~Config~
+        +createContext() RuntimeContext
+    }
+
+    class RuntimeContext {
+        +RuntimeScope scope
+        +RuntimeName runtimeName
+        +RuntimeCapabilities capabilities
+        +register(key, service) void
+        +get(key) T | undefined
+        +require(key) T
+        +has(key) boolean
+        +dispose() Promise~void~
+    }
+
+    class FileSystem {
+        <<interface>>
+        +readFile(path) Promise~string~
+        +writeFile(path, content) Promise~void~
+        +exists(path) Promise~boolean~
+        +mkdir(path) Promise~void~
+        +readDir(path) Promise~string[]~
+        +unlink(path) Promise~void~
+        +stat(path) Promise~FileStat | null~
+        +realpath(path) Promise~string~
+        +copy(src, dest) Promise~void~
+        +rename(src, dest) Promise~void~
+    }
+
+    class NodeFileSystem {
+        +readFile(path) Promise~string~
+        +writeFile(path, content) Promise~void~
+        +exists(path) Promise~boolean~
+        +mkdir(path) Promise~void~
+        +readDir(path) Promise~string[]~
+        +unlink(path) Promise~void~
+        +stat(path) Promise~FileStat | null~
+        +realpath(path) Promise~string~
+        +copy(src, dest) Promise~void~
+        +rename(src, dest) Promise~void~
+        +createLogStream(path) LogStream
+    }
+
+    class CloudflareFileSystem {
+        +readFile(path) Promise~string~
+        +writeFile(path, content) Promise~void~
+        +exists(path) Promise~boolean~
+        +mkdir(path) Promise~void~
+        +readDir(path) Promise~string[]~
+        +unlink(path) Promise~void~
+        +stat(path) Promise~FileStat | null~
+        +realpath(path) Promise~string~
+        +copy(src, dest) Promise~void~
+        +rename(src, dest) Promise~void~
+        +createLogStream(path) LogStream
+    }
+
+    class ProcessExecutor {
+        <<interface>>
+        +run(options) Promise~ProcessResult~
+    }
+
+    class NodeProcessExecutor {
+        +run(options) Promise~ProcessResult~
+    }
+
+    class Config {
+        +AppConfig app
+        +DatabaseConfig database
+        +LoggingConfig logging
+    }
+
+    class SpanContext {
+        <<interface>>
+        +string traceId
+        +string spanId
+        +Record~string,string~ baggage?
+        +Record~string,string|number|boolean~ attributes?
+    }
+
+    FileSystem <|.. NodeFileSystem : implements
+    FileSystem <|.. CloudflareFileSystem : implements
+    ProcessExecutor <|.. NodeProcessExecutor : implements
+    RuntimeContext --> FileSystem : "fileSystem"
+    RuntimeContext --> Config : "config"
+    RuntimeContext --> ProcessExecutor : "processExecutor"
+    RuntimeFactory --> RuntimeContext : creates
+    RuntimeFactory --> FileSystem : creates
+    RuntimeFactory --> Config : loadConfig()
+```
+
+## How It Works
+
+### 1. Runtime detection
+
+At startup, a `RuntimeFactory` is selected based on the environment:
+
+```ts
+import { createRuntimeContext } from '@gobing-ai/ts-runtime';
+
+const ctx = createRuntimeContext({
+    runtimeName: 'node-bun',
+    capabilities: {
+        hasFilesystem: true,
+        hasProcessExecution: true,
+        hasPersistentStorage: true,
+    },
+});
+```
+
+### 2. Service registration
+
+Services are registered into `RuntimeContext` and accessed by key:
+
+```ts
+ctx.register('db', drizzleAdapter);
+ctx.register('cache', redisClient);
+
+const db = ctx.require('db'); // throws if missing
+const cache = ctx.get('cache'); // undefined if missing
+```
+
+### 3. Configuration
+
+Config is loaded from YAML with environment variable interpolation and Zod validation:
+
+```yaml
+# config.yaml
+app:
+  name: my-app
+  env: ${APP_ENV}
+  port: ${PORT}
+database:
+  url: ${DATABASE_URL}
+logging:
+  level: debug
+```
+
+```ts
+import { buildConfigFromYaml } from '@gobing-ai/ts-runtime';
+
+const yaml = await fs.readFile('config.yaml');
+const config = buildConfigFromYaml(yaml, {
+    overrides: { app: { port: 8080 } },
+});
+// config.app.port === 8080 (overridden)
+// config.logging.level === 'debug' (from YAML)
+```
+
+### 4. File system abstraction
+
+All file operations go through the `FileSystem` interface. Swap implementations for testing:
+
+```ts
+import { getFs } from '@gobing-ai/ts-runtime';
+
+const fs = getFs();
+await fs.writeFile('output.json', JSON.stringify(data));
+const content = await fs.readFile('output.json');
+```
+
+### 5. Graceful disposal
+
+`RuntimeContext.dispose()` calls `dispose()` on every registered service that implements the pattern:
+
+```ts
+process.on('SIGTERM', async () => {
+    await ctx.dispose();
+    process.exit(0);
+});
+```
+
+## Usage
+
+### Install
+
+```bash
+bun add @gobing-ai/ts-runtime
+```
+
+### Basic setup (Bun/Node)
+
+```ts
+import { createRuntimeContext, getFs, NodeFileSystem } from '@gobing-ai/ts-runtime';
+
+const ctx = createRuntimeContext({
+    runtimeName: 'node-bun',
+    services: {
+        fileSystem: new NodeFileSystem(),
+    },
+});
+
+const fs = ctx.require('fileSystem');
+await fs.writeFile('hello.txt', 'Hello, world!');
+```
+
+### Cloudflare Workers
+
+```ts
+import { createRuntimeContext, CloudflareFileSystem } from '@gobing-ai/ts-runtime';
+
+export default {
+    async fetch(request: Request, env: Env): Promise<Response> {
+        const ctx = createRuntimeContext({
+            runtimeName: 'cloudflare-workers',
+            capabilities: {
+                hasFilesystem: false,
+                hasProcessExecution: false,
+                hasPersistentStorage: false,
+            },
+            services: {
+                fileSystem: new CloudflareFileSystem(),
+            },
+        });
+        // ...
+    },
+};
+```
+
+### Config with env interpolation
+
+```ts
+import { buildConfigFromYaml, buildConfigFromObject } from '@gobing-ai/ts-runtime';
+
+// From YAML file
+const config = buildConfigFromYaml(yamlText);
+
+// From plain object (programmatic config)
+const config = buildConfigFromObject({
+    app: { name: 'api', env: 'production', port: 3000 },
+    database: { url: ':memory:' },
+});
+```
+
+### Process execution
+
+```ts
+import { NodeProcessExecutor } from '@gobing-ai/ts-runtime';
+
+const exec = new NodeProcessExecutor({ defaultTimeout: 30_000 });
+
+const result = await exec.run({
+    command: 'git',
+    args: ['status', '--short'],
+    cwd: '/path/to/repo',
+    rejectOnError: true,
+});
+
+console.log(result.stdout);
+console.log(`Duration: ${result.durationMs}ms`);
+```
+
+### SpanContext (for telemetry)
+
+```ts
+import type { SpanContext } from '@gobing-ai/ts-runtime';
+
+function processRequest(ctx: SpanContext) {
+    console.log(`Trace: ${ctx.traceId}, Span: ${ctx.spanId}`);
+}
+```

package/dist/config.d.ts

@@ -0,0 +1,51 @@
+import { type ZodIssue, z } from 'zod';
+export declare const configSchema: z.ZodObject<{
+    app: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        env: z.ZodDefault<z.ZodEnum<{
+            development: "development";
+            staging: "staging";
+            production: "production";
+            test: "test";
+        }>>;
+        port: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    database: z.ZodDefault<z.ZodObject<{
+        url: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    logging: z.ZodDefault<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            trace: "trace";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+            fatal: "fatal";
+        }>>;
+        console: z.ZodDefault<z.ZodBoolean>;
+        file: z.ZodDefault<z.ZodBoolean>;
+        filePath: z.ZodOptional<z.ZodString>;
+        json: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Config = z.output<typeof configSchema>;
+export declare class ConfigLoadError extends Error {
+    readonly issues: ZodIssue[];
+    constructor(message: string, issues?: ZodIssue[]);
+}
+export declare function getNodeEnv(): string;
+export declare function isTestEnv(): boolean;
+export declare function getDatabaseUrl(): string | undefined;
+export declare function interpolateEnv(value: string): string;
+export declare function interpolateTree(value: unknown): unknown;
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+export declare function flattenKeys(obj: Record<string, unknown>, prefix?: string): Record<string, string>;
+export declare function deFlattenKeys(entries: Record<string, string>): Record<string, unknown>;
+export declare function buildConfigFromObject(raw: Record<string, unknown>, options?: {
+    overrides?: Partial<Config>;
+}): Config;
+export declare function parseConfigYaml(yamlText: string): Record<string, unknown>;
+export declare function buildConfigFromYaml(yamlText: string, options?: {
+    overrides?: Partial<Config>;
+}): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEvC,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsBvB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAInD,qBAAa,eAAgB,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,EAAO;CAKvD;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOvD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUnH;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,SAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAW7F;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAetF;AAED,wBAAgB,qBAAqB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAAO,GAC9C,MAAM,CAUR;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzE;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAAO,GAAG,MAAM,CAE3G"}

package/dist/config.js

@@ -0,0 +1,156 @@
+import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
+export const configSchema = z.object({
+    app: z
+        .object({
+        name: z.string().default('app'),
+        env: z.enum(['development', 'staging', 'production', 'test']).default('development'),
+        port: z.number().int().positive().default(3000),
+    })
+        .default({ name: 'app', env: 'development', port: 3000 }),
+    database: z
+        .object({
+        url: z.string().default(':memory:'),
+    })
+        .default({ url: ':memory:' }),
+    logging: z
+        .object({
+        level: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).default('info'),
+        console: z.boolean().default(true),
+        file: z.boolean().default(false),
+        filePath: z.string().optional(),
+        json: z.boolean().default(false),
+    })
+        .default({ level: 'info', console: true, file: false, json: false }),
+});
+const ENV_INTERPOLATION_RE = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+export class ConfigLoadError extends Error {
+    issues;
+    constructor(message, issues = []) {
+        super(message);
+        this.name = 'ConfigLoadError';
+        this.issues = issues;
+    }
+}
+export function getNodeEnv() {
+    return process.env.NODE_ENV ?? 'development';
+}
+export function isTestEnv() {
+    return getNodeEnv() === 'test';
+}
+export function getDatabaseUrl() {
+    return process.env.DATABASE_URL;
+}
+export function interpolateEnv(value) {
+    return value.replace(ENV_INTERPOLATION_RE, (_match, name) => process.env[name] ?? `\${${name}}`);
+}
+export function interpolateTree(value) {
+    if (typeof value === 'string')
+        return interpolateEnv(value);
+    if (Array.isArray(value))
+        return value.map(interpolateTree);
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, interpolateTree(child)]));
+    }
+    return value;
+}
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = deepMerge(result[key], value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export function flattenKeys(obj, prefix = '') {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (isPlainObject(value)) {
+            Object.assign(result, flattenKeys(value, fullKey));
+        }
+        else {
+            result[fullKey] = JSON.stringify(value);
+        }
+    }
+    return result;
+}
+export function deFlattenKeys(entries) {
+    const result = {};
+    for (const [key, rawValue] of Object.entries(entries)) {
+        const parts = key.split('.');
+        let current = result;
+        for (const part of parts.slice(0, -1)) {
+            if (!isPlainObject(current[part]))
+                current[part] = {};
+            current = current[part];
+        }
+        const last = parts.at(-1);
+        if (last === undefined)
+            continue;
+        current[last] = parseConfigValue(rawValue);
+    }
+    return result;
+}
+export function buildConfigFromObject(raw, options = {}) {
+    const interpolated = interpolateTree(raw);
+    const merged = options.overrides
+        ? deepMerge(interpolated, options.overrides)
+        : interpolated;
+    const result = configSchema.safeParse(merged);
+    if (!result.success) {
+        throw new ConfigLoadError('Config validation failed', result.error.issues);
+    }
+    return deepFreeze(result.data);
+}
+export function parseConfigYaml(yamlText) {
+    try {
+        const parsed = parseYaml(yamlText);
+        if (parsed === null || parsed === undefined)
+            return {};
+        if (!isPlainObject(parsed)) {
+            throw new ConfigLoadError('Config YAML must parse to an object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof ConfigLoadError)
+            throw error;
+        throw new ConfigLoadError(`Config YAML parsing failed: ${error.message}`);
+    }
+}
+export function buildConfigFromYaml(yamlText, options = {}) {
+    return buildConfigFromObject(parseConfigYaml(yamlText), options);
+}
+function parseConfigValue(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function deepFreeze(obj) {
+    Object.freeze(obj);
+    for (const value of Object.values(obj)) {
+        if (Array.isArray(value)) {
+            Object.freeze(value);
+            for (const item of value) {
+                if (isPlainObject(item) && !Object.isFrozen(item)) {
+                    deepFreeze(item);
+                }
+            }
+        }
+        else if (isPlainObject(value) && !Object.isFrozen(value)) {
+            deepFreeze(value);
+        }
+    }
+    return obj;
+}

package/dist/context.d.ts

@@ -0,0 +1,30 @@
+import type { Config } from './config';
+import type { FileSystem } from './fs';
+import type { RuntimeCapabilities, RuntimeFactory, RuntimeName } from './types';
+export type RuntimeScope = 'process' | 'server-request' | 'scheduled-event' | 'test';
+export interface RuntimeServiceMap {
+    config: Config;
+    fileSystem: FileSystem;
+    [serviceName: string]: unknown;
+}
+export interface RuntimeContextOptions<TServices extends RuntimeServiceMap = RuntimeServiceMap> {
+    scope?: RuntimeScope;
+    runtimeName?: RuntimeName;
+    capabilities?: RuntimeCapabilities;
+    services?: Partial<TServices>;
+    factory?: RuntimeFactory;
+}
+export declare class RuntimeContext<TServices extends RuntimeServiceMap = RuntimeServiceMap> {
+    readonly scope: RuntimeScope;
+    readonly runtimeName: RuntimeName;
+    readonly capabilities: RuntimeCapabilities;
+    readonly services: Map<keyof TServices, TServices[keyof TServices]>;
+    constructor(options?: RuntimeContextOptions<TServices>);
+    register<K extends keyof TServices>(key: K, service: TServices[K]): this;
+    get<K extends keyof TServices>(key: K): TServices[K] | undefined;
+    require<K extends keyof TServices>(key: K): TServices[K];
+    has<K extends keyof TServices>(key: K): boolean;
+    dispose(): Promise<void>;
+}
+export declare function createRuntimeContext<TServices extends RuntimeServiceMap = RuntimeServiceMap>(options?: RuntimeContextOptions<TServices>): RuntimeContext<TServices>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEhF,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAErF,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB;IAC1F,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,qBAAa,cAAc,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB;IAC/E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,mDAA0D;gBAE/D,OAAO,GAAE,qBAAqB,CAAC,SAAS,CAAM;IAsB1D,QAAQ,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAKxE,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;IAIhE,OAAO,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAQxD,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO;IAIzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAejC;AAMD,wBAAgB,oBAAoB,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB,EACxF,OAAO,GAAE,qBAAqB,CAAC,SAAS,CAAM,GAC/C,cAAc,CAAC,SAAS,CAAC,CAE3B"}

package/dist/context.js

@@ -0,0 +1,66 @@
+import { buildConfigFromObject } from './config.js';
+import { getFs } from './fs.js';
+export class RuntimeContext {
+    scope;
+    runtimeName;
+    capabilities;
+    services = new Map();
+    constructor(options = {}) {
+        this.scope = options.scope ?? 'process';
+        this.runtimeName = options.runtimeName ?? options.factory?.runtimeName ?? 'node-bun';
+        this.capabilities =
+            options.capabilities ??
+                options.factory?.capabilities ??
+                {
+                    hasFilesystem: true,
+                    hasProcessExecution: true,
+                    hasPersistentStorage: true,
+                };
+        this.register('config', (options.services?.config ?? buildConfigFromObject({})));
+        this.register('fileSystem', (options.services?.fileSystem ?? getFs()));
+        for (const [key, value] of Object.entries(options.services ?? {})) {
+            if (value !== undefined) {
+                this.register(key, value);
+            }
+        }
+    }
+    register(key, service) {
+        this.services.set(key, service);
+        return this;
+    }
+    get(key) {
+        return this.services.get(key);
+    }
+    require(key) {
+        const service = this.get(key);
+        if (service === undefined) {
+            throw new Error(`Runtime service "${String(key)}" is unavailable for runtime ${this.runtimeName}.`);
+        }
+        return service;
+    }
+    has(key) {
+        return this.services.has(key);
+    }
+    async dispose() {
+        const errors = [];
+        for (const service of this.services.values()) {
+            if (isDisposable(service)) {
+                try {
+                    await service.dispose();
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+        }
+        if (errors.length > 0) {
+            throw new Error(`Failed to dispose some services:\n${errors.map((e) => `- ${e.message}`).join('\n')}`);
+        }
+    }
+}
+function isDisposable(value) {
+    return typeof value === 'object' && value !== null && 'dispose' in value && typeof value.dispose === 'function';
+}
+export function createRuntimeContext(options = {}) {
+    return new RuntimeContext(options);
+}

package/dist/fs.d.ts

@@ -0,0 +1,64 @@
+export interface FileStat {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    size: number;
+    mtimeMs: number;
+}
+export interface LogStream {
+    write(chunk: string): void;
+    end(): void;
+}
+export interface FileSystem {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    appendFile(path: string, content: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readDir(path: string): Promise<string[]>;
+    unlink(path: string): Promise<void>;
+    stat(path: string): Promise<FileStat | null>;
+    realpath(path: string): Promise<string>;
+    copy(src: string, dest: string): Promise<void>;
+    rename(src: string, dest: string): Promise<void>;
+    createLogStream(path: string): LogStream;
+}
+export declare class NodeFileSystem implements FileSystem {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    appendFile(path: string, content: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readDir(path: string): Promise<string[]>;
+    unlink(path: string): Promise<void>;
+    stat(path: string): Promise<FileStat | null>;
+    realpath(path: string): Promise<string>;
+    copy(src: string, dest: string): Promise<void>;
+    rename(src: string, dest: string): Promise<void>;
+    createLogStream(path: string): LogStream;
+}
+export declare class CloudflareFileSystem implements FileSystem {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, _content: string): Promise<void>;
+    appendFile(path: string, _content: string): Promise<void>;
+    mkdir(_path: string): Promise<void>;
+    exists(_path: string): Promise<boolean>;
+    readDir(path: string): Promise<string[]>;
+    unlink(path: string): Promise<void>;
+    stat(_path: string): Promise<FileStat | null>;
+    realpath(path: string): Promise<string>;
+    copy(src: string, _dest: string): Promise<void>;
+    rename(src: string, _dest: string): Promise<void>;
+    createLogStream(path: string): LogStream;
+}
+export declare function setFileSystem(fileSystem: FileSystem): () => void;
+export declare function getFs(): FileSystem;
+export declare function ensureDirForFile(path: string, fs?: FileSystem): Promise<void>;
+export declare function atomicWriteFile(path: string, content: string, fs?: FileSystem): Promise<void>;
+export declare function atomicWriteJson(path: string, value: unknown, fs?: FileSystem): Promise<void>;
+export declare function readJsonFile<T = unknown>(path: string, fs?: FileSystem): Promise<T>;
+export declare function writeJsonFile(path: string, value: unknown, fs?: FileSystem): Promise<void>;
+export declare function walkDir(path: string, fs?: FileSystem): Promise<string[]>;
+export declare function getProjectRoot(startDir?: string): string;
+export declare function resolveProjectPath(...segments: string[]): string;
+export declare function createLogStream(path: string, fs?: FileSystem): LogStream;
+//# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"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"}