@gobing-ai/ts-runtime 0.3.1 → 0.3.3

package/README.md

@@ -1,123 +1,90 @@
 # @gobing-ai/ts-runtime
 
-Runtime abstraction layer — environment detection, file system, process execution, configuration, and context management. Works on Bun/Node and Cloudflare Workers.
+Runtime abstraction layer — platform detection, file system, process execution, configuration,
+context management, path utilities, and a shared plugin/capability core. Works on Node.js, Bun,
+and Cloudflare Workers through a factory pattern that auto-detects the runtime.
+
+`ts-runtime` decouples application code from platform specifics. Instead of importing `node:fs` or `node:child_process` directly, consumers use interfaces (`FileSystem`, `ProcessExecutor`) resolved by `loadRuntimeFactory()` at startup. The factory auto-detects the platform and wires the correct implementations — `createNodeFileSystem` (real `node:fs`) for Node/Bun, `createCfFileSystem` (stub) for Workers. Node filesystem modules are loaded lazily, so importing the package remains safe for Worker bundles.
 
 ## Overview
 
-`ts-runtime` decouples application code from platform specifics. Instead of importing `node:fs` or `node:child_process` directly, consumers go through interfaces (`FileSystem`, `SyncFileSystem`, `ProcessExecutor`, `SyncProcessExecutor`, `PipeProcessSpawner`) that resolve to the correct implementation at startup based on `RuntimeContext`. Node filesystem modules are loaded lazily by `NodeFileSystem`, so importing the package remains safe for Worker bundles that select `CloudflareFileSystem`.
+
 
 **Key abstractions:**
 
 | Concept | Interface | Bun/Node impl | Cloudflare impl |
 |---------|-----------|---------------|-----------------|
-| Async file system | `FileSystem` | `NodeFileSystem` | `CloudflareFileSystem` (unsupported filesystem facade) |
-| Sync file system | `SyncFileSystem` | `NodeSyncFileSystem` | — |
-| Buffered process execution | `ProcessExecutor` | `NodeProcessExecutor` | — |
-| Sync process execution | `SyncProcessExecutor` | `BunSyncProcessExecutor` | — |
-| Pipe process spawning | `PipeProcessSpawner` | `BunPipeProcessSpawner` | — |
-| Configuration | `Config` (Zod schema) | YAML + env vars | YAML + env vars |
+| Runtime factory | `RuntimeFactory` → `loadRuntimeFactory()` | `nodeBunFactory` | `cloudflareWorkersFactory` |
+| File system | `FileSystem` | `createNodeFileSystem()` (sync `node:fs`) | `createCfFileSystem()` (stub) |
+| Process execution | `ProcessExecutor` (class) | `run()` via execa, `runStreaming()` via `Bun.spawn` | throws |
+| Configuration | `Config` (Zod schema) | YAML + env vars | CONFIG_YAML blob + env vars |
 | Context | `RuntimeContext` | service locator | service locator |
+| Path utilities | `SEP`, `basenamePath`, `dirnamePath`, `joinPath`, `resolvePath`, `relativePath`, … | runtime-portable (zero `node:*`) | runtime-portable (zero `node:*`) |
+| Schema validation | `loadStructuredConfig` | JSON-Schema + YAML | JSON-Schema + YAML |
+| Plugin core (`./plugin`) | `CapabilityRegistry`, `loadExtensionModules` | trust-gated module loading | — |
 | Tracing | `SpanContext` | `{ traceId, spanId }` | `{ traceId, spanId }` |
 
 ## Architecture
 
 ```mermaid
 classDiagram
-    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 {
+    class RuntimeFactory {
         <<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~
+        +string runtimeName
+        +RuntimeCapabilities capabilities
+        +createFileSystem() FileSystem
+        +createProcessExecutor() ProcessExecutor
+        +loadConfig() Promise~Config~
     }
 
-    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 nodeBunFactory {
+        +string runtimeName
+        +createFileSystem() createNodeFileSystem()
+        +createProcessExecutor() ProcessExecutor
+        +loadConfig() Promise~Config~
     }
 
-    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 cloudflareWorkersFactory {
+        +string runtimeName
+        +createFileSystem() createCfFileSystem()
+        +createProcessExecutor() never
+        +loadConfig() Promise~Config~
     }
 
-    class SyncFileSystem {
+    class FileSystem {
         <<interface>>
-        +readFile(path) string
-        +writeFile(path, content) void
-        +mkdir(path) void
-        +readDir(path) string[]
-        +unlink(path) void
+        +exists(path) boolean~|~Promise~boolean~
+        +readFile(path) string~|~Promise~string~
+        +writeFile(path, content) void~|~Promise~void~
+        +ensureDir(path) void~|~Promise~void~
+        +readDir(path) string[]~|~Promise~string[]~
+        +deleteFile(path) void~|~Promise~void~
+        +stat(path) FileStat~|~null~|~Promise~FileStat|~
+        +resolve(...segments) string
+        +getProjectRoot() string
     }
 
-    class NodeSyncFileSystem {
+    class createNodeFileSystem {
         +readFile(path) string
         +writeFile(path, content) void
-        +mkdir(path) void
-        +readDir(path) string[]
-        +unlink(path) void
+        +exists(path) boolean
+        +ensureDir(path) void
+        +stat(path) FileStat | null
+        +getProjectRoot() string
     }
 
-    class ProcessExecutor {
-        <<interface>>
-        +run(options) Promise~ProcessResult~
+    class createCfFileSystem {
+        +readFile(path) never
+        +writeFile(path, content) never
+        +exists(path) false
+        +ensureDir(path) void
+        +stat(path) null
+        +getProjectRoot() '/bundle'
     }
 
-    class NodeProcessExecutor {
+    class ProcessExecutor {
         +run(options) Promise~ProcessResult~
-    }
-
-    class SyncProcessExecutor {
-        <<interface>>
-        +runSync(options) ProcessResult
-    }
-
-    class BunSyncProcessExecutor {
-        +runSync(options) ProcessResult
-    }
-
-    class PipeProcessSpawner {
-        <<interface>>
-        +spawn(options) PipeProcess
-    }
-
-    class BunPipeProcessSpawner {
-        +spawn(options) PipeProcess
+        +runStreaming(options) PipeProcess
     }
 
     class PipeProcess {
@@ -131,6 +98,17 @@ classDiagram
         +kill(signal?) void
     }
 
+    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 Config {
         +AppConfig app
         +DatabaseConfig database
@@ -145,13 +123,14 @@ classDiagram
         +Record~string,string|number|boolean~ attributes?
     }
 
-    FileSystem <|.. NodeFileSystem : implements
-    FileSystem <|.. CloudflareFileSystem : implements
-    SyncFileSystem <|.. NodeSyncFileSystem : implements
-    ProcessExecutor <|.. NodeProcessExecutor : implements
-    SyncProcessExecutor <|.. BunSyncProcessExecutor : implements
-    PipeProcessSpawner <|.. BunPipeProcessSpawner : implements
-    BunPipeProcessSpawner --> PipeProcess : creates
+    RuntimeFactory <|.. nodeBunFactory : implements
+    RuntimeFactory <|.. cloudflareWorkersFactory : implements
+    FileSystem <|.. createNodeFileSystem : implements
+    FileSystem <|.. createCfFileSystem : implements
+    ProcessExecutor --> PipeProcess : creates
+    nodeBunFactory --> createNodeFileSystem : creates
+    nodeBunFactory --> ProcessExecutor : creates
+    cloudflareWorkersFactory --> createCfFileSystem : creates
     RuntimeContext --> FileSystem : "fileSystem"
     RuntimeContext --> Config : "config"
     RuntimeContext --> ProcessExecutor : "processExecutor"
@@ -161,20 +140,29 @@ classDiagram
 
 ### 1. Runtime selection
 
-The active `FileSystem` is a process-global swapped via `setFileSystem` (default: `NodeFileSystem`);
-`getFs()` returns it. A `RuntimeContext` is constructed directly with the scope, capabilities, and
-services for the current environment — there is no factory abstraction (see ADR-008):
+`loadRuntimeFactory()` auto-detects the platform and returns a factory that creates the correct
+FileSystem, ProcessExecutor, and Config. Use `createRuntimeContextFromFactory()` to wire
+everything automatically:
+
+```ts
+import { createRuntimeContextFromFactory } from '@gobing-ai/ts-runtime';
+
+const ctx = await createRuntimeContextFromFactory();
+// ctx.runtimeName → 'node-bun' (auto-detected)
+// ctx.capabilities → { hasFilesystem: true, hasProcessExecution: true }
+// ctx.require('fileSystem') → NodeFileSystem
+// ctx.require('config') → Config from config.yaml
+```
+
+For manual control or synchronous code, `createRuntimeContext()` is still available
+(deprecated — kept for backward compatibility):
 
 ```ts
 import { createRuntimeContext } from '@gobing-ai/ts-runtime';
 
 const ctx = createRuntimeContext({
     runtimeName: 'node-bun',
-    capabilities: {
-        hasFilesystem: true,
-        hasProcessExecution: true,
-        hasPersistentStorage: true,
-    },
+    capabilities: { hasFilesystem: true, hasProcessExecution: true, hasPersistentStorage: true },
 });
 ```
 
@@ -258,35 +246,132 @@ await loadStructuredConfig('rules.yaml', { fetch: myFetch });           // or in
 > `node_modules` keeps validation entirely local — no outbound request, no dependency on a schema host's
 > availability, and no chance for a malicious config to point validation at an internal URL.
 
-### 5. File system abstraction
 
-Most file operations go through the async `FileSystem` interface. Swap implementations for testing:
+### 5. Path utilities
+
+Runtime-portable path math that avoids `node:path` so the same logic works on Cloudflare Workers
+(ADR-008). All functions use POSIX-style separators; Windows drive paths are normalized and treated
+as absolute.
+
+```ts
+import {
+    SEP, basenamePath, dirnamePath, isAbsolutePath,
+    joinPath, normalizeSeparators, relativePath, resolvePath,
+    getProcessCwd,
+} from '@gobing-ai/ts-runtime';
+
+normalizeSeparators('C:\\Users\\x\\file');  // 'C:/Users/x/file'
+SEP;                                          // '/' on POSIX, '\\' on Windows
+isAbsolutePath('/abs');                       // true
+dirnamePath('/a/b/c.ts');                     // '/a/b'
+basenamePath('/a/b/c.ts');                    // 'c.ts'
+basenamePath('/a/b/c.ts', '.ts');            // 'c'
+joinPath('/a', 'b', 'c');                     // '/a/b/c'
+resolvePath('/a/b', '../c');                  // '/a/c'
+relativePath('/a/x', '/a/y');                 // '../y'
+getProcessCwd();                              // process.cwd() or '/' on Workers
+```
+
+### 6. Plugin core (`@gobing-ai/ts-runtime/plugin`)
+
+The `./plugin` subpath exposes a generic, domain-agnostic plugin/capability core used by both
+`ts-rule-engine` and `ts-dual-workflow-engine` (ADR-010). It shares the mechanism — a typed registry
+with origin metadata, a trust-gated extension loader, and a path guard — without knowing anything
+about evaluators, resolvers, actions, or guards. Each engine owns its domain-specific kinds,
+schemas, error types, and override semantics.
+#### Capability registry
 
 ```ts
-import { getFs } from '@gobing-ai/ts-runtime';
+import { CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';
+
+interface Widget { execute(): void; }
+const registry = new CapabilityRegistry<Widget>('widget');
 
-const fs = getFs();
-await fs.writeFile('output.json', JSON.stringify(data));
-const content = await fs.readFile('output.json');
+// Register built-ins and extensions with origin metadata.
+registry.register('core', coreWidget, 'builtin');
+registry.register('ext',  extWidget,  'extension');   // default
+
+registry.has('core');          // true
+registry.list();               // ['core', 'ext']          (insertion order)
+registry.get('core').execute(); // ok
+registry.get('missing');        // throws: Unknown widget: missing
+
+// Introspect origin without throwing.
+registry.getEntry('core')?.origin;   // 'builtin'
+registry.entries();                   // [['core', { capability, origin: 'builtin' }], ...]
 ```
 
-Use `SyncFileSystem` only for APIs that must stay synchronous, such as config discovery at module
-boundaries or compatibility wrappers. The sync seam still keeps direct `node:fs` access inside
-`ts-runtime`.
+#### Extension loading (trust-gated)
+
+Extension modules are arbitrary code — the loader is disabled by default and fails closed:
+
+```ts
+import { loadExtensionModules, type ExtensionRef } from '@gobing-ai/ts-runtime/plugin';
+
+const refs: ExtensionRef<'actions'>[] = [{
+    kind: 'actions',
+    path: './ext/slack.ts',
+    baseDir: '/abs/path/to/configs',
+    sourceName: 'my-config',
+}];
+
+// Throws before any import: "declares actions extension … but extensions are disabled"
+await loadExtensionModules(refs, { moduleLoader: (p) => import(p) }, register);
+
+// Explicitly opt in.
+await loadExtensionModules(refs, {
+    allowExtensions: true,
+    moduleLoader: (p) => import(p),
+}, (ref, extension) => {
+    // Engine-provided callback — the loader never chooses a target registry.
+    myHost.actions.register(extension.name, extension, 'extension');
+});
+```
+
+The loader validates both the default export and the named `extension` export. Invalid modules
+throw with source name, kind, and path context. `moduleLoader` is required — the shared core has
+no ambient `import()` capability of its own.
+
+#### Path guard
+
+`assertRelativeExtensionPath` rejects absolute paths and `..` traversal at load time, independent
+of any engine's zod schema (defense in depth):
 
 ```ts
-import { NodeSyncFileSystem } from '@gobing-ai/ts-runtime';
+import { assertRelativeExtensionPath } from '@gobing-ai/ts-runtime/plugin';
 
-const fs = new NodeSyncFileSystem();
-fs.writeFile('agents/coder.yaml', 'id: coder\n');
-const files = fs.readDir('agents');
+assertRelativeExtensionPath('./ext/my.ts');    // ok
+assertRelativeExtensionPath('/etc/evil.ts');   // throws: must be relative
+assertRelativeExtensionPath('../escape.ts');   // throws: must not contain ".."
 ```
 
-### 6. Graceful disposal
+### 7. File system abstraction
 
-`RuntimeContext.dispose()` calls `dispose()` on every registered service that implements the pattern:
+Use `createNodeFileSystem()` for a real `node:fs`-backed filesystem (Node/Bun) or
+`createCfFileSystem()` for a Cloudflare Workers stub:
 
 ```ts
+import { createNodeFileSystem, createCfFileSystem } from '@gobing-ai/ts-runtime';
+
+// Node.js / Bun — real filesystem (sync node:fs)
+const fs = createNodeFileSystem('/path/to/project');
+const content = fs.readFile('src/index.ts');     // string
+fs.writeFile('output.json', JSON.stringify(data));
+fs.ensureDir('tmp/cache');                       // recursive mkdir
+
+// Cloudflare Workers — stub (throws on mutating ops)
+const cffs = createCfFileSystem();
+cffs.getProjectRoot();   // '/bundle'
+cffs.readFile('/x');     // throws: "use D1, KV, or R2"
+```
+
+The old `getFs()` / `setFileSystem` global swap and `SyncFileSystem` are marked `@deprecated` —
+use `createNodeFileSystem()` or `ctx.require('fileSystem')` instead.
+
+### 8. Graceful disposal
+
+`RuntimeContext.dispose()` calls `dispose()` on every registered service that implements the pattern:
+
 process.on('SIGTERM', async () => {
     await ctx.dispose();
     process.exit(0);
@@ -301,39 +386,27 @@ process.on('SIGTERM', async () => {
 bun add @gobing-ai/ts-runtime
 ```
 
-### Basic setup (Bun/Node)
+### Basic setup (Node/Bun)
 
 ```ts
-import { createRuntimeContext, getFs, NodeFileSystem } from '@gobing-ai/ts-runtime';
-
-const ctx = createRuntimeContext({
-    runtimeName: 'node-bun',
-    services: {
-        fileSystem: new NodeFileSystem(),
-    },
-});
+import { createRuntimeContextFromFactory } from '@gobing-ai/ts-runtime';
 
+const ctx = await createRuntimeContextFromFactory();
 const fs = ctx.require('fileSystem');
-await fs.writeFile('hello.txt', 'Hello, world!');
+fs.writeFile('hello.txt', 'Hello, world!');
 ```
 
 ### Cloudflare Workers
 
 ```ts
-import { createRuntimeContext, CloudflareFileSystem } from '@gobing-ai/ts-runtime';
+import { createCfFileSystem, createRuntimeContext } 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(),
-            },
+            capabilities: { hasFilesystem: false, hasProcessExecution: false, hasPersistentStorage: false },
+            services: { fileSystem: createCfFileSystem() },
         });
         // ...
     },
@@ -348,6 +421,15 @@ import { buildConfigFromYaml, buildConfigFromObject } from '@gobing-ai/ts-runtim
 // 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:' },
+});
+```
+// From YAML file
+const config = buildConfigFromYaml(yamlText);
+
 // From plain object (programmatic config)
 const config = buildConfigFromObject({
     app: { name: 'api', env: 'production', port: 3000 },
@@ -357,14 +439,14 @@ const config = buildConfigFromObject({
 
 ### Process execution
 
-`NodeProcessExecutor` is the default buffered async executor. It returns a `ProcessResult` and only
-throws on non-zero exits when `rejectOnError` is set.
+`ProcessExecutor` is a single class wrapping `execa` (buffered) and `Bun.spawn` (streaming):
 
 ```ts
-import { NodeProcessExecutor } from '@gobing-ai/ts-runtime';
+import { ProcessExecutor } from '@gobing-ai/ts-runtime';
 
-const exec = new NodeProcessExecutor({ defaultTimeout: 30_000 });
+const exec = new ProcessExecutor({ defaultTimeout: 30_000 });
 
+// Buffered — captures stdout/stderr, no throw on non-zero
 const result = await exec.run({
     command: 'git',
     args: ['status', '--short'],
@@ -372,49 +454,25 @@ const result = await exec.run({
     rejectOnError: true,
 });
 
-console.log(result.stdout);
+console.log(result.stdout);          // 'M src/index.ts\n'
 console.log(`Duration: ${result.durationMs}ms`);
-```
-
-Use `BunSyncProcessExecutor` for synchronous command probes where the caller needs an immediate
-result, for example checking git state while building a prompt preamble.
-
-```ts
-import { BunSyncProcessExecutor } from '@gobing-ai/ts-runtime';
 
-const exec = new BunSyncProcessExecutor();
-
-const branch = exec.runSync({
-    command: 'git',
-    args: ['branch', '--show-current'],
-    cwd: '/path/to/repo',
-    rejectOnError: false,
-});
-
-if (branch.exitCode === 0) {
-    console.log(branch.stdout);
-}
+// Streaming — interactive subprocess with stdin control
+const proc = exec.runStreaming({ command: 'cat' });
+proc.writeStdin('hello\n');
+proc.endStdin();
+const exitCode = await proc.exited; // 0
 ```
 
-Use `BunPipeProcessSpawner` when the host needs a long-running subprocess with writable stdin and
-readable stdout/stderr streams. This is the primitive used by team-mode agent processes.
+`rejectOnError: true` throws on non-zero exits. `OutputPolicy` controls
+buffered vs streamed output. `ProcessOptions` supports timeout, env, cwd,
+maxOutput, and forceBuffered.
 
-```ts
-import { BunPipeProcessSpawner } from '@gobing-ai/ts-runtime';
-
-const process = new BunPipeProcessSpawner().spawn({
-    command: 'codex',
-    args: ['exec', 'Wait for task messages.'],
-    cwd: '/path/to/repo',
-});
-
-process.writeStdin('[task from=operator id=msg-1] Inspect packages/runtime\n');
-process.endStdin();
-
-const exitCode = await process.exited;
-```
+Cloudflare Workers do not expose process execution; check
+`factory.capabilities.hasProcessExecution` first.
 
-Cloudflare Workers do not expose process execution; do not register process executors there.
+Old classes (`NodeProcessExecutor`, `BunSyncProcessExecutor`, `BunPipeProcessSpawner`)
+are kept as deprecated backward-compatible wrappers.
 
 ### SpanContext (for telemetry)
 

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { type ZodIssue, z } from 'zod';
+/** Zod schema for the application configuration object, providing defaults for app, database, and logging sections. */
 export declare const configSchema: z.ZodObject<{
     app: z.ZodDefault<z.ZodObject<{
         name: z.ZodDefault<z.ZodString>;
@@ -28,6 +29,7 @@ export declare const configSchema: z.ZodObject<{
         json: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/** Inferred TypeScript type of a validated configuration object, derived from {@link configSchema}. */
 export type Config = z.output<typeof configSchema>;
 /** Raised when a YAML text cannot be parsed as a plain object. */
 export declare class YamlParseError extends Error {
@@ -38,21 +40,32 @@ export declare class YamlParseError extends Error {
 export declare function parseYamlObject(text: string): Record<string, unknown>;
 /** Serialize a plain object to a YAML string. */
 export declare function stringifyYamlObject(value: Record<string, unknown>): string;
+/** Error thrown when configuration validation fails, carrying the Zod validation issues for diagnostics. */
 export declare class ConfigLoadError extends Error {
     readonly issues: ZodIssue[];
     constructor(message: string, issues?: ZodIssue[]);
 }
+/** Returns the value of `process.env.NODE_ENV`, or `"development"` as default. Node/Bun only. */
 export declare function getNodeEnv(): string;
+/** Returns `true` when `NODE_ENV` is `"test"`. Node/Bun only. */
 export declare function isTestEnv(): boolean;
+/** Returns `process.env` as a plain object. Node/Bun only. */
 export declare function getProcessEnv(): Record<string, string | undefined>;
+/** Returns `process.env.DATABASE_URL`, or `undefined` if not set. Node/Bun only. */
 export declare function getDatabaseUrl(): string | undefined;
+/** Returns the user's home directory (`HOME`, falling back to `USERPROFILE` on Windows), or `undefined` if unset. Node/Bun only. */
+export declare function getHomeDir(): string | undefined;
 /** Node-bun only: interpolates `${VAR}` from `process.env` (see note above). */
 export declare function interpolateEnv(value: string): string;
+/** Recursively interpolates `${VAR}` environment variables in all string leaves of a nested object or array. Node/Bun only. */
 export declare function interpolateTree(value: unknown): unknown;
+/** Interpolates env vars, merges overrides, validates against {@link configSchema}, and returns a frozen {@link Config}. */
 export declare function buildConfigFromObject(raw: Record<string, unknown>, options?: {
     overrides?: Partial<Config>;
 }): Config;
+/** Parses a YAML configuration string into a raw object, throwing {@link ConfigLoadError} on failure. */
 export declare function parseConfigYaml(yamlText: string): Record<string, unknown>;
+/** Parses YAML text and builds a validated {@link Config}, equivalent to `buildConfigFromObject(parseConfigYaml(…))`. */
 export declare function buildConfigFromYaml(yamlText: string, options?: {
     overrides?: Partial<Config>;
 }): Config;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,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,kEAAkE;AAClE,qBAAa,cAAe,SAAQ,KAAK;IAGjC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO;gBAD7B,OAAO,EAAE,MAAM,EACN,UAAU,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAerE;AAED,iDAAiD;AACjD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE1E;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,EAAO;CAKvD;AAKD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAElE;AAED,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOvD;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,CAOzE;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAAO,GAAG,MAAM,CAE3G"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEvC,uHAAuH;AACvH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsBvB,CAAC;AAEH,uGAAuG;AACvG,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAInD,kEAAkE;AAClE,qBAAa,cAAe,SAAQ,KAAK;IAGjC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO;gBAD7B,OAAO,EAAE,MAAM,EACN,UAAU,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAerE;AAED,iDAAiD;AACjD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE1E;AAED,4GAA4G;AAC5G,qBAAa,eAAgB,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,EAAO;CAKvD;AAKD,iGAAiG;AACjG,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AACD,iEAAiE;AACjE,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAElE;AAED,oFAAoF;AACpF,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAED,oIAAoI;AACpI,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAE/C;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,+HAA+H;AAC/H,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOvD;AACD,4HAA4H;AAC5H,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;AACD,yGAAyG;AACzG,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzE;AACD,yHAAyH;AACzH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAAO,GAAG,MAAM,CAE3G"}