@engenty/wizards-runtime 0.0.0-stage → 0.7.6

package/apps/runtime/dist/cli/connect.js

@@ -0,0 +1,540 @@
+import { execFile, execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { installedByScript, packageRoot } from "./home.js";
+import { findOnPath, macAppPresent } from "./machine.js";
+import { bad, cmd, dim, ok, tilde } from "./ui.js";
+const run = promisify(execFile);
+/**
+ * The wizards in the person's own AI apps: `wizards connect` writes this install's MCP
+ * server into each app's config, as the command `wizards mcp` (stdio). Every app starts
+ * servers that way; the command finds the running runtime itself and signs in with the data
+ * folder's secret, so a config holds neither a port nor a key.
+ */
+/** The name the server has in every app's config. */
+export const SERVER_NAME = "engenty-wizards";
+/**
+ * How an app starts this install's MCP server. An install made by install.sh has a command that
+ * stays where it is across updates; any other copy is started by its Node and its script. The
+ * studio connects apps too: from the runtime, which is not the command.
+ */
+export function serverCommand(paths, script = join(packageRoot, "bin", "wizards.mjs")) {
+    const moved = dirname(paths.home) !== join(homedir(), ".engenty");
+    const env = moved ? { env: { ENGENTY_HOME: dirname(paths.home) } } : {};
+    if (installedByScript(paths)) {
+        return { command: join(paths.bin, "wizards"), args: ["mcp"], ...env };
+    }
+    return { command: process.execPath, args: [script, "mcp"], ...env };
+}
+/** A JSON config with the server set under `at` (e.g. ["mcpServers"]); null when it is no JSON. */
+export function withJsonServer(text, at, entry, name = SERVER_NAME) {
+    let root;
+    try {
+        root = text?.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        return null;
+    }
+    if (!root || typeof root !== "object" || Array.isArray(root)) {
+        return null;
+    }
+    let node = root;
+    for (const key of at) {
+        const next = node[key];
+        if (!next || typeof next !== "object" || Array.isArray(next)) {
+            node[key] = {};
+        }
+        node = node[key];
+    }
+    node[name] = entry;
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+/** The same config without the server; null when it is no JSON. */
+export function withoutJsonServer(text, at, name = SERVER_NAME) {
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    let node = root;
+    for (const key of at) {
+        node = node?.[key];
+    }
+    if (node && typeof node === "object") {
+        delete node[name];
+    }
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+export function jsonHasServer(text, at, name = SERVER_NAME) {
+    try {
+        let node = JSON.parse(text);
+        for (const key of at) {
+            node = node?.[key];
+        }
+        return Boolean(node && typeof node === "object" && name in node);
+    }
+    catch {
+        return false;
+    }
+}
+const tomlString = (value) => JSON.stringify(value);
+/** A TOML config (Codex) without the server's tables `[mcp_servers.<name>]` and below. */
+export function withoutTomlServer(text, name = SERVER_NAME) {
+    const lines = text.split("\n");
+    const out = [];
+    let skipping = false;
+    for (const line of lines) {
+        const table = line.match(/^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/)?.[1];
+        if (table !== undefined) {
+            const key = table.replaceAll('"', "");
+            skipping = key === `mcp_servers.${name}` || key.startsWith(`mcp_servers.${name}.`);
+        }
+        if (!skipping) {
+            out.push(line);
+        }
+    }
+    return out.join("\n").replace(/\n{3,}$/, "\n\n");
+}
+export function withTomlServer(text, server, name = SERVER_NAME) {
+    const rest = withoutTomlServer(text ?? "", name).trimEnd();
+    const table = [
+        `[mcp_servers.${name}]`,
+        `command = ${tomlString(server.command)}`,
+        `args = [${server.args.map(tomlString).join(", ")}]`,
+        // A run waits up to 45 s for a step; the default of 60 s leaves room for it.
+        "tool_timeout_sec = 120",
+        ...(server.env
+            ? [
+                `env = { ${Object.entries(server.env)
+                    .map(([key, value]) => `${key} = ${tomlString(value)}`)
+                    .join(", ")} }`,
+            ]
+            : []),
+    ].join("\n");
+    return `${rest ? `${rest}\n\n` : ""}${table}\n`;
+}
+export function tomlHasServer(text, name = SERVER_NAME) {
+    return text.split("\n").some((line) => line.trim() === `[mcp_servers.${name}]`);
+}
+/** Goose's YAML: the server's block below `extensions:`, at two spaces. */
+export function withoutYamlExtension(text, name = SERVER_NAME) {
+    const lines = text.split("\n");
+    const out = [];
+    let skipping = false;
+    for (const line of lines) {
+        if (line === `  ${name}:`) {
+            skipping = true;
+            continue;
+        }
+        if (skipping && line.trim() && !line.startsWith("   ")) {
+            skipping = false;
+        }
+        if (!skipping) {
+            out.push(line);
+        }
+    }
+    return out.join("\n");
+}
+export function withYamlExtension(text, server, name = SERVER_NAME) {
+    const quote = (value) => JSON.stringify(value);
+    const block = [
+        `  ${name}:`,
+        `    name: ${name}`,
+        "    type: stdio",
+        `    cmd: ${quote(server.command)}`,
+        `    args: [${server.args.map(quote).join(", ")}]`,
+        "    enabled: true",
+        "    timeout: 300",
+        ...(server.env
+            ? [
+                "    envs:",
+                ...Object.entries(server.env).map(([key, value]) => `      ${key}: ${quote(value)}`),
+            ]
+            : []),
+    ];
+    const lines = withoutYamlExtension(text ?? "", name).split("\n");
+    const at = lines.findIndex((line) => /^extensions:\s*(\{\s*\})?\s*$/.test(line));
+    if (at === -1) {
+        const rest = lines.join("\n").trimEnd();
+        return `${rest ? `${rest}\n` : ""}extensions:\n${block.join("\n")}\n`;
+    }
+    lines[at] = "extensions:";
+    lines.splice(at + 1, 0, ...block);
+    return lines.join("\n");
+}
+export function yamlHasExtension(text, name = SERVER_NAME) {
+    return text.split("\n").includes(`  ${name}:`);
+}
+const home = homedir();
+const appData = process.env.APPDATA || join(home, "AppData", "Roaming");
+/** A folder below the per-user application data: Library/Application Support, %APPDATA%, ~/.config. */
+function appSupport(...parts) {
+    if (process.platform === "darwin") {
+        return join(home, "Library", "Application Support", ...parts);
+    }
+    if (process.platform === "win32") {
+        return join(appData, ...parts);
+    }
+    return join(process.env.XDG_CONFIG_HOME || join(home, ".config"), ...parts);
+}
+/** Claude Desktop's main process, as `ps` (macOS) or `tasklist` (Windows) names it. */
+const CLAUDE_DESKTOP_PROCESS = {
+    darwin: /\/Claude\.app\/Contents\/MacOS\/Claude$/m,
+    win32: /^"?Claude\.exe"?,/im,
+};
+/** Whether an app's process runs; false where it cannot be told (Linux, no `ps`). */
+export function processRunning(names, platform = process.platform, list = () => platform === "win32"
+    ? execFileSync("tasklist", ["/FO", "CSV", "/NH"], { encoding: "utf8" })
+    : execFileSync("ps", ["-axo", "comm"], { encoding: "utf8" })) {
+    const pattern = names[platform];
+    if (!pattern) {
+        return false;
+    }
+    try {
+        return pattern.test(list());
+    }
+    catch {
+        return false;
+    }
+}
+const read = (file) => (existsSync(file) ? readFileSync(file, "utf8") : null);
+/** Writes a config, keeping the version before it once next to it. */
+function save(file, text) {
+    mkdirSync(dirname(file), { recursive: true });
+    if (existsSync(file)) {
+        copyFileSync(file, `${file}.before-engenty`);
+    }
+    writeFileSync(file, text);
+}
+function jsonApp(def) {
+    const running = () => def.ownsFileWhileRunning?.()
+        ? {
+            ok: false,
+            message: `${def.name} is running and would overwrite its settings. Quit it completely, then try again.`,
+        }
+        : null;
+    const snippet = (server) => JSON.stringify(def.at.reduceRight((inner, key) => ({ [key]: inner }), {
+        [SERVER_NAME]: def.entry(server),
+    }), null, 2);
+    return {
+        id: def.id,
+        name: def.name,
+        widgets: def.widgets,
+        where: def.file,
+        installed: () => existsSync(def.marker) &&
+            (process.platform !== "darwin" || !def.macApp || macAppPresent(def.macApp)),
+        connected: async () => jsonHasServer(read(def.file) ?? "", def.at),
+        async connect(server) {
+            const busy = running();
+            if (busy) {
+                return busy;
+            }
+            const next = withJsonServer(read(def.file), def.at, def.entry(server));
+            if (next === null) {
+                return {
+                    ok: false,
+                    message: `${tilde(def.file)} isn’t plain JSON (comments?). Add this to it yourself:`,
+                    snippet: snippet(server),
+                };
+            }
+            save(def.file, next);
+            return { ok: true, message: `added to ${tilde(def.file)}` };
+        },
+        async disconnect() {
+            const text = read(def.file);
+            if (!text || !jsonHasServer(text, def.at)) {
+                return { ok: true, message: "wasn’t connected" };
+            }
+            const busy = running();
+            if (busy) {
+                return busy;
+            }
+            const next = withoutJsonServer(text, def.at);
+            if (next === null) {
+                return {
+                    ok: false,
+                    message: `${tilde(def.file)} isn’t plain JSON. Remove “${SERVER_NAME}” from it yourself.`,
+                };
+            }
+            save(def.file, next);
+            return { ok: true, message: `removed from ${tilde(def.file)}` };
+        },
+    };
+}
+const stdioEntry = (server) => ({
+    command: server.command,
+    args: server.args,
+    ...(server.env ? { env: server.env } : {}),
+});
+/** A command of an app: on the PATH, or among the clients this install brought. */
+function appCommand(paths, name) {
+    return findOnPath(name, [join(paths.clients, "bin"), process.env.PATH ?? ""].join(delimiter));
+}
+function claudeCode(paths) {
+    const file = join(home, ".claude.json");
+    return {
+        id: "claude-code",
+        name: "Claude Code",
+        widgets: false,
+        where: "claude mcp (user scope)",
+        installed: () => Boolean(appCommand(paths, "claude")),
+        connected: async () => jsonHasServer(read(file) ?? "", ["mcpServers"]),
+        async connect(server) {
+            const claude = appCommand(paths, "claude");
+            if (!claude) {
+                return { ok: false, message: "The claude command wasn’t found." };
+            }
+            // Claude Code keeps rewriting its own file: its command changes it, not we.
+            await run(claude, ["mcp", "remove", "--scope", "user", SERVER_NAME]).catch(() => undefined);
+            try {
+                await run(claude, [
+                    "mcp",
+                    "add",
+                    "--scope",
+                    "user",
+                    // The name before `-e`: claude's `-e` takes every value up to the next option, so a
+                    // name after it is read as one more variable.
+                    SERVER_NAME,
+                    ...Object.entries(server.env ?? {}).flatMap(([key, value]) => ["-e", `${key}=${value}`]),
+                    "--",
+                    server.command,
+                    ...server.args,
+                ]);
+                return { ok: true, message: "added with claude mcp add --scope user" };
+            }
+            catch (error) {
+                // claude's own words say what was wrong; "Command failed: …" only repeats the command.
+                const said = String(error.stderr ?? "").trim();
+                return { ok: false, message: (said || error.message).split("\n")[0] };
+            }
+        },
+        async disconnect() {
+            const claude = appCommand(paths, "claude");
+            if (!claude) {
+                return { ok: true, message: "wasn’t connected" };
+            }
+            await run(claude, ["mcp", "remove", "--scope", "user", SERVER_NAME]).catch(() => undefined);
+            return { ok: true, message: "removed with claude mcp remove" };
+        },
+    };
+}
+function codex() {
+    const dir = process.env.CODEX_HOME || join(home, ".codex");
+    const file = join(dir, "config.toml");
+    return {
+        id: "codex",
+        name: "Codex · ChatGPT app",
+        widgets: false,
+        where: file,
+        installed: () => existsSync(dir),
+        connected: async () => tomlHasServer(read(file) ?? ""),
+        async connect(server) {
+            save(file, withTomlServer(read(file), server));
+            return { ok: true, message: `added to ${tilde(file)}` };
+        },
+        async disconnect() {
+            const text = read(file);
+            if (!text || !tomlHasServer(text)) {
+                return { ok: true, message: "wasn’t connected" };
+            }
+            save(file, withoutTomlServer(text));
+            return { ok: true, message: `removed from ${tilde(file)}` };
+        },
+    };
+}
+function goose() {
+    const dir = process.platform === "win32"
+        ? join(appData, "Block", "goose", "config")
+        : join(process.env.XDG_CONFIG_HOME || join(home, ".config"), "goose");
+    const file = join(dir, "config.yaml");
+    return {
+        id: "goose",
+        name: "Goose",
+        widgets: true,
+        where: file,
+        installed: () => existsSync(dir),
+        connected: async () => yamlHasExtension(read(file) ?? ""),
+        async connect(server) {
+            save(file, withYamlExtension(read(file), server));
+            return { ok: true, message: `added to ${tilde(file)}` };
+        },
+        async disconnect() {
+            const text = read(file);
+            if (!text || !yamlHasExtension(text)) {
+                return { ok: true, message: "wasn’t connected" };
+            }
+            save(file, withoutYamlExtension(text));
+            return { ok: true, message: `removed from ${tilde(file)}` };
+        },
+    };
+}
+function openClaw(paths) {
+    const dir = join(home, ".openclaw");
+    const file = join(dir, "openclaw.json");
+    const json = jsonApp({
+        id: "openclaw",
+        name: "OpenClaw",
+        widgets: false,
+        file,
+        marker: dir,
+        at: ["mcp", "servers"],
+        entry: stdioEntry,
+    });
+    return {
+        ...json,
+        // Its config is JSON5: its own command writes it when it is there.
+        async connect(server) {
+            const openclaw = appCommand(paths, "openclaw");
+            if (!openclaw) {
+                return json.connect(server);
+            }
+            try {
+                await run(openclaw, [
+                    "mcp",
+                    "set",
+                    SERVER_NAME,
+                    "--command",
+                    server.command,
+                    "--args",
+                    ...server.args,
+                ]);
+                return { ok: true, message: "added with openclaw mcp set" };
+            }
+            catch (error) {
+                return { ok: false, message: error.message.split("\n")[0] };
+            }
+        },
+        async disconnect() {
+            const openclaw = appCommand(paths, "openclaw");
+            if (!openclaw) {
+                return json.disconnect();
+            }
+            await run(openclaw, ["mcp", "unset", SERVER_NAME]).catch(() => undefined);
+            return { ok: true, message: "removed with openclaw mcp unset" };
+        },
+    };
+}
+/** The AI apps this install can connect to, in the order they are offered. */
+export function apps(paths) {
+    const vscodeUser = appSupport("Code", "User");
+    return [
+        jsonApp({
+            id: "claude-desktop",
+            name: "Claude Desktop",
+            widgets: true,
+            file: join(appSupport("Claude"), "claude_desktop_config.json"),
+            marker: appSupport("Claude"),
+            macApp: "Claude",
+            at: ["mcpServers"],
+            entry: stdioEntry,
+            ownsFileWhileRunning: () => processRunning(CLAUDE_DESKTOP_PROCESS),
+        }),
+        claudeCode(paths),
+        codex(),
+        jsonApp({
+            id: "cursor",
+            name: "Cursor",
+            widgets: true,
+            file: join(home, ".cursor", "mcp.json"),
+            marker: join(home, ".cursor"),
+            at: ["mcpServers"],
+            entry: stdioEntry,
+        }),
+        jsonApp({
+            id: "vscode",
+            name: "VS Code (Copilot)",
+            widgets: true,
+            file: join(vscodeUser, "mcp.json"),
+            marker: vscodeUser,
+            macApp: "Visual Studio Code",
+            at: ["servers"],
+            entry: (server) => ({ type: "stdio", ...stdioEntry(server) }),
+        }),
+        jsonApp({
+            id: "windsurf",
+            name: "Windsurf",
+            widgets: false,
+            file: join(home, ".codeium", "windsurf", "mcp_config.json"),
+            marker: join(home, ".codeium", "windsurf"),
+            macApp: "Windsurf",
+            at: ["mcpServers"],
+            entry: stdioEntry,
+        }),
+        jsonApp({
+            id: "antigravity",
+            name: "Antigravity",
+            widgets: false,
+            // The app and its CLI (agy) read the same file.
+            file: join(home, ".gemini", "config", "mcp_config.json"),
+            marker: join(home, ".gemini", "config"),
+            at: ["mcpServers"],
+            entry: stdioEntry,
+        }),
+        goose(),
+        openClaw(paths),
+        jsonApp({
+            id: "lm-studio",
+            name: "LM Studio",
+            widgets: false,
+            file: join(home, ".lmstudio", "mcp.json"),
+            marker: join(home, ".lmstudio"),
+            at: ["mcpServers"],
+            entry: stdioEntry,
+        }),
+    ];
+}
+export async function appStates(paths) {
+    return Promise.all(apps(paths).map(async (app) => ({
+        id: app.id,
+        name: app.name,
+        widgets: app.widgets,
+        where: app.where,
+        installed: app.installed(),
+        connected: await app.connected(),
+    })));
+}
+/** `wizards connect [app …]` and `disconnect`: what was done, app by app. */
+export async function connectCommand(paths, ids, remove) {
+    const unknown = ids.filter((id) => !apps(paths).some((app) => app.id === id));
+    if (unknown.length) {
+        console.error(`Unknown app ${unknown.map((id) => `“${id}”`).join(", ")}. Choose from: ${apps(paths)
+            .map((app) => app.id)
+            .join(", ")}.`);
+        return 2;
+    }
+    const results = await connectApps(paths, ids, remove);
+    if (!results.length) {
+        console.log(`No AI app found on this computer. Name one: ${cmd("connect cursor")}`);
+        return 0;
+    }
+    for (const { app, outcome } of results) {
+        console.log(`${outcome.ok ? ok : bad} ${app.name.padEnd(22)} ${dim(outcome.message)}`);
+        if (!outcome.ok && outcome.snippet) {
+            console.log(outcome.snippet);
+        }
+    }
+    if (!remove && results.some((r) => r.outcome.ok)) {
+        console.log("");
+        console.log(dim("Restart the app (or reload its MCP servers) to see the wizards in it."));
+        console.log(dim("Claude Desktop, Cursor, VS Code and Goose show a run as a widget, the others as text."));
+    }
+    return results.every((r) => r.outcome.ok) ? 0 : 1;
+}
+/** Connects (or disconnects) the named apps; without names every app found on this machine. */
+export async function connectApps(paths, ids, remove = false) {
+    const all = apps(paths);
+    const picked = ids.length
+        ? all.filter((app) => ids.includes(app.id))
+        : all.filter((app) => app.installed());
+    const server = serverCommand(paths);
+    const out = [];
+    for (const app of picked) {
+        const outcome = await (remove ? app.disconnect() : app.connect(server)).catch((error) => ({ ok: false, message: error.message }));
+        out.push({ app, outcome });
+    }
+    return out;
+}

package/apps/runtime/dist/cli/environment.js

@@ -0,0 +1,95 @@
+import { basename, delimiter, dirname, join } from "node:path";
+import { isCI } from "./autoupdate.js";
+/**
+ * Variables of the terminal the runtime inherits. Everything else it gets comes from the
+ * install's `.env` or is set by the command line. A key or a database address that the shell
+ * happens to export for another project never reaches it; in particular it never sees
+ * `MANAGE_URL`, which would make it a cloud runtime.
+ */
+const INHERITED = new Set([
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TMPDIR",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "COLORTERM",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+    "SSL_CERT_FILE",
+    "NODE_EXTRA_CA_CERTS",
+    // Settings of this install somebody may give for one start: `API_PORT=8900 wizards`.
+    "API_HOST",
+    "APP_URL",
+    "ALLOWED_HOSTS",
+    "SECRETS",
+    "CHROME_PATH",
+    "FFMPEG_PATH",
+    "OLLAMA_URL",
+    "SANDBOX",
+    "SANDBOX_ENABLED",
+    "SANDBOX_IMAGE",
+    "SANDBOX_ALLOW_HOSTS",
+    "SANDBOX_ENGINES_DIR",
+    "PLUGINS_DIR",
+    "PLUGINS_WATCH",
+    "ACCOUNT_URL",
+    "ACCOUNT_GATEWAY_URL",
+    "CLOUD_URL",
+    // Off for this start (autoupdate.ts).
+    "WIZARDS_DISABLE_AUTOUPDATE",
+]);
+export function inherited(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined && (INHERITED.has(key) || key.startsWith("MODEL_"))) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * The PATH of the runtime: AI clients the setup installed and the Node that runs this command
+ * come first — a client installed with npm is a script that asks for `node`.
+ */
+export function runtimePath(paths, env, node = process.execPath) {
+    const entries = [
+        join(paths.clients, "bin"),
+        dirname(node),
+        ...(env.PATH ?? "").split(delimiter),
+        join(env.HOME ?? "", ".local", "bin"),
+    ];
+    return [...new Set(entries.filter(Boolean))].join(delimiter);
+}
+/**
+ * The environment the command line starts the runtime with. `fileEnv` is the install's `.env`:
+ * the runtime reads it itself, it is only looked at here so that a default does not override it.
+ */
+export function runtimeEnv(paths, start, env = process.env, fileEnv = {}, platform = process.platform) {
+    const secretsGiven = env.SECRETS !== undefined || fileEnv.SECRETS !== undefined;
+    const pluginsGiven = env.PLUGINS_DIR !== undefined || fileEnv.PLUGINS_DIR !== undefined;
+    return {
+        // Plugins live beside the data, in the install's own folder.
+        ...(pluginsGiven ? {} : { PLUGINS_DIR: paths.plugins }),
+        ...inherited(env),
+        PATH: runtimePath(paths, env),
+        NODE_ENV: "production",
+        API_PORT: String(start.port),
+        APP_URL: start.url,
+        DATA_DIR: start.dataDir,
+        LOCAL_ACCESS_KEY: start.accessKey,
+        // The install the runtime belongs to: the studio connects AI apps to its command.
+        ...(basename(paths.home) === "wizards" ? { ENGENTY_HOME: dirname(paths.home) } : {}),
+        // The runtime sees no CI variables; it is told so, and checks for no updates (autoupdate.ts).
+        ...(isCI(env) ? { ENGENTY_WIZARDS_CI: "1" } : {}),
+        // Keys entered in the settings live in the Keychain, as with the desktop app.
+        ...(platform === "darwin" && !secretsGiven ? { SECRETS: "keychain" } : {}),
+    };
+}

package/apps/runtime/dist/cli/exec.js

@@ -0,0 +1,45 @@
+import { spawn } from "node:child_process";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Runs a command; what it prints goes line by line to `onLine` and into the log file.
+ * Never rejects for a command that fails: the caller reads `code`.
+ */
+export function runLogged(command, args, options = {}) {
+    const { logFile, onLine } = options;
+    if (logFile) {
+        mkdirSync(dirname(logFile), { recursive: true });
+        appendFileSync(logFile, `\n$ ${command} ${args.join(" ")}\n`);
+    }
+    return new Promise((resolve) => {
+        let tail = "";
+        let pending = "";
+        const take = (chunk) => {
+            const text = chunk.toString("utf8");
+            tail = (tail + text).slice(-4000);
+            if (logFile) {
+                appendFileSync(logFile, text);
+            }
+            pending += text;
+            const lines = pending.split(/\r?\n|\r/);
+            pending = lines.pop() ?? "";
+            for (const line of lines) {
+                if (line.trim()) {
+                    onLine?.(line);
+                }
+            }
+        };
+        const child = spawn(command, args, {
+            env: options.env,
+            cwd: options.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout.on("data", take);
+        child.stderr.on("data", take);
+        child.on("error", (error) => {
+            tail = `${tail}\n${error.message}`.trim();
+            resolve({ code: 127, tail });
+        });
+        child.on("close", (code) => resolve({ code: code ?? 1, tail: tail.trim() }));
+    });
+}