neon 8.11.1 → 8.11.2

package/dist/_chunks/dev-CSvxAecE.js

@@ -0,0 +1,945 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { log } from "../log.js";
+import { isClaimableEnvTarget } from "../claimable/state.js";
+import { getCliName } from "../utils/cli_name.js";
+import { defaultDevEnvFiles, readEnvFile, resolveEnvFilePath } from "../env_file.js";
+import { l as functionBaseUrlKey } from "./env-BpP3Dqpe.js";
+import { branchIdResolve } from "../utils/enrichers.js";
+import { bundleEntry } from "../utils/esbuild.js";
+import { a as resolveDevEnv } from "./env-BNm69Qh8.js";
+import { f as envFlag } from "./config-BH_qRHiG.js";
+import { findConfigFunctionBySource, resolveFunctionsFromConfig } from "../dev/functions.js";
+import { resolveWatchInputs } from "../dev/inputs.js";
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import { spawn, spawnSync } from "node:child_process";
+import { bundleAsIs, describeNativeFinding, findUndeclaredNativePackages, resolveEsbuildEntry } from "@neon/config-runtime";
+import { once } from "node:events";
+import { createServer } from "node:net";
+//#region src/commands/dev.ts
+var dev_exports = /* @__PURE__ */ __exportAll({
+	builder: () => builder,
+	captureShellEnv: () => captureShellEnv,
+	command: () => "dev",
+	describe: () => describe,
+	devBundleDir: () => devBundleDir,
+	devEnvContext: () => devEnvContext,
+	diffUnits: () => diffUnits,
+	formatEnvFiles: () => formatEnvFiles,
+	formatEnvSummary: () => formatEnvSummary,
+	handler: () => handler,
+	loadDevEnvFiles: () => loadDevEnvFiles,
+	localFunctionUrlEnv: () => localFunctionUrlEnv,
+	planFunctionsToUnits: () => planFunctionsToUnits,
+	reportDevCredential: () => reportDevCredential,
+	sourceFunctionUrlOverlay: () => sourceFunctionUrlOverlay
+});
+const command = "dev";
+const describe = "Run Neon Functions locally with a dev server";
+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"
+	},
+	...envFlag
+}).epilogue([
+	"",
+	"Functions run with the linked branch's Neon env injected, the same set the",
+	"deployed runtime gives them: DATABASE_URL, plus Neon Auth, the Data API,",
+	"object storage and the AI Gateway where the branch has them. A neon.ts in",
+	"this directory decides instead, exactly as it does for `env pull`.",
+	"",
+	"NEON_FUNCTION_<SLUG>_BASE_URL from `env pull` / `neon-env run` is the production",
+	"invocation URL. `dev` rewrites it to `http://localhost:<port>` for each function",
+	"this process is serving (every neon.ts function, or the matching slug when",
+	"`--source` names one).",
+	"",
+	"Before neon.ts is evaluated, `dev` loads the project's .env, then .env.local,",
+	"which overrides it, into the environment, so Function env values that read",
+	"process.env resolve. A variable already set in the shell wins. `--env <file>`",
+	"loads only that file instead. Functions inherit every loaded variable.",
+	"",
+	"`dev` reuses the branch credential behind the AI Gateway and object storage from",
+	"the file `env pull` writes, and never writes to it. With no such file it issues a",
+	"credential on every start, so run `env pull` once if you restart often."
+].join("\n")).strict();
+/**
+* The resolver context for a `neon dev` run.
+*
+* Two things here are what make local dev match the deployed runtime, which injects a
+* branch's whole env into a function:
+*
+* - **The AI Gateway is asked for**, like `env pull` does, because nothing can detect it.
+*   Without this, a function that works deployed fails locally with no `NEON_AI_GATEWAY_*`,
+*   which is exactly the difference `dev` exists to eliminate.
+* - **The local dotenv file is layered in**, so the branch credential behind the gateway and
+*   object storage is *reused* rather than re-minted. `dev` writes no file of its own, so
+*   without a source of persisted secrets every start would mint a credential and leave the
+*   last one live — one orphan per restart. `neon-env run` already reads the file for this
+*   reason; `dev` was the one that didn't.
+*/
+const devEnvContext = (props, branchId, cwd, baseEnv = process.env) => {
+	const location = {
+		cwd,
+		...props.contextFile ? { contextFile: props.contextFile } : {}
+	};
+	const envFile = resolveEnvFilePath(location);
+	return {
+		...location,
+		implyAiGateway: true,
+		env: {
+			...baseEnv,
+			...existsSync(envFile) ? readEnvFile(envFile) : {}
+		},
+		...props.projectId ? { projectId: props.projectId } : {},
+		...branchId ? { branchId } : {},
+		...props.apiKey ? { apiKey: props.apiKey } : {},
+		...props.apiHost ? { apiHost: props.apiHost } : {},
+		...isClaimableEnvTarget({
+			apiHost: props.apiHost,
+			contextFile: props.contextFile ?? "",
+			configDir: props.configDir ?? ""
+		}) ? { claimable: true } : {}
+	};
+};
+/**
+* Say when this run obtained credential secrets it did not already hold.
+*
+* `dev` writes no file. With platform defaults, each start re-reveals the same secrets until
+* `env pull` persists them. In a region with no defaults, each start mints another credential
+* and cannot revoke the last one. The note names the one action that stops either loop.
+*/
+const reportDevCredential = (credential) => {
+	if (!credential?.issued) return;
+	if (credential.revoked.length > 0) {
+		log.info("Wrote credential secrets — %s changed. Revoked the leftover it replaced (%s).", credential.keys.join(", "), credential.revoked.join(", "));
+		return;
+	}
+	log.warning(`Resolved credential secrets for this run (%s) without writing them to a file. Run \`${getCliName()} env pull\` once so restarts reuse them instead of revealing or minting again.`, credential.keys.join(", "));
+};
+const handler = async (props) => {
+	const shellEnv = captureShellEnv();
+	const envFiles = formatEnvFiles(loadDevEnvFiles(props, process.cwd()), process.cwd());
+	if (props.source !== void 0) {
+		await runSingleSource(props, shellEnv, envFiles);
+		return;
+	}
+	if (props.port !== void 0) 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, shellEnv, envFiles);
+};
+/**
+* Copy of the shell env before any dotenv file loads. PORT is read through `process.env`,
+* which is case-insensitive on Windows, so a shell `Port` still sets the port. Exported for
+* unit testing.
+*/
+const captureShellEnv = () => ({
+	...process.env,
+	PORT: process.env.PORT
+});
+/**
+* Load dotenv files into process.env before neon.ts is evaluated: `--env <file>` alone
+* (relative to cwd), else the project's {@link defaultDevEnvFiles}. A later file overrides
+* an earlier one; a key set before loading (the shell) is never overridden.
+*/
+const loadDevEnvFiles = (props, cwd) => {
+	const files = props.env ? [resolve(cwd, props.env)] : defaultDevEnvFiles({
+		cwd,
+		...props.contextFile ? { contextFile: props.contextFile } : {}
+	});
+	const name = (key) => process.platform === "win32" ? key.toUpperCase() : key;
+	const preset = new Set(Object.keys(process.env).filter((key) => process.env[key] !== void 0).map(name));
+	return files.map((path) => {
+		const applied = [];
+		for (const [key, value] of Object.entries(readEnvFile(path))) {
+			if (preset.has(name(key))) continue;
+			process.env[key] = value;
+			applied.push(key);
+		}
+		return {
+			path,
+			applied
+		};
+	});
+};
+/**
+* The banner's account of the dotenv files, in load order, e.g.
+* `.env.local (4 vars) → .env (2 vars)`. Counts are the keys each file set. Exported for
+* unit testing.
+*/
+const formatEnvFiles = (files, cwd) => {
+	if (files.length === 0) return "none (no .env.local or .env)";
+	return files.map(({ path, applied }) => {
+		const count = `${applied.length} var${applied.length === 1 ? "" : "s"}`;
+		return `${relative(cwd, path) || path} (${count})`;
+	}).join(" → ");
+};
+/** Single-function mode: serve exactly the `--source` path (legacy behavior). */
+const runSingleSource = async (props, shellEnv, envFiles) => {
+	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, credential } = await resolveDevEnv(devEnvContext(props, branchId, process.cwd(), shellEnv));
+	reportDevCredential(credential);
+	const match = await findConfigFunctionBySource(process.cwd(), source, props.contextFile);
+	const { overlay, port } = await sourceFunctionUrlOverlay(match, props.port, shellEnv);
+	const unit = {
+		slug: null,
+		source,
+		bundleDir: devBundleDir(process.cwd()),
+		childEnv: buildChildEnv({
+			...neonEnv,
+			...overlay
+		}, port),
+		label: null,
+		envSummary: {
+			neon: Object.keys(neonEnv),
+			fn: []
+		}
+	};
+	await runSupervisor([unit], {
+		envFiles,
+		...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, shellEnv, envFiles) => {
+	const branchId = await resolveBranchId(props);
+	const resolved = await resolveFunctionsFromConfig(process.cwd(), void 0, props.contextFile);
+	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 `functions`.");
+	const { configPath, functions } = resolved;
+	if (functions.length === 0) throw new Error("neon.ts has no functions to serve. Add at least one under `functions`, or pass --source <path>.");
+	const { vars: neonEnv, skipped, credential } = await resolveDevEnv(devEnvContext(props, branchId, process.cwd(), shellEnv));
+	reportDevCredential(credential);
+	const units = await planFunctionsToUnits(functions, neonEnv, DEFAULT_PORT_BASE);
+	const replan = async (searchBase, keepPorts) => {
+		const re = await resolveFunctionsFromConfig(process.cwd(), void 0, props.contextFile);
+		if (re === null) return null;
+		return planFunctionsToUnits(re.functions, neonEnv, searchBase, keepPorts);
+	};
+	await runSupervisor(units, {
+		reload: {
+			configPath,
+			replan
+		},
+		envFiles,
+		...skipped ? { envNote: skipped.reason } : {}
+	});
+};
+/** Ports are chosen before spawn so every sibling's localhost URL can be overlaid. */
+const planFunctionsToUnits = async (functions, neonEnv, searchBase, keepPorts = /* @__PURE__ */ new Map()) => {
+	const reserved = /* @__PURE__ */ new Set();
+	const portBySlug = /* @__PURE__ */ new Map();
+	for (const fn of functions) {
+		if (fn.port === void 0) continue;
+		portBySlug.set(fn.slug, fn.port);
+		reserved.add(fn.port);
+	}
+	for (const fn of functions) {
+		if (portBySlug.has(fn.slug)) continue;
+		const kept = keepPorts.get(fn.slug);
+		if (kept !== void 0 && !reserved.has(kept)) {
+			portBySlug.set(fn.slug, kept);
+			reserved.add(kept);
+		}
+	}
+	let searchOffset = 0;
+	for (const fn of functions) {
+		if (portBySlug.has(fn.slug)) continue;
+		const port = await pickFreePort(searchBase + searchOffset, reserved);
+		portBySlug.set(fn.slug, port);
+		reserved.add(port);
+		searchOffset = port - searchBase + 1;
+	}
+	const assigned = functions.map((fn) => {
+		const port = portBySlug.get(fn.slug);
+		if (port === void 0) throw new Error(`planFunctionsToUnits: no port for ${fn.slug}`);
+		return {
+			fn,
+			port
+		};
+	});
+	const overlay = localFunctionUrlEnv(assigned.map(({ fn, port }) => ({
+		slug: fn.slug,
+		port
+	})));
+	const branchEnv = {
+		...neonEnv,
+		...overlay
+	};
+	return assigned.map(({ fn, port }) => plannedToUnit(fn, branchEnv, {
+		mode: "explicit",
+		port
+	}, overlay));
+};
+/**
+* Local invocation URLs for functions `neon dev` is serving, so siblings call each
+* other on localhost instead of the production compute host.
+*/
+const localFunctionUrlEnv = (functions) => {
+	const out = {};
+	for (const fn of functions) out[functionBaseUrlKey(fn.slug)] = `http://localhost:${fn.port}`;
+	return out;
+};
+/**
+* `--source` serves one file. If that file is a neon.ts function, rewrite only that
+* slug to localhost — this process is not listening for the others.
+*/
+const sourceFunctionUrlOverlay = async (match, cliPort, shellEnv = process.env) => {
+	const portSpec = portFromProps(cliPort, shellEnv);
+	if (match === void 0) return {
+		overlay: {},
+		port: portSpec
+	};
+	const port = portSpec.mode === "explicit" ? portSpec.port : match.port ?? await pickFreePort(portSpec.from);
+	return {
+		overlay: localFunctionUrlEnv([{
+			slug: match.slug,
+			port
+		}]),
+		port: {
+			mode: "explicit",
+			port
+		}
+	};
+};
+const pickFreePort = (from, reserved = /* @__PURE__ */ new Set()) => new Promise((resolvePort, reject) => {
+	const tryPort = (port) => {
+		if (port > 65535) {
+			reject(/* @__PURE__ */ new Error(`No free port at or above ${from}`));
+			return;
+		}
+		if (reserved.has(port)) {
+			tryPort(port + 1);
+			return;
+		}
+		const server = createServer();
+		server.once("error", (err) => {
+			if (err.code === "EADDRINUSE") {
+				tryPort(port + 1);
+				return;
+			}
+			reject(err);
+		});
+		server.listen(port, "127.0.0.1", () => {
+			const addr = server.address();
+			const bound = typeof addr === "object" && addr !== null ? addr.port : port;
+			server.close((closeErr) => {
+				if (closeErr) reject(closeErr);
+				else resolvePort(bound);
+			});
+		});
+	};
+	tryPort(from);
+});
+/**
+* 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 void 0;
+	const branch = props.branch ?? props.id;
+	if (!branch) return void 0;
+	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;
+	}
+};
+const DEFAULT_PORT_BASE = 8787;
+const portFromProps = (port, shellEnv) => {
+	if (port !== void 0) return {
+		mode: "explicit",
+		port
+	};
+	if (shellEnv.PORT !== void 0 && shellEnv.PORT !== "") return {
+		mode: "explicit",
+		port: Number(shellEnv.PORT)
+	};
+	return {
+		mode: "search",
+		from: DEFAULT_PORT_BASE
+	};
+};
+/**
+* Where a locally-served function's bundle is written.
+*
+* The location inside the project's own `node_modules` is load-bearing, not a tidiness
+* choice. A function's `externalPackages` are left unbundled, and Node resolves an unbundled
+* import by walking up from the importing file — so from here it reaches the project's real
+* `node_modules` and finds them, at the host architecture that can actually run locally.
+* Moving this directory anywhere outside `node_modules` breaks `neon dev` for those
+* functions with a `Cannot find module`, so the path is pinned by a test.
+*/
+const devBundleDir = (cwd, slug) => slug === void 0 ? join(cwd, "node_modules", ".neon-dev") : join(cwd, "node_modules", ".neon-dev", slug);
+/**
+* Translate a {@link PlannedFunction} into a {@link ServedUnit}. The bind port is
+* already chosen by the caller so sibling localhost URLs can be overlaid first.
+* Per-function neon.ts env layers over the shared branch env.
+*/
+const plannedToUnit = (fn, branchEnv, port, overlay = {}) => {
+	const childEnv = buildChildEnv({
+		...branchEnv,
+		...fn.env
+	}, port);
+	return {
+		slug: fn.slug,
+		source: fn.source,
+		bundleDir: devBundleDir(process.cwd(), fn.slug),
+		childEnv,
+		label: fn.slug,
+		envSummary: {
+			neon: Object.keys(branchEnv),
+			fn: Object.keys(fn.env)
+		},
+		...fn.externalPackages ? { externalPackages: fn.externalPackages } : {},
+		...fn.bundler !== void 0 ? { bundler: fn.bundler } : {},
+		configKey: JSON.stringify({
+			source: fn.source,
+			port: fn.port ?? null,
+			env: fn.env,
+			overlay,
+			externalPackages: fn.externalPackages ?? null,
+			bundler: typeof fn.bundler === "function" ? "custom" : fn.bundler ?? null
+		})
+	};
+};
+/**
+* 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, envFiles } = 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, r.unit.externalPackages, r.unit.slug ?? void 0, r.unit.bundler);
+		} 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(() => {
+			(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);
+	};
+	const startUnit = async (r) => {
+		r.watcher = await startWatcher(r.unit, () => {
+			restart(r);
+		});
+		await bundleAndStart(r);
+	};
+	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
+		});
+	};
+	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, envFiles);
+	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;
+			(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".
+*/
+const diffUnits = (running, desired) => {
+	const desiredBySlug = /* @__PURE__ */ new Map();
+	for (const u of desired ?? []) if (u.slug !== null) desiredBySlug.set(u.slug, u);
+	const runningBySlug = /* @__PURE__ */ 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), keepPortsFromRunning(running));
+	} catch (err) {
+		log.warning("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}`) : ""));
+		}
+	}
+};
+const keepPortsFromRunning = (running) => {
+	const keep = /* @__PURE__ */ new Map();
+	for (const r of running) {
+		if (r.unit.slug === null) continue;
+		const bound = r.boundPort;
+		if (bound !== null) {
+			keep.set(r.unit.slug, bound);
+			continue;
+		}
+		const pending = Number(r.unit.childEnv.NEON_DEV_PORT);
+		if (Number.isFinite(pending) && pending > 0) keep.set(r.unit.slug, pending);
+	}
+	return keep;
+};
+/**
+* Start pickFreePort above every port live units already bound, so a hot-added
+* function is not probed on a port a sibling is serving.
+*/
+const nextSearchBase = (running) => {
+	let max = 8786;
+	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
+	});
+};
+/**
+* Findings already reported for a served unit, so an advisory that cannot change between
+* saves is not reprinted on every one. A dev session on a project with a standing false
+* positive would otherwise repeat the whole block for its lifetime.
+*/
+const reportedFindings = /* @__PURE__ */ new Map();
+const writeBundle = async (source, bundleDir, externalPackages, label, bundler) => {
+	if (bundler !== void 0 && bundler !== "esbuild") {
+		const files = await bundleForDev(source, label, bundler);
+		return writeBundleFiles(bundleDir, files);
+	}
+	const entry = await resolveEsbuildEntry(source);
+	const { files, metafile, warnings } = await bundleEntry(entry, { ...externalPackages ? { externalPackages } : {} });
+	for (const warning of warnings) log.warning(warning);
+	const findings = findUndeclaredNativePackages({
+		metafile,
+		declared: externalPackages ?? [],
+		projectDir: dirname(entry)
+	});
+	const signature = findings.map((f) => f.name).join(",");
+	if (reportedFindings.get(source) !== signature) {
+		reportedFindings.set(source, signature);
+		for (const finding of findings) log.warning(describeNativeFinding(label ?? basename(source), finding));
+	}
+	return writeBundleFiles(bundleDir, files);
+};
+const bundleForDev = async (source, label, bundler) => {
+	const fn = {
+		slug: label ?? basename(source),
+		name: label ?? basename(source),
+		source,
+		env: {},
+		runtime: "nodejs24",
+		bundler
+	};
+	return bundler === "none" ? bundleAsIs(fn) : bundler(fn);
+};
+const writeBundleFiles = (bundleDir, files) => {
+	rmSync(bundleDir, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(bundleDir, { recursive: true });
+	for (const [name, contents] of Object.entries(files)) {
+		const dest = join(bundleDir, name);
+		mkdirSync(dirname(dest), { recursive: true });
+		writeFileSync(dest, contents);
+	}
+	const entry = ["index.mjs", "index.js"].find((name) => name in files);
+	return join(bundleDir, entry ?? "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, envFiles) => {
+	log.info("");
+	log.info(chalk.green.bold("  Neon Functions dev server"));
+	log.info("");
+	if (envFiles) {
+		log.info(`  ${chalk.dim("env files".padEnd(20))} ${chalk.dim(envFiles)}`);
+		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.
+*/
+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 (unit, restart) => {
+	const { default: chokidar } = await import("chokidar");
+	if (unit.bundler !== void 0 && unit.bundler !== "esbuild") {
+		const dir = statSync(unit.source, { throwIfNoEntry: false })?.isDirectory() === true ? unit.source : dirname(unit.source);
+		return startDirectoryWatcher(chokidar, dir, restart, { ignoreDist: false });
+	}
+	let entry = unit.source;
+	try {
+		entry = await resolveEsbuildEntry(unit.source);
+	} catch {}
+	const initialInputs = await resolveWatchInputs(entry);
+	if (initialInputs === null) return startDirectoryWatcher(chokidar, entry, restart, { ignoreDist: true });
+	return startInputWatcher(chokidar, entry, 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 = /* @__PURE__ */ 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 = /* @__PURE__ */ 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, options) => {
+	const watchedDir = statSync(source, { throwIfNoEntry: false })?.isDirectory() ? source : dirname(source);
+	const isIgnored = (p) => {
+		const rel = relative(watchedDir, p);
+		if (rel === "" || rel === ".") return false;
+		if (rel.startsWith("..")) return false;
+		const segments = rel.split(/[/\\]/);
+		if (segments.includes("node_modules") || segments.includes(".git")) return true;
+		return options.ignoreDist && 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);
+		}, 2e3);
+		child.once("exit", () => {
+			clearTimeout(timeout);
+			resolveKill();
+		});
+		if (pid !== void 0 && process.platform !== "win32") try {
+			process.kill(-pid, "SIGTERM");
+			return;
+		} catch {}
+		child.kill("SIGTERM");
+	});
+};
+const forceKill = (child, pid) => {
+	if (pid === void 0) {
+		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;
+};
+//#endregion
+export { devBundleDir as a, diffUnits as c, handler as d, loadDevEnvFiles as f, sourceFunctionUrlOverlay as g, reportDevCredential as h, describe as i, formatEnvFiles as l, planFunctionsToUnits as m, captureShellEnv as n, devEnvContext as o, localFunctionUrlEnv as p, command as r, dev_exports as s, builder as t, formatEnvSummary as u };