@neondatabase/env 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/env 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,66 @@
+# @neondatabase/env
+
+Resolve and inject Neon connection strings for the branch selected by your `neon.ts` policy. Exposes `fetchEnv` / `parseEnv` functions plus a single CLI command: `neon-env run -- <cmd>`.
+
+Builds on [`@neondatabase/config`](../config) — it reuses the `Config` policy type and the Neon API client.
+
+## Install
+
+```bash
+npm install @neondatabase/env
+```
+
+## Functions
+
+The library functions are **filesystem- and env-agnostic**: `fetchEnv` requires an explicit `projectId` + `branchId`, and `parseEnv` requires an explicit `branchName`. (The `neon-env` CLI does the `.neon`/`NEON_*` resolution and passes these in.)
+
+> `parseEnv` takes a branch **name**, not an id, because it makes no API call — it only needs the branch to evaluate your `neon.ts` policy, which switches on `branch.name`. The API-backed functions take a `branchId` (`br-…`) and read the name back from Neon.
+
+```ts
+import config from "../neon";
+import { fetchEnv, parseEnv } from "@neondatabase/env/v1";
+
+// Async — calls the Neon API for live connection strings. Use in build scripts / top-level await.
+const env = await fetchEnv(config, { projectId: "patient-art-12345", branchId: "br-…" });
+const db = drizzle(neon(env.postgres.databaseUrl), { schema });
+
+// Sync — reads already-injected process.env and validates it (no network).
+// Use in app bootstrap where async isn't available.
+const env2 = parseEnv(config, process.env.NEON_BRANCH_NAME ?? "main");
+```
+
+Both return the same namespaced `NeonEnv` shape: `postgres` is always present; `auth` and `dataApi` are included (and statically typed) when the evaluated branch policy enables them.
+
+| Function | Description |
+| --- | --- |
+| `fetchEnv(config, { projectId, branchId, ... })` | Async. Calls the Neon API for the given project + branch and returns live connection strings (and Auth/Data API values when enabled). `projectId` and `branchId` are required (`branchId` is a `br-…` id). |
+| `parseEnv(config, branchName)` | Sync. Reads/validates the Neon env vars already present in `process.env`, evaluating the policy for `branchName`. Throws `PlatformError(EnvNotInjected)` listing missing vars when the env isn't populated. |
+| `toEntries(env)` | Project a resolved `NeonEnv` into `{ KEY: value }` pairs for cross-process transport (named after the web `.entries()` convention; returns a `Record`). |
+
+## CLI
+
+One command — inject the env vars for your `neon.ts` branch into a dev command:
+
+```bash
+neon-env run -- npm run dev
+neon-env run -- pnpm dev
+```
+
+`run` loads `neon.ts`, resolves the branch (via `--branch`, `NEON_BRANCH_ID`, or `.neon[/project.json]`), fetches the connection strings from Neon, and spawns the command with `DATABASE_URL` / `DATABASE_URL_UNPOOLED` (and `NEON_AUTH_BASE_URL` / `NEON_DATA_API_URL` when the policy enables them) injected on top of the inherited environment. Stdio is inherited so interactive dev servers keep working, and the parent exits with the child's exit code.
+
+Flags: `--config <path>`, `--project-id`, `--branch`, `--api-key`, `--debug`.
+
+## Env vars produced
+
+| Key | From |
+| --- | --- |
+| `DATABASE_URL` | pooled connection string |
+| `DATABASE_URL_UNPOOLED` | direct connection string |
+| `NEON_AUTH_BASE_URL` | Neon Auth integration (when `auth` is enabled) |
+| `NEON_DATA_API_URL` | Data API integration (when `dataApi` is enabled) |
+
+## Resolution
+
+The **CLI** (`neon-env run`) resolves project + branch itself: `--project-id` / `--branch` flag → `NEON_PROJECT_ID` / `NEON_BRANCH_ID` env → `.neon[/project.json]` walked up from the working directory. The API key resolves via `--api-key` → `NEON_API_KEY` → `~/.config/neonctl/credentials.json`.
+
+The **library functions** do none of this — pass `projectId` / `branchId` explicitly. This keeps `.neon` parsing in one place (the CLI / neonctl) and the functions pure.

package/e2e/env.e2e.test.ts

@@ -0,0 +1,36 @@
+import { defineConfig } from "@neondatabase/config/v1";
+import { describe, expect } from "vitest";
+import { fetchEnv } from "../src/v1.js";
+import {
+	bootstrapProject,
+	DEFAULT_REGION,
+	detectApiKeyScope,
+	e2eTest,
+	makeRealApi,
+	uniqueProjectName,
+} from "./helpers.js";
+
+describe("e2e — fetchEnv against real Neon API", () => {
+	e2eTest("returns Postgres env for selected branch", async ({ track }) => {
+		const scope = await detectApiKeyScope();
+		const api = makeRealApi();
+		const projectId =
+			scope.kind === "org-or-user"
+				? await bootstrapProject(api, {
+						name: uniqueProjectName("env"),
+						region: DEFAULT_REGION,
+					})
+				: scope.projectId;
+		if (scope.kind === "org-or-user") track(projectId);
+		const branchId = (await api.listBranches(projectId)).find(
+			(b) => b.isDefault,
+		)?.id;
+		if (!branchId) throw new Error("missing default branch");
+		const env = await fetchEnv(
+			defineConfig(() => ({})),
+			{ api, projectId, branchId },
+		);
+		expect(env.postgres.databaseUrl).toContain("postgresql://");
+		expect(env.postgres.databaseUrlUnpooled).toContain("postgresql://");
+	});
+});

package/e2e/helpers.ts

@@ -0,0 +1,188 @@
+import { randomUUID } from "node:crypto";
+import { createApiClient } from "@neondatabase/api-client";
+import { createRealNeonApi, type NeonApi } from "@neondatabase/config/v1";
+import { test } from "vitest";
+
+/**
+ * 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.
+ */
+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/env/.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.
+ */
+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 };
+
+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/env/.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.`,
+		);
+	}
+	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.
+ */
+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.
+ */
+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) {
+				console.error(
+					`[e2e cleanup] failed to delete ${projectId}: ${(err as Error).message}`,
+				);
+			}
+		}
+	},
+});
+
+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/env/.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,22 @@
+{
+	"name": "@neondatabase/env",
+	"version": "0.0.0",
+	"description": "Resolve and inject Neon connection strings for the branch selected by your neon.ts policy. fetchEnv / parseEnv plus a single `env run -- <cmd>` CLI.",
+	"keywords": [
+		"neon",
+		"database",
+		"postgres",
+		"env",
+		"dotenv",
+		"platform"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/neondatabase/neon-pkgs.git"
+	},
+	"license": "Apache-2.0",
+	"author": {
+		"name": "Neon",
+		"url": "https://neon.com"
+	}
+}

package/src/cli.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { type CommandResult, runEnvRun } from "./lib/cli/commands.js";
+
+const pkgVersion = readPackageVersion();
+
+const argv = yargs(hideBin(process.argv))
+	.scriptName("neon-env")
+	.usage("$0 run -- <command> [options]")
+	.parserConfiguration({ "populate--": true })
+	.option("debug", {
+		type: "boolean",
+		default: false,
+		describe:
+			"Print stack traces and structured error details when something fails",
+	})
+	.command(
+		"run",
+		"Run a command with Neon env vars (from your neon.ts policy) injected into its environment. Use `--` to separate the command: `neon-env run -- npm run dev`.",
+		(y) =>
+			y
+				.option("config", {
+					type: "string",
+					describe:
+						"Path to neon.ts (defaults to walking up from cwd)",
+				})
+				.option("project-id", {
+					type: "string",
+					describe: "Override the .neon/project.json projectId",
+				})
+				.option("branch", {
+					type: "string",
+					describe:
+						"Override the .neon/project.json branchId / NEON_BRANCH_ID",
+				})
+				.option("api-key", {
+					type: "string",
+					describe: "Neon API key (defaults to NEON_API_KEY)",
+				}),
+	)
+	.demandCommand(1, "Run `neon-env --help` to see the available commands.")
+	.strict()
+	.help()
+	.version(pkgVersion)
+	.parseSync();
+
+const command = String(argv._[0]);
+const cwd = process.cwd();
+
+let result: CommandResult;
+switch (command) {
+	case "run": {
+		const passthrough = Array.isArray(argv["--"])
+			? argv["--"].map(String)
+			: [];
+		result = await runEnvRun(
+			{
+				command: passthrough,
+				...(typeof argv.config === "string"
+					? { configPath: argv.config }
+					: {}),
+				...(typeof argv["project-id"] === "string"
+					? { projectId: argv["project-id"] }
+					: {}),
+				...(typeof argv.branch === "string"
+					? { branch: argv.branch }
+					: {}),
+				...(typeof argv["api-key"] === "string"
+					? { apiKey: argv["api-key"] }
+					: {}),
+			},
+			{ cwd },
+		);
+		break;
+	}
+	default:
+		result = {
+			exitCode: 1,
+			stdout: "",
+			stderr: `Unknown command: ${command}\n`,
+		};
+}
+
+if (result.stdout) process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(result.stderr);
+if (argv.debug && result.exitCode !== 0 && result.debugInfo) {
+	process.stderr.write(`\n--- debug ---\n${result.debugInfo}\n`);
+}
+process.exit(result.exitCode);
+
+function readPackageVersion(): string {
+	// The built CLI lives at `dist/cli.js`, so `package.json` is one directory up. When
+	// running from source (tsx, vitest), the file lives at `src/cli.ts` and `package.json`
+	// is again one directory up. Single resolution covers both layouts.
+	try {
+		const pkgUrl = new URL("../package.json", import.meta.url);
+		const raw = readFileSync(fileURLToPath(pkgUrl), "utf-8");
+		const parsed = JSON.parse(raw) as { version?: unknown };
+		return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}

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/env/v1` to opt in to a specific major.
+ */
+export * from "./v1.js";

package/src/lib/cli/commands.test.ts

@@ -0,0 +1,101 @@
+import { existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { FakeNeonApi } from "../fake-neon-api.js";
+import { makeTempRepo, stubCleanNeonEnv } from "../test-utils.js";
+import { runEnvRun } from "./commands.js";
+
+const CONFIG_SRC = new URL("../../../../config/src/v1.ts", import.meta.url)
+	.pathname;
+
+const cleanups: Array<() => void> = [];
+afterEach(() => {
+	while (cleanups.length > 0) cleanups.shift()?.();
+});
+beforeEach(() => stubCleanNeonEnv());
+
+function setup(files: Record<string, string | null>) {
+	const repo = makeTempRepo(files);
+	cleanups.push(repo.cleanup);
+	return repo.root;
+}
+
+function seededFake() {
+	const api = new FakeNeonApi();
+	const projectId = "proj-env-cli";
+	api.seedProject({
+		project: {
+			id: projectId,
+			name: "env-cli-test",
+			regionId: "aws-us-east-1",
+			pgVersion: 17,
+		},
+		branches: [
+			{ branch: { id: "br-main", name: "main", isDefault: true } },
+		],
+	});
+	return { api, projectId };
+}
+
+function policy() {
+	return `import { defineConfig } from "${CONFIG_SRC}";
+export default defineConfig(() => ({}));`;
+}
+
+describe("runEnvRun", () => {
+	test("injects DATABASE_URL into the spawned command", async () => {
+		const { api, projectId } = seededFake();
+		const root = setup({
+			"package.json": "{}",
+			".neon/project.json": JSON.stringify({
+				projectId,
+				branchId: "br-main",
+			}),
+			"neon.ts": policy(),
+		});
+		const outFile = join(
+			mkdtempSync(join(tmpdir(), "neon-env-out-")),
+			"url.txt",
+		);
+
+		const result = await runEnvRun(
+			{
+				command: [
+					process.execPath,
+					"-e",
+					`require("node:fs").writeFileSync(${JSON.stringify(outFile)}, process.env.DATABASE_URL ?? "")`,
+				],
+			},
+			{ cwd: root, api },
+		);
+
+		expect(result.exitCode).toBe(0);
+		expect(existsSync(outFile)).toBe(true);
+	});
+
+	test("returns a non-zero exit code with usage when no command is given", async () => {
+		const { api } = seededFake();
+		const root = setup({ "package.json": "{}" });
+		const result = await runEnvRun({ command: [] }, { cwd: root, api });
+		expect(result.exitCode).not.toBe(0);
+		expect(result.stderr).toContain("neon-env run --");
+	});
+
+	test("propagates the child's exit code", async () => {
+		const { api, projectId } = seededFake();
+		const root = setup({
+			"package.json": "{}",
+			".neon/project.json": JSON.stringify({
+				projectId,
+				branchId: "br-main",
+			}),
+			"neon.ts": policy(),
+		});
+		const result = await runEnvRun(
+			{ command: [process.execPath, "-e", "process.exit(3)"] },
+			{ cwd: root, api },
+		);
+		expect(result.exitCode).toBe(3);
+	});
+});