@neondatabase/config-runtime 0.0.0

package/src/lib/function-bundle.test.ts

@@ -0,0 +1,60 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ResolvedFunctionConfig } from "@neondatabase/config";
+import { unzipSync } from "fflate";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { buildFunctionBundle } from "./function-bundle.js";
+
+let dir: string;
+beforeAll(() => {
+	dir = mkdtempSync(join(tmpdir(), "neon-bundle-"));
+});
+afterAll(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+function fn(source: string): ResolvedFunctionConfig {
+	return {
+		slug: "hello-world",
+		name: "Hello World",
+		source,
+		env: {},
+		runtime: "nodejs24",
+		memoryMib: 512,
+	};
+}
+
+describe("buildFunctionBundle", () => {
+	test("bundles a handler with esbuild and returns a ZIP containing out.js + sourcemap", async () => {
+		const helper = join(dir, "shared.ts");
+		writeFileSync(helper, "export const greeting = 'hello from neon';\n");
+		const source = join(dir, "hello-world.ts");
+		// Importing a sibling proves esbuild actually *bundles* (not just copies) the entry.
+		writeFileSync(
+			source,
+			[
+				"import { greeting } from './shared.js';",
+				"export default { fetch(_req: Request): Response { return new Response(greeting); } };",
+			].join("\n"),
+		);
+
+		const bundle = await buildFunctionBundle(fn(source));
+		expect(bundle.byteLength).toBeGreaterThan(0);
+
+		const files = unzipSync(bundle);
+		const names = Object.keys(files).sort();
+		expect(names).toContain("out.js");
+		expect(names).toContain("out.js.map");
+
+		// The bundled output should have inlined the imported constant.
+		const js = new TextDecoder().decode(files["out.js"]);
+		expect(js).toContain("hello from neon");
+	});
+
+	test("throws a PlatformError when the source cannot be resolved", async () => {
+		await expect(
+			buildFunctionBundle(fn(join(dir, "does-not-exist.ts"))),
+		).rejects.toThrow(/Failed to bundle function "hello-world"/);
+	});
+});

package/src/lib/function-bundle.ts

@@ -0,0 +1,104 @@
+import { basename } from "node:path";
+import {
+	ErrorCode,
+	PlatformError,
+	type ResolvedFunctionConfig,
+} from "@neondatabase/config";
+
+/**
+ * Build the deployable bundle (a ZIP archive of the esbuild-bundled source) for a function.
+ *
+ * This is the **imperative shell** step of function deploys, and the reason it lives in
+ * `@neondatabase/config-runtime` rather than `@neondatabase/config`: it pulls in `esbuild`
+ * (a native binary) and `fflate`. Keeping it out of `@neondatabase/config` means a `neon.ts`
+ * that only imports `defineConfig` never drags esbuild into the user's dependency tree or
+ * bundle. Deploy-side consumers (the neonctl CLI, CI) import this package and get esbuild as
+ * a normal, auto-installed dependency.
+ *
+ * esbuild and fflate are loaded with a dynamic `import()` (not a static top-level import) so
+ * that nothing in this package's static graph names esbuild until a deploy actually runs —
+ * a second layer of protection on top of the package split.
+ *
+ * Mirrors: `esbuild <source> --bundle --outfile=out.js --sourcemap --minify`, then zips the
+ * emitted files into the archive the Functions deploy endpoint expects.
+ */
+export async function buildFunctionBundle(
+	fn: ResolvedFunctionConfig,
+): Promise<Uint8Array> {
+	const esbuild = await loadEsbuild();
+
+	let result: Awaited<ReturnType<typeof esbuild.build>>;
+	try {
+		result = await esbuild.build({
+			entryPoints: [fn.source],
+			bundle: true,
+			write: false,
+			// Set an explicit outfile so the emitted files are named `out.js` / `out.js.map`
+			// (with `write: false` and no outfile, esbuild labels the buffer `<stdout>`).
+			outfile: "out.js",
+			sourcemap: true,
+			minify: true,
+			format: "esm",
+			platform: "node",
+			// The Functions runtime provides Node built-ins; don't try to bundle them.
+			packages: "external",
+			logLevel: "silent",
+		});
+	} catch (cause) {
+		throw new PlatformError(
+			ErrorCode.InvalidConfig,
+			[
+				`Failed to bundle function "${fn.slug}" from ${fn.source}.`,
+				(cause as Error)?.message ?? String(cause),
+			].join(" "),
+			{ cause },
+		);
+	}
+
+	const entries: Record<string, Uint8Array> = {};
+	// `write: false` guarantees `outputFiles`, but the type is optional — guard for safety.
+	for (const file of result.outputFiles ?? []) {
+		// esbuild returns absolute output paths; archive them under their basename
+		// (`out.js`, `out.js.map`) so the bundle layout is stable regardless of cwd.
+		entries[basename(file.path)] = file.contents;
+	}
+
+	return zipBundle(entries);
+}
+
+async function zipBundle(
+	entries: Record<string, Uint8Array>,
+): Promise<Uint8Array> {
+	const { zipSync } = await loadFflate();
+	return zipSync(entries, { level: 6 });
+}
+
+async function loadEsbuild(): Promise<typeof import("esbuild")> {
+	try {
+		return await import("esbuild");
+	} catch (cause) {
+		throw new PlatformError(
+			ErrorCode.InvalidConfig,
+			[
+				"Deploying Neon Functions requires `esbuild`, which could not be loaded.",
+				"It is a dependency of @neondatabase/config-runtime — reinstall your dependencies (`pnpm install` / `npm install`).",
+			].join(" "),
+			{ cause },
+		);
+	}
+}
+
+async function loadFflate(): Promise<typeof import("fflate")> {
+	try {
+		return await import("fflate");
+	} catch (cause) {
+		throw new PlatformError(
+			ErrorCode.InvalidConfig,
+			[
+				"Deploying Neon Functions requires `fflate`, which could not be loaded.",
+				"It is a dependency of @neondatabase/config-runtime — reinstall your dependencies (`pnpm install` / `npm install`).",
+			].join(" "),
+			{ cause },
+		);
+	}
+}

package/src/lib/operations.test.ts

@@ -0,0 +1,150 @@
+import { defineConfig, ErrorCode } from "@neondatabase/config";
+import { describe, expect, test } from "vitest";
+import { FakeNeonApi } from "./fake-neon-api.js";
+import { apply, inspect, plan } from "./operations.js";
+
+function seededFake(opts?: { protected?: boolean }) {
+	const api = new FakeNeonApi();
+	const projectId = "proj-ops";
+	api.seedProject({
+		project: {
+			id: projectId,
+			name: "ops-test",
+			regionId: "aws-us-east-1",
+			pgVersion: 17,
+			orgId: "org-ops",
+		},
+		branches: [
+			{
+				branch: {
+					id: "br-main",
+					name: "main",
+					isDefault: true,
+					protected: opts?.protected ?? false,
+				},
+			},
+		],
+	});
+	return { api, projectId };
+}
+
+describe("inspect", () => {
+	test("returns the selected branch's live state", async () => {
+		const { api, projectId } = seededFake();
+		const result = await inspect({ api, projectId, branchId: "br-main" });
+		expect(result.project.name).toBe("ops-test");
+		expect(result.branch.name).toBe("main");
+		expect(result.config).toBeDefined();
+	});
+});
+
+describe("plan", () => {
+	test("computes a dry-run plan without mutating", async () => {
+		const { api, projectId } = seededFake();
+		const config = defineConfig(() => ({ auth: {} }));
+		const result = await plan(config, {
+			api,
+			projectId,
+			branchId: "br-main",
+		});
+		expect(result.dryRun).toBe(true);
+		expect(result.applied).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					kind: "service",
+					identifier: "auth",
+				}),
+			]),
+		);
+		// No mutation happened: a fresh plan still shows the same enable.
+		const again = await plan(config, {
+			api,
+			projectId,
+			branchId: "br-main",
+		});
+		expect(again.applied).toEqual(result.applied);
+	});
+});
+
+describe("apply", () => {
+	test("applies the branch policy to the selected branch", async () => {
+		const { api, projectId } = seededFake();
+		const config = defineConfig(() => ({ auth: {} }));
+		const result = await apply(config, {
+			api,
+			projectId,
+			branchId: "br-main",
+			updateExisting: true,
+		});
+		expect(result.dryRun).toBe(false);
+		expect(result.applied).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					kind: "service",
+					identifier: "auth",
+				}),
+			]),
+		);
+	});
+
+	test("surfaces drift as a PushConflictError without updateExisting", async () => {
+		const { api, projectId } = seededFake();
+		const config = defineConfig(() => ({
+			postgres: { computeSettings: { autoscalingLimitMaxCu: 4 } },
+		}));
+		await expect(
+			apply(config, { api, projectId, branchId: "br-main" }),
+		).rejects.toMatchObject({ code: ErrorCode.PushConflict });
+	});
+
+	test("applies drift to a protected branch with both override flags", async () => {
+		const { api, projectId } = seededFake({ protected: true });
+		const config = defineConfig(() => ({
+			postgres: { computeSettings: { autoscalingLimitMaxCu: 4 } },
+		}));
+		const result = await apply(config, {
+			api,
+			projectId,
+			branchId: "br-main",
+			updateExisting: true,
+			allowProtectedBranch: true,
+		});
+		expect(result.dryRun).toBe(false);
+		expect(api.history.some((h) => h.method === "updateEndpoint")).toBe(
+			true,
+		);
+	});
+});
+
+describe("branch not found (id-only lookup)", () => {
+	test("inspect throws BranchNotFound for an unknown id", async () => {
+		const { api, projectId } = seededFake();
+		await expect(
+			inspect({ api, projectId, branchId: "br-does-not-exist" }),
+		).rejects.toMatchObject({ code: ErrorCode.BranchNotFound });
+	});
+
+	test("plan throws BranchNotFound for an unknown id", async () => {
+		const { api, projectId } = seededFake();
+		const config = defineConfig(() => ({}));
+		await expect(
+			plan(config, { api, projectId, branchId: "br-does-not-exist" }),
+		).rejects.toMatchObject({ code: ErrorCode.BranchNotFound });
+	});
+
+	test("apply throws BranchNotFound for an unknown id", async () => {
+		const { api, projectId } = seededFake();
+		const config = defineConfig(() => ({}));
+		await expect(
+			apply(config, { api, projectId, branchId: "br-does-not-exist" }),
+		).rejects.toMatchObject({ code: ErrorCode.BranchNotFound });
+	});
+
+	test("inspect rejects a branch name (ids only)", async () => {
+		const { api, projectId } = seededFake();
+		// "main" is the branch NAME; lookups match by id only, so this must fail.
+		await expect(
+			inspect({ api, projectId, branchId: "main" }),
+		).rejects.toMatchObject({ code: ErrorCode.BranchNotFound });
+	});
+});

package/src/lib/operations.ts

@@ -0,0 +1,103 @@
+import type { Config, PushResult } from "@neondatabase/config";
+import { type PulledBranchConfig, pullConfig } from "./pull-config.js";
+import { type PushConfigOptions, pushConfig } from "./push-config.js";
+
+/**
+ * Where to run the operation and how to authenticate. Filesystem- and env-agnostic: the
+ * `projectId` and `branchId` are always passed explicitly by the caller (e.g. neonctl
+ * resolves them from `.neon` / `NEON_*` and forwards them here).
+ */
+export interface ConfigOperationOptions {
+	/**
+	 * Neon project id. **Required** — the management API addresses branches through their
+	 * project, so operations cannot run without it.
+	 */
+	projectId: string;
+	/**
+	 * Neon branch id (`br-…`). **Required.** Must already exist on the project; resolve
+	 * branch names to ids before calling.
+	 */
+	branchId: string;
+	/** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. */
+	apiKey?: string;
+	/** Inject a custom NeonApi adapter (primarily for tests). */
+	api?: PushConfigOptions["api"];
+}
+
+/**
+ * Options accepted by {@link apply} on top of {@link ConfigOperationOptions}.
+ */
+export interface ApplyOptions extends ConfigOperationOptions {
+	/**
+	 * Auto-confirm overriding existing remote settings (TTL, `protected`, compute
+	 * settings) on the selected branch. Without it, drift is reported as a conflict.
+	 */
+	updateExisting?: boolean;
+	/** Auto-confirm applying to a branch marked `protected` on Neon. */
+	allowProtectedBranch?: boolean;
+}
+
+/**
+ * Read a branch's live Neon state as a plain object (project + branch metadata and the
+ * reverse-engineered `BranchConfig`). Network read only — never mutates.
+ *
+ * `projectId` and `branchId` are **required** (both in `options`).
+ */
+export async function inspect(
+	options: ConfigOperationOptions,
+): Promise<PulledBranchConfig> {
+	return pullConfig({
+		projectId: options.projectId,
+		branchId: options.branchId,
+		...(options.api ? { api: options.api } : {}),
+		...(options.apiKey ? { apiKey: options.apiKey } : {}),
+	});
+}
+
+/**
+ * Compute what {@link apply} would do for the given branch without mutating anything
+ * (dry-run plan). Returns the full {@link PushResult} with the planned changes in
+ * `applied` and any blocking drift in `conflicts` — the Neon equivalent of
+ * `terraform plan`.
+ *
+ * `projectId` and `branchId` are **required** (both in `options`).
+ */
+export async function plan(
+	config: Config,
+	options: ConfigOperationOptions,
+): Promise<PushResult> {
+	return pushConfig(config, {
+		projectId: options.projectId,
+		branchId: options.branchId,
+		dryRun: true,
+		// Surface the full would-apply list as plan steps without mutating anything.
+		updateExisting: true,
+		...(options.api ? { api: options.api } : {}),
+		...(options.apiKey ? { apiKey: options.apiKey } : {}),
+	});
+}
+
+/**
+ * Apply a `neon.ts` policy to the given Neon branch and return the {@link PushResult}
+ * describing what changed — the Neon equivalent of `terraform apply`.
+ *
+ * `projectId` and `branchId` are **required** (both in `options`). Pass `updateExisting`
+ * to auto-confirm overriding existing remote settings and `allowProtectedBranch` to
+ * auto-confirm applying to a protected branch; otherwise drift is reported as a
+ * `PushConflictError`.
+ *
+ * Never creates projects or branches — both must already exist.
+ */
+export async function apply(
+	config: Config,
+	options: ApplyOptions,
+): Promise<PushResult> {
+	return pushConfig(config, {
+		projectId: options.projectId,
+		branchId: options.branchId,
+		...(options.api ? { api: options.api } : {}),
+		...(options.apiKey ? { apiKey: options.apiKey } : {}),
+		...(options.updateExisting ? { updateExisting: true } : {}),
+		...(options.allowProtectedBranch ? { allowProtectedBranch: true } : {}),
+	});
+}

package/src/lib/pull-config.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "vitest";
+import { FakeNeonApi } from "./fake-neon-api.js";
+import { pullConfig } from "./pull-config.js";
+
+describe("pullConfig", () => {
+	test("returns selected branch state as JSON-friendly branch config", async () => {
+		const api = new FakeNeonApi();
+		const projectId = "proj-pull";
+		api.seedProject({
+			project: {
+				id: projectId,
+				name: "pull-test",
+				regionId: "aws-us-east-1",
+				pgVersion: 17,
+				orgId: "org-pull",
+			},
+			branches: [
+				{ branch: { id: "br-main", name: "main", isDefault: true } },
+				{
+					branch: {
+						id: "br-dev",
+						name: "dev-a",
+						isDefault: false,
+						parentId: "br-main",
+						protected: true,
+					},
+					endpoint: { autoscalingLimitMaxCu: 2 },
+				},
+			],
+		});
+
+		const pulled = await pullConfig({ api, projectId, branchId: "br-dev" });
+
+		expect(pulled.project).toMatchObject({
+			id: projectId,
+			name: "pull-test",
+			orgId: "org-pull",
+		});
+		expect(pulled.branch).toMatchObject({
+			id: "br-dev",
+			name: "dev-a",
+			parent: "main",
+			protected: true,
+		});
+		expect(pulled.config).toMatchObject({
+			parent: "main",
+			protected: true,
+			postgres: { computeSettings: { autoscalingLimitMaxCu: 2 } },
+		});
+	});
+});

package/src/lib/pull-config.ts

@@ -0,0 +1,215 @@
+import {
+	type BranchConfig,
+	type BucketConfig,
+	type ComputeSettings,
+	createNeonApiFromOptions,
+	ErrorCode,
+	type NeonApi,
+	type NeonBranchSnapshot,
+	type NeonBucketSnapshot,
+	type NeonEndpointSnapshot,
+	type NeonFunctionSnapshot,
+	type NeonProjectSnapshot,
+	PlatformError,
+} from "@neondatabase/config";
+
+export interface PullConfigOptions {
+	/** Neon project id (`<project>`). Required — the API addresses branches by project. */
+	projectId: string;
+	/** Neon branch id (`br-…`). Required. Resolve names to ids before calling. */
+	branchId: string;
+	/** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. */
+	apiKey?: string;
+	/** Inject a custom NeonApi adapter (primarily for tests). */
+	api?: NeonApi;
+}
+
+/**
+ * Live Preview-feature state read back from a branch. Surfaced alongside `config` rather
+ * than inside it because functions cannot round-trip: the remote only knows the deployed
+ * bundle, not the local `source` path a {@link FunctionConfig} requires, so a pulled
+ * function is reported as `{ slug, name }` (no `source`).
+ */
+export interface PulledPreview {
+	buckets: BucketConfig[];
+	functions: Array<{ slug: string; name: string }>;
+	aiGatewayEnabled: boolean;
+}
+
+export interface PulledBranchConfig {
+	project: {
+		id: string;
+		name: string;
+		region: string;
+		pgVersion: number;
+		orgId?: string;
+	};
+	branch: {
+		id: string;
+		name: string;
+		parent?: string;
+		isDefault: boolean;
+		protected: boolean;
+		expiresAt?: string;
+	};
+	config: BranchConfig;
+	/**
+	 * Live Preview-feature state, when the branch has any buckets/functions or an enabled
+	 * AI Gateway. Omitted entirely when there is nothing to report.
+	 */
+	preview?: PulledPreview;
+}
+
+export async function pullConfig(
+	options: PullConfigOptions,
+): Promise<PulledBranchConfig> {
+	const api = options.api ?? createApiFromOptions(options);
+	const projectId = options.projectId;
+	const project = await api.getProject(projectId);
+	const [branches, endpoints] = await Promise.all([
+		api.listBranches(projectId),
+		api.listEndpoints(projectId),
+	]);
+	const branch = resolveBranch(options.branchId, branches);
+	const endpoint = endpoints.find(
+		(ep) => ep.type === "read_write" && ep.branchId === branch.id,
+	);
+	const [buckets, functions, aiGatewayEnabled] = await Promise.all([
+		api.listBranchBuckets(projectId, branch.id),
+		api.listBranchFunctions(projectId, branch.id),
+		api.getAiGatewayEnabled(projectId, branch.id),
+	]);
+	return buildPulledBranchConfig(project, branch, branches, endpoint, {
+		buckets,
+		functions,
+		aiGatewayEnabled,
+	});
+}
+
+function createApiFromOptions(options: PullConfigOptions): NeonApi {
+	return createNeonApiFromOptions("pullConfig", {
+		...(options.apiKey ? { apiKey: options.apiKey } : {}),
+	});
+}
+
+export function buildPulledBranchConfig(
+	project: NeonProjectSnapshot,
+	branch: NeonBranchSnapshot,
+	branches: NeonBranchSnapshot[],
+	endpoint: NeonEndpointSnapshot | undefined,
+	previewState?: {
+		buckets: NeonBucketSnapshot[];
+		functions: NeonFunctionSnapshot[];
+		aiGatewayEnabled: boolean;
+	},
+): PulledBranchConfig {
+	const parent = branch.parentId
+		? branches.find((b) => b.id === branch.parentId)
+		: undefined;
+	const config: BranchConfig = {};
+	if (parent) config.parent = parent.name;
+	if (branch.expiresAt) config.ttl = branch.expiresAt;
+	if (branch.protected) config.protected = true;
+	if (endpoint) {
+		const compute = endpointToComputeSettings(endpoint, project);
+		if (compute) config.postgres = { computeSettings: compute };
+	}
+	const result: PulledBranchConfig = {
+		project: {
+			id: project.id,
+			name: project.name,
+			region: project.regionId,
+			pgVersion: project.pgVersion,
+			...(project.orgId ? { orgId: project.orgId } : {}),
+		},
+		branch: {
+			id: branch.id,
+			name: branch.name,
+			...(parent ? { parent: parent.name } : {}),
+			isDefault: branch.isDefault,
+			protected: branch.protected,
+			...(branch.expiresAt ? { expiresAt: branch.expiresAt } : {}),
+		},
+		config,
+	};
+	const preview = previewState ? buildPulledPreview(previewState) : undefined;
+	if (preview) result.preview = preview;
+	return result;
+}
+
+/**
+ * Reverse-engineer the {@link PulledPreview} from remote snapshots. Returns `undefined` when
+ * the branch has no Preview features so the field can be omitted entirely.
+ */
+function buildPulledPreview(state: {
+	buckets: NeonBucketSnapshot[];
+	functions: NeonFunctionSnapshot[];
+	aiGatewayEnabled: boolean;
+}): PulledPreview | undefined {
+	if (
+		state.buckets.length === 0 &&
+		state.functions.length === 0 &&
+		!state.aiGatewayEnabled
+	) {
+		return undefined;
+	}
+	return {
+		buckets: state.buckets.map((b) => ({
+			name: b.name,
+			access: b.accessLevel,
+		})),
+		functions: state.functions.map((f) => ({
+			slug: f.slug,
+			name: f.name,
+		})),
+		aiGatewayEnabled: state.aiGatewayEnabled,
+	};
+}
+
+function resolveBranch(
+	branchId: string,
+	branches: NeonBranchSnapshot[],
+): NeonBranchSnapshot {
+	const match = branches.find((b) => b.id === branchId);
+	if (match) return match;
+	throw new PlatformError(
+		ErrorCode.BranchNotFound,
+		[
+			`pullConfig: branch id ${JSON.stringify(branchId)} not found on project.`,
+			`Available branches: ${branches.map((b) => `${b.name} (${b.id})`).join(", ") || "(none)"}.`,
+		].join(" "),
+		{
+			details: {
+				branchId,
+				available: branches.map((b) => b.id),
+			},
+		},
+	);
+}
+
+function endpointToComputeSettings(
+	endpoint: NeonEndpointSnapshot,
+	project: NeonProjectSnapshot,
+): ComputeSettings | undefined {
+	const defaults = project.defaultEndpointSettings;
+	const out: ComputeSettings = {};
+	if (
+		endpoint.autoscalingLimitMinCu !== undefined &&
+		endpoint.autoscalingLimitMinCu !== defaults?.autoscalingLimitMinCu
+	) {
+		out.autoscalingLimitMinCu = endpoint.autoscalingLimitMinCu;
+	}
+	if (
+		endpoint.autoscalingLimitMaxCu !== undefined &&
+		endpoint.autoscalingLimitMaxCu !== defaults?.autoscalingLimitMaxCu
+	) {
+		out.autoscalingLimitMaxCu = endpoint.autoscalingLimitMaxCu;
+	}
+	if (
+		endpoint.suspendTimeout !== undefined &&
+		endpoint.suspendTimeout !== defaults?.suspendTimeout
+	) {
+		out.suspendTimeout = endpoint.suspendTimeout;
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}