@gobing-ai/ts-runtime 0.2.8 → 0.2.9

package/src/fs.ts

@@ -1,3 +1,6 @@
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirnamePath, getProcessCwd, joinPath, resolvePath } from './path';
+
 export interface FileStat {
     isFile(): boolean;
     isDirectory(): boolean;
@@ -25,6 +28,14 @@ export interface FileSystem {
     createLogStream(path: string): LogStream;
 }
 
+export interface SyncFileSystem {
+    readFile(path: string): string;
+    writeFile(path: string, content: string): void;
+    mkdir(path: string): void;
+    readDir(path: string): string[];
+    unlink(path: string): void;
+}
+
 type NodeFsPromises = typeof import('node:fs/promises');
 type NodeFs = typeof import('node:fs');
 
@@ -119,39 +130,61 @@ export class NodeFileSystem implements FileSystem {
     }
 }
 
+export class NodeSyncFileSystem implements SyncFileSystem {
+    readFile(path: string): string {
+        return readFileSync(path, 'utf-8');
+    }
+
+    writeFile(path: string, content: string): void {
+        ensureDirForFileSync(path, this);
+        writeFileSync(path, content, 'utf-8');
+    }
+
+    mkdir(path: string): void {
+        mkdirSync(path, { recursive: true });
+    }
+
+    readDir(path: string): string[] {
+        return readdirSync(path);
+    }
+
+    unlink(path: string): void {
+        rmSync(path, { recursive: true, force: true });
+    }
+}
+
 class LazyNodeLogStream implements LogStream {
     private readonly ready: Promise<{
         write: (chunk: string) => void;
         end: () => void;
     }>;
     private ended = false;
-    private readonly pending: string[] = [];
+    // Single serialized chain: every write/end is appended here, so the underlying stream observes
+    // them in call order regardless of how the resolving microtasks interleave. A per-write `shift()`
+    // off a shared buffer (the previous approach) could reorder writes that arrived in the same tick.
+    private tail: Promise<unknown>;
 
     constructor(path: string) {
         this.ready = nodeFs().then(({ createWriteStream, mkdirSync }) => {
             mkdirSync(dirnamePath(path), { recursive: true });
             const stream = createWriteStream(path, { flags: 'a' });
-            for (const chunk of this.pending.splice(0)) stream.write(chunk);
-            if (this.ended) stream.end();
             return {
                 write: (chunk: string) => stream.write(chunk),
                 end: () => stream.end(),
             };
         });
+        this.tail = this.ready;
     }
 
     write(chunk: string): void {
         if (this.ended) return;
-        this.pending.push(chunk);
-        void this.ready.then((stream) => {
-            const next = this.pending.shift();
-            if (next !== undefined) stream.write(next);
-        });
+        this.tail = this.tail.then(() => this.ready.then((stream) => stream.write(chunk)));
     }
 
     end(): void {
+        if (this.ended) return;
         this.ended = true;
-        void this.ready.then((stream) => stream.end());
+        this.tail = this.tail.then(() => this.ready.then((stream) => stream.end()));
     }
 }
 
@@ -229,9 +262,13 @@ export async function ensureDirForFile(path: string, fs = getFs()): Promise<void
     await fs.mkdir(dirnamePath(path));
 }
 
+export function ensureDirForFileSync(path: string, fs: SyncFileSystem): void {
+    fs.mkdir(dirnamePath(path));
+}
+
 export async function atomicWriteFile(path: string, content: string, fs = getFs()): Promise<void> {
     await ensureDirForFile(path, fs);
-    const tempPath = `${path}.${getProcessPid()}.${Date.now()}.tmp`;
+    const tempPath = `${path}.${getProcessPid()}.${uniqueToken()}.tmp`;
     await fs.writeFile(tempPath, content);
     await fs.rename(tempPath, path);
 }
@@ -294,53 +331,8 @@ function getProcessPid(): number {
     return (globalThis as { process?: { pid?: number } }).process?.pid ?? 0;
 }
 
-function getProcessCwd(): string {
-    return (globalThis as { process?: { cwd?: () => string } }).process?.cwd?.() ?? '/';
-}
-
-function normalizeSeparators(path: string): string {
-    return path.replaceAll('\\', '/');
-}
-
-function isAbsolutePath(path: string): boolean {
-    return path.startsWith('/') || /^[A-Za-z]:\//.test(normalizeSeparators(path));
-}
-
-function dirnamePath(path: string): string {
-    const input = normalizeSeparators(path);
-    if (/^\/+$/.test(input)) return '/';
-    const normalized = input.replace(/\/+$/, '');
-    if (normalized === '' || normalized === '/') return normalized || '.';
-    const index = normalized.lastIndexOf('/');
-    if (index < 0) return '.';
-    if (index === 0) return '/';
-    return normalized.slice(0, index);
-}
-
-function joinPath(...segments: string[]): string {
-    const filtered = segments.filter((segment) => segment.length > 0).map(normalizeSeparators);
-    if (filtered.length === 0) return '.';
-    const absolute = isAbsolutePath(filtered[0] ?? '');
-    const joined = filtered.join('/').replace(/\/+/g, '/');
-    return absolute ? joined : joined.replace(/^\//, '');
-}
-
-function resolvePath(...segments: string[]): string {
-    const candidates = segments.length === 0 ? [getProcessCwd()] : segments;
-    let resolved = '';
-    for (const segment of candidates.map(normalizeSeparators)) {
-        if (segment.length === 0) continue;
-        resolved = isAbsolutePath(segment) ? segment : joinPath(resolved || getProcessCwd(), segment);
-    }
-    const parts: string[] = [];
-    const absolute = isAbsolutePath(resolved);
-    for (const part of resolved.split('/')) {
-        if (part === '' || part === '.') continue;
-        if (part === '..') {
-            parts.pop();
-            continue;
-        }
-        parts.push(part);
-    }
-    return `${absolute ? '/' : ''}${parts.join('/')}` || (absolute ? '/' : '.');
+// Two writers to the same path in the same millisecond must not share a temp name, or one clobbers
+// the other before rename. randomUUID disambiguates; Date.now keeps names sortable for debugging.
+function uniqueToken(): string {
+    return `${Date.now()}.${crypto.randomUUID()}`;
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './config';
 export * from './context';
 export * from './fs';
+export * from './path';
 export * from './process-executor';
 export * from './schema-validation';
 export * from './types';

package/src/path.ts

@@ -0,0 +1,54 @@
+// Runtime-portable path math. Deliberately avoids `node:path` so the same logic works on
+// `cloudflare-workers` (no `node:*`) as on node-bun (ADR-008). POSIX-style separators throughout;
+// Windows drive paths (`C:/...`) are normalized and treated as absolute.
+
+export function normalizeSeparators(path: string): string {
+    return path.replaceAll('\\', '/');
+}
+
+export function isAbsolutePath(path: string): boolean {
+    return path.startsWith('/') || /^[A-Za-z]:\//.test(normalizeSeparators(path));
+}
+
+export function dirnamePath(path: string): string {
+    const input = normalizeSeparators(path);
+    if (/^\/+$/.test(input)) return '/';
+    const normalized = input.replace(/\/+$/, '');
+    if (normalized === '' || normalized === '/') return normalized || '.';
+    const index = normalized.lastIndexOf('/');
+    if (index < 0) return '.';
+    if (index === 0) return '/';
+    return normalized.slice(0, index);
+}
+
+export function joinPath(...segments: string[]): string {
+    const filtered = segments.filter((segment) => segment.length > 0).map(normalizeSeparators);
+    if (filtered.length === 0) return '.';
+    const absolute = isAbsolutePath(filtered[0] ?? '');
+    const joined = filtered.join('/').replace(/\/+/g, '/');
+    return absolute ? joined : joined.replace(/^\//, '');
+}
+
+export function resolvePath(...segments: string[]): string {
+    const candidates = segments.length === 0 ? [getProcessCwd()] : segments;
+    let resolved = '';
+    for (const segment of candidates.map(normalizeSeparators)) {
+        if (segment.length === 0) continue;
+        resolved = isAbsolutePath(segment) ? segment : joinPath(resolved || getProcessCwd(), segment);
+    }
+    const parts: string[] = [];
+    const absolute = isAbsolutePath(resolved);
+    for (const part of resolved.split('/')) {
+        if (part === '' || part === '.') continue;
+        if (part === '..') {
+            parts.pop();
+            continue;
+        }
+        parts.push(part);
+    }
+    return `${absolute ? '/' : ''}${parts.join('/')}` || (absolute ? '/' : '.');
+}
+
+export function getProcessCwd(): string {
+    return (globalThis as { process?: { cwd?: () => string } }).process?.cwd?.() ?? '/';
+}

package/src/process-executor.ts

@@ -13,6 +13,11 @@ 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`). */
@@ -36,6 +41,32 @@ export interface ProcessExecutor {
     run(options: ProcessOptions): Promise<ProcessResult>;
 }
 
+export interface SyncProcessExecutor {
+    runSync(options: Omit<ProcessOptions, 'timeout'>): ProcessResult;
+}
+
+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>;
+}
+
+export interface PipeProcess {
+    readonly pid: number | null;
+    readonly stdout: ReadableStream<Uint8Array> | null;
+    readonly stderr: ReadableStream<Uint8Array> | null;
+    readonly exited: Promise<number | null>;
+    writeStdin(input: string | Uint8Array): void;
+    endStdin(): void;
+    kill(signal?: ProcessSignal): void;
+}
+
+export interface PipeProcessSpawner {
+    spawn(options: PipeProcessOptions): PipeProcess;
+}
+
 export class NodeProcessExecutor implements ProcessExecutor {
     constructor(private readonly config: ProcessExecutorConfig = {}) {}
 
@@ -84,6 +115,95 @@ export class NodeProcessExecutor implements ProcessExecutor {
     }
 }
 
+export class BunSyncProcessExecutor implements SyncProcessExecutor {
+    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,
+        };
+    }
+}
+
+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 } : {}),
+        });
+        return new BunPipeProcess(subprocess);
+    }
+}
+
+type BunSubprocess = ReturnType<typeof Bun.spawn>;
+type ProcessSignal = Parameters<BunSubprocess['kill']>[0];
+type StdinSink = {
+    write: (data: string | Uint8Array) => unknown;
+    end?: () => unknown;
+    flush?: () => unknown;
+};
+
+class BunPipeProcess implements PipeProcess {
+    private readonly writer: StdinSink;
+
+    constructor(private readonly subprocess: BunSubprocess) {
+        this.writer = subprocess.stdin as StdinSink;
+    }
+
+    get pid(): number | null {
+        return this.subprocess.pid ?? null;
+    }
+
+    get stdout(): ReadableStream<Uint8Array> | null {
+        return isReadableStream(this.subprocess.stdout) ? this.subprocess.stdout : null;
+    }
+
+    get stderr(): ReadableStream<Uint8Array> | null {
+        return isReadableStream(this.subprocess.stderr) ? this.subprocess.stderr : null;
+    }
+
+    get exited(): Promise<number | null> {
+        return this.subprocess.exited;
+    }
+
+    writeStdin(input: string | Uint8Array): void {
+        this.writer.write(input);
+        this.writer.flush?.();
+    }
+
+    endStdin(): void {
+        this.writer.end?.();
+    }
+
+    kill(signal?: ProcessSignal): void {
+        this.subprocess.kill(signal);
+    }
+}
+
 function buildExecaOptions(opts: {
     cwd: string | undefined;
     env: Record<string, string> | undefined;
@@ -116,3 +236,11 @@ function asString(value: string | string[] | unknown[] | Uint8Array | undefined)
     if (Array.isArray(value)) return value.map(String).join('');
     return '';
 }
+
+function stripFinalNewline(value: string): string {
+    return value.endsWith('\r\n') ? value.slice(0, -2) : value.endsWith('\n') ? value.slice(0, -1) : value;
+}
+
+function isReadableStream(value: unknown): value is ReadableStream<Uint8Array> {
+    return value instanceof ReadableStream;
+}

package/src/schema-validation.ts

@@ -1,10 +1,13 @@
-import { dirname, isAbsolute, join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { getFs } from './fs';
+import { dirnamePath, isAbsolutePath, joinPath } from './path';
 
 /** Default time budget for a single remote schema fetch. */
 const REMOTE_SCHEMA_FETCH_TIMEOUT_MS = 5_000;
 
+/** Upper bound on a remote schema body. A timeout alone lets a slow multi-GB drip exhaust memory. */
+const REMOTE_SCHEMA_MAX_BYTES = 5 * 1024 * 1024;
+
 export interface JsonSchemaViolation {
     path: string;
     message: string;
@@ -110,22 +113,31 @@ export function validateJsonSchema(
     schema: JsonSchema,
     path = '',
     defs: Record<string, JsonSchema> = {},
+    seenRefs: ReadonlySet<string> = new Set(),
 ): JsonSchemaViolation[] {
     const violations: JsonSchemaViolation[] = [];
 
     // Applicator keywords compose with their siblings (logical AND), per JSON Schema 2020-12 —
     // a node may carry `$ref`/`oneOf`/`anyOf` *and* `type`/`properties`/... and all apply.
     if (schema.$ref !== undefined) {
-        const resolved = resolveRef(schema.$ref, defs, schema.$defs);
-        if (resolved !== undefined) violations.push(...validateJsonSchema(value, resolved, path, defs));
+        // Cyclic `$ref` (A→B→A) would recurse until stack overflow — a DoS surface for untrusted
+        // schemas. Following a ref already on the current path is a no-op: that branch is being
+        // validated higher up the stack, so re-entering adds nothing but unbounded depth.
+        if (!seenRefs.has(schema.$ref)) {
+            const resolved = resolveRef(schema.$ref, defs, schema.$defs);
+            if (resolved !== undefined) {
+                const nextSeen = new Set(seenRefs).add(schema.$ref);
+                violations.push(...validateJsonSchema(value, resolved, path, defs, nextSeen));
+            }
+        }
     }
 
     if (schema.oneOf !== undefined) {
-        violations.push(...validateCombinator(value, schema.oneOf, path, defs, 'oneOf'));
+        violations.push(...validateCombinator(value, schema.oneOf, path, defs, 'oneOf', seenRefs));
     }
 
     if (schema.anyOf !== undefined) {
-        violations.push(...validateCombinator(value, schema.anyOf, path, defs, 'anyOf'));
+        violations.push(...validateCombinator(value, schema.anyOf, path, defs, 'anyOf', seenRefs));
     }
 
     if (schema.const !== undefined && !jsonEqual(value, schema.const)) {
@@ -150,11 +162,11 @@ export function validateJsonSchema(
     const hasObjectKeywords =
         schema.properties !== undefined || schema.required !== undefined || schema.additionalProperties !== undefined;
     if (schema.type === 'object' || (hasObjectKeywords && isObject(value))) {
-        violations.push(...validateObject(value, schema, path, defs));
+        violations.push(...validateObject(value, schema, path, defs, seenRefs));
     }
 
     if (schema.type === 'array' || (schema.items !== undefined && Array.isArray(value))) {
-        violations.push(...validateArray(value, schema, path, defs));
+        violations.push(...validateArray(value, schema, path, defs, seenRefs));
     }
 
     return violations;
@@ -165,6 +177,7 @@ function validateObject(
     schema: JsonSchema,
     path: string,
     defs: Record<string, JsonSchema>,
+    seenRefs: ReadonlySet<string>,
 ): JsonSchemaViolation[] {
     if (!isObject(value)) return [{ path: path || '(root)', message: `expected object, got ${typeName(value)}` }];
 
@@ -178,7 +191,9 @@ function validateObject(
     const properties = schema.properties ?? {};
     for (const [key, childSchema] of Object.entries(properties)) {
         if (key in value) {
-            violations.push(...validateJsonSchema(value[key], childSchema, path ? `${path}.${key}` : key, defs));
+            violations.push(
+                ...validateJsonSchema(value[key], childSchema, path ? `${path}.${key}` : key, defs, seenRefs),
+            );
         }
     }
 
@@ -193,7 +208,13 @@ function validateObject(
         for (const [key, child] of Object.entries(value)) {
             if (!(key in properties)) {
                 violations.push(
-                    ...validateJsonSchema(child, schema.additionalProperties, path ? `${path}.${key}` : key, defs),
+                    ...validateJsonSchema(
+                        child,
+                        schema.additionalProperties,
+                        path ? `${path}.${key}` : key,
+                        defs,
+                        seenRefs,
+                    ),
                 );
             }
         }
@@ -207,11 +228,12 @@ function validateArray(
     schema: JsonSchema,
     path: string,
     defs: Record<string, JsonSchema>,
+    seenRefs: ReadonlySet<string>,
 ): JsonSchemaViolation[] {
     if (!Array.isArray(value)) return [{ path: path || '(root)', message: `expected array, got ${typeName(value)}` }];
     if (schema.items === undefined) return [];
     return value.flatMap((entry, index) =>
-        validateJsonSchema(entry, schema.items as JsonSchema, `${path}[${index}]`, defs),
+        validateJsonSchema(entry, schema.items as JsonSchema, `${path}[${index}]`, defs, seenRefs),
     );
 }
 
@@ -221,8 +243,9 @@ function validateCombinator(
     path: string,
     defs: Record<string, JsonSchema>,
     mode: 'oneOf' | 'anyOf',
+    seenRefs: ReadonlySet<string>,
 ): JsonSchemaViolation[] {
-    const branchViolations = schemas.map((schema) => validateJsonSchema(value, schema, path, defs));
+    const branchViolations = schemas.map((schema) => validateJsonSchema(value, schema, path, defs, seenRefs));
     const passing = branchViolations.filter((violations) => violations.length === 0).length;
     if (mode === 'anyOf' && passing >= 1) return [];
     if (mode === 'oneOf' && passing === 1) return [];
@@ -260,10 +283,10 @@ function resolveSchemaRef(
     source: string,
     resolve: ((specifier: string, from: string) => string) | undefined,
 ): string {
-    if (isRemoteRef(schemaRef) || isAbsolute(schemaRef)) return schemaRef;
+    if (isRemoteRef(schemaRef) || isAbsolutePath(schemaRef)) return schemaRef;
     // Relative ref — resolve against the config file's directory.
     if (schemaRef.startsWith('./') || schemaRef.startsWith('../')) {
-        return join(isRemoteRef(source) ? '.' : dirname(source), schemaRef);
+        return joinPath(isRemoteRef(source) ? '.' : dirnamePath(source), schemaRef);
     }
     // Bare package specifier (e.g. "@scope/pkg/schemas/x.json") — resolve through node_modules.
     return resolvePackageSchema(schemaRef, source, resolve);
@@ -286,12 +309,12 @@ function resolvePackageSchema(
             `Package schema ref "${specifier}" referenced by "${source}" must include a path within the package`,
         );
     }
-    const from = isRemoteRef(source) ? process.cwd() : dirname(source);
+    const from = isRemoteRef(source) ? process.cwd() : dirnamePath(source);
     try {
         // Resolve the package root via its always-present package.json, then join the subpath.
         // This sidesteps `exports` gating on arbitrary JSON subpaths.
         const manifest = resolveFn(`${pkg}/package.json`, from);
-        return join(dirname(manifest), subpath);
+        return joinPath(dirnamePath(manifest), subpath);
     } catch (error) {
         throw new StructuredConfigSchemaError(
             `Cannot resolve package schema "${specifier}" referenced by "${source}": ${errorMessage(error)}`,
@@ -319,11 +342,56 @@ async function readSchema(schemaLocation: string, options: StructuredConfigLoadO
                 `Failed to fetch JSON schema "${schemaLocation}": HTTP ${response.status}`,
             );
         }
-        return await response.text();
+        return await readBoundedBody(response, schemaLocation);
     }
     return await getFs().readFile(schemaLocation);
 }
 
+/**
+ * Read a response body under a hard byte cap. `Content-Length` is a fast-path reject, but servers
+ * lie or omit it, so the stream is also tallied chunk-by-chunk — a multi-GB drip is aborted before
+ * it can exhaust memory. Falls back to `.text()` only when the body is not a readable stream.
+ */
+async function readBoundedBody(response: Response, schemaLocation: string): Promise<string> {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > REMOTE_SCHEMA_MAX_BYTES) {
+        throw new StructuredConfigSchemaError(
+            `Remote JSON schema "${schemaLocation}" exceeds the ${REMOTE_SCHEMA_MAX_BYTES}-byte limit (Content-Length ${declared})`,
+        );
+    }
+
+    const body = response.body;
+    if (body === null) return await response.text();
+
+    const reader = body.getReader();
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            total += value.byteLength;
+            if (total > REMOTE_SCHEMA_MAX_BYTES) {
+                await reader.cancel();
+                throw new StructuredConfigSchemaError(
+                    `Remote JSON schema "${schemaLocation}" exceeds the ${REMOTE_SCHEMA_MAX_BYTES}-byte limit`,
+                );
+            }
+            chunks.push(value);
+        }
+    } finally {
+        reader.releaseLock();
+    }
+
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(merged);
+}
+
 const defaultResolve: ((specifier: string, from: string) => string) | undefined =
     typeof Bun !== 'undefined' ? (specifier, from) => Bun.resolveSync(specifier, from) : undefined;
 

package/src/types.ts

@@ -1,6 +1,4 @@
 import type { Config } from './config';
-import type { RuntimeContext } from './context';
-import type { FileSystem } from './fs';
 
 export type RuntimeName = 'node-bun' | 'cloudflare-workers' | 'test';
 
@@ -15,14 +13,6 @@ export interface LoadConfigOptions {
     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;