RuntimeAdapter
Runtime adapter interface.
Defines the minimal contract between the platform-agnostic core and the host runtime (Node.js, Bun, Deno). Every platform-dependent operation flows through this interface — the core never calls process.*, Deno.*, or Bun.* directly.
Adapters are designed to be:
Immutable in shape: all properties are readonly
Minimal: only the operations the framework actually needs
Testable: easily stubbed in tests via createTestAdapter()
Import:
@kjanat/dreamcli/runtimeExport kind: interface
Declared in:
src/runtime/adapter.tsSource link:
src/runtime/adapter.ts:39
Signatures
interface RuntimeAdapter {}Members
Properties
argv
Raw argv array (including binary + script path, e.g. ['node', 'cli.js', 'deploy']).
argv: readonly string[];configDir
Platform-specific user configuration directory (absolute path).
- Unix:
$XDG_CONFIG_HOMEor~/.config - Windows:
%APPDATA%or~\AppData\Roaming
Config discovery appends the app-specific subdirectory.
configDir: string;cwd
Current working directory (absolute path).
cwd: string;env
Environment variables. Values are string | undefined — mirrors Node's process.env semantics.
env: Readonly<Record<string, string | undefined>>;exit
Exit the process with the given code. Must not return (divergent function).
exit: { (code: number): never; };flush
Wait for pending output writes to settle, rejecting with a recorded output failure.
flush?: { (): Promise<void>; };getTerminalSize
Read current terminal dimensions for stdout, if available.
getTerminalSize: { (): TerminalSize | undefined; };homedir
User home directory (absolute path).
- Node/Bun: derived from
HOME/USERPROFILEenv - Deno:
Deno.env.get('HOME')/Deno.env.get('USERPROFILE')
homedir: string;isTTY
Whether stdout is connected to a TTY.
isTTY: boolean;mkdir
Create a directory, including missing parents.
Succeeds when the directory already exists. Throws on other I/O errors (permission denied, existing file at the path, etc.).
Used by flag.path() create checks after resolution.
mkdir: { (path: string): Promise<void>; };onTerminalResize
Subscribe to terminal resize events when the runtime supports them.
onTerminalResize: { (listener: { (): void; }): { (): void; } | undefined; };readFile
Read a file as UTF-8 text.
Returns file contents on success, null if the file does not exist (ENOENT/NotFound). Throws on other I/O errors (permission denied, is-directory, etc.) — those indicate unexpected failures, not "try the next path".
Used by config file discovery to probe multiple candidate paths.
readFile: { (path: string): Promise<string | null>; };readStdin
Read all of stdin as a single string (for piped data).
Returns the full stdin contents when data is piped (stdinIsTTY is false), or null when stdin is a TTY (no piped data available).
Used by the resolve chain for args with .stdin() configured. Unlike stdin (which reads one line for prompts), this consumes the entire stream to EOF.
readStdin: { (): Promise<string | null>; };stat
Probe what exists at a filesystem path.
Returns 'file' or 'directory' for existing paths (other kinds such as sockets report 'file'), or null when nothing exists there.
Used by flag.path() existence/type checks after resolution.
stat: { (path: string): Promise<"file" | "directory" | null>; };stderr
Writer for stderr. Framework routes out.warn/out.error through this.
stderr: WriteFn;stdin
Line reader for stdin. Used by the prompt engine for interactive input.
Returns null on EOF (Ctrl+D on Unix, Ctrl+Z on Windows), indicating the user closed the input stream (treated as cancel).
stdin: ReadFn;stdinIsTTY
Whether stdin is connected to a TTY (used for prompt gating).
stdinIsTTY: boolean;stdout
Writer for stdout. Framework routes out.log/out.info through this.
stdout: WriteFn;systemConfigDirs
System-scope config roots for discovery (['/etc'] on Linux and macOS, [] on Windows). When absent, discovery probes none.
systemConfigDirs?: readonly string[];userConfigDirs
User-scope config roots for discovery, highest priority first.
- Unix:
[configDir] - macOS:
[configDir, ~/Library/Application Support] - Windows:
[configDir]
When absent, discovery falls back to [configDir].
userConfigDirs?: readonly string[];Examples
// Production: auto-detected
cli('mycli').run(); // uses Node/Bun/Deno adapter
// Test: explicit adapter
cli('mycli').run({ adapter: createTestAdapter({ argv: ['deploy'] }) });