basepad 0.0.0-stage → 0.0.0

package/dist/config.js

@@ -0,0 +1,217 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, realpathSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { FACTORIES, SCHEMAS } from "./catalogue.js";
+import { BasepadError } from "./internal/exec.js";
+export const CONFIG_FILE = "basepad.config.ts";
+export const LOCAL_FILE = "basepad.config.local.ts";
+/**
+ * Finds `basepad.config.ts` in `cwd` or its nearest parent that has one, loads it and the local
+ * file beside it, and validates the result. Every failure is a `BasepadError` naming the file,
+ * and the key when one is at fault.
+ */
+export async function loadProject(cwd) {
+    const file = findConfig(cwd);
+    const root = dirname(file);
+    let config = validate(await importDefault(file), file);
+    const local = join(root, LOCAL_FILE);
+    if (existsSync(local)) {
+        const override = await importDefault(local);
+        if (typeof override !== "function") {
+            throw new BasepadError(`${local}: its default export must be a function from the project's config to a config.`);
+        }
+        let changed;
+        try {
+            changed = await override(config);
+        }
+        catch (error) {
+            throw new BasepadError(`${local} threw: ${messageOf(error)}`);
+        }
+        config = validate(changed, local);
+    }
+    return {
+        file,
+        root,
+        name: config.name,
+        services: config.services ?? {},
+        apps: Object.fromEntries(Object.entries(config.apps ?? {}).map(([key, app]) => [
+            key,
+            {
+                run: app.run,
+                cwd: resolve(root, app.cwd ?? "."),
+                ...(app.port === false ? { port: false } : {}),
+                ...(app.domain === false ? { domain: false } : {}),
+            },
+        ])),
+        env: config.env ?? (() => ({})),
+        worktrees: {
+            prefix: config.worktrees?.prefix ?? "worktree",
+            clone: config.worktrees?.clone ?? [],
+            setup: config.worktrees?.setup ?? [],
+            ...(config.worktrees?.dir === undefined ? {} : { dir: resolve(root, config.worktrees.dir) }),
+        },
+    };
+}
+function findConfig(cwd) {
+    for (let dir = resolve(cwd);; dir = dirname(dir)) {
+        const file = join(dir, CONFIG_FILE);
+        if (existsSync(file))
+            return realpathSync(file);
+        if (dirname(dir) === dir)
+            break;
+    }
+    throw new BasepadError(`No ${CONFIG_FILE} in ${cwd} or any folder above it. Run \`basepad init\` to write one.`);
+}
+/** What a config imports basepad as. */
+const PACKAGE = "basepad";
+/** The running basepad's own entry: `index.ts` from source, `index.js` once built. */
+const OWN_INDEX = new URL(import.meta.url.endsWith(".ts") ? "./index.ts" : "./index.js", import.meta.url).href;
+/** Real paths of the files basepad loads; the hook reads each as TypeScript ESM. */
+const typescriptFiles = new Set();
+let hooked = false;
+/**
+ * Imports a file as TypeScript ESM, whatever the nearest `package.json` says about module type, so
+ * a project never renames files or changes settings for basepad, and Node prints no warning.
+ */
+async function importDefault(file) {
+    const real = realpathSync(file);
+    typescriptFiles.add(pathToFileURL(real).href);
+    if (!hooked) {
+        hooked = true;
+        registerHooks({
+            resolve(specifier, context, nextResolve) {
+                try {
+                    return nextResolve(specifier, context);
+                }
+                catch (error) {
+                    // A fresh worktree has no `node_modules` yet: its config gets the running basepad.
+                    const fromConfig = context.parentURL && typescriptFiles.has(context.parentURL);
+                    if (specifier !== PACKAGE || !fromConfig)
+                        throw error;
+                    return { url: OWN_INDEX, shortCircuit: true };
+                }
+            },
+            load(url, context, nextLoad) {
+                if (!typescriptFiles.has(url))
+                    return nextLoad(url, context);
+                const loaded = nextLoad(url, { ...context, format: "module-typescript" });
+                return { ...loaded, format: "module-typescript" };
+            },
+        });
+    }
+    let module;
+    try {
+        module = await import(__rewriteRelativeImportExtension(pathToFileURL(real).href));
+    }
+    catch (error) {
+        throw new BasepadError(`${file} failed to load: ${messageOf(error)}`);
+    }
+    if (module.default === undefined) {
+        throw new BasepadError(`${file}: it must \`export default defineConfig({ ... })\`.`);
+    }
+    return module.default;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** A lowercase DNS label: letters, digits and inner hyphens. */
+export const LABEL = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const label = z
+    .string({ error: "must be a string" })
+    .regex(LABEL, "must be a lowercase DNS label (letters, digits and inner hyphens)");
+const AppSchema = z.strictObject({
+    run: z.string({ error: "`run` must be a command" }).min(1, "`run` must be a command"),
+    cwd: z.string({ error: "`cwd` must be a folder relative to the config" }).optional(),
+    port: z
+        .literal(false, { error: "`port` can only be `false`, for an app that listens on nothing" })
+        .optional(),
+    domain: z
+        .literal(false, {
+        error: "`domain` can only be `false`, for an app served at `https://localhost:$PORT`",
+    })
+        .optional(),
+});
+const ConfigSchema = z
+    .strictObject({
+    name: label,
+    services: z
+        .record(label, 
+    // Each kind's schema is a strict object with a literal `kind`, as a discriminated union needs.
+    z.discriminatedUnion("kind", SCHEMAS, {
+        error: `a service must be made by a service function, such as ${FACTORIES.join(" or ")}`,
+    }))
+        .optional(),
+    apps: z.record(label, AppSchema).optional(),
+    env: z
+        .custom((value) => typeof value === "function", {
+        error: "`env` must be a function from outputs to env files",
+    })
+        .optional(),
+    worktrees: z
+        .strictObject({
+        prefix: label.optional(),
+        dir: z
+            .string({ error: "must be a folder relative to the config" })
+            .min(1, "must be a folder relative to the config")
+            .optional(),
+        clone: z
+            .array(z
+            .string({ error: "each must be a path relative to the config" })
+            .min(1, "each must be a path relative to the config")
+            .refine((path) => !isAbsolute(path) && !normalize(path).startsWith(".."), "each must be a path inside the config's folder"))
+            .optional(),
+        setup: z
+            .array(z
+            .string({ error: "each must be a shell command" })
+            .min(1, "each must be a shell command"))
+            .optional(),
+    })
+        .optional(),
+})
+    .superRefine((config, ctx) => {
+    for (const [key, app] of Object.entries(config.apps ?? {})) {
+        if (app.port === false && app.domain === false) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["apps", key, "domain"],
+                message: "an app with no port has no domain already; drop `domain`",
+            });
+        }
+    }
+    // Services and apps share one namespace: `env`'s outputs and the supervisor's daemons.
+    for (const key of Object.keys(config.services ?? {})) {
+        if (config.apps && key in config.apps) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["apps", key],
+                message: "a service has the same key; a key names one service or one app",
+            });
+        }
+    }
+});
+function validate(value, file) {
+    const result = ConfigSchema.safeParse(value);
+    if (result.success)
+        return result.data;
+    const lines = result.error.issues.map((issue) => {
+        const at = issue.path.map(String).join(".");
+        if (issue.code === "unrecognized_keys") {
+            const keys = issue.keys.map((key) => `\`${at ? `${at}.` : ""}${key}\``).join(", ");
+            return `unknown key ${keys}`;
+        }
+        // A bad record key's own reason is nested inside the issue.
+        const message = issue.code === "invalid_key" ? (issue.issues[0]?.message ?? issue.message) : issue.message;
+        return at ? `\`${at}\`: ${message}` : message;
+    });
+    throw new BasepadError(`${file} is invalid:\n  ${lines.join("\n  ")}`);
+}

package/dist/env-files.js

@@ -0,0 +1,123 @@
+/**
+ * Env files: basepad sets exactly the keys the config names, and nothing else in the file changes.
+ */
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+/**
+ * Copies each env file a worktree lacks from main's folder, so its other lines (secrets, settings)
+ * come along before basepad sets its own keys. A file the worktree has is its own, and kept.
+ */
+export async function copyEnvFiles(from, to, paths) {
+    for (const path of paths) {
+        const source = resolve(from, path);
+        const target = resolve(to, path);
+        if (existsSync(target) || !existsSync(source))
+            continue;
+        await mkdir(dirname(target), { recursive: true });
+        await copyFile(source, target);
+    }
+}
+/**
+ * Sets each file's keys, paths resolved from `root`, creating a file that is missing. A file whose
+ * keys already read as wanted is not written. Returns the paths it changed.
+ */
+export async function writeEnvFiles(root, files) {
+    const changed = [];
+    for (const [path, keys] of Object.entries(files)) {
+        const file = resolve(root, path);
+        const text = await readFile(file, "utf8").catch((error) => {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        const next = setKeys(text ?? "", keys);
+        if (next === text)
+            continue;
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, next);
+        changed.push(path);
+    }
+    return changed;
+}
+/** One `KEY=value` assignment's start: optional `export`, the key, then `=`. */
+const ASSIGNMENT = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_.-]*)(\s*=\s*)/;
+/**
+ * Sets `keys` in an env file's text: in place where a key is assigned (every assignment of it),
+ * appended in the order given where it is not. Every other byte is kept. A key whose value already
+ * reads as the wanted one is left as written, so setting the same keys twice changes nothing.
+ */
+export function setKeys(text, keys) {
+    const wanted = new Map(Object.entries(keys).map(([key, value]) => [key, String(value)]));
+    const found = new Set();
+    const lines = text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = ASSIGNMENT.exec(line);
+        const key = match?.[2];
+        if (!match || key === undefined || !wanted.has(key)) {
+            out.push(line);
+            continue;
+        }
+        found.add(key);
+        // A quoted value may run over several lines; take them all as this assignment.
+        let assignment = line;
+        while (opensQuote(assignment.slice(match[0].length)) && i + 1 < lines.length) {
+            i++;
+            assignment += lines[i];
+        }
+        const ending = /\r?\n$/.exec(assignment)?.[0] ?? "";
+        const raw = assignment.slice(match[0].length, assignment.length - ending.length);
+        const value = wanted.get(key);
+        out.push(readValue(raw) === value
+            ? assignment
+            : `${match[1]}${key}${match[3]}${quote(value)}${ending}`);
+    }
+    const missing = [...wanted].filter(([key]) => !found.has(key));
+    if (missing.length === 0)
+        return out.join("");
+    const newline = text.includes("\r\n") ? "\r\n" : "\n";
+    const gap = text === "" || text.endsWith("\n") ? "" : newline;
+    return `${out.join("")}${gap}${missing.map(([key, value]) => `${key}=${quote(value)}${newline}`).join("")}`;
+}
+/** Whether a raw value starts a quoted string it does not close. */
+function opensQuote(raw) {
+    const q = raw[0];
+    if (q !== '"' && q !== "'")
+        return false;
+    return closing(raw, q) === -1;
+}
+/** The index of the quote closing a value that starts with `q`, or -1. */
+function closing(raw, q) {
+    for (let i = 1; i < raw.length; i++) {
+        if (q === '"' && raw[i] === "\\")
+            i++;
+        else if (raw[i] === q)
+            return i;
+    }
+    return -1;
+}
+/** What a raw value reads as: quoted literally or with escapes, or bare up to a ` #` comment. */
+function readValue(raw) {
+    const q = raw[0];
+    if (q === "'" || q === '"') {
+        const end = closing(raw, q);
+        if (end === -1)
+            return raw;
+        const inner = raw.slice(1, end);
+        return q === "'" ? inner : inner.replace(/\\(.)/gs, (_, c) => (c === "n" ? "\n" : c));
+    }
+    return raw.replace(/\s+#.*$/, "").trim();
+}
+/**
+ * A value as written: bare when that reads back the same in every common parser, else in single
+ * quotes (literal, no expansion), else in double quotes with `\` and `"` escaped.
+ */
+export function quote(value) {
+    if (/^[A-Za-z0-9_@%+=:,./?&~-]*$/.test(value))
+        return value;
+    if (!value.includes("'") && !value.includes("\n"))
+        return `'${value}'`;
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", "\\n")}"`;
+}

package/dist/forward.js

@@ -0,0 +1,53 @@
+import { existsSync } from "node:fs";
+import { connect, createServer } from "node:net";
+import { fileURLToPath } from "node:url";
+/** A peer on this machine, as a dual-stack socket reports it. */
+const LOOPBACK = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+/** How often it checks that the supervisor still runs. */
+const CHECK_MS = 500;
+export async function forward({ port, to, whileExists }) {
+    const open = new Set();
+    const server = createServer((client) => {
+        // Bound on every address, it would serve the network: only this machine gets through.
+        if (!LOOPBACK.has(client.remoteAddress ?? "")) {
+            client.destroy();
+            return;
+        }
+        const upstream = connect({ host: "127.0.0.1", port: to });
+        open.add(client).add(upstream);
+        client.pipe(upstream).pipe(client);
+        const end = () => {
+            client.destroy();
+            upstream.destroy();
+            open.delete(client);
+            open.delete(upstream);
+        };
+        client.on("error", end).on("close", end);
+        upstream.on("error", end).on("close", end);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        // `::` takes IPv4 too.
+        server.listen(port, "::", resolve);
+    });
+    let close;
+    const stopped = new Promise((resolve) => {
+        const check = setInterval(() => {
+            if (!existsSync(whileExists))
+                void close();
+        }, CHECK_MS);
+        close = () => {
+            clearInterval(check);
+            for (const socket of open)
+                socket.destroy();
+            return new Promise((done) => server.close(() => done())).then(resolve);
+        };
+    });
+    return { port: server.address().port, stopped, close };
+}
+// Run as a process of its own (`node forward.js <port> <to> <whileExists>`), detached from `serve`:
+// it exits once it stops, or at once when it cannot bind (something else took the port).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const [port, to, whileExists] = process.argv.slice(2);
+    forward({ port: Number(port), to: Number(to), whileExists: whileExists }).then((forwarder) => forwarder.stopped.then(() => process.exit(0)), () => process.exit(1));
+}

package/dist/hosts.js

@@ -0,0 +1,79 @@
+import { lookup } from "node:dns/promises";
+import { access, constants, readFile, writeFile } from "node:fs/promises";
+/**
+ * Name resolution for server-side code. Browsers and curl resolve `*.localhost` themselves, and so
+ * do macOS and Linux with systemd's resolver; glibc without it (a container) and musl do not. There
+ * basepad adds the project's domains to the hosts file, or says which lines to add.
+ */
+const HOSTS_FILE = "/etc/hosts";
+/** `text` with the project's block of domains set: replaced where it is, else appended. Pure. */
+export function withHosts(text, name, hosts) {
+    const start = `# >>> basepad ${name}\n`;
+    const end = `# <<< basepad ${name}\n`;
+    const block = `${start}${hosts.map((host) => `127.0.0.1 ${host}\n`).join("")}${end}`;
+    const at = text.indexOf(start);
+    const until = at === -1 ? -1 : text.indexOf(end, at);
+    if (at !== -1 && until !== -1) {
+        return text.slice(0, at) + block + text.slice(until + end.length);
+    }
+    const gap = text === "" || text.endsWith("\n") ? "" : "\n";
+    return `${text}${gap}${block}`;
+}
+/** `text` without the project's block of domains. Pure. */
+export function withoutHosts(text, name) {
+    const start = `# >>> basepad ${name}\n`;
+    const end = `# <<< basepad ${name}\n`;
+    const at = text.indexOf(start);
+    const until = at === -1 ? -1 : text.indexOf(end, at);
+    if (at === -1 || until === -1)
+        return text;
+    return text.slice(0, at) + text.slice(until + end.length);
+}
+/** Takes the project's block out of the hosts file, when it is there and writable. */
+export async function dropHosts(name) {
+    const current = await readFile(HOSTS_FILE, "utf8").catch(() => undefined);
+    if (current === undefined)
+        return;
+    const text = withoutHosts(current, name);
+    if (text !== current && (await writable(HOSTS_FILE)))
+        await writeFile(HOSTS_FILE, text);
+}
+/**
+ * Makes the project's domains resolve: nothing when they already do (and no block of ours is
+ * there to keep current), else writes its block when the file is writable, else returns the lines
+ * for the developer to add. Returns what to tell them.
+ */
+export async function syncHosts(name, hosts) {
+    if (hosts.length === 0)
+        return [];
+    const current = await readFile(HOSTS_FILE, "utf8").catch(() => undefined);
+    if (current === undefined)
+        return [];
+    const ours = current.includes(`# >>> basepad ${name}\n`);
+    if (!ours) {
+        const missing = [];
+        for (const host of hosts)
+            if (!(await resolves(host)))
+                missing.push(host);
+        if (missing.length === 0)
+            return [];
+    }
+    const text = withHosts(current, name, hosts);
+    if (text === current)
+        return [];
+    if (!(await writable(HOSTS_FILE))) {
+        return [
+            `This system does not resolve ${name}'s domains for server-side code. Add to ${HOSTS_FILE}:`,
+            ...hosts.map((host) => `  127.0.0.1 ${host}`),
+        ];
+    }
+    // In place, not by rename: in a container the hosts file is a bind mount.
+    await writeFile(HOSTS_FILE, text);
+    return [`Added ${name}'s domains to ${HOSTS_FILE}.`];
+}
+async function resolves(host) {
+    return lookup(host).then(() => true, () => false);
+}
+async function writable(file) {
+    return access(file, constants.W_OK).then(() => true, () => false);
+}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * What a project's `basepad.config.ts` imports: `defineConfig` and the service kinds. ADR 0001: the
+ * config is the only way a project talks to basepad.
+ */
+export { mailpit } from "./catalogue/mailpit.js";
+export { postgres } from "./catalogue/postgres.js";
+export { redis } from "./catalogue/redis.js";
+/** Types a project's config. It returns the config unchanged. */
+export function defineConfig(config) {
+    return config;
+}

package/dist/init.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { CONFIG_FILE, LOCAL_FILE } from "./config.js";
+import { BasepadError } from "./internal/exec.js";
+/**
+ * `basepad init`: a starter config named from the folder, the local file kept out of git, and
+ * basepad added as a devDependency.
+ */
+const PACKAGE = "basepad";
+export async function init({ cwd, print }) {
+    const file = join(cwd, CONFIG_FILE);
+    if (existsSync(file)) {
+        throw new BasepadError(`${file} already exists; \`basepad init\` leaves it as it is.`);
+    }
+    const name = labelOf(basename(cwd));
+    await writeFile(file, starter(name));
+    print(`Wrote ${CONFIG_FILE} with name "${name}".`);
+    if (await ignoreLocalFile(cwd))
+        print(`Added ${LOCAL_FILE} to .gitignore.`);
+    if (await addDevDependency(cwd)) {
+        print(`Added ${PACKAGE} to devDependencies in package.json; install it with your package manager.`);
+    }
+}
+/** A folder's name as a lowercase DNS label. Never truncated: `status` says when it is too long. */
+function labelOf(folder) {
+    const label = folder
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return label || "project";
+}
+function starter(name) {
+    return `import { defineConfig } from "${PACKAGE}";
+
+export default defineConfig({
+	name: ${JSON.stringify(name)},
+	// services: {
+	// 	db: postgres({ version: 18 }), // import postgres from "${PACKAGE}" too
+	// },
+	apps: {
+		// web: { run: "npm run dev" }, // https://web.${name}.localhost
+	},
+	// env: ({ db, web }) => ({
+	// 	".env.local": { DATABASE_URL: db.url, APP_URL: web.url },
+	// }),
+});
+`;
+}
+/** Adds the local file to `.gitignore`, creating it. Returns whether it changed anything. */
+async function ignoreLocalFile(cwd) {
+    const file = join(cwd, ".gitignore");
+    const text = await readFile(file, "utf8").catch(() => "");
+    const lines = text.split(/\r?\n/).map((line) => line.trim());
+    if (lines.includes(LOCAL_FILE) || lines.includes(`/${LOCAL_FILE}`))
+        return false;
+    const gap = text === "" || text.endsWith("\n") ? "" : "\n";
+    await writeFile(file, `${text}${gap}${LOCAL_FILE}\n`);
+    return true;
+}
+/** Adds basepad to `package.json`'s devDependencies when the file exists and lacks it. */
+async function addDevDependency(cwd) {
+    const file = join(cwd, "package.json");
+    const text = await readFile(file, "utf8").catch(() => undefined);
+    if (text === undefined)
+        return false;
+    let pkg;
+    try {
+        pkg = JSON.parse(text);
+    }
+    catch (error) {
+        throw new BasepadError(`${file} is not valid JSON: ${error.message}`);
+    }
+    const has = (field) => typeof pkg[field] === "object" && pkg[field] !== null && PACKAGE in pkg[field];
+    if (has("dependencies") || has("devDependencies"))
+        return false;
+    pkg.devDependencies = {
+        ...pkg.devDependencies,
+        [PACKAGE]: `^${await ownVersion()}`,
+    };
+    const indent = /^[ \t]+/m.exec(text)?.[0] ?? "\t";
+    await writeFile(file, `${JSON.stringify(pkg, null, indent)}\n`);
+    return true;
+}
+async function ownVersion() {
+    const text = await readFile(new URL("../package.json", import.meta.url), "utf8");
+    return JSON.parse(text).version;
+}

package/dist/internal/exec.js

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+/** A failure the user can act on. The CLI prints its message without a stack. */
+export class BasepadError extends Error {
+}
+/** Runs a program to completion and captures its output. Never throws for a non-zero exit. */
+export function exec(file, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+        });
+        child.stdin?.end(options.input);
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8").on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.setEncoding("utf8").on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            if (error.code === "ENOENT")
+                reject(new BasepadError(`basepad needs \`${file}\` on PATH.`));
+            else
+                reject(error);
+        });
+        child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+}
+/** Runs a program and returns its stdout, or throws with what it printed. */
+export async function must(file, args, options = {}) {
+    const out = await exec(file, args, options);
+    if (out.code !== 0) {
+        const detail = (out.stderr || out.stdout).trim();
+        throw new BasepadError(`\`${[file, ...args].join(" ")}\` failed (exit ${out.code}):\n${detail}`);
+    }
+    return out.stdout;
+}
+/** Quotes one word for a POSIX shell. */
+export function shellQuote(word) {
+    return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`;
+}
+/**
+ * Runs a program on the user's own terminal, so it can ask them things (`sudo`'s password, a
+ * confirmation). Returns its exit code; never throws for a non-zero exit.
+ */
+export function interactive(file, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}