neon 2.1.1 → 2.29.0

package/dist/commands/dev.js

@@ -0,0 +1,698 @@
+import { spawn, spawnSync } from "node:child_process";
+import { once } from "node:events";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import { resolveDevEnv } from "../dev/env.js";
+import { resolveFunctionsFromConfig, } from "../dev/functions.js";
+import { resolveWatchInputs } from "../dev/inputs.js";
+import { log } from "../log.js";
+import { branchIdResolve } from "../utils/enrichers.js";
+import { bundleEntry } from "../utils/esbuild.js";
+export const command = "dev";
+export const describe = "Run Neon Functions locally with a dev server";
+export const builder = (argv) => argv
+    .usage("$0 dev [--source <path>] [options]")
+    .example("$0 dev --source ./functions/hello.ts", "Serve one function on a free port with hot reload")
+    .example("$0 dev", "Serve every function declared in neon.ts (one dev server each)")
+    .example("$0 dev --source ./functions/hello.ts --port 3000", "Serve one function on an explicit port (fails if the port is taken)")
+    .options({
+    source: {
+        describe: "Path to a single function entry module. Omit to serve every " +
+            "function declared in neon.ts.",
+        type: "string",
+    },
+    port: {
+        describe: "Port to listen on (single-function mode only, with --source). " +
+            "Fails if taken. Without it (and without a PORT env var) a free " +
+            "port is chosen automatically.",
+        type: "number",
+    },
+})
+    .strict();
+export const handler = async (props) => {
+    if (props.source !== undefined) {
+        await runSingleSource(props);
+        return;
+    }
+    // No --source: --port has no single target to bind, so reject it explicitly
+    // rather than silently ignoring it.
+    if (props.port !== undefined) {
+        throw new Error("--port can only be used with --source. To set ports for the functions " +
+            "in neon.ts, give each one a `dev.port` in its config.");
+    }
+    await runFromConfig(props);
+};
+/** Single-function mode: serve exactly the `--source` path (legacy behavior). */
+const runSingleSource = async (props) => {
+    const source = resolve(process.cwd(), props.source);
+    if (!existsSync(source)) {
+        throw new Error(`Source file not found: ${source}`);
+    }
+    const branchId = await resolveBranchId(props);
+    const { vars: neonEnv, skipped } = await resolveDevEnv({
+        cwd: process.cwd(),
+        ...(props.projectId ? { projectId: props.projectId } : {}),
+        ...(branchId ? { branchId } : {}),
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+    });
+    const unit = {
+        slug: null,
+        source,
+        bundleDir: join(process.cwd(), "node_modules", ".neon-dev"),
+        childEnv: buildChildEnv(neonEnv, portFromProps(props.port)),
+        label: null,
+        envSummary: { neon: Object.keys(neonEnv), fn: [] },
+    };
+    // No config reload in single-source mode: there's exactly one file to serve, and
+    // nothing to add or remove. neon.ts hot-reload is config-mode only.
+    await runSupervisor([unit], {
+        ...(skipped ? { envNote: skipped.reason } : {}),
+    });
+};
+/**
+ * Multi-function mode: serve every function declared in neon.ts. Requires a neon.ts
+ * (there is no single source to fall back on), one dev server per function.
+ */
+const runFromConfig = async (props) => {
+    const branchId = await resolveBranchId(props);
+    const resolved = await resolveFunctionsFromConfig(process.cwd());
+    if (resolved === null) {
+        throw new Error("No --source given and no neon.ts found. Pass --source <path> to run a " +
+            "single function, or add a neon.ts that declares functions under " +
+            "`preview.functions`.");
+    }
+    const { configPath, functions } = resolved;
+    if (functions.length === 0) {
+        throw new Error("neon.ts has no functions to serve. Add at least one under " +
+            "`preview.functions`, or pass --source <path>.");
+    }
+    const { vars: neonEnv, skipped } = await resolveDevEnv({
+        cwd: process.cwd(),
+        ...(props.projectId ? { projectId: props.projectId } : {}),
+        ...(branchId ? { branchId } : {}),
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+    });
+    const units = planFunctionsToUnits(functions, neonEnv, DEFAULT_PORT_BASE);
+    // Re-derive the units from neon.ts on demand so the config watcher can hot-add/remove
+    // functions without restarting the dev server. `searchBase` lets a freshly-added unit
+    // start probing above the ports already taken by live units (the runtime still walks
+    // upward from there, so this never fails — it just keeps startup deterministic).
+    const replan = async (searchBase) => {
+        const re = await resolveFunctionsFromConfig(process.cwd());
+        if (re === null)
+            return null;
+        return planFunctionsToUnits(re.functions, neonEnv, searchBase);
+    };
+    await runSupervisor(units, {
+        reload: { configPath, replan },
+        ...(skipped ? { envNote: skipped.reason } : {}),
+    });
+};
+/**
+ * Map a list of {@link PlannedFunction}s to {@link ServedUnit}s, coordinating the search
+ * base across them so search-mode functions don't all probe the same starting port.
+ *
+ * Each search-mode (no `dev.port`) function gets a distinct base starting at
+ * `searchBase`; the runtime still walks upward from its base, so an occupied base
+ * self-resolves and this never fails — the offset just makes startup deterministic.
+ */
+const planFunctionsToUnits = (functions, neonEnv, searchBase) => {
+    let searchOffset = 0;
+    return functions.map((fn) => {
+        const base = searchBase + searchOffset;
+        if (fn.port === undefined)
+            searchOffset += 1;
+        return plannedToUnit(fn, neonEnv, base);
+    });
+};
+/**
+ * Resolve the selected branch id from props, if any. Best-effort: a failure here only
+ * means env injection is skipped, so it never throws.
+ */
+const resolveBranchId = async (props) => {
+    if (!props.apiClient || !props.projectId)
+        return undefined;
+    const branch = props.branch ?? props.id;
+    if (!branch)
+        return undefined;
+    try {
+        return await branchIdResolve({
+            branch,
+            apiClient: props.apiClient,
+            projectId: props.projectId,
+        });
+    }
+    catch (err) {
+        log.debug("dev: could not resolve branch id: %s", err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+};
+const DEFAULT_PORT_BASE = 8787;
+const portFromProps = (port) => {
+    if (port !== undefined)
+        return { mode: "explicit", port };
+    if (process.env.PORT !== undefined && process.env.PORT !== "") {
+        return { mode: "explicit", port: Number(process.env.PORT) };
+    }
+    return { mode: "search", from: DEFAULT_PORT_BASE };
+};
+/**
+ * Translate a {@link PlannedFunction} into a {@link ServedUnit}. Port rules:
+ *   - explicit `dev.port`: bind exactly, fail if taken.
+ *   - no `dev.port`: search for a free port (base coordinated by the caller).
+ * Per-function neon.ts env layers over the shared branch env.
+ */
+const plannedToUnit = (fn, branchEnv, searchBase) => {
+    const port = fn.port !== undefined
+        ? { mode: "explicit", port: fn.port }
+        : { mode: "search", from: searchBase };
+    const childEnv = buildChildEnv({ ...branchEnv, ...fn.env }, port);
+    return {
+        slug: fn.slug,
+        source: fn.source,
+        bundleDir: join(process.cwd(), "node_modules", ".neon-dev", fn.slug),
+        childEnv,
+        label: fn.slug,
+        envSummary: { neon: Object.keys(branchEnv), fn: Object.keys(fn.env) },
+        // Signature of the function's *own* neon.ts config (NOT the dynamically-chosen search
+        // base) so reconcile can tell a real change from a no-op save. A search-mode function
+        // re-planned with a different base must hash identically, or it would be needlessly
+        // restarted — see reconcile().
+        configKey: JSON.stringify({
+            source: fn.source,
+            port: fn.port ?? null,
+            env: fn.env,
+        }),
+    };
+};
+/**
+ * Build a child's env. Neon vars layer over the inherited environment (so the branch's
+ * DATABASE_URL wins over a stale inherited value); a function that loads its own `.env`
+ * at runtime still overrides them. The port spec is encoded for the runtime via
+ * NEON_DEV_PORT (explicit) or NEON_DEV_PORT_BASE (search).
+ */
+const buildChildEnv = (neonEnv, port) => {
+    const env = { ...process.env, ...neonEnv };
+    delete env.NEON_DEV_PORT;
+    delete env.NEON_DEV_PORT_BASE;
+    if (port.mode === "explicit") {
+        env.NEON_DEV_PORT = String(port.port);
+    }
+    else if (port.mode === "search") {
+        env.NEON_DEV_PORT_BASE = String(port.from);
+    }
+    return env;
+};
+const READY_PATTERN = /neon-dev:ready (\d+)/;
+/**
+ * Supervise one or more {@link ServedUnit}s: bundle + start each in its own child, watch
+ * its inputs for hot reload, and tear everything down cleanly on shutdown. Units are
+ * independent — one crashing or failing to start does not stop the others (it is shown
+ * as errored and recovered on the next edit). A single SIGINT/SIGTERM shuts all of them
+ * down, tree-killing each child so no descendant it spawned is orphaned.
+ *
+ * In config mode, `reload` lets the supervisor watch `neon.ts` and reconcile the live set
+ * of units when it changes: a newly-declared function is hot-added (its own child, watcher,
+ * and port) and a removed one is torn down — all without disturbing the functions that
+ * stayed the same. A function whose config (env/port/source) changed is restarted
+ * in place; siblings are untouched.
+ */
+const runSupervisor = async (units, options = {}) => {
+    const { reload, envNote } = options;
+    const runtimePath = resolveRuntimePath();
+    let shuttingDown = false;
+    const running = units.map(makeRunningUnit);
+    const bundleAndStart = async (r) => {
+        let bundlePath;
+        try {
+            bundlePath = await writeBundle(r.unit.source, r.unit.bundleDir);
+        }
+        catch (err) {
+            r.status = "error";
+            logUnit(r.unit, chalk.red("bundle failed: ") +
+                (err instanceof Error ? err.message : String(err)));
+            return;
+        }
+        if (r.watcher)
+            await r.watcher.sync();
+        const next = spawnChild(r.unit, runtimePath, bundlePath);
+        r.child = next;
+        const ready = waitForReady(next);
+        pipeChildOutput(next, r.unit.label);
+        next.on("exit", (code, signal) => {
+            if (shuttingDown || r.child !== next)
+                return;
+            if (signal) {
+                log.debug("runtime for %s exited via %s", r.unit.slug ?? "(source)", signal);
+                return;
+            }
+            if (code && code !== 0 && r.everReady) {
+                r.status = "error";
+                logUnit(r.unit, chalk.red(`exited with code ${code} (waiting for a change)`));
+            }
+        });
+        const port = await ready;
+        if (port !== null) {
+            r.boundPort = port;
+            r.everReady = true;
+            r.status = "ready";
+        }
+        else {
+            r.status = "error";
+        }
+    };
+    const restart = (r) => {
+        if (shuttingDown)
+            return;
+        if (r.restartTimer)
+            clearTimeout(r.restartTimer);
+        r.restartTimer = setTimeout(() => {
+            void (async () => {
+                logUnit(r.unit, chalk.dim("change detected, restarting…"));
+                if (r.child)
+                    await killTree(r.child);
+                if (shuttingDown)
+                    return;
+                await bundleAndStart(r);
+                if (r.status === "ready") {
+                    logUnit(r.unit, chalk.green("ready") + ` ${urlFor(r.boundPort)}`);
+                }
+            })();
+        }, 150);
+    };
+    // Bring a unit fully online: create its source watcher (before the first bundle so
+    // bundleAndStart can sync the watch set on every run) then bundle + spawn it.
+    const startUnit = async (r) => {
+        r.watcher = await startWatcher(r.unit.source, () => {
+            restart(r);
+        });
+        await bundleAndStart(r);
+    };
+    // Tear a unit down completely: stop its restart timer + watcher, reap its child tree, and
+    // remove its bundle dir. Used both on shutdown and when neon.ts drops a function.
+    const stopUnit = async (r) => {
+        if (r.restartTimer)
+            clearTimeout(r.restartTimer);
+        await r.watcher?.close();
+        if (r.child)
+            await killTree(r.child);
+        rmSync(r.unit.bundleDir, { recursive: true, force: true });
+    };
+    // Start every unit. They are independent: keep going if one fails.
+    await Promise.all(running.map((r) => startUnit(r)));
+    if (running.every((r) => r.status === "error")) {
+        await Promise.all(running.map((r) => stopUnit(r)));
+        throw new Error("No function started. See the output above for details.");
+    }
+    printBanner(running, envNote);
+    // Config mode only: watch neon.ts and reconcile the live unit set when it changes.
+    // Reconciles are serialized: a burst of saves (editor write-then-format) must not run
+    // overlapping diffs against the mutating `running` array. A trailing run coalesces the
+    // burst and picks up the latest config.
+    let configWatcher = null;
+    if (reload) {
+        const ops = {
+            isShuttingDown: () => shuttingDown,
+            startUnit,
+            stopUnit,
+            restartUnit: restart,
+        };
+        let inFlight = null;
+        let pending = false;
+        const drive = () => {
+            if (inFlight) {
+                pending = true;
+                return;
+            }
+            inFlight = (async () => {
+                do {
+                    pending = false;
+                    await reconcileOnce(running, reload.replan, ops);
+                } while (pending && !shuttingDown);
+            })().finally(() => {
+                inFlight = null;
+            });
+        };
+        configWatcher = await startConfigWatcher(reload.configPath, drive);
+    }
+    await new Promise((resolveRun) => {
+        const shutdown = () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            void (async () => {
+                await configWatcher?.close();
+                await Promise.all(running.map((r) => stopUnit(r)));
+                log.info(chalk.dim("Stopped the dev server."));
+                resolveRun();
+            })();
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    });
+};
+const makeRunningUnit = (unit) => ({
+    unit,
+    child: null,
+    boundPort: null,
+    everReady: false,
+    restartTimer: null,
+    watcher: null,
+    status: "starting",
+});
+/**
+ * Pure slug-keyed diff of the live units against the freshly-resolved desired set:
+ *   - a slug present now but not before → **add** (new child + watcher + port),
+ *   - a slug gone from neon.ts → **remove** (torn down),
+ *   - a slug whose config (source/port/env) changed → **restart** in place,
+ *   - an unchanged slug → left out of the plan entirely (never touched).
+ * Functions that stayed the same never die, so an edit that only adds a function is
+ * non-disruptive. `desired === null` (neon.ts deleted) is treated as "no functions".
+ */
+export const diffUnits = (running, desired) => {
+    const desiredBySlug = new Map();
+    for (const u of desired ?? []) {
+        if (u.slug !== null)
+            desiredBySlug.set(u.slug, u);
+    }
+    const runningBySlug = new Map();
+    for (const r of running) {
+        if (r.unit.slug !== null)
+            runningBySlug.set(r.unit.slug, r);
+    }
+    const plan = { remove: [], restart: [], add: [] };
+    for (const [slug, r] of runningBySlug) {
+        if (!desiredBySlug.has(slug))
+            plan.remove.push(r);
+    }
+    for (const [slug, want] of desiredBySlug) {
+        const r = runningBySlug.get(slug);
+        if (r) {
+            if (r.unit.configKey !== want.configKey) {
+                r.unit = want;
+                plan.restart.push(r);
+            }
+        }
+        else {
+            plan.add.push(want);
+        }
+    }
+    return plan;
+};
+/**
+ * Run one reconcile: re-resolve neon.ts (ignoring the change with a clear message if it no
+ * longer loads), {@link diffUnits} against the live set, then apply the plan — tearing down
+ * removed functions, restarting changed ones in place, and hot-adding new ones. Mutates
+ * `running` in place so the surrounding supervisor sees the converged set.
+ */
+const reconcileOnce = async (running, replan, ops) => {
+    if (ops.isShuttingDown())
+        return;
+    let desired;
+    try {
+        desired = await replan(nextSearchBase(running));
+    }
+    catch (err) {
+        log.info(chalk.red("neon.ts change ignored: ") +
+            (err instanceof Error ? err.message : String(err)) +
+            chalk.dim(" (fix it and save again)"));
+        return;
+    }
+    if (ops.isShuttingDown())
+        return;
+    const plan = diffUnits(running, desired);
+    for (const r of plan.remove) {
+        logUnit(r.unit, chalk.dim("removed from neon.ts, stopping…"));
+        await ops.stopUnit(r);
+        const idx = running.indexOf(r);
+        if (idx !== -1)
+            running.splice(idx, 1);
+    }
+    for (const r of plan.restart)
+        ops.restartUnit(r);
+    if (plan.add.length > 0) {
+        const added = plan.add.map((unit) => {
+            const r = makeRunningUnit(unit);
+            running.push(r);
+            logUnit(unit, chalk.dim("added in neon.ts, starting…"));
+            return r;
+        });
+        await Promise.all(added.map((r) => ops.startUnit(r)));
+        for (const r of added) {
+            if (r.status === "ready") {
+                const env = formatEnvSummary(r.unit.envSummary);
+                logUnit(r.unit, chalk.green("ready") +
+                    ` ${urlFor(r.boundPort)}` +
+                    (env ? chalk.dim(`  ${env}`) : ""));
+            }
+        }
+    }
+};
+/**
+ * Choose a port search base above every port the live units already bound, so a hot-added
+ * search-mode function starts probing where there's room. The runtime still walks upward
+ * from here, so it never fails even if this guess is taken — it just keeps things tidy.
+ */
+const nextSearchBase = (running) => {
+    let max = DEFAULT_PORT_BASE - 1;
+    for (const r of running) {
+        if (r.boundPort !== null && r.boundPort > max)
+            max = r.boundPort;
+    }
+    return max + 1;
+};
+/**
+ * Spawn the child for a unit: the bundled output run directly under `node`.
+ *
+ * Spawned detached (own process group) so killTree can reap the whole group.
+ */
+const spawnChild = (unit, runtimePath, bundlePath) => {
+    return spawn(process.execPath, [runtimePath, bundlePath], {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: unit.childEnv,
+        detached: true,
+    });
+};
+const writeBundle = async (source, bundleDir) => {
+    const files = await bundleEntry(source);
+    mkdirSync(bundleDir, { recursive: true });
+    // bundleEntry emits a single `index.mjs` (no source map). The `.mjs` extension makes Node
+    // load it as ESM directly, so no `package.json` `"type": "module"` marker is needed.
+    for (const [name, contents] of Object.entries(files)) {
+        writeFileSync(join(bundleDir, name), contents);
+    }
+    return join(bundleDir, "index.mjs");
+};
+const urlFor = (port) => port === null ? chalk.red("not running") : `http://localhost:${port}`;
+const waitForReady = (child) => new Promise((resolveReady) => {
+    let settled = false;
+    let buffer = "";
+    const onData = (chunk) => {
+        buffer += chunk.toString();
+        const match = READY_PATTERN.exec(buffer);
+        if (match && !settled) {
+            settled = true;
+            child.stdout?.off("data", onData);
+            resolveReady(Number(match[1]));
+        }
+    };
+    child.stdout?.on("data", onData);
+    child.once("exit", () => {
+        if (!settled) {
+            settled = true;
+            resolveReady(null);
+        }
+    });
+});
+/**
+ * Forward the child's stdout/stderr to the parent, swallowing the machine-readable
+ * `neon-dev:ready` line. When `label` is set (multi-function mode), every line is
+ * prefixed with `[slug]` so concurrent servers' output stays readable.
+ */
+const pipeChildOutput = (child, label) => {
+    const prefix = label ? chalk.dim(`[${label}] `) : "";
+    const forward = (stream) => {
+        let buffer = "";
+        child[stream]?.on("data", (chunk) => {
+            buffer += chunk.toString();
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                if (READY_PATTERN.test(line))
+                    continue;
+                process[stream].write(`${prefix}${line}\n`);
+            }
+        });
+    };
+    forward("stdout");
+    forward("stderr");
+};
+const printBanner = (running, envNote) => {
+    log.info("");
+    log.info(chalk.green.bold("  Neon Functions dev server"));
+    log.info("");
+    for (const r of running) {
+        const name = r.unit.label ?? "function";
+        const url = urlFor(r.boundPort);
+        log.info(`  ${chalk.dim(name.padEnd(20))} ${url}`);
+        const env = formatEnvSummary(r.unit.envSummary);
+        if (env)
+            log.info(`  ${" ".repeat(20)} ${chalk.dim(env)}`);
+    }
+    if (envNote) {
+        log.info("");
+        log.info(`  ${chalk.yellow("!")} ${chalk.dim(`Neon env: ${envNote}`)}`);
+    }
+    log.info("");
+};
+/**
+ * Render a unit's injected env into one transparent line for the banner, e.g.
+ * `env: DATABASE_URL, DATABASE_URL_UNPOOLED · neon.ts: RESEND_API_KEY`. Var **names** only
+ * (never values — they're secrets). Returns `''` when nothing is injected, so the caller can
+ * skip the line. Exported for unit testing.
+ */
+export const formatEnvSummary = (summary) => {
+    if (!summary)
+        return "";
+    const parts = [];
+    if (summary.neon.length > 0) {
+        parts.push(`env: ${[...summary.neon].sort().join(", ")}`);
+    }
+    if (summary.fn.length > 0) {
+        parts.push(`neon.ts: ${[...summary.fn].sort().join(", ")}`);
+    }
+    return parts.join(" · ");
+};
+const logUnit = (unit, message) => {
+    const prefix = unit.label ? chalk.dim(`[${unit.label}] `) : "";
+    log.info(`${prefix}${message}`);
+};
+const startWatcher = async (source, restart) => {
+    const { default: chokidar } = await import("chokidar");
+    const initialInputs = await resolveWatchInputs(source);
+    if (initialInputs === null) {
+        return startDirectoryWatcher(chokidar, source, restart);
+    }
+    return startInputWatcher(chokidar, source, initialInputs, restart);
+};
+/**
+ * Watch the neon.ts file itself for changes, firing `onChange` on every save. Used by the
+ * supervisor (config mode only) to hot-add/remove/restart functions when the declared set
+ * changes. We watch the single config file rather than its import graph: editing neon.ts to
+ * add or remove a function is the case that matters, and a plain file watch is robust where
+ * the esbuild-based input resolution (built for function bundles) is not a fit for a
+ * jiti-loaded config.
+ */
+const startConfigWatcher = async (configPath, onChange) => {
+    const { default: chokidar } = await import("chokidar");
+    const watcher = chokidar.watch(configPath, { ignoreInitial: true });
+    await once(watcher, "ready");
+    watcher.on("all", () => {
+        onChange();
+    });
+    return { sync: () => Promise.resolve(), close: () => watcher.close() };
+};
+const startInputWatcher = async (chokidar, source, initialInputs, restart) => {
+    const watched = new Set([source, ...initialInputs]);
+    const watcher = chokidar.watch([...watched], { ignoreInitial: true });
+    await once(watcher, "ready");
+    watcher.on("all", () => {
+        restart();
+    });
+    const sync = async () => {
+        const next = await resolveWatchInputs(source);
+        if (next === null)
+            return;
+        const desired = new Set([source, ...next]);
+        for (const file of desired) {
+            if (!watched.has(file)) {
+                watcher.add(file);
+                watched.add(file);
+            }
+        }
+        for (const file of watched) {
+            if (!desired.has(file)) {
+                watcher.unwatch(file);
+                watched.delete(file);
+            }
+        }
+    };
+    return { sync, close: () => watcher.close() };
+};
+const startDirectoryWatcher = async (chokidar, source, restart) => {
+    const watchedDir = dirname(source);
+    const isIgnored = (p) => {
+        const segments = p.split(/[/\\]/);
+        return (segments.includes("node_modules") ||
+            segments.includes(".git") ||
+            segments.includes("dist"));
+    };
+    const watcher = chokidar.watch(watchedDir, {
+        ignoreInitial: true,
+        ignored: (path) => isIgnored(path),
+    });
+    await once(watcher, "ready");
+    watcher.on("all", () => {
+        restart();
+    });
+    return { sync: () => Promise.resolve(), close: () => watcher.close() };
+};
+/**
+ * Terminate a child and every descendant it spawned. The child is started `detached`, so
+ * on POSIX it leads its own process group and a negative-PID signal reaps the group
+ * (covering the runtime and anything it spawned). On Windows there are no POSIX groups, so we
+ * shell out to `taskkill /T` to kill the tree. Escalates SIGTERM -> SIGKILL after 2s.
+ */
+const killTree = (child) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return Promise.resolve();
+    }
+    const pid = child.pid;
+    return new Promise((resolveKill) => {
+        const timeout = setTimeout(() => {
+            forceKill(child, pid);
+        }, 2000);
+        child.once("exit", () => {
+            clearTimeout(timeout);
+            resolveKill();
+        });
+        if (pid !== undefined && process.platform !== "win32") {
+            try {
+                process.kill(-pid, "SIGTERM");
+                return;
+            }
+            catch {
+                // Fall through to a direct kill if the group is already gone.
+            }
+        }
+        child.kill("SIGTERM");
+    });
+};
+const forceKill = (child, pid) => {
+    if (pid === undefined) {
+        child.kill("SIGKILL");
+        return;
+    }
+    if (process.platform === "win32") {
+        spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"]);
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        child.kill("SIGKILL");
+    }
+};
+const resolveRuntimePath = () => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidate = join(here, "..", "dev", "runtime.js");
+    if (!existsSync(candidate)) {
+        throw new Error(`Could not locate the dev runtime at ${candidate}`);
+    }
+    return candidate;
+};