@neondatabase/config 0.0.0 → 0.2.0

package/e2e/helpers.ts

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

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

@@ -1,24 +0,0 @@
-// 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/src/index.ts

@@ -1,5 +0,0 @@
-/**
- * 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

@@ -1,166 +0,0 @@
-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",
-		});
-	});
-});

package/src/lib/auth.ts

@@ -1,124 +0,0 @@
-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(" "),
-	);
-}