basepad 0.0.0-stage → 0.0.0

package/dist/supervisor.js

@@ -0,0 +1,477 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { request as httpsRequest } from "node:https";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { connect } from "node:tls";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { interactive, must, shellQuote } from "./internal/exec.js";
+import { answers } from "./internal/ports.js";
+import { daemonId, ofDaemon, supervisorPaths } from "./layout.js";
+import { install } from "./tools.js";
+import { PITCHFORK_VERSION } from "./versions.js";
+/**
+ * The settings basepad's pitchfork runs with, in its user config (which also holds pitchfork's
+ * registry, so basepad sets keys through pitchfork rather than writing the file). The proxy's are
+ * read once, at supervisor start.
+ */
+function settings(machine) {
+    return {
+        // Every daemon basepad runs is waited on by basepad itself, never by a fixed delay.
+        "general.ready_delay": "0s",
+        // A worktree's domains are <daemon>.<folder>.<name>.localhost, its folder being a git worktree.
+        "general.worktree": "true",
+        "proxy.enable": "true",
+        "proxy.https": "true",
+        "proxy.port": String(machine.proxyPort),
+        // Name resolution, trust and port-free URLs are `basepad setup`'s, not pitchfork's own.
+        "proxy.dns": "false",
+        "proxy.sync_hosts": "false",
+        "proxy.auto_trust": "false",
+        // A first request to an app's domain starts it, and what it depends on. `hold` keeps an app
+        // stopped, until `start`.
+        "proxy.auto_start": "true",
+    };
+}
+/** What `serve` prints before a settings change restarts a running supervisor. */
+export const RESTART_WARNING = "basepad's supervisor restarts to take new settings, which stops every project's running apps and services. Run `basepad up` in a project to start it again.";
+/**
+ * Installs pitchfork through mise and opens basepad's supervisor. Nothing starts until asked.
+ * `print` gets what the developer must know before it happens: a restart that stops their apps.
+ */
+export async function openSupervisor(machine, print) {
+    const paths = supervisorPaths(machine);
+    const dirs = {
+        PITCHFORK_STATE_DIR: paths.state,
+        PITCHFORK_CONFIG_DIR: paths.config,
+        PITCHFORK_LOGS_DIR: paths.logs,
+    };
+    const pitchfork = (await install("pitchfork", PITCHFORK_VERSION, machine.home)).bin("pitchfork");
+    const env = supervisorEnv(dirs);
+    const run = (...args) => must(pitchfork, args, { cwd: machine.home, env });
+    const running = () => existsSync(join(dirs.PITCHFORK_STATE_DIR, "sock"));
+    const { ca } = paths;
+    /** Sets what differs; a running supervisor restarts to take changed settings (its daemons stop). */
+    const applySettings = async () => {
+        const current = z
+            .array(z.looseObject({ key: z.string(), value: z.string() }))
+            .parse(JSON.parse(await run("settings", "--json")));
+        const now = new Map(current.map((entry) => [entry.key, entry.value]));
+        const changes = Object.entries(settings(machine)).filter(([key, value]) => now.get(key) !== value);
+        for (const [key, value] of changes)
+            await run("settings", "set", key, value, "--global");
+        if (changes.length > 0 && running()) {
+            print(RESTART_WARNING);
+            await run("supervisor", "start", "--force");
+        }
+    };
+    /** The namespace's daemons. With no supervisor running there are none, and none is started. */
+    const list = async (namespace) => {
+        if (!running())
+            return [];
+        return z.array(Listed).parse(JSON.parse(await run("list", "--json", "--namespace", namespace)));
+    };
+    const states = async (namespace) => {
+        const out = {};
+        for (const daemon of await list(namespace))
+            out[daemon.name] = await stateOf(daemon);
+        return out;
+    };
+    const stopAll = async (namespace, names) => {
+        const running = (await list(namespace)).filter((d) => LIVE.has(d.status) && (names === undefined || names.includes(d.name)));
+        if (running.length > 0)
+            await run("stop", ...running.map((d) => d.id));
+    };
+    const hold = async (namespace, names) => {
+        for (const daemon of await list(namespace)) {
+            if (names.includes(daemon.name) && !daemon.disabled)
+                await run("disable", daemon.id);
+        }
+    };
+    const registrations = async () => z
+        .array(z.looseObject({ namespace: z.string(), dir: z.string() }))
+        .parse(JSON.parse(await run("config", "list", "--json")))
+        .map(({ namespace, dir }) => ({ namespace, dir }));
+    const registeredDir = async (namespace) => (await registrations()).find((entry) => entry.namespace === namespace)?.dir;
+    /** Drops a namespace from pitchfork's registry, which keeps its folder after its file is detached. */
+    const forget = async (namespace, definitions) => {
+        await run("config", "remove", definitions);
+        const file = join(dirs.PITCHFORK_CONFIG_DIR, "config.toml");
+        if (existsSync(file)) {
+            await writeFile(file, withoutNamespace(await readFile(file, "utf8"), namespace));
+        }
+    };
+    const serve = async () => {
+        await applySettings();
+        if (!running()) {
+            await run("supervisor", "start");
+            // The proxy (and its CA, on a first start) comes up just after the supervisor returns.
+            const until = Date.now() + 5000;
+            while (!(await listening(machine.proxyPort)) && Date.now() < until) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+        }
+        if (machine.forwards443)
+            await forward443();
+    };
+    /**
+     * Starts the forwarder (src/forward.ts) when nothing answers on port 443, and waits briefly for
+     * it. Something else there (Herd, Valet, a pf redirect) is left alone. It stops with the
+     * supervisor; the next `serve` starts it again.
+     */
+    const forward443 = async () => {
+        if ((await probeStandardPort(ca)) !== "closed")
+            return;
+        const script = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./forward.ts" : "./forward.js", import.meta.url));
+        const sock = join(dirs.PITCHFORK_STATE_DIR, "sock");
+        spawn(process.execPath, [script, "443", String(machine.proxyPort), sock], {
+            detached: true,
+            stdio: "ignore",
+        }).unref();
+        const until = Date.now() + 2000;
+        while ((await probeStandardPort(ca)) === "closed" && Date.now() < until) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    };
+    return {
+        ca,
+        serve,
+        standardPort: () => probeStandardPort(ca),
+        async proxySetupPlan() {
+            const out = await run("proxy", "setup", "--dry-run");
+            return (out
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line !== "" && !line.endsWith("following:"))
+                // pitchfork lists this step even when the CA exists, and skips it when applying.
+                .filter((line) => !(line.startsWith("generate the pitchfork CA") && existsSync(ca))));
+        },
+        proxySetup: () => interactive(pitchfork, ["proxy", "setup", "--yes"], { cwd: machine.home, env }),
+        proxyUndo: () => interactive(pitchfork, ["proxy", "setup", "--undo", "--yes"], { cwd: machine.home, env }),
+        async trust() {
+            await run("proxy", "trust");
+        },
+        async register({ namespace, label, dir, definitions, daemons }) {
+            await serve();
+            const text = toml(daemons);
+            // Written even when empty (a worktree with no apps): pitchfork refuses a missing file.
+            if ((await readFile(definitions, "utf8").catch(() => undefined)) !== text) {
+                await mkdir(dirname(definitions), { recursive: true });
+                await writeFile(definitions, text);
+            }
+            const owner = await registeredDir(namespace);
+            if (owner !== undefined && owner !== dir) {
+                // pitchfork keeps a namespace's folder even after its file is detached, and refuses
+                // another, so the namespace's entry is dropped from its registry by hand.
+                await stopAll(namespace);
+                await forget(namespace, definitions);
+            }
+            await run("config", "add", definitions, "--dir", dir, "--namespace", namespace, ...(label === undefined ? [] : ["--label", label]));
+        },
+        owner: registeredDir,
+        registrations,
+        async unregister({ namespace, definitions }) {
+            if (running()) {
+                await stopAll(namespace);
+                await run("clean", namespace);
+            }
+            await forget(namespace, definitions);
+            await rm(definitions, { force: true });
+        },
+        async start(namespace, names, waitMs, hosts) {
+            const listed = await list(namespace);
+            for (const daemon of listed) {
+                if (daemon.disabled && names.includes(daemon.name))
+                    await run("enable", daemon.id);
+            }
+            const idle = names.filter((name) => !listed.some((d) => d.name === name && LIVE.has(d.status)));
+            // basepad waits on them itself, below, so pitchfork's readiness here is immediate.
+            // pitchfork fails the start when a daemon fails: that is an app's failure, read below.
+            let refused;
+            if (idle.length > 0) {
+                await run("start", ...idle.map((name) => daemonId(namespace, name)), "--cmd", "true").catch((error) => {
+                    refused = error;
+                });
+            }
+            const until = Date.now() + waitMs;
+            for (;;) {
+                const now = await states(namespace);
+                const settled = names.every((name) => now[name] !== "starting");
+                if (settled || Date.now() >= until) {
+                    // With none it was asked to start failed, pitchfork's refusal is its own trouble: an
+                    // app already live, left alone here, that has failed since does not explain it.
+                    if (refused !== undefined && !idle.some((name) => now[name] === "failed")) {
+                        throw refused;
+                    }
+                    // The proxy re-reads its routes every 2 s, so a new daemon's domain can lag.
+                    for (const [name, host] of Object.entries(hosts)) {
+                        if (now[name] !== "running")
+                            continue;
+                        while (!(await routed(machine.proxyPort, host)) && Date.now() < until + 3000) {
+                            await new Promise((resolve) => setTimeout(resolve, 200));
+                        }
+                    }
+                    return now;
+                }
+                await new Promise((resolve) => setTimeout(resolve, 200));
+            }
+        },
+        stop: stopAll,
+        hold,
+        status: states,
+        async logs(namespace, name, since, lines) {
+            const out = await run("logs", daemonId(namespace, name), "-n", String(lines), "--since", localTime(since), "--raw", "--no-pager");
+            return out.split("\n").filter((line) => line !== "");
+        },
+        async daemons() {
+            if (!running())
+                return [];
+            const listed = z.array(Listed).parse(JSON.parse(await run("list", "--json")));
+            return Promise.all(listed.map(async (daemon) => {
+                const state = await stateOf(daemon);
+                const port = daemon.active_port ?? daemon.port?.[0];
+                return {
+                    id: daemon.id,
+                    namespace: daemon.namespace ?? ofDaemon(daemon.id).namespace,
+                    name: daemon.name,
+                    state: state === "stopped" && !daemon.disabled ? "idle" : state,
+                    ...(daemon.pid == null ? {} : { pid: daemon.pid }),
+                    ...(port === undefined || port === null ? {} : { port }),
+                    ...(daemon.error == null ? {} : { error: daemon.error }),
+                };
+            }));
+        },
+        follow(ids, history, line) {
+            if (ids.length === 0)
+                return () => { };
+            let stopped = false;
+            // One process follows them all from now. `-n` with several ids counts lines over all of
+            // them, so a chatty daemon would push out a crashed one's: each one's history is its own.
+            const tail = spawn(pitchfork, ["logs", ...ids, "--tail", "-n", "0"], {
+                cwd: machine.home,
+                env,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            const kill = () => tail.kill();
+            process.once("exit", kill);
+            const live = [];
+            let replayed = false;
+            createInterface({ input: tail.stdout }).on("line", (text) => {
+                const entry = parseLogLine(text, ids);
+                if (entry === undefined || stopped)
+                    return;
+                if (replayed)
+                    line(entry);
+                else
+                    live.push(entry);
+            });
+            Promise.all(ids.map((id) => (history === 0
+                ? Promise.resolve("")
+                : run("logs", id, "-n", String(history), "--no-pager")).then((out) => out
+                .split("\n")
+                .map((text) => parseLogLine(text, [id]))
+                .filter((entry) => entry !== undefined), () => []))).then((lists) => {
+                if (stopped)
+                    return;
+                // A stable sort: each daemon's own lines stay in order within a second.
+                const past = lists.flat().sort((a, b) => a.stamp.localeCompare(b.stamp));
+                // A line printed while both ran is in each; the history's copy is kept.
+                const key = (e) => `${e.id}\0${e.stamp}\0${e.text}`;
+                const seen = new Set(past.map(key));
+                for (const entry of [...past, ...live.filter((e) => !seen.has(key(e)))])
+                    line(entry);
+                replayed = true;
+            });
+            return () => {
+                stopped = true;
+                process.off("exit", kill);
+                kill();
+            };
+        },
+        logsCommand(namespace, name) {
+            // basepad's own pitchfork binary, so the command needs no mise and no PATH.
+            return `PITCHFORK_LOGS_DIR=${shellQuote(dirs.PITCHFORK_LOGS_DIR)} ${shellQuote(pitchfork)} logs ${daemonId(namespace, name)}`;
+        },
+    };
+}
+/**
+ * The environment pitchfork runs in, which its supervisor passes on to every daemon: the caller's,
+ * minus any `PITCHFORK_*` setting meant for a developer's own pitchfork, and with the PATH the
+ * developer had before the launcher moved basepad onto mise's Node.
+ */
+function supervisorEnv(dirs) {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("PITCHFORK_")));
+    if (env.BASEPAD_PATH)
+        env.PATH = env.BASEPAD_PATH;
+    delete env.BASEPAD_PATH;
+    return { ...env, ...dirs };
+}
+/** pitchfork's user config without the `[namespaces.<namespace>]` table. */
+function withoutNamespace(text, namespace) {
+    const headers = new Set([`[namespaces.${namespace}]`, `[namespaces."${namespace}"]`]);
+    const out = [];
+    let skipping = false;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("["))
+            skipping = headers.has(trimmed);
+        if (!skipping)
+            out.push(line);
+    }
+    return out.join("\n");
+}
+/** Whether the proxy has a route for `host`: its answer is anything but its own "No route". */
+function routed(port, host) {
+    return new Promise((resolve) => {
+        const req = httpsRequest({
+            host: "127.0.0.1",
+            port,
+            servername: host,
+            headers: { host },
+            rejectUnauthorized: false,
+            timeout: 1000,
+        }, (res) => {
+            let body = "";
+            res.setEncoding("utf8").on("data", (chunk) => {
+                body += chunk;
+            });
+            res.on("end", () => resolve(!(res.statusCode === 404 && body.includes("No route for"))));
+        });
+        // A slow answer comes from the app, so the proxy did route it.
+        req.on("timeout", () => {
+            resolve(true);
+            req.destroy();
+        });
+        req.on("error", () => resolve(false));
+        req.end();
+    });
+}
+/** The name the probe asks the proxy for: any name under `localhost` gets a certificate. */
+const PROBE_HOST = "basepad-probe.localhost";
+async function probeStandardPort(ca) {
+    const pem = await readFile(ca, "utf8").catch(() => undefined);
+    return new Promise((resolve) => {
+        const socket = connect({
+            host: "127.0.0.1",
+            port: 443,
+            servername: PROBE_HOST,
+            ca: pem ?? [],
+            rejectUnauthorized: false,
+        });
+        const done = (answer) => {
+            socket.destroy();
+            resolve(answer);
+        };
+        socket.setTimeout(1000, () => done("other"));
+        socket.on("secureConnect", () => done(pem && socket.authorized ? "proxy" : "other"));
+        socket.on("error", (error) => done(error.code === "ECONNREFUSED" ? "closed" : "other"));
+    });
+}
+/**
+ * One of pitchfork's log lines, `MM-DD HH:MM:SS [<id>] message`; with a single id given, without
+ * the `[<id>]`. `stamp` sorts lines by time.
+ */
+function parseLogLine(text, ids) {
+    const tagged = /^(?<day>\d\d-\d\d) (?<time>\d\d:\d\d:\d\d) \[(?<id>[^\]]+)\] ?(?<message>.*)$/.exec(text)?.groups;
+    const plain = /^(?<day>\d\d-\d\d) (?<time>\d\d:\d\d:\d\d) ?(?<message>.*)$/.exec(text)?.groups;
+    const [only] = ids;
+    const [groups, id] = tagged?.id !== undefined && ids.includes(tagged.id)
+        ? [tagged, tagged.id]
+        : ids.length === 1
+            ? [plain, only]
+            : [];
+    if (groups === undefined || id === undefined)
+        return undefined;
+    const { day = "", time = "", message = "" } = groups;
+    return { id, time, text: message, stamp: `${day} ${time}` };
+}
+/** One entry of `pitchfork list --json`; only what basepad reads. */
+const Listed = z.looseObject({
+    id: z.string(),
+    namespace: z.string().optional(),
+    name: z.string(),
+    pid: z.number().nullable().optional(),
+    error: z.string().nullable().optional(),
+    status: z.string(),
+    disabled: z.boolean().optional(),
+    active_port: z.number().nullable().optional(),
+    port: z.array(z.number()).optional(),
+});
+/** pitchfork's statuses of a daemon that is up or on its way up. */
+const LIVE = new Set(["running", "waiting", "restarting"]);
+/**
+ * A daemon with a port is running once something listens there; until then it is starting.
+ * pitchfork's `active_port` says it saw the daemon listen, so it is running with no connection of
+ * basepad's: a dev server logs each one, and mission control asks every second. pitchfork finds it
+ * some time after the daemon is ready, so until then basepad asks the port it gave the daemon:
+ * else an app that just answered its first request reads as starting.
+ */
+async function stateOf(daemon) {
+    if (daemon.status === "running") {
+        if (daemon.active_port != null)
+            return "running";
+        const port = daemon.port?.[0];
+        return port === undefined || (await listening(port)) ? "running" : "starting";
+    }
+    if (LIVE.has(daemon.status))
+        return "starting";
+    if (daemon.status === "errored" || daemon.status === "failed" || daemon.status === "completed") {
+        return "failed";
+    }
+    return "stopped";
+}
+/** Whether a daemon listens on `port`, on either loopback address. */
+function listening(port) {
+    return answers(port, ["127.0.0.1", "::1"]);
+}
+/**
+ * The definitions file. pitchfork's own `dir` key would make the proxy refuse a daemon that runs
+ * outside the registered folder, so each daemon `cd`s into its folder itself.
+ *
+ * Each daemon is ready once it listens on its port, so the proxy, starting it on a first request,
+ * forwards that request only once it can answer; a daemon with no port is ready at once. Never
+ * pitchfork's delay readiness, the default: it asks whether the process is live as the delay
+ * ends, which with no delay is mid-`exec` on macOS and can read as dead, and then `pitchfork start`
+ * waits forever on a daemon that runs. basepad's own `start` waits on daemons itself.
+ */
+function toml(daemons) {
+    return Object.entries(daemons)
+        .map(([name, daemon]) => {
+        const lines = [
+            `[daemons.${name}]`,
+            `run = ${JSON.stringify(`cd ${shellQuote(daemon.dir)} && ${daemon.run}`)}`,
+            `ready_cmd = ${JSON.stringify(readyCommand(daemon))}`,
+        ];
+        if (daemon.depends !== undefined && daemon.depends.length > 0) {
+            lines.push(`depends = ${JSON.stringify(daemon.depends)}`);
+        }
+        if (daemon.port !== undefined) {
+            lines.push(`port = { expect = [${daemon.port}], bump = true }`);
+        }
+        if (daemon.proxy === false)
+            lines.push("proxy = false");
+        if (daemon.stopSignal !== undefined) {
+            lines.push(`stop_signal = ${JSON.stringify(daemon.stopSignal)}`);
+        }
+        return `${lines.join("\n")}\n`;
+    })
+        .join("\n");
+}
+/**
+ * A shell command that succeeds once the daemon listens on either loopback address: on `PORT`,
+ * which pitchfork gives a daemon with a port, else on the port it `listens` on.
+ */
+function readyCommand(daemon) {
+    const port = daemon.port !== undefined ? "$PORT" : daemon.listens;
+    if (port === undefined)
+        return "true";
+    const probe = `: <>/dev/tcp/127.0.0.1/${port} || : <>/dev/tcp/::1/${port}`;
+    return `bash -c '${probe}' 2>/dev/null`;
+}
+/** `YYYY-MM-DD HH:MM:SS` in local time, as `pitchfork logs --since` reads it. */
+function localTime(date) {
+    const p = (n) => String(n).padStart(2, "0");
+    return `${date.getFullYear()}-${p(date.getMonth() + 1)}-${p(date.getDate())} ${p(date.getHours())}:${p(date.getMinutes())}:${p(date.getSeconds())}`;
+}

package/dist/tls.js

@@ -0,0 +1,99 @@
+import { generateKeyPairSync, randomBytes, X509Certificate } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { must } from "./internal/exec.js";
+import { waitFor } from "./internal/ports.js";
+/** Days a new certificate lasts: under the 398 browsers accept. */
+const DAYS = 365;
+/** A certificate with less left than this is made again. */
+const RENEW_MS = 30 * 24 * 60 * 60 * 1000;
+/** How long a lock another basepad holds is waited on before it is taken as abandoned. */
+const STALE_LOCK_MS = 30_000;
+/**
+ * Makes the certificate for `localhost` that apps with no domain serve HTTPS with, signed by the
+ * proxy's CA, unless one it signed, with time left, is already there. Waits up to `waitMs` for the
+ * CA, which the proxy writes as it starts. Two basepads at once take turns, and each file is
+ * replaced whole, so an app never reads a key and a certificate that do not match.
+ */
+export async function ensureLocalhostCertificate(paths, waitMs = 10_000) {
+    const ca = await waitFor(() => readFile(paths.ca, "utf8"), `No CA at ${paths.ca} to sign the certificate for localhost with.`, waitMs);
+    if (await current(paths.cert, ca))
+        return;
+    const dir = dirname(paths.cert);
+    await mkdir(dir, { recursive: true });
+    const lock = `${paths.cert}.lock`;
+    await waitFor(() => takeLock(lock), `${lock} is held by another basepad.`, STALE_LOCK_MS * 2);
+    const scratch = await mkdtemp(join(dir, ".new-"));
+    try {
+        // Another basepad may have made it while this one waited.
+        if (await current(paths.cert, ca))
+            return;
+        const key = join(scratch, "key.pem");
+        const cert = join(scratch, "cert.pem");
+        const csr = join(scratch, "localhost.csr");
+        const extensions = join(scratch, "localhost.ext");
+        const { privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+        await writeFile(key, privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 });
+        await writeFile(extensions, [
+            "subjectAltName=DNS:localhost,IP:127.0.0.1,IP:::1",
+            "extendedKeyUsage=serverAuth",
+            "keyUsage=digitalSignature",
+            "basicConstraints=CA:FALSE",
+        ].join("\n"));
+        await must("openssl", ["req", "-new", "-key", key, "-subj", "/CN=localhost", "-out", csr]);
+        await must("openssl", [
+            "x509",
+            "-req",
+            "-in",
+            csr,
+            "-CA",
+            paths.ca,
+            "-CAkey",
+            paths.caKey,
+            "-set_serial",
+            `0x${randomBytes(8).toString("hex")}`,
+            "-days",
+            String(DAYS),
+            "-sha256",
+            "-extfile",
+            extensions,
+            "-out",
+            cert,
+        ]);
+        await rename(key, paths.key);
+        await rename(cert, paths.cert);
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+        await rm(lock, { recursive: true, force: true });
+    }
+}
+/** Takes the lock, a folder only one process can make; throws while another holds it. */
+async function takeLock(lock) {
+    try {
+        await mkdir(lock);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const age = Date.now() - (await stat(lock)).mtimeMs;
+        if (age < STALE_LOCK_MS)
+            throw new Error("another basepad is making it");
+        await rm(lock, { recursive: true, force: true });
+        await mkdir(lock);
+    }
+}
+/** Whether the certificate is there, signed by this CA, and not about to expire. */
+async function current(cert, ca) {
+    const pem = await readFile(cert, "utf8").catch(() => undefined);
+    if (pem === undefined)
+        return false;
+    try {
+        const certificate = new X509Certificate(pem);
+        const signed = certificate.verify(new X509Certificate(ca).publicKey);
+        return signed && Date.parse(certificate.validTo) - Date.now() > RENEW_MS;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tools.js

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { BasepadError, must } from "./internal/exec.js";
+/**
+ * Installs `tool@version` through mise when it is missing, and locates it. Runs mise from `cwd`
+ * (basepad's home), so no project's mise config is read or needs trusting.
+ */
+export async function install(tool, version, cwd) {
+    const spec = `${tool}@${version}`;
+    await mkdir(cwd, { recursive: true });
+    // Always, not only when `mise where` fails: `where` answers for an install still in progress
+    // (another basepad installing at the same moment), and `install` waits on mise's lock for it.
+    // mise fails an install when it cannot fetch a skill the tool declares; basepad needs only the tool.
+    await must("mise", ["install", "--quiet", spec], {
+        cwd,
+        env: { ...process.env, MISE_SKILLS_FETCH: "false" },
+    });
+    const dir = (await must("mise", ["where", spec], { cwd })).trim();
+    const paths = (await must("mise", ["bin-paths", spec], { cwd })).split("\n").filter(Boolean);
+    return {
+        dir,
+        bin(program) {
+            for (const path of paths) {
+                const file = join(path, program);
+                if (existsSync(file))
+                    return file;
+            }
+            throw new BasepadError(`mise's ${spec} has no \`${program}\` in ${paths.join(", ")}.`);
+        },
+    };
+}

package/dist/versions.js

@@ -0,0 +1,19 @@
+/**
+ * The tool versions basepad relies on, in one place. Kept free of imports and of syntax newer
+ * than Node 18, since the launcher reads it before basepad has moved onto a Node 24.
+ */
+/** The oldest mise basepad runs with. Lower it only with a test on that version. */
+export const MISE_MIN_VERSION = "2026.10.24";
+/** The Node basepad runs on, from mise, whatever Node the project has. */
+export const NODE_MAJOR = 24;
+/** pitchfork is pinned: 2.34.0 fixes a port clash between apps started in parallel. */
+export const PITCHFORK_VERSION = "2.34.0";
+/**
+ * pgvector, per Postgres major, from conda-forge (mise's Postgres is conda-forge's build). 0.8.0 is
+ * the last build for 17.
+ */
+export const PGVECTOR_VERSIONS = { 17: "0.8.0", 18: "0.8.6" };
+/** Mailpit's major, from mise's registry. */
+export const MAILPIT_VERSION = "1";
+/** Redis's major, from mise (conda-forge's build). */
+export const REDIS_VERSION = "8";