// Shared spawn helper for running external commands import { spawn } from "node:child_process"; import { basename, dirname, extname, join } from "node:path"; import { StringDecoder } from "node:string_decoder"; import { findExecutable, findExecutableFile } from "./src/pi-ext-executable.ts"; export type SpawnTextOptions = { signal?: AbortSignal; timeoutMs?: number; maxStdoutBytes?: number; maxStderrBytes?: number; }; export class SpawnTextResourceError extends Error { constructor(message: string) { super(message); this.name = "SpawnTextResourceError"; } } const DEFAULT_TIMEOUT_MS = 120_000; const DEFAULT_MAX_STDOUT_BYTES = 8 * 1024 * 1024; const DEFAULT_MAX_STDERR_BYTES = 64 * 1024; type ResolvedSpawnTextOptions = Required> & { signal?: AbortSignal; }; function boundedOption( value: number | undefined, defaultValue: number, name: string, ): number { const result = value ?? defaultValue; if (!Number.isSafeInteger(result) || result < 0) { throw new RangeError(`${name} must be a non-negative safe integer`); } return result; } function resolveOptions(options: SpawnTextOptions): ResolvedSpawnTextOptions { return { ...(options.signal === undefined ? {} : { signal: options.signal }), timeoutMs: boundedOption( options.timeoutMs, DEFAULT_TIMEOUT_MS, "timeoutMs", ), maxStdoutBytes: boundedOption( options.maxStdoutBytes, DEFAULT_MAX_STDOUT_BYTES, "maxStdoutBytes", ), maxStderrBytes: boundedOption( options.maxStderrBytes, DEFAULT_MAX_STDERR_BYTES, "maxStderrBytes", ), }; } export async function spawnToText( cmd: string, args: string[], input?: string, options: SpawnTextOptions = {}, ): Promise { const limits = resolveOptions(options); if (limits.signal?.aborted) { throw new SpawnTextResourceError(`${cmd}: aborted before start`); } const resolved = (await resolveCommand(cmd)) ?? cmd; if (limits.signal?.aborted) { throw new SpawnTextResourceError(`${cmd}: aborted before start`); } const spawnArgs = commandArgs(resolved, args); return new Promise((resolve, reject) => { let proc: ReturnType; try { proc = spawn(spawnArgs.command, spawnArgs.args, { windowsHide: true, ...spawnArgs.options, }); } catch (error) { reject(error); return; } let stdout = ""; let stderr = ""; let stdoutBytes = 0; let stderrBytes = 0; let settled = false; const stdoutDecoder = new StringDecoder("utf8"); const stderrDecoder = new StringDecoder("utf8"); let timer: ReturnType | undefined; let killTimer: ReturnType | undefined; let closed = false; const cleanup = () => { if (timer) clearTimeout(timer); if (killTimer) clearTimeout(killTimer); limits.signal?.removeEventListener("abort", onAbort); proc.stdout?.off("data", onStdout); proc.stderr?.off("data", onStderr); proc.stdin?.off("error", onStdinError); proc.off("close", onClose); proc.off("error", onProcessError); }; const stop = () => { proc.stdin?.destroy(); try { proc.kill("SIGTERM"); } catch { // The process may have already exited. } killTimer = setTimeout(() => { if (closed) return; if (proc.exitCode === null && proc.signalCode === null) { try { proc.kill("SIGKILL"); } catch { // The process may have already exited. } } proc.stdin?.destroy(); proc.stdout?.destroy(); proc.stderr?.destroy(); }, 500); killTimer.unref(); }; const fail = (error: Error, terminate = false) => { if (settled) return; settled = true; if (timer) clearTimeout(timer); limits.signal?.removeEventListener("abort", onAbort); if (terminate) stop(); reject(error); }; const onAbort = () => fail(new SpawnTextResourceError(`${cmd}: aborted`), true); const onStdout = (chunk: Buffer) => { stdoutBytes += chunk.byteLength; if (stdoutBytes > limits.maxStdoutBytes) { fail( new SpawnTextResourceError( `${cmd}: stdout exceeded ${limits.maxStdoutBytes} byte limit`, ), true, ); return; } stdout += stdoutDecoder.write(chunk); }; const onStderr = (chunk: Buffer) => { stderrBytes += chunk.byteLength; if (stderrBytes > limits.maxStderrBytes) { fail( new SpawnTextResourceError( `${cmd}: stderr exceeded ${limits.maxStderrBytes} byte limit`, ), true, ); return; } stderr += stderrDecoder.write(chunk); }; const onStdinError = (error: NodeJS.ErrnoException) => { if (error.code !== "EPIPE" && error.code !== "EOF") fail(error, true); }; const onProcessError = (error: Error) => fail(error, true); const onClose = (code: number | null) => { closed = true; cleanup(); if (settled) return; settled = true; stdout += stdoutDecoder.end(); stderr += stderrDecoder.end(); if (code === 0) resolve(stdout); else reject(new Error(stderr || `${cmd}: ${code}`)); }; proc.stdout?.on("data", onStdout); proc.stderr?.on("data", onStderr); proc.stdin?.on("error", onStdinError); proc.on("close", onClose); proc.on("error", onProcessError); limits.signal?.addEventListener("abort", onAbort, { once: true }); if (limits.signal?.aborted) { onAbort(); return; } timer = setTimeout( () => fail( new SpawnTextResourceError( `${cmd}: timed out after ${limits.timeoutMs}ms`, ), true, ), limits.timeoutMs, ); try { proc.stdin?.end(input); } catch (error) { fail(error instanceof Error ? error : new Error(String(error)), true); } }); } /** * Check if a command is available on PATH. * Returns null if available, or an install hint string if not. */ const availableCommands = new Set(); function pathEnv(): string { const key = Object.keys(process.env).find((k) => k.toLowerCase() === "path"); return key ? (process.env[key] ?? "") : ""; } function pathextEnv(): string[] { if (process.platform !== "win32") return [""]; const raw = process.env["PATHEXT"] || ".COM;.EXE;.BAT;.CMD"; return raw .split(";") .map((ext) => ext.trim()) .filter(Boolean); } function candidateNames(cmd: string): string[] { if (process.platform !== "win32" || extname(cmd)) return [cmd]; return [ cmd, ...pathextEnv().flatMap((ext) => [cmd + ext, cmd + ext.toLowerCase()]), ]; } export async function resolveCommand(cmd: string): Promise { if (cmd.includes("/") || cmd.includes("\\")) { for (const name of candidateNames(basename(cmd))) { const candidate = findExecutableFile(join(dirname(cmd), name)); if (candidate) return candidate; } return null; } return findExecutable(candidateNames(cmd), { path: pathEnv() }) ?? null; } function commandArgs( resolved: string, args: string[], ): { command: string; args: string[]; options?: { windowsVerbatimArguments: boolean }; } { if (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(resolved)) { return { command: process.env["ComSpec"] || process.env["COMSPEC"] || "cmd.exe", args: [ "/d", "/s", "/c", `"${[quoteCmdArg(resolved), ...args.map(quoteCmdArg)].join(" ")}"`, ], options: { windowsVerbatimArguments: true }, }; } return { command: resolved, args }; } function quoteCmdArg(arg: string): string { return `"${arg.replace(/"/g, '""')}"`; } export async function checkToolAvailability( cmd: string, installHint: string, ): Promise { const cacheKey = `${cmd}\0${pathEnv()}\0${process.env["PATHEXT"] ?? ""}`; if (availableCommands.has(cacheKey)) return null; if (await resolveCommand(cmd)) { availableCommands.add(cacheKey); return null; } return installHint; } // Tool install hints export const TOOL_HINTS = { pandoc: "pandoc is not installed. Install with: brew install pandoc / apt install pandoc / conda install pandoc", pdftotext: "pdftotext (poppler-utils) is not installed. Install with: brew install poppler / apt install poppler-utils", identify: "identify (ImageMagick) is not installed. Install with: brew install imagemagick / apt install imagemagick", ffprobe: "ffprobe (ffmpeg) is not installed. Install with: brew install ffmpeg / apt install ffmpeg", } as const;