@gobing-ai/ts-runtime 0.1.0

package/src/fs.ts

@@ -0,0 +1,239 @@
+import { createWriteStream, mkdirSync } from 'node:fs';
+import {
+    access,
+    appendFile,
+    cp,
+    mkdir,
+    readdir,
+    readFile,
+    realpath,
+    rename,
+    rm,
+    stat,
+    writeFile,
+} from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+export interface FileStat {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    size: number;
+    mtimeMs: number;
+}
+
+export interface LogStream {
+    write(chunk: string): void;
+    end(): void;
+}
+
+export interface FileSystem {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    appendFile(path: string, content: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readDir(path: string): Promise<string[]>;
+    unlink(path: string): Promise<void>;
+    stat(path: string): Promise<FileStat | null>;
+    realpath(path: string): Promise<string>;
+    copy(src: string, dest: string): Promise<void>;
+    rename(src: string, dest: string): Promise<void>;
+    createLogStream(path: string): LogStream;
+}
+
+export class NodeFileSystem implements FileSystem {
+    async readFile(path: string): Promise<string> {
+        return await readFile(path, 'utf-8');
+    }
+
+    async writeFile(path: string, content: string): Promise<void> {
+        await ensureDirForFile(path, this);
+        await writeFile(path, content, 'utf-8');
+    }
+
+    async appendFile(path: string, content: string): Promise<void> {
+        await ensureDirForFile(path, this);
+        await appendFile(path, content, 'utf-8');
+    }
+
+    async mkdir(path: string): Promise<void> {
+        await mkdir(path, { recursive: true });
+    }
+
+    async exists(path: string): Promise<boolean> {
+        try {
+            await access(path);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async readDir(path: string): Promise<string[]> {
+        return await readdir(path);
+    }
+
+    async unlink(path: string): Promise<void> {
+        await rm(path, { recursive: true, force: true });
+    }
+
+    async stat(path: string): Promise<FileStat | null> {
+        try {
+            const value = await stat(path);
+            return {
+                isFile: () => value.isFile(),
+                isDirectory: () => value.isDirectory(),
+                size: value.size,
+                mtimeMs: value.mtimeMs,
+            };
+        } catch {
+            return null;
+        }
+    }
+
+    async realpath(path: string): Promise<string> {
+        return await realpath(path);
+    }
+
+    async copy(src: string, dest: string): Promise<void> {
+        await cp(src, dest, { recursive: true });
+    }
+
+    async rename(src: string, dest: string): Promise<void> {
+        await rename(src, dest);
+    }
+
+    createLogStream(path: string): LogStream {
+        mkdirSync(dirname(path), { recursive: true });
+        return createWriteStream(path, { flags: 'a' });
+    }
+}
+
+const CLOUDFLARE_FS_ERROR = 'FileSystem is not available on Cloudflare Workers. Use D1, KV, or R2.';
+
+export class CloudflareFileSystem implements FileSystem {
+    async readFile(path: string): Promise<string> {
+        throw unsupportedCloudflareFs('readFile', path);
+    }
+
+    async writeFile(path: string, _content: string): Promise<void> {
+        throw unsupportedCloudflareFs('writeFile', path);
+    }
+
+    async appendFile(path: string, _content: string): Promise<void> {
+        throw unsupportedCloudflareFs('appendFile', path);
+    }
+
+    async mkdir(_path: string): Promise<void> {
+        return;
+    }
+
+    async exists(_path: string): Promise<boolean> {
+        return false;
+    }
+
+    async readDir(path: string): Promise<string[]> {
+        throw unsupportedCloudflareFs('readDir', path);
+    }
+
+    async unlink(path: string): Promise<void> {
+        throw unsupportedCloudflareFs('unlink', path);
+    }
+
+    async stat(_path: string): Promise<FileStat | null> {
+        return null;
+    }
+
+    async realpath(path: string): Promise<string> {
+        return resolveProjectPath(path);
+    }
+
+    async copy(src: string, _dest: string): Promise<void> {
+        throw unsupportedCloudflareFs('copy', src);
+    }
+
+    async rename(src: string, _dest: string): Promise<void> {
+        throw unsupportedCloudflareFs('rename', src);
+    }
+
+    createLogStream(path: string): LogStream {
+        throw unsupportedCloudflareFs('createLogStream', path);
+    }
+}
+
+function unsupportedCloudflareFs(operation: string, path: string): Error {
+    return new Error(`CloudflareFileSystem.${operation} failed for "${path}": ${CLOUDFLARE_FS_ERROR}`);
+}
+
+let activeFileSystem: FileSystem = new NodeFileSystem();
+
+export function setFileSystem(fileSystem: FileSystem): () => void {
+    const previous = activeFileSystem;
+    activeFileSystem = fileSystem;
+    return () => {
+        activeFileSystem = previous;
+    };
+}
+
+export function getFs(): FileSystem {
+    return activeFileSystem;
+}
+
+export async function ensureDirForFile(path: string, fs = getFs()): Promise<void> {
+    await fs.mkdir(dirname(path));
+}
+
+export async function atomicWriteFile(path: string, content: string, fs = getFs()): Promise<void> {
+    await ensureDirForFile(path, fs);
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(tempPath, content);
+    await fs.rename(tempPath, path);
+}
+
+export async function atomicWriteJson(path: string, value: unknown, fs = getFs()): Promise<void> {
+    await atomicWriteFile(path, `${JSON.stringify(value, null, 2)}\n`, fs);
+}
+
+export async function readJsonFile<T = unknown>(path: string, fs = getFs()): Promise<T> {
+    return JSON.parse(await fs.readFile(path)) as T;
+}
+
+export async function writeJsonFile(path: string, value: unknown, fs = getFs()): Promise<void> {
+    await fs.writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function walkDir(path: string, fs = getFs()): Promise<string[]> {
+    const entries = (await fs.readDir(path)).sort();
+    const result: string[] = [];
+    for (const entry of entries) {
+        const fullPath = join(path, entry);
+        const entryStat = await fs.stat(fullPath);
+        if (entryStat?.isDirectory()) {
+            result.push(...(await walkDir(fullPath, fs)));
+        } else if (entryStat?.isFile()) {
+            result.push(fullPath);
+        }
+    }
+    return result;
+}
+
+export function getProjectRoot(startDir = process.cwd()): string {
+    let current = resolve(startDir);
+    for (let i = 0; i < 12; i++) {
+        if (Bun.file(join(current, 'bun.lock')).size !== 0 || Bun.file(join(current, 'package.json')).size !== 0) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) return startDir;
+        current = parent;
+    }
+    return startDir;
+}
+
+export function resolveProjectPath(...segments: string[]): string {
+    return resolve(getProjectRoot(), ...segments);
+}
+
+export function createLogStream(path: string, fs = getFs()): LogStream {
+    return fs.createLogStream(path);
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './config';
+export * from './context';
+export * from './fs';
+export * from './process-executor';
+export * from './types';

package/src/process-executor.ts

@@ -0,0 +1,118 @@
+import { isatty } from 'node:tty';
+import { type Options as ExecaOptions, execa } from 'execa';
+
+export type OutputPolicy = { mode: 'buffered' } | { mode: 'stream'; isTTY?: boolean };
+
+export interface ProcessExecutorConfig {
+    defaultTimeout?: number;
+    defaultMaxOutput?: number;
+    output?: OutputPolicy;
+}
+
+export interface ProcessOptions {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    /** Maximum output buffer size in bytes (maps to execa `maxBuffer`). */
+    maxOutput?: number;
+    label?: string;
+    rejectOnError?: boolean;
+    forceBuffered?: boolean;
+}
+
+export interface ProcessResult {
+    command: string;
+    args: string[];
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    signal?: string;
+    durationMs: number;
+}
+
+export interface ProcessExecutor {
+    run(options: ProcessOptions): Promise<ProcessResult>;
+}
+
+export class NodeProcessExecutor implements ProcessExecutor {
+    constructor(private readonly config: ProcessExecutorConfig = {}) {}
+
+    async run(options: ProcessOptions): Promise<ProcessResult> {
+        const args = options.args ?? [];
+        const execaOptions = buildExecaOptions({
+            cwd: options.cwd,
+            env: options.env,
+            timeout: options.timeout ?? this.config.defaultTimeout,
+            maxOutput: options.maxOutput ?? this.config.defaultMaxOutput,
+            rejectOnError: options.rejectOnError ?? false,
+            outputPolicy: this.config.output,
+            forceBuffered: options.forceBuffered ?? false,
+        });
+
+        try {
+            const result = await execa(options.command, args, execaOptions);
+            return {
+                command: options.command,
+                args,
+                exitCode: result.exitCode ?? null,
+                stdout: asString(result.stdout),
+                stderr: asString(result.stderr),
+                ...(result.signalDescription !== undefined ? { signal: result.signalDescription } : {}),
+                durationMs: result.durationMs,
+            };
+        } catch (error) {
+            if (options.rejectOnError) throw error;
+            const failed = error as {
+                exitCode?: number;
+                stdout?: string | string[] | Uint8Array;
+                stderr?: string | string[] | Uint8Array;
+                signalDescription?: string;
+                durationMs?: number;
+            };
+            return {
+                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,
+            };
+        }
+    }
+}
+
+function buildExecaOptions(opts: {
+    cwd: string | undefined;
+    env: Record<string, string> | undefined;
+    timeout: number | undefined;
+    maxOutput: number | undefined;
+    rejectOnError: boolean;
+    outputPolicy: OutputPolicy | undefined;
+    forceBuffered: boolean;
+}): ExecaOptions {
+    const canStream =
+        !opts.forceBuffered &&
+        opts.outputPolicy?.mode === 'stream' &&
+        (opts.outputPolicy.isTTY ?? process.stdout.isTTY ?? isatty(1));
+
+    return {
+        reject: opts.rejectOnError,
+        stdin: 'ignore',
+        stripFinalNewline: true,
+        ...(canStream ? { stdout: ['inherit', 'pipe'] as const, stderr: ['inherit', 'pipe'] as const } : { all: true }),
+        ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        ...(opts.env !== undefined ? { env: opts.env } : {}),
+        ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
+        ...(opts.maxOutput !== undefined ? { maxBuffer: opts.maxOutput } : {}),
+    };
+}
+
+function asString(value: string | string[] | unknown[] | Uint8Array | undefined): string {
+    if (typeof value === 'string') return value;
+    if (value instanceof Uint8Array) return new TextDecoder().decode(value);
+    if (Array.isArray(value)) return value.map(String).join('');
+    return '';
+}

package/src/types.ts

@@ -0,0 +1,31 @@
+import type { Config } from './config';
+import type { RuntimeContext } from './context';
+import type { FileSystem } from './fs';
+
+export type RuntimeName = 'node-bun' | 'cloudflare-workers' | 'test';
+
+export interface RuntimeCapabilities {
+    readonly hasFilesystem: boolean;
+    readonly hasProcessExecution: boolean;
+    readonly hasPersistentStorage: boolean;
+}
+
+export interface LoadConfigOptions {
+    overrides?: Partial<Config>;
+    envBindings?: Record<string, unknown>;
+}
+
+export interface RuntimeFactory {
+    readonly runtimeName: RuntimeName;
+    readonly capabilities: RuntimeCapabilities;
+    createFileSystem(): FileSystem;
+    loadConfig(options?: LoadConfigOptions): Promise<Config>;
+    createContext?(options?: { scope?: string }): RuntimeContext;
+}
+
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+    baggage?: Record<string, string>;
+    attributes?: Record<string, string | number | boolean>;
+}