@neondatabase/config 0.0.0

package/.env.example

@@ -0,0 +1,5 @@
+# Copy to `.env` and fill in real values. `.env` itself is gitignored.
+# Required to run `pnpm --filter @neondatabase/config test:e2e`.
+NEON_API_KEY=
+# Optional. When set, e2e tests scope project creation/listing to this org.
+NEON_ORG_ID=

package/README.md

@@ -0,0 +1,92 @@
+# @neondatabase/config
+
+Config-as-Code for the Neon Platform. A repo-local `neon.ts` exports a TypeScript policy function describing a branch's desired state. This package exposes **functions** to inspect, diff, and deploy that policy against the Neon API.
+
+> No CLI commands ship here, and the package is **filesystem- and env-agnostic**: it never reads `.neon` files or `NEON_*` environment variables. You pass `projectId` and the target branch explicitly (resolve them in your CLI, e.g. neonctl). This package is functions only.
+
+## Install
+
+```bash
+npm install @neondatabase/config
+```
+
+## Define a policy
+
+```ts
+// neon.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` argument is a **read-only descriptor** (`BranchTarget`) of the branch this policy is being evaluated for — `name`, `id`, `exists`, `isDefault`, `isProtected`, `parentId`, `expiresAt`. It is not a live branch handle: don't mutate it, just switch on its fields and **return** the desired config. The same callback runs both against existing branches and during pre-create evaluation (`exists: false`).
+
+`parent` and `ttl` are branch lifecycle fields. Product-specific settings live under product namespaces such as `postgres`, `auth`, and `dataApi`.
+
+## Functions
+
+The three operations mirror the Terraform mental model: **`inspect`** (read live state), **`plan`** (dry-run diff), **`apply`** (reconcile).
+
+`projectId` and `branchId` are **required** — there is no `.neon`/env fallback. (`projectId` is required because the Neon management API addresses every branch through its project; deriving it from a branch id would need an extra discovery round-trip.)
+
+```ts
+import config from "../neon";
+import { inspect, plan, apply } from "@neondatabase/config/v1";
+
+const target = { projectId: "patient-art-12345", branchId: "main" };
+
+// Dry-run: what would apply do for this branch? No mutations.
+const diff = await plan(config, target);
+
+// Apply the policy to a branch. Never creates projects/branches.
+await apply(config, { ...target, updateExisting: true });
+
+// Read a branch's live Neon state as a plain object.
+const live = await inspect(target);
+```
+
+| Function | Description |
+| --- | --- |
+| `inspect(options)` | Returns the branch's live Neon state (project + branch metadata and a reverse-engineered `BranchConfig`). Read-only. |
+| `plan(config, options)` | Returns the dry-run diff — what `apply` would do for the branch, with no mutations. Returns a `PushResult` whose `applied` holds the plan and `conflicts` holds blocking drift. |
+| `apply(config, options)` | Reconciles your local `neon.ts` policy onto the branch. Pass `updateExisting` to auto-confirm overriding existing remote settings and `allowProtectedBranch` to auto-confirm applying to a protected branch. |
+
+`options` requires both `projectId` and `branchId` (a Neon branch id, `br-…`). Resolve branch names to ids before calling. The Neon API key resolves via the `apiKey` option → `NEON_API_KEY` → `~/.config/neonctl/credentials.json`.
+
+## Lower-level engine
+
+`inspect` / `plan` / `apply` are thin wrappers over `pullConfig(options)` / `pushConfig(config, options)` (both require `projectId` + `branchId`), which are also exported for advanced/programmatic use along with `defineConfig`, `loadConfigFromFile` (optional `neon.ts` loader), `createRealNeonApi`, the `PlatformError` base class + `ErrorCode` enum, the `errors` and `schemas` namespaces, and the supporting types.
+
+```ts
+import {
+  defineConfig,
+  inspect,
+  plan,
+  apply,
+  pushConfig,
+  pullConfig,
+  loadConfigFromFile,
+  createRealNeonApi,
+  resolveApiKey,
+  PlatformError,
+  ErrorCode,
+  errors,
+  schemas,
+} from "@neondatabase/config/v1";
+```
+
+## Safety Rules
+
+- `apply` / `pushConfig` never creates projects or branches.
+- `auth: {}` and `dataApi: {}` enable those integrations with Neon defaults. `auth.enabled: false`, `dataApi.enabled: false`, or absence leaves existing integrations alone. Disabling is destructive and remains explicit/manual.
+- Mutable branch drift (`protected`, `ttl`, `postgres.computeSettings`) is reported as a conflict unless `updateExisting` is passed (or a `confirm` callback is supplied to `pushConfig`).
+- Applying to a branch with the `protected` flag set on Neon requires `allowProtectedBranch` (or a `confirm` callback).
+
+## Env vars
+
+Connection-string resolution/injection lives in the companion package [`@neondatabase/env`](../env), which depends on this package for the `Config` type and the Neon API client.

package/e2e/errors.e2e.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect } from "vitest";
+import { createRealNeonApi, ErrorCode, type PlatformError } from "../src/v1.js";
+import { detectApiKeyScope, e2eTest } from "./helpers.js";
+
+describe("e2e — error wrapping against real Neon API", () => {
+	e2eTest(
+		"bad API key yields PLATFORM_UNAUTHORIZED with key-rotation guidance",
+		async () => {
+			const api = createRealNeonApi({
+				apiKey: "napi_definitely_not_a_real_key_xxxxxxxxxxxxxxxxxx",
+			});
+			await expect(api.listProjects({})).rejects.toMatchObject({
+				code: ErrorCode.Unauthorized,
+			});
+			try {
+				await api.listProjects({});
+			} catch (err) {
+				const p = err as PlatformError;
+				expect(p.message).toContain(
+					"Bearer token sent to the Neon API was rejected",
+				);
+				expect(p.message).toContain(
+					"https://console.neon.tech/app/settings/api-keys",
+				);
+				expect(p.message).toContain("neonctl auth");
+			}
+		},
+	);
+
+	e2eTest(
+		"getProject on a non-existent id yields PLATFORM_NOT_FOUND with the offending id in the message",
+		async () => {
+			const scope = await detectApiKeyScope();
+			if (scope.kind !== "org-or-user") return;
+			const api = createRealNeonApi({
+				apiKey: process.env.NEON_API_KEY ?? "",
+			});
+			await expect(
+				api.getProject("proj-definitely-not-real-12345"),
+			).rejects.toMatchObject({
+				code: ErrorCode.NotFound,
+			});
+			try {
+				await api.getProject("proj-definitely-not-real-12345");
+			} catch (err) {
+				const p = err as PlatformError;
+				expect(p.message).toContain("proj-definitely-not-real-12345");
+				expect(p.details.status).toBe(404);
+			}
+		},
+	);
+});

package/e2e/helpers.ts

@@ -0,0 +1,205 @@
+import { randomUUID } from "node:crypto";
+import { createApiClient } from "@neondatabase/api-client";
+import { test } from "vitest";
+import type { NeonApi } from "../src/lib/neon-api.js";
+import { createRealNeonApi } from "../src/lib/neon-api-real.js";
+
+/**
+ * Every e2e-created project is named `neon-ts-e2e-<uuid>`. Tests can register
+ * `track(id)` to opt into the per-test cleanup hook. The suite-level
+ * {@link sweepOrphans} additionally deletes leftovers from a previous failed run.
+ */
+const PROJECT_PREFIX = "neon-ts-e2e-";
+
+/**
+ * Default Neon region used by every e2e test that creates a project. Override per-test
+ * by passing `region` to `defineConfig`.
+ */
+export const DEFAULT_REGION = "aws-us-east-2";
+
+/** Generate a project name guaranteed not to collide with anything else in the org. */
+export function uniqueProjectName(suffix?: string): string {
+	const id = randomUUID().slice(0, 8);
+	return suffix
+		? `${PROJECT_PREFIX}${id}-${suffix}`
+		: `${PROJECT_PREFIX}${id}`;
+}
+
+function requireApiKey(): string {
+	const key = process.env.NEON_API_KEY;
+	if (!key || key.trim() === "") {
+		throw new Error(
+			"NEON_API_KEY is not set. Create packages/config/.env (see .env.example) before running test:e2e.",
+		);
+	}
+	return key;
+}
+
+/** The same real NeonApi adapter the SDK uses internally — exercised end-to-end. */
+export function makeRealApi(): NeonApi {
+	return createRealNeonApi({ apiKey: requireApiKey() });
+}
+
+/**
+ * Create a real Neon project via the NeonApi adapter directly. `pushConfig` no longer
+ * provisions projects (callers are expected to run `neonctl link` first), so every e2e
+ * test that needs a fresh project to push against goes through this helper instead.
+ */
+export async function bootstrapProject(
+	api: NeonApi,
+	args: { name: string; region: string },
+): Promise<string> {
+	const created = await api.createProject({
+		name: args.name,
+		regionId: args.region,
+	});
+	return created.id;
+}
+
+/** Lower-level Neon client. Used by cleanup and a few setup helpers. */
+function makeRawClient(): ReturnType<typeof createApiClient> {
+	return createApiClient({ apiKey: requireApiKey() });
+}
+
+/**
+ * Discriminates the key currently configured. Project-scoped keys can't list projects;
+ * org/user-scoped keys can.
+ */
+export type ApiKeyScope =
+	| { kind: "org-or-user"; canCreate: true }
+	| { kind: "project"; projectId: string; canCreate: false };
+
+/**
+ * Probe the configured API key to find out what it can do. Memoised because we only need
+ * to do this once per process.
+ */
+let cachedScope: ApiKeyScope | undefined;
+export async function detectApiKeyScope(): Promise<ApiKeyScope> {
+	if (cachedScope) return cachedScope;
+	const client = makeRawClient();
+	try {
+		await client.listProjects({ limit: 1 });
+		cachedScope = { kind: "org-or-user", canCreate: true };
+		return cachedScope;
+	} catch (err) {
+		const status = (err as { response?: { status?: number } } | undefined)
+			?.response?.status;
+		if (status !== 401 && status !== 403) throw err;
+	}
+	const fixedProjectId = process.env.NEON_PROJECT_ID;
+	if (!fixedProjectId || fixedProjectId.trim() === "") {
+		throw new Error(
+			"API key cannot list projects (looks project-scoped) and NEON_PROJECT_ID is not set. " +
+				"Set NEON_PROJECT_ID in packages/config/.env to target a fixed project for the bounded e2e subset.",
+		);
+	}
+	cachedScope = {
+		kind: "project",
+		projectId: fixedProjectId,
+		canCreate: false,
+	};
+	return cachedScope;
+}
+
+/**
+ * Delete a project, ignoring "already gone" errors so cleanup is idempotent. Refuses to
+ * delete anything that isn't prefixed with {@link PROJECT_PREFIX} so a mis-typed id can
+ * never wipe an unrelated project.
+ */
+async function deleteProject(projectId: string): Promise<void> {
+	const client = makeRawClient();
+	const project = await client.getProject(projectId).catch((err) => {
+		const status = (err as { response?: { status?: number } } | undefined)
+			?.response?.status;
+		if (status === 404 || status === 410) return null;
+		throw err;
+	});
+	if (!project) return;
+	if (!project.data.project.name.startsWith(PROJECT_PREFIX)) {
+		throw new Error(
+			`Refusing to delete project ${projectId} ("${project.data.project.name}"): does not match the e2e prefix.`,
+		);
+	}
+	// Retry on 423 (locked while a previous mutation is in flight) so cleanup is robust.
+	const maxAttempts = 12;
+	let delay = 500;
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+		try {
+			await client.deleteProject(projectId);
+			return;
+		} catch (err) {
+			const status = (
+				err as { response?: { status?: number } } | undefined
+			)?.response?.status;
+			if (status === 404 || status === 410) return;
+			if (status !== 423 || attempt === maxAttempts) throw err;
+			await sleep(delay);
+			delay = Math.min(delay * 2, 5_000);
+		}
+	}
+}
+
+/**
+ * List every project whose name starts with {@link PROJECT_PREFIX} and delete them.
+ * Called once at suite start to mop up orphans from a previous failed run.
+ */
+export async function sweepOrphans(): Promise<{ swept: string[] }> {
+	const scope = await detectApiKeyScope();
+	if (scope.kind === "project") return { swept: [] };
+	const client = makeRawClient();
+	const swept: string[] = [];
+	let cursor: string | undefined;
+	while (true) {
+		const res = await client.listProjects({
+			limit: 100,
+			...(cursor ? { cursor } : {}),
+		});
+		for (const project of res.data.projects) {
+			if (project.name.startsWith(PROJECT_PREFIX)) {
+				await deleteProject(project.id);
+				swept.push(project.id);
+			}
+		}
+		const next = (res.data as { pagination?: { next?: string } }).pagination
+			?.next;
+		if (!next || next === cursor) break;
+		cursor = next;
+	}
+	return { swept };
+}
+
+/**
+ * A vitest `test.extend` fixture that tracks every project id a test creates and deletes
+ * each one in the cleanup phase, even if the test failed mid-way. Use `track(id)` to
+ * register ids — cleanup runs regardless of outcome.
+ */
+export const e2eTest = test.extend<{
+	track: (projectId: string) => void;
+}>({
+	// biome-ignore lint/correctness/noEmptyPattern: vitest's fixture API requires this exact shape.
+	track: async ({}, use) => {
+		const created: string[] = [];
+		await use((projectId: string) => {
+			created.push(projectId);
+		});
+		for (const projectId of created) {
+			try {
+				await deleteProject(projectId);
+			} catch (err) {
+				// Surface, but don't fail on cleanup errors — the orphan sweep on the next
+				// run will mop up anything we miss.
+				console.error(
+					`[e2e cleanup] failed to delete ${projectId}: ${(err as Error).message}`,
+				);
+			}
+		}
+	},
+});
+
+/**
+ * Some Neon operations are eventually consistent (notably branch creation finishing
+ * `init` → `ready`). A small wait avoids racing on subsequent reads.
+ */
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/e2e/load-env.ts

@@ -0,0 +1,29 @@
+// Loaded by vitest.e2e.config.ts `setupFiles`; not imported statically.
+// fallow-ignore-file unused-file
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Vitest setup file — loads `packages/config/.env` into `process.env` so e2e tests can
+ * read `NEON_API_KEY` (and friends). Node 22 has `--env-file` but it's per-process; doing
+ * it here keeps the test command short (`pnpm test:e2e`).
+ *
+ * Lines starting with `#` are treated as comments; everything else is parsed as
+ * `KEY=value` (no quoting / interpolation — we keep this minimal on purpose).
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const envPath = resolve(here, "..", ".env");
+
+if (existsSync(envPath)) {
+	const raw = readFileSync(envPath, "utf-8");
+	for (const rawLine of raw.split("\n")) {
+		const line = rawLine.trim();
+		if (line === "" || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq <= 0) continue;
+		const key = line.slice(0, eq).trim();
+		const value = line.slice(eq + 1).trim();
+		if (process.env[key] === undefined) process.env[key] = value;
+	}
+}

package/e2e/setup.ts

@@ -0,0 +1,24 @@
+// Loaded by vitest.e2e.config.ts `setupFiles`; not imported statically.
+// fallow-ignore-file unused-file
+import { beforeAll } from "vitest";
+import { detectApiKeyScope, sweepOrphans } from "./helpers.js";
+
+/**
+ * Suite-level setup. Runs once before any e2e test:
+ * 1. Probes the configured API key to detect its scope. We do this here so a misconfigured
+ *    environment fails fast with a clear message rather than surfacing as cryptic 403s
+ *    inside individual tests.
+ * 2. When the key is org/user-scoped, sweep any orphaned `neon-ts-e2e-*` projects
+ *    left over from a previous run.
+ */
+beforeAll(async () => {
+	const scope = await detectApiKeyScope();
+	if (scope.kind === "org-or-user") {
+		const { swept } = await sweepOrphans();
+		if (swept.length > 0) {
+			console.warn(
+				`[e2e setup] swept ${swept.length} orphaned project(s) from a previous run.`,
+			);
+		}
+	}
+});

package/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@neondatabase/config",
+	"version": "0.0.0",
+	"description": "Config-as-Code for the Neon Platform. Define a `neon.ts` policy and inspect/diff/deploy it against the Neon API as plain TypeScript functions.",
+	"keywords": [
+		"neon",
+		"database",
+		"postgres",
+		"iac",
+		"config-as-code",
+		"platform"
+	],
+	"license": "Apache-2.0",
+	"author": {
+		"name": "Neon",
+		"url": "https://neon.com"
+	}
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * The default entry point re-exports the latest stable version. New consumers should import
+ * directly from `@neondatabase/config/v1` to opt in to a specific major.
+ */
+export * from "./v1.js";

package/src/lib/auth.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { readNeonctlCredentials, resolveApiKey } from "./auth.js";
+import { makeTempRepo, stubCleanNeonEnv } from "./test-utils.js";
+
+const cleanups: Array<() => void> = [];
+afterEach(() => {
+	while (cleanups.length > 0) cleanups.shift()?.();
+});
+
+beforeEach(() => {
+	stubCleanNeonEnv();
+});
+
+function setupHome(files: Record<string, string | null>): string {
+	const repo = makeTempRepo(files);
+	cleanups.push(repo.cleanup);
+	return repo.root;
+}
+
+describe("readNeonctlCredentials", () => {
+	test("reads access_token from <home>/.config/neonctl/credentials.json by default", () => {
+		const home = setupHome({
+			".config/neonctl/credentials.json": JSON.stringify({
+				access_token: "oauth-token-abc",
+				refresh_token: "rt-xyz",
+			}),
+		});
+		vi.stubEnv("HOME", home);
+		const creds = readNeonctlCredentials();
+		expect(creds?.access_token).toBe("oauth-token-abc");
+		expect(creds?.refresh_token).toBe("rt-xyz");
+	});
+
+	test("honours NEONCTL_CONFIG_DIR over the default location", () => {
+		const home = setupHome({
+			".config/neonctl/credentials.json": JSON.stringify({
+				access_token: "default-loc",
+			}),
+			"custom/credentials.json": JSON.stringify({
+				access_token: "from-env-dir",
+			}),
+		});
+		vi.stubEnv("HOME", home);
+		vi.stubEnv("NEONCTL_CONFIG_DIR", `${home}/custom`);
+		const creds = readNeonctlCredentials();
+		expect(creds?.access_token).toBe("from-env-dir");
+	});
+
+	test("honours explicit configDir over the env var", () => {
+		const home = setupHome({
+			".config/neonctl/credentials.json": JSON.stringify({
+				access_token: "default-loc",
+			}),
+			"env/credentials.json": JSON.stringify({
+				access_token: "from-env-dir",
+			}),
+			"opt/credentials.json": JSON.stringify({
+				access_token: "from-option",
+			}),
+		});
+		vi.stubEnv("HOME", home);
+		vi.stubEnv("NEONCTL_CONFIG_DIR", `${home}/env`);
+		const creds = readNeonctlCredentials({ configDir: `${home}/opt` });
+		expect(creds?.access_token).toBe("from-option");
+	});
+
+	test("returns null when the file is missing", () => {
+		const home = setupHome({ ".config/neonctl/.keep": "" });
+		vi.stubEnv("HOME", home);
+		expect(readNeonctlCredentials()).toBeNull();
+	});
+
+	test("returns null on malformed JSON instead of throwing", () => {
+		const home = setupHome({
+			".config/neonctl/credentials.json": "not json",
+		});
+		vi.stubEnv("HOME", home);
+		expect(readNeonctlCredentials()).toBeNull();
+	});
+
+	test("returns null when access_token is missing or empty", () => {
+		const home = setupHome({
+			".config/neonctl/credentials.json": JSON.stringify({
+				refresh_token: "rt-only",
+			}),
+		});
+		vi.stubEnv("HOME", home);
+		expect(readNeonctlCredentials()).toBeNull();
+		const home2 = setupHome({
+			".config/neonctl/credentials.json": JSON.stringify({
+				access_token: "",
+			}),
+		});
+		vi.stubEnv("HOME", home2);
+		expect(readNeonctlCredentials()).toBeNull();
+	});
+
+	test("returns null when no home dir resolvable", () => {
+		// `stubCleanNeonEnv()` already cleared HOME and USERPROFILE.
+		expect(readNeonctlCredentials()).toBeNull();
+	});
+
+	test("falls back to USERPROFILE on Windows-style env", () => {
+		const winHome = setupHome({
+			".config/neonctl/credentials.json": JSON.stringify({
+				access_token: "win-token",
+			}),
+		});
+		vi.stubEnv("USERPROFILE", winHome);
+		const creds = readNeonctlCredentials();
+		expect(creds?.access_token).toBe("win-token");
+	});
+});
+
+describe("resolveApiKey — priority chain", () => {
+	test("explicit option wins over env wins over credentials.json", () => {
+		const home = setupHome({
+			".config/neonctl/credentials.json": JSON.stringify({
+				access_token: "from-file",
+			}),
+		});
+		vi.stubEnv("HOME", home);
+		vi.stubEnv("NEON_API_KEY", "from-env");
+		expect(resolveApiKey({ apiKey: "from-option" })).toEqual({
+			token: "from-option",
+			source: "option",
+		});
+
+		expect(resolveApiKey()).toEqual({ token: "from-env", source: "env" });
+
+		vi.stubEnv("NEON_API_KEY", undefined);
+		expect(resolveApiKey()).toEqual({
+			token: "from-file",
+			source: "neonctl",
+		});
+	});
+
+	test("returns null when no source provides a token", () => {
+		const home = setupHome({ ".config/neonctl/.keep": "" });
+		vi.stubEnv("HOME", home);
+		expect(resolveApiKey()).toBeNull();
+	});
+
+	test("treats whitespace-only option / env as missing", () => {
+		const home = setupHome({
+			".config/neonctl/credentials.json": JSON.stringify({
+				access_token: "from-file",
+			}),
+		});
+		vi.stubEnv("HOME", home);
+		vi.stubEnv("NEON_API_KEY", "   ");
+		expect(resolveApiKey({ apiKey: "   " })).toEqual({
+			token: "from-file",
+			source: "neonctl",
+		});
+	});
+
+	test("trims whitespace around the resolved token", () => {
+		const home = setupHome({ ".config/neonctl/.keep": "" });
+		vi.stubEnv("HOME", home);
+		expect(resolveApiKey({ apiKey: "  napi_x  " })).toEqual({
+			token: "napi_x",
+			source: "option",
+		});
+	});
+});