@neondatabase/config-runtime 0.0.0 → 0.1.0

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

@@ -1,60 +0,0 @@
-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

@@ -1,104 +0,0 @@
-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

@@ -1,150 +0,0 @@
-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

@@ -1,103 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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

@@ -1,215 +0,0 @@
-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;
-}