next-evolve 0.1.0 → 0.3.1

package/dist/cli/connect.js

@@ -0,0 +1,46 @@
+import { parseFlags } from "./args.js";
+import { getSiteInfo, putAppUrl, runCloudTest } from "./cloud.js";
+import { parseSecretKey } from "@next-evolve/protocol";
+// src/cli/connect.ts
+async function connectCommand(args, deps) {
+	const out = deps.out ?? ((s) => console.warn(s));
+	const err = deps.err ?? ((s) => console.error(s));
+	const p = parseFlags(args, {
+		test: { type: "boolean" },
+		"app-url": { type: "string" }
+	});
+	if (!p.ok) {
+		err(`next-evolve connect: ${p.error}`);
+		return 1;
+	}
+	const key = deps.env.EVOLVE_SECRET_KEY ?? "";
+	if (!parseSecretKey(key)) {
+		err("next-evolve connect: set EVOLVE_SECRET_KEY (evk_live_…)");
+		return 1;
+	}
+	const site = await getSiteInfo(deps, key);
+	if (!site.ok) {
+		err(`next-evolve connect: ${site.error}`);
+		return 1;
+	}
+	out(`✓ Connected to "${site.site.name}" (${site.site.id})`);
+	if (p.flags["app-url"]) {
+		const r = await putAppUrl(deps, key, p.flags["app-url"]);
+		if (!r.ok) {
+			err(`✗ App URL: ${r.error}`);
+			return 1;
+		}
+		out(`✓ App URL: ${r.appUrl}`);
+	} else if (site.site.appUrl) out(`  App URL: ${site.site.appUrl}`);
+	if (!p.flags.test) return 0;
+	const t = await runCloudTest(deps, key);
+	if (!t.ok) {
+		err(`✗ Connection test: ${t.error}`);
+		return 1;
+	}
+	const line = (name, c) => `${c.ok ? "✓" : "✗"} ${name}${c.detail ? ` (${c.detail})` : ""}`;
+	out(line("Sync webhook reaches the app", t.webhook));
+	out(line("Aggregate route answers (signed dry run)", t.aggregate));
+	return t.webhook.ok && t.aggregate.ok ? 0 : 1;
+}
+export { connectCommand };

package/dist/cli/detect.d.ts

@@ -0,0 +1,26 @@
+export type PackageManager = "pnpm" | "yarn" | "npm" | "bun";
+export type Problem = {
+  level: "error" | "warn";
+  message: string;
+};
+export type Detection = {
+  root: string;
+  /** Installed version, else the declared one (range stripped). */
+  nextVersion: string | null;
+  /** `app` or `src/app`. */
+  appDir: string | null;
+  srcDir: boolean;
+  typescript: boolean;
+  packageManager: PackageManager;
+  /** Existing proxy/middleware file, relative to root. */
+  proxyFile: string | null;
+  /** What Next calls it: `proxy.ts` from 16, `middleware.ts` (runtime nodejs) on 15.5. */
+  proxyKind: "proxy" | "middleware";
+  nextConfigFile: string | null;
+  outputExport: boolean;
+  cacheComponents: boolean;
+  hasEvolve: boolean;
+  hasZod: boolean;
+  problems: Problem[];
+};
+export declare function detectProject(root: string): Detection;

package/dist/cli/detect.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// src/cli/detect.ts
+const read = (p) => {
+	try {
+		return readFileSync(p, "utf8");
+	} catch {
+		return null;
+	}
+};
+function parseVersion(v) {
+	const m = /(\d+)\.(\d+)/.exec(v ?? "");
+	return m ? [Number(m[1]), Number(m[2])] : null;
+}
+function detectProject(root) {
+	const problems = [];
+	const pkgText = read(join(root, "package.json"));
+	let pkg = {};
+	try {
+		pkg = pkgText ? JSON.parse(pkgText) : {};
+	} catch {
+		problems.push({
+			level: "error",
+			message: "package.json isn't valid JSON"
+		});
+	}
+	const deps = {
+		...pkg.devDependencies,
+		...pkg.dependencies
+	};
+	const installed = read(join(root, "node_modules/next/package.json"));
+	let nextVersion = null;
+	try {
+		nextVersion = installed ? JSON.parse(installed).version : null;
+	} catch {}
+	if (!nextVersion && deps.next) {
+		const v = parseVersion(deps.next);
+		nextVersion = v ? `${v[0]}.${v[1]}.0` : deps.next;
+	}
+	const ver = parseVersion(nextVersion);
+	const appDir = existsSync(join(root, "src/app")) ? "src/app" : existsSync(join(root, "app")) ? "app" : null;
+	const srcDir = appDir === "src/app";
+	const packageManager = existsSync(join(root, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(root, "yarn.lock")) ? "yarn" : existsSync(join(root, "bun.lock")) || existsSync(join(root, "bun.lockb")) ? "bun" : "npm";
+	const base = srcDir ? "src/" : "";
+	const proxyFile = ["proxy", "middleware"].flatMap((n) => [
+		"ts",
+		"js",
+		"mjs",
+		"tsx"
+	].map((e) => `${base}${n}.${e}`)).find((f) => existsSync(join(root, f))) ?? null;
+	const nextConfigFile = [
+		"next.config.ts",
+		"next.config.mjs",
+		"next.config.js",
+		"next.config.cjs"
+	].find((f) => existsSync(join(root, f))) ?? null;
+	const nextConfig = nextConfigFile ? read(join(root, nextConfigFile)) ?? "" : "";
+	const outputExport = /output\s*:\s*["'`]export["'`]/.test(nextConfig);
+	const cacheComponents = /cacheComponents\s*:\s*true/.test(nextConfig);
+	if (!deps.next && !installed) problems.push({
+		level: "error",
+		message: "This isn't a Next.js app (no next in package.json)"
+	});
+	else if (!ver || ver[0] < 15 || ver[0] === 15 && ver[1] < 5) problems.push({
+		level: "error",
+		message: `Evolve needs Next.js 15.5 or newer (found ${nextVersion ?? "unknown"})`
+	});
+	if (deps.next && !appDir) problems.push({
+		level: "error",
+		message: "Evolve needs the App Router (no app/ directory)"
+	});
+	if (outputExport) problems.push({
+		level: "error",
+		message: "output: \"export\" builds a static site; Evolve needs a server (remove it)"
+	});
+	if (cacheComponents) problems.push({
+		level: "warn",
+		message: "cacheComponents is on: static-mode pages are untested with it; prefer dynamic mode"
+	});
+	return {
+		root,
+		nextVersion,
+		appDir,
+		srcDir,
+		typescript: existsSync(join(root, "tsconfig.json")),
+		packageManager,
+		proxyFile,
+		proxyKind: ver && ver[0] >= 16 ? "proxy" : "middleware",
+		nextConfigFile,
+		outputExport,
+		cacheComponents,
+		hasEvolve: Boolean(deps["next-evolve"]),
+		hasZod: Boolean(deps.zod),
+		problems
+	};
+}
+export { detectProject };

package/dist/cli/doctor.d.ts

@@ -0,0 +1,34 @@
+import { AppModules } from "./load-app.js";
+type Env = Record<string, string | undefined>;
+export type Check = {
+  name: string;
+  status: "ok" | "warn" | "fail";
+  detail?: string;
+};
+export type DoctorDeps = {
+  env: Env;
+  cwd?: string;
+  fetch?: typeof fetch;
+  out?: (s: string) => void;
+  err?: (s: string) => void;
+  /** Milliseconds (tests move the clock). */
+  now?: () => number;
+  /** The app's config (tests); default loads evolve.config. */
+  load?: () => Promise<AppModules>;
+  /** Reachable and migrated? Default connects with the app's DB URL. */
+  checkDb?: (url: string) => Promise<{
+    ok: true;
+    pending: string[];
+  } | {
+    ok: false;
+    error: string;
+  }>;
+  /** Override the app URL the cloud has (tests); default from GET /v1/site. */
+  appUrl?: string | null;
+};
+/** The string literals in `config.matcher`, or null when there's no matcher (= every path). */
+export declare function readMatcher(src: string): string[] | null;
+export declare const covers: (matchers: string[] | null, path: string) => boolean;
+export declare function runDoctor(deps: DoctorDeps): Promise<Check[]>;
+export declare function doctorCommand(args: string[], deps: DoctorDeps): Promise<number>;
+export {};

package/dist/cli/doctor.js

@@ -0,0 +1,230 @@
+import { normalizePath } from "../config/config.js";
+import { trustedKeys } from "../core/keys.js";
+import { createSql } from "../db/client.js";
+import { loadMigrations } from "../db/migrate.js";
+import { fetchBundle } from "../store/fetch.js";
+import { cloudUrl, getSiteInfo, runCloudTest } from "./cloud.js";
+import { detectProject } from "./detect.js";
+import { fileEnv } from "./env-file.js";
+import { loadAppModules, reexecWithTypes } from "./load-app.js";
+import { BUILD_BUNDLE_PATH, readBuildBundle } from "./pull.js";
+import { parseSecretKey, verifyBundle } from "@next-evolve/protocol";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+// src/cli/doctor.ts
+const DAY = 86400;
+const ok = (name, detail) => ({
+	name,
+	status: "ok",
+	detail
+});
+const warn = (name, detail) => ({
+	name,
+	status: "warn",
+	detail
+});
+const fail = (name, detail) => ({
+	name,
+	status: "fail",
+	detail
+});
+/** Next matcher (path-to-regexp style) → RegExp; null when it can't be read. */
+function matcherRegex(m) {
+	try {
+		const s = m.replace(/\/:\w+\*/g, "(?:/.*)?").replace(/\/:\w+\+/g, "(?:/.+)").replace(/\/:\w+\?/g, "(?:/[^/]+)?").replace(/:\w+/g, "[^/]+");
+		return new RegExp(`^${s}$`);
+	} catch {
+		return null;
+	}
+}
+/** The string literals in `config.matcher`, or null when there's no matcher (= every path). */
+function readMatcher(src) {
+	const m = /matcher\s*:\s*(\[[\s\S]*?\]|"[^"]*"|'[^']*'|`[^`]*`)/.exec(src);
+	if (!m) return null;
+	return [...m[1].matchAll(/(["'`])((?:\\.|(?!\1).)*)\1/g)].map((x) => x[2]);
+}
+const covers = (matchers, path) => matchers === null || matchers.some((m) => m === path || matcherRegex(m)?.test(path));
+function dirs(root, dir) {
+	try {
+		return readdirSync(join(root, dir)).filter((e) => statSync(join(root, dir, e)).isDirectory());
+	} catch {
+		return [];
+	}
+}
+const read = (p) => {
+	try {
+		return readFileSync(p, "utf8");
+	} catch {
+		return null;
+	}
+};
+async function runDoctor(deps) {
+	const cwd = deps.cwd ?? process.cwd();
+	const env = {
+		...fileEnv(cwd),
+		...deps.env
+	};
+	const nowMs = (deps.now ?? Date.now)();
+	const checks = [];
+	const d = detectProject(cwd);
+	const errors = d.problems.filter((p) => p.level === "error");
+	const warns = d.problems.filter((p) => p.level === "warn");
+	checks.push(errors.length ? fail("Next.js", errors.map((p) => p.message).join("; ")) : warns.length ? warn("Next.js", warns.map((p) => p.message).join("; ")) : ok("Next.js", `${d.nextVersion} · ${d.appDir}/`));
+	const required = ["EVOLVE_SECRET_KEY", "EVOLVE_WEBHOOK_SECRET"].filter((k) => !env[k]);
+	const optional = ["EVOLVE_DATABASE_URL", "EVOLVE_TRACK_SECRET"].filter((k) => !env[k]);
+	checks.push(required.length ? fail("Env vars", `missing ${required.join(", ")}`) : optional.length ? warn("Env vars", `missing ${optional.join(", ")}`) : ok("Env vars"));
+	const key = env.EVOLVE_SECRET_KEY ?? "";
+	const parsed = parseSecretKey(key);
+	let appUrl = deps.appUrl === void 0 ? null : deps.appUrl;
+	let keyOk = false;
+	if (!parsed) checks.push(fail("Secret key", "EVOLVE_SECRET_KEY isn't an evk_live_… key"));
+	else {
+		const site = await getSiteInfo({
+			env,
+			fetch: deps.fetch
+		}, key);
+		if (!site.ok) checks.push(fail("Secret key", site.error));
+		else {
+			keyOk = true;
+			if (deps.appUrl === void 0) appUrl = site.site.appUrl;
+			checks.push(ok("Secret key", `"${site.site.name}" (${site.site.id})`));
+		}
+	}
+	const dbUrl = env.EVOLVE_DATABASE_URL;
+	if (!dbUrl) checks.push(warn("Database", "EVOLVE_DATABASE_URL isn't set: variants serve, nothing is measured"));
+	else {
+		const r = await (deps.checkDb ?? checkDatabase)(dbUrl);
+		checks.push(!r.ok ? fail("Database", r.error) : r.pending.length ? fail("Database", `not migrated (${r.pending.join(", ")}): run npx next-evolve migrate`) : ok("Database", "reachable and migrated"));
+	}
+	const now = Math.floor(nowMs / 1e3);
+	if (!keyOk || !parsed) checks.push(fail("Bundle", "needs a working secret key"));
+	else {
+		const res = await fetchBundle({
+			cloudUrl: cloudUrl(env),
+			secretKey: key,
+			timeoutMs: 1e4,
+			fetch: deps.fetch
+		});
+		if (res.status !== "ok") checks.push(fail("Bundle", "couldn't fetch the bundle"));
+		else {
+			const v = verifyBundle(res.token, {
+				keys: trustedKeys(env),
+				site: parsed.siteId,
+				now
+			});
+			const days = v.ok ? Math.floor((v.payload.exp - now) / DAY) : 0;
+			const build = read(join(cwd, BUILD_BUNDLE_PATH));
+			if (!v.ok) checks.push(fail("Bundle", `rejected (${v.reason})`));
+			else if (v.payload.exp - now < 7 * DAY) checks.push(fail("Bundle", `expires in ${days} day(s); the cloud re-signs daily, so check its cron/status`));
+			else if (!build || !readBuildBundle(build)) checks.push(warn("Bundle", `no ${BUILD_BUNDLE_PATH}: add "prebuild": "next-evolve pull" (cold starts serve control)`));
+			else checks.push(ok("Bundle", `ver ${v.payload.ver}, expires in ${days} days`));
+		}
+	}
+	let config = null;
+	let configError = null;
+	try {
+		if (deps.load) config = (await deps.load()).config;
+		else {
+			const r = await loadAppModules(cwd);
+			if (r.ok) config = r.mods.config;
+			else configError = r.error;
+		}
+	} catch (e) {
+		configError = e instanceof Error ? e.message : String(e);
+	}
+	const routes = config ? Object.entries(config.routes ?? {}).map(([p, r]) => ({
+		path: normalizePath(p),
+		mode: r.mode
+	})) : [];
+	if (!d.proxyFile) checks.push(fail("Proxy matcher", `no proxy (${d.proxyKind}.ts) file`));
+	else {
+		const src = read(join(cwd, d.proxyFile)) ?? "";
+		if (!src.includes("next-evolve")) checks.push(fail("Proxy matcher", `${d.proxyFile} doesn't run Evolve (applyEvolve)`));
+		else {
+			const matchers = readMatcher(src);
+			const missing = [...routes.filter((r) => !covers(matchers, r.path)).map((r) => r.path), ...covers(matchers, "/ev_0") ? [] : ["/(ev_.*)"]];
+			checks.push(missing.length ? fail("Proxy matcher", `config.matcher in ${d.proxyFile} misses ${missing.join(", ")}`) : ok("Proxy matcher"));
+		}
+	}
+	const app = d.appDir ?? "app";
+	if (!config) checks.push(fail("Pages", configError ?? "couldn't load evolve.config"));
+	else {
+		const problems = [];
+		const statics = routes.filter((r) => r.mode === "static");
+		const clash = dirs(cwd, app).find((x) => /^\[.+\]$/.test(x) && x !== "[evolve]");
+		if (statics.length && clash) problems.push(`${app}/${clash} conflicts with ${app}/[evolve]; use "dynamic" mode`);
+		for (const r of statics) {
+			const seg = r.path === "/" ? "" : r.path;
+			const page = [
+				"tsx",
+				"jsx",
+				"ts",
+				"js"
+			].map((e) => `${app}/[evolve]${seg}/page.${e}`).find((f) => existsSync(join(cwd, f)));
+			if (!page) problems.push(`${r.path}: no ${app}/[evolve]${seg}/page (run init again)`);
+			else if (!read(join(cwd, page))?.includes("withEvolve")) problems.push(`${r.path}: ${page} isn't wrapped with withEvolve()`);
+		}
+		checks.push(problems.length ? fail("Pages", problems.join("; ")) : ok("Pages"));
+	}
+	const layout = [
+		"tsx",
+		"jsx",
+		"js",
+		"ts"
+	].map((e) => `${app}/layout.${e}`).find((f) => existsSync(join(cwd, f)));
+	checks.push(layout && read(join(cwd, layout))?.includes("EvolveScript") ? ok("EvolveScript") : fail("EvolveScript", `add <EvolveScript /> (next-evolve/client) to ${layout ?? "the root layout"}`));
+	if (!keyOk) checks.push(fail("Cloud → app", "needs a working secret key"));
+	else if (!appUrl) checks.push(warn("Cloud → app", "no app URL yet; after you deploy: npx next-evolve connect --test --app-url https://…"));
+	else {
+		const t = await runCloudTest({
+			env,
+			fetch: deps.fetch
+		}, key);
+		if (!t.ok) checks.push(fail("Cloud → app", t.error));
+		else {
+			const bad = [...t.webhook.ok ? [] : [`sync route: ${t.webhook.detail ?? "failed"}`], ...t.aggregate.ok ? [] : [`aggregate route: ${t.aggregate.detail ?? "failed"}`]];
+			checks.push(bad.length ? fail("Cloud → app", `${appUrl}: ${bad.join("; ")}`) : ok("Cloud → app", appUrl));
+		}
+	}
+	const onVercel = Boolean(env.VERCEL) || existsSync(join(cwd, ".vercel/project.json"));
+	checks.push(onVercel ? ok("CDN", "Vercel") : warn("CDN", "not on Vercel: if a CDN caches pages, it must not cache Evolve routes by URL alone (the variant comes from the evolve cookie)"));
+	return checks;
+}
+async function checkDatabase(url) {
+	const sql = createSql(url, { max: 1 });
+	try {
+		await sql`select 1`;
+		const [t] = await sql`select to_regclass('evolve.migrations') as r`;
+		const done = t?.r ? new Set((await sql`select id from evolve.migrations`).map((r) => r.id)) : /* @__PURE__ */ new Set();
+		return {
+			ok: true,
+			pending: (await loadMigrations()).map((m) => m.id).filter((id) => !done.has(id))
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	} finally {
+		await sql.end({ timeout: 5 }).catch(() => {});
+	}
+}
+async function doctorCommand(args, deps) {
+	const out = deps.out ?? ((s) => console.warn(s));
+	const cwd = deps.cwd ?? process.cwd();
+	if (!deps.load) {
+		const r = await loadAppModules(cwd);
+		if (!r.ok && r.needsTs && process.argv[1]) return reexecWithTypes("doctor", args, cwd, deps.env);
+	}
+	const checks = await runDoctor(deps);
+	const mark = {
+		ok: "✓",
+		warn: "!",
+		fail: "✗"
+	};
+	for (const c of checks) out(`${mark[c.status]} ${c.name}${c.detail ? `: ${c.detail}` : ""}`);
+	const failed = checks.filter((c) => c.status === "fail").length;
+	out(failed ? `\n${failed} check(s) failed.` : "\nAll good.");
+	return failed ? 1 : 0;
+}
+export { covers, doctorCommand, readMatcher, runDoctor };

package/dist/cli/env-file.d.ts

@@ -0,0 +1,4 @@
+type Env = Record<string, string | undefined>;
+/** Reads a value from the app's .env.local / .env without touching process.env. */
+export declare function fileEnv(root: string): Env;
+export {};

package/dist/cli/env-file.js

@@ -0,0 +1,15 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+// src/cli/env-file.ts
+/** Reads a value from the app's .env.local / .env without touching process.env. */
+function fileEnv(root) {
+	const out = {};
+	for (const f of [".env", ".env.local"]) try {
+		for (const line of readFileSync(join(root, f), "utf8").split("\n")) {
+			const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
+			if (m) out[m[1]] = m[2].replace(/^(['"])(.*)\1$/, "$2");
+		}
+	} catch {}
+	return out;
+}
+export { fileEnv };

package/dist/cli/files.d.ts

@@ -0,0 +1,25 @@
+import { Detection } from "./detect.js";
+import { Plan } from "./plan.js";
+export type RouteMode = {
+  path: string;
+  mode: "static" | "dynamic";
+};
+/** Import specifier from one project file to another (extension dropped). */
+export declare function relImport(fromFile: string, toFile: string): string;
+export declare const configFile: (d: Detection) => string;
+export declare const goalsFile: (d: Detection) => string;
+export declare const routeFile: (d: Detection) => string;
+export declare const matcherFor: (routes: RouteMode[]) => string[];
+export declare function planConfig(plan: Plan, d: Detection, routes: RouteMode[]): void;
+export declare function planGoals(plan: Plan, d: Detection): void;
+export declare function planRouteHandler(plan: Plan, d: Detection): void;
+export declare function planProxy(plan: Plan, d: Detection, routes: RouteMode[]): void;
+/** Imports go after the last import line (or at the top). */
+export declare function addImport(src: string, line: string): string;
+export declare function planLayout(plan: Plan, d: Detection): void;
+export declare function planInstrumentation(plan: Plan, d: Detection): void;
+export declare function planPackageJson(plan: Plan): void;
+export declare function planGitignore(plan: Plan): void;
+export declare const newTrackSecret: () => string;
+/** Appends variables missing from .env.local; never changes a line that's there. */
+export declare function planEnv(plan: Plan, vars: Record<string, string | undefined>): string[];

package/dist/cli/files.js

@@ -0,0 +1,173 @@
+import { posix } from "node:path";
+import { randomBytes } from "node:crypto";
+// src/cli/files.ts
+const ext = (d) => d.typescript ? "ts" : "js";
+const base = (d) => d.srcDir ? "src/" : "";
+/** Import specifier from one project file to another (extension dropped). */
+function relImport(fromFile, toFile) {
+	const r = posix.relative(posix.dirname(fromFile), toFile).replace(/\.(tsx?|jsx?|mjs)$/, "");
+	return r.startsWith("./") || r.startsWith("../") ? r : `./${r}`;
+}
+const configFile = (d) => `evolve.config.${ext(d)}`;
+const goalsFile = (d) => `evolve.goals.${ext(d)}`;
+const routeFile = (d) => `${d.appDir}/api/evolve/[...evolve]/route.${ext(d)}`;
+const matcherFor = (routes) => [...routes.map((r) => r.path), "/(ev_.*)"];
+const list = (xs) => `[${xs.map((x) => JSON.stringify(x)).join(", ")}]`;
+function planConfig(plan, d, routes) {
+	const routeLines = routes.map((r) => `    ${JSON.stringify(r.path)}: { mode: "${r.mode}" },`);
+	if (!plan.create(configFile(d), `import { defineConfig } from "next-evolve/config";
+
+export default defineConfig({
+  // Pages Evolve may test. "static": cached per variant (moved under app/[evolve]/).
+  // "dynamic": rendered per request, the page stays where it is.
+  routes: {
+${routeLines.join("\n")}
+  },
+});
+`)) {
+		const current = plan.read(configFile(d)) ?? "";
+		const missing = routes.filter((r) => !current.includes(JSON.stringify(r.path)));
+		if (missing.length) plan.manual.push(`Add to routes in ${configFile(d)}: ${missing.map((r) => `${JSON.stringify(r.path)}: { mode: "${r.mode}" }`).join(", ")}`);
+	}
+}
+function planGoals(plan, d) {
+	plan.create(goalsFile(d), `import { defineGoals } from "next-evolve/config";
+
+// What counts as success. Fire events with data-evolve-goal="<event>" on a
+// link or form, or evolve.track("<event>") on the server.
+export default defineGoals({
+  signed_up: { event: "signup", window: "7d" },
+});
+`);
+}
+function planRouteHandler(plan, d) {
+	const f = routeFile(d);
+	plan.create(f, `import { createEvolveHandler } from "next-evolve/server";
+import evolveConfig from "${relImport(f, configFile(d))}";
+import goals from "${relImport(f, goalsFile(d))}";
+
+// collect (beacon), track, sync (cloud webhook), aggregate (cloud), health
+export const { GET, POST } = createEvolveHandler({ config: evolveConfig, goals });
+export const maxDuration = 60;
+`);
+}
+function planProxy(plan, d, routes) {
+	const matcher = list(matcherFor(routes));
+	if (d.proxyFile) {
+		if ((plan.read(d.proxyFile) ?? "").includes("next-evolve")) return;
+		plan.manual.push(`Your ${d.proxyFile} exists, so add Evolve to it:
+    import { applyEvolve } from "next-evolve/proxy";
+    import buildBundle from "${relImport(d.proxyFile, ".evolve/bundle.generated.ts")}";
+    import evolveConfig from "${relImport(d.proxyFile, configFile(d))}";
+    // first thing in your ${d.proxyKind} function:
+    const evolved = applyEvolve(evolveConfig, req, event, { buildBundle });
+    if (evolved) return evolved;
+  and add ${matcher.slice(1, -1)} to config.matcher${d.proxyKind === "middleware" ? ", with runtime: \"nodejs\"" : ""}.`);
+		return;
+	}
+	const f = `${base(d)}${d.proxyKind}.${ext(d)}`;
+	const imports = `import { createEvolveProxy } from "next-evolve/proxy";
+import buildBundle from "${relImport(f, ".evolve/bundle.generated.ts")}";
+import evolveConfig from "${relImport(f, configFile(d))}";
+`;
+	plan.write(f, d.proxyKind === "proxy" ? `${imports}
+export const proxy = createEvolveProxy(evolveConfig, { buildBundle });
+
+export const config = { matcher: ${matcher} };
+` : `${imports}
+export const middleware = createEvolveProxy(evolveConfig, { buildBundle });
+
+export const config = { matcher: ${matcher}, runtime: "nodejs" };
+`);
+}
+/** Imports go after the last import line (or at the top). */
+function addImport(src, line) {
+	const lines = src.split("\n");
+	let last = -1;
+	lines.forEach((l, i) => {
+		if (/^import\s/.test(l) || /^\s*} from ["']/.test(l)) last = i;
+	});
+	if (last === -1) {
+		const directive = /^["']use (client|server)["'];?$/.test(lines[0] ?? "") ? 1 : 0;
+		lines.splice(directive, 0, line, "");
+	} else lines.splice(last + 1, 0, line);
+	return lines.join("\n");
+}
+function planLayout(plan, d) {
+	const f = [
+		"tsx",
+		"jsx",
+		"js",
+		"ts"
+	].map((e) => `${d.appDir}/layout.${e}`).find((p) => plan.exists(p));
+	if (!f) {
+		plan.manual.push(`Add <EvolveScript /> (from "next-evolve/client") to your root layout's <body>.`);
+		return;
+	}
+	const src = plan.read(f);
+	if (src.includes("EvolveScript")) return;
+	const m = /^([ \t]*)<\/body>/m.exec(src);
+	if (!m) {
+		plan.manual.push(`Add <EvolveScript /> (from "next-evolve/client") inside <body> in ${f}.`);
+		return;
+	}
+	const indent = `${m[1]}  `;
+	const withTag = src.replace(m[0], `${indent}<EvolveScript />\n${m[0]}`);
+	plan.write(f, addImport(withTag, `import { EvolveScript } from "next-evolve/client";`));
+}
+function planInstrumentation(plan, d) {
+	const f = `${base(d)}instrumentation.${ext(d)}`;
+	const existing = ["ts", "js"].map((e) => `${base(d)}instrumentation.${e}`).find((p) => plan.exists(p));
+	const block = `  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const [{ registerEvolve }, { default: config }, { default: goals }] = await Promise.all([
+      import("next-evolve/instrumentation"),
+      import("${relImport(existing ?? f, configFile(d))}"),
+      import("${relImport(existing ?? f, goalsFile(d))}"),
+    ]);
+    await registerEvolve({ config, goals });
+  }`;
+	if (!existing) {
+		plan.write(f, `export async function register() {\n${block}\n}\n`);
+		return;
+	}
+	const src = plan.read(existing);
+	if (src.includes("registerEvolve")) return;
+	const m = /export\s+(async\s+)?function\s+register\s*\([^)]*\)\s*(:\s*[^{]+)?\{\n?/.exec(src);
+	if (!m) {
+		plan.manual.push(`Add to register() in ${existing}:\n${block}`);
+		return;
+	}
+	const head = m[1] ? m[0] : m[0].replace(/function/, "async function");
+	plan.write(existing, src.replace(m[0], `${head.endsWith("\n") ? head : `${head}\n`}${block}\n`));
+}
+function planPackageJson(plan) {
+	const src = plan.read("package.json");
+	if (!src) return;
+	const pkg = JSON.parse(src);
+	const pre = pkg.scripts?.prebuild;
+	if (pre?.includes("next-evolve pull")) return;
+	pkg.scripts = {
+		...pkg.scripts,
+		prebuild: pre ? `next-evolve pull && ${pre}` : "next-evolve pull"
+	};
+	const indent = /^(\s+)"/m.exec(src)?.[1] ?? "  ";
+	plan.write("package.json", `${JSON.stringify(pkg, null, indent)}\n`);
+}
+function planGitignore(plan) {
+	const src = plan.read(".gitignore") ?? "";
+	if (/^\/?\.evolve\/?$/m.test(src)) return;
+	plan.write(".gitignore", `${src}${src && !src.endsWith("\n") ? "\n" : ""}\n# Evolve build bundle\n.evolve/\n`);
+}
+const BASE62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const newTrackSecret = () => `trk_${Array.from(randomBytes(32), (b) => BASE62[b % 62]).join("")}`;
+/** Appends variables missing from .env.local; never changes a line that's there. */
+function planEnv(plan, vars) {
+	const src = plan.read(".env.local") ?? "";
+	const has = (k) => new RegExp(`^\\s*(export\\s+)?${k}\\s*=`, "m").test(src);
+	const add = Object.entries(vars).filter(([k, v]) => v && !has(k));
+	if (!add.length) return [];
+	const lines = add.map(([k, v]) => `${k}=${v}`).join("\n");
+	plan.write(".env.local", `${src}${src && !src.endsWith("\n") ? "\n" : ""}${src ? "\n" : ""}# Evolve\n${lines}\n`);
+	return add.map(([k]) => k);
+}
+export { addImport, configFile, goalsFile, matcherFor, newTrackSecret, planConfig, planEnv, planGitignore, planGoals, planInstrumentation, planLayout, planPackageJson, planProxy, planRouteHandler, relImport, routeFile };