@gobing-ai/ts-runtime 0.3.0 → 0.3.2

package/dist/plugin/index.js

@@ -0,0 +1,3 @@
+export * from './capability-registry.js';
+export * from './extension-loader.js';
+export * from './extension-path.js';

package/dist/plugin.d.ts

@@ -0,0 +1,2 @@
+export * from './plugin/index';
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/plugin.js

@@ -0,0 +1 @@
+export * from './plugin/index.js';

package/dist/process-executor.d.ts

@@ -1,31 +1,31 @@
+/** 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[];
@@ -35,19 +35,46 @@ export interface ProcessResult {
     signal?: string;
     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;
 }
-export interface SyncProcessExecutor {
-    runSync(options: Omit<ProcessOptions, 'timeout'>): ProcessResult;
+/** Zero-dependency structural event sink for process observability. */
+export interface ProcessEventSink {
+    emit(event: 'process.started' | 'process.exited', detail: ProcessEventDetail): void;
+}
+/** 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;
@@ -57,21 +84,52 @@ export interface PipeProcess {
     endStdin(): void;
     kill(signal?: ProcessSignal): void;
 }
-export interface PipeProcessSpawner {
-    spawn(options: PipeProcessOptions): PipeProcess;
-}
-export declare class NodeProcessExecutor implements ProcessExecutor {
+/**
+ * Runtime-agnostic process executor wrapping `execa`.
+ *
+ * Every invocation supports timeout enforcement, output capture, and
+ * configurable output policy (buffered vs streamed).
+ */
+export declare class ProcessExecutor {
     private readonly config;
     constructor(config?: ProcessExecutorConfig);
+    /**
+     * Run a command, buffered by default. Returns a structured {@link ProcessResult}.
+     * Does NOT throw on non-zero exit codes unless `rejectOnError` is set.
+     */
     run(options: ProcessOptions): Promise<ProcessResult>;
+    private runUntraced;
+    /**
+     * 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;
+    private trace;
+    private emitExitedFromResult;
+    private emitProcessEvent;
 }
-export declare class BunSyncProcessExecutor implements SyncProcessExecutor {
+/**
+ * @deprecated Use {@link ProcessExecutor} directly.
+ * This subclass is kept for backward compatibility.
+ */
+export declare 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 declare class BunSyncProcessExecutor {
     runSync(options: Omit<ProcessOptions, 'timeout'>): ProcessResult;
 }
-export declare class BunPipeProcessSpawner implements PipeProcessSpawner {
+/**
+ * @deprecated Use {@link ProcessExecutor.runStreaming} instead.
+ * This class is kept for backward compatibility.
+ */
+export declare class BunPipeProcessSpawner {
     spawn(options: PipeProcessOptions): PipeProcess;
 }
-type BunSubprocess = ReturnType<typeof Bun.spawn>;
-type ProcessSignal = Parameters<BunSubprocess['kill']>[0];
 export {};
 //# sourceMappingURL=process-executor.d.ts.map

package/dist/process-executor.d.ts.map

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

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