@farm.js/cli 0.1.0-beta.14 → 0.1.0-beta.16

package/dist/index.js

@@ -23,32 +23,97 @@ let node_url = require("node:url");
 * Deploy Farm.js application
 */
 async function deployFarm(options = {}) {
-	const root = options.root || process.cwd();
+	const { plan, deployConfig } = await resolveFarmDeployContext(options);
+	if (options.plan) {
+		_farm_js_core.logger.info(formatFarmDeployPlan(plan));
+		return plan;
+	}
+	_farm_js_core.logger.info(`🚀 Building with ${plan.preset} preset...`);
+	await require_build.buildFarm({
+		root: plan.root,
+		preset: plan.preset
+	});
+	if (!(0, fs.existsSync)(plan.outputDir)) throw new Error(`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.default.resolve(options.root || process.cwd());
 	const mode = "production";
 	const userConfig = await (0, _farm_js_core.loadConfig)(root, void 0, mode);
-	const config = userConfig ? await (0, _farm_js_core.resolveConfig)(userConfig, mode) : void 0;
+	const config = await (0, _farm_js_core.resolveConfig)({
+		root,
+		...userConfig
+	}, mode);
 	const cliTarget = options.vercel ? "vercel" : options.cloudflare ? "cloudflare" : options.netlify ? "netlify" : void 0;
-	const platform = (0, _farm_js_core.normalizeDeployTarget)(cliTarget || config?.deploy.target);
-	if (platform !== "vercel" && platform !== "cloudflare" && platform !== "netlify") {
-		_farm_js_core.logger.error("Please specify a deployment target with --vercel, --cloudflare, --netlify, or farm.config deploy.target.");
-		process.exit(1);
-	}
+	const platform = (0, _farm_js_core.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 deployConfig = (0, _farm_js_core.resolveDeployConfig)(userConfig || {}, {
 		target: platform,
 		preset: cliTarget ? userConfig?.deploy?.preset || userConfig?.preset || (0, _farm_js_core.getPresetForDeployTarget)(platform) : void 0
 	});
 	const preset = deployConfig.preset || (0, _farm_js_core.getPresetForDeployTarget)(platform) || "node-server";
-	_farm_js_core.logger.info(`🚀 Building with ${preset} preset...`);
-	await require_build.buildFarm({
-		root,
-		preset
-	});
 	const nitroOutput = (0, _farm_js_core.resolveDeployOutputPath)(root, deployConfig.outputDir);
-	if (!(0, fs.existsSync)(nitroOutput)) {
-		_farm_js_core.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.default.resolve(root),
+			target: platform,
+			preset,
+			runtime: (0, _farm_js_core.getFarmPresetRuntime)(preset),
+			outputDir: nitroOutput,
+			production: platform === "netlify" || Boolean(options.prod),
+			build: {
+				command: `farm build --preset ${preset}`,
+				cwd: path.default.resolve(root)
+			},
+			deploy,
+			...cloudflareAgent ? { cloudflareAgent } : {}
+		},
+		deployConfig
+	};
+}
+function createDeployCommand(platform, root, outputDir, deployConfig, prod, cloudflareAgent) {
+	if (platform === "vercel") return {
+		command: `vercel deploy --prebuilt --yes${prod ? " --prod" : ""}`,
+		cwd: path.default.resolve(root)
+	};
+	if (platform === "netlify") {
+		const site = deployConfig.netlify?.site;
+		return {
+			command: `netlify deploy --prod --dir=.${site ? ` --site=${site}` : ""}`,
+			cwd: outputDir
+		};
 	}
-	await deployPlatform(platform, root, nitroOutput, deployConfig, options.prod);
+	if (cloudflareAgent) return {
+		command: `wrangler deploy --config ${cloudflareAgent.configPath}${cloudflareAgent.environment ? ` --env ${cloudflareAgent.environment}` : ""}`,
+		cwd: path.default.resolve(root)
+	};
+	return {
+		command: `wrangler pages deploy . --project-name=${deployConfig.cloudflare?.projectName || deployConfig.projectName || "farm-app"}`,
+		cwd: outputDir
+	};
 }
 /**
 * Deploy using platform's native CLI (user credentials)
@@ -253,6 +318,26 @@ 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.default.resolve(root);
+	const sourceConfigPath = path.default.resolve(projectRoot, configuredPath);
+	assertPathInsideProject(projectRoot, sourceConfigPath, "Cloudflare Agents source config");
+	const configPath = path.default.join(path.default.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.default.relative(projectRoot, candidate);
+	if (relativePath === ".." || relativePath.startsWith(`..${path.default.sep}`) || path.default.isAbsolute(relativePath)) throw new Error(`${label} must stay inside the Farm project root.`);
+}
 function assertWranglerInstalled(root) {
 	try {
 		(0, child_process.execFileSync)("wrangler", ["--version"], {
@@ -801,10 +886,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) => node_path.default.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 = node_path.default.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 (0, _farm_js_core.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 (0, _farm_js_core.resolveConfig)({
@@ -819,14 +914,20 @@ async function generateFarmArtifacts(options = {}) {
 		layers: resolvedConfig.layers,
 		extraRoutes,
 		suppressLintOnLink: resolvedConfig.suppressLintOnLink,
-		i18nConfig: resolvedConfig.i18n
+		i18nConfig: resolvedConfig.i18n,
+		check: options.check
 	});
+	if (options.check) {
+		if (typeArtifacts.stalePaths.length) throw new FarmGeneratedArtifactsStaleError(root, typeArtifacts.stalePaths);
+		_farm_js_core.logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types are up to date.`);
+		return typeArtifacts;
+	}
 	_farm_js_core.logger.success(`Generated route, API, env${resolvedConfig.i18n.enabled ? ", and i18n" : ""} types (${typeArtifacts.apiRoutes.length} API route${typeArtifacts.apiRoutes.length === 1 ? "" : "s"}).`);
 	const schemas = (0, _farm_js_core.getIntegrationSchemas)(resolvedConfig.integrations);
 	const schemaEntries = Object.entries(schemas);
 	if (!schemaEntries.length) {
 		if (hasSchemaOptions(options)) _farm_js_core.logger.warn("No integration schemas were found in the current Farm config.");
-		return;
+		return typeArtifacts;
 	}
 	const packageManifest = await readPackageManifest(root);
 	const schemaOptionsExplicit = hasSchemaOptions(options);
@@ -836,12 +937,12 @@ async function generateFarmArtifacts(options = {}) {
 	} catch (error) {
 		if (schemaOptionsExplicit) throw error;
 		_farm_js_core.logger.warn(`Integration schemas were found, but Farm could not choose a schema target automatically: ${error.message}`);
-		return;
+		return typeArtifacts;
 	}
 	if (!orm) {
 		if (!schemaOptionsExplicit) {
 			_farm_js_core.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.");
 	}
@@ -852,7 +953,7 @@ async function generateFarmArtifacts(options = {}) {
 			if (!(0, node_fs.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);
 			_farm_js_core.logger.success(`Generated Prisma integration schema in ${node_path.default.relative(root, schemaPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "drizzle": {
 			const dialect = options.dialect ?? await detectDrizzleDialect(root, packageManifest) ?? void 0;
@@ -860,7 +961,7 @@ async function generateFarmArtifacts(options = {}) {
 			const outputPath = options.output ? node_path.default.resolve(root, options.output) : node_path.default.join(root, "farm-integrations.generated.ts");
 			await writeGeneratedFile(outputPath, generateDrizzleSchema(collectedModels, dialect));
 			_farm_js_core.logger.success(`Generated Drizzle integration schema in ${node_path.default.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "postgres":
 		case "mysql":
@@ -868,13 +969,13 @@ async function generateFarmArtifacts(options = {}) {
 			const outputPath = options.output ? node_path.default.resolve(root, options.output) : node_path.default.join(root, `farm-integrations.generated.${orm}.sql`);
 			await writeGeneratedFile(outputPath, generateSqlSchema(collectedModels, orm));
 			_farm_js_core.logger.success(`Generated ${orm} integration schema in ${node_path.default.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 		case "mongodb": {
 			const outputPath = options.output ? node_path.default.resolve(root, options.output) : node_path.default.join(root, "farm-integrations.generated.mongodb.ts");
 			await writeGeneratedFile(outputPath, generateMongoBootstrap(collectedModels));
 			_farm_js_core.logger.success(`Generated MongoDB integration bootstrap in ${node_path.default.relative(root, outputPath)}.`);
-			return;
+			return typeArtifacts;
 		}
 	}
 }
@@ -1059,7 +1160,7 @@ function cloneSchemaModel(model) {
 async function writePrismaSchema(schemaPath, models) {
 	const source = await (0, node_fs_promises.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 (0, node_fs_promises.writeFile)(schemaPath, nextSource, "utf8");
 }
@@ -1387,12 +1488,12 @@ function toCamelCase(value) {
 function escapeString(value) {
 	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/'/g, "''");
 }
-function escapeRegExp(value) {
+function escapeRegExp$1(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 //#endregion
 //#region src/doctor.ts
-const ROUTE_EXTENSIONS = [
+const ROUTE_EXTENSIONS$1 = [
 	"ts",
 	"tsx",
 	"js",
@@ -1414,7 +1515,7 @@ async function runFarmDoctor(options = {}) {
 	const root = node_path.default.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);
@@ -1461,6 +1562,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");
@@ -1560,9 +1668,10 @@ async function createProjectReport(root, options) {
 			action: "Add farm.config.ts and export defineConfig({...})."
 		});
 		else {
+			const configRoot = node_path.default.resolve(root, userConfig.root || ".");
 			config = await (0, _farm_js_core.resolveConfig)({
-				root,
-				...userConfig
+				...userConfig,
+				root: configRoot
 			}, "development");
 			const configFile = findConfigFile(root, options.configPath);
 			checks.push({
@@ -1586,9 +1695,40 @@ 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 layoutPath = node_path.default.join(config.root, config.srcDir, "app", "layout.tsx");
+		if (!(0, node_fs.existsSync)(layoutPath)) {
+			(0, node_fs.mkdirSync)(node_path.default.dirname(layoutPath), { recursive: true });
+			(0, node_fs.writeFileSync)(layoutPath, `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: node_path.default.relative(root, layoutPath)
+			});
+		}
+	}
+	return fixes;
+}
 function collectNodeCheck(checks) {
 	const major = Number(process.versions.node.split(".")[0]);
 	checks.push(major >= 18 ? {
@@ -1649,7 +1789,7 @@ function collectRouterChecks(config, checks) {
 	const sources = (0, _farm_js_core.getFarmSourceRoots)(config);
 	const appDirectories = sources.map((source) => node_path.default.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) => (0, node_fs.existsSync)(node_path.default.join(source.root, source.srcDir, `farm.routes.${extension}`))));
+	const hasProgrammaticRoutes = sources.some((source) => ROUTE_EXTENSIONS$1.some((extension) => (0, node_fs.existsSync)(node_path.default.join(source.root, source.srcDir, `farm.routes.${extension}`))));
 	checks.push(hasPages || hasProgrammaticRoutes ? {
 		status: "pass",
 		code: "APP_ROUTER_READY",
@@ -1662,7 +1802,7 @@ 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) => (0, node_fs.existsSync)(node_path.default.join(directory, `layout.${extension}`))));
+	const hasRootLayout = appDirectories.some((directory) => ROUTE_EXTENSIONS$1.some((extension) => (0, node_fs.existsSync)(node_path.default.join(directory, `layout.${extension}`))));
 	checks.push(hasRootLayout ? {
 		status: "pass",
 		code: "ROOT_LAYOUT_READY",
@@ -1732,7 +1872,7 @@ function hasCronRoute(config, job) {
 	const relative = job.path.replace(/^\/+/, "").replace(/^api\//, "");
 	return (0, _farm_js_core.getFarmSourceRoots)(config).some((source) => {
 		const directory = node_path.default.join(source.root, source.srcDir, "app", "api", relative);
-		return ROUTE_EXTENSIONS.some((extension) => (0, node_fs.existsSync)(node_path.default.join(directory, `route.${extension}`)));
+		return ROUTE_EXTENSIONS$1.some((extension) => (0, node_fs.existsSync)(node_path.default.join(directory, `route.${extension}`)));
 	});
 }
 function containsFile(directory, pattern) {
@@ -1800,6 +1940,415 @@ function formatCount$1(value, noun) {
 	return `${value} ${noun}${value === 1 ? "" : "s"}`;
 }
 //#endregion
+//#region src/explain.ts
+const ROUTE_EXTENSIONS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js",
+	"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 = node_path.default.resolve(options.root || process.cwd());
+	const userConfig = await (0, _farm_js_core.loadConfig)(root, options.configPath, "production");
+	const config = await (0, _farm_js_core.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 = (0, node_fs.readFileSync)(page.filePath, "utf8");
+	const layoutSources = layouts.map((filePath) => ({
+		filePath,
+		source: (0, node_fs.readFileSync)(filePath, "utf8")
+	}));
+	const runtime = (0, _farm_js_core.resolveFarmRouteRuntimeConfig)((0, _farm_js_core.mergeFarmRouteRuntimeConfigs)((0, _farm_js_core.resolveFarmRouteRuleRuntimeConfig)(normalizedPathname, config.routeRules), ...layoutSources.map(({ source }) => readRuntimeExports(source)), readRuntimeExports(pageSource)), `Route ${page.pattern}`);
+	const matchingRules = Object.entries(config.routeRules).filter(([pattern]) => (0, _farm_js_core.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 = (0, _farm_js_core.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 ? picocolors.default : picocolors.default.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 (0, _farm_js_core.getFarmSourceRoots)(config).entries()) {
+		const appDirectory = node_path.default.join(source.root, source.srcDir, "app");
+		if ((0, node_fs.existsSync)(appDirectory)) for (const filePath of walkFiles(appDirectory)) {
+			if (!/^page\.(?:tsx?|jsx?|mdx?)$/.test(node_path.default.basename(filePath))) continue;
+			const relativeDirectory = node_path.default.relative(appDirectory, node_path.default.dirname(filePath));
+			if (relativeDirectory.split(node_path.default.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 = node_path.default.join(source.root, source.srcDir);
+		if (!(0, node_fs.existsSync)(sourceDirectory)) continue;
+		for (const entry of (0, node_fs.readdirSync)(sourceDirectory, { withFileTypes: true })) {
+			if (!entry.isFile() || !(0, _farm_js_core.isProgrammaticRoutesFileName)(entry.name)) continue;
+			const filePath = node_path.default.join(sourceDirectory, entry.name);
+			const moduleSource = (0, node_fs.readFileSync)(filePath, "utf8");
+			for (const pattern of (0, _farm_js_core.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(node_path.default.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 (0, node_fs.readdirSync)(current, { withFileTypes: true })) {
+			const entryPath = node_path.default.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(node_path.default.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 (0, _farm_js_core.getFarmSourceRoots)(config)) {
+		const filePath = findFile(node_path.default.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 (0, _farm_js_core.getFarmSourceRoots)(config)) {
+		const appDirectory = node_path.default.join(source.root, source.srcDir, "app");
+		if (!(0, node_fs.existsSync)(appDirectory)) continue;
+		for (const filePath of walkFiles(appDirectory)) {
+			if (!filePattern.test(node_path.default.basename(filePath))) continue;
+			const pattern = directoryToRoutePattern(node_path.default.relative(appDirectory, node_path.default.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) => node_path.default.join(directory, `${baseName}.${extension}`)).find(node_fs.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 = (0, _farm_js_core.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 = node_path.default.relative(root, filePath);
+	if ((relativePath === ".." || relativePath.startsWith(`..${node_path.default.sep}`)) && (0, node_fs.existsSync)(root) && (0, node_fs.existsSync)(filePath)) relativePath = node_path.default.relative((0, node_fs.realpathSync)(root), (0, node_fs.realpathSync)(filePath));
+	return relativePath.split(node_path.default.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 = node_path.default.resolve(options.root || process.cwd());
@@ -2604,8 +3153,10 @@ function formatError(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
+exports.FarmGeneratedArtifactsStaleError = FarmGeneratedArtifactsStaleError;
 exports.addFarmIntegration = require_add_integration.addFarmIntegration;
 exports.buildFarm = require_build.buildFarm;
+exports.createFarmDeployPlan = createFarmDeployPlan;
 exports.createFarmUpgradePlan = createFarmUpgradePlan;
 exports.createFrameworkMigrationPlan = createFrameworkMigrationPlan;
 exports.createGatewaySession = createGatewaySession;
@@ -2619,8 +3170,11 @@ Object.defineProperty(exports, "createServer", {
 });
 exports.deployFarm = deployFarm;
 exports.detectFarmPackageManager = detectFarmPackageManager;
+exports.explainFarmRoute = explainFarmRoute;
 exports.formatFarmCronJobs = formatFarmCronJobs;
+exports.formatFarmDeployPlan = formatFarmDeployPlan;
 exports.formatFarmDoctorReport = formatFarmDoctorReport;
+exports.formatFarmRouteExplanation = formatFarmRouteExplanation;
 exports.formatFarmUpgradePlan = formatFarmUpgradePlan;
 exports.forwardGatewayRequest = forwardGatewayRequest;
 exports.generateFarmArtifacts = generateFarmArtifacts;