@farm.js/cli 0.1.0-beta.6 → 0.1.0-beta.60

package/dist/index.mjs

@@ -1,52 +1,173 @@
-import { n as listFarmIntegrationProviders, t as addFarmIntegration } from "./add-integration-CdVfiPjG.mjs";
+import { n as listFarmIntegrationProviders, t as addFarmIntegration } from "./add-integration-7hf9WI7e.mjs";
 import { buildFarm } from "./build.mjs";
+import { a as resolveFarmTelemetryCommand, c as trackFarmCommand, i as resolveFarmCreateAppTelemetryCommand, l as trackFarmCreateAppCommand, n as getFarmTelemetryConfigFile, o as setFarmTelemetryEnabled, r as getFarmTelemetryStatus, s as showFarmTelemetryNotice, t as flushFarmTelemetry, u as trackFarmProjectCreated } from "./telemetry-DjbMk2du.mjs";
 import { createRequire } from "node:module";
 import { createServer, startDevServer } from "@farm.js/core/server";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { execFileSync, execSync } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import { existsSync as existsSync$1, readFileSync as readFileSync$1 } from "fs";
 import path$1 from "path";
-import { APITypeGenerator, generateEnvTypes, generateFarmI18nTypes, generateRouteTypes, getFarmDocsRouteTypeEntries, getFarmSourceRoots, getIntegrationSchemas, getPresetForDeployTarget, loadConfig, logger, normalizeDeployTarget, resolveConfig, resolveDeployConfig, resolveDeployOutputPath } from "@farm.js/core";
-import { spawn, spawnSync } from "node:child_process";
+import { farmRouteRuleMatches, generateFarmTypeArtifacts, getDeployTargetForPreset, getFarmDocsRouteTypeEntries, getFarmPresetRuntime, getFarmSourceRoots, getIntegrationSchemas, getPresetForDeployTarget, loadConfig, logger, mergeFarmRouteRuntimeConfigs, normalizeDeployTarget, resolveConfig, resolveDeployConfig, resolveDeployOutputPath, resolveFarmRouteRuleRuntimeConfig, resolveFarmRouteRuntimeConfig, resolveRouteRenderingConfig, scanProgrammaticPagePaths } from "@farm.js/core";
+import { constants } from "os";
+import { spawn as spawn$1, spawnSync } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import pc from "picocolors";
 import { Cron } from "croner";
+import { pathToFileURL } from "node:url";
 //#region \0rolldown/runtime.js
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 //#endregion
 //#region src/deploy.ts
+var FarmDeployError = class extends Error {
+	constructor(code, platform, message, options) {
+		super(message);
+		this.name = "FarmDeployError";
+		this.code = code;
+		this.platform = platform;
+		this.cause = options?.cause;
+	}
+};
 /**
 * Deploy Farm.js application
 */
 async function deployFarm(options = {}) {
-	const root = options.root || process.cwd();
+	const { plan, deployConfig } = await resolveFarmDeployContext(options);
+	if (options.plan) {
+		logger.info(formatFarmDeployPlan(plan));
+		return plan;
+	}
+	logger.info(`🚀 Building with ${plan.preset} preset...`);
+	await buildFarm({
+		root: plan.root,
+		preset: plan.preset,
+		target: plan.target
+	});
+	if (!existsSync$1(plan.outputDir)) throw new FarmDeployError("INVALID_BUILD_OUTPUT", plan.target, `Build output not found at ${plan.outputDir}. Please run 'farm build' first.`);
+	await deployPlatform(plan.target, plan.root, plan.outputDir, deployConfig, options.prod);
+	return plan;
+}
+async function createFarmDeployPlan(options = {}) {
+	return (await resolveFarmDeployContext(options)).plan;
+}
+function formatFarmDeployPlan(plan) {
+	return [
+		"FARM / DEPLOY PLAN",
+		"",
+		`Target:     ${plan.target}`,
+		`Preset:     ${plan.preset}`,
+		`Runtime:    ${plan.runtime}`,
+		`Output:     ${plan.outputDir}`,
+		`Production: ${plan.production ? "yes" : "no"}`,
+		"",
+		`1. ${plan.build.command}`,
+		`   cwd: ${plan.build.cwd}`,
+		`2. ${plan.deploy.command}`,
+		`   cwd: ${plan.deploy.cwd}`,
+		...plan.cloudflareAgent ? ["", `Cloudflare Agent config: ${plan.cloudflareAgent.configPath}${plan.cloudflareAgent.generated ? " (generated during build)" : ""}`] : []
+	].join("\n");
+}
+async function resolveFarmDeployContext(options) {
+	const root = path$1.resolve(options.root || process.cwd());
 	const mode = "production";
 	const userConfig = await loadConfig(root, void 0, mode);
-	const config = userConfig ? await resolveConfig(userConfig, mode) : void 0;
+	const config = await resolveConfig({
+		root,
+		...userConfig
+	}, mode);
 	const cliTarget = options.vercel ? "vercel" : options.cloudflare ? "cloudflare" : options.netlify ? "netlify" : void 0;
-	const platform = normalizeDeployTarget(cliTarget || config?.deploy.target);
-	if (platform !== "vercel" && platform !== "cloudflare" && platform !== "netlify") {
-		logger.error("Please specify a deployment target with --vercel, --cloudflare, --netlify, or farm.config deploy.target.");
-		process.exit(1);
-	}
+	const platform = normalizeDeployTarget(cliTarget || config.deploy.target);
+	if (platform !== "vercel" && platform !== "cloudflare" && platform !== "netlify") throw new Error("Please specify a deployment target with --vercel, --cloudflare, --netlify, or farm.config deploy.target.");
+	const configuredPreset = userConfig?.deploy?.preset || userConfig?.preset;
+	const configuredPresetTarget = getDeployTargetForPreset(configuredPreset);
+	const configuredTarget = normalizeDeployTarget(userConfig?.deploy?.target);
+	const presetMatchesPlatform = Boolean(configuredPreset) && (configuredPresetTarget === platform || !configuredPresetTarget && configuredTarget === platform);
+	if (cliTarget && configuredPreset && !presetMatchesPlatform) logger.warn(`Configured preset "${configuredPreset}" targets ${configuredPresetTarget || "an unknown platform"}; using the "${getPresetForDeployTarget(platform)}" preset because --${cliTarget} was passed.`);
 	const deployConfig = resolveDeployConfig(userConfig || {}, {
 		target: platform,
-		preset: cliTarget ? userConfig?.deploy?.preset || userConfig?.preset || getPresetForDeployTarget(platform) : void 0
+		preset: cliTarget ? presetMatchesPlatform ? configuredPreset : getPresetForDeployTarget(platform) : void 0
 	});
 	const preset = deployConfig.preset || getPresetForDeployTarget(platform) || "node-server";
-	logger.info(`🚀 Building with ${preset} preset...`);
-	await buildFarm({
-		root,
-		preset
-	});
 	const nitroOutput = resolveDeployOutputPath(root, deployConfig.outputDir);
-	if (!existsSync$1(nitroOutput)) {
-		logger.error(`Build output not found at ${nitroOutput}. Please run 'farm build' first.`);
-		process.exit(1);
+	const cloudflareAgent = platform === "cloudflare" ? resolveCloudflareAgentDeployPlan(root) || resolveConfiguredCloudflareAgentDeployPlan(root, config.integrations) : void 0;
+	const deploy = createDeployCommand(platform, root, nitroOutput, deployConfig, options.prod, cloudflareAgent);
+	return {
+		plan: {
+			root: path$1.resolve(root),
+			target: platform,
+			preset,
+			runtime: getFarmPresetRuntime(preset),
+			outputDir: nitroOutput,
+			production: platform === "netlify" || Boolean(options.prod),
+			build: {
+				command: `farm build --preset ${preset}`,
+				cwd: path$1.resolve(root)
+			},
+			deploy,
+			...cloudflareAgent ? { cloudflareAgent } : {}
+		},
+		deployConfig
+	};
+}
+function createDeployCommand(platform, root, outputDir, deployConfig, prod, cloudflareAgent) {
+	if (platform === "vercel") {
+		const args = [
+			"deploy",
+			"--prebuilt",
+			"--yes",
+			...prod ? ["--prod"] : []
+		];
+		return {
+			command: formatCommand$1("vercel", args),
+			cwd: path$1.resolve(root),
+			executable: "vercel",
+			args
+		};
 	}
-	await deployPlatform(platform, root, nitroOutput, deployConfig, options.prod);
+	if (platform === "netlify") {
+		const args = createNetlifyDeployArgs(deployConfig.netlify?.site);
+		return {
+			command: formatCommand$1("netlify", args),
+			cwd: outputDir,
+			executable: "netlify",
+			args
+		};
+	}
+	if (cloudflareAgent) {
+		const args = [
+			"deploy",
+			"--config",
+			cloudflareAgent.configPath,
+			...cloudflareAgent.environment ? ["--env", cloudflareAgent.environment] : []
+		];
+		return {
+			command: formatCommand$1("wrangler", args),
+			cwd: path$1.resolve(root),
+			executable: "wrangler",
+			args
+		};
+	}
+	const args = [
+		"pages",
+		"deploy",
+		".",
+		`--project-name=${deployConfig.cloudflare?.projectName || deployConfig.projectName || "farm-app"}`
+	];
+	return {
+		command: formatCommand$1("wrangler", args),
+		cwd: outputDir,
+		executable: "wrangler",
+		args
+	};
+}
+function createNetlifyDeployArgs(site) {
+	return [
+		"deploy",
+		"--prod",
+		"--dir=.",
+		...site ? [`--site=${site}`] : []
+	];
 }
 /**
 * Deploy using platform's native CLI (user credentials)
@@ -68,19 +189,20 @@ async function deployPlatform(platform, root, outputDir, deployConfig, prod) {
 async function deployVercel(root, outputDir, prod) {
 	logger.info("🚀 Deploying to Vercel...");
 	try {
-		execSync("vercel --version", { stdio: "ignore" });
-	} catch {
-		logger.error("❌ Vercel CLI is not installed.");
-		logger.info("💡 Install it with: npm i -g vercel");
-		process.exit(1);
+		execFileSync("vercel", ["--version"], {
+			stdio: "ignore",
+			cwd: root
+		});
+	} catch (error) {
+		throw new FarmDeployError("CLI_NOT_INSTALLED", "vercel", "Vercel CLI is not installed. Install it with: npm i -g vercel", { cause: error });
 	}
 	try {
-		execSync("vercel whoami", { stdio: "ignore" });
-	} catch {
-		logger.warn("⚠️  Not logged in to Vercel.");
-		logger.info("💡 Please run: vercel login");
-		logger.info("   Then run: farm deploy --vercel");
-		process.exit(1);
+		execFileSync("vercel", ["whoami"], {
+			stdio: "ignore",
+			cwd: root
+		});
+	} catch (error) {
+		throw new FarmDeployError("CLI_NOT_AUTHENTICATED", "vercel", "Vercel CLI is not authenticated. Run 'vercel login', then retry the deployment.", { cause: error });
 	}
 	try {
 		const { existsSync, statSync, readdirSync } = await import("fs");
@@ -89,14 +211,8 @@ async function deployVercel(root, outputDir, prod) {
 		const configFile = path$1.join(outputDir, "config.json");
 		const serverIndex = path$1.join(functionsDir, "index.mjs");
 		logger.info("🔍 Verifying deployment structure...");
-		if (!existsSync(functionsDir)) {
-			logger.error(`❌ Functions directory not found at ${functionsDir}`);
-			process.exit(1);
-		}
-		if (!existsSync(serverIndex)) {
-			logger.error(`❌ Server entry point not found at ${serverIndex}`);
-			process.exit(1);
-		}
+		if (!existsSync(functionsDir)) throw new FarmDeployError("INVALID_BUILD_OUTPUT", "vercel", `Functions directory not found at ${functionsDir}.`);
+		if (!existsSync(serverIndex)) throw new FarmDeployError("INVALID_BUILD_OUTPUT", "vercel", `Server entry point not found at ${serverIndex}.`);
 		logger.info(`✅ Functions directory: ${functionsDir}`);
 		if (!existsSync(staticDir)) logger.warn(`⚠️  Static directory not found at ${staticDir}`);
 		else {
@@ -177,14 +293,19 @@ async function deployVercel(root, outputDir, prod) {
 		logger.info(`   Static: ${staticDir}`);
 		logger.info(`   Config: ${configFile}`);
 		logger.info("📤 Uploading to Vercel...");
-		execSync(`vercel deploy --prebuilt --yes${prod ? " --prod" : ""}`, {
+		execFileSync("vercel", [
+			"deploy",
+			"--prebuilt",
+			"--yes",
+			...prod ? ["--prod"] : []
+		], {
 			stdio: "inherit",
 			cwd: root
 		});
 		logger.success("✅ Deployed to Vercel successfully!");
 	} catch (error) {
-		logger.error(`❌ Failed to deploy to Vercel: ${error.message}`);
-		process.exit(1);
+		if (error instanceof FarmDeployError) throw error;
+		throw new FarmDeployError("DEPLOY_FAILED", "vercel", `Failed to deploy to Vercel: ${getErrorMessage(error)}`, { cause: error });
 	}
 }
 /** Deploy to a composed Worker or fall back to Cloudflare Pages. */
@@ -205,8 +326,7 @@ async function deployCloudflare(root, outputDir, projectName) {
 			});
 			logger.success("✅ Deployed Farm and Cloudflare Agents successfully!");
 		} catch (error) {
-			logger.error(`❌ Failed to deploy to Cloudflare: ${error.message}`);
-			process.exit(1);
+			throw new FarmDeployError("DEPLOY_FAILED", "cloudflare", `Failed to deploy to Cloudflare: ${getErrorMessage(error)}`, { cause: error });
 		}
 		return;
 	}
@@ -224,8 +344,7 @@ async function deployCloudflare(root, outputDir, projectName) {
 		});
 		logger.success("✅ Deployed to Cloudflare Pages successfully!");
 	} catch (error) {
-		logger.error(`❌ Failed to deploy to Cloudflare: ${error.message}`);
-		process.exit(1);
+		throw new FarmDeployError("DEPLOY_FAILED", "cloudflare", `Failed to deploy to Cloudflare: ${getErrorMessage(error)}`, { cause: error });
 	}
 }
 /** Read the trusted Workers deployment handoff emitted by @farm.js/cf-agent. */
@@ -251,16 +370,34 @@ function resolveCloudflareAgentDeployPlan(root) {
 		...typeof environment === "string" ? { environment: environment.trim() } : {}
 	};
 }
+function resolveConfiguredCloudflareAgentDeployPlan(root, integrations) {
+	const integration = Object.values(integrations || {}).find((value) => isRecord(value) && value.category === "agent" && value.type === "cloudflare" && value.serverRuntime === false);
+	if (!isRecord(integration) || !isRecord(integration.instance)) return void 0;
+	const configuredPath = integration.instance.config;
+	if (typeof configuredPath !== "string" || !configuredPath.trim()) return void 0;
+	const projectRoot = path$1.resolve(root);
+	const sourceConfigPath = path$1.resolve(projectRoot, configuredPath);
+	assertPathInsideProject(projectRoot, sourceConfigPath, "Cloudflare Agents source config");
+	const configPath = path$1.join(path$1.dirname(sourceConfigPath), ".farm-cf-agent.wrangler.jsonc");
+	const environment = integration.instance.environment;
+	return {
+		configPath,
+		...typeof environment === "string" && environment.trim() ? { environment: environment.trim() } : {},
+		generated: true
+	};
+}
+function assertPathInsideProject(projectRoot, candidate, label) {
+	const relativePath = path$1.relative(projectRoot, candidate);
+	if (relativePath === ".." || relativePath.startsWith(`..${path$1.sep}`) || path$1.isAbsolute(relativePath)) throw new Error(`${label} must stay inside the Farm project root.`);
+}
 function assertWranglerInstalled(root) {
 	try {
 		execFileSync("wrangler", ["--version"], {
 			stdio: "ignore",
 			cwd: root
 		});
-	} catch {
-		logger.error("❌ Wrangler CLI is not installed.");
-		logger.info("💡 Install it in this project with: npm i -D wrangler");
-		process.exit(1);
+	} catch (error) {
+		throw new FarmDeployError("CLI_NOT_INSTALLED", "cloudflare", "Wrangler CLI is not installed. Install it in this project with: npm i -D wrangler", { cause: error });
 	}
 }
 function isRecord(value) {
@@ -272,20 +409,103 @@ function isRecord(value) {
 async function deployNetlify(root, outputDir, site) {
 	logger.info("🚀 Deploying to Netlify...");
 	try {
-		execSync("netlify --version", { stdio: "ignore" });
-	} catch {
-		logger.error("❌ Netlify CLI is not installed.");
-		logger.info("💡 Install it with: npm i -g netlify-cli");
-		process.exit(1);
+		execFileSync("netlify", ["--version"], {
+			stdio: "ignore",
+			cwd: root
+		});
+	} catch (error) {
+		throw new FarmDeployError("CLI_NOT_INSTALLED", "netlify", "Netlify CLI is not installed. Install it with: npm i -g netlify-cli", { cause: error });
 	}
 	try {
-		process.chdir(outputDir);
-		const siteFlag = site ? ` --site=${site}` : "";
-		execSync(`netlify deploy --prod --dir=.${siteFlag}`, { stdio: "inherit" });
+		execFileSync("netlify", createNetlifyDeployArgs(site), {
+			stdio: "inherit",
+			cwd: outputDir
+		});
 		logger.success("✅ Deployed to Netlify successfully!");
 	} catch (error) {
-		logger.error(`❌ Failed to deploy to Netlify: ${error.message}`);
-		process.exit(1);
+		throw new FarmDeployError("DEPLOY_FAILED", "netlify", `Failed to deploy to Netlify: ${getErrorMessage(error)}`, { cause: error });
+	}
+}
+function formatCommand$1(executable, args) {
+	return [executable, ...args].map(formatCommandArgument).join(" ");
+}
+const SAFE_ARGUMENT = process.platform === "win32" ? /^[A-Za-z0-9_.\\/:=@+-]+$/ : /^[A-Za-z0-9_./:=@+-]+$/;
+function formatCommandArgument(argument) {
+	if (SAFE_ARGUMENT.test(argument)) return argument;
+	return `'${argument.replace(/'/g, `'"'"'`)}'`;
+}
+function getErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/start.ts
+var FarmStartError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.name = "FarmStartError";
+		this.code = code;
+	}
+};
+const PLATFORM_HINTS = {
+	vercel: "Deploy it with `farm deploy --vercel`",
+	cloudflare: "Deploy it with `farm deploy --cloudflare`",
+	netlify: "Deploy it with `farm deploy --netlify`"
+};
+async function createFarmStartPlan(options = {}) {
+	const root = path$1.resolve(options.root || process.cwd());
+	const userConfig = await loadConfig(root, void 0, "production");
+	const deployConfig = resolveDeployConfig(userConfig || {});
+	const target = deployConfig.target;
+	const preset = deployConfig.preset || "node-server";
+	const outputDir = resolveDeployOutputPath(root, deployConfig.outputDir);
+	if (target && target !== "node") throw new FarmStartError("PLATFORM_TARGET", `The "${target}" target builds platform output with no local server to start. ${PLATFORM_HINTS[target]}, or set deploy.target: "node" in farm.config.ts to self-host.`);
+	if (!target) throw new FarmStartError("UNSUPPORTED_PRESET", `Preset "${preset}" has no known local server entry. Set deploy.target: "node" in farm.config.ts to self-host.`);
+	const serverEntry = path$1.join(outputDir, "server", "index.mjs");
+	if (!existsSync$1(serverEntry)) throw new FarmStartError("MISSING_OUTPUT", `No build output found at ${serverEntry}. Run \`farm build\` first.`);
+	const env = {};
+	if (options.port !== void 0 && options.port !== "") env.NITRO_PORT = String(options.port);
+	if (options.host) env.NITRO_HOST = options.host;
+	return {
+		root,
+		target: "node",
+		preset,
+		outputDir,
+		serverEntry,
+		command: {
+			command: process.execPath,
+			args: [serverEntry]
+		},
+		env
+	};
+}
+async function startFarm(options = {}) {
+	const plan = await createFarmStartPlan(options);
+	logger.info(`Starting Node server: node ${path$1.relative(plan.root, plan.serverEntry)}`);
+	const child = spawn(plan.command.command, plan.command.args, {
+		cwd: plan.root,
+		stdio: "inherit",
+		env: {
+			...process.env,
+			...plan.env
+		}
+	});
+	const forward = (signal) => {
+		const handler = () => child.kill(signal);
+		process.on(signal, handler);
+		return () => process.off(signal, handler);
+	};
+	const cleanups = [forward("SIGINT"), forward("SIGTERM")];
+	try {
+		await new Promise((resolve, reject) => {
+			child.on("error", reject);
+			child.on("exit", (code, signal) => {
+				if (signal) process.exitCode = 128 + (constants.signals[signal] ?? 1);
+				else if (code !== null) process.exitCode = code;
+				resolve();
+			});
+		});
+	} finally {
+		for (const cleanup of cleanups) cleanup();
 	}
 }
 //#endregion
@@ -310,10 +530,12 @@ const HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
 function createPreviewGatewayPlan(target, options = {}) {
 	const requestedName = sanitizePreviewName$1(options.name || process.env.FARM_PREVIEW_NAME) || randomPreviewName$1();
 	const gatewayUrl = normalizeGatewayUrl(options.gatewayUrl || process.env.FARM_PREVIEW_GATEWAY_URL || DEFAULT_GATEWAY_URL);
+	const relayUrl = normalizeRelayUrl(process.env.FARM_PREVIEW_RELAY_URL || gatewayUrl);
 	const requestedHostname = `${requestedName}.${normalizePreviewDomain$1(process.env.FARM_PREVIEW_DOMAIN || DEFAULT_PREVIEW_DOMAIN)}`;
 	return {
 		provider: "farm-gateway",
 		gatewayUrl,
+		relayUrl,
 		target,
 		requestedName,
 		requestedHostname,
@@ -422,6 +644,9 @@ async function createGatewaySession(plan, timeoutMs) {
 	if (!session.id || !session.token || !session.publicUrl) throw new Error("Preview gateway returned an invalid session.");
 	return session;
 }
+function getSetCookies(headers) {
+	return headers.getSetCookie?.call(headers) || [];
+}
 async function forwardGatewayRequest(target, request) {
 	const headers = new Headers();
 	for (const [key, value] of Object.entries(request.headers || {})) {
@@ -440,8 +665,10 @@ async function forwardGatewayRequest(target, request) {
 	const responseHeaders = {};
 	response.headers.forEach((value, key) => {
 		const normalized = key.toLowerCase();
-		if (!HOP_BY_HOP_HEADERS.has(normalized)) responseHeaders[key] = value;
+		if (!HOP_BY_HOP_HEADERS.has(normalized) && normalized !== "set-cookie") responseHeaders[key] = value;
 	});
+	const setCookies = getSetCookies(response.headers);
+	if (setCookies.length > 0) responseHeaders["set-cookie"] = setCookies;
 	return {
 		status: response.status,
 		headers: responseHeaders,
@@ -478,6 +705,7 @@ async function closeGatewaySession(plan, session) {
 function formatGatewayPlan(plan) {
 	return [
 		`Gateway: ${plan.gatewayUrl}`,
+		`Relay:   ${plan.relayUrl}`,
 		`Local:   ${plan.target.localUrl}`,
 		`Public:  ${plan.requestedPublicUrl}`
 	].join("\n");
@@ -489,6 +717,17 @@ function formatRequestPath(path) {
 function normalizeGatewayUrl(value) {
 	return value.replace(/\/+$/, "");
 }
+function normalizeRelayUrl(value) {
+	const url = new URL(value);
+	if (url.protocol === "http:") url.protocol = "ws:";
+	if (url.protocol === "https:") url.protocol = "wss:";
+	if (url.protocol !== "ws:" && url.protocol !== "wss:") throw new Error(`Preview relay must use ws or wss, received ${url.protocol}`);
+	const pathname = url.pathname.replace(/\/+$/, "");
+	url.pathname = pathname.endsWith("/agent") ? pathname : `${pathname}/agent`;
+	url.search = "";
+	url.hash = "";
+	return url.toString();
+}
 function normalizePreviewDomain$1(value) {
 	return value.replace(/^https?:\/\//, "").replace(/^\.*/, "").replace(/\/*$/, "");
 }
@@ -500,6 +739,39 @@ function randomPreviewName$1() {
 	return `farm-${Math.random().toString(36).slice(2, 8)}`;
 }
 //#endregion
+//#region src/preview-native.ts
+async function runNativePreviewTunnel(plan, options = {}) {
+	const runtime = options.runtime || await loadNativeTunnel();
+	const session = await runtime.startPreviewAgent(plan.relayUrl, plan.requestedName, plan.target.localUrl);
+	let stopping = false;
+	const stop = () => {
+		if (stopping) return;
+		stopping = true;
+		runtime.stopPreviewAgent(session.sessionId);
+	};
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+	logger.success("Preview URL ready.");
+	logger.info(`Public: ${session.publicUrl}`);
+	logger.info("Forwarding requests through the native tunnel until Ctrl+C.");
+	try {
+		if (!await runtime.waitPreviewAgent(session.sessionId)) throw new Error("The native preview tunnel stopped before its lifecycle could be observed.");
+		return session;
+	} finally {
+		process.removeListener("SIGINT", stop);
+		process.removeListener("SIGTERM", stop);
+		await runtime.stopPreviewAgent(session.sessionId).catch(() => false);
+	}
+}
+async function loadNativeTunnel() {
+	try {
+		return await import("@farm.js/tunnel");
+	} catch (error) {
+		const reason = error instanceof Error ? ` ${error.message}` : "";
+		throw new Error(`Could not load @farm.js/tunnel for this platform. Reinstall @farm.js/cli so its native platform package is restored.${reason}`);
+	}
+}
+//#endregion
 //#region src/preview.ts
 const DEFAULT_PREVIEW_PORTS = [
 	3e3,
@@ -523,15 +795,26 @@ async function previewFarm(options = {}) {
 				plan
 			};
 		}
-		logger.info(`Gateway: ${plan.gatewayUrl}`);
-		logger.info("Opening Farm preview gateway session...");
-		const session = await runPreviewGateway(plan, { timeoutMs: options.timeoutMs });
-		return {
-			target,
-			plan,
-			publicUrl: session.publicUrl,
-			session
-		};
+		logger.info(`Relay: ${plan.relayUrl}`);
+		logger.info("Opening native Farm preview tunnel...");
+		try {
+			const session = await runNativePreviewTunnel(plan);
+			return {
+				target,
+				plan,
+				publicUrl: session.publicUrl,
+				session
+			};
+		} catch (error) {
+			logger.warn(`Native preview relay unavailable; using compatibility gateway polling.${formatPreviewError(error)}`);
+			const session = await runPreviewGateway(plan, { timeoutMs: options.timeoutMs });
+			return {
+				target,
+				plan,
+				publicUrl: session.publicUrl,
+				session
+			};
+		}
 	}
 	const plan = createPreviewTunnelPlan(target, options);
 	if (options.dryRun) {
@@ -549,6 +832,9 @@ async function previewFarm(options = {}) {
 		publicUrl: await runPreviewTunnel(plan, options.timeoutMs ?? 3e4)
 	};
 }
+function formatPreviewError(error) {
+	return error instanceof Error && error.message ? ` ${error.message}` : "";
+}
 function shouldUseManagedGateway(options) {
 	if (options.provider === "farm" || process.env.FARM_PREVIEW_PROVIDER === "farm") return true;
 	if (options.provider === "local" || process.env.FARM_PREVIEW_PROVIDER === "local") return false;
@@ -657,7 +943,7 @@ function parsePreviewPublicUrl(output, preferredHostname) {
 	}) || urls[0];
 }
 async function runPreviewTunnel(plan, timeoutMs) {
-	const child = spawn(plan.command, plan.args, {
+	const child = spawn$1(plan.command, plan.args, {
 		env: {
 			...process.env,
 			FARM_PREVIEW_LOCAL_URL: plan.target.localUrl,
@@ -799,10 +1085,20 @@ function normalizePreviewDomain(value) {
 }
 //#endregion
 //#region src/generate.ts
+var FarmGeneratedArtifactsStaleError = class extends Error {
+	constructor(root, stalePaths) {
+		const normalizedPaths = [...new Set(stalePaths)].sort();
+		const relativePaths = normalizedPaths.map((filePath) => path.relative(root, filePath));
+		super(`Generated types are stale:\n${relativePaths.map((filePath) => `  - ${filePath}`).join("\n")}\nRun farm generate and commit the updated files.`);
+		this.name = "FarmGeneratedArtifactsStaleError";
+		this.stalePaths = normalizedPaths;
+	}
+};
 const PRISMA_GENERATED_START = "// Farm.js integrations generated schema: start";
 const PRISMA_GENERATED_END = "// Farm.js integrations generated schema: end";
 async function generateFarmArtifacts(options = {}) {
 	const root = path.resolve(options.root || process.cwd());
+	if (options.check && hasSchemaOptions(options)) throw new Error("--check verifies generated framework types and cannot be combined with schema output options.");
 	const userConfig = await loadConfig(root, options.configPath, "development");
 	if (!userConfig && hasSchemaOptions(options)) throw new Error("No Farm config found. Please create farm.config.ts or config.ts.");
 	const resolvedConfig = await resolveConfig({
@@ -810,34 +1106,28 @@ async function generateFarmArtifacts(options = {}) {
 		...userConfig
 	}, "development");
 	const extraRoutes = [...resolvedConfig.openapi?.enabled && resolvedConfig.openapi.route ? [resolvedConfig.openapi.route] : [], ...getFarmDocsRouteTypeEntries(resolvedConfig.docs)];
-	await generateRouteTypes({
+	const typeArtifacts = await generateFarmTypeArtifacts({
 		root: resolvedConfig.root,
 		srcDir: resolvedConfig.srcDir,
+		configPath: options.configPath,
+		layers: resolvedConfig.layers,
 		extraRoutes,
-		suppressLintOnLink: resolvedConfig.suppressLintOnLink
-	});
-	await generateEnvTypes({
-		root: resolvedConfig.root,
-		srcDir: resolvedConfig.srcDir,
-		configPath: options.configPath
-	});
-	const appDir = path.join(resolvedConfig.root, resolvedConfig.srcDir, "app");
-	const apiGenerator = new APITypeGenerator(appDir);
-	const apiRoutes = apiGenerator.scanAPIRoutes();
-	const apiTypesPath = path.join(resolvedConfig.root, resolvedConfig.srcDir, "lib", "api.generated.ts");
-	await mkdir(path.dirname(apiTypesPath), { recursive: true });
-	await writeFile(apiTypesPath, apiGenerator.generateAPIRouter(apiRoutes), "utf8");
-	if (resolvedConfig.i18n.enabled) await generateFarmI18nTypes({
-		root: resolvedConfig.root,
-		srcDir: resolvedConfig.srcDir,
-		config: resolvedConfig.i18n
+		suppressLintOnLink: resolvedConfig.suppressLintOnLink,
+		componentExtensions: resolvedConfig.renderer.componentExtensions,
+		i18nConfig: resolvedConfig.i18n,
+		check: options.check
 	});
-	logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types (${apiRoutes.length} API route${apiRoutes.length === 1 ? "" : "s"}).`);
+	if (options.check) {
+		if (typeArtifacts.stalePaths.length) throw new FarmGeneratedArtifactsStaleError(root, typeArtifacts.stalePaths);
+		logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types are up to date.`);
+		return typeArtifacts;
+	}
+	logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types (${typeArtifacts.apiRoutes.length} API route${typeArtifacts.apiRoutes.length === 1 ? "" : "s"}).`);
 	const schemas = getIntegrationSchemas(resolvedConfig.integrations);
 	const schemaEntries = Object.entries(schemas);
 	if (!schemaEntries.length) {
 		if (hasSchemaOptions(options)) logger.warn("No integration schemas were found in the current Farm config.");
-		return;
+		return typeArtifacts;
 	}
 	const packageManifest = await readPackageManifest(root);
 	const schemaOptionsExplicit = hasSchemaOptions(options);
@@ -847,12 +1137,12 @@ async function generateFarmArtifacts(options = {}) {
 	} catch (error) {
 		if (schemaOptionsExplicit) throw error;
 		logger.warn(`Integration schemas were found, but Farm could not choose a schema target automatically: ${error.message}`);
-		return;
+		return typeArtifacts;
 	}
 	if (!orm) {
 		if (!schemaOptionsExplicit) {
 			logger.warn("Integration schemas were found, but no data layer was detected. Pass --orm prisma|drizzle|postgres|mysql|sqlite|mongodb to generate schema artifacts.");
-			return;
+			return typeArtifacts;
 		}
 		throw new Error("Could not auto-detect a schema target. Pass one explicitly with --orm prisma|drizzle|postgres|mysql|sqlite|mongodb.");
 	}
@@ -863,7 +1153,7 @@ async function generateFarmArtifacts(options = {}) {
 			if (!existsSync(schemaPath)) throw new Error(`Prisma target was selected but no schema file was found at ${schemaPath}. Create prisma/schema.prisma or pass --output.`);
 			await writePrismaSchema(schemaPath, collectedModels);
 			logger.success(`Generated Prisma integration schema in ${path.relative(root, schemaPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "drizzle": {
 			const dialect = options.dialect ?? await detectDrizzleDialect(root, packageManifest) ?? void 0;
@@ -871,7 +1161,7 @@ async function generateFarmArtifacts(options = {}) {
 			const outputPath = options.output ? path.resolve(root, options.output) : path.join(root, "farm-integrations.generated.ts");
 			await writeGeneratedFile(outputPath, generateDrizzleSchema(collectedModels, dialect));
 			logger.success(`Generated Drizzle integration schema in ${path.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "postgres":
 		case "mysql":
@@ -879,13 +1169,13 @@ async function generateFarmArtifacts(options = {}) {
 			const outputPath = options.output ? path.resolve(root, options.output) : path.join(root, `farm-integrations.generated.${orm}.sql`);
 			await writeGeneratedFile(outputPath, generateSqlSchema(collectedModels, orm));
 			logger.success(`Generated ${orm} integration schema in ${path.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "mongodb": {
 			const outputPath = options.output ? path.resolve(root, options.output) : path.join(root, "farm-integrations.generated.mongodb.ts");
 			await writeGeneratedFile(outputPath, generateMongoBootstrap(collectedModels));
 			logger.success(`Generated MongoDB integration bootstrap in ${path.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 	}
 }
@@ -1070,7 +1360,7 @@ function cloneSchemaModel(model) {
 async function writePrismaSchema(schemaPath, models) {
 	const source = await readFile(schemaPath, "utf8");
 	const generated = createPrismaGeneratedBlock(generatePrismaSchema(models));
-	const pattern = new RegExp(`${escapeRegExp(PRISMA_GENERATED_START)}[\\s\\S]*?${escapeRegExp(PRISMA_GENERATED_END)}`, "m");
+	const pattern = new RegExp(`${escapeRegExp$1(PRISMA_GENERATED_START)}[\\s\\S]*?${escapeRegExp$1(PRISMA_GENERATED_END)}`, "m");
 	const nextSource = pattern.test(source) ? source.replace(pattern, generated) : `${source.trimEnd()}\n\n${generated}\n`;
 	await writeFile(schemaPath, nextSource, "utf8");
 }
@@ -1092,18 +1382,18 @@ function renderPrismaModel(model) {
 		const defaultAttribute = getPrismaDefaultAttribute(field);
 		if (defaultAttribute) attributes.push(defaultAttribute);
 		if (field.meta?.autoUpdate && field.type === "datetime") attributes.push("@updatedAt");
-		if (field.name !== fieldKey) attributes.push(`@map("${escapeString(field.name)}")`);
+		if (field.name !== fieldKey) attributes.push(`@map("${escapeDoubleQuoted(field.name)}")`);
 		if (attributes.length) parts.push(attributes.join(" "));
 		lines.push(`  ${parts.join(" ")}`);
-		if (field.index) modelLevelConstraints.push(`@@index([${fieldKey}], map: "${escapeString(`${model.modelName}_${field.name}_idx`)}")`);
+		if (field.index) modelLevelConstraints.push(`@@index([${fieldKey}], map: "${escapeDoubleQuoted(`${model.modelName}_${field.name}_idx`)}")`);
 	}
 	for (const constraint of model.model.constraints || []) {
 		const fields = constraint.fields.join(", ");
 		const attribute = constraint.type === "unique" ? "@@unique" : "@@index";
-		const suffix = constraint.name ? `, map: "${escapeString(constraint.name)}"` : "";
+		const suffix = constraint.name ? `, map: "${escapeDoubleQuoted(constraint.name)}"` : "";
 		modelLevelConstraints.push(`${attribute}([${fields}]${suffix})`);
 	}
-	lines.push(`  @@map("${escapeString(model.modelName)}")`);
+	lines.push(`  @@map("${escapeDoubleQuoted(model.modelName)}")`);
 	for (const constraint of modelLevelConstraints) lines.push(`  ${constraint}`);
 	lines.push("}");
 	return lines.join("\n");
@@ -1121,7 +1411,7 @@ function getPrismaFieldType(field) {
 function getPrismaDefaultAttribute(field) {
 	if (field.default === void 0) return null;
 	if (field.type === "datetime" && field.default === "now") return "@default(now())";
-	if (typeof field.default === "string") return `@default("${escapeString(field.default)}")`;
+	if (typeof field.default === "string") return `@default("${escapeDoubleQuoted(field.default)}")`;
 	if (typeof field.default === "number" || typeof field.default === "boolean") return `@default(${String(field.default)})`;
 	return null;
 }
@@ -1159,12 +1449,12 @@ function renderDrizzleModel(model, dialect, tableFactoryName) {
 		lines.push(`  ${fieldKey}: ${renderDrizzleColumn(field, dialect)},`);
 	}
 	lines.push("}, (table) => ({");
-	for (const [fieldKey, field] of Object.entries(model.model.fields)) if (field.index) lines.push(`  ${fieldKey}Idx: index("${escapeString(`${model.modelName}_${field.name}_idx`)}").on(table.${fieldKey}),`);
+	for (const [fieldKey, field] of Object.entries(model.model.fields)) if (field.index) lines.push(`  ${fieldKey}Idx: index("${escapeDoubleQuoted(`${model.modelName}_${field.name}_idx`)}").on(table.${fieldKey}),`);
 	for (const constraint of model.model.constraints || []) {
 		const builder = constraint.type === "unique" ? "uniqueIndex" : "index";
 		const accessor = constraint.fields.map((fieldKey) => `table.${fieldKey}`).join(", ");
 		const name = constraint.name || `${model.modelName}_${constraint.fields.map((fieldKey) => model.model.fields[fieldKey]?.name || fieldKey).join("_")}_${constraint.type}`;
-		lines.push(`  ${toCamelCase(name)}: ${builder}("${escapeString(name)}").on(${accessor}),`);
+		lines.push(`  ${toCamelCase(name)}: ${builder}("${escapeDoubleQuoted(name)}").on(${accessor}),`);
 	}
 	lines.push("}));");
 	return lines.join("\n");
@@ -1242,7 +1532,7 @@ function renderSqliteDrizzleColumn(field) {
 function getDrizzleDefaultExpression(field, dialect) {
 	if (field.default === void 0) return "";
 	if (field.type === "datetime" && field.default === "now") return dialect === "sqlite" ? "" : ".defaultNow()";
-	if (typeof field.default === "string") return `.default("${escapeString(field.default)}")`;
+	if (typeof field.default === "string") return `.default("${escapeDoubleQuoted(field.default)}")`;
 	if (typeof field.default === "number" || typeof field.default === "boolean") return `.default(${String(field.default)})`;
 	return "";
 }
@@ -1333,7 +1623,7 @@ function getSqlColumnType(field, dialect) {
 function getSqlDefaultExpression(field, dialect) {
 	if (field.default === void 0) return null;
 	if (field.type === "datetime" && field.default === "now") return "CURRENT_TIMESTAMP";
-	if (typeof field.default === "string") return `'${escapeString(field.default)}'`;
+	if (typeof field.default === "string") return `'${escapeSqlString(field.default)}'`;
 	if (typeof field.default === "number") return String(field.default);
 	if (typeof field.default === "boolean") {
 		if (dialect === "sqlite") return field.default ? "1" : "0";
@@ -1350,20 +1640,20 @@ function generateMongoBootstrap(models) {
 	];
 	for (const model of models) {
 		lines.push(`  // Integration "${model.integrationKey}" model "${model.modelKey}"`);
-		lines.push(`  const ${model.exportName} = db.collection("${escapeString(model.modelName)}");`);
+		lines.push(`  const ${model.exportName} = db.collection("${escapeDoubleQuoted(model.modelName)}");`);
 		for (const [fieldKey, field] of Object.entries(model.model.fields)) {
 			if (field.unique) {
 				const options = ["unique: true"];
 				if (isNullableField(field)) options.push("sparse: true");
-				options.push(`name: "${escapeString(`${model.modelName}_${field.name}_unique`)}"`);
+				options.push(`name: "${escapeDoubleQuoted(`${model.modelName}_${field.name}_unique`)}"`);
 				lines.push(`  await ${model.exportName}.createIndex({ ${JSON.stringify(field.name)}: 1 }, { ${options.join(", ")} });`);
-			} else if (field.index) lines.push(`  await ${model.exportName}.createIndex({ ${JSON.stringify(field.name)}: 1 }, { name: "${escapeString(`${model.modelName}_${field.name}_idx`)}" });`);
+			} else if (field.index) lines.push(`  await ${model.exportName}.createIndex({ ${JSON.stringify(field.name)}: 1 }, { name: "${escapeDoubleQuoted(`${model.modelName}_${field.name}_idx`)}" });`);
 			if (field.reference) lines.push(`  // ${fieldKey} references ${field.reference.model}.${field.reference.field}${field.reference.onDelete ? ` (onDelete: ${field.reference.onDelete})` : ""}`);
 		}
 		for (const constraint of model.model.constraints || []) {
 			const indexSpec = constraint.fields.map((fieldKey) => `${JSON.stringify(model.model.fields[fieldKey]?.name || fieldKey)}: 1`).join(", ");
 			const indexName = constraint.name || `${model.modelName}_${constraint.fields.map((fieldKey) => model.model.fields[fieldKey]?.name || fieldKey).join("_")}_${constraint.type}`;
-			const options = constraint.type === "unique" ? `{ unique: true, name: "${escapeString(indexName)}" }` : `{ name: "${escapeString(indexName)}" }`;
+			const options = constraint.type === "unique" ? `{ unique: true, name: "${escapeDoubleQuoted(indexName)}" }` : `{ name: "${escapeDoubleQuoted(indexName)}" }`;
 			lines.push(`  await ${model.exportName}.createIndex({ ${indexSpec} }, ${options});`);
 		}
 		lines.push("");
@@ -1395,19 +1685,23 @@ function toCamelCase(value) {
 	const pascal = toPascalCase(value);
 	return pascal ? pascal.charAt(0).toLowerCase() + pascal.slice(1) : pascal;
 }
-function escapeString(value) {
-	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/'/g, "''");
+function escapeDoubleQuoted(value) {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
 }
-function escapeRegExp(value) {
+function escapeSqlString(value) {
+	return value.replace(/'/g, "''");
+}
+function escapeRegExp$1(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
 //#region src/doctor.ts
-const ROUTE_EXTENSIONS = [
+const ROUTE_EXTENSIONS$1 = [
 	"ts",
 	"tsx",
 	"js",
 	"jsx",
+	"vue",
 	"md",
 	"mdx"
 ];
@@ -1425,7 +1719,7 @@ async function runFarmDoctor(options = {}) {
 	const root = path.resolve(options.root || process.cwd());
 	const liveTarget = resolveLiveTarget(options);
 	let liveError;
-	if (!options.offline) try {
+	if (!options.offline && !options.fix) try {
 		return createLiveReport(await fetchLiveSnapshot(liveTarget, options), liveTarget, options.now);
 	} catch (error) {
 		liveError = formatError$2(error);
@@ -1472,6 +1766,13 @@ function formatFarmDoctorReport(report, options = {}) {
 		`${report.summary.fail} failed`,
 		`${report.summary.info} info`
 	].join(" / ");
+	if (report.fixes?.length) {
+		lines.push("", color.bold("FIXED"));
+		for (const fix of report.fixes) {
+			lines.push(`  ${color.green("✓")} ${fix.title}`);
+			lines.push(`    ${color.dim(fix.filePath)}`);
+		}
+	}
 	lines.push("", `${color.bold("SUMMARY")}  ${summary}`);
 	if (report.target?.devtoolsUrl) lines.push(`${color.bold("DEVTOOLS")} ${report.target.devtoolsUrl}`);
 	return lines.join("\n");
@@ -1498,6 +1799,10 @@ async function fetchLiveSnapshot(baseUrl, options) {
 		clearTimeout(timeout);
 	}
 }
+/** Reported paths are shown to the user, so keep them POSIX on every platform. */
+function toPosix$1(value) {
+	return value.split(path.sep).join("/");
+}
 function createLiveReport(snapshot, baseUrl, now) {
 	const checks = [
 		{
@@ -1571,16 +1876,17 @@ async function createProjectReport(root, options) {
 			action: "Add farm.config.ts and export defineConfig({...})."
 		});
 		else {
+			const configRoot = path.resolve(root, userConfig.root || ".");
 			config = await resolveConfig({
-				root,
-				...userConfig
+				...userConfig,
+				root: configRoot
 			}, "development");
 			const configFile = findConfigFile(root, options.configPath);
 			checks.push({
 				status: "pass",
 				code: "CONFIG_VALID",
 				title: "Farm config loads successfully",
-				message: configFile ? path.relative(root, configFile) || path.basename(configFile) : "Resolved config"
+				message: configFile ? toPosix$1(path.relative(root, configFile)) || path.basename(configFile) : "Resolved config"
 			});
 		}
 	} catch (error) {
@@ -1597,9 +1903,41 @@ async function createProjectReport(root, options) {
 		report.target = collectDeploymentChecks(config, userConfig, checks);
 		collectCronChecks(config, options.env || process.env, checks);
 	}
+	if (config && options.fix) {
+		const fixes = applySafeProjectFixes(root, config, checks);
+		if (fixes.length) {
+			const refreshed = await createProjectReport(root, {
+				...options,
+				fix: false
+			});
+			refreshed.fixes = fixes;
+			return refreshed;
+		}
+		report.fixes = [];
+	}
 	finalizeReport(report);
 	return report;
 }
+function applySafeProjectFixes(root, config, checks) {
+	const fixes = [];
+	if (checks.some((check) => check.code === "ROOT_LAYOUT_MISSING")) {
+		const rendererExtension = config.renderer.componentExtensions?.[0] || ".tsx";
+		const layoutPath = path.join(config.root, config.srcDir, "app", `layout${rendererExtension}`);
+		if (!existsSync(layoutPath)) {
+			mkdirSync(path.dirname(layoutPath), { recursive: true });
+			writeFileSync(layoutPath, config.renderer.name === "vue" ? `<script setup lang="ts">\ndefineOptions({ inheritAttrs: false });\n<\/script>\n\n<template>\n  <slot />\n</template>\n` : config.renderer.name === "solid" ? `import type { ParentProps } from "solid-js";\n\nexport default function RootLayout(props: ParentProps) {\n  return <>{props.children}</>;\n}\n` : `import type { ReactNode } from "react";\n\nexport default function RootLayout({ children }: { children: ReactNode }) {\n  return (\n    <html lang="en">\n      <body>{children}</body>\n    </html>\n  );\n}\n`, {
+				encoding: "utf8",
+				flag: "wx"
+			});
+			fixes.push({
+				code: "ROOT_LAYOUT_CREATED",
+				title: "Created the missing root layout",
+				filePath: toPosix$1(path.relative(root, layoutPath))
+			});
+		}
+	}
+	return fixes;
+}
 function collectNodeCheck(checks) {
 	const major = Number(process.versions.node.split(".")[0]);
 	checks.push(major >= 18 ? {
@@ -1659,8 +1997,8 @@ function collectPackageCheck(root, checks) {
 function collectRouterChecks(config, checks) {
 	const sources = getFarmSourceRoots(config);
 	const appDirectories = sources.map((source) => path.join(source.root, source.srcDir, "app"));
-	const hasPages = appDirectories.some((directory) => containsFile(directory, /^page\.(?:ts|tsx|js|jsx|md|mdx)$/));
-	const hasProgrammaticRoutes = sources.some((source) => ROUTE_EXTENSIONS.some((extension) => existsSync(path.join(source.root, source.srcDir, `farm.routes.${extension}`))));
+	const hasPages = appDirectories.some((directory) => containsFile(directory, /^page\.(?:ts|tsx|js|jsx|vue|md|mdx)$/));
+	const hasProgrammaticRoutes = sources.some((source) => ROUTE_EXTENSIONS$1.some((extension) => existsSync(path.join(source.root, source.srcDir, `farm.routes.${extension}`))));
 	checks.push(hasPages || hasProgrammaticRoutes ? {
 		status: "pass",
 		code: "APP_ROUTER_READY",
@@ -1673,7 +2011,8 @@ function collectRouterChecks(config, checks) {
 		message: `Farm found no page modules under ${config.srcDir}/app.`,
 		action: `Add ${config.srcDir}/app/page.tsx or ${config.srcDir}/farm.routes.tsx.`
 	});
-	const hasRootLayout = appDirectories.some((directory) => ROUTE_EXTENSIONS.some((extension) => existsSync(path.join(directory, `layout.${extension}`))));
+	const hasRootLayout = appDirectories.some((directory) => ROUTE_EXTENSIONS$1.some((extension) => existsSync(path.join(directory, `layout.${extension}`))));
+	const suggestedLayoutExtension = config.renderer.componentExtensions?.[0] || ".tsx";
 	checks.push(hasRootLayout ? {
 		status: "pass",
 		code: "ROOT_LAYOUT_READY",
@@ -1684,7 +2023,7 @@ function collectRouterChecks(config, checks) {
 		code: "ROOT_LAYOUT_MISSING",
 		title: "Root layout is missing",
 		message: "The application has no shared root layout.",
-		action: `Add ${config.srcDir}/app/layout.tsx.`
+		action: `Add ${config.srcDir}/app/layout${suggestedLayoutExtension}.`
 	});
 }
 function collectDeploymentChecks(config, userConfig, checks) {
@@ -1743,7 +2082,7 @@ function hasCronRoute(config, job) {
 	const relative = job.path.replace(/^\/+/, "").replace(/^api\//, "");
 	return getFarmSourceRoots(config).some((source) => {
 		const directory = path.join(source.root, source.srcDir, "app", "api", relative);
-		return ROUTE_EXTENSIONS.some((extension) => existsSync(path.join(directory, `route.${extension}`)));
+		return ROUTE_EXTENSIONS$1.some((extension) => existsSync(path.join(directory, `route.${extension}`)));
 	});
 }
 function containsFile(directory, pattern) {
@@ -1811,6 +2150,415 @@ function formatCount$1(value, noun) {
 	return `${value} ${noun}${value === 1 ? "" : "s"}`;
 }
 //#endregion
+//#region src/explain.ts
+const ROUTE_EXTENSIONS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js",
+	"vue",
+	"mdx",
+	"md"
+];
+const MIDDLEWARE_EXTENSIONS = [
+	"ts",
+	"tsx",
+	"js",
+	"jsx",
+	"mjs",
+	"cjs"
+];
+const SOCIAL_IMAGE_EXTENSIONS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js",
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"webp"
+];
+async function explainFarmRoute(pathname, options = {}) {
+	const root = path.resolve(options.root || process.cwd());
+	const userConfig = await loadConfig(root, options.configPath, "production");
+	const config = await resolveConfig({
+		root,
+		...userConfig
+	}, "production");
+	const normalizedPathname = normalizePathname(pathname, config.basePath || "/");
+	const page = discoverMatchingPages(config, normalizedPathname).sort((left, right) => right.score - left.score || right.priority - left.priority)[0];
+	if (!page) throw new Error(`No Farm page route matches ${normalizedPathname}.`);
+	const layouts = collectInheritedRouteFiles(config, normalizedPathname, "layout", ROUTE_EXTENSIONS);
+	const middleware = collectMiddleware(root, Boolean(userConfig?.middleware && Object.keys(userConfig.middleware).length), config, normalizedPathname);
+	const pageSource = readFileSync(page.filePath, "utf8");
+	const layoutSources = layouts.map((filePath) => ({
+		filePath,
+		source: readFileSync(filePath, "utf8")
+	}));
+	const runtime = resolveFarmRouteRuntimeConfig(mergeFarmRouteRuntimeConfigs(resolveFarmRouteRuleRuntimeConfig(normalizedPathname, config.routeRules), ...layoutSources.map(({ source }) => readRuntimeExports(source)), readRuntimeExports(pageSource)), `Route ${page.pattern}`);
+	const matchingRules = Object.entries(config.routeRules).filter(([pattern]) => farmRouteRuleMatches(pattern, normalizedPathname)).sort(([left], [right]) => routeSpecificity(left) - routeSpecificity(right));
+	const rendering = resolveRendering(pageSource, matchingRules);
+	const cache = resolveCaching(pageSource, matchingRules);
+	const metadataSources = [...layoutSources, {
+		filePath: page.filePath,
+		source: pageSource
+	}];
+	const openGraphImage = findNearestSocialImage(config, normalizedPathname, "opengraph-image");
+	const twitterImage = findNearestSocialImage(config, normalizedPathname, "twitter-image");
+	const preset = String(config.deploy.preset || config.preset || "node-server");
+	const presetRuntime = getFarmPresetRuntime(preset);
+	const compatible = rendering.mode === "static" || rendering.mode === "client" || runtime.runtime === "auto" || presetRuntime !== "unknown" && runtime.runtime === presetRuntime;
+	const warnings = [];
+	if (presetRuntime === "unknown" && runtime.runtime !== "auto") warnings.push(`Farm cannot verify the ${runtime.runtime} route requirement because the ${preset} preset runtime is unknown.`);
+	else if (!compatible) warnings.push(`The route requires ${runtime.runtime}, but the ${preset} preset emits ${presetRuntime} functions.`);
+	if (runtime.regions?.length && preset !== "vercel" && preset !== "vercel-edge") warnings.push(`${preset} does not map Farm per-route region hints.`);
+	if (runtime.maxDuration && preset !== "vercel") warnings.push(`${preset} does not map Farm per-route maxDuration.`);
+	return {
+		pathname: normalizedPathname,
+		pattern: page.pattern,
+		params: page.params,
+		filePath: toProjectPath(root, page.filePath),
+		source: page.source,
+		layouts: layouts.map((filePath) => toProjectPath(root, filePath)),
+		middleware,
+		runtime,
+		rendering,
+		cache,
+		metadata: {
+			static: metadataSources.filter(({ source }) => /export\s+const\s+metadata\b/.test(source)).map(({ filePath }) => toProjectPath(root, filePath)),
+			dynamic: metadataSources.filter(({ source }) => /export\s+(?:async\s+)?function\s+generateMetadata\b|export\s+const\s+generateMetadata\b/.test(source)).map(({ filePath }) => toProjectPath(root, filePath)),
+			...openGraphImage ? { openGraphImage: toProjectPath(root, openGraphImage) } : {},
+			...twitterImage ? { twitterImage: toProjectPath(root, twitterImage) } : {}
+		},
+		deployment: {
+			target: String(config.deploy.target || "node"),
+			preset,
+			runtime: presetRuntime,
+			compatible,
+			warnings
+		}
+	};
+}
+function formatFarmRouteExplanation(explanation, options = {}) {
+	const color = options.color === void 0 ? pc : pc.createColors(options.color);
+	const lines = [
+		color.bold("FARM / EXPLAIN"),
+		"",
+		`${color.bold("Path")}       ${explanation.pathname}`,
+		`${color.bold("Pattern")}    ${explanation.pattern}`,
+		`${color.bold("File")}       ${explanation.filePath}`,
+		`${color.bold("Source")}     ${explanation.source}`,
+		`${color.bold("Params")}     ${formatParams(explanation.params)}`,
+		`${color.bold("Layouts")}    ${explanation.layouts.length ? explanation.layouts.join(" -> ") : "none"}`,
+		`${color.bold("Middleware")} ${explanation.middleware.length ? explanation.middleware.map((entry) => entry.filePath).join(", ") : "none"}`,
+		`${color.bold("Runtime")}    ${formatRuntime(explanation.runtime)}`,
+		`${color.bold("Rendering")}  ${explanation.rendering.mode} (${explanation.rendering.reason})${explanation.rendering.ppr ? ", PPR" : ""}`,
+		`${color.bold("Caching")}    ${formatCaching(explanation.cache)}`,
+		`${color.bold("Metadata")}   ${formatMetadata(explanation.metadata)}`,
+		`${color.bold("Deployment")} ${explanation.deployment.target} / ${explanation.deployment.preset} — ${explanation.deployment.compatible ? color.green("compatible") : color.red("incompatible")}`
+	];
+	for (const warning of explanation.deployment.warnings) lines.push(`  ${color.yellow("!")} ${warning}`);
+	return lines.join("\n");
+}
+function discoverMatchingPages(config, pathname) {
+	const candidates = [];
+	for (const [priority, source] of getFarmSourceRoots(config).entries()) {
+		const appDirectory = path.join(source.root, source.srcDir, "app");
+		if (existsSync(appDirectory)) for (const filePath of walkFiles(appDirectory)) {
+			if (!/^page\.(?:tsx?|jsx?|vue|svelte|mdx?)$/.test(path.basename(filePath))) continue;
+			const relativeDirectory = path.relative(appDirectory, path.dirname(filePath));
+			if (relativeDirectory.split(path.sep).includes("api") || isRouteSlotDirectory(relativeDirectory)) continue;
+			const pattern = directoryToRoutePattern(relativeDirectory);
+			const match = matchRoutePattern(pattern, pathname);
+			if (!match) continue;
+			candidates.push({
+				filePath,
+				pattern,
+				params: match.params,
+				score: match.score,
+				source: source.name,
+				priority
+			});
+		}
+		const sourceDirectory = path.join(source.root, source.srcDir);
+		if (!existsSync(sourceDirectory)) continue;
+		for (const filePath of walkFiles(sourceDirectory)) {
+			if (!/\.(?:tsx?|jsx?)$/.test(filePath) || filePath.endsWith(".d.ts")) continue;
+			const moduleSource = readFileSync(filePath, "utf8");
+			for (const pattern of scanProgrammaticPagePaths(moduleSource)) {
+				const match = matchRoutePattern(pattern, pathname);
+				if (!match) continue;
+				candidates.push({
+					filePath,
+					pattern,
+					params: match.params,
+					score: match.score,
+					source: source.name,
+					priority
+				});
+			}
+		}
+	}
+	return candidates;
+}
+function isRouteSlotDirectory(relativeDirectory) {
+	return relativeDirectory.split(path.sep).some((segment) => /^@[A-Za-z][\w-]*$/.test(segment));
+}
+function walkFiles(directory) {
+	const files = [];
+	const pending = [directory];
+	while (pending.length) {
+		const current = pending.pop();
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const entryPath = path.join(current, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+				pending.push(entryPath);
+				continue;
+			}
+			files.push(entryPath);
+		}
+	}
+	return files;
+}
+function directoryToRoutePattern(relativeDirectory) {
+	const segments = relativeDirectory.split(path.sep).filter(Boolean).filter((segment) => !/^\(.+\)$/.test(segment) && !segment.startsWith("@")).map((segment) => segment.replace(/^\(\.{1,3}\)/, ""));
+	return segments.length ? `/${segments.join("/")}` : "/";
+}
+function matchRoutePattern(pattern, pathname) {
+	const patternSegments = splitPath(pattern);
+	const pathSegments = splitPath(pathname);
+	const params = {};
+	let score = 0;
+	let pathIndex = 0;
+	for (const segment of patternSegments) {
+		const optionalCatchAll = segment.match(/^\[\[\.\.\.(.+)\]\]$/);
+		if (optionalCatchAll) {
+			params[optionalCatchAll[1]] = pathSegments.slice(pathIndex);
+			pathIndex = pathSegments.length;
+			score += 1;
+			continue;
+		}
+		const catchAll = segment.match(/^\[\.\.\.(.+)\]$/);
+		if (catchAll) {
+			if (pathIndex >= pathSegments.length) return null;
+			params[catchAll[1]] = pathSegments.slice(pathIndex);
+			pathIndex = pathSegments.length;
+			score += 10;
+			continue;
+		}
+		const dynamic = segment.match(/^\[(.+)\]$/);
+		if (dynamic) {
+			if (pathIndex >= pathSegments.length) return null;
+			params[dynamic[1]] = pathSegments[pathIndex++];
+			score += 50;
+			continue;
+		}
+		if (segment !== pathSegments[pathIndex++]) return null;
+		score += 100;
+	}
+	return pathIndex === pathSegments.length ? {
+		params,
+		score
+	} : null;
+}
+function collectInheritedRouteFiles(config, pathname, baseName, extensions) {
+	return collectLayeredRouteFiles(config, baseName, extensions).filter((entry) => matchesRoutePrefix(entry.pattern, pathname)).sort(compareInheritedRouteFiles).map((entry) => entry.filePath);
+}
+function collectMiddleware(root, hasConfigMiddleware, config, pathname) {
+	const rootMiddleware = /* @__PURE__ */ new Map();
+	for (const source of getFarmSourceRoots(config)) {
+		const filePath = findFile(path.join(source.root, source.srcDir), "middleware", MIDDLEWARE_EXTENSIONS);
+		if (filePath) rootMiddleware.set("root", {
+			filePath,
+			pattern: "/"
+		});
+	}
+	const files = [...rootMiddleware.values(), ...collectLayeredRouteFiles(config, "middleware", MIDDLEWARE_EXTENSIONS).filter((entry) => matchesRoutePrefix(entry.pattern, pathname))].sort(compareInheritedRouteFiles).map((entry) => entry.filePath);
+	return [...hasConfigMiddleware ? [{
+		source: "config",
+		filePath: "farm.config (middleware)"
+	}] : [], ...files.map((filePath) => ({
+		source: "file",
+		filePath: toProjectPath(root, filePath)
+	}))];
+}
+function collectLayeredRouteFiles(config, baseName, extensions) {
+	const files = /* @__PURE__ */ new Map();
+	const filePattern = new RegExp(`^${escapeRegExp(baseName)}\\.(?:${extensions.map(escapeRegExp).join("|")})$`);
+	for (const source of getFarmSourceRoots(config)) {
+		const appDirectory = path.join(source.root, source.srcDir, "app");
+		if (!existsSync(appDirectory)) continue;
+		for (const filePath of walkFiles(appDirectory)) {
+			if (!filePattern.test(path.basename(filePath))) continue;
+			const pattern = directoryToRoutePattern(path.relative(appDirectory, path.dirname(filePath)));
+			files.set(pattern, {
+				filePath,
+				pattern
+			});
+		}
+	}
+	return [...files.values()];
+}
+function findNearestSocialImage(config, pathname, baseName) {
+	return collectLayeredRouteFiles(config, baseName, SOCIAL_IMAGE_EXTENSIONS).filter((entry) => matchesRoutePrefix(entry.pattern, pathname)).sort((left, right) => compareInheritedRouteFiles(right, left))[0]?.filePath;
+}
+function compareInheritedRouteFiles(left, right) {
+	return splitPath(left.pattern).length - splitPath(right.pattern).length;
+}
+function matchesRoutePrefix(pattern, pathname) {
+	const patternSegments = splitPath(pattern);
+	const pathSegments = splitPath(pathname);
+	if (patternSegments.length > pathSegments.length) return false;
+	return patternSegments.every((segment, index) => {
+		if (/^\[{1,2}(?:\.\.\.)?.+\]{1,2}$/.test(segment)) return true;
+		return segment === pathSegments[index];
+	});
+}
+function findFile(directory, baseName, extensions) {
+	return extensions.map((extension) => path.join(directory, `${baseName}.${extension}`)).find(existsSync);
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function readRuntimeExports(source) {
+	const runtime = readStringExport(source, "runtime");
+	const maxDuration = readNumberOrAutoExport(source, "maxDuration");
+	const regions = readStringArrayOrAutoExport(source, "regions");
+	return {
+		...runtime === "auto" || runtime === "node" || runtime === "edge" ? { runtime } : {},
+		...regions ? { regions } : {},
+		...maxDuration !== void 0 ? { maxDuration } : {}
+	};
+}
+function resolveRendering(pageSource, matchingRules) {
+	const pageRendering = resolveRouteRenderingConfig({
+		...readBooleanExport(pageSource, "ssg") !== void 0 ? { ssg: readBooleanExport(pageSource, "ssg") } : {},
+		...readBooleanExport(pageSource, "ppr") !== void 0 ? { ppr: readBooleanExport(pageSource, "ppr") } : {},
+		...readBooleanExport(pageSource, "experimental_ppr") !== void 0 ? { experimental_ppr: readBooleanExport(pageSource, "experimental_ppr") } : {},
+		...readNumberOrFalseExport(pageSource, "revalidate") !== void 0 ? { revalidate: readNumberOrFalseExport(pageSource, "revalidate") } : {},
+		...readDynamicExport(pageSource) ? { dynamic: readDynamicExport(pageSource) } : {}
+	}, pageSource);
+	let mode = pageRendering.ssg ? "static" : pageRendering.ppr ? "partial" : "dynamic";
+	let reason = pageRendering.directive ? `page directive ${JSON.stringify(pageRendering.directive)}` : pageRendering.ssg ? "page static rendering declaration" : pageRendering.ppr ? "page PPR declaration" : "default server rendering";
+	let ppr = pageRendering.ppr;
+	for (const [pattern, rule] of matchingRules) if (rule.prerender === true || rule.render === "static") {
+		mode = "static";
+		reason = `routeRules ${pattern}`;
+		ppr = false;
+	} else if (rule.prerender === false || rule.render === "dynamic" || rule.ssr === true) {
+		mode = "dynamic";
+		reason = `routeRules ${pattern}`;
+		ppr = false;
+	} else if (rule.ssr === false) {
+		mode = "client";
+		reason = `routeRules ${pattern}`;
+		ppr = false;
+	}
+	return {
+		mode,
+		reason,
+		ppr
+	};
+}
+function resolveCaching(pageSource, matchingRules) {
+	let swr;
+	let isr;
+	for (const [, rule] of matchingRules) {
+		if (typeof rule.swr === "number" || typeof rule.swr === "boolean") swr = rule.swr;
+		if (typeof rule.isr === "number" || typeof rule.isr === "boolean") isr = rule.isr;
+	}
+	return {
+		...readNumberOrFalseExport(pageSource, "revalidate") !== void 0 ? { revalidate: readNumberOrFalseExport(pageSource, "revalidate") } : {},
+		...swr !== void 0 ? { swr } : {},
+		...isr !== void 0 ? { isr } : {},
+		rules: matchingRules.map(([pattern]) => pattern)
+	};
+}
+function readStringExport(source, name) {
+	return source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*["']([^"']+)["']`))?.[1];
+}
+function readDynamicExport(source) {
+	const dynamic = readStringExport(source, "dynamic");
+	return dynamic === "auto" || dynamic === "force-dynamic" || dynamic === "error" || dynamic === "force-static" ? dynamic : void 0;
+}
+function readBooleanExport(source, name) {
+	const value = source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(true|false)`))?.[1];
+	return value === void 0 ? void 0 : value === "true";
+}
+function readNumberOrAutoExport(source, name) {
+	const value = source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(?:["'](auto)["']|(\\d+))`));
+	return value?.[1] === "auto" ? "auto" : value?.[2] ? Number(value[2]) : void 0;
+}
+function readNumberOrFalseExport(source, name) {
+	const value = source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(false|\\d+)`))?.[1];
+	return value === "false" ? false : value ? Number(value) : void 0;
+}
+function readStringArrayOrAutoExport(source, name) {
+	if (source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*["']auto["']`))) return "auto";
+	const array = source.match(new RegExp(`export\\s+const\\s+${name}\\s*=\\s*\\[([^\\]]*)\\]`))?.[1];
+	if (array === void 0) return void 0;
+	return [...array.matchAll(/["']([^"']+)["']/g)].map((match) => match[1]);
+}
+function routeSpecificity(pattern) {
+	return splitPath(pattern).reduce((score, segment) => {
+		if (segment === "**" || segment.startsWith("[[...")) return score + 1;
+		if (segment === "*" || segment.startsWith("[...")) return score + 10;
+		if (segment.startsWith("[") || segment.startsWith(":")) return score + 50;
+		return score + 100;
+	}, 0);
+}
+function normalizePathname(value, basePath) {
+	let pathname;
+	try {
+		pathname = new URL(value, "http://farm.local").pathname;
+	} catch {
+		pathname = value;
+	}
+	pathname = pathname.startsWith("/") ? pathname : `/${pathname}`;
+	const normalizedBase = basePath && basePath !== "/" ? `/${basePath.replace(/^\/+|\/+$/g, "")}` : "";
+	if (normalizedBase && (pathname === normalizedBase || pathname.startsWith(`${normalizedBase}/`))) pathname = pathname.slice(normalizedBase.length) || "/";
+	return pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+}
+function splitPath(value) {
+	return value.split("/").filter(Boolean).map(decodeURIComponent);
+}
+function toProjectPath(root, filePath) {
+	let relativePath = path.relative(root, filePath);
+	if ((relativePath === ".." || relativePath.startsWith(`..${path.sep}`)) && existsSync(root) && existsSync(filePath)) relativePath = path.relative(realpathSync(root), realpathSync(filePath));
+	return relativePath.split(path.sep).join("/");
+}
+function formatParams(params) {
+	const entries = Object.entries(params);
+	return entries.length ? entries.map(([key, value]) => `${key}=${Array.isArray(value) ? value.join("/") : value}`).join(", ") : "none";
+}
+function formatRuntime(runtime) {
+	return [
+		runtime.runtime,
+		runtime.regions?.length ? `regions=${runtime.regions.join(",")}` : "",
+		runtime.maxDuration ? `maxDuration=${runtime.maxDuration}s` : ""
+	].filter(Boolean).join(", ");
+}
+function formatCaching(cache) {
+	const values = [
+		cache.revalidate !== void 0 ? `revalidate=${cache.revalidate}` : "",
+		cache.swr !== void 0 ? `swr=${cache.swr}` : "",
+		cache.isr !== void 0 ? `isr=${cache.isr}` : "",
+		cache.rules.length ? `rules=${cache.rules.join(",")}` : ""
+	].filter(Boolean);
+	return values.length ? values.join("; ") : "request-time / no declared cache";
+}
+function formatMetadata(metadata) {
+	const values = [
+		metadata.static.length ? `static=${metadata.static.join(",")}` : "",
+		metadata.dynamic.length ? `dynamic=${metadata.dynamic.join(",")}` : "",
+		metadata.openGraphImage ? `og=${metadata.openGraphImage}` : "",
+		metadata.twitterImage ? `twitter=${metadata.twitterImage}` : ""
+	].filter(Boolean);
+	return values.length ? values.join("; ") : "none";
+}
+//#endregion
 //#region src/cron.ts
 async function loadFarmCronConfig(options = {}) {
 	const root = path.resolve(options.root || process.cwd());
@@ -2016,7 +2764,7 @@ function resolveMigrationCommand(root, entry, index) {
 }
 function runMigrationCommand(command) {
 	return new Promise((resolve, reject) => {
-		const child = spawn(command.command, {
+		const child = spawn$1(command.command, {
 			cwd: command.cwd,
 			env: {
 				...process.env,
@@ -2420,6 +3168,31 @@ function toPosix(value) {
 	return value.split(path.sep).join("/");
 }
 //#endregion
+//#region src/auth.ts
+async function migrateFarmAuth(options = {}) {
+	const root = path.resolve(options.root || process.cwd());
+	const userConfig = await loadConfig(root, options.configPath, "production");
+	if (!userConfig) throw new Error(`No farm.config file was found in ${root}.`);
+	if (!(await resolveConfig({
+		...userConfig,
+		root
+	}, "production")).auth.enabled) throw new Error("Farm Auth is disabled. Add `auth: true` to farm.config.ts first.");
+	const resolveFromApp = createRequire(path.join(root, "package.json"));
+	let modulePath;
+	try {
+		modulePath = resolveFromApp.resolve("@farm.js/auth/internal");
+	} catch {
+		throw new Error("Install @farm.js/auth before running `farm auth migrate`.");
+	}
+	const runtime = await import(
+		/* @vite-ignore */
+		pathToFileURL(modulePath).href
+);
+	logger.info("Applying the Farm Auth database schema...");
+	await runtime.migrateFarmAuth();
+	logger.success("Farm Auth database is ready.");
+}
+//#endregion
 //#region src/upgrade.ts
 const DEPENDENCY_SECTIONS = [
 	"dependencies",
@@ -2560,11 +3333,13 @@ function getDependencySectionFlags(packageManager, section) {
 }
 function runFarmUpgradeCommand(command) {
 	return new Promise((resolve, reject) => {
-		const executable = process.platform === "win32" ? `${command.command}.cmd` : command.command;
-		const child = spawn(executable, command.args, {
+		const isWindows = process.platform === "win32";
+		const executable = isWindows ? `${command.command}.cmd` : command.command;
+		const child = spawn$1(executable, command.args, {
 			cwd: command.cwd,
 			env: process.env,
-			stdio: "inherit"
+			stdio: "inherit",
+			shell: isWindows
 		});
 		child.on("error", reject);
 		child.on("close", (code, signal) => {
@@ -2590,6 +3365,6 @@ function formatError(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
-export { addFarmIntegration, buildFarm, createFarmUpgradePlan, createFrameworkMigrationPlan, createGatewaySession, createPreviewGatewayPlan, createPreviewTunnelPlan, createServer, deployFarm, detectFarmPackageManager, formatFarmCronJobs, formatFarmDoctorReport, formatFarmUpgradePlan, forwardGatewayRequest, generateFarmArtifacts, inspectFrameworkMigrations, listFarmCronJobs, listFarmIntegrationProviders, loadFarmCronConfig, migrateFarm, parsePreviewPublicUrl, previewFarm, resolveCloudflareAgentDeployPlan, resolvePreviewTarget, runFarmCronJob, runFarmDoctor, runPreviewGateway, startDevServer, startFarmCronScheduler, upgradeFarm };
+export { FarmDeployError, FarmGeneratedArtifactsStaleError, FarmStartError, addFarmIntegration, buildFarm, createFarmDeployPlan, createFarmStartPlan, createFarmUpgradePlan, createFrameworkMigrationPlan, createGatewaySession, createPreviewGatewayPlan, createPreviewTunnelPlan, createServer, deployFarm, detectFarmPackageManager, escapeDoubleQuoted, escapeSqlString, explainFarmRoute, flushFarmTelemetry, formatFarmCronJobs, formatFarmDeployPlan, formatFarmDoctorReport, formatFarmRouteExplanation, formatFarmUpgradePlan, forwardGatewayRequest, generateFarmArtifacts, getFarmTelemetryConfigFile, getFarmTelemetryStatus, inspectFrameworkMigrations, listFarmCronJobs, listFarmIntegrationProviders, loadFarmCronConfig, migrateFarm, migrateFarmAuth, parsePreviewPublicUrl, previewFarm, resolveCloudflareAgentDeployPlan, resolveFarmCreateAppTelemetryCommand, resolveFarmTelemetryCommand, resolvePreviewTarget, runFarmCronJob, runFarmDoctor, runNativePreviewTunnel, runPreviewGateway, setFarmTelemetryEnabled, showFarmTelemetryNotice, startDevServer, startFarm, startFarmCronScheduler, trackFarmCommand, trackFarmCreateAppCommand, trackFarmProjectCreated, upgradeFarm };
 
 //# sourceMappingURL=index.mjs.map