@neondatabase/config 0.0.0

package/src/lib/auth.ts

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ErrorCode, PlatformError } from "./errors.js";
+import type { NeonApi } from "./neon-api.js";
+import { createRealNeonApi } from "./neon-api-real.js";
+
+/**
+ * Minimal shape of `~/.config/neonctl/credentials.json` we read. `neonctl` writes more
+ * fields (refresh_token, expires_at, …) but only `access_token` is what we need — it's a
+ * Bearer token the Neon API accepts on the same endpoints `napi_*` API keys do.
+ */
+export interface NeonctlCredentials {
+	access_token: string;
+	[key: string]: unknown;
+}
+
+/**
+ * Locate and read the OAuth credentials neonctl writes after `neon auth`.
+ *
+ * Resolution:
+ * 1. `options.configDir` (explicit override — mirrors neonctl's `--config-dir` flag).
+ * 2. `NEONCTL_CONFIG_DIR` environment variable.
+ * 3. `<home>/.config/neonctl/credentials.json` (the neonctl default; `home` reads
+ *    `HOME`, falling back to `USERPROFILE` for Windows parity).
+ *
+ * Returns `null` (never throws) when the file is missing, unreadable, malformed, or has
+ * no `access_token` — so callers can use this as a quiet fallback in a resolution chain
+ * without try/catch noise.
+ */
+export function readNeonctlCredentials(
+	options: { configDir?: string } = {},
+): NeonctlCredentials | null {
+	const home = process.env.HOME ?? process.env.USERPROFILE;
+	const configDir =
+		options.configDir ??
+		process.env.NEONCTL_CONFIG_DIR ??
+		(home ? resolve(home, ".config", "neonctl") : undefined);
+	if (!configDir) return null;
+
+	const credentialsPath = resolve(configDir, "credentials.json");
+	if (!existsSync(credentialsPath)) return null;
+
+	let raw: string;
+	try {
+		raw = readFileSync(credentialsPath, "utf-8");
+	} catch {
+		return null;
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+		return null;
+	const obj = parsed as Record<string, unknown>;
+	if (typeof obj.access_token !== "string" || obj.access_token === "")
+		return null;
+	return obj as NeonctlCredentials;
+}
+
+/**
+ * Resolution chain for the Bearer token sent to the Neon API. Each entry wins over the
+ * next:
+ *
+ * 1. `options.apiKey` (explicit).
+ * 2. `NEON_API_KEY` environment variable.
+ * 3. `access_token` from `~/.config/neonctl/credentials.json` (or `NEONCTL_CONFIG_DIR`).
+ *
+ * Returns `null` when no source provides one. Callers wrap the null case in a
+ * `PLATFORM_MISSING_API_KEY` error with a message tailored to the operation.
+ */
+export function resolveApiKey(
+	options: { apiKey?: string; configDir?: string } = {},
+): { token: string; source: "option" | "env" | "neonctl" } | null {
+	if (options.apiKey && options.apiKey.trim() !== "") {
+		return { token: options.apiKey.trim(), source: "option" };
+	}
+	const envKey = process.env.NEON_API_KEY;
+	if (typeof envKey === "string" && envKey.trim() !== "") {
+		return { token: envKey.trim(), source: "env" };
+	}
+	const creds = readNeonctlCredentials(
+		options.configDir ? { configDir: options.configDir } : {},
+	);
+	if (creds) {
+		return { token: creds.access_token, source: "neonctl" };
+	}
+	return null;
+}
+
+/**
+ * Resolve the Neon API key via the standard chain (option → `NEON_API_KEY` env →
+ * `~/.config/neonctl/credentials.json`) and construct a real {@link NeonApi} adapter from
+ * it, or throw a uniform `PLATFORM_MISSING_API_KEY` error if no key can be found.
+ *
+ * Used by `pullConfig`, `pushConfig`, `fetchEnv`, and `branch` to build their default
+ * `NeonApi` when the caller doesn't inject one. `operation` is the calling function's
+ * name (e.g. `"pushConfig"`, `"branch"`) — it's prepended to the error message so users
+ * can tell which call surfaced the missing key.
+ */
+export function createNeonApiFromOptions(
+	operation: string,
+	options: {
+		apiKey?: string;
+	} = {},
+): NeonApi {
+	const resolved = resolveApiKey(
+		options.apiKey ? { apiKey: options.apiKey } : {},
+	);
+	if (resolved) return createRealNeonApi({ apiKey: resolved.token });
+	throw new PlatformError(
+		ErrorCode.MissingApiKey,
+		[
+			`${operation} has no Neon API key to work with.`,
+			"Tried (in order): `apiKey` option, NEON_API_KEY env, and `~/.config/neonctl/credentials.json`.",
+			"Either pass `apiKey` directly, set NEON_API_KEY, run `npx neonctl auth` to populate the credentials file, or pass a custom `api` adapter (e.g. an in-memory fake for tests).",
+			"Generate a key at https://console.neon.tech/app/settings/api-keys.",
+		].join(" "),
+	);
+}

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

@@ -0,0 +1,161 @@
+import { describe, expect, test } from "vitest";
+import { defineConfig, resolveConfig } from "./define-config.js";
+import { ConfigValidationError } from "./errors.js";
+
+describe("defineConfig", () => {
+	test("accepts a branch policy function and preserves literal behavior", () => {
+		const config = defineConfig((branch) => {
+			if (branch.name === "main")
+				return { protected: true, auth: { enabled: true } };
+			return { parent: "main", ttl: "7d" };
+		});
+		expect(typeof config).toBe("function");
+		expect(config({ name: "main", exists: true })).toEqual({
+			protected: true,
+			auth: { enabled: true },
+		});
+	});
+
+	test("rejects object configs so project-level config is not accepted", () => {
+		expect(() => defineConfig({ project: { name: "x" } } as never)).toThrow(
+			ConfigValidationError,
+		);
+	});
+});
+
+describe("resolveConfig", () => {
+	test("normalizes branch policy output", () => {
+		const config = defineConfig(() => ({
+			parent: "main",
+			ttl: "1h",
+			protected: true,
+			postgres: { computeSettings: { autoscalingLimitMaxCu: 2 } },
+			auth: {},
+			dataApi: {},
+		}));
+		const resolved = resolveConfig(config, {
+			name: "dev-a",
+			exists: false,
+		});
+		expect(resolved).toMatchObject({
+			parent: "main",
+			ttlSeconds: 3600,
+			protected: true,
+			authEnabled: true,
+			dataApiEnabled: true,
+			postgres: { computeSettings: { autoscalingLimitMaxCu: 2 } },
+		});
+	});
+
+	test("treats explicit service false as disabled", () => {
+		const config = defineConfig(() => ({
+			auth: { enabled: false },
+			dataApi: { enabled: false },
+		}));
+		const resolved = resolveConfig(config, {
+			name: "dev-a",
+			exists: false,
+		});
+		expect(resolved.authEnabled).toBe(false);
+		expect(resolved.dataApiEnabled).toBe(false);
+	});
+
+	test("reports invalid returned branch config", () => {
+		const config = defineConfig(() => ({ parent: "preview-*" }));
+		expect(() =>
+			resolveConfig(config, { name: "dev", exists: false }),
+		).toThrow(ConfigValidationError);
+	});
+
+	test("resolves preview functions with deploy defaults and buckets with private access", () => {
+		const config = defineConfig(() => ({
+			preview: {
+				functions: [
+					{
+						name: "Hello World",
+						slug: "hello-world",
+						source: "./functions/hello-world.ts",
+						env: { RESEND_API_KEY: "re_abc" },
+					},
+				],
+				buckets: [{ name: "uploads" }],
+				aiGateway: { enabled: true },
+			},
+		}));
+		const resolved = resolveConfig(config, {
+			name: "preview-1",
+			exists: false,
+		});
+		expect(resolved.preview).toEqual({
+			functions: [
+				{
+					slug: "hello-world",
+					name: "Hello World",
+					source: "./functions/hello-world.ts",
+					env: { RESEND_API_KEY: "re_abc" },
+					runtime: "nodejs24",
+					memoryMib: 512,
+				},
+			],
+			buckets: [{ name: "uploads", access: "private" }],
+			aiGatewayEnabled: true,
+		});
+	});
+
+	test("treats aiGateway enabled:false as disabled", () => {
+		const config = defineConfig(() => ({
+			preview: { aiGateway: { enabled: false } },
+		}));
+		const resolved = resolveConfig(config, {
+			name: "preview-1",
+			exists: false,
+		});
+		expect(resolved.preview?.aiGatewayEnabled).toBe(false);
+	});
+
+	test("rejects a function env value that is undefined (e.g. unset process.env)", () => {
+		const config = defineConfig(() => ({
+			preview: {
+				functions: [
+					{
+						name: "Hello",
+						slug: "hello",
+						source: "./hello.ts",
+						// Simulates `RESEND_API_KEY: process.env.RESEND_API_KEY` when unset.
+						env: { RESEND_API_KEY: undefined as unknown as string },
+					},
+				],
+			},
+		}));
+		expect(() =>
+			resolveConfig(config, { name: "preview-1", exists: false }),
+		).toThrow(ConfigValidationError);
+	});
+
+	test("rejects an invalid function slug", () => {
+		const config = defineConfig(() => ({
+			preview: {
+				functions: [
+					{ name: "Bad", slug: "Hello World", source: "./x.ts" },
+				],
+			},
+		}));
+		expect(() =>
+			resolveConfig(config, { name: "preview-1", exists: false }),
+		).toThrow(ConfigValidationError);
+	});
+
+	test("rejects duplicate function slugs", () => {
+		const config = defineConfig(() => ({
+			preview: {
+				functions: [
+					{ name: "A", slug: "dup", source: "./a.ts" },
+					{ name: "B", slug: "dup", source: "./b.ts" },
+				],
+			},
+		}));
+		expect(() =>
+			resolveConfig(config, { name: "preview-1", exists: false }),
+		).toThrow(ConfigValidationError);
+	});
+});

package/src/lib/define-config.ts

@@ -0,0 +1,152 @@
+import { parseDuration } from "./duration.js";
+import { ConfigValidationError } from "./errors.js";
+import { branchConfigSchema, formatZodIssues } from "./schema.js";
+import type {
+	BranchTarget,
+	Config,
+	FunctionConfig,
+	PreviewConfig,
+	ResolvedBranchConfig,
+	ResolvedPreviewConfig,
+} from "./types.js";
+
+/** Default deploy parameters applied to functions that omit them in `neon.ts`. */
+const DEFAULT_FUNCTION_RUNTIME = "nodejs24" as const;
+const DEFAULT_FUNCTION_MEMORY_MIB = 512 as const;
+
+const REGION_PREFIX = /^(aws|azure|gcp)-/;
+
+/**
+ * Validate and freeze a Neon Platform branch policy.
+ *
+ * Used at the top of `neon.ts`:
+ * ```ts
+ * import { defineConfig } from "@neondatabase/config/v1";
+ *
+ * export default defineConfig((branch) => {
+ *   if (branch.name === "main") {
+ *     return { protected: true, auth: {} };
+ *   }
+ *   return { parent: "main", ttl: "7d" };
+ * });
+ * ```
+ *
+ * The `branch` parameter is a **read-only {@link BranchTarget} descriptor** of the branch
+ * this policy invocation is deciding for — not a live branch handle. You don't mutate it
+ * (`branch.protected = true` does nothing); you switch on its facts (`branch.name`,
+ * `branch.isDefault`, `branch.exists`, …) and **return** the desired {@link BranchConfig}.
+ * The same callback runs in two modes: against an existing branch (fields populated from
+ * Neon) and during pre-create evaluation (`exists: false`, `id` undefined).
+ *
+ * Pure function — no I/O, no side effects. The returned policy validates its output every
+ * time it is evaluated so errors point at the concrete branch target that triggered them.
+ */
+export function defineConfig<const C extends Config>(input: C): C {
+	if (typeof input !== "function") {
+		throw new ConfigValidationError([
+			"defineConfig expects a function: `export default defineConfig((branch) => ({ ... }))`.",
+			"Project-level config has moved to `neonctl link`; neon.ts now describes branch-level policy only.",
+		]);
+	}
+
+	return Object.freeze(input) as C;
+}
+
+/**
+ * Evaluate a branch policy for a specific branch target and return a normalized config.
+ */
+export function resolveConfig(
+	config: Config,
+	branch: BranchTarget,
+): ResolvedBranchConfig {
+	let raw: unknown;
+	try {
+		raw = config(Object.freeze({ ...branch }));
+	} catch (cause) {
+		throw new ConfigValidationError([
+			`Config function threw while evaluating branch "${branch.name}".`,
+			(cause as Error)?.message ?? String(cause),
+		]);
+	}
+
+	const parsed = branchConfigSchema.safeParse(raw);
+	if (!parsed.success) {
+		throw new ConfigValidationError(formatZodIssues(parsed.error));
+	}
+
+	const cfg = parsed.data;
+	const issues: string[] = [];
+	let ttlSeconds: number | undefined;
+	if (cfg.ttl !== undefined) {
+		const parsedTtl = parseDuration(cfg.ttl);
+		if ("error" in parsedTtl) {
+			issues.push(`ttl: ${parsedTtl.error}`);
+		} else {
+			ttlSeconds = parsedTtl.seconds;
+		}
+	}
+	if (issues.length > 0) {
+		throw new ConfigValidationError(issues);
+	}
+
+	const resolved: ResolvedBranchConfig = {
+		authEnabled: isServiceEnabled(cfg.auth),
+		dataApiEnabled: isServiceEnabled(cfg.dataApi),
+	};
+	if (cfg.parent !== undefined) resolved.parent = cfg.parent;
+	if (ttlSeconds !== undefined) resolved.ttlSeconds = ttlSeconds;
+	if (cfg.protected !== undefined) resolved.protected = cfg.protected;
+	if (cfg.postgres) {
+		resolved.postgres = {
+			...(cfg.postgres.computeSettings
+				? { computeSettings: { ...cfg.postgres.computeSettings } }
+				: {}),
+		};
+	}
+	if (cfg.preview) {
+		resolved.preview = resolvePreviewConfig(cfg.preview);
+	}
+	return resolved;
+}
+
+function isServiceEnabled(service: { enabled?: boolean } | undefined): boolean {
+	return service !== undefined && service.enabled !== false;
+}
+
+/**
+ * Normalize a {@link PreviewConfig} into a {@link ResolvedPreviewConfig}: apply per-function
+ * deploy defaults, default each bucket's access level to `private`, and collapse the
+ * `aiGateway` toggle to a boolean using the same present-and-not-`false` rule as
+ * `auth` / `dataApi`.
+ */
+function resolvePreviewConfig(preview: PreviewConfig): ResolvedPreviewConfig {
+	return {
+		functions: (preview.functions ?? []).map(resolveFunctionConfig),
+		buckets: (preview.buckets ?? []).map((bucket) => ({
+			name: bucket.name,
+			access: bucket.access ?? "private",
+		})),
+		aiGatewayEnabled: isServiceEnabled(preview.aiGateway),
+	};
+}
+
+function resolveFunctionConfig(fn: FunctionConfig) {
+	return {
+		slug: fn.slug,
+		name: fn.name,
+		source: fn.source,
+		env: { ...(fn.env ?? {}) },
+		runtime: fn.runtime ?? DEFAULT_FUNCTION_RUNTIME,
+		memoryMib: fn.memoryMib ?? DEFAULT_FUNCTION_MEMORY_MIB,
+	};
+}
+
+/**
+ * Normalize a region identifier to Neon's `<cloud>-<region>` format. When the user writes
+ * `us-east-1` we assume `aws-us-east-1`. Pure helper used by both the validator and the
+ * NeonApi adapter.
+ */
+export function normalizeRegion(region: string): string {
+	if (REGION_PREFIX.test(region)) return region;
+	return `aws-${region}`;
+}

package/src/lib/diff.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, test } from "vitest";
+import { diffConfig, type RemoteState } from "./diff.js";
+
+describe("diffConfig", () => {
+	const remote: RemoteState = {
+		projectId: "proj",
+		branch: {
+			id: "br-main",
+			name: "main",
+			isDefault: true,
+			protected: false,
+		},
+		endpoint: {
+			id: "ep",
+			branchId: "br-main",
+			type: "read_write" as const,
+			autoscalingLimitMinCu: 0.25,
+			autoscalingLimitMaxCu: 1,
+			suspendTimeout: "5m",
+		},
+		services: {
+			databaseName: "neondb",
+			authEnabled: false,
+			dataApiEnabled: false,
+		},
+	};
+
+	test("plans service enables", () => {
+		const diff = diffConfig(
+			{ authEnabled: true, dataApiEnabled: true },
+			remote,
+			{ updateExisting: false },
+		);
+		expect(diff.plan.map((p) => p.kind)).toEqual([
+			"enable-auth",
+			"enable-data-api",
+		]);
+	});
+
+	test("reports compute drift unless updateExisting is set", () => {
+		const diff = diffConfig(
+			{
+				authEnabled: false,
+				dataApiEnabled: false,
+				postgres: { computeSettings: { autoscalingLimitMaxCu: 2 } },
+			},
+			remote,
+			{ updateExisting: false },
+		);
+		expect(diff.conflicts[0]).toMatchObject({ field: "computeSettings" });
+	});
+
+	test("plans mutable branch updates with updateExisting", () => {
+		const diff = diffConfig(
+			{ authEnabled: false, dataApiEnabled: false, protected: true },
+			remote,
+			{ updateExisting: true },
+		);
+		expect(diff.plan[0]).toMatchObject({
+			kind: "update-branch-protected",
+			branchId: "br-main",
+		});
+	});
+
+	test("plans preview create + deploy + bucket + ai-gateway when nothing exists", () => {
+		const diff = diffConfig(
+			{
+				authEnabled: false,
+				dataApiEnabled: false,
+				preview: {
+					functions: [
+						{
+							slug: "hello-world",
+							name: "Hello World",
+							source: "./hello.ts",
+							env: {},
+							runtime: "nodejs24",
+							memoryMib: 512,
+						},
+					],
+					buckets: [{ name: "uploads", access: "private" }],
+					aiGatewayEnabled: true,
+				},
+			},
+			{
+				...remote,
+				preview: {
+					buckets: [],
+					functions: [],
+					aiGatewayEnabled: false,
+				},
+			},
+			{ updateExisting: false },
+		);
+		expect(diff.plan.map((p) => p.kind)).toEqual([
+			"create-bucket",
+			"create-function",
+			"deploy-function",
+			"enable-ai-gateway",
+		]);
+	});
+
+	test("skips create-function and skips enable-ai-gateway when already present, but still re-deploys", () => {
+		const diff = diffConfig(
+			{
+				authEnabled: false,
+				dataApiEnabled: false,
+				preview: {
+					functions: [
+						{
+							slug: "hello-world",
+							name: "Hello World",
+							source: "./hello.ts",
+							env: {},
+							runtime: "nodejs24",
+							memoryMib: 512,
+						},
+					],
+					buckets: [{ name: "uploads", access: "private" }],
+					aiGatewayEnabled: true,
+				},
+			},
+			{
+				...remote,
+				preview: {
+					buckets: [{ name: "uploads", accessLevel: "private" }],
+					functions: [
+						{
+							id: "fn-1",
+							slug: "hello-world",
+							name: "Hello World",
+							invocationUrl: "https://x/functions/hello-world",
+						},
+					],
+					aiGatewayEnabled: true,
+				},
+			},
+			{ updateExisting: false },
+		);
+		expect(diff.plan.map((p) => p.kind)).toEqual(["deploy-function"]);
+	});
+});