agent-cloud-kit 0.0.0-stage → 1.0.0-rc.1

package/dist/prepare/index.js

@@ -0,0 +1,489 @@
+/**
+ * @file The `prepare` command: walks the user, in a local terminal, from an unprepared repo to a
+ * pushed branch with the cloud setup and a cloud session that verifies it. It never deletes the
+ * worktree or the branch it creates.
+ */
+import { existsSync, lstatSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { readConfig } from "../config.js";
+import { CONFIG_FILE, OUTPUT_PREFIX, PACKAGE } from "../constants.js";
+import { defaultBranch } from "../detect.js";
+import { init } from "../init.js";
+import { renderEnvironmentSection, writeManual } from "../manual.js";
+import { preflight } from "./detect.js";
+import { configurePrompt, verifyPrompt } from "./prompts.js";
+/** Prefix of the branch `prepare` creates; the day follows it. */
+const BRANCH_PREFIX = "chore/cloud-ready-";
+/** Suffix added to the repo folder name to name the worktree folder, next to the repo. */
+const WORKTREE_SUFFIX = "-cloud-ready";
+/** Notes file the skill writes when `notes` is not set in the config. */
+const DEFAULT_NOTES_FILE = ".claude/cloud-notes.md";
+/** Files `prepare` always commits when they exist, relative to the worktree. */
+const KNOWN_PATHS = [
+    CONFIG_FILE,
+    ".claude/settings.json",
+    ".agents/skills/cloud-ready",
+    ".claude/skills/cloud-ready",
+    "docs/agent-cloud.md",
+];
+/** Project file of the test-audit skill, committed too when it exists. */
+const TEST_AUDIT_PROJECT_FILE = ".agents/skills/test-audit/project.md";
+/** Message of the commit `prepare` makes. */
+const COMMIT_MESSAGE = "chore: prepare the repo for the Claude Code cloud";
+/** Question asked before committing changes outside the known files. */
+const INCLUDE_QUESTION = "Include these changes in the commit? [y/N]";
+/** Answers to `INCLUDE_QUESTION` that mean yes. */
+const YES_ANSWER = /^y(es)?$/i;
+/** Text shown while the user configures the environment in claude.ai. */
+const WAIT_TEXT = "Configure the environment in claude.ai, then press Enter";
+/** Matches a GitHub remote URL (https or ssh) and captures `owner/repo`. */
+const GITHUB_REMOTE = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/;
+/** Matches a pull request URL and captures its number. */
+const PR_URL = /\/pull\/(\d+)/;
+/** Command that continues a prepare run; `npx` because a first-time user does not have the binary on PATH. */
+const RESUME_COMMAND = `npx ${PACKAGE} prepare --resume`;
+/** Printed just before the local agent starts: `prepare` continues only when `claude` exits. */
+const EXIT_CLAUDE_HINT = `${OUTPUT_PREFIX}when the skill says configure is done, exit claude (/exit) and prepare will commit, push and open the PR`;
+/** Exit code for success. */
+const EXIT_OK = 0;
+/** Exit code for failure. */
+const EXIT_FAIL = 1;
+/** Exit code after Ctrl+C (128 + SIGINT). */
+export const EXIT_INTERRUPTED = 130;
+/** Matches a PR number printed by `gh pr view --jq .number`. */
+const PR_NUMBER = /^\d+$/;
+/** Thrown by `ask` or `waitEnter` when the user presses Ctrl+C. */
+export class InterruptedError extends Error {
+    /** Builds the error. */
+    constructor() {
+        super("interrupted");
+        this.name = "InterruptedError";
+    }
+}
+/**
+ * Formats a local date as the day of the branch name.
+ *
+ * @param date - Date, read in the local time zone.
+ * @returns `YYYYMMDD`.
+ * @example
+ * branchDay(new Date(2026, 10, 2)); // "20261102"
+ */
+export function branchDay(date) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`;
+}
+/**
+ * Says where the worktree is and how to continue there.
+ *
+ * @param reason - What happened, e.g. "the local agent stopped".
+ * @param worktree - Worktree folder.
+ * @returns The line to print.
+ * @example
+ * resumeLine("interrupted", "/home/u/app-cloud-ready"); // "interrupted; the worktree is at ...; run ... --resume there"
+ */
+function resumeLine(reason, worktree) {
+    return `${reason}; the worktree is at ${worktree}; run ${RESUME_COMMAND} there`;
+}
+/**
+ * Runs a capture and trims its output; never throws.
+ *
+ * @param deps - Dependencies.
+ * @param cmd - Executable.
+ * @param args - Arguments.
+ * @param cwd - Working directory.
+ * @returns Trimmed stdout, or undefined when the command failed.
+ * @example
+ * await tryCapture(deps, "git", ["rev-parse", "--show-toplevel"], "/repo"); // "/repo"
+ */
+async function tryCapture(deps, cmd, args, cwd) {
+    try {
+        return (await deps.capture(cmd, args, { cwd })).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Turns an unknown error into its message.
+ *
+ * @param err - Anything thrown.
+ * @returns The message.
+ * @example
+ * message(new Error("x")); // "x"
+ */
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Tells whether a path exists, without following a symlink (so a link counts even if broken).
+ *
+ * @param path - Absolute path.
+ * @returns True when something is there.
+ * @example
+ * entryExists("/repo/.claude/skills/cloud-ready"); // true
+ */
+function entryExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Names the worktree folder: next to the repo, with `WORKTREE_SUFFIX`.
+ *
+ * @param repo - Repo root.
+ * @returns Absolute path of the worktree.
+ * @example
+ * worktreePath("/home/u/app"); // "/home/u/app-cloud-ready"
+ */
+function worktreePath(repo) {
+    return join(dirname(repo), `${basename(repo)}${WORKTREE_SUFFIX}`);
+}
+/**
+ * Finds the notes file the config names, when `configure` finished.
+ *
+ * @param worktree - Worktree root.
+ * @returns Undefined when the config reads without errors and its notes file exists; else why not.
+ * @example
+ * configureProblem("/home/u/app-cloud-ready"); // undefined
+ */
+function configureProblem(worktree) {
+    const { config, errors } = readConfig(worktree);
+    if (!config || errors.length)
+        return errors[0] ?? `${CONFIG_FILE} not found`;
+    const notes = config.notes ?? DEFAULT_NOTES_FILE;
+    const rel = relative(worktree, join(worktree, notes));
+    const inside = !isAbsolute(notes) && rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`);
+    try {
+        if (inside && statSync(join(worktree, notes)).isFile())
+            return undefined;
+    }
+    catch {
+        // NOTE: a missing file is reported below.
+    }
+    return `the notes file ${notes} does not exist`;
+}
+/**
+ * Lists the paths of `git status --porcelain=v1 -z` output.
+ *
+ * @param output - Raw output (NUL-separated entries).
+ * @returns Paths, renames giving both the new and the old path.
+ * @example
+ * statusPaths("?? a.txt\0"); // ["a.txt"]
+ */
+function statusPaths(output) {
+    const tokens = output.split("\0").filter((t) => t !== "");
+    const paths = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i] ?? "";
+        const code = token.slice(0, 2);
+        paths.push(token.slice(3));
+        if (code.includes("R") || code.includes("C")) {
+            const old = tokens[++i];
+            if (old !== undefined)
+                paths.push(old);
+        }
+    }
+    return paths;
+}
+/**
+ * Tells whether a path is one of the given paths or inside one of them.
+ *
+ * @param path - Repo-relative path.
+ * @param roots - Repo-relative paths.
+ * @returns True when covered.
+ * @example
+ * covered(".agents/skills/cloud-ready/SKILL.md", [".agents/skills/cloud-ready"]); // true
+ */
+function covered(path, roots) {
+    return roots.some((root) => path === root || path.startsWith(`${root}/`));
+}
+/**
+ * Builds the GitHub compare link for a branch from the origin URL.
+ *
+ * @param originUrl - URL of `origin`, if known.
+ * @param branch - Branch to compare.
+ * @returns The link, or undefined when origin is not on GitHub.
+ * @example
+ * compareLink("git@github.com:acme/app.git", "b"); // "https://github.com/acme/app/compare/b?expand=1"
+ */
+function compareLink(originUrl, branch) {
+    const slug = GITHUB_REMOTE.exec(originUrl ?? "")?.[1];
+    return slug ? `https://github.com/${slug}/compare/${branch}?expand=1` : undefined;
+}
+/**
+ * Finds the worktree and branch to resume.
+ *
+ * @param repo - Git root where `prepare --resume` runs: the worktree, or the repo next to it.
+ * @param deps - Dependencies.
+ * @returns The worktree and its branch, or undefined when there is none.
+ * @example
+ * await findResume("/home/u/app-cloud-ready", deps); // { worktree: "...", branch: "chore/cloud-ready-20261102" }
+ */
+async function findResume(repo, deps) {
+    for (const worktree of [repo, worktreePath(repo)]) {
+        if (!existsSync(worktree))
+            continue;
+        const branch = await tryCapture(deps, "git", ["rev-parse", "--abbrev-ref", "HEAD"], worktree);
+        if (branch?.startsWith(BRANCH_PREFIX))
+            return { worktree, branch };
+    }
+    return undefined;
+}
+/**
+ * Steps 2–5: creates the worktree, installs the kit and runs the local agent.
+ *
+ * @param repo - Git root of the repo.
+ * @param branch - Branch to create.
+ * @param worktree - Worktree folder to create.
+ * @param deps - Dependencies.
+ * @param progress - Gets the worktree once it exists.
+ * @returns True when the worktree is ready to commit.
+ * @example
+ * await createAndConfigure("/home/u/app", "chore/cloud-ready-20261102", "/home/u/app-cloud-ready", deps, {});
+ */
+async function createAndConfigure(repo, branch, worktree, deps, progress) {
+    if (existsSync(worktree)) {
+        deps.print(`${OUTPUT_PREFIX}${worktree} already exists; remove it (git worktree remove ${worktree}) or continue there with ${RESUME_COMMAND}`);
+        return false;
+    }
+    if ((await tryCapture(deps, "git", ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], repo)) !== undefined) {
+        deps.print(`${OUTPUT_PREFIX}branch ${branch} already exists; delete it (git branch -D ${branch}) or run prepare another day`);
+        return false;
+    }
+    const base = `origin/${defaultBranch(repo)}`;
+    try {
+        await deps.run("git", ["fetch", "-q", "origin"], { cwd: repo });
+        await deps.run("git", ["worktree", "add", "-b", branch, worktree, base], { cwd: repo });
+        progress.worktree = worktree;
+    }
+    catch (err) {
+        deps.print(`${OUTPUT_PREFIX}could not create the worktree: ${message(err)}`);
+        return false;
+    }
+    const stopped = resumeLine("the local agent stopped", worktree);
+    try {
+        const result = init(worktree, deps.packageVersion, deps.packageRoot);
+        for (const line of result.lines)
+            deps.print(line);
+        if (!result.ok) {
+            deps.print(stopped);
+            return false;
+        }
+    }
+    catch (err) {
+        deps.print(`${OUTPUT_PREFIX}${message(err)}`);
+        deps.print(stopped);
+        return false;
+    }
+    deps.print(EXIT_CLAUDE_HINT);
+    try {
+        await runInteractive(deps, progress, [configurePrompt()], worktree);
+    }
+    catch {
+        deps.print(stopped);
+        return false;
+    }
+    const problem = configureProblem(worktree);
+    if (problem !== undefined) {
+        deps.print(`${OUTPUT_PREFIX}configure did not finish: ${problem}`);
+        deps.print(resumeLine("prepare stopped", worktree));
+        return false;
+    }
+    return true;
+}
+/**
+ * Step 6: writes the manual, commits the setup (and, if the user says so, the other changes),
+ * pushes the branch and opens a draft PR.
+ *
+ * @param worktree - Worktree root.
+ * @param branch - Its branch.
+ * @param deps - Dependencies.
+ * @returns The PR number when known (an open PR for the branch is reused), or false when the
+ *   branch could not be committed or pushed.
+ * @throws InterruptedError when the user presses Ctrl+C at the question.
+ * @example
+ * await commitAndPush("/home/u/app-cloud-ready", "chore/cloud-ready-20261102", deps); // { pr: "7" }
+ */
+async function commitAndPush(worktree, branch, deps) {
+    try {
+        writeManual(worktree, deps.packageVersion);
+        const notes = readConfig(worktree).config?.notes ?? DEFAULT_NOTES_FILE;
+        const known = [...KNOWN_PATHS, notes, TEST_AUDIT_PROJECT_FILE].filter((path) => entryExists(join(worktree, path)));
+        await deps.run("git", ["add", "--", ...known], { cwd: worktree });
+        const status = await deps.capture("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: worktree });
+        const others = statusPaths(status).filter((path) => !covered(path, known));
+        if (others.length) {
+            deps.print(`${OUTPUT_PREFIX}the local agent also changed:`);
+            for (const path of others)
+                deps.print(`  ${path}`);
+            if (YES_ANSWER.test((await deps.ask(INCLUDE_QUESTION, "")).trim())) {
+                await deps.run("git", ["add", "--", ...others], { cwd: worktree });
+            }
+            else {
+                await deps.run("git", ["reset", "-q", "--", ...others], { cwd: worktree });
+                deps.print(`${OUTPUT_PREFIX}left uncommitted in ${worktree}`);
+            }
+        }
+        const staged = await deps.capture("git", ["diff", "--cached", "--name-only"], { cwd: worktree });
+        if (staged.trim())
+            await deps.run("git", ["commit", "-m", COMMIT_MESSAGE], { cwd: worktree });
+        else
+            deps.print(`${OUTPUT_PREFIX}nothing new to commit`);
+        await deps.run("git", ["push", "-u", "origin", branch], { cwd: worktree });
+    }
+    catch (err) {
+        if (err instanceof InterruptedError)
+            throw err;
+        deps.print(`${OUTPUT_PREFIX}could not commit and push: ${message(err)}; fix it in ${worktree} and run ${RESUME_COMMAND} there`);
+        return false;
+    }
+    const existing = await tryCapture(deps, "gh", ["pr", "view", branch, "--json", "number", "--jq", ".number"], worktree);
+    if (existing !== undefined && PR_NUMBER.test(existing)) {
+        deps.print(`${OUTPUT_PREFIX}reusing the open PR #${existing}`);
+        return { pr: existing };
+    }
+    try {
+        const url = await deps.capture("gh", ["pr", "create", "--draft", "--fill"], { cwd: worktree });
+        deps.print(`${OUTPUT_PREFIX}draft PR: ${url.trim()}`);
+        return { pr: PR_URL.exec(url)?.[1] };
+    }
+    catch {
+        const origin = await tryCapture(deps, "git", ["remote", "get-url", "origin"], worktree);
+        const link = compareLink(origin, branch);
+        deps.print(`${OUTPUT_PREFIX}could not open the PR with gh; open it by hand${link ? `: ${link}` : ` from branch ${branch}`}`);
+        return {};
+    }
+}
+/**
+ * Prepares a repo for Claude Code cloud sessions: checks, asks, creates a worktree on a new
+ * branch, runs the local agent with the `cloud-ready` skill, commits, pushes, opens a draft PR,
+ * waits while the user configures the environment and starts a cloud session that verifies it.
+ *
+ * @param repo - Folder where the user runs `prepare` (inside the repo, or the worktree with resume).
+ * @param deps - Dependencies.
+ * @param options - `resume` continues in an existing prepare worktree.
+ * @returns 0 when the cloud session was started, 130 after Ctrl+C at a question, 1 otherwise.
+ * @example
+ * process.exitCode = await prepare(process.cwd(), deps);
+ */
+export async function prepare(repo, deps, options = {}) {
+    const gitRoot = await tryCapture(deps, "git", ["rev-parse", "--show-toplevel"], repo);
+    const cwd = gitRoot ?? repo;
+    const hasOrigin = (await tryCapture(deps, "git", ["remote", "get-url", "origin"], cwd)) !== undefined;
+    const clean = options.resume ? true : (await tryCapture(deps, "git", ["status", "--porcelain"], cwd)) === "";
+    const claudeHelp = await tryCapture(deps, "claude", ["--help"], cwd);
+    const problems = preflight({ isTty: deps.isTty, gitRoot, hasOrigin, clean, claudeHelp });
+    if (problems.length || gitRoot === undefined) {
+        for (const problem of problems)
+            deps.print(`${OUTPUT_PREFIX}${problem}`);
+        return EXIT_FAIL;
+    }
+    const progress = {};
+    const stop = deps.onInterrupt?.(() => {
+        if (progress.childOwnsTerminal)
+            return false;
+        deps.print(interruptedLine(progress));
+        return true;
+    });
+    try {
+        return await prepareSteps(gitRoot, deps, options, progress);
+    }
+    catch (err) {
+        if (!(err instanceof InterruptedError))
+            throw err;
+        deps.print(interruptedLine(progress));
+        return EXIT_INTERRUPTED;
+    }
+    finally {
+        stop?.();
+    }
+}
+/**
+ * Runs an interactive `claude` that owns the terminal. Ctrl+C meanwhile belongs to Claude (it
+ * interrupts the agent), so the interrupt handler ignores it until the child returns.
+ *
+ * @param deps - Dependencies.
+ * @param progress - Marks the child as owning the terminal.
+ * @param args - Arguments of `claude`.
+ * @param cwd - Worktree.
+ * @returns Resolves when `claude` exits 0.
+ * @throws When `claude` exits non-zero.
+ * @example
+ * await runInteractive(deps, progress, ["--cloud", prompt], "/home/u/app-cloud-ready");
+ */
+async function runInteractive(deps, progress, args, cwd) {
+    progress.childOwnsTerminal = true;
+    try {
+        await deps.run("claude", args, { cwd });
+    }
+    finally {
+        progress.childOwnsTerminal = false;
+    }
+}
+/**
+ * The line printed on Ctrl+C: where the worktree is, when it exists.
+ *
+ * @param progress - What exists so far.
+ * @returns The line.
+ * @example
+ * interruptedLine({}); // "agent-cloud-kit: interrupted; nothing was created"
+ */
+function interruptedLine(progress) {
+    return progress.worktree === undefined ? `${OUTPUT_PREFIX}interrupted; nothing was created` : resumeLine("interrupted", progress.worktree);
+}
+/**
+ * Everything after the preflight: resume or create the worktree, commit, wait, launch.
+ *
+ * @param gitRoot - Git root where `prepare` runs.
+ * @param deps - Dependencies.
+ * @param options - Options of `prepare`.
+ * @param progress - Gets the worktree once it exists.
+ * @returns The exit code.
+ * @throws InterruptedError when the user presses Ctrl+C at a question.
+ * @example
+ * await prepareSteps("/home/u/app", deps, {}, {}); // 0
+ */
+async function prepareSteps(gitRoot, deps, options, progress) {
+    let worktree;
+    let branch;
+    if (options.resume) {
+        const found = await findResume(gitRoot, deps);
+        if (!found) {
+            deps.print(`${OUTPUT_PREFIX}nothing to resume: run it in the ${WORKTREE_SUFFIX} worktree on a ${BRANCH_PREFIX}* branch`);
+            return EXIT_FAIL;
+        }
+        ({ worktree, branch } = found);
+        progress.worktree = worktree;
+        const problem = configureProblem(worktree);
+        if (problem) {
+            deps.print(`${OUTPUT_PREFIX}configure is not finished in ${worktree}: ${problem}; run claude "/cloud-ready configure" there first, then ${RESUME_COMMAND}`);
+            return EXIT_FAIL;
+        }
+    }
+    else {
+        branch = `${BRANCH_PREFIX}${deps.today}`;
+        worktree = worktreePath(gitRoot);
+        if (!(await createAndConfigure(gitRoot, branch, worktree, deps, progress)))
+            return EXIT_FAIL;
+    }
+    const pushed = await commitAndPush(worktree, branch, deps);
+    if (!pushed)
+        return EXIT_FAIL;
+    const config = readConfig(worktree).config;
+    if (config)
+        deps.print(renderEnvironmentSection(config, deps.packageVersion));
+    await deps.waitEnter(WAIT_TEXT);
+    try {
+        await runInteractive(deps, progress, ["--cloud", verifyPrompt({ branch, pr: pushed.pr })], worktree);
+    }
+    catch (err) {
+        deps.print(`${OUTPUT_PREFIX}claude --cloud failed: ${message(err)}; run ${RESUME_COMMAND} in ${worktree} to try again`);
+        return EXIT_FAIL;
+    }
+    deps.print(`${OUTPUT_PREFIX}the cloud session will report back as a push to ${branch} and a comment on the PR`);
+    return EXIT_OK;
+}

package/dist/prepare/prompts.js

@@ -0,0 +1,28 @@
+/**
+ * @file Prompts `prepare` hands to Claude, in Spanish: they invoke the `cloud-ready` skill.
+ */
+/**
+ * Prompt for the local session: `configure` mode. `prepare` asks nothing first; the skill detects
+ * secrets and domains itself.
+ *
+ * @returns The prompt.
+ * @example
+ * configurePrompt(); // "/cloud-ready configure"
+ */
+export function configurePrompt() {
+    return "/cloud-ready configure";
+}
+/**
+ * Prompt for the cloud session: `verify` mode with the prepare branch and, when known, the PR.
+ *
+ * @param input Branch of `prepare` and optional PR number.
+ * @returns The prompt.
+ * @example
+ * verifyPrompt({ branch: "chore/cloud-ready-1", pr: "42" }); // "/cloud-ready verify\n\n- Rama de prepare: ..."
+ */
+export function verifyPrompt(input) {
+    const lines = ["/cloud-ready verify", "", `- Rama de prepare: ${input.branch}`];
+    if (input.pr !== undefined)
+        lines.push(`- PR: #${input.pr}`);
+    return lines.join("\n");
+}

package/dist/prepare/questions.js

@@ -0,0 +1,5 @@
+/**
+ * @file How `prepare` asks the user a question. It asks nothing up front: secrets and domains are
+ * detected by the `cloud-ready` skill, locally or in the cloud, when they are needed.
+ */
+export {};

package/dist/run.js

@@ -0,0 +1,113 @@
+/**
+ * @file Process runner: the single place where child processes are spawned.
+ * Modules that execute processes receive a `Run` (or a `Capture`) so tests can inject a fake.
+ */
+import { spawn } from "node:child_process";
+/** Signal sent to a process group that ran past its time limit. */
+const KILL_SIGNAL = "SIGKILL";
+/** File descriptor of the parent's stderr, reused as the child's stdout and stderr. */
+const PARENT_STDERR = 2;
+/** Error thrown when a child is killed because it ran past its time limit. */
+export class RunTimeoutError extends Error {
+    /**
+     * Builds the error.
+     *
+     * @param cmd - Executable that timed out.
+     * @param ms - Time limit, in milliseconds.
+     */
+    constructor(cmd, ms) {
+        super(`${cmd} timed out after ${ms}ms`);
+        this.name = "RunTimeoutError";
+    }
+}
+/**
+ * Maps an output mode to the spawn stdio setting.
+ *
+ * @param mode - Output mode.
+ * @returns `"inherit"`, or stdin ignored and stdout plus stderr on the parent's stderr.
+ */
+function stdioFor(mode) {
+    return mode === "stderr" ? ["ignore", PARENT_STDERR, PARENT_STDERR] : "inherit";
+}
+/**
+ * Kills a detached child together with its process group; never throws.
+ *
+ * @param pid - Process id of the group leader.
+ */
+function killGroup(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, KILL_SIGNAL);
+    }
+    catch {
+        try {
+            process.kill(pid, KILL_SIGNAL);
+        }
+        catch {
+            // NOTE: the process already exited.
+        }
+    }
+}
+/**
+ * Spawns a process and settles when it exits, or when it runs past its time limit.
+ *
+ * @param cmd - Executable to run.
+ * @param args - Arguments passed to the executable.
+ * @param opts - Options.
+ * @param stdio - Spawn stdio setting.
+ * @param onStdout - Receives stdout chunks when stdout is piped.
+ * @returns Resolves on exit code 0.
+ * @throws When the process cannot be spawned, exits non-zero, is killed by a signal or times out.
+ */
+function spawnAndWait(cmd, args, opts, stdio, onStdout) {
+    return new Promise((resolve, reject) => {
+        const limited = opts.timeoutMs !== undefined;
+        const child = spawn(cmd, args, { stdio, cwd: opts.cwd, env: opts.env, detached: limited });
+        if (onStdout)
+            child.stdout?.on("data", onStdout);
+        let timer;
+        if (limited) {
+            const ms = opts.timeoutMs ?? 0;
+            timer = setTimeout(() => {
+                killGroup(child.pid);
+                reject(new RunTimeoutError(cmd, ms));
+            }, ms);
+        }
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            if (code === 0)
+                return resolve();
+            reject(new Error(`${cmd} exited with ${code === null ? `signal ${signal}` : `code ${code}`}`));
+        });
+    });
+}
+/**
+ * Spawns a process with inherited stdio, or with its output sent to stderr.
+ *
+ * @param cmd - Executable to run.
+ * @param args - Arguments passed to the executable.
+ * @param opts - Optional working directory, environment, output mode and timeout.
+ * @returns Resolves on exit code 0; rejects with the exit code in the message otherwise.
+ * @throws When the process cannot be spawned, exits with a non-zero code or signal, or times out
+ *   (`RunTimeoutError`).
+ */
+export const runProcess = (cmd, args, opts = {}) => spawnAndWait(cmd, args, opts, stdioFor(opts.stdio ?? "inherit"));
+/**
+ * Spawns a process and collects its stdout; stdin and stderr are ignored.
+ *
+ * @param cmd - Executable to run.
+ * @param args - Arguments passed to the executable.
+ * @param opts - Optional working directory, environment and timeout.
+ * @returns The stdout text.
+ * @throws When the process cannot be spawned, exits with a non-zero code or signal, or times out.
+ */
+export const captureProcess = async (cmd, args, opts = {}) => {
+    const chunks = [];
+    await spawnAndWait(cmd, args, opts, ["ignore", "pipe", "ignore"], (chunk) => chunks.push(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+};