repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/web/spawn.ts
Raw// 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<Omit<SpawnTextOptions, "signal">> & {
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<string> {
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<typeof spawn>;
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<typeof setTimeout> | undefined;
let killTimer: ReturnType<typeof setTimeout> | 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<string>();
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<string | null> {
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<string | null> {
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;