next-evolve 0.0.0-stage → 0.3.1

package/dist/cli/cloud.d.ts

@@ -0,0 +1,41 @@
+type Env = Record<string, string | undefined>;
+export type CloudDeps = {
+  env: Env;
+  fetch?: typeof fetch;
+};
+export type SiteInfo = {
+  id: string;
+  name: string;
+  appUrl: string | null;
+};
+export declare const cloudUrl: (env: Env) => string;
+/** `GET /v1/site`: which site this key belongs to. Accepts the cloud's and the fake cloud's shapes. */
+export declare function getSiteInfo(deps: CloudDeps, key: string): Promise<{
+  ok: true;
+  site: SiteInfo;
+} | {
+  ok: false;
+  error: string;
+}>;
+/** `PUT /v1/site/app-url`. */
+export declare function putAppUrl(deps: CloudDeps, key: string, appUrl: string): Promise<{
+  ok: true;
+  appUrl: string;
+} | {
+  ok: false;
+  error: string;
+}>;
+export type CheckResult = {
+  ok: boolean;
+  detail?: string;
+};
+/** `POST /v1/site/test`: the cloud pings the sync route and dry-runs an aggregate. */
+export declare function runCloudTest(deps: CloudDeps, key: string): Promise<{
+  ok: true;
+  webhook: CheckResult;
+  aggregate: CheckResult;
+} | {
+  ok: false;
+  error: string;
+}>;
+export {};

package/dist/cli/cloud.js

@@ -0,0 +1,74 @@
+import "../store/runtime.js";
+// src/cli/cloud.ts
+const cloudUrl = (env) => env.EVOLVE_CLOUD_URL ?? "https://api.evolveab.com";
+async function call(deps, key, method, path, body) {
+	try {
+		const res = await (deps.fetch ?? fetch)(new URL(path, cloudUrl(deps.env)), {
+			method,
+			headers: {
+				authorization: `Bearer ${key}`,
+				...body === void 0 ? {} : { "content-type": "application/json" }
+			},
+			body: body === void 0 ? void 0 : JSON.stringify(body),
+			signal: AbortSignal.timeout(3e4)
+		});
+		const text = await res.text();
+		let json = null;
+		try {
+			json = JSON.parse(text);
+		} catch {}
+		if (!res.ok) {
+			const err = json ?? {};
+			return {
+				ok: false,
+				status: res.status,
+				error: res.status === 401 ? "the secret key was rejected (check EVOLVE_SECRET_KEY)" : `HTTP ${res.status}${err.message ? `: ${err.message}` : err.error ? `: ${err.error}` : ""}`
+			};
+		}
+		return {
+			ok: true,
+			status: res.status,
+			json
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: `can't reach ${cloudUrl(deps.env)} (${e instanceof Error ? e.message : e})`
+		};
+	}
+}
+/** `GET /v1/site`: which site this key belongs to. Accepts the cloud's and the fake cloud's shapes. */
+async function getSiteInfo(deps, key) {
+	const r = await call(deps, key, "GET", "/v1/site");
+	if (!r.ok) return r;
+	const j = r.json;
+	return {
+		ok: true,
+		site: j.site && typeof j.site === "object" ? j.site : {
+			id: String(j.site ?? ""),
+			name: j.name ?? "",
+			appUrl: j.appUrl ?? null
+		}
+	};
+}
+/** `PUT /v1/site/app-url`. */
+async function putAppUrl(deps, key, appUrl) {
+	const r = await call(deps, key, "PUT", "/v1/site/app-url", { appUrl });
+	if (!r.ok) return r;
+	return {
+		ok: true,
+		appUrl: r.json.appUrl
+	};
+}
+/** `POST /v1/site/test`: the cloud pings the sync route and dry-runs an aggregate. */
+async function runCloudTest(deps, key) {
+	const r = await call(deps, key, "POST", "/v1/site/test");
+	if (!r.ok) return r;
+	const j = r.json;
+	return {
+		ok: true,
+		webhook: j.webhook,
+		aggregate: j.aggregate
+	};
+}
+export { cloudUrl, getSiteInfo, putAppUrl, runCloudTest };

package/dist/cli/connect.d.ts

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

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[];