@gobing-ai/ts-runtime 0.3.1 → 0.3.2

package/dist/process-executor.js

@@ -1,11 +1,25 @@
 import { isatty } from 'node:tty';
 import { execa } from 'execa';
-export class NodeProcessExecutor {
+// ── ProcessExecutor ───────────────────────────────────────────────────────
+/**
+ * Runtime-agnostic process executor wrapping `execa`.
+ *
+ * Every invocation supports timeout enforcement, output capture, and
+ * configurable output policy (buffered vs streamed).
+ */
+export class ProcessExecutor {
     config;
     constructor(config = {}) {
         this.config = config;
     }
+    /**
+     * Run a command, buffered by default. Returns a structured {@link ProcessResult}.
+     * Does NOT throw on non-zero exit codes unless `rejectOnError` is set.
+     */
     async run(options) {
+        return this.trace('process.run', () => this.runUntraced(options));
+    }
+    async runUntraced(options) {
         const args = options.args ?? [];
         const execaOptions = buildExecaOptions({
             cwd: options.cwd,
@@ -16,9 +30,19 @@ export class NodeProcessExecutor {
             outputPolicy: this.config.output,
             forceBuffered: options.forceBuffered ?? false,
         });
+        const startedAt = Date.now();
+        this.emitProcessEvent('process.started', {
+            command: options.command,
+            args,
+            exitCode: null,
+            durationMs: 0,
+            reason: 'exit',
+            timestamp: new Date(startedAt).toISOString(),
+            ...(options.label !== undefined ? { label: options.label } : {}),
+        });
         try {
             const result = await execa(options.command, args, execaOptions);
-            return {
+            const processResult = {
                 command: options.command,
                 args,
                 exitCode: result.exitCode ?? null,
@@ -27,23 +51,190 @@ export class NodeProcessExecutor {
                 ...(result.signalDescription !== undefined ? { signal: result.signalDescription } : {}),
                 durationMs: result.durationMs,
             };
+            this.emitExitedFromResult(options, processResult, result);
+            return processResult;
         }
         catch (error) {
-            if (options.rejectOnError)
-                throw error;
             const failed = error;
-            return {
+            const processResult = {
                 command: options.command,
                 args,
                 exitCode: failed.exitCode ?? null,
                 stdout: asString(failed.stdout),
                 stderr: asString(failed.stderr),
-                ...(failed.signalDescription !== undefined ? { signal: failed.signalDescription } : {}),
-                durationMs: failed.durationMs ?? 0,
+                ...(failed.signalDescription !== undefined
+                    ? { signal: failed.signalDescription }
+                    : failed.signal !== undefined
+                        ? { signal: failed.signal }
+                        : {}),
+                durationMs: failed.durationMs ?? Date.now() - startedAt,
             };
+            this.emitExitedFromResult(options, processResult, error, error);
+            if (options.rejectOnError)
+                throw error;
+            return processResult;
+        }
+    }
+    /**
+     * 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) {
+        const args = options.args ?? [];
+        void this.config.tracer?.traceAsync('process.runStreaming', async () => undefined).catch(() => undefined);
+        try {
+            const startedAt = Date.now();
+            this.emitProcessEvent('process.started', {
+                command: options.command,
+                args,
+                exitCode: null,
+                durationMs: 0,
+                reason: 'exit',
+                timestamp: new Date(startedAt).toISOString(),
+                ...(options.label !== undefined ? { label: options.label } : {}),
+            });
+            const subprocess = Bun.spawn({
+                cmd: [options.command, ...args],
+                stdin: 'pipe',
+                stdout: 'pipe',
+                stderr: 'pipe',
+                ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+                ...(options.env !== undefined ? { env: options.env } : {}),
+            });
+            return new ObservedPipeProcess(new BunPipeProcess(subprocess), this.config.events, {
+                command: options.command,
+                args,
+                startedAt,
+                ...(options.label !== undefined ? { label: options.label } : {}),
+            });
         }
+        catch (error) {
+            this.emitProcessEvent('process.exited', {
+                command: options.command,
+                args,
+                exitCode: null,
+                durationMs: 0,
+                reason: 'error',
+                timestamp: new Date().toISOString(),
+                ...(options.label !== undefined ? { label: options.label } : {}),
+                error: errorMessage(error),
+            });
+            throw error;
+        }
+    }
+    async trace(name, fn) {
+        if (this.config.tracer === undefined)
+            return await fn();
+        return await this.config.tracer.traceAsync(name, async () => await fn());
+    }
+    emitExitedFromResult(options, result, completion, error) {
+        const reason = isTimedOut(completion)
+            ? 'timeout'
+            : result.signal !== undefined
+                ? 'signal'
+                : error
+                    ? 'error'
+                    : 'exit';
+        this.emitProcessEvent('process.exited', {
+            command: result.command,
+            args: result.args,
+            exitCode: result.exitCode,
+            ...(result.signal !== undefined ? { signal: result.signal } : {}),
+            durationMs: result.durationMs,
+            reason,
+            timestamp: new Date().toISOString(),
+            ...(options.label !== undefined ? { label: options.label } : {}),
+            ...(error !== undefined ? { error: errorMessage(error) } : {}),
+        });
+    }
+    emitProcessEvent(event, detail) {
+        this.config.events?.emit(event, detail);
+    }
+}
+class ObservedPipeProcess {
+    inner;
+    killedWith;
+    exited;
+    constructor(inner, events, context) {
+        this.inner = inner;
+        this.exited = inner.exited.then((exitCode) => {
+            events?.emit('process.exited', {
+                command: context.command,
+                args: context.args,
+                exitCode,
+                ...(this.killedWith !== undefined ? { signal: String(this.killedWith) } : {}),
+                durationMs: Date.now() - context.startedAt,
+                reason: this.killedWith !== undefined ? 'signal' : 'exit',
+                timestamp: new Date().toISOString(),
+                ...(context.label !== undefined ? { label: context.label } : {}),
+            });
+            return exitCode;
+        });
+    }
+    get pid() {
+        return this.inner.pid;
+    }
+    get stdout() {
+        return this.inner.stdout;
+    }
+    get stderr() {
+        return this.inner.stderr;
+    }
+    writeStdin(input) {
+        this.inner.writeStdin(input);
+    }
+    endStdin() {
+        this.inner.endStdin();
+    }
+    kill(signal) {
+        this.killedWith = signal;
+        this.inner.kill(signal);
+    }
+}
+class BunPipeProcess {
+    subprocess;
+    writer;
+    constructor(subprocess) {
+        this.subprocess = subprocess;
+        this.writer = subprocess.stdin;
+    }
+    get pid() {
+        return this.subprocess.pid ?? null;
     }
+    get stdout() {
+        return isReadableStream(this.subprocess.stdout) ? this.subprocess.stdout : null;
+    }
+    get stderr() {
+        return isReadableStream(this.subprocess.stderr) ? this.subprocess.stderr : null;
+    }
+    get exited() {
+        return this.subprocess.exited;
+    }
+    writeStdin(input) {
+        this.writer.write(input);
+        this.writer.flush?.();
+    }
+    endStdin() {
+        this.writer.end?.();
+    }
+    kill(signal) {
+        this.subprocess.kill(signal);
+    }
+}
+// ── Deprecated backward-compatible subclasses ─────────────────────────────
+/**
+ * @deprecated Use {@link ProcessExecutor} directly.
+ * This subclass is kept for backward compatibility.
+ */
+export 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 class BunSyncProcessExecutor {
     runSync(options) {
         const args = options.args ?? [];
@@ -69,6 +260,10 @@ export class BunSyncProcessExecutor {
         };
     }
 }
+/**
+ * @deprecated Use {@link ProcessExecutor.runStreaming} instead.
+ * This class is kept for backward compatibility.
+ */
 export class BunPipeProcessSpawner {
     spawn(options) {
         const subprocess = Bun.spawn({
@@ -82,36 +277,7 @@ export class BunPipeProcessSpawner {
         return new BunPipeProcess(subprocess);
     }
 }
-class BunPipeProcess {
-    subprocess;
-    writer;
-    constructor(subprocess) {
-        this.subprocess = subprocess;
-        this.writer = subprocess.stdin;
-    }
-    get pid() {
-        return this.subprocess.pid ?? null;
-    }
-    get stdout() {
-        return isReadableStream(this.subprocess.stdout) ? this.subprocess.stdout : null;
-    }
-    get stderr() {
-        return isReadableStream(this.subprocess.stderr) ? this.subprocess.stderr : null;
-    }
-    get exited() {
-        return this.subprocess.exited;
-    }
-    writeStdin(input) {
-        this.writer.write(input);
-        this.writer.flush?.();
-    }
-    endStdin() {
-        this.writer.end?.();
-    }
-    kill(signal) {
-        this.subprocess.kill(signal);
-    }
-}
+// ── Helpers ───────────────────────────────────────────────────────────────
 function buildExecaOptions(opts) {
     const canStream = !opts.forceBuffered &&
         opts.outputPolicy?.mode === 'stream' &&
@@ -142,3 +308,9 @@ function stripFinalNewline(value) {
 function isReadableStream(value) {
     return value instanceof ReadableStream;
 }
+function isTimedOut(error) {
+    return typeof error === 'object' && error !== null && 'timedOut' in error && error.timedOut === true;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/runtime-cf.d.ts

@@ -0,0 +1,6 @@
+import type { RuntimeFactory } from './runtime-factory';
+/**
+ * Cloudflare Workers runtime factory (no filesystem, no process execution).
+ */
+export declare const cloudflareWorkersFactory: RuntimeFactory;
+//# sourceMappingURL=runtime-cf.d.ts.map

package/dist/runtime-cf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-cf.d.ts","sourceRoot":"","sources":["../src/runtime-cf.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,cA6BtC,CAAC"}

package/dist/runtime-cf.js

@@ -0,0 +1,33 @@
+import { parse as parseYaml } from 'yaml';
+import { buildConfigFromObject } from './config.js';
+import { createCfFileSystem } from './file-system-cf.js';
+/** Binding name for the YAML config text blob set in wrangler.toml. */
+const CONFIG_YAML_BINDING = 'CONFIG_YAML';
+/**
+ * Cloudflare Workers runtime factory (no filesystem, no process execution).
+ */
+export const cloudflareWorkersFactory = {
+    runtimeName: 'cloudflare-workers',
+    capabilities: {
+        hasFilesystem: false,
+        hasProcessExecution: false,
+        hasPersistentStorage: false,
+    },
+    createFileSystem: () => createCfFileSystem(),
+    createProcessExecutor: (_config) => {
+        throw new Error('ProcessExecutor is not available on Cloudflare Workers.');
+    },
+    async loadConfig(options) {
+        const yamlString = options?.envBindings?.[CONFIG_YAML_BINDING];
+        let raw = {};
+        if (yamlString) {
+            try {
+                raw = parseYaml(yamlString);
+            }
+            catch {
+                // Fall through to schema defaults on parse failure
+            }
+        }
+        return buildConfigFromObject(raw, options);
+    },
+};

package/dist/runtime-factory.d.ts

@@ -0,0 +1,24 @@
+import type { Config } from './config';
+import type { FileSystem } from './file-system';
+import type { ProcessExecutor, ProcessExecutorConfig } from './process-executor';
+import type { LoadConfigOptions, RuntimeCapabilities, RuntimeName } from './types';
+/**
+ * Abstract factory for creating runtime-aware infrastructure.
+ *
+ * Each runtime environment (Node/Bun, Cloudflare Workers) provides its own
+ * implementation. Consumers call {@link loadRuntimeFactory} to get the
+ * appropriate factory, then use it to create FileSystem, ProcessExecutor,
+ * and load configuration.
+ */
+export interface RuntimeFactory {
+    /** Stable runtime identity owned by the factory implementation. */
+    readonly runtimeName: RuntimeName;
+    readonly capabilities: RuntimeCapabilities;
+    /** Create a runtime-specific file system (real fs for Node/Bun, stub for CF Workers). */
+    createFileSystem(): FileSystem;
+    /** Create a runtime-specific process executor (execa-backed for Node/Bun, throws on CF Workers). */
+    createProcessExecutor(config?: ProcessExecutorConfig): ProcessExecutor;
+    /** Load config from the runtime's config backend. */
+    loadConfig(options?: LoadConfigOptions): Promise<Config>;
+}
+//# sourceMappingURL=runtime-factory.d.ts.map

package/dist/runtime-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-factory.d.ts","sourceRoot":"","sources":["../src/runtime-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAE3C,yFAAyF;IACzF,gBAAgB,IAAI,UAAU,CAAC;IAE/B,oGAAoG;IACpG,qBAAqB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,eAAe,CAAC;IAEvE,qDAAqD;IACrD,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5D"}

package/dist/runtime-node-bun.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeFactory } from './runtime-factory';
+/** @internal — reset the cached filesystem (for test isolation). */
+export declare function _resetNodeFileSystem(): void;
+/**
+ * Node.js / Bun runtime factory (filesystem, process execution, config).
+ */
+export declare const nodeBunFactory: RuntimeFactory;
+//# sourceMappingURL=runtime-node-bun.d.ts.map

package/dist/runtime-node-bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-node-bun.d.ts","sourceRoot":"","sources":["../src/runtime-node-bun.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAgB5B,CAAC"}

package/dist/runtime-node-bun.js

@@ -0,0 +1,67 @@
+import { parse as parseYaml } from 'yaml';
+import { buildConfigFromObject, getProcessEnv } from './config.js';
+import { createNodeFileSystem } from './file-system-node.js';
+import { ProcessExecutor } from './process-executor.js';
+// Lazy re-initialisable singleton for test isolation.
+let _nodeFileSystem;
+function getNodeFileSystem() {
+    if (!_nodeFileSystem)
+        _nodeFileSystem = createNodeFileSystem();
+    return _nodeFileSystem;
+}
+/** @internal — reset the cached filesystem (for test isolation). */
+export function _resetNodeFileSystem() {
+    _nodeFileSystem = undefined;
+}
+/**
+ * Node.js / Bun runtime factory (filesystem, process execution, config).
+ */
+export const nodeBunFactory = {
+    runtimeName: 'node-bun',
+    capabilities: {
+        hasFilesystem: true,
+        hasProcessExecution: true,
+        hasPersistentStorage: true,
+    },
+    createFileSystem: () => getNodeFileSystem(),
+    createProcessExecutor: (config) => new ProcessExecutor(config),
+    async loadConfig(options) {
+        return loadNodeConfig(options);
+    },
+};
+// ── Config loading (Node/Bun) ────────────────────────────────────────────
+/**
+ * Load config for Node/Bun: reads YAML from filesystem via {@link FileSystem},
+ * applies env-variable interpolation, merges overrides, and validates.
+ */
+async function loadNodeConfig(options) {
+    const fs = getNodeFileSystem();
+    const raw = readYamlConfig(fs);
+    return buildConfigFromObject(raw ?? {}, options);
+}
+/**
+ * Read and parse YAML config from filesystem.
+ *
+ * Searches common config locations in order:
+ * 1. `CONFIG_PATH` env var (absolute path)
+ * 2. `./config/config.yaml` (repo-local)
+ * 3. `./config/config.example.yaml` (fallback)
+ *
+ * Returns `null` if no config file is found.
+ */
+function readYamlConfig(fs) {
+    const candidates = [getProcessEnv().CONFIG_PATH, 'config/config.yaml', 'config/config.example.yaml'].filter((p) => typeof p === 'string' && p.length > 0);
+    for (const candidate of candidates) {
+        const resolved = fs.resolve(candidate);
+        if (fs.exists(resolved)) {
+            const content = fs.readFile(resolved);
+            try {
+                return parseYaml(content);
+            }
+            catch {
+                // Try next candidate on parse failure
+            }
+        }
+    }
+    return null;
+}

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.1",
+    "version": "0.3.2",
     "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
     "keywords": [
         "typescript",
@@ -58,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.1",
+        "@gobing-ai/ts-utils": "^0.3.2",
         "execa": "^9.5.0",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"