next-evolve 0.1.0 → 0.3.1

package/dist/cli/index.js

@@ -1,40 +1,81 @@
 #!/usr/bin/env node
-import { createSql } from "../db/client.js";
-import { migrate } from "../db/migrate.js";
+import { aggregateCommand } from "./aggregate.js";
+import { connectCommand } from "./connect.js";
+import { doctorCommand } from "./doctor.js";
+import { initCommand } from "./init.js";
+import { migrateCommand } from "./migrate.js";
+import { pullCommand } from "./pull.js";
+import { pushCommand } from "./push.js";
 import { existsSync } from "node:fs";
 // src/cli/index.ts
-const HELP = `Usage: next-evolve <command>
-
-Commands:
-  migrate [--url <postgres-url>]   Create or update the evolve schema in your database
-                                   (default: $EVOLVE_DATABASE_URL, read from .env.local / .env)
-`;
+const COMMANDS = {
+	init: {
+		usage: "init [--key] [--webhook-secret] [--db] [--app-url] [--mode] [--routes] [--yes] [--dry-run]",
+		summary: "Set Evolve up in this Next.js app (safe to re-run)",
+		run: async (args, env) => {
+			if (!(process.stdin.isTTY && !args.includes("--yes") && !args.includes("-y"))) return initCommand(args, {
+				env,
+				ask: null
+			});
+			const { createInterface } = await import("node:readline/promises");
+			const rl = createInterface({
+				input: process.stdin,
+				output: process.stdout
+			});
+			try {
+				return await initCommand(args, {
+					env,
+					ask: (q) => rl.question(q)
+				});
+			} finally {
+				rl.close();
+			}
+		}
+	},
+	migrate: {
+		usage: "migrate [--url <postgres-url>]",
+		summary: "Create or update the evolve schema in your database ($EVOLVE_DATABASE_URL)",
+		run: (args, env) => migrateCommand(args, { env })
+	},
+	pull: {
+		usage: "pull",
+		summary: "Write the verified bundle to .evolve/bundle.generated.ts (run as \"prebuild\")",
+		run: (args, env) => pullCommand(args, { env })
+	},
+	push: {
+		usage: "push",
+		summary: "Send routes and goals (the manifest) to Evolve Cloud now",
+		run: (args, env) => pushCommand(args, { env })
+	},
+	connect: {
+		usage: "connect [--test] [--app-url <url>]",
+		summary: "Check the key; register the app URL; --test: can the cloud reach your app?",
+		run: (args, env) => connectCommand(args, { env })
+	},
+	doctor: {
+		usage: "doctor",
+		summary: "Check the whole setup (env, key, DB, bundle, proxy, pages, cloud → app)",
+		run: (args, env) => doctorCommand(args, { env })
+	},
+	aggregate: {
+		usage: "aggregate [--upload]",
+		summary: "Run the cloud's aggregate request on your local DB (--upload sends the result)",
+		run: (args, env) => aggregateCommand(args, { env })
+	}
+};
+function help() {
+	const width = Math.max(...Object.values(COMMANDS).map((c) => c.usage.length)) + 2;
+	return `Usage: next-evolve <command>\n\nCommands:\n${Object.values(COMMANDS).map((c) => `  ${c.usage.padEnd(width)}${c.summary}`).join("\n")}\n\nEnv is read from .env.local and .env (never overriding what's set).\n`;
+}
 function loadEnvFiles() {
 	for (const f of [".env.local", ".env"]) if (existsSync(f)) process.loadEnvFile(f);
 }
-async function runMigrate(args) {
-	loadEnvFiles();
-	const i = args.indexOf("--url");
-	const url = i >= 0 ? args[i + 1] : process.env.EVOLVE_DATABASE_URL;
-	if (!url) {
-		console.error("next-evolve migrate: set EVOLVE_DATABASE_URL or pass --url");
-		return 1;
-	}
-	const sql = createSql(url, { max: 1 });
-	try {
-		const r = await migrate(sql);
-		console.warn(r.applied.length ? `Applied ${r.applied.join(", ")}` : `Up to date (${r.skipped.join(", ") || "nothing to apply"})`);
-		return 0;
-	} catch (e) {
-		console.error("next-evolve migrate failed:", e instanceof Error ? e.message : e);
-		return 1;
-	} finally {
-		await sql.end({ timeout: 5 });
-	}
-}
 const [cmd, ...rest] = process.argv.slice(2);
-if (cmd === "migrate") process.exitCode = await runMigrate(rest);
-else {
-	process.stdout.write(HELP);
-	process.exitCode = cmd && cmd !== "help" && cmd !== "--help" ? 1 : 0;
+const command = cmd ? COMMANDS[cmd] : void 0;
+if (command) {
+	loadEnvFiles();
+	process.exitCode = await command.run(rest, process.env);
+} else {
+	process.stdout.write(help());
+	process.exitCode = cmd && cmd !== "help" && cmd !== "--help" && cmd !== "-h" ? 1 : 0;
 }

package/dist/cli/init.d.ts

@@ -0,0 +1,26 @@
+import { Detection } from "./detect.js";
+type Env = Record<string, string | undefined>;
+export type InitDeps = {
+  env: Env;
+  cwd?: string;
+  fetch?: typeof fetch;
+  out?: (s: string) => void;
+  err?: (s: string) => void;
+  /** Asks a question (interactive); null when there's no terminal. */
+  ask?: ((q: string) => Promise<string>) | null;
+  /** Runs a command (install). */
+  run?: (cmd: string, args: string[], cwd: string) => Promise<number>;
+  /** Tests the DB and migrates it. */
+  setupDb?: (url: string) => Promise<{
+    ok: true;
+    applied: string[];
+  } | {
+    ok: false;
+    error: string;
+  }>;
+  /** Runs `push` (tests can skip). */
+  push?: (env: Env) => Promise<number>;
+};
+export declare function initCommand(args: string[], deps: InitDeps): Promise<number>;
+export declare function installCommand(d: Detection, pkgs: string[]): string[];
+export {};

package/dist/cli/init.js

@@ -0,0 +1,240 @@
+import { createSql } from "../db/client.js";
+import { migrate } from "../db/migrate.js";
+import { parseFlags } from "./args.js";
+import { getSiteInfo, putAppUrl } from "./cloud.js";
+import { detectProject } from "./detect.js";
+import { fileEnv } from "./env-file.js";
+import { newTrackSecret, planConfig, planEnv, planGitignore, planGoals, planInstrumentation, planLayout, planPackageJson, planProxy, planRouteHandler } from "./files.js";
+import { planPages } from "./pages.js";
+import { Plan, renderDiff } from "./plan.js";
+import { pullCommand } from "./pull.js";
+import { pushCommand } from "./push.js";
+import { WEBHOOK_SECRET_RE, parseSecretKey } from "@next-evolve/protocol";
+import { spawn } from "node:child_process";
+// src/cli/init.ts
+const FLAGS = {
+	key: { type: "string" },
+	"webhook-secret": { type: "string" },
+	db: { type: "string" },
+	"app-url": { type: "string" },
+	yes: {
+		type: "boolean",
+		short: "y"
+	},
+	"dry-run": { type: "boolean" },
+	mode: { type: "string" },
+	routes: { type: "string" }
+};
+const DB_HELP = `Evolve stores events in your own Postgres (its own "evolve" schema).
+  One-click options:
+    Vercel Marketplace → Neon:  https://vercel.com/marketplace/neon
+    Supabase:                   https://supabase.com/dashboard/new
+    Neon:                       https://console.neon.tech/signup`;
+async function initCommand(args, deps) {
+	const out = deps.out ?? ((s) => console.warn(s));
+	const err = deps.err ?? ((s) => console.error(s));
+	const cwd = deps.cwd ?? process.cwd();
+	const p = parseFlags(args, FLAGS);
+	if (!p.ok) {
+		err(`next-evolve init: ${p.error}`);
+		return 1;
+	}
+	const f = p.flags;
+	const dry = Boolean(f["dry-run"]);
+	const yes = Boolean(f.yes);
+	const ask = deps.ask === void 0 ? null : deps.ask;
+	const env = {
+		...fileEnv(cwd),
+		...deps.env
+	};
+	const d = detectProject(cwd);
+	for (const pr of d.problems) (pr.level === "error" ? err : out)(`${pr.level === "error" ? "✗" : "!"} ${pr.message}`);
+	if (d.problems.some((pr) => pr.level === "error")) return 1;
+	out(`✓ Next.js ${d.nextVersion} · ${d.appDir}/ · ${d.typescript ? "TypeScript" : "JavaScript"} · ${d.packageManager}`);
+	const mode = f.mode ?? "static";
+	if (mode !== "static" && mode !== "dynamic") {
+		err("next-evolve init: --mode is \"static\" or \"dynamic\"");
+		return 1;
+	}
+	const paths = (f.routes ?? "/").split(/[\s,]+/).filter(Boolean);
+	if (paths.some((r) => !r.startsWith("/") || /[[\]*?#]/.test(r))) {
+		err("next-evolve init: --routes are concrete paths like \"/ /pricing\"");
+		return 1;
+	}
+	const need = async (label, flag, envKey, valid) => {
+		let v = flag ?? env[envKey];
+		if (!v && ask && !yes) v = (await ask(`${label}: `)).trim();
+		if (!v || !valid(v)) return null;
+		return v;
+	};
+	const key = await need("Secret key (evk_live_…)", f.key, "EVOLVE_SECRET_KEY", (v) => Boolean(parseSecretKey(v)));
+	if (!key) {
+		err("✗ A secret key is needed: --key evk_live_… (shown once when you created the site)");
+		return 1;
+	}
+	const webhookSecret = await need("Webhook secret (whsec_…)", f["webhook-secret"], "EVOLVE_WEBHOOK_SECRET", (v) => WEBHOOK_SECRET_RE.test(v));
+	if (!webhookSecret) {
+		err("✗ The webhook secret is needed: --webhook-secret whsec_…");
+		return 1;
+	}
+	const site = await getSiteInfo({
+		env,
+		fetch: deps.fetch
+	}, key);
+	if (!site.ok) {
+		err(`✗ ${site.error}`);
+		return 1;
+	}
+	out(`✓ Connected to "${site.site.name}" (${site.site.id})`);
+	const missing = [...d.hasEvolve ? [] : ["next-evolve"], ...d.hasZod ? [] : ["zod@^4"]];
+	if (missing.length) {
+		if (dry) out(`  would install ${missing.join(" ")}`);
+		else {
+			const [cmd, ...a] = installCommand(d, missing);
+			out(`  ${cmd} ${a.join(" ")}`);
+			const code = await (deps.run ?? runCommand)(cmd, a, cwd);
+			if (code !== 0) {
+				err(`✗ Install failed (exit ${code})`);
+				return 1;
+			}
+		}
+	}
+	let dbUrl = f.db ?? env.EVOLVE_DATABASE_URL ?? null;
+	if (!dbUrl) {
+		const reuse = env.DATABASE_URL ? "DATABASE_URL" : env.POSTGRES_URL ? "POSTGRES_URL" : null;
+		if (reuse) {
+			if (yes || !ask || /^(y|yes|)$/i.test((await ask(`Use ${reuse} for Evolve's events (own "evolve" schema)? [Y/n] `)).trim())) dbUrl = env[reuse];
+		}
+		if (!dbUrl && ask && !yes) {
+			out(DB_HELP);
+			dbUrl = (await ask("Postgres URL (empty to skip for now): ")).trim() || null;
+		}
+	}
+	if (!dbUrl) out(`! No database yet: variants serve, but nothing is measured.\n${DB_HELP}\n  Then: set EVOLVE_DATABASE_URL and run npx next-evolve migrate`);
+	else if (dry) out("  would test the database and run migrations");
+	else {
+		const r = await (deps.setupDb ?? setupDatabase)(dbUrl);
+		if (!r.ok) {
+			err(`✗ Database: ${r.error}`);
+			return 1;
+		}
+		out(`✓ Database ready${r.applied.length ? ` (applied ${r.applied.join(", ")})` : ""}`);
+	}
+	const plan = new Plan(cwd);
+	const routes = paths.map((path) => ({
+		path,
+		mode
+	}));
+	const finalRoutes = planPages(plan, d, routes);
+	planConfig(plan, d, finalRoutes);
+	planGoals(plan, d);
+	planRouteHandler(plan, d);
+	planProxy(plan, d, finalRoutes);
+	planLayout(plan, d);
+	planInstrumentation(plan, d);
+	planPackageJson(plan);
+	planGitignore(plan);
+	const added = planEnv(plan, {
+		EVOLVE_SECRET_KEY: key,
+		EVOLVE_WEBHOOK_SECRET: webhookSecret,
+		EVOLVE_DATABASE_URL: dbUrl ?? void 0,
+		EVOLVE_TRACK_SECRET: env.EVOLVE_TRACK_SECRET ?? newTrackSecret()
+	});
+	const changes = plan.changes();
+	if (dry) out(changes.length ? `\nWould change:\n\n${renderDiff(changes)}` : "\nNothing to change.");
+	else {
+		plan.apply();
+		for (const c of changes) out(`  ${c.before === null ? "created" : c.after === null ? "removed" : "updated"} ${c.path}`);
+		if (!changes.length) out("  files already set up");
+	}
+	for (const n of plan.notes) out(`  ${n}`);
+	const appEnv = {
+		...env,
+		EVOLVE_SECRET_KEY: key,
+		EVOLVE_WEBHOOK_SECRET: webhookSecret
+	};
+	if (!dry) {
+		await pullCommand([], {
+			env: appEnv,
+			cwd,
+			out: () => {},
+			err: () => {}
+		});
+		if (f["app-url"]) {
+			const r = await putAppUrl({
+				env,
+				fetch: deps.fetch
+			}, key, f["app-url"]);
+			if (r.ok) out(`✓ App URL: ${r.appUrl}`);
+			else err(`! App URL not set: ${r.error}`);
+		}
+		out(await (deps.push ?? ((e) => pushCommand([], {
+			env: e,
+			cwd,
+			out: () => {},
+			err: () => {},
+			quiet: true
+		})))(appEnv) === 0 ? "✓ Manifest sent" : "! Manifest not sent yet (it's sent when your app starts)");
+	} else if (f["app-url"]) out(`  would register the app URL ${f["app-url"]}`);
+	out(`\nNext:\n${[
+		...plan.manual,
+		...added.length && !dry ? [`In production, set ${added.join(", ")} (they're in .env.local now)`] : [],
+		`Wrap a component: <Optimizable id="hero" component={Hero} props={...} /> (from "next-evolve")`,
+		"Visit the page once so the region registers, then open the dashboard",
+		...f["app-url"] ? ["After you deploy: npx next-evolve connect --test"] : ["After you deploy: npx next-evolve connect --test --app-url https://your-app.com"]
+	].map((s, i) => `  ${i + 1}. ${s}`).join("\n")}`);
+	return 0;
+}
+function installCommand(d, pkgs) {
+	switch (d.packageManager) {
+		case "pnpm": return [
+			"pnpm",
+			"add",
+			...pkgs
+		];
+		case "yarn": return [
+			"yarn",
+			"add",
+			...pkgs
+		];
+		case "bun": return [
+			"bun",
+			"add",
+			...pkgs
+		];
+		default: return [
+			"npm",
+			"install",
+			...pkgs
+		];
+	}
+}
+function runCommand(cmd, args, cwd) {
+	return new Promise((resolve) => {
+		const child = spawn(cmd, args, {
+			cwd,
+			stdio: "inherit",
+			shell: process.platform === "win32"
+		});
+		child.on("exit", (code) => resolve(code ?? 1));
+		child.on("error", () => resolve(1));
+	});
+}
+async function setupDatabase(url) {
+	const sql = createSql(url, { max: 1 });
+	try {
+		await sql`select 1`;
+		return {
+			ok: true,
+			applied: (await migrate(sql)).applied
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	} finally {
+		await sql.end({ timeout: 5 }).catch(() => {});
+	}
+}
+export { initCommand, installCommand };

package/dist/cli/load-app.d.ts

@@ -0,0 +1,19 @@
+import { EvolveConfig } from "../config/config.js";
+import { Goals } from "../config/goals.js";
+export type AppModules = {
+  config: EvolveConfig;
+  goals?: Goals;
+};
+/** True when this Node can import .ts files (type stripping on). */
+export declare const canImportTs: () => boolean;
+export declare function loadAppModules(root: string): Promise<{
+  ok: true;
+  mods: AppModules;
+  files: string[];
+} | {
+  ok: false;
+  error: string;
+  needsTs?: boolean;
+}>;
+/** Re-runs this CLI command with type stripping on (Node < 22.18 has it behind a flag). */
+export declare function reexecWithTypes(command: string, args: string[], cwd: string, env: Record<string, string | undefined>, quiet?: boolean): number;

package/dist/cli/load-app.js

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+// src/cli/load-app.ts
+const find = (root, name) => [
+	"ts",
+	"mts",
+	"js",
+	"mjs"
+].map((e) => join(root, `${name}.${e}`)).find((p) => existsSync(p));
+/** True when this Node can import .ts files (type stripping on). */
+const canImportTs = () => Boolean(process.features.typescript) || process.execArgv.some((a) => a.includes("strip-types"));
+async function loadAppModules(root) {
+	const configPath = find(root, "evolve.config");
+	if (!configPath) return {
+		ok: false,
+		error: "no evolve.config.ts (run npx next-evolve init)"
+	};
+	const goalsPath = find(root, "evolve.goals");
+	const files = [configPath, ...goalsPath ? [goalsPath] : []];
+	if (files.some((f) => /\.m?ts$/.test(f)) && !canImportTs()) return {
+		ok: false,
+		error: "this Node can't load .ts files",
+		needsTs: true
+	};
+	try {
+		const c = await import(pathToFileURL(configPath).href);
+		const g = goalsPath ? await import(pathToFileURL(goalsPath).href) : void 0;
+		return {
+			ok: true,
+			mods: {
+				config: c.default ?? c,
+				goals: g ? g.default ?? g : void 0
+			},
+			files
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: `couldn't load ${configPath} (${e instanceof Error ? e.message : e})`
+		};
+	}
+}
+/** Re-runs this CLI command with type stripping on (Node < 22.18 has it behind a flag). */
+function reexecWithTypes(command, args, cwd, env, quiet = false) {
+	return spawnSync(process.execPath, [
+		"--experimental-strip-types",
+		"--disable-warning=ExperimentalWarning",
+		"--disable-warning=MODULE_TYPELESS_PACKAGE_JSON",
+		process.argv[1],
+		command,
+		...args
+	], {
+		stdio: [
+			"ignore",
+			quiet ? "ignore" : "inherit",
+			"inherit"
+		],
+		cwd,
+		env: {
+			...process.env,
+			...env
+		}
+	}).status ?? 1;
+}
+export { canImportTs, loadAppModules, reexecWithTypes };

package/dist/cli/migrate.d.ts

@@ -0,0 +1,7 @@
+type Env = Record<string, string | undefined>;
+export declare function migrateCommand(args: string[], deps: {
+  env: Env;
+  out?: (s: string) => void;
+  err?: (s: string) => void;
+}): Promise<number>;
+export {};

package/dist/cli/migrate.js

@@ -0,0 +1,30 @@
+import { createSql } from "../db/client.js";
+import { migrate } from "../db/migrate.js";
+import { parseFlags } from "./args.js";
+// src/cli/migrate.ts
+async function migrateCommand(args, deps) {
+	const out = deps.out ?? ((s) => console.warn(s));
+	const err = deps.err ?? ((s) => console.error(s));
+	const parsed = parseFlags(args, { url: { type: "string" } });
+	if (!parsed.ok) {
+		err(`next-evolve migrate: ${parsed.error}`);
+		return 1;
+	}
+	const url = parsed.flags.url ?? deps.env.EVOLVE_DATABASE_URL;
+	if (!url) {
+		err("next-evolve migrate: set EVOLVE_DATABASE_URL or pass --url");
+		return 1;
+	}
+	const sql = createSql(url, { max: 1 });
+	try {
+		const r = await migrate(sql);
+		out(r.applied.length ? `Applied ${r.applied.join(", ")}` : `Up to date (${r.skipped.join(", ") || "nothing to apply"})`);
+		return 0;
+	} catch (e) {
+		err(`next-evolve migrate failed: ${e instanceof Error ? e.message : e}`);
+		return 1;
+	} finally {
+		await sql.end({ timeout: 5 });
+	}
+}
+export { migrateCommand };

package/dist/cli/pages.d.ts

@@ -0,0 +1,17 @@
+import { typescript_d_exports } from "../node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/typescript.js";
+import { Detection } from "./detect.js";
+import { RouteMode } from "./files.js";
+import { Plan } from "./plan.js";
+/** The app's typescript, else the one next to next-evolve; null when neither exists. */
+export declare function loadTypescript(root: string): typeof typescript_d_exports | null;
+export declare function planPages(plan: Plan, d: Detection, routes: RouteMode[]): RouteMode[];
+/** Wraps the page module: default export → withEvolve, metadata → evolveMetadata. */
+export declare function wrapPage(ts: typeof typescript_d_exports, src: string, file: string, path: string): {
+  ok: true;
+  code: string;
+} | {
+  ok: false;
+  why: string;
+};
+/** Rewrites relative specifiers for a file that moved; files moving together keep pointing at each other. */
+export declare function rewriteImports(ts: typeof typescript_d_exports, src: string, oldPath: string, newPath: string, moves: Map<string, string>): string;