@gobing-ai/ts-runtime 0.3.0 → 0.3.2

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

package/src/runtime-factory.ts

@@ -0,0 +1,28 @@
+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>;
+}

package/src/runtime-node-bun.ts

@@ -0,0 +1,83 @@
+import { parse as parseYaml } from 'yaml';
+import type { Config } from './config';
+import { buildConfigFromObject, getProcessEnv } from './config';
+import type { FileSystem } from './file-system';
+import { createNodeFileSystem } from './file-system-node';
+import { ProcessExecutor, type ProcessExecutorConfig } from './process-executor';
+import type { RuntimeFactory } from './runtime-factory';
+import type { LoadConfigOptions } from './types';
+
+// Lazy re-initialisable singleton for test isolation.
+let _nodeFileSystem: FileSystem | undefined;
+function getNodeFileSystem(): FileSystem {
+    if (!_nodeFileSystem) _nodeFileSystem = createNodeFileSystem();
+    return _nodeFileSystem;
+}
+
+/** @internal — reset the cached filesystem (for test isolation). */
+export function _resetNodeFileSystem(): void {
+    _nodeFileSystem = undefined;
+}
+
+/**
+ * Node.js / Bun runtime factory (filesystem, process execution, config).
+ */
+export const nodeBunFactory: RuntimeFactory = {
+    runtimeName: 'node-bun',
+
+    capabilities: {
+        hasFilesystem: true,
+        hasProcessExecution: true,
+        hasPersistentStorage: true,
+    },
+
+    createFileSystem: () => getNodeFileSystem(),
+
+    createProcessExecutor: (config?: ProcessExecutorConfig) => new ProcessExecutor(config),
+
+    async loadConfig(options?: LoadConfigOptions): Promise<Config> {
+        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?: LoadConfigOptions): Promise<Config> {
+    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: FileSystem): Record<string, unknown> | null {
+    const candidates = [getProcessEnv().CONFIG_PATH, 'config/config.yaml', 'config/config.example.yaml'].filter(
+        (p): p is string => 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) as string;
+            try {
+                return parseYaml(content) as Record<string, unknown>;
+            } catch {
+                // Try next candidate on parse failure
+            }
+        }
+    }
+
+    return null;
+}