@neondatabase/config 0.0.0 → 0.1.0

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(" "),
-	);
-}

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

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

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