@gobing-ai/ts-runtime 0.3.1 → 0.3.3

package/src/path.ts

@@ -2,16 +2,42 @@
 // `cloudflare-workers` (no `node:*`) as on node-bun (ADR-008). POSIX-style separators throughout;
 // Windows drive paths (`C:/...`) are normalized and treated as absolute.
 
+/** Replaces Windows backslashes with forward slashes for consistent POSIX-style path handling. */
 export function normalizeSeparators(path: string): string {
     return path.replaceAll('\\', '/');
 }
 
+/** Platform-specific path segment separator (`'/'` on POSIX, `'\\'` on Windows). */
+export const SEP: string =
+    (globalThis as { process?: { platform?: string } }).process?.platform === 'win32' ? '\\' : '/';
+
+/** Returns `true` for POSIX absolute paths and Windows drive paths (`C:/…`). */
 export function isAbsolutePath(path: string): boolean {
     return path.startsWith('/') || /^[A-Za-z]:\//.test(normalizeSeparators(path));
 }
 
+function splitRoot(path: string): { root: string; rest: string } {
+    const normalized = normalizeSeparators(path);
+    const drive = normalized.match(/^([A-Za-z]:)(?:\/|$)/);
+    if (drive) {
+        return { root: drive[1] ?? '', rest: normalized.slice((drive[1] ?? '').length).replace(/^\/+/, '') };
+    }
+    if (normalized.startsWith('/')) {
+        return { root: '/', rest: normalized.replace(/^\/+/, '') };
+    }
+    return { root: '', rest: normalized };
+}
+
+function pathParts(path: string): { root: string; parts: string[] } {
+    const { root, rest } = splitRoot(path);
+    return { root, parts: rest.split('/').filter(Boolean) };
+}
+
+/** Returns the parent directory of a path. Platform-independent — avoids `node:path`. */
 export function dirnamePath(path: string): string {
     const input = normalizeSeparators(path);
+    const { root } = splitRoot(input);
+    if (root !== '' && input.replace(/\/+$/, '') === root) return root === '/' ? '/' : `${root}/`;
     if (/^\/+$/.test(input)) return '/';
     const normalized = input.replace(/\/+$/, '');
     if (normalized === '' || normalized === '/') return normalized || '.';
@@ -21,6 +47,39 @@ export function dirnamePath(path: string): string {
     return normalized.slice(0, index);
 }
 
+/** Return the last segment of a path. Optionally strip a trailing extension. */
+export function basenamePath(p: string, ext?: string): string {
+    const normalized = normalizeSeparators(p).replace(/\/+$/, '');
+    const index = normalized.lastIndexOf('/');
+    let base = index < 0 ? normalized : normalized.slice(index + 1);
+    if (ext !== undefined && base !== ext && base.endsWith(ext)) {
+        base = base.slice(0, -ext.length);
+    }
+    return base;
+}
+
+/** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
+export function relativePath(from: string, to: string): string {
+    const fromParsed = pathParts(resolvePath(from));
+    const toParsed = pathParts(resolvePath(to));
+    if (fromParsed.root.toLowerCase() !== toParsed.root.toLowerCase()) {
+        return resolvePath(to);
+    }
+    const fromParts = fromParsed.parts;
+    const toParts = toParsed.parts;
+
+    // Strip common prefix.
+    let i = 0;
+    const minLen = Math.min(fromParts.length, toParts.length);
+    while (i < minLen && fromParts[i] === toParts[i]) i++;
+
+    const up = fromParts.slice(i).map(() => '..');
+    const down = toParts.slice(i);
+    const result = [...up, ...down].join('/');
+    return result || '.';
+}
+
+/** Joins path segments with `/`, normalizing separators and collapsing redundant slashes. */
 export function joinPath(...segments: string[]): string {
     const filtered = segments.filter((segment) => segment.length > 0).map(normalizeSeparators);
     if (filtered.length === 0) return '.';
@@ -29,6 +88,7 @@ export function joinPath(...segments: string[]): string {
     return absolute ? joined : joined.replace(/^\//, '');
 }
 
+/** Resolves a sequence of path segments to an absolute path, collapsing `..` and `.`. */
 export function resolvePath(...segments: string[]): string {
     const candidates = segments.length === 0 ? [getProcessCwd()] : segments;
     let resolved = '';
@@ -36,19 +96,23 @@ export function resolvePath(...segments: string[]): string {
         if (segment.length === 0) continue;
         resolved = isAbsolutePath(segment) ? segment : joinPath(resolved || getProcessCwd(), segment);
     }
+    const { root, rest } = splitRoot(resolved);
     const parts: string[] = [];
-    const absolute = isAbsolutePath(resolved);
-    for (const part of resolved.split('/')) {
+    const absolute = root !== '';
+    for (const part of rest.split('/')) {
         if (part === '' || part === '.') continue;
         if (part === '..') {
-            parts.pop();
+            if (parts.length > 0) parts.pop();
             continue;
         }
         parts.push(part);
     }
-    return `${absolute ? '/' : ''}${parts.join('/')}` || (absolute ? '/' : '.');
+    if (!absolute) return parts.join('/') || '.';
+    if (root === '/') return `/${parts.join('/')}` || '/';
+    return parts.length > 0 ? `${root}/${parts.join('/')}` : `${root}/`;
 }
 
+/** Returns `process.cwd()` if available, or `/` as fallback (Cloudflare Workers). */
 export function getProcessCwd(): string {
     return (globalThis as { process?: { cwd?: () => string } }).process?.cwd?.() ?? '/';
 }

package/src/platform.ts

@@ -0,0 +1,47 @@
+import type { RuntimeFactory } from './runtime-factory';
+import type { RuntimeName } from './types';
+
+// Single authoritative source for runtime detection.
+// All other code MUST consume RuntimeFactory via loadRuntimeFactory().
+// Probe-once contract: each primitive is invoked at most once per process and
+// the result is cached in `_factory` / `_runtimeName`.
+
+/** True when running in a Cloudflare Worker (server-tier only). */
+export function isCloudflareWorkerRuntime(): boolean {
+    return globalThis.navigator?.userAgent?.startsWith('Cloudflare-Workers') ?? false;
+}
+
+let _factory: RuntimeFactory | undefined;
+let _runtimeName: RuntimeName | undefined;
+
+/**
+ * Lazy-load and cache the appropriate {@link RuntimeFactory} based on environment detection.
+ */
+export async function loadRuntimeFactory(): Promise<RuntimeFactory> {
+    if (_factory) return _factory;
+
+    let factory: RuntimeFactory;
+    if (getRuntimeName() === 'cloudflare-workers') {
+        const { cloudflareWorkersFactory } = await import('./runtime-cf');
+        factory = cloudflareWorkersFactory;
+    } else {
+        const { nodeBunFactory } = await import('./runtime-node-bun');
+        factory = nodeBunFactory;
+    }
+    _factory = factory;
+    return factory;
+}
+
+function getRuntimeName(): RuntimeName {
+    if (_runtimeName) return _runtimeName;
+    _runtimeName = isCloudflareWorkerRuntime() ? 'cloudflare-workers' : 'node-bun';
+    return _runtimeName;
+}
+
+/**
+ * Reset the cached runtime factory and name (for test isolation).
+ */
+export function _resetRuntimeFactory(): void {
+    _factory = undefined;
+    _runtimeName = undefined;
+}

package/src/process-executor.ts

@@ -1,32 +1,34 @@
 import { isatty } from 'node:tty';
 import { type Options as ExecaOptions, execa } from 'execa';
 
+// ── Types ────────────────────────────────────────────────────────────────
+
+/** Controls how stdout/stderr is captured: buffered in memory or streamed to the caller's terminal. */
 export type OutputPolicy = { mode: 'buffered' } | { mode: 'stream'; isTTY?: boolean };
 
+/** Shared configuration for a process executor (default timeout, output buffering, output policy). */
 export interface ProcessExecutorConfig {
     defaultTimeout?: number;
     defaultMaxOutput?: number;
     output?: OutputPolicy;
+    events?: ProcessEventSink;
+    tracer?: TracerPort;
 }
 
+/** Options for spawning a child process. */
 export interface ProcessOptions {
     command: string;
     args?: string[];
     cwd?: string;
-    /**
-     * Environment forwarded verbatim to the child process. Caller-controlled — when launching an
-     * untrusted command, pass an explicit allowlist rather than the parent's full environment, so
-     * inherited secrets are not leaked into the subprocess.
-     */
     env?: Record<string, string>;
     timeout?: number;
-    /** Maximum output buffer size in bytes (maps to execa `maxBuffer`). */
     maxOutput?: number;
     label?: string;
     rejectOnError?: boolean;
     forceBuffered?: boolean;
 }
 
+/** Result of a completed child process, including exit code, captured output, and duration. */
 export interface ProcessResult {
     command: string;
     args: string[];
@@ -37,22 +39,54 @@ export interface ProcessResult {
     durationMs: number;
 }
 
-export interface ProcessExecutor {
-    run(options: ProcessOptions): Promise<ProcessResult>;
+/** Reason a process completion event was emitted. */
+export type ProcessExitReason = 'exit' | 'signal' | 'timeout' | 'error';
+
+/** Payload emitted for process execution observability. */
+export interface ProcessEventDetail {
+    command: string;
+    args: string[];
+    exitCode: number | null;
+    signal?: string;
+    durationMs: number;
+    reason: ProcessExitReason;
+    timestamp: string;
+    label?: string;
+    error?: string;
+}
+
+/** Zero-dependency structural event sink for process observability. */
+export interface ProcessEventSink {
+    emit(event: 'process.started' | 'process.exited', detail: ProcessEventDetail): void;
 }
 
-export interface SyncProcessExecutor {
-    runSync(options: Omit<ProcessOptions, 'timeout'>): ProcessResult;
+/** Typed process event map, consumable by `EventBus<ProcessEvents>` in higher layers. */
+export type ProcessEvents = {
+    'process.started': (detail: ProcessEventDetail) => void;
+    'process.exited': (detail: ProcessEventDetail) => void;
+};
+
+/** Minimal structural tracing port; concrete adapters live above `ts-runtime`. */
+export interface TracerPort {
+    traceAsync<T>(name: string, fn: (span: unknown) => Promise<T>): Promise<T>;
 }
 
+/** Options for spawning a long-running interactive process. */
 export interface PipeProcessOptions {
     command: string;
     args?: string[];
     cwd?: string;
-    /** Forwarded verbatim to the child — pass an allowlist for untrusted commands (see {@link ProcessOptions.env}). */
     env?: Record<string, string>;
+    label?: string;
 }
 
+/** Signal values accepted by subprocess kill. */
+type BunSubprocess = ReturnType<typeof Bun.spawn>;
+
+/** Signal values accepted by subprocess kill (e.g. 'SIGTERM', 'SIGKILL'). */
+export type ProcessSignal = Parameters<BunSubprocess['kill']>[0];
+
+/** Handle to a running pipe process with streaming stdout/stderr and stdin write support. */
 export interface PipeProcess {
     readonly pid: number | null;
     readonly stdout: ReadableStream<Uint8Array> | null;
@@ -63,14 +97,30 @@ export interface PipeProcess {
     kill(signal?: ProcessSignal): void;
 }
 
-export interface PipeProcessSpawner {
-    spawn(options: PipeProcessOptions): PipeProcess;
-}
+// ── ProcessExecutor ───────────────────────────────────────────────────────
 
-export class NodeProcessExecutor implements ProcessExecutor {
-    constructor(private readonly config: ProcessExecutorConfig = {}) {}
+/**
+ * Runtime-agnostic process executor wrapping `execa`.
+ *
+ * Every invocation supports timeout enforcement, output capture, and
+ * configurable output policy (buffered vs streamed).
+ */
+export class ProcessExecutor {
+    private readonly config: ProcessExecutorConfig;
 
+    constructor(config: ProcessExecutorConfig = {}) {
+        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: ProcessOptions): Promise<ProcessResult> {
+        return this.trace('process.run', () => this.runUntraced(options));
+    }
+
+    private async runUntraced(options: ProcessOptions): Promise<ProcessResult> {
         const args = options.args ?? [];
         const execaOptions = buildExecaOptions({
             cwd: options.cwd,
@@ -81,10 +131,20 @@ export class NodeProcessExecutor implements ProcessExecutor {
             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,
@@ -93,74 +153,181 @@ export class NodeProcessExecutor implements ProcessExecutor {
                 ...(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 as {
                 exitCode?: number;
                 stdout?: string | string[] | Uint8Array;
                 stderr?: string | string[] | Uint8Array;
                 signalDescription?: string;
+                signal?: string;
                 durationMs?: number;
+                timedOut?: boolean;
+                message?: string;
             };
-            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;
         }
     }
-}
 
-export class BunSyncProcessExecutor implements SyncProcessExecutor {
-    runSync(options: Omit<ProcessOptions, 'timeout'>): 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: PipeProcessOptions): PipeProcess {
         const args = options.args ?? [];
-        const startedAt = Date.now();
-        const result = Bun.spawnSync({
-            cmd: [options.command, ...args],
-            stdout: 'pipe',
-            stderr: 'pipe',
-            stdin: 'ignore',
-            ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
-            ...(options.env !== undefined ? { env: options.env } : {}),
-        });
-        if (options.rejectOnError === true && result.exitCode !== 0) {
-            throw new Error(
-                `${options.command} ${args.join(' ')} failed with exit code ${result.exitCode}: ${stripFinalNewline(
-                    asString(result.stderr),
-                )}`,
-            );
+        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;
         }
-        return {
-            command: options.command,
-            args,
+    }
+
+    private async trace<T>(name: string, fn: () => Promise<T>): Promise<T> {
+        if (this.config.tracer === undefined) return await fn();
+        return await this.config.tracer.traceAsync(name, async () => await fn());
+    }
+
+    private emitExitedFromResult(
+        options: ProcessOptions,
+        result: ProcessResult,
+        completion: unknown,
+        error?: unknown,
+    ): void {
+        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,
-            stdout: stripFinalNewline(asString(result.stdout)),
-            stderr: stripFinalNewline(asString(result.stderr)),
-            durationMs: Date.now() - startedAt,
-        };
+            ...(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) } : {}),
+        });
+    }
+
+    private emitProcessEvent(event: 'process.started' | 'process.exited', detail: ProcessEventDetail): void {
+        this.config.events?.emit(event, detail);
     }
 }
 
-export class BunPipeProcessSpawner implements PipeProcessSpawner {
-    spawn(options: PipeProcessOptions): PipeProcess {
-        const subprocess = Bun.spawn({
-            cmd: [options.command, ...(options.args ?? [])],
-            stdin: 'pipe',
-            stdout: 'pipe',
-            stderr: 'pipe',
-            ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
-            ...(options.env !== undefined ? { env: options.env } : {}),
+class ObservedPipeProcess implements PipeProcess {
+    private killedWith: ProcessSignal | undefined;
+
+    readonly exited: Promise<number | null>;
+
+    constructor(
+        private readonly inner: PipeProcess,
+        events: ProcessEventSink | undefined,
+        context: {
+            command: string;
+            args: string[];
+            startedAt: number;
+            label?: string;
+        },
+    ) {
+        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;
         });
-        return new BunPipeProcess(subprocess);
+    }
+
+    get pid(): number | null {
+        return this.inner.pid;
+    }
+
+    get stdout(): ReadableStream<Uint8Array> | null {
+        return this.inner.stdout;
+    }
+
+    get stderr(): ReadableStream<Uint8Array> | null {
+        return this.inner.stderr;
+    }
+
+    writeStdin(input: string | Uint8Array): void {
+        this.inner.writeStdin(input);
+    }
+
+    endStdin(): void {
+        this.inner.endStdin();
+    }
+
+    kill(signal?: ProcessSignal): void {
+        this.killedWith = signal;
+        this.inner.kill(signal);
     }
 }
 
-type BunSubprocess = ReturnType<typeof Bun.spawn>;
-type ProcessSignal = Parameters<BunSubprocess['kill']>[0];
+// ── BunPipeProcess (internal) ─────────────────────────────────────────────
+
 type StdinSink = {
     write: (data: string | Uint8Array) => unknown;
     end?: () => unknown;
@@ -204,6 +371,69 @@ class BunPipeProcess implements PipeProcess {
     }
 }
 
+// ── 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: Omit<ProcessOptions, 'timeout'>): ProcessResult {
+        const args = options.args ?? [];
+        const startedAt = Date.now();
+        const result = Bun.spawnSync({
+            cmd: [options.command, ...args],
+            stdout: 'pipe',
+            stderr: 'pipe',
+            stdin: 'ignore',
+            ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+            ...(options.env !== undefined ? { env: options.env } : {}),
+        });
+        if (options.rejectOnError === true && result.exitCode !== 0) {
+            throw new Error(
+                `${options.command} ${args.join(' ')} failed with exit code ${result.exitCode}: ${stripFinalNewline(
+                    asString(result.stderr),
+                )}`,
+            );
+        }
+        return {
+            command: options.command,
+            args,
+            exitCode: result.exitCode,
+            stdout: stripFinalNewline(asString(result.stdout)),
+            stderr: stripFinalNewline(asString(result.stderr)),
+            durationMs: Date.now() - startedAt,
+        };
+    }
+}
+
+/**
+ * @deprecated Use {@link ProcessExecutor.runStreaming} instead.
+ * This class is kept for backward compatibility.
+ */
+export class BunPipeProcessSpawner {
+    spawn(options: PipeProcessOptions): PipeProcess {
+        const subprocess = Bun.spawn({
+            cmd: [options.command, ...(options.args ?? [])],
+            stdin: 'pipe',
+            stdout: 'pipe',
+            stderr: 'pipe',
+            ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+            ...(options.env !== undefined ? { env: options.env } : {}),
+        });
+        return new BunPipeProcess(subprocess);
+    }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
 function buildExecaOptions(opts: {
     cwd: string | undefined;
     env: Record<string, string> | undefined;
@@ -244,3 +474,11 @@ function stripFinalNewline(value: string): string {
 function isReadableStream(value: unknown): value is ReadableStream<Uint8Array> {
     return value instanceof ReadableStream;
 }
+
+function isTimedOut(error: unknown): boolean {
+    return typeof error === 'object' && error !== null && 'timedOut' in error && error.timedOut === true;
+}
+
+function errorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}

package/src/runtime-cf.ts

@@ -0,0 +1,44 @@
+import { parse as parseYaml } from 'yaml';
+import type { Config } from './config';
+import { buildConfigFromObject } from './config';
+import { createCfFileSystem } from './file-system-cf';
+import type { ProcessExecutorConfig } from './process-executor';
+import type { RuntimeFactory } from './runtime-factory';
+import type { LoadConfigOptions } from './types';
+
+/** 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: RuntimeFactory = {
+    runtimeName: 'cloudflare-workers',
+
+    capabilities: {
+        hasFilesystem: false,
+        hasProcessExecution: false,
+        hasPersistentStorage: false,
+    },
+
+    createFileSystem: () => createCfFileSystem(),
+
+    createProcessExecutor: (_config?: ProcessExecutorConfig): never => {
+        throw new Error('ProcessExecutor is not available on Cloudflare Workers.');
+    },
+
+    async loadConfig(options?: LoadConfigOptions): Promise<Config> {
+        const yamlString = options?.envBindings?.[CONFIG_YAML_BINDING] as string | undefined;
+        let raw: Record<string, unknown> = {};
+
+        if (yamlString) {
+            try {
+                raw = parseYaml(yamlString) as Record<string, unknown>;
+            } catch {
+                // Fall through to schema defaults on parse failure
+            }
+        }
+
+        return buildConfigFromObject(raw, options);
+    },
+};